This is
/ldhome/software/toolsbuild/slave2/workspace/Toolchain/release-riscv-0/build-riscv-gcc-riscv64-unknown-linux-gnu/build-riscv64-linux-x86_64/build-glibc-linux-rv64imafdcvxtheadc-lp64dv/manual/libc.info,
produced by makeinfo version 4.9 from libc.texinfo.

INFO-DIR-SECTION Software libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION GNU C library functions and macros
START-INFO-DIR-ENTRY
* ALTWERASE: (libc)Local Modes.
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
* ARG_MAX: (libc)General Limits.
* BC_BASE_MAX: (libc)Utility Limits.
* BC_DIM_MAX: (libc)Utility Limits.
* BC_SCALE_MAX: (libc)Utility Limits.
* BC_STRING_MAX: (libc)Utility Limits.
* BRKINT: (libc)Input Modes.
* BUFSIZ: (libc)Controlling Buffering.
* CCTS_OFLOW: (libc)Control Modes.
* CHAR_BIT: (libc)Width of Type.
* CHILD_MAX: (libc)General Limits.
* CIGNORE: (libc)Control Modes.
* CLK_TCK: (libc)Processor Time.
* CLOCAL: (libc)Control Modes.
* CLOCKS_PER_SEC: (libc)CPU Time.
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
* CPU_CLR: (libc)CPU Affinity.
* CPU_ISSET: (libc)CPU Affinity.
* CPU_SET: (libc)CPU Affinity.
* CPU_SETSIZE: (libc)CPU Affinity.
* CPU_ZERO: (libc)CPU Affinity.
* CREAD: (libc)Control Modes.
* CRTS_IFLOW: (libc)Control Modes.
* CS5: (libc)Control Modes.
* CS6: (libc)Control Modes.
* CS7: (libc)Control Modes.
* CS8: (libc)Control Modes.
* CSIZE: (libc)Control Modes.
* CSTOPB: (libc)Control Modes.
* DTTOIF: (libc)Directory Entries.
* E2BIG: (libc)Error Codes.
* EACCES: (libc)Error Codes.
* EADDRINUSE: (libc)Error Codes.
* EADDRNOTAVAIL: (libc)Error Codes.
* EADV: (libc)Error Codes.
* EAFNOSUPPORT: (libc)Error Codes.
* EAGAIN: (libc)Error Codes.
* EALREADY: (libc)Error Codes.
* EAUTH: (libc)Error Codes.
* EBACKGROUND: (libc)Error Codes.
* EBADE: (libc)Error Codes.
* EBADF: (libc)Error Codes.
* EBADFD: (libc)Error Codes.
* EBADMSG: (libc)Error Codes.
* EBADR: (libc)Error Codes.
* EBADRPC: (libc)Error Codes.
* EBADRQC: (libc)Error Codes.
* EBADSLT: (libc)Error Codes.
* EBFONT: (libc)Error Codes.
* EBUSY: (libc)Error Codes.
* ECANCELED: (libc)Error Codes.
* ECHILD: (libc)Error Codes.
* ECHO: (libc)Local Modes.
* ECHOCTL: (libc)Local Modes.
* ECHOE: (libc)Local Modes.
* ECHOK: (libc)Local Modes.
* ECHOKE: (libc)Local Modes.
* ECHONL: (libc)Local Modes.
* ECHOPRT: (libc)Local Modes.
* ECHRNG: (libc)Error Codes.
* ECOMM: (libc)Error Codes.
* ECONNABORTED: (libc)Error Codes.
* ECONNREFUSED: (libc)Error Codes.
* ECONNRESET: (libc)Error Codes.
* ED: (libc)Error Codes.
* EDEADLK: (libc)Error Codes.
* EDEADLOCK: (libc)Error Codes.
* EDESTADDRREQ: (libc)Error Codes.
* EDIED: (libc)Error Codes.
* EDOM: (libc)Error Codes.
* EDOTDOT: (libc)Error Codes.
* EDQUOT: (libc)Error Codes.
* EEXIST: (libc)Error Codes.
* EFAULT: (libc)Error Codes.
* EFBIG: (libc)Error Codes.
* EFTYPE: (libc)Error Codes.
* EGRATUITOUS: (libc)Error Codes.
* EGREGIOUS: (libc)Error Codes.
* EHOSTDOWN: (libc)Error Codes.
* EHOSTUNREACH: (libc)Error Codes.
* EHWPOISON: (libc)Error Codes.
* EIDRM: (libc)Error Codes.
* EIEIO: (libc)Error Codes.
* EILSEQ: (libc)Error Codes.
* EINPROGRESS: (libc)Error Codes.
* EINTR: (libc)Error Codes.
* EINVAL: (libc)Error Codes.
* EIO: (libc)Error Codes.
* EISCONN: (libc)Error Codes.
* EISDIR: (libc)Error Codes.
* EISNAM: (libc)Error Codes.
* EKEYEXPIRED: (libc)Error Codes.
* EKEYREJECTED: (libc)Error Codes.
* EKEYREVOKED: (libc)Error Codes.
* EL2HLT: (libc)Error Codes.
* EL2NSYNC: (libc)Error Codes.
* EL3HLT: (libc)Error Codes.
* EL3RST: (libc)Error Codes.
* ELIBACC: (libc)Error Codes.
* ELIBBAD: (libc)Error Codes.
* ELIBEXEC: (libc)Error Codes.
* ELIBMAX: (libc)Error Codes.
* ELIBSCN: (libc)Error Codes.
* ELNRNG: (libc)Error Codes.
* ELOOP: (libc)Error Codes.
* EMEDIUMTYPE: (libc)Error Codes.
* EMFILE: (libc)Error Codes.
* EMLINK: (libc)Error Codes.
* EMSGSIZE: (libc)Error Codes.
* EMULTIHOP: (libc)Error Codes.
* ENAMETOOLONG: (libc)Error Codes.
* ENAVAIL: (libc)Error Codes.
* ENEEDAUTH: (libc)Error Codes.
* ENETDOWN: (libc)Error Codes.
* ENETRESET: (libc)Error Codes.
* ENETUNREACH: (libc)Error Codes.
* ENFILE: (libc)Error Codes.
* ENOANO: (libc)Error Codes.
* ENOBUFS: (libc)Error Codes.
* ENOCSI: (libc)Error Codes.
* ENODATA: (libc)Error Codes.
* ENODEV: (libc)Error Codes.
* ENOENT: (libc)Error Codes.
* ENOEXEC: (libc)Error Codes.
* ENOKEY: (libc)Error Codes.
* ENOLCK: (libc)Error Codes.
* ENOLINK: (libc)Error Codes.
* ENOMEDIUM: (libc)Error Codes.
* ENOMEM: (libc)Error Codes.
* ENOMSG: (libc)Error Codes.
* ENONET: (libc)Error Codes.
* ENOPKG: (libc)Error Codes.
* ENOPROTOOPT: (libc)Error Codes.
* ENOSPC: (libc)Error Codes.
* ENOSR: (libc)Error Codes.
* ENOSTR: (libc)Error Codes.
* ENOSYS: (libc)Error Codes.
* ENOTBLK: (libc)Error Codes.
* ENOTCONN: (libc)Error Codes.
* ENOTDIR: (libc)Error Codes.
* ENOTEMPTY: (libc)Error Codes.
* ENOTNAM: (libc)Error Codes.
* ENOTRECOVERABLE: (libc)Error Codes.
* ENOTSOCK: (libc)Error Codes.
* ENOTSUP: (libc)Error Codes.
* ENOTTY: (libc)Error Codes.
* ENOTUNIQ: (libc)Error Codes.
* ENXIO: (libc)Error Codes.
* EOF: (libc)EOF and Errors.
* EOPNOTSUPP: (libc)Error Codes.
* EOVERFLOW: (libc)Error Codes.
* EOWNERDEAD: (libc)Error Codes.
* EPERM: (libc)Error Codes.
* EPFNOSUPPORT: (libc)Error Codes.
* EPIPE: (libc)Error Codes.
* EPROCLIM: (libc)Error Codes.
* EPROCUNAVAIL: (libc)Error Codes.
* EPROGMISMATCH: (libc)Error Codes.
* EPROGUNAVAIL: (libc)Error Codes.
* EPROTO: (libc)Error Codes.
* EPROTONOSUPPORT: (libc)Error Codes.
* EPROTOTYPE: (libc)Error Codes.
* EQUIV_CLASS_MAX: (libc)Utility Limits.
* ERANGE: (libc)Error Codes.
* EREMCHG: (libc)Error Codes.
* EREMOTE: (libc)Error Codes.
* EREMOTEIO: (libc)Error Codes.
* ERESTART: (libc)Error Codes.
* ERFKILL: (libc)Error Codes.
* EROFS: (libc)Error Codes.
* ERPCMISMATCH: (libc)Error Codes.
* ESHUTDOWN: (libc)Error Codes.
* ESOCKTNOSUPPORT: (libc)Error Codes.
* ESPIPE: (libc)Error Codes.
* ESRCH: (libc)Error Codes.
* ESRMNT: (libc)Error Codes.
* ESTALE: (libc)Error Codes.
* ESTRPIPE: (libc)Error Codes.
* ETIME: (libc)Error Codes.
* ETIMEDOUT: (libc)Error Codes.
* ETOOMANYREFS: (libc)Error Codes.
* ETXTBSY: (libc)Error Codes.
* EUCLEAN: (libc)Error Codes.
* EUNATCH: (libc)Error Codes.
* EUSERS: (libc)Error Codes.
* EWOULDBLOCK: (libc)Error Codes.
* EXDEV: (libc)Error Codes.
* EXFULL: (libc)Error Codes.
* EXIT_FAILURE: (libc)Exit Status.
* EXIT_SUCCESS: (libc)Exit Status.
* EXPR_NEST_MAX: (libc)Utility Limits.
* FD_CLOEXEC: (libc)Descriptor Flags.
* FD_CLR: (libc)Waiting for I/O.
* FD_ISSET: (libc)Waiting for I/O.
* FD_SET: (libc)Waiting for I/O.
* FD_SETSIZE: (libc)Waiting for I/O.
* FD_ZERO: (libc)Waiting for I/O.
* FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
* FILENAME_MAX: (libc)Limits for Files.
* FLUSHO: (libc)Local Modes.
* FOPEN_MAX: (libc)Opening Streams.
* FP_ILOGB0: (libc)Exponents and Logarithms.
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
* FP_LLOGB0: (libc)Exponents and Logarithms.
* FP_LLOGBNAN: (libc)Exponents and Logarithms.
* F_DUPFD: (libc)Duplicating Descriptors.
* F_GETFD: (libc)Descriptor Flags.
* F_GETFL: (libc)Getting File Status Flags.
* F_GETLK: (libc)File Locks.
* F_GETOWN: (libc)Interrupt Input.
* F_OFD_GETLK: (libc)Open File Description Locks.
* F_OFD_SETLK: (libc)Open File Description Locks.
* F_OFD_SETLKW: (libc)Open File Description Locks.
* F_OK: (libc)Testing File Access.
* F_SETFD: (libc)Descriptor Flags.
* F_SETFL: (libc)Getting File Status Flags.
* F_SETLK: (libc)File Locks.
* F_SETLKW: (libc)File Locks.
* F_SETOWN: (libc)Interrupt Input.
* HUGE_VAL: (libc)Math Error Reporting.
* HUGE_VALF: (libc)Math Error Reporting.
* HUGE_VALL: (libc)Math Error Reporting.
* HUGE_VAL_FN: (libc)Math Error Reporting.
* HUGE_VAL_FNx: (libc)Math Error Reporting.
* HUPCL: (libc)Control Modes.
* I: (libc)Complex Numbers.
* ICANON: (libc)Local Modes.
* ICRNL: (libc)Input Modes.
* IEXTEN: (libc)Local Modes.
* IFNAMSIZ: (libc)Interface Naming.
* IFTODT: (libc)Directory Entries.
* IGNBRK: (libc)Input Modes.
* IGNCR: (libc)Input Modes.
* IGNPAR: (libc)Input Modes.
* IMAXBEL: (libc)Input Modes.
* INADDR_ANY: (libc)Host Address Data Type.
* INADDR_BROADCAST: (libc)Host Address Data Type.
* INADDR_LOOPBACK: (libc)Host Address Data Type.
* INADDR_NONE: (libc)Host Address Data Type.
* INFINITY: (libc)Infinity and NaN.
* INLCR: (libc)Input Modes.
* INPCK: (libc)Input Modes.
* IPPORT_RESERVED: (libc)Ports.
* IPPORT_USERRESERVED: (libc)Ports.
* ISIG: (libc)Local Modes.
* ISTRIP: (libc)Input Modes.
* IXANY: (libc)Input Modes.
* IXOFF: (libc)Input Modes.
* IXON: (libc)Input Modes.
* LINE_MAX: (libc)Utility Limits.
* LINK_MAX: (libc)Limits for Files.
* L_ctermid: (libc)Identifying the Terminal.
* L_cuserid: (libc)Who Logged In.
* L_tmpnam: (libc)Temporary Files.
* MAXNAMLEN: (libc)Limits for Files.
* MAXSYMLINKS: (libc)Symbolic Links.
* MAX_CANON: (libc)Limits for Files.
* MAX_INPUT: (libc)Limits for Files.
* MB_CUR_MAX: (libc)Selecting the Conversion.
* MB_LEN_MAX: (libc)Selecting the Conversion.
* MDMBUF: (libc)Control Modes.
* MSG_DONTROUTE: (libc)Socket Data Options.
* MSG_OOB: (libc)Socket Data Options.
* MSG_PEEK: (libc)Socket Data Options.
* NAME_MAX: (libc)Limits for Files.
* NAN: (libc)Infinity and NaN.
* NCCS: (libc)Mode Data Types.
* NGROUPS_MAX: (libc)General Limits.
* NOFLSH: (libc)Local Modes.
* NOKERNINFO: (libc)Local Modes.
* NSIG: (libc)Standard Signals.
* NULL: (libc)Null Pointer Constant.
* ONLCR: (libc)Output Modes.
* ONOEOT: (libc)Output Modes.
* OPEN_MAX: (libc)General Limits.
* OPOST: (libc)Output Modes.
* OXTABS: (libc)Output Modes.
* O_ACCMODE: (libc)Access Modes.
* O_APPEND: (libc)Operating Modes.
* O_ASYNC: (libc)Operating Modes.
* O_CREAT: (libc)Open-time Flags.
* O_EXCL: (libc)Open-time Flags.
* O_EXEC: (libc)Access Modes.
* O_EXLOCK: (libc)Open-time Flags.
* O_FSYNC: (libc)Operating Modes.
* O_IGNORE_CTTY: (libc)Open-time Flags.
* O_NDELAY: (libc)Operating Modes.
* O_NOATIME: (libc)Operating Modes.
* O_NOCTTY: (libc)Open-time Flags.
* O_NOLINK: (libc)Open-time Flags.
* O_NONBLOCK: (libc)Open-time Flags.
* O_NONBLOCK: (libc)Operating Modes.
* O_NOTRANS: (libc)Open-time Flags.
* O_RDONLY: (libc)Access Modes.
* O_RDWR: (libc)Access Modes.
* O_READ: (libc)Access Modes.
* O_SHLOCK: (libc)Open-time Flags.
* O_SYNC: (libc)Operating Modes.
* O_TMPFILE: (libc)Open-time Flags.
* O_TRUNC: (libc)Open-time Flags.
* O_WRITE: (libc)Access Modes.
* O_WRONLY: (libc)Access Modes.
* PARENB: (libc)Control Modes.
* PARMRK: (libc)Input Modes.
* PARODD: (libc)Control Modes.
* PATH_MAX: (libc)Limits for Files.
* PA_FLAG_MASK: (libc)Parsing a Template String.
* PENDIN: (libc)Local Modes.
* PF_FILE: (libc)Local Namespace Details.
* PF_INET6: (libc)Internet Namespace.
* PF_INET: (libc)Internet Namespace.
* PF_LOCAL: (libc)Local Namespace Details.
* PF_UNIX: (libc)Local Namespace Details.
* PIPE_BUF: (libc)Limits for Files.
* P_tmpdir: (libc)Temporary Files.
* RAND_MAX: (libc)ISO Random.
* RE_DUP_MAX: (libc)General Limits.
* RLIM_INFINITY: (libc)Limits on Resources.
* R_OK: (libc)Testing File Access.
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
* SA_ONSTACK: (libc)Flags for Sigaction.
* SA_RESTART: (libc)Flags for Sigaction.
* SEEK_CUR: (libc)File Positioning.
* SEEK_END: (libc)File Positioning.
* SEEK_SET: (libc)File Positioning.
* SIGABRT: (libc)Program Error Signals.
* SIGALRM: (libc)Alarm Signals.
* SIGBUS: (libc)Program Error Signals.
* SIGCHLD: (libc)Job Control Signals.
* SIGCLD: (libc)Job Control Signals.
* SIGCONT: (libc)Job Control Signals.
* SIGEMT: (libc)Program Error Signals.
* SIGFPE: (libc)Program Error Signals.
* SIGHUP: (libc)Termination Signals.
* SIGILL: (libc)Program Error Signals.
* SIGINFO: (libc)Miscellaneous Signals.
* SIGINT: (libc)Termination Signals.
* SIGIO: (libc)Asynchronous I/O Signals.
* SIGIOT: (libc)Program Error Signals.
* SIGKILL: (libc)Termination Signals.
* SIGLOST: (libc)Operation Error Signals.
* SIGPIPE: (libc)Operation Error Signals.
* SIGPOLL: (libc)Asynchronous I/O Signals.
* SIGPROF: (libc)Alarm Signals.
* SIGQUIT: (libc)Termination Signals.
* SIGSEGV: (libc)Program Error Signals.
* SIGSTOP: (libc)Job Control Signals.
* SIGSYS: (libc)Program Error Signals.
* SIGTERM: (libc)Termination Signals.
* SIGTRAP: (libc)Program Error Signals.
* SIGTSTP: (libc)Job Control Signals.
* SIGTTIN: (libc)Job Control Signals.
* SIGTTOU: (libc)Job Control Signals.
* SIGURG: (libc)Asynchronous I/O Signals.
* SIGUSR1: (libc)Miscellaneous Signals.
* SIGUSR2: (libc)Miscellaneous Signals.
* SIGVTALRM: (libc)Alarm Signals.
* SIGWINCH: (libc)Miscellaneous Signals.
* SIGXCPU: (libc)Operation Error Signals.
* SIGXFSZ: (libc)Operation Error Signals.
* SIG_ERR: (libc)Basic Signal Handling.
* SNAN: (libc)Infinity and NaN.
* SNANF: (libc)Infinity and NaN.
* SNANFN: (libc)Infinity and NaN.
* SNANFNx: (libc)Infinity and NaN.
* SNANL: (libc)Infinity and NaN.
* SOCK_DGRAM: (libc)Communication Styles.
* SOCK_RAW: (libc)Communication Styles.
* SOCK_RDM: (libc)Communication Styles.
* SOCK_SEQPACKET: (libc)Communication Styles.
* SOCK_STREAM: (libc)Communication Styles.
* SOL_SOCKET: (libc)Socket-Level Options.
* SSIZE_MAX: (libc)General Limits.
* STREAM_MAX: (libc)General Limits.
* SUN_LEN: (libc)Local Namespace Details.
* S_IFMT: (libc)Testing File Type.
* S_ISBLK: (libc)Testing File Type.
* S_ISCHR: (libc)Testing File Type.
* S_ISDIR: (libc)Testing File Type.
* S_ISFIFO: (libc)Testing File Type.
* S_ISLNK: (libc)Testing File Type.
* S_ISREG: (libc)Testing File Type.
* S_ISSOCK: (libc)Testing File Type.
* S_TYPEISMQ: (libc)Testing File Type.
* S_TYPEISSEM: (libc)Testing File Type.
* S_TYPEISSHM: (libc)Testing File Type.
* TMP_MAX: (libc)Temporary Files.
* TOSTOP: (libc)Local Modes.
* TZNAME_MAX: (libc)General Limits.
* VDISCARD: (libc)Other Special.
* VDSUSP: (libc)Signal Characters.
* VEOF: (libc)Editing Characters.
* VEOL2: (libc)Editing Characters.
* VEOL: (libc)Editing Characters.
* VERASE: (libc)Editing Characters.
* VINTR: (libc)Signal Characters.
* VKILL: (libc)Editing Characters.
* VLNEXT: (libc)Other Special.
* VMIN: (libc)Noncanonical Input.
* VQUIT: (libc)Signal Characters.
* VREPRINT: (libc)Editing Characters.
* VSTART: (libc)Start/Stop Characters.
* VSTATUS: (libc)Other Special.
* VSTOP: (libc)Start/Stop Characters.
* VSUSP: (libc)Signal Characters.
* VTIME: (libc)Noncanonical Input.
* VWERASE: (libc)Editing Characters.
* WCHAR_MAX: (libc)Extended Char Intro.
* WCHAR_MIN: (libc)Extended Char Intro.
* WCOREDUMP: (libc)Process Completion Status.
* WEOF: (libc)EOF and Errors.
* WEOF: (libc)Extended Char Intro.
* WEXITSTATUS: (libc)Process Completion Status.
* WIFEXITED: (libc)Process Completion Status.
* WIFSIGNALED: (libc)Process Completion Status.
* WIFSTOPPED: (libc)Process Completion Status.
* WSTOPSIG: (libc)Process Completion Status.
* WTERMSIG: (libc)Process Completion Status.
* W_OK: (libc)Testing File Access.
* X_OK: (libc)Testing File Access.
* _Complex_I: (libc)Complex Numbers.
* _Exit: (libc)Termination Internals.
* _IOFBF: (libc)Controlling Buffering.
* _IOLBF: (libc)Controlling Buffering.
* _IONBF: (libc)Controlling Buffering.
* _Imaginary_I: (libc)Complex Numbers.
* _PATH_UTMP: (libc)Manipulating the Database.
* _PATH_WTMP: (libc)Manipulating the Database.
* _POSIX2_C_DEV: (libc)System Options.
* _POSIX2_C_VERSION: (libc)Version Supported.
* _POSIX2_FORT_DEV: (libc)System Options.
* _POSIX2_FORT_RUN: (libc)System Options.
* _POSIX2_LOCALEDEF: (libc)System Options.
* _POSIX2_SW_DEV: (libc)System Options.
* _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
* _POSIX_JOB_CONTROL: (libc)System Options.
* _POSIX_NO_TRUNC: (libc)Options for Files.
* _POSIX_SAVED_IDS: (libc)System Options.
* _POSIX_VDISABLE: (libc)Options for Files.
* _POSIX_VERSION: (libc)Version Supported.
* __fbufsize: (libc)Controlling Buffering.
* __flbf: (libc)Controlling Buffering.
* __fpending: (libc)Controlling Buffering.
* __fpurge: (libc)Flushing Buffers.
* __freadable: (libc)Opening Streams.
* __freading: (libc)Opening Streams.
* __fsetlocking: (libc)Streams and Threads.
* __fwritable: (libc)Opening Streams.
* __fwriting: (libc)Opening Streams.
* __gconv_end_fct: (libc)glibc iconv Implementation.
* __gconv_fct: (libc)glibc iconv Implementation.
* __gconv_init_fct: (libc)glibc iconv Implementation.
* __ppc_get_timebase: (libc)PowerPC.
* __ppc_get_timebase_freq: (libc)PowerPC.
* __ppc_mdoio: (libc)PowerPC.
* __ppc_mdoom: (libc)PowerPC.
* __ppc_set_ppr_low: (libc)PowerPC.
* __ppc_set_ppr_med: (libc)PowerPC.
* __ppc_set_ppr_med_high: (libc)PowerPC.
* __ppc_set_ppr_med_low: (libc)PowerPC.
* __ppc_set_ppr_very_low: (libc)PowerPC.
* __ppc_yield: (libc)PowerPC.
* __riscv_flush_icache: (libc)RISC-V.
* __va_copy: (libc)Argument Macros.
* _exit: (libc)Termination Internals.
* _flushlbf: (libc)Flushing Buffers.
* _tolower: (libc)Case Conversion.
* _toupper: (libc)Case Conversion.
* a64l: (libc)Encode Binary Data.
* abort: (libc)Aborting a Program.
* abs: (libc)Absolute Value.
* accept: (libc)Accepting Connections.
* access: (libc)Testing File Access.
* acos: (libc)Inverse Trig Functions.
* acosf: (libc)Inverse Trig Functions.
* acosfN: (libc)Inverse Trig Functions.
* acosfNx: (libc)Inverse Trig Functions.
* acosh: (libc)Hyperbolic Functions.
* acoshf: (libc)Hyperbolic Functions.
* acoshfN: (libc)Hyperbolic Functions.
* acoshfNx: (libc)Hyperbolic Functions.
* acoshl: (libc)Hyperbolic Functions.
* acosl: (libc)Inverse Trig Functions.
* addmntent: (libc)mtab.
* addseverity: (libc)Adding Severity Classes.
* adjtime: (libc)High-Resolution Calendar.
* adjtimex: (libc)High-Resolution Calendar.
* aio_cancel64: (libc)Cancel AIO Operations.
* aio_cancel: (libc)Cancel AIO Operations.
* aio_error64: (libc)Status of AIO Operations.
* aio_error: (libc)Status of AIO Operations.
* aio_fsync64: (libc)Synchronizing AIO Operations.
* aio_fsync: (libc)Synchronizing AIO Operations.
* aio_init: (libc)Configuration of AIO.
* aio_read64: (libc)Asynchronous Reads/Writes.
* aio_read: (libc)Asynchronous Reads/Writes.
* aio_return64: (libc)Status of AIO Operations.
* aio_return: (libc)Status of AIO Operations.
* aio_suspend64: (libc)Synchronizing AIO Operations.
* aio_suspend: (libc)Synchronizing AIO Operations.
* aio_write64: (libc)Asynchronous Reads/Writes.
* aio_write: (libc)Asynchronous Reads/Writes.
* alarm: (libc)Setting an Alarm.
* aligned_alloc: (libc)Aligned Memory Blocks.
* alloca: (libc)Variable Size Automatic.
* alphasort64: (libc)Scanning Directory Content.
* alphasort: (libc)Scanning Directory Content.
* argp_error: (libc)Argp Helper Functions.
* argp_failure: (libc)Argp Helper Functions.
* argp_help: (libc)Argp Help.
* argp_parse: (libc)Argp.
* argp_state_help: (libc)Argp Helper Functions.
* argp_usage: (libc)Argp Helper Functions.
* argz_add: (libc)Argz Functions.
* argz_add_sep: (libc)Argz Functions.
* argz_append: (libc)Argz Functions.
* argz_count: (libc)Argz Functions.
* argz_create: (libc)Argz Functions.
* argz_create_sep: (libc)Argz Functions.
* argz_delete: (libc)Argz Functions.
* argz_extract: (libc)Argz Functions.
* argz_insert: (libc)Argz Functions.
* argz_next: (libc)Argz Functions.
* argz_replace: (libc)Argz Functions.
* argz_stringify: (libc)Argz Functions.
* asctime: (libc)Formatting Calendar Time.
* asctime_r: (libc)Formatting Calendar Time.
* asin: (libc)Inverse Trig Functions.
* asinf: (libc)Inverse Trig Functions.
* asinfN: (libc)Inverse Trig Functions.
* asinfNx: (libc)Inverse Trig Functions.
* asinh: (libc)Hyperbolic Functions.
* asinhf: (libc)Hyperbolic Functions.
* asinhfN: (libc)Hyperbolic Functions.
* asinhfNx: (libc)Hyperbolic Functions.
* asinhl: (libc)Hyperbolic Functions.
* asinl: (libc)Inverse Trig Functions.
* asprintf: (libc)Dynamic Output.
* assert: (libc)Consistency Checking.
* assert_perror: (libc)Consistency Checking.
* atan2: (libc)Inverse Trig Functions.
* atan2f: (libc)Inverse Trig Functions.
* atan2fN: (libc)Inverse Trig Functions.
* atan2fNx: (libc)Inverse Trig Functions.
* atan2l: (libc)Inverse Trig Functions.
* atan: (libc)Inverse Trig Functions.
* atanf: (libc)Inverse Trig Functions.
* atanfN: (libc)Inverse Trig Functions.
* atanfNx: (libc)Inverse Trig Functions.
* atanh: (libc)Hyperbolic Functions.
* atanhf: (libc)Hyperbolic Functions.
* atanhfN: (libc)Hyperbolic Functions.
* atanhfNx: (libc)Hyperbolic Functions.
* atanhl: (libc)Hyperbolic Functions.
* atanl: (libc)Inverse Trig Functions.
* atexit: (libc)Cleanups on Exit.
* atof: (libc)Parsing of Floats.
* atoi: (libc)Parsing of Integers.
* atol: (libc)Parsing of Integers.
* atoll: (libc)Parsing of Integers.
* backtrace: (libc)Backtraces.
* backtrace_symbols: (libc)Backtraces.
* backtrace_symbols_fd: (libc)Backtraces.
* basename: (libc)Finding Tokens in a String.
* basename: (libc)Finding Tokens in a String.
* bcmp: (libc)String/Array Comparison.
* bcopy: (libc)Copying Strings and Arrays.
* bind: (libc)Setting Address.
* bind_textdomain_codeset: (libc)Charset conversion in gettext.
* bindtextdomain: (libc)Locating gettext catalog.
* brk: (libc)Resizing the Data Segment.
* bsearch: (libc)Array Search Function.
* btowc: (libc)Converting a Character.
* bzero: (libc)Copying Strings and Arrays.
* cabs: (libc)Absolute Value.
* cabsf: (libc)Absolute Value.
* cabsfN: (libc)Absolute Value.
* cabsfNx: (libc)Absolute Value.
* cabsl: (libc)Absolute Value.
* cacos: (libc)Inverse Trig Functions.
* cacosf: (libc)Inverse Trig Functions.
* cacosfN: (libc)Inverse Trig Functions.
* cacosfNx: (libc)Inverse Trig Functions.
* cacosh: (libc)Hyperbolic Functions.
* cacoshf: (libc)Hyperbolic Functions.
* cacoshfN: (libc)Hyperbolic Functions.
* cacoshfNx: (libc)Hyperbolic Functions.
* cacoshl: (libc)Hyperbolic Functions.
* cacosl: (libc)Inverse Trig Functions.
* call_once: (libc)Call Once.
* calloc: (libc)Allocating Cleared Space.
* canonicalize: (libc)FP Bit Twiddling.
* canonicalize_file_name: (libc)Symbolic Links.
* canonicalizef: (libc)FP Bit Twiddling.
* canonicalizefN: (libc)FP Bit Twiddling.
* canonicalizefNx: (libc)FP Bit Twiddling.
* canonicalizel: (libc)FP Bit Twiddling.
* carg: (libc)Operations on Complex.
* cargf: (libc)Operations on Complex.
* cargfN: (libc)Operations on Complex.
* cargfNx: (libc)Operations on Complex.
* cargl: (libc)Operations on Complex.
* casin: (libc)Inverse Trig Functions.
* casinf: (libc)Inverse Trig Functions.
* casinfN: (libc)Inverse Trig Functions.
* casinfNx: (libc)Inverse Trig Functions.
* casinh: (libc)Hyperbolic Functions.
* casinhf: (libc)Hyperbolic Functions.
* casinhfN: (libc)Hyperbolic Functions.
* casinhfNx: (libc)Hyperbolic Functions.
* casinhl: (libc)Hyperbolic Functions.
* casinl: (libc)Inverse Trig Functions.
* catan: (libc)Inverse Trig Functions.
* catanf: (libc)Inverse Trig Functions.
* catanfN: (libc)Inverse Trig Functions.
* catanfNx: (libc)Inverse Trig Functions.
* catanh: (libc)Hyperbolic Functions.
* catanhf: (libc)Hyperbolic Functions.
* catanhfN: (libc)Hyperbolic Functions.
* catanhfNx: (libc)Hyperbolic Functions.
* catanhl: (libc)Hyperbolic Functions.
* catanl: (libc)Inverse Trig Functions.
* catclose: (libc)The catgets Functions.
* catgets: (libc)The catgets Functions.
* catopen: (libc)The catgets Functions.
* cbrt: (libc)Exponents and Logarithms.
* cbrtf: (libc)Exponents and Logarithms.
* cbrtfN: (libc)Exponents and Logarithms.
* cbrtfNx: (libc)Exponents and Logarithms.
* cbrtl: (libc)Exponents and Logarithms.
* ccos: (libc)Trig Functions.
* ccosf: (libc)Trig Functions.
* ccosfN: (libc)Trig Functions.
* ccosfNx: (libc)Trig Functions.
* ccosh: (libc)Hyperbolic Functions.
* ccoshf: (libc)Hyperbolic Functions.
* ccoshfN: (libc)Hyperbolic Functions.
* ccoshfNx: (libc)Hyperbolic Functions.
* ccoshl: (libc)Hyperbolic Functions.
* ccosl: (libc)Trig Functions.
* ceil: (libc)Rounding Functions.
* ceilf: (libc)Rounding Functions.
* ceilfN: (libc)Rounding Functions.
* ceilfNx: (libc)Rounding Functions.
* ceill: (libc)Rounding Functions.
* cexp: (libc)Exponents and Logarithms.
* cexpf: (libc)Exponents and Logarithms.
* cexpfN: (libc)Exponents and Logarithms.
* cexpfNx: (libc)Exponents and Logarithms.
* cexpl: (libc)Exponents and Logarithms.
* cfgetispeed: (libc)Line Speed.
* cfgetospeed: (libc)Line Speed.
* cfmakeraw: (libc)Noncanonical Input.
* cfsetispeed: (libc)Line Speed.
* cfsetospeed: (libc)Line Speed.
* cfsetspeed: (libc)Line Speed.
* chdir: (libc)Working Directory.
* chmod: (libc)Setting Permissions.
* chown: (libc)File Owner.
* cimag: (libc)Operations on Complex.
* cimagf: (libc)Operations on Complex.
* cimagfN: (libc)Operations on Complex.
* cimagfNx: (libc)Operations on Complex.
* cimagl: (libc)Operations on Complex.
* clearenv: (libc)Environment Access.
* clearerr: (libc)Error Recovery.
* clearerr_unlocked: (libc)Error Recovery.
* clock: (libc)CPU Time.
* clog10: (libc)Exponents and Logarithms.
* clog10f: (libc)Exponents and Logarithms.
* clog10fN: (libc)Exponents and Logarithms.
* clog10fNx: (libc)Exponents and Logarithms.
* clog10l: (libc)Exponents and Logarithms.
* clog: (libc)Exponents and Logarithms.
* clogf: (libc)Exponents and Logarithms.
* clogfN: (libc)Exponents and Logarithms.
* clogfNx: (libc)Exponents and Logarithms.
* clogl: (libc)Exponents and Logarithms.
* close: (libc)Opening and Closing Files.
* closedir: (libc)Reading/Closing Directory.
* closelog: (libc)closelog.
* cnd_broadcast: (libc)ISO C Condition Variables.
* cnd_destroy: (libc)ISO C Condition Variables.
* cnd_init: (libc)ISO C Condition Variables.
* cnd_signal: (libc)ISO C Condition Variables.
* cnd_timedwait: (libc)ISO C Condition Variables.
* cnd_wait: (libc)ISO C Condition Variables.
* confstr: (libc)String Parameters.
* conj: (libc)Operations on Complex.
* conjf: (libc)Operations on Complex.
* conjfN: (libc)Operations on Complex.
* conjfNx: (libc)Operations on Complex.
* conjl: (libc)Operations on Complex.
* connect: (libc)Connecting.
* copy_file_range: (libc)Copying File Data.
* copysign: (libc)FP Bit Twiddling.
* copysignf: (libc)FP Bit Twiddling.
* copysignfN: (libc)FP Bit Twiddling.
* copysignfNx: (libc)FP Bit Twiddling.
* copysignl: (libc)FP Bit Twiddling.
* cos: (libc)Trig Functions.
* cosf: (libc)Trig Functions.
* cosfN: (libc)Trig Functions.
* cosfNx: (libc)Trig Functions.
* cosh: (libc)Hyperbolic Functions.
* coshf: (libc)Hyperbolic Functions.
* coshfN: (libc)Hyperbolic Functions.
* coshfNx: (libc)Hyperbolic Functions.
* coshl: (libc)Hyperbolic Functions.
* cosl: (libc)Trig Functions.
* cpow: (libc)Exponents and Logarithms.
* cpowf: (libc)Exponents and Logarithms.
* cpowfN: (libc)Exponents and Logarithms.
* cpowfNx: (libc)Exponents and Logarithms.
* cpowl: (libc)Exponents and Logarithms.
* cproj: (libc)Operations on Complex.
* cprojf: (libc)Operations on Complex.
* cprojfN: (libc)Operations on Complex.
* cprojfNx: (libc)Operations on Complex.
* cprojl: (libc)Operations on Complex.
* creal: (libc)Operations on Complex.
* crealf: (libc)Operations on Complex.
* crealfN: (libc)Operations on Complex.
* crealfNx: (libc)Operations on Complex.
* creall: (libc)Operations on Complex.
* creat64: (libc)Opening and Closing Files.
* creat: (libc)Opening and Closing Files.
* crypt: (libc)Passphrase Storage.
* crypt_r: (libc)Passphrase Storage.
* csin: (libc)Trig Functions.
* csinf: (libc)Trig Functions.
* csinfN: (libc)Trig Functions.
* csinfNx: (libc)Trig Functions.
* csinh: (libc)Hyperbolic Functions.
* csinhf: (libc)Hyperbolic Functions.
* csinhfN: (libc)Hyperbolic Functions.
* csinhfNx: (libc)Hyperbolic Functions.
* csinhl: (libc)Hyperbolic Functions.
* csinl: (libc)Trig Functions.
* csqrt: (libc)Exponents and Logarithms.
* csqrtf: (libc)Exponents and Logarithms.
* csqrtfN: (libc)Exponents and Logarithms.
* csqrtfNx: (libc)Exponents and Logarithms.
* csqrtl: (libc)Exponents and Logarithms.
* ctan: (libc)Trig Functions.
* ctanf: (libc)Trig Functions.
* ctanfN: (libc)Trig Functions.
* ctanfNx: (libc)Trig Functions.
* ctanh: (libc)Hyperbolic Functions.
* ctanhf: (libc)Hyperbolic Functions.
* ctanhfN: (libc)Hyperbolic Functions.
* ctanhfNx: (libc)Hyperbolic Functions.
* ctanhl: (libc)Hyperbolic Functions.
* ctanl: (libc)Trig Functions.
* ctermid: (libc)Identifying the Terminal.
* ctime: (libc)Formatting Calendar Time.
* ctime_r: (libc)Formatting Calendar Time.
* cuserid: (libc)Who Logged In.
* daddl: (libc)Misc FP Arithmetic.
* dcgettext: (libc)Translation with gettext.
* dcngettext: (libc)Advanced gettext functions.
* ddivl: (libc)Misc FP Arithmetic.
* dgettext: (libc)Translation with gettext.
* difftime: (libc)Elapsed Time.
* dirfd: (libc)Opening a Directory.
* dirname: (libc)Finding Tokens in a String.
* div: (libc)Integer Division.
* dmull: (libc)Misc FP Arithmetic.
* dngettext: (libc)Advanced gettext functions.
* drand48: (libc)SVID Random.
* drand48_r: (libc)SVID Random.
* drem: (libc)Remainder Functions.
* dremf: (libc)Remainder Functions.
* dreml: (libc)Remainder Functions.
* dsubl: (libc)Misc FP Arithmetic.
* dup2: (libc)Duplicating Descriptors.
* dup: (libc)Duplicating Descriptors.
* ecvt: (libc)System V Number Conversion.
* ecvt_r: (libc)System V Number Conversion.
* endfsent: (libc)fstab.
* endgrent: (libc)Scanning All Groups.
* endhostent: (libc)Host Names.
* endmntent: (libc)mtab.
* endnetent: (libc)Networks Database.
* endnetgrent: (libc)Lookup Netgroup.
* endprotoent: (libc)Protocols Database.
* endpwent: (libc)Scanning All Users.
* endservent: (libc)Services Database.
* endutent: (libc)Manipulating the Database.
* endutxent: (libc)XPG Functions.
* envz_add: (libc)Envz Functions.
* envz_entry: (libc)Envz Functions.
* envz_get: (libc)Envz Functions.
* envz_merge: (libc)Envz Functions.
* envz_remove: (libc)Envz Functions.
* envz_strip: (libc)Envz Functions.
* erand48: (libc)SVID Random.
* erand48_r: (libc)SVID Random.
* erf: (libc)Special Functions.
* erfc: (libc)Special Functions.
* erfcf: (libc)Special Functions.
* erfcfN: (libc)Special Functions.
* erfcfNx: (libc)Special Functions.
* erfcl: (libc)Special Functions.
* erff: (libc)Special Functions.
* erffN: (libc)Special Functions.
* erffNx: (libc)Special Functions.
* erfl: (libc)Special Functions.
* err: (libc)Error Messages.
* errno: (libc)Checking for Errors.
* error: (libc)Error Messages.
* error_at_line: (libc)Error Messages.
* errx: (libc)Error Messages.
* execl: (libc)Executing a File.
* execle: (libc)Executing a File.
* execlp: (libc)Executing a File.
* execv: (libc)Executing a File.
* execve: (libc)Executing a File.
* execvp: (libc)Executing a File.
* exit: (libc)Normal Termination.
* exp10: (libc)Exponents and Logarithms.
* exp10f: (libc)Exponents and Logarithms.
* exp10fN: (libc)Exponents and Logarithms.
* exp10fNx: (libc)Exponents and Logarithms.
* exp10l: (libc)Exponents and Logarithms.
* exp2: (libc)Exponents and Logarithms.
* exp2f: (libc)Exponents and Logarithms.
* exp2fN: (libc)Exponents and Logarithms.
* exp2fNx: (libc)Exponents and Logarithms.
* exp2l: (libc)Exponents and Logarithms.
* exp: (libc)Exponents and Logarithms.
* expf: (libc)Exponents and Logarithms.
* expfN: (libc)Exponents and Logarithms.
* expfNx: (libc)Exponents and Logarithms.
* expl: (libc)Exponents and Logarithms.
* explicit_bzero: (libc)Erasing Sensitive Data.
* expm1: (libc)Exponents and Logarithms.
* expm1f: (libc)Exponents and Logarithms.
* expm1fN: (libc)Exponents and Logarithms.
* expm1fNx: (libc)Exponents and Logarithms.
* expm1l: (libc)Exponents and Logarithms.
* fMaddfN: (libc)Misc FP Arithmetic.
* fMaddfNx: (libc)Misc FP Arithmetic.
* fMdivfN: (libc)Misc FP Arithmetic.
* fMdivfNx: (libc)Misc FP Arithmetic.
* fMmulfN: (libc)Misc FP Arithmetic.
* fMmulfNx: (libc)Misc FP Arithmetic.
* fMsubfN: (libc)Misc FP Arithmetic.
* fMsubfNx: (libc)Misc FP Arithmetic.
* fMxaddfN: (libc)Misc FP Arithmetic.
* fMxaddfNx: (libc)Misc FP Arithmetic.
* fMxdivfN: (libc)Misc FP Arithmetic.
* fMxdivfNx: (libc)Misc FP Arithmetic.
* fMxmulfN: (libc)Misc FP Arithmetic.
* fMxmulfNx: (libc)Misc FP Arithmetic.
* fMxsubfN: (libc)Misc FP Arithmetic.
* fMxsubfNx: (libc)Misc FP Arithmetic.
* fabs: (libc)Absolute Value.
* fabsf: (libc)Absolute Value.
* fabsfN: (libc)Absolute Value.
* fabsfNx: (libc)Absolute Value.
* fabsl: (libc)Absolute Value.
* fadd: (libc)Misc FP Arithmetic.
* faddl: (libc)Misc FP Arithmetic.
* fchdir: (libc)Working Directory.
* fchmod: (libc)Setting Permissions.
* fchown: (libc)File Owner.
* fclose: (libc)Closing Streams.
* fcloseall: (libc)Closing Streams.
* fcntl: (libc)Control Operations.
* fcvt: (libc)System V Number Conversion.
* fcvt_r: (libc)System V Number Conversion.
* fdatasync: (libc)Synchronizing I/O.
* fdim: (libc)Misc FP Arithmetic.
* fdimf: (libc)Misc FP Arithmetic.
* fdimfN: (libc)Misc FP Arithmetic.
* fdimfNx: (libc)Misc FP Arithmetic.
* fdiml: (libc)Misc FP Arithmetic.
* fdiv: (libc)Misc FP Arithmetic.
* fdivl: (libc)Misc FP Arithmetic.
* fdopen: (libc)Descriptors and Streams.
* fdopendir: (libc)Opening a Directory.
* feclearexcept: (libc)Status bit operations.
* fedisableexcept: (libc)Control Functions.
* feenableexcept: (libc)Control Functions.
* fegetenv: (libc)Control Functions.
* fegetexcept: (libc)Control Functions.
* fegetexceptflag: (libc)Status bit operations.
* fegetmode: (libc)Control Functions.
* fegetround: (libc)Rounding.
* feholdexcept: (libc)Control Functions.
* feof: (libc)EOF and Errors.
* feof_unlocked: (libc)EOF and Errors.
* feraiseexcept: (libc)Status bit operations.
* ferror: (libc)EOF and Errors.
* ferror_unlocked: (libc)EOF and Errors.
* fesetenv: (libc)Control Functions.
* fesetexcept: (libc)Status bit operations.
* fesetexceptflag: (libc)Status bit operations.
* fesetmode: (libc)Control Functions.
* fesetround: (libc)Rounding.
* fetestexcept: (libc)Status bit operations.
* fetestexceptflag: (libc)Status bit operations.
* feupdateenv: (libc)Control Functions.
* fflush: (libc)Flushing Buffers.
* fflush_unlocked: (libc)Flushing Buffers.
* fgetc: (libc)Character Input.
* fgetc_unlocked: (libc)Character Input.
* fgetgrent: (libc)Scanning All Groups.
* fgetgrent_r: (libc)Scanning All Groups.
* fgetpos64: (libc)Portable Positioning.
* fgetpos: (libc)Portable Positioning.
* fgetpwent: (libc)Scanning All Users.
* fgetpwent_r: (libc)Scanning All Users.
* fgets: (libc)Line Input.
* fgets_unlocked: (libc)Line Input.
* fgetwc: (libc)Character Input.
* fgetwc_unlocked: (libc)Character Input.
* fgetws: (libc)Line Input.
* fgetws_unlocked: (libc)Line Input.
* fileno: (libc)Descriptors and Streams.
* fileno_unlocked: (libc)Descriptors and Streams.
* finite: (libc)Floating Point Classes.
* finitef: (libc)Floating Point Classes.
* finitel: (libc)Floating Point Classes.
* flockfile: (libc)Streams and Threads.
* floor: (libc)Rounding Functions.
* floorf: (libc)Rounding Functions.
* floorfN: (libc)Rounding Functions.
* floorfNx: (libc)Rounding Functions.
* floorl: (libc)Rounding Functions.
* fma: (libc)Misc FP Arithmetic.
* fmaf: (libc)Misc FP Arithmetic.
* fmafN: (libc)Misc FP Arithmetic.
* fmafNx: (libc)Misc FP Arithmetic.
* fmal: (libc)Misc FP Arithmetic.
* fmax: (libc)Misc FP Arithmetic.
* fmaxf: (libc)Misc FP Arithmetic.
* fmaxfN: (libc)Misc FP Arithmetic.
* fmaxfNx: (libc)Misc FP Arithmetic.
* fmaxl: (libc)Misc FP Arithmetic.
* fmaxmag: (libc)Misc FP Arithmetic.
* fmaxmagf: (libc)Misc FP Arithmetic.
* fmaxmagfN: (libc)Misc FP Arithmetic.
* fmaxmagfNx: (libc)Misc FP Arithmetic.
* fmaxmagl: (libc)Misc FP Arithmetic.
* fmemopen: (libc)String Streams.
* fmin: (libc)Misc FP Arithmetic.
* fminf: (libc)Misc FP Arithmetic.
* fminfN: (libc)Misc FP Arithmetic.
* fminfNx: (libc)Misc FP Arithmetic.
* fminl: (libc)Misc FP Arithmetic.
* fminmag: (libc)Misc FP Arithmetic.
* fminmagf: (libc)Misc FP Arithmetic.
* fminmagfN: (libc)Misc FP Arithmetic.
* fminmagfNx: (libc)Misc FP Arithmetic.
* fminmagl: (libc)Misc FP Arithmetic.
* fmod: (libc)Remainder Functions.
* fmodf: (libc)Remainder Functions.
* fmodfN: (libc)Remainder Functions.
* fmodfNx: (libc)Remainder Functions.
* fmodl: (libc)Remainder Functions.
* fmtmsg: (libc)Printing Formatted Messages.
* fmul: (libc)Misc FP Arithmetic.
* fmull: (libc)Misc FP Arithmetic.
* fnmatch: (libc)Wildcard Matching.
* fopen64: (libc)Opening Streams.
* fopen: (libc)Opening Streams.
* fopencookie: (libc)Streams and Cookies.
* fork: (libc)Creating a Process.
* forkpty: (libc)Pseudo-Terminal Pairs.
* fpathconf: (libc)Pathconf.
* fpclassify: (libc)Floating Point Classes.
* fprintf: (libc)Formatted Output Functions.
* fputc: (libc)Simple Output.
* fputc_unlocked: (libc)Simple Output.
* fputs: (libc)Simple Output.
* fputs_unlocked: (libc)Simple Output.
* fputwc: (libc)Simple Output.
* fputwc_unlocked: (libc)Simple Output.
* fputws: (libc)Simple Output.
* fputws_unlocked: (libc)Simple Output.
* fread: (libc)Block Input/Output.
* fread_unlocked: (libc)Block Input/Output.
* free: (libc)Freeing after Malloc.
* freopen64: (libc)Opening Streams.
* freopen: (libc)Opening Streams.
* frexp: (libc)Normalization Functions.
* frexpf: (libc)Normalization Functions.
* frexpfN: (libc)Normalization Functions.
* frexpfNx: (libc)Normalization Functions.
* frexpl: (libc)Normalization Functions.
* fromfp: (libc)Rounding Functions.
* fromfpf: (libc)Rounding Functions.
* fromfpfN: (libc)Rounding Functions.
* fromfpfNx: (libc)Rounding Functions.
* fromfpl: (libc)Rounding Functions.
* fromfpx: (libc)Rounding Functions.
* fromfpxf: (libc)Rounding Functions.
* fromfpxfN: (libc)Rounding Functions.
* fromfpxfNx: (libc)Rounding Functions.
* fromfpxl: (libc)Rounding Functions.
* fscanf: (libc)Formatted Input Functions.
* fseek: (libc)File Positioning.
* fseeko64: (libc)File Positioning.
* fseeko: (libc)File Positioning.
* fsetpos64: (libc)Portable Positioning.
* fsetpos: (libc)Portable Positioning.
* fstat64: (libc)Reading Attributes.
* fstat: (libc)Reading Attributes.
* fsub: (libc)Misc FP Arithmetic.
* fsubl: (libc)Misc FP Arithmetic.
* fsync: (libc)Synchronizing I/O.
* ftell: (libc)File Positioning.
* ftello64: (libc)File Positioning.
* ftello: (libc)File Positioning.
* ftruncate64: (libc)File Size.
* ftruncate: (libc)File Size.
* ftrylockfile: (libc)Streams and Threads.
* ftw64: (libc)Working with Directory Trees.
* ftw: (libc)Working with Directory Trees.
* funlockfile: (libc)Streams and Threads.
* futimes: (libc)File Times.
* fwide: (libc)Streams and I18N.
* fwprintf: (libc)Formatted Output Functions.
* fwrite: (libc)Block Input/Output.
* fwrite_unlocked: (libc)Block Input/Output.
* fwscanf: (libc)Formatted Input Functions.
* gamma: (libc)Special Functions.
* gammaf: (libc)Special Functions.
* gammal: (libc)Special Functions.
* gcvt: (libc)System V Number Conversion.
* get_avphys_pages: (libc)Query Memory Parameters.
* get_current_dir_name: (libc)Working Directory.
* get_nprocs: (libc)Processor Resources.
* get_nprocs_conf: (libc)Processor Resources.
* get_phys_pages: (libc)Query Memory Parameters.
* getauxval: (libc)Auxiliary Vector.
* getc: (libc)Character Input.
* getc_unlocked: (libc)Character Input.
* getchar: (libc)Character Input.
* getchar_unlocked: (libc)Character Input.
* getcontext: (libc)System V contexts.
* getcpu: (libc)CPU Affinity.
* getcwd: (libc)Working Directory.
* getdate: (libc)General Time String Parsing.
* getdate_r: (libc)General Time String Parsing.
* getdelim: (libc)Line Input.
* getdomainnname: (libc)Host Identification.
* getegid: (libc)Reading Persona.
* getentropy: (libc)Unpredictable Bytes.
* getenv: (libc)Environment Access.
* geteuid: (libc)Reading Persona.
* getfsent: (libc)fstab.
* getfsfile: (libc)fstab.
* getfsspec: (libc)fstab.
* getgid: (libc)Reading Persona.
* getgrent: (libc)Scanning All Groups.
* getgrent_r: (libc)Scanning All Groups.
* getgrgid: (libc)Lookup Group.
* getgrgid_r: (libc)Lookup Group.
* getgrnam: (libc)Lookup Group.
* getgrnam_r: (libc)Lookup Group.
* getgrouplist: (libc)Setting Groups.
* getgroups: (libc)Reading Persona.
* gethostbyaddr: (libc)Host Names.
* gethostbyaddr_r: (libc)Host Names.
* gethostbyname2: (libc)Host Names.
* gethostbyname2_r: (libc)Host Names.
* gethostbyname: (libc)Host Names.
* gethostbyname_r: (libc)Host Names.
* gethostent: (libc)Host Names.
* gethostid: (libc)Host Identification.
* gethostname: (libc)Host Identification.
* getitimer: (libc)Setting an Alarm.
* getline: (libc)Line Input.
* getloadavg: (libc)Processor Resources.
* getlogin: (libc)Who Logged In.
* getmntent: (libc)mtab.
* getmntent_r: (libc)mtab.
* getnetbyaddr: (libc)Networks Database.
* getnetbyname: (libc)Networks Database.
* getnetent: (libc)Networks Database.
* getnetgrent: (libc)Lookup Netgroup.
* getnetgrent_r: (libc)Lookup Netgroup.
* getopt: (libc)Using Getopt.
* getopt_long: (libc)Getopt Long Options.
* getopt_long_only: (libc)Getopt Long Options.
* getpagesize: (libc)Query Memory Parameters.
* getpass: (libc)getpass.
* getpayload: (libc)FP Bit Twiddling.
* getpayloadf: (libc)FP Bit Twiddling.
* getpayloadfN: (libc)FP Bit Twiddling.
* getpayloadfNx: (libc)FP Bit Twiddling.
* getpayloadl: (libc)FP Bit Twiddling.
* getpeername: (libc)Who is Connected.
* getpgid: (libc)Process Group Functions.
* getpgrp: (libc)Process Group Functions.
* getpid: (libc)Process Identification.
* getppid: (libc)Process Identification.
* getpriority: (libc)Traditional Scheduling Functions.
* getprotobyname: (libc)Protocols Database.
* getprotobynumber: (libc)Protocols Database.
* getprotoent: (libc)Protocols Database.
* getpt: (libc)Allocation.
* getpwent: (libc)Scanning All Users.
* getpwent_r: (libc)Scanning All Users.
* getpwnam: (libc)Lookup User.
* getpwnam_r: (libc)Lookup User.
* getpwuid: (libc)Lookup User.
* getpwuid_r: (libc)Lookup User.
* getrandom: (libc)Unpredictable Bytes.
* getrlimit64: (libc)Limits on Resources.
* getrlimit: (libc)Limits on Resources.
* getrusage: (libc)Resource Usage.
* gets: (libc)Line Input.
* getservbyname: (libc)Services Database.
* getservbyport: (libc)Services Database.
* getservent: (libc)Services Database.
* getsid: (libc)Process Group Functions.
* getsockname: (libc)Reading Address.
* getsockopt: (libc)Socket Option Functions.
* getsubopt: (libc)Suboptions.
* gettext: (libc)Translation with gettext.
* gettimeofday: (libc)High-Resolution Calendar.
* getuid: (libc)Reading Persona.
* getumask: (libc)Setting Permissions.
* getutent: (libc)Manipulating the Database.
* getutent_r: (libc)Manipulating the Database.
* getutid: (libc)Manipulating the Database.
* getutid_r: (libc)Manipulating the Database.
* getutline: (libc)Manipulating the Database.
* getutline_r: (libc)Manipulating the Database.
* getutmp: (libc)XPG Functions.
* getutmpx: (libc)XPG Functions.
* getutxent: (libc)XPG Functions.
* getutxid: (libc)XPG Functions.
* getutxline: (libc)XPG Functions.
* getw: (libc)Character Input.
* getwc: (libc)Character Input.
* getwc_unlocked: (libc)Character Input.
* getwchar: (libc)Character Input.
* getwchar_unlocked: (libc)Character Input.
* getwd: (libc)Working Directory.
* glob64: (libc)Calling Glob.
* glob: (libc)Calling Glob.
* globfree64: (libc)More Flags for Globbing.
* globfree: (libc)More Flags for Globbing.
* gmtime: (libc)Broken-down Time.
* gmtime_r: (libc)Broken-down Time.
* grantpt: (libc)Allocation.
* gsignal: (libc)Signaling Yourself.
* gtty: (libc)BSD Terminal Modes.
* hasmntopt: (libc)mtab.
* hcreate: (libc)Hash Search Function.
* hcreate_r: (libc)Hash Search Function.
* hdestroy: (libc)Hash Search Function.
* hdestroy_r: (libc)Hash Search Function.
* hsearch: (libc)Hash Search Function.
* hsearch_r: (libc)Hash Search Function.
* htonl: (libc)Byte Order.
* htons: (libc)Byte Order.
* hypot: (libc)Exponents and Logarithms.
* hypotf: (libc)Exponents and Logarithms.
* hypotfN: (libc)Exponents and Logarithms.
* hypotfNx: (libc)Exponents and Logarithms.
* hypotl: (libc)Exponents and Logarithms.
* iconv: (libc)Generic Conversion Interface.
* iconv_close: (libc)Generic Conversion Interface.
* iconv_open: (libc)Generic Conversion Interface.
* if_freenameindex: (libc)Interface Naming.
* if_indextoname: (libc)Interface Naming.
* if_nameindex: (libc)Interface Naming.
* if_nametoindex: (libc)Interface Naming.
* ilogb: (libc)Exponents and Logarithms.
* ilogbf: (libc)Exponents and Logarithms.
* ilogbfN: (libc)Exponents and Logarithms.
* ilogbfNx: (libc)Exponents and Logarithms.
* ilogbl: (libc)Exponents and Logarithms.
* imaxabs: (libc)Absolute Value.
* imaxdiv: (libc)Integer Division.
* in6addr_any: (libc)Host Address Data Type.
* in6addr_loopback: (libc)Host Address Data Type.
* index: (libc)Search Functions.
* inet_addr: (libc)Host Address Functions.
* inet_aton: (libc)Host Address Functions.
* inet_lnaof: (libc)Host Address Functions.
* inet_makeaddr: (libc)Host Address Functions.
* inet_netof: (libc)Host Address Functions.
* inet_network: (libc)Host Address Functions.
* inet_ntoa: (libc)Host Address Functions.
* inet_ntop: (libc)Host Address Functions.
* inet_pton: (libc)Host Address Functions.
* initgroups: (libc)Setting Groups.
* initstate: (libc)BSD Random.
* initstate_r: (libc)BSD Random.
* innetgr: (libc)Netgroup Membership.
* ioctl: (libc)IOCTLs.
* isalnum: (libc)Classification of Characters.
* isalpha: (libc)Classification of Characters.
* isascii: (libc)Classification of Characters.
* isatty: (libc)Is It a Terminal.
* isblank: (libc)Classification of Characters.
* iscanonical: (libc)Floating Point Classes.
* iscntrl: (libc)Classification of Characters.
* isdigit: (libc)Classification of Characters.
* iseqsig: (libc)FP Comparison Functions.
* isfinite: (libc)Floating Point Classes.
* isgraph: (libc)Classification of Characters.
* isgreater: (libc)FP Comparison Functions.
* isgreaterequal: (libc)FP Comparison Functions.
* isinf: (libc)Floating Point Classes.
* isinff: (libc)Floating Point Classes.
* isinfl: (libc)Floating Point Classes.
* isless: (libc)FP Comparison Functions.
* islessequal: (libc)FP Comparison Functions.
* islessgreater: (libc)FP Comparison Functions.
* islower: (libc)Classification of Characters.
* isnan: (libc)Floating Point Classes.
* isnan: (libc)Floating Point Classes.
* isnanf: (libc)Floating Point Classes.
* isnanl: (libc)Floating Point Classes.
* isnormal: (libc)Floating Point Classes.
* isprint: (libc)Classification of Characters.
* ispunct: (libc)Classification of Characters.
* issignaling: (libc)Floating Point Classes.
* isspace: (libc)Classification of Characters.
* issubnormal: (libc)Floating Point Classes.
* isunordered: (libc)FP Comparison Functions.
* isupper: (libc)Classification of Characters.
* iswalnum: (libc)Classification of Wide Characters.
* iswalpha: (libc)Classification of Wide Characters.
* iswblank: (libc)Classification of Wide Characters.
* iswcntrl: (libc)Classification of Wide Characters.
* iswctype: (libc)Classification of Wide Characters.
* iswdigit: (libc)Classification of Wide Characters.
* iswgraph: (libc)Classification of Wide Characters.
* iswlower: (libc)Classification of Wide Characters.
* iswprint: (libc)Classification of Wide Characters.
* iswpunct: (libc)Classification of Wide Characters.
* iswspace: (libc)Classification of Wide Characters.
* iswupper: (libc)Classification of Wide Characters.
* iswxdigit: (libc)Classification of Wide Characters.
* isxdigit: (libc)Classification of Characters.
* iszero: (libc)Floating Point Classes.
* j0: (libc)Special Functions.
* j0f: (libc)Special Functions.
* j0fN: (libc)Special Functions.
* j0fNx: (libc)Special Functions.
* j0l: (libc)Special Functions.
* j1: (libc)Special Functions.
* j1f: (libc)Special Functions.
* j1fN: (libc)Special Functions.
* j1fNx: (libc)Special Functions.
* j1l: (libc)Special Functions.
* jn: (libc)Special Functions.
* jnf: (libc)Special Functions.
* jnfN: (libc)Special Functions.
* jnfNx: (libc)Special Functions.
* jnl: (libc)Special Functions.
* jrand48: (libc)SVID Random.
* jrand48_r: (libc)SVID Random.
* kill: (libc)Signaling Another Process.
* killpg: (libc)Signaling Another Process.
* l64a: (libc)Encode Binary Data.
* labs: (libc)Absolute Value.
* lcong48: (libc)SVID Random.
* lcong48_r: (libc)SVID Random.
* ldexp: (libc)Normalization Functions.
* ldexpf: (libc)Normalization Functions.
* ldexpfN: (libc)Normalization Functions.
* ldexpfNx: (libc)Normalization Functions.
* ldexpl: (libc)Normalization Functions.
* ldiv: (libc)Integer Division.
* lfind: (libc)Array Search Function.
* lgamma: (libc)Special Functions.
* lgamma_r: (libc)Special Functions.
* lgammaf: (libc)Special Functions.
* lgammafN: (libc)Special Functions.
* lgammafN_r: (libc)Special Functions.
* lgammafNx: (libc)Special Functions.
* lgammafNx_r: (libc)Special Functions.
* lgammaf_r: (libc)Special Functions.
* lgammal: (libc)Special Functions.
* lgammal_r: (libc)Special Functions.
* link: (libc)Hard Links.
* linkat: (libc)Hard Links.
* lio_listio64: (libc)Asynchronous Reads/Writes.
* lio_listio: (libc)Asynchronous Reads/Writes.
* listen: (libc)Listening.
* llabs: (libc)Absolute Value.
* lldiv: (libc)Integer Division.
* llogb: (libc)Exponents and Logarithms.
* llogbf: (libc)Exponents and Logarithms.
* llogbfN: (libc)Exponents and Logarithms.
* llogbfNx: (libc)Exponents and Logarithms.
* llogbl: (libc)Exponents and Logarithms.
* llrint: (libc)Rounding Functions.
* llrintf: (libc)Rounding Functions.
* llrintfN: (libc)Rounding Functions.
* llrintfNx: (libc)Rounding Functions.
* llrintl: (libc)Rounding Functions.
* llround: (libc)Rounding Functions.
* llroundf: (libc)Rounding Functions.
* llroundfN: (libc)Rounding Functions.
* llroundfNx: (libc)Rounding Functions.
* llroundl: (libc)Rounding Functions.
* localeconv: (libc)The Lame Way to Locale Data.
* localtime: (libc)Broken-down Time.
* localtime_r: (libc)Broken-down Time.
* log10: (libc)Exponents and Logarithms.
* log10f: (libc)Exponents and Logarithms.
* log10fN: (libc)Exponents and Logarithms.
* log10fNx: (libc)Exponents and Logarithms.
* log10l: (libc)Exponents and Logarithms.
* log1p: (libc)Exponents and Logarithms.
* log1pf: (libc)Exponents and Logarithms.
* log1pfN: (libc)Exponents and Logarithms.
* log1pfNx: (libc)Exponents and Logarithms.
* log1pl: (libc)Exponents and Logarithms.
* log2: (libc)Exponents and Logarithms.
* log2f: (libc)Exponents and Logarithms.
* log2fN: (libc)Exponents and Logarithms.
* log2fNx: (libc)Exponents and Logarithms.
* log2l: (libc)Exponents and Logarithms.
* log: (libc)Exponents and Logarithms.
* logb: (libc)Exponents and Logarithms.
* logbf: (libc)Exponents and Logarithms.
* logbfN: (libc)Exponents and Logarithms.
* logbfNx: (libc)Exponents and Logarithms.
* logbl: (libc)Exponents and Logarithms.
* logf: (libc)Exponents and Logarithms.
* logfN: (libc)Exponents and Logarithms.
* logfNx: (libc)Exponents and Logarithms.
* login: (libc)Logging In and Out.
* login_tty: (libc)Logging In and Out.
* logl: (libc)Exponents and Logarithms.
* logout: (libc)Logging In and Out.
* logwtmp: (libc)Logging In and Out.
* longjmp: (libc)Non-Local Details.
* lrand48: (libc)SVID Random.
* lrand48_r: (libc)SVID Random.
* lrint: (libc)Rounding Functions.
* lrintf: (libc)Rounding Functions.
* lrintfN: (libc)Rounding Functions.
* lrintfNx: (libc)Rounding Functions.
* lrintl: (libc)Rounding Functions.
* lround: (libc)Rounding Functions.
* lroundf: (libc)Rounding Functions.
* lroundfN: (libc)Rounding Functions.
* lroundfNx: (libc)Rounding Functions.
* lroundl: (libc)Rounding Functions.
* lsearch: (libc)Array Search Function.
* lseek64: (libc)File Position Primitive.
* lseek: (libc)File Position Primitive.
* lstat64: (libc)Reading Attributes.
* lstat: (libc)Reading Attributes.
* lutimes: (libc)File Times.
* madvise: (libc)Memory-mapped I/O.
* makecontext: (libc)System V contexts.
* mallinfo: (libc)Statistics of Malloc.
* malloc: (libc)Basic Allocation.
* mallopt: (libc)Malloc Tunable Parameters.
* mblen: (libc)Non-reentrant Character Conversion.
* mbrlen: (libc)Converting a Character.
* mbrtowc: (libc)Converting a Character.
* mbsinit: (libc)Keeping the state.
* mbsnrtowcs: (libc)Converting Strings.
* mbsrtowcs: (libc)Converting Strings.
* mbstowcs: (libc)Non-reentrant String Conversion.
* mbtowc: (libc)Non-reentrant Character Conversion.
* mcheck: (libc)Heap Consistency Checking.
* memalign: (libc)Aligned Memory Blocks.
* memccpy: (libc)Copying Strings and Arrays.
* memchr: (libc)Search Functions.
* memcmp: (libc)String/Array Comparison.
* memcpy: (libc)Copying Strings and Arrays.
* memfd_create: (libc)Memory-mapped I/O.
* memfrob: (libc)Obfuscating Data.
* memmem: (libc)Search Functions.
* memmove: (libc)Copying Strings and Arrays.
* mempcpy: (libc)Copying Strings and Arrays.
* memrchr: (libc)Search Functions.
* memset: (libc)Copying Strings and Arrays.
* mkdir: (libc)Creating Directories.
* mkdtemp: (libc)Temporary Files.
* mkfifo: (libc)FIFO Special Files.
* mknod: (libc)Making Special Files.
* mkstemp: (libc)Temporary Files.
* mktemp: (libc)Temporary Files.
* mktime: (libc)Broken-down Time.
* mlock2: (libc)Page Lock Functions.
* mlock: (libc)Page Lock Functions.
* mlockall: (libc)Page Lock Functions.
* mmap64: (libc)Memory-mapped I/O.
* mmap: (libc)Memory-mapped I/O.
* modf: (libc)Rounding Functions.
* modff: (libc)Rounding Functions.
* modffN: (libc)Rounding Functions.
* modffNx: (libc)Rounding Functions.
* modfl: (libc)Rounding Functions.
* mount: (libc)Mount-Unmount-Remount.
* mprobe: (libc)Heap Consistency Checking.
* mprotect: (libc)Memory Protection.
* mrand48: (libc)SVID Random.
* mrand48_r: (libc)SVID Random.
* mremap: (libc)Memory-mapped I/O.
* msync: (libc)Memory-mapped I/O.
* mtrace: (libc)Tracing malloc.
* mtx_destroy: (libc)ISO C Mutexes.
* mtx_init: (libc)ISO C Mutexes.
* mtx_lock: (libc)ISO C Mutexes.
* mtx_timedlock: (libc)ISO C Mutexes.
* mtx_trylock: (libc)ISO C Mutexes.
* mtx_unlock: (libc)ISO C Mutexes.
* munlock: (libc)Page Lock Functions.
* munlockall: (libc)Page Lock Functions.
* munmap: (libc)Memory-mapped I/O.
* muntrace: (libc)Tracing malloc.
* nan: (libc)FP Bit Twiddling.
* nanf: (libc)FP Bit Twiddling.
* nanfN: (libc)FP Bit Twiddling.
* nanfNx: (libc)FP Bit Twiddling.
* nanl: (libc)FP Bit Twiddling.
* nanosleep: (libc)Sleeping.
* nearbyint: (libc)Rounding Functions.
* nearbyintf: (libc)Rounding Functions.
* nearbyintfN: (libc)Rounding Functions.
* nearbyintfNx: (libc)Rounding Functions.
* nearbyintl: (libc)Rounding Functions.
* nextafter: (libc)FP Bit Twiddling.
* nextafterf: (libc)FP Bit Twiddling.
* nextafterfN: (libc)FP Bit Twiddling.
* nextafterfNx: (libc)FP Bit Twiddling.
* nextafterl: (libc)FP Bit Twiddling.
* nextdown: (libc)FP Bit Twiddling.
* nextdownf: (libc)FP Bit Twiddling.
* nextdownfN: (libc)FP Bit Twiddling.
* nextdownfNx: (libc)FP Bit Twiddling.
* nextdownl: (libc)FP Bit Twiddling.
* nexttoward: (libc)FP Bit Twiddling.
* nexttowardf: (libc)FP Bit Twiddling.
* nexttowardl: (libc)FP Bit Twiddling.
* nextup: (libc)FP Bit Twiddling.
* nextupf: (libc)FP Bit Twiddling.
* nextupfN: (libc)FP Bit Twiddling.
* nextupfNx: (libc)FP Bit Twiddling.
* nextupl: (libc)FP Bit Twiddling.
* nftw64: (libc)Working with Directory Trees.
* nftw: (libc)Working with Directory Trees.
* ngettext: (libc)Advanced gettext functions.
* nice: (libc)Traditional Scheduling Functions.
* nl_langinfo: (libc)The Elegant and Fast Way.
* nrand48: (libc)SVID Random.
* nrand48_r: (libc)SVID Random.
* ntohl: (libc)Byte Order.
* ntohs: (libc)Byte Order.
* ntp_adjtime: (libc)High Accuracy Clock.
* ntp_gettime: (libc)High Accuracy Clock.
* obstack_1grow: (libc)Growing Objects.
* obstack_1grow_fast: (libc)Extra Fast Growing.
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
* obstack_alloc: (libc)Allocation in an Obstack.
* obstack_base: (libc)Status of an Obstack.
* obstack_blank: (libc)Growing Objects.
* obstack_blank_fast: (libc)Extra Fast Growing.
* obstack_chunk_size: (libc)Obstack Chunks.
* obstack_copy0: (libc)Allocation in an Obstack.
* obstack_copy: (libc)Allocation in an Obstack.
* obstack_finish: (libc)Growing Objects.
* obstack_free: (libc)Freeing Obstack Objects.
* obstack_grow0: (libc)Growing Objects.
* obstack_grow: (libc)Growing Objects.
* obstack_init: (libc)Preparing for Obstacks.
* obstack_int_grow: (libc)Growing Objects.
* obstack_int_grow_fast: (libc)Extra Fast Growing.
* obstack_next_free: (libc)Status of an Obstack.
* obstack_object_size: (libc)Growing Objects.
* obstack_object_size: (libc)Status of an Obstack.
* obstack_printf: (libc)Dynamic Output.
* obstack_ptr_grow: (libc)Growing Objects.
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
* obstack_room: (libc)Extra Fast Growing.
* obstack_vprintf: (libc)Variable Arguments Output.
* offsetof: (libc)Structure Measurement.
* on_exit: (libc)Cleanups on Exit.
* open64: (libc)Opening and Closing Files.
* open: (libc)Opening and Closing Files.
* open_memstream: (libc)String Streams.
* opendir: (libc)Opening a Directory.
* openlog: (libc)openlog.
* openpty: (libc)Pseudo-Terminal Pairs.
* parse_printf_format: (libc)Parsing a Template String.
* pathconf: (libc)Pathconf.
* pause: (libc)Using Pause.
* pclose: (libc)Pipe to a Subprocess.
* perror: (libc)Error Messages.
* pipe: (libc)Creating a Pipe.
* pkey_alloc: (libc)Memory Protection.
* pkey_free: (libc)Memory Protection.
* pkey_get: (libc)Memory Protection.
* pkey_mprotect: (libc)Memory Protection.
* pkey_set: (libc)Memory Protection.
* popen: (libc)Pipe to a Subprocess.
* posix_fallocate64: (libc)Storage Allocation.
* posix_fallocate: (libc)Storage Allocation.
* posix_memalign: (libc)Aligned Memory Blocks.
* pow: (libc)Exponents and Logarithms.
* powf: (libc)Exponents and Logarithms.
* powfN: (libc)Exponents and Logarithms.
* powfNx: (libc)Exponents and Logarithms.
* powl: (libc)Exponents and Logarithms.
* pread64: (libc)I/O Primitives.
* pread: (libc)I/O Primitives.
* preadv2: (libc)Scatter-Gather.
* preadv64: (libc)Scatter-Gather.
* preadv64v2: (libc)Scatter-Gather.
* preadv: (libc)Scatter-Gather.
* printf: (libc)Formatted Output Functions.
* printf_size: (libc)Predefined Printf Handlers.
* printf_size_info: (libc)Predefined Printf Handlers.
* psignal: (libc)Signal Messages.
* pthread_getattr_default_np: (libc)Default Thread Attributes.
* pthread_getspecific: (libc)Thread-specific Data.
* pthread_key_create: (libc)Thread-specific Data.
* pthread_key_delete: (libc)Thread-specific Data.
* pthread_setattr_default_np: (libc)Default Thread Attributes.
* pthread_setspecific: (libc)Thread-specific Data.
* ptsname: (libc)Allocation.
* ptsname_r: (libc)Allocation.
* putc: (libc)Simple Output.
* putc_unlocked: (libc)Simple Output.
* putchar: (libc)Simple Output.
* putchar_unlocked: (libc)Simple Output.
* putenv: (libc)Environment Access.
* putpwent: (libc)Writing a User Entry.
* puts: (libc)Simple Output.
* pututline: (libc)Manipulating the Database.
* pututxline: (libc)XPG Functions.
* putw: (libc)Simple Output.
* putwc: (libc)Simple Output.
* putwc_unlocked: (libc)Simple Output.
* putwchar: (libc)Simple Output.
* putwchar_unlocked: (libc)Simple Output.
* pwrite64: (libc)I/O Primitives.
* pwrite: (libc)I/O Primitives.
* pwritev2: (libc)Scatter-Gather.
* pwritev64: (libc)Scatter-Gather.
* pwritev64v2: (libc)Scatter-Gather.
* pwritev: (libc)Scatter-Gather.
* qecvt: (libc)System V Number Conversion.
* qecvt_r: (libc)System V Number Conversion.
* qfcvt: (libc)System V Number Conversion.
* qfcvt_r: (libc)System V Number Conversion.
* qgcvt: (libc)System V Number Conversion.
* qsort: (libc)Array Sort Function.
* raise: (libc)Signaling Yourself.
* rand: (libc)ISO Random.
* rand_r: (libc)ISO Random.
* random: (libc)BSD Random.
* random_r: (libc)BSD Random.
* rawmemchr: (libc)Search Functions.
* read: (libc)I/O Primitives.
* readdir64: (libc)Reading/Closing Directory.
* readdir64_r: (libc)Reading/Closing Directory.
* readdir: (libc)Reading/Closing Directory.
* readdir_r: (libc)Reading/Closing Directory.
* readlink: (libc)Symbolic Links.
* readv: (libc)Scatter-Gather.
* realloc: (libc)Changing Block Size.
* reallocarray: (libc)Changing Block Size.
* realpath: (libc)Symbolic Links.
* recv: (libc)Receiving Data.
* recvfrom: (libc)Receiving Datagrams.
* recvmsg: (libc)Receiving Datagrams.
* regcomp: (libc)POSIX Regexp Compilation.
* regerror: (libc)Regexp Cleanup.
* regexec: (libc)Matching POSIX Regexps.
* regfree: (libc)Regexp Cleanup.
* register_printf_function: (libc)Registering New Conversions.
* remainder: (libc)Remainder Functions.
* remainderf: (libc)Remainder Functions.
* remainderfN: (libc)Remainder Functions.
* remainderfNx: (libc)Remainder Functions.
* remainderl: (libc)Remainder Functions.
* remove: (libc)Deleting Files.
* rename: (libc)Renaming Files.
* rewind: (libc)File Positioning.
* rewinddir: (libc)Random Access Directory.
* rindex: (libc)Search Functions.
* rint: (libc)Rounding Functions.
* rintf: (libc)Rounding Functions.
* rintfN: (libc)Rounding Functions.
* rintfNx: (libc)Rounding Functions.
* rintl: (libc)Rounding Functions.
* rmdir: (libc)Deleting Files.
* round: (libc)Rounding Functions.
* roundeven: (libc)Rounding Functions.
* roundevenf: (libc)Rounding Functions.
* roundevenfN: (libc)Rounding Functions.
* roundevenfNx: (libc)Rounding Functions.
* roundevenl: (libc)Rounding Functions.
* roundf: (libc)Rounding Functions.
* roundfN: (libc)Rounding Functions.
* roundfNx: (libc)Rounding Functions.
* roundl: (libc)Rounding Functions.
* rpmatch: (libc)Yes-or-No Questions.
* sbrk: (libc)Resizing the Data Segment.
* scalb: (libc)Normalization Functions.
* scalbf: (libc)Normalization Functions.
* scalbl: (libc)Normalization Functions.
* scalbln: (libc)Normalization Functions.
* scalblnf: (libc)Normalization Functions.
* scalblnfN: (libc)Normalization Functions.
* scalblnfNx: (libc)Normalization Functions.
* scalblnl: (libc)Normalization Functions.
* scalbn: (libc)Normalization Functions.
* scalbnf: (libc)Normalization Functions.
* scalbnfN: (libc)Normalization Functions.
* scalbnfNx: (libc)Normalization Functions.
* scalbnl: (libc)Normalization Functions.
* scandir64: (libc)Scanning Directory Content.
* scandir: (libc)Scanning Directory Content.
* scanf: (libc)Formatted Input Functions.
* sched_get_priority_max: (libc)Basic Scheduling Functions.
* sched_get_priority_min: (libc)Basic Scheduling Functions.
* sched_getaffinity: (libc)CPU Affinity.
* sched_getparam: (libc)Basic Scheduling Functions.
* sched_getscheduler: (libc)Basic Scheduling Functions.
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
* sched_setaffinity: (libc)CPU Affinity.
* sched_setparam: (libc)Basic Scheduling Functions.
* sched_setscheduler: (libc)Basic Scheduling Functions.
* sched_yield: (libc)Basic Scheduling Functions.
* secure_getenv: (libc)Environment Access.
* seed48: (libc)SVID Random.
* seed48_r: (libc)SVID Random.
* seekdir: (libc)Random Access Directory.
* select: (libc)Waiting for I/O.
* sem_close: (libc)Semaphores.
* sem_destroy: (libc)Semaphores.
* sem_getvalue: (libc)Semaphores.
* sem_init: (libc)Semaphores.
* sem_open: (libc)Semaphores.
* sem_post: (libc)Semaphores.
* sem_timedwait: (libc)Semaphores.
* sem_trywait: (libc)Semaphores.
* sem_unlink: (libc)Semaphores.
* sem_wait: (libc)Semaphores.
* semctl: (libc)Semaphores.
* semget: (libc)Semaphores.
* semop: (libc)Semaphores.
* semtimedop: (libc)Semaphores.
* send: (libc)Sending Data.
* sendmsg: (libc)Receiving Datagrams.
* sendto: (libc)Sending Datagrams.
* setbuf: (libc)Controlling Buffering.
* setbuffer: (libc)Controlling Buffering.
* setcontext: (libc)System V contexts.
* setdomainname: (libc)Host Identification.
* setegid: (libc)Setting Groups.
* setenv: (libc)Environment Access.
* seteuid: (libc)Setting User ID.
* setfsent: (libc)fstab.
* setgid: (libc)Setting Groups.
* setgrent: (libc)Scanning All Groups.
* setgroups: (libc)Setting Groups.
* sethostent: (libc)Host Names.
* sethostid: (libc)Host Identification.
* sethostname: (libc)Host Identification.
* setitimer: (libc)Setting an Alarm.
* setjmp: (libc)Non-Local Details.
* setlinebuf: (libc)Controlling Buffering.
* setlocale: (libc)Setting the Locale.
* setlogmask: (libc)setlogmask.
* setmntent: (libc)mtab.
* setnetent: (libc)Networks Database.
* setnetgrent: (libc)Lookup Netgroup.
* setpayload: (libc)FP Bit Twiddling.
* setpayloadf: (libc)FP Bit Twiddling.
* setpayloadfN: (libc)FP Bit Twiddling.
* setpayloadfNx: (libc)FP Bit Twiddling.
* setpayloadl: (libc)FP Bit Twiddling.
* setpayloadsig: (libc)FP Bit Twiddling.
* setpayloadsigf: (libc)FP Bit Twiddling.
* setpayloadsigfN: (libc)FP Bit Twiddling.
* setpayloadsigfNx: (libc)FP Bit Twiddling.
* setpayloadsigl: (libc)FP Bit Twiddling.
* setpgid: (libc)Process Group Functions.
* setpgrp: (libc)Process Group Functions.
* setpriority: (libc)Traditional Scheduling Functions.
* setprotoent: (libc)Protocols Database.
* setpwent: (libc)Scanning All Users.
* setregid: (libc)Setting Groups.
* setreuid: (libc)Setting User ID.
* setrlimit64: (libc)Limits on Resources.
* setrlimit: (libc)Limits on Resources.
* setservent: (libc)Services Database.
* setsid: (libc)Process Group Functions.
* setsockopt: (libc)Socket Option Functions.
* setstate: (libc)BSD Random.
* setstate_r: (libc)BSD Random.
* settimeofday: (libc)High-Resolution Calendar.
* setuid: (libc)Setting User ID.
* setutent: (libc)Manipulating the Database.
* setutxent: (libc)XPG Functions.
* setvbuf: (libc)Controlling Buffering.
* shm_open: (libc)Memory-mapped I/O.
* shm_unlink: (libc)Memory-mapped I/O.
* shutdown: (libc)Closing a Socket.
* sigaction: (libc)Advanced Signal Handling.
* sigaddset: (libc)Signal Sets.
* sigaltstack: (libc)Signal Stack.
* sigblock: (libc)BSD Signal Handling.
* sigdelset: (libc)Signal Sets.
* sigemptyset: (libc)Signal Sets.
* sigfillset: (libc)Signal Sets.
* siginterrupt: (libc)BSD Signal Handling.
* sigismember: (libc)Signal Sets.
* siglongjmp: (libc)Non-Local Exits and Signals.
* sigmask: (libc)BSD Signal Handling.
* signal: (libc)Basic Signal Handling.
* signbit: (libc)FP Bit Twiddling.
* significand: (libc)Normalization Functions.
* significandf: (libc)Normalization Functions.
* significandl: (libc)Normalization Functions.
* sigpause: (libc)BSD Signal Handling.
* sigpending: (libc)Checking for Pending Signals.
* sigprocmask: (libc)Process Signal Mask.
* sigsetjmp: (libc)Non-Local Exits and Signals.
* sigsetmask: (libc)BSD Signal Handling.
* sigstack: (libc)Signal Stack.
* sigsuspend: (libc)Sigsuspend.
* sin: (libc)Trig Functions.
* sincos: (libc)Trig Functions.
* sincosf: (libc)Trig Functions.
* sincosfN: (libc)Trig Functions.
* sincosfNx: (libc)Trig Functions.
* sincosl: (libc)Trig Functions.
* sinf: (libc)Trig Functions.
* sinfN: (libc)Trig Functions.
* sinfNx: (libc)Trig Functions.
* sinh: (libc)Hyperbolic Functions.
* sinhf: (libc)Hyperbolic Functions.
* sinhfN: (libc)Hyperbolic Functions.
* sinhfNx: (libc)Hyperbolic Functions.
* sinhl: (libc)Hyperbolic Functions.
* sinl: (libc)Trig Functions.
* sleep: (libc)Sleeping.
* snprintf: (libc)Formatted Output Functions.
* socket: (libc)Creating a Socket.
* socketpair: (libc)Socket Pairs.
* sprintf: (libc)Formatted Output Functions.
* sqrt: (libc)Exponents and Logarithms.
* sqrtf: (libc)Exponents and Logarithms.
* sqrtfN: (libc)Exponents and Logarithms.
* sqrtfNx: (libc)Exponents and Logarithms.
* sqrtl: (libc)Exponents and Logarithms.
* srand48: (libc)SVID Random.
* srand48_r: (libc)SVID Random.
* srand: (libc)ISO Random.
* srandom: (libc)BSD Random.
* srandom_r: (libc)BSD Random.
* sscanf: (libc)Formatted Input Functions.
* ssignal: (libc)Basic Signal Handling.
* stat64: (libc)Reading Attributes.
* stat: (libc)Reading Attributes.
* stime: (libc)Simple Calendar Time.
* stpcpy: (libc)Copying Strings and Arrays.
* stpncpy: (libc)Truncating Strings.
* strcasecmp: (libc)String/Array Comparison.
* strcasestr: (libc)Search Functions.
* strcat: (libc)Concatenating Strings.
* strchr: (libc)Search Functions.
* strchrnul: (libc)Search Functions.
* strcmp: (libc)String/Array Comparison.
* strcoll: (libc)Collation Functions.
* strcpy: (libc)Copying Strings and Arrays.
* strcspn: (libc)Search Functions.
* strdup: (libc)Copying Strings and Arrays.
* strdupa: (libc)Copying Strings and Arrays.
* strerror: (libc)Error Messages.
* strerror_r: (libc)Error Messages.
* strfmon: (libc)Formatting Numbers.
* strfromd: (libc)Printing of Floats.
* strfromf: (libc)Printing of Floats.
* strfromfN: (libc)Printing of Floats.
* strfromfNx: (libc)Printing of Floats.
* strfroml: (libc)Printing of Floats.
* strfry: (libc)Shuffling Bytes.
* strftime: (libc)Formatting Calendar Time.
* strlen: (libc)String Length.
* strncasecmp: (libc)String/Array Comparison.
* strncat: (libc)Truncating Strings.
* strncmp: (libc)String/Array Comparison.
* strncpy: (libc)Truncating Strings.
* strndup: (libc)Truncating Strings.
* strndupa: (libc)Truncating Strings.
* strnlen: (libc)String Length.
* strpbrk: (libc)Search Functions.
* strptime: (libc)Low-Level Time String Parsing.
* strrchr: (libc)Search Functions.
* strsep: (libc)Finding Tokens in a String.
* strsignal: (libc)Signal Messages.
* strspn: (libc)Search Functions.
* strstr: (libc)Search Functions.
* strtod: (libc)Parsing of Floats.
* strtof: (libc)Parsing of Floats.
* strtofN: (libc)Parsing of Floats.
* strtofNx: (libc)Parsing of Floats.
* strtoimax: (libc)Parsing of Integers.
* strtok: (libc)Finding Tokens in a String.
* strtok_r: (libc)Finding Tokens in a String.
* strtol: (libc)Parsing of Integers.
* strtold: (libc)Parsing of Floats.
* strtoll: (libc)Parsing of Integers.
* strtoq: (libc)Parsing of Integers.
* strtoul: (libc)Parsing of Integers.
* strtoull: (libc)Parsing of Integers.
* strtoumax: (libc)Parsing of Integers.
* strtouq: (libc)Parsing of Integers.
* strverscmp: (libc)String/Array Comparison.
* strxfrm: (libc)Collation Functions.
* stty: (libc)BSD Terminal Modes.
* swapcontext: (libc)System V contexts.
* swprintf: (libc)Formatted Output Functions.
* swscanf: (libc)Formatted Input Functions.
* symlink: (libc)Symbolic Links.
* sync: (libc)Synchronizing I/O.
* syscall: (libc)System Calls.
* sysconf: (libc)Sysconf Definition.
* sysctl: (libc)System Parameters.
* syslog: (libc)syslog; vsyslog.
* system: (libc)Running a Command.
* sysv_signal: (libc)Basic Signal Handling.
* tan: (libc)Trig Functions.
* tanf: (libc)Trig Functions.
* tanfN: (libc)Trig Functions.
* tanfNx: (libc)Trig Functions.
* tanh: (libc)Hyperbolic Functions.
* tanhf: (libc)Hyperbolic Functions.
* tanhfN: (libc)Hyperbolic Functions.
* tanhfNx: (libc)Hyperbolic Functions.
* tanhl: (libc)Hyperbolic Functions.
* tanl: (libc)Trig Functions.
* tcdrain: (libc)Line Control.
* tcflow: (libc)Line Control.
* tcflush: (libc)Line Control.
* tcgetattr: (libc)Mode Functions.
* tcgetpgrp: (libc)Terminal Access Functions.
* tcgetsid: (libc)Terminal Access Functions.
* tcsendbreak: (libc)Line Control.
* tcsetattr: (libc)Mode Functions.
* tcsetpgrp: (libc)Terminal Access Functions.
* tdelete: (libc)Tree Search Function.
* tdestroy: (libc)Tree Search Function.
* telldir: (libc)Random Access Directory.
* tempnam: (libc)Temporary Files.
* textdomain: (libc)Locating gettext catalog.
* tfind: (libc)Tree Search Function.
* tgamma: (libc)Special Functions.
* tgammaf: (libc)Special Functions.
* tgammafN: (libc)Special Functions.
* tgammafNx: (libc)Special Functions.
* tgammal: (libc)Special Functions.
* thrd_create: (libc)ISO C Thread Management.
* thrd_current: (libc)ISO C Thread Management.
* thrd_detach: (libc)ISO C Thread Management.
* thrd_equal: (libc)ISO C Thread Management.
* thrd_exit: (libc)ISO C Thread Management.
* thrd_join: (libc)ISO C Thread Management.
* thrd_sleep: (libc)ISO C Thread Management.
* thrd_yield: (libc)ISO C Thread Management.
* time: (libc)Simple Calendar Time.
* timegm: (libc)Broken-down Time.
* timelocal: (libc)Broken-down Time.
* times: (libc)Processor Time.
* tmpfile64: (libc)Temporary Files.
* tmpfile: (libc)Temporary Files.
* tmpnam: (libc)Temporary Files.
* tmpnam_r: (libc)Temporary Files.
* toascii: (libc)Case Conversion.
* tolower: (libc)Case Conversion.
* totalorder: (libc)FP Comparison Functions.
* totalorderf: (libc)FP Comparison Functions.
* totalorderfN: (libc)FP Comparison Functions.
* totalorderfNx: (libc)FP Comparison Functions.
* totalorderl: (libc)FP Comparison Functions.
* totalordermag: (libc)FP Comparison Functions.
* totalordermagf: (libc)FP Comparison Functions.
* totalordermagfN: (libc)FP Comparison Functions.
* totalordermagfNx: (libc)FP Comparison Functions.
* totalordermagl: (libc)FP Comparison Functions.
* toupper: (libc)Case Conversion.
* towctrans: (libc)Wide Character Case Conversion.
* towlower: (libc)Wide Character Case Conversion.
* towupper: (libc)Wide Character Case Conversion.
* trunc: (libc)Rounding Functions.
* truncate64: (libc)File Size.
* truncate: (libc)File Size.
* truncf: (libc)Rounding Functions.
* truncfN: (libc)Rounding Functions.
* truncfNx: (libc)Rounding Functions.
* truncl: (libc)Rounding Functions.
* tsearch: (libc)Tree Search Function.
* tss_create: (libc)ISO C Thread-local Storage.
* tss_delete: (libc)ISO C Thread-local Storage.
* tss_get: (libc)ISO C Thread-local Storage.
* tss_set: (libc)ISO C Thread-local Storage.
* ttyname: (libc)Is It a Terminal.
* ttyname_r: (libc)Is It a Terminal.
* twalk: (libc)Tree Search Function.
* tzset: (libc)Time Zone Functions.
* ufromfp: (libc)Rounding Functions.
* ufromfpf: (libc)Rounding Functions.
* ufromfpfN: (libc)Rounding Functions.
* ufromfpfNx: (libc)Rounding Functions.
* ufromfpl: (libc)Rounding Functions.
* ufromfpx: (libc)Rounding Functions.
* ufromfpxf: (libc)Rounding Functions.
* ufromfpxfN: (libc)Rounding Functions.
* ufromfpxfNx: (libc)Rounding Functions.
* ufromfpxl: (libc)Rounding Functions.
* ulimit: (libc)Limits on Resources.
* umask: (libc)Setting Permissions.
* umount2: (libc)Mount-Unmount-Remount.
* umount: (libc)Mount-Unmount-Remount.
* uname: (libc)Platform Type.
* ungetc: (libc)How Unread.
* ungetwc: (libc)How Unread.
* unlink: (libc)Deleting Files.
* unlockpt: (libc)Allocation.
* unsetenv: (libc)Environment Access.
* updwtmp: (libc)Manipulating the Database.
* utime: (libc)File Times.
* utimes: (libc)File Times.
* utmpname: (libc)Manipulating the Database.
* utmpxname: (libc)XPG Functions.
* va_arg: (libc)Argument Macros.
* va_copy: (libc)Argument Macros.
* va_end: (libc)Argument Macros.
* va_start: (libc)Argument Macros.
* valloc: (libc)Aligned Memory Blocks.
* vasprintf: (libc)Variable Arguments Output.
* verr: (libc)Error Messages.
* verrx: (libc)Error Messages.
* versionsort64: (libc)Scanning Directory Content.
* versionsort: (libc)Scanning Directory Content.
* vfork: (libc)Creating a Process.
* vfprintf: (libc)Variable Arguments Output.
* vfscanf: (libc)Variable Arguments Input.
* vfwprintf: (libc)Variable Arguments Output.
* vfwscanf: (libc)Variable Arguments Input.
* vlimit: (libc)Limits on Resources.
* vprintf: (libc)Variable Arguments Output.
* vscanf: (libc)Variable Arguments Input.
* vsnprintf: (libc)Variable Arguments Output.
* vsprintf: (libc)Variable Arguments Output.
* vsscanf: (libc)Variable Arguments Input.
* vswprintf: (libc)Variable Arguments Output.
* vswscanf: (libc)Variable Arguments Input.
* vsyslog: (libc)syslog; vsyslog.
* vtimes: (libc)Resource Usage.
* vwarn: (libc)Error Messages.
* vwarnx: (libc)Error Messages.
* vwprintf: (libc)Variable Arguments Output.
* vwscanf: (libc)Variable Arguments Input.
* wait3: (libc)BSD Wait Functions.
* wait4: (libc)Process Completion.
* wait: (libc)Process Completion.
* waitpid: (libc)Process Completion.
* warn: (libc)Error Messages.
* warnx: (libc)Error Messages.
* wcpcpy: (libc)Copying Strings and Arrays.
* wcpncpy: (libc)Truncating Strings.
* wcrtomb: (libc)Converting a Character.
* wcscasecmp: (libc)String/Array Comparison.
* wcscat: (libc)Concatenating Strings.
* wcschr: (libc)Search Functions.
* wcschrnul: (libc)Search Functions.
* wcscmp: (libc)String/Array Comparison.
* wcscoll: (libc)Collation Functions.
* wcscpy: (libc)Copying Strings and Arrays.
* wcscspn: (libc)Search Functions.
* wcsdup: (libc)Copying Strings and Arrays.
* wcsftime: (libc)Formatting Calendar Time.
* wcslen: (libc)String Length.
* wcsncasecmp: (libc)String/Array Comparison.
* wcsncat: (libc)Truncating Strings.
* wcsncmp: (libc)String/Array Comparison.
* wcsncpy: (libc)Truncating Strings.
* wcsnlen: (libc)String Length.
* wcsnrtombs: (libc)Converting Strings.
* wcspbrk: (libc)Search Functions.
* wcsrchr: (libc)Search Functions.
* wcsrtombs: (libc)Converting Strings.
* wcsspn: (libc)Search Functions.
* wcsstr: (libc)Search Functions.
* wcstod: (libc)Parsing of Floats.
* wcstof: (libc)Parsing of Floats.
* wcstofN: (libc)Parsing of Floats.
* wcstofNx: (libc)Parsing of Floats.
* wcstoimax: (libc)Parsing of Integers.
* wcstok: (libc)Finding Tokens in a String.
* wcstol: (libc)Parsing of Integers.
* wcstold: (libc)Parsing of Floats.
* wcstoll: (libc)Parsing of Integers.
* wcstombs: (libc)Non-reentrant String Conversion.
* wcstoq: (libc)Parsing of Integers.
* wcstoul: (libc)Parsing of Integers.
* wcstoull: (libc)Parsing of Integers.
* wcstoumax: (libc)Parsing of Integers.
* wcstouq: (libc)Parsing of Integers.
* wcswcs: (libc)Search Functions.
* wcsxfrm: (libc)Collation Functions.
* wctob: (libc)Converting a Character.
* wctomb: (libc)Non-reentrant Character Conversion.
* wctrans: (libc)Wide Character Case Conversion.
* wctype: (libc)Classification of Wide Characters.
* wmemchr: (libc)Search Functions.
* wmemcmp: (libc)String/Array Comparison.
* wmemcpy: (libc)Copying Strings and Arrays.
* wmemmove: (libc)Copying Strings and Arrays.
* wmempcpy: (libc)Copying Strings and Arrays.
* wmemset: (libc)Copying Strings and Arrays.
* wordexp: (libc)Calling Wordexp.
* wordfree: (libc)Calling Wordexp.
* wprintf: (libc)Formatted Output Functions.
* write: (libc)I/O Primitives.
* writev: (libc)Scatter-Gather.
* wscanf: (libc)Formatted Input Functions.
* y0: (libc)Special Functions.
* y0f: (libc)Special Functions.
* y0fN: (libc)Special Functions.
* y0fNx: (libc)Special Functions.
* y0l: (libc)Special Functions.
* y1: (libc)Special Functions.
* y1f: (libc)Special Functions.
* y1fN: (libc)Special Functions.
* y1fNx: (libc)Special Functions.
* y1l: (libc)Special Functions.
* yn: (libc)Special Functions.
* ynf: (libc)Special Functions.
* ynfN: (libc)Special Functions.
* ynfNx: (libc)Special Functions.
* ynl: (libc)Special Functions.
END-INFO-DIR-ENTRY

   This file documents the GNU C Library.

   This is `The GNU C Library Reference Manual', for version 2.29.

   Copyright (C) 1993-2019 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version
1.3 or any later version published by the Free Software Foundation;
with the Invariant Sections being "Free Software Needs Free
Documentation" and "GNU Lesser General Public License", the Front-Cover
texts being "A GNU Manual", and with the Back-Cover Texts as in (a)
below.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

   (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom."


File: libc.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Main Menu
*********

This is `The GNU C Library Reference Manual', for Version 2.29 of the
GNU C Library.

* Menu:

* Introduction::                 Purpose of the GNU C Library.
* Error Reporting::              How library functions report errors.
* Memory::                       Allocating virtual memory and controlling
                                   paging.
* Character Handling::           Character testing and conversion functions.
* String and Array Utilities::   Utilities for copying and comparing strings
                                   and arrays.
* Character Set Handling::       Support for extended character sets.
* Locales::                      The country and language can affect the
                                   behavior of library functions.
* Message Translation::          How to make the program speak the user's
                                   language.
* Searching and Sorting::        General searching and sorting functions.
* Pattern Matching::             Matching shell ``globs'' and regular
                                   expressions.
* I/O Overview::                 Introduction to the I/O facilities.
* I/O on Streams::               High-level, portable I/O facilities.
* Low-Level I/O::                Low-level, less portable I/O.
* File System Interface::        Functions for manipulating files.
* Pipes and FIFOs::              A simple interprocess communication
                                   mechanism.
* Sockets::                      A more complicated IPC mechanism, with
                                   networking support.
* Low-Level Terminal Interface:: How to change the characteristics of a
                                   terminal device.
* Syslog::                       System logging and messaging.
* Mathematics::                  Math functions, useful constants, random
                                   numbers.
* Arithmetic::                   Low level arithmetic functions.
* Date and Time::                Functions for getting the date and time and
                                   formatting them nicely.
* Resource Usage And Limitation:: Functions for examining resource usage and
                                   getting and setting limits.
* Non-Local Exits::              Jumping out of nested function calls.
* Signal Handling::              How to send, block, and handle signals.
* Program Basics::               Writing the beginning and end of your
                                   program.
* Processes::                    How to create processes and run other
                                   programs.
* Inter-Process Communication::  All about inter-process communication.
* Job Control::                  All about process groups and sessions.
* Name Service Switch::          Accessing system databases.
* Users and Groups::             How users are identified and classified.
* System Management::            Controlling the system and getting
                                   information about it.
* System Configuration::         Parameters describing operating system
                                   limits.
* Cryptographic Functions::      Passphrase storage and strongly
                                   unpredictable bytes..
* Debugging Support::            Functions to help debugging applications.
* Threads::                      Functions, constants, and data types for
                                   working with threads.
* Internal Probes::              Probes to monitor libc internal behavior.
* Tunables::                     Tunable switches to alter libc internal
                                   behavior.

Appendices

* Language Features::            C language features provided by the library.
* Library Summary::              A summary showing the syntax, header file,
                                   and derivation of each library feature.
* Installation::                 How to install the GNU C Library.
* Maintenance::                  How to enhance and port the GNU C Library.
* Platform::                     Describe all platform-specific facilities
                                   provided.
* Contributors::                 Who wrote what parts of the GNU C Library.
* Free Manuals::		 Free Software Needs Free Documentation.
* Copying::                      The GNU Lesser General Public License says
                                  how you can copy and share the GNU C Library.
* Documentation License::        This manual is under the GNU Free
                                  Documentation License.

Indices

* Concept Index::                Index of concepts and names.
* Type Index::                   Index of types and type qualifiers.
* Function Index::               Index of functions and function-like macros.
* Variable Index::               Index of variables and variable-like macros.
* File Index::                   Index of programs and files.

  --- The Detailed Node Listing ---

Introduction

* Getting Started::             What this manual is for and how to use it.
* Standards and Portability::   Standards and sources upon which the GNU
                                 C library is based.
* Using the Library::           Some practical uses for the library.
* Roadmap to the Manual::       Overview of the remaining chapters in
                                 this manual.

Standards and Portability

* ISO C::                       The international standard for the C
                                 programming language.
* POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
                                 for operating systems.
* Berkeley Unix::               BSD and SunOS.
* SVID::                        The System V Interface Description.
* XPG::                         The X/Open Portability Guide.

POSIX

* POSIX Safety Concepts::       Safety concepts from POSIX.
* Unsafe Features::             Features that make functions unsafe.
* Conditionally Safe Features:: Features that make functions unsafe
                                 in the absence of workarounds.
* Other Safety Remarks::        Additional safety features and remarks.

Using the Library

* Header Files::                How to include the header files in your
                                 programs.
* Macro Definitions::           Some functions in the library may really
                                 be implemented as macros.
* Reserved Names::              The C standard reserves some names for
                                 the library, and some for users.
* Feature Test Macros::         How to control what names are defined.

Error Reporting

* Checking for Errors::         How errors are reported by library functions.
* Error Codes::                 Error code macros; all of these expand
                                 into integer constant values.
* Error Messages::              Mapping error codes onto error messages.

Memory

* Memory Concepts::             An introduction to concepts and terminology.
* Memory Allocation::           Allocating storage for your program data
* Resizing the Data Segment::   `brk', `sbrk'
* Memory Protection::           Controlling access to memory regions.
* Locking Pages::               Preventing page faults

Memory Allocation

* Memory Allocation and C::     How to get different kinds of allocation in C.
* The GNU Allocator::		An overview of the GNU `malloc'
				implementation.
* Unconstrained Allocation::    The `malloc' facility allows fully general
		 		 dynamic allocation.
* Allocation Debugging::        Finding memory leaks and not freed memory.
* Replacing malloc::            Using your own `malloc'-style allocator.
* Obstacks::                    Obstacks are less general than malloc
				 but more efficient and convenient.
* Variable Size Automatic::     Allocation of variable-sized blocks
				 of automatic storage that are freed when the
				 calling function returns.

Unconstrained Allocation

* Basic Allocation::            Simple use of `malloc'.
* Malloc Examples::             Examples of `malloc'.  `xmalloc'.
* Freeing after Malloc::        Use `free' to free a block you
				 got with `malloc'.
* Changing Block Size::         Use `realloc' to make a block
				 bigger or smaller.
* Allocating Cleared Space::    Use `calloc' to allocate a
				 block and clear it.
* Aligned Memory Blocks::       Allocating specially aligned memory.
* Malloc Tunable Parameters::   Use `mallopt' to adjust allocation
                                 parameters.
* Heap Consistency Checking::   Automatic checking for errors.
* Hooks for Malloc::            You can use these hooks for debugging
				 programs that use `malloc'.
* Statistics of Malloc::        Getting information about how much
				 memory your program is using.
* Summary of Malloc::           Summary of `malloc' and related functions.

Allocation Debugging

* Tracing malloc::               How to install the tracing functionality.
* Using the Memory Debugger::    Example programs excerpts.
* Tips for the Memory Debugger:: Some more or less clever ideas.
* Interpreting the traces::      What do all these lines mean?

Obstacks

* Creating Obstacks::		How to declare an obstack in your program.
* Preparing for Obstacks::	Preparations needed before you can
				 use obstacks.
* Allocation in an Obstack::    Allocating objects in an obstack.
* Freeing Obstack Objects::     Freeing objects in an obstack.
* Obstack Functions::		The obstack functions are both
				 functions and macros.
* Growing Objects::             Making an object bigger by stages.
* Extra Fast Growing::		Extra-high-efficiency (though more
				 complicated) growing objects.
* Status of an Obstack::        Inquiries about the status of an obstack.
* Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
* Obstack Chunks::              How obstacks obtain and release chunks;
				 efficiency considerations.
* Summary of Obstacks::

Variable Size Automatic

* Alloca Example::              Example of using `alloca'.
* Advantages of Alloca::        Reasons to use `alloca'.
* Disadvantages of Alloca::     Reasons to avoid `alloca'.
* GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
				 method of allocating dynamically and
				 freeing automatically.

Locking Pages

* Why Lock Pages::                Reasons to read this section.
* Locked Memory Details::         Everything you need to know locked
                                    memory
* Page Lock Functions::           Here's how to do it.

Character Handling

* Classification of Characters::       Testing whether characters are
			                letters, digits, punctuation, etc.

* Case Conversion::                    Case mapping, and the like.
* Classification of Wide Characters::  Character class determination for
                                        wide characters.
* Using Wide Char Classes::            Notes on using the wide character
                                        classes.
* Wide Character Case Conversion::     Mapping of wide characters.

String and Array Utilities

* Representation of Strings::   Introduction to basic concepts.
* String/Array Conventions::    Whether to use a string function or an
				 arbitrary array function.
* String Length::               Determining the length of a string.
* Copying Strings and Arrays::  Functions to copy strings and arrays.
* Concatenating Strings::       Functions to concatenate strings while copying.
* Truncating Strings::          Functions to truncate strings while copying.
* String/Array Comparison::     Functions for byte-wise and character-wise
				 comparison.
* Collation Functions::         Functions for collating strings.
* Search Functions::            Searching for a specific element or substring.
* Finding Tokens in a String::  Splitting a string into tokens by looking
				 for delimiters.
* Erasing Sensitive Data::      Clearing memory which contains sensitive
                                 data, after it's no longer needed.
* Shuffling Bytes::             Or how to flash-cook a string.
* Obfuscating Data::            Reversibly obscuring data from casual view.
* Encode Binary Data::          Encoding and Decoding of Binary Data.
* Argz and Envz Vectors::       Null-separated string vectors.

Argz and Envz Vectors

* Argz Functions::              Operations on argz vectors.
* Envz Functions::              Additional operations on environment vectors.

Character Set Handling

* Extended Char Intro::              Introduction to Extended Characters.
* Charset Function Overview::        Overview about Character Handling
                                      Functions.
* Restartable multibyte conversion:: Restartable multibyte conversion
                                      Functions.
* Non-reentrant Conversion::         Non-reentrant Conversion Function.
* Generic Charset Conversion::       Generic Charset Conversion.

Restartable multibyte conversion

* Selecting the Conversion::     Selecting the conversion and its properties.
* Keeping the state::            Representing the state of the conversion.
* Converting a Character::       Converting Single Characters.
* Converting Strings::           Converting Multibyte and Wide Character
                                  Strings.
* Multibyte Conversion Example:: A Complete Multibyte Conversion Example.

Non-reentrant Conversion

* Non-reentrant Character Conversion::  Non-reentrant Conversion of Single
                                         Characters.
* Non-reentrant String Conversion::     Non-reentrant Conversion of Strings.
* Shift State::                         States in Non-reentrant Functions.

Generic Charset Conversion

* Generic Conversion Interface::    Generic Character Set Conversion Interface.
* iconv Examples::                  A complete `iconv' example.
* Other iconv Implementations::     Some Details about other `iconv'
                                     Implementations.
* glibc iconv Implementation::      The `iconv' Implementation in the GNU C
                                     library.

Locales

* Effects of Locale::           Actions affected by the choice of
                                 locale.
* Choosing Locale::             How the user specifies a locale.
* Locale Categories::           Different purposes for which you can
                                 select a locale.
* Setting the Locale::          How a program specifies the locale
                                 with library functions.
* Standard Locales::            Locale names available on all systems.
* Locale Names::                Format of system-specific locale names.
* Locale Information::          How to access the information for the locale.
* Formatting Numbers::          A dedicated function to format numbers.
* Yes-or-No Questions::         Check a Response against the locale.

Locale Information

* The Lame Way to Locale Data::   ISO C's `localeconv'.
* The Elegant and Fast Way::      X/Open's `nl_langinfo'.

The Lame Way to Locale Data

* General Numeric::             Parameters for formatting numbers and
                                 currency amounts.
* Currency Symbol::             How to print the symbol that identifies an
                                 amount of money (e.g. `$').
* Sign of Money Amount::        How to print the (positive or negative) sign
                                 for a monetary amount, if one exists.

Message Translation

* Message catalogs a la X/Open::  The `catgets' family of functions.
* The Uniforum approach::         The `gettext' family of functions.

Message catalogs a la X/Open

* The catgets Functions::      The `catgets' function family.
* The message catalog files::  Format of the message catalog files.
* The gencat program::         How to generate message catalogs files which
                                can be used by the functions.
* Common Usage::               How to use the `catgets' interface.

The Uniforum approach

* Message catalogs with gettext::  The `gettext' family of functions.
* Helper programs for gettext::    Programs to handle message catalogs
                                    for `gettext'.

Message catalogs with gettext

* Translation with gettext::       What has to be done to translate a message.
* Locating gettext catalog::       How to determine which catalog to be used.
* Advanced gettext functions::     Additional functions for more complicated
                                    situations.
* Charset conversion in gettext::  How to specify the output character set
                                    `gettext' uses.
* GUI program problems::           How to use `gettext' in GUI programs.
* Using gettextized software::     The possibilities of the user to influence
                                    the way `gettext' works.

Searching and Sorting

* Comparison Functions::        Defining how to compare two objects.
				 Since the sort and search facilities
                                 are general, you have to specify the
                                 ordering.
* Array Search Function::       The `bsearch' function.
* Array Sort Function::         The `qsort' function.
* Search/Sort Example::         An example program.
* Hash Search Function::        The `hsearch' function.
* Tree Search Function::        The `tsearch' function.

Pattern Matching

* Wildcard Matching::    Matching a wildcard pattern against a single string.
* Globbing::             Finding the files that match a wildcard pattern.
* Regular Expressions::  Matching regular expressions against strings.
* Word Expansion::       Expanding shell variables, nested commands,
			    arithmetic, and wildcards.
			    This is what the shell does with shell commands.

Globbing

* Calling Glob::             Basic use of `glob'.
* Flags for Globbing::       Flags that enable various options in `glob'.
* More Flags for Globbing::  GNU specific extensions to `glob'.

Regular Expressions

* POSIX Regexp Compilation::    Using `regcomp' to prepare to match.
* Flags for POSIX Regexps::     Syntax variations for `regcomp'.
* Matching POSIX Regexps::      Using `regexec' to match the compiled
				   pattern that you get from `regcomp'.
* Regexp Subexpressions::       Finding which parts of the string were matched.
* Subexpression Complications:: Find points of which parts were matched.
* Regexp Cleanup::		Freeing storage; reporting errors.

Word Expansion

* Expansion Stages::            What word expansion does to a string.
* Calling Wordexp::             How to call `wordexp'.
* Flags for Wordexp::           Options you can enable in `wordexp'.
* Wordexp Example::             A sample program that does word expansion.
* Tilde Expansion::             Details of how tilde expansion works.
* Variable Substitution::       Different types of variable substitution.

I/O Overview

* I/O Concepts::       Some basic information and terminology.
* File Names::         How to refer to a file.

I/O Concepts

* Streams and File Descriptors::    The GNU C Library provides two ways
			             to access the contents of files.
* File Position::                   The number of bytes from the
                                     beginning of the file.

File Names

* Directories::                 Directories contain entries for files.
* File Name Resolution::        A file name specifies how to look up a file.
* File Name Errors::            Error conditions relating to file names.
* File Name Portability::       File name portability and syntax issues.

I/O on Streams

* Streams::                     About the data type representing a stream.
* Standard Streams::            Streams to the standard input and output
				 devices are created for you.
* Opening Streams::             How to create a stream to talk to a file.
* Closing Streams::             Close a stream when you are finished with it.
* Streams and Threads::         Issues with streams in threaded programs.
* Streams and I18N::            Streams in internationalized applications.
* Simple Output::               Unformatted output by characters and lines.
* Character Input::             Unformatted input by characters and words.
* Line Input::                  Reading a line or a record from a stream.
* Unreading::                   Peeking ahead/pushing back input just read.
* Block Input/Output::          Input and output operations on blocks of data.
* Formatted Output::            `printf' and related functions.
* Customizing Printf::          You can define new conversion specifiers for
				 `printf' and friends.
* Formatted Input::             `scanf' and related functions.
* EOF and Errors::              How you can tell if an I/O error happens.
* Error Recovery::		What you can do about errors.
* Binary Streams::              Some systems distinguish between text files
				 and binary files.
* File Positioning::            About random-access streams.
* Portable Positioning::        Random access on peculiar ISO C systems.
* Stream Buffering::            How to control buffering of streams.
* Other Kinds of Streams::      Streams that do not necessarily correspond
				 to an open file.
* Formatted Messages::          Print strictly formatted messages.

Unreading

* Unreading Idea::              An explanation of unreading with pictures.
* How Unread::                  How to call `ungetc' to do unreading.

Formatted Output

* Formatted Output Basics::     Some examples to get you started.
* Output Conversion Syntax::    General syntax of conversion
				 specifications.
* Table of Output Conversions:: Summary of output conversions and
				 what they do.
* Integer Conversions::         Details about formatting of integers.
* Floating-Point Conversions::  Details about formatting of
				 floating-point numbers.
* Other Output Conversions::    Details about formatting of strings,
				 characters, pointers, and the like.
* Formatted Output Functions::  Descriptions of the actual functions.
* Dynamic Output::		Functions that allocate memory for the output.
* Variable Arguments Output::   `vprintf' and friends.
* Parsing a Template String::   What kinds of args does a given template
				 call for?
* Example of Parsing::          Sample program using `parse_printf_format'.

Customizing Printf

* Registering New Conversions::         Using `register_printf_function'
					 to register a new output conversion.
* Conversion Specifier Options::        The handler must be able to get
					 the options specified in the
					 template when it is called.
* Defining the Output Handler::         Defining the handler and arginfo
					 functions that are passed as arguments
					 to `register_printf_function'.
* Printf Extension Example::            How to define a `printf'
					 handler function.
* Predefined Printf Handlers::          Predefined `printf' handlers.

Formatted Input

* Formatted Input Basics::      Some basics to get you started.
* Input Conversion Syntax::     Syntax of conversion specifications.
* Table of Input Conversions::  Summary of input conversions and what they do.
* Numeric Input Conversions::   Details of conversions for reading numbers.
* String Input Conversions::    Details of conversions for reading strings.
* Dynamic String Input::	String conversions that `malloc' the buffer.
* Other Input Conversions::     Details of miscellaneous other conversions.
* Formatted Input Functions::   Descriptions of the actual functions.
* Variable Arguments Input::    `vscanf' and friends.

Stream Buffering

* Buffering Concepts::          Terminology is defined here.
* Flushing Buffers::            How to ensure that output buffers are flushed.
* Controlling Buffering::       How to specify what kind of buffering to use.

Other Kinds of Streams

* String Streams::              Streams that get data from or put data in
				 a string or memory buffer.
* Custom Streams::              Defining your own streams with an arbitrary
				 input data source and/or output data sink.

Custom Streams

* Streams and Cookies::         The "cookie" records where to fetch or
				 store data that is read or written.
* Hook Functions::              How you should define the four "hook
				 functions" that a custom stream needs.

Formatted Messages

* Printing Formatted Messages::   The `fmtmsg' function.
* Adding Severity Classes::       Add more severity classes.
* Example::                       How to use `fmtmsg' and `addseverity'.

Low-Level I/O

* Opening and Closing Files::           How to open and close file
                                         descriptors.
* I/O Primitives::                      Reading and writing data.
* File Position Primitive::             Setting a descriptor's file
                                         position.
* Descriptors and Streams::             Converting descriptor to stream
                                         or vice-versa.
* Stream/Descriptor Precautions::       Precautions needed if you use both
                                         descriptors and streams.
* Scatter-Gather::                      Fast I/O to discontinuous buffers.
* Copying File Data::                   Copying data between files.
* Memory-mapped I/O::                   Using files like memory.
* Waiting for I/O::                     How to check for input or output
					 on multiple file descriptors.
* Synchronizing I/O::                   Making sure all I/O actions completed.
* Asynchronous I/O::                    Perform I/O in parallel.
* Control Operations::                  Various other operations on file
					 descriptors.
* Duplicating Descriptors::             Fcntl commands for duplicating
                                         file descriptors.
* Descriptor Flags::                    Fcntl commands for manipulating
                                         flags associated with file
                                         descriptors.
* File Status Flags::                   Fcntl commands for manipulating
                                         flags associated with open files.
* File Locks::                          Fcntl commands for implementing
                                         file locking.
* Open File Description Locks::         Fcntl commands for implementing
                                         open file description locking.
* Open File Description Locks Example:: An example of open file description lock
                                         usage
* Interrupt Input::                     Getting an asynchronous signal when
                                         input arrives.
* IOCTLs::                              Generic I/O Control operations.

Stream/Descriptor Precautions

* Linked Channels::	   Dealing with channels sharing a file position.
* Independent Channels::   Dealing with separately opened, unlinked channels.
* Cleaning Streams::	   Cleaning a stream makes it safe to use
                            another channel.

Asynchronous I/O

* Asynchronous Reads/Writes::    Asynchronous Read and Write Operations.
* Status of AIO Operations::     Getting the Status of AIO Operations.
* Synchronizing AIO Operations:: Getting into a consistent state.
* Cancel AIO Operations::        Cancellation of AIO Operations.
* Configuration of AIO::         How to optimize the AIO implementation.

File Status Flags

* Access Modes::                Whether the descriptor can read or write.
* Open-time Flags::             Details of `open'.
* Operating Modes::             Special modes to control I/O operations.
* Getting File Status Flags::   Fetching and changing these flags.

File System Interface

* Working Directory::           This is used to resolve relative
				 file names.
* Accessing Directories::       Finding out what files a directory
				 contains.
* Working with Directory Trees:: Apply actions to all files or a selectable
                                 subset of a directory hierarchy.
* Hard Links::                  Adding alternate names to a file.
* Symbolic Links::              A file that ``points to'' a file name.
* Deleting Files::              How to delete a file, and what that means.
* Renaming Files::              Changing a file's name.
* Creating Directories::        A system call just for creating a directory.
* File Attributes::             Attributes of individual files.
* Making Special Files::        How to create special files.
* Temporary Files::             Naming and creating temporary files.

Accessing Directories

* Directory Entries::           Format of one directory entry.
* Opening a Directory::         How to open a directory stream.
* Reading/Closing Directory::   How to read directory entries from the stream.
* Simple Directory Lister::     A very simple directory listing program.
* Random Access Directory::     Rereading part of the directory
                                 already read with the same stream.
* Scanning Directory Content::  Get entries for user selected subset of
                                 contents in given directory.
* Simple Directory Lister Mark II::  Revised version of the program.

File Attributes

* Attribute Meanings::          The names of the file attributes,
                                 and what their values mean.
* Reading Attributes::          How to read the attributes of a file.
* Testing File Type::           Distinguishing ordinary files,
                                 directories, links...
* File Owner::                  How ownership for new files is determined,
			         and how to change it.
* Permission Bits::             How information about a file's access
                                 mode is stored.
* Access Permission::           How the system decides who can access a file.
* Setting Permissions::         How permissions for new files are assigned,
			         and how to change them.
* Testing File Access::         How to find out if your process can
                                 access a file.
* File Times::                  About the time attributes of a file.
* File Size::			Manually changing the size of a file.
* Storage Allocation::          Allocate backing storage for files.

Pipes and FIFOs

* Creating a Pipe::             Making a pipe with the `pipe' function.
* Pipe to a Subprocess::        Using a pipe to communicate with a
				 child process.
* FIFO Special Files::          Making a FIFO special file.
* Pipe Atomicity::		When pipe (or FIFO) I/O is atomic.

Sockets

* Socket Concepts::	Basic concepts you need to know about.
* Communication Styles::Stream communication, datagrams and other styles.
* Socket Addresses::	How socket names (``addresses'') work.
* Interface Naming::	Identifying specific network interfaces.
* Local Namespace::	Details about the local namespace.
* Internet Namespace::	Details about the Internet namespace.
* Misc Namespaces::	Other namespaces not documented fully here.
* Open/Close Sockets::  Creating sockets and destroying them.
* Connections::		Operations on sockets with connection state.
* Datagrams::		Operations on datagram sockets.
* Inetd::		Inetd is a daemon that starts servers on request.
			   The most convenient way to write a server
			   is to make it work with Inetd.
* Socket Options::	Miscellaneous low-level socket options.
* Networks Database::   Accessing the database of network names.

Socket Addresses

* Address Formats::		About `struct sockaddr'.
* Setting Address::		Binding an address to a socket.
* Reading Address::		Reading the address of a socket.

Local Namespace

* Concepts: Local Namespace Concepts. What you need to understand.
* Details: Local Namespace Details.   Address format, symbolic names, etc.
* Example: Local Socket Example.      Example of creating a socket.

Internet Namespace

* Internet Address Formats::    How socket addresses are specified in the
                                 Internet namespace.
* Host Addresses::	        All about host addresses of Internet host.
* Ports::			Internet port numbers.
* Services Database::           Ports may have symbolic names.
* Byte Order::		        Different hosts may use different byte
                                 ordering conventions; you need to
                                 canonicalize host address and port number.
* Protocols Database::		Referring to protocols by name.
* Inet Example::	        Putting it all together.

Host Addresses

* Abstract Host Addresses::	What a host number consists of.
* Data type: Host Address Data Type.	Data type for a host number.
* Functions: Host Address Functions.	Functions to operate on them.
* Names: Host Names.		Translating host names to host numbers.

Open/Close Sockets

* Creating a Socket::           How to open a socket.
* Closing a Socket::            How to close a socket.
* Socket Pairs::                These are created like pipes.

Connections

* Connecting::    	     What the client program must do.
* Listening::		     How a server program waits for requests.
* Accepting Connections::    What the server does when it gets a request.
* Who is Connected::	     Getting the address of the
				other side of a connection.
* Transferring Data::        How to send and receive data.
* Byte Stream Example::	     An example program: a client for communicating
			      over a byte stream socket in the Internet namespace.
* Server Example::	     A corresponding server program.
* Out-of-Band Data::         This is an advanced feature.

Transferring Data

* Sending Data::		Sending data with `send'.
* Receiving Data::		Reading data with `recv'.
* Socket Data Options::		Using `send' and `recv'.

Datagrams

* Sending Datagrams::    Sending packets on a datagram socket.
* Receiving Datagrams::  Receiving packets on a datagram socket.
* Datagram Example::     An example program: packets sent over a
                           datagram socket in the local namespace.
* Example Receiver::	 Another program, that receives those packets.

Inetd

* Inetd Servers::
* Configuring Inetd::

Socket Options

* Socket Option Functions::     The basic functions for setting and getting
                                 socket options.
* Socket-Level Options::        Details of the options at the socket level.

Low-Level Terminal Interface

* Is It a Terminal::            How to determine if a file is a terminal
			         device, and what its name is.
* I/O Queues::                  About flow control and typeahead.
* Canonical or Not::            Two basic styles of input processing.
* Terminal Modes::              How to examine and modify flags controlling
			         details of terminal I/O: echoing,
                                 signals, editing.  Posix.
* BSD Terminal Modes::          BSD compatible terminal mode setting
* Line Control::                Sending break sequences, clearing
                                 terminal buffers ...
* Noncanon Example::            How to read single characters without echo.
* getpass::                     Prompting the user for a passphrase.
* Pseudo-Terminals::            How to open a pseudo-terminal.

Terminal Modes

* Mode Data Types::             The data type `struct termios' and
                                 related types.
* Mode Functions::              Functions to read and set the terminal
                                 attributes.
* Setting Modes::               The right way to set terminal attributes
                                 reliably.
* Input Modes::                 Flags controlling low-level input handling.
* Output Modes::                Flags controlling low-level output handling.
* Control Modes::               Flags controlling serial port behavior.
* Local Modes::                 Flags controlling high-level input handling.
* Line Speed::                  How to read and set the terminal line speed.
* Special Characters::          Characters that have special effects,
			         and how to change them.
* Noncanonical Input::          Controlling how long to wait for input.

Special Characters

* Editing Characters::          Special characters that terminate lines and
                                  delete text, and other editing functions.
* Signal Characters::           Special characters that send or raise signals
                                  to or for certain classes of processes.
* Start/Stop Characters::       Special characters that suspend or resume
                                  suspended output.
* Other Special::		Other special characters for BSD systems:
				  they can discard output, and print status.

Pseudo-Terminals

* Allocation::             Allocating a pseudo terminal.
* Pseudo-Terminal Pairs::  How to open both sides of a
                            pseudo-terminal in a single operation.

Syslog

* Overview of Syslog::           Overview of a system's Syslog facility
* Submitting Syslog Messages::   Functions to submit messages to Syslog

Submitting Syslog Messages

* openlog::                      Open connection to Syslog
* syslog; vsyslog::              Submit message to Syslog
* closelog::                     Close connection to Syslog
* setlogmask::                   Cause certain messages to be ignored
* Syslog Example::               Example of all of the above

Mathematics

* Mathematical Constants::      Precise numeric values for often-used
                                 constants.
* Trig Functions::              Sine, cosine, tangent, and friends.
* Inverse Trig Functions::      Arcsine, arccosine, etc.
* Exponents and Logarithms::    Also pow and sqrt.
* Hyperbolic Functions::        sinh, cosh, tanh, etc.
* Special Functions::           Bessel, gamma, erf.
* Errors in Math Functions::    Known Maximum Errors in Math Functions.
* Pseudo-Random Numbers::       Functions for generating pseudo-random
				 numbers.
* FP Function Optimizations::   Fast code or small code.

Pseudo-Random Numbers

* ISO Random::                  `rand' and friends.
* BSD Random::                  `random' and friends.
* SVID Random::                 `drand48' and friends.

Arithmetic

* Integers::                    Basic integer types and concepts
* Integer Division::            Integer division with guaranteed rounding.
* Floating Point Numbers::      Basic concepts.  IEEE 754.
* Floating Point Classes::      The five kinds of floating-point number.
* Floating Point Errors::       When something goes wrong in a calculation.
* Rounding::                    Controlling how results are rounded.
* Control Functions::           Saving and restoring the FPU's state.
* Arithmetic Functions::        Fundamental operations provided by the library.
* Complex Numbers::             The types.  Writing complex constants.
* Operations on Complex::       Projection, conjugation, decomposition.
* Parsing of Numbers::          Converting strings to numbers.
* Printing of Floats::          Converting floating-point numbers to strings.
* System V Number Conversion::  An archaic way to convert numbers to strings.

Floating Point Errors

* FP Exceptions::               IEEE 754 math exceptions and how to detect them.
* Infinity and NaN::            Special values returned by calculations.
* Status bit operations::       Checking for exceptions after the fact.
* Math Error Reporting::        How the math functions report errors.

Arithmetic Functions

* Absolute Value::              Absolute values of integers and floats.
* Normalization Functions::     Extracting exponents and putting them back.
* Rounding Functions::          Rounding floats to integers.
* Remainder Functions::         Remainders on division, precisely defined.
* FP Bit Twiddling::            Sign bit adjustment.  Adding epsilon.
* FP Comparison Functions::     Comparisons without risk of exceptions.
* Misc FP Arithmetic::          Max, min, positive difference, multiply-add.

Parsing of Numbers

* Parsing of Integers::         Functions for conversion of integer values.
* Parsing of Floats::           Functions for conversion of floating-point
				 values.

Date and Time

* Time Basics::                 Concepts and definitions.
* Elapsed Time::                Data types to represent elapsed times
* Processor And CPU Time::      Time a program has spent executing.
* Calendar Time::               Manipulation of ``real'' dates and times.
* Setting an Alarm::            Sending a signal after a specified time.
* Sleeping::                    Waiting for a period of time.

Processor And CPU Time

* CPU Time::                    The `clock' function.
* Processor Time::              The `times' function.

Calendar Time

* Simple Calendar Time::        Facilities for manipulating calendar time.
* High-Resolution Calendar::    A time representation with greater precision.
* Broken-down Time::            Facilities for manipulating local time.
* High Accuracy Clock::         Maintaining a high accuracy system clock.
* Formatting Calendar Time::    Converting times to strings.
* Parsing Date and Time::       Convert textual time and date information back
                                 into broken-down time values.
* TZ Variable::                 How users specify the time zone.
* Time Zone Functions::         Functions to examine or specify the time zone.
* Time Functions Example::      An example program showing use of some of
				 the time functions.

Parsing Date and Time

* Low-Level Time String Parsing::  Interpret string according to given format.
* General Time String Parsing::    User-friendly function to parse data and
                                    time strings.

Resource Usage And Limitation

* Resource Usage::		Measuring various resources used.
* Limits on Resources::		Specifying limits on resource usage.
* Priority::			Reading or setting process run priority.
* Memory Resources::            Querying memory available resources.
* Processor Resources::         Learn about the processors available.

Priority

* Absolute Priority::               The first tier of priority.  Posix
* Realtime Scheduling::             Scheduling among the process nobility
* Basic Scheduling Functions::      Get/set scheduling policy, priority
* Traditional Scheduling::          Scheduling among the vulgar masses
* CPU Affinity::                    Limiting execution to certain CPUs

Traditional Scheduling

* Traditional Scheduling Intro::
* Traditional Scheduling Functions::

Memory Resources

* Memory Subsystem::           Overview about traditional Unix memory handling.
* Query Memory Parameters::    How to get information about the memory
                                subsystem?

Non-Local Exits

* Intro: Non-Local Intro.        When and how to use these facilities.
* Details: Non-Local Details.    Functions for non-local exits.
* Non-Local Exits and Signals::  Portability issues.
* System V contexts::            Complete context control a la System V.

Signal Handling

* Concepts of Signals::         Introduction to the signal facilities.
* Standard Signals::            Particular kinds of signals with
                                 standard names and meanings.
* Signal Actions::              Specifying what happens when a
                                 particular signal is delivered.
* Defining Handlers::           How to write a signal handler function.
* Interrupted Primitives::	Signal handlers affect use of `open',
				 `read', `write' and other functions.
* Generating Signals::          How to send a signal to a process.
* Blocking Signals::            Making the system hold signals temporarily.
* Waiting for a Signal::        Suspending your program until a signal
                                 arrives.
* Signal Stack::                Using a Separate Signal Stack.
* BSD Signal Handling::         Additional functions for backward
			         compatibility with BSD.

Concepts of Signals

* Kinds of Signals::            Some examples of what can cause a signal.
* Signal Generation::           Concepts of why and how signals occur.
* Delivery of Signal::          Concepts of what a signal does to the
                                 process.

Standard Signals

* Program Error Signals::       Used to report serious program errors.
* Termination Signals::         Used to interrupt and/or terminate the
                                 program.
* Alarm Signals::               Used to indicate expiration of timers.
* Asynchronous I/O Signals::    Used to indicate input is available.
* Job Control Signals::         Signals used to support job control.
* Operation Error Signals::     Used to report operational system errors.
* Miscellaneous Signals::       Miscellaneous Signals.
* Signal Messages::             Printing a message describing a signal.

Signal Actions

* Basic Signal Handling::       The simple `signal' function.
* Advanced Signal Handling::    The more powerful `sigaction' function.
* Signal and Sigaction::        How those two functions interact.
* Sigaction Function Example::  An example of using the sigaction function.
* Flags for Sigaction::         Specifying options for signal handling.
* Initial Signal Actions::      How programs inherit signal actions.

Defining Handlers

* Handler Returns::             Handlers that return normally, and what
                                 this means.
* Termination in Handler::      How handler functions terminate a program.
* Longjmp in Handler::          Nonlocal transfer of control out of a
                                 signal handler.
* Signals in Handler::          What happens when signals arrive while
                                 the handler is already occupied.
* Merged Signals::		When a second signal arrives before the
				 first is handled.
* Nonreentrancy::               Do not call any functions unless you know they
                                 are reentrant with respect to signals.
* Atomic Data Access::          A single handler can run in the middle of
                                 reading or writing a single object.

Atomic Data Access

* Non-atomic Example::		A program illustrating interrupted access.
* Types: Atomic Types.		Data types that guarantee no interruption.
* Usage: Atomic Usage.		Proving that interruption is harmless.

Generating Signals

* Signaling Yourself::          A process can send a signal to itself.
* Signaling Another Process::   Send a signal to another process.
* Permission for kill::         Permission for using `kill'.
* Kill Example::                Using `kill' for Communication.

Blocking Signals

* Why Block::                           The purpose of blocking signals.
* Signal Sets::                         How to specify which signals to
                                         block.
* Process Signal Mask::                 Blocking delivery of signals to your
				         process during normal execution.
* Testing for Delivery::                Blocking to Test for Delivery of
                                         a Signal.
* Blocking for Handler::                Blocking additional signals while a
				         handler is being run.
* Checking for Pending Signals::        Checking for Pending Signals
* Remembering a Signal::                How you can get almost the same
                                         effect as blocking a signal, by
                                         handling it and setting a flag
                                         to be tested later.

Waiting for a Signal

* Using Pause::                 The simple way, using `pause'.
* Pause Problems::              Why the simple way is often not very good.
* Sigsuspend::                  Reliably waiting for a specific signal.

Program Basics

* Program Arguments::           Parsing your program's command-line arguments
* Environment Variables::       Less direct parameters affecting your program
* Auxiliary Vector::            Least direct parameters affecting your program
* System Calls::                Requesting service from the system
* Program Termination::         Telling the system you're done; return status

Program Arguments

* Argument Syntax::             By convention, options start with a hyphen.
* Parsing Program Arguments::   Ways to parse program options and arguments.

Parsing Program Arguments

* Getopt::                      Parsing program options using `getopt'.
* Argp::                        Parsing program options using `argp_parse'.
* Suboptions::                  Some programs need more detailed options.
* Suboptions Example::          This shows how it could be done for `mount'.

Environment Variables

* Environment Access::          How to get and set the values of
				 environment variables.
* Standard Environment::        These environment variables have
                		 standard interpretations.

Program Termination

* Normal Termination::          If a program calls `exit', a
                                 process terminates normally.
* Exit Status::                 The `exit status' provides information
                                 about why the process terminated.
* Cleanups on Exit::            A process can run its own cleanup
                                 functions upon normal termination.
* Aborting a Program::          The `abort' function causes
                                 abnormal program termination.
* Termination Internals::       What happens when a process terminates.

Processes

* Running a Command::           The easy way to run another program.
* Process Creation Concepts::   An overview of the hard way to do it.
* Process Identification::      How to get the process ID of a process.
* Creating a Process::          How to fork a child process.
* Executing a File::            How to make a process execute another program.
* Process Completion::          How to tell when a child process has completed.
* Process Completion Status::   How to interpret the status value
                                 returned from a child process.
* BSD Wait Functions::  	More functions, for backward compatibility.
* Process Creation Example::    A complete example program.

Inter-Process Communication

* Semaphores::	Support for creating and managing semaphores

Job Control

* Concepts of Job Control::     Jobs can be controlled by a shell.
* Controlling Terminal::        How a process gets its controlling terminal.
* Access to the Terminal::      How processes share the controlling terminal.
* Orphaned Process Groups::     Jobs left after the user logs out.
* Implementing a Shell::        What a shell must do to implement job control.
* Functions for Job Control::   Functions to control process groups.

Implementing a Shell

* Data Structures::             Introduction to the sample shell.
* Initializing the Shell::      What the shell must do to take
				 responsibility for job control.
* Launching Jobs::              Creating jobs to execute commands.
* Foreground and Background::   Putting a job in foreground of background.
* Stopped and Terminated Jobs::  Reporting job status.
* Continuing Stopped Jobs::     How to continue a stopped job in
				 the foreground or background.
* Missing Pieces::              Other parts of the shell.

Functions for Job Control

* Identifying the Terminal::    Determining the controlling terminal's name.
* Process Group Functions::     Functions for manipulating process groups.
* Terminal Access Functions::   Functions for controlling terminal access.

Name Service Switch

* NSS Basics::                  What is this NSS good for.
* NSS Configuration File::      Configuring NSS.
* NSS Module Internals::        How does it work internally.
* Extending NSS::               What to do to add services or databases.

NSS Configuration File

* Services in the NSS configuration::  Service names in the NSS configuration.
* Actions in the NSS configuration::  React appropriately to the lookup result.
* Notes on NSS Configuration File::  Things to take care about while
                                     configuring NSS.

NSS Module Internals

* NSS Module Names::            Construction of the interface function of
                                the NSS modules.
* NSS Modules Interface::       Programming interface in the NSS module
                                functions.

Extending NSS

* Adding another Service to NSS::  What is to do to add a new service.
* NSS Module Function Internals::  Guidelines for writing new NSS
                                        service functions.

Users and Groups

* User and Group IDs::          Each user has a unique numeric ID;
				 likewise for groups.
* Process Persona::             The user IDs and group IDs of a process.
* Why Change Persona::          Why a program might need to change
				 its user and/or group IDs.
* How Change Persona::          Changing the user and group IDs.
* Reading Persona::             How to examine the user and group IDs.

* Setting User ID::             Functions for setting the user ID.
* Setting Groups::              Functions for setting the group IDs.

* Enable/Disable Setuid::       Turning setuid access on and off.
* Setuid Program Example::      The pertinent parts of one sample program.
* Tips for Setuid::             How to avoid granting unlimited access.

* Who Logged In::               Getting the name of the user who logged in,
				 or of the real user ID of the current process.

* User Accounting Database::    Keeping information about users and various
                                 actions in databases.

* User Database::               Functions and data structures for
                        	 accessing the user database.
* Group Database::              Functions and data structures for
                        	 accessing the group database.
* Database Example::            Example program showing the use of database
				 inquiry functions.
* Netgroup Database::           Functions for accessing the netgroup database.

User Accounting Database

* Manipulating the Database::   Scanning and modifying the user
                                 accounting database.
* XPG Functions::               A standardized way for doing the same thing.
* Logging In and Out::          Functions from BSD that modify the user
                                 accounting database.

User Database

* User Data Structure::         What each user record contains.
* Lookup User::                 How to look for a particular user.
* Scanning All Users::          Scanning the list of all users, one by one.
* Writing a User Entry::        How a program can rewrite a user's record.

Group Database

* Group Data Structure::        What each group record contains.
* Lookup Group::                How to look for a particular group.
* Scanning All Groups::         Scanning the list of all groups.

Netgroup Database

* Netgroup Data::                  Data in the Netgroup database and where
                                   it comes from.
* Lookup Netgroup::                How to look for a particular netgroup.
* Netgroup Membership::            How to test for netgroup membership.

System Management

* Host Identification::         Determining the name of the machine.
* Platform Type::               Determining operating system and basic
                                  machine type
* Filesystem Handling::         Controlling/querying mounts
* System Parameters::           Getting and setting various system parameters

Filesystem Handling

* Mount Information::           What is or could be mounted?
* Mount-Unmount-Remount::       Controlling what is mounted and how

Mount Information

* fstab::                       The `fstab' file
* mtab::                        The `mtab' file
* Other Mount Information::     Other (non-libc) sources of mount information

System Configuration

* General Limits::           Constants and functions that describe
				various process-related limits that have
				one uniform value for any given machine.
* System Options::           Optional POSIX features.
* Version Supported::        Version numbers of POSIX.1 and POSIX.2.
* Sysconf::                  Getting specific configuration values
                                of general limits and system options.
* Minimums::                 Minimum values for general limits.

* Limits for Files::         Size limitations that pertain to individual files.
                                These can vary between file systems
                                or even from file to file.
* Options for Files::        Optional features that some files may support.
* File Minimums::            Minimum values for file limits.
* Pathconf::                 Getting the limit values for a particular file.

* Utility Limits::           Capacity limits of some POSIX.2 utility programs.
* Utility Minimums::         Minimum allowable values of those limits.

* String Parameters::        Getting the default search path.

Sysconf

* Sysconf Definition::        Detailed specifications of `sysconf'.
* Constants for Sysconf::     The list of parameters `sysconf' can read.
* Examples of Sysconf::       How to use `sysconf' and the parameter
				 macros properly together.

Cryptographic Functions

* Passphrase Storage::          One-way hashing for passphrases.
* Unpredictable Bytes::         Randomness for cryptographic purposes.

Debugging Support

* Backtraces::                Obtaining and printing a back trace of the
                               current stack.

Threads

* ISO C Threads::	Threads based on the ISO C specification.
* POSIX Threads::	Threads based on the POSIX specification.

ISO C Threads

* ISO C Threads Return Values:: Symbolic constants that represent a
				function's return value.
* ISO C Thread Management::	Support for basic threading.
* Call Once::			Single-call functions and macros.
* ISO C Mutexes::		A low-level mechanism for mutual exclusion.
* ISO C Condition Variables::	High-level objects for thread synchronization.
* ISO C Thread-local Storage::	Functions to support thread-local storage.

POSIX Threads

* Thread-specific Data::          Support for creating and
				  managing thread-specific data
* Non-POSIX Extensions::          Additional functions to extend
				  POSIX Thread functionality

Non-POSIX Extensions

* Default Thread Attributes::             Setting default attributes for
					  threads in a process.

Internal Probes

* Memory Allocation Probes::  Probes in the memory allocation subsystem
* Mathematical Function Probes::  Probes in mathematical functions
* Non-local Goto Probes::  Probes in setjmp and longjmp

Tunables

* Tunable names::  The structure of a tunable name
* Memory Allocation Tunables::  Tunables in the memory allocation subsystem
* Elision Tunables::  Tunables in elision subsystem
* POSIX Thread Tunables:: Tunables in the POSIX thread subsystem
* Hardware Capability Tunables::  Tunables that modify the hardware
				  capabilities seen by the GNU C Library

Language Features

* Consistency Checking::        Using `assert' to abort if
				 something ``impossible'' happens.
* Variadic Functions::          Defining functions with varying numbers
                                 of args.
* Null Pointer Constant::       The macro `NULL'.
* Important Data Types::        Data types for object sizes.
* Data Type Measurements::      Parameters of data type representations.

Variadic Functions

* Why Variadic::                Reasons for making functions take
                                 variable arguments.
* How Variadic::                How to define and call variadic functions.
* Variadic Example::            A complete example.

How Variadic

* Variadic Prototypes::  How to make a prototype for a function
			  with variable arguments.
* Receiving Arguments::  Steps you must follow to access the
			  optional argument values.
* How Many Arguments::   How to decide whether there are more arguments.
* Calling Variadics::    Things you need to know about calling
			  variable arguments functions.
* Argument Macros::      Detailed specification of the macros
        		  for accessing variable arguments.

Data Type Measurements

* Width of Type::           How many bits does an integer type hold?
* Range of Type::           What are the largest and smallest values
			     that an integer type can hold?
* Floating Type Macros::    Parameters that measure the floating point types.
* Structure Measurement::   Getting measurements on structure types.

Floating Type Macros

* Floating Point Concepts::     Definitions of terminology.
* Floating Point Parameters::   Details of specific macros.
* IEEE Floating Point::         The measurements for one common
                                 representation.

Installation

* Configuring and compiling::   How to compile and test GNU libc.
* Running make install::        How to install it once you've got it
 compiled.
* Tools for Compilation::       You'll need these first.
* Linux::                       Specific advice for GNU/Linux systems.
* Reporting Bugs::              So they'll get fixed.

Maintenance

* Source Layout::         How to add new functions or header files
                             to the GNU C Library.
* Symbol handling::       How to handle symbols in the GNU C Library.
* Porting::               How to port the GNU C Library to
                             a new machine or operating system.

Source Layout

* Platform: Adding Platform-specific.             Adding platform-specific
                                         features.

Symbol handling

* 64-bit time symbol handling :: How to handle 64-bit time related
                                    symbols in the GNU C Library.

Porting

* Hierarchy Conventions::       The layout of the `sysdeps' hierarchy.
* Porting to Unix::             Porting the library to an average
                                   Unix-like system.

Platform

* PowerPC::           Facilities Specific to the PowerPC Architecture
* RISC-V::            Facilities Specific to the RISC-V Architecture


File: libc.info,  Node: Introduction,  Next: Error Reporting,  Prev: Top,  Up: Top

1 Introduction
**************

The C language provides no built-in facilities for performing such
common operations as input/output, memory management, string
manipulation, and the like.  Instead, these facilities are defined in a
standard "library", which you compile and link with your programs.  

   The GNU C Library, described in this document, defines all of the
library functions that are specified by the ISO C standard, as well as
additional features specific to POSIX and other derivatives of the Unix
operating system, and extensions specific to GNU systems.

   The purpose of this manual is to tell you how to use the facilities
of the GNU C Library.  We have mentioned which features belong to which
standards to help you identify things that are potentially non-portable
to other systems.  But the emphasis in this manual is not on strict
portability.

* Menu:

* Getting Started::             What this manual is for and how to use it.
* Standards and Portability::   Standards and sources upon which the GNU
                                 C library is based.
* Using the Library::           Some practical uses for the library.
* Roadmap to the Manual::       Overview of the remaining chapters in
                                 this manual.


File: libc.info,  Node: Getting Started,  Next: Standards and Portability,  Up: Introduction

1.1 Getting Started
===================

This manual is written with the assumption that you are at least
somewhat familiar with the C programming language and basic programming
concepts.  Specifically, familiarity with ISO standard C (*note ISO
C::), rather than "traditional" pre-ISO C dialects, is assumed.

   The GNU C Library includes several "header files", each of which
provides definitions and declarations for a group of related facilities;
this information is used by the C compiler when processing your program.
For example, the header file `stdio.h' declares facilities for
performing input and output, and the header file `string.h' declares
string processing utilities.  The organization of this manual generally
follows the same division as the header files.

   If you are reading this manual for the first time, you should read
all of the introductory material and skim the remaining chapters.
There are a _lot_ of functions in the GNU C Library and it's not
realistic to expect that you will be able to remember exactly _how_ to
use each and every one of them.  It's more important to become
generally familiar with the kinds of facilities that the library
provides, so that when you are writing your programs you can recognize
_when_ to make use of library functions, and _where_ in this manual you
can find more specific information about them.


File: libc.info,  Node: Standards and Portability,  Next: Using the Library,  Prev: Getting Started,  Up: Introduction

1.2 Standards and Portability
=============================

This section discusses the various standards and other sources that the
GNU C Library is based upon.  These sources include the ISO C and POSIX
standards, and the System V and Berkeley Unix implementations.

   The primary focus of this manual is to tell you how to make effective
use of the GNU C Library facilities.  But if you are concerned about
making your programs compatible with these standards, or portable to
operating systems other than GNU, this can affect how you use the
library.  This section gives you an overview of these standards, so that
you will know what they are when they are mentioned in other parts of
the manual.

   *Note Library Summary::, for an alphabetical list of the functions
and other symbols provided by the library.  This list also states which
standards each function or symbol comes from.

* Menu:

* ISO C::                       The international standard for the C
                                 programming language.
* POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
                                 for operating systems.
* Berkeley Unix::               BSD and SunOS.
* SVID::                        The System V Interface Description.
* XPG::                         The X/Open Portability Guide.


File: libc.info,  Node: ISO C,  Next: POSIX,  Up: Standards and Portability

1.2.1 ISO C
-----------

The GNU C Library is compatible with the C standard adopted by the
American National Standards Institute (ANSI): `American National
Standard X3.159-1989--"ANSI C"' and later by the International
Standardization Organization (ISO): `ISO/IEC 9899:1990, "Programming
languages--C"'.  We here refer to the standard as ISO C since this is
the more general standard in respect of ratification.  The header files
and library facilities that make up the GNU C Library are a superset of
those specified by the ISO C standard.

   If you are concerned about strict adherence to the ISO C standard,
you should use the `-ansi' option when you compile your programs with
the GNU C compiler.  This tells the compiler to define _only_ ISO
standard features from the library header files, unless you explicitly
ask for additional features.  *Note Feature Test Macros::, for
information on how to do this.

   Being able to restrict the library to include only ISO C features is
important because ISO C puts limitations on what names can be defined
by the library implementation, and the GNU extensions don't fit these
limitations.  *Note Reserved Names::, for more information about these
restrictions.

   This manual does not attempt to give you complete details on the
differences between ISO C and older dialects.  It gives advice on how
to write programs to work portably under multiple C dialects, but does
not aim for completeness.


File: libc.info,  Node: POSIX,  Next: Berkeley Unix,  Prev: ISO C,  Up: Standards and Portability

1.2.2 POSIX (The Portable Operating System Interface)
-----------------------------------------------------

The GNU C Library is also compatible with the ISO "POSIX" family of
standards, known more formally as the "Portable Operating System
Interface for Computer Environments" (ISO/IEC 9945).  They were also
published as ANSI/IEEE Std 1003.  POSIX is derived mostly from various
versions of the Unix operating system.

   The library facilities specified by the POSIX standards are a
superset of those required by ISO C; POSIX specifies additional
features for ISO C functions, as well as specifying new additional
functions.  In general, the additional requirements and functionality
defined by the POSIX standards are aimed at providing lower-level
support for a particular kind of operating system environment, rather
than general programming language support which can run in many diverse
operating system environments.

   The GNU C Library implements all of the functions specified in
`ISO/IEC 9945-1:1996, the POSIX System Application Program Interface',
commonly referred to as POSIX.1.  The primary extensions to the ISO C
facilities specified by this standard include file system interface
primitives (*note File System Interface::), device-specific terminal
control functions (*note Low-Level Terminal Interface::), and process
control functions (*note Processes::).

   Some facilities from `ISO/IEC 9945-2:1993, the POSIX Shell and
Utilities standard' (POSIX.2) are also implemented in the GNU C Library.
These include utilities for dealing with regular expressions and other
pattern matching facilities (*note Pattern Matching::).

* Menu:

* POSIX Safety Concepts::       Safety concepts from POSIX.
* Unsafe Features::             Features that make functions unsafe.
* Conditionally Safe Features:: Features that make functions unsafe
                                 in the absence of workarounds.
* Other Safety Remarks::        Additional safety features and remarks.


File: libc.info,  Node: POSIX Safety Concepts,  Next: Unsafe Features,  Up: POSIX

1.2.2.1 POSIX Safety Concepts
.............................

This manual documents various safety properties of GNU C Library
functions, in lines that follow their prototypes and look like:

Preliminary: | MT-Safe | AS-Safe | AC-Safe |

   The properties are assessed according to the criteria set forth in
the POSIX standard for such safety contexts as Thread-, Async-Signal-
and Async-Cancel- -Safety.  Intuitive definitions of these properties,
attempting to capture the meaning of the standard definitions, follow.

   * `MT-Safe' or Thread-Safe functions are safe to call in the presence
     of other threads.  MT, in MT-Safe, stands for Multi Thread.

     Being MT-Safe does not imply a function is atomic, nor that it
     uses any of the memory synchronization mechanisms POSIX exposes to
     users.  It is even possible that calling MT-Safe functions in
     sequence does not yield an MT-Safe combination.  For example,
     having a thread call two MT-Safe functions one right after the
     other does not guarantee behavior equivalent to atomic execution
     of a combination of both functions, since concurrent calls in
     other threads may interfere in a destructive way.

     Whole-program optimizations that could inline functions across
     library interfaces may expose unsafe reordering, and so performing
     inlining across the GNU C Library interface is not recommended.
     The documented MT-Safety status is not guaranteed under
     whole-program optimization.  However, functions defined in
     user-visible headers are designed to be safe for inlining.

   * `AS-Safe' or Async-Signal-Safe functions are safe to call from
     asynchronous signal handlers.  AS, in AS-Safe, stands for
     Asynchronous Signal.

     Many functions that are AS-Safe may set `errno', or modify the
     floating-point environment, because their doing so does not make
     them unsuitable for use in signal handlers.  However, programs
     could misbehave should asynchronous signal handlers modify this
     thread-local state, and the signal handling machinery cannot be
     counted on to preserve it.  Therefore, signal handlers that call
     functions that may set `errno' or modify the floating-point
     environment _must_ save their original values, and restore them
     before returning.

   * `AC-Safe' or Async-Cancel-Safe functions are safe to call when
     asynchronous cancellation is enabled.  AC in AC-Safe stands for
     Asynchronous Cancellation.

     The POSIX standard defines only three functions to be AC-Safe,
     namely `pthread_cancel', `pthread_setcancelstate', and
     `pthread_setcanceltype'.  At present the GNU C Library provides no
     guarantees beyond these three functions, but does document which
     functions are presently AC-Safe.  This documentation is provided
     for use by the GNU C Library developers.

     Just like signal handlers, cancellation cleanup routines must
     configure the floating point environment they require.  The
     routines cannot assume a floating point environment, particularly
     when asynchronous cancellation is enabled.  If the configuration
     of the floating point environment cannot be performed atomically
     then it is also possible that the environment encountered is
     internally inconsistent.

   * `MT-Unsafe', `AS-Unsafe', `AC-Unsafe' functions are not safe to
     call within the safety contexts described above.  Calling them
     within such contexts invokes undefined behavior.

     Functions not explicitly documented as safe in a safety context
     should be regarded as Unsafe.

   * `Preliminary' safety properties are documented, indicating these
     properties may _not_ be counted on in future releases of the GNU C
     Library.

     Such preliminary properties are the result of an assessment of the
     properties of our current implementation, rather than of what is
     mandated and permitted by current and future standards.

     Although we strive to abide by the standards, in some cases our
     implementation is safe even when the standard does not demand
     safety, and in other cases our implementation does not meet the
     standard safety requirements.  The latter are most likely bugs;
     the former, when marked as `Preliminary', should not be counted
     on: future standards may require changes that are not compatible
     with the additional safety properties afforded by the current
     implementation.

     Furthermore, the POSIX standard does not offer a detailed
     definition of safety.  We assume that, by "safe to call", POSIX
     means that, as long as the program does not invoke undefined
     behavior, the "safe to call" function behaves as specified, and
     does not cause other functions to deviate from their specified
     behavior.  We have chosen to use its loose definitions of safety,
     not because they are the best definitions to use, but because
     choosing them harmonizes this manual with POSIX.

     Please keep in mind that these are preliminary definitions and
     annotations, and certain aspects of the definitions are still under
     discussion and might be subject to clarification or change.

     Over time, we envision evolving the preliminary safety notes into
     stable commitments, as stable as those of our interfaces.  As we
     do, we will remove the `Preliminary' keyword from safety notes.
     As long as the keyword remains, however, they are not to be
     regarded as a promise of future behavior.


   Other keywords that appear in safety notes are defined in subsequent
sections.


File: libc.info,  Node: Unsafe Features,  Next: Conditionally Safe Features,  Prev: POSIX Safety Concepts,  Up: POSIX

1.2.2.2 Unsafe Features
.......................

Functions that are unsafe to call in certain contexts are annotated with
keywords that document their features that make them unsafe to call.
AS-Unsafe features in this section indicate the functions are never safe
to call when asynchronous signals are enabled.  AC-Unsafe features
indicate they are never safe to call when asynchronous cancellation is
enabled.  There are no MT-Unsafe marks in this section.

   * `lock' 

     Functions marked with `lock' as an AS-Unsafe feature may be
     interrupted by a signal while holding a non-recursive lock.  If the
     signal handler calls another such function that takes the same
     lock, the result is a deadlock.

     Functions annotated with `lock' as an AC-Unsafe feature may, if
     cancelled asynchronously, fail to release a lock that would have
     been released if their execution had not been interrupted by
     asynchronous thread cancellation.  Once a lock is left taken,
     attempts to take that lock will block indefinitely.

   * `corrupt' 

     Functions marked with `corrupt' as an AS-Unsafe feature may corrupt
     data structures and misbehave when they interrupt, or are
     interrupted by, another such function.  Unlike functions marked
     with `lock', these take recursive locks to avoid MT-Safety
     problems, but this is not enough to stop a signal handler from
     observing a partially-updated data structure.  Further corruption
     may arise from the interrupted function's failure to notice
     updates made by signal handlers.

     Functions marked with `corrupt' as an AC-Unsafe feature may leave
     data structures in a corrupt, partially updated state.  Subsequent
     uses of the data structure may misbehave.

   * `heap' 

     Functions marked with `heap' may call heap memory management
     functions from the `malloc'/`free' family of functions and are
     only as safe as those functions.  This note is thus equivalent to:

     | AS-Unsafe lock | AC-Unsafe lock fd mem |

   * `dlopen' 

     Functions marked with `dlopen' use the dynamic loader to load
     shared libraries into the current execution image.  This involves
     opening files, mapping them into memory, allocating additional
     memory, resolving symbols, applying relocations and more, all of
     this while holding internal dynamic loader locks.

     The locks are enough for these functions to be AS- and AC-Unsafe,
     but other issues may arise.  At present this is a placeholder for
     all potential safety issues raised by `dlopen'.

   * `plugin' 

     Functions annotated with `plugin' may run code from plugins that
     may be external to the GNU C Library.  Such plugin functions are
     assumed to be MT-Safe, AS-Unsafe and AC-Unsafe.  Examples of such
     plugins are stack unwinding libraries, name service switch (NSS)
     and character set conversion (iconv) back-ends.

     Although the plugins mentioned as examples are all brought in by
     means of dlopen, the `plugin' keyword does not imply any direct
     involvement of the dynamic loader or the `libdl' interfaces, those
     are covered by `dlopen'.  For example, if one function loads a
     module and finds the addresses of some of its functions, while
     another just calls those already-resolved functions, the former
     will be marked with `dlopen', whereas the latter will get the
     `plugin'.  When a single function takes all of these actions, then
     it gets both marks.

   * `i18n' 

     Functions marked with `i18n' may call internationalization
     functions of the `gettext' family and will be only as safe as those
     functions.  This note is thus equivalent to:

     | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt |

   * `timer' 

     Functions marked with `timer' use the `alarm' function or similar
     to set a time-out for a system call or a long-running operation.
     In a multi-threaded program, there is a risk that the time-out
     signal will be delivered to a different thread, thus failing to
     interrupt the intended thread.  Besides being MT-Unsafe, such
     functions are always AS-Unsafe, because calling them in signal
     handlers may interfere with timers set in the interrupted code,
     and AC-Unsafe, because there is no safe way to guarantee an
     earlier timer will be reset in case of asynchronous cancellation.



File: libc.info,  Node: Conditionally Safe Features,  Next: Other Safety Remarks,  Prev: Unsafe Features,  Up: POSIX

1.2.2.3 Conditionally Safe Features
...................................

For some features that make functions unsafe to call in certain
contexts, there are known ways to avoid the safety problem other than
refraining from calling the function altogether.  The keywords that
follow refer to such features, and each of their definitions indicate
how the whole program needs to be constrained in order to remove the
safety problem indicated by the keyword.  Only when all the reasons that
make a function unsafe are observed and addressed, by applying the
documented constraints, does the function become safe to call in a
context.

   * `init' 

     Functions marked with `init' as an MT-Unsafe feature perform
     MT-Unsafe initialization when they are first called.

     Calling such a function at least once in single-threaded mode
     removes this specific cause for the function to be regarded as
     MT-Unsafe.  If no other cause for that remains, the function can
     then be safely called after other threads are started.

     Functions marked with `init' as an AS- or AC-Unsafe feature use the
     internal `libc_once' machinery or similar to initialize internal
     data structures.

     If a signal handler interrupts such an initializer, and calls any
     function that also performs `libc_once' initialization, it will
     deadlock if the thread library has been loaded.

     Furthermore, if an initializer is partially complete before it is
     canceled or interrupted by a signal whose handler requires the same
     initialization, some or all of the initialization may be performed
     more than once, leaking resources or even resulting in corrupt
     internal data.

     Applications that need to call functions marked with `init' as an
     AS- or AC-Unsafe feature should ensure the initialization is
     performed before configuring signal handlers or enabling
     cancellation, so that the AS- and AC-Safety issues related with
     `libc_once' do not arise.

   * `race' 

     Functions annotated with `race' as an MT-Safety issue operate on
     objects in ways that may cause data races or similar forms of
     destructive interference out of concurrent execution.  In some
     cases, the objects are passed to the functions by users; in
     others, they are used by the functions to return values to users;
     in others, they are not even exposed to users.

     We consider access to objects passed as (indirect) arguments to
     functions to be data race free.  The assurance of data race free
     objects is the caller's responsibility.  We will not mark a
     function as MT-Unsafe or AS-Unsafe if it misbehaves when users
     fail to take the measures required by POSIX to avoid data races
     when dealing with such objects.  As a general rule, if a function
     is documented as reading from an object passed (by reference) to
     it, or modifying it, users ought to use memory synchronization
     primitives to avoid data races just as they would should they
     perform the accesses themselves rather than by calling the library
     function.  `FILE' streams are the exception to the general rule,
     in that POSIX mandates the library to guard against data races in
     many functions that manipulate objects of this specific opaque
     type.  We regard this as a convenience provided to users, rather
     than as a general requirement whose expectations should extend to
     other types.

     In order to remind users that guarding certain arguments is their
     responsibility, we will annotate functions that take objects of
     certain types as arguments.  We draw the line for objects passed
     by users as follows: objects whose types are exposed to users, and
     that users are expected to access directly, such as memory
     buffers, strings, and various user-visible `struct' types, do
     _not_ give reason for functions to be annotated with `race'.  It
     would be noisy and redundant with the general requirement, and not
     many would be surprised by the library's lack of internal guards
     when accessing objects that can be accessed directly by users.

     As for objects that are opaque or opaque-like, in that they are to
     be manipulated only by passing them to library functions (e.g.,
     `FILE', `DIR', `obstack', `iconv_t'), there might be additional
     expectations as to internal coordination of access by the library.
     We will annotate, with `race' followed by a colon and the
     argument name, functions that take such objects but that do not
     take care of synchronizing access to them by default.  For example,
     `FILE' stream `unlocked' functions will be annotated, but those
     that perform implicit locking on `FILE' streams by default will
     not, even though the implicit locking may be disabled on a
     per-stream basis.

     In either case, we will not regard as MT-Unsafe functions that may
     access user-supplied objects in unsafe ways should users fail to
     ensure the accesses are well defined.  The notion prevails that
     users are expected to safeguard against data races any
     user-supplied objects that the library accesses on their behalf.

     This user responsibility does not apply, however, to objects
     controlled by the library itself, such as internal objects and
     static buffers used to return values from certain calls.  When the
     library doesn't guard them against concurrent uses, these cases
     are regarded as MT-Unsafe and AS-Unsafe (although the `race' mark
     under AS-Unsafe will be omitted as redundant with the one under
     MT-Unsafe).  As in the case of user-exposed objects, the mark may
     be followed by a colon and an identifier.  The identifier groups
     all functions that operate on a certain unguarded object; users
     may avoid the MT-Safety issues related with unguarded concurrent
     access to such internal objects by creating a non-recursive mutex
     related with the identifier, and always holding the mutex when
     calling any function marked as racy on that identifier, as they
     would have to should the identifier be an object under user
     control.  The non-recursive mutex avoids the MT-Safety issue, but
     it trades one AS-Safety issue for another, so use in asynchronous
     signals remains undefined.

     When the identifier relates to a static buffer used to hold return
     values, the mutex must be held for as long as the buffer remains
     in use by the caller.  Many functions that return pointers to
     static buffers offer reentrant variants that store return values
     in caller-supplied buffers instead.  In some cases, such as
     `tmpname', the variant is chosen not by calling an alternate entry
     point, but by passing a non-`NULL' pointer to the buffer in which
     the returned values are to be stored.  These variants are
     generally preferable in multi-threaded programs, although some of
     them are not MT-Safe because of other internal buffers, also
     documented with `race' notes.

   * `const' 

     Functions marked with `const' as an MT-Safety issue non-atomically
     modify internal objects that are better regarded as constant,
     because a substantial portion of the GNU C Library accesses them
     without synchronization.  Unlike `race', that causes both readers
     and writers of internal objects to be regarded as MT-Unsafe and
     AS-Unsafe, this mark is applied to writers only.  Writers remain
     equally MT- and AS-Unsafe to call, but the then-mandatory
     constness of objects they modify enables readers to be regarded as
     MT-Safe and AS-Safe (as long as no other reasons for them to be
     unsafe remain), since the lack of synchronization is not a problem
     when the objects are effectively constant.

     The identifier that follows the `const' mark will appear by itself
     as a safety note in readers.  Programs that wish to work around
     this safety issue, so as to call writers, may use a non-recursve
     `rwlock' associated with the identifier, and guard _all_ calls to
     functions marked with `const' followed by the identifier with a
     write lock, and _all_ calls to functions marked with the identifier
     by itself with a read lock.  The non-recursive locking removes the
     MT-Safety problem, but it trades one AS-Safety problem for
     another, so use in asynchronous signals remains undefined.

   * `sig' 

     Functions marked with `sig' as a MT-Safety issue (that implies an
     identical AS-Safety issue, omitted for brevity) may temporarily
     install a signal handler for internal purposes, which may
     interfere with other uses of the signal, identified after a colon.

     This safety problem can be worked around by ensuring that no other
     uses of the signal will take place for the duration of the call.
     Holding a non-recursive mutex while calling all functions that use
     the same temporary signal; blocking that signal before the call
     and resetting its handler afterwards is recommended.

     There is no safe way to guarantee the original signal handler is
     restored in case of asynchronous cancellation, therefore so-marked
     functions are also AC-Unsafe.

     Besides the measures recommended to work around the MT- and
     AS-Safety problem, in order to avert the cancellation problem,
     disabling asynchronous cancellation _and_ installing a cleanup
     handler to restore the signal to the desired state and to release
     the mutex are recommended.

   * `term' 

     Functions marked with `term' as an MT-Safety issue may change the
     terminal settings in the recommended way, namely: call `tcgetattr',
     modify some flags, and then call `tcsetattr'; this creates a window
     in which changes made by other threads are lost.  Thus, functions
     marked with `term' are MT-Unsafe.  The same window enables changes
     made by asynchronous signals to be lost.  These functions are also
     AS-Unsafe, but the corresponding mark is omitted as redundant.

     It is thus advisable for applications using the terminal to avoid
     concurrent and reentrant interactions with it, by not using it in
     signal handlers or blocking signals that might use it, and holding
     a lock while calling these functions and interacting with the
     terminal.  This lock should also be used for mutual exclusion with
     functions marked with `race:tcattr(fd)', where FD is a file
     descriptor for the controlling terminal.  The caller may use a
     single mutex for simplicity, or use one mutex per terminal, even
     if referenced by different file descriptors.

     Functions marked with `term' as an AC-Safety issue are supposed to
     restore terminal settings to their original state, after
     temporarily changing them, but they may fail to do so if cancelled.

     Besides the measures recommended to work around the MT- and
     AS-Safety problem, in order to avert the cancellation problem,
     disabling asynchronous cancellation _and_ installing a cleanup
     handler to restore the terminal settings to the original state and
     to release the mutex are recommended.



File: libc.info,  Node: Other Safety Remarks,  Prev: Conditionally Safe Features,  Up: POSIX

1.2.2.4 Other Safety Remarks
............................

Additional keywords may be attached to functions, indicating features
that do not make a function unsafe to call, but that may need to be
taken into account in certain classes of programs:

   * `locale' 

     Functions annotated with `locale' as an MT-Safety issue read from
     the locale object without any form of synchronization.  Functions
     annotated with `locale' called concurrently with locale changes may
     behave in ways that do not correspond to any of the locales active
     during their execution, but an unpredictable mix thereof.

     We do not mark these functions as MT- or AS-Unsafe, however,
     because functions that modify the locale object are marked with
     `const:locale' and regarded as unsafe.  Being unsafe, the latter
     are not to be called when multiple threads are running or
     asynchronous signals are enabled, and so the locale can be
     considered effectively constant in these contexts, which makes the
     former safe.

   * `env' 

     Functions marked with `env' as an MT-Safety issue access the
     environment with `getenv' or similar, without any guards to ensure
     safety in the presence of concurrent modifications.

     We do not mark these functions as MT- or AS-Unsafe, however,
     because functions that modify the environment are all marked with
     `const:env' and regarded as unsafe.  Being unsafe, the latter are
     not to be called when multiple threads are running or asynchronous
     signals are enabled, and so the environment can be considered
     effectively constant in these contexts, which makes the former
     safe.

   * `hostid' 

     The function marked with `hostid' as an MT-Safety issue reads from
     the system-wide data structures that hold the "host ID" of the
     machine.  These data structures cannot generally be modified
     atomically.  Since it is expected that the "host ID" will not
     normally change, the function that reads from it (`gethostid') is
     regarded as safe, whereas the function that modifies it
     (`sethostid') is marked with `const:hostid', indicating it may
     require special care if it is to be called.  In this specific
     case, the special care amounts to system-wide (not merely
     intra-process) coordination.

   * `sigintr' 

     Functions marked with `sigintr' as an MT-Safety issue access the
     `_sigintr' internal data structure without any guards to ensure
     safety in the presence of concurrent modifications.

     We do not mark these functions as MT- or AS-Unsafe, however,
     because functions that modify the this data structure are all
     marked with `const:sigintr' and regarded as unsafe.  Being unsafe,
     the latter are not to be called when multiple threads are running
     or asynchronous signals are enabled, and so the data structure can
     be considered effectively constant in these contexts, which makes
     the former safe.

   * `fd' 

     Functions annotated with `fd' as an AC-Safety issue may leak file
     descriptors if asynchronous thread cancellation interrupts their
     execution.

     Functions that allocate or deallocate file descriptors will
     generally be marked as such.  Even if they attempted to protect
     the file descriptor allocation and deallocation with cleanup
     regions, allocating a new descriptor and storing its number where
     the cleanup region could release it cannot be performed as a
     single atomic operation.  Similarly, releasing the descriptor and
     taking it out of the data structure normally responsible for
     releasing it cannot be performed atomically.  There will always be
     a window in which the descriptor cannot be released because it was
     not stored in the cleanup handler argument yet, or it was already
     taken out before releasing it.  It cannot be taken out after
     release: an open descriptor could mean either that the descriptor
     still has to be closed, or that it already did so but the
     descriptor was reallocated by another thread or signal handler.

     Such leaks could be internally avoided, with some performance
     penalty, by temporarily disabling asynchronous thread
     cancellation.  However, since callers of allocation or
     deallocation functions would have to do this themselves, to avoid
     the same sort of leak in their own layer, it makes more sense for
     the library to assume they are taking care of it than to impose a
     performance penalty that is redundant when the problem is solved
     in upper layers, and insufficient when it is not.

     This remark by itself does not cause a function to be regarded as
     AC-Unsafe.  However, cumulative effects of such leaks may pose a
     problem for some programs.  If this is the case, suspending
     asynchronous cancellation for the duration of calls to such
     functions is recommended.

   * `mem' 

     Functions annotated with `mem' as an AC-Safety issue may leak
     memory if asynchronous thread cancellation interrupts their
     execution.

     The problem is similar to that of file descriptors: there is no
     atomic interface to allocate memory and store its address in the
     argument to a cleanup handler, or to release it and remove its
     address from that argument, without at least temporarily disabling
     asynchronous cancellation, which these functions do not do.

     This remark does not by itself cause a function to be regarded as
     generally AC-Unsafe.  However, cumulative effects of such leaks
     may be severe enough for some programs that disabling asynchronous
     cancellation for the duration of calls to such functions may be
     required.

   * `cwd' 

     Functions marked with `cwd' as an MT-Safety issue may temporarily
     change the current working directory during their execution, which
     may cause relative pathnames to be resolved in unexpected ways in
     other threads or within asynchronous signal or cancellation
     handlers.

     This is not enough of a reason to mark so-marked functions as MT-
     or AS-Unsafe, but when this behavior is optional (e.g., `nftw' with
     `FTW_CHDIR'), avoiding the option may be a good alternative to
     using full pathnames or file descriptor-relative (e.g. `openat')
     system calls.

   * `!posix' 

     This remark, as an MT-, AS- or AC-Safety note to a function,
     indicates the safety status of the function is known to differ
     from the specified status in the POSIX standard.  For example,
     POSIX does not require a function to be Safe, but our
     implementation is, or vice-versa.

     For the time being, the absence of this remark does not imply the
     safety properties we documented are identical to those mandated by
     POSIX for the corresponding functions.

   * `:identifier' 

     Annotations may sometimes be followed by identifiers, intended to
     group several functions that e.g. access the data structures in an
     unsafe way, as in `race' and `const', or to provide more specific
     information, such as naming a signal in a function marked with
     `sig'.  It is envisioned that it may be applied to `lock' and
     `corrupt' as well in the future.

     In most cases, the identifier will name a set of functions, but it
     may name global objects or function arguments, or identifiable
     properties or logical components associated with them, with a
     notation such as e.g. `:buf(arg)' to denote a buffer associated
     with the argument ARG, or `:tcattr(fd)' to denote the terminal
     attributes of a file descriptor FD.

     The most common use for identifiers is to provide logical groups of
     functions and arguments that need to be protected by the same
     synchronization primitive in order to ensure safe operation in a
     given context.

   * `/condition' 

     Some safety annotations may be conditional, in that they only
     apply if a boolean expression involving arguments, global
     variables or even the underlying kernel evaluates to true.  Such
     conditions as `/hurd' or `/!linux!bsd' indicate the preceding
     marker only applies when the underlying kernel is the HURD, or
     when it is neither Linux nor a BSD kernel, respectively.  `/!ps'
     and `/one_per_line' indicate the preceding marker only applies when
     argument PS is NULL, or global variable ONE_PER_LINE is nonzero.

     When all marks that render a function unsafe are adorned with such
     conditions, and none of the named conditions hold, then the
     function can be regarded as safe.



File: libc.info,  Node: Berkeley Unix,  Next: SVID,  Prev: POSIX,  Up: Standards and Portability

1.2.3 Berkeley Unix
-------------------

The GNU C Library defines facilities from some versions of Unix which
are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD,
and 4.4 BSD Unix systems (also known as "Berkeley Unix") and from
"SunOS" (a popular 4.2 BSD derivative that includes some Unix System V
functionality).  These systems support most of the ISO C and POSIX
facilities, and 4.4 BSD and newer releases of SunOS in fact support
them all.

   The BSD facilities include symbolic links (*note Symbolic Links::),
the `select' function (*note Waiting for I/O::), the BSD signal
functions (*note BSD Signal Handling::), and sockets (*note Sockets::).


File: libc.info,  Node: SVID,  Next: XPG,  Prev: Berkeley Unix,  Up: Standards and Portability

1.2.4 SVID (The System V Interface Description)
-----------------------------------------------

The "System V Interface Description" (SVID) is a document describing
the AT&T Unix System V operating system.  It is to some extent a
superset of the POSIX standard (*note POSIX::).

   The GNU C Library defines most of the facilities required by the SVID
that are not also required by the ISO C or POSIX standards, for
compatibility with  System V Unix and other Unix systems (such as
SunOS) which include these facilities.  However, many of the more
obscure and less generally useful facilities required by the SVID are
not included.  (In fact, Unix System V itself does not provide them
all.)

   The supported facilities from System V include the methods for
inter-process communication and shared memory, the `hsearch' and
`drand48' families of functions, `fmtmsg' and several of the
mathematical functions.


File: libc.info,  Node: XPG,  Prev: SVID,  Up: Standards and Portability

1.2.5 XPG (The X/Open Portability Guide)
----------------------------------------

The X/Open Portability Guide, published by the X/Open Company, Ltd., is
a more general standard than POSIX.  X/Open owns the Unix copyright and
the XPG specifies the requirements for systems which are intended to be
a Unix system.

   The GNU C Library complies to the X/Open Portability Guide, Issue
4.2, with all extensions common to XSI (X/Open System Interface)
compliant systems and also all X/Open UNIX extensions.

   The additions on top of POSIX are mainly derived from functionality
available in System V and BSD systems.  Some of the really bad mistakes
in System V systems were corrected, though.  Since fulfilling the XPG
standard with the Unix extensions is a precondition for getting the
Unix brand chances are good that the functionality is available on
commercial systems.


File: libc.info,  Node: Using the Library,  Next: Roadmap to the Manual,  Prev: Standards and Portability,  Up: Introduction

1.3 Using the Library
=====================

This section describes some of the practical issues involved in using
the GNU C Library.

* Menu:

* Header Files::                How to include the header files in your
                                 programs.
* Macro Definitions::           Some functions in the library may really
                                 be implemented as macros.
* Reserved Names::              The C standard reserves some names for
                                 the library, and some for users.
* Feature Test Macros::         How to control what names are defined.


File: libc.info,  Node: Header Files,  Next: Macro Definitions,  Up: Using the Library

1.3.1 Header Files
------------------

Libraries for use by C programs really consist of two parts: "header
files" that define types and macros and declare variables and
functions; and the actual library or "archive" that contains the
definitions of the variables and functions.

   (Recall that in C, a "declaration" merely provides information that
a function or variable exists and gives its type.  For a function
declaration, information about the types of its arguments might be
provided as well.  The purpose of declarations is to allow the compiler
to correctly process references to the declared variables and functions.
A "definition", on the other hand, actually allocates storage for a
variable or says what a function does.)  

   In order to use the facilities in the GNU C Library, you should be
sure that your program source files include the appropriate header
files.  This is so that the compiler has declarations of these
facilities available and can correctly process references to them.
Once your program has been compiled, the linker resolves these
references to the actual definitions provided in the archive file.

   Header files are included into a program source file by the
`#include' preprocessor directive.  The C language supports two forms
of this directive; the first,

     #include "HEADER"

is typically used to include a header file HEADER that you write
yourself; this would contain definitions and declarations describing the
interfaces between the different parts of your particular application.
By contrast,

     #include <file.h>

is typically used to include a header file `file.h' that contains
definitions and declarations for a standard library.  This file would
normally be installed in a standard place by your system administrator.
You should use this second form for the C library header files.

   Typically, `#include' directives are placed at the top of the C
source file, before any other code.  If you begin your source files with
some comments explaining what the code in the file does (a good idea),
put the `#include' directives immediately afterwards, following the
feature test macro definition (*note Feature Test Macros::).

   For more information about the use of header files and `#include'
directives, *note Header Files: (cpp.info)Header Files.

   The GNU C Library provides several header files, each of which
contains the type and macro definitions and variable and function
declarations for a group of related facilities.  This means that your
programs may need to include several header files, depending on exactly
which facilities you are using.

   Some library header files include other library header files
automatically.  However, as a matter of programming style, you should
not rely on this; it is better to explicitly include all the header
files required for the library facilities you are using.  The GNU C
Library header files have been written in such a way that it doesn't
matter if a header file is accidentally included more than once;
including a header file a second time has no effect.  Likewise, if your
program needs to include multiple header files, the order in which they
are included doesn't matter.

   *Compatibility Note:* Inclusion of standard header files in any
order and any number of times works in any ISO C implementation.
However, this has traditionally not been the case in many older C
implementations.

   Strictly speaking, you don't _have to_ include a header file to use
a function it declares; you could declare the function explicitly
yourself, according to the specifications in this manual.  But it is
usually better to include the header file because it may define types
and macros that are not otherwise available and because it may define
more efficient macro replacements for some functions.  It is also a sure
way to have the correct declaration.


File: libc.info,  Node: Macro Definitions,  Next: Reserved Names,  Prev: Header Files,  Up: Using the Library

1.3.2 Macro Definitions of Functions
------------------------------------

If we describe something as a function in this manual, it may have a
macro definition as well.  This normally has no effect on how your
program runs--the macro definition does the same thing as the function
would.  In particular, macro equivalents for library functions evaluate
arguments exactly once, in the same way that a function call would.  The
main reason for these macro definitions is that sometimes they can
produce an inline expansion that is considerably faster than an actual
function call.

   Taking the address of a library function works even if it is also
defined as a macro.  This is because, in this context, the name of the
function isn't followed by the left parenthesis that is syntactically
necessary to recognize a macro call.

   You might occasionally want to avoid using the macro definition of a
function--perhaps to make your program easier to debug.  There are two
ways you can do this:

   * You can avoid a macro definition in a specific use by enclosing
     the name of the function in parentheses.  This works because the
     name of the function doesn't appear in a syntactic context where
     it is recognizable as a macro call.

   * You can suppress any macro definition for a whole source file by
     using the `#undef' preprocessor directive, unless otherwise stated
     explicitly in the description of that facility.

   For example, suppose the header file `stdlib.h' declares a function
named `abs' with

     extern int abs (int);

and also provides a macro definition for `abs'.  Then, in:

     #include <stdlib.h>
     int f (int *i) { return abs (++*i); }

the reference to `abs' might refer to either a macro or a function.  On
the other hand, in each of the following examples the reference is to a
function and not a macro.

     #include <stdlib.h>
     int g (int *i) { return (abs) (++*i); }

     #undef abs
     int h (int *i) { return abs (++*i); }

   Since macro definitions that double for a function behave in exactly
the same way as the actual function version, there is usually no need
for any of these methods.  In fact, removing macro definitions usually
just makes your program slower.


File: libc.info,  Node: Reserved Names,  Next: Feature Test Macros,  Prev: Macro Definitions,  Up: Using the Library

1.3.3 Reserved Names
--------------------

The names of all library types, macros, variables and functions that
come from the ISO C standard are reserved unconditionally; your program
*may not* redefine these names.  All other library names are reserved
if your program explicitly includes the header file that defines or
declares them.  There are several reasons for these restrictions:

   * Other people reading your code could get very confused if you were
     using a function named `exit' to do something completely different
     from what the standard `exit' function does, for example.
     Preventing this situation helps to make your programs easier to
     understand and contributes to modularity and maintainability.

   * It avoids the possibility of a user accidentally redefining a
     library function that is called by other library functions.  If
     redefinition were allowed, those other functions would not work
     properly.

   * It allows the compiler to do whatever special optimizations it
     pleases on calls to these functions, without the possibility that
     they may have been redefined by the user.  Some library
     facilities, such as those for dealing with variadic arguments
     (*note Variadic Functions::) and non-local exits (*note Non-Local
     Exits::), actually require a considerable amount of cooperation on
     the part of the C compiler, and with respect to the
     implementation, it might be easier for the compiler to treat these
     as built-in parts of the language.

   In addition to the names documented in this manual, reserved names
include all external identifiers (global functions and variables) that
begin with an underscore (`_') and all identifiers regardless of use
that begin with either two underscores or an underscore followed by a
capital letter are reserved names.  This is so that the library and
header files can define functions, variables, and macros for internal
purposes without risk of conflict with names in user programs.

   Some additional classes of identifier names are reserved for future
extensions to the C language or the POSIX.1 environment.  While using
these names for your own purposes right now might not cause a problem,
they do raise the possibility of conflict with future versions of the C
or POSIX standards, so you should avoid these names.

   * Names beginning with a capital `E' followed a digit or uppercase
     letter may be used for additional error code names.  *Note Error
     Reporting::.

   * Names that begin with either `is' or `to' followed by a lowercase
     letter may be used for additional character testing and conversion
     functions.  *Note Character Handling::.

   * Names that begin with `LC_' followed by an uppercase letter may be
     used for additional macros specifying locale attributes.  *Note
     Locales::.

   * Names of all existing mathematics functions (*note Mathematics::)
     suffixed with `f' or `l' are reserved for corresponding functions
     that operate on `float' and `long double' arguments, respectively.

   * Names that begin with `SIG' followed by an uppercase letter are
     reserved for additional signal names.  *Note Standard Signals::.

   * Names that begin with `SIG_' followed by an uppercase letter are
     reserved for additional signal actions.  *Note Basic Signal
     Handling::.

   * Names beginning with `str', `mem', or `wcs' followed by a
     lowercase letter are reserved for additional string and array
     functions.  *Note String and Array Utilities::.

   * Names that end with `_t' are reserved for additional type names.

   In addition, some individual header files reserve names beyond those
that they actually define.  You only need to worry about these
restrictions if your program includes that particular header file.

   * The header file `dirent.h' reserves names prefixed with `d_'.  

   * The header file `fcntl.h' reserves names prefixed with `l_', `F_',
     `O_', and `S_'.  

   * The header file `grp.h' reserves names prefixed with `gr_'.  

   * The header file `limits.h' reserves names suffixed with `_MAX'.  

   * The header file `pwd.h' reserves names prefixed with `pw_'.  

   * The header file `signal.h' reserves names prefixed with `sa_' and
     `SA_'.  

   * The header file `sys/stat.h' reserves names prefixed with `st_'
     and `S_'.  

   * The header file `sys/times.h' reserves names prefixed with `tms_'.  

   * The header file `termios.h' reserves names prefixed with `c_',
     `V', `I', `O', and `TC'; and names prefixed with `B' followed by a
     digit.  


File: libc.info,  Node: Feature Test Macros,  Prev: Reserved Names,  Up: Using the Library

1.3.4 Feature Test Macros
-------------------------

The exact set of features available when you compile a source file is
controlled by which "feature test macros" you define.

   If you compile your programs using `gcc -ansi', you get only the
ISO C library features, unless you explicitly request additional
features by defining one or more of the feature macros.  *Note GNU CC
Command Options: (gcc)Invoking GCC, for more information about GCC
options.

   You should define these macros by using `#define' preprocessor
directives at the top of your source code files.  These directives
_must_ come before any `#include' of a system header file.  It is best
to make them the very first thing in the file, preceded only by
comments.  You could also use the `-D' option to GCC, but it's better
if you make the source files indicate their own meaning in a
self-contained way.

   This system exists to allow the library to conform to multiple
standards.  Although the different standards are often described as
supersets of each other, they are usually incompatible because larger
standards require functions with names that smaller ones reserve to the
user program.  This is not mere pedantry -- it has been a problem in
practice.  For instance, some non-GNU programs define functions named
`getline' that have nothing to do with this library's `getline'.  They
would not be compilable if all features were enabled indiscriminately.

   This should not be used to verify that a program conforms to a
limited standard.  It is insufficient for this purpose, as it will not
protect you from including header files outside the standard, or
relying on semantics undefined within the standard.

 -- Macro: _POSIX_SOURCE
     If you define this macro, then the functionality from the POSIX.1
     standard (IEEE Standard 1003.1) is available, as well as all of the
     ISO C facilities.

     The state of `_POSIX_SOURCE' is irrelevant if you define the macro
     `_POSIX_C_SOURCE' to a positive integer.

 -- Macro: _POSIX_C_SOURCE
     Define this macro to a positive integer to control which POSIX
     functionality is made available.  The greater the value of this
     macro, the more functionality is made available.

     If you define this macro to a value greater than or equal to `1',
     then the functionality from the 1990 edition of the POSIX.1
     standard (IEEE Standard 1003.1-1990) is made available.

     If you define this macro to a value greater than or equal to `2',
     then the functionality from the 1992 edition of the POSIX.2
     standard (IEEE Standard 1003.2-1992) is made available.

     If you define this macro to a value greater than or equal to
     `199309L', then the functionality from the 1993 edition of the
     POSIX.1b standard (IEEE Standard 1003.1b-1993) is made available.

     If you define this macro to a value greater than or equal to
     `199506L', then the functionality from the 1995 edition of the
     POSIX.1c standard (IEEE Standard 1003.1c-1995) is made available.

     If you define this macro to a value greater than or equal to
     `200112L', then the functionality from the 2001 edition of the
     POSIX standard (IEEE Standard 1003.1-2001) is made available.

     If you define this macro to a value greater than or equal to
     `200809L', then the functionality from the 2008 edition of the
     POSIX standard (IEEE Standard 1003.1-2008) is made available.

     Greater values for `_POSIX_C_SOURCE' will enable future extensions.
     The POSIX standards process will define these values as necessary,
     and the GNU C Library should support them some time after they
     become standardized.  The 1996 edition of POSIX.1 (ISO/IEC 9945-1:
     1996) states that if you define `_POSIX_C_SOURCE' to a value
     greater than or equal to `199506L', then the functionality from
     the 1996 edition is made available.  In general, in the GNU C
     Library, bugfixes to the standards are included when specifying
     the base version; e.g., POSIX.1-2004 will always be included with
     a value of `200112L'.

 -- Macro: _XOPEN_SOURCE
 -- Macro: _XOPEN_SOURCE_EXTENDED
     If you define this macro, functionality described in the X/Open
     Portability Guide is included.  This is a superset of the POSIX.1
     and POSIX.2 functionality and in fact `_POSIX_SOURCE' and
     `_POSIX_C_SOURCE' are automatically defined.

     As the unification of all Unices, functionality only available in
     BSD and SVID is also included.

     If the macro `_XOPEN_SOURCE_EXTENDED' is also defined, even more
     functionality is available.  The extra functions will make all
     functions available which are necessary for the X/Open Unix brand.

     If the macro `_XOPEN_SOURCE' has the value 500 this includes all
     functionality described so far plus some new definitions from the
     Single Unix Specification, version 2.  The value 600
     (corresponding to the sixth revision) includes definitions from
     SUSv3, and using 700 (the seventh revision) includes definitions
     from SUSv4.

 -- Macro: _LARGEFILE_SOURCE
     If this macro is defined some extra functions are available which
     rectify a few shortcomings in all previous standards.
     Specifically, the functions `fseeko' and `ftello' are available.
     Without these functions the difference between the ISO C interface
     (`fseek', `ftell') and the low-level POSIX interface (`lseek')
     would lead to problems.

     This macro was introduced as part of the Large File Support
     extension (LFS).

 -- Macro: _LARGEFILE64_SOURCE
     If you define this macro an additional set of functions is made
     available which enables 32 bit systems to use files of sizes beyond
     the usual limit of 2GB.  This interface is not available if the
     system does not support files that large.  On systems where the
     natural file size limit is greater than 2GB (i.e., on 64 bit
     systems) the new functions are identical to the replaced functions.

     The new functionality is made available by a new set of types and
     functions which replace the existing ones.  The names of these new
     objects contain `64' to indicate the intention, e.g., `off_t' vs.
     `off64_t' and `fseeko' vs. `fseeko64'.

     This macro was introduced as part of the Large File Support
     extension (LFS).  It is a transition interface for the period when
     64 bit offsets are not generally used (see `_FILE_OFFSET_BITS').

 -- Macro: _FILE_OFFSET_BITS
     This macro determines which file system interface shall be used,
     one replacing the other.  Whereas `_LARGEFILE64_SOURCE' makes the
     64 bit interface available as an additional interface,
     `_FILE_OFFSET_BITS' allows the 64 bit interface to replace the old
     interface.

     If `_FILE_OFFSET_BITS' is undefined, or if it is defined to the
     value `32', nothing changes.  The 32 bit interface is used and
     types like `off_t' have a size of 32 bits on 32 bit systems.

     If the macro is defined to the value `64', the large file interface
     replaces the old interface.  I.e., the functions are not made
     available under different names (as they are with
     `_LARGEFILE64_SOURCE').  Instead the old function names now
     reference the new functions, e.g., a call to `fseeko' now indeed
     calls `fseeko64'.

     This macro should only be selected if the system provides
     mechanisms for handling large files.  On 64 bit systems this macro
     has no effect since the `*64' functions are identical to the
     normal functions.

     This macro was introduced as part of the Large File Support
     extension (LFS).

 -- Macro: _ISOC99_SOURCE
     If this macro is defined, features from ISO C99 are included.
     Since these features are included by default, this macro is mostly
     relevant when the compiler uses an earlier language version.

 -- Macro: _ISOC11_SOURCE
     If this macro is defined, ISO C11 extensions to ISO C99 are
     included.

 -- Macro: __STDC_WANT_LIB_EXT2__
     If you define this macro to the value `1', features from ISO/IEC
     TR 24731-2:2010 (Dynamic Allocation Functions) are enabled.  Only
     some of the features from this TR are supported by the GNU C
     Library.

 -- Macro: __STDC_WANT_IEC_60559_BFP_EXT__
     If you define this macro, features from ISO/IEC TS 18661-1:2014
     (Floating-point extensions for C: Binary floating-point arithmetic)
     are enabled.  Only some of the features from this TS are supported
     by the GNU C Library.

 -- Macro: __STDC_WANT_IEC_60559_FUNCS_EXT__
     If you define this macro, features from ISO/IEC TS 18661-4:2015
     (Floating-point extensions for C: Supplementary functions) are
     enabled.  Only some of the features from this TS are supported by
     the GNU C Library.

 -- Macro: __STDC_WANT_IEC_60559_TYPES_EXT__
     If you define this macro, features from ISO/IEC TS 18661-3:2015
     (Floating-point extensions for C: Interchange and extended types)
     are enabled.  Only some of the features from this TS are supported
     by the GNU C Library.

 -- Macro: _GNU_SOURCE
     If you define this macro, everything is included: ISO C89,
     ISO C99, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU
     extensions.  In the cases where POSIX.1 conflicts with BSD, the
     POSIX definitions take precedence.

 -- Macro: _DEFAULT_SOURCE
     If you define this macro, most features are included apart from
     X/Open, LFS and GNU extensions: the effect is to enable features
     from the 2008 edition of POSIX, as well as certain BSD and SVID
     features without a separate feature test macro to control them.

     Be aware that compiler options also affect included features:

        * If you use a strict conformance option, features beyond those
          from the compiler's language version will be disabled, though
          feature test macros may be used to enable them.

        * Features enabled by compiler options are not overridden by
          feature test macros.

 -- Macro: _ATFILE_SOURCE
     If this macro is defined, additional `*at' interfaces are included.

 -- Macro: _FORTIFY_SOURCE
     If this macro is defined to 1, security hardening is added to
     various library functions.  If defined to 2, even stricter checks
     are applied.

 -- Macro: _REENTRANT
 -- Macro: _THREAD_SAFE
     These macros are obsolete.  They have the same effect as defining
     `_POSIX_C_SOURCE' with the value `199506L'.

     Some very old C libraries required one of these macros to be
     defined for basic functionality (e.g. `getchar') to be thread-safe.

   We recommend you use `_GNU_SOURCE' in new programs.  If you don't
specify the `-ansi' option to GCC, or other conformance options such as
`-std=c99', and don't define any of these macros explicitly, the effect
is the same as defining `_DEFAULT_SOURCE' to 1.

   When you define a feature test macro to request a larger class of
features, it is harmless to define in addition a feature test macro for
a subset of those features.  For example, if you define
`_POSIX_C_SOURCE', then defining `_POSIX_SOURCE' as well has no effect.
Likewise, if you define `_GNU_SOURCE', then defining either
`_POSIX_SOURCE' or `_POSIX_C_SOURCE' as well has no effect.


File: libc.info,  Node: Roadmap to the Manual,  Prev: Using the Library,  Up: Introduction

1.4 Roadmap to the Manual
=========================

Here is an overview of the contents of the remaining chapters of this
manual.

   * *Note Error Reporting::, describes how errors detected by the
     library are reported.

   * *Note Memory::, describes the GNU C Library's facilities for
     managing and using virtual and real memory, including dynamic
     allocation of virtual memory.  If you do not know in advance how
     much memory your program needs, you can allocate it dynamically
     instead, and manipulate it via pointers.

   * *Note Character Handling::, contains information about character
     classification functions (such as `isspace') and functions for
     performing case conversion.

   * *Note String and Array Utilities::, has descriptions of functions
     for manipulating strings (null-terminated character arrays) and
     general byte arrays, including operations such as copying and
     comparison.

   * *Note Character Set Handling::, contains information about
     manipulating characters and strings using character sets larger
     than will fit in the usual `char' data type.

   * *Note Locales::, describes how selecting a particular country or
     language affects the behavior of the library.  For example, the
     locale affects collation sequences for strings and how monetary
     values are formatted.

   * *Note Searching and Sorting::, contains information about functions
     for searching and sorting arrays.  You can use these functions on
     any kind of array by providing an appropriate comparison function.

   * *Note Pattern Matching::, presents functions for matching regular
     expressions and shell file name patterns, and for expanding words
     as the shell does.

   * *Note I/O Overview::, gives an overall look at the input and output
     facilities in the library, and contains information about basic
     concepts such as file names.

   * *Note I/O on Streams::, describes I/O operations involving streams
     (or `FILE *' objects).  These are the normal C library functions
     from `stdio.h'.

   * *Note Low-Level I/O::, contains information about I/O operations
     on file descriptors.  File descriptors are a lower-level mechanism
     specific to the Unix family of operating systems.

   * *Note File System Interface::, has descriptions of operations on
     entire files, such as functions for deleting and renaming them and
     for creating new directories.  This chapter also contains
     information about how you can access the attributes of a file,
     such as its owner and file protection modes.

   * *Note Pipes and FIFOs::, contains information about simple
     interprocess communication mechanisms.  Pipes allow communication
     between two related processes (such as between a parent and
     child), while FIFOs allow communication between processes sharing
     a common file system on the same machine.

   * *Note Sockets::, describes a more complicated interprocess
     communication mechanism that allows processes running on different
     machines to communicate over a network.  This chapter also
     contains information about Internet host addressing and how to use
     the system network databases.

   * *Note Low-Level Terminal Interface::, describes how you can change
     the attributes of a terminal device.  If you want to disable echo
     of characters typed by the user, for example, read this chapter.

   * *Note Mathematics::, contains information about the math library
     functions.  These include things like random-number generators and
     remainder functions on integers as well as the usual trigonometric
     and exponential functions on floating-point numbers.

   * *Note Low-Level Arithmetic Functions: Arithmetic, describes
     functions for simple arithmetic, analysis of floating-point
     values, and reading numbers from strings.

   * *Note Date and Time::, describes functions for measuring both
     calendar time and CPU time, as well as functions for setting
     alarms and timers.

   * *Note Non-Local Exits::, contains descriptions of the `setjmp' and
     `longjmp' functions.  These functions provide a facility for
     `goto'-like jumps which can jump from one function to another.

   * *Note Signal Handling::, tells you all about signals--what they
     are, how to establish a handler that is called when a particular
     kind of signal is delivered, and how to prevent signals from
     arriving during critical sections of your program.

   * *Note Program Basics::, tells how your programs can access their
     command-line arguments and environment variables.

   * *Note Processes::, contains information about how to start new
     processes and run programs.

   * *Note Job Control::, describes functions for manipulating process
     groups and the controlling terminal.  This material is probably
     only of interest if you are writing a shell or other program which
     handles job control specially.

   * *Note Name Service Switch::, describes the services which are
     available for looking up names in the system databases, how to
     determine which service is used for which database, and how these
     services are implemented so that contributors can design their own
     services.

   * *Note User Database::, and *Note Group Database::, tell you how to
     access the system user and group databases.

   * *Note System Management::, describes functions for controlling and
     getting information about the hardware and software configuration
     your program is executing under.

   * *Note System Configuration::, tells you how you can get
     information about various operating system limits.  Most of these
     parameters are provided for compatibility with POSIX.

   * *Note Language Features::, contains information about library
     support for standard parts of the C language, including things
     like the `sizeof' operator and the symbolic constant `NULL', how
     to write functions accepting variable numbers of arguments, and
     constants describing the ranges and other properties of the
     numerical types.  There is also a simple debugging mechanism which
     allows you to put assertions in your code, and have diagnostic
     messages printed if the tests fail.

   * *Note Library Summary::, gives a summary of all the functions,
     variables, and macros in the library, with complete data types and
     function prototypes, and says what standard or system each is
     derived from.

   * *Note Installation::, explains how to build and install the GNU C
     Library on your system, and how to report any bugs you might find.

   * *Note Maintenance::, explains how to add new functions or port the
     library to a new system.

   If you already know the name of the facility you are interested in,
you can look it up in *Note Library Summary::.  This gives you a
summary of its syntax and a pointer to where you can find a more
detailed description.  This appendix is particularly useful if you just
want to verify the order and type of arguments to a function, for
example.  It also tells you what standard or system each function,
variable, or macro is derived from.


File: libc.info,  Node: Error Reporting,  Next: Memory,  Prev: Introduction,  Up: Top

2 Error Reporting
*****************

Many functions in the GNU C Library detect and report error conditions,
and sometimes your programs need to check for these error conditions.
For example, when you open an input file, you should verify that the
file was actually opened correctly, and print an error message or take
other appropriate action if the call to the library function failed.

   This chapter describes how the error reporting facility works.  Your
program should include the header file `errno.h' to use this facility.  

* Menu:

* Checking for Errors::         How errors are reported by library functions.
* Error Codes::                 Error code macros; all of these expand
                                 into integer constant values.
* Error Messages::              Mapping error codes onto error messages.


File: libc.info,  Node: Checking for Errors,  Next: Error Codes,  Up: Error Reporting

2.1 Checking for Errors
=======================

Most library functions return a special value to indicate that they have
failed.  The special value is typically `-1', a null pointer, or a
constant such as `EOF' that is defined for that purpose.  But this
return value tells you only that an error has occurred.  To find out
what kind of error it was, you need to look at the error code stored in
the variable `errno'.  This variable is declared in the header file
`errno.h'.  

 -- Variable: volatile int errno
     The variable `errno' contains the system error number.  You can
     change the value of `errno'.

     Since `errno' is declared `volatile', it might be changed
     asynchronously by a signal handler; see *Note Defining Handlers::.
     However, a properly written signal handler saves and restores the
     value of `errno', so you generally do not need to worry about this
     possibility except when writing signal handlers.

     The initial value of `errno' at program startup is zero.  In many
     cases, when a library function encounters an error, it will set
     `errno' to a non-zero value to indicate what specific error
     condition occurred.  The documentation for each function lists the
     error conditions that are possible for that function.  Not all
     library functions use this mechanism; some return an error code
     directly, instead.

     *Warning:* Many library functions may set `errno' to some
     meaningless non-zero value even if they did not encounter any
     errors, and even if they return error codes directly.  Therefore,
     it is usually incorrect to check _whether_ an error occurred by
     inspecting the value of `errno'.  The proper way to check for
     error is documented for each function.

     *Portability Note:* ISO C specifies `errno' as a "modifiable
     lvalue" rather than as a variable, permitting it to be implemented
     as a macro.  For example, its expansion might involve a function
     call, like `*__errno_location ()'.  In fact, that is what it is on
     GNU/Linux and GNU/Hurd systems.  The GNU C Library, on each
     system, does whatever is right for the particular system.

     There are a few library functions, like `sqrt' and `atan', that
     return a perfectly legitimate value in case of an error, but also
     set `errno'.  For these functions, if you want to check to see
     whether an error occurred, the recommended method is to set `errno'
     to zero before calling the function, and then check its value
     afterward.

   All the error codes have symbolic names; they are macros defined in
`errno.h'.  The names start with `E' and an upper-case letter or digit;
you should consider names of this form to be reserved names.  *Note
Reserved Names::.

   The error code values are all positive integers and are all distinct,
with one exception: `EWOULDBLOCK' and `EAGAIN' are the same.  Since the
values are distinct, you can use them as labels in a `switch'
statement; just don't use both `EWOULDBLOCK' and `EAGAIN'.  Your
program should not make any other assumptions about the specific values
of these symbolic constants.

   The value of `errno' doesn't necessarily have to correspond to any
of these macros, since some library functions might return other error
codes of their own for other situations.  The only values that are
guaranteed to be meaningful for a particular library function are the
ones that this manual lists for that function.

   Except on GNU/Hurd systems, almost any system call can return
`EFAULT' if it is given an invalid pointer as an argument.  Since this
could only happen as a result of a bug in your program, and since it
will not happen on GNU/Hurd systems, we have saved space by not
mentioning `EFAULT' in the descriptions of individual functions.

   In some Unix systems, many system calls can also return `EFAULT' if
given as an argument a pointer into the stack, and the kernel for some
obscure reason fails in its attempt to extend the stack.  If this ever
happens, you should probably try using statically or dynamically
allocated memory instead of stack memory on that system.


File: libc.info,  Node: Error Codes,  Next: Error Messages,  Prev: Checking for Errors,  Up: Error Reporting

2.2 Error Codes
===============

The error code macros are defined in the header file `errno.h'.  All of
them expand into integer constant values.  Some of these error codes
can't occur on GNU systems, but they can occur using the GNU C Library
on other systems.

 -- Macro: int EPERM
     "Operation not permitted."  Only the owner of the file (or other
     resource) or processes with special privileges can perform the
     operation.

 -- Macro: int ENOENT
     "No such file or directory."  This is a "file doesn't exist" error
     for ordinary files that are referenced in contexts where they are
     expected to already exist.

 -- Macro: int ESRCH
     "No such process."  No process matches the specified process ID.

 -- Macro: int EINTR
     "Interrupted system call."  An asynchronous signal occurred and
     prevented completion of the call.  When this happens, you should
     try the call again.

     You can choose to have functions resume after a signal that is
     handled, rather than failing with `EINTR'; see *Note Interrupted
     Primitives::.

 -- Macro: int EIO
     "Input/output error."  Usually used for physical read or write
     errors.

 -- Macro: int ENXIO
     "No such device or address."  The system tried to use the device
     represented by a file you specified, and it couldn't find the
     device.  This can mean that the device file was installed
     incorrectly, or that the physical device is missing or not
     correctly attached to the computer.

 -- Macro: int E2BIG
     "Argument list too long."  Used when the arguments passed to a new
     program being executed with one of the `exec' functions (*note
     Executing a File::) occupy too much memory space.  This condition
     never arises on GNU/Hurd systems.

 -- Macro: int ENOEXEC
     "Exec format error."  Invalid executable file format.  This
     condition is detected by the `exec' functions; see *Note Executing
     a File::.

 -- Macro: int EBADF
     "Bad file descriptor."  For example, I/O on a descriptor that has
     been closed or reading from a descriptor open only for writing (or
     vice versa).

 -- Macro: int ECHILD
     "No child processes."  This error happens on operations that are
     supposed to manipulate child processes, when there aren't any
     processes to manipulate.

 -- Macro: int EDEADLK
     "Resource deadlock avoided."  Allocating a system resource would
     have resulted in a deadlock situation.  The system does not
     guarantee that it will notice all such situations.  This error
     means you got lucky and the system noticed; it might just hang.
     *Note File Locks::, for an example.

 -- Macro: int ENOMEM
     "Cannot allocate memory."  The system cannot allocate more virtual
     memory because its capacity is full.

 -- Macro: int EACCES
     "Permission denied."  The file permissions do not allow the
     attempted operation.

 -- Macro: int EFAULT
     "Bad address."  An invalid pointer was detected.  On GNU/Hurd
     systems, this error never happens; you get a signal instead.

 -- Macro: int ENOTBLK
     "Block device required."  A file that isn't a block special file
     was given in a situation that requires one.  For example, trying
     to mount an ordinary file as a file system in Unix gives this
     error.

 -- Macro: int EBUSY
     "Device or resource busy."  A system resource that can't be shared
     is already in use.  For example, if you try to delete a file that
     is the root of a currently mounted filesystem, you get this error.

 -- Macro: int EEXIST
     "File exists."  An existing file was specified in a context where
     it only makes sense to specify a new file.

 -- Macro: int EXDEV
     "Invalid cross-device link."  An attempt to make an improper link
     across file systems was detected.  This happens not only when you
     use `link' (*note Hard Links::) but also when you rename a file
     with `rename' (*note Renaming Files::).

 -- Macro: int ENODEV
     "No such device."  The wrong type of device was given to a
     function that expects a particular sort of device.

 -- Macro: int ENOTDIR
     "Not a directory."  A file that isn't a directory was specified
     when a directory is required.

 -- Macro: int EISDIR
     "Is a directory."  You cannot open a directory for writing, or
     create or remove hard links to it.

 -- Macro: int EINVAL
     "Invalid argument."  This is used to indicate various kinds of
     problems with passing the wrong argument to a library function.

 -- Macro: int EMFILE
     "Too many open files."  The current process has too many files
     open and can't open any more.  Duplicate descriptors do count
     toward this limit.

     In BSD and GNU, the number of open files is controlled by a
     resource limit that can usually be increased.  If you get this
     error, you might want to increase the `RLIMIT_NOFILE' limit or
     make it unlimited; *note Limits on Resources::.

 -- Macro: int ENFILE
     "Too many open files in system."  There are too many distinct file
     openings in the entire system.  Note that any number of linked
     channels count as just one file opening; see *Note Linked
     Channels::.  This error never occurs on GNU/Hurd systems.

 -- Macro: int ENOTTY
     "Inappropriate ioctl for device."  Inappropriate I/O control
     operation, such as trying to set terminal modes on an ordinary
     file.

 -- Macro: int ETXTBSY
     "Text file busy."  An attempt to execute a file that is currently
     open for writing, or write to a file that is currently being
     executed.  Often using a debugger to run a program is considered
     having it open for writing and will cause this error.  (The name
     stands for "text file busy".)  This is not an error on GNU/Hurd
     systems; the text is copied as necessary.

 -- Macro: int EFBIG
     "File too large."  The size of a file would be larger than allowed
     by the system.

 -- Macro: int ENOSPC
     "No space left on device."  Write operation on a file failed
     because the disk is full.

 -- Macro: int ESPIPE
     "Illegal seek."  Invalid seek operation (such as on a pipe).

 -- Macro: int EROFS
     "Read-only file system."  An attempt was made to modify something
     on a read-only file system.

 -- Macro: int EMLINK
     "Too many links."  The link count of a single file would become
     too large.  `rename' can cause this error if the file being
     renamed already has as many links as it can take (*note Renaming
     Files::).

 -- Macro: int EPIPE
     "Broken pipe."  There is no process reading from the other end of
     a pipe.  Every library function that returns this error code also
     generates a `SIGPIPE' signal; this signal terminates the program
     if not handled or blocked.  Thus, your program will never actually
     see `EPIPE' unless it has handled or blocked `SIGPIPE'.

 -- Macro: int EDOM
     "Numerical argument out of domain."  Used by mathematical
     functions when an argument value does not fall into the domain
     over which the function is defined.

 -- Macro: int ERANGE
     "Numerical result out of range."  Used by mathematical functions
     when the result value is not representable because of overflow or
     underflow.

 -- Macro: int EAGAIN
     "Resource temporarily unavailable."  The call might work if you
     try again later.  The macro `EWOULDBLOCK' is another name for
     `EAGAIN'; they are always the same in the GNU C Library.

     This error can happen in a few different situations:

        * An operation that would block was attempted on an object that
          has non-blocking mode selected.  Trying the same operation
          again will block until some external condition makes it
          possible to read, write, or connect (whatever the operation).
          You can use `select' to find out when the operation will be
          possible; *note Waiting for I/O::.

          *Portability Note:* In many older Unix systems, this condition
          was indicated by `EWOULDBLOCK', which was a distinct error
          code different from `EAGAIN'.  To make your program portable,
          you should check for both codes and treat them the same.

        * A temporary resource shortage made an operation impossible.
          `fork' can return this error.  It indicates that the shortage
          is expected to pass, so your program can try the call again
          later and it may succeed.  It is probably a good idea to
          delay for a few seconds before trying it again, to allow time
          for other processes to release scarce resources.  Such
          shortages are usually fairly serious and affect the whole
          system, so usually an interactive program should report the
          error to the user and return to its command loop.

 -- Macro: int EWOULDBLOCK
     "Operation would block."  In the GNU C Library, this is another
     name for `EAGAIN' (above).  The values are always the same, on
     every operating system.

     C libraries in many older Unix systems have `EWOULDBLOCK' as a
     separate error code.

 -- Macro: int EINPROGRESS
     "Operation now in progress."  An operation that cannot complete
     immediately was initiated on an object that has non-blocking mode
     selected.  Some functions that must always block (such as
     `connect'; *note Connecting::) never return `EAGAIN'.  Instead,
     they return `EINPROGRESS' to indicate that the operation has begun
     and will take some time.  Attempts to manipulate the object before
     the call completes return `EALREADY'.  You can use the `select'
     function to find out when the pending operation has completed;
     *note Waiting for I/O::.

 -- Macro: int EALREADY
     "Operation already in progress."  An operation is already in
     progress on an object that has non-blocking mode selected.

 -- Macro: int ENOTSOCK
     "Socket operation on non-socket."  A file that isn't a socket was
     specified when a socket is required.

 -- Macro: int EMSGSIZE
     "Message too long."  The size of a message sent on a socket was
     larger than the supported maximum size.

 -- Macro: int EPROTOTYPE
     "Protocol wrong type for socket."  The socket type does not
     support the requested communications protocol.

 -- Macro: int ENOPROTOOPT
     "Protocol not available."  You specified a socket option that
     doesn't make sense for the particular protocol being used by the
     socket.  *Note Socket Options::.

 -- Macro: int EPROTONOSUPPORT
     "Protocol not supported."  The socket domain does not support the
     requested communications protocol (perhaps because the requested
     protocol is completely invalid).  *Note Creating a Socket::.

 -- Macro: int ESOCKTNOSUPPORT
     "Socket type not supported."  The socket type is not supported.

 -- Macro: int EOPNOTSUPP
     "Operation not supported."  The operation you requested is not
     supported.  Some socket functions don't make sense for all types
     of sockets, and others may not be implemented for all
     communications protocols.  On GNU/Hurd systems, this error can
     happen for many calls when the object does not support the
     particular operation; it is a generic indication that the server
     knows nothing to do for that call.

 -- Macro: int EPFNOSUPPORT
     "Protocol family not supported."  The socket communications
     protocol family you requested is not supported.

 -- Macro: int EAFNOSUPPORT
     "Address family not supported by protocol."  The address family
     specified for a socket is not supported; it is inconsistent with
     the protocol being used on the socket.  *Note Sockets::.

 -- Macro: int EADDRINUSE
     "Address already in use."  The requested socket address is already
     in use.  *Note Socket Addresses::.

 -- Macro: int EADDRNOTAVAIL
     "Cannot assign requested address."  The requested socket address
     is not available; for example, you tried to give a socket a name
     that doesn't match the local host name.  *Note Socket Addresses::.

 -- Macro: int ENETDOWN
     "Network is down."  A socket operation failed because the network
     was down.

 -- Macro: int ENETUNREACH
     "Network is unreachable."  A socket operation failed because the
     subnet containing the remote host was unreachable.

 -- Macro: int ENETRESET
     "Network dropped connection on reset."  A network connection was
     reset because the remote host crashed.

 -- Macro: int ECONNABORTED
     "Software caused connection abort."  A network connection was
     aborted locally.

 -- Macro: int ECONNRESET
     "Connection reset by peer."  A network connection was closed for
     reasons outside the control of the local host, such as by the
     remote machine rebooting or an unrecoverable protocol violation.

 -- Macro: int ENOBUFS
     "No buffer space available."  The kernel's buffers for I/O
     operations are all in use.  In GNU, this error is always
     synonymous with `ENOMEM'; you may get one or the other from
     network operations.

 -- Macro: int EISCONN
     "Transport endpoint is already connected."  You tried to connect a
     socket that is already connected.  *Note Connecting::.

 -- Macro: int ENOTCONN
     "Transport endpoint is not connected."  The socket is not
     connected to anything.  You get this error when you try to
     transmit data over a socket, without first specifying a
     destination for the data.  For a connectionless socket (for
     datagram protocols, such as UDP), you get `EDESTADDRREQ' instead.

 -- Macro: int EDESTADDRREQ
     "Destination address required."  No default destination address
     was set for the socket.  You get this error when you try to
     transmit data over a connectionless socket, without first
     specifying a destination for the data with `connect'.

 -- Macro: int ESHUTDOWN
     "Cannot send after transport endpoint shutdown."  The socket has
     already been shut down.

 -- Macro: int ETOOMANYREFS
     "Too many references: cannot splice."

 -- Macro: int ETIMEDOUT
     "Connection timed out."  A socket operation with a specified
     timeout received no response during the timeout period.

 -- Macro: int ECONNREFUSED
     "Connection refused."  A remote host refused to allow the network
     connection (typically because it is not running the requested
     service).

 -- Macro: int ELOOP
     "Too many levels of symbolic links."  Too many levels of symbolic
     links were encountered in looking up a file name.  This often
     indicates a cycle of symbolic links.

 -- Macro: int ENAMETOOLONG
     "File name too long."  Filename too long (longer than `PATH_MAX';
     *note Limits for Files::) or host name too long (in `gethostname'
     or `sethostname'; *note Host Identification::).

 -- Macro: int EHOSTDOWN
     "Host is down."  The remote host for a requested network
     connection is down.

 -- Macro: int EHOSTUNREACH
     "No route to host."  The remote host for a requested network
     connection is not reachable.

 -- Macro: int ENOTEMPTY
     "Directory not empty."  Directory not empty, where an empty
     directory was expected.  Typically, this error occurs when you are
     trying to delete a directory.

 -- Macro: int EPROCLIM
     "Too many processes."  This means that the per-user limit on new
     process would be exceeded by an attempted `fork'.  *Note Limits on
     Resources::, for details on the `RLIMIT_NPROC' limit.

 -- Macro: int EUSERS
     "Too many users."  The file quota system is confused because there
     are too many users.

 -- Macro: int EDQUOT
     "Disk quota exceeded."  The user's disk quota was exceeded.

 -- Macro: int ESTALE
     "Stale file handle."  This indicates an internal confusion in the
     file system which is due to file system rearrangements on the
     server host for NFS file systems or corruption in other file
     systems.  Repairing this condition usually requires unmounting,
     possibly repairing and remounting the file system.

 -- Macro: int EREMOTE
     "Object is remote."  An attempt was made to NFS-mount a remote
     file system with a file name that already specifies an NFS-mounted
     file.  (This is an error on some operating systems, but we expect
     it to work properly on GNU/Hurd systems, making this error code
     impossible.)

 -- Macro: int EBADRPC
     "RPC struct is bad."

 -- Macro: int ERPCMISMATCH
     "RPC version wrong."

 -- Macro: int EPROGUNAVAIL
     "RPC program not available."

 -- Macro: int EPROGMISMATCH
     "RPC program version wrong."

 -- Macro: int EPROCUNAVAIL
     "RPC bad procedure for program."

 -- Macro: int ENOLCK
     "No locks available."  This is used by the file locking
     facilities; see *Note File Locks::.  This error is never generated
     by GNU/Hurd systems, but it can result from an operation to an NFS
     server running another operating system.

 -- Macro: int EFTYPE
     "Inappropriate file type or format."  The file was the wrong type
     for the operation, or a data file had the wrong format.

     On some systems `chmod' returns this error if you try to set the
     sticky bit on a non-directory file; *note Setting Permissions::.

 -- Macro: int EAUTH
     "Authentication error."

 -- Macro: int ENEEDAUTH
     "Need authenticator."

 -- Macro: int ENOSYS
     "Function not implemented."  This indicates that the function
     called is not implemented at all, either in the C library itself
     or in the operating system.  When you get this error, you can be
     sure that this particular function will always fail with `ENOSYS'
     unless you install a new version of the C library or the operating
     system.

 -- Macro: int ENOTSUP
     "Not supported."  A function returns this error when certain
     parameter values are valid, but the functionality they request is
     not available.  This can mean that the function does not implement
     a particular command or option value or flag bit at all.  For
     functions that operate on some object given in a parameter, such
     as a file descriptor or a port, it might instead mean that only
     _that specific object_ (file descriptor, port, etc.) is unable to
     support the other parameters given; different file descriptors
     might support different ranges of parameter values.

     If the entire function is not available at all in the
     implementation, it returns `ENOSYS' instead.

 -- Macro: int EILSEQ
     "Invalid or incomplete multibyte or wide character."  While
     decoding a multibyte character the function came along an invalid
     or an incomplete sequence of bytes or the given wide character is
     invalid.

 -- Macro: int EBACKGROUND
     "Inappropriate operation for background process."  On GNU/Hurd
     systems, servers supporting the `term' protocol return this error
     for certain operations when the caller is not in the foreground
     process group of the terminal.  Users do not usually see this
     error because functions such as `read' and `write' translate it
     into a `SIGTTIN' or `SIGTTOU' signal.  *Note Job Control::, for
     information on process groups and these signals.

 -- Macro: int EDIED
     "Translator died."  On GNU/Hurd systems, opening a file returns
     this error when the file is translated by a program and the
     translator program dies while starting up, before it has connected
     to the file.

 -- Macro: int ED
     "?."  The experienced user will know what is wrong.

 -- Macro: int EGREGIOUS
     "You really blew it this time."  You did *what*?

 -- Macro: int EIEIO
     "Computer bought the farm."  Go home and have a glass of warm,
     dairy-fresh milk.

 -- Macro: int EGRATUITOUS
     "Gratuitous error."  This error code has no purpose.

 -- Macro: int EBADMSG
     "Bad message."

 -- Macro: int EIDRM
     "Identifier removed."

 -- Macro: int EMULTIHOP
     "Multihop attempted."

 -- Macro: int ENODATA
     "No data available."

 -- Macro: int ENOLINK
     "Link has been severed."

 -- Macro: int ENOMSG
     "No message of desired type."

 -- Macro: int ENOSR
     "Out of streams resources."

 -- Macro: int ENOSTR
     "Device not a stream."

 -- Macro: int EOVERFLOW
     "Value too large for defined data type."

 -- Macro: int EPROTO
     "Protocol error."

 -- Macro: int ETIME
     "Timer expired."

 -- Macro: int ECANCELED
     "Operation canceled."  An asynchronous operation was canceled
     before it completed.  *Note Asynchronous I/O::.  When you call
     `aio_cancel', the normal result is for the operations affected to
     complete with this error; *note Cancel AIO Operations::.

 -- Macro: int EOWNERDEAD
     "Owner died."

 -- Macro: int ENOTRECOVERABLE
     "State not recoverable."

   _The following error codes are defined by the Linux/i386 kernel.
They are not yet documented._

 -- Macro: int ERESTART
     "Interrupted system call should be restarted."

 -- Macro: int ECHRNG
     "Channel number out of range."

 -- Macro: int EL2NSYNC
     "Level 2 not synchronized."

 -- Macro: int EL3HLT
     "Level 3 halted."

 -- Macro: int EL3RST
     "Level 3 reset."

 -- Macro: int ELNRNG
     "Link number out of range."

 -- Macro: int EUNATCH
     "Protocol driver not attached."

 -- Macro: int ENOCSI
     "No CSI structure available."

 -- Macro: int EL2HLT
     "Level 2 halted."

 -- Macro: int EBADE
     "Invalid exchange."

 -- Macro: int EBADR
     "Invalid request descriptor."

 -- Macro: int EXFULL
     "Exchange full."

 -- Macro: int ENOANO
     "No anode."

 -- Macro: int EBADRQC
     "Invalid request code."

 -- Macro: int EBADSLT
     "Invalid slot."

 -- Macro: int EDEADLOCK
     "File locking deadlock error."

 -- Macro: int EBFONT
     "Bad font file format."

 -- Macro: int ENONET
     "Machine is not on the network."

 -- Macro: int ENOPKG
     "Package not installed."

 -- Macro: int EADV
     "Advertise error."

 -- Macro: int ESRMNT
     "Srmount error."

 -- Macro: int ECOMM
     "Communication error on send."

 -- Macro: int EDOTDOT
     "RFS specific error."

 -- Macro: int ENOTUNIQ
     "Name not unique on network."

 -- Macro: int EBADFD
     "File descriptor in bad state."

 -- Macro: int EREMCHG
     "Remote address changed."

 -- Macro: int ELIBACC
     "Can not access a needed shared library."

 -- Macro: int ELIBBAD
     "Accessing a corrupted shared library."

 -- Macro: int ELIBSCN
     ".lib section in a.out corrupted."

 -- Macro: int ELIBMAX
     "Attempting to link in too many shared libraries."

 -- Macro: int ELIBEXEC
     "Cannot exec a shared library directly."

 -- Macro: int ESTRPIPE
     "Streams pipe error."

 -- Macro: int EUCLEAN
     "Structure needs cleaning."

 -- Macro: int ENOTNAM
     "Not a XENIX named type file."

 -- Macro: int ENAVAIL
     "No XENIX semaphores available."

 -- Macro: int EISNAM
     "Is a named type file."

 -- Macro: int EREMOTEIO
     "Remote I/O error."

 -- Macro: int ENOMEDIUM
     "No medium found."

 -- Macro: int EMEDIUMTYPE
     "Wrong medium type."

 -- Macro: int ENOKEY
     "Required key not available."

 -- Macro: int EKEYEXPIRED
     "Key has expired."

 -- Macro: int EKEYREVOKED
     "Key has been revoked."

 -- Macro: int EKEYREJECTED
     "Key was rejected by service."

 -- Macro: int ERFKILL
     "Operation not possible due to RF-kill."

 -- Macro: int EHWPOISON
     "Memory page has hardware error."


File: libc.info,  Node: Error Messages,  Prev: Error Codes,  Up: Error Reporting

2.3 Error Messages
==================

The library has functions and variables designed to make it easy for
your program to report informative error messages in the customary
format about the failure of a library call.  The functions `strerror'
and `perror' give you the standard error message for a given error
code; the variable `program_invocation_short_name' gives you convenient
access to the name of the program that encountered the error.

 -- Function: char * strerror (int ERRNUM)
     Preliminary: | MT-Unsafe race:strerror | AS-Unsafe heap i18n |
     AC-Unsafe mem | *Note POSIX Safety Concepts::.

     The `strerror' function maps the error code (*note Checking for
     Errors::) specified by the ERRNUM argument to a descriptive error
     message string.  The return value is a pointer to this string.

     The value ERRNUM normally comes from the variable `errno'.

     You should not modify the string returned by `strerror'.  Also, if
     you make subsequent calls to `strerror', the string might be
     overwritten.  (But it's guaranteed that no library function ever
     calls `strerror' behind your back.)

     The function `strerror' is declared in `string.h'.

 -- Function: char * strerror_r (int ERRNUM, char *BUF, size_t N)
     Preliminary: | MT-Safe | AS-Unsafe i18n | AC-Unsafe | *Note POSIX
     Safety Concepts::.

     The `strerror_r' function works like `strerror' but instead of
     returning the error message in a statically allocated buffer
     shared by all threads in the process, it returns a private copy
     for the thread.  This might be either some permanent global data
     or a message string in the user supplied buffer starting at BUF
     with the length of N bytes.

     At most N characters are written (including the NUL byte) so it is
     up to the user to select a buffer large enough.

     This function should always be used in multi-threaded programs
     since there is no way to guarantee the string returned by
     `strerror' really belongs to the last call of the current thread.

     The function `strerror_r' is a GNU extension and it is declared in
     `string.h'.

 -- Function: void perror (const char *MESSAGE)
     Preliminary: | MT-Safe race:stderr | AS-Unsafe corrupt i18n heap
     lock | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety
     Concepts::.

     This function prints an error message to the stream `stderr'; see
     *Note Standard Streams::.  The orientation of `stderr' is not
     changed.

     If you call `perror' with a MESSAGE that is either a null pointer
     or an empty string, `perror' just prints the error message
     corresponding to `errno', adding a trailing newline.

     If you supply a non-null MESSAGE argument, then `perror' prefixes
     its output with this string.  It adds a colon and a space
     character to separate the MESSAGE from the error string
     corresponding to `errno'.

     The function `perror' is declared in `stdio.h'.

   `strerror' and `perror' produce the exact same message for any given
error code; the precise text varies from system to system.  With the
GNU C Library, the messages are fairly short; there are no multi-line
messages or embedded newlines.  Each error message begins with a capital
letter and does not include any terminating punctuation.

   Many programs that don't read input from the terminal are designed to
exit if any system call fails.  By convention, the error message from
such a program should start with the program's name, sans directories.
You can find that name in the variable `program_invocation_short_name';
the full file name is stored the variable `program_invocation_name'.

 -- Variable: char * program_invocation_name
     This variable's value is the name that was used to invoke the
     program running in the current process.  It is the same as
     `argv[0]'.  Note that this is not necessarily a useful file name;
     often it contains no directory names.  *Note Program Arguments::.

     This variable is a GNU extension and is declared in `errno.h'.

 -- Variable: char * program_invocation_short_name
     This variable's value is the name that was used to invoke the
     program running in the current process, with directory names
     removed.  (That is to say, it is the same as
     `program_invocation_name' minus everything up to the last slash,
     if any.)

     This variable is a GNU extension and is declared in `errno.h'.

   The library initialization code sets up both of these variables
before calling `main'.

   *Portability Note:* If you want your program to work with non-GNU
libraries, you must save the value of `argv[0]' in `main', and then
strip off the directory names yourself.  We added these extensions to
make it possible to write self-contained error-reporting subroutines
that require no explicit cooperation from `main'.

   Here is an example showing how to handle failure to open a file
correctly.  The function `open_sesame' tries to open the named file for
reading and returns a stream if successful.  The `fopen' library
function returns a null pointer if it couldn't open the file for some
reason.  In that situation, `open_sesame' constructs an appropriate
error message using the `strerror' function, and terminates the
program.  If we were going to make some other library calls before
passing the error code to `strerror', we'd have to save it in a local
variable instead, because those other library functions might overwrite
`errno' in the meantime.

     #define _GNU_SOURCE

     #include <errno.h>
     #include <stdio.h>
     #include <stdlib.h>
     #include <string.h>

     FILE *
     open_sesame (char *name)
     {
       FILE *stream;

       errno = 0;
       stream = fopen (name, "r");
       if (stream == NULL)
         {
           fprintf (stderr, "%s: Couldn't open file %s; %s\n",
                    program_invocation_short_name, name, strerror (errno));
           exit (EXIT_FAILURE);
         }
       else
         return stream;
     }

   Using `perror' has the advantage that the function is portable and
available on all systems implementing ISO C.  But often the text
`perror' generates is not what is wanted and there is no way to extend
or change what `perror' does.  The GNU coding standard, for instance,
requires error messages to be preceded by the program name and programs
which read some input files should provide information about the input
file name and the line number in case an error is encountered while
reading the file.  For these occasions there are two functions
available which are widely used throughout the GNU project.  These
functions are declared in `error.h'.

 -- Function: void error (int STATUS, int ERRNUM, const char *FORMAT,
          ...)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n |
     AC-Safe | *Note POSIX Safety Concepts::.

     The `error' function can be used to report general problems during
     program execution.  The FORMAT argument is a format string just
     like those given to the `printf' family of functions.  The
     arguments required for the format can follow the FORMAT parameter.
     Just like `perror', `error' also can report an error code in
     textual form.  But unlike `perror' the error value is explicitly
     passed to the function in the ERRNUM parameter.  This eliminates
     the problem mentioned above that the error reporting function must
     be called immediately after the function causing the error since
     otherwise `errno' might have a different value.

     `error' prints first the program name.  If the application defined
     a global variable `error_print_progname' and points it to a
     function this function will be called to print the program name.
     Otherwise the string from the global variable `program_name' is
     used.  The program name is followed by a colon and a space which
     in turn is followed by the output produced by the format string.
     If the ERRNUM parameter is non-zero the format string output is
     followed by a colon and a space, followed by the error message for
     the error code ERRNUM.  In any case is the output terminated with
     a newline.

     The output is directed to the `stderr' stream.  If the `stderr'
     wasn't oriented before the call it will be narrow-oriented
     afterwards.

     The function will return unless the STATUS parameter has a
     non-zero value.  In this case the function will call `exit' with
     the STATUS value for its parameter and therefore never return.  If
     `error' returns, the global variable `error_message_count' is
     incremented by one to keep track of the number of errors reported.

 -- Function: void error_at_line (int STATUS, int ERRNUM, const char
          *FNAME, unsigned int LINENO, const char *FORMAT, ...)
     Preliminary: | MT-Unsafe race:error_at_line/error_one_per_line
     locale | AS-Unsafe corrupt heap i18n | AC-Unsafe
     corrupt/error_one_per_line | *Note POSIX Safety Concepts::.

     The `error_at_line' function is very similar to the `error'
     function.  The only differences are the additional parameters FNAME
     and LINENO.  The handling of the other parameters is identical to
     that of `error' except that between the program name and the string
     generated by the format string additional text is inserted.

     Directly following the program name a colon, followed by the file
     name pointed to by FNAME, another colon, and the value of LINENO is
     printed.

     This additional output of course is meant to be used to locate an
     error in an input file (like a programming language source code
     file etc).

     If the global variable `error_one_per_line' is set to a non-zero
     value `error_at_line' will avoid printing consecutive messages for
     the same file and line.  Repetition which are not directly
     following each other are not caught.

     Just like `error' this function only returns if STATUS is zero.
     Otherwise `exit' is called with the non-zero value.  If `error'
     returns, the global variable `error_message_count' is incremented
     by one to keep track of the number of errors reported.

   As mentioned above, the `error' and `error_at_line' functions can be
customized by defining a variable named `error_print_progname'.

 -- Variable: void (*error_print_progname) (void)
     If the `error_print_progname' variable is defined to a non-zero
     value the function pointed to is called by `error' or
     `error_at_line'.  It is expected to print the program name or do
     something similarly useful.

     The function is expected to print to the `stderr' stream and must
     be able to handle whatever orientation the stream has.

     The variable is global and shared by all threads.

 -- Variable: unsigned int error_message_count
     The `error_message_count' variable is incremented whenever one of
     the functions `error' or `error_at_line' returns.  The variable is
     global and shared by all threads.

 -- Variable: int error_one_per_line
     The `error_one_per_line' variable influences only `error_at_line'.
     Normally the `error_at_line' function creates output for every
     invocation.  If `error_one_per_line' is set to a non-zero value
     `error_at_line' keeps track of the last file name and line number
     for which an error was reported and avoids directly following
     messages for the same file and line.  This variable is global and
     shared by all threads.

A program which read some input file and reports errors in it could look
like this:

     {
       char *line = NULL;
       size_t len = 0;
       unsigned int lineno = 0;

       error_message_count = 0;
       while (! feof_unlocked (fp))
         {
           ssize_t n = getline (&line, &len, fp);
           if (n <= 0)
             /* End of file or error.  */
             break;
           ++lineno;

           /* Process the line.  */
           ...

           if (Detect error in line)
             error_at_line (0, errval, filename, lineno,
                            "some error text %s", some_variable);
         }

       if (error_message_count != 0)
         error (EXIT_FAILURE, 0, "%u errors found", error_message_count);
     }

   `error' and `error_at_line' are clearly the functions of choice and
enable the programmer to write applications which follow the GNU coding
standard.  The GNU C Library additionally contains functions which are
used in BSD for the same purpose.  These functions are declared in
`err.h'.  It is generally advised to not use these functions.  They are
included only for compatibility.

 -- Function: void warn (const char *FORMAT, ...)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n |
     AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.

     The `warn' function is roughly equivalent to a call like
            error (0, errno, format, the parameters)
     except that the global variables `error' respects and modifies are
     not used.

 -- Function: void vwarn (const char *FORMAT, va_list AP)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n |
     AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.

     The `vwarn' function is just like `warn' except that the
     parameters for the handling of the format string FORMAT are passed
     in as a value of type `va_list'.

 -- Function: void warnx (const char *FORMAT, ...)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
     corrupt lock mem | *Note POSIX Safety Concepts::.

     The `warnx' function is roughly equivalent to a call like
            error (0, 0, format, the parameters)
     except that the global variables `error' respects and modifies are
     not used.  The difference to `warn' is that no error number string
     is printed.

 -- Function: void vwarnx (const char *FORMAT, va_list AP)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
     corrupt lock mem | *Note POSIX Safety Concepts::.

     The `vwarnx' function is just like `warnx' except that the
     parameters for the handling of the format string FORMAT are passed
     in as a value of type `va_list'.

 -- Function: void err (int STATUS, const char *FORMAT, ...)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n |
     AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.

     The `err' function is roughly equivalent to a call like
            error (status, errno, format, the parameters)
     except that the global variables `error' respects and modifies are
     not used and that the program is exited even if STATUS is zero.

 -- Function: void verr (int STATUS, const char *FORMAT, va_list AP)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap i18n |
     AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.

     The `verr' function is just like `err' except that the parameters
     for the handling of the format string FORMAT are passed in as a
     value of type `va_list'.

 -- Function: void errx (int STATUS, const char *FORMAT, ...)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
     corrupt lock mem | *Note POSIX Safety Concepts::.

     The `errx' function is roughly equivalent to a call like
            error (status, 0, format, the parameters)
     except that the global variables `error' respects and modifies are
     not used and that the program is exited even if STATUS is zero.
     The difference to `err' is that no error number string is printed.

 -- Function: void verrx (int STATUS, const char *FORMAT, va_list AP)
     Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
     corrupt lock mem | *Note POSIX Safety Concepts::.

     The `verrx' function is just like `errx' except that the
     parameters for the handling of the format string FORMAT are passed
     in as a value of type `va_list'.


File: libc.info,  Node: Memory,  Next: Character Handling,  Prev: Error Reporting,  Up: Top

3 Virtual Memory Allocation And Paging
**************************************

This chapter describes how processes manage and use memory in a system
that uses the GNU C Library.

   The GNU C Library has several functions for dynamically allocating
virtual memory in various ways.  They vary in generality and in
efficiency.  The library also provides functions for controlling paging
and allocation of real memory.

* Menu:

* Memory Concepts::             An introduction to concepts and terminology.
* Memory Allocation::           Allocating storage for your program data
* Resizing the Data Segment::   `brk', `sbrk'
* Memory Protection::           Controlling access to memory regions.
* Locking Pages::               Preventing page faults

   Memory mapped I/O is not discussed in this chapter.  *Note
Memory-mapped I/O::.


File: libc.info,  Node: Memory Concepts,  Next: Memory Allocation,  Up: Memory

3.1 Process Memory Concepts
===========================

One of the most basic resources a process has available to it is memory.
There are a lot of different ways systems organize memory, but in a
typical one, each process has one linear virtual address space, with
addresses running from zero to some huge maximum.  It need not be
contiguous; i.e., not all of these addresses actually can be used to
store data.

   The virtual memory is divided into pages (4 kilobytes is typical).
Backing each page of virtual memory is a page of real memory (called a
"frame") or some secondary storage, usually disk space.  The disk space
might be swap space or just some ordinary disk file.  Actually, a page
of all zeroes sometimes has nothing at all backing it - there's just a
flag saying it is all zeroes.  

   The same frame of real memory or backing store can back multiple
virtual pages belonging to multiple processes.  This is normally the
case, for example, with virtual memory occupied by GNU C Library code.
The same real memory frame containing the `printf' function backs a
virtual memory page in each of the existing processes that has a
`printf' call in its program.

   In order for a program to access any part of a virtual page, the page
must at that moment be backed by ("connected to") a real frame.  But
because there is usually a lot more virtual memory than real memory, the
pages must move back and forth between real memory and backing store
regularly, coming into real memory when a process needs to access them
and then retreating to backing store when not needed anymore.  This
movement is called "paging".

   When a program attempts to access a page which is not at that moment
backed by real memory, this is known as a "page fault".  When a page
fault occurs, the kernel suspends the process, places the page into a
real page frame (this is called "paging in" or "faulting in"), then
resumes the process so that from the process' point of view, the page
was in real memory all along.  In fact, to the process, all pages always
seem to be in real memory.  Except for one thing: the elapsed execution
time of an instruction that would normally be a few nanoseconds is
suddenly much, much, longer (because the kernel normally has to do I/O
to complete the page-in).  For programs sensitive to that, the functions
described in *Note Locking Pages:: can control it.  

   Within each virtual address space, a process has to keep track of
what is at which addresses, and that process is called memory
allocation.  Allocation usually brings to mind meting out scarce
resources, but in the case of virtual memory, that's not a major goal,
because there is generally much more of it than anyone needs.  Memory
allocation within a process is mainly just a matter of making sure that
the same byte of memory isn't used to store two different things.

   Processes allocate memory in two major ways: by exec and
programmatically.  Actually, forking is a third way, but it's not very
interesting.  *Note Creating a Process::.

   Exec is the operation of creating a virtual address space for a
process, loading its basic program into it, and executing the program.
It is done by the "exec" family of functions (e.g. `execl').  The
operation takes a program file (an executable), it allocates space to
load all the data in the executable, loads it, and transfers control to
it.  That data is most notably the instructions of the program (the
"text"), but also literals and constants in the program and even some
variables: C variables with the static storage class (*note Memory
Allocation and C::).  

   Once that program begins to execute, it uses programmatic allocation
to gain additional memory.  In a C program with the GNU C Library, there
are two kinds of programmatic allocation: automatic and dynamic.  *Note
Memory Allocation and C::.

   Memory-mapped I/O is another form of dynamic virtual memory
allocation.  Mapping memory to a file means declaring that the contents
of certain range of a process' addresses shall be identical to the
contents of a specified regular file.  The system makes the virtual
memory initially contain the contents of the file, and if you modify
the memory, the system writes the same modification to the file.  Note
that due to the magic of virtual memory and page faults, there is no
reason for the system to do I/O to read the file, or allocate real
memory for its contents, until the program accesses the virtual memory.
*Note Memory-mapped I/O::.  

   Just as it programmatically allocates memory, the program can
programmatically deallocate ("free") it.  You can't free the memory
that was allocated by exec.  When the program exits or execs, you might
say that all its memory gets freed, but since in both cases the address
space ceases to exist, the point is really moot.  *Note Program
Termination::.  

   A process' virtual address space is divided into segments.  A
segment is a contiguous range of virtual addresses.  Three important
segments are:

   *  The "text segment" contains a program's instructions and literals
     and static constants.  It is allocated by exec and stays the same
     size for the life of the virtual address space.

   * The "data segment" is working storage for the program.  It can be
     preallocated and preloaded by exec and the process can extend or
     shrink it by calling functions as described in *Note Resizing the
     Data Segment::.  Its lower end is fixed.

   * The "stack segment" contains a program stack.  It grows as the
     stack grows, but doesn't shrink when the stack shrinks.



File: libc.info,  Node: Memory Allocation,  Next: Resizing the Data Segment,  Prev: Memory Concepts,  Up: Memory

3.2 Allocating Storage For Program Data
=======================================

This section covers how ordinary programs manage storage for their data,
including the famous `malloc' function and some fancier facilities
special to the GNU C Library and GNU Compiler.

* Menu:

* Memory Allocation and C::     How to get different kinds of allocation in C.
* The GNU Allocator::		An overview of the GNU `malloc'
				implementation.
* Unconstrained Allocation::    The `malloc' facility allows fully general
		 		 dynamic allocation.
* Allocation Debugging::        Finding memory leaks and not freed memory.
* Replacing malloc::            Using your own `malloc'-style allocator.
* Obstacks::                    Obstacks are less general than malloc
				 but more efficient and convenient.
* Variable Size Automatic::     Allocation of variable-sized blocks
				 of automatic storage that are freed when the
				 calling function returns.


File: libc.info,  Node: Memory Allocation and C,  Next: The GNU Allocator,  Up: Memory Allocation

3.2.1 Memory Allocation in C Programs
-------------------------------------

The C language supports two kinds of memory allocation through the
variables in C programs:

   * "Static allocation" is what happens when you declare a static or
     global variable.  Each static or global variable defines one block
     of space, of a fixed size.  The space is allocated once, when your
     program is started (part of the exec operation), and is never
     freed.  

   * "Automatic allocation" happens when you declare an automatic
     variable, such as a function argument or a local variable.  The
     space for an automatic variable is allocated when the compound
     statement containing the declaration is entered, and is freed when
     that compound statement is exited.  

     In GNU C, the size of the automatic storage can be an expression
     that varies.  In other C implementations, it must be a constant.

   A third important kind of memory allocation, "dynamic allocation",
is not supported by C variables but is available via GNU C Library
functions.  

3.2.1.1 Dynamic Memory Allocation
.................................

"Dynamic memory allocation" is a technique in which programs determine
as they are running where to store some information.  You need dynamic
allocation when the amount of memory you need, or how long you continue
to need it, depends on factors that are not known before the program
runs.

   For example, you may need a block to store a line read from an input
file; since there is no limit to how long a line can be, you must
allocate the memory dynamically and make it dynamically larger as you
read more of the line.

   Or, you may need a block for each record or each definition in the
input data; since you can't know in advance how many there will be, you
must allocate a new block for each record or definition as you read it.

   When you use dynamic allocation, the allocation of a block of memory
is an action that the program requests explicitly.  You call a function
or macro when you want to allocate space, and specify the size with an
argument.  If you want to free the space, you do so by calling another
function or macro.  You can do these things whenever you want, as often
as you want.

   Dynamic allocation is not supported by C variables; there is no
storage class "dynamic", and there can never be a C variable whose
value is stored in dynamically allocated space.  The only way to get
dynamically allocated memory is via a system call (which is generally
via a GNU C Library function call), and the only way to refer to
dynamically allocated space is through a pointer.  Because it is less
convenient, and because the actual process of dynamic allocation
requires more computation time, programmers generally use dynamic
allocation only when neither static nor automatic allocation will serve.

   For example, if you want to allocate dynamically some space to hold a
`struct foobar', you cannot declare a variable of type `struct foobar'
whose contents are the dynamically allocated space.  But you can
declare a variable of pointer type `struct foobar *' and assign it the
address of the space.  Then you can use the operators `*' and `->' on
this pointer variable to refer to the contents of the space:

     {
       struct foobar *ptr
          = (struct foobar *) malloc (sizeof (struct foobar));
       ptr->name = x;
       ptr->next = current_foobar;
       current_foobar = ptr;
     }


File: libc.info,  Node: The GNU Allocator,  Next: Unconstrained Allocation,  Prev: Memory Allocation and C,  Up: Memory Allocation

3.2.2 The GNU Allocator
-----------------------

The `malloc' implementation in the GNU C Library is derived from
ptmalloc (pthreads malloc), which in turn is derived from dlmalloc
(Doug Lea malloc).  This malloc may allocate memory in two different
ways depending on their size and certain parameters that may be
controlled by users. The most common way is to allocate portions of
memory (called chunks) from a large contiguous area of memory and
manage these areas to optimize their use and reduce wastage in the form
of unusable chunks. Traditionally the system heap was set up to be the
one large memory area but the GNU C Library `malloc' implementation
maintains multiple such areas to optimize their use in multi-threaded
applications.  Each such area is internally referred to as an "arena".

   As opposed to other versions, the `malloc' in the GNU C Library does
not round up chunk sizes to powers of two, neither for large nor for
small sizes.  Neighboring chunks can be coalesced on a `free' no matter
what their size is.  This makes the implementation suitable for all
kinds of allocation patterns without generally incurring high memory
waste through fragmentation.  The presence of multiple arenas allows
multiple threads to allocate memory simultaneously in separate arenas,
thus improving performance.

   The other way of memory allocation is for very large blocks, i.e.
much larger than a page. These requests are allocated with `mmap'
(anonymous or via `/dev/zero'; *note Memory-mapped I/O::)). This has
the great advantage that these chunks are returned to the system
immediately when they are freed.  Therefore, it cannot happen that a
large chunk becomes "locked" in between smaller ones and even after
calling `free' wastes memory.  The size threshold for `mmap' to be used
is dynamic and gets adjusted according to allocation patterns of the
program.  `mallopt' can be used to statically adjust the threshold
using `M_MMAP_THRESHOLD' and the use of `mmap' can be disabled
completely with `M_MMAP_MAX'; *note Malloc Tunable Parameters::.

   A more detailed technical description of the GNU Allocator is
maintained in the GNU C Library wiki. See
`https://sourceware.org/glibc/wiki/MallocInternals'.

   It is possible to use your own custom `malloc' instead of the
built-in allocator provided by the GNU C Library.  *Note Replacing
malloc::.


File: libc.info,  Node: Unconstrained Allocation,  Next: Allocation Debugging,  Prev: The GNU Allocator,  Up: Memory Allocation

3.2.3 Unconstrained Allocation
------------------------------

The most general dynamic allocation facility is `malloc'.  It allows
you to allocate blocks of memory of any size at any time, make them
bigger or smaller at any time, and free the blocks individually at any
time (or never).

* Menu:

* Basic Allocation::            Simple use of `malloc'.
* Malloc Examples::             Examples of `malloc'.  `xmalloc'.
* Freeing after Malloc::        Use `free' to free a block you
				 got with `malloc'.
* Changing Block Size::         Use `realloc' to make a block
				 bigger or smaller.
* Allocating Cleared Space::    Use `calloc' to allocate a
				 block and clear it.
* Aligned Memory Blocks::       Allocating specially aligned memory.
* Malloc Tunable Parameters::   Use `mallopt' to adjust allocation
                                 parameters.
* Heap Consistency Checking::   Automatic checking for errors.
* Hooks for Malloc::            You can use these hooks for debugging
				 programs that use `malloc'.
* Statistics of Malloc::        Getting information about how much
				 memory your program is using.
* Summary of Malloc::           Summary of `malloc' and related functions.


File: libc.info,  Node: Basic Allocation,  Next: Malloc Examples,  Up: Unconstrained Allocation

3.2.3.1 Basic Memory Allocation
...............................

To allocate a block of memory, call `malloc'.  The prototype for this
function is in `stdlib.h'.  

 -- Function: void * malloc (size_t SIZE)
     Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem |
     *Note POSIX Safety Concepts::.

     This function returns a pointer to a newly allocated block SIZE
     bytes long, or a null pointer if the block could not be allocated.

   The contents of the block are undefined; you must initialize it
yourself (or use `calloc' instead; *note Allocating Cleared Space::).
Normally you would cast the value as a pointer to the kind of object
that you want to store in the block.  Here we show an example of doing
so, and of initializing the space with zeros using the library function
`memset' (*note Copying Strings and Arrays::):

     struct foo *ptr;
     ...
     ptr = (struct foo *) malloc (sizeof (struct foo));
     if (ptr == 0) abort ();
     memset (ptr, 0, sizeof (struct foo));

   You can store the result of `malloc' into any pointer variable
without a cast, because ISO C automatically converts the type `void *'
to another type of pointer when necessary.  But the cast is necessary
in contexts other than assignment operators or if you might want your
code to run in traditional C.

   Remember that when allocating space for a string, the argument to
`malloc' must be one plus the length of the string.  This is because a
string is terminated with a null character that doesn't count in the
"length" of the string but does need space.  For example:

     char *ptr;
     ...
     ptr = (char *) malloc (length + 1);

*Note Representation of Strings::, for more information about this.


File: libc.info,  Node: Malloc Examples,  Next: Freeing after Malloc,  Prev: Basic Allocation,  Up: Unconstrained Allocation

3.2.3.2 Examples of `malloc'
............................

If no more space is available, `malloc' returns a null pointer.  You
should check the value of _every_ call to `malloc'.  It is useful to
write a subroutine that calls `malloc' and reports an error if the
value is a null pointer, returning only if the value is nonzero.  This
function is conventionally called `xmalloc'.  Here it is:

     void *
     xmalloc (size_t size)
     {
       void *value = malloc (size);
       if (value == 0)
         fatal ("virtual memory exhausted");
       return value;
     }

   Here is a real example of using `malloc' (by way of `xmalloc').  The
function `savestring' will copy a sequence of characters into a newly
allocated null-terminated string:

     char *
     savestring (const char *ptr, size_t len)
     {
       char *value = (char *) xmalloc (len + 1);
       value[len] = '\0';
       return (char *) memcpy (value, ptr, len);
     }

   The block that `malloc' gives you is guaranteed to be aligned so
that it can hold any type of data.  On GNU systems, the address is
always a multiple of eight on 32-bit systems, and a multiple of 16 on
64-bit systems.  Only rarely is any higher boundary (such as a page
boundary) necessary; for those cases, use `aligned_alloc' or
`posix_memalign' (*note Aligned Memory Blocks::).

   Note that the memory located after the end of the block is likely to
be in use for something else; perhaps a block already allocated by
another call to `malloc'.  If you attempt to treat the block as longer
than you asked for it to be, you are liable to destroy the data that
`malloc' uses to keep track of its blocks, or you may destroy the
contents of another block.  If you have already allocated a block and
discover you want it to be bigger, use `realloc' (*note Changing Block
Size::).


File: libc.info,  Node: Freeing after Malloc,  Next: Changing Block Size,  Prev: Malloc Examples,  Up: Unconstrained Allocation

3.2.3.3 Freeing Memory Allocated with `malloc'
..............................................

When you no longer need a block that you got with `malloc', use the
function `free' to make the block available to be allocated again.  The
prototype for this function is in `stdlib.h'.  

 -- Function: void free (void *PTR)
     Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem |
     *Note POSIX Safety Concepts::.

     The `free' function deallocates the block of memory pointed at by
     PTR.

   Freeing a block alters the contents of the block.  *Do not expect to
find any data (such as a pointer to the next block in a chain of
blocks) in the block after freeing it.*  Copy whatever you need out of
the block before freeing it!  Here is an example of the proper way to
free all the blocks in a chain, and the strings that they point to:

     struct chain
       {
         struct chain *next;
         char *name;
       }

     void
     free_chain (struct chain *chain)
     {
       while (chain != 0)
         {
           struct chain *next = chain->next;
           free (chain->name);
           free (chain);
           chain = next;
         }
     }

   Occasionally, `free' can actually return memory to the operating
system and make the process smaller.  Usually, all it can do is allow a
later call to `malloc' to reuse the space.  In the meantime, the space
remains in your program as part of a free-list used internally by
`malloc'.

   There is no point in freeing blocks at the end of a program, because
all of the program's space is given back to the system when the process
terminates.


File: libc.info,  Node: Changing Block Size,  Next: Allocating Cleared Space,  Prev: Freeing after Malloc,  Up: Unconstrained Allocation

3.2.3.4 Changing the Size of a Block
....................................

Often you do not know for certain how big a block you will ultimately
need at the time you must begin to use the block.  For example, the
block might be a buffer that you use to hold a line being read from a
file; no matter how long you make the buffer initially, you may
encounter a line that is longer.

   You can make the block longer by calling `realloc' or
`reallocarray'.  These functions are declared in `stdlib.h'.  

 -- Function: void * realloc (void *PTR, size_t NEWSIZE)
     Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem |
     *Note POSIX Safety Concepts::.

     The `realloc' function changes the size of the block whose address
     is PTR to be NEWSIZE.

     Since the space after the end of the block may be in use, `realloc'
     may find it necessary to copy the block to a new address where
     more free space is available.  The value of `realloc' is the new
     address of the block.  If the block needs to be moved, `realloc'
     copies the old contents.

     If you pass a null pointer for PTR, `realloc' behaves just like
     `malloc (NEWSIZE)'.  This can be convenient, but beware that older
     implementations (before ISO C) may not support this behavior, and
     will probably crash when `realloc' is passed a null pointer.

 -- Function: void * reallocarray (void *PTR, size_t NMEMB, size_t SIZE)
     Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem |
     *Note POSIX Safety Concepts::.

     The `reallocarray' function changes the size of the block whose
     address is PTR to be long enough to contain a vector of NMEMB
     elements, each of size SIZE.  It is equivalent to `realloc (PTR,
     NMEMB * SIZE)', except that `reallocarray' fails safely if the
     multiplication overflows, by setting `errno' to `ENOMEM',
     returning a null pointer, and leaving the original block unchanged.

     `reallocarray' should be used instead of `realloc' when the new
     size of the allocated block is the result of a multiplication that
     might overflow.

     *Portability Note:* This function is not part of any standard.  It
     was first introduced in OpenBSD 5.6.

   Like `malloc', `realloc' and `reallocarray' may return a null
pointer if no memory space is available to make the block bigger.  When
this happens, the original block is untouched; it has not been modified
or relocated.

   In most cases it makes no difference what happens to the original
block when `realloc' fails, because the application program cannot
continue when it is out of memory, and the only thing to do is to give
a fatal error message.  Often it is convenient to write and use a
subroutine, conventionally called `xrealloc', that takes care of the
error message as `xmalloc' does for `malloc':

     void *
     xrealloc (void *ptr, size_t size)
     {
       void *value = realloc (ptr, size);
       if (value == 0)
         fatal ("Virtual memory exhausted");
       return value;
     }

   You can also use `realloc' or `reallocarray' to make a block
smaller.  The reason you would do this is to avoid tying up a lot of
memory space when only a little is needed.  In several allocation
implementations, making a block smaller sometimes necessitates copying
it, so it can fail if no other space is available.

   If the new size you specify is the same as the old size, `realloc'
and `reallocarray' are guaranteed to change nothing and return the same
address that you gave.


File: libc.info,  Node: Allocating Cleared Space,  Next: Aligned Memory Blocks,  Prev: Changing Block Size,  Up: Unconstrained Allocation

3.2.3.5 Allocating Cleared Space
................................

The function `calloc' allocates memory and clears it to zero.  It is
declared in `stdlib.h'.  

 -- Function: void * calloc (size_t COUNT, size_t ELTSIZE)
     Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem |
     *Note POSIX Safety Concepts::.

     This function allocates a block long enough to contain a vector of
     COUNT elements, each of size ELTSIZE.  Its contents are cleared to
     zero before `calloc' returns.

   You could define `calloc' as follows:

     void *
     calloc (size_t count, size_t eltsize)
     {
       size_t size = count * eltsize;
       void *value = malloc (size);
       if (value != 0)
         memset (value, 0, size);
       return value;
     }

   But in general, it is not guaranteed that `calloc' calls `malloc'
internally.  Therefore, if an application provides its own
`malloc'/`realloc'/`free' outside the C library, it should always
define `calloc', too.


File: libc.info,  Node: Aligned Memory Blocks,  Next: Malloc Tunable Parameters,  Prev: Allocating Cleared Space,  Up: Unconstrained Allocation

3.2.3.6 Allocating Aligned Memory Blocks
........................................

The address of a block returned by `malloc' or `realloc' in GNU systems
is always a multiple of eight (or sixteen on 64-bit systems).  If you
need a block whose address is a multiple of a higher power of two than
that, use `aligned_alloc' or `posix_memalign'.  `aligned_alloc' and
`posix_memalign' are declared in `stdlib.h'.

 -- Function: void * aligned_alloc (size_t ALIGNMENT, size_t SIZE)
     Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem |
     *Note POSIX Safety Concepts::.

     The `aligned_alloc' function allocates a block of SIZE bytes whose
     address is a multiple of ALIGNMENT.  The ALIGNMENT must be a power
     of two and SIZE must be a multiple of ALIGNMENT.

     The `aligned_alloc' function returns a null pointer on error and
     sets `errno' to one of the following values:

    `ENOMEM'
          There was insufficient memory available to satisfy the
          request.

    `EINVAL'
          ALIGNMENT is not a power of two.

          This function was introduced in ISO C11 and hence may have
          better portability to modern non-POSIX systems than
          `posix_memalign'.


 -- Function: void * memalign (size_t BOUNDARY, size_t SIZE)
     Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem |
     *Note POSIX Safety Concepts::.

     The `memalign' function allocates a block of SIZE bytes whose
     address is a multiple of BOUNDARY.  The BOUNDARY must be a power
     of two!  The function `memalign' works by allocating a somewhat
     larger block, and then returning an address within the block that
     is on the specified boundary.

     The `memalign' function returns a null pointer on error and sets
     `errno' to one of the following values:

    `ENOMEM'
          There was insufficient memory available to satisfy the
          request.

    `EINVAL'
          BOUNDARY is not a power of two.


     The `memalign' function is obsolete and `aligned_alloc' or
     `posix_memalign' should be used instead.

 -- Function: int posix_memalign (void **MEMPTR, size_t ALIGNMENT,
          size_t SIZE)
     Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd mem |
     *Note POSIX Safety Concepts::.

     The `posix_memalign' function is similar to the `memalign'
     function in that it returns a buffer of SIZE bytes aligned to a
     multiple of ALIGNMENT.  But it adds one requirement to the
     parameter ALIGNMENT: the value must be a power of two multiple of
     `sizeof (void *)'.

     If the function succeeds in allocation memory a pointer to the
     allocated memory is returned in `*MEMPTR' and the return value is
     zero.  Otherwise the function returns an error value indicating
     the problem.  The possible error values returned are:

    `ENOMEM'
          There was insufficient memory available to satisfy the
          request.

    `EINVAL'
          ALIGNMENT is not a power of two multiple of `sizeof (void *)'.


     This function was introduced in POSIX 1003.1d.  Although this
     function is superseded by `aligned_alloc', it is more portable to
     older POSIX systems that do not support ISO C11.

 -- Function: void * valloc (size_t SIZE)
     Preliminary: | MT-Unsafe init | AS-Unsafe init lock | AC-Unsafe
     init lock fd mem | *Note POSIX Safety Concepts::.

     Using `valloc' is like using `memalign' and passing the page size
     as the value of the first argument.  It is implemented like this:

          void *
          valloc (size_t size)
          {
            return memalign (getpagesize (), size);
          }

     *Note Query Memory Parameters:: for more information about the
     memory subsystem.

     The `valloc' function is obsolete and `aligned_alloc' or
     `posix_memalign' should be used instead.


File: libc.info,  Node: Malloc Tunable Parameters,  Next: Heap Consistency Checking,  Prev: Aligned Memory Blocks,  Up: Unconstrained Allocation

3.2.3.7 Malloc Tunable Parameters
.................................

You can adjust some parameters for dynamic memory allocation with the
`mallopt' function.  This function is the general SVID/XPG interface,
defined in `malloc.h'.  

 -- Function: int mallopt (int PARAM, int VALUE)
     Preliminary: | MT-Unsafe init const:mallopt | AS-Unsafe init lock
     | AC-Unsafe init lock | *Note POSIX Safety Concepts::.

     When calling `mallopt', the PARAM argument specifies the parameter
     to be set, and VALUE the new value to be set.  Possible choices
     for PARAM, as defined in `malloc.h', are:

    `M_MMAP_MAX'
          The maximum number of chunks to allocate with `mmap'.
          Setting this to zero disables all use of `mmap'.

          The default value of this parameter is `65536'.

          This parameter can also be set for the process at startup by
          setting the environment variable `MALLOC_MMAP_MAX_' to the
          desired value.

    `M_MMAP_THRESHOLD'
          All chunks larger than this value are allocated outside the
          normal heap, using the `mmap' system call.  This way it is
          guaranteed that the memory for these chunks can be returned
          to the system on `free'.  Note that requests smaller than
          this threshold might still be allocated via `mmap'.

          If this parameter is not set, the default value is set as 128
          KiB and the threshold is adjusted dynamically to suit the
          allocation patterns of the program. If the parameter is set,
          the dynamic adjustment is disabled and the value is set
          statically to the input value.

          This parameter can also be set for the process at startup by
          setting the environment variable `MALLOC_MMAP_THRESHOLD_' to
          the desired value.

    `M_PERTURB'
          If non-zero, memory blocks are filled with values depending
          on some low order bits of this parameter when they are
          allocated (except when allocated by `calloc') and freed.
          This can be used to debug the use of uninitialized or freed
          heap memory.  Note that this option does not guarantee that
          the freed block will have any specific values.  It only
          guarantees that the content the block had before it was freed
          will be overwritten.

          The default value of this parameter is `0'.

          This parameter can also be set for the process at startup by
          setting the environment variable `MALLOC_MMAP_PERTURB_' to
          the desired value.

    `M_TOP_PAD'
          This parameter determines the amount of extra memory to
          obtain from the system when an arena needs to be extended.
          It also specifies the number of bytes to retain when
          shrinking an arena.  This provides the necessary hysteresis
          in heap size such that excessive amounts of system calls can
          be avoided.

          The default value of this parameter is `0'.

          This parameter can also be set for the process at startup by
          setting the environment variable `MALLOC_TOP_PAD_' to the
          desired value.

    `M_TRIM_THRESHOLD'
          This is the minimum size (in bytes) of the top-most,
          releasable chunk that will trigger a system call in order to
          return memory to the system.

          If this parameter is not set, the default value is set as 128
          KiB and the threshold is adjusted dynamically to suit the
          allocation patterns of the program. If the parameter is set,
          the dynamic adjustment is disabled and the value is set
          statically to the provided input.

          This parameter can also be set for the process at startup by
          setting the environment variable `MALLOC_TRIM_THRESHOLD_' to
          the desired value.

    `M_ARENA_TEST'
          This parameter specifies the number of arenas that can be
          created before the test on the limit to the number of arenas
          is conducted. The value is ignored if `M_ARENA_MAX' is set.

          The default value of this parameter is 2 on 32-bit systems
          and 8 on 64-bit systems.

          This parameter can also be set for the process at startup by
          setting the environment variable `MALLOC_ARENA_TEST' to the
          desired value.

    `M_ARENA_MAX'
          This parameter sets the number of arenas to use regardless of
          the number of cores in the system.

          The default value of this tunable is `0', meaning that the
          limit on the number of arenas is determined by the number of
          CPU cores online. For 32-bit systems the limit is twice the
          number of cores online and on 64-bit systems, it is eight
          times the number of cores online.  Note that the default
          value is not derived from the default value of M_ARENA_TEST
          and is computed independently.

          This parameter can also be set for the process at startup by
          setting the environment variable `MALLOC_ARENA_MAX' to the
          desired value.



File: libc.info,  Node: Heap Consistency Checking,  Next: Hooks for Malloc,  Prev: Malloc Tunable Parameters,  Up: Unconstrained Allocation

3.2.3.8 Heap Consistency Checking
.................................

You can ask `malloc' to check the consistency of dynamic memory by
using the `mcheck' function.  This function is a GNU extension,
declared in `mcheck.h'.  

 -- Function: int mcheck (void (*ABORTFN) (enum mcheck_status STATUS))
     Preliminary: | MT-Unsafe race:mcheck const:malloc_hooks |
     AS-Unsafe corrupt | AC-Unsafe corrupt | *Note POSIX Safety
     Concepts::.

     Calling `mcheck' tells `malloc' to perform occasional consistency
     checks.  These will catch things such as writing past the end of a
     block that was allocated with `malloc'.

     The ABORTFN argument is the function to call when an inconsistency
     is found.  If you supply a null pointer, then `mcheck' uses a
     default function which prints a message and calls `abort' (*note
     Aborting a Program::).  The function you supply is called with one
     argument, which says what sort of inconsistency was detected; its
     type is described below.

     It is too late to begin allocation checking once you have allocated
     anything with `malloc'.  So `mcheck' does nothing in that case.
     The function returns `-1' if you call it too late, and `0'
     otherwise (when it is successful).

     The easiest way to arrange to call `mcheck' early enough is to use
     the option `-lmcheck' when you link your program; then you don't
     need to modify your program source at all.  Alternatively you
     might use a debugger to insert a call to `mcheck' whenever the
     program is started, for example these gdb commands will
     automatically call `mcheck' whenever the program starts:

          (gdb) break main
          Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10
          (gdb) command 1
          Type commands for when breakpoint 1 is hit, one per line.
          End with a line saying just "end".
          >call mcheck(0)
          >continue
          >end
          (gdb) ...

     This will however only work if no initialization function of any
     object involved calls any of the `malloc' functions since `mcheck'
     must be called before the first such function.


 -- Function: enum mcheck_status mprobe (void *POINTER)
     Preliminary: | MT-Unsafe race:mcheck const:malloc_hooks |
     AS-Unsafe corrupt | AC-Unsafe corrupt | *Note POSIX Safety
     Concepts::.

     The `mprobe' function lets you explicitly check for inconsistencies
     in a particular allocated block.  You must have already called
     `mcheck' at the beginning of the program, to do its occasional
     checks; calling `mprobe' requests an additional consistency check
     to be done at the time of the call.

     The argument POINTER must be a pointer returned by `malloc' or
     `realloc'.  `mprobe' returns a value that says what inconsistency,
     if any, was found.  The values are described below.

 -- Data Type: enum mcheck_status
     This enumerated type describes what kind of inconsistency was
     detected in an allocated block, if any.  Here are the possible
     values:

    `MCHECK_DISABLED'
          `mcheck' was not called before the first allocation.  No
          consistency checking can be done.

    `MCHECK_OK'
          No inconsistency detected.

    `MCHECK_HEAD'
          The data immediately before the block was modified.  This
          commonly happens when an array index or pointer is
          decremented too far.

    `MCHECK_TAIL'
          The data immediately after the block was modified.  This
          commonly happens when an array index or pointer is
          incremented too far.

    `MCHECK_FREE'
          The block was already freed.

   Another possibility to check for and guard against bugs in the use of
`malloc', `realloc' and `free' is to set the environment variable
`MALLOC_CHECK_'.  When `MALLOC_CHECK_' is set to a non-zero value, a
special (less efficient) implementation is used which is designed to be
tolerant against simple errors, such as double calls of `free' with the
same argument, or overruns of a single byte (off-by-one bugs).  Not all
such errors can be protected against, however, and memory leaks can
result.

   Any detected heap corruption results in immediate termination of the
process.

   There is one problem with `MALLOC_CHECK_': in SUID or SGID binaries
it could possibly be exploited since diverging from the normal programs
behavior it now writes something to the standard error descriptor.
Therefore the use of `MALLOC_CHECK_' is disabled by default for SUID
and SGID binaries.  It can be enabled again by the system administrator
by adding a file `/etc/suid-debug' (the content is not important it
could be empty).

   So, what's the difference between using `MALLOC_CHECK_' and linking
with `-lmcheck'?  `MALLOC_CHECK_' is orthogonal with respect to
`-lmcheck'.  `-lmcheck' has been added for backward compatibility.
Both `MALLOC_CHECK_' and `-lmcheck' should uncover the same bugs - but
using `MALLOC_CHECK_' you don't need to recompile your application.


File: libc.info,  Node: Hooks for Malloc,  Next: Statistics of Malloc,  Prev: Heap Consistency Checking,  Up: Unconstrained Allocation

3.2.3.9 Memory Allocation Hooks
...............................

The GNU C Library lets you modify the behavior of `malloc', `realloc',
and `free' by specifying appropriate hook functions.  You can use these
hooks to help you debug programs that use dynamic memory allocation,
for example.

   The hook variables are declared in `malloc.h'.  

 -- Variable: __malloc_hook
     The value of this variable is a pointer to the function that
     `malloc' uses whenever it is called.  You should define this
     function to look like `malloc'; that is, like:

          void *FUNCTION (size_t SIZE, const void *CALLER)

     The value of CALLER is the return address found on the stack when
     the `malloc' function was called.  This value allows you to trace
     the memory consumption of the program.

 -- Variable: __realloc_hook
     The value of this variable is a pointer to function that `realloc'
     uses whenever it is called.  You should define this function to
     look like `realloc'; that is, like:

          void *FUNCTION (void *PTR, size_t SIZE, const void *CALLER)

     The value of CALLER is the return address found on the stack when
     the `realloc' function was called.  This value allows you to trace
     the memory consumption of the program.

 -- Variable: __free_hook
     The value of this variable is a pointer to function that `free'
     uses whenever it is called.  You should define this function to
     look like `free'; that is, like:

          void FUNCTION (void *PTR, const void *CALLER)

     The value of CALLER is the return address found on the stack when
     the `free' function was called.  This value allows you to trace the
     memory consumption of the program.

 -- Variable: __memalign_hook
     The value of this variable is a pointer to function that
     `aligned_alloc', `memalign', `posix_memalign' and `valloc' use
     whenever they are called.  You should define this function to look
     like `aligned_alloc'; that is, like:

          void *FUNCTION (size_t ALIGNMENT, size_t SIZE, const void *CALLER)

     The value of CALLER is the return address found on the stack when
     the `aligned_alloc', `memalign', `posix_memalign' or `valloc'
     functions are called.  This value allows you to trace the memory
     consumption of the program.

   You must make sure that the function you install as a hook for one of
these functions does not call that function recursively without
restoring the old value of the hook first!  Otherwise, your program
will get stuck in an infinite recursion.  Before calling the function
recursively, one should make sure to restore all the hooks to their
previous value.  When coming back from the recursive call, all the
hooks should be resaved since a hook might modify itself.

   An issue to look out for is the time at which the malloc hook
functions can be safely installed.  If the hook functions call the
malloc-related functions recursively, it is necessary that malloc has
already properly initialized itself at the time when `__malloc_hook'
etc. is assigned to.  On the other hand, if the hook functions provide a
complete malloc implementation of their own, it is vital that the hooks
are assigned to _before_ the very first `malloc' call has completed,
because otherwise a chunk obtained from the ordinary, un-hooked malloc
may later be handed to `__free_hook', for example.

   Here is an example showing how to use `__malloc_hook' and
`__free_hook' properly.  It installs a function that prints out
information every time `malloc' or `free' is called.  We just assume
here that `realloc' and `memalign' are not used in our program.

     /* Prototypes for __malloc_hook, __free_hook */
     #include <malloc.h>

     /* Prototypes for our hooks.  */
     static void my_init_hook (void);
     static void *my_malloc_hook (size_t, const void *);
     static void my_free_hook (void*, const void *);

     static void
     my_init (void)
     {
       old_malloc_hook = __malloc_hook;
       old_free_hook = __free_hook;
       __malloc_hook = my_malloc_hook;
       __free_hook = my_free_hook;
     }

     static void *
     my_malloc_hook (size_t size, const void *caller)
     {
       void *result;
       /* Restore all old hooks */
       __malloc_hook = old_malloc_hook;
       __free_hook = old_free_hook;
       /* Call recursively */
       result = malloc (size);
       /* Save underlying hooks */
       old_malloc_hook = __malloc_hook;
       old_free_hook = __free_hook;
       /* `printf' might call `malloc', so protect it too. */
       printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
       /* Restore our own hooks */
       __malloc_hook = my_malloc_hook;
       __free_hook = my_free_hook;
       return result;
     }

     static void
     my_free_hook (void *ptr, const void *caller)
     {
       /* Restore all old hooks */
       __malloc_hook = old_malloc_hook;
       __free_hook = old_free_hook;
       /* Call recursively */
       free (ptr);
       /* Save underlying hooks */
       old_malloc_hook = __malloc_hook;
       old_free_hook = __free_hook;
       /* `printf' might call `free', so protect it too. */
       printf ("freed pointer %p\n", ptr);
       /* Restore our own hooks */
       __malloc_hook = my_malloc_hook;
       __free_hook = my_free_hook;
     }

     main ()
     {
       my_init ();
       ...
     }

   The `mcheck' function (*note Heap Consistency Checking::) works by
installing such hooks.


File: libc.info,  Node: Statistics of Malloc,  Next: Summary of Malloc,  Prev: Hooks for Malloc,  Up: Unconstrained Allocation

3.2.3.10 Statistics for Memory Allocation with `malloc'
.......................................................

You can get information about dynamic memory allocation by calling the
`mallinfo' function.  This function and its associated data type are
declared in `malloc.h'; they are an extension of the standard SVID/XPG
version.  

 -- Data Type: struct mallinfo
     This structure type is used to return information about the dynamic
     memory allocator.  It contains the following members:

    `int arena'
          This is the total size of memory allocated with `sbrk' by
          `malloc', in bytes.

    `int ordblks'
          This is the number of chunks not in use.  (The memory
          allocator internally gets chunks of memory from the operating
          system, and then carves them up to satisfy individual
          `malloc' requests; *note The GNU Allocator::.)

    `int smblks'
          This field is unused.

    `int hblks'
          This is the total number of chunks allocated with `mmap'.

    `int hblkhd'
          This is the total size of memory allocated with `mmap', in
          bytes.

    `int usmblks'
          This field is unused and always 0.

    `int fsmblks'
          This field is unused.

    `int uordblks'
          This is the total size of memory occupied by chunks handed
          out by `malloc'.

    `int fordblks'
          This is the total size of memory occupied by free (not in
          use) chunks.

    `int keepcost'
          This is the size of the top-most releasable chunk that
          normally borders the end of the heap (i.e., the high end of
          the virtual address space's data segment).


 -- Function: struct mallinfo mallinfo (void)
     Preliminary: | MT-Unsafe init const:mallopt | AS-Unsafe init lock
     | AC-Unsafe init lock | *Note POSIX Safety Concepts::.

     This function returns information about the current dynamic memory
     usage in a structure of type `struct mallinfo'.


File: libc.info,  Node: Summary of Malloc,  Prev: Statistics of Malloc,  Up: Unconstrained Allocation

3.2.3.11 Summary of `malloc'-Related Functions
..............................................

Here is a summary of the functions that work with `malloc':

`void *malloc (size_t SIZE)'
     Allocate a block of SIZE bytes.  *Note Basic Allocation::.

`void free (void *ADDR)'
     Free a block previously allocated by `malloc'.  *Note Freeing
     after Malloc::.

`void *realloc (void *ADDR, size_t SIZE)'
     Make a block previously allocated by `malloc' larger or smaller,
     possibly by copying it to a new location.  *Note Changing Block
     Size::.

`void *reallocarray (void *PTR, size_t NMEMB, size_t SIZE)'
     Change the size of a block previously allocated by `malloc' to
     `NMEMB * SIZE' bytes as with `realloc'.  *Note Changing Block
     Size::.

`void *calloc (size_t COUNT, size_t ELTSIZE)'
     Allocate a block of COUNT * ELTSIZE bytes using `malloc', and set
     its contents to zero.  *Note Allocating Cleared Space::.

`void *valloc (size_t SIZE)'
     Allocate a block of SIZE bytes, starting on a page boundary.
     *Note Aligned Memory Blocks::.

`void *aligned_alloc (size_t SIZE, size_t ALIGNMENT)'
     Allocate a block of SIZE bytes, starting on an address that is a
     multiple of ALIGNMENT.  *Note Aligned Memory Blocks::.

`int posix_memalign (void **MEMPTR, size_t ALIGNMENT, size_t SIZE)'
     Allocate a block of SIZE bytes, starting on an address that is a
     multiple of ALIGNMENT.  *Note Aligned Memory Blocks::.

`void *memalign (size_t SIZE, size_t BOUNDARY)'
     Allocate a block of SIZE bytes, starting on an address that is a
     multiple of BOUNDARY.  *Note Aligned Memory Blocks::.

`int mallopt (int PARAM, int VALUE)'
     Adjust a tunable parameter.  *Note Malloc Tunable Parameters::.

`int mcheck (void (*ABORTFN) (void))'
     Tell `malloc' to perform occasional consistency checks on
     dynamically allocated memory, and to call ABORTFN when an
     inconsistency is found.  *Note Heap Consistency Checking::.

`void *(*__malloc_hook) (size_t SIZE, const void *CALLER)'
     A pointer to a function that `malloc' uses whenever it is called.

`void *(*__realloc_hook) (void *PTR, size_t SIZE, const void *CALLER)'
     A pointer to a function that `realloc' uses whenever it is called.

`void (*__free_hook) (void *PTR, const void *CALLER)'
     A pointer to a function that `free' uses whenever it is called.

`void (*__memalign_hook) (size_t SIZE, size_t ALIGNMENT, const void *CALLER)'
     A pointer to a function that `aligned_alloc', `memalign',
     `posix_memalign' and `valloc' use whenever they are called.

`struct mallinfo mallinfo (void)'
     Return information about the current dynamic memory usage.  *Note
     Statistics of Malloc::.


File: libc.info,  Node: Allocation Debugging,  Next: Replacing malloc,  Prev: Unconstrained Allocation,  Up: Memory Allocation

3.2.4 Allocation Debugging
--------------------------

A complicated task when programming with languages which do not use
garbage collected dynamic memory allocation is to find memory leaks.
Long running programs must ensure that dynamically allocated objects are
freed at the end of their lifetime.  If this does not happen the system
runs out of memory, sooner or later.

   The `malloc' implementation in the GNU C Library provides some
simple means to detect such leaks and obtain some information to find
the location.  To do this the application must be started in a special
mode which is enabled by an environment variable.  There are no speed
penalties for the program if the debugging mode is not enabled.

* Menu:

* Tracing malloc::               How to install the tracing functionality.
* Using the Memory Debugger::    Example programs excerpts.
* Tips for the Memory Debugger:: Some more or less clever ideas.
* Interpreting the traces::      What do all these lines mean?


File: libc.info,  Node: Tracing malloc,  Next: Using the Memory Debugger,  Up: Allocation Debugging

3.2.4.1 How to install the tracing functionality
................................................

 -- Function: void mtrace (void)
     Preliminary: | MT-Unsafe env race:mtrace const:malloc_hooks init |
     AS-Unsafe init heap corrupt lock | AC-Unsafe init corrupt lock fd
     mem | *Note POSIX Safety Concepts::.

     When the `mtrace' function is called it looks for an environment
     variable named `MALLOC_TRACE'.  This variable is supposed to
     contain a valid file name.  The user must have write access.  If
     the file already exists it is truncated.  If the environment
     variable is not set or it does not name a valid file which can be
     opened for writing nothing is done.  The behavior of `malloc' etc.
     is not changed.  For obvious reasons this also happens if the
     application is installed with the SUID or SGID bit set.

     If the named file is successfully opened, `mtrace' installs special
     handlers for the functions `malloc', `realloc', and `free' (*note
     Hooks for Malloc::).  From then on, all uses of these functions
     are traced and protocolled into the file.  There is now of course
     a speed penalty for all calls to the traced functions so tracing
     should not be enabled during normal use.

     This function is a GNU extension and generally not available on
     other systems.  The prototype can be found in `mcheck.h'.

 -- Function: void muntrace (void)
     Preliminary: | MT-Unsafe race:mtrace const:malloc_hooks locale |
     AS-Unsafe corrupt heap | AC-Unsafe corrupt mem lock fd | *Note
     POSIX Safety Concepts::.

     The `muntrace' function can be called after `mtrace' was used to
     enable tracing the `malloc' calls.  If no (successful) call of
     `mtrace' was made `muntrace' does nothing.

     Otherwise it deinstalls the handlers for `malloc', `realloc', and
     `free' and then closes the protocol file.  No calls are
     protocolled anymore and the program runs again at full speed.

     This function is a GNU extension and generally not available on
     other systems.  The prototype can be found in `mcheck.h'.


File: libc.info,  Node: Using the Memory Debugger,  Next: Tips for the Memory Debugger,  Prev: Tracing malloc,  Up: Allocation Debugging

3.2.4.2 Example program excerpts
................................

Even though the tracing functionality does not influence the runtime
behavior of the program it is not a good idea to call `mtrace' in all
programs.  Just imagine that you debug a program using `mtrace' and all
other programs used in the debugging session also trace their `malloc'
calls.  The output file would be the same for all programs and thus is
unusable.  Therefore one should call `mtrace' only if compiled for
debugging.  A program could therefore start like this:

     #include <mcheck.h>

     int
     main (int argc, char *argv[])
     {
     #ifdef DEBUGGING
       mtrace ();
     #endif
       ...
     }

   This is all that is needed if you want to trace the calls during the
whole runtime of the program.  Alternatively you can stop the tracing at
any time with a call to `muntrace'.  It is even possible to restart the
tracing again with a new call to `mtrace'.  But this can cause
unreliable results since there may be calls of the functions which are
not called.  Please note that not only the application uses the traced
functions, also libraries (including the C library itself) use these
functions.

   This last point is also why it is not a good idea to call `muntrace'
before the program terminates.  The libraries are informed about the
termination of the program only after the program returns from `main'
or calls `exit' and so cannot free the memory they use before this time.

   So the best thing one can do is to call `mtrace' as the very first
function in the program and never call `muntrace'.  So the program
traces almost all uses of the `malloc' functions (except those calls
which are executed by constructors of the program or used libraries).


File: libc.info,  Node: Tips for the Memory Debugger,  Next: Interpreting the traces,  Prev: Using the Memory Debugger,  Up: Allocation Debugging

3.2.4.3 Some more or less clever ideas
......................................

You know the situation.  The program is prepared for debugging and in
all debugging sessions it runs well.  But once it is started without
debugging the error shows up.  A typical example is a memory leak that
becomes visible only when we turn off the debugging.  If you foresee
such situations you can still win.  Simply use something equivalent to
the following little program:

     #include <mcheck.h>
     #include <signal.h>

     static void
     enable (int sig)
     {
       mtrace ();
       signal (SIGUSR1, enable);
     }

     static void
     disable (int sig)
     {
       muntrace ();
       signal (SIGUSR2, disable);
     }

     int
     main (int argc, char *argv[])
     {
       ...

       signal (SIGUSR1, enable);
       signal (SIGUSR2, disable);

       ...
     }

   I.e., the user can start the memory debugger any time s/he wants if
the program was started with `MALLOC_TRACE' set in the environment.
The output will of course not show the allocations which happened before
the first signal but if there is a memory leak this will show up
nevertheless.


File: libc.info,  Node: Interpreting the traces,  Prev: Tips for the Memory Debugger,  Up: Allocation Debugging

3.2.4.4 Interpreting the traces
...............................

If you take a look at the output it will look similar to this:

     = Start
      [0x8048209] - 0x8064cc8
      [0x8048209] - 0x8064ce0
      [0x8048209] - 0x8064cf8
      [0x80481eb] + 0x8064c48 0x14
      [0x80481eb] + 0x8064c60 0x14
      [0x80481eb] + 0x8064c78 0x14
      [0x80481eb] + 0x8064c90 0x14
     = End

   What this all means is not really important since the trace file is
not meant to be read by a human.  Therefore no attention is given to
readability.  Instead there is a program which comes with the GNU C
Library which interprets the traces and outputs a summary in an
user-friendly way.  The program is called `mtrace' (it is in fact a
Perl script) and it takes one or two arguments.  In any case the name of
the file with the trace output must be specified.  If an optional
argument precedes the name of the trace file this must be the name of
the program which generated the trace.

     drepper$ mtrace tst-mtrace log
     No memory leaks.

   In this case the program `tst-mtrace' was run and it produced a
trace file `log'.  The message printed by `mtrace' shows there are no
problems with the code, all allocated memory was freed afterwards.

   If we call `mtrace' on the example trace given above we would get a
different outout:

     drepper$ mtrace errlog
     - 0x08064cc8 Free 2 was never alloc'd 0x8048209
     - 0x08064ce0 Free 3 was never alloc'd 0x8048209
     - 0x08064cf8 Free 4 was never alloc'd 0x8048209

     Memory not freed:
     -----------------
        Address     Size     Caller
     0x08064c48     0x14  at 0x80481eb
     0x08064c60     0x14  at 0x80481eb
     0x08064c78     0x14  at 0x80481eb
     0x08064c90     0x14  at 0x80481eb

   We have called `mtrace' with only one argument and so the script has
no chance to find out what is meant with the addresses given in the
trace.  We can do better:

     drepper$ mtrace tst errlog
     - 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
     - 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
     - 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39

     Memory not freed:
     -----------------
        Address     Size     Caller
     0x08064c48     0x14  at /home/drepper/tst.c:33
     0x08064c60     0x14  at /home/drepper/tst.c:33
     0x08064c78     0x14  at /home/drepper/tst.c:33
     0x08064c90     0x14  at /home/drepper/tst.c:33

   Suddenly the output makes much more sense and the user can see
immediately where the function calls causing the trouble can be found.

   Interpreting this output is not complicated.  There are at most two
different situations being detected.  First, `free' was called for
pointers which were never returned by one of the allocation functions.
This is usually a very bad problem and what this looks like is shown in
the first three lines of the output.  Situations like this are quite
rare and if they appear they show up very drastically: the program
normally crashes.

   The other situation which is much harder to detect are memory leaks.
As you can see in the output the `mtrace' function collects all this
information and so can say that the program calls an allocation function
from line 33 in the source file `/home/drepper/tst-mtrace.c' four times
without freeing this memory before the program terminates.  Whether
this is a real problem remains to be investigated.


File: libc.info,  Node: Replacing malloc,  Next: Obstacks,  Prev: Allocation Debugging,  Up: Memory Allocation

3.2.5 Replacing `malloc'
------------------------

The GNU C Library supports replacing the built-in `malloc'
implementation with a different allocator with the same interface.  For
dynamically linked programs, this happens through ELF symbol
interposition, either using shared object dependencies or `LD_PRELOAD'.
For static linking, the `malloc' replacement library must be linked in
before linking against `libc.a' (explicitly or implicitly).

   *Note_* Failure to provide a complete set of replacement functions
(that is, all the functions used by the application, the GNU C Library,
and other linked-in libraries) can lead to static linking failures,
and, at run time, to heap corruption and application crashes.

   The minimum set of functions which has to be provided by a custom
`malloc' is given in the table below.

`malloc'

`free'

`calloc'

`realloc'

   These `malloc'-related functions are required for the GNU C Library
to work.(1)

   The `malloc' implementation in the GNU C Library provides additional
functionality not used by the library itself, but which is often used by
other system libraries and applications.  A general-purpose replacement
`malloc' implementation should provide definitions of these functions,
too.  Their names are listed in the following table.

`aligned_alloc'

`malloc_usable_size'

`memalign'

`posix_memalign'

`pvalloc'

`valloc'

   In addition, very old applications may use the obsolete `cfree'
function.

   Further `malloc'-related functions such as `mallopt' or `mallinfo'
will not have any effect or return incorrect statistics when a
replacement `malloc' is in use.  However, failure to replace these
functions typically does not result in crashes or other incorrect
application behavior, but may result in static linking failures.

   ---------- Footnotes ----------

   (1) Versions of the GNU C Library before 2.25 required that a custom
`malloc' defines `__libc_memalign' (with the same interface as the
`memalign' function).


File: libc.info,  Node: Obstacks,  Next: Variable Size Automatic,  Prev: Replacing malloc,  Up: Memory Allocation

3.2.6 Obstacks
--------------

An "obstack" is a pool of memory containing a stack of objects.  You
can create any number of separate obstacks, and then allocate objects in
specified obstacks.  Within each obstack, the last object allocated must
always be the first one freed, but distinct obstacks are independent of
each other.

   Aside from this one constraint of order of freeing, obstacks are
totally general: an obstack can contain any number of objects of any
size.  They are implemented with macros, so allocation is usually very
fast as long as the objects are usually small.  And the only space
overhead per object is the padding needed to start each object on a
suitable boundary.

* Menu:

* Creating Obstacks::		How to declare an obstack in your program.
* Preparing for Obstacks::	Preparations needed before you can
				 use obstacks.
* Allocation in an Obstack::    Allocating objects in an obstack.
* Freeing Obstack Objects::     Freeing objects in an obstack.
* Obstack Functions::		The obstack functions are both
				 functions and macros.
* Growing Objects::             Making an object bigger by stages.
* Extra Fast Growing::		Extra-high-efficiency (though more
				 complicated) growing objects.
* Status of an Obstack::        Inquiries about the status of an obstack.
* Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
* Obstack Chunks::              How obstacks obtain and release chunks;
				 efficiency considerations.
* Summary of Obstacks::


File: libc.info,  Node: Creating Obstacks,  Next: Preparing for Obstacks,  Up: Obstacks

3.2.6.1 Creating Obstacks
.........................

The utilities for manipulating obstacks are declared in the header file
`obstack.h'.  

 -- Data Type: struct obstack
     An obstack is represented by a data structure of type `struct
     obstack'.  This structure has a small fixed size; it records the
     status of the obstack and how to find the space in which objects
     are allocated.  It does not contain any of the objects themselves.
     You should not try to access the contents of the structure
     directly; use only the functions described in this chapter.

   You can declare variables of type `struct obstack' and use them as
obstacks, or you can allocate obstacks dynamically like any other kind
of object.  Dynamic allocation of obstacks allows your program to have a
variable number of different stacks.  (You can even allocate an obstack
structure in another obstack, but this is rarely useful.)

   All the functions that work with obstacks require you to specify
which obstack to use.  You do this with a pointer of type `struct
obstack *'.  In the following, we often say "an obstack" when strictly
speaking the object at hand is such a pointer.

   The objects in the obstack are packed into large blocks called
"chunks".  The `struct obstack' structure points to a chain of the
chunks currently in use.

   The obstack library obtains a new chunk whenever you allocate an
object that won't fit in the previous chunk.  Since the obstack library
manages chunks automatically, you don't need to pay much attention to
them, but you do need to supply a function which the obstack library
should use to get a chunk.  Usually you supply a function which uses
`malloc' directly or indirectly.  You must also supply a function to
free a chunk.  These matters are described in the following section.


File: libc.info,  Node: Preparing for Obstacks,  Next: Allocation in an Obstack,  Prev: Creating Obstacks,  Up: Obstacks

3.2.6.2 Preparing for Using Obstacks
....................................

Each source file in which you plan to use the obstack functions must
include the header file `obstack.h', like this:

     #include <obstack.h>

   Also, if the source file uses the macro `obstack_init', it must
declare or define two functions or macros that will be called by the
obstack library.  One, `obstack_chunk_alloc', is used to allocate the
chunks of memory into which objects are packed.  The other,
`obstack_chunk_free', is used to return chunks when the objects in them
are freed.  These macros should appear before any use of obstacks in
the source file.

   Usually these are defined to use `malloc' via the intermediary
`xmalloc' (*note Unconstrained Allocation::).  This is done with the
following pair of macro definitions:

     #define obstack_chunk_alloc xmalloc
     #define obstack_chunk_free free

Though the memory you get using obstacks really comes from `malloc',
using obstacks is faster because `malloc' is called less often, for
larger blocks of memory.  *Note Obstack Chunks::, for full details.

   At run time, before the program can use a `struct obstack' object as
an obstack, it must initialize the obstack by calling `obstack_init'.

 -- Function: int obstack_init (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe mem |
     *Note POSIX Safety Concepts::.

     Initialize obstack OBSTACK-PTR for allocation of objects.  This
     function calls the obstack's `obstack_chunk_alloc' function.  If
     allocation of memory fails, the function pointed to by
     `obstack_alloc_failed_handler' is called.  The `obstack_init'
     function always returns 1 (Compatibility notice: Former versions of
     obstack returned 0 if allocation failed).

   Here are two examples of how to allocate the space for an obstack and
initialize it.  First, an obstack that is a static variable:

     static struct obstack myobstack;
     ...
     obstack_init (&myobstack);

Second, an obstack that is itself dynamically allocated:

     struct obstack *myobstack_ptr
       = (struct obstack *) xmalloc (sizeof (struct obstack));

     obstack_init (myobstack_ptr);

 -- Variable: obstack_alloc_failed_handler
     The value of this variable is a pointer to a function that
     `obstack' uses when `obstack_chunk_alloc' fails to allocate
     memory.  The default action is to print a message and abort.  You
     should supply a function that either calls `exit' (*note Program
     Termination::) or `longjmp' (*note Non-Local Exits::) and doesn't
     return.

          void my_obstack_alloc_failed (void)
          ...
          obstack_alloc_failed_handler = &my_obstack_alloc_failed;



File: libc.info,  Node: Allocation in an Obstack,  Next: Freeing Obstack Objects,  Prev: Preparing for Obstacks,  Up: Obstacks

3.2.6.3 Allocation in an Obstack
................................

The most direct way to allocate an object in an obstack is with
`obstack_alloc', which is invoked almost like `malloc'.

 -- Function: void * obstack_alloc (struct obstack *OBSTACK-PTR, int
          SIZE)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     This allocates an uninitialized block of SIZE bytes in an obstack
     and returns its address.  Here OBSTACK-PTR specifies which obstack
     to allocate the block in; it is the address of the `struct obstack'
     object which represents the obstack.  Each obstack function or
     macro requires you to specify an OBSTACK-PTR as the first argument.

     This function calls the obstack's `obstack_chunk_alloc' function if
     it needs to allocate a new chunk of memory; it calls
     `obstack_alloc_failed_handler' if allocation of memory by
     `obstack_chunk_alloc' failed.

   For example, here is a function that allocates a copy of a string STR
in a specific obstack, which is in the variable `string_obstack':

     struct obstack string_obstack;

     char *
     copystring (char *string)
     {
       size_t len = strlen (string) + 1;
       char *s = (char *) obstack_alloc (&string_obstack, len);
       memcpy (s, string, len);
       return s;
     }

   To allocate a block with specified contents, use the function
`obstack_copy', declared like this:

 -- Function: void * obstack_copy (struct obstack *OBSTACK-PTR, void
          *ADDRESS, int SIZE)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     This allocates a block and initializes it by copying SIZE bytes of
     data starting at ADDRESS.  It calls `obstack_alloc_failed_handler'
     if allocation of memory by `obstack_chunk_alloc' failed.

 -- Function: void * obstack_copy0 (struct obstack *OBSTACK-PTR, void
          *ADDRESS, int SIZE)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     Like `obstack_copy', but appends an extra byte containing a null
     character.  This extra byte is not counted in the argument SIZE.

   The `obstack_copy0' function is convenient for copying a sequence of
characters into an obstack as a null-terminated string.  Here is an
example of its use:

     char *
     obstack_savestring (char *addr, int size)
     {
       return obstack_copy0 (&myobstack, addr, size);
     }

Contrast this with the previous example of `savestring' using `malloc'
(*note Basic Allocation::).


File: libc.info,  Node: Freeing Obstack Objects,  Next: Obstack Functions,  Prev: Allocation in an Obstack,  Up: Obstacks

3.2.6.4 Freeing Objects in an Obstack
.....................................

To free an object allocated in an obstack, use the function
`obstack_free'.  Since the obstack is a stack of objects, freeing one
object automatically frees all other objects allocated more recently in
the same obstack.

 -- Function: void obstack_free (struct obstack *OBSTACK-PTR, void
          *OBJECT)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt | *Note POSIX Safety Concepts::.

     If OBJECT is a null pointer, everything allocated in the obstack
     is freed.  Otherwise, OBJECT must be the address of an object
     allocated in the obstack.  Then OBJECT is freed, along with
     everything allocated in OBSTACK-PTR since OBJECT.

   Note that if OBJECT is a null pointer, the result is an
uninitialized obstack.  To free all memory in an obstack but leave it
valid for further allocation, call `obstack_free' with the address of
the first object allocated on the obstack:

     obstack_free (obstack_ptr, first_object_allocated_ptr);

   Recall that the objects in an obstack are grouped into chunks.  When
all the objects in a chunk become free, the obstack library
automatically frees the chunk (*note Preparing for Obstacks::).  Then
other obstacks, or non-obstack allocation, can reuse the space of the
chunk.


File: libc.info,  Node: Obstack Functions,  Next: Growing Objects,  Prev: Freeing Obstack Objects,  Up: Obstacks

3.2.6.5 Obstack Functions and Macros
....................................

The interfaces for using obstacks may be defined either as functions or
as macros, depending on the compiler.  The obstack facility works with
all C compilers, including both ISO C and traditional C, but there are
precautions you must take if you plan to use compilers other than GNU C.

   If you are using an old-fashioned non-ISO C compiler, all the obstack
"functions" are actually defined only as macros.  You can call these
macros like functions, but you cannot use them in any other way (for
example, you cannot take their address).

   Calling the macros requires a special precaution: namely, the first
operand (the obstack pointer) may not contain any side effects, because
it may be computed more than once.  For example, if you write this:

     obstack_alloc (get_obstack (), 4);

you will find that `get_obstack' may be called several times.  If you
use `*obstack_list_ptr++' as the obstack pointer argument, you will get
very strange results since the incrementation may occur several times.

   In ISO C, each function has both a macro definition and a function
definition.  The function definition is used if you take the address of
the function without calling it.  An ordinary call uses the macro
definition by default, but you can request the function definition
instead by writing the function name in parentheses, as shown here:

     char *x;
     void *(*funcp) ();
     /* Use the macro.  */
     x = (char *) obstack_alloc (obptr, size);
     /* Call the function.  */
     x = (char *) (obstack_alloc) (obptr, size);
     /* Take the address of the function.  */
     funcp = obstack_alloc;

This is the same situation that exists in ISO C for the standard library
functions.  *Note Macro Definitions::.

   *Warning:* When you do use the macros, you must observe the
precaution of avoiding side effects in the first operand, even in ISO C.

   If you use the GNU C compiler, this precaution is not necessary,
because various language extensions in GNU C permit defining the macros
so as to compute each argument only once.


File: libc.info,  Node: Growing Objects,  Next: Extra Fast Growing,  Prev: Obstack Functions,  Up: Obstacks

3.2.6.6 Growing Objects
.......................

Because memory in obstack chunks is used sequentially, it is possible to
build up an object step by step, adding one or more bytes at a time to
the end of the object.  With this technique, you do not need to know
how much data you will put in the object until you come to the end of
it.  We call this the technique of "growing objects".  The special
functions for adding data to the growing object are described in this
section.

   You don't need to do anything special when you start to grow an
object.  Using one of the functions to add data to the object
automatically starts it.  However, it is necessary to say explicitly
when the object is finished.  This is done with the function
`obstack_finish'.

   The actual address of the object thus built up is not known until the
object is finished.  Until then, it always remains possible that you
will add so much data that the object must be copied into a new chunk.

   While the obstack is in use for a growing object, you cannot use it
for ordinary allocation of another object.  If you try to do so, the
space already added to the growing object will become part of the other
object.

 -- Function: void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     The most basic function for adding to a growing object is
     `obstack_blank', which adds space without initializing it.

 -- Function: void obstack_grow (struct obstack *OBSTACK-PTR, void
          *DATA, int SIZE)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     To add a block of initialized space, use `obstack_grow', which is
     the growing-object analogue of `obstack_copy'.  It adds SIZE bytes
     of data to the growing object, copying the contents from DATA.

 -- Function: void obstack_grow0 (struct obstack *OBSTACK-PTR, void
          *DATA, int SIZE)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     This is the growing-object analogue of `obstack_copy0'.  It adds
     SIZE bytes copied from DATA, followed by an additional null
     character.

 -- Function: void obstack_1grow (struct obstack *OBSTACK-PTR, char C)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     To add one character at a time, use the function `obstack_1grow'.
     It adds a single byte containing C to the growing object.

 -- Function: void obstack_ptr_grow (struct obstack *OBSTACK-PTR, void
          *DATA)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     Adding the value of a pointer one can use the function
     `obstack_ptr_grow'.  It adds `sizeof (void *)' bytes containing
     the value of DATA.

 -- Function: void obstack_int_grow (struct obstack *OBSTACK-PTR, int
          DATA)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     A single value of type `int' can be added by using the
     `obstack_int_grow' function.  It adds `sizeof (int)' bytes to the
     growing object and initializes them with the value of DATA.

 -- Function: void * obstack_finish (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt | *Note POSIX Safety Concepts::.

     When you are finished growing the object, use the function
     `obstack_finish' to close it off and return its final address.

     Once you have finished the object, the obstack is available for
     ordinary allocation or for growing another object.

     This function can return a null pointer under the same conditions
     as `obstack_alloc' (*note Allocation in an Obstack::).

   When you build an object by growing it, you will probably need to
know afterward how long it became.  You need not keep track of this as
you grow the object, because you can find out the length from the
obstack just before finishing the object with the function
`obstack_object_size', declared as follows:

 -- Function: int obstack_object_size (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe |
     *Note POSIX Safety Concepts::.

     This function returns the current size of the growing object, in
     bytes.  Remember to call this function _before_ finishing the
     object.  After it is finished, `obstack_object_size' will return
     zero.

   If you have started growing an object and wish to cancel it, you
should finish it and then free it, like this:

     obstack_free (obstack_ptr, obstack_finish (obstack_ptr));

This has no effect if no object was growing.

   You can use `obstack_blank' with a negative size argument to make
the current object smaller.  Just don't try to shrink it beyond zero
length--there's no telling what will happen if you do that.


File: libc.info,  Node: Extra Fast Growing,  Next: Status of an Obstack,  Prev: Growing Objects,  Up: Obstacks

3.2.6.7 Extra Fast Growing Objects
..................................

The usual functions for growing objects incur overhead for checking
whether there is room for the new growth in the current chunk.  If you
are frequently constructing objects in small steps of growth, this
overhead can be significant.

   You can reduce the overhead by using special "fast growth" functions
that grow the object without checking.  In order to have a robust
program, you must do the checking yourself.  If you do this checking in
the simplest way each time you are about to add data to the object, you
have not saved anything, because that is what the ordinary growth
functions do.  But if you can arrange to check less often, or check
more efficiently, then you make the program faster.

   The function `obstack_room' returns the amount of room available in
the current chunk.  It is declared as follows:

 -- Function: int obstack_room (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe |
     *Note POSIX Safety Concepts::.

     This returns the number of bytes that can be added safely to the
     current growing object (or to an object about to be started) in
     obstack OBSTACK-PTR using the fast growth functions.

   While you know there is room, you can use these fast growth functions
for adding data to a growing object:

 -- Function: void obstack_1grow_fast (struct obstack *OBSTACK-PTR,
          char C)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
     corrupt mem | *Note POSIX Safety Concepts::.

     The function `obstack_1grow_fast' adds one byte containing the
     character C to the growing object in obstack OBSTACK-PTR.

 -- Function: void obstack_ptr_grow_fast (struct obstack *OBSTACK-PTR,
          void *DATA)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe |
     *Note POSIX Safety Concepts::.

     The function `obstack_ptr_grow_fast' adds `sizeof (void *)' bytes
     containing the value of DATA to the growing object in obstack
     OBSTACK-PTR.

 -- Function: void obstack_int_grow_fast (struct obstack *OBSTACK-PTR,
          int DATA)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe |
     *Note POSIX Safety Concepts::.

     The function `obstack_int_grow_fast' adds `sizeof (int)' bytes
     containing the value of DATA to the growing object in obstack
     OBSTACK-PTR.

 -- Function: void obstack_blank_fast (struct obstack *OBSTACK-PTR, int
          SIZE)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe |
     *Note POSIX Safety Concepts::.

     The function `obstack_blank_fast' adds SIZE bytes to the growing
     object in obstack OBSTACK-PTR without initializing them.

   When you check for space using `obstack_room' and there is not
enough room for what you want to add, the fast growth functions are not
safe.  In this case, simply use the corresponding ordinary growth
function instead.  Very soon this will copy the object to a new chunk;
then there will be lots of room available again.

   So, each time you use an ordinary growth function, check afterward
for sufficient space using `obstack_room'.  Once the object is copied
to a new chunk, there will be plenty of space again, so the program will
start using the fast growth functions again.

   Here is an example:

     void
     add_string (struct obstack *obstack, const char *ptr, int len)
     {
       while (len > 0)
         {
           int room = obstack_room (obstack);
           if (room == 0)
             {
               /* Not enough room.  Add one character slowly,
                  which may copy to a new chunk and make room.  */
               obstack_1grow (obstack, *ptr++);
               len--;
             }
           else
             {
               if (room > len)
                 room = len;
               /* Add fast as much as we have room for. */
               len -= room;
               while (room-- > 0)
                 obstack_1grow_fast (obstack, *ptr++);
             }
         }
     }


File: libc.info,  Node: Status of an Obstack,  Next: Obstacks Data Alignment,  Prev: Extra Fast Growing,  Up: Obstacks

3.2.6.8 Status of an Obstack
............................

Here are functions that provide information on the current status of
allocation in an obstack.  You can use them to learn about an object
while still growing it.

 -- Function: void * obstack_base (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | *Note POSIX
     Safety Concepts::.

     This function returns the tentative address of the beginning of the
     currently growing object in OBSTACK-PTR.  If you finish the object
     immediately, it will have that address.  If you make it larger
     first, it may outgrow the current chunk--then its address will
     change!

     If no object is growing, this value says where the next object you
     allocate will start (once again assuming it fits in the current
     chunk).

 -- Function: void * obstack_next_free (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | *Note POSIX
     Safety Concepts::.

     This function returns the address of the first free byte in the
     current chunk of obstack OBSTACK-PTR.  This is the end of the
     currently growing object.  If no object is growing,
     `obstack_next_free' returns the same value as `obstack_base'.

 -- Function: int obstack_object_size (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe |
     *Note POSIX Safety Concepts::.

     This function returns the size in bytes of the currently growing
     object.  This is equivalent to

          obstack_next_free (OBSTACK-PTR) - obstack_base (OBSTACK-PTR)


File: libc.info,  Node: Obstacks Data Alignment,  Next: Obstack Chunks,  Prev: Status of an Obstack,  Up: Obstacks

3.2.6.9 Alignment of Data in Obstacks
.....................................

Each obstack has an "alignment boundary"; each object allocated in the
obstack automatically starts on an address that is a multiple of the
specified boundary.  By default, this boundary is aligned so that the
object can hold any type of data.

   To access an obstack's alignment boundary, use the macro
`obstack_alignment_mask', whose function prototype looks like this:

 -- Macro: int obstack_alignment_mask (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     The value is a bit mask; a bit that is 1 indicates that the
     corresponding bit in the address of an object should be 0.  The
     mask value should be one less than a power of 2; the effect is
     that all object addresses are multiples of that power of 2.  The
     default value of the mask is a value that allows aligned objects
     to hold any type of data: for example, if its value is 3, any type
     of data can be stored at locations whose addresses are multiples
     of 4.  A mask value of 0 means an object can start on any multiple
     of 1 (that is, no alignment is required).

     The expansion of the macro `obstack_alignment_mask' is an lvalue,
     so you can alter the mask by assignment.  For example, this
     statement:

          obstack_alignment_mask (obstack_ptr) = 0;

     has the effect of turning off alignment processing in the
     specified obstack.

   Note that a change in alignment mask does not take effect until
_after_ the next time an object is allocated or finished in the
obstack.  If you are not growing an object, you can make the new
alignment mask take effect immediately by calling `obstack_finish'.
This will finish a zero-length object and then do proper alignment for
the next object.


File: libc.info,  Node: Obstack Chunks,  Next: Summary of Obstacks,  Prev: Obstacks Data Alignment,  Up: Obstacks

3.2.6.10 Obstack Chunks
.......................

Obstacks work by allocating space for themselves in large chunks, and
then parceling out space in the chunks to satisfy your requests.  Chunks
are normally 4096 bytes long unless you specify a different chunk size.
The chunk size includes 8 bytes of overhead that are not actually used
for storing objects.  Regardless of the specified size, longer chunks
will be allocated when necessary for long objects.

   The obstack library allocates chunks by calling the function
`obstack_chunk_alloc', which you must define.  When a chunk is no
longer needed because you have freed all the objects in it, the obstack
library frees the chunk by calling `obstack_chunk_free', which you must
also define.

   These two must be defined (as macros) or declared (as functions) in
each source file that uses `obstack_init' (*note Creating Obstacks::).
Most often they are defined as macros like this:

     #define obstack_chunk_alloc malloc
     #define obstack_chunk_free free

   Note that these are simple macros (no arguments).  Macro definitions
with arguments will not work!  It is necessary that
`obstack_chunk_alloc' or `obstack_chunk_free', alone, expand into a
function name if it is not itself a function name.

   If you allocate chunks with `malloc', the chunk size should be a
power of 2.  The default chunk size, 4096, was chosen because it is long
enough to satisfy many typical requests on the obstack yet short enough
not to waste too much memory in the portion of the last chunk not yet
used.

 -- Macro: int obstack_chunk_size (struct obstack *OBSTACK-PTR)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     This returns the chunk size of the given obstack.

   Since this macro expands to an lvalue, you can specify a new chunk
size by assigning it a new value.  Doing so does not affect the chunks
already allocated, but will change the size of chunks allocated for
that particular obstack in the future.  It is unlikely to be useful to
make the chunk size smaller, but making it larger might improve
efficiency if you are allocating many objects whose size is comparable
to the chunk size.  Here is how to do so cleanly:

     if (obstack_chunk_size (obstack_ptr) < NEW-CHUNK-SIZE)
       obstack_chunk_size (obstack_ptr) = NEW-CHUNK-SIZE;


File: libc.info,  Node: Summary of Obstacks,  Prev: Obstack Chunks,  Up: Obstacks

3.2.6.11 Summary of Obstack Functions
.....................................

Here is a summary of all the functions associated with obstacks.  Each
takes the address of an obstack (`struct obstack *') as its first
argument.

`void obstack_init (struct obstack *OBSTACK-PTR)'
     Initialize use of an obstack.  *Note Creating Obstacks::.

`void *obstack_alloc (struct obstack *OBSTACK-PTR, int SIZE)'
     Allocate an object of SIZE uninitialized bytes.  *Note Allocation
     in an Obstack::.

`void *obstack_copy (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
     Allocate an object of SIZE bytes, with contents copied from
     ADDRESS.  *Note Allocation in an Obstack::.

`void *obstack_copy0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
     Allocate an object of SIZE+1 bytes, with SIZE of them copied from
     ADDRESS, followed by a null character at the end.  *Note
     Allocation in an Obstack::.

`void obstack_free (struct obstack *OBSTACK-PTR, void *OBJECT)'
     Free OBJECT (and everything allocated in the specified obstack
     more recently than OBJECT).  *Note Freeing Obstack Objects::.

`void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)'
     Add SIZE uninitialized bytes to a growing object.  *Note Growing
     Objects::.

`void obstack_grow (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
     Add SIZE bytes, copied from ADDRESS, to a growing object.  *Note
     Growing Objects::.

`void obstack_grow0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)'
     Add SIZE bytes, copied from ADDRESS, to a growing object, and then
     add another byte containing a null character.  *Note Growing
     Objects::.

`void obstack_1grow (struct obstack *OBSTACK-PTR, char DATA-CHAR)'
     Add one byte containing DATA-CHAR to a growing object.  *Note
     Growing Objects::.

`void *obstack_finish (struct obstack *OBSTACK-PTR)'
     Finalize the object that is growing and return its permanent
     address.  *Note Growing Objects::.

`int obstack_object_size (struct obstack *OBSTACK-PTR)'
     Get the current size of the currently growing object.  *Note
     Growing Objects::.

`void obstack_blank_fast (struct obstack *OBSTACK-PTR, int SIZE)'
     Add SIZE uninitialized bytes to a growing object without checking
     that there is enough room.  *Note Extra Fast Growing::.

`void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char DATA-CHAR)'
     Add one byte containing DATA-CHAR to a growing object without
     checking that there is enough room.  *Note Extra Fast Growing::.

`int obstack_room (struct obstack *OBSTACK-PTR)'
     Get the amount of room now available for growing the current
     object.  *Note Extra Fast Growing::.

`int obstack_alignment_mask (struct obstack *OBSTACK-PTR)'
     The mask used for aligning the beginning of an object.  This is an
     lvalue.  *Note Obstacks Data Alignment::.

`int obstack_chunk_size (struct obstack *OBSTACK-PTR)'
     The size for allocating chunks.  This is an lvalue.  *Note Obstack
     Chunks::.

`void *obstack_base (struct obstack *OBSTACK-PTR)'
     Tentative starting address of the currently growing object.  *Note
     Status of an Obstack::.

`void *obstack_next_free (struct obstack *OBSTACK-PTR)'
     Address just after the end of the currently growing object.  *Note
     Status of an Obstack::.


File: libc.info,  Node: Variable Size Automatic,  Prev: Obstacks,  Up: Memory Allocation

3.2.7 Automatic Storage with Variable Size
------------------------------------------

The function `alloca' supports a kind of half-dynamic allocation in
which blocks are allocated dynamically but freed automatically.

   Allocating a block with `alloca' is an explicit action; you can
allocate as many blocks as you wish, and compute the size at run time.
But all the blocks are freed when you exit the function that `alloca'
was called from, just as if they were automatic variables declared in
that function.  There is no way to free the space explicitly.

   The prototype for `alloca' is in `stdlib.h'.  This function is a BSD
extension.  

 -- Function: void * alloca (size_t SIZE)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     The return value of `alloca' is the address of a block of SIZE
     bytes of memory, allocated in the stack frame of the calling
     function.

   Do not use `alloca' inside the arguments of a function call--you
will get unpredictable results, because the stack space for the
`alloca' would appear on the stack in the middle of the space for the
function arguments.  An example of what to avoid is `foo (x, alloca
(4), y)'.

* Menu:

* Alloca Example::              Example of using `alloca'.
* Advantages of Alloca::        Reasons to use `alloca'.
* Disadvantages of Alloca::     Reasons to avoid `alloca'.
* GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
				 method of allocating dynamically and
				 freeing automatically.


File: libc.info,  Node: Alloca Example,  Next: Advantages of Alloca,  Up: Variable Size Automatic

3.2.7.1 `alloca' Example
........................

As an example of the use of `alloca', here is a function that opens a
file name made from concatenating two argument strings, and returns a
file descriptor or minus one signifying failure:

     int
     open2 (char *str1, char *str2, int flags, int mode)
     {
       char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
       stpcpy (stpcpy (name, str1), str2);
       return open (name, flags, mode);
     }

Here is how you would get the same results with `malloc' and `free':

     int
     open2 (char *str1, char *str2, int flags, int mode)
     {
       char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
       int desc;
       if (name == 0)
         fatal ("virtual memory exceeded");
       stpcpy (stpcpy (name, str1), str2);
       desc = open (name, flags, mode);
       free (name);
       return desc;
     }

   As you can see, it is simpler with `alloca'.  But `alloca' has
other, more important advantages, and some disadvantages.


File: libc.info,  Node: Advantages of Alloca,  Next: Disadvantages of Alloca,  Prev: Alloca Example,  Up: Variable Size Automatic

3.2.7.2 Advantages of `alloca'
..............................

Here are the reasons why `alloca' may be preferable to `malloc':

   * Using `alloca' wastes very little space and is very fast.  (It is
     open-coded by the GNU C compiler.)

   * Since `alloca' does not have separate pools for different sizes of
     blocks, space used for any size block can be reused for any other
     size.  `alloca' does not cause memory fragmentation.

   * Nonlocal exits done with `longjmp' (*note Non-Local Exits::)
     automatically free the space allocated with `alloca' when they exit
     through the function that called `alloca'.  This is the most
     important reason to use `alloca'.

     To illustrate this, suppose you have a function
     `open_or_report_error' which returns a descriptor, like `open', if
     it succeeds, but does not return to its caller if it fails.  If
     the file cannot be opened, it prints an error message and jumps
     out to the command level of your program using `longjmp'.  Let's
     change `open2' (*note Alloca Example::) to use this subroutine:

          int
          open2 (char *str1, char *str2, int flags, int mode)
          {
            char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
            stpcpy (stpcpy (name, str1), str2);
            return open_or_report_error (name, flags, mode);
          }

     Because of the way `alloca' works, the memory it allocates is
     freed even when an error occurs, with no special effort required.

     By contrast, the previous definition of `open2' (which uses
     `malloc' and `free') would develop a memory leak if it were
     changed in this way.  Even if you are willing to make more changes
     to fix it, there is no easy way to do so.


File: libc.info,  Node: Disadvantages of Alloca,  Next: GNU C Variable-Size Arrays,  Prev: Advantages of Alloca,  Up: Variable Size Automatic

3.2.7.3 Disadvantages of `alloca'
.................................

These are the disadvantages of `alloca' in comparison with `malloc':

   * If you try to allocate more memory than the machine can provide,
     you don't get a clean error message.  Instead you get a fatal
     signal like the one you would get from an infinite recursion;
     probably a segmentation violation (*note Program Error Signals::).

   * Some non-GNU systems fail to support `alloca', so it is less
     portable.  However, a slower emulation of `alloca' written in C is
     available for use on systems with this deficiency.


File: libc.info,  Node: GNU C Variable-Size Arrays,  Prev: Disadvantages of Alloca,  Up: Variable Size Automatic

3.2.7.4 GNU C Variable-Size Arrays
..................................

In GNU C, you can replace most uses of `alloca' with an array of
variable size.  Here is how `open2' would look then:

     int open2 (char *str1, char *str2, int flags, int mode)
     {
       char name[strlen (str1) + strlen (str2) + 1];
       stpcpy (stpcpy (name, str1), str2);
       return open (name, flags, mode);
     }

   But `alloca' is not always equivalent to a variable-sized array, for
several reasons:

   * A variable size array's space is freed at the end of the scope of
     the name of the array.  The space allocated with `alloca' remains
     until the end of the function.

   * It is possible to use `alloca' within a loop, allocating an
     additional block on each iteration.  This is impossible with
     variable-sized arrays.

   *NB:* If you mix use of `alloca' and variable-sized arrays within
one function, exiting a scope in which a variable-sized array was
declared frees all blocks allocated with `alloca' during the execution
of that scope.


File: libc.info,  Node: Resizing the Data Segment,  Next: Memory Protection,  Prev: Memory Allocation,  Up: Memory

3.3 Resizing the Data Segment
=============================

The symbols in this section are declared in `unistd.h'.

   You will not normally use the functions in this section, because the
functions described in *Note Memory Allocation:: are easier to use.
Those are interfaces to a GNU C Library memory allocator that uses the
functions below itself.  The functions below are simple interfaces to
system calls.

 -- Function: int brk (void *ADDR)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     `brk' sets the high end of the calling process' data segment to
     ADDR.

     The address of the end of a segment is defined to be the address
     of the last byte in the segment plus 1.

     The function has no effect if ADDR is lower than the low end of
     the data segment.  (This is considered success, by the way.)

     The function fails if it would cause the data segment to overlap
     another segment or exceed the process' data storage limit (*note
     Limits on Resources::).

     The function is named for a common historical case where data
     storage and the stack are in the same segment.  Data storage
     allocation grows upward from the bottom of the segment while the
     stack grows downward toward it from the top of the segment and the
     curtain between them is called the "break".

     The return value is zero on success.  On failure, the return value
     is `-1' and `errno' is set accordingly.  The following `errno'
     values are specific to this function:

    `ENOMEM'
          The request would cause the data segment to overlap another
          segment or exceed the process' data storage limit.


 -- Function: void *sbrk (ptrdiff_t DELTA)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     This function is the same as `brk' except that you specify the new
     end of the data segment as an offset DELTA from the current end
     and on success the return value is the address of the resulting
     end of the data segment instead of zero.

     This means you can use `sbrk(0)' to find out what the current end
     of the data segment is.



File: libc.info,  Node: Memory Protection,  Next: Locking Pages,  Prev: Resizing the Data Segment,  Up: Memory

3.4 Memory Protection
=====================

When a page is mapped using `mmap', page protection flags can be
specified using the protection flags argument.  *Note Memory-mapped
I/O::.

   The following flags are available:

`PROT_WRITE'
     The memory can be written to.

`PROT_READ'
     The memory can be read.  On some architectures, this flag implies
     that the memory can be executed as well (as if `PROT_EXEC' had been
     specified at the same time).

`PROT_EXEC'
     The memory can be used to store instructions which can then be
     executed.  On most architectures, this flag implies that the
     memory can be read (as if `PROT_READ' had been specified).

`PROT_NONE'
     This flag must be specified on its own.

     The memory is reserved, but cannot be read, written, or executed.
     If this flag is specified in a call to `mmap', a virtual memory
     area will be set aside for future use in the process, and `mmap'
     calls without the `MAP_FIXED' flag will not use it for subsequent
     allocations.  For anonymous mappings, the kernel will not reserve
     any physical memory for the allocation at the time the mapping is
     created.

   The operating system may keep track of these flags separately even if
the underlying hardware treats them the same for the purposes of access
checking (as happens with `PROT_READ' and `PROT_EXEC' on some
platforms).  On GNU systems, `PROT_EXEC' always implies `PROT_READ', so
that users can view the machine code which is executing on their system.

   Inappropriate access will cause a segfault (*note Program Error
Signals::).

   After allocation, protection flags can be changed using the
`mprotect' function.

 -- Function: int mprotect (void *ADDRESS, size_t LENGTH, int
          PROTECTION)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     A successful call to the `mprotect' function changes the protection
     flags of at least LENGTH bytes of memory, starting at ADDRESS.

     ADDRESS must be aligned to the page size for the mapping.  The
     system page size can be obtained by calling `sysconf' with the
     `_SC_PAGESIZE' parameter (*note Sysconf Definition::).  The system
     page size is the granularity in which the page protection of
     anonymous memory mappings and most file mappings can be changed.
     Memory which is mapped from special files or devices may have
     larger page granularity than the system page size and may require
     larger alignment.

     LENGTH is the number of bytes whose protection flags must be
     changed.  It is automatically rounded up to the next multiple of
     the system page size.

     PROTECTION is a combination of the `PROT_*' flags described above.

     The `mprotect' function returns 0 on success and -1 on failure.

     The following `errno' error conditions are defined for this
     function:

    `ENOMEM'
          The system was not able to allocate resources to fulfill the
          request.  This can happen if there is not enough physical
          memory in the system for the allocation of backing storage.
          The error can also occur if the new protection flags would
          cause the memory region to be split from its neighbors, and
          the process limit for the number of such distinct memory
          regions would be exceeded.

    `EINVAL'
          ADDRESS is not properly aligned to a page boundary for the
          mapping, or LENGTH (after rounding up to the system page
          size) is not a multiple of the applicable page size for the
          mapping, or the combination of flags in PROTECTION is not
          valid.

    `EACCES'
          The file for a file-based mapping was not opened with open
          flags which are compatible with PROTECTION.

    `EPERM'
          The system security policy does not allow a mapping with the
          specified flags.  For example, mappings which are both
          `PROT_EXEC' and `PROT_WRITE' at the same time might not be
          allowed.

   If the `mprotect' function is used to make a region of memory
inaccessible by specifying the `PROT_NONE' protection flag and access
is later restored, the memory retains its previous contents.

   On some systems, it may not be possible to specify additional flags
which were not present when the mapping was first created.  For example,
an attempt to make a region of memory executable could fail if the
initial protection flags were `PROT_READ | PROT_WRITE'.

   In general, the `mprotect' function can be used to change any
process memory, no matter how it was allocated.  However, portable use
of the function requires that it is only used with memory regions
returned by `mmap' or `mmap64'.

3.4.1 Memory Protection Keys
----------------------------

On some systems, further restrictions can be added to specific pages
using "memory protection keys".  These restrictions work as follows:

   * All memory pages are associated with a protection key.  The default
     protection key does not cause any additional protections to be
     applied during memory accesses.  New keys can be allocated with the
     `pkey_alloc' function, and applied to pages using `pkey_mprotect'.

   * Each thread has a set of separate access right restriction for each
     protection key.  These access rights can be manipulated using the
     `pkey_set' and `pkey_get' functions.

   * During a memory access, the system obtains the protection key for
     the accessed page and uses that to determine the applicable access
     rights, as configured for the current thread.  If the access is
     restricted, a segmentation fault is the result ((*note Program
     Error Signals::).  These checks happen in addition to the `PROT_'*
     protection flags set by `mprotect' or `pkey_mprotect'.

   New threads and subprocesses inherit the access rights of the current
thread.  If a protection key is allocated subsequently, existing threads
(except the current) will use an unspecified system default for the
access rights associated with newly allocated keys.

   Upon entering a signal handler, the system resets the access rights
of the current thread so that pages with the default key can be
accessed, but the access rights for other protection keys are
unspecified.

   Applications are expected to allocate a key once using `pkey_alloc',
and apply the key to memory regions which need special protection with
`pkey_mprotect':

       int key = pkey_alloc (0, PKEY_DISABLE_ACCESS);
       if (key < 0)
         /* Perform error checking, including fallback for lack of support.  */
         ...;

       /* Apply the key to a special memory region used to store critical
          data.  */
       if (pkey_mprotect (region, region_length,
                          PROT_READ | PROT_WRITE, key) < 0)
         ...; /* Perform error checking (generally fatal).  */

   If the key allocation fails due to lack of support for memory
protection keys, the `pkey_mprotect' call can usually be skipped.  In
this case, the region will not be protected by default.  It is also
possible to call `pkey_mprotect' with a key value of -1, in which case
it will behave in the same way as `mprotect'.

   After key allocation assignment to memory pages, `pkey_set' can be
used to temporarily acquire access to the memory region and relinquish
it again:

       if (key >= 0 && pkey_set (key, 0) < 0)
         ...; /* Perform error checking (generally fatal).  */
       /* At this point, the current thread has read-write access to the
          memory region.  */
       ...
       /* Revoke access again.  */
       if (key >= 0 && pkey_set (key, PKEY_DISABLE_ACCESS) < 0)
         ...; /* Perform error checking (generally fatal).  */

   In this example, a negative key value indicates that no key had been
allocated, which means that the system lacks support for memory
protection keys and it is not necessary to change the the access rights
of the current thread (because it always has access).

   Compared to using `mprotect' to change the page protection flags,
this approach has two advantages: It is thread-safe in the sense that
the access rights are only changed for the current thread, so another
thread which changes its own access rights concurrently to gain access
to the mapping will not suddenly see its access rights revoked.  And
`pkey_set' typically does not involve a call into the kernel and a
context switch, so it is more efficient.

 -- Function: int pkey_alloc (unsigned int FLAGS, unsigned int
          RESTRICTIONS)
     Preliminary: | MT-Safe | AS-Safe | AC-Unsafe corrupt | *Note POSIX
     Safety Concepts::.

     Allocate a new protection key.  The FLAGS argument is reserved and
     must be zero.  The RESTRICTIONS argument specifies access rights
     which are applied to the current thread (as if with `pkey_set'
     below).  Access rights of other threads are not changed.

     The function returns the new protection key, a non-negative
     number, or -1 on error.

     The following `errno' error conditions are defined for this
     function:

    `ENOSYS'
          The system does not implement memory protection keys.

    `EINVAL'
          The FLAGS argument is not zero.

          The RESTRICTIONS argument is invalid.

          The system does not implement memory protection keys or runs
          in a mode in which memory protection keys are disabled.

    `ENOSPC'
          All available protection keys already have been allocated.

 -- Function: int pkey_free (int KEY)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Deallocate the protection key, so that it can be reused by
     `pkey_alloc'.

     Calling this function does not change the access rights of the
     freed protection key.  The calling thread and other threads may
     retain access to it, even if it is subsequently allocated again.
     For this reason, it is not recommended to call the `pkey_free'
     function.

    `ENOSYS'
          The system does not implement memory protection keys.

    `EINVAL'
          The KEY argument is not a valid protection key.

 -- Function: int pkey_mprotect (void *ADDRESS, size_t LENGTH, int
          PROTECTION, int KEY)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Similar to `mprotect', but also set the memory protection key for
     the memory region to `key'.

     Some systems use memory protection keys to emulate certain
     combinations of PROTECTION flags.  Under such circumstances,
     specifying an explicit protection key may behave as if additional
     flags have been specified in PROTECTION, even though this does not
     happen with the default protection key.  For example, some systems
     can support `PROT_EXEC'-only mappings only with a default
     protection key, and memory with a key which was allocated using
     `pkey_alloc' will still be readable if `PROT_EXEC' is specified
     without `PROT_READ'.

     If KEY is -1, the default protection key is applied to the
     mapping, just as if `mprotect' had been called.

     The `pkey_mprotect' function returns 0 on success and -1 on
     failure.  The same `errno' error conditions as for `mprotect' are
     defined for this function, with the following addition:

    `EINVAL'
          The KEY argument is not -1 or a valid memory protection key
          allocated using `pkey_alloc'.

    `ENOSYS'
          The system does not implement memory protection keys, and KEY
          is not -1.

 -- Function: int pkey_set (int KEY, unsigned int RIGHTS)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Change the access rights of the current thread for memory pages
     with the protection key KEY to RIGHTS.  If RIGHTS is zero, no
     additional access restrictions on top of the page protection flags
     are applied.  Otherwise, RIGHTS is a combination of the following
     flags:

    `PKEY_DISABLE_WRITE'
          Subsequent attempts to write to memory with the specified
          protection key will fault.

    `PKEY_DISABLE_ACCESS'
          Subsequent attempts to write to or read from memory with the
          specified protection key will fault.

     Operations not specified as flags are not restricted.  In
     particular, this means that the memory region will remain
     executable if it was mapped with the `PROT_EXEC' protection flag
     and `PKEY_DISABLE_ACCESS' has been specified.

     Calling the `pkey_set' function with a protection key which was not
     allocated by `pkey_alloc' results in undefined behavior.  This
     means that calling this function on systems which do not support
     memory protection keys is undefined.

     The `pkey_set' function returns 0 on success and -1 on failure.

     The following `errno' error conditions are defined for this
     function:

    `EINVAL'
          The system does not support the access rights restrictions
          expressed in the RIGHTS argument.

 -- Function: int pkey_get (int KEY)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Return the access rights of the current thread for memory pages
     with protection key KEY.  The return value is zero or a
     combination of the `PKEY_DISABLE_'* flags; see the `pkey_set'
     function.

     Calling the `pkey_get' function with a protection key which was not
     allocated by `pkey_alloc' results in undefined behavior.  This
     means that calling this function on systems which do not support
     memory protection keys is undefined.


File: libc.info,  Node: Locking Pages,  Prev: Memory Protection,  Up: Memory

3.5 Locking Pages
=================

You can tell the system to associate a particular virtual memory page
with a real page frame and keep it that way -- i.e., cause the page to
be paged in if it isn't already and mark it so it will never be paged
out and consequently will never cause a page fault.  This is called
"locking" a page.

   The functions in this chapter lock and unlock the calling process'
pages.

* Menu:

* Why Lock Pages::                Reasons to read this section.
* Locked Memory Details::         Everything you need to know locked
                                    memory
* Page Lock Functions::           Here's how to do it.


File: libc.info,  Node: Why Lock Pages,  Next: Locked Memory Details,  Up: Locking Pages

3.5.1 Why Lock Pages
--------------------

Because page faults cause paged out pages to be paged in transparently,
a process rarely needs to be concerned about locking pages.  However,
there are two reasons people sometimes are:

   * Speed.  A page fault is transparent only insofar as the process is
     not sensitive to how long it takes to do a simple memory access.
     Time-critical processes, especially realtime processes, may not be
     able to wait or may not be able to tolerate variance in execution
     speed.  

     A process that needs to lock pages for this reason probably also
     needs priority among other processes for use of the CPU.  *Note
     Priority::.

     In some cases, the programmer knows better than the system's demand
     paging allocator which pages should remain in real memory to
     optimize system performance.  In this case, locking pages can help.

   * Privacy.  If you keep secrets in virtual memory and that virtual
     memory gets paged out, that increases the chance that the secrets
     will get out.  If a passphrase gets written out to disk swap
     space, for example, it might still be there long after virtual and
     real memory have been wiped clean.


   Be aware that when you lock a page, that's one fewer page frame that
can be used to back other virtual memory (by the same or other
processes), which can mean more page faults, which means the system
runs more slowly.  In fact, if you lock enough memory, some programs
may not be able to run at all for lack of real memory.