Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Fri, 6 Sep 2013 17:14:56 +0200
From: Szabolcs Nagy <>
Subject: Re: Third draft of musl documentation/manual

* Rich Felker <> [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

and then

grep -r --color=always -C2 -i implementation-defined basedefs/ functions/ |less -R

> ### 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

> #### 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

> ### 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
(arguably this is not a musl runtime fs layout dependency, you can
interpret the binary as './ name', but is worth mentioning here)

> ### 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?

> * `/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

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

> 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

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)

> 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)

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)

for pedants stddef requires __builtin_offsetof

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


>     extensions and interfaces for making use of Linux-specific
>     features.
> The specific extensions provided by the nonstandard feature test
> macros are documented in subsequent sections of this manual.

Powered by blists - more mailing lists

Confused about mailing lists and their use? Read about mailing lists on Wikipedia and check out these guidelines on proper formatting of your messages.