This is
/usr/local/google/home/jnewlin/src/uclibc/buildroot/output/build/glibc-2.19/build/manual/libc.info,
produced by makeinfo version 4.13 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.
* 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.
* DES_FAILED: (libc)DES Encryption.
* 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.
* 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.
* 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_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.
* 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_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.
* 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.
* SV_INTERRUPT: (libc)BSD Handler.
* SV_ONSTACK: (libc)BSD Handler.
* SV_RESETHAND: (libc)BSD Handler.
* 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_low: (libc)PowerPC.
* __ppc_yield: (libc)PowerPC.
* __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.
* acosh: (libc)Hyperbolic Functions.
* acoshf: (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.
* asinh: (libc)Hyperbolic Functions.
* asinhf: (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.
* atan2l: (libc)Inverse Trig Functions.
* atan: (libc)Inverse Trig Functions.
* atanf: (libc)Inverse Trig Functions.
* atanh: (libc)Hyperbolic Functions.
* atanhf: (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 and Concatenation.
* 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 and Concatenation.
* cabs: (libc)Absolute Value.
* cabsf: (libc)Absolute Value.
* cabsl: (libc)Absolute Value.
* cacos: (libc)Inverse Trig Functions.
* cacosf: (libc)Inverse Trig Functions.
* cacosh: (libc)Hyperbolic Functions.
* cacoshf: (libc)Hyperbolic Functions.
* cacoshl: (libc)Hyperbolic Functions.
* cacosl: (libc)Inverse Trig Functions.
* calloc: (libc)Allocating Cleared Space.
* canonicalize_file_name: (libc)Symbolic Links.
* carg: (libc)Operations on Complex.
* cargf: (libc)Operations on Complex.
* cargl: (libc)Operations on Complex.
* casin: (libc)Inverse Trig Functions.
* casinf: (libc)Inverse Trig Functions.
* casinh: (libc)Hyperbolic Functions.
* casinhf: (libc)Hyperbolic Functions.
* casinhl: (libc)Hyperbolic Functions.
* casinl: (libc)Inverse Trig Functions.
* catan: (libc)Inverse Trig Functions.
* catanf: (libc)Inverse Trig Functions.
* catanh: (libc)Hyperbolic Functions.
* catanhf: (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.
* cbc_crypt: (libc)DES Encryption.
* cbrt: (libc)Exponents and Logarithms.
* cbrtf: (libc)Exponents and Logarithms.
* cbrtl: (libc)Exponents and Logarithms.
* ccos: (libc)Trig Functions.
* ccosf: (libc)Trig Functions.
* ccosh: (libc)Hyperbolic Functions.
* ccoshf: (libc)Hyperbolic Functions.
* ccoshl: (libc)Hyperbolic Functions.
* ccosl: (libc)Trig Functions.
* ceil: (libc)Rounding Functions.
* ceilf: (libc)Rounding Functions.
* ceill: (libc)Rounding Functions.
* cexp: (libc)Exponents and Logarithms.
* cexpf: (libc)Exponents and Logarithms.
* cexpl: (libc)Exponents and Logarithms.
* cfgetispeed: (libc)Line Speed.
* cfgetospeed: (libc)Line Speed.
* cfmakeraw: (libc)Noncanonical Input.
* cfree: (libc)Freeing after Malloc.
* 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.
* 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.
* clog10l: (libc)Exponents and Logarithms.
* clog: (libc)Exponents and Logarithms.
* clogf: (libc)Exponents and Logarithms.
* clogl: (libc)Exponents and Logarithms.
* close: (libc)Opening and Closing Files.
* closedir: (libc)Reading/Closing Directory.
* closelog: (libc)closelog.
* confstr: (libc)String Parameters.
* conj: (libc)Operations on Complex.
* conjf: (libc)Operations on Complex.
* conjl: (libc)Operations on Complex.
* connect: (libc)Connecting.
* copysign: (libc)FP Bit Twiddling.
* copysignf: (libc)FP Bit Twiddling.
* copysignl: (libc)FP Bit Twiddling.
* cos: (libc)Trig Functions.
* cosf: (libc)Trig Functions.
* cosh: (libc)Hyperbolic Functions.
* coshf: (libc)Hyperbolic Functions.
* coshl: (libc)Hyperbolic Functions.
* cosl: (libc)Trig Functions.
* cpow: (libc)Exponents and Logarithms.
* cpowf: (libc)Exponents and Logarithms.
* cpowl: (libc)Exponents and Logarithms.
* cproj: (libc)Operations on Complex.
* cprojf: (libc)Operations on Complex.
* cprojl: (libc)Operations on Complex.
* creal: (libc)Operations on Complex.
* crealf: (libc)Operations on Complex.
* creall: (libc)Operations on Complex.
* creat64: (libc)Opening and Closing Files.
* creat: (libc)Opening and Closing Files.
* crypt: (libc)crypt.
* crypt_r: (libc)crypt.
* csin: (libc)Trig Functions.
* csinf: (libc)Trig Functions.
* csinh: (libc)Hyperbolic Functions.
* csinhf: (libc)Hyperbolic Functions.
* csinhl: (libc)Hyperbolic Functions.
* csinl: (libc)Trig Functions.
* csqrt: (libc)Exponents and Logarithms.
* csqrtf: (libc)Exponents and Logarithms.
* csqrtl: (libc)Exponents and Logarithms.
* ctan: (libc)Trig Functions.
* ctanf: (libc)Trig Functions.
* ctanh: (libc)Hyperbolic Functions.
* ctanhf: (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.
* dcgettext: (libc)Translation with gettext.
* dcngettext: (libc)Advanced gettext functions.
* des_setparity: (libc)DES Encryption.
* 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.
* 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.
* dup2: (libc)Duplicating Descriptors.
* dup: (libc)Duplicating Descriptors.
* ecb_crypt: (libc)DES Encryption.
* ecvt: (libc)System V Number Conversion.
* ecvt_r: (libc)System V Number Conversion.
* encrypt: (libc)DES Encryption.
* encrypt_r: (libc)DES Encryption.
* 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_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.
* erfcl: (libc)Special Functions.
* erff: (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.
* exp10l: (libc)Exponents and Logarithms.
* exp2: (libc)Exponents and Logarithms.
* exp2f: (libc)Exponents and Logarithms.
* exp2l: (libc)Exponents and Logarithms.
* exp: (libc)Exponents and Logarithms.
* expf: (libc)Exponents and Logarithms.
* expl: (libc)Exponents and Logarithms.
* expm1: (libc)Exponents and Logarithms.
* expm1f: (libc)Exponents and Logarithms.
* expm1l: (libc)Exponents and Logarithms.
* fabs: (libc)Absolute Value.
* fabsf: (libc)Absolute Value.
* fabsl: (libc)Absolute Value.
* 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.
* fdiml: (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.
* 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.
* fesetexceptflag: (libc)Status bit operations.
* fesetround: (libc)Rounding.
* fetestexcept: (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.
* floorl: (libc)Rounding Functions.
* fma: (libc)Misc FP Arithmetic.
* fmaf: (libc)Misc FP Arithmetic.
* fmal: (libc)Misc FP Arithmetic.
* fmax: (libc)Misc FP Arithmetic.
* fmaxf: (libc)Misc FP Arithmetic.
* fmaxl: (libc)Misc FP Arithmetic.
* fmemopen: (libc)String Streams.
* fmin: (libc)Misc FP Arithmetic.
* fminf: (libc)Misc FP Arithmetic.
* fminl: (libc)Misc FP Arithmetic.
* fmod: (libc)Remainder Functions.
* fmodf: (libc)Remainder Functions.
* fmodl: (libc)Remainder Functions.
* fmtmsg: (libc)Printing Formatted Messages.
* 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.
* frexpl: (libc)Normalization 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* 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.
* iscntrl: (libc)Classification of Characters.
* isdigit: (libc)Classification of Characters.
* 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.
* 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.
* j0: (libc)Special Functions.
* j0f: (libc)Special Functions.
* j0l: (libc)Special Functions.
* j1: (libc)Special Functions.
* j1f: (libc)Special Functions.
* j1l: (libc)Special Functions.
* jn: (libc)Special Functions.
* jnf: (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.
* 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.
* lgammaf_r: (libc)Special Functions.
* lgammal: (libc)Special Functions.
* lgammal_r: (libc)Special Functions.
* link: (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.
* llrint: (libc)Rounding Functions.
* llrintf: (libc)Rounding Functions.
* llrintl: (libc)Rounding Functions.
* llround: (libc)Rounding Functions.
* llroundf: (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.
* log10l: (libc)Exponents and Logarithms.
* log1p: (libc)Exponents and Logarithms.
* log1pf: (libc)Exponents and Logarithms.
* log1pl: (libc)Exponents and Logarithms.
* log2: (libc)Exponents and Logarithms.
* log2f: (libc)Exponents and Logarithms.
* log2l: (libc)Exponents and Logarithms.
* log: (libc)Exponents and Logarithms.
* logb: (libc)Exponents and Logarithms.
* logbf: (libc)Exponents and Logarithms.
* logbl: (libc)Exponents and Logarithms.
* logf: (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.
* lrintl: (libc)Rounding Functions.
* lround: (libc)Rounding Functions.
* lroundf: (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 and Concatenation.
* memchr: (libc)Search Functions.
* memcmp: (libc)String/Array Comparison.
* memcpy: (libc)Copying and Concatenation.
* memfrob: (libc)Trivial Encryption.
* memmem: (libc)Search Functions.
* memmove: (libc)Copying and Concatenation.
* mempcpy: (libc)Copying and Concatenation.
* memrchr: (libc)Search Functions.
* memset: (libc)Copying and Concatenation.
* 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.
* 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.
* modfl: (libc)Rounding Functions.
* mount: (libc)Mount-Unmount-Remount.
* mprobe: (libc)Heap Consistency Checking.
* 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.
* 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.
* nanl: (libc)FP Bit Twiddling.
* nanosleep: (libc)Sleeping.
* nearbyint: (libc)Rounding Functions.
* nearbyintf: (libc)Rounding Functions.
* nearbyintl: (libc)Rounding Functions.
* nextafter: (libc)FP Bit Twiddling.
* nextafterf: (libc)FP Bit Twiddling.
* nextafterl: (libc)FP Bit Twiddling.
* nexttoward: (libc)FP Bit Twiddling.
* nexttowardf: (libc)FP Bit Twiddling.
* nexttowardl: (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.
* popen: (libc)Pipe to a Subprocess.
* posix_memalign: (libc)Aligned Memory Blocks.
* pow10: (libc)Exponents and Logarithms.
* pow10f: (libc)Exponents and Logarithms.
* pow10l: (libc)Exponents and Logarithms.
* pow: (libc)Exponents and Logarithms.
* powf: (libc)Exponents and Logarithms.
* powl: (libc)Exponents and Logarithms.
* pread64: (libc)I/O Primitives.
* pread: (libc)I/O Primitives.
* 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.
* 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.
* 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.
* 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.
* rintl: (libc)Rounding Functions.
* rmdir: (libc)Deleting Files.
* round: (libc)Rounding Functions.
* roundf: (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.
* scalblnl: (libc)Normalization Functions.
* scalbn: (libc)Normalization Functions.
* scalbnf: (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.
* 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.
* setkey: (libc)DES Encryption.
* setkey_r: (libc)DES Encryption.
* setlinebuf: (libc)Controlling Buffering.
* setlocale: (libc)Setting the Locale.
* setlogmask: (libc)setlogmask.
* setmntent: (libc)mtab.
* setnetent: (libc)Networks Database.
* setnetgrent: (libc)Lookup Netgroup.
* 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)Blocking in BSD.
* sigdelset: (libc)Signal Sets.
* sigemptyset: (libc)Signal Sets.
* sigfillset: (libc)Signal Sets.
* siginterrupt: (libc)BSD Handler.
* sigismember: (libc)Signal Sets.
* siglongjmp: (libc)Non-Local Exits and Signals.
* sigmask: (libc)Blocking in BSD.
* signal: (libc)Basic Signal Handling.
* signbit: (libc)FP Bit Twiddling.
* significand: (libc)Normalization Functions.
* significandf: (libc)Normalization Functions.
* significandl: (libc)Normalization Functions.
* sigpause: (libc)Blocking in BSD.
* sigpending: (libc)Checking for Pending Signals.
* sigprocmask: (libc)Process Signal Mask.
* sigsetjmp: (libc)Non-Local Exits and Signals.
* sigsetmask: (libc)Blocking in BSD.
* sigstack: (libc)Signal Stack.
* sigsuspend: (libc)Sigsuspend.
* sigvec: (libc)BSD Handler.
* sin: (libc)Trig Functions.
* sincos: (libc)Trig Functions.
* sincosf: (libc)Trig Functions.
* sincosl: (libc)Trig Functions.
* sinf: (libc)Trig Functions.
* sinh: (libc)Hyperbolic Functions.
* sinhf: (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.
* 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 and Concatenation.
* stpncpy: (libc)Copying and Concatenation.
* strcasecmp: (libc)String/Array Comparison.
* strcasestr: (libc)Search Functions.
* strcat: (libc)Copying and Concatenation.
* strchr: (libc)Search Functions.
* strchrnul: (libc)Search Functions.
* strcmp: (libc)String/Array Comparison.
* strcoll: (libc)Collation Functions.
* strcpy: (libc)Copying and Concatenation.
* strcspn: (libc)Search Functions.
* strdup: (libc)Copying and Concatenation.
* strdupa: (libc)Copying and Concatenation.
* strerror: (libc)Error Messages.
* strerror_r: (libc)Error Messages.
* strfmon: (libc)Formatting Numbers.
* strfry: (libc)strfry.
* strftime: (libc)Formatting Calendar Time.
* strlen: (libc)String Length.
* strncasecmp: (libc)String/Array Comparison.
* strncat: (libc)Copying and Concatenation.
* strncmp: (libc)String/Array Comparison.
* strncpy: (libc)Copying and Concatenation.
* strndup: (libc)Copying and Concatenation.
* strndupa: (libc)Copying and Concatenation.
* 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.
* 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.
* tanh: (libc)Hyperbolic Functions.
* tanhf: (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.
* tgammal: (libc)Special Functions.
* 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.
* 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.
* truncl: (libc)Rounding Functions.
* tsearch: (libc)Tree Search Function.
* ttyname: (libc)Is It a Terminal.
* ttyname_r: (libc)Is It a Terminal.
* twalk: (libc)Tree Search Function.
* tzset: (libc)Time Zone 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 and Concatenation.
* wcpncpy: (libc)Copying and Concatenation.
* wcrtomb: (libc)Converting a Character.
* wcscasecmp: (libc)String/Array Comparison.
* wcscat: (libc)Copying and Concatenation.
* wcschr: (libc)Search Functions.
* wcschrnul: (libc)Search Functions.
* wcscmp: (libc)String/Array Comparison.
* wcscoll: (libc)Collation Functions.
* wcscpy: (libc)Copying and Concatenation.
* wcscspn: (libc)Search Functions.
* wcsdup: (libc)Copying and Concatenation.
* wcsftime: (libc)Formatting Calendar Time.
* wcslen: (libc)String Length.
* wcsncasecmp: (libc)String/Array Comparison.
* wcsncat: (libc)Copying and Concatenation.
* wcsncmp: (libc)String/Array Comparison.
* wcsncpy: (libc)Copying and Concatenation.
* 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.
* 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 and Concatenation.
* wmemmove: (libc)Copying and Concatenation.
* wmempcpy: (libc)Copying and Concatenation.
* wmemset: (libc)Copying and Concatenation.
* 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.
* y0l: (libc)Special Functions.
* y1: (libc)Special Functions.
* y1f: (libc)Special Functions.
* y1l: (libc)Special Functions.
* yn: (libc)Special Functions.
* ynf: (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.19
(Buildroot).

   Copyright (C) 1993-2014 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.19
(Buildroot) 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.
* 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::      DES encryption and password handling.
* Debugging Support::            Functions to help debugging applications.
* POSIX Threads::                POSIX Threads.
* Internal Probes::              Probes to monitor 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'
* Locking Pages::               Preventing page faults

Memory Allocation

* Memory Allocation and C::     How to get different kinds of allocation in C.
* Unconstrained Allocation::    The `malloc' facility allows fully general
		 		 dynamic allocation.
* Allocation Debugging::        Finding memory leaks and not freed memory.
* 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.
* Efficiency and Malloc::       Efficiency considerations in use of
				 these functions.
* 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 and Concatenation::   Functions to copy the contents of strings
				 and arrays.
* 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.
* strfry::                      Function for flash-cooking a string.
* Trivial Encryption::          Obscuring data.
* 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 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.
* 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.
* 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.

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.
* 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.
* 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.

BSD Signal Handling

* BSD Handler::                 BSD Function to Establish a Handler.
* Blocking in BSD::             BSD Functions for Blocking Signals.

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.

Job Control

* Concepts of Job Control::     Jobs can be controlled by a shell.
* Job Control is Optional::     Not all POSIX systems support job control.
* 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

* Legal Problems::              This software can get you locked up, or worse.
* getpass::                     Prompting the user for a password.
* crypt::                       A one-way function for passwords.
* DES Encryption::              Routines for DES encryption.

Debugging Support

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

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

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.
* 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.

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

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

     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.

 -- Macro: _BSD_SOURCE
     If you define this macro, functionality derived from 4.3 BSD Unix
     is included as well as the ISO C, POSIX.1, and POSIX.2 material.

 -- Macro: _SVID_SOURCE
     If you define this macro, functionality derived from SVID is
     included as well as the ISO C, POSIX.1, POSIX.2, and X/Open
     material.

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

 -- 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
     Until the revised ISO C standard is widely adopted the new features
     are not automatically enabled.  The GNU C Library nevertheless has
     a complete implementation of the new standard and to enable the
     new features the macro `_ISOC99_SOURCE' should be defined.

 -- 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 similar to defining
     `_POSIX_C_SOURCE' to `200809L' and `_POSIX_SOURCE',
     `_SVID_SOURCE', and `_BSD_SOURCE' to 1.  Defining this macro, on
     its own and without using compiler options such as `-ansi' or
     `-std=c99', has the same effect as not defining any feature test
     macros; defining it together with other feature test macros, or
     when options such as `-ansi' are used, enables those features even
     when the other options would otherwise cause them to be disabled.

 -- Macro: _REENTRANT
 -- Macro: _THREAD_SAFE
     If you define one of these macros, reentrant versions of several
     functions get declared.  Some of the functions are specified in
     POSIX.1c but many others are only available on a few other systems
     or are unique to the GNU C Library.  The problem is the delay in
     the standardization of the thread safe C library interface.

     Unlike on some other systems, no special version of the C library
     must be used for linking.  There is only one version but while
     compiling this it must have been specified to compile as 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' or `_SVID_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 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 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 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 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 Date and Time::, describes functions for measuring both
     calendar time and CPU time, as well as functions for setting
     alarms and timers.

   * *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 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 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.  Many
     library functions are guaranteed to set it to certain nonzero
     values when they encounter certain kinds of errors.  These error
     conditions are listed for each function.  These functions do not
     change `errno' when they succeed; thus, the value of `errno' after
     a successful call is not necessarily zero, and you should not use
     `errno' to determine _whether_ a call failed.  The proper way to
     do that is documented for each function.  _If_ the call failed,
     you can examine `errno'.

     Many library functions can set `errno' to a nonzero value as a
     result of calling other library functions which might fail.  You
     should assume that any library function might alter `errno' when
     the function returns an error.

     *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 process matches the specified process ID.

 -- Macro: int EINTR
     Interrupted function 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
     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
     There are 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
     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
     No memory available.  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
     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
     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
     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
     The wrong type of device was given to a function that expects a
     particular sort of device.

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

 -- Macro: int EISDIR
     File 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
     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
     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 I/O control operation, such as trying to set terminal
     modes on an ordinary file.

 -- Macro: int ETXTBSY
     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 big; 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
     Invalid seek operation (such as on a pipe).

 -- Macro: int EROFS
     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
     Domain error; used by mathematical functions when an argument
     value does not fall into the domain over which the function is
     defined.

 -- Macro: int ERANGE
     Range error; 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
     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
     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
     An operation is already in progress on an object that has
     non-blocking mode selected.

 -- Macro: int ENOTSOCK
     A file that isn't a socket was specified when a socket is required.

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

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

 -- Macro: int ENOPROTOOPT
     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
     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
     The socket type is not supported.

 -- Macro: int EOPNOTSUPP
     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
     The socket communications protocol family you requested is not
     supported.

 -- Macro: int EAFNOSUPPORT
     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
     The requested socket address is already in use.  *Note Socket
     Addresses::.

 -- Macro: int EADDRNOTAVAIL
     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
     A socket operation failed because the network was down.

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

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

 -- Macro: int ECONNABORTED
     A network connection was aborted locally.

 -- Macro: int ECONNRESET
     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
     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
     You tried to connect a socket that is already connected.  *Note
     Connecting::.

 -- Macro: int ENOTCONN
     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
     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
     The socket has already been shut down.

 -- Macro: int ETOOMANYREFS
     ???

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

 -- Macro: int ECONNREFUSED
     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 were encountered in looking up a
     file name.  This often indicates a cycle of symbolic links.

 -- Macro: int ENAMETOOLONG
     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
     The remote host for a requested network connection is down.

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

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

 -- Macro: int EPROCLIM
     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
     The file quota system is confused because there are too many users.

 -- Macro: int EDQUOT
     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
     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
     ???

 -- Macro: int ERPCMISMATCH
     ???

 -- Macro: int EPROGUNAVAIL
     ???

 -- Macro: int EPROGMISMATCH
     ???

 -- Macro: int EPROCUNAVAIL
     ???

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

 -- Macro: int ENEEDAUTH
     ???

 -- 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
     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
     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
     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 did *what*?

 -- Macro: int EIEIO
     Go home and have a glass of warm, dairy-fresh milk.

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

 -- Macro: int EBADMSG

 -- Macro: int EIDRM

 -- Macro: int EMULTIHOP

 -- Macro: int ENODATA

 -- Macro: int ENOLINK

 -- Macro: int ENOMSG

 -- Macro: int ENOSR

 -- Macro: int ENOSTR

 -- Macro: int EOVERFLOW

 -- Macro: int EPROTO

 -- Macro: int ETIME

 -- 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::.

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

 -- Macro: int ERESTART

 -- Macro: int ECHRNG

 -- Macro: int EL2NSYNC

 -- Macro: int EL3HLT

 -- Macro: int EL3RST

 -- Macro: int ELNRNG

 -- Macro: int EUNATCH

 -- Macro: int ENOCSI

 -- Macro: int EL2HLT

 -- Macro: int EBADE

 -- Macro: int EBADR

 -- Macro: int EXFULL

 -- Macro: int ENOANO

 -- Macro: int EBADRQC

 -- Macro: int EBADSLT

 -- Macro: int EDEADLOCK

 -- Macro: int EBFONT

 -- Macro: int ENONET

 -- Macro: int ENOPKG

 -- Macro: int EADV

 -- Macro: int ESRMNT

 -- Macro: int ECOMM

 -- Macro: int EDOTDOT

 -- Macro: int ENOTUNIQ

 -- Macro: int EBADFD

 -- Macro: int EREMCHG

 -- Macro: int ELIBACC

 -- Macro: int ELIBBAD

 -- Macro: int ELIBSCN

 -- Macro: int ELIBMAX

 -- Macro: int ELIBEXEC

 -- Macro: int ESTRPIPE

 -- Macro: int EUCLEAN

 -- Macro: int ENOTNAM

 -- Macro: int ENAVAIL

 -- Macro: int EISNAM

 -- Macro: int EREMOTEIO

 -- Macro: int ENOMEDIUM

 -- Macro: int EMEDIUMTYPE

 -- Macro: int ENOKEY

 -- Macro: int EKEYEXPIRED

 -- Macro: int EKEYREVOKED

 -- Macro: int EKEYREJECTED

 -- Macro: int EOWNERDEAD

 -- Macro: int ENOTRECOVERABLE

 -- Macro: int ERFKILL

 -- Macro: int EHWPOISON


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 the 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.

     This 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.

   *Compatibility Note:* The `strerror' function was introduced in
ISO C89.  Many older C systems do not support this function yet.

   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::.

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

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

   *Portability Note:* These two variables are GNU extensions.  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.

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

     The `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 difference 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 pointer to by FNAME, another colon, and a 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 returned 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 be 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 avoid 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'
* 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 the GNU C Library and GNU Compiler.

* Menu:

* Memory Allocation and C::     How to get different kinds of allocation in C.
* Unconstrained Allocation::    The `malloc' facility allows fully general
		 		 dynamic allocation.
* Allocation Debugging::        Finding memory leaks and not freed memory.
* 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: Unconstrained Allocation,  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: Unconstrained Allocation,  Next: Allocation Debugging,  Prev: Memory Allocation and C,  Up: Memory Allocation

3.2.2 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.
* Efficiency and Malloc::       Efficiency considerations in use of
				 these functions.
* 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.2.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 and Concatenation::):

     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.2.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.2.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.

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

     This function does the same thing as `free'.  It's provided for
     backward compatibility with SunOS; you should use `free' instead.

   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.2.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'.  This function
is 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.

   Like `malloc', `realloc' 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' 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'
is guaranteed to change nothing and return the same address that you
gave.

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

3.2.2.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: Efficiency and Malloc,  Next: Aligned Memory Blocks,  Prev: Allocating Cleared Space,  Up: Unconstrained Allocation

3.2.2.6 Efficiency Considerations for `malloc'
..............................................

As opposed to other versions, the `malloc' in the GNU C Library does
not round up block 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.

   Very large blocks (much larger than a page) are allocated with
`mmap' (anonymous or via `/dev/zero') by this implementation.  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
can be adjusted with `mallopt'.  The use of `mmap' can also be disabled
completely.


File: libc.info,  Node: Aligned Memory Blocks,  Next: Malloc Tunable Parameters,  Prev: Efficiency and Malloc,  Up: Unconstrained Allocation

3.2.2.7 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'
          ALIGNMENT 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 second 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.2.8 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'.

    `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'.

    `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.

    `M_TOP_PAD'
          This parameter determines the amount of extra memory to
          obtain from the system when a call to `sbrk' is required.  It
          also specifies the number of bytes to retain when shrinking
          the heap by calling `sbrk' with a negative argument.  This
          provides the necessary hysteresis in heap size such that
          excessive amounts of system calls can be avoided.

    `M_TRIM_THRESHOLD'
          This is the minimum size (in bytes) of the top-most,
          releasable chunk that will cause `sbrk' to be called with a
          negative argument in order to return memory to the system.



File: libc.info,  Node: Heap Consistency Checking,  Next: Hooks for Malloc,  Prev: Malloc Tunable Parameters,  Up: Unconstrained Allocation

3.2.2.9 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, 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.
If `MALLOC_CHECK_' is set to `0', any detected heap corruption is
silently ignored; if set to `1', a diagnostic is printed on `stderr';
if set to `2', `abort' is called immediately.  This can be useful
because otherwise a crash may happen much later, and the true cause for
the problem is then very hard to track down.

   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.2.10 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.

 -- Variable: __malloc_initialize_hook
     The value of this variable is a pointer to a function that is
     called once when the malloc implementation is initialized.  This
     is a weak variable, so it can be overridden in the application
     with a definition like the following:

          void (*__MALLOC_INITIALIZE_HOOK) (void) = my_init_hook;

   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.

   In both cases, the problem can be solved by setting up the hooks from
within a user-defined function pointed to by
`__malloc_initialize_hook'--then the hooks will be set up safely at the
right time.

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

     /* Override initializing hook from the C library. */
     void (*__malloc_initialize_hook) (void) = my_init_hook;

     static void
     my_init_hook (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 ()
     {
       ...
     }

   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.2.11 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; see *note Efficiency and Malloc::.)

    `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.

    `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.2.12 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 *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: Obstacks,  Prev: Unconstrained Allocation,  Up: Memory Allocation

3.2.3 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 assure 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.3.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.3.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 what 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 no good idea to call `muntrace'
before the program terminated.  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.3.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.3.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: Obstacks,  Next: Variable Size Automatic,  Prev: Allocation Debugging,  Up: Memory Allocation

3.2.4 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.4.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.4.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.4.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.4.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 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.4.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.4.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.4.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 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.4.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.4.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.4.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.4.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.5 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.5.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.5.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
     block, 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.5.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.5.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: Locking Pages,  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: Locking Pages,  Prev: Resizing the Data Segment,  Up: Memory

3.4 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.4.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 password 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.


File: libc.info,  Node: Locked Memory Details,  Next: Page Lock Functions,  Prev: Why Lock Pages,  Up: Locking Pages

3.4.2 Locked Memory Details
---------------------------

A memory lock is associated with a virtual page, not a real frame.  The
paging rule is: If a frame backs at least one locked page, don't page it
out.

   Memory locks do not stack.  I.e., you can't lock a particular page
twice so that it has to be unlocked twice before it is truly unlocked.
It is either locked or it isn't.

   A memory lock persists until the process that owns the memory
explicitly unlocks it.  (But process termination and exec cause the
virtual memory to cease to exist, which you might say means it isn't
locked any more).

   Memory locks are not inherited by child processes.  (But note that
on a modern Unix system, immediately after a fork, the parent's and the
child's virtual address space are backed by the same real page frames,
so the child enjoys the parent's locks).  *Note Creating a Process::.

   Because of its ability to impact other processes, only the superuser
can lock a page.  Any process can unlock its own page.

   The system sets limits on the amount of memory a process can have
locked and the amount of real memory it can have dedicated to it.
*Note Limits on Resources::.

   In Linux, locked pages aren't as locked as you might think.  Two
virtual pages that are not shared memory can nonetheless be backed by
the same real frame.  The kernel does this in the name of efficiency
when it knows both virtual pages contain identical data, and does it
even if one or both of the virtual pages are locked.

   But when a process modifies one of those pages, the kernel must get
it a separate frame and fill it with the page's data.  This is known as
a "copy-on-write page fault".  It takes a small amount of time and in a
pathological case, getting that frame may require I/O.  

   To make sure this doesn't happen to your program, don't just lock the
pages.  Write to them as well, unless you know you won't write to them
ever.  And to make sure you have pre-allocated frames for your stack,
enter a scope that declares a C automatic variable larger than the
maximum stack size you will need, set it to something, then return from
its scope.


File: libc.info,  Node: Page Lock Functions,  Prev: Locked Memory Details,  Up: Locking Pages

3.4.3 Functions To Lock And Unlock Pages
----------------------------------------

The symbols in this section are declared in `sys/mman.h'.  These
functions are defined by POSIX.1b, but their availability depends on
your kernel.  If your kernel doesn't allow these functions, they exist
but always fail.  They _are_ available with a Linux kernel.

   *Portability Note:* POSIX.1b requires that when the `mlock' and
`munlock' functions are available, the file `unistd.h' define the macro
`_POSIX_MEMLOCK_RANGE' and the file `limits.h' define the macro
`PAGESIZE' to be the size of a memory page in bytes.  It requires that
when the `mlockall' and `munlockall' functions are available, the
`unistd.h' file define the macro `_POSIX_MEMLOCK'.  The GNU C Library
conforms to this requirement.

 -- Function: int mlock (const void *ADDR, size_t LEN)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     `mlock' locks a range of the calling process' virtual pages.

     The range of memory starts at address ADDR and is LEN bytes long.
     Actually, since you must lock whole pages, it is the range of
     pages that include any part of the specified range.

     When the function returns successfully, each of those pages is
     backed by (connected to) a real frame (is resident) and is marked
     to stay that way.  This means the function may cause page-ins and
     have to wait for them.

     When the function fails, it does not affect the lock status of any
     pages.

     The return value is zero if the function succeeds.  Otherwise, it
     is `-1' and `errno' is set accordingly.  `errno' values specific
     to this function are:

    `ENOMEM'
             * At least some of the specified address range does not
               exist in the calling process' virtual address space.

             * The locking would cause the process to exceed its locked
               page limit.

    `EPERM'
          The calling process is not superuser.

    `EINVAL'
          LEN is not positive.

    `ENOSYS'
          The kernel does not provide `mlock' capability.


     You can lock _all_ a process' memory with `mlockall'.  You unlock
     memory with `munlock' or `munlockall'.

     To avoid all page faults in a C program, you have to use
     `mlockall', because some of the memory a program uses is hidden
     from the C code, e.g. the stack and automatic variables, and you
     wouldn't know what address to tell `mlock'.


 -- Function: int munlock (const void *ADDR, size_t LEN)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     `munlock' unlocks a range of the calling process' virtual pages.

     `munlock' is the inverse of `mlock' and functions completely
     analogously to `mlock', except that there is no `EPERM' failure.


 -- Function: int mlockall (int FLAGS)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     `mlockall' locks all the pages in a process' virtual memory address
     space, and/or any that are added to it in the future.  This
     includes the pages of the code, data and stack segment, as well as
     shared libraries, user space kernel data, shared memory, and
     memory mapped files.

     FLAGS is a string of single bit flags represented by the following
     macros.  They tell `mlockall' which of its functions you want.  All
     other bits must be zero.

    `MCL_CURRENT'
          Lock all pages which currently exist in the calling process'
          virtual address space.

    `MCL_FUTURE'
          Set a mode such that any pages added to the process' virtual
          address space in the future will be locked from birth.  This
          mode does not affect future address spaces owned by the same
          process so exec, which replaces a process' address space,
          wipes out `MCL_FUTURE'.  *Note Executing a File::.


     When the function returns successfully, and you specified
     `MCL_CURRENT', all of the process' pages are backed by (connected
     to) real frames (they are resident) and are marked to stay that
     way.  This means the function may cause page-ins and have to wait
     for them.

     When the process is in `MCL_FUTURE' mode because it successfully
     executed this function and specified `MCL_CURRENT', any system call
     by the process that requires space be added to its virtual address
     space fails with `errno' = `ENOMEM' if locking the additional space
     would cause the process to exceed its locked page limit.  In the
     case that the address space addition that can't be accommodated is
     stack expansion, the stack expansion fails and the kernel sends a
     `SIGSEGV' signal to the process.

     When the function fails, it does not affect the lock status of any
     pages or the future locking mode.

     The return value is zero if the function succeeds.  Otherwise, it
     is `-1' and `errno' is set accordingly.  `errno' values specific
     to this function are:

    `ENOMEM'
             * At least some of the specified address range does not
               exist in the calling process' virtual address space.

             * The locking would cause the process to exceed its locked
               page limit.

    `EPERM'
          The calling process is not superuser.

    `EINVAL'
          Undefined bits in FLAGS are not zero.

    `ENOSYS'
          The kernel does not provide `mlockall' capability.


     You can lock just specific pages with `mlock'.  You unlock pages
     with `munlockall' and `munlock'.


 -- Function: int munlockall (void)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     `munlockall' unlocks every page in the calling process' virtual
     address space and turn off `MCL_FUTURE' future locking mode.

     The return value is zero if the function succeeds.  Otherwise, it
     is `-1' and `errno' is set accordingly.  The only way this
     function can fail is for generic reasons that all functions and
     system calls can fail, so there are no specific `errno' values.



File: libc.info,  Node: Character Handling,  Next: String and Array Utilities,  Prev: Memory,  Up: Top

4 Character Handling
********************

Programs that work with characters and strings often need to classify a
character--is it alphabetic, is it a digit, is it whitespace, and so
on--and perform case conversion operations on characters.  The
functions in the header file `ctype.h' are provided for this purpose.  

   Since the choice of locale and character set can alter the
classifications of particular character codes, all of these functions
are affected by the current locale.  (More precisely, they are affected
by the locale currently selected for character classification--the
`LC_CTYPE' category; see *note Locale Categories::.)

   The ISO C standard specifies two different sets of functions.  The
one set works on `char' type characters, the other one on `wchar_t'
wide characters (*note Extended Char Intro::).

* Menu:

* 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.


File: libc.info,  Node: Classification of Characters,  Next: Case Conversion,  Up: Character Handling

4.1 Classification of Characters
================================

This section explains the library functions for classifying characters.
For example, `isalpha' is the function to test for an alphabetic
character.  It takes one argument, the character to test, and returns a
nonzero integer if the character is alphabetic, and zero otherwise.  You
would use it like this:

     if (isalpha (c))
       printf ("The character `%c' is alphabetic.\n", c);

   Each of the functions in this section tests for membership in a
particular class of characters; each has a name starting with `is'.
Each of them takes one argument, which is a character to test, and
returns an `int' which is treated as a boolean value.  The character
argument is passed as an `int', and it may be the constant value `EOF'
instead of a real character.

   The attributes of any given character can vary between locales.
*Note Locales::, for more information on locales.

   These functions are declared in the header file `ctype.h'.  

 -- Function: int islower (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a lower-case letter.  The letter need not be
     from the Latin alphabet, any alphabet representable is valid.

 -- Function: int isupper (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is an upper-case letter.  The letter need not be
     from the Latin alphabet, any alphabet representable is valid.

 -- Function: int isalpha (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is an alphabetic character (a letter).  If
     `islower' or `isupper' is true of a character, then `isalpha' is
     also true.

     In some locales, there may be additional characters for which
     `isalpha' is true--letters which are neither upper case nor lower
     case.  But in the standard `"C"' locale, there are no such
     additional characters.

 -- Function: int isdigit (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a decimal digit (`0' through `9').

 -- Function: int isalnum (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is an alphanumeric character (a letter or
     number); in other words, if either `isalpha' or `isdigit' is true
     of a character, then `isalnum' is also true.

 -- Function: int isxdigit (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a hexadecimal digit.  Hexadecimal digits
     include the normal decimal digits `0' through `9' and the letters
     `A' through `F' and `a' through `f'.

 -- Function: int ispunct (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a punctuation character.  This means any
     printing character that is not alphanumeric or a space character.

 -- Function: int isspace (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a "whitespace" character.  In the standard
     `"C"' locale, `isspace' returns true for only the standard
     whitespace characters:

    `' ''
          space

    `'\f''
          formfeed

    `'\n''
          newline

    `'\r''
          carriage return

    `'\t''
          horizontal tab

    `'\v''
          vertical tab

 -- Function: int isblank (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a blank character; that is, a space or a tab.
     This function was originally a GNU extension, but was added in
     ISO C99.

 -- Function: int isgraph (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a graphic character; that is, a character
     that has a glyph associated with it.  The whitespace characters
     are not considered graphic.

 -- Function: int isprint (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a printing character.  Printing characters
     include all the graphic characters, plus the space (` ') character.

 -- Function: int iscntrl (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a control character (that is, a character that
     is not a printing character).

 -- Function: int isascii (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     Returns true if C is a 7-bit `unsigned char' value that fits into
     the US/UK ASCII character set.  This function is a BSD extension
     and is also an SVID extension.


File: libc.info,  Node: Case Conversion,  Next: Classification of Wide Characters,  Prev: Classification of Characters,  Up: Character Handling

4.2 Case Conversion
===================

This section explains the library functions for performing conversions
such as case mappings on characters.  For example, `toupper' converts
any character to upper case if possible.  If the character can't be
converted, `toupper' returns it unchanged.

   These functions take one argument of type `int', which is the
character to convert, and return the converted character as an `int'.
If the conversion is not applicable to the argument given, the argument
is returned unchanged.

   *Compatibility Note:* In pre-ISO C dialects, instead of returning
the argument unchanged, these functions may fail when the argument is
not suitable for the conversion.  Thus for portability, you may need to
write `islower(c) ? toupper(c) : c' rather than just `toupper(c)'.

   These functions are declared in the header file `ctype.h'.  

 -- Function: int tolower (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     If C is an upper-case letter, `tolower' returns the corresponding
     lower-case letter.  If C is not an upper-case letter, C is
     returned unchanged.

 -- Function: int toupper (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     If C is a lower-case letter, `toupper' returns the corresponding
     upper-case letter.  Otherwise C is returned unchanged.

 -- Function: int toascii (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     This function converts C to a 7-bit `unsigned char' value that
     fits into the US/UK ASCII character set, by clearing the high-order
     bits.  This function is a BSD extension and is also an SVID
     extension.

 -- Function: int _tolower (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     This is identical to `tolower', and is provided for compatibility
     with the SVID.  *Note SVID::.

 -- Function: int _toupper (int C)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     This is identical to `toupper', and is provided for compatibility
     with the SVID.


File: libc.info,  Node: Classification of Wide Characters,  Next: Using Wide Char Classes,  Prev: Case Conversion,  Up: Character Handling

4.3 Character class determination for wide characters
=====================================================

Amendment 1 to ISO C90 defines functions to classify wide characters.
Although the original ISO C90 standard already defined the type
`wchar_t', no functions operating on them were defined.

   The general design of the classification functions for wide
characters is more general.  It allows extensions to the set of
available classifications, beyond those which are always available.
The POSIX standard specifies how extensions can be made, and this is
already implemented in the GNU C Library implementation of the
`localedef' program.

   The character class functions are normally implemented with bitsets,
with a bitset per character.  For a given character, the appropriate
bitset is read from a table and a test is performed as to whether a
certain bit is set.  Which bit is tested for is determined by the class.

   For the wide character classification functions this is made visible.
There is a type classification type defined, a function to retrieve this
value for a given class, and a function to test whether a given
character is in this class, using the classification value.  On top of
this the normal character classification functions as used for `char'
objects can be defined.

 -- Data type: wctype_t
     The `wctype_t' can hold a value which represents a character class.
     The only defined way to generate such a value is by using the
     `wctype' function.

     This type is defined in `wctype.h'.

 -- Function: wctype_t wctype (const char *PROPERTY)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     The `wctype' returns a value representing a class of wide
     characters which is identified by the string PROPERTY.  Beside
     some standard properties each locale can define its own ones.  In
     case no property with the given name is known for the current
     locale selected for the `LC_CTYPE' category, the function returns
     zero.

     The properties known in every locale are:

     `"alnum"'         `"alpha"'         `"cntrl"'         `"digit"'
     `"graph"'         `"lower"'         `"print"'         `"punct"'
     `"space"'         `"upper"'         `"xdigit"'        

     This function is declared in `wctype.h'.

   To test the membership of a character to one of the non-standard
classes the ISO C standard defines a completely new function.

 -- Function: int iswctype (wint_t WC, wctype_t DESC)
     Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
     Concepts::.

     This function returns a nonzero value if WC is in the character
     class specified by DESC.  DESC must previously be returned by a
     successful call to `wctype'.

     This function is declared in `wctype.h'.

   To make it easier to use the commonly-used classification functions,
they are defined in the C library.  There is no need to use `wctype' if
the property string is one of the known character classes.  In some
situations it is desirable to construct the property strings, and then
it is important that `wctype' can also handle the standard classes.

 -- Function: int iswalnum (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     This function returns a nonzero value if WC is an alphanumeric
     character (a letter or number); in other words, if either
     `iswalpha' or `iswdigit' is true of a character, then `iswalnum'
     is also true.

     This function can be implemented using

          iswctype (wc, wctype ("alnum"))

     It is declared in `wctype.h'.

 -- Function: int iswalpha (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is an alphabetic character (a letter).  If
     `iswlower' or `iswupper' is true of a character, then `iswalpha'
     is also true.

     In some locales, there may be additional characters for which
     `iswalpha' is true--letters which are neither upper case nor lower
     case.  But in the standard `"C"' locale, there are no such
     additional characters.

     This function can be implemented using

          iswctype (wc, wctype ("alpha"))

     It is declared in `wctype.h'.

 -- Function: int iswcntrl (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a control character (that is, a character
     that is not a printing character).

     This function can be implemented using

          iswctype (wc, wctype ("cntrl"))

     It is declared in `wctype.h'.

 -- Function: int iswdigit (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a digit (e.g., `0' through `9').  Please
     note that this function does not only return a nonzero value for
     _decimal_ digits, but for all kinds of digits.  A consequence is
     that code like the following will *not* work unconditionally for
     wide characters:

          n = 0;
          while (iswdigit (*wc))
            {
              n *= 10;
              n += *wc++ - L'0';
            }

     This function can be implemented using

          iswctype (wc, wctype ("digit"))

     It is declared in `wctype.h'.

 -- Function: int iswgraph (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a graphic character; that is, a character
     that has a glyph associated with it.  The whitespace characters
     are not considered graphic.

     This function can be implemented using

          iswctype (wc, wctype ("graph"))

     It is declared in `wctype.h'.

 -- Function: int iswlower (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a lower-case letter.  The letter need not be
     from the Latin alphabet, any alphabet representable is valid.

     This function can be implemented using

          iswctype (wc, wctype ("lower"))

     It is declared in `wctype.h'.

 -- Function: int iswprint (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a printing character.  Printing characters
     include all the graphic characters, plus the space (` ') character.

     This function can be implemented using

          iswctype (wc, wctype ("print"))

     It is declared in `wctype.h'.

 -- Function: int iswpunct (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a punctuation character.  This means any
     printing character that is not alphanumeric or a space character.

     This function can be implemented using

          iswctype (wc, wctype ("punct"))

     It is declared in `wctype.h'.

 -- Function: int iswspace (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a "whitespace" character.  In the standard
     `"C"' locale, `iswspace' returns true for only the standard
     whitespace characters:

    `L' ''
          space

    `L'\f''
          formfeed

    `L'\n''
          newline

    `L'\r''
          carriage return

    `L'\t''
          horizontal tab

    `L'\v''
          vertical tab

     This function can be implemented using

          iswctype (wc, wctype ("space"))

     It is declared in `wctype.h'.

 -- Function: int iswupper (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is an upper-case letter.  The letter need not be
     from the Latin alphabet, any alphabet representable is valid.

     This function can be implemented using

          iswctype (wc, wctype ("upper"))

     It is declared in `wctype.h'.

 -- Function: int iswxdigit (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a hexadecimal digit.  Hexadecimal digits
     include the normal decimal digits `0' through `9' and the letters
     `A' through `F' and `a' through `f'.

     This function can be implemented using

          iswctype (wc, wctype ("xdigit"))

     It is declared in `wctype.h'.

   The GNU C Library also provides a function which is not defined in
the ISO C standard but which is available as a version for single byte
characters as well.

 -- Function: int iswblank (wint_t WC)
     Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
     Safety Concepts::.

     Returns true if WC is a blank character; that is, a space or a tab.
     This function was originally a GNU extension, but was added in
     ISO C99.  It is declared in `wchar.h'.


File: libc.info,  Node: Using Wide Char Classes,  Next: Wide Character Case Conversion,  Prev: Classification of Wide Characters,  Up: Character Handling

4.4 Notes on using the wide character classes
=============================================

The first note is probably not astonishing but still occasionally a
cause of problems.  The `iswXXX' functions can be implemented using
macros and in fact, the GNU C Library does this.  They are still
available as real functions but when the `wctype.h' header is included
the macros will be used.  This is the same as the `char' type versions
of these functions.

   The second note covers something new.  It can be best illustrated by
a (real-world) example.  The first piece of code is an excerpt from the
original code.  It is truncated a bit but the intention should be clear.

     int
     is_in_class (int c, const char *class)
     {
       if (strcmp (class, "alnum") == 0)
         return isalnum (c);
       if (strcmp (class, "alpha") == 0)
         return isalpha (c);
       if (strcmp (class, "cntrl") == 0)
         return iscntrl (c);
       ...
       return 0;
     }

   Now, with the `wctype' and `iswctype' you can avoid the `if'
cascades, but rewriting the code as follows is wrong:

     int
     is_in_class (int c, const char *class)
     {
       wctype_t desc = wctype (class);
       return desc ? iswctype ((wint_t) c, desc) : 0;
     }

   The problem is that it is not guaranteed that the wide character
representation of a single-byte character can be found using casting.
In fact, usually this fails miserably.  The correct solution to this
problem is to write the code as follows:

     int
     is_in_class (int c, const char *class)
     {
       wctype_t desc = wctype (class);
       return desc ? iswctype (btowc (c), desc) : 0;
     }

   *Note Converting a Character::, for more information on `btowc'.
Note that this change probably does not improve the performance of the
program a lot since the `wctype' function still has to make the string
comparisons.  It gets really interesting if the `is_in_class' function
is called more than once for the same class name.  In this case the
variable DESC could be computed once and reused for all the calls.
Therefore the above form of the function is probably not the final one.