Re: Third draft of musl documentation/manual

[Rich Felker <dalias@aerifal.cx>]

On Fri, Sep 06, 2013 at 05:14:56PM +0200, Szabolcs Nagy wrote:
> * Rich Felker <dalias@aerifal.cx> [2013-09-06 00:20:43 -0400]:
> > document, but POSIX has a lot more things which are specified as
> > implementation-defined for which I don't have such a nice checklist.
> > Ideas on how to build one would be great.
> 
> i would download the htmls from
> 
> http://pubs.opengroup.org/onlinepubs/9699919799/download/index.html
> 
> and then
> 
> grep -r --color=always -C2 -i implementation-defined basedefs/ functions/ |less -R

Probably need to make that merely "implementation-" to catch cases
broken by hyphenation, unless the html avoids using such line breaks.

> > ### Supported Targets
> > 
> > * i386
> >     * Requires support or kernel emulation of `cmpxchg` instruction,
> >       introduced on the 80486
> 
> maybe note that both i387 and sse fpus are supported

Yes but it's not part of the ABI.

> > #### Compiler wrapper
> > 
> > Included with musl is a wrapper script `musl-gcc` which can be used
> > with an existing GCC compiler toolchain to build programs using musl.
> > If installed, the script itself is located at `$(bindir)/musl-gcc`,
> > and a supporting GCC specs file it uses is located at
> > `$(libdir)/musl-gcc.specs`.
> 
> note that it uses ${REALGCC:-gcc}, not the compiler configured to
> build musl

I'll probably add an additional usage section for the wrapper.

> > ### Filesystem Layout Dependencies
> > 
> > musl aims to avoid imposing filesystem policy; however, the following
> > minimal set of filesystems dependencies must be met in order for
> > programs using musl to function correctly:
> > 
> > * `/dev/null` - device node, required by POSIX
> > 
> > * `/dev/tty` - device node, required by POSIX
> > 
> > * `/tmp` - required by POSIX to exist as a directory, and used by
> >   various temporary file creation functions.
> > 
> > * `/bin/sh` - an executable file providing as POSIX-conforming shell
> > 
> > * `/proc` - must be a mount point for Linux procfs or a symlink to
> >   such. Several functions such as realpath, fexecve, and a number of
> >   the "at" functions added in POSIX 2008 need access to /proc to
> >   function correctly.
> > 
> > While some programs may operate correctly even without some or all of
> > the above, musl's behavior in their absence is unspecified.
> > 
> 
> i would still add a note about the hardcoded program interpreter path
> in dynamically linked elf binaries that is required so the kernel can
> execute those binaries
> (referring back to the dynamic linking section about ld-musl-* and libc.so)
> (arguably this is not a musl runtime fs layout dependency, you can
> interpret the binary as './libc.so name', but is worth mentioning here)

Yes, I just forgot to add it.

> > ### Additional Pathnames Used
> > 
> > * `/dev/log` - a UNIX domain socket to which the `syslog()` interface
> >   sends log messages. If absent or inaccessible, log messages will be
> >   discarded.
> > 
> > * `/dev/shm` - a directory; should have permissions 01777. If absent,
> >   POSIX shared memory and named semaphore interfaces will fail;
> >   programs not using these features will be unaffected.
> > 
> > * `/dev/ptmx` and `/dev/pts` - device node and devpts filesystem mount
> >   point, respectively. If absent or inaccessible, `posix_openpt()` and
> >   `openpty()` will fail.
> > 
> > * `/etc/passwd` and `/etc/group` - text files containing the user and
> >   group databases, mappings between names and numeric ids, and group
> >   membership lists, in the standard traditional format. If absent,
> >   user and/or group lookups will fail.
> > 
> > * `/etc/shadow` - text file containing shadow password hashes for some
> >   or all users.
> 
> what about /etc/tcb/.. that can be used optionally?

Yes, this should still be added too.

> > * `/etc/resolv.conf` - text file providing addresses of nameservers to
> >   be used for DNS lookups. If absent, DNS requests will be sent to the
> >   loopback address and will fail unless the host has its own
> >   nameserver.
> > 
> > * `/etc/hosts` - text file mapping hostnames to IP addresses.
> > 
> > * `/etc/services` - text file mapping network service names to port
> >   numbers.
> > 
> > * `/usr/share/zoneinfo`, `/share/zoneinfo`, and `/etc/zoneinfo` -
> >   directories searched for time zone files when the `TZ` environment
> >   variable is set to a relative pathname.
> > 
> > * `../etc/ld-musl-$(ARCH).path`, taken relative to the location of the
> >   "program interpreter" specified in the program's headers - if
> >   present, this will be processed as a text file containing the shared
> >   library search path, with components delimited by newlines or
> >   colons. If absent, a default path of
> >   `"/lib:/usr/local/lib:/usr/lib"` will be used. Not used by
> >   static-linked programs.
> 
> there is the legacy getusershell api which uses /etc/shells

This could be added as well.

> mntent.h defines MOUNTED as /etc/mtab but that's not hardcoded
> into the libc

Probably doesn't need to be included. This is an app issue.

> > Part III - Library Usage for Development
> > ----------------------------------------
> > 
> > ### Compiler Support
> > 
> > All public interfaces in musl, at both the header file and library
> > level, are intended to be mostly compatible with any C99, C11, or C++
> > compiler targetting the same CPU architecture and ABI musl was built
> > for. C89 compilers are also supported provided that they accept the
> > `long long` type as an extension. A few public header files do,
> 
> stdint.h uses L' ' wide char literal which is technically
> not c89 but c94/amd1

OK, noted.

> there is another minor c89 issue (at least in math.h):
> in c89 struct/union/array members cannot be initialized from a function
> argument directly and gcc warns about them with -ansi -pedantic
> (it also warns about long long so it's not a big deal, but i
> can fix this)

Do you mean the initializers can't be non-constant-expressions? Or is
the issue more subtle?

> > however, require compiler-specific extensions in order to provide the
> > mandated standard features:
> > 
> > * `complex.h` requires `1.0fi` to be accepted as a constant expression
> >   suitable for defining `_Complex_I`.
> > 
> > * `tgmath.h` requires the `__typeof__` extension.
> > 
> > * FIXME: is this list complete?
> 
> stdarg.h requires __builtin_va_* (+headers that use va_list)

Yes. Thanks.

> NAN in math.h with fenv access support requires __builtin_nanf("")
> (in theory if fenv access is on then 0/0.0f raises the invalid
> flag at runtime except when used in static initializers)

Use of __builtin_nanf("") is conditional on __GNUC__. By default,
0.0f/0.0f is used.

> for pedants stddef requires __builtin_offsetof

This also has a non-__GNUC__ fallback, but it may fail to be a
constant expression, yielding slightly incorrect semantics.

> > * `_GNU_SOURCE` (or `_ALL_SOURCE`)
> > 
> >     Adds everything above, plus interfaces modelef after GNU libc
> 
> typo

You're the third one to report it. :-)

Rich