arm-buildroot-linux-gnueabi/sysroot/usr/share/info/libc.info-4 - toolchains/mindspeed - Git at Google

 This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.

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


 File: libc.info,  Node: Flags for Globbing,  Next: More Flags for Globbing,  Prev: Calling Glob,  Up: Globbing

 10.2.2 Flags for Globbing
 -------------------------

 This section describes the standard flags that you can specify in the
 FLAGS argument to 'glob'.  Choose the flags you want, and combine them
 with the C bitwise OR operator '|'.

    Note that there are *note More Flags for Globbing:: available as GNU
 extensions.

 'GLOB_APPEND'
      Append the words from this expansion to the vector of words
      produced by previous calls to 'glob'.  This way you can effectively
      expand several words as if they were concatenated with spaces
      between them.

      In order for appending to work, you must not modify the contents of
      the word vector structure between calls to 'glob'.  And, if you set
      'GLOB_DOOFFS' in the first call to 'glob', you must also set it
      when you append to the results.

      Note that the pointer stored in 'gl_pathv' may no longer be valid
      after you call 'glob' the second time, because 'glob' might have
      relocated the vector.  So always fetch 'gl_pathv' from the 'glob_t'
      structure after each 'glob' call; *never* save the pointer across
      calls.

 'GLOB_DOOFFS'
      Leave blank slots at the beginning of the vector of words.  The
      'gl_offs' field says how many slots to leave.  The blank slots
      contain null pointers.

 'GLOB_ERR'
      Give up right away and report an error if there is any difficulty
      reading the directories that must be read in order to expand
      PATTERN fully.  Such difficulties might include a directory in
      which you don't have the requisite access.  Normally, 'glob' tries
      its best to keep on going despite any errors, reading whatever
      directories it can.

      You can exercise even more control than this by specifying an
      error-handler function ERRFUNC when you call 'glob'.  If ERRFUNC is
      not a null pointer, then 'glob' doesn't give up right away when it
      can't read a directory; instead, it calls ERRFUNC with two
      arguments, like this:

           (*ERRFUNC) (FILENAME, ERROR-CODE)

      The argument FILENAME is the name of the directory that 'glob'
      couldn't open or couldn't read, and ERROR-CODE is the 'errno' value
      that was reported to 'glob'.

      If the error handler function returns nonzero, then 'glob' gives up
      right away.  Otherwise, it continues.

 'GLOB_MARK'
      If the pattern matches the name of a directory, append '/' to the
      directory's name when returning it.

 'GLOB_NOCHECK'
      If the pattern doesn't match any file names, return the pattern
      itself as if it were a file name that had been matched.  (Normally,
      when the pattern doesn't match anything, 'glob' returns that there
      were no matches.)

 'GLOB_NOESCAPE'
      Don't treat the '\' character specially in patterns.  Normally, '\'
      quotes the following character, turning off its special meaning (if
      any) so that it matches only itself.  When quoting is enabled, the
      pattern '\?' matches only the string '?', because the question mark
      in the pattern acts like an ordinary character.

      If you use 'GLOB_NOESCAPE', then '\' is an ordinary character.

      'glob' does its work by calling the function 'fnmatch' repeatedly.
      It handles the flag 'GLOB_NOESCAPE' by turning on the
      'FNM_NOESCAPE' flag in calls to 'fnmatch'.

 'GLOB_NOSORT'
      Don't sort the file names; return them in no particular order.  (In
      practice, the order will depend on the order of the entries in the
      directory.)  The only reason _not_ to sort is to save time.


 File: libc.info,  Node: More Flags for Globbing,  Prev: Flags for Globbing,  Up: Globbing

 10.2.3 More Flags for Globbing
 ------------------------------

 Beside the flags described in the last section, the GNU implementation
 of 'glob' allows a few more flags which are also defined in the 'glob.h'
 file.  Some of the extensions implement functionality which is available
 in modern shell implementations.

 'GLOB_PERIOD'
      The '.' character (period) is treated special.  It cannot be
      matched by wildcards.  *Note Wildcard Matching::, 'FNM_PERIOD'.

 'GLOB_MAGCHAR'
      The 'GLOB_MAGCHAR' value is not to be given to 'glob' in the FLAGS
      parameter.  Instead, 'glob' sets this bit in the GL_FLAGS element
      of the GLOB_T structure provided as the result if the pattern used
      for matching contains any wildcard character.

 'GLOB_ALTDIRFUNC'
      Instead of the using the using the normal functions for accessing
      the filesystem the 'glob' implementation uses the user-supplied
      functions specified in the structure pointed to by PGLOB parameter.
      For more information about the functions refer to the sections
      about directory handling see *note Accessing Directories::, and
      *note Reading Attributes::.

 'GLOB_BRACE'
      If this flag is given the handling of braces in the pattern is
      changed.  It is now required that braces appear correctly grouped.
      I.e., for each opening brace there must be a closing one.  Braces
      can be used recursively.  So it is possible to define one brace
      expression in another one.  It is important to note that the range
      of each brace expression is completely contained in the outer brace
      expression (if there is one).

      The string between the matching braces is separated into single
      expressions by splitting at ',' (comma) characters.  The commas
      themselves are discarded.  Please note what we said above about
      recursive brace expressions.  The commas used to separate the
      subexpressions must be at the same level.  Commas in brace
      subexpressions are not matched.  They are used during expansion of
      the brace expression of the deeper level.  The example below shows
      this

           glob ("{foo/{,bar,biz},baz}", GLOB_BRACE, NULL, &result)

      is equivalent to the sequence

           glob ("foo/", GLOB_BRACE, NULL, &result)
           glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)
           glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
           glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)

      if we leave aside error handling.

 'GLOB_NOMAGIC'
      If the pattern contains no wildcard constructs (it is a literal
      file name), return it as the sole "matching" word, even if no file
      exists by that name.

 'GLOB_TILDE'
      If this flag is used the character '~' (tilde) is handled special
      if it appears at the beginning of the pattern.  Instead of being
      taken verbatim it is used to represent the home directory of a
      known user.

      If '~' is the only character in pattern or it is followed by a '/'
      (slash), the home directory of the process owner is substituted.
      Using 'getlogin' and 'getpwnam' the information is read from the
      system databases.  As an example take user 'bart' with his home
      directory at '/home/bart'.  For him a call like

           glob ("~/bin/*", GLOB_TILDE, NULL, &result)

      would return the contents of the directory '/home/bart/bin'.
      Instead of referring to the own home directory it is also possible
      to name the home directory of other users.  To do so one has to
      append the user name after the tilde character.  So the contents of
      user 'homer''s 'bin' directory can be retrieved by

           glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)

      If the user name is not valid or the home directory cannot be
      determined for some reason the pattern is left untouched and itself
      used as the result.  I.e., if in the last example 'home' is not
      available the tilde expansion yields to '"~homer/bin/*"' and 'glob'
      is not looking for a directory named '~homer'.

      This functionality is equivalent to what is available in C-shells
      if the 'nonomatch' flag is set.

 'GLOB_TILDE_CHECK'
      If this flag is used 'glob' behaves like as if 'GLOB_TILDE' is
      given.  The only difference is that if the user name is not
      available or the home directory cannot be determined for other
      reasons this leads to an error.  'glob' will return 'GLOB_NOMATCH'
      instead of using the pattern itself as the name.

      This functionality is equivalent to what is available in C-shells
      if 'nonomatch' flag is not set.

 'GLOB_ONLYDIR'
      If this flag is used the globbing function takes this as a *hint*
      that the caller is only interested in directories matching the
      pattern.  If the information about the type of the file is easily
      available non-directories will be rejected but no extra work will
      be done to determine the information for each file.  I.e., the
      caller must still be able to filter directories out.

      This functionality is only available with the GNU 'glob'
      implementation.  It is mainly used internally to increase the
      performance but might be useful for a user as well and therefore is
      documented here.

    Calling 'glob' will in most cases allocate resources which are used
 to represent the result of the function call.  If the same object of
 type 'glob_t' is used in multiple call to 'glob' the resources are freed
 or reused so that no leaks appear.  But this does not include the time
 when all 'glob' calls are done.

  -- Function: void globfree (glob_t *PGLOB)
      Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe corrupt
      mem | *Note POSIX Safety Concepts::.

      The 'globfree' function frees all resources allocated by previous
      calls to 'glob' associated with the object pointed to by PGLOB.
      This function should be called whenever the currently used 'glob_t'
      typed object isn't used anymore.

  -- Function: void globfree64 (glob64_t *PGLOB)
      Preliminary: | MT-Safe | AS-Unsafe corrupt lock | AC-Unsafe corrupt
      lock fd mem | *Note POSIX Safety Concepts::.

      This function is equivalent to 'globfree' but it frees records of
      type 'glob64_t' which were allocated by 'glob64'.


 File: libc.info,  Node: Regular Expressions,  Next: Word Expansion,  Prev: Globbing,  Up: Pattern Matching

 10.3 Regular Expression Matching
 ================================

 The GNU C Library supports two interfaces for matching regular
 expressions.  One is the standard POSIX.2 interface, and the other is
 what the GNU C Library has had for many years.

    Both interfaces are declared in the header file 'regex.h'.  If you
 define '_POSIX_C_SOURCE', then only the POSIX.2 functions, structures,
 and constants are declared.

 * Menu:

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


 File: libc.info,  Node: POSIX Regexp Compilation,  Next: Flags for POSIX Regexps,  Up: Regular Expressions

 10.3.1 POSIX Regular Expression Compilation
 -------------------------------------------

 Before you can actually match a regular expression, you must "compile"
 it.  This is not true compilation--it produces a special data structure,
 not machine instructions.  But it is like ordinary compilation in that
 its purpose is to enable you to "execute" the pattern fast.  (*Note
 Matching POSIX Regexps::, for how to use the compiled regular expression
 for matching.)

    There is a special data type for compiled regular expressions:

  -- Data Type: regex_t
      This type of object holds a compiled regular expression.  It is
      actually a structure.  It has just one field that your programs
      should look at:

      're_nsub'
           This field holds the number of parenthetical subexpressions in
           the regular expression that was compiled.

      There are several other fields, but we don't describe them here,
      because only the functions in the library should use them.

    After you create a 'regex_t' object, you can compile a regular
 expression into it by calling 'regcomp'.

  -- Function: int regcomp (regex_t *restrict COMPILED, const char
           *restrict PATTERN, int CFLAGS)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
      | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.

      The function 'regcomp' "compiles" a regular expression into a data
      structure that you can use with 'regexec' to match against a
      string.  The compiled regular expression format is designed for
      efficient matching.  'regcomp' stores it into '*COMPILED'.

      It's up to you to allocate an object of type 'regex_t' and pass its
      address to 'regcomp'.

      The argument CFLAGS lets you specify various options that control
      the syntax and semantics of regular expressions.  *Note Flags for
      POSIX Regexps::.

      If you use the flag 'REG_NOSUB', then 'regcomp' omits from the
      compiled regular expression the information necessary to record how
      subexpressions actually match.  In this case, you might as well
      pass '0' for the MATCHPTR and NMATCH arguments when you call
      'regexec'.

      If you don't use 'REG_NOSUB', then the compiled regular expression
      does have the capacity to record how subexpressions match.  Also,
      'regcomp' tells you how many subexpressions PATTERN has, by storing
      the number in 'COMPILED->re_nsub'.  You can use that value to
      decide how long an array to allocate to hold information about
      subexpression matches.

      'regcomp' returns '0' if it succeeds in compiling the regular
      expression; otherwise, it returns a nonzero error code (see the
      table below).  You can use 'regerror' to produce an error message
      string describing the reason for a nonzero value; see *note Regexp
      Cleanup::.

    Here are the possible nonzero values that 'regcomp' can return:

 'REG_BADBR'
      There was an invalid '\{...\}' construct in the regular expression.
      A valid '\{...\}' construct must contain either a single number, or
      two numbers in increasing order separated by a comma.

 'REG_BADPAT'
      There was a syntax error in the regular expression.

 'REG_BADRPT'
      A repetition operator such as '?' or '*' appeared in a bad position
      (with no preceding subexpression to act on).

 'REG_ECOLLATE'
      The regular expression referred to an invalid collating element
      (one not defined in the current locale for string collation).
      *Note Locale Categories::.

 'REG_ECTYPE'
      The regular expression referred to an invalid character class name.

 'REG_EESCAPE'
      The regular expression ended with '\'.

 'REG_ESUBREG'
      There was an invalid number in the '\DIGIT' construct.

 'REG_EBRACK'
      There were unbalanced square brackets in the regular expression.

 'REG_EPAREN'
      An extended regular expression had unbalanced parentheses, or a
      basic regular expression had unbalanced '\(' and '\)'.

 'REG_EBRACE'
      The regular expression had unbalanced '\{' and '\}'.

 'REG_ERANGE'
      One of the endpoints in a range expression was invalid.

 'REG_ESPACE'
      'regcomp' ran out of memory.


 File: libc.info,  Node: Flags for POSIX Regexps,  Next: Matching POSIX Regexps,  Prev: POSIX Regexp Compilation,  Up: Regular Expressions

 10.3.2 Flags for POSIX Regular Expressions
 ------------------------------------------

 These are the bit flags that you can use in the CFLAGS operand when
 compiling a regular expression with 'regcomp'.

 'REG_EXTENDED'
      Treat the pattern as an extended regular expression, rather than as
      a basic regular expression.

 'REG_ICASE'
      Ignore case when matching letters.

 'REG_NOSUB'
      Don't bother storing the contents of the MATCHES-PTR array.

 'REG_NEWLINE'
      Treat a newline in STRING as dividing STRING into multiple lines,
      so that '$' can match before the newline and '^' can match after.
      Also, don't permit '.' to match a newline, and don't permit
      '[^...]' to match a newline.

      Otherwise, newline acts like any other ordinary character.


 File: libc.info,  Node: Matching POSIX Regexps,  Next: Regexp Subexpressions,  Prev: Flags for POSIX Regexps,  Up: Regular Expressions

 10.3.3 Matching a Compiled POSIX Regular Expression
 ---------------------------------------------------

 Once you have compiled a regular expression, as described in *note POSIX
 Regexp Compilation::, you can match it against strings using 'regexec'.
 A match anywhere inside the string counts as success, unless the regular
 expression contains anchor characters ('^' or '$').

  -- Function: int regexec (const regex_t *restrict COMPILED, const char
           *restrict STRING, size_t NMATCH, regmatch_t
           MATCHPTR[restrict], int EFLAGS)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
      | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.

      This function tries to match the compiled regular expression
      '*COMPILED' against STRING.

      'regexec' returns '0' if the regular expression matches; otherwise,
      it returns a nonzero value.  See the table below for what nonzero
      values mean.  You can use 'regerror' to produce an error message
      string describing the reason for a nonzero value; see *note Regexp
      Cleanup::.

      The argument EFLAGS is a word of bit flags that enable various
      options.

      If you want to get information about what part of STRING actually
      matched the regular expression or its subexpressions, use the
      arguments MATCHPTR and NMATCH.  Otherwise, pass '0' for NMATCH, and
      'NULL' for MATCHPTR.  *Note Regexp Subexpressions::.

    You must match the regular expression with the same set of current
 locales that were in effect when you compiled the regular expression.

    The function 'regexec' accepts the following flags in the EFLAGS
 argument:

 'REG_NOTBOL'
      Do not regard the beginning of the specified string as the
      beginning of a line; more generally, don't make any assumptions
      about what text might precede it.

 'REG_NOTEOL'
      Do not regard the end of the specified string as the end of a line;
      more generally, don't make any assumptions about what text might
      follow it.

    Here are the possible nonzero values that 'regexec' can return:

 'REG_NOMATCH'
      The pattern didn't match the string.  This isn't really an error.

 'REG_ESPACE'
      'regexec' ran out of memory.


 File: libc.info,  Node: Regexp Subexpressions,  Next: Subexpression Complications,  Prev: Matching POSIX Regexps,  Up: Regular Expressions

 10.3.4 Match Results with Subexpressions
 ----------------------------------------

 When 'regexec' matches parenthetical subexpressions of PATTERN, it
 records which parts of STRING they match.  It returns that information
 by storing the offsets into an array whose elements are structures of
 type 'regmatch_t'.  The first element of the array (index '0') records
 the part of the string that matched the entire regular expression.  Each
 other element of the array records the beginning and end of the part
 that matched a single parenthetical subexpression.

  -- Data Type: regmatch_t
      This is the data type of the MATCHARRAY array that you pass to
      'regexec'.  It contains two structure fields, as follows:

      'rm_so'
           The offset in STRING of the beginning of a substring.  Add
           this value to STRING to get the address of that part.

      'rm_eo'
           The offset in STRING of the end of the substring.

  -- Data Type: regoff_t
      'regoff_t' is an alias for another signed integer type.  The fields
      of 'regmatch_t' have type 'regoff_t'.

    The 'regmatch_t' elements correspond to subexpressions positionally;
 the first element (index '1') records where the first subexpression
 matched, the second element records the second subexpression, and so on.
 The order of the subexpressions is the order in which they begin.

    When you call 'regexec', you specify how long the MATCHPTR array is,
 with the NMATCH argument.  This tells 'regexec' how many elements to
 store.  If the actual regular expression has more than NMATCH
 subexpressions, then you won't get offset information about the rest of
 them.  But this doesn't alter whether the pattern matches a particular
 string or not.

    If you don't want 'regexec' to return any information about where the
 subexpressions matched, you can either supply '0' for NMATCH, or use the
 flag 'REG_NOSUB' when you compile the pattern with 'regcomp'.


 File: libc.info,  Node: Subexpression Complications,  Next: Regexp Cleanup,  Prev: Regexp Subexpressions,  Up: Regular Expressions

 10.3.5 Complications in Subexpression Matching
 ----------------------------------------------

 Sometimes a subexpression matches a substring of no characters.  This
 happens when 'f\(o*\)' matches the string 'fum'.  (It really matches
 just the 'f'.)  In this case, both of the offsets identify the point in
 the string where the null substring was found.  In this example, the
 offsets are both '1'.

    Sometimes the entire regular expression can match without using some
 of its subexpressions at all--for example, when 'ba\(na\)*' matches the
 string 'ba', the parenthetical subexpression is not used.  When this
 happens, 'regexec' stores '-1' in both fields of the element for that
 subexpression.

    Sometimes matching the entire regular expression can match a
 particular subexpression more than once--for example, when 'ba\(na\)*'
 matches the string 'bananana', the parenthetical subexpression matches
 three times.  When this happens, 'regexec' usually stores the offsets of
 the last part of the string that matched the subexpression.  In the case
 of 'bananana', these offsets are '6' and '8'.

    But the last match is not always the one that is chosen.  It's more
 accurate to say that the last _opportunity_ to match is the one that
 takes precedence.  What this means is that when one subexpression
 appears within another, then the results reported for the inner
 subexpression reflect whatever happened on the last match of the outer
 subexpression.  For an example, consider '\(ba\(na\)*s \)*' matching the
 string 'bananas bas '.  The last time the inner expression actually
 matches is near the end of the first word.  But it is _considered_ again
 in the second word, and fails to match there.  'regexec' reports nonuse
 of the "na" subexpression.

    Another place where this rule applies is when the regular expression
      \(ba\(na\)*s \|nefer\(ti\)* \)*
 matches 'bananas nefertiti'.  The "na" subexpression does match in the
 first word, but it doesn't match in the second word because the other
 alternative is used there.  Once again, the second repetition of the
 outer subexpression overrides the first, and within that second
 repetition, the "na" subexpression is not used.  So 'regexec' reports
 nonuse of the "na" subexpression.


 File: libc.info,  Node: Regexp Cleanup,  Prev: Subexpression Complications,  Up: Regular Expressions

 10.3.6 POSIX Regexp Matching Cleanup
 ------------------------------------

 When you are finished using a compiled regular expression, you can free
 the storage it uses by calling 'regfree'.

  -- Function: void regfree (regex_t *COMPILED)
      Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
      POSIX Safety Concepts::.

      Calling 'regfree' frees all the storage that '*COMPILED' points to.
      This includes various internal fields of the 'regex_t' structure
      that aren't documented in this manual.

      'regfree' does not free the object '*COMPILED' itself.

    You should always free the space in a 'regex_t' structure with
 'regfree' before using the structure to compile another regular
 expression.

    When 'regcomp' or 'regexec' reports an error, you can use the
 function 'regerror' to turn it into an error message string.

  -- Function: size_t regerror (int ERRCODE, const regex_t *restrict
           COMPILED, char *restrict BUFFER, size_t LENGTH)
      Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
      AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.

      This function produces an error message string for the error code
      ERRCODE, and stores the string in LENGTH bytes of memory starting
      at BUFFER.  For the COMPILED argument, supply the same compiled
      regular expression structure that 'regcomp' or 'regexec' was
      working with when it got the error.  Alternatively, you can supply
      'NULL' for COMPILED; you will still get a meaningful error message,
      but it might not be as detailed.

      If the error message can't fit in LENGTH bytes (including a
      terminating null character), then 'regerror' truncates it.  The
      string that 'regerror' stores is always null-terminated even if it
      has been truncated.

      The return value of 'regerror' is the minimum length needed to
      store the entire error message.  If this is less than LENGTH, then
      the error message was not truncated, and you can use it.
      Otherwise, you should call 'regerror' again with a larger buffer.

      Here is a function which uses 'regerror', but always dynamically
      allocates a buffer for the error message:

           char *get_regerror (int errcode, regex_t *compiled)
           {
             size_t length = regerror (errcode, compiled, NULL, 0);
             char *buffer = xmalloc (length);
             (void) regerror (errcode, compiled, buffer, length);
             return buffer;
           }


 File: libc.info,  Node: Word Expansion,  Prev: Regular Expressions,  Up: Pattern Matching

 10.4 Shell-Style Word Expansion
 ===============================

 "Word expansion" means the process of splitting a string into "words"
 and substituting for variables, commands, and wildcards just as the
 shell does.

    For example, when you write 'ls -l foo.c', this string is split into
 three separate words--'ls', '-l' and 'foo.c'.  This is the most basic
 function of word expansion.

    When you write 'ls *.c', this can become many words, because the word
 '*.c' can be replaced with any number of file names.  This is called
 "wildcard expansion", and it is also a part of word expansion.

    When you use 'echo $PATH' to print your path, you are taking
 advantage of "variable substitution", which is also part of word
 expansion.

    Ordinary programs can perform word expansion just like the shell by
 calling the library function 'wordexp'.

 * Menu:

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


 File: libc.info,  Node: Expansion Stages,  Next: Calling Wordexp,  Up: Word Expansion

 10.4.1 The Stages of Word Expansion
 -----------------------------------

 When word expansion is applied to a sequence of words, it performs the
 following transformations in the order shown here:

   1. "Tilde expansion": Replacement of '~foo' with the name of the home
      directory of 'foo'.

   2. Next, three different transformations are applied in the same step,
      from left to right:

         * "Variable substitution": Environment variables are substituted
           for references such as '$foo'.

         * "Command substitution": Constructs such as '`cat foo`' and the
           equivalent '$(cat foo)' are replaced with the output from the
           inner command.

         * "Arithmetic expansion": Constructs such as '$(($x-1))' are
           replaced with the result of the arithmetic computation.

   3. "Field splitting": subdivision of the text into "words".

   4. "Wildcard expansion": The replacement of a construct such as '*.c'
      with a list of '.c' file names.  Wildcard expansion applies to an
      entire word at a time, and replaces that word with 0 or more file
      names that are themselves words.

   5. "Quote removal": The deletion of string-quotes, now that they have
      done their job by inhibiting the above transformations when
      appropriate.

    For the details of these transformations, and how to write the
 constructs that use them, see 'The BASH Manual' (to appear).


 File: libc.info,  Node: Calling Wordexp,  Next: Flags for Wordexp,  Prev: Expansion Stages,  Up: Word Expansion

 10.4.2 Calling 'wordexp'
 ------------------------

 All the functions, constants and data types for word expansion are
 declared in the header file 'wordexp.h'.

    Word expansion produces a vector of words (strings).  To return this
 vector, 'wordexp' uses a special data type, 'wordexp_t', which is a
 structure.  You pass 'wordexp' the address of the structure, and it
 fills in the structure's fields to tell you about the results.

  -- Data Type: wordexp_t
      This data type holds a pointer to a word vector.  More precisely,
      it records both the address of the word vector and its size.

      'we_wordc'
           The number of elements in the vector.

      'we_wordv'
           The address of the vector.  This field has type 'char **'.

      'we_offs'
           The offset of the first real element of the vector, from its
           nominal address in the 'we_wordv' field.  Unlike the other
           fields, this is always an input to 'wordexp', rather than an
           output from it.

           If you use a nonzero offset, then that many elements at the
           beginning of the vector are left empty.  (The 'wordexp'
           function fills them with null pointers.)

           The 'we_offs' field is meaningful only if you use the
           'WRDE_DOOFFS' flag.  Otherwise, the offset is always zero
           regardless of what is in this field, and the first real
           element comes at the beginning of the vector.

  -- Function: int wordexp (const char *WORDS, wordexp_t
           *WORD-VECTOR-PTR, int FLAGS)
      Preliminary: | MT-Unsafe race:utent const:env env sig:ALRM timer
      locale | AS-Unsafe dlopen plugin i18n heap corrupt lock | AC-Unsafe
      corrupt lock fd mem | *Note POSIX Safety Concepts::.

      Perform word expansion on the string WORDS, putting the result in a
      newly allocated vector, and store the size and address of this
      vector into '*WORD-VECTOR-PTR'.  The argument FLAGS is a
      combination of bit flags; see *note Flags for Wordexp::, for
      details of the flags.

      You shouldn't use any of the characters '|&;<>' in the string WORDS
      unless they are quoted; likewise for newline.  If you use these
      characters unquoted, you will get the 'WRDE_BADCHAR' error code.
      Don't use parentheses or braces unless they are quoted or part of a
      word expansion construct.  If you use quotation characters ''"`',
      they should come in pairs that balance.

      The results of word expansion are a sequence of words.  The
      function 'wordexp' allocates a string for each resulting word, then
      allocates a vector of type 'char **' to store the addresses of
      these strings.  The last element of the vector is a null pointer.
      This vector is called the "word vector".

      To return this vector, 'wordexp' stores both its address and its
      length (number of elements, not counting the terminating null
      pointer) into '*WORD-VECTOR-PTR'.

      If 'wordexp' succeeds, it returns 0.  Otherwise, it returns one of
      these error codes:

      'WRDE_BADCHAR'
           The input string WORDS contains an unquoted invalid character
           such as '|'.

      'WRDE_BADVAL'
           The input string refers to an undefined shell variable, and
           you used the flag 'WRDE_UNDEF' to forbid such references.

      'WRDE_CMDSUB'
           The input string uses command substitution, and you used the
           flag 'WRDE_NOCMD' to forbid command substitution.

      'WRDE_NOSPACE'
           It was impossible to allocate memory to hold the result.  In
           this case, 'wordexp' can store part of the results--as much as
           it could allocate room for.

      'WRDE_SYNTAX'
           There was a syntax error in the input string.  For example, an
           unmatched quoting character is a syntax error.

  -- Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
      Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe corrupt
      mem | *Note POSIX Safety Concepts::.

      Free the storage used for the word-strings and vector that
      '*WORD-VECTOR-PTR' points to.  This does not free the structure
      '*WORD-VECTOR-PTR' itself--only the other data it points to.


 File: libc.info,  Node: Flags for Wordexp,  Next: Wordexp Example,  Prev: Calling Wordexp,  Up: Word Expansion

 10.4.3 Flags for Word Expansion
 -------------------------------

 This section describes the flags that you can specify in the FLAGS
 argument to 'wordexp'.  Choose the flags you want, and combine them with
 the C operator '|'.

 'WRDE_APPEND'
      Append the words from this expansion to the vector of words
      produced by previous calls to 'wordexp'.  This way you can
      effectively expand several words as if they were concatenated with
      spaces between them.

      In order for appending to work, you must not modify the contents of
      the word vector structure between calls to 'wordexp'.  And, if you
      set 'WRDE_DOOFFS' in the first call to 'wordexp', you must also set
      it when you append to the results.

 'WRDE_DOOFFS'
      Leave blank slots at the beginning of the vector of words.  The
      'we_offs' field says how many slots to leave.  The blank slots
      contain null pointers.

 'WRDE_NOCMD'
      Don't do command substitution; if the input requests command
      substitution, report an error.

 'WRDE_REUSE'
      Reuse a word vector made by a previous call to 'wordexp'.  Instead
      of allocating a new vector of words, this call to 'wordexp' will
      use the vector that already exists (making it larger if necessary).

      Note that the vector may move, so it is not safe to save an old
      pointer and use it again after calling 'wordexp'.  You must fetch
      'we_pathv' anew after each call.

 'WRDE_SHOWERR'
      Do show any error messages printed by commands run by command
      substitution.  More precisely, allow these commands to inherit the
      standard error output stream of the current process.  By default,
      'wordexp' gives these commands a standard error stream that
      discards all output.

 'WRDE_UNDEF'
      If the input refers to a shell variable that is not defined, report
      an error.


 File: libc.info,  Node: Wordexp Example,  Next: Tilde Expansion,  Prev: Flags for Wordexp,  Up: Word Expansion

 10.4.4 'wordexp' Example
 ------------------------

 Here is an example of using 'wordexp' to expand several strings and use
 the results to run a shell command.  It also shows the use of
 'WRDE_APPEND' to concatenate the expansions and of 'wordfree' to free
 the space allocated by 'wordexp'.

      int
      expand_and_execute (const char *program, const char **options)
      {
        wordexp_t result;
        pid_t pid
        int status, i;

        /* Expand the string for the program to run.  */
        switch (wordexp (program, &result, 0))
          {
          case 0:			/* Successful.  */
            break;
          case WRDE_NOSPACE:
            /* If the error was 'WRDE_NOSPACE',
               then perhaps part of the result was allocated.  */
            wordfree (&result);
          default:                    /* Some other error.  */
            return -1;
          }

        /* Expand the strings specified for the arguments.  */
        for (i = 0; options[i] != NULL; i++)
          {
            if (wordexp (options[i], &result, WRDE_APPEND))
              {
                wordfree (&result);
                return -1;
              }
          }

        pid = fork ();
        if (pid == 0)
          {
            /* This is the child process.  Execute the command. */
            execv (result.we_wordv[0], result.we_wordv);
            exit (EXIT_FAILURE);
          }
        else if (pid < 0)
          /* The fork failed.  Report failure.  */
          status = -1;
        else
          /* This is the parent process.  Wait for the child to complete.  */
          if (waitpid (pid, &status, 0) != pid)
            status = -1;

        wordfree (&result);
        return status;
      }


 File: libc.info,  Node: Tilde Expansion,  Next: Variable Substitution,  Prev: Wordexp Example,  Up: Word Expansion

 10.4.5 Details of Tilde Expansion
 ---------------------------------

 It's a standard part of shell syntax that you can use '~' at the
 beginning of a file name to stand for your own home directory.  You can
 use '~USER' to stand for USER's home directory.

    "Tilde expansion" is the process of converting these abbreviations to
 the directory names that they stand for.

    Tilde expansion applies to the '~' plus all following characters up
 to whitespace or a slash.  It takes place only at the beginning of a
 word, and only if none of the characters to be transformed is quoted in
 any way.

    Plain '~' uses the value of the environment variable 'HOME' as the
 proper home directory name.  '~' followed by a user name uses
 'getpwname' to look up that user in the user database, and uses whatever
 directory is recorded there.  Thus, '~' followed by your own name can
 give different results from plain '~', if the value of 'HOME' is not
 really your home directory.


 File: libc.info,  Node: Variable Substitution,  Prev: Tilde Expansion,  Up: Word Expansion

 10.4.6 Details of Variable Substitution
 ---------------------------------------

 Part of ordinary shell syntax is the use of '$VARIABLE' to substitute
 the value of a shell variable into a command.  This is called "variable
 substitution", and it is one part of doing word expansion.

    There are two basic ways you can write a variable reference for
 substitution:

 '${VARIABLE}'
      If you write braces around the variable name, then it is completely
      unambiguous where the variable name ends.  You can concatenate
      additional letters onto the end of the variable value by writing
      them immediately after the close brace.  For example, '${foo}s'
      expands into 'tractors'.

 '$VARIABLE'
      If you do not put braces around the variable name, then the
      variable name consists of all the alphanumeric characters and
      underscores that follow the '$'.  The next punctuation character
      ends the variable name.  Thus, '$foo-bar' refers to the variable
      'foo' and expands into 'tractor-bar'.

    When you use braces, you can also use various constructs to modify
 the value that is substituted, or test it in various ways.

 '${VARIABLE:-DEFAULT}'
      Substitute the value of VARIABLE, but if that is empty or
      undefined, use DEFAULT instead.

 '${VARIABLE:=DEFAULT}'
      Substitute the value of VARIABLE, but if that is empty or
      undefined, use DEFAULT instead and set the variable to DEFAULT.

 '${VARIABLE:?MESSAGE}'
      If VARIABLE is defined and not empty, substitute its value.

      Otherwise, print MESSAGE as an error message on the standard error
      stream, and consider word expansion a failure.

 '${VARIABLE:+REPLACEMENT}'
      Substitute REPLACEMENT, but only if VARIABLE is defined and
      nonempty.  Otherwise, substitute nothing for this construct.

 '${#VARIABLE}'
      Substitute a numeral which expresses in base ten the number of
      characters in the value of VARIABLE.  '${#foo}' stands for '7',
      because 'tractor' is seven characters.

    These variants of variable substitution let you remove part of the
 variable's value before substituting it.  The PREFIX and SUFFIX are not
 mere strings; they are wildcard patterns, just like the patterns that
 you use to match multiple file names.  But in this context, they match
 against parts of the variable value rather than against file names.

 '${VARIABLE%%SUFFIX}'
      Substitute the value of VARIABLE, but first discard from that
      variable any portion at the end that matches the pattern SUFFIX.

      If there is more than one alternative for how to match against
      SUFFIX, this construct uses the longest possible match.

      Thus, '${foo%%r*}' substitutes 't', because the largest match for
      'r*' at the end of 'tractor' is 'ractor'.

 '${VARIABLE%SUFFIX}'
      Substitute the value of VARIABLE, but first discard from that
      variable any portion at the end that matches the pattern SUFFIX.

      If there is more than one alternative for how to match against
      SUFFIX, this construct uses the shortest possible alternative.

      Thus, '${foo%r*}' substitutes 'tracto', because the shortest match
      for 'r*' at the end of 'tractor' is just 'r'.

 '${VARIABLE##PREFIX}'
      Substitute the value of VARIABLE, but first discard from that
      variable any portion at the beginning that matches the pattern
      PREFIX.

      If there is more than one alternative for how to match against
      PREFIX, this construct uses the longest possible match.

      Thus, '${foo##*t}' substitutes 'or', because the largest match for
      '*t' at the beginning of 'tractor' is 'tract'.

 '${VARIABLE#PREFIX}'
      Substitute the value of VARIABLE, but first discard from that
      variable any portion at the beginning that matches the pattern
      PREFIX.

      If there is more than one alternative for how to match against
      PREFIX, this construct uses the shortest possible alternative.

      Thus, '${foo#*t}' substitutes 'ractor', because the shortest match
      for '*t' at the beginning of 'tractor' is just 't'.


 File: libc.info,  Node: I/O Overview,  Next: I/O on Streams,  Prev: Pattern Matching,  Up: Top

 11 Input/Output Overview
 ************************

 Most programs need to do either input (reading data) or output (writing
 data), or most frequently both, in order to do anything useful.  The GNU
 C Library provides such a large selection of input and output functions
 that the hardest part is often deciding which function is most
 appropriate!

    This chapter introduces concepts and terminology relating to input
 and output.  Other chapters relating to the GNU I/O facilities are:

    * *note I/O on Streams::, which covers the high-level functions that
      operate on streams, including formatted input and output.

    * *note Low-Level I/O::, which covers the basic I/O and control
      functions on file descriptors.

    * *note File System Interface::, which covers functions for operating
      on directories and for manipulating file attributes such as access
      modes and ownership.

    * *note Pipes and FIFOs::, which includes information on the basic
      interprocess communication facilities.

    * *note Sockets::, which covers a more complicated interprocess
      communication facility with support for networking.

    * *note Low-Level Terminal Interface::, which covers functions for
      changing how input and output to terminals or other serial devices
      are processed.

 * Menu:

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


 File: libc.info,  Node: I/O Concepts,  Next: File Names,  Up: I/O Overview

 11.1 Input/Output Concepts
 ==========================

 Before you can read or write the contents of a file, you must establish
 a connection or communications channel to the file.  This process is
 called "opening" the file.  You can open a file for reading, writing, or
 both.

    The connection to an open file is represented either as a stream or
 as a file descriptor.  You pass this as an argument to the functions
 that do the actual read or write operations, to tell them which file to
 operate on.  Certain functions expect streams, and others are designed
 to operate on file descriptors.

    When you have finished reading to or writing from the file, you can
 terminate the connection by "closing" the file.  Once you have closed a
 stream or file descriptor, you cannot do any more input or output
 operations on it.

 * Menu:

 * 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: libc.info,  Node: Streams and File Descriptors,  Next: File Position,  Up: I/O Concepts

 11.1.1 Streams and File Descriptors
 -----------------------------------

 When you want to do input or output to a file, you have a choice of two
 basic mechanisms for representing the connection between your program
 and the file: file descriptors and streams.  File descriptors are
 represented as objects of type 'int', while streams are represented as
 'FILE *' objects.

    File descriptors provide a primitive, low-level interface to input
 and output operations.  Both file descriptors and streams can represent
 a connection to a device (such as a terminal), or a pipe or socket for
 communicating with another process, as well as a normal file.  But, if
 you want to do control operations that are specific to a particular kind
 of device, you must use a file descriptor; there are no facilities to
 use streams in this way.  You must also use file descriptors if your
 program needs to do input or output in special modes, such as
 nonblocking (or polled) input (*note File Status Flags::).

    Streams provide a higher-level interface, layered on top of the
 primitive file descriptor facilities.  The stream interface treats all
 kinds of files pretty much alike--the sole exception being the three
 styles of buffering that you can choose (*note Stream Buffering::).

    The main advantage of using the stream interface is that the set of
 functions for performing actual input and output operations (as opposed
 to control operations) on streams is much richer and more powerful than
 the corresponding facilities for file descriptors.  The file descriptor
 interface provides only simple functions for transferring blocks of
 characters, but the stream interface also provides powerful formatted
 input and output functions ('printf' and 'scanf') as well as functions
 for character- and line-oriented input and output.

    Since streams are implemented in terms of file descriptors, you can
 extract the file descriptor from a stream and perform low-level
 operations directly on the file descriptor.  You can also initially open
 a connection as a file descriptor and then make a stream associated with
 that file descriptor.

    In general, you should stick with using streams rather than file
 descriptors, unless there is some specific operation you want to do that
 can only be done on a file descriptor.  If you are a beginning
 programmer and aren't sure what functions to use, we suggest that you
 concentrate on the formatted input functions (*note Formatted Input::)
 and formatted output functions (*note Formatted Output::).

    If you are concerned about portability of your programs to systems
 other than GNU, you should also be aware that file descriptors are not
 as portable as streams.  You can expect any system running ISO C to
 support streams, but non-GNU systems may not support file descriptors at
 all, or may only implement a subset of the GNU functions that operate on
 file descriptors.  Most of the file descriptor functions in the GNU C
 Library are included in the POSIX.1 standard, however.


 File: libc.info,  Node: File Position,  Prev: Streams and File Descriptors,  Up: I/O Concepts

 11.1.2 File Position
 --------------------

 One of the attributes of an open file is its "file position" that keeps
 track of where in the file the next character is to be read or written.
 On GNU systems, and all POSIX.1 systems, the file position is simply an
 integer representing the number of bytes from the beginning of the file.

    The file position is normally set to the beginning of the file when
 it is opened, and each time a character is read or written, the file
 position is incremented.  In other words, access to the file is normally
 "sequential".

    Ordinary files permit read or write operations at any position within
 the file.  Some other kinds of files may also permit this.  Files which
 do permit this are sometimes referred to as "random-access" files.  You
 can change the file position using the 'fseek' function on a stream
 (*note File Positioning::) or the 'lseek' function on a file descriptor
 (*note I/O Primitives::).  If you try to change the file position on a
 file that doesn't support random access, you get the 'ESPIPE' error.

    Streams and descriptors that are opened for "append access" are
 treated specially for output: output to such files is _always_ appended
 sequentially to the _end_ of the file, regardless of the file position.
 However, the file position is still used to control where in the file
 reading is done.

    If you think about it, you'll realize that several programs can read
 a given file at the same time.  In order for each program to be able to
 read the file at its own pace, each program must have its own file
 pointer, which is not affected by anything the other programs do.

    In fact, each opening of a file creates a separate file position.
 Thus, if you open a file twice even in the same program, you get two
 streams or descriptors with independent file positions.

    By contrast, if you open a descriptor and then duplicate it to get
 another descriptor, these two descriptors share the same file position:
 changing the file position of one descriptor will affect the other.


 File: libc.info,  Node: File Names,  Prev: I/O Concepts,  Up: I/O Overview

 11.2 File Names
 ===============

 In order to open a connection to a file, or to perform other operations
 such as deleting a file, you need some way to refer to the file.  Nearly
 all files have names that are strings--even files which are actually
 devices such as tape drives or terminals.  These strings are called
 "file names".  You specify the file name to say which file you want to
 open or operate on.

    This section describes the conventions for file names and how the
 operating system works with them.

 * Menu:

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


 File: libc.info,  Node: Directories,  Next: File Name Resolution,  Up: File Names

 11.2.1 Directories
 ------------------

 In order to understand the syntax of file names, you need to understand
 how the file system is organized into a hierarchy of directories.

    A "directory" is a file that contains information to associate other
 files with names; these associations are called "links" or "directory
 entries".  Sometimes, people speak of "files in a directory", but in
 reality, a directory only contains pointers to files, not the files
 themselves.

    The name of a file contained in a directory entry is called a "file
 name component".  In general, a file name consists of a sequence of one
 or more such components, separated by the slash character ('/').  A file
 name which is just one component names a file with respect to its
 directory.  A file name with multiple components names a directory, and
 then a file in that directory, and so on.

    Some other documents, such as the POSIX standard, use the term
 "pathname" for what we call a file name, and either "filename" or
 "pathname component" for what this manual calls a file name component.
 We don't use this terminology because a "path" is something completely
 different (a list of directories to search), and we think that
 "pathname" used for something else will confuse users.  We always use
 "file name" and "file name component" (or sometimes just "component",
 where the context is obvious) in GNU documentation.  Some macros use the
 POSIX terminology in their names, such as 'PATH_MAX'.  These macros are
 defined by the POSIX standard, so we cannot change their names.

    You can find more detailed information about operations on
 directories in *note File System Interface::.


 File: libc.info,  Node: File Name Resolution,  Next: File Name Errors,  Prev: Directories,  Up: File Names

 11.2.2 File Name Resolution
 ---------------------------

 A file name consists of file name components separated by slash ('/')
 characters.  On the systems that the GNU C Library supports, multiple
 successive '/' characters are equivalent to a single '/' character.

    The process of determining what file a file name refers to is called
 "file name resolution".  This is performed by examining the components
 that make up a file name in left-to-right order, and locating each
 successive component in the directory named by the previous component.
 Of course, each of the files that are referenced as directories must
 actually exist, be directories instead of regular files, and have the
 appropriate permissions to be accessible by the process; otherwise the
 file name resolution fails.

    If a file name begins with a '/', the first component in the file
 name is located in the "root directory" of the process (usually all
 processes on the system have the same root directory).  Such a file name
 is called an "absolute file name".

    Otherwise, the first component in the file name is located in the
 current working directory (*note Working Directory::).  This kind of
 file name is called a "relative file name".

    The file name components '.' ("dot") and '..' ("dot-dot") have
 special meanings.  Every directory has entries for these file name
 components.  The file name component '.' refers to the directory itself,
 while the file name component '..' refers to its "parent directory" (the
 directory that contains the link for the directory in question).  As a
 special case, '..' in the root directory refers to the root directory
 itself, since it has no parent; thus '/..' is the same as '/'.

    Here are some examples of file names:

 '/a'
      The file named 'a', in the root directory.

 '/a/b'
      The file named 'b', in the directory named 'a' in the root
      directory.

 'a'
      The file named 'a', in the current working directory.

 '/a/./b'
      This is the same as '/a/b'.

 './a'
      The file named 'a', in the current working directory.

 '../a'
      The file named 'a', in the parent directory of the current working
      directory.

    A file name that names a directory may optionally end in a '/'.  You
 can specify a file name of '/' to refer to the root directory, but the
 empty string is not a meaningful file name.  If you want to refer to the
 current working directory, use a file name of '.' or './'.

    Unlike some other operating systems, GNU systems don't have any
 built-in support for file types (or extensions) or file versions as part
 of its file name syntax.  Many programs and utilities use conventions
 for file names--for example, files containing C source code usually have
 names suffixed with '.c'--but there is nothing in the file system itself
 that enforces this kind of convention.


 File: libc.info,  Node: File Name Errors,  Next: File Name Portability,  Prev: File Name Resolution,  Up: File Names

 11.2.3 File Name Errors
 -----------------------

 Functions that accept file name arguments usually detect these 'errno'
 error conditions relating to the file name syntax or trouble finding the
 named file.  These errors are referred to throughout this manual as the
 "usual file name errors".

 'EACCES'
      The process does not have search permission for a directory
      component of the file name.

 'ENAMETOOLONG'
      This error is used when either the total length of a file name is
      greater than 'PATH_MAX', or when an individual file name component
      has a length greater than 'NAME_MAX'.  *Note Limits for Files::.

      On GNU/Hurd systems, there is no imposed limit on overall file name
      length, but some file systems may place limits on the length of a
      component.

 'ENOENT'
      This error is reported when a file referenced as a directory
      component in the file name doesn't exist, or when a component is a
      symbolic link whose target file does not exist.  *Note Symbolic
      Links::.

 'ENOTDIR'
      A file that is referenced as a directory component in the file name
      exists, but it isn't a directory.

 'ELOOP'
      Too many symbolic links were resolved while trying to look up the
      file name.  The system has an arbitrary limit on the number of
      symbolic links that may be resolved in looking up a single file
      name, as a primitive way to detect loops.  *Note Symbolic Links::.


 File: libc.info,  Node: File Name Portability,  Prev: File Name Errors,  Up: File Names

 11.2.4 Portability of File Names
 --------------------------------

 The rules for the syntax of file names discussed in *note File Names::,
 are the rules normally used by GNU systems and by other POSIX systems.
 However, other operating systems may use other conventions.

    There are two reasons why it can be important for you to be aware of
 file name portability issues:

    * If your program makes assumptions about file name syntax, or
      contains embedded literal file name strings, it is more difficult
      to get it to run under other operating systems that use different
      syntax conventions.

    * Even if you are not concerned about running your program on
      machines that run other operating systems, it may still be possible
      to access files that use different naming conventions.  For
      example, you may be able to access file systems on another computer
      running a different operating system over a network, or read and
      write disks in formats used by other operating systems.

    The ISO C standard says very little about file name syntax, only that
 file names are strings.  In addition to varying restrictions on the
 length of file names and what characters can validly appear in a file
 name, different operating systems use different conventions and syntax
 for concepts such as structured directories and file types or
 extensions.  Some concepts such as file versions might be supported in
 some operating systems and not by others.

    The POSIX.1 standard allows implementations to put additional
 restrictions on file name syntax, concerning what characters are
 permitted in file names and on the length of file name and file name
 component strings.  However, on GNU systems, any character except the
 null character is permitted in a file name string, and on GNU/Hurd
 systems there are no limits on the length of file name strings.


 File: libc.info,  Node: I/O on Streams,  Next: Low-Level I/O,  Prev: I/O Overview,  Up: Top

 12 Input/Output on Streams
 **************************

 This chapter describes the functions for creating streams and performing
 input and output operations on them.  As discussed in *note I/O
 Overview::, a stream is a fairly abstract, high-level concept
 representing a communications channel to a file, device, or process.

 * Menu:

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


 File: libc.info,  Node: Streams,  Next: Standard Streams,  Up: I/O on Streams

 12.1 Streams
 ============

 For historical reasons, the type of the C data structure that represents
 a stream is called 'FILE' rather than "stream".  Since most of the
 library functions deal with objects of type 'FILE *', sometimes the term
 "file pointer" is also used to mean "stream".  This leads to unfortunate
 confusion over terminology in many books on C. This manual, however, is
 careful to use the terms "file" and "stream" only in the technical
 sense.

    The 'FILE' type is declared in the header file 'stdio.h'.

  -- Data Type: FILE
      This is the data type used to represent stream objects.  A 'FILE'
      object holds all of the internal state information about the
      connection to the associated file, including such things as the
      file position indicator and buffering information.  Each stream
      also has error and end-of-file status indicators that can be tested
      with the 'ferror' and 'feof' functions; see *note EOF and Errors::.

    'FILE' objects are allocated and managed internally by the
 input/output library functions.  Don't try to create your own objects of
 type 'FILE'; let the library do it.  Your programs should deal only with
 pointers to these objects (that is, 'FILE *' values) rather than the
 objects themselves.


 File: libc.info,  Node: Standard Streams,  Next: Opening Streams,  Prev: Streams,  Up: I/O on Streams

 12.2 Standard Streams
 =====================

 When the 'main' function of your program is invoked, it already has
 three predefined streams open and available for use.  These represent
 the "standard" input and output channels that have been established for
 the process.

    These streams are declared in the header file 'stdio.h'.

  -- Variable: FILE * stdin
      The "standard input" stream, which is the normal source of input
      for the program.

  -- Variable: FILE * stdout
      The "standard output" stream, which is used for normal output from
      the program.

  -- Variable: FILE * stderr
      The "standard error" stream, which is used for error messages and
      diagnostics issued by the program.

    On GNU systems, you can specify what files or processes correspond to
 these streams using the pipe and redirection facilities provided by the
 shell.  (The primitives shells use to implement these facilities are
 described in *note File System Interface::.)  Most other operating
 systems provide similar mechanisms, but the details of how to use them
 can vary.

    In the GNU C Library, 'stdin', 'stdout', and 'stderr' are normal
 variables which you can set just like any others.  For example, to
 redirect the standard output to a file, you could do:

      fclose (stdout);
      stdout = fopen ("standard-output-file", "w");

    Note however, that in other systems 'stdin', 'stdout', and 'stderr'
 are macros that you cannot assign to in the normal way.  But you can use
 'freopen' to get the effect of closing one and reopening it.  *Note
 Opening Streams::.

    The three streams 'stdin', 'stdout', and 'stderr' are not unoriented
 at program start (*note Streams and I18N::).


 File: libc.info,  Node: Opening Streams,  Next: Closing Streams,  Prev: Standard Streams,  Up: I/O on Streams

 12.3 Opening Streams
 ====================

 Opening a file with the 'fopen' function creates a new stream and
 establishes a connection between the stream and a file.  This may
 involve creating a new file.

    Everything described in this section is declared in the header file
 'stdio.h'.

  -- Function: FILE * fopen (const char *FILENAME, const char *OPENTYPE)
      Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
      lock | *Note POSIX Safety Concepts::.

      The 'fopen' function opens a stream for I/O to the file FILENAME,
      and returns a pointer to the stream.

      The OPENTYPE argument is a string that controls how the file is
      opened and specifies attributes of the resulting stream.  It must
      begin with one of the following sequences of characters:

      'r'
           Open an existing file for reading only.

      'w'
           Open the file for writing only.  If the file already exists,
           it is truncated to zero length.  Otherwise a new file is
           created.

      'a'
           Open a file for append access; that is, writing at the end of
           file only.  If the file already exists, its initial contents
           are unchanged and output to the stream is appended to the end
           of the file.  Otherwise, a new, empty file is created.

      'r+'
           Open an existing file for both reading and writing.  The
           initial contents of the file are unchanged and the initial
           file position is at the beginning of the file.

      'w+'
           Open a file for both reading and writing.  If the file already
           exists, it is truncated to zero length.  Otherwise, a new file
           is created.

      'a+'
           Open or create file for both reading and appending.  If the
           file exists, its initial contents are unchanged.  Otherwise, a
           new file is created.  The initial file position for reading is
           at the beginning of the file, but output is always appended to
           the end of the file.

      As you can see, '+' requests a stream that can do both input and
      output.  When using such a stream, you must call 'fflush' (*note
      Stream Buffering::) or a file positioning function such as 'fseek'
      (*note File Positioning::) when switching from reading to writing
      or vice versa.  Otherwise, internal buffers might not be emptied
      properly.

      Additional characters may appear after these to specify flags for
      the call.  Always put the mode ('r', 'w+', etc.)  first; that is
      the only part you are guaranteed will be understood by all systems.

      The GNU C Library defines additional characters for use in
      OPENTYPE:

      'c'
           The file is opened with cancellation in the I/O functions
           disabled.

      'e'
           The underlying file descriptor will be closed if you use any
           of the 'exec...' functions (*note Executing a File::).  (This
           is equivalent to having set 'FD_CLOEXEC' on that descriptor.
           *Note Descriptor Flags::.)

      'm'
           The file is opened and accessed using 'mmap'.  This is only
           supported with files opened for reading.

      'x'
           Insist on creating a new file--if a file FILENAME already
           exists, 'fopen' fails rather than opening it.  If you use 'x'
           you are guaranteed that you will not clobber an existing file.
           This is equivalent to the 'O_EXCL' option to the 'open'
           function (*note Opening and Closing Files::).

           The 'x' modifier is part of ISO C11.

      The character 'b' in OPENTYPE has a standard meaning; it requests a
      binary stream rather than a text stream.  But this makes no
      difference in POSIX systems (including GNU systems).  If both '+'
      and 'b' are specified, they can appear in either order.  *Note
      Binary Streams::.

      If the OPENTYPE string contains the sequence ',ccs=STRING' then
      STRING is taken as the name of a coded character set and 'fopen'
      will mark the stream as wide-oriented with appropriate conversion
      functions in place to convert from and to the character set STRING.
      Any other stream is opened initially unoriented and the orientation
      is decided with the first file operation.  If the first operation
      is a wide character operation, the stream is not only marked as
      wide-oriented, also the conversion functions to convert to the
      coded character set used for the current locale are loaded.  This
      will not change anymore from this point on even if the locale
      selected for the 'LC_CTYPE' category is changed.

      Any other characters in OPENTYPE are simply ignored.  They may be
      meaningful in other systems.

      If the open fails, 'fopen' returns a null pointer.

      When the sources are compiling with '_FILE_OFFSET_BITS == 64' on a
      32 bit machine this function is in fact 'fopen64' since the LFS
      interface replaces transparently the old interface.

    You can have multiple streams (or file descriptors) pointing to the
 same file open at the same time.  If you do only input, this works
 straightforwardly, but you must be careful if any output streams are
 included.  *Note Stream/Descriptor Precautions::.  This is equally true
 whether the streams are in one program (not usual) or in several
 programs (which can easily happen).  It may be advantageous to use the
 file locking facilities to avoid simultaneous access.  *Note File
 Locks::.

  -- Function: FILE * fopen64 (const char *FILENAME, const char
           *OPENTYPE)
      Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
      lock | *Note POSIX Safety Concepts::.

      This function is similar to 'fopen' but the stream it returns a
      pointer for is opened using 'open64'.  Therefore this stream can be
      used even on files larger than 2^31 bytes on 32 bit machines.

      Please note that the return type is still 'FILE *'.  There is no
      special 'FILE' type for the LFS interface.

      If the sources are compiled with '_FILE_OFFSET_BITS == 64' on a 32
      bits machine this function is available under the name 'fopen' and
      so transparently replaces the old interface.

  -- Macro: int FOPEN_MAX
      The value of this macro is an integer constant expression that
      represents the minimum number of streams that the implementation
      guarantees can be open simultaneously.  You might be able to open
      more than this many streams, but that is not guaranteed.  The value
      of this constant is at least eight, which includes the three
      standard streams 'stdin', 'stdout', and 'stderr'.  In POSIX.1
      systems this value is determined by the 'OPEN_MAX' parameter; *note
      General Limits::.  In BSD and GNU, it is controlled by the
      'RLIMIT_NOFILE' resource limit; *note Limits on Resources::.

  -- Function: FILE * freopen (const char *FILENAME, const char
           *OPENTYPE, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt fd |
      *Note POSIX Safety Concepts::.

      This function is like a combination of 'fclose' and 'fopen'.  It
      first closes the stream referred to by STREAM, ignoring any errors
      that are detected in the process.  (Because errors are ignored, you
      should not use 'freopen' on an output stream if you have actually
      done any output using the stream.)  Then the file named by FILENAME
      is opened with mode OPENTYPE as for 'fopen', and associated with
      the same stream object STREAM.

      If the operation fails, a null pointer is returned; otherwise,
      'freopen' returns STREAM.

      'freopen' has traditionally been used to connect a standard stream
      such as 'stdin' with a file of your own choice.  This is useful in
      programs in which use of a standard stream for certain purposes is
      hard-coded.  In the GNU C Library, you can simply close the
      standard streams and open new ones with 'fopen'.  But other systems
      lack this ability, so using 'freopen' is more portable.

      When the sources are compiling with '_FILE_OFFSET_BITS == 64' on a
      32 bit machine this function is in fact 'freopen64' since the LFS
      interface replaces transparently the old interface.

  -- Function: FILE * freopen64 (const char *FILENAME, const char
           *OPENTYPE, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt fd |
      *Note POSIX Safety Concepts::.

      This function is similar to 'freopen'.  The only difference is that
      on 32 bit machine the stream returned is able to read beyond the
      2^31 bytes limits imposed by the normal interface.  It should be
      noted that the stream pointed to by STREAM need not be opened using
      'fopen64' or 'freopen64' since its mode is not important for this
      function.

      If the sources are compiled with '_FILE_OFFSET_BITS == 64' on a 32
      bits machine this function is available under the name 'freopen'
      and so transparently replaces the old interface.

    In some situations it is useful to know whether a given stream is
 available for reading or writing.  This information is normally not
 available and would have to be remembered separately.  Solaris
 introduced a few functions to get this information from the stream
 descriptor and these functions are also available in the GNU C Library.

  -- Function: int __freadable (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
      Concepts::.

      The '__freadable' function determines whether the stream STREAM was
      opened to allow reading.  In this case the return value is nonzero.
      For write-only streams the function returns zero.

      This function is declared in 'stdio_ext.h'.

  -- Function: int __fwritable (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
      Concepts::.

      The '__fwritable' function determines whether the stream STREAM was
      opened to allow writing.  In this case the return value is nonzero.
      For read-only streams the function returns zero.

      This function is declared in 'stdio_ext.h'.

    For slightly different kind of problems there are two more functions.
 They provide even finer-grained information.

  -- Function: int __freading (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
      Concepts::.

      The '__freading' function determines whether the stream STREAM was
      last read from or whether it is opened read-only.  In this case the
      return value is nonzero, otherwise it is zero.  Determining whether
      a stream opened for reading and writing was last used for writing
      allows to draw conclusions about the content about the buffer,
      among other things.

      This function is declared in 'stdio_ext.h'.

  -- Function: int __fwriting (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
      Concepts::.

      The '__fwriting' function determines whether the stream STREAM was
      last written to or whether it is opened write-only.  In this case
      the return value is nonzero, otherwise it is zero.

      This function is declared in 'stdio_ext.h'.


 File: libc.info,  Node: Closing Streams,  Next: Streams and Threads,  Prev: Opening Streams,  Up: I/O on Streams

 12.4 Closing Streams
 ====================

 When a stream is closed with 'fclose', the connection between the stream
 and the file is canceled.  After you have closed a stream, you cannot
 perform any additional operations on it.

  -- Function: int fclose (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem
      fd | *Note POSIX Safety Concepts::.

      This function causes STREAM to be closed and the connection to the
      corresponding file to be broken.  Any buffered output is written
      and any buffered input is discarded.  The 'fclose' function returns
      a value of '0' if the file was closed successfully, and 'EOF' if an
      error was detected.

      It is important to check for errors when you call 'fclose' to close
      an output stream, because real, everyday errors can be detected at
      this time.  For example, when 'fclose' writes the remaining
      buffered output, it might get an error because the disk is full.
      Even if you know the buffer is empty, errors can still occur when
      closing a file if you are using NFS.

      The function 'fclose' is declared in 'stdio.h'.

    To close all streams currently available the GNU C Library provides
 another function.

  -- Function: int fcloseall (void)
      Preliminary: | MT-Unsafe race:streams | AS-Unsafe | AC-Safe | *Note
      POSIX Safety Concepts::.

      This function causes all open streams of the process to be closed
      and the connection to corresponding files to be broken.  All
      buffered data is written and any buffered input is discarded.  The
      'fcloseall' function returns a value of '0' if all the files were
      closed successfully, and 'EOF' if an error was detected.

      This function should be used only in special situations, e.g., when
      an error occurred and the program must be aborted.  Normally each
      single stream should be closed separately so that problems with
      individual streams can be identified.  It is also problematic since
      the standard streams (*note Standard Streams::) will also be
      closed.

      The function 'fcloseall' is declared in 'stdio.h'.

    If the 'main' function to your program returns, or if you call the
 'exit' function (*note Normal Termination::), all open streams are
 automatically closed properly.  If your program terminates in any other
 manner, such as by calling the 'abort' function (*note Aborting a
 Program::) or from a fatal signal (*note Signal Handling::), open
 streams might not be closed properly.  Buffered output might not be
 flushed and files may be incomplete.  For more information on buffering
 of streams, see *note Stream Buffering::.


 File: libc.info,  Node: Streams and Threads,  Next: Streams and I18N,  Prev: Closing Streams,  Up: I/O on Streams

 12.5 Streams and Threads
 ========================

 Streams can be used in multi-threaded applications in the same way they
 are used in single-threaded applications.  But the programmer must be
 aware of the possible complications.  It is important to know about
 these also if the program one writes never use threads since the design
 and implementation of many stream functions is heavily influenced by the
 requirements added by multi-threaded programming.

    The POSIX standard requires that by default the stream operations are
 atomic.  I.e., issuing two stream operations for the same stream in two
 threads at the same time will cause the operations to be executed as if
 they were issued sequentially.  The buffer operations performed while
 reading or writing are protected from other uses of the same stream.  To
 do this each stream has an internal lock object which has to be
 (implicitly) acquired before any work can be done.

    But there are situations where this is not enough and there are also
 situations where this is not wanted.  The implicit locking is not enough
 if the program requires more than one stream function call to happen
 atomically.  One example would be if an output line a program wants to
 generate is created by several function calls.  The functions by
 themselves would ensure only atomicity of their own operation, but not
 atomicity over all the function calls.  For this it is necessary to
 perform the stream locking in the application code.

  -- Function: void flockfile (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
      Safety Concepts::.

      The 'flockfile' function acquires the internal locking object
      associated with the stream STREAM.  This ensures that no other
      thread can explicitly through 'flockfile'/'ftrylockfile' or
      implicit through a call of a stream function lock the stream.  The
      thread will block until the lock is acquired.  An explicit call to
      'funlockfile' has to be used to release the lock.

  -- Function: int ftrylockfile (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
      Safety Concepts::.

      The 'ftrylockfile' function tries to acquire the internal locking
      object associated with the stream STREAM just like 'flockfile'.
      But unlike 'flockfile' this function does not block if the lock is
      not available.  'ftrylockfile' returns zero if the lock was
      successfully acquired.  Otherwise the stream is locked by another
      thread.

  -- Function: void funlockfile (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
      Safety Concepts::.

      The 'funlockfile' function releases the internal locking object of
      the stream STREAM.  The stream must have been locked before by a
      call to 'flockfile' or a successful call of 'ftrylockfile'.  The
      implicit locking performed by the stream operations do not count.
      The 'funlockfile' function does not return an error status and the
      behavior of a call for a stream which is not locked by the current
      thread is undefined.

    The following example shows how the functions above can be used to
 generate an output line atomically even in multi-threaded applications
 (yes, the same job could be done with one 'fprintf' call but it is
 sometimes not possible):

      FILE *fp;
      {
         ...
         flockfile (fp);
         fputs ("This is test number ", fp);
         fprintf (fp, "%d\n", test);
         funlockfile (fp)
      }

    Without the explicit locking it would be possible for another thread
 to use the stream FP after the 'fputs' call return and before 'fprintf'
 was called with the result that the number does not follow the word
 'number'.

    From this description it might already be clear that the locking
 objects in streams are no simple mutexes.  Since locking the same stream
 twice in the same thread is allowed the locking objects must be
 equivalent to recursive mutexes.  These mutexes keep track of the owner
 and the number of times the lock is acquired.  The same number of
 'funlockfile' calls by the same threads is necessary to unlock the
 stream completely.  For instance:

      void
      foo (FILE *fp)
      {
        ftrylockfile (fp);
        fputs ("in foo\n", fp);
        /* This is very wrong!!!  */
        funlockfile (fp);
      }

    It is important here that the 'funlockfile' function is only called
 if the 'ftrylockfile' function succeeded in locking the stream.  It is
 therefore always wrong to ignore the result of 'ftrylockfile'.  And it
 makes no sense since otherwise one would use 'flockfile'.  The result of
 code like that above is that either 'funlockfile' tries to free a stream
 that hasn't been locked by the current thread or it frees the stream
 prematurely.  The code should look like this:

      void
      foo (FILE *fp)
      {
        if (ftrylockfile (fp) == 0)
          {
            fputs ("in foo\n", fp);
            funlockfile (fp);
          }
      }

    Now that we covered why it is necessary to have these locking it is
 necessary to talk about situations when locking is unwanted and what can
 be done.  The locking operations (explicit or implicit) don't come for
 free.  Even if a lock is not taken the cost is not zero.  The operations
 which have to be performed require memory operations that are safe in
 multi-processor environments.  With the many local caches involved in
 such systems this is quite costly.  So it is best to avoid the locking
 completely if it is not needed - because the code in question is never
 used in a context where two or more threads may use a stream at a time.
 This can be determined most of the time for application code; for
 library code which can be used in many contexts one should default to be
 conservative and use locking.

    There are two basic mechanisms to avoid locking.  The first is to use
 the '_unlocked' variants of the stream operations.  The POSIX standard
 defines quite a few of those and the GNU C Library adds a few more.
 These variants of the functions behave just like the functions with the
 name without the suffix except that they do not lock the stream.  Using
 these functions is very desirable since they are potentially much
 faster.  This is not only because the locking operation itself is
 avoided.  More importantly, functions like 'putc' and 'getc' are very
 simple and traditionally (before the introduction of threads) were
 implemented as macros which are very fast if the buffer is not empty.
 With the addition of locking requirements these functions are no longer
 implemented as macros since they would expand to too much code.  But
 these macros are still available with the same functionality under the
 new names 'putc_unlocked' and 'getc_unlocked'.  This possibly huge
 difference of speed also suggests the use of the '_unlocked' functions
 even if locking is required.  The difference is that the locking then
 has to be performed in the program:

      void
      foo (FILE *fp, char *buf)
      {
        flockfile (fp);
        while (*buf != '/')
          putc_unlocked (*buf++, fp);
        funlockfile (fp);
      }

    If in this example the 'putc' function would be used and the explicit
 locking would be missing the 'putc' function would have to acquire the
 lock in every call, potentially many times depending on when the loop
 terminates.  Writing it the way illustrated above allows the
 'putc_unlocked' macro to be used which means no locking and direct
 manipulation of the buffer of the stream.

    A second way to avoid locking is by using a non-standard function
 which was introduced in Solaris and is available in the GNU C Library as
 well.

  -- Function: int __fsetlocking (FILE *STREAM, int TYPE)
      Preliminary: | MT-Safe race:stream | AS-Unsafe lock | AC-Safe |
      *Note POSIX Safety Concepts::.

      The '__fsetlocking' function can be used to select whether the
      stream operations will implicitly acquire the locking object of the
      stream STREAM.  By default this is done but it can be disabled and
      reinstated using this function.  There are three values defined for
      the TYPE parameter.

      'FSETLOCKING_INTERNAL'
           The stream 'stream' will from now on use the default internal
           locking.  Every stream operation with exception of the
           '_unlocked' variants will implicitly lock the stream.

      'FSETLOCKING_BYCALLER'
           After the '__fsetlocking' function returns the user is
           responsible for locking the stream.  None of the stream
           operations will implicitly do this anymore until the state is
           set back to 'FSETLOCKING_INTERNAL'.

      'FSETLOCKING_QUERY'
           '__fsetlocking' only queries the current locking state of the
           stream.  The return value will be 'FSETLOCKING_INTERNAL' or
           'FSETLOCKING_BYCALLER' depending on the state.

      The return value of '__fsetlocking' is either
      'FSETLOCKING_INTERNAL' or 'FSETLOCKING_BYCALLER' depending on the
      state of the stream before the call.

      This function and the values for the TYPE parameter are declared in
      'stdio_ext.h'.

    This function is especially useful when program code has to be used
 which is written without knowledge about the '_unlocked' functions (or
 if the programmer was too lazy to use them).


 File: libc.info,  Node: Streams and I18N,  Next: Simple Output,  Prev: Streams and Threads,  Up: I/O on Streams

 12.6 Streams in Internationalized Applications
 ==============================================

 ISO C90 introduced the new type 'wchar_t' to allow handling larger
 character sets.  What was missing was a possibility to output strings of
 'wchar_t' directly.  One had to convert them into multibyte strings
 using 'mbstowcs' (there was no 'mbsrtowcs' yet) and then use the normal
 stream functions.  While this is doable it is very cumbersome since
 performing the conversions is not trivial and greatly increases program
 complexity and size.

    The Unix standard early on (I think in XPG4.2) introduced two
 additional format specifiers for the 'printf' and 'scanf' families of
 functions.  Printing and reading of single wide characters was made
 possible using the '%C' specifier and wide character strings can be
 handled with '%S'.  These modifiers behave just like '%c' and '%s' only
 that they expect the corresponding argument to have the wide character
 type and that the wide character and string are transformed into/from
 multibyte strings before being used.

    This was a beginning but it is still not good enough.  Not always is
 it desirable to use 'printf' and 'scanf'.  The other, smaller and faster
 functions cannot handle wide characters.  Second, it is not possible to
 have a format string for 'printf' and 'scanf' consisting of wide
 characters.  The result is that format strings would have to be
 generated if they have to contain non-basic characters.

    In the Amendment 1 to ISO C90 a whole new set of functions was added
 to solve the problem.  Most of the stream functions got a counterpart
 which take a wide character or wide character string instead of a
 character or string respectively.  The new functions operate on the same
 streams (like 'stdout').  This is different from the model of the C++
 runtime library where separate streams for wide and normal I/O are used.

    Being able to use the same stream for wide and normal operations
 comes with a restriction: a stream can be used either for wide
 operations or for normal operations.  Once it is decided there is no way
 back.  Only a call to 'freopen' or 'freopen64' can reset the
 "orientation".  The orientation can be decided in three ways:

    * If any of the normal character functions is used (this includes the
      'fread' and 'fwrite' functions) the stream is marked as not wide
      oriented.

    * If any of the wide character functions is used the stream is marked
      as wide oriented.

    * The 'fwide' function can be used to set the orientation either way.

    It is important to never mix the use of wide and not wide operations
 on a stream.  There are no diagnostics issued.  The application behavior
 will simply be strange or the application will simply crash.  The
 'fwide' function can help avoiding this.

  -- Function: int fwide (FILE *STREAM, int MODE)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock | *Note
      POSIX Safety Concepts::.

      The 'fwide' function can be used to set and query the state of the
      orientation of the stream STREAM.  If the MODE parameter has a
      positive value the streams get wide oriented, for negative values
      narrow oriented.  It is not possible to overwrite previous
      orientations with 'fwide'.  I.e., if the stream STREAM was already
      oriented before the call nothing is done.

      If MODE is zero the current orientation state is queried and
      nothing is changed.

      The 'fwide' function returns a negative value, zero, or a positive
      value if the stream is narrow, not at all, or wide oriented
      respectively.

      This function was introduced in Amendment 1 to ISO C90 and is
      declared in 'wchar.h'.

    It is generally a good idea to orient a stream as early as possible.
 This can prevent surprise especially for the standard streams 'stdin',
 'stdout', and 'stderr'.  If some library function in some situations
 uses one of these streams and this use orients the stream in a different
 way the rest of the application expects it one might end up with hard to
 reproduce errors.  Remember that no errors are signal if the streams are
 used incorrectly.  Leaving a stream unoriented after creation is
 normally only necessary for library functions which create streams which
 can be used in different contexts.

    When writing code which uses streams and which can be used in
 different contexts it is important to query the orientation of the
 stream before using it (unless the rules of the library interface demand
 a specific orientation).  The following little, silly function
 illustrates this.

      void
      print_f (FILE *fp)
      {
        if (fwide (fp, 0) > 0)
          /* Positive return value means wide orientation.  */
          fputwc (L'f', fp);
        else
          fputc ('f', fp);
      }

    Note that in this case the function 'print_f' decides about the
 orientation of the stream if it was unoriented before (will not happen
 if the advise above is followed).

    The encoding used for the 'wchar_t' values is unspecified and the
 user must not make any assumptions about it.  For I/O of 'wchar_t'
 values this means that it is impossible to write these values directly
 to the stream.  This is not what follows from the ISO C locale model
 either.  What happens instead is that the bytes read from or written to
 the underlying media are first converted into the internal encoding
 chosen by the implementation for 'wchar_t'.  The external encoding is
 determined by the 'LC_CTYPE' category of the current locale or by the
 'ccs' part of the mode specification given to 'fopen', 'fopen64',
 'freopen', or 'freopen64'.  How and when the conversion happens is
 unspecified and it happens invisible to the user.

    Since a stream is created in the unoriented state it has at that
 point no conversion associated with it.  The conversion which will be
 used is determined by the 'LC_CTYPE' category selected at the time the
 stream is oriented.  If the locales are changed at the runtime this
 might produce surprising results unless one pays attention.  This is
 just another good reason to orient the stream explicitly as soon as
 possible, perhaps with a call to 'fwide'.


 File: libc.info,  Node: Simple Output,  Next: Character Input,  Prev: Streams and I18N,  Up: I/O on Streams

 12.7 Simple Output by Characters or Lines
 =========================================

 This section describes functions for performing character- and
 line-oriented output.

    These narrow streams functions are declared in the header file
 'stdio.h' and the wide stream functions in 'wchar.h'.

  -- Function: int fputc (int C, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
      | *Note POSIX Safety Concepts::.

      The 'fputc' function converts the character C to type 'unsigned
      char', and writes it to the stream STREAM.  'EOF' is returned if a
      write error occurs; otherwise the character C is returned.

  -- Function: wint_t fputwc (wchar_t WC, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
      | *Note POSIX Safety Concepts::.

      The 'fputwc' function writes the wide character WC to the stream
      STREAM.  'WEOF' is returned if a write error occurs; otherwise the
      character WC is returned.

  -- Function: int fputc_unlocked (int C, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fputc_unlocked' function is equivalent to the 'fputc' function
      except that it does not implicitly lock the stream.

  -- Function: wint_t fputwc_unlocked (wchar_t WC, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fputwc_unlocked' function is equivalent to the 'fputwc'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: int putc (int C, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
      | *Note POSIX Safety Concepts::.

      This is just like 'fputc', except that most systems implement it as
      a macro, making it faster.  One consequence is that it may evaluate
      the STREAM argument more than once, which is an exception to the
      general rule for macros.  'putc' is usually the best function to
      use for writing a single character.

  -- Function: wint_t putwc (wchar_t WC, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
      | *Note POSIX Safety Concepts::.

      This is just like 'fputwc', except that it can be implement as a
      macro, making it faster.  One consequence is that it may evaluate
      the STREAM argument more than once, which is an exception to the
      general rule for macros.  'putwc' is usually the best function to
      use for writing a single wide character.

  -- Function: int putc_unlocked (int C, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'putc_unlocked' function is equivalent to the 'putc' function
      except that it does not implicitly lock the stream.

  -- Function: wint_t putwc_unlocked (wchar_t WC, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'putwc_unlocked' function is equivalent to the 'putwc' function
      except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: int putchar (int C)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
      | *Note POSIX Safety Concepts::.

      The 'putchar' function is equivalent to 'putc' with 'stdout' as the
      value of the STREAM argument.

  -- Function: wint_t putwchar (wchar_t WC)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
      | *Note POSIX Safety Concepts::.

      The 'putwchar' function is equivalent to 'putwc' with 'stdout' as
      the value of the STREAM argument.

  -- Function: int putchar_unlocked (int C)
      Preliminary: | MT-Unsafe race:stdout | AS-Unsafe corrupt |
      AC-Unsafe corrupt | *Note POSIX Safety Concepts::.

      The 'putchar_unlocked' function is equivalent to the 'putchar'
      function except that it does not implicitly lock the stream.

  -- Function: wint_t putwchar_unlocked (wchar_t WC)
      Preliminary: | MT-Unsafe race:stdout | AS-Unsafe corrupt |
      AC-Unsafe corrupt | *Note POSIX Safety Concepts::.

      The 'putwchar_unlocked' function is equivalent to the 'putwchar'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: int fputs (const char *S, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
      | *Note POSIX Safety Concepts::.

      The function 'fputs' writes the string S to the stream STREAM.  The
      terminating null character is not written.  This function does
      _not_ add a newline character, either.  It outputs only the
      characters in the string.

      This function returns 'EOF' if a write error occurs, and otherwise
      a non-negative value.

      For example:

           fputs ("Are ", stdout);
           fputs ("you ", stdout);
           fputs ("hungry?\n", stdout);

      outputs the text 'Are you hungry?' followed by a newline.

  -- Function: int fputws (const wchar_t *WS, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
      | *Note POSIX Safety Concepts::.

      The function 'fputws' writes the wide character string WS to the
      stream STREAM.  The terminating null character is not written.
      This function does _not_ add a newline character, either.  It
      outputs only the characters in the string.

      This function returns 'WEOF' if a write error occurs, and otherwise
      a non-negative value.

  -- Function: int fputs_unlocked (const char *S, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fputs_unlocked' function is equivalent to the 'fputs' function
      except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: int fputws_unlocked (const wchar_t *WS, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fputws_unlocked' function is equivalent to the 'fputws'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: int puts (const char *S)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'puts' function writes the string S to the stream 'stdout'
      followed by a newline.  The terminating null character of the
      string is not written.  (Note that 'fputs' does _not_ write a
      newline as this function does.)

      'puts' is the most convenient function for printing simple
      messages.  For example:

           puts ("This is a message.");

      outputs the text 'This is a message.' followed by a newline.

  -- Function: int putw (int W, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function writes the word W (that is, an 'int') to STREAM.  It
      is provided for compatibility with SVID, but we recommend you use
      'fwrite' instead (*note Block Input/Output::).


 File: libc.info,  Node: Character Input,  Next: Line Input,  Prev: Simple Output,  Up: I/O on Streams

 12.8 Character Input
 ====================

 This section describes functions for performing character-oriented
 input.  These narrow streams functions are declared in the header file
 'stdio.h' and the wide character functions are declared in 'wchar.h'.

    These functions return an 'int' or 'wint_t' value (for narrow and
 wide stream functions respectively) that is either a character of input,
 or the special value 'EOF'/'WEOF' (usually -1).  For the narrow stream
 functions it is important to store the result of these functions in a
 variable of type 'int' instead of 'char', even when you plan to use it
 only as a character.  Storing 'EOF' in a 'char' variable truncates its
 value to the size of a character, so that it is no longer
 distinguishable from the valid character '(char) -1'.  So always use an
 'int' for the result of 'getc' and friends, and check for 'EOF' after
 the call; once you've verified that the result is not 'EOF', you can be
 sure that it will fit in a 'char' variable without loss of information.

  -- Function: int fgetc (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function reads the next character as an 'unsigned char' from
      the stream STREAM and returns its value, converted to an 'int'.  If
      an end-of-file condition or read error occurs, 'EOF' is returned
      instead.

  -- Function: wint_t fgetwc (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function reads the next wide character from the stream STREAM
      and returns its value.  If an end-of-file condition or read error
      occurs, 'WEOF' is returned instead.

  -- Function: int fgetc_unlocked (FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fgetc_unlocked' function is equivalent to the 'fgetc' function
      except that it does not implicitly lock the stream.

  -- Function: wint_t fgetwc_unlocked (FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fgetwc_unlocked' function is equivalent to the 'fgetwc'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: int getc (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This is just like 'fgetc', except that it is permissible (and
      typical) for it to be implemented as a macro that evaluates the
      STREAM argument more than once.  'getc' is often highly optimized,
      so it is usually the best function to use to read a single
      character.

  -- Function: wint_t getwc (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This is just like 'fgetwc', except that it is permissible for it to
      be implemented as a macro that evaluates the STREAM argument more
      than once.  'getwc' can be highly optimized, so it is usually the
      best function to use to read a single wide character.

  -- Function: int getc_unlocked (FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'getc_unlocked' function is equivalent to the 'getc' function
      except that it does not implicitly lock the stream.

  -- Function: wint_t getwc_unlocked (FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'getwc_unlocked' function is equivalent to the 'getwc' function
      except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: int getchar (void)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'getchar' function is equivalent to 'getc' with 'stdin' as the
      value of the STREAM argument.

  -- Function: wint_t getwchar (void)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'getwchar' function is equivalent to 'getwc' with 'stdin' as
      the value of the STREAM argument.

  -- Function: int getchar_unlocked (void)
      Preliminary: | MT-Unsafe race:stdin | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'getchar_unlocked' function is equivalent to the 'getchar'
      function except that it does not implicitly lock the stream.

  -- Function: wint_t getwchar_unlocked (void)
      Preliminary: | MT-Unsafe race:stdin | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'getwchar_unlocked' function is equivalent to the 'getwchar'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.

    Here is an example of a function that does input using 'fgetc'.  It
 would work just as well using 'getc' instead, or using 'getchar ()'
 instead of 'fgetc (stdin)'.  The code would also work the same for the
 wide character stream functions.

      int
      y_or_n_p (const char *question)
      {
        fputs (question, stdout);
        while (1)
          {
            int c, answer;
            /* Write a space to separate answer from question. */
            fputc (' ', stdout);
            /* Read the first character of the line.
 	      This should be the answer character, but might not be. */
            c = tolower (fgetc (stdin));
            answer = c;
            /* Discard rest of input line. */
            while (c != '\n' && c != EOF)
      	c = fgetc (stdin);
            /* Obey the answer if it was valid. */
            if (answer == 'y')
      	return 1;
            if (answer == 'n')
      	return 0;
            /* Answer was invalid: ask for valid answer. */
            fputs ("Please answer y or n:", stdout);
          }
      }

  -- Function: int getw (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function reads a word (that is, an 'int') from STREAM.  It's
      provided for compatibility with SVID. We recommend you use 'fread'
      instead (*note Block Input/Output::).  Unlike 'getc', any 'int'
      value could be a valid result.  'getw' returns 'EOF' when it
      encounters end-of-file or an error, but there is no way to
      distinguish this from an input word with value -1.


 File: libc.info,  Node: Line Input,  Next: Unreading,  Prev: Character Input,  Up: I/O on Streams

 12.9 Line-Oriented Input
 ========================

 Since many programs interpret input on the basis of lines, it is
 convenient to have functions to read a line of text from a stream.

    Standard C has functions to do this, but they aren't very safe: null
 characters and even (for 'gets') long lines can confuse them.  So the
 GNU C Library provides the nonstandard 'getline' function that makes it
 easy to read lines reliably.

    Another GNU extension, 'getdelim', generalizes 'getline'.  It reads a
 delimited record, defined as everything through the next occurrence of a
 specified delimiter character.

    All these functions are declared in 'stdio.h'.

  -- Function: ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock
      corrupt mem | *Note POSIX Safety Concepts::.

      This function reads an entire line from STREAM, storing the text
      (including the newline and a terminating null character) in a
      buffer and storing the buffer address in '*LINEPTR'.

      Before calling 'getline', you should place in '*LINEPTR' the
      address of a buffer '*N' bytes long, allocated with 'malloc'.  If
      this buffer is long enough to hold the line, 'getline' stores the
      line in this buffer.  Otherwise, 'getline' makes the buffer bigger
      using 'realloc', storing the new buffer address back in '*LINEPTR'
      and the increased size back in '*N'.  *Note Unconstrained
      Allocation::.

      If you set '*LINEPTR' to a null pointer, and '*N' to zero, before
      the call, then 'getline' allocates the initial buffer for you by
      calling 'malloc'.

      In either case, when 'getline' returns, '*LINEPTR' is a 'char *'
      which points to the text of the line.

      When 'getline' is successful, it returns the number of characters
      read (including the newline, but not including the terminating
      null).  This value enables you to distinguish null characters that
      are part of the line from the null character inserted as a
      terminator.

      This function is a GNU extension, but it is the recommended way to
      read lines from a stream.  The alternative standard functions are
      unreliable.

      If an error occurs or end of file is reached without any bytes
      read, 'getline' returns '-1'.

  -- Function: ssize_t getdelim (char **LINEPTR, size_t *N, int
           DELIMITER, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock
      corrupt mem | *Note POSIX Safety Concepts::.

      This function is like 'getline' except that the character which
      tells it to stop reading is not necessarily newline.  The argument
      DELIMITER specifies the delimiter character; 'getdelim' keeps
      reading until it sees that character (or end of file).

      The text is stored in LINEPTR, including the delimiter character
      and a terminating null.  Like 'getline', 'getdelim' makes LINEPTR
      bigger if it isn't big enough.

      'getline' is in fact implemented in terms of 'getdelim', just like
      this:

           ssize_t
           getline (char **lineptr, size_t *n, FILE *stream)
           {
             return getdelim (lineptr, n, '\n', stream);
           }

  -- Function: char * fgets (char *S, int COUNT, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'fgets' function reads characters from the stream STREAM up to
      and including a newline character and stores them in the string S,
      adding a null character to mark the end of the string.  You must
      supply COUNT characters worth of space in S, but the number of
      characters read is at most COUNT - 1.  The extra character space is
      used to hold the null character at the end of the string.

      If the system is already at end of file when you call 'fgets', then
      the contents of the array S are unchanged and a null pointer is
      returned.  A null pointer is also returned if a read error occurs.
      Otherwise, the return value is the pointer S.

      *Warning:* If the input data has a null character, you can't tell.
      So don't use 'fgets' unless you know the data cannot contain a
      null.  Don't use it to read files edited by the user because, if
      the user inserts a null character, you should either handle it
      properly or print a clear error message.  We recommend using
      'getline' instead of 'fgets'.

  -- Function: wchar_t * fgetws (wchar_t *WS, int COUNT, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'fgetws' function reads wide characters from the stream STREAM
      up to and including a newline character and stores them in the
      string WS, adding a null wide character to mark the end of the
      string.  You must supply COUNT wide characters worth of space in
      WS, but the number of characters read is at most COUNT - 1.  The
      extra character space is used to hold the null wide character at
      the end of the string.

      If the system is already at end of file when you call 'fgetws',
      then the contents of the array WS are unchanged and a null pointer
      is returned.  A null pointer is also returned if a read error
      occurs.  Otherwise, the return value is the pointer WS.

      *Warning:* If the input data has a null wide character (which are
      null bytes in the input stream), you can't tell.  So don't use
      'fgetws' unless you know the data cannot contain a null.  Don't use
      it to read files edited by the user because, if the user inserts a
      null character, you should either handle it properly or print a
      clear error message.

  -- Function: char * fgets_unlocked (char *S, int COUNT, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fgets_unlocked' function is equivalent to the 'fgets' function
      except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: wchar_t * fgetws_unlocked (wchar_t *WS, int COUNT, FILE
           *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fgetws_unlocked' function is equivalent to the 'fgetws'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Deprecated function: char * gets (char *S)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The function 'gets' reads characters from the stream 'stdin' up to
      the next newline character, and stores them in the string S.  The
      newline character is discarded (note that this differs from the
      behavior of 'fgets', which copies the newline character into the
      string).  If 'gets' encounters a read error or end-of-file, it
      returns a null pointer; otherwise it returns S.

      *Warning:* The 'gets' function is *very dangerous* because it
      provides no protection against overflowing the string S.  The GNU C
      Library includes it for compatibility only.  You should *always*
      use 'fgets' or 'getline' instead.  To remind you of this, the
      linker (if using GNU 'ld') will issue a warning whenever you use
      'gets'.


 File: libc.info,  Node: Unreading,  Next: Block Input/Output,  Prev: Line Input,  Up: I/O on Streams

 12.10 Unreading
 ===============

 In parser programs it is often useful to examine the next character in
 the input stream without removing it from the stream.  This is called
 "peeking ahead" at the input because your program gets a glimpse of the
 input it will read next.

    Using stream I/O, you can peek ahead at input by first reading it and
 then "unreading" it (also called "pushing it back" on the stream).
 Unreading a character makes it available to be input again from the
 stream, by the next call to 'fgetc' or other input function on that
 stream.

 * Menu:

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


 File: libc.info,  Node: Unreading Idea,  Next: How Unread,  Up: Unreading

 12.10.1 What Unreading Means
 ----------------------------

 Here is a pictorial explanation of unreading.  Suppose you have a stream
 reading a file that contains just six characters, the letters 'foobar'.
 Suppose you have read three characters so far.  The situation looks like
 this:

      f  o  o  b  a  r
      	 ^

 so the next input character will be 'b'.

    If instead of reading 'b' you unread the letter 'o', you get a
 situation like this:

      f  o  o  b  a  r
      	 |
            o--
            ^

 so that the next input characters will be 'o' and 'b'.

    If you unread '9' instead of 'o', you get this situation:

      f  o  o  b  a  r
      	 |
            9--
            ^

 so that the next input characters will be '9' and 'b'.


 File: libc.info,  Node: How Unread,  Prev: Unreading Idea,  Up: Unreading

 12.10.2 Using 'ungetc' To Do Unreading
 --------------------------------------

 The function to unread a character is called 'ungetc', because it
 reverses the action of 'getc'.

  -- Function: int ungetc (int C, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'ungetc' function pushes back the character C onto the input
      stream STREAM.  So the next input from STREAM will read C before
      anything else.

      If C is 'EOF', 'ungetc' does nothing and just returns 'EOF'.  This
      lets you call 'ungetc' with the return value of 'getc' without
      needing to check for an error from 'getc'.

      The character that you push back doesn't have to be the same as the
      last character that was actually read from the stream.  In fact, it
      isn't necessary to actually read any characters from the stream
      before unreading them with 'ungetc'!  But that is a strange way to
      write a program; usually 'ungetc' is used only to unread a
      character that was just read from the same stream.  The GNU C
      Library supports this even on files opened in binary mode, but
      other systems might not.

      The GNU C Library only supports one character of pushback--in other
      words, it does not work to call 'ungetc' twice without doing input
      in between.  Other systems might let you push back multiple
      characters; then reading from the stream retrieves the characters
      in the reverse order that they were pushed.

      Pushing back characters doesn't alter the file; only the internal
      buffering for the stream is affected.  If a file positioning
      function (such as 'fseek', 'fseeko' or 'rewind'; *note File
      Positioning::) is called, any pending pushed-back characters are
      discarded.

      Unreading a character on a stream that is at end of file clears the
      end-of-file indicator for the stream, because it makes the
      character of input available.  After you read that character,
      trying to read again will encounter end of file.

  -- Function: wint_t ungetwc (wint_t WC, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'ungetwc' function behaves just like 'ungetc' just that it
      pushes back a wide character.

    Here is an example showing the use of 'getc' and 'ungetc' to skip
 over whitespace characters.  When this function reaches a non-whitespace
 character, it unreads that character to be seen again on the next read
 operation on the stream.

      #include <stdio.h>
      #include <ctype.h>

      void
      skip_whitespace (FILE *stream)
      {
        int c;
        do
          /* No need to check for 'EOF' because it is not
             'isspace', and 'ungetc' ignores 'EOF'.  */
          c = getc (stream);
        while (isspace (c));
        ungetc (c, stream);
      }


 File: libc.info,  Node: Block Input/Output,  Next: Formatted Output,  Prev: Unreading,  Up: I/O on Streams

 12.11 Block Input/Output
 ========================

 This section describes how to do input and output operations on blocks
 of data.  You can use these functions to read and write binary data, as
 well as to read and write text in fixed-size blocks instead of by
 characters or lines.

    Binary files are typically used to read and write blocks of data in
 the same format as is used to represent the data in a running program.
 In other words, arbitrary blocks of memory--not just character or string
 objects--can be written to a binary file, and meaningfully read in again
 by the same program.

    Storing data in binary form is often considerably more efficient than
 using the formatted I/O functions.  Also, for floating-point numbers,
 the binary form avoids possible loss of precision in the conversion
 process.  On the other hand, binary files can't be examined or modified
 easily using many standard file utilities (such as text editors), and
 are not portable between different implementations of the language, or
 different kinds of computers.

    These functions are declared in 'stdio.h'.

  -- Function: size_t fread (void *DATA, size_t SIZE, size_t COUNT, FILE
           *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function reads up to COUNT objects of size SIZE into the array
      DATA, from the stream STREAM.  It returns the number of objects
      actually read, which might be less than COUNT if a read error
      occurs or the end of the file is reached.  This function returns a
      value of zero (and doesn't read anything) if either SIZE or COUNT
      is zero.

      If 'fread' encounters end of file in the middle of an object, it
      returns the number of complete objects read, and discards the
      partial object.  Therefore, the stream remains at the actual end of
      the file.

  -- Function: size_t fread_unlocked (void *DATA, size_t SIZE, size_t
           COUNT, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fread_unlocked' function is equivalent to the 'fread' function
      except that it does not implicitly lock the stream.

      This function is a GNU extension.

  -- Function: size_t fwrite (const void *DATA, size_t SIZE, size_t
           COUNT, FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function writes up to COUNT objects of size SIZE from the
      array DATA, to the stream STREAM.  The return value is normally
      COUNT, if the call succeeds.  Any other value indicates some sort
      of error, such as running out of space.

  -- Function: size_t fwrite_unlocked (const void *DATA, size_t SIZE,
           size_t COUNT, FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
      corrupt | *Note POSIX Safety Concepts::.

      The 'fwrite_unlocked' function is equivalent to the 'fwrite'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.


 File: libc.info,  Node: Formatted Output,  Next: Customizing Printf,  Prev: Block Input/Output,  Up: I/O on Streams

 12.12 Formatted Output
 ======================

 The functions described in this section ('printf' and related functions)
 provide a convenient way to perform formatted output.  You call 'printf'
 with a "format string" or "template string" that specifies how to format
 the values of the remaining arguments.

    Unless your program is a filter that specifically performs line- or
 character-oriented processing, using 'printf' or one of the other
 related functions described in this section is usually the easiest and
 most concise way to perform output.  These functions are especially
 useful for printing error messages, tables of data, and the like.

 * Menu:

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


 File: libc.info,  Node: Formatted Output Basics,  Next: Output Conversion Syntax,  Up: Formatted Output

 12.12.1 Formatted Output Basics
 -------------------------------

 The 'printf' function can be used to print any number of arguments.  The
 template string argument you supply in a call provides information not
 only about the number of additional arguments, but also about their
 types and what style should be used for printing them.

    Ordinary characters in the template string are simply written to the
 output stream as-is, while "conversion specifications" introduced by a
 '%' character in the template cause subsequent arguments to be formatted
 and written to the output stream.  For example,

      int pct = 37;
      char filename[] = "foo.txt";
      printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
      	filename, pct);

 produces output like

      Processing of `foo.txt' is 37% finished.
      Please be patient.

    This example shows the use of the '%d' conversion to specify that an
 'int' argument should be printed in decimal notation, the '%s'
 conversion to specify printing of a string argument, and the '%%'
 conversion to print a literal '%' character.

    There are also conversions for printing an integer argument as an
 unsigned value in octal, decimal, or hexadecimal radix ('%o', '%u', or
 '%x', respectively); or as a character value ('%c').

    Floating-point numbers can be printed in normal, fixed-point notation
 using the '%f' conversion or in exponential notation using the '%e'
 conversion.  The '%g' conversion uses either '%e' or '%f' format,
 depending on what is more appropriate for the magnitude of the
 particular number.

    You can control formatting more precisely by writing "modifiers"
 between the '%' and the character that indicates which conversion to
 apply.  These slightly alter the ordinary behavior of the conversion.
 For example, most conversion specifications permit you to specify a
 minimum field width and a flag indicating whether you want the result
 left- or right-justified within the field.

    The specific flags and modifiers that are permitted and their
 interpretation vary depending on the particular conversion.  They're all
 described in more detail in the following sections.  Don't worry if this
 all seems excessively complicated at first; you can almost always get
 reasonable free-format output without using any of the modifiers at all.
 The modifiers are mostly used to make the output look "prettier" in
 tables.


 File: libc.info,  Node: Output Conversion Syntax,  Next: Table of Output Conversions,  Prev: Formatted Output Basics,  Up: Formatted Output

 12.12.2 Output Conversion Syntax
 --------------------------------

 This section provides details about the precise syntax of conversion
 specifications that can appear in a 'printf' template string.

    Characters in the template string that are not part of a conversion
 specification are printed as-is to the output stream.  Multibyte
 character sequences (*note Character Set Handling::) are permitted in a
 template string.

    The conversion specifications in a 'printf' template string have the
 general form:

      % [ PARAM-NO $] FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION

 or

      % [ PARAM-NO $] FLAGS WIDTH . * [ PARAM-NO $] TYPE CONVERSION

    For example, in the conversion specifier '%-10.8ld', the '-' is a
 flag, '10' specifies the field width, the precision is '8', the letter
 'l' is a type modifier, and 'd' specifies the conversion style.  (This
 particular type specifier says to print a 'long int' argument in decimal
 notation, with a minimum of 8 digits left-justified in a field at least
 10 characters wide.)

    In more detail, output conversion specifications consist of an
 initial '%' character followed in sequence by:

    * An optional specification of the parameter used for this format.
      Normally the parameters to the 'printf' function are assigned to
      the formats in the order of appearance in the format string.  But
      in some situations (such as message translation) this is not
      desirable and this extension allows an explicit parameter to be
      specified.

      The PARAM-NO parts of the format must be integers in the range of 1
      to the maximum number of arguments present to the function call.
      Some implementations limit this number to a certainly upper bound.
      The exact limit can be retrieved by the following constant.

       -- Macro: NL_ARGMAX
           The value of 'NL_ARGMAX' is the maximum value allowed for the
           specification of a positional parameter in a 'printf' call.
           The actual value in effect at runtime can be retrieved by
           using 'sysconf' using the '_SC_NL_ARGMAX' parameter *note
           Sysconf Definition::.

           Some system have a quite low limit such as 9 for System V
           systems.  The GNU C Library has no real limit.

      If any of the formats has a specification for the parameter
      position all of them in the format string shall have one.
      Otherwise the behavior is undefined.

    * Zero or more "flag characters" that modify the normal behavior of
      the conversion specification.

    * An optional decimal integer specifying the "minimum field width".
      If the normal conversion produces fewer characters than this, the
      field is padded with spaces to the specified width.  This is a
      _minimum_ value; if the normal conversion produces more characters
      than this, the field is _not_ truncated.  Normally, the output is
      right-justified within the field.

      You can also specify a field width of '*'.  This means that the
      next argument in the argument list (before the actual value to be
      printed) is used as the field width.  The value must be an 'int'.
      If the value is negative, this means to set the '-' flag (see
      below) and to use the absolute value as the field width.

    * An optional "precision" to specify the number of digits to be
      written for the numeric conversions.  If the precision is
      specified, it consists of a period ('.') followed optionally by a
      decimal integer (which defaults to zero if omitted).

      You can also specify a precision of '*'.  This means that the next
      argument in the argument list (before the actual value to be
      printed) is used as the precision.  The value must be an 'int', and
      is ignored if it is negative.  If you specify '*' for both the
      field width and precision, the field width argument precedes the
      precision argument.  Other C library versions may not recognize
      this syntax.

    * An optional "type modifier character", which is used to specify the
      data type of the corresponding argument if it differs from the
      default type.  (For example, the integer conversions assume a type
      of 'int', but you can specify 'h', 'l', or 'L' for other integer
      types.)

    * A character that specifies the conversion to be applied.

    The exact options that are permitted and how they are interpreted
 vary between the different conversion specifiers.  See the descriptions
 of the individual conversions for information about the particular
 options that they use.

    With the '-Wformat' option, the GNU C compiler checks calls to
 'printf' and related functions.  It examines the format string and
 verifies that the correct number and types of arguments are supplied.
 There is also a GNU C syntax to tell the compiler that a function you
 write uses a 'printf'-style format string.  *Note Declaring Attributes
 of Functions: (gcc.info)Function Attributes, for more information.


 File: libc.info,  Node: Table of Output Conversions,  Next: Integer Conversions,  Prev: Output Conversion Syntax,  Up: Formatted Output

 12.12.3 Table of Output Conversions
 -----------------------------------

 Here is a table summarizing what all the different conversions do:

 '%d', '%i'
      Print an integer as a signed decimal number.  *Note Integer
      Conversions::, for details.  '%d' and '%i' are synonymous for
      output, but are different when used with 'scanf' for input (*note
      Table of Input Conversions::).

 '%o'
      Print an integer as an unsigned octal number.  *Note Integer
      Conversions::, for details.

 '%u'
      Print an integer as an unsigned decimal number.  *Note Integer
      Conversions::, for details.

 '%x', '%X'
      Print an integer as an unsigned hexadecimal number.  '%x' uses
      lower-case letters and '%X' uses upper-case.  *Note Integer
      Conversions::, for details.

 '%f'
      Print a floating-point number in normal (fixed-point) notation.
      *Note Floating-Point Conversions::, for details.

 '%e', '%E'
      Print a floating-point number in exponential notation.  '%e' uses
      lower-case letters and '%E' uses upper-case.  *Note Floating-Point
      Conversions::, for details.

 '%g', '%G'
      Print a floating-point number in either normal or exponential
      notation, whichever is more appropriate for its magnitude.  '%g'
      uses lower-case letters and '%G' uses upper-case.  *Note
      Floating-Point Conversions::, for details.

 '%a', '%A'
      Print a floating-point number in a hexadecimal fractional notation
      which the exponent to base 2 represented in decimal digits.  '%a'
      uses lower-case letters and '%A' uses upper-case.  *Note
      Floating-Point Conversions::, for details.

 '%c'
      Print a single character.  *Note Other Output Conversions::.

 '%C'
      This is an alias for '%lc' which is supported for compatibility
      with the Unix standard.

 '%s'
      Print a string.  *Note Other Output Conversions::.

 '%S'
      This is an alias for '%ls' which is supported for compatibility
      with the Unix standard.

 '%p'
      Print the value of a pointer.  *Note Other Output Conversions::.

 '%n'
      Get the number of characters printed so far.  *Note Other Output
      Conversions::.  Note that this conversion specification never
      produces any output.

 '%m'
      Print the string corresponding to the value of 'errno'.  (This is a
      GNU extension.)  *Note Other Output Conversions::.

 '%%'
      Print a literal '%' character.  *Note Other Output Conversions::.

    If the syntax of a conversion specification is invalid, unpredictable
 things will happen, so don't do this.  If there aren't enough function
 arguments provided to supply values for all the conversion
 specifications in the template string, or if the arguments are not of
 the correct types, the results are unpredictable.  If you supply more
 arguments than conversion specifications, the extra argument values are
 simply ignored; this is sometimes useful.


 File: libc.info,  Node: Integer Conversions,  Next: Floating-Point Conversions,  Prev: Table of Output Conversions,  Up: Formatted Output

 12.12.4 Integer Conversions
 ---------------------------

 This section describes the options for the '%d', '%i', '%o', '%u', '%x',
 and '%X' conversion specifications.  These conversions print integers in
 various formats.

    The '%d' and '%i' conversion specifications both print an 'int'
 argument as a signed decimal number; while '%o', '%u', and '%x' print
 the argument as an unsigned octal, decimal, or hexadecimal number
 (respectively).  The '%X' conversion specification is just like '%x'
 except that it uses the characters 'ABCDEF' as digits instead of
 'abcdef'.

    The following flags are meaningful:

 '-'
      Left-justify the result in the field (instead of the normal
      right-justification).

 '+'
      For the signed '%d' and '%i' conversions, print a plus sign if the
      value is positive.

 ' '
      For the signed '%d' and '%i' conversions, if the result doesn't
      start with a plus or minus sign, prefix it with a space character
      instead.  Since the '+' flag ensures that the result includes a
      sign, this flag is ignored if you supply both of them.

 '#'
      For the '%o' conversion, this forces the leading digit to be '0',
      as if by increasing the precision.  For '%x' or '%X', this prefixes
      a leading '0x' or '0X' (respectively) to the result.  This doesn't
      do anything useful for the '%d', '%i', or '%u' conversions.  Using
      this flag produces output which can be parsed by the 'strtoul'
      function (*note Parsing of Integers::) and 'scanf' with the '%i'
      conversion (*note Numeric Input Conversions::).

 '''
      Separate the digits into groups as specified by the locale
      specified for the 'LC_NUMERIC' category; *note General Numeric::.
      This flag is a GNU extension.

 '0'
      Pad the field with zeros instead of spaces.  The zeros are placed
      after any indication of sign or base.  This flag is ignored if the
      '-' flag is also specified, or if a precision is specified.

    If a precision is supplied, it specifies the minimum number of digits
 to appear; leading zeros are produced if necessary.  If you don't
 specify a precision, the number is printed with as many digits as it
 needs.  If you convert a value of zero with an explicit precision of
 zero, then no characters at all are produced.

    Without a type modifier, the corresponding argument is treated as an
 'int' (for the signed conversions '%i' and '%d') or 'unsigned int' (for
 the unsigned conversions '%o', '%u', '%x', and '%X').  Recall that since
 'printf' and friends are variadic, any 'char' and 'short' arguments are
 automatically converted to 'int' by the default argument promotions.
 For arguments of other integer types, you can use these modifiers:

 'hh'
      Specifies that the argument is a 'signed char' or 'unsigned char',
      as appropriate.  A 'char' argument is converted to an 'int' or
      'unsigned int' by the default argument promotions anyway, but the
      'h' modifier says to convert it back to a 'char' again.

      This modifier was introduced in ISO C99.

 'h'
      Specifies that the argument is a 'short int' or 'unsigned short
      int', as appropriate.  A 'short' argument is converted to an 'int'
      or 'unsigned int' by the default argument promotions anyway, but
      the 'h' modifier says to convert it back to a 'short' again.

 'j'
      Specifies that the argument is a 'intmax_t' or 'uintmax_t', as
      appropriate.

      This modifier was introduced in ISO C99.

 'l'
      Specifies that the argument is a 'long int' or 'unsigned long int',
      as appropriate.  Two 'l' characters is like the 'L' modifier,
      below.

      If used with '%c' or '%s' the corresponding parameter is considered
      as a wide character or wide character string respectively.  This
      use of 'l' was introduced in Amendment 1 to ISO C90.

 'L'
 'll'
 'q'
      Specifies that the argument is a 'long long int'.  (This type is an
      extension supported by the GNU C compiler.  On systems that don't
      support extra-long integers, this is the same as 'long int'.)

      The 'q' modifier is another name for the same thing, which comes
      from 4.4 BSD; a 'long long int' is sometimes called a "quad" 'int'.

 't'
      Specifies that the argument is a 'ptrdiff_t'.

      This modifier was introduced in ISO C99.

 'z'
 'Z'
      Specifies that the argument is a 'size_t'.

      'z' was introduced in ISO C99.  'Z' is a GNU extension predating
      this addition and should not be used in new code.

    Here is an example.  Using the template string:

      "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"

 to print numbers using the different options for the '%d' conversion
 gives results like:

      |    0|0    |   +0|+0   |    0|00000|     |   00|0|
      |    1|1    |   +1|+1   |    1|00001|    1|   01|1|
      |   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
      |100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|

    In particular, notice what happens in the last case where the number
 is too large to fit in the minimum field width specified.

    Here are some more examples showing how unsigned integers print under
 various format options, using the template string:

      "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"

      |    0|    0|    0|    0|    0|    0|    0|  00000000|
      |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
      |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|


 File: libc.info,  Node: Floating-Point Conversions,  Next: Other Output Conversions,  Prev: Integer Conversions,  Up: Formatted Output

 12.12.5 Floating-Point Conversions
 ----------------------------------

 This section discusses the conversion specifications for floating-point
 numbers: the '%f', '%e', '%E', '%g', and '%G' conversions.

    The '%f' conversion prints its argument in fixed-point notation,
 producing output of the form ['-']DDD'.'DDD, where the number of digits
 following the decimal point is controlled by the precision you specify.

    The '%e' conversion prints its argument in exponential notation,
 producing output of the form ['-']D'.'DDD'e'['+'|'-']DD.  Again, the
 number of digits following the decimal point is controlled by the
 precision.  The exponent always contains at least two digits.  The '%E'
 conversion is similar but the exponent is marked with the letter 'E'
 instead of 'e'.

    The '%g' and '%G' conversions print the argument in the style of '%e'
 or '%E' (respectively) if the exponent would be less than -4 or greater
 than or equal to the precision; otherwise they use the '%f' style.  A
 precision of '0', is taken as 1.  Trailing zeros are removed from the
 fractional portion of the result and a decimal-point character appears
 only if it is followed by a digit.

    The '%a' and '%A' conversions are meant for representing
 floating-point numbers exactly in textual form so that they can be
 exchanged as texts between different programs and/or machines.  The
 numbers are represented is the form ['-']'0x'H'.'HHH'p'['+'|'-']DD.  At
 the left of the decimal-point character exactly one digit is print.
 This character is only '0' if the number is denormalized.  Otherwise the
 value is unspecified; it is implementation dependent how many bits are
 used.  The number of hexadecimal digits on the right side of the
 decimal-point character is equal to the precision.  If the precision is
 zero it is determined to be large enough to provide an exact
 representation of the number (or it is large enough to distinguish two
 adjacent values if the 'FLT_RADIX' is not a power of 2, *note Floating
 Point Parameters::).  For the '%a' conversion lower-case characters are
 used to represent the hexadecimal number and the prefix and exponent
 sign are printed as '0x' and 'p' respectively.  Otherwise upper-case
 characters are used and '0X' and 'P' are used for the representation of
 prefix and exponent string.  The exponent to the base of two is printed
 as a decimal number using at least one digit but at most as many digits
 as necessary to represent the value exactly.

    If the value to be printed represents infinity or a NaN, the output
 is ['-']'inf' or 'nan' respectively if the conversion specifier is '%a',
 '%e', '%f', or '%g' and it is ['-']'INF' or 'NAN' respectively if the
 conversion is '%A', '%E', or '%G'.

    The following flags can be used to modify the behavior:

 '-'
      Left-justify the result in the field.  Normally the result is
      right-justified.

 '+'
      Always include a plus or minus sign in the result.

 ' '
      If the result doesn't start with a plus or minus sign, prefix it
      with a space instead.  Since the '+' flag ensures that the result
      includes a sign, this flag is ignored if you supply both of them.

 '#'
      Specifies that the result should always include a decimal point,
      even if no digits follow it.  For the '%g' and '%G' conversions,
      this also forces trailing zeros after the decimal point to be left
      in place where they would otherwise be removed.

 '''
      Separate the digits of the integer part of the result into groups
      as specified by the locale specified for the 'LC_NUMERIC' category;
      *note General Numeric::.  This flag is a GNU extension.

 '0'
      Pad the field with zeros instead of spaces; the zeros are placed
      after any sign.  This flag is ignored if the '-' flag is also
      specified.

    The precision specifies how many digits follow the decimal-point
 character for the '%f', '%e', and '%E' conversions.  For these
 conversions, the default precision is '6'.  If the precision is
 explicitly '0', this suppresses the decimal point character entirely.
 For the '%g' and '%G' conversions, the precision specifies how many
 significant digits to print.  Significant digits are the first digit
 before the decimal point, and all the digits after it.  If the precision
 is '0' or not specified for '%g' or '%G', it is treated like a value of
 '1'.  If the value being printed cannot be expressed accurately in the
 specified number of digits, the value is rounded to the nearest number
 that fits.

    Without a type modifier, the floating-point conversions use an
 argument of type 'double'.  (By the default argument promotions, any
 'float' arguments are automatically converted to 'double'.)  The
 following type modifier is supported:

 'L'
      An uppercase 'L' specifies that the argument is a 'long double'.

    Here are some examples showing how numbers print using the various
 floating-point conversions.  All of the numbers were printed using this
 template string:

      "|%13.4a|%13.4f|%13.4e|%13.4g|\n"

    Here is the output:

      |  0x0.0000p+0|       0.0000|   0.0000e+00|            0|
      |  0x1.0000p-1|       0.5000|   5.0000e-01|          0.5|
      |  0x1.0000p+0|       1.0000|   1.0000e+00|            1|
      | -0x1.0000p+0|      -1.0000|  -1.0000e+00|           -1|
      |  0x1.9000p+6|     100.0000|   1.0000e+02|          100|
      |  0x1.f400p+9|    1000.0000|   1.0000e+03|         1000|
      | 0x1.3880p+13|   10000.0000|   1.0000e+04|        1e+04|
      | 0x1.81c8p+13|   12345.0000|   1.2345e+04|    1.234e+04|
      | 0x1.86a0p+16|  100000.0000|   1.0000e+05|        1e+05|
      | 0x1.e240p+16|  123456.0000|   1.2346e+05|    1.235e+05|

    Notice how the '%g' conversion drops trailing zeros.


 File: libc.info,  Node: Other Output Conversions,  Next: Formatted Output Functions,  Prev: Floating-Point Conversions,  Up: Formatted Output

 12.12.6 Other Output Conversions
 --------------------------------

 This section describes miscellaneous conversions for 'printf'.

    The '%c' conversion prints a single character.  In case there is no
 'l' modifier the 'int' argument is first converted to an 'unsigned
 char'.  Then, if used in a wide stream function, the character is
 converted into the corresponding wide character.  The '-' flag can be
 used to specify left-justification in the field, but no other flags are
 defined, and no precision or type modifier can be given.  For example:

      printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');

 prints 'hello'.

    If there is a 'l' modifier present the argument is expected to be of
 type 'wint_t'.  If used in a multibyte function the wide character is
 converted into a multibyte character before being added to the output.
 In this case more than one output byte can be produced.

    The '%s' conversion prints a string.  If no 'l' modifier is present
 the corresponding argument must be of type 'char *' (or 'const char *').
 If used in a wide stream function the string is first converted in a
 wide character string.  A precision can be specified to indicate the
 maximum number of characters to write; otherwise characters in the
 string up to but not including the terminating null character are
 written to the output stream.  The '-' flag can be used to specify
 left-justification in the field, but no other flags or type modifiers
 are defined for this conversion.  For example:

      printf ("%3s%-6s", "no", "where");

 prints ' nowhere '.

    If there is a 'l' modifier present the argument is expected to be of
 type 'wchar_t' (or 'const wchar_t *').

    If you accidentally pass a null pointer as the argument for a '%s'
 conversion, the GNU C Library prints it as '(null)'.  We think this is
 more useful than crashing.  But it's not good practice to pass a null
 argument intentionally.

    The '%m' conversion prints the string corresponding to the error code
 in 'errno'.  *Note Error Messages::.  Thus:

      fprintf (stderr, "can't open `%s': %m\n", filename);

 is equivalent to:

      fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));

 The '%m' conversion is a GNU C Library extension.

    The '%p' conversion prints a pointer value.  The corresponding
 argument must be of type 'void *'.  In practice, you can use any type of
 pointer.

    In the GNU C Library, non-null pointers are printed as unsigned
 integers, as if a '%#x' conversion were used.  Null pointers print as
 '(nil)'.  (Pointers might print differently in other systems.)

    For example:

      printf ("%p", "testing");

 prints '0x' followed by a hexadecimal number--the address of the string
 constant '"testing"'.  It does not print the word 'testing'.

    You can supply the '-' flag with the '%p' conversion to specify
 left-justification, but no other flags, precision, or type modifiers are
 defined.

    The '%n' conversion is unlike any of the other output conversions.
 It uses an argument which must be a pointer to an 'int', but instead of
 printing anything it stores the number of characters printed so far by
 this call at that location.  The 'h' and 'l' type modifiers are
 permitted to specify that the argument is of type 'short int *' or 'long
 int *' instead of 'int *', but no flags, field width, or precision are
 permitted.

    For example,

      int nchar;
      printf ("%d %s%n\n", 3, "bears", &nchar);

 prints:

      3 bears

 and sets 'nchar' to '7', because '3 bears' is seven characters.

    The '%%' conversion prints a literal '%' character.  This conversion
 doesn't use an argument, and no flags, field width, precision, or type
 modifiers are permitted.


 File: libc.info,  Node: Formatted Output Functions,  Next: Dynamic Output,  Prev: Other Output Conversions,  Up: Formatted Output

 12.12.7 Formatted Output Functions
 ----------------------------------

 This section describes how to call 'printf' and related functions.
 Prototypes for these functions are in the header file 'stdio.h'.
 Because these functions take a variable number of arguments, you _must_
 declare prototypes for them before using them.  Of course, the easiest
 way to make sure you have all the right prototypes is to just include
 'stdio.h'.

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

      The 'printf' function prints the optional arguments under the
      control of the template string TEMPLATE to the stream 'stdout'.  It
      returns the number of characters printed, or a negative value if
      there was an output error.

  -- Function: int wprintf (const wchar_t *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      The 'wprintf' function prints the optional arguments under the
      control of the wide template string TEMPLATE to the stream
      'stdout'.  It returns the number of wide characters printed, or a
      negative value if there was an output error.

  -- Function: int fprintf (FILE *STREAM, const char *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This function is just like 'printf', except that the output is
      written to the stream STREAM instead of 'stdout'.

  -- Function: int fwprintf (FILE *STREAM, const wchar_t *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This function is just like 'wprintf', except that the output is
      written to the stream STREAM instead of 'stdout'.

  -- Function: int sprintf (char *S, const char *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is like 'printf', except that the output is stored in the
      character array S instead of written to a stream.  A null character
      is written to mark the end of the string.

      The 'sprintf' function returns the number of characters stored in
      the array S, not including the terminating null character.

      The behavior of this function is undefined if copying takes place
      between objects that overlap--for example, if S is also given as an
      argument to be printed under control of the '%s' conversion.  *Note
      Copying and Concatenation::.

      *Warning:* The 'sprintf' function can be *dangerous* because it can
      potentially output more characters than can fit in the allocation
      size of the string S.  Remember that the field width given in a
      conversion specification is only a _minimum_ value.

      To avoid this problem, you can use 'snprintf' or 'asprintf',
      described below.

  -- Function: int swprintf (wchar_t *S, size_t SIZE, const wchar_t
           *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is like 'wprintf', except that the output is stored in the
      wide character array WS instead of written to a stream.  A null
      wide character is written to mark the end of the string.  The SIZE
      argument specifies the maximum number of characters to produce.
      The trailing null character is counted towards this limit, so you
      should allocate at least SIZE wide characters for the string WS.

      The return value is the number of characters generated for the
      given input, excluding the trailing null.  If not all output fits
      into the provided buffer a negative value is returned.  You should
      try again with a bigger output string.  _Note:_ this is different
      from how 'snprintf' handles this situation.

      Note that the corresponding narrow stream function takes fewer
      parameters.  'swprintf' in fact corresponds to the 'snprintf'
      function.  Since the 'sprintf' function can be dangerous and should
      be avoided the ISO C committee refused to make the same mistake
      again and decided to not define a function exactly corresponding to
      'sprintf'.

  -- Function: int snprintf (char *S, size_t SIZE, const char *TEMPLATE,
           ...)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      The 'snprintf' function is similar to 'sprintf', except that the
      SIZE argument specifies the maximum number of characters to
      produce.  The trailing null character is counted towards this
      limit, so you should allocate at least SIZE characters for the
      string S.  If SIZE is zero, nothing, not even the null byte, shall
      be written and S may be a null pointer.

      The return value is the number of characters which would be
      generated for the given input, excluding the trailing null.  If
      this value is greater or equal to SIZE, not all characters from the
      result have been stored in S.  You should try again with a bigger
      output string.  Here is an example of doing this:

           /* Construct a message describing the value of a variable
              whose name is NAME and whose value is VALUE. */
           char *
           make_message (char *name, char *value)
           {
             /* Guess we need no more than 100 chars of space. */
             int size = 100;
             char *buffer = (char *) xmalloc (size);
             int nchars;
             if (buffer == NULL)
               return NULL;

            /* Try to print in the allocated space. */
             nchars = snprintf (buffer, size, "value of %s is %s",
           		     name, value);
             if (nchars >= size)
               {
                 /* Reallocate buffer now that we know
           	 how much space is needed. */
                 size = nchars + 1;
                 buffer = (char *) xrealloc (buffer, size);

                 if (buffer != NULL)
           	/* Try again. */
           	snprintf (buffer, size, "value of %s is %s",
           		  name, value);
               }
             /* The last call worked, return the string. */
             return buffer;
           }

      In practice, it is often easier just to use 'asprintf', below.

      *Attention:* In versions of the GNU C Library prior to 2.1 the
      return value is the number of characters stored, not including the
      terminating null; unless there was not enough space in S to store
      the result in which case '-1' is returned.  This was changed in
      order to comply with the ISO C99 standard.


 File: libc.info,  Node: Dynamic Output,  Next: Variable Arguments Output,  Prev: Formatted Output Functions,  Up: Formatted Output

 12.12.8 Dynamically Allocating Formatted Output
 -----------------------------------------------

 The functions in this section do formatted output and place the results
 in dynamically allocated memory.

  -- Function: int asprintf (char **PTR, const char *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This function is similar to 'sprintf', except that it dynamically
      allocates a string (as with 'malloc'; *note Unconstrained
      Allocation::) to hold the output, instead of putting the output in
      a buffer you allocate in advance.  The PTR argument should be the
      address of a 'char *' object, and a successful call to 'asprintf'
      stores a pointer to the newly allocated string at that location.

      The return value is the number of characters allocated for the
      buffer, or less than zero if an error occurred.  Usually this means
      that the buffer could not be allocated.

      Here is how to use 'asprintf' to get the same result as the
      'snprintf' example, but more easily:

           /* Construct a message describing the value of a variable
              whose name is NAME and whose value is VALUE. */
           char *
           make_message (char *name, char *value)
           {
             char *result;
             if (asprintf (&result, "value of %s is %s", name, value) < 0)
               return NULL;
             return result;
           }

  -- Function: int obstack_printf (struct obstack *OBSTACK, const char
           *TEMPLATE, ...)
      Preliminary: | MT-Safe race:obstack locale | AS-Unsafe corrupt heap
      | AC-Unsafe corrupt mem | *Note POSIX Safety Concepts::.

      This function is similar to 'asprintf', except that it uses the
      obstack OBSTACK to allocate the space.  *Note Obstacks::.

      The characters are written onto the end of the current object.  To
      get at them, you must finish the object with 'obstack_finish'
      (*note Growing Objects::).


 File: libc.info,  Node: Variable Arguments Output,  Next: Parsing a Template String,  Prev: Dynamic Output,  Up: Formatted Output

 12.12.9 Variable Arguments Output Functions
 -------------------------------------------

 The functions 'vprintf' and friends are provided so that you can define
 your own variadic 'printf'-like functions that make use of the same
 internals as the built-in formatted output functions.

    The most natural way to define such functions would be to use a
 language construct to say, "Call 'printf' and pass this template plus
 all of my arguments after the first five."  But there is no way to do
 this in C, and it would be hard to provide a way, since at the C
 language level there is no way to tell how many arguments your function
 received.

    Since that method is impossible, we provide alternative functions,
 the 'vprintf' series, which lets you pass a 'va_list' to describe "all
 of my arguments after the first five."

    When it is sufficient to define a macro rather than a real function,
 the GNU C compiler provides a way to do this much more easily with
 macros.  For example:

      #define myprintf(a, b, c, d, e, rest...) \
      	    printf (mytemplate , ## rest)

 *Note (cpp)Variadic Macros::, for details.  But this is limited to
 macros, and does not apply to real functions at all.

    Before calling 'vprintf' or the other functions listed in this
 section, you _must_ call 'va_start' (*note Variadic Functions::) to
 initialize a pointer to the variable arguments.  Then you can call
 'va_arg' to fetch the arguments that you want to handle yourself.  This
 advances the pointer past those arguments.

    Once your 'va_list' pointer is pointing at the argument of your
 choice, you are ready to call 'vprintf'.  That argument and all
 subsequent arguments that were passed to your function are used by
 'vprintf' along with the template that you specified separately.

    In some other systems, the 'va_list' pointer may become invalid after
 the call to 'vprintf', so you must not use 'va_arg' after you call
 'vprintf'.  Instead, you should call 'va_end' to retire the pointer from
 service.  However, you can safely call 'va_start' on another pointer
 variable and begin fetching the arguments again through that pointer.
 Calling 'vprintf' does not destroy the argument list of your function,
 merely the particular pointer that you passed to it.

    GNU C does not have such restrictions.  You can safely continue to
 fetch arguments from a 'va_list' pointer after passing it to 'vprintf',
 and 'va_end' is a no-op.  (Note, however, that subsequent 'va_arg' calls
 will fetch the same arguments which 'vprintf' previously used.)

    Prototypes for these functions are declared in 'stdio.h'.

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

      This function is similar to 'printf' except that, instead of taking
      a variable number of arguments directly, it takes an argument list
      pointer AP.

  -- Function: int vwprintf (const wchar_t *TEMPLATE, va_list AP)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This function is similar to 'wprintf' except that, instead of
      taking a variable number of arguments directly, it takes an
      argument list pointer AP.

  -- Function: int vfprintf (FILE *STREAM, const char *TEMPLATE, va_list
           AP)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This is the equivalent of 'fprintf' with the variable argument list
      specified directly as for 'vprintf'.

  -- Function: int vfwprintf (FILE *STREAM, const wchar_t *TEMPLATE,
           va_list AP)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This is the equivalent of 'fwprintf' with the variable argument
      list specified directly as for 'vwprintf'.

  -- Function: int vsprintf (char *S, const char *TEMPLATE, va_list AP)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is the equivalent of 'sprintf' with the variable argument list
      specified directly as for 'vprintf'.

  -- Function: int vswprintf (wchar_t *S, size_t SIZE, const wchar_t
           *TEMPLATE, va_list AP)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is the equivalent of 'swprintf' with the variable argument
      list specified directly as for 'vwprintf'.

  -- Function: int vsnprintf (char *S, size_t SIZE, const char *TEMPLATE,
           va_list AP)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is the equivalent of 'snprintf' with the variable argument
      list specified directly as for 'vprintf'.

  -- Function: int vasprintf (char **PTR, const char *TEMPLATE, va_list
           AP)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      The 'vasprintf' function is the equivalent of 'asprintf' with the
      variable argument list specified directly as for 'vprintf'.

  -- Function: int obstack_vprintf (struct obstack *OBSTACK, const char
           *TEMPLATE, va_list AP)
      Preliminary: | MT-Safe race:obstack locale | AS-Unsafe corrupt heap
      | AC-Unsafe corrupt mem | *Note POSIX Safety Concepts::.

      The 'obstack_vprintf' function is the equivalent of
      'obstack_printf' with the variable argument list specified directly
      as for 'vprintf'.

    Here's an example showing how you might use 'vfprintf'.  This is a
 function that prints error messages to the stream 'stderr', along with a
 prefix indicating the name of the program (*note Error Messages::, for a
 description of 'program_invocation_short_name').

      #include <stdio.h>
      #include <stdarg.h>

      void
      eprintf (const char *template, ...)
      {
        va_list ap;
        extern char *program_invocation_short_name;

        fprintf (stderr, "%s: ", program_invocation_short_name);
        va_start (ap, template);
        vfprintf (stderr, template, ap);
        va_end (ap);
      }

 You could call 'eprintf' like this:

      eprintf ("file `%s' does not exist\n", filename);

    In GNU C, there is a special construct you can use to let the
 compiler know that a function uses a 'printf'-style format string.  Then
 it can check the number and types of arguments in each call to the
 function, and warn you when they do not match the format string.  For
 example, take this declaration of 'eprintf':

      void eprintf (const char *template, ...)
      	__attribute__ ((format (printf, 1, 2)));

 This tells the compiler that 'eprintf' uses a format string like
 'printf' (as opposed to 'scanf'; *note Formatted Input::); the format
 string appears as the first argument; and the arguments to satisfy the
 format begin with the second.  *Note Declaring Attributes of Functions:
 (gcc.info)Function Attributes, for more information.


 File: libc.info,  Node: Parsing a Template String,  Next: Example of Parsing,  Prev: Variable Arguments Output,  Up: Formatted Output

 12.12.10 Parsing a Template String
 ----------------------------------

 You can use the function 'parse_printf_format' to obtain information
 about the number and types of arguments that are expected by a given
 template string.  This function permits interpreters that provide
 interfaces to 'printf' to avoid passing along invalid arguments from the
 user's program, which could cause a crash.

    All the symbols described in this section are declared in the header
 file 'printf.h'.

  -- Function: size_t parse_printf_format (const char *TEMPLATE, size_t
           N, int *ARGTYPES)
      Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
      Safety Concepts::.

      This function returns information about the number and types of
      arguments expected by the 'printf' template string TEMPLATE.  The
      information is stored in the array ARGTYPES; each element of this
      array describes one argument.  This information is encoded using
      the various 'PA_' macros, listed below.

      The argument N specifies the number of elements in the array
      ARGTYPES.  This is the maximum number of elements that
      'parse_printf_format' will try to write.

      'parse_printf_format' returns the total number of arguments
      required by TEMPLATE.  If this number is greater than N, then the
      information returned describes only the first N arguments.  If you
      want information about additional arguments, allocate a bigger
      array and call 'parse_printf_format' again.

    The argument types are encoded as a combination of a basic type and
 modifier flag bits.

  -- Macro: int PA_FLAG_MASK
      This macro is a bitmask for the type modifier flag bits.  You can
      write the expression '(argtypes[i] & PA_FLAG_MASK)' to extract just
      the flag bits for an argument, or '(argtypes[i] & ~PA_FLAG_MASK)'
      to extract just the basic type code.

    Here are symbolic constants that represent the basic types; they
 stand for integer values.

 'PA_INT'
      This specifies that the base type is 'int'.

 'PA_CHAR'
      This specifies that the base type is 'int', cast to 'char'.

 'PA_STRING'
      This specifies that the base type is 'char *', a null-terminated
      string.

 'PA_POINTER'
      This specifies that the base type is 'void *', an arbitrary
      pointer.

 'PA_FLOAT'
      This specifies that the base type is 'float'.

 'PA_DOUBLE'
      This specifies that the base type is 'double'.

 'PA_LAST'
      You can define additional base types for your own programs as
      offsets from 'PA_LAST'.  For example, if you have data types 'foo'
      and 'bar' with their own specialized 'printf' conversions, you
      could define encodings for these types as:

           #define PA_FOO  PA_LAST
           #define PA_BAR  (PA_LAST + 1)

    Here are the flag bits that modify a basic type.  They are combined
 with the code for the basic type using inclusive-or.

 'PA_FLAG_PTR'
      If this bit is set, it indicates that the encoded type is a pointer
      to the base type, rather than an immediate value.  For example,
      'PA_INT|PA_FLAG_PTR' represents the type 'int *'.

 'PA_FLAG_SHORT'
      If this bit is set, it indicates that the base type is modified
      with 'short'.  (This corresponds to the 'h' type modifier.)

 'PA_FLAG_LONG'
      If this bit is set, it indicates that the base type is modified
      with 'long'.  (This corresponds to the 'l' type modifier.)

 'PA_FLAG_LONG_LONG'
      If this bit is set, it indicates that the base type is modified
      with 'long long'.  (This corresponds to the 'L' type modifier.)

 'PA_FLAG_LONG_DOUBLE'
      This is a synonym for 'PA_FLAG_LONG_LONG', used by convention with
      a base type of 'PA_DOUBLE' to indicate a type of 'long double'.

    For an example of using these facilities, see *note Example of
 Parsing::.


 File: libc.info,  Node: Example of Parsing,  Prev: Parsing a Template String,  Up: Formatted Output

 12.12.11 Example of Parsing a Template String
 ---------------------------------------------

 Here is an example of decoding argument types for a format string.  We
 assume this is part of an interpreter which contains arguments of type
 'NUMBER', 'CHAR', 'STRING' and 'STRUCTURE' (and perhaps others which are
 not valid here).

      /* Test whether the NARGS specified objects
         in the vector ARGS are valid
         for the format string FORMAT:
         if so, return 1.
         If not, return 0 after printing an error message.  */

      int
      validate_args (char *format, int nargs, OBJECT *args)
      {
        int *argtypes;
        int nwanted;

        /* Get the information about the arguments.
           Each conversion specification must be at least two characters
           long, so there cannot be more specifications than half the
           length of the string.  */

        argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
        nwanted = parse_printf_format (string, nelts, argtypes);

        /* Check the number of arguments.  */
        if (nwanted > nargs)
          {
            error ("too few arguments (at least %d required)", nwanted);
            return 0;
          }

        /* Check the C type wanted for each argument
           and see if the object given is suitable.  */
        for (i = 0; i < nwanted; i++)
          {
            int wanted;

            if (argtypes[i] & PA_FLAG_PTR)
      	wanted = STRUCTURE;
            else
      	switch (argtypes[i] & ~PA_FLAG_MASK)
 	       {
      	  case PA_INT:
      	  case PA_FLOAT:
      	  case PA_DOUBLE:
      	    wanted = NUMBER;
      	    break;
      	  case PA_CHAR:
      	    wanted = CHAR;
      	    break;
      	  case PA_STRING:
      	    wanted = STRING;
      	    break;
      	  case PA_POINTER:
      	    wanted = STRUCTURE;
      	    break;
 	       }
            if (TYPE (args[i]) != wanted)
 	     {
      	  error ("type mismatch for arg number %d", i);
      	  return 0;
 	     }
          }
        return 1;
      }


 File: libc.info,  Node: Customizing Printf,  Next: Formatted Input,  Prev: Formatted Output,  Up: I/O on Streams

 12.13 Customizing 'printf'
 ==========================

 The GNU C Library lets you define your own custom conversion specifiers
 for 'printf' template strings, to teach 'printf' clever ways to print
 the important data structures of your program.

    The way you do this is by registering the conversion with the
 function 'register_printf_function'; see *note Registering New
 Conversions::.  One of the arguments you pass to this function is a
 pointer to a handler function that produces the actual output; see *note
 Defining the Output Handler::, for information on how to write this
 function.

    You can also install a function that just returns information about
 the number and type of arguments expected by the conversion specifier.
 *Note Parsing a Template String::, for information about this.

    The facilities of this section are declared in the header file
 'printf.h'.

 * Menu:

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

    *Portability Note:* The ability to extend the syntax of 'printf'
 template strings is a GNU extension.  ISO standard C has nothing
 similar.


 File: libc.info,  Node: Registering New Conversions,  Next: Conversion Specifier Options,  Up: Customizing Printf

 12.13.1 Registering New Conversions
 -----------------------------------

 The function to register a new output conversion is
 'register_printf_function', declared in 'printf.h'.

  -- Function: int register_printf_function (int SPEC, printf_function
           HANDLER-FUNCTION, printf_arginfo_function ARGINFO-FUNCTION)
      Preliminary: | MT-Unsafe const:printfext | AS-Unsafe heap lock |
      AC-Unsafe mem lock | *Note POSIX Safety Concepts::.

      This function defines the conversion specifier character SPEC.
      Thus, if SPEC is ''Y'', it defines the conversion '%Y'.  You can
      redefine the built-in conversions like '%s', but flag characters
      like '#' and type modifiers like 'l' can never be used as
      conversions; calling 'register_printf_function' for those
      characters has no effect.  It is advisable not to use lowercase
      letters, since the ISO C standard warns that additional lowercase
      letters may be standardized in future editions of the standard.

      The HANDLER-FUNCTION is the function called by 'printf' and friends
      when this conversion appears in a template string.  *Note Defining
      the Output Handler::, for information about how to define a
      function to pass as this argument.  If you specify a null pointer,
      any existing handler function for SPEC is removed.

      The ARGINFO-FUNCTION is the function called by
      'parse_printf_format' when this conversion appears in a template
      string.  *Note Parsing a Template String::, for information about
      this.

      *Attention:* In the GNU C Library versions before 2.0 the
      ARGINFO-FUNCTION function did not need to be installed unless the
      user used the 'parse_printf_format' function.  This has changed.
      Now a call to any of the 'printf' functions will call this function
      when this format specifier appears in the format string.

      The return value is '0' on success, and '-1' on failure (which
      occurs if SPEC is out of range).

      You can redefine the standard output conversions, but this is
      probably not a good idea because of the potential for confusion.
      Library routines written by other people could break if you do
      this.


 File: libc.info,  Node: Conversion Specifier Options,  Next: Defining the Output Handler,  Prev: Registering New Conversions,  Up: Customizing Printf

 12.13.2 Conversion Specifier Options
 ------------------------------------

 If you define a meaning for '%A', what if the template contains '%+23A'
 or '%-#A'?  To implement a sensible meaning for these, the handler when
 called needs to be able to get the options specified in the template.

    Both the HANDLER-FUNCTION and ARGINFO-FUNCTION accept an argument
 that points to a 'struct printf_info', which contains information about
 the options appearing in an instance of the conversion specifier.  This
 data type is declared in the header file 'printf.h'.

  -- Type: struct printf_info
      This structure is used to pass information about the options
      appearing in an instance of a conversion specifier in a 'printf'
      template string to the handler and arginfo functions for that
      specifier.  It contains the following members:

      'int prec'
           This is the precision specified.  The value is '-1' if no
           precision was specified.  If the precision was given as '*',
           the 'printf_info' structure passed to the handler function
           contains the actual value retrieved from the argument list.
           But the structure passed to the arginfo function contains a
           value of 'INT_MIN', since the actual value is not known.

      'int width'
           This is the minimum field width specified.  The value is '0'
           if no width was specified.  If the field width was given as
           '*', the 'printf_info' structure passed to the handler
           function contains the actual value retrieved from the argument
           list.  But the structure passed to the arginfo function
           contains a value of 'INT_MIN', since the actual value is not
           known.

      'wchar_t spec'
           This is the conversion specifier character specified.  It's
           stored in the structure so that you can register the same
           handler function for multiple characters, but still have a way
           to tell them apart when the handler function is called.

      'unsigned int is_long_double'
           This is a boolean that is true if the 'L', 'll', or 'q' type
           modifier was specified.  For integer conversions, this
           indicates 'long long int', as opposed to 'long double' for
           floating point conversions.

      'unsigned int is_char'
           This is a boolean that is true if the 'hh' type modifier was
           specified.

      'unsigned int is_short'
           This is a boolean that is true if the 'h' type modifier was
           specified.

      'unsigned int is_long'
           This is a boolean that is true if the 'l' type modifier was
           specified.

      'unsigned int alt'
           This is a boolean that is true if the '#' flag was specified.

      'unsigned int space'
           This is a boolean that is true if the ' ' flag was specified.

      'unsigned int left'
           This is a boolean that is true if the '-' flag was specified.

      'unsigned int showsign'
           This is a boolean that is true if the '+' flag was specified.

      'unsigned int group'
           This is a boolean that is true if the ''' flag was specified.

      'unsigned int extra'
           This flag has a special meaning depending on the context.  It
           could be used freely by the user-defined handlers but when
           called from the 'printf' function this variable always
           contains the value '0'.

      'unsigned int wide'
           This flag is set if the stream is wide oriented.

      'wchar_t pad'
           This is the character to use for padding the output to the
           minimum field width.  The value is ''0'' if the '0' flag was
           specified, and '' '' otherwise.


 File: libc.info,  Node: Defining the Output Handler,  Next: Printf Extension Example,  Prev: Conversion Specifier Options,  Up: Customizing Printf

 12.13.3 Defining the Output Handler
 -----------------------------------

 Now let's look at how to define the handler and arginfo functions which
 are passed as arguments to 'register_printf_function'.

    *Compatibility Note:* The interface changed in the GNU C Library
 version 2.0.  Previously the third argument was of type 'va_list *'.

    You should define your handler functions with a prototype like:

      int FUNCTION (FILE *stream, const struct printf_info *info,
      		    const void *const *args)

    The STREAM argument passed to the handler function is the stream to
 which it should write output.

    The INFO argument is a pointer to a structure that contains
 information about the various options that were included with the
 conversion in the template string.  You should not modify this structure
 inside your handler function.  *Note Conversion Specifier Options::, for
 a description of this data structure.

    The ARGS is a vector of pointers to the arguments data.  The number
 of arguments was determined by calling the argument information function
 provided by the user.

    Your handler function should return a value just like 'printf' does:
 it should return the number of characters it has written, or a negative
 value to indicate an error.

  -- Data Type: printf_function
      This is the data type that a handler function should have.

    If you are going to use 'parse_printf_format' in your application,
 you must also define a function to pass as the ARGINFO-FUNCTION argument
 for each new conversion you install with 'register_printf_function'.

    You have to define these functions with a prototype like:

      int FUNCTION (const struct printf_info *info,
      		    size_t n, int *argtypes)

    The return value from the function should be the number of arguments
 the conversion expects.  The function should also fill in no more than N
 elements of the ARGTYPES array with information about the types of each
 of these arguments.  This information is encoded using the various 'PA_'
 macros.  (You will notice that this is the same calling convention
 'parse_printf_format' itself uses.)

  -- Data Type: printf_arginfo_function
      This type is used to describe functions that return information
      about the number and type of arguments used by a conversion
      specifier.


 File: libc.info,  Node: Printf Extension Example,  Next: Predefined Printf Handlers,  Prev: Defining the Output Handler,  Up: Customizing Printf

 12.13.4 'printf' Extension Example
 ----------------------------------

 Here is an example showing how to define a 'printf' handler function.
 This program defines a data structure called a 'Widget' and defines the
 '%W' conversion to print information about 'Widget *' arguments,
 including the pointer value and the name stored in the data structure.
 The '%W' conversion supports the minimum field width and
 left-justification options, but ignores everything else.


      #include <stdio.h>
      #include <stdlib.h>
      #include <printf.h>

      typedef struct
      {
        char *name;
      }
      Widget;

      int
      print_widget (FILE *stream,
                    const struct printf_info *info,
                    const void *const *args)
      {
        const Widget *w;
        char *buffer;
        int len;

        /* Format the output into a string. */
        w = *((const Widget **) (args[0]));
        len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
        if (len == -1)
          return -1;

        /* Pad to the minimum field width and print to the stream. */
        len = fprintf (stream, "%*s",
                       (info->left ? -info->width : info->width),
                       buffer);

        /* Clean up and return. */
        free (buffer);
        return len;
      }


      int
      print_widget_arginfo (const struct printf_info *info, size_t n,
                            int *argtypes)
      {
        /* We always take exactly one argument and this is a pointer to the
           structure.. */
        if (n > 0)
          argtypes[0] = PA_POINTER;
        return 1;
      }


      int
      main (void)
      {
        /* Make a widget to print. */
        Widget mywidget;
        mywidget.name = "mywidget";

        /* Register the print function for widgets. */
        register_printf_function ('W', print_widget, print_widget_arginfo);

        /* Now print the widget. */
        printf ("|%W|\n", &mywidget);
        printf ("|%35W|\n", &mywidget);
        printf ("|%-35W|\n", &mywidget);

        return 0;
      }

    The output produced by this program looks like:

      |<Widget 0xffeffb7c: mywidget>|
      |      <Widget 0xffeffb7c: mywidget>|
      |<Widget 0xffeffb7c: mywidget>      |


 File: libc.info,  Node: Predefined Printf Handlers,  Prev: Printf Extension Example,  Up: Customizing Printf

 12.13.5 Predefined 'printf' Handlers
 ------------------------------------

 The GNU C Library also contains a concrete and useful application of the
 'printf' handler extension.  There are two functions available which
 implement a special way to print floating-point numbers.

  -- Function: int printf_size (FILE *FP, const struct printf_info *INFO,
           const void *const *ARGS)
      Preliminary: | MT-Safe race:fp locale | AS-Unsafe corrupt heap |
      AC-Unsafe mem corrupt | *Note POSIX Safety Concepts::.

      Print a given floating point number as for the format '%f' except
      that there is a postfix character indicating the divisor for the
      number to make this less than 1000.  There are two possible
      divisors: powers of 1024 or powers of 1000.  Which one is used
      depends on the format character specified while registered this
      handler.  If the character is of lower case, 1024 is used.  For
      upper case characters, 1000 is used.

      The postfix tag corresponds to bytes, kilobytes, megabytes,
      gigabytes, etc.  The full table is:

      low   Multiplier    From    Upper   Multiplier
      ' '   1                     ' '     1
      k     2^10 (1024)   kilo    K       10^3 (1000)
      m     2^20          mega    M       10^6
      g     2^30          giga    G       10^9
      t     2^40          tera    T       10^12
      p     2^50          peta    P       10^15
      e     2^60          exa     E       10^18
      z     2^70          zetta   Z       10^21
      y     2^80          yotta   Y       10^24

      The default precision is 3, i.e., 1024 is printed with a lower-case
      format character as if it were '%.3fk' and will yield '1.000k'.

    Due to the requirements of 'register_printf_function' we must also
 provide the function which returns information about the arguments.

  -- Function: int printf_size_info (const struct printf_info *INFO,
           size_t N, int *ARGTYPES)
      Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
      Concepts::.

      This function will return in ARGTYPES the information about the
      used parameters in the way the 'vfprintf' implementation expects
      it.  The format always takes one argument.

    To use these functions both functions must be registered with a call
 like

      register_printf_function ('B', printf_size, printf_size_info);

    Here we register the functions to print numbers as powers of 1000
 since the format character ''B'' is an upper-case character.  If we
 would additionally use ''b'' in a line like

      register_printf_function ('b', printf_size, printf_size_info);

 we could also print using a power of 1024.  Please note that all that is
 different in these two lines is the format specifier.  The 'printf_size'
 function knows about the difference between lower and upper case format
 specifiers.

    The use of ''B'' and ''b'' is no coincidence.  Rather it is the
 preferred way to use this functionality since it is available on some
 other systems which also use format specifiers.


 File: libc.info,  Node: Formatted Input,  Next: EOF and Errors,  Prev: Customizing Printf,  Up: I/O on Streams

 12.14 Formatted Input
 =====================

 The functions described in this section ('scanf' and related functions)
 provide facilities for formatted input analogous to the formatted output
 facilities.  These functions provide a mechanism for reading arbitrary
 values under the control of a "format string" or "template string".

 * Menu:

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


 File: libc.info,  Node: Formatted Input Basics,  Next: Input Conversion Syntax,  Up: Formatted Input

 12.14.1 Formatted Input Basics
 ------------------------------

 Calls to 'scanf' are superficially similar to calls to 'printf' in that
 arbitrary arguments are read under the control of a template string.
 While the syntax of the conversion specifications in the template is
 very similar to that for 'printf', the interpretation of the template is
 oriented more towards free-format input and simple pattern matching,
 rather than fixed-field formatting.  For example, most 'scanf'
 conversions skip over any amount of "white space" (including spaces,
 tabs, and newlines) in the input file, and there is no concept of
 precision for the numeric input conversions as there is for the
 corresponding output conversions.  Ordinarily, non-whitespace characters
 in the template are expected to match characters in the input stream
 exactly, but a matching failure is distinct from an input error on the
 stream.

    Another area of difference between 'scanf' and 'printf' is that you
 must remember to supply pointers rather than immediate values as the
 optional arguments to 'scanf'; the values that are read are stored in
 the objects that the pointers point to.  Even experienced programmers
 tend to forget this occasionally, so if your program is getting strange
 errors that seem to be related to 'scanf', you might want to
 double-check this.

    When a "matching failure" occurs, 'scanf' returns immediately,
 leaving the first non-matching character as the next character to be
 read from the stream.  The normal return value from 'scanf' is the
 number of values that were assigned, so you can use this to determine if
 a matching error happened before all the expected values were read.

    The 'scanf' function is typically used for things like reading in the
 contents of tables.  For example, here is a function that uses 'scanf'
 to initialize an array of 'double':

      void
      readarray (double *array, int n)
      {
        int i;
        for (i=0; i<n; i++)
          if (scanf (" %lf", &(array[i])) != 1)
            invalid_input_error ();
      }

    The formatted input functions are not used as frequently as the
 formatted output functions.  Partly, this is because it takes some care
 to use them properly.  Another reason is that it is difficult to recover
 from a matching error.

    If you are trying to read input that doesn't match a single, fixed
 pattern, you may be better off using a tool such as Flex to generate a
 lexical scanner, or Bison to generate a parser, rather than using
 'scanf'.  For more information about these tools, see *note
 (flex.info)Top::, and *note (bison.info)Top::.


 File: libc.info,  Node: Input Conversion Syntax,  Next: Table of Input Conversions,  Prev: Formatted Input Basics,  Up: Formatted Input

 12.14.2 Input Conversion Syntax
 -------------------------------

 A 'scanf' template string is a string that contains ordinary multibyte
 characters interspersed with conversion specifications that start with
 '%'.

    Any whitespace character (as defined by the 'isspace' function; *note
 Classification of Characters::) in the template causes any number of
 whitespace characters in the input stream to be read and discarded.  The
 whitespace characters that are matched need not be exactly the same
 whitespace characters that appear in the template string.  For example,
 write ' , ' in the template to recognize a comma with optional
 whitespace before and after.

    Other characters in the template string that are not part of
 conversion specifications must match characters in the input stream
 exactly; if this is not the case, a matching failure occurs.

    The conversion specifications in a 'scanf' template string have the
 general form:

      % FLAGS WIDTH TYPE CONVERSION

    In more detail, an input conversion specification consists of an
 initial '%' character followed in sequence by:

    * An optional "flag character" '*', which says to ignore the text
      read for this specification.  When 'scanf' finds a conversion
      specification that uses this flag, it reads input as directed by
      the rest of the conversion specification, but it discards this
      input, does not use a pointer argument, and does not increment the
      count of successful assignments.

    * An optional flag character 'a' (valid with string conversions only)
      which requests allocation of a buffer long enough to store the
      string in.  (This is a GNU extension.)  *Note Dynamic String
      Input::.

    * An optional decimal integer that specifies the "maximum field
      width".  Reading of characters from the input stream stops either
      when this maximum is reached or when a non-matching character is
      found, whichever happens first.  Most conversions discard initial
      whitespace characters (those that don't are explicitly documented),
      and these discarded characters don't count towards the maximum
      field width.  String input conversions store a null character to
      mark the end of the input; the maximum field width does not include
      this terminator.

    * An optional "type modifier character".  For example, you can
      specify a type modifier of 'l' with integer conversions such as
      '%d' to specify that the argument is a pointer to a 'long int'
      rather than a pointer to an 'int'.

    * A character that specifies the conversion to be applied.

    The exact options that are permitted and how they are interpreted
 vary between the different conversion specifiers.  See the descriptions
 of the individual conversions for information about the particular
 options that they allow.

    With the '-Wformat' option, the GNU C compiler checks calls to
 'scanf' and related functions.  It examines the format string and
 verifies that the correct number and types of arguments are supplied.
 There is also a GNU C syntax to tell the compiler that a function you
 write uses a 'scanf'-style format string.  *Note Declaring Attributes of
 Functions: (gcc.info)Function Attributes, for more information.


 File: libc.info,  Node: Table of Input Conversions,  Next: Numeric Input Conversions,  Prev: Input Conversion Syntax,  Up: Formatted Input

 12.14.3 Table of Input Conversions
 ----------------------------------

 Here is a table that summarizes the various conversion specifications:

 '%d'
      Matches an optionally signed integer written in decimal.  *Note
      Numeric Input Conversions::.

 '%i'
      Matches an optionally signed integer in any of the formats that the
      C language defines for specifying an integer constant.  *Note
      Numeric Input Conversions::.

 '%o'
      Matches an unsigned integer written in octal radix.  *Note Numeric
      Input Conversions::.

 '%u'
      Matches an unsigned integer written in decimal radix.  *Note
      Numeric Input Conversions::.

 '%x', '%X'
      Matches an unsigned integer written in hexadecimal radix.  *Note
      Numeric Input Conversions::.

 '%e', '%f', '%g', '%E', '%G'
      Matches an optionally signed floating-point number.  *Note Numeric
      Input Conversions::.

 '%s'

      Matches a string containing only non-whitespace characters.  *Note
      String Input Conversions::.  The presence of the 'l' modifier
      determines whether the output is stored as a wide character string
      or a multibyte string.  If '%s' is used in a wide character
      function the string is converted as with multiple calls to
      'wcrtomb' into a multibyte string.  This means that the buffer must
      provide room for 'MB_CUR_MAX' bytes for each wide character read.
      In case '%ls' is used in a multibyte function the result is
      converted into wide characters as with multiple calls of 'mbrtowc'
      before being stored in the user provided buffer.

 '%S'
      This is an alias for '%ls' which is supported for compatibility
      with the Unix standard.

 '%['
      Matches a string of characters that belong to a specified set.
      *Note String Input Conversions::.  The presence of the 'l' modifier
      determines whether the output is stored as a wide character string
      or a multibyte string.  If '%[' is used in a wide character
      function the string is converted as with multiple calls to
      'wcrtomb' into a multibyte string.  This means that the buffer must
      provide room for 'MB_CUR_MAX' bytes for each wide character read.
      In case '%l[' is used in a multibyte function the result is
      converted into wide characters as with multiple calls of 'mbrtowc'
      before being stored in the user provided buffer.

 '%c'
      Matches a string of one or more characters; the number of
      characters read is controlled by the maximum field width given for
      the conversion.  *Note String Input Conversions::.

      If the '%c' is used in a wide stream function the read value is
      converted from a wide character to the corresponding multibyte
      character before storing it.  Note that this conversion can produce
      more than one byte of output and therefore the provided buffer be
      large enough for up to 'MB_CUR_MAX' bytes for each character.  If
      '%lc' is used in a multibyte function the input is treated as a
      multibyte sequence (and not bytes) and the result is converted as
      with calls to 'mbrtowc'.

 '%C'
      This is an alias for '%lc' which is supported for compatibility
      with the Unix standard.

 '%p'
      Matches a pointer value in the same implementation-defined format
      used by the '%p' output conversion for 'printf'.  *Note Other Input
      Conversions::.

 '%n'
      This conversion doesn't read any characters; it records the number
      of characters read so far by this call.  *Note Other Input
      Conversions::.

 '%%'
      This matches a literal '%' character in the input stream.  No
      corresponding argument is used.  *Note Other Input Conversions::.

    If the syntax of a conversion specification is invalid, the behavior
 is undefined.  If there aren't enough function arguments provided to
 supply addresses for all the conversion specifications in the template
 strings that perform assignments, or if the arguments are not of the
 correct types, the behavior is also undefined.  On the other hand, extra
 arguments are simply ignored.


 File: libc.info,  Node: Numeric Input Conversions,  Next: String Input Conversions,  Prev: Table of Input Conversions,  Up: Formatted Input

 12.14.4 Numeric Input Conversions
 ---------------------------------

 This section describes the 'scanf' conversions for reading numeric
 values.

    The '%d' conversion matches an optionally signed integer in decimal
 radix.  The syntax that is recognized is the same as that for the
 'strtol' function (*note Parsing of Integers::) with the value '10' for
 the BASE argument.

    The '%i' conversion matches an optionally signed integer in any of
 the formats that the C language defines for specifying an integer
 constant.  The syntax that is recognized is the same as that for the
 'strtol' function (*note Parsing of Integers::) with the value '0' for
 the BASE argument.  (You can print integers in this syntax with 'printf'
 by using the '#' flag character with the '%x', '%o', or '%d' conversion.
 *Note Integer Conversions::.)

    For example, any of the strings '10', '0xa', or '012' could be read
 in as integers under the '%i' conversion.  Each of these specifies a
 number with decimal value '10'.

    The '%o', '%u', and '%x' conversions match unsigned integers in
 octal, decimal, and hexadecimal radices, respectively.  The syntax that
 is recognized is the same as that for the 'strtoul' function (*note
 Parsing of Integers::) with the appropriate value ('8', '10', or '16')
 for the BASE argument.

    The '%X' conversion is identical to the '%x' conversion.  They both
 permit either uppercase or lowercase letters to be used as digits.

    The default type of the corresponding argument for the '%d' and '%i'
 conversions is 'int *', and 'unsigned int *' for the other integer
 conversions.  You can use the following type modifiers to specify other
 sizes of integer:

 'hh'
      Specifies that the argument is a 'signed char *' or 'unsigned char
      *'.

      This modifier was introduced in ISO C99.

 'h'
      Specifies that the argument is a 'short int *' or 'unsigned short
      int *'.

 'j'
      Specifies that the argument is a 'intmax_t *' or 'uintmax_t *'.

      This modifier was introduced in ISO C99.

 'l'
      Specifies that the argument is a 'long int *' or 'unsigned long int
      *'.  Two 'l' characters is like the 'L' modifier, below.

      If used with '%c' or '%s' the corresponding parameter is considered
      as a pointer to a wide character or wide character string
      respectively.  This use of 'l' was introduced in Amendment 1 to
      ISO C90.

 'll'
 'L'
 'q'
      Specifies that the argument is a 'long long int *' or 'unsigned
      long long int *'.  (The 'long long' type is an extension supported
      by the GNU C compiler.  For systems that don't provide extra-long
      integers, this is the same as 'long int'.)

      The 'q' modifier is another name for the same thing, which comes
      from 4.4 BSD; a 'long long int' is sometimes called a "quad" 'int'.

 't'
      Specifies that the argument is a 'ptrdiff_t *'.

      This modifier was introduced in ISO C99.

 'z'
      Specifies that the argument is a 'size_t *'.

      This modifier was introduced in ISO C99.

    All of the '%e', '%f', '%g', '%E', and '%G' input conversions are
 interchangeable.  They all match an optionally signed floating point
 number, in the same syntax as for the 'strtod' function (*note Parsing
 of Floats::).

    For the floating-point input conversions, the default argument type
 is 'float *'.  (This is different from the corresponding output
 conversions, where the default type is 'double'; remember that 'float'
 arguments to 'printf' are converted to 'double' by the default argument
 promotions, but 'float *' arguments are not promoted to 'double *'.)
 You can specify other sizes of float using these type modifiers:

 'l'
      Specifies that the argument is of type 'double *'.

 'L'
      Specifies that the argument is of type 'long double *'.

    For all the above number parsing formats there is an additional
 optional flag '''.  When this flag is given the 'scanf' function expects
 the number represented in the input string to be formatted according to
 the grouping rules of the currently selected locale (*note General
 Numeric::).

    If the '"C"' or '"POSIX"' locale is selected there is no difference.
 But for a locale which specifies values for the appropriate fields in
 the locale the input must have the correct form in the input.  Otherwise
 the longest prefix with a correct form is processed.


 File: libc.info,  Node: String Input Conversions,  Next: Dynamic String Input,  Prev: Numeric Input Conversions,  Up: Formatted Input

 12.14.5 String Input Conversions
 --------------------------------

 This section describes the 'scanf' input conversions for reading string
 and character values: '%s', '%S', '%[', '%c', and '%C'.

    You have two options for how to receive the input from these
 conversions:

    * Provide a buffer to store it in.  This is the default.  You should
      provide an argument of type 'char *' or 'wchar_t *' (the latter of
      the 'l' modifier is present).

      *Warning:* To make a robust program, you must make sure that the
      input (plus its terminating null) cannot possibly exceed the size
      of the buffer you provide.  In general, the only way to do this is
      to specify a maximum field width one less than the buffer size.
      *If you provide the buffer, always specify a maximum field width to
      prevent overflow.*

    * Ask 'scanf' to allocate a big enough buffer, by specifying the 'a'
      flag character.  This is a GNU extension.  You should provide an
      argument of type 'char **' for the buffer address to be stored in.
      *Note Dynamic String Input::.

    The '%c' conversion is the simplest: it matches a fixed number of
 characters, always.  The maximum field width says how many characters to
 read; if you don't specify the maximum, the default is 1.  This
 conversion doesn't append a null character to the end of the text it
 reads.  It also does not skip over initial whitespace characters.  It
 reads precisely the next N characters, and fails if it cannot get that
 many.  Since there is always a maximum field width with '%c' (whether
 specified, or 1 by default), you can always prevent overflow by making
 the buffer long enough.

    If the format is '%lc' or '%C' the function stores wide characters
 which are converted using the conversion determined at the time the
 stream was opened from the external byte stream.  The number of bytes
 read from the medium is limited by 'MB_CUR_LEN * N' but at most N wide
 character get stored in the output string.

    The '%s' conversion matches a string of non-whitespace characters.
 It skips and discards initial whitespace, but stops when it encounters
 more whitespace after having read something.  It stores a null character
 at the end of the text that it reads.

    For example, reading the input:

       hello, world

 with the conversion '%10c' produces '" hello, wo"', but reading the same
 input with the conversion '%10s' produces '"hello,"'.

    *Warning:* If you do not specify a field width for '%s', then the
 number of characters read is limited only by where the next whitespace
 character appears.  This almost certainly means that invalid input can
 make your program crash--which is a bug.

    The '%ls' and '%S' format are handled just like '%s' except that the
 external byte sequence is converted using the conversion associated with
 the stream to wide characters with their own encoding.  A width or
 precision specified with the format do not directly determine how many
 bytes are read from the stream since they measure wide characters.  But
 an upper limit can be computed by multiplying the value of the width or
 precision by 'MB_CUR_MAX'.

    To read in characters that belong to an arbitrary set of your choice,
 use the '%[' conversion.  You specify the set between the '[' character
 and a following ']' character, using the same syntax used in regular
 expressions for explicit sets of characters.  As special cases:

    * A literal ']' character can be specified as the first character of
      the set.

    * An embedded '-' character (that is, one that is not the first or
      last character of the set) is used to specify a range of
      characters.

    * If a caret character '^' immediately follows the initial '[', then
      the set of allowed input characters is the everything _except_ the
      characters listed.

    The '%[' conversion does not skip over initial whitespace characters.

    Note that the "character class" syntax available in character sets
 that appear inside regular expressions (such as '[:alpha:]') is _not_
 available in the '%[' conversion.

    Here are some examples of '%[' conversions and what they mean:

 '%25[1234567890]'
      Matches a string of up to 25 digits.

 '%25[][]'
      Matches a string of up to 25 square brackets.

 '%25[^ \f\n\r\t\v]'
      Matches a string up to 25 characters long that doesn't contain any
      of the standard whitespace characters.  This is slightly different
      from '%s', because if the input begins with a whitespace character,
      '%[' reports a matching failure while '%s' simply discards the
      initial whitespace.

 '%25[a-z]'
      Matches up to 25 lowercase characters.

    As for '%c' and '%s' the '%[' format is also modified to produce wide
 characters if the 'l' modifier is present.  All what is said about '%ls'
 above is true for '%l['.

    One more reminder: the '%s' and '%[' conversions are *dangerous* if
 you don't specify a maximum width or use the 'a' flag, because input too
 long would overflow whatever buffer you have provided for it.  No matter
 how long your buffer is, a user could supply input that is longer.  A
 well-written program reports invalid input with a comprehensible error
 message, not with a crash.


 File: libc.info,  Node: Dynamic String Input,  Next: Other Input Conversions,  Prev: String Input Conversions,  Up: Formatted Input

 12.14.6 Dynamically Allocating String Conversions
 -------------------------------------------------

 A GNU extension to formatted input lets you safely read a string with no
 maximum size.  Using this feature, you don't supply a buffer; instead,
 'scanf' allocates a buffer big enough to hold the data and gives you its
 address.  To use this feature, write 'a' as a flag character, as in
 '%as' or '%a[0-9a-z]'.

    The pointer argument you supply for where to store the input should
 have type 'char **'.  The 'scanf' function allocates a buffer and stores
 its address in the word that the argument points to.  You should free
 the buffer with 'free' when you no longer need it.

    Here is an example of using the 'a' flag with the '%[...]' conversion
 specification to read a "variable assignment" of the form 'VARIABLE =
 VALUE'.

      {
        char *variable, *value;

        if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
      		 &variable, &value))
          {
            invalid_input_error ();
            return 0;
          }

        ...
      }


 File: libc.info,  Node: Other Input Conversions,  Next: Formatted Input Functions,  Prev: Dynamic String Input,  Up: Formatted Input

 12.14.7 Other Input Conversions
 -------------------------------

 This section describes the miscellaneous input conversions.

    The '%p' conversion is used to read a pointer value.  It recognizes
 the same syntax used by the '%p' output conversion for 'printf' (*note
 Other Output Conversions::); that is, a hexadecimal number just as the
 '%x' conversion accepts.  The corresponding argument should be of type
 'void **'; that is, the address of a place to store a pointer.

    The resulting pointer value is not guaranteed to be valid if it was
 not originally written during the same program execution that reads it
 in.

    The '%n' conversion produces the number of characters read so far by
 this call.  The corresponding argument should be of type 'int *'.  This
 conversion works in the same way as the '%n' conversion for 'printf';
 see *note Other Output Conversions::, for an example.

    The '%n' conversion is the only mechanism for determining the success
 of literal matches or conversions with suppressed assignments.  If the
 '%n' follows the locus of a matching failure, then no value is stored
 for it since 'scanf' returns before processing the '%n'.  If you store
 '-1' in that argument slot before calling 'scanf', the presence of '-1'
 after 'scanf' indicates an error occurred before the '%n' was reached.

    Finally, the '%%' conversion matches a literal '%' character in the
 input stream, without using an argument.  This conversion does not
 permit any flags, field width, or type modifier to be specified.


 File: libc.info,  Node: Formatted Input Functions,  Next: Variable Arguments Input,  Prev: Other Input Conversions,  Up: Formatted Input

 12.14.8 Formatted Input Functions
 ---------------------------------

 Here are the descriptions of the functions for performing formatted
 input.  Prototypes for these functions are in the header file 'stdio.h'.

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

      The 'scanf' function reads formatted input from the stream 'stdin'
      under the control of the template string TEMPLATE.  The optional
      arguments are pointers to the places which receive the resulting
      values.

      The return value is normally the number of successful assignments.
      If an end-of-file condition is detected before any matches are
      performed, including matches against whitespace and literal
      characters in the template, then 'EOF' is returned.

  -- Function: int wscanf (const wchar_t *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      The 'wscanf' function reads formatted input from the stream 'stdin'
      under the control of the template string TEMPLATE.  The optional
      arguments are pointers to the places which receive the resulting
      values.

      The return value is normally the number of successful assignments.
      If an end-of-file condition is detected before any matches are
      performed, including matches against whitespace and literal
      characters in the template, then 'WEOF' is returned.

  -- Function: int fscanf (FILE *STREAM, const char *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This function is just like 'scanf', except that the input is read
      from the stream STREAM instead of 'stdin'.

  -- Function: int fwscanf (FILE *STREAM, const wchar_t *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This function is just like 'wscanf', except that the input is read
      from the stream STREAM instead of 'stdin'.

  -- Function: int sscanf (const char *S, const char *TEMPLATE, ...)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is like 'scanf', except that the characters are taken from the
      null-terminated string S instead of from a stream.  Reaching the
      end of the string is treated as an end-of-file condition.

      The behavior of this function is undefined if copying takes place
      between objects that overlap--for example, if S is also given as an
      argument to receive a string read under control of the '%s', '%S',
      or '%[' conversion.

  -- Function: int swscanf (const wchar_t *WS, const wchar_t *TEMPLATE,
           ...)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is like 'wscanf', except that the characters are taken from
      the null-terminated string WS instead of from a stream.  Reaching
      the end of the string is treated as an end-of-file condition.

      The behavior of this function is undefined if copying takes place
      between objects that overlap--for example, if WS is also given as
      an argument to receive a string read under control of the '%s',
      '%S', or '%[' conversion.


 File: libc.info,  Node: Variable Arguments Input,  Prev: Formatted Input Functions,  Up: Formatted Input

 12.14.9 Variable Arguments Input Functions
 ------------------------------------------

 The functions 'vscanf' and friends are provided so that you can define
 your own variadic 'scanf'-like functions that make use of the same
 internals as the built-in formatted output functions.  These functions
 are analogous to the 'vprintf' series of output functions.  *Note
 Variable Arguments Output::, for important information on how to use
 them.

    *Portability Note:* The functions listed in this section were
 introduced in ISO C99 and were before available as GNU extensions.

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

      This function is similar to 'scanf', but instead of taking a
      variable number of arguments directly, it takes an argument list
      pointer AP of type 'va_list' (*note Variadic Functions::).

  -- Function: int vwscanf (const wchar_t *TEMPLATE, va_list AP)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This function is similar to 'wscanf', but instead of taking a
      variable number of arguments directly, it takes an argument list
      pointer AP of type 'va_list' (*note Variadic Functions::).

  -- Function: int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list
           AP)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This is the equivalent of 'fscanf' with the variable argument list
      specified directly as for 'vscanf'.

  -- Function: int vfwscanf (FILE *STREAM, const wchar_t *TEMPLATE,
           va_list AP)
      Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
      mem lock corrupt | *Note POSIX Safety Concepts::.

      This is the equivalent of 'fwscanf' with the variable argument list
      specified directly as for 'vwscanf'.

  -- Function: int vsscanf (const char *S, const char *TEMPLATE, va_list
           AP)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is the equivalent of 'sscanf' with the variable argument list
      specified directly as for 'vscanf'.

  -- Function: int vswscanf (const wchar_t *S, const wchar_t *TEMPLATE,
           va_list AP)
      Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
      *Note POSIX Safety Concepts::.

      This is the equivalent of 'swscanf' with the variable argument list
      specified directly as for 'vwscanf'.

    In GNU C, there is a special construct you can use to let the
 compiler know that a function uses a 'scanf'-style format string.  Then
 it can check the number and types of arguments in each call to the
 function, and warn you when they do not match the format string.  For
 details, see *note Declaring Attributes of Functions: (gcc.info)Function
 Attributes.


 File: libc.info,  Node: EOF and Errors,  Next: Error Recovery,  Prev: Formatted Input,  Up: I/O on Streams

 12.15 End-Of-File and Errors
 ============================

 Many of the functions described in this chapter return the value of the
 macro 'EOF' to indicate unsuccessful completion of the operation.  Since
 'EOF' is used to report both end of file and random errors, it's often
 better to use the 'feof' function to check explicitly for end of file
 and 'ferror' to check for errors.  These functions check indicators that
 are part of the internal state of the stream object, indicators set if
 the appropriate condition was detected by a previous I/O operation on
 that stream.

  -- Macro: int EOF
      This macro is an integer value that is returned by a number of
      narrow stream functions to indicate an end-of-file condition, or
      some other error situation.  With the GNU C Library, 'EOF' is '-1'.
      In other libraries, its value may be some other negative number.

      This symbol is declared in 'stdio.h'.

  -- Macro: int WEOF
      This macro is an integer value that is returned by a number of wide
      stream functions to indicate an end-of-file condition, or some
      other error situation.  With the GNU C Library, 'WEOF' is '-1'.  In
      other libraries, its value may be some other negative number.

      This symbol is declared in 'wchar.h'.

  -- Function: int feof (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
      Safety Concepts::.

      The 'feof' function returns nonzero if and only if the end-of-file
      indicator for the stream STREAM is set.

      This symbol is declared in 'stdio.h'.

  -- Function: int feof_unlocked (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
      Concepts::.

      The 'feof_unlocked' function is equivalent to the 'feof' function
      except that it does not implicitly lock the stream.

      This function is a GNU extension.

      This symbol is declared in 'stdio.h'.

  -- Function: int ferror (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
      Safety Concepts::.

      The 'ferror' function returns nonzero if and only if the error
      indicator for the stream STREAM is set, indicating that an error
      has occurred on a previous operation on the stream.

      This symbol is declared in 'stdio.h'.

  -- Function: int ferror_unlocked (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
      Concepts::.

      The 'ferror_unlocked' function is equivalent to the 'ferror'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.

      This symbol is declared in 'stdio.h'.

    In addition to setting the error indicator associated with the
 stream, the functions that operate on streams also set 'errno' in the
 same way as the corresponding low-level functions that operate on file
 descriptors.  For example, all of the functions that perform output to a
 stream--such as 'fputc', 'printf', and 'fflush'--are implemented in
 terms of 'write', and all of the 'errno' error conditions defined for
 'write' are meaningful for these functions.  For more information about
 the descriptor-level I/O functions, see *note Low-Level I/O::.


 File: libc.info,  Node: Error Recovery,  Next: Binary Streams,  Prev: EOF and Errors,  Up: I/O on Streams

 12.16 Recovering from errors
 ============================

 You may explicitly clear the error and EOF flags with the 'clearerr'
 function.

  -- Function: void clearerr (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
      Safety Concepts::.

      This function clears the end-of-file and error indicators for the
      stream STREAM.

      The file positioning functions (*note File Positioning::) also
      clear the end-of-file indicator for the stream.

  -- Function: void clearerr_unlocked (FILE *STREAM)
      Preliminary: | MT-Safe race:stream | AS-Safe | AC-Safe | *Note
      POSIX Safety Concepts::.

      The 'clearerr_unlocked' function is equivalent to the 'clearerr'
      function except that it does not implicitly lock the stream.

      This function is a GNU extension.

    Note that it is _not_ correct to just clear the error flag and retry
 a failed stream operation.  After a failed write, any number of
 characters since the last buffer flush may have been committed to the
 file, while some buffered data may have been discarded.  Merely retrying
 can thus cause lost or repeated data.

    A failed read may leave the file pointer in an inappropriate position
 for a second try.  In both cases, you should seek to a known position
 before retrying.

    Most errors that can happen are not recoverable -- a second try will
 always fail again in the same way.  So usually it is best to give up and
 report the error to the user, rather than install complicated recovery
 logic.

    One important exception is 'EINTR' (*note Interrupted Primitives::).
 Many stream I/O implementations will treat it as an ordinary error,
 which can be quite inconvenient.  You can avoid this hassle by
 installing all signals with the 'SA_RESTART' flag.

    For similar reasons, setting nonblocking I/O on a stream's file
 descriptor is not usually advisable.


 File: libc.info,  Node: Binary Streams,  Next: File Positioning,  Prev: Error Recovery,  Up: I/O on Streams

 12.17 Text and Binary Streams
 =============================

 GNU systems and other POSIX-compatible operating systems organize all
 files as uniform sequences of characters.  However, some other systems
 make a distinction between files containing text and files containing
 binary data, and the input and output facilities of ISO C provide for
 this distinction.  This section tells you how to write programs portable
 to such systems.

    When you open a stream, you can specify either a "text stream" or a
 "binary stream".  You indicate that you want a binary stream by
 specifying the 'b' modifier in the OPENTYPE argument to 'fopen'; see
 *note Opening Streams::.  Without this option, 'fopen' opens the file as
 a text stream.

    Text and binary streams differ in several ways:

    * The data read from a text stream is divided into "lines" which are
      terminated by newline (''\n'') characters, while a binary stream is
      simply a long series of characters.  A text stream might on some
      systems fail to handle lines more than 254 characters long
      (including the terminating newline character).

    * On some systems, text files can contain only printing characters,
      horizontal tab characters, and newlines, and so text streams may
      not support other characters.  However, binary streams can handle
      any character value.

    * Space characters that are written immediately preceding a newline
      character in a text stream may disappear when the file is read in
      again.

    * More generally, there need not be a one-to-one mapping between
      characters that are read from or written to a text stream, and the
      characters in the actual file.

    Since a binary stream is always more capable and more predictable
 than a text stream, you might wonder what purpose text streams serve.
 Why not simply always use binary streams?  The answer is that on these
 operating systems, text and binary streams use different file formats,
 and the only way to read or write "an ordinary file of text" that can
 work with other text-oriented programs is through a text stream.

    In the GNU C Library, and on all POSIX systems, there is no
 difference between text streams and binary streams.  When you open a
 stream, you get the same kind of stream regardless of whether you ask
 for binary.  This stream can handle any file content, and has none of
 the restrictions that text streams sometimes have.


 File: libc.info,  Node: File Positioning,  Next: Portable Positioning,  Prev: Binary Streams,  Up: I/O on Streams

 12.18 File Positioning
 ======================

 The "file position" of a stream describes where in the file the stream
 is currently reading or writing.  I/O on the stream advances the file
 position through the file.  On GNU systems, the file position is
 represented as an integer, which counts the number of bytes from the
 beginning of the file.  *Note File Position::.

    During I/O to an ordinary disk file, you can change the file position
 whenever you wish, so as to read or write any portion of the file.  Some
 other kinds of files may also permit this.  Files which support changing
 the file position are sometimes referred to as "random-access" files.

    You can use the functions in this section to examine or modify the
 file position indicator associated with a stream.  The symbols listed
 below are declared in the header file 'stdio.h'.

  -- Function: long int ftell (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function returns the current file position of the stream
      STREAM.

      This function can fail if the stream doesn't support file
      positioning, or if the file position can't be represented in a
      'long int', and possibly for other reasons as well.  If a failure
      occurs, a value of '-1' is returned.

  -- Function: off_t ftello (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'ftello' function is similar to 'ftell', except that it returns
      a value of type 'off_t'.  Systems which support this type use it to
      describe all file positions, unlike the POSIX specification which
      uses a long int.  The two are not necessarily the same size.
      Therefore, using ftell can lead to problems if the implementation
      is written on top of a POSIX compliant low-level I/O
      implementation, and using 'ftello' is preferable whenever it is
      available.

      If this function fails it returns '(off_t) -1'.  This can happen
      due to missing support for file positioning or internal errors.
      Otherwise the return value is the current file position.

      The function is an extension defined in the Unix Single
      Specification version 2.

      When the sources are compiled with '_FILE_OFFSET_BITS == 64' on a
      32 bit system this function is in fact 'ftello64'.  I.e., the LFS
      interface transparently replaces the old interface.

  -- Function: off64_t ftello64 (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function is similar to 'ftello' with the only difference that
      the return value is of type 'off64_t'.  This also requires that the
      stream STREAM was opened using either 'fopen64', 'freopen64', or
      'tmpfile64' since otherwise the underlying file operations to
      position the file pointer beyond the 2^31 bytes limit might fail.

      If the sources are compiled with '_FILE_OFFSET_BITS == 64' on a 32
      bits machine this function is available under the name 'ftello' and
      so transparently replaces the old interface.

  -- Function: int fseek (FILE *STREAM, long int OFFSET, int WHENCE)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'fseek' function is used to change the file position of the
      stream STREAM.  The value of WHENCE must be one of the constants
      'SEEK_SET', 'SEEK_CUR', or 'SEEK_END', to indicate whether the
      OFFSET is relative to the beginning of the file, the current file
      position, or the end of the file, respectively.

      This function returns a value of zero if the operation was
      successful, and a nonzero value to indicate failure.  A successful
      call also clears the end-of-file indicator of STREAM and discards
      any characters that were "pushed back" by the use of 'ungetc'.

      'fseek' either flushes any buffered output before setting the file
      position or else remembers it so it will be written later in its
      proper place in the file.

  -- Function: int fseeko (FILE *STREAM, off_t OFFSET, int WHENCE)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function is similar to 'fseek' but it corrects a problem with
      'fseek' in a system with POSIX types.  Using a value of type 'long
      int' for the offset is not compatible with POSIX. 'fseeko' uses the
      correct type 'off_t' for the OFFSET parameter.

      For this reason it is a good idea to prefer 'ftello' whenever it is
      available since its functionality is (if different at all) closer
      the underlying definition.

      The functionality and return value is the same as for 'fseek'.

      The function is an extension defined in the Unix Single
      Specification version 2.

      When the sources are compiled with '_FILE_OFFSET_BITS == 64' on a
      32 bit system this function is in fact 'fseeko64'.  I.e., the LFS
      interface transparently replaces the old interface.

  -- Function: int fseeko64 (FILE *STREAM, off64_t OFFSET, int WHENCE)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      This function is similar to 'fseeko' with the only difference that
      the OFFSET parameter is of type 'off64_t'.  This also requires that
      the stream STREAM was opened using either 'fopen64', 'freopen64',
      or 'tmpfile64' since otherwise the underlying file operations to
      position the file pointer beyond the 2^31 bytes limit might fail.

      If the sources are compiled with '_FILE_OFFSET_BITS == 64' on a 32
      bits machine this function is available under the name 'fseeko' and
      so transparently replaces the old interface.

    *Portability Note:* In non-POSIX systems, 'ftell', 'ftello', 'fseek'
 and 'fseeko' might work reliably only on binary streams.  *Note Binary
 Streams::.

    The following symbolic constants are defined for use as the WHENCE
 argument to 'fseek'.  They are also used with the 'lseek' function
 (*note I/O Primitives::) and to specify offsets for file locks (*note
 Control Operations::).

  -- Macro: int SEEK_SET
      This is an integer constant which, when used as the WHENCE argument
      to the 'fseek' or 'fseeko' function, specifies that the offset
      provided is relative to the beginning of the file.

  -- Macro: int SEEK_CUR
      This is an integer constant which, when used as the WHENCE argument
      to the 'fseek' or 'fseeko' function, specifies that the offset
      provided is relative to the current file position.

  -- Macro: int SEEK_END
      This is an integer constant which, when used as the WHENCE argument
      to the 'fseek' or 'fseeko' function, specifies that the offset
      provided is relative to the end of the file.

  -- Function: void rewind (FILE *STREAM)
      Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
      | *Note POSIX Safety Concepts::.

      The 'rewind' function positions the stream STREAM at the beginning
      of the file.  It is equivalent to calling 'fseek' or 'fseeko' on
      the STREAM with an OFFSET argument of '0L' and a WHENCE argument of
      'SEEK_SET', except that the return value is discarded and the error
      indicator for the stream is reset.

    These three aliases for the 'SEEK_...' constants exist for the sake
 of compatibility with older BSD systems.  They are defined in two
 different header files: 'fcntl.h' and 'sys/file.h'.

 'L_SET'
      An alias for 'SEEK_SET'.

 'L_INCR'
      An alias for 'SEEK_CUR'.

 'L_XTND'
      An alias for 'SEEK_END'.