musl 1.1.24 (Draft) Reference Manual

Part I - Introduction

musl is an implementation of the userspace portion of the standard library functionality described in the ISO C and POSIX standards, plus common extensions. It can be used both as the system-wide C library for operating system installations and distributions, and as a tool for building individual application binaries deployable on a wide range of systems compatible with the Linux system calls API.

This manual covers many details of musl which may be of interest to programmers, systems integrators, and end users. It is a work in progress.

Conformance

The interfaces in musl are modeled upon and intended to conform to the requirements of the ISO C11 standard (ISO/IEC 9899-2011), including Annex F, and POSIX 2008 / Single Unix Standard Version 4, with all current technical corrigenda applied. However, musl has not been certified by any standards body, and no guarantee of conformance is made by the copyright holders or any other party with an interest in musl.

Moreover, since musl provides only the userspace portion of the standard system interfaces, conformance to the requirements of POSIX depends in part on the behavior of the underlying kernel. Linux 2.6.39 or later is believed to be sufficient; earlier versions in the 2.6 series will work, but with varying degrees of non-conformance, particularly in the area of signal handling behavior and close-on-exec race conditions.

Likewise, conformance to the requirements of ISO C, and especially Annex F (IEEE floating point semantics), depends in part on both the compiler used to build musl and the compiler used when building applications against musl. At this time there is no known fully conforming compiler.

Supported Targets

The following targets architectures are supported, and unless otherwise noted should be fully functional. Targets described as "experimental" are available for build, but may not work correctly and may not yet have ABI stability.

x86 / IA32 (i386)

Despite the name, the minimum supported CPU model is actually 80486 unless kernel emulation of the cmpxchg instruction is added.

x86_64 / AMD64 (x86_64, x32)

Both the standard LP64 ABI and the "x32" ILP32 ABI are supported, but the latter is experimental.

ARM (arm[eb][hf])

All ARM targets use the EABI, which requires armv4t or later. The default target is little-endian and uses the standard EABI where floating point arguments are passed in general-purpose registers. Hard-float ABI and big-endian variants are also supported.

AArch64 (aarch64[_be])

The default AArch64 target is little-endian. A big-endian variant is also supported. This target is experimental.

MIPS (mips[r6][el][-sf], mips64[r6][el][-sf], mipsn32[r6][el][-sf])

All 32-bit MIPS targets use the o32 ABI. For 64-bit, both the standard LP64 ABI and the "n32" ILP32 ABI are supported. The default target is big-endian and uses FPU registers for floating point arguments. Little-endian and soft-float ABI variants are also supported.

For early MIPS models lacking ll/sc atomics or the rdhwr TLS register, kernel emulation of these features is mandatory; this is standard on Linux.

PowerPC (powerpc[-sf], powerpc64[le])

For 32-bit, only big-endian is supported. Hard-float is default but thre is a soft-float option, mainly intended for use with Freescale CPUs that use an incompatible FPU. In addition, the following non-default toolchain configurations are mandatory: long double must be implemented as 64-bit IEEE double (not IBM double-double), and for dynamic linking to be supported, the "secure PLT" variant must be selected.

For 64-bit, both little and big endian are supported and use the new ("ELFv2") ABI. This differs from tradition on non-musl systems where big endian used the old ABI. As with 32-bit, long double must be implemented as 64-bit IEEE double (not IBM double-double)

RISC-V (riscv64[-sp|-sf])

The default ABI is hard-float; soft-float and single-precision-only FPU variants are also available but experimental.

Only 64-bit is supported.

Microblaze (microblaze[el])

The Microblaze target is big-endian and soft-float by default. A little-endian variant is also supported. The lwx and swx atomic instructions, which were missing on early Microblaze versions, are mandatory.

OpenRISC 1000 (or1k)

No target/ABI variants exist for OpenRISC 1000. It is always big-endian with soft-float.

SuperH (sh[eb][-nofpu][-fdpic])

SuperH targets are little-endian and hard-float by default. Big-endian and soft-float variants are also supported. An alternate FDPIC ABI is also supported, admitting shared program text on targets without an MMU.

