[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20130906154730.GH20515@brightrain.aerifal.cx>
Date: Fri, 6 Sep 2013 11:47:30 -0400
From: Rich Felker <dalias@...ifal.cx>
To: musl@...ts.openwall.com
Subject: Re: Third draft of musl documentation/manual
On Fri, Sep 06, 2013 at 05:14:56PM +0200, Szabolcs Nagy wrote:
> * Rich Felker <dalias@...ifal.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
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.
