From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/4020 Path: news.gmane.org!not-for-mail From: Rich Felker Newsgroups: gmane.linux.lib.musl.general Subject: Re: Third draft of musl documentation/manual Date: Fri, 6 Sep 2013 11:47:30 -0400 Message-ID: <20130906154730.GH20515@brightrain.aerifal.cx> References: <20130901044106.GA29630@brightrain.aerifal.cx> <20130906042043.GF20515@brightrain.aerifal.cx> <20130906151455.GS5116@port70.net> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1378482463 7762 80.91.229.3 (6 Sep 2013 15:47:43 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 6 Sep 2013 15:47:43 +0000 (UTC) To: musl@lists.openwall.com Original-X-From: musl-return-4024-gllmg-musl=m.gmane.org@lists.openwall.com Fri Sep 06 17:47:47 2013 Return-path: Envelope-to: gllmg-musl@plane.gmane.org Original-Received: from mother.openwall.net ([195.42.179.200]) by plane.gmane.org with smtp (Exim 4.69) (envelope-from ) id 1VHyG9-0004dX-D9 for gllmg-musl@plane.gmane.org; Fri, 06 Sep 2013 17:47:45 +0200 Original-Received: (qmail 30461 invoked by uid 550); 6 Sep 2013 15:47:44 -0000 Mailing-List: contact musl-help@lists.openwall.com; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Original-Received: (qmail 30447 invoked from network); 6 Sep 2013 15:47:43 -0000 Content-Disposition: inline In-Reply-To: <20130906151455.GS5116@port70.net> User-Agent: Mutt/1.5.21 (2010-09-15) Xref: news.gmane.org gmane.linux.lib.musl.general:4020 Archived-At: On Fri, Sep 06, 2013 at 05:14:56PM +0200, Szabolcs Nagy wrote: > * 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 > > 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