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