usr.bin: add flock and ts utilities

[laffer1]

Summary

• add flock(1) with command, shell-command, descriptor, shared/exclusive, nonblocking, and timeout modes
• add ts(1) with absolute, elapsed, incremental, and fractional timestamps
• add manual pages and ATF coverage and register both utilities in the userland build
• normalize the return statement in the existing shuf(1) implementation for style(9)

base64(1) and shuf(1) were already present after updating this branch from current master.

Provenance

• flock(1) is based on the BSD-2-Clause NetBSD implementation, with MidnightBSD portability, validation, and test changes
• ts(1) is based on the ISC-licensed OpenBSD implementation imported by FreeBSD, with additional error handling, bounds checks, and tests

Testing

• 24 ATF cases passed for flock, ts, base64, and shuf using host-built binaries
• strict host compilation with -Wall -Wextra -Werror passed
• tools/build/checkstyle9.pl --strict passed
• cppcheck passed for the changed C sources
• sh -n passed for the test scripts
• mandoc -Tlint passed apart from host manual-database lookup warnings
• git diff --check passed

A native MidnightBSD cross-build could not be completed because this host lacks a configured target compiler/sysroot. The repository precommit wrappers for clang-format and Splint could not run because those executables are not installed.

AI contribution checklist

• I have manually reviewed every line of AI-generated code for security flaws.
• The code adheres to the MidnightBSD style guide (style(9)).
• No proprietary or copyleft code was introduced via the AI tool.

AI-Assisted-by: OpenAI GPT-5
Obtained from: NetBSD and OpenBSD/FreeBSD

Summary by Sourcery

Add flock(1) and ts(1) userland utilities with documentation, tests, and build integration.

New Features:

• Add flock(1) for command, shell-command, file-descriptor, lock-mode, nonblocking, and timeout-based locking.
• Add ts(1) for prefixing input lines with absolute, elapsed, incremental, and microsecond-resolution timestamps.

Enhancements:

• Provide manual pages and ATF coverage for both utilities.
• Register flock(1) and ts(1) in the userland build.
• Normalize shuf(1)'s return statement to conform to style(9).

Build:

• Add build definitions for flock(1) and ts(1).

Documentation:

• Add user-facing manual pages for flock(1) and ts(1).

Tests:

• Add ATF tests covering flock locking modes, command execution, exit status, and timeout validation.
• Add ATF tests covering ts formatting, elapsed timestamps, empty and unterminated input, and option validation.

[sourcery-ai]

Sorry @laffer1, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days and 12 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Introduces and registers flock(1) and ts(1), including their implementations, manual pages, build metadata, and ATF tests; flock wraps flock(2) across command and descriptor workflows with configurable locking and timeouts, while ts formats line-oriented input using wall-clock or monotonic elapsed timestamps. The existing shuf(1) return statement is also normalized to style(9).

Sequence diagram for flock command locking

sequenceDiagram
    participant User
    participant flock
    participant Kernel as flock(2)
    participant Command
    User->>flock: invoke with file and command
    flock->>flock: open(path)
    opt timeout configured
        flock->>flock: start_timer(timeout)
    end
    flock->>Kernel: flock(fd, lock)
    alt lock acquired
        flock->>Command: execvp(command, args)
        Command-->>flock: exit status
    else lock unavailable
        Kernel-->>flock: failure or EINTR
        flock-->>User: failure status
    end

Loading

Sequence diagram for flock descriptor workflow

sequenceDiagram
    participant ShellScript
    participant flock
    participant Kernel as flock(2)
    ShellScript->>flock: invoke with descriptor
    flock->>Kernel: flock(fd, lock)
    alt lock acquired
        flock-->>ShellScript: success
    else nonblocking or timeout failure
        Kernel-->>flock: failure
        flock-->>ShellScript: failure status
    end

Loading

Flow diagram for ts timestamp processing

flowchart TD
    A["Read line from stdin"] --> B["clock_gettime(clock)"]
    B --> C{"Timestamp mode"}
    C -->|absolute| D["Use current realtime timestamp"]
    C -->|elapsed| E["timespecsub(now, start, ts)"]
    C -->|incremental| F["timespecsub(now, previous, ts)"]
    C -->|monotonic absolute| G["timespecadd(now, utc_offset, ts)"]
    D --> H["fmtfmt(ts)"]
    E --> H
    F --> H
    G --> H
    H --> I["Write timestamp and input line"]
    I --> A

Loading

File-Level Changes

Change	Details	Files
Adds the flock utility with multiple locking interfaces and timeout behavior.	Implements command, shell-command, and file-descriptor modes. Supports shared/exclusive/unlock, nonblocking, close, verbose/debug, and fractional timeout options. Adds usage documentation and ATF coverage for command execution, status propagation, contention, and validation.	usr.bin/flock/flock.c usr.bin/flock/flock.1 usr.bin/flock/Makefile usr.bin/flock/tests/flock_test.sh usr.bin/flock/tests/Makefile
Adds the ts utility for prefixing input lines with formatted timestamps.	Implements wall-clock, monotonic, elapsed, and since-start timestamp modes. Adds fractional-second format extensions with bounds and error handling. Adds documentation, build integration, and ATF coverage for formatting and input edge cases.	contrib/ts/ts.c contrib/ts/ts.1 usr.bin/ts/Makefile usr.bin/ts/tests/ts_test.sh usr.bin/ts/tests/Makefile
Registers the new utilities in the userland build and normalizes existing style.	Adds flock and ts to the usr.bin subdirectory list. Changes shuf's final return statement to style(9) parenthesized form.	usr.bin/Makefile usr.bin/shuf/shuf.c

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[github-actions]

Claude finished @laffer1's task in 2m 9s —— View job

---

Code Review: flock(1) and ts(1) utilities

Tasks

• Gather context (PR diff, CLAUDE.md, AI_POLICY.md)
• Review usr.bin/flock/flock.c
• Review contrib/ts/ts.c
• Review Makefiles, man pages, tests
• Check usr.bin/shuf/shuf.c change
• Post final review

No assembly or contrib/mksh changes in this PR, so the AI-restriction on those areas doesn't apply. All touched files are C/Shell, which are permitted with review.

Findings

I did not find any high-confidence correctness, memory-safety, or security bugs.

• usr.bin/flock/flock.c: malloc/free not applicable (no heap allocation). Bounds checks on strtol/strtod inputs are correct (ERANGE, range clamps, isfinite). The SIGALRM/setitimer timeout logic correctly distinguishes a timer-driven EINTR (timeout_expired) from spurious interrupts, and stop_timer() disarms the timer after a successful lock to avoid a late signal. Lock-flag conflict validation (-s/-x/-u) is sound.
• contrib/ts/ts.c: bufsize = format_length(format) * 10 is protected against overflow inside format_length() (len >= SIZE_MAX / 10 check), and the %.S/%.s/%.T in-place expansion in fmtfmt() bounds-checks the shift (bufsize - offset < len + 7) before writing — this correctly prevents an out-of-bounds write even with multiple fractional-second specifiers in one format string. buf/outbuf are freed at the one non-error exit path; early exits go through err/errx, which is the accepted pattern for CLI tools.
• Style/build: usr.bin/flock/Makefile and usr.bin/ts/Makefile follow existing HAS_TESTS/SUBDIR.${MK_TESTS} conventions used elsewhere in usr.bin. usr.bin/ts/Makefile sourcing ts.c from contrib/ts via .PATH matches the pattern used for other contrib-derived utilities (e.g. awk, bzip2, addr2line). flock.c/flock.1 retain NetBSD copyright headers; ts.c/ts.1 retain OpenBSD/ISC headers — both appropriate given "Obtained from" attribution in the PR body.
• usr.bin/shuf/shuf.c: return 0; → return (0); is a correct, minimal style(9) fix.

Minor nit (non-blocking)

• usr.bin/flock/flock.c:173-182 — option_is_command() compares -c/--command character-by-character instead of strcmp(arg, "-c") == 0 || strcmp(arg, "--command") == 0. It's bounds-safe as written (each indexed access is guarded by the preceding && short-circuit hitting the NUL terminator first), just harder to read than necessary.

Testing

Per the PR description, ATF cases, strict -Wall -Wextra -Werror compile, checkstyle9.pl --strict, and cppcheck all passed on the author's host. I did not re-run these in this environment (no configured MidnightBSD cross-toolchain here), so I'm relying on the author's reported results for build/test verification.

Overall: This looks like a clean, well-scoped port of two well-known utilities with reasonable test coverage and correct AI-policy attribution trailers. No blocking issues found.

[Copilot]

🟡 Changes recommended

usr.bin/flock/flock.1 is added but not listed in usr.bin/flock/Makefile’s MAN, so it won’t be installed with the utility.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds two new userland utilities to the MidnightBSD base system: flock(1) (file/descriptor locking wrapper) and ts(1) (timestamp prefixing filter), including ATF-based regression tests and build integration, plus a small shuf(1) style(9) return normalization.

Changes:

• Add usr.bin/flock utility, its manual page, and ATF shell tests; register it in usr.bin/Makefile.
• Add usr.bin/ts build glue for the imported contrib/ts implementation, with ATF shell tests; register it in usr.bin/Makefile.
• Normalize shuf(1) return style to return (0);.

File summaries

File	Description
usr.bin/ts/tests/ts_test.sh	Adds ATF coverage for core ts(1) behaviors and option validation.
usr.bin/ts/tests/Makefile	Registers ts ATF shell tests for the test build.
usr.bin/ts/Makefile	Builds ts(1) from contrib/ts and installs its man page; wires in tests.
usr.bin/shuf/shuf.c	Style(9) return normalization in main().
usr.bin/Makefile	Adds flock and ts to the usr.bin build.
usr.bin/flock/tests/Makefile	Registers flock ATF shell tests for the test build.
usr.bin/flock/tests/flock_test.sh	Adds ATF coverage for command execution, nonblocking behavior, and timeout validation.
usr.bin/flock/Makefile	Adds build glue for flock(1) and wires in tests.
usr.bin/flock/flock.c	New flock(1) implementation (NetBSD-derived) with timeout/nonblocking/descriptor modes.
usr.bin/flock/flock.1	New flock(1) manual page.
contrib/ts/ts.c	Imported ts(1) implementation (OpenBSD/FreeBSD provenance) with timestamp formatting.
contrib/ts/ts.1	Imported ts(1) manual page.

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Claude finished @laffer1's task in 1m 10s —— View job

---

Claude's task

• Gather context (PR state, diff vs origin/master, merge history)
• Check whether Copilot's flagged issue (flock.1 missing from MAN in usr.bin/flock/Makefile) was addressed
• Confirm current state and report back

---

Status

PR #506 is already merged (squash commit 016854d093), and the branch I'm on (claude/pr-506-20260910-0420) is even with origin/master — git diff origin/master...HEAD is empty, so there's no new PR content to review.

Looking at the merge history, this squash included two commits:

1. usr.bin: add flock and ts utilities — the original implementation
2. Update Makefile for flock program configuration (co-authored by Copilot Autofix)

That second commit already fixes the one real issue flagged during review — usr.bin/flock/Makefile now has MAN= flock.1 on line 4, so the manual page is installed correctly:

1  .include <src.opts.mk>
2
3  PROG=	flock
4  MAN=	flock.1
5
6  HAS_TESTS=
7  SUBDIR.${MK_TESTS}+=	tests

No other findings from the earlier automated review (malloc/free symmetry, bounds checks, style(9), timeout/signal handling in flock.c, buffer sizing in ts.c's fmtfmt()) indicated any blocking problems, and those still hold for the code as merged.

I don't see any further actionable request in this comment thread — if there's a specific follow-up you'd like reviewed or changed, let me know and I'll pick it up.

[Copilot]

🔵 Needs a closer look

The new ts(1) ATF test for elapsed timestamps is overly strict and can be flaky under load, risking intermittent CI failures.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

usr.bin/ts/tests/ts_test.sh:48

• The elapsed test is too strict: it assumes the seconds field will be "00", but on slower/loaded systems ts -s %.S can legitimately print 01.xxxxxx (or higher), making this test flaky. Broaden the regex to accept any valid %S seconds value (00–59).

• Files reviewed: 12/12 changed files
• Comments generated: 0 new
• Review effort level: Lite