From: Ingo Schwarze <schwarze@usta.de>
Subject: Re: Documentation in ar(5) does not reflect ar(1) behavior
To: Sören Tempel <soeren@soeren-tempel.net>
Cc: tech@openbsd.org
Date: Mon, 5 Oct 2026 17:22:02 +0200

Hello,

Soeren Tempel wrote on Mon, Oct 05, 2026 at 03:40:23PM +0200:

> The other day, I was reading the ar(5) man page.

To be clear, i assume we are talking about this file:

  /usr/src/share/man/man5/ar.5  installed as  /usr/share/man/man5/ar.5

The content of this file has not been updated since 2013.
At that point miod@ called the file "worth keeping", and i can see why:
The DESCRIPTION explains the purpose and basic information
contained in an archive file with some simplicity, and in a way
that could also be made precise if desired.  That does seem
worthwhile because pages like llvm-ar(1) are complicated and
incomplete, in particular don't explain the file format
at all, and we don't want to modify them locally if that can be
avoided.

POSIX is blunt:
https://pubs.opengroup.org/onlinepubs/9799919799/utilities/ar.html

  OUTPUT FILES
    Archives are files with unspecified formats.

  RATIONALE
    The archive format is not described.  It is recognized that there
    are several known ar formats, which are not compatible.  The ar
    utility is included, however, to allow creation of archives
    that are intended for use only on one machine.  The archive is
    specified as a file, and it can be moved as a file.  This does
    allow an archive to be moved from one machine to another machine
    that uses the same implementation of ar.
    [...]
    The archive format used by the 4.4 BSD implementation is
    documented in this RATIONALE as an example:
    [...]

> Specifically with respect to handling of file names with spaces
> in them, it states:

>> If any file name is more than 16 characters in length or contains an
>> embedded space, the string "#1/" followed by the ASCII length of the
>> name is written in the name field. The file size (stored in the
>> archive header) is incremented by the length of the name. The name is
>> then written immediately following the archive header.

> However, this is not actually what is implemented by ar(1) nowadays:
> 
> 	$ printf 'C D' > 'A B'
> 	$ ar r test.ar A\ B
> 	$ vis test.ar
> 	!<arch>
> 	A B/            0           0     0     644     3         `
> 	C D
> 
> Note that there is no "#1/" in the created test.ar file.
> 
> Even with `ar --format=bsd`, the format differs slightly as LLVM's
> ar(1) implementation inserts null bytes after the name. The ar(5) man
> page also explains the history of the different formats at great length.
> Nonetheless, it is surprising that the documented "current format"
> differs from the one that is implemented and used by default by ar(1).
> 
> Should ar(5) be removed, updated, and/or just refer to LLVM's ar(1)?

I think it should be updated, and it needs expert attention, but i'm
not an export for ar(1).

In particular, i see these tasks:
 * A developer who knows should say whether OpenBSD uses the same
   archive format on all architectures, or whether there are
   differences.  If there are differences, these should possibly
   be mentioned.
 * If we use a common format and that format has a name, that name
   should probably be mentioned up front in the DESCRIPTION.
   If it has no name, the page should probably say something like
   "The archive file format used by default on OpenBSD...".
 * "six variable length ASCII fields" followed by six field
   purposes each with an explicit length specification sounds
   like an outright contradiction to me.
 * Using hexdump(1) to look at *.a files i recently created on amd64,
   my impression is that the actual content of the header does not
   match the description.  Various header fields look longer than
   described, and the trailer looks like "\0\n" rather than " \n".
 * The aspect reported by Soeren.
 * STANDARDS should probably say that POSIX explicitly calls
   the archive format "unspecified", which is a stronger statement
   than "not specified by any standard".
 * Treating AT&T System V as a de-facto standard probably made sense
   around 4.4BSD times, but seems dubious today.  Maybe move this
   to HISTORY?
 * HISTORY seems long.  If all that information is useful, it should
   maybe be said where exactly these formats were used.  Or maybe
   should instead be shortened?

Anyone willing to provide guidance?

Yours,
  Ingo