Some CPU models have only a single-precision FPU; these must use the soft-float ABI. Compiler configurations that redefine the double type as single-precision are not supported.

IBM S/390 (s390x)

Only 64-bit is supported.

Motorola 680x0 (m68k)

Only hard-float is supported.

Part II - Setup and Usage

Build and Installation

The build system for musl uses the well-known ./configure idiom. musl's configure script is not based on GNU autoconf, but is intended to closely match the configure command line interface documented in the GNU Coding Standards. Running configure produces a config.mak file which can further be edited by hand, if necessary.

Prerequisites

The only build-time prerequisites for musl are the standard POSIX shell and utilities, GNU Make (version 3.81 or later) and an appropriate freestanding C99 compiler toolchain (see below) targeting the desired instruction set architecture and ABI.

The system used to build musl does not need to be Linux-based, nor do the Linux kernel headers need to be available.

Compiler Requirements

Building musl requires a conforming C99 compiler that can target a freestanding environment, plus the following extensions:

To build musl as a shared library and dynamic linker, the compiler must also support generation of position-independent code via -fPIC.

Specific Compilers and Versions

Recent versions of GCC or LLVM/clang are recommended for building musl. Other compilers may work but are not as widely tested.

For i386 targets, GCC versions prior to 4.6 fail to handle excess floating point precision in a conforming manner; this may affect the behavior of some math functions. If this is not a concern, GCC versions as early as 3.4.6, and possibly earlier, can be used.

LLVM/clang versions prior to 3.2 are unable to build musl due to PR #13694.

Firm/cparser can build musl as a static library, but lack of support for position-independent code generation precludes building a shared library. At times there have been regressions which break musl.

PCC can build musl as a static or shared library. Versions prior to a 1.2.0.DEVEL 20150512 have known bugs which affect the dynamic linker for i386. Regressions in PCC have frequently affected musl, so the current status of the compiler and its compatibility with musl should be checked before usea.

Build options

Running ./configure --help from the top-level source directory will print usage information for configure. In most cases, the only options which should be needed are:

Both --prefix and --syslibdir should reflect the final runtime location where musl will be installed. If musl should be installed to a different location to prepare a package file or new target system image, the DESTDIR variable can be set when running make install. In this case, DESTDIR will be prepended to all installation paths, but will not be saved anywhere in the files installed.

Other build options of interest are:

See ./configure --help for additional options.

Compiling and Installing

After running configure, run make to compile and make install to install. If desired, make install can be invoked directly without first running make, but it may be desirable to do these as separate steps if elevated privileges are needed to install to the final destination. musl's makefile is fully declarative and non-recursive, and may be arbitrarily parallelized with the -j option.

Note: The install target in musl's Makefile is also declarative, and its proper operation depends on file timestamps being correct. If files with newer/future timestamps already exist in the destination, updated files may fail to be installed. This can be avoided by deleting the offending files, fixing their timestamps, or installing first to a fresh DESTDIR then moving the files into place.

After Installation

If installing for the first time and using dynamic linking, it may be necessary to create a path file for the dynamic linker. See ../etc/ld-musl-$(ARCH).path under the heading Additional Files Used later in this part of the manual.

Installed Components

In the following, $(syslibdir), $(includedir), and $(libdir) refer to the paths chosen at build time (by default, /lib, $(prefix)/include, and $(prefix)/lib, respectively) and $(ARCH) refers to the full name for the target CPU architecture/ABI, including the "subarch" component.

Dynamic linking runtime

$(syslibdir)/ld-musl-$(ARCH).so.1 provides the dynamic linker, or "program interpreter", for dynamically linked ELF programs using musl. The absolute pathname to this file must be stored in all such programs. The build and installation system provided with musl sets it up as a symbolic link to $(libdir)/libc.so, but system integrators may choose to make it available in whichever ways they find suitable.

Development environment

Header files for use by the C compiler are installed in $(includedir). The standard headers are fully self-contained, and do not make use of kernel-provided or compiler-provided headers or otherwise require such headers to be present.

The file libc.a installed in $(libdir) provides the entire standard library implementation for static linking. The file libc.so provides the linker with access to the standard library's symbols for use at link-time in producing dynamic-linked binaries. It is not searched at runtime; the standard library is resolved as part of the program interpreter at $(syslibdir)/ld-musl-$(ARCH).so.1.

Additional files libm.a, librt.a, libpthread.a, libcrypt.a, libutil.a, libxnet.a, libresolv.a, and libdl.a are provided in $(libdir) as empty library archives. They contain no code, but are present to satisfy the POSIX requirement that options of the form -lm, -lpthread, etc. be accepted by the c99 compiler.

Several bare object files are also included in $(libdir): crt1.o and Scrt1.o are the normal and position-independent versions, respectively, of the entry point code linked into every program. crti.o and crtn.o, also linked into every program and into shared libraries, provide support for legacy means by which the compiler can arrange for global constructors and destructors to be executed. It is possible to setup a legacy-free compiler toolchain that does not need the crti.o and crtn.o files if desired.

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.

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:

While some programs may operate correctly even without some or all of the above, musl's behavior in their absence is unspecified.

Additional Files Used

Environment Variables

Part III - Programmers' Manual

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 targeting the same CPU architecture and ABI musl was built for. C89 compilers are also supported provided that they accept the long long type and wide character literals as extensions. A few public header files do, however, require compiler-specific extensions in order to provide the mandated standard features:

In addition, the definitions of NAN (in math.h) and offsetof (in stddef.h) require the __builtin_nanf and __builtin_offsetof extensions, respectively, to provide fully conforming definitions. When used with compilers which do not predefine __GNUC__, these headers will fallback to alternate definitions.

System Header Files

Introduction to Namespace Issues

Any C program using a library, whether the standard library or a third-party library, needs to observe a contract with the library regarding usage of identifiers - in particular, which identifiers are used as part of the library's public interface or header file implementation, and which identifiers are used by the application. Having a clear contract is especially important when the library being used is not a single fixed implementation, but may have multiple versions or multiple independent implementations. The canonical example of such a library is the standard library.

ISO C reserves all identifiers which are not explicitly defined or reserved by the standard for use by the application. POSIX, however, exposes a number of additional identifiers, and popular extensions outside of the standards define even more. In order to support applications which are written with different expectations on which identifiers may be used for the application's purposes, and which ones are defined by the system, a mechanism must be provided for choosing which contract will be used.

Introduction to Feature Test Macros

To solve this problem, POSIX introduced the concept of feature test macros. These are macros which an application may define prior to the inclusion of any system header (either at the source level, or via -D options passed as arguments to the compiler) in order to request a particular namespace contract. POSIX 2008 specifies two such feature test macros:

No requirements are placed on the namespace when neither of these macros is defined by the application. If one or both of these macros is defined by the application, two constraints are placed on the system headers:

There is, however, an exception to the second rule: since the standard does not define behavior when the application has defined macros whose names are reserved for system use, implementations may specify their own feature test macros to expose additional identifiers alongside the standard ones.

This is what musl, and most other implementations of the standard library, do.

Feature Test Macros Supported by musl

If no feature test macros are defined, musl's headers operate in "default features" mode, exposing the equivalent of the _BSD_SOURCE option below. This corresponds fairly well to what most applications unaware of feature test macros expect, and also provides a number of more modern features.

Otherwise, if at least one of the below-listed feature test macros is defined, they are treated additively, starting from pure ISO C as a base. Unless otherwise specified, musl ignores the value of the macro and only checks whether it is defined.

Documentation of specific extensions provided by the nonstandard feature test macros will be added in a future edition of this manual.

Library Interfaces

For all interfaces provided by musl that are specified by standards to which musl aims for conformance, the relevant standards documents are the official documentation.

This portion of the manual is incomplete. Future editions will document musl's behavior where the standards specify that it is implementation-defined, non-standard extensions musl implements, and additional properties of musl's implementation.