This is libc.info, produced by makeinfo version 5.1 from libc.texinfo.
|
|
This is ‘The GNU C Library Reference Manual’, for version 2.33 (GNU).
|
|
Copyright © 1993–2021 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.
|
* CHAR_BIT: (libc)Width of Type.
|
* CHILD_MAX: (libc)General Limits.
|
* CIGNORE: (libc)Control Modes.
|
* CLK_TCK: (libc)Processor Time.
|
* CLOCAL: (libc)Control Modes.
|
* CLOCKS_PER_SEC: (libc)CPU Time.
|
* CLOCK_MONOTONIC: (libc)Getting the Time.
|
* CLOCK_REALTIME: (libc)Getting the Time.
|
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
|
* CPU_CLR: (libc)CPU Affinity.
|
* CPU_FEATURE_USABLE: (libc)X86.
|
* CPU_ISSET: (libc)CPU Affinity.
|
* CPU_SET: (libc)CPU Affinity.
|
* CPU_SETSIZE: (libc)CPU Affinity.
|
* CPU_ZERO: (libc)CPU Affinity.
|
* CREAD: (libc)Control Modes.
|
* CRTS_IFLOW: (libc)Control Modes.
|
* CS5: (libc)Control Modes.
|
* CS6: (libc)Control Modes.
|
* CS7: (libc)Control Modes.
|
* CS8: (libc)Control Modes.
|
* CSIZE: (libc)Control Modes.
|
* CSTOPB: (libc)Control Modes.
|
* DTTOIF: (libc)Directory Entries.
|
* E2BIG: (libc)Error Codes.
|
* EACCES: (libc)Error Codes.
|
* EADDRINUSE: (libc)Error Codes.
|
* EADDRNOTAVAIL: (libc)Error Codes.
|
* EADV: (libc)Error Codes.
|
* EAFNOSUPPORT: (libc)Error Codes.
|
* EAGAIN: (libc)Error Codes.
|
* EALREADY: (libc)Error Codes.
|
* EAUTH: (libc)Error Codes.
|
* EBACKGROUND: (libc)Error Codes.
|
* EBADE: (libc)Error Codes.
|
* EBADF: (libc)Error Codes.
|
* EBADFD: (libc)Error Codes.
|
* EBADMSG: (libc)Error Codes.
|
* EBADR: (libc)Error Codes.
|
* EBADRPC: (libc)Error Codes.
|
* EBADRQC: (libc)Error Codes.
|
* EBADSLT: (libc)Error Codes.
|
* EBFONT: (libc)Error Codes.
|
* EBUSY: (libc)Error Codes.
|
* ECANCELED: (libc)Error Codes.
|
* ECHILD: (libc)Error Codes.
|
* ECHO: (libc)Local Modes.
|
* ECHOCTL: (libc)Local Modes.
|
* ECHOE: (libc)Local Modes.
|
* ECHOK: (libc)Local Modes.
|
* ECHOKE: (libc)Local Modes.
|
* ECHONL: (libc)Local Modes.
|
* ECHOPRT: (libc)Local Modes.
|
* ECHRNG: (libc)Error Codes.
|
* ECOMM: (libc)Error Codes.
|
* ECONNABORTED: (libc)Error Codes.
|
* ECONNREFUSED: (libc)Error Codes.
|
* ECONNRESET: (libc)Error Codes.
|
* ED: (libc)Error Codes.
|
* EDEADLK: (libc)Error Codes.
|
* EDEADLOCK: (libc)Error Codes.
|
* EDESTADDRREQ: (libc)Error Codes.
|
* EDIED: (libc)Error Codes.
|
* EDOM: (libc)Error Codes.
|
* EDOTDOT: (libc)Error Codes.
|
* EDQUOT: (libc)Error Codes.
|
* EEXIST: (libc)Error Codes.
|
* EFAULT: (libc)Error Codes.
|
* EFBIG: (libc)Error Codes.
|
* EFTYPE: (libc)Error Codes.
|
* EGRATUITOUS: (libc)Error Codes.
|
* EGREGIOUS: (libc)Error Codes.
|
* EHOSTDOWN: (libc)Error Codes.
|
* EHOSTUNREACH: (libc)Error Codes.
|
* EHWPOISON: (libc)Error Codes.
|
* EIDRM: (libc)Error Codes.
|
* EIEIO: (libc)Error Codes.
|
* EILSEQ: (libc)Error Codes.
|
* EINPROGRESS: (libc)Error Codes.
|
* EINTR: (libc)Error Codes.
|
* EINVAL: (libc)Error Codes.
|
* EIO: (libc)Error Codes.
|
* EISCONN: (libc)Error Codes.
|
* EISDIR: (libc)Error Codes.
|
* EISNAM: (libc)Error Codes.
|
* EKEYEXPIRED: (libc)Error Codes.
|
* EKEYREJECTED: (libc)Error Codes.
|
* EKEYREVOKED: (libc)Error Codes.
|
* EL2HLT: (libc)Error Codes.
|
* EL2NSYNC: (libc)Error Codes.
|
* EL3HLT: (libc)Error Codes.
|
* EL3RST: (libc)Error Codes.
|
* ELIBACC: (libc)Error Codes.
|
* ELIBBAD: (libc)Error Codes.
|
* ELIBEXEC: (libc)Error Codes.
|
* ELIBMAX: (libc)Error Codes.
|
* ELIBSCN: (libc)Error Codes.
|
* ELNRNG: (libc)Error Codes.
|
* ELOOP: (libc)Error Codes.
|
* EMEDIUMTYPE: (libc)Error Codes.
|
* EMFILE: (libc)Error Codes.
|
* EMLINK: (libc)Error Codes.
|
* EMSGSIZE: (libc)Error Codes.
|
* EMULTIHOP: (libc)Error Codes.
|
* ENAMETOOLONG: (libc)Error Codes.
|
* ENAVAIL: (libc)Error Codes.
|
* ENEEDAUTH: (libc)Error Codes.
|
* ENETDOWN: (libc)Error Codes.
|
* ENETRESET: (libc)Error Codes.
|
* ENETUNREACH: (libc)Error Codes.
|
* ENFILE: (libc)Error Codes.
|
* ENOANO: (libc)Error Codes.
|
* ENOBUFS: (libc)Error Codes.
|
* ENOCSI: (libc)Error Codes.
|
* ENODATA: (libc)Error Codes.
|
* ENODEV: (libc)Error Codes.
|
* ENOENT: (libc)Error Codes.
|
* ENOEXEC: (libc)Error Codes.
|
* ENOKEY: (libc)Error Codes.
|
* ENOLCK: (libc)Error Codes.
|
* ENOLINK: (libc)Error Codes.
|
* ENOMEDIUM: (libc)Error Codes.
|
* ENOMEM: (libc)Error Codes.
|
* ENOMSG: (libc)Error Codes.
|
* ENONET: (libc)Error Codes.
|
* ENOPKG: (libc)Error Codes.
|
* ENOPROTOOPT: (libc)Error Codes.
|
* ENOSPC: (libc)Error Codes.
|
* ENOSR: (libc)Error Codes.
|
* ENOSTR: (libc)Error Codes.
|
* ENOSYS: (libc)Error Codes.
|
* ENOTBLK: (libc)Error Codes.
|
* ENOTCONN: (libc)Error Codes.
|
* ENOTDIR: (libc)Error Codes.
|
* ENOTEMPTY: (libc)Error Codes.
|
* ENOTNAM: (libc)Error Codes.
|
* ENOTRECOVERABLE: (libc)Error Codes.
|
* ENOTSOCK: (libc)Error Codes.
|
* ENOTSUP: (libc)Error Codes.
|
* ENOTTY: (libc)Error Codes.
|
* ENOTUNIQ: (libc)Error Codes.
|
* ENXIO: (libc)Error Codes.
|
* EOF: (libc)EOF and Errors.
|
* EOPNOTSUPP: (libc)Error Codes.
|
* EOVERFLOW: (libc)Error Codes.
|
* EOWNERDEAD: (libc)Error Codes.
|
* EPERM: (libc)Error Codes.
|
* EPFNOSUPPORT: (libc)Error Codes.
|
* EPIPE: (libc)Error Codes.
|
* EPROCLIM: (libc)Error Codes.
|
* EPROCUNAVAIL: (libc)Error Codes.
|
* EPROGMISMATCH: (libc)Error Codes.
|
* EPROGUNAVAIL: (libc)Error Codes.
|
* EPROTO: (libc)Error Codes.
|
* EPROTONOSUPPORT: (libc)Error Codes.
|
* EPROTOTYPE: (libc)Error Codes.
|
* EQUIV_CLASS_MAX: (libc)Utility Limits.
|
* ERANGE: (libc)Error Codes.
|
* EREMCHG: (libc)Error Codes.
|
* EREMOTE: (libc)Error Codes.
|
* EREMOTEIO: (libc)Error Codes.
|
* ERESTART: (libc)Error Codes.
|
* ERFKILL: (libc)Error Codes.
|
* EROFS: (libc)Error Codes.
|
* ERPCMISMATCH: (libc)Error Codes.
|
* ESHUTDOWN: (libc)Error Codes.
|
* ESOCKTNOSUPPORT: (libc)Error Codes.
|
* ESPIPE: (libc)Error Codes.
|
* ESRCH: (libc)Error Codes.
|
* ESRMNT: (libc)Error Codes.
|
* ESTALE: (libc)Error Codes.
|
* ESTRPIPE: (libc)Error Codes.
|
* ETIME: (libc)Error Codes.
|
* ETIMEDOUT: (libc)Error Codes.
|
* ETOOMANYREFS: (libc)Error Codes.
|
* ETXTBSY: (libc)Error Codes.
|
* EUCLEAN: (libc)Error Codes.
|
* EUNATCH: (libc)Error Codes.
|
* EUSERS: (libc)Error Codes.
|
* EWOULDBLOCK: (libc)Error Codes.
|
* EXDEV: (libc)Error Codes.
|
* EXFULL: (libc)Error Codes.
|
* EXIT_FAILURE: (libc)Exit Status.
|
* EXIT_SUCCESS: (libc)Exit Status.
|
* EXPR_NEST_MAX: (libc)Utility Limits.
|
* FD_CLOEXEC: (libc)Descriptor Flags.
|
* FD_CLR: (libc)Waiting for I/O.
|
* FD_ISSET: (libc)Waiting for I/O.
|
* FD_SET: (libc)Waiting for I/O.
|
* FD_SETSIZE: (libc)Waiting for I/O.
|
* FD_ZERO: (libc)Waiting for I/O.
|
* FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
|
* FILENAME_MAX: (libc)Limits for Files.
|
* FLUSHO: (libc)Local Modes.
|
* FOPEN_MAX: (libc)Opening Streams.
|
* FP_ILOGB0: (libc)Exponents and Logarithms.
|
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
|
* FP_LLOGB0: (libc)Exponents and Logarithms.
|
* FP_LLOGBNAN: (libc)Exponents and Logarithms.
|
* F_DUPFD: (libc)Duplicating Descriptors.
|
* F_GETFD: (libc)Descriptor Flags.
|
* F_GETFL: (libc)Getting File Status Flags.
|
* F_GETLK: (libc)File Locks.
|
* F_GETOWN: (libc)Interrupt Input.
|
* F_OFD_GETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLKW: (libc)Open File Description Locks.
|
* F_OK: (libc)Testing File Access.
|
* F_SETFD: (libc)Descriptor Flags.
|
* F_SETFL: (libc)Getting File Status Flags.
|
* F_SETLK: (libc)File Locks.
|
* F_SETLKW: (libc)File Locks.
|
* F_SETOWN: (libc)Interrupt Input.
|
* HAS_CPU_FEATURE: (libc)X86.
|
* HUGE_VAL: (libc)Math Error Reporting.
|
* HUGE_VALF: (libc)Math Error Reporting.
|
* HUGE_VALL: (libc)Math Error Reporting.
|
* HUGE_VAL_FN: (libc)Math Error Reporting.
|
* HUGE_VAL_FNx: (libc)Math Error Reporting.
|
* HUPCL: (libc)Control Modes.
|
* I: (libc)Complex Numbers.
|
* ICANON: (libc)Local Modes.
|
* ICRNL: (libc)Input Modes.
|
* IEXTEN: (libc)Local Modes.
|
* IFNAMSIZ: (libc)Interface Naming.
|
* IFTODT: (libc)Directory Entries.
|
* IGNBRK: (libc)Input Modes.
|
* IGNCR: (libc)Input Modes.
|
* IGNPAR: (libc)Input Modes.
|
* IMAXBEL: (libc)Input Modes.
|
* INADDR_ANY: (libc)Host Address Data Type.
|
* INADDR_BROADCAST: (libc)Host Address Data Type.
|
* INADDR_LOOPBACK: (libc)Host Address Data Type.
|
* INADDR_NONE: (libc)Host Address Data Type.
|
* INFINITY: (libc)Infinity and NaN.
|
* INLCR: (libc)Input Modes.
|
* INPCK: (libc)Input Modes.
|
* IPPORT_RESERVED: (libc)Ports.
|
* IPPORT_USERRESERVED: (libc)Ports.
|
* ISIG: (libc)Local Modes.
|
* ISTRIP: (libc)Input Modes.
|
* IXANY: (libc)Input Modes.
|
* IXOFF: (libc)Input Modes.
|
* IXON: (libc)Input Modes.
|
* LINE_MAX: (libc)Utility Limits.
|
* LINK_MAX: (libc)Limits for Files.
|
* L_ctermid: (libc)Identifying the Terminal.
|
* L_cuserid: (libc)Who Logged In.
|
* L_tmpnam: (libc)Temporary Files.
|
* MAXNAMLEN: (libc)Limits for Files.
|
* MAXSYMLINKS: (libc)Symbolic Links.
|
* MAX_CANON: (libc)Limits for Files.
|
* MAX_INPUT: (libc)Limits for Files.
|
* MB_CUR_MAX: (libc)Selecting the Conversion.
|
* MB_LEN_MAX: (libc)Selecting the Conversion.
|
* MDMBUF: (libc)Control Modes.
|
* MSG_DONTROUTE: (libc)Socket Data Options.
|
* MSG_OOB: (libc)Socket Data Options.
|
* MSG_PEEK: (libc)Socket Data Options.
|
* NAME_MAX: (libc)Limits for Files.
|
* NAN: (libc)Infinity and NaN.
|
* NCCS: (libc)Mode Data Types.
|
* NGROUPS_MAX: (libc)General Limits.
|
* NOFLSH: (libc)Local Modes.
|
* NOKERNINFO: (libc)Local Modes.
|
* NSIG: (libc)Standard Signals.
|
* NULL: (libc)Null Pointer Constant.
|
* ONLCR: (libc)Output Modes.
|
* ONOEOT: (libc)Output Modes.
|
* OPEN_MAX: (libc)General Limits.
|
* OPOST: (libc)Output Modes.
|
* OXTABS: (libc)Output Modes.
|
* O_ACCMODE: (libc)Access Modes.
|
* O_APPEND: (libc)Operating Modes.
|
* O_ASYNC: (libc)Operating Modes.
|
* O_CREAT: (libc)Open-time Flags.
|
* O_DIRECTORY: (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_NOFOLLOW: (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_PATH: (libc)Access Modes.
|
* O_RDONLY: (libc)Access Modes.
|
* O_RDWR: (libc)Access Modes.
|
* O_READ: (libc)Access Modes.
|
* O_SHLOCK: (libc)Open-time Flags.
|
* O_SYNC: (libc)Operating Modes.
|
* O_TMPFILE: (libc)Open-time Flags.
|
* O_TRUNC: (libc)Open-time Flags.
|
* O_WRITE: (libc)Access Modes.
|
* O_WRONLY: (libc)Access Modes.
|
* PARENB: (libc)Control Modes.
|
* PARMRK: (libc)Input Modes.
|
* PARODD: (libc)Control Modes.
|
* PATH_MAX: (libc)Limits for Files.
|
* PA_FLAG_MASK: (libc)Parsing a Template String.
|
* PENDIN: (libc)Local Modes.
|
* PF_FILE: (libc)Local Namespace Details.
|
* PF_INET6: (libc)Internet Namespace.
|
* PF_INET: (libc)Internet Namespace.
|
* PF_LOCAL: (libc)Local Namespace Details.
|
* PF_UNIX: (libc)Local Namespace Details.
|
* PIPE_BUF: (libc)Limits for Files.
|
* PTHREAD_ATTR_NO_SIGMASK_NP: (libc)Initial Thread Signal Mask.
|
* P_tmpdir: (libc)Temporary Files.
|
* RAND_MAX: (libc)ISO Random.
|
* RE_DUP_MAX: (libc)General Limits.
|
* RLIM_INFINITY: (libc)Limits on Resources.
|
* R_OK: (libc)Testing File Access.
|
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
|
* SA_ONSTACK: (libc)Flags for Sigaction.
|
* SA_RESTART: (libc)Flags for Sigaction.
|
* SEEK_CUR: (libc)File Positioning.
|
* SEEK_END: (libc)File Positioning.
|
* SEEK_SET: (libc)File Positioning.
|
* SIGABRT: (libc)Program Error Signals.
|
* SIGALRM: (libc)Alarm Signals.
|
* SIGBUS: (libc)Program Error Signals.
|
* SIGCHLD: (libc)Job Control Signals.
|
* SIGCLD: (libc)Job Control Signals.
|
* SIGCONT: (libc)Job Control Signals.
|
* SIGEMT: (libc)Program Error Signals.
|
* SIGFPE: (libc)Program Error Signals.
|
* SIGHUP: (libc)Termination Signals.
|
* SIGILL: (libc)Program Error Signals.
|
* SIGINFO: (libc)Miscellaneous Signals.
|
* SIGINT: (libc)Termination Signals.
|
* SIGIO: (libc)Asynchronous I/O Signals.
|
* SIGIOT: (libc)Program Error Signals.
|
* SIGKILL: (libc)Termination Signals.
|
* SIGLOST: (libc)Operation Error Signals.
|
* SIGPIPE: (libc)Operation Error Signals.
|
* SIGPOLL: (libc)Asynchronous I/O Signals.
|
* SIGPROF: (libc)Alarm Signals.
|
* SIGQUIT: (libc)Termination Signals.
|
* SIGSEGV: (libc)Program Error Signals.
|
* SIGSTOP: (libc)Job Control Signals.
|
* SIGSYS: (libc)Program Error Signals.
|
* SIGTERM: (libc)Termination Signals.
|
* SIGTRAP: (libc)Program Error Signals.
|
* SIGTSTP: (libc)Job Control Signals.
|
* SIGTTIN: (libc)Job Control Signals.
|
* SIGTTOU: (libc)Job Control Signals.
|
* SIGURG: (libc)Asynchronous I/O Signals.
|
* SIGUSR1: (libc)Miscellaneous Signals.
|
* SIGUSR2: (libc)Miscellaneous Signals.
|
* SIGVTALRM: (libc)Alarm Signals.
|
* SIGWINCH: (libc)Miscellaneous Signals.
|
* SIGXCPU: (libc)Operation Error Signals.
|
* SIGXFSZ: (libc)Operation Error Signals.
|
* SIG_ERR: (libc)Basic Signal Handling.
|
* SNAN: (libc)Infinity and NaN.
|
* SNANF: (libc)Infinity and NaN.
|
* SNANFN: (libc)Infinity and NaN.
|
* SNANFNx: (libc)Infinity and NaN.
|
* SNANL: (libc)Infinity and NaN.
|
* SOCK_DGRAM: (libc)Communication Styles.
|
* SOCK_RAW: (libc)Communication Styles.
|
* SOCK_RDM: (libc)Communication Styles.
|
* SOCK_SEQPACKET: (libc)Communication Styles.
|
* SOCK_STREAM: (libc)Communication Styles.
|
* SOL_SOCKET: (libc)Socket-Level Options.
|
* SSIZE_MAX: (libc)General Limits.
|
* STREAM_MAX: (libc)General Limits.
|
* SUN_LEN: (libc)Local Namespace Details.
|
* S_IFMT: (libc)Testing File Type.
|
* S_ISBLK: (libc)Testing File Type.
|
* S_ISCHR: (libc)Testing File Type.
|
* S_ISDIR: (libc)Testing File Type.
|
* S_ISFIFO: (libc)Testing File Type.
|
* S_ISLNK: (libc)Testing File Type.
|
* S_ISREG: (libc)Testing File Type.
|
* S_ISSOCK: (libc)Testing File Type.
|
* S_TYPEISMQ: (libc)Testing File Type.
|
* S_TYPEISSEM: (libc)Testing File Type.
|
* S_TYPEISSHM: (libc)Testing File Type.
|
* TMP_MAX: (libc)Temporary Files.
|
* TOSTOP: (libc)Local Modes.
|
* TZNAME_MAX: (libc)General Limits.
|
* VDISCARD: (libc)Other Special.
|
* VDSUSP: (libc)Signal Characters.
|
* VEOF: (libc)Editing Characters.
|
* VEOL2: (libc)Editing Characters.
|
* VEOL: (libc)Editing Characters.
|
* VERASE: (libc)Editing Characters.
|
* VINTR: (libc)Signal Characters.
|
* VKILL: (libc)Editing Characters.
|
* VLNEXT: (libc)Other Special.
|
* VMIN: (libc)Noncanonical Input.
|
* VQUIT: (libc)Signal Characters.
|
* VREPRINT: (libc)Editing Characters.
|
* VSTART: (libc)Start/Stop Characters.
|
* VSTATUS: (libc)Other Special.
|
* VSTOP: (libc)Start/Stop Characters.
|
* VSUSP: (libc)Signal Characters.
|
* VTIME: (libc)Noncanonical Input.
|
* VWERASE: (libc)Editing Characters.
|
* WCHAR_MAX: (libc)Extended Char Intro.
|
* WCHAR_MIN: (libc)Extended Char Intro.
|
* WCOREDUMP: (libc)Process Completion Status.
|
* WEOF: (libc)EOF and Errors.
|
* WEOF: (libc)Extended Char Intro.
|
* WEXITSTATUS: (libc)Process Completion Status.
|
* WIFEXITED: (libc)Process Completion Status.
|
* WIFSIGNALED: (libc)Process Completion Status.
|
* WIFSTOPPED: (libc)Process Completion Status.
|
* WSTOPSIG: (libc)Process Completion Status.
|
* WTERMSIG: (libc)Process Completion Status.
|
* W_OK: (libc)Testing File Access.
|
* X_OK: (libc)Testing File Access.
|
* _Complex_I: (libc)Complex Numbers.
|
* _Exit: (libc)Termination Internals.
|
* _IOFBF: (libc)Controlling Buffering.
|
* _IOLBF: (libc)Controlling Buffering.
|
* _IONBF: (libc)Controlling Buffering.
|
* _Imaginary_I: (libc)Complex Numbers.
|
* _PATH_UTMP: (libc)Manipulating the Database.
|
* _PATH_WTMP: (libc)Manipulating the Database.
|
* _POSIX2_C_DEV: (libc)System Options.
|
* _POSIX2_C_VERSION: (libc)Version Supported.
|
* _POSIX2_FORT_DEV: (libc)System Options.
|
* _POSIX2_FORT_RUN: (libc)System Options.
|
* _POSIX2_LOCALEDEF: (libc)System Options.
|
* _POSIX2_SW_DEV: (libc)System Options.
|
* _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
|
* _POSIX_JOB_CONTROL: (libc)System Options.
|
* _POSIX_NO_TRUNC: (libc)Options for Files.
|
* _POSIX_SAVED_IDS: (libc)System Options.
|
* _POSIX_VDISABLE: (libc)Options for Files.
|
* _POSIX_VERSION: (libc)Version Supported.
|
* __fbufsize: (libc)Controlling Buffering.
|
* __flbf: (libc)Controlling Buffering.
|
* __fpending: (libc)Controlling Buffering.
|
* __fpurge: (libc)Flushing Buffers.
|
* __freadable: (libc)Opening Streams.
|
* __freading: (libc)Opening Streams.
|
* __fsetlocking: (libc)Streams and Threads.
|
* __fwritable: (libc)Opening Streams.
|
* __fwriting: (libc)Opening Streams.
|
* __gconv_end_fct: (libc)glibc iconv Implementation.
|
* __gconv_fct: (libc)glibc iconv Implementation.
|
* __gconv_init_fct: (libc)glibc iconv Implementation.
|
* __ppc_get_timebase: (libc)PowerPC.
|
* __ppc_get_timebase_freq: (libc)PowerPC.
|
* __ppc_mdoio: (libc)PowerPC.
|
* __ppc_mdoom: (libc)PowerPC.
|
* __ppc_set_ppr_low: (libc)PowerPC.
|
* __ppc_set_ppr_med: (libc)PowerPC.
|
* __ppc_set_ppr_med_high: (libc)PowerPC.
|
* __ppc_set_ppr_med_low: (libc)PowerPC.
|
* __ppc_set_ppr_very_low: (libc)PowerPC.
|
* __ppc_yield: (libc)PowerPC.
|
* __riscv_flush_icache: (libc)RISC-V.
|
* __va_copy: (libc)Argument Macros.
|
* __x86_get_cpuid_feature_leaf: (libc)X86.
|
* _exit: (libc)Termination Internals.
|
* _flushlbf: (libc)Flushing Buffers.
|
* _tolower: (libc)Case Conversion.
|
* _toupper: (libc)Case Conversion.
|
* a64l: (libc)Encode Binary Data.
|
* abort: (libc)Aborting a Program.
|
* abs: (libc)Absolute Value.
|
* accept: (libc)Accepting Connections.
|
* access: (libc)Testing File Access.
|
* acos: (libc)Inverse Trig Functions.
|
* acosf: (libc)Inverse Trig Functions.
|
* acosfN: (libc)Inverse Trig Functions.
|
* acosfNx: (libc)Inverse Trig Functions.
|
* acosh: (libc)Hyperbolic Functions.
|
* acoshf: (libc)Hyperbolic Functions.
|
* acoshfN: (libc)Hyperbolic Functions.
|
* acoshfNx: (libc)Hyperbolic Functions.
|
* acoshl: (libc)Hyperbolic Functions.
|
* acosl: (libc)Inverse Trig Functions.
|
* addmntent: (libc)mtab.
|
* addseverity: (libc)Adding Severity Classes.
|
* adjtime: (libc)Setting and Adjusting the Time.
|
* adjtimex: (libc)Setting and Adjusting the Time.
|
* aio_cancel64: (libc)Cancel AIO Operations.
|
* aio_cancel: (libc)Cancel AIO Operations.
|
* aio_error64: (libc)Status of AIO Operations.
|
* aio_error: (libc)Status of AIO Operations.
|
* aio_fsync64: (libc)Synchronizing AIO Operations.
|
* aio_fsync: (libc)Synchronizing AIO Operations.
|
* aio_init: (libc)Configuration of AIO.
|
* aio_read64: (libc)Asynchronous Reads/Writes.
|
* aio_read: (libc)Asynchronous Reads/Writes.
|
* aio_return64: (libc)Status of AIO Operations.
|
* aio_return: (libc)Status of AIO Operations.
|
* aio_suspend64: (libc)Synchronizing AIO Operations.
|
* aio_suspend: (libc)Synchronizing AIO Operations.
|
* aio_write64: (libc)Asynchronous Reads/Writes.
|
* aio_write: (libc)Asynchronous Reads/Writes.
|
* alarm: (libc)Setting an Alarm.
|
* aligned_alloc: (libc)Aligned Memory Blocks.
|
* alloca: (libc)Variable Size Automatic.
|
* alphasort64: (libc)Scanning Directory Content.
|
* alphasort: (libc)Scanning Directory Content.
|
* argp_error: (libc)Argp Helper Functions.
|
* argp_failure: (libc)Argp Helper Functions.
|
* argp_help: (libc)Argp Help.
|
* argp_parse: (libc)Argp.
|
* argp_state_help: (libc)Argp Helper Functions.
|
* argp_usage: (libc)Argp Helper Functions.
|
* argz_add: (libc)Argz Functions.
|
* argz_add_sep: (libc)Argz Functions.
|
* argz_append: (libc)Argz Functions.
|
* argz_count: (libc)Argz Functions.
|
* argz_create: (libc)Argz Functions.
|
* argz_create_sep: (libc)Argz Functions.
|
* argz_delete: (libc)Argz Functions.
|
* argz_extract: (libc)Argz Functions.
|
* argz_insert: (libc)Argz Functions.
|
* argz_next: (libc)Argz Functions.
|
* argz_replace: (libc)Argz Functions.
|
* argz_stringify: (libc)Argz Functions.
|
* asctime: (libc)Formatting Calendar Time.
|
* asctime_r: (libc)Formatting Calendar Time.
|
* asin: (libc)Inverse Trig Functions.
|
* asinf: (libc)Inverse Trig Functions.
|
* asinfN: (libc)Inverse Trig Functions.
|
* asinfNx: (libc)Inverse Trig Functions.
|
* asinh: (libc)Hyperbolic Functions.
|
* asinhf: (libc)Hyperbolic Functions.
|
* asinhfN: (libc)Hyperbolic Functions.
|
* asinhfNx: (libc)Hyperbolic Functions.
|
* asinhl: (libc)Hyperbolic Functions.
|
* asinl: (libc)Inverse Trig Functions.
|
* asprintf: (libc)Dynamic Output.
|
* assert: (libc)Consistency Checking.
|
* assert_perror: (libc)Consistency Checking.
|
* atan2: (libc)Inverse Trig Functions.
|
* atan2f: (libc)Inverse Trig Functions.
|
* atan2fN: (libc)Inverse Trig Functions.
|
* atan2fNx: (libc)Inverse Trig Functions.
|
* atan2l: (libc)Inverse Trig Functions.
|
* atan: (libc)Inverse Trig Functions.
|
* atanf: (libc)Inverse Trig Functions.
|
* atanfN: (libc)Inverse Trig Functions.
|
* atanfNx: (libc)Inverse Trig Functions.
|
* atanh: (libc)Hyperbolic Functions.
|
* atanhf: (libc)Hyperbolic Functions.
|
* atanhfN: (libc)Hyperbolic Functions.
|
* atanhfNx: (libc)Hyperbolic Functions.
|
* atanhl: (libc)Hyperbolic Functions.
|
* atanl: (libc)Inverse Trig Functions.
|
* atexit: (libc)Cleanups on Exit.
|
* atof: (libc)Parsing of Floats.
|
* atoi: (libc)Parsing of Integers.
|
* atol: (libc)Parsing of Integers.
|
* atoll: (libc)Parsing of Integers.
|
* backtrace: (libc)Backtraces.
|
* backtrace_symbols: (libc)Backtraces.
|
* backtrace_symbols_fd: (libc)Backtraces.
|
* basename: (libc)Finding Tokens in a String.
|
* basename: (libc)Finding Tokens in a String.
|
* bcmp: (libc)String/Array Comparison.
|
* bcopy: (libc)Copying Strings and Arrays.
|
* bind: (libc)Setting Address.
|
* bind_textdomain_codeset: (libc)Charset conversion in gettext.
|
* bindtextdomain: (libc)Locating gettext catalog.
|
* brk: (libc)Resizing the Data Segment.
|
* bsearch: (libc)Array Search Function.
|
* btowc: (libc)Converting a Character.
|
* bzero: (libc)Copying Strings and Arrays.
|
* cabs: (libc)Absolute Value.
|
* cabsf: (libc)Absolute Value.
|
* cabsfN: (libc)Absolute Value.
|
* cabsfNx: (libc)Absolute Value.
|
* cabsl: (libc)Absolute Value.
|
* cacos: (libc)Inverse Trig Functions.
|
* cacosf: (libc)Inverse Trig Functions.
|
* cacosfN: (libc)Inverse Trig Functions.
|
* cacosfNx: (libc)Inverse Trig Functions.
|
* cacosh: (libc)Hyperbolic Functions.
|
* cacoshf: (libc)Hyperbolic Functions.
|
* cacoshfN: (libc)Hyperbolic Functions.
|
* cacoshfNx: (libc)Hyperbolic Functions.
|
* cacoshl: (libc)Hyperbolic Functions.
|
* cacosl: (libc)Inverse Trig Functions.
|
* call_once: (libc)Call Once.
|
* calloc: (libc)Allocating Cleared Space.
|
* canonicalize: (libc)FP Bit Twiddling.
|
* canonicalize_file_name: (libc)Symbolic Links.
|
* canonicalizef: (libc)FP Bit Twiddling.
|
* canonicalizefN: (libc)FP Bit Twiddling.
|
* canonicalizefNx: (libc)FP Bit Twiddling.
|
* canonicalizel: (libc)FP Bit Twiddling.
|
* carg: (libc)Operations on Complex.
|
* cargf: (libc)Operations on Complex.
|
* cargfN: (libc)Operations on Complex.
|
* cargfNx: (libc)Operations on Complex.
|
* cargl: (libc)Operations on Complex.
|
* casin: (libc)Inverse Trig Functions.
|
* casinf: (libc)Inverse Trig Functions.
|
* casinfN: (libc)Inverse Trig Functions.
|
* casinfNx: (libc)Inverse Trig Functions.
|
* casinh: (libc)Hyperbolic Functions.
|
* casinhf: (libc)Hyperbolic Functions.
|
* casinhfN: (libc)Hyperbolic Functions.
|
* casinhfNx: (libc)Hyperbolic Functions.
|
* casinhl: (libc)Hyperbolic Functions.
|
* casinl: (libc)Inverse Trig Functions.
|
* catan: (libc)Inverse Trig Functions.
|
* catanf: (libc)Inverse Trig Functions.
|
* catanfN: (libc)Inverse Trig Functions.
|
* catanfNx: (libc)Inverse Trig Functions.
|
* catanh: (libc)Hyperbolic Functions.
|
* catanhf: (libc)Hyperbolic Functions.
|
* catanhfN: (libc)Hyperbolic Functions.
|
* catanhfNx: (libc)Hyperbolic Functions.
|
* catanhl: (libc)Hyperbolic Functions.
|
* catanl: (libc)Inverse Trig Functions.
|
* catclose: (libc)The catgets Functions.
|
* catgets: (libc)The catgets Functions.
|
* catopen: (libc)The catgets Functions.
|
* cbrt: (libc)Exponents and Logarithms.
|
* cbrtf: (libc)Exponents and Logarithms.
|
* cbrtfN: (libc)Exponents and Logarithms.
|
* cbrtfNx: (libc)Exponents and Logarithms.
|
* cbrtl: (libc)Exponents and Logarithms.
|
* ccos: (libc)Trig Functions.
|
* ccosf: (libc)Trig Functions.
|
* ccosfN: (libc)Trig Functions.
|
* ccosfNx: (libc)Trig Functions.
|
* ccosh: (libc)Hyperbolic Functions.
|
* ccoshf: (libc)Hyperbolic Functions.
|
* ccoshfN: (libc)Hyperbolic Functions.
|
* ccoshfNx: (libc)Hyperbolic Functions.
|
* ccoshl: (libc)Hyperbolic Functions.
|
* ccosl: (libc)Trig Functions.
|
* ceil: (libc)Rounding Functions.
|
* ceilf: (libc)Rounding Functions.
|
* ceilfN: (libc)Rounding Functions.
|
* ceilfNx: (libc)Rounding Functions.
|
* ceill: (libc)Rounding Functions.
|
* cexp: (libc)Exponents and Logarithms.
|
* cexpf: (libc)Exponents and Logarithms.
|
* cexpfN: (libc)Exponents and Logarithms.
|
* cexpfNx: (libc)Exponents and Logarithms.
|
* cexpl: (libc)Exponents and Logarithms.
|
* cfgetispeed: (libc)Line Speed.
|
* cfgetospeed: (libc)Line Speed.
|
* cfmakeraw: (libc)Noncanonical Input.
|
* cfsetispeed: (libc)Line Speed.
|
* cfsetospeed: (libc)Line Speed.
|
* cfsetspeed: (libc)Line Speed.
|
* chdir: (libc)Working Directory.
|
* chmod: (libc)Setting Permissions.
|
* chown: (libc)File Owner.
|
* cimag: (libc)Operations on Complex.
|
* cimagf: (libc)Operations on Complex.
|
* cimagfN: (libc)Operations on Complex.
|
* cimagfNx: (libc)Operations on Complex.
|
* cimagl: (libc)Operations on Complex.
|
* clearenv: (libc)Environment Access.
|
* clearerr: (libc)Error Recovery.
|
* clearerr_unlocked: (libc)Error Recovery.
|
* clock: (libc)CPU Time.
|
* clock_getres: (libc)Getting the Time.
|
* clock_gettime: (libc)Getting the Time.
|
* clock_settime: (libc)Setting and Adjusting the Time.
|
* clog10: (libc)Exponents and Logarithms.
|
* clog10f: (libc)Exponents and Logarithms.
|
* clog10fN: (libc)Exponents and Logarithms.
|
* clog10fNx: (libc)Exponents and Logarithms.
|
* clog10l: (libc)Exponents and Logarithms.
|
* clog: (libc)Exponents and Logarithms.
|
* clogf: (libc)Exponents and Logarithms.
|
* clogfN: (libc)Exponents and Logarithms.
|
* clogfNx: (libc)Exponents and Logarithms.
|
* clogl: (libc)Exponents and Logarithms.
|
* close: (libc)Opening and Closing Files.
|
* closedir: (libc)Reading/Closing Directory.
|
* closelog: (libc)closelog.
|
* cnd_broadcast: (libc)ISO C Condition Variables.
|
* cnd_destroy: (libc)ISO C Condition Variables.
|
* cnd_init: (libc)ISO C Condition Variables.
|
* cnd_signal: (libc)ISO C Condition Variables.
|
* cnd_timedwait: (libc)ISO C Condition Variables.
|
* cnd_wait: (libc)ISO C Condition Variables.
|
* confstr: (libc)String Parameters.
|
* conj: (libc)Operations on Complex.
|
* conjf: (libc)Operations on Complex.
|
* conjfN: (libc)Operations on Complex.
|
* conjfNx: (libc)Operations on Complex.
|
* conjl: (libc)Operations on Complex.
|
* connect: (libc)Connecting.
|
* copy_file_range: (libc)Copying File Data.
|
* copysign: (libc)FP Bit Twiddling.
|
* copysignf: (libc)FP Bit Twiddling.
|
* copysignfN: (libc)FP Bit Twiddling.
|
* copysignfNx: (libc)FP Bit Twiddling.
|
* copysignl: (libc)FP Bit Twiddling.
|
* cos: (libc)Trig Functions.
|
* cosf: (libc)Trig Functions.
|
* cosfN: (libc)Trig Functions.
|
* cosfNx: (libc)Trig Functions.
|
* cosh: (libc)Hyperbolic Functions.
|
* coshf: (libc)Hyperbolic Functions.
|
* coshfN: (libc)Hyperbolic Functions.
|
* coshfNx: (libc)Hyperbolic Functions.
|
* coshl: (libc)Hyperbolic Functions.
|
* cosl: (libc)Trig Functions.
|
* cpow: (libc)Exponents and Logarithms.
|
* cpowf: (libc)Exponents and Logarithms.
|
* cpowfN: (libc)Exponents and Logarithms.
|
* cpowfNx: (libc)Exponents and Logarithms.
|
* cpowl: (libc)Exponents and Logarithms.
|
* cproj: (libc)Operations on Complex.
|
* cprojf: (libc)Operations on Complex.
|
* cprojfN: (libc)Operations on Complex.
|
* cprojfNx: (libc)Operations on Complex.
|
* cprojl: (libc)Operations on Complex.
|
* creal: (libc)Operations on Complex.
|
* crealf: (libc)Operations on Complex.
|
* crealfN: (libc)Operations on Complex.
|
* crealfNx: (libc)Operations on Complex.
|
* creall: (libc)Operations on Complex.
|
* creat64: (libc)Opening and Closing Files.
|
* creat: (libc)Opening and Closing Files.
|
* crypt: (libc)Passphrase Storage.
|
* crypt_r: (libc)Passphrase Storage.
|
* csin: (libc)Trig Functions.
|
* csinf: (libc)Trig Functions.
|
* csinfN: (libc)Trig Functions.
|
* csinfNx: (libc)Trig Functions.
|
* csinh: (libc)Hyperbolic Functions.
|
* csinhf: (libc)Hyperbolic Functions.
|
* csinhfN: (libc)Hyperbolic Functions.
|
* csinhfNx: (libc)Hyperbolic Functions.
|
* csinhl: (libc)Hyperbolic Functions.
|
* csinl: (libc)Trig Functions.
|
* csqrt: (libc)Exponents and Logarithms.
|
* csqrtf: (libc)Exponents and Logarithms.
|
* csqrtfN: (libc)Exponents and Logarithms.
|
* csqrtfNx: (libc)Exponents and Logarithms.
|
* csqrtl: (libc)Exponents and Logarithms.
|
* ctan: (libc)Trig Functions.
|
* ctanf: (libc)Trig Functions.
|
* ctanfN: (libc)Trig Functions.
|
* ctanfNx: (libc)Trig Functions.
|
* ctanh: (libc)Hyperbolic Functions.
|
* ctanhf: (libc)Hyperbolic Functions.
|
* ctanhfN: (libc)Hyperbolic Functions.
|
* ctanhfNx: (libc)Hyperbolic Functions.
|
* ctanhl: (libc)Hyperbolic Functions.
|
* ctanl: (libc)Trig Functions.
|
* ctermid: (libc)Identifying the Terminal.
|
* ctime: (libc)Formatting Calendar Time.
|
* ctime_r: (libc)Formatting Calendar Time.
|
* cuserid: (libc)Who Logged In.
|
* daddl: (libc)Misc FP Arithmetic.
|
* dcgettext: (libc)Translation with gettext.
|
* dcngettext: (libc)Advanced gettext functions.
|
* ddivl: (libc)Misc FP Arithmetic.
|
* dgettext: (libc)Translation with gettext.
|
* difftime: (libc)Calculating Elapsed Time.
|
* dirfd: (libc)Opening a Directory.
|
* dirname: (libc)Finding Tokens in a String.
|
* div: (libc)Integer Division.
|
* dmull: (libc)Misc FP Arithmetic.
|
* dngettext: (libc)Advanced gettext functions.
|
* drand48: (libc)SVID Random.
|
* drand48_r: (libc)SVID Random.
|
* drem: (libc)Remainder Functions.
|
* dremf: (libc)Remainder Functions.
|
* dreml: (libc)Remainder Functions.
|
* dsubl: (libc)Misc FP Arithmetic.
|
* dup2: (libc)Duplicating Descriptors.
|
* dup: (libc)Duplicating Descriptors.
|
* ecvt: (libc)System V Number Conversion.
|
* ecvt_r: (libc)System V Number Conversion.
|
* endfsent: (libc)fstab.
|
* endgrent: (libc)Scanning All Groups.
|
* endhostent: (libc)Host Names.
|
* endmntent: (libc)mtab.
|
* endnetent: (libc)Networks Database.
|
* endnetgrent: (libc)Lookup Netgroup.
|
* endprotoent: (libc)Protocols Database.
|
* endpwent: (libc)Scanning All Users.
|
* endservent: (libc)Services Database.
|
* endutent: (libc)Manipulating the Database.
|
* endutxent: (libc)XPG Functions.
|
* envz_add: (libc)Envz Functions.
|
* envz_entry: (libc)Envz Functions.
|
* envz_get: (libc)Envz Functions.
|
* envz_merge: (libc)Envz Functions.
|
* envz_remove: (libc)Envz Functions.
|
* envz_strip: (libc)Envz Functions.
|
* erand48: (libc)SVID Random.
|
* erand48_r: (libc)SVID Random.
|
* erf: (libc)Special Functions.
|
* erfc: (libc)Special Functions.
|
* erfcf: (libc)Special Functions.
|
* erfcfN: (libc)Special Functions.
|
* erfcfNx: (libc)Special Functions.
|
* erfcl: (libc)Special Functions.
|
* erff: (libc)Special Functions.
|
* erffN: (libc)Special Functions.
|
* erffNx: (libc)Special Functions.
|
* erfl: (libc)Special Functions.
|
* err: (libc)Error Messages.
|
* errno: (libc)Checking for Errors.
|
* error: (libc)Error Messages.
|
* error_at_line: (libc)Error Messages.
|
* errx: (libc)Error Messages.
|
* execl: (libc)Executing a File.
|
* execle: (libc)Executing a File.
|
* execlp: (libc)Executing a File.
|
* execv: (libc)Executing a File.
|
* execve: (libc)Executing a File.
|
* execvp: (libc)Executing a File.
|
* exit: (libc)Normal Termination.
|
* exp10: (libc)Exponents and Logarithms.
|
* exp10f: (libc)Exponents and Logarithms.
|
* exp10fN: (libc)Exponents and Logarithms.
|
* exp10fNx: (libc)Exponents and Logarithms.
|
* exp10l: (libc)Exponents and Logarithms.
|
* exp2: (libc)Exponents and Logarithms.
|
* exp2f: (libc)Exponents and Logarithms.
|
* exp2fN: (libc)Exponents and Logarithms.
|
* exp2fNx: (libc)Exponents and Logarithms.
|
* exp2l: (libc)Exponents and Logarithms.
|
* exp: (libc)Exponents and Logarithms.
|
* expf: (libc)Exponents and Logarithms.
|
* expfN: (libc)Exponents and Logarithms.
|
* expfNx: (libc)Exponents and Logarithms.
|
* expl: (libc)Exponents and Logarithms.
|
* explicit_bzero: (libc)Erasing Sensitive Data.
|
* expm1: (libc)Exponents and Logarithms.
|
* expm1f: (libc)Exponents and Logarithms.
|
* expm1fN: (libc)Exponents and Logarithms.
|
* expm1fNx: (libc)Exponents and Logarithms.
|
* expm1l: (libc)Exponents and Logarithms.
|
* fMaddfN: (libc)Misc FP Arithmetic.
|
* fMaddfNx: (libc)Misc FP Arithmetic.
|
* fMdivfN: (libc)Misc FP Arithmetic.
|
* fMdivfNx: (libc)Misc FP Arithmetic.
|
* fMmulfN: (libc)Misc FP Arithmetic.
|
* fMmulfNx: (libc)Misc FP Arithmetic.
|
* fMsubfN: (libc)Misc FP Arithmetic.
|
* fMsubfNx: (libc)Misc FP Arithmetic.
|
* fMxaddfN: (libc)Misc FP Arithmetic.
|
* fMxaddfNx: (libc)Misc FP Arithmetic.
|
* fMxdivfN: (libc)Misc FP Arithmetic.
|
* fMxdivfNx: (libc)Misc FP Arithmetic.
|
* fMxmulfN: (libc)Misc FP Arithmetic.
|
* fMxmulfNx: (libc)Misc FP Arithmetic.
|
* fMxsubfN: (libc)Misc FP Arithmetic.
|
* fMxsubfNx: (libc)Misc FP Arithmetic.
|
* fabs: (libc)Absolute Value.
|
* fabsf: (libc)Absolute Value.
|
* fabsfN: (libc)Absolute Value.
|
* fabsfNx: (libc)Absolute Value.
|
* fabsl: (libc)Absolute Value.
|
* fadd: (libc)Misc FP Arithmetic.
|
* faddl: (libc)Misc FP Arithmetic.
|
* fchdir: (libc)Working Directory.
|
* fchmod: (libc)Setting Permissions.
|
* fchown: (libc)File Owner.
|
* fclose: (libc)Closing Streams.
|
* fcloseall: (libc)Closing Streams.
|
* fcntl: (libc)Control Operations.
|
* fcvt: (libc)System V Number Conversion.
|
* fcvt_r: (libc)System V Number Conversion.
|
* fdatasync: (libc)Synchronizing I/O.
|
* fdim: (libc)Misc FP Arithmetic.
|
* fdimf: (libc)Misc FP Arithmetic.
|
* fdimfN: (libc)Misc FP Arithmetic.
|
* fdimfNx: (libc)Misc FP Arithmetic.
|
* fdiml: (libc)Misc FP Arithmetic.
|
* fdiv: (libc)Misc FP Arithmetic.
|
* fdivl: (libc)Misc FP Arithmetic.
|
* fdopen: (libc)Descriptors and Streams.
|
* fdopendir: (libc)Opening a Directory.
|
* feclearexcept: (libc)Status bit operations.
|
* fedisableexcept: (libc)Control Functions.
|
* feenableexcept: (libc)Control Functions.
|
* fegetenv: (libc)Control Functions.
|
* fegetexcept: (libc)Control Functions.
|
* fegetexceptflag: (libc)Status bit operations.
|
* fegetmode: (libc)Control Functions.
|
* fegetround: (libc)Rounding.
|
* feholdexcept: (libc)Control Functions.
|
* feof: (libc)EOF and Errors.
|
* feof_unlocked: (libc)EOF and Errors.
|
* feraiseexcept: (libc)Status bit operations.
|
* ferror: (libc)EOF and Errors.
|
* ferror_unlocked: (libc)EOF and Errors.
|
* fesetenv: (libc)Control Functions.
|
* fesetexcept: (libc)Status bit operations.
|
* fesetexceptflag: (libc)Status bit operations.
|
* fesetmode: (libc)Control Functions.
|
* fesetround: (libc)Rounding.
|
* fetestexcept: (libc)Status bit operations.
|
* fetestexceptflag: (libc)Status bit operations.
|
* feupdateenv: (libc)Control Functions.
|
* fexecve: (libc)Executing a File.
|
* fflush: (libc)Flushing Buffers.
|
* fflush_unlocked: (libc)Flushing Buffers.
|
* fgetc: (libc)Character Input.
|
* fgetc_unlocked: (libc)Character Input.
|
* fgetgrent: (libc)Scanning All Groups.
|
* fgetgrent_r: (libc)Scanning All Groups.
|
* fgetpos64: (libc)Portable Positioning.
|
* fgetpos: (libc)Portable Positioning.
|
* fgetpwent: (libc)Scanning All Users.
|
* fgetpwent_r: (libc)Scanning All Users.
|
* fgets: (libc)Line Input.
|
* fgets_unlocked: (libc)Line Input.
|
* fgetwc: (libc)Character Input.
|
* fgetwc_unlocked: (libc)Character Input.
|
* fgetws: (libc)Line Input.
|
* fgetws_unlocked: (libc)Line Input.
|
* fileno: (libc)Descriptors and Streams.
|
* fileno_unlocked: (libc)Descriptors and Streams.
|
* finite: (libc)Floating Point Classes.
|
* finitef: (libc)Floating Point Classes.
|
* finitel: (libc)Floating Point Classes.
|
* flockfile: (libc)Streams and Threads.
|
* floor: (libc)Rounding Functions.
|
* floorf: (libc)Rounding Functions.
|
* floorfN: (libc)Rounding Functions.
|
* floorfNx: (libc)Rounding Functions.
|
* floorl: (libc)Rounding Functions.
|
* fma: (libc)Misc FP Arithmetic.
|
* fmaf: (libc)Misc FP Arithmetic.
|
* fmafN: (libc)Misc FP Arithmetic.
|
* fmafNx: (libc)Misc FP Arithmetic.
|
* fmal: (libc)Misc FP Arithmetic.
|
* fmax: (libc)Misc FP Arithmetic.
|
* fmaxf: (libc)Misc FP Arithmetic.
|
* fmaxfN: (libc)Misc FP Arithmetic.
|
* fmaxfNx: (libc)Misc FP Arithmetic.
|
* fmaxl: (libc)Misc FP Arithmetic.
|
* fmaxmag: (libc)Misc FP Arithmetic.
|
* fmaxmagf: (libc)Misc FP Arithmetic.
|
* fmaxmagfN: (libc)Misc FP Arithmetic.
|
* fmaxmagfNx: (libc)Misc FP Arithmetic.
|
* fmaxmagl: (libc)Misc FP Arithmetic.
|
* fmemopen: (libc)String Streams.
|
* fmin: (libc)Misc FP Arithmetic.
|
* fminf: (libc)Misc FP Arithmetic.
|
* fminfN: (libc)Misc FP Arithmetic.
|
* fminfNx: (libc)Misc FP Arithmetic.
|
* fminl: (libc)Misc FP Arithmetic.
|
* fminmag: (libc)Misc FP Arithmetic.
|
* fminmagf: (libc)Misc FP Arithmetic.
|
* fminmagfN: (libc)Misc FP Arithmetic.
|
* fminmagfNx: (libc)Misc FP Arithmetic.
|
* fminmagl: (libc)Misc FP Arithmetic.
|
* fmod: (libc)Remainder Functions.
|
* fmodf: (libc)Remainder Functions.
|
* fmodfN: (libc)Remainder Functions.
|
* fmodfNx: (libc)Remainder Functions.
|
* fmodl: (libc)Remainder Functions.
|
* fmtmsg: (libc)Printing Formatted Messages.
|
* fmul: (libc)Misc FP Arithmetic.
|
* fmull: (libc)Misc FP Arithmetic.
|
* fnmatch: (libc)Wildcard Matching.
|
* fopen64: (libc)Opening Streams.
|
* fopen: (libc)Opening Streams.
|
* fopencookie: (libc)Streams and Cookies.
|
* fork: (libc)Creating a Process.
|
* forkpty: (libc)Pseudo-Terminal Pairs.
|
* fpathconf: (libc)Pathconf.
|
* fpclassify: (libc)Floating Point Classes.
|
* fprintf: (libc)Formatted Output Functions.
|
* fputc: (libc)Simple Output.
|
* fputc_unlocked: (libc)Simple Output.
|
* fputs: (libc)Simple Output.
|
* fputs_unlocked: (libc)Simple Output.
|
* fputwc: (libc)Simple Output.
|
* fputwc_unlocked: (libc)Simple Output.
|
* fputws: (libc)Simple Output.
|
* fputws_unlocked: (libc)Simple Output.
|
* fread: (libc)Block Input/Output.
|
* fread_unlocked: (libc)Block Input/Output.
|
* free: (libc)Freeing after Malloc.
|
* freopen64: (libc)Opening Streams.
|
* freopen: (libc)Opening Streams.
|
* frexp: (libc)Normalization Functions.
|
* frexpf: (libc)Normalization Functions.
|
* frexpfN: (libc)Normalization Functions.
|
* frexpfNx: (libc)Normalization Functions.
|
* frexpl: (libc)Normalization Functions.
|
* fromfp: (libc)Rounding Functions.
|
* fromfpf: (libc)Rounding Functions.
|
* fromfpfN: (libc)Rounding Functions.
|
* fromfpfNx: (libc)Rounding Functions.
|
* fromfpl: (libc)Rounding Functions.
|
* fromfpx: (libc)Rounding Functions.
|
* fromfpxf: (libc)Rounding Functions.
|
* fromfpxfN: (libc)Rounding Functions.
|
* fromfpxfNx: (libc)Rounding Functions.
|
* fromfpxl: (libc)Rounding Functions.
|
* fscanf: (libc)Formatted Input Functions.
|
* fseek: (libc)File Positioning.
|
* fseeko64: (libc)File Positioning.
|
* fseeko: (libc)File Positioning.
|
* fsetpos64: (libc)Portable Positioning.
|
* fsetpos: (libc)Portable Positioning.
|
* fstat64: (libc)Reading Attributes.
|
* fstat: (libc)Reading Attributes.
|
* fsub: (libc)Misc FP Arithmetic.
|
* fsubl: (libc)Misc FP Arithmetic.
|
* fsync: (libc)Synchronizing I/O.
|
* ftell: (libc)File Positioning.
|
* ftello64: (libc)File Positioning.
|
* ftello: (libc)File Positioning.
|
* ftruncate64: (libc)File Size.
|
* ftruncate: (libc)File Size.
|
* ftrylockfile: (libc)Streams and Threads.
|
* ftw64: (libc)Working with Directory Trees.
|
* ftw: (libc)Working with Directory Trees.
|
* funlockfile: (libc)Streams and Threads.
|
* futimes: (libc)File Times.
|
* fwide: (libc)Streams and I18N.
|
* fwprintf: (libc)Formatted Output Functions.
|
* fwrite: (libc)Block Input/Output.
|
* fwrite_unlocked: (libc)Block Input/Output.
|
* fwscanf: (libc)Formatted Input Functions.
|
* gamma: (libc)Special Functions.
|
* gammaf: (libc)Special Functions.
|
* gammal: (libc)Special Functions.
|
* gcvt: (libc)System V Number Conversion.
|
* get_avphys_pages: (libc)Query Memory Parameters.
|
* get_current_dir_name: (libc)Working Directory.
|
* get_nprocs: (libc)Processor Resources.
|
* get_nprocs_conf: (libc)Processor Resources.
|
* get_phys_pages: (libc)Query Memory Parameters.
|
* getauxval: (libc)Auxiliary Vector.
|
* getc: (libc)Character Input.
|
* getc_unlocked: (libc)Character Input.
|
* getchar: (libc)Character Input.
|
* getchar_unlocked: (libc)Character Input.
|
* getcontext: (libc)System V contexts.
|
* getcpu: (libc)CPU Affinity.
|
* getcwd: (libc)Working Directory.
|
* getdate: (libc)General Time String Parsing.
|
* getdate_r: (libc)General Time String Parsing.
|
* getdelim: (libc)Line Input.
|
* getdents64: (libc)Low-level Directory Access.
|
* getdomainnname: (libc)Host Identification.
|
* getegid: (libc)Reading Persona.
|
* getentropy: (libc)Unpredictable Bytes.
|
* getenv: (libc)Environment Access.
|
* geteuid: (libc)Reading Persona.
|
* getfsent: (libc)fstab.
|
* getfsfile: (libc)fstab.
|
* getfsspec: (libc)fstab.
|
* getgid: (libc)Reading Persona.
|
* getgrent: (libc)Scanning All Groups.
|
* getgrent_r: (libc)Scanning All Groups.
|
* getgrgid: (libc)Lookup Group.
|
* getgrgid_r: (libc)Lookup Group.
|
* getgrnam: (libc)Lookup Group.
|
* getgrnam_r: (libc)Lookup Group.
|
* getgrouplist: (libc)Setting Groups.
|
* getgroups: (libc)Reading Persona.
|
* gethostbyaddr: (libc)Host Names.
|
* gethostbyaddr_r: (libc)Host Names.
|
* gethostbyname2: (libc)Host Names.
|
* gethostbyname2_r: (libc)Host Names.
|
* gethostbyname: (libc)Host Names.
|
* gethostbyname_r: (libc)Host Names.
|
* gethostent: (libc)Host Names.
|
* gethostid: (libc)Host Identification.
|
* gethostname: (libc)Host Identification.
|
* getitimer: (libc)Setting an Alarm.
|
* getline: (libc)Line Input.
|
* getloadavg: (libc)Processor Resources.
|
* getlogin: (libc)Who Logged In.
|
* getmntent: (libc)mtab.
|
* getmntent_r: (libc)mtab.
|
* getnetbyaddr: (libc)Networks Database.
|
* getnetbyname: (libc)Networks Database.
|
* getnetent: (libc)Networks Database.
|
* getnetgrent: (libc)Lookup Netgroup.
|
* getnetgrent_r: (libc)Lookup Netgroup.
|
* getopt: (libc)Using Getopt.
|
* getopt_long: (libc)Getopt Long Options.
|
* getopt_long_only: (libc)Getopt Long Options.
|
* getpagesize: (libc)Query Memory Parameters.
|
* getpass: (libc)getpass.
|
* getpayload: (libc)FP Bit Twiddling.
|
* getpayloadf: (libc)FP Bit Twiddling.
|
* getpayloadfN: (libc)FP Bit Twiddling.
|
* getpayloadfNx: (libc)FP Bit Twiddling.
|
* getpayloadl: (libc)FP Bit Twiddling.
|
* getpeername: (libc)Who is Connected.
|
* getpgid: (libc)Process Group Functions.
|
* getpgrp: (libc)Process Group Functions.
|
* getpid: (libc)Process Identification.
|
* getppid: (libc)Process Identification.
|
* getpriority: (libc)Traditional Scheduling Functions.
|
* getprotobyname: (libc)Protocols Database.
|
* getprotobynumber: (libc)Protocols Database.
|
* getprotoent: (libc)Protocols Database.
|
* getpt: (libc)Allocation.
|
* getpwent: (libc)Scanning All Users.
|
* getpwent_r: (libc)Scanning All Users.
|
* getpwnam: (libc)Lookup User.
|
* getpwnam_r: (libc)Lookup User.
|
* getpwuid: (libc)Lookup User.
|
* getpwuid_r: (libc)Lookup User.
|
* getrandom: (libc)Unpredictable Bytes.
|
* getrlimit64: (libc)Limits on Resources.
|
* getrlimit: (libc)Limits on Resources.
|
* getrusage: (libc)Resource Usage.
|
* gets: (libc)Line Input.
|
* getservbyname: (libc)Services Database.
|
* getservbyport: (libc)Services Database.
|
* getservent: (libc)Services Database.
|
* getsid: (libc)Process Group Functions.
|
* getsockname: (libc)Reading Address.
|
* getsockopt: (libc)Socket Option Functions.
|
* getsubopt: (libc)Suboptions.
|
* gettext: (libc)Translation with gettext.
|
* gettid: (libc)Process Identification.
|
* gettimeofday: (libc)Getting the Time.
|
* getuid: (libc)Reading Persona.
|
* getumask: (libc)Setting Permissions.
|
* getutent: (libc)Manipulating the Database.
|
* getutent_r: (libc)Manipulating the Database.
|
* getutid: (libc)Manipulating the Database.
|
* getutid_r: (libc)Manipulating the Database.
|
* getutline: (libc)Manipulating the Database.
|
* getutline_r: (libc)Manipulating the Database.
|
* getutmp: (libc)XPG Functions.
|
* getutmpx: (libc)XPG Functions.
|
* getutxent: (libc)XPG Functions.
|
* getutxid: (libc)XPG Functions.
|
* getutxline: (libc)XPG Functions.
|
* getw: (libc)Character Input.
|
* getwc: (libc)Character Input.
|
* getwc_unlocked: (libc)Character Input.
|
* getwchar: (libc)Character Input.
|
* getwchar_unlocked: (libc)Character Input.
|
* getwd: (libc)Working Directory.
|
* glob64: (libc)Calling Glob.
|
* glob: (libc)Calling Glob.
|
* globfree64: (libc)More Flags for Globbing.
|
* globfree: (libc)More Flags for Globbing.
|
* gmtime: (libc)Broken-down Time.
|
* gmtime_r: (libc)Broken-down Time.
|
* grantpt: (libc)Allocation.
|
* gsignal: (libc)Signaling Yourself.
|
* gtty: (libc)BSD Terminal Modes.
|
* hasmntopt: (libc)mtab.
|
* hcreate: (libc)Hash Search Function.
|
* hcreate_r: (libc)Hash Search Function.
|
* hdestroy: (libc)Hash Search Function.
|
* hdestroy_r: (libc)Hash Search Function.
|
* hsearch: (libc)Hash Search Function.
|
* hsearch_r: (libc)Hash Search Function.
|
* htonl: (libc)Byte Order.
|
* htons: (libc)Byte Order.
|
* hypot: (libc)Exponents and Logarithms.
|
* hypotf: (libc)Exponents and Logarithms.
|
* hypotfN: (libc)Exponents and Logarithms.
|
* hypotfNx: (libc)Exponents and Logarithms.
|
* hypotl: (libc)Exponents and Logarithms.
|
* iconv: (libc)Generic Conversion Interface.
|
* iconv_close: (libc)Generic Conversion Interface.
|
* iconv_open: (libc)Generic Conversion Interface.
|
* if_freenameindex: (libc)Interface Naming.
|
* if_indextoname: (libc)Interface Naming.
|
* if_nameindex: (libc)Interface Naming.
|
* if_nametoindex: (libc)Interface Naming.
|
* ilogb: (libc)Exponents and Logarithms.
|
* ilogbf: (libc)Exponents and Logarithms.
|
* ilogbfN: (libc)Exponents and Logarithms.
|
* ilogbfNx: (libc)Exponents and Logarithms.
|
* ilogbl: (libc)Exponents and Logarithms.
|
* imaxabs: (libc)Absolute Value.
|
* imaxdiv: (libc)Integer Division.
|
* in6addr_any: (libc)Host Address Data Type.
|
* in6addr_loopback: (libc)Host Address Data Type.
|
* index: (libc)Search Functions.
|
* inet_addr: (libc)Host Address Functions.
|
* inet_aton: (libc)Host Address Functions.
|
* inet_lnaof: (libc)Host Address Functions.
|
* inet_makeaddr: (libc)Host Address Functions.
|
* inet_netof: (libc)Host Address Functions.
|
* inet_network: (libc)Host Address Functions.
|
* inet_ntoa: (libc)Host Address Functions.
|
* inet_ntop: (libc)Host Address Functions.
|
* inet_pton: (libc)Host Address Functions.
|
* initgroups: (libc)Setting Groups.
|
* initstate: (libc)BSD Random.
|
* initstate_r: (libc)BSD Random.
|
* innetgr: (libc)Netgroup Membership.
|
* ioctl: (libc)IOCTLs.
|
* isalnum: (libc)Classification of Characters.
|
* isalpha: (libc)Classification of Characters.
|
* isascii: (libc)Classification of Characters.
|
* isatty: (libc)Is It a Terminal.
|
* isblank: (libc)Classification of Characters.
|
* iscanonical: (libc)Floating Point Classes.
|
* iscntrl: (libc)Classification of Characters.
|
* isdigit: (libc)Classification of Characters.
|
* iseqsig: (libc)FP Comparison Functions.
|
* isfinite: (libc)Floating Point Classes.
|
* isgraph: (libc)Classification of Characters.
|
* isgreater: (libc)FP Comparison Functions.
|
* isgreaterequal: (libc)FP Comparison Functions.
|
* isinf: (libc)Floating Point Classes.
|
* isinff: (libc)Floating Point Classes.
|
* isinfl: (libc)Floating Point Classes.
|
* isless: (libc)FP Comparison Functions.
|
* islessequal: (libc)FP Comparison Functions.
|
* islessgreater: (libc)FP Comparison Functions.
|
* islower: (libc)Classification of Characters.
|
* isnan: (libc)Floating Point Classes.
|
* isnan: (libc)Floating Point Classes.
|
* isnanf: (libc)Floating Point Classes.
|
* isnanl: (libc)Floating Point Classes.
|
* isnormal: (libc)Floating Point Classes.
|
* isprint: (libc)Classification of Characters.
|
* ispunct: (libc)Classification of Characters.
|
* issignaling: (libc)Floating Point Classes.
|
* isspace: (libc)Classification of Characters.
|
* issubnormal: (libc)Floating Point Classes.
|
* isunordered: (libc)FP Comparison Functions.
|
* isupper: (libc)Classification of Characters.
|
* iswalnum: (libc)Classification of Wide Characters.
|
* iswalpha: (libc)Classification of Wide Characters.
|
* iswblank: (libc)Classification of Wide Characters.
|
* iswcntrl: (libc)Classification of Wide Characters.
|
* iswctype: (libc)Classification of Wide Characters.
|
* iswdigit: (libc)Classification of Wide Characters.
|
* iswgraph: (libc)Classification of Wide Characters.
|
* iswlower: (libc)Classification of Wide Characters.
|
* iswprint: (libc)Classification of Wide Characters.
|
* iswpunct: (libc)Classification of Wide Characters.
|
* iswspace: (libc)Classification of Wide Characters.
|
* iswupper: (libc)Classification of Wide Characters.
|
* iswxdigit: (libc)Classification of Wide Characters.
|
* isxdigit: (libc)Classification of Characters.
|
* iszero: (libc)Floating Point Classes.
|
* j0: (libc)Special Functions.
|
* j0f: (libc)Special Functions.
|
* j0fN: (libc)Special Functions.
|
* j0fNx: (libc)Special Functions.
|
* j0l: (libc)Special Functions.
|
* j1: (libc)Special Functions.
|
* j1f: (libc)Special Functions.
|
* j1fN: (libc)Special Functions.
|
* j1fNx: (libc)Special Functions.
|
* j1l: (libc)Special Functions.
|
* jn: (libc)Special Functions.
|
* jnf: (libc)Special Functions.
|
* jnfN: (libc)Special Functions.
|
* jnfNx: (libc)Special Functions.
|
* jnl: (libc)Special Functions.
|
* jrand48: (libc)SVID Random.
|
* jrand48_r: (libc)SVID Random.
|
* kill: (libc)Signaling Another Process.
|
* killpg: (libc)Signaling Another Process.
|
* l64a: (libc)Encode Binary Data.
|
* labs: (libc)Absolute Value.
|
* lcong48: (libc)SVID Random.
|
* lcong48_r: (libc)SVID Random.
|
* ldexp: (libc)Normalization Functions.
|
* ldexpf: (libc)Normalization Functions.
|
* ldexpfN: (libc)Normalization Functions.
|
* ldexpfNx: (libc)Normalization Functions.
|
* ldexpl: (libc)Normalization Functions.
|
* ldiv: (libc)Integer Division.
|
* lfind: (libc)Array Search Function.
|
* lgamma: (libc)Special Functions.
|
* lgamma_r: (libc)Special Functions.
|
* lgammaf: (libc)Special Functions.
|
* lgammafN: (libc)Special Functions.
|
* lgammafN_r: (libc)Special Functions.
|
* lgammafNx: (libc)Special Functions.
|
* lgammafNx_r: (libc)Special Functions.
|
* lgammaf_r: (libc)Special Functions.
|
* lgammal: (libc)Special Functions.
|
* lgammal_r: (libc)Special Functions.
|
* link: (libc)Hard Links.
|
* linkat: (libc)Hard Links.
|
* lio_listio64: (libc)Asynchronous Reads/Writes.
|
* lio_listio: (libc)Asynchronous Reads/Writes.
|
* listen: (libc)Listening.
|
* llabs: (libc)Absolute Value.
|
* lldiv: (libc)Integer Division.
|
* llogb: (libc)Exponents and Logarithms.
|
* llogbf: (libc)Exponents and Logarithms.
|
* llogbfN: (libc)Exponents and Logarithms.
|
* llogbfNx: (libc)Exponents and Logarithms.
|
* llogbl: (libc)Exponents and Logarithms.
|
* llrint: (libc)Rounding Functions.
|
* llrintf: (libc)Rounding Functions.
|
* llrintfN: (libc)Rounding Functions.
|
* llrintfNx: (libc)Rounding Functions.
|
* llrintl: (libc)Rounding Functions.
|
* llround: (libc)Rounding Functions.
|
* llroundf: (libc)Rounding Functions.
|
* llroundfN: (libc)Rounding Functions.
|
* llroundfNx: (libc)Rounding Functions.
|
* llroundl: (libc)Rounding Functions.
|
* localeconv: (libc)The Lame Way to Locale Data.
|
* localtime: (libc)Broken-down Time.
|
* localtime_r: (libc)Broken-down Time.
|
* log10: (libc)Exponents and Logarithms.
|
* log10f: (libc)Exponents and Logarithms.
|
* log10fN: (libc)Exponents and Logarithms.
|
* log10fNx: (libc)Exponents and Logarithms.
|
* log10l: (libc)Exponents and Logarithms.
|
* log1p: (libc)Exponents and Logarithms.
|
* log1pf: (libc)Exponents and Logarithms.
|
* log1pfN: (libc)Exponents and Logarithms.
|
* log1pfNx: (libc)Exponents and Logarithms.
|
* log1pl: (libc)Exponents and Logarithms.
|
* log2: (libc)Exponents and Logarithms.
|
* log2f: (libc)Exponents and Logarithms.
|
* log2fN: (libc)Exponents and Logarithms.
|
* log2fNx: (libc)Exponents and Logarithms.
|
* log2l: (libc)Exponents and Logarithms.
|
* log: (libc)Exponents and Logarithms.
|
* logb: (libc)Exponents and Logarithms.
|
* logbf: (libc)Exponents and Logarithms.
|
* logbfN: (libc)Exponents and Logarithms.
|
* logbfNx: (libc)Exponents and Logarithms.
|
* logbl: (libc)Exponents and Logarithms.
|
* logf: (libc)Exponents and Logarithms.
|
* logfN: (libc)Exponents and Logarithms.
|
* logfNx: (libc)Exponents and Logarithms.
|
* login: (libc)Logging In and Out.
|
* login_tty: (libc)Logging In and Out.
|
* logl: (libc)Exponents and Logarithms.
|
* logout: (libc)Logging In and Out.
|
* logwtmp: (libc)Logging In and Out.
|
* longjmp: (libc)Non-Local Details.
|
* lrand48: (libc)SVID Random.
|
* lrand48_r: (libc)SVID Random.
|
* lrint: (libc)Rounding Functions.
|
* lrintf: (libc)Rounding Functions.
|
* lrintfN: (libc)Rounding Functions.
|
* lrintfNx: (libc)Rounding Functions.
|
* lrintl: (libc)Rounding Functions.
|
* lround: (libc)Rounding Functions.
|
* lroundf: (libc)Rounding Functions.
|
* lroundfN: (libc)Rounding Functions.
|
* lroundfNx: (libc)Rounding Functions.
|
* lroundl: (libc)Rounding Functions.
|
* lsearch: (libc)Array Search Function.
|
* lseek64: (libc)File Position Primitive.
|
* lseek: (libc)File Position Primitive.
|
* lstat64: (libc)Reading Attributes.
|
* lstat: (libc)Reading Attributes.
|
* lutimes: (libc)File Times.
|
* madvise: (libc)Memory-mapped I/O.
|
* makecontext: (libc)System V contexts.
|
* mallinfo2: (libc)Statistics of Malloc.
|
* malloc: (libc)Basic Allocation.
|
* mallopt: (libc)Malloc Tunable Parameters.
|
* mblen: (libc)Non-reentrant Character Conversion.
|
* mbrlen: (libc)Converting a Character.
|
* mbrtowc: (libc)Converting a Character.
|
* mbsinit: (libc)Keeping the state.
|
* mbsnrtowcs: (libc)Converting Strings.
|
* mbsrtowcs: (libc)Converting Strings.
|
* mbstowcs: (libc)Non-reentrant String Conversion.
|
* mbtowc: (libc)Non-reentrant Character Conversion.
|
* mcheck: (libc)Heap Consistency Checking.
|
* memalign: (libc)Aligned Memory Blocks.
|
* memccpy: (libc)Copying Strings and Arrays.
|
* memchr: (libc)Search Functions.
|
* memcmp: (libc)String/Array Comparison.
|
* memcpy: (libc)Copying Strings and Arrays.
|
* memfd_create: (libc)Memory-mapped I/O.
|
* memfrob: (libc)Obfuscating Data.
|
* memmem: (libc)Search Functions.
|
* memmove: (libc)Copying Strings and Arrays.
|
* mempcpy: (libc)Copying Strings and Arrays.
|
* memrchr: (libc)Search Functions.
|
* memset: (libc)Copying Strings and Arrays.
|
* mkdir: (libc)Creating Directories.
|
* mkdtemp: (libc)Temporary Files.
|
* mkfifo: (libc)FIFO Special Files.
|
* mknod: (libc)Making Special Files.
|
* mkstemp: (libc)Temporary Files.
|
* mktemp: (libc)Temporary Files.
|
* mktime: (libc)Broken-down Time.
|
* mlock2: (libc)Page Lock Functions.
|
* mlock: (libc)Page Lock Functions.
|
* mlockall: (libc)Page Lock Functions.
|
* mmap64: (libc)Memory-mapped I/O.
|
* mmap: (libc)Memory-mapped I/O.
|
* modf: (libc)Rounding Functions.
|
* modff: (libc)Rounding Functions.
|
* modffN: (libc)Rounding Functions.
|
* modffNx: (libc)Rounding Functions.
|
* modfl: (libc)Rounding Functions.
|
* mount: (libc)Mount-Unmount-Remount.
|
* mprobe: (libc)Heap Consistency Checking.
|
* mprotect: (libc)Memory Protection.
|
* mrand48: (libc)SVID Random.
|
* mrand48_r: (libc)SVID Random.
|
* mremap: (libc)Memory-mapped I/O.
|
* msync: (libc)Memory-mapped I/O.
|
* mtrace: (libc)Tracing malloc.
|
* mtx_destroy: (libc)ISO C Mutexes.
|
* mtx_init: (libc)ISO C Mutexes.
|
* mtx_lock: (libc)ISO C Mutexes.
|
* mtx_timedlock: (libc)ISO C Mutexes.
|
* mtx_trylock: (libc)ISO C Mutexes.
|
* mtx_unlock: (libc)ISO C Mutexes.
|
* munlock: (libc)Page Lock Functions.
|
* munlockall: (libc)Page Lock Functions.
|
* munmap: (libc)Memory-mapped I/O.
|
* muntrace: (libc)Tracing malloc.
|
* nan: (libc)FP Bit Twiddling.
|
* nanf: (libc)FP Bit Twiddling.
|
* nanfN: (libc)FP Bit Twiddling.
|
* nanfNx: (libc)FP Bit Twiddling.
|
* nanl: (libc)FP Bit Twiddling.
|
* nanosleep: (libc)Sleeping.
|
* nearbyint: (libc)Rounding Functions.
|
* nearbyintf: (libc)Rounding Functions.
|
* nearbyintfN: (libc)Rounding Functions.
|
* nearbyintfNx: (libc)Rounding Functions.
|
* nearbyintl: (libc)Rounding Functions.
|
* nextafter: (libc)FP Bit Twiddling.
|
* nextafterf: (libc)FP Bit Twiddling.
|
* nextafterfN: (libc)FP Bit Twiddling.
|
* nextafterfNx: (libc)FP Bit Twiddling.
|
* nextafterl: (libc)FP Bit Twiddling.
|
* nextdown: (libc)FP Bit Twiddling.
|
* nextdownf: (libc)FP Bit Twiddling.
|
* nextdownfN: (libc)FP Bit Twiddling.
|
* nextdownfNx: (libc)FP Bit Twiddling.
|
* nextdownl: (libc)FP Bit Twiddling.
|
* nexttoward: (libc)FP Bit Twiddling.
|
* nexttowardf: (libc)FP Bit Twiddling.
|
* nexttowardl: (libc)FP Bit Twiddling.
|
* nextup: (libc)FP Bit Twiddling.
|
* nextupf: (libc)FP Bit Twiddling.
|
* nextupfN: (libc)FP Bit Twiddling.
|
* nextupfNx: (libc)FP Bit Twiddling.
|
* nextupl: (libc)FP Bit Twiddling.
|
* nftw64: (libc)Working with Directory Trees.
|
* nftw: (libc)Working with Directory Trees.
|
* ngettext: (libc)Advanced gettext functions.
|
* nice: (libc)Traditional Scheduling Functions.
|
* nl_langinfo: (libc)The Elegant and Fast Way.
|
* nrand48: (libc)SVID Random.
|
* nrand48_r: (libc)SVID Random.
|
* ntohl: (libc)Byte Order.
|
* ntohs: (libc)Byte Order.
|
* ntp_adjtime: (libc)Setting and Adjusting the Time.
|
* ntp_gettime: (libc)Setting and Adjusting the Time.
|
* obstack_1grow: (libc)Growing Objects.
|
* obstack_1grow_fast: (libc)Extra Fast Growing.
|
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
|
* obstack_alloc: (libc)Allocation in an Obstack.
|
* obstack_base: (libc)Status of an Obstack.
|
* obstack_blank: (libc)Growing Objects.
|
* obstack_blank_fast: (libc)Extra Fast Growing.
|
* obstack_chunk_size: (libc)Obstack Chunks.
|
* obstack_copy0: (libc)Allocation in an Obstack.
|
* obstack_copy: (libc)Allocation in an Obstack.
|
* obstack_finish: (libc)Growing Objects.
|
* obstack_free: (libc)Freeing Obstack Objects.
|
* obstack_grow0: (libc)Growing Objects.
|
* obstack_grow: (libc)Growing Objects.
|
* obstack_init: (libc)Preparing for Obstacks.
|
* obstack_int_grow: (libc)Growing Objects.
|
* obstack_int_grow_fast: (libc)Extra Fast Growing.
|
* obstack_next_free: (libc)Status of an Obstack.
|
* obstack_object_size: (libc)Growing Objects.
|
* obstack_object_size: (libc)Status of an Obstack.
|
* obstack_printf: (libc)Dynamic Output.
|
* obstack_ptr_grow: (libc)Growing Objects.
|
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
|
* obstack_room: (libc)Extra Fast Growing.
|
* obstack_vprintf: (libc)Variable Arguments Output.
|
* offsetof: (libc)Structure Measurement.
|
* on_exit: (libc)Cleanups on Exit.
|
* open64: (libc)Opening and Closing Files.
|
* open: (libc)Opening and Closing Files.
|
* open_memstream: (libc)String Streams.
|
* opendir: (libc)Opening a Directory.
|
* openlog: (libc)openlog.
|
* openpty: (libc)Pseudo-Terminal Pairs.
|
* parse_printf_format: (libc)Parsing a Template String.
|
* pathconf: (libc)Pathconf.
|
* pause: (libc)Using Pause.
|
* pclose: (libc)Pipe to a Subprocess.
|
* perror: (libc)Error Messages.
|
* pipe: (libc)Creating a Pipe.
|
* pkey_alloc: (libc)Memory Protection.
|
* pkey_free: (libc)Memory Protection.
|
* pkey_get: (libc)Memory Protection.
|
* pkey_mprotect: (libc)Memory Protection.
|
* pkey_set: (libc)Memory Protection.
|
* popen: (libc)Pipe to a Subprocess.
|
* posix_fallocate64: (libc)Storage Allocation.
|
* posix_fallocate: (libc)Storage Allocation.
|
* posix_memalign: (libc)Aligned Memory Blocks.
|
* pow: (libc)Exponents and Logarithms.
|
* powf: (libc)Exponents and Logarithms.
|
* powfN: (libc)Exponents and Logarithms.
|
* powfNx: (libc)Exponents and Logarithms.
|
* powl: (libc)Exponents and Logarithms.
|
* pread64: (libc)I/O Primitives.
|
* pread: (libc)I/O Primitives.
|
* preadv2: (libc)Scatter-Gather.
|
* preadv64: (libc)Scatter-Gather.
|
* preadv64v2: (libc)Scatter-Gather.
|
* preadv: (libc)Scatter-Gather.
|
* printf: (libc)Formatted Output Functions.
|
* printf_size: (libc)Predefined Printf Handlers.
|
* printf_size_info: (libc)Predefined Printf Handlers.
|
* psignal: (libc)Signal Messages.
|
* pthread_attr_getsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_attr_setsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_clockjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_cond_clockwait: (libc)Waiting with Explicit Clocks.
|
* 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_rwlock_clockrdlock: (libc)Waiting with Explicit Clocks.
|
* pthread_rwlock_clockwrlock: (libc)Waiting with Explicit Clocks.
|
* pthread_setattr_default_np: (libc)Default Thread Attributes.
|
* pthread_setspecific: (libc)Thread-specific Data.
|
* pthread_timedjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_tryjoin_np: (libc)Waiting with Explicit Clocks.
|
* ptsname: (libc)Allocation.
|
* ptsname_r: (libc)Allocation.
|
* putc: (libc)Simple Output.
|
* putc_unlocked: (libc)Simple Output.
|
* putchar: (libc)Simple Output.
|
* putchar_unlocked: (libc)Simple Output.
|
* putenv: (libc)Environment Access.
|
* putpwent: (libc)Writing a User Entry.
|
* puts: (libc)Simple Output.
|
* pututline: (libc)Manipulating the Database.
|
* pututxline: (libc)XPG Functions.
|
* putw: (libc)Simple Output.
|
* putwc: (libc)Simple Output.
|
* putwc_unlocked: (libc)Simple Output.
|
* putwchar: (libc)Simple Output.
|
* putwchar_unlocked: (libc)Simple Output.
|
* pwrite64: (libc)I/O Primitives.
|
* pwrite: (libc)I/O Primitives.
|
* pwritev2: (libc)Scatter-Gather.
|
* pwritev64: (libc)Scatter-Gather.
|
* pwritev64v2: (libc)Scatter-Gather.
|
* pwritev: (libc)Scatter-Gather.
|
* qecvt: (libc)System V Number Conversion.
|
* qecvt_r: (libc)System V Number Conversion.
|
* qfcvt: (libc)System V Number Conversion.
|
* qfcvt_r: (libc)System V Number Conversion.
|
* qgcvt: (libc)System V Number Conversion.
|
* qsort: (libc)Array Sort Function.
|
* raise: (libc)Signaling Yourself.
|
* rand: (libc)ISO Random.
|
* rand_r: (libc)ISO Random.
|
* random: (libc)BSD Random.
|
* random_r: (libc)BSD Random.
|
* rawmemchr: (libc)Search Functions.
|
* read: (libc)I/O Primitives.
|
* readdir64: (libc)Reading/Closing Directory.
|
* readdir64_r: (libc)Reading/Closing Directory.
|
* readdir: (libc)Reading/Closing Directory.
|
* readdir_r: (libc)Reading/Closing Directory.
|
* readlink: (libc)Symbolic Links.
|
* readv: (libc)Scatter-Gather.
|
* realloc: (libc)Changing Block Size.
|
* reallocarray: (libc)Changing Block Size.
|
* realpath: (libc)Symbolic Links.
|
* recv: (libc)Receiving Data.
|
* recvfrom: (libc)Receiving Datagrams.
|
* recvmsg: (libc)Receiving Datagrams.
|
* regcomp: (libc)POSIX Regexp Compilation.
|
* regerror: (libc)Regexp Cleanup.
|
* regexec: (libc)Matching POSIX Regexps.
|
* regfree: (libc)Regexp Cleanup.
|
* register_printf_function: (libc)Registering New Conversions.
|
* remainder: (libc)Remainder Functions.
|
* remainderf: (libc)Remainder Functions.
|
* remainderfN: (libc)Remainder Functions.
|
* remainderfNx: (libc)Remainder Functions.
|
* remainderl: (libc)Remainder Functions.
|
* remove: (libc)Deleting Files.
|
* rename: (libc)Renaming Files.
|
* rewind: (libc)File Positioning.
|
* rewinddir: (libc)Random Access Directory.
|
* rindex: (libc)Search Functions.
|
* rint: (libc)Rounding Functions.
|
* rintf: (libc)Rounding Functions.
|
* rintfN: (libc)Rounding Functions.
|
* rintfNx: (libc)Rounding Functions.
|
* rintl: (libc)Rounding Functions.
|
* rmdir: (libc)Deleting Files.
|
* round: (libc)Rounding Functions.
|
* roundeven: (libc)Rounding Functions.
|
* roundevenf: (libc)Rounding Functions.
|
* roundevenfN: (libc)Rounding Functions.
|
* roundevenfNx: (libc)Rounding Functions.
|
* roundevenl: (libc)Rounding Functions.
|
* roundf: (libc)Rounding Functions.
|
* roundfN: (libc)Rounding Functions.
|
* roundfNx: (libc)Rounding Functions.
|
* roundl: (libc)Rounding Functions.
|
* rpmatch: (libc)Yes-or-No Questions.
|
* sbrk: (libc)Resizing the Data Segment.
|
* scalb: (libc)Normalization Functions.
|
* scalbf: (libc)Normalization Functions.
|
* scalbl: (libc)Normalization Functions.
|
* scalbln: (libc)Normalization Functions.
|
* scalblnf: (libc)Normalization Functions.
|
* scalblnfN: (libc)Normalization Functions.
|
* scalblnfNx: (libc)Normalization Functions.
|
* scalblnl: (libc)Normalization Functions.
|
* scalbn: (libc)Normalization Functions.
|
* scalbnf: (libc)Normalization Functions.
|
* scalbnfN: (libc)Normalization Functions.
|
* scalbnfNx: (libc)Normalization Functions.
|
* scalbnl: (libc)Normalization Functions.
|
* scandir64: (libc)Scanning Directory Content.
|
* scandir: (libc)Scanning Directory Content.
|
* scanf: (libc)Formatted Input Functions.
|
* sched_get_priority_max: (libc)Basic Scheduling Functions.
|
* sched_get_priority_min: (libc)Basic Scheduling Functions.
|
* sched_getaffinity: (libc)CPU Affinity.
|
* sched_getparam: (libc)Basic Scheduling Functions.
|
* sched_getscheduler: (libc)Basic Scheduling Functions.
|
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
|
* sched_setaffinity: (libc)CPU Affinity.
|
* sched_setparam: (libc)Basic Scheduling Functions.
|
* sched_setscheduler: (libc)Basic Scheduling Functions.
|
* sched_yield: (libc)Basic Scheduling Functions.
|
* secure_getenv: (libc)Environment Access.
|
* seed48: (libc)SVID Random.
|
* seed48_r: (libc)SVID Random.
|
* seekdir: (libc)Random Access Directory.
|
* select: (libc)Waiting for I/O.
|
* sem_clockwait: (libc)Waiting with Explicit Clocks.
|
* sem_close: (libc)Semaphores.
|
* sem_destroy: (libc)Semaphores.
|
* sem_getvalue: (libc)Semaphores.
|
* sem_init: (libc)Semaphores.
|
* sem_open: (libc)Semaphores.
|
* sem_post: (libc)Semaphores.
|
* sem_timedwait: (libc)Semaphores.
|
* sem_trywait: (libc)Semaphores.
|
* sem_unlink: (libc)Semaphores.
|
* sem_wait: (libc)Semaphores.
|
* semctl: (libc)Semaphores.
|
* semget: (libc)Semaphores.
|
* semop: (libc)Semaphores.
|
* semtimedop: (libc)Semaphores.
|
* send: (libc)Sending Data.
|
* sendmsg: (libc)Receiving Datagrams.
|
* sendto: (libc)Sending Datagrams.
|
* setbuf: (libc)Controlling Buffering.
|
* setbuffer: (libc)Controlling Buffering.
|
* setcontext: (libc)System V contexts.
|
* setdomainname: (libc)Host Identification.
|
* setegid: (libc)Setting Groups.
|
* setenv: (libc)Environment Access.
|
* seteuid: (libc)Setting User ID.
|
* setfsent: (libc)fstab.
|
* setgid: (libc)Setting Groups.
|
* setgrent: (libc)Scanning All Groups.
|
* setgroups: (libc)Setting Groups.
|
* sethostent: (libc)Host Names.
|
* sethostid: (libc)Host Identification.
|
* sethostname: (libc)Host Identification.
|
* setitimer: (libc)Setting an Alarm.
|
* setjmp: (libc)Non-Local Details.
|
* setlinebuf: (libc)Controlling Buffering.
|
* setlocale: (libc)Setting the Locale.
|
* setlogmask: (libc)setlogmask.
|
* setmntent: (libc)mtab.
|
* setnetent: (libc)Networks Database.
|
* setnetgrent: (libc)Lookup Netgroup.
|
* setpayload: (libc)FP Bit Twiddling.
|
* setpayloadf: (libc)FP Bit Twiddling.
|
* setpayloadfN: (libc)FP Bit Twiddling.
|
* setpayloadfNx: (libc)FP Bit Twiddling.
|
* setpayloadl: (libc)FP Bit Twiddling.
|
* setpayloadsig: (libc)FP Bit Twiddling.
|
* setpayloadsigf: (libc)FP Bit Twiddling.
|
* setpayloadsigfN: (libc)FP Bit Twiddling.
|
* setpayloadsigfNx: (libc)FP Bit Twiddling.
|
* setpayloadsigl: (libc)FP Bit Twiddling.
|
* setpgid: (libc)Process Group Functions.
|
* setpgrp: (libc)Process Group Functions.
|
* setpriority: (libc)Traditional Scheduling Functions.
|
* setprotoent: (libc)Protocols Database.
|
* setpwent: (libc)Scanning All Users.
|
* setregid: (libc)Setting Groups.
|
* setreuid: (libc)Setting User ID.
|
* setrlimit64: (libc)Limits on Resources.
|
* setrlimit: (libc)Limits on Resources.
|
* setservent: (libc)Services Database.
|
* setsid: (libc)Process Group Functions.
|
* setsockopt: (libc)Socket Option Functions.
|
* setstate: (libc)BSD Random.
|
* setstate_r: (libc)BSD Random.
|
* settimeofday: (libc)Setting and Adjusting the Time.
|
* 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.
|
* sigabbrev_np: (libc)Signal Messages.
|
* sigaction: (libc)Advanced Signal Handling.
|
* sigaddset: (libc)Signal Sets.
|
* sigaltstack: (libc)Signal Stack.
|
* sigblock: (libc)BSD Signal Handling.
|
* sigdelset: (libc)Signal Sets.
|
* sigdescr_np: (libc)Signal Messages.
|
* sigemptyset: (libc)Signal Sets.
|
* sigfillset: (libc)Signal Sets.
|
* siginterrupt: (libc)BSD Signal Handling.
|
* sigismember: (libc)Signal Sets.
|
* siglongjmp: (libc)Non-Local Exits and Signals.
|
* sigmask: (libc)BSD Signal Handling.
|
* signal: (libc)Basic Signal Handling.
|
* signbit: (libc)FP Bit Twiddling.
|
* significand: (libc)Normalization Functions.
|
* significandf: (libc)Normalization Functions.
|
* significandl: (libc)Normalization Functions.
|
* sigpause: (libc)BSD Signal Handling.
|
* sigpending: (libc)Checking for Pending Signals.
|
* sigprocmask: (libc)Process Signal Mask.
|
* sigsetjmp: (libc)Non-Local Exits and Signals.
|
* sigsetmask: (libc)BSD Signal Handling.
|
* sigstack: (libc)Signal Stack.
|
* sigsuspend: (libc)Sigsuspend.
|
* sin: (libc)Trig Functions.
|
* sincos: (libc)Trig Functions.
|
* sincosf: (libc)Trig Functions.
|
* sincosfN: (libc)Trig Functions.
|
* sincosfNx: (libc)Trig Functions.
|
* sincosl: (libc)Trig Functions.
|
* sinf: (libc)Trig Functions.
|
* sinfN: (libc)Trig Functions.
|
* sinfNx: (libc)Trig Functions.
|
* sinh: (libc)Hyperbolic Functions.
|
* sinhf: (libc)Hyperbolic Functions.
|
* sinhfN: (libc)Hyperbolic Functions.
|
* sinhfNx: (libc)Hyperbolic Functions.
|
* sinhl: (libc)Hyperbolic Functions.
|
* sinl: (libc)Trig Functions.
|
* sleep: (libc)Sleeping.
|
* snprintf: (libc)Formatted Output Functions.
|
* socket: (libc)Creating a Socket.
|
* socketpair: (libc)Socket Pairs.
|
* sprintf: (libc)Formatted Output Functions.
|
* sqrt: (libc)Exponents and Logarithms.
|
* sqrtf: (libc)Exponents and Logarithms.
|
* sqrtfN: (libc)Exponents and Logarithms.
|
* sqrtfNx: (libc)Exponents and Logarithms.
|
* sqrtl: (libc)Exponents and Logarithms.
|
* srand48: (libc)SVID Random.
|
* srand48_r: (libc)SVID Random.
|
* srand: (libc)ISO Random.
|
* srandom: (libc)BSD Random.
|
* srandom_r: (libc)BSD Random.
|
* sscanf: (libc)Formatted Input Functions.
|
* ssignal: (libc)Basic Signal Handling.
|
* stat64: (libc)Reading Attributes.
|
* stat: (libc)Reading Attributes.
|
* stime: (libc)Setting and Adjusting the Time.
|
* stpcpy: (libc)Copying Strings and Arrays.
|
* stpncpy: (libc)Truncating Strings.
|
* strcasecmp: (libc)String/Array Comparison.
|
* strcasestr: (libc)Search Functions.
|
* strcat: (libc)Concatenating Strings.
|
* strchr: (libc)Search Functions.
|
* strchrnul: (libc)Search Functions.
|
* strcmp: (libc)String/Array Comparison.
|
* strcoll: (libc)Collation Functions.
|
* strcpy: (libc)Copying Strings and Arrays.
|
* strcspn: (libc)Search Functions.
|
* strdup: (libc)Copying Strings and Arrays.
|
* strdupa: (libc)Copying Strings and Arrays.
|
* strerror: (libc)Error Messages.
|
* strerror_r: (libc)Error Messages.
|
* strerrordesc_np: (libc)Error Messages.
|
* strerrorname_np: (libc)Error Messages.
|
* strfmon: (libc)Formatting Numbers.
|
* strfromd: (libc)Printing of Floats.
|
* strfromf: (libc)Printing of Floats.
|
* strfromfN: (libc)Printing of Floats.
|
* strfromfNx: (libc)Printing of Floats.
|
* strfroml: (libc)Printing of Floats.
|
* strfry: (libc)Shuffling Bytes.
|
* strftime: (libc)Formatting Calendar Time.
|
* strlen: (libc)String Length.
|
* strncasecmp: (libc)String/Array Comparison.
|
* strncat: (libc)Truncating Strings.
|
* strncmp: (libc)String/Array Comparison.
|
* strncpy: (libc)Truncating Strings.
|
* strndup: (libc)Truncating Strings.
|
* strndupa: (libc)Truncating Strings.
|
* strnlen: (libc)String Length.
|
* strpbrk: (libc)Search Functions.
|
* strptime: (libc)Low-Level Time String Parsing.
|
* strrchr: (libc)Search Functions.
|
* strsep: (libc)Finding Tokens in a String.
|
* strsignal: (libc)Signal Messages.
|
* strspn: (libc)Search Functions.
|
* strstr: (libc)Search Functions.
|
* strtod: (libc)Parsing of Floats.
|
* strtof: (libc)Parsing of Floats.
|
* strtofN: (libc)Parsing of Floats.
|
* strtofNx: (libc)Parsing of Floats.
|
* strtoimax: (libc)Parsing of Integers.
|
* strtok: (libc)Finding Tokens in a String.
|
* strtok_r: (libc)Finding Tokens in a String.
|
* strtol: (libc)Parsing of Integers.
|
* strtold: (libc)Parsing of Floats.
|
* strtoll: (libc)Parsing of Integers.
|
* strtoq: (libc)Parsing of Integers.
|
* strtoul: (libc)Parsing of Integers.
|
* strtoull: (libc)Parsing of Integers.
|
* strtoumax: (libc)Parsing of Integers.
|
* strtouq: (libc)Parsing of Integers.
|
* strverscmp: (libc)String/Array Comparison.
|
* strxfrm: (libc)Collation Functions.
|
* stty: (libc)BSD Terminal Modes.
|
* swapcontext: (libc)System V contexts.
|
* swprintf: (libc)Formatted Output Functions.
|
* swscanf: (libc)Formatted Input Functions.
|
* symlink: (libc)Symbolic Links.
|
* sync: (libc)Synchronizing I/O.
|
* syscall: (libc)System Calls.
|
* sysconf: (libc)Sysconf Definition.
|
* syslog: (libc)syslog; vsyslog.
|
* system: (libc)Running a Command.
|
* sysv_signal: (libc)Basic Signal Handling.
|
* tan: (libc)Trig Functions.
|
* tanf: (libc)Trig Functions.
|
* tanfN: (libc)Trig Functions.
|
* tanfNx: (libc)Trig Functions.
|
* tanh: (libc)Hyperbolic Functions.
|
* tanhf: (libc)Hyperbolic Functions.
|
* tanhfN: (libc)Hyperbolic Functions.
|
* tanhfNx: (libc)Hyperbolic Functions.
|
* tanhl: (libc)Hyperbolic Functions.
|
* tanl: (libc)Trig Functions.
|
* tcdrain: (libc)Line Control.
|
* tcflow: (libc)Line Control.
|
* tcflush: (libc)Line Control.
|
* tcgetattr: (libc)Mode Functions.
|
* tcgetpgrp: (libc)Terminal Access Functions.
|
* tcgetsid: (libc)Terminal Access Functions.
|
* tcsendbreak: (libc)Line Control.
|
* tcsetattr: (libc)Mode Functions.
|
* tcsetpgrp: (libc)Terminal Access Functions.
|
* tdelete: (libc)Tree Search Function.
|
* tdestroy: (libc)Tree Search Function.
|
* telldir: (libc)Random Access Directory.
|
* tempnam: (libc)Temporary Files.
|
* textdomain: (libc)Locating gettext catalog.
|
* tfind: (libc)Tree Search Function.
|
* tgamma: (libc)Special Functions.
|
* tgammaf: (libc)Special Functions.
|
* tgammafN: (libc)Special Functions.
|
* tgammafNx: (libc)Special Functions.
|
* tgammal: (libc)Special Functions.
|
* tgkill: (libc)Signaling Another Process.
|
* thrd_create: (libc)ISO C Thread Management.
|
* thrd_current: (libc)ISO C Thread Management.
|
* thrd_detach: (libc)ISO C Thread Management.
|
* thrd_equal: (libc)ISO C Thread Management.
|
* thrd_exit: (libc)ISO C Thread Management.
|
* thrd_join: (libc)ISO C Thread Management.
|
* thrd_sleep: (libc)ISO C Thread Management.
|
* thrd_yield: (libc)ISO C Thread Management.
|
* time: (libc)Getting the Time.
|
* timegm: (libc)Broken-down Time.
|
* timelocal: (libc)Broken-down Time.
|
* times: (libc)Processor Time.
|
* tmpfile64: (libc)Temporary Files.
|
* tmpfile: (libc)Temporary Files.
|
* tmpnam: (libc)Temporary Files.
|
* tmpnam_r: (libc)Temporary Files.
|
* toascii: (libc)Case Conversion.
|
* tolower: (libc)Case Conversion.
|
* totalorder: (libc)FP Comparison Functions.
|
* totalorderf: (libc)FP Comparison Functions.
|
* totalorderfN: (libc)FP Comparison Functions.
|
* totalorderfNx: (libc)FP Comparison Functions.
|
* totalorderl: (libc)FP Comparison Functions.
|
* totalordermag: (libc)FP Comparison Functions.
|
* totalordermagf: (libc)FP Comparison Functions.
|
* totalordermagfN: (libc)FP Comparison Functions.
|
* totalordermagfNx: (libc)FP Comparison Functions.
|
* totalordermagl: (libc)FP Comparison Functions.
|
* toupper: (libc)Case Conversion.
|
* towctrans: (libc)Wide Character Case Conversion.
|
* towlower: (libc)Wide Character Case Conversion.
|
* towupper: (libc)Wide Character Case Conversion.
|
* trunc: (libc)Rounding Functions.
|
* truncate64: (libc)File Size.
|
* truncate: (libc)File Size.
|
* truncf: (libc)Rounding Functions.
|
* truncfN: (libc)Rounding Functions.
|
* truncfNx: (libc)Rounding Functions.
|
* truncl: (libc)Rounding Functions.
|
* tsearch: (libc)Tree Search Function.
|
* tss_create: (libc)ISO C Thread-local Storage.
|
* tss_delete: (libc)ISO C Thread-local Storage.
|
* tss_get: (libc)ISO C Thread-local Storage.
|
* tss_set: (libc)ISO C Thread-local Storage.
|
* ttyname: (libc)Is It a Terminal.
|
* ttyname_r: (libc)Is It a Terminal.
|
* twalk: (libc)Tree Search Function.
|
* twalk_r: (libc)Tree Search Function.
|
* tzset: (libc)Time Zone Functions.
|
* ufromfp: (libc)Rounding Functions.
|
* ufromfpf: (libc)Rounding Functions.
|
* ufromfpfN: (libc)Rounding Functions.
|
* ufromfpfNx: (libc)Rounding Functions.
|
* ufromfpl: (libc)Rounding Functions.
|
* ufromfpx: (libc)Rounding Functions.
|
* ufromfpxf: (libc)Rounding Functions.
|
* ufromfpxfN: (libc)Rounding Functions.
|
* ufromfpxfNx: (libc)Rounding Functions.
|
* ufromfpxl: (libc)Rounding Functions.
|
* ulimit: (libc)Limits on Resources.
|
* umask: (libc)Setting Permissions.
|
* umount2: (libc)Mount-Unmount-Remount.
|
* umount: (libc)Mount-Unmount-Remount.
|
* uname: (libc)Platform Type.
|
* ungetc: (libc)How Unread.
|
* ungetwc: (libc)How Unread.
|
* unlink: (libc)Deleting Files.
|
* unlockpt: (libc)Allocation.
|
* unsetenv: (libc)Environment Access.
|
* updwtmp: (libc)Manipulating the Database.
|
* utime: (libc)File Times.
|
* utimes: (libc)File Times.
|
* utmpname: (libc)Manipulating the Database.
|
* utmpxname: (libc)XPG Functions.
|
* va_arg: (libc)Argument Macros.
|
* va_copy: (libc)Argument Macros.
|
* va_end: (libc)Argument Macros.
|
* va_start: (libc)Argument Macros.
|
* valloc: (libc)Aligned Memory Blocks.
|
* vasprintf: (libc)Variable Arguments Output.
|
* verr: (libc)Error Messages.
|
* verrx: (libc)Error Messages.
|
* versionsort64: (libc)Scanning Directory Content.
|
* versionsort: (libc)Scanning Directory Content.
|
* vfork: (libc)Creating a Process.
|
* vfprintf: (libc)Variable Arguments Output.
|
* vfscanf: (libc)Variable Arguments Input.
|
* vfwprintf: (libc)Variable Arguments Output.
|
* vfwscanf: (libc)Variable Arguments Input.
|
* vlimit: (libc)Limits on Resources.
|
* vprintf: (libc)Variable Arguments Output.
|
* vscanf: (libc)Variable Arguments Input.
|
* vsnprintf: (libc)Variable Arguments Output.
|
* vsprintf: (libc)Variable Arguments Output.
|
* vsscanf: (libc)Variable Arguments Input.
|
* vswprintf: (libc)Variable Arguments Output.
|
* vswscanf: (libc)Variable Arguments Input.
|
* vsyslog: (libc)syslog; vsyslog.
|
* vwarn: (libc)Error Messages.
|
* vwarnx: (libc)Error Messages.
|
* vwprintf: (libc)Variable Arguments Output.
|
* vwscanf: (libc)Variable Arguments Input.
|
* wait3: (libc)BSD Wait Functions.
|
* wait4: (libc)Process Completion.
|
* wait: (libc)Process Completion.
|
* waitpid: (libc)Process Completion.
|
* warn: (libc)Error Messages.
|
* warnx: (libc)Error Messages.
|
* wcpcpy: (libc)Copying Strings and Arrays.
|
* wcpncpy: (libc)Truncating Strings.
|
* wcrtomb: (libc)Converting a Character.
|
* wcscasecmp: (libc)String/Array Comparison.
|
* wcscat: (libc)Concatenating Strings.
|
* wcschr: (libc)Search Functions.
|
* wcschrnul: (libc)Search Functions.
|
* wcscmp: (libc)String/Array Comparison.
|
* wcscoll: (libc)Collation Functions.
|
* wcscpy: (libc)Copying Strings and Arrays.
|
* wcscspn: (libc)Search Functions.
|
* wcsdup: (libc)Copying Strings and Arrays.
|
* wcsftime: (libc)Formatting Calendar Time.
|
* wcslen: (libc)String Length.
|
* wcsncasecmp: (libc)String/Array Comparison.
|
* wcsncat: (libc)Truncating Strings.
|
* wcsncmp: (libc)String/Array Comparison.
|
* wcsncpy: (libc)Truncating Strings.
|
* wcsnlen: (libc)String Length.
|
* wcsnrtombs: (libc)Converting Strings.
|
* wcspbrk: (libc)Search Functions.
|
* wcsrchr: (libc)Search Functions.
|
* wcsrtombs: (libc)Converting Strings.
|
* wcsspn: (libc)Search Functions.
|
* wcsstr: (libc)Search Functions.
|
* wcstod: (libc)Parsing of Floats.
|
* wcstof: (libc)Parsing of Floats.
|
* wcstofN: (libc)Parsing of Floats.
|
* wcstofNx: (libc)Parsing of Floats.
|
* wcstoimax: (libc)Parsing of Integers.
|
* wcstok: (libc)Finding Tokens in a String.
|
* wcstol: (libc)Parsing of Integers.
|
* wcstold: (libc)Parsing of Floats.
|
* wcstoll: (libc)Parsing of Integers.
|
* wcstombs: (libc)Non-reentrant String Conversion.
|
* wcstoq: (libc)Parsing of Integers.
|
* wcstoul: (libc)Parsing of Integers.
|
* wcstoull: (libc)Parsing of Integers.
|
* wcstoumax: (libc)Parsing of Integers.
|
* wcstouq: (libc)Parsing of Integers.
|
* wcswcs: (libc)Search Functions.
|
* wcsxfrm: (libc)Collation Functions.
|
* wctob: (libc)Converting a Character.
|
* wctomb: (libc)Non-reentrant Character Conversion.
|
* wctrans: (libc)Wide Character Case Conversion.
|
* wctype: (libc)Classification of Wide Characters.
|
* wmemchr: (libc)Search Functions.
|
* wmemcmp: (libc)String/Array Comparison.
|
* wmemcpy: (libc)Copying Strings and Arrays.
|
* wmemmove: (libc)Copying Strings and Arrays.
|
* wmempcpy: (libc)Copying Strings and Arrays.
|
* wmemset: (libc)Copying Strings and Arrays.
|
* wordexp: (libc)Calling Wordexp.
|
* wordfree: (libc)Calling Wordexp.
|
* wprintf: (libc)Formatted Output Functions.
|
* write: (libc)I/O Primitives.
|
* writev: (libc)Scatter-Gather.
|
* wscanf: (libc)Formatted Input Functions.
|
* y0: (libc)Special Functions.
|
* y0f: (libc)Special Functions.
|
* y0fN: (libc)Special Functions.
|
* y0fNx: (libc)Special Functions.
|
* y0l: (libc)Special Functions.
|
* y1: (libc)Special Functions.
|
* y1f: (libc)Special Functions.
|
* y1fN: (libc)Special Functions.
|
* y1fNx: (libc)Special Functions.
|
* y1l: (libc)Special Functions.
|
* yn: (libc)Special Functions.
|
* ynf: (libc)Special Functions.
|
* ynfN: (libc)Special Functions.
|
* ynfNx: (libc)Special Functions.
|
* ynl: (libc)Special Functions.
|
END-INFO-DIR-ENTRY
|
|
|
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 stream 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’. This buffer remains allocated even if ‘getline’
|
encounters errors and is unable to read any bytes.
|
|
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 certain 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 systems 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)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
|
with 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
|
‘hh’ 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 are 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 in 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 an ‘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 to 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 an ‘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 Strings and Arrays::.
|
|
*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 *WS, 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 than 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.
|
|
*Portability Note:* The value of the ‘va_list’ pointer is
|
undetermined 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. You can call ‘va_start’ again and begin
|
fetching the arguments from the start of the variable argument list.
|
(Alternatively, you can use ‘va_copy’ to make a copy of the ‘va_list’
|
pointer before calling ‘vfprintf’.) Calling ‘vprintf’ does not destroy
|
the argument list of your function, merely the particular pointer that
|
you passed to it.
|
|
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 *WS, 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)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 (format, nargs, 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. When using the GNU C compiler or any other compiler that
|
interprets calls to standard I/O functions according to the rules of the
|
language standard it is necessary to disable such handling by the
|
appropriate compiler option. Otherwise the behavior of a program that
|
relies on the extension is undefined.
|
|
|
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).
|
|
*Portability Note:* It is possible to redefine the standard output
|
conversions but doing so is strongly discouraged because it may
|
interfere with the behavior of programs and compiler
|
implementations that assume the effects of the conversions conform
|
to the relevant language standards. In addition, conforming
|
compilers need not guarantee that the function registered for a
|
standard conversion will be called for each such conversion in
|
every format string in a program.
|
|
|
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)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 ‘%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 must
|
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 if
|
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
|
characters 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 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)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 are 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’ functions, 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’ functions, 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’ functions, 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’.
|
|
|
File: libc.info, Node: Portable Positioning, Next: Stream Buffering, Prev: File Positioning, Up: I/O on Streams
|
|
12.19 Portable File-Position Functions
|
======================================
|
|
On GNU systems, the file position is truly a character count. You can
|
specify any character count value as an argument to ‘fseek’ or ‘fseeko’
|
and get reliable results for any random access file. However, some ISO C
|
systems do not represent file positions in this way.
|
|
On some systems where text streams truly differ from binary streams,
|
it is impossible to represent the file position of a text stream as a
|
count of characters from the beginning of the file. For example, the
|
file position on some systems must encode both a record offset within
|
the file, and a character offset within the record.
|
|
As a consequence, if you want your programs to be portable to these
|
systems, you must observe certain rules:
|
|
• The value returned from ‘ftell’ on a text stream has no predictable
|
relationship to the number of characters you have read so far. The
|
only thing you can rely on is that you can use it subsequently as
|
the OFFSET argument to ‘fseek’ or ‘fseeko’ to move back to the same
|
file position.
|
|
• In a call to ‘fseek’ or ‘fseeko’ on a text stream, either the
|
OFFSET must be zero, or WHENCE must be ‘SEEK_SET’ and the OFFSET
|
must be the result of an earlier call to ‘ftell’ on the same
|
stream.
|
|
• The value of the file position indicator of a text stream is
|
undefined while there are characters that have been pushed back
|
with ‘ungetc’ that haven’t been read or discarded. *Note
|
Unreading::.
|
|
But even if you observe these rules, you may still have trouble for
|
long files, because ‘ftell’ and ‘fseek’ use a ‘long int’ value to
|
represent the file position. This type may not have room to encode all
|
the file positions in a large file. Using the ‘ftello’ and ‘fseeko’
|
functions might help here since the ‘off_t’ type is expected to be able
|
to hold all file position values but this still does not help to handle
|
additional information which must be associated with a file position.
|
|
So if you do want to support systems with peculiar encodings for the
|
file positions, it is better to use the functions ‘fgetpos’ and
|
‘fsetpos’ instead. These functions represent the file position using
|
the data type ‘fpos_t’, whose internal representation varies from system
|
to system.
|
|
These symbols are declared in the header file ‘stdio.h’.
|
|
-- Data Type: fpos_t
|
|
This is the type of an object that can encode information about the
|
file position of a stream, for use by the functions ‘fgetpos’ and
|
‘fsetpos’.
|
|
In the GNU C Library, ‘fpos_t’ is an opaque data structure that
|
contains internal data to represent file offset and conversion
|
state information. In other systems, it might have a different
|
internal representation.
|
|
When compiling with ‘_FILE_OFFSET_BITS == 64’ on a 32 bit machine
|
this type is in fact equivalent to ‘fpos64_t’ since the LFS
|
interface transparently replaces the old interface.
|
|
-- Data Type: fpos64_t
|
|
This is the type of an object that can encode information about the
|
file position of a stream, for use by the functions ‘fgetpos64’ and
|
‘fsetpos64’.
|
|
In the GNU C Library, ‘fpos64_t’ is an opaque data structure that
|
contains internal data to represent file offset and conversion
|
state information. In other systems, it might have a different
|
internal representation.
|
|
-- Function: int fgetpos (FILE *STREAM, fpos_t *POSITION)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function stores the value of the file position indicator for
|
the stream STREAM in the ‘fpos_t’ object pointed to by POSITION.
|
If successful, ‘fgetpos’ returns zero; otherwise it returns a
|
nonzero value and stores an implementation-defined positive value
|
in ‘errno’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32 bit system the function is in fact ‘fgetpos64’. I.e., the LFS
|
interface transparently replaces the old interface.
|
|
-- Function: int fgetpos64 (FILE *STREAM, fpos64_t *POSITION)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘fgetpos’ but the file position is
|
returned in a variable of type ‘fpos64_t’ to which POSITION points.
|
|
If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
|
bits machine this function is available under the name ‘fgetpos’
|
and so transparently replaces the old interface.
|
|
-- Function: int fsetpos (FILE *STREAM, const fpos_t *POSITION)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function sets the file position indicator for the stream
|
STREAM to the position POSITION, which must have been set by a
|
previous call to ‘fgetpos’ on the same stream. If successful,
|
‘fsetpos’ clears the end-of-file indicator on the stream, discards
|
any characters that were “pushed back” by the use of ‘ungetc’, and
|
returns a value of zero. Otherwise, ‘fsetpos’ returns a nonzero
|
value and stores an implementation-defined positive value in
|
‘errno’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32 bit system the function is in fact ‘fsetpos64’. I.e., the LFS
|
interface transparently replaces the old interface.
|
|
-- Function: int fsetpos64 (FILE *STREAM, const fpos64_t *POSITION)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘fsetpos’ but the file position used
|
for positioning is provided in a variable of type ‘fpos64_t’ to
|
which POSITION points.
|
|
If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
|
bits machine this function is available under the name ‘fsetpos’
|
and so transparently replaces the old interface.
|
|
|
File: libc.info, Node: Stream Buffering, Next: Other Kinds of Streams, Prev: Portable Positioning, Up: I/O on Streams
|
|
12.20 Stream Buffering
|
======================
|
|
Characters that are written to a stream are normally accumulated and
|
transmitted asynchronously to the file in a block, instead of appearing
|
as soon as they are output by the application program. Similarly,
|
streams often retrieve input from the host environment in blocks rather
|
than on a character-by-character basis. This is called "buffering".
|
|
If you are writing programs that do interactive input and output
|
using streams, you need to understand how buffering works when you
|
design the user interface to your program. Otherwise, you might find
|
that output (such as progress or prompt messages) doesn’t appear when
|
you intended it to, or displays some other unexpected behavior.
|
|
This section deals only with controlling when characters are
|
transmitted between the stream and the file or device, and _not_ with
|
how things like echoing, flow control, and the like are handled on
|
specific classes of devices. For information on common control
|
operations on terminal devices, see *note Low-Level Terminal
|
Interface::.
|
|
You can bypass the stream buffering facilities altogether by using
|
the low-level input and output functions that operate on file
|
descriptors instead. *Note Low-Level I/O::.
|
|
* Menu:
|
|
* Buffering Concepts:: Terminology is defined here.
|
* Flushing Buffers:: How to ensure that output buffers are flushed.
|
* Controlling Buffering:: How to specify what kind of buffering to use.
|
|
|
File: libc.info, Node: Buffering Concepts, Next: Flushing Buffers, Up: Stream Buffering
|
|
12.20.1 Buffering Concepts
|
--------------------------
|
|
There are three different kinds of buffering strategies:
|
|
• Characters written to or read from an "unbuffered" stream are
|
transmitted individually to or from the file as soon as possible.
|
|
• Characters written to a "line buffered" stream are transmitted to
|
the file in blocks when a newline character is encountered.
|
|
• Characters written to or read from a "fully buffered" stream are
|
transmitted to or from the file in blocks of arbitrary size.
|
|
Newly opened streams are normally fully buffered, with one exception:
|
a stream connected to an interactive device such as a terminal is
|
initially line buffered. *Note Controlling Buffering::, for information
|
on how to select a different kind of buffering. Usually the automatic
|
selection gives you the most convenient kind of buffering for the file
|
or device you open.
|
|
The use of line buffering for interactive devices implies that output
|
messages ending in a newline will appear immediately—which is usually
|
what you want. Output that doesn’t end in a newline might or might not
|
show up immediately, so if you want them to appear immediately, you
|
should flush buffered output explicitly with ‘fflush’, as described in
|
*note Flushing Buffers::.
|
|
|
File: libc.info, Node: Flushing Buffers, Next: Controlling Buffering, Prev: Buffering Concepts, Up: Stream Buffering
|
|
12.20.2 Flushing Buffers
|
------------------------
|
|
"Flushing" output on a buffered stream means transmitting all
|
accumulated characters to the file. There are many circumstances when
|
buffered output on a stream is flushed automatically:
|
|
• When you try to do output and the output buffer is full.
|
|
• When the stream is closed. *Note Closing Streams::.
|
|
• When the program terminates by calling ‘exit’. *Note Normal
|
Termination::.
|
|
• When a newline is written, if the stream is line buffered.
|
|
• Whenever an input operation on _any_ stream actually reads data
|
from its file.
|
|
If you want to flush the buffered output at another time, call
|
‘fflush’, which is declared in the header file ‘stdio.h’.
|
|
-- Function: int fflush (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function causes any buffered output on STREAM to be delivered
|
to the file. If STREAM is a null pointer, then ‘fflush’ causes
|
buffered output on _all_ open output streams to be flushed.
|
|
This function returns ‘EOF’ if a write error occurs, or zero
|
otherwise.
|
|
-- Function: int fflush_unlocked (FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘fflush_unlocked’ function is equivalent to the ‘fflush’
|
function except that it does not implicitly lock the stream.
|
|
The ‘fflush’ function can be used to flush all streams currently
|
opened. While this is useful in some situations it does often more than
|
necessary since it might be done in situations when terminal input is
|
required and the program wants to be sure that all output is visible on
|
the terminal. But this means that only line buffered streams have to be
|
flushed. Solaris introduced a function especially for this. It was
|
always available in the GNU C Library in some form but never officially
|
exported.
|
|
-- Function: void _flushlbf (void)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
The ‘_flushlbf’ function flushes all line buffered streams
|
currently opened.
|
|
This function is declared in the ‘stdio_ext.h’ header.
|
|
*Compatibility Note:* Some brain-damaged operating systems have been
|
known to be so thoroughly fixated on line-oriented input and output that
|
flushing a line buffered stream causes a newline to be written!
|
Fortunately, this “feature” seems to be becoming less common. You do
|
not need to worry about this with the GNU C Library.
|
|
In some situations it might be useful to not flush the output pending
|
for a stream but instead simply forget it. If transmission is costly
|
and the output is not needed anymore this is valid reasoning. In this
|
situation a non-standard function introduced in Solaris and available in
|
the GNU C Library can be used.
|
|
-- Function: void __fpurge (FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘__fpurge’ function causes the buffer of the stream STREAM to
|
be emptied. If the stream is currently in read mode all input in
|
the buffer is lost. If the stream is in output mode the buffered
|
output is not written to the device (or whatever other underlying
|
storage) and the buffer is cleared.
|
|
This function is declared in ‘stdio_ext.h’.
|
|
|
File: libc.info, Node: Controlling Buffering, Prev: Flushing Buffers, Up: Stream Buffering
|
|
12.20.3 Controlling Which Kind of Buffering
|
-------------------------------------------
|
|
After opening a stream (but before any other operations have been
|
performed on it), you can explicitly specify what kind of buffering you
|
want it to have using the ‘setvbuf’ function.
|
|
The facilities listed in this section are declared in the header file
|
‘stdio.h’.
|
|
-- Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t
|
SIZE)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function is used to specify that the stream STREAM should have
|
the buffering mode MODE, which can be either ‘_IOFBF’ (for full
|
buffering), ‘_IOLBF’ (for line buffering), or ‘_IONBF’ (for
|
unbuffered input/output).
|
|
If you specify a null pointer as the BUF argument, then ‘setvbuf’
|
allocates a buffer itself using ‘malloc’. This buffer will be
|
freed when you close the stream.
|
|
Otherwise, BUF should be a character array that can hold at least
|
SIZE characters. You should not free the space for this array as
|
long as the stream remains open and this array remains its buffer.
|
You should usually either allocate it statically, or ‘malloc’
|
(*note Unconstrained Allocation::) the buffer. Using an automatic
|
array is not a good idea unless you close the file before exiting
|
the block that declares the array.
|
|
While the array remains a stream buffer, the stream I/O functions
|
will use the buffer for their internal purposes. You shouldn’t try
|
to access the values in the array directly while the stream is
|
using it for buffering.
|
|
The ‘setvbuf’ function returns zero on success, or a nonzero value
|
if the value of MODE is not valid or if the request could not be
|
honored.
|
|
-- Macro: int _IOFBF
|
|
The value of this macro is an integer constant expression that can
|
be used as the MODE argument to the ‘setvbuf’ function to specify
|
that the stream should be fully buffered.
|
|
-- Macro: int _IOLBF
|
|
The value of this macro is an integer constant expression that can
|
be used as the MODE argument to the ‘setvbuf’ function to specify
|
that the stream should be line buffered.
|
|
-- Macro: int _IONBF
|
|
The value of this macro is an integer constant expression that can
|
be used as the MODE argument to the ‘setvbuf’ function to specify
|
that the stream should be unbuffered.
|
|
-- Macro: int BUFSIZ
|
|
The value of this macro is an integer constant expression that is
|
good to use for the SIZE argument to ‘setvbuf’. This value is
|
guaranteed to be at least ‘256’.
|
|
The value of ‘BUFSIZ’ is chosen on each system so as to make stream
|
I/O efficient. So it is a good idea to use ‘BUFSIZ’ as the size
|
for the buffer when you call ‘setvbuf’.
|
|
Actually, you can get an even better value to use for the buffer
|
size by means of the ‘fstat’ system call: it is found in the
|
‘st_blksize’ field of the file attributes. *Note Attribute
|
Meanings::.
|
|
Sometimes people also use ‘BUFSIZ’ as the allocation size of
|
buffers used for related purposes, such as strings used to receive
|
a line of input with ‘fgets’ (*note Character Input::). There is
|
no particular reason to use ‘BUFSIZ’ for this instead of any other
|
integer, except that it might lead to doing I/O in chunks of an
|
efficient size.
|
|
-- Function: void setbuf (FILE *STREAM, char *BUF)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
If BUF is a null pointer, the effect of this function is equivalent
|
to calling ‘setvbuf’ with a MODE argument of ‘_IONBF’. Otherwise,
|
it is equivalent to calling ‘setvbuf’ with BUF, and a MODE of
|
‘_IOFBF’ and a SIZE argument of ‘BUFSIZ’.
|
|
The ‘setbuf’ function is provided for compatibility with old code;
|
use ‘setvbuf’ in all new programs.
|
|
-- Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
If BUF is a null pointer, this function makes STREAM unbuffered.
|
Otherwise, it makes STREAM fully buffered using BUF as the buffer.
|
The SIZE argument specifies the length of BUF.
|
|
This function is provided for compatibility with old BSD code. Use
|
‘setvbuf’ instead.
|
|
-- Function: void setlinebuf (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function makes STREAM be line buffered, and allocates the
|
buffer for you.
|
|
This function is provided for compatibility with old BSD code. Use
|
‘setvbuf’ instead.
|
|
It is possible to query whether a given stream is line buffered or
|
not using a non-standard function introduced in Solaris and available in
|
the GNU C Library.
|
|
-- Function: int __flbf (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘__flbf’ function will return a nonzero value in case the
|
stream STREAM is line buffered. Otherwise the return value is
|
zero.
|
|
This function is declared in the ‘stdio_ext.h’ header.
|
|
Two more extensions allow to determine the size of the buffer and how
|
much of it is used. These functions were also introduced in Solaris.
|
|
-- Function: size_t __fbufsize (FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe |
|
*Note POSIX Safety Concepts::.
|
|
The ‘__fbufsize’ function return the size of the buffer in the
|
stream STREAM. This value can be used to optimize the use of the
|
stream.
|
|
This function is declared in the ‘stdio_ext.h’ header.
|
|
-- Function: size_t __fpending (FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe |
|
*Note POSIX Safety Concepts::.
|
|
The ‘__fpending’ function returns the number of bytes currently in
|
the output buffer. For wide-oriented streams the measuring unit is
|
wide characters. This function should not be used on buffers in
|
read mode or opened read-only.
|
|
This function is declared in the ‘stdio_ext.h’ header.
|
|
|
File: libc.info, Node: Other Kinds of Streams, Next: Formatted Messages, Prev: Stream Buffering, Up: I/O on Streams
|
|
12.21 Other Kinds of Streams
|
============================
|
|
The GNU C Library provides ways for you to define additional kinds of
|
streams that do not necessarily correspond to an open file.
|
|
One such type of stream takes input from or writes output to a
|
string. These kinds of streams are used internally to implement the
|
‘sprintf’ and ‘sscanf’ functions. You can also create such a stream
|
explicitly, using the functions described in *note String Streams::.
|
|
More generally, you can define streams that do input/output to
|
arbitrary objects using functions supplied by your program. This
|
protocol is discussed in *note Custom Streams::.
|
|
*Portability Note:* The facilities described in this section are
|
specific to GNU. Other systems or C implementations might or might not
|
provide equivalent functionality.
|
|
* Menu:
|
|
* String Streams:: Streams that get data from or put data in
|
a string or memory buffer.
|
* Custom Streams:: Defining your own streams with an arbitrary
|
input data source and/or output data sink.
|
|
|
File: libc.info, Node: String Streams, Next: Custom Streams, Up: Other Kinds of Streams
|
|
12.21.1 String Streams
|
----------------------
|
|
The ‘fmemopen’ and ‘open_memstream’ functions allow you to do I/O to a
|
string or memory buffer. These facilities are declared in ‘stdio.h’.
|
|
-- Function: FILE * fmemopen (void *BUF, size_t SIZE, const char
|
*OPENTYPE)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
|
*Note POSIX Safety Concepts::.
|
|
This function opens a stream that allows the access specified by
|
the OPENTYPE argument, that reads from or writes to the buffer
|
specified by the argument BUF. This array must be at least SIZE
|
bytes long.
|
|
If you specify a null pointer as the BUF argument, ‘fmemopen’
|
dynamically allocates an array SIZE bytes long (as with ‘malloc’;
|
*note Unconstrained Allocation::). This is really only useful if
|
you are going to write things to the buffer and then read them back
|
in again, because you have no way of actually getting a pointer to
|
the buffer (for this, try ‘open_memstream’, below). The buffer is
|
freed when the stream is closed.
|
|
The argument OPENTYPE is the same as in ‘fopen’ (*note Opening
|
Streams::). If the OPENTYPE specifies append mode, then the
|
initial file position is set to the first null character in the
|
buffer. Otherwise the initial file position is at the beginning of
|
the buffer.
|
|
When a stream open for writing is flushed or closed, a null
|
character (zero byte) is written at the end of the buffer if it
|
fits. You should add an extra byte to the SIZE argument to account
|
for this. Attempts to write more than SIZE bytes to the buffer
|
result in an error.
|
|
For a stream open for reading, null characters (zero bytes) in the
|
buffer do not count as “end of file”. Read operations indicate end
|
of file only when the file position advances past SIZE bytes. So,
|
if you want to read characters from a null-terminated string, you
|
should supply the length of the string as the SIZE argument.
|
|
Here is an example of using ‘fmemopen’ to create a stream for reading
|
from a string:
|
|
|
#include <stdio.h>
|
|
static char buffer[] = "foobar";
|
|
int
|
main (void)
|
{
|
int ch;
|
FILE *stream;
|
|
stream = fmemopen (buffer, strlen (buffer), "r");
|
while ((ch = fgetc (stream)) != EOF)
|
printf ("Got %c\n", ch);
|
fclose (stream);
|
|
return 0;
|
}
|
|
This program produces the following output:
|
|
Got f
|
Got o
|
Got o
|
Got b
|
Got a
|
Got r
|
|
-- Function: FILE * open_memstream (char **PTR, size_t *SIZELOC)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
This function opens a stream for writing to a buffer. The buffer
|
is allocated dynamically and grown as necessary, using ‘malloc’.
|
After you’ve closed the stream, this buffer is your responsibility
|
to clean up using ‘free’ or ‘realloc’. *Note Unconstrained
|
Allocation::.
|
|
When the stream is closed with ‘fclose’ or flushed with ‘fflush’,
|
the locations PTR and SIZELOC are updated to contain the pointer to
|
the buffer and its size. The values thus stored remain valid only
|
as long as no further output on the stream takes place. If you do
|
more output, you must flush the stream again to store new values
|
before you use them again.
|
|
A null character is written at the end of the buffer. This null
|
character is _not_ included in the size value stored at SIZELOC.
|
|
You can move the stream’s file position with ‘fseek’ or ‘fseeko’
|
(*note File Positioning::). Moving the file position past the end
|
of the data already written fills the intervening space with
|
zeroes.
|
|
Here is an example of using ‘open_memstream’:
|
|
|
#include <stdio.h>
|
|
int
|
main (void)
|
{
|
char *bp;
|
size_t size;
|
FILE *stream;
|
|
stream = open_memstream (&bp, &size);
|
fprintf (stream, "hello");
|
fflush (stream);
|
printf ("buf = `%s', size = %zu\n", bp, size);
|
fprintf (stream, ", world");
|
fclose (stream);
|
printf ("buf = `%s', size = %zu\n", bp, size);
|
|
return 0;
|
}
|
|
This program produces the following output:
|
|
buf = `hello', size = 5
|
buf = `hello, world', size = 12
|
|
|
File: libc.info, Node: Custom Streams, Prev: String Streams, Up: Other Kinds of Streams
|
|
12.21.2 Programming Your Own Custom Streams
|
-------------------------------------------
|
|
This section describes how you can make a stream that gets input from an
|
arbitrary data source or writes output to an arbitrary data sink
|
programmed by you. We call these "custom streams". The functions and
|
types described here are all GNU extensions.
|
|
* Menu:
|
|
* Streams and Cookies:: The "cookie" records where to fetch or
|
store data that is read or written.
|
* Hook Functions:: How you should define the four "hook
|
functions" that a custom stream needs.
|
|
|
File: libc.info, Node: Streams and Cookies, Next: Hook Functions, Up: Custom Streams
|
|
12.21.2.1 Custom Streams and Cookies
|
....................................
|
|
Inside every custom stream is a special object called the "cookie".
|
This is an object supplied by you which records where to fetch or store
|
the data read or written. It is up to you to define a data type to use
|
for the cookie. The stream functions in the library never refer
|
directly to its contents, and they don’t even know what the type is;
|
they record its address with type ‘void *’.
|
|
To implement a custom stream, you must specify _how_ to fetch or
|
store the data in the specified place. You do this by defining "hook
|
functions" to read, write, change “file position”, and close the stream.
|
All four of these functions will be passed the stream’s cookie so they
|
can tell where to fetch or store the data. The library functions don’t
|
know what’s inside the cookie, but your functions will know.
|
|
When you create a custom stream, you must specify the cookie pointer,
|
and also the four hook functions stored in a structure of type
|
‘cookie_io_functions_t’.
|
|
These facilities are declared in ‘stdio.h’.
|
|
-- Data Type: cookie_io_functions_t
|
|
This is a structure type that holds the functions that define the
|
communications protocol between the stream and its cookie. It has
|
the following members:
|
|
‘cookie_read_function_t *read’
|
This is the function that reads data from the cookie. If the
|
value is a null pointer instead of a function, then read
|
operations on this stream always return ‘EOF’.
|
|
‘cookie_write_function_t *write’
|
This is the function that writes data to the cookie. If the
|
value is a null pointer instead of a function, then data
|
written to the stream is discarded.
|
|
‘cookie_seek_function_t *seek’
|
This is the function that performs the equivalent of file
|
positioning on the cookie. If the value is a null pointer
|
instead of a function, calls to ‘fseek’ or ‘fseeko’ on this
|
stream can only seek to locations within the buffer; any
|
attempt to seek outside the buffer will return an ‘ESPIPE’
|
error.
|
|
‘cookie_close_function_t *close’
|
This function performs any appropriate cleanup on the cookie
|
when closing the stream. If the value is a null pointer
|
instead of a function, nothing special is done to close the
|
cookie when the stream is closed.
|
|
-- Function: FILE * fopencookie (void *COOKIE, const char *OPENTYPE,
|
cookie_io_functions_t IO-FUNCTIONS)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
|
*Note POSIX Safety Concepts::.
|
|
This function actually creates the stream for communicating with
|
the COOKIE using the functions in the IO-FUNCTIONS argument. The
|
OPENTYPE argument is interpreted as for ‘fopen’; see *note Opening
|
Streams::. (But note that the “truncate on open” option is
|
ignored.) The new stream is fully buffered.
|
|
The ‘fopencookie’ function returns the newly created stream, or a
|
null pointer in case of an error.
|
|
|
File: libc.info, Node: Hook Functions, Prev: Streams and Cookies, Up: Custom Streams
|
|
12.21.2.2 Custom Stream Hook Functions
|
......................................
|
|
Here are more details on how you should define the four hook functions
|
that a custom stream needs.
|
|
You should define the function to read data from the cookie as:
|
|
ssize_t READER (void *COOKIE, char *BUFFER, size_t SIZE)
|
|
This is very similar to the ‘read’ function; see *note I/O
|
Primitives::. Your function should transfer up to SIZE bytes into the
|
BUFFER, and return the number of bytes read, or zero to indicate
|
end-of-file. You can return a value of ‘-1’ to indicate an error.
|
|
You should define the function to write data to the cookie as:
|
|
ssize_t WRITER (void *COOKIE, const char *BUFFER, size_t SIZE)
|
|
This is very similar to the ‘write’ function; see *note I/O
|
Primitives::. Your function should transfer up to SIZE bytes from the
|
buffer, and return the number of bytes written. You can return a value
|
of ‘0’ to indicate an error. You must not return any negative value.
|
|
You should define the function to perform seek operations on the
|
cookie as:
|
|
int SEEKER (void *COOKIE, off64_t *POSITION, int WHENCE)
|
|
For this function, the POSITION and WHENCE arguments are interpreted
|
as for ‘fgetpos’; see *note Portable Positioning::.
|
|
After doing the seek operation, your function should store the
|
resulting file position relative to the beginning of the file in
|
POSITION. Your function should return a value of ‘0’ on success and
|
‘-1’ to indicate an error.
|
|
You should define the function to do cleanup operations on the cookie
|
appropriate for closing the stream as:
|
|
int CLEANER (void *COOKIE)
|
|
Your function should return ‘-1’ to indicate an error, and ‘0’
|
otherwise.
|
|
-- Data Type: cookie_read_function_t
|
|
This is the data type that the read function for a custom stream
|
should have. If you declare the function as shown above, this is
|
the type it will have.
|
|
-- Data Type: cookie_write_function_t
|
|
The data type of the write function for a custom stream.
|
|
-- Data Type: cookie_seek_function_t
|
|
The data type of the seek function for a custom stream.
|
|
-- Data Type: cookie_close_function_t
|
|
The data type of the close function for a custom stream.
|
|
|
File: libc.info, Node: Formatted Messages, Prev: Other Kinds of Streams, Up: I/O on Streams
|
|
12.22 Formatted Messages
|
========================
|
|
On systems which are based on System V messages of programs (especially
|
the system tools) are printed in a strict form using the ‘fmtmsg’
|
function. The uniformity sometimes helps the user to interpret messages
|
and the strictness tests of the ‘fmtmsg’ function ensure that the
|
programmer follows some minimal requirements.
|
|
* Menu:
|
|
* Printing Formatted Messages:: The ‘fmtmsg’ function.
|
* Adding Severity Classes:: Add more severity classes.
|
* Example:: How to use ‘fmtmsg’ and ‘addseverity’.
|
|
|
File: libc.info, Node: Printing Formatted Messages, Next: Adding Severity Classes, Up: Formatted Messages
|
|
12.22.1 Printing Formatted Messages
|
-----------------------------------
|
|
Messages can be printed to standard error and/or to the console. To
|
select the destination the programmer can use the following two values,
|
bitwise OR combined if wanted, for the CLASSIFICATION parameter of
|
‘fmtmsg’:
|
|
‘MM_PRINT’
|
Display the message in standard error.
|
‘MM_CONSOLE’
|
Display the message on the system console.
|
|
The erroneous piece of the system can be signalled by exactly one of
|
the following values which also is bitwise ORed with the CLASSIFICATION
|
parameter to ‘fmtmsg’:
|
|
‘MM_HARD’
|
The source of the condition is some hardware.
|
‘MM_SOFT’
|
The source of the condition is some software.
|
‘MM_FIRM’
|
The source of the condition is some firmware.
|
|
A third component of the CLASSIFICATION parameter to ‘fmtmsg’ can
|
describe the part of the system which detects the problem. This is done
|
by using exactly one of the following values:
|
|
‘MM_APPL’
|
The erroneous condition is detected by the application.
|
‘MM_UTIL’
|
The erroneous condition is detected by a utility.
|
‘MM_OPSYS’
|
The erroneous condition is detected by the operating system.
|
|
A last component of CLASSIFICATION can signal the results of this
|
message. Exactly one of the following values can be used:
|
|
‘MM_RECOVER’
|
It is a recoverable error.
|
‘MM_NRECOV’
|
It is a non-recoverable error.
|
|
-- Function: int fmtmsg (long int CLASSIFICATION, const char *LABEL,
|
int SEVERITY, const char *TEXT, const char *ACTION, const char
|
*TAG)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
Display a message described by its parameters on the device(s)
|
specified in the CLASSIFICATION parameter. The LABEL parameter
|
identifies the source of the message. The string should consist of
|
two colon separated parts where the first part has not more than 10
|
and the second part not more than 14 characters. The TEXT
|
parameter describes the condition of the error, the ACTION
|
parameter possible steps to recover from the error and the TAG
|
parameter is a reference to the online documentation where more
|
information can be found. It should contain the LABEL value and a
|
unique identification number.
|
|
Each of the parameters can be a special value which means this
|
value is to be omitted. The symbolic names for these values are:
|
|
‘MM_NULLLBL’
|
Ignore LABEL parameter.
|
‘MM_NULLSEV’
|
Ignore SEVERITY parameter.
|
‘MM_NULLMC’
|
Ignore CLASSIFICATION parameter. This implies that nothing is
|
actually printed.
|
‘MM_NULLTXT’
|
Ignore TEXT parameter.
|
‘MM_NULLACT’
|
Ignore ACTION parameter.
|
‘MM_NULLTAG’
|
Ignore TAG parameter.
|
|
There is another way certain fields can be omitted from the output
|
to standard error. This is described below in the description of
|
environment variables influencing the behavior.
|
|
The SEVERITY parameter can have one of the values in the following
|
table:
|
|
‘MM_NOSEV’
|
Nothing is printed, this value is the same as ‘MM_NULLSEV’.
|
‘MM_HALT’
|
This value is printed as ‘HALT’.
|
‘MM_ERROR’
|
This value is printed as ‘ERROR’.
|
‘MM_WARNING’
|
This value is printed as ‘WARNING’.
|
‘MM_INFO’
|
This value is printed as ‘INFO’.
|
|
The numeric value of these five macros are between ‘0’ and ‘4’.
|
Using the environment variable ‘SEV_LEVEL’ or using the
|
‘addseverity’ function one can add more severity levels with their
|
corresponding string to print. This is described below (*note
|
Adding Severity Classes::).
|
|
If no parameter is ignored the output looks like this:
|
|
LABEL: SEVERITY-STRING: TEXT
|
TO FIX: ACTION TAG
|
|
The colons, new line characters and the ‘TO FIX’ string are
|
inserted if necessary, i.e., if the corresponding parameter is not
|
ignored.
|
|
This function is specified in the X/Open Portability Guide. It is
|
also available on all systems derived from System V.
|
|
The function returns the value ‘MM_OK’ if no error occurred. If
|
only the printing to standard error failed, it returns ‘MM_NOMSG’.
|
If printing to the console fails, it returns ‘MM_NOCON’. If
|
nothing is printed ‘MM_NOTOK’ is returned. Among situations where
|
all outputs fail this last value is also returned if a parameter
|
value is incorrect.
|
|
There are two environment variables which influence the behavior of
|
‘fmtmsg’. The first is ‘MSGVERB’. It is used to control the output
|
actually happening on standard error (_not_ the console output). Each
|
of the five fields can explicitly be enabled. To do this the user has
|
to put the ‘MSGVERB’ variable with a format like the following in the
|
environment before calling the ‘fmtmsg’ function the first time:
|
|
MSGVERB=KEYWORD[:KEYWORD[:…]]
|
|
Valid KEYWORDs are ‘label’, ‘severity’, ‘text’, ‘action’, and ‘tag’.
|
If the environment variable is not given or is the empty string, a not
|
supported keyword is given or the value is somehow else invalid, no part
|
of the message is masked out.
|
|
The second environment variable which influences the behavior of
|
‘fmtmsg’ is ‘SEV_LEVEL’. This variable and the change in the behavior
|
of ‘fmtmsg’ is not specified in the X/Open Portability Guide. It is
|
available in System V systems, though. It can be used to introduce new
|
severity levels. By default, only the five severity levels described
|
above are available. Any other numeric value would make ‘fmtmsg’ print
|
nothing.
|
|
If the user puts ‘SEV_LEVEL’ with a format like
|
|
SEV_LEVEL=[DESCRIPTION[:DESCRIPTION[:…]]]
|
|
in the environment of the process before the first call to ‘fmtmsg’,
|
where DESCRIPTION has a value of the form
|
|
SEVERITY-KEYWORD,LEVEL,PRINTSTRING
|
|
The SEVERITY-KEYWORD part is not used by ‘fmtmsg’ but it has to be
|
present. The LEVEL part is a string representation of a number. The
|
numeric value must be a number greater than 4. This value must be used
|
in the SEVERITY parameter of ‘fmtmsg’ to select this class. It is not
|
possible to overwrite any of the predefined classes. The PRINTSTRING is
|
the string printed when a message of this class is processed by ‘fmtmsg’
|
(see above, ‘fmtsmg’ does not print the numeric value but instead the
|
string representation).
|
|
|
File: libc.info, Node: Adding Severity Classes, Next: Example, Prev: Printing Formatted Messages, Up: Formatted Messages
|
|
12.22.2 Adding Severity Classes
|
-------------------------------
|
|
There is another possibility to introduce severity classes besides using
|
the environment variable ‘SEV_LEVEL’. This simplifies the task of
|
introducing new classes in a running program. One could use the
|
‘setenv’ or ‘putenv’ function to set the environment variable, but this
|
is toilsome.
|
|
-- Function: int addseverity (int SEVERITY, const char *STRING)
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function allows the introduction of new severity classes which
|
can be addressed by the SEVERITY parameter of the ‘fmtmsg’
|
function. The SEVERITY parameter of ‘addseverity’ must match the
|
value for the parameter with the same name of ‘fmtmsg’, and STRING
|
is the string printed in the actual messages instead of the numeric
|
value.
|
|
If STRING is ‘NULL’ the severity class with the numeric value
|
according to SEVERITY is removed.
|
|
It is not possible to overwrite or remove one of the default
|
severity classes. All calls to ‘addseverity’ with SEVERITY set to
|
one of the values for the default classes will fail.
|
|
The return value is ‘MM_OK’ if the task was successfully performed.
|
If the return value is ‘MM_NOTOK’ something went wrong. This could
|
mean that no more memory is available or a class is not available
|
when it has to be removed.
|
|
This function is not specified in the X/Open Portability Guide
|
although the ‘fmtsmg’ function is. It is available on System V
|
systems.
|
|
|
File: libc.info, Node: Example, Prev: Adding Severity Classes, Up: Formatted Messages
|
|
12.22.3 How to use ‘fmtmsg’ and ‘addseverity’
|
---------------------------------------------
|
|
Here is a simple example program to illustrate the use of both functions
|
described in this section.
|
|
|
#include <fmtmsg.h>
|
|
int
|
main (void)
|
{
|
addseverity (5, "NOTE2");
|
fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2");
|
fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual",
|
"UX:cat:001");
|
fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag");
|
return 0;
|
}
|
|
The second call to ‘fmtmsg’ illustrates a use of this function as it
|
usually occurs on System V systems, which heavily use this function. It
|
seems worthwhile to give a short explanation here of how this system
|
works on System V. The value of the LABEL field (‘UX:cat’) says that the
|
error occurred in the Unix program ‘cat’. The explanation of the error
|
follows and the value for the ACTION parameter is ‘"refer to manual"’.
|
One could be more specific here, if necessary. The TAG field contains,
|
as proposed above, the value of the string given for the LABEL
|
parameter, and additionally a unique ID (‘001’ in this case). For a GNU
|
environment this string could contain a reference to the corresponding
|
node in the Info page for the program.
|
|
Running this program without specifying the ‘MSGVERB’ and ‘SEV_LEVEL’
|
function produces the following output:
|
|
UX:cat: NOTE2: invalid syntax
|
TO FIX: refer to manual UX:cat:001
|
|
We see the different fields of the message and how the extra glue
|
(the colons and the ‘TO FIX’ string) is printed. But only one of the
|
three calls to ‘fmtmsg’ produced output. The first call does not print
|
anything because the LABEL parameter is not in the correct form. The
|
string must contain two fields, separated by a colon (*note Printing
|
Formatted Messages::). The third ‘fmtmsg’ call produced no output since
|
the class with the numeric value ‘6’ is not defined. Although a class
|
with numeric value ‘5’ is also not defined by default, the call to
|
‘addseverity’ introduces it and the second call to ‘fmtmsg’ produces the
|
above output.
|
|
When we change the environment of the program to contain
|
‘SEV_LEVEL=XXX,6,NOTE’ when running it we get a different result:
|
|
UX:cat: NOTE2: invalid syntax
|
TO FIX: refer to manual UX:cat:001
|
label:foo: NOTE: text
|
TO FIX: action tag
|
|
Now the third call to ‘fmtmsg’ produced some output and we see how
|
the string ‘NOTE’ from the environment variable appears in the message.
|
|
Now we can reduce the output by specifying which fields we are
|
interested in. If we additionally set the environment variable
|
‘MSGVERB’ to the value ‘severity:label:action’ we get the following
|
output:
|
|
UX:cat: NOTE2
|
TO FIX: refer to manual
|
label:foo: NOTE
|
TO FIX: action
|
|
I.e., the output produced by the TEXT and the TAG parameters to ‘fmtmsg’
|
vanished. Please also note that now there is no colon after the ‘NOTE’
|
and ‘NOTE2’ strings in the output. This is not necessary since there is
|
no more output on this line because the text is missing.
|
|
|
File: libc.info, Node: Low-Level I/O, Next: File System Interface, Prev: I/O on Streams, Up: Top
|
|
13 Low-Level Input/Output
|
*************************
|
|
This chapter describes functions for performing low-level input/output
|
operations on file descriptors. These functions include the primitives
|
for the higher-level I/O functions described in *note I/O on Streams::,
|
as well as functions for performing low-level control operations for
|
which there are no equivalents on streams.
|
|
Stream-level I/O is more flexible and usually more convenient;
|
therefore, programmers generally use the descriptor-level functions only
|
when necessary. These are some of the usual reasons:
|
|
• For reading binary files in large chunks.
|
|
• For reading an entire file into core before parsing it.
|
|
• To perform operations other than data transfer, which can only be
|
done with a descriptor. (You can use ‘fileno’ to get the
|
descriptor corresponding to a stream.)
|
|
• To pass descriptors to a child process. (The child can create its
|
own stream to use a descriptor that it inherits, but cannot inherit
|
a stream directly.)
|
|
* Menu:
|
|
* Opening and Closing Files:: How to open and close file
|
descriptors.
|
* I/O Primitives:: Reading and writing data.
|
* File Position Primitive:: Setting a descriptor’s file
|
position.
|
* Descriptors and Streams:: Converting descriptor to stream
|
or vice-versa.
|
* Stream/Descriptor Precautions:: Precautions needed if you use both
|
descriptors and streams.
|
* Scatter-Gather:: Fast I/O to discontinuous buffers.
|
* Copying File Data:: Copying data between files.
|
* Memory-mapped I/O:: Using files like memory.
|
* Waiting for I/O:: How to check for input or output
|
on multiple file descriptors.
|
* Synchronizing I/O:: Making sure all I/O actions completed.
|
* Asynchronous I/O:: Perform I/O in parallel.
|
* Control Operations:: Various other operations on file
|
descriptors.
|
* Duplicating Descriptors:: Fcntl commands for duplicating
|
file descriptors.
|
* Descriptor Flags:: Fcntl commands for manipulating
|
flags associated with file
|
descriptors.
|
* File Status Flags:: Fcntl commands for manipulating
|
flags associated with open files.
|
* File Locks:: Fcntl commands for implementing
|
file locking.
|
* Open File Description Locks:: Fcntl commands for implementing
|
open file description locking.
|
* Open File Description Locks Example:: An example of open file description lock
|
usage
|
* Interrupt Input:: Getting an asynchronous signal when
|
input arrives.
|
* IOCTLs:: Generic I/O Control operations.
|
|
|
File: libc.info, Node: Opening and Closing Files, Next: I/O Primitives, Up: Low-Level I/O
|
|
13.1 Opening and Closing Files
|
==============================
|
|
This section describes the primitives for opening and closing files
|
using file descriptors. The ‘open’ and ‘creat’ functions are declared
|
in the header file ‘fcntl.h’, while ‘close’ is declared in ‘unistd.h’.
|
|
-- Function: int open (const char *FILENAME, int FLAGS[, mode_t MODE])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘open’ function creates and returns a new file descriptor for
|
the file named by FILENAME. Initially, the file position indicator
|
for the file is at the beginning of the file. The argument MODE
|
(*note Permission Bits::) is used only when a file is created, but
|
it doesn’t hurt to supply the argument in any case.
|
|
The FLAGS argument controls how the file is to be opened. This is
|
a bit mask; you create the value by the bitwise OR of the
|
appropriate parameters (using the ‘|’ operator in C). *Note File
|
Status Flags::, for the parameters available.
|
|
The normal return value from ‘open’ is a non-negative integer file
|
descriptor. In the case of an error, a value of -1 is returned
|
instead. In addition to the usual file name errors (*note File
|
Name Errors::), the following ‘errno’ error conditions are defined
|
for this function:
|
|
‘EACCES’
|
The file exists but is not readable/writable as requested by
|
the FLAGS argument, or the file does not exist and the
|
directory is unwritable so it cannot be created.
|
|
‘EEXIST’
|
Both ‘O_CREAT’ and ‘O_EXCL’ are set, and the named file
|
already exists.
|
|
‘EINTR’
|
The ‘open’ operation was interrupted by a signal. *Note
|
Interrupted Primitives::.
|
|
‘EISDIR’
|
The FLAGS argument specified write access, and the file is a
|
directory.
|
|
‘EMFILE’
|
The process has too many files open. The maximum number of
|
file descriptors is controlled by the ‘RLIMIT_NOFILE’ resource
|
limit; *note Limits on Resources::.
|
|
‘ENFILE’
|
The entire system, or perhaps the file system which contains
|
the directory, cannot support any additional open files at the
|
moment. (This problem cannot happen on GNU/Hurd systems.)
|
|
‘ENOENT’
|
The named file does not exist, and ‘O_CREAT’ is not specified.
|
|
‘ENOSPC’
|
The directory or file system that would contain the new file
|
cannot be extended, because there is no disk space left.
|
|
‘ENXIO’
|
‘O_NONBLOCK’ and ‘O_WRONLY’ are both set in the FLAGS
|
argument, the file named by FILENAME is a FIFO (*note Pipes
|
and FIFOs::), and no process has the file open for reading.
|
|
‘EROFS’
|
The file resides on a read-only file system and any of
|
‘O_WRONLY’, ‘O_RDWR’, and ‘O_TRUNC’ are set in the FLAGS
|
argument, or ‘O_CREAT’ is set and the file does not already
|
exist.
|
|
If on a 32 bit machine the sources are translated with
|
‘_FILE_OFFSET_BITS == 64’ the function ‘open’ returns a file
|
descriptor opened in the large file mode which enables the file
|
handling functions to use files up to 2^63 bytes in size and offset
|
from −2^63 to 2^63. This happens transparently for the user since
|
all of the low-level file handling functions are equally replaced.
|
|
This function is a cancellation point in multi-threaded programs.
|
This is a problem if the thread allocates some resources (like
|
memory, file descriptors, semaphores or whatever) at the time
|
‘open’ is called. If the thread gets canceled these resources stay
|
allocated until the program ends. To avoid this calls to ‘open’
|
should be protected using cancellation handlers.
|
|
The ‘open’ function is the underlying primitive for the ‘fopen’ and
|
‘freopen’ functions, that create streams.
|
|
-- Function: int open64 (const char *FILENAME, int FLAGS[, mode_t
|
MODE])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to ‘open’. It returns a file descriptor
|
which can be used to access the file named by FILENAME. The only
|
difference is that on 32 bit systems the file is opened in the
|
large file mode. I.e., file length and file offsets can exceed 31
|
bits.
|
|
When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
|
function is actually available under the name ‘open’. I.e., the
|
new, extended API using 64 bit file sizes and offsets transparently
|
replaces the old API.
|
|
-- Obsolete function: int creat (const char *FILENAME, mode_t MODE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
This function is obsolete. The call:
|
|
creat (FILENAME, MODE)
|
|
is equivalent to:
|
|
open (FILENAME, O_WRONLY | O_CREAT | O_TRUNC, MODE)
|
|
If on a 32 bit machine the sources are translated with
|
‘_FILE_OFFSET_BITS == 64’ the function ‘creat’ returns a file
|
descriptor opened in the large file mode which enables the file
|
handling functions to use files up to 2^63 in size and offset from
|
−2^63 to 2^63. This happens transparently for the user since all
|
of the low-level file handling functions are equally replaced.
|
|
-- Obsolete function: int creat64 (const char *FILENAME, mode_t MODE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to ‘creat’. It returns a file descriptor
|
which can be used to access the file named by FILENAME. The only
|
difference is that on 32 bit systems the file is opened in the
|
large file mode. I.e., file length and file offsets can exceed 31
|
bits.
|
|
To use this file descriptor one must not use the normal operations
|
but instead the counterparts named ‘*64’, e.g., ‘read64’.
|
|
When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
|
function is actually available under the name ‘open’. I.e., the
|
new, extended API using 64 bit file sizes and offsets transparently
|
replaces the old API.
|
|
-- Function: int close (int FILEDES)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
The function ‘close’ closes the file descriptor FILEDES. Closing a
|
file has the following consequences:
|
|
• The file descriptor is deallocated.
|
|
• Any record locks owned by the process on the file are
|
unlocked.
|
|
• When all file descriptors associated with a pipe or FIFO have
|
been closed, any unread data is discarded.
|
|
This function is a cancellation point in multi-threaded programs.
|
This is a problem if the thread allocates some resources (like
|
memory, file descriptors, semaphores or whatever) at the time
|
‘close’ is called. If the thread gets canceled these resources
|
stay allocated until the program ends. To avoid this, calls to
|
‘close’ should be protected using cancellation handlers.
|
|
The normal return value from ‘close’ is 0; a value of -1 is
|
returned in case of failure. The following ‘errno’ error
|
conditions are defined for this function:
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor.
|
|
‘EINTR’
|
The ‘close’ call was interrupted by a signal. *Note
|
Interrupted Primitives::. Here is an example of how to handle
|
‘EINTR’ properly:
|
|
TEMP_FAILURE_RETRY (close (desc));
|
|
‘ENOSPC’
|
‘EIO’
|
‘EDQUOT’
|
When the file is accessed by NFS, these errors from ‘write’
|
can sometimes not be detected until ‘close’. *Note I/O
|
Primitives::, for details on their meaning.
|
|
Please note that there is _no_ separate ‘close64’ function. This
|
is not necessary since this function does not determine nor depend
|
on the mode of the file. The kernel which performs the ‘close’
|
operation knows which mode the descriptor is used for and can
|
handle this situation.
|
|
To close a stream, call ‘fclose’ (*note Closing Streams::) instead of
|
trying to close its underlying file descriptor with ‘close’. This
|
flushes any buffered output and updates the stream object to indicate
|
that it is closed.
|
|
|
File: libc.info, Node: I/O Primitives, Next: File Position Primitive, Prev: Opening and Closing Files, Up: Low-Level I/O
|
|
13.2 Input and Output Primitives
|
================================
|
|
This section describes the functions for performing primitive input and
|
output operations on file descriptors: ‘read’, ‘write’, and ‘lseek’.
|
These functions are declared in the header file ‘unistd.h’.
|
|
-- Data Type: ssize_t
|
|
This data type is used to represent the sizes of blocks that can be
|
read or written in a single operation. It is similar to ‘size_t’,
|
but must be a signed type.
|
|
-- Function: ssize_t read (int FILEDES, void *BUFFER, size_t SIZE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘read’ function reads up to SIZE bytes from the file with
|
descriptor FILEDES, storing the results in the BUFFER. (This is
|
not necessarily a character string, and no terminating null
|
character is added.)
|
|
The return value is the number of bytes actually read. This might
|
be less than SIZE; for example, if there aren’t that many bytes
|
left in the file or if there aren’t that many bytes immediately
|
available. The exact behavior depends on what kind of file it is.
|
Note that reading less than SIZE bytes is not an error.
|
|
A value of zero indicates end-of-file (except if the value of the
|
SIZE argument is also zero). This is not considered an error. If
|
you keep calling ‘read’ while at end-of-file, it will keep
|
returning zero and doing nothing else.
|
|
If ‘read’ returns at least one character, there is no way you can
|
tell whether end-of-file was reached. But if you did reach the
|
end, the next read will return zero.
|
|
In case of an error, ‘read’ returns -1. The following ‘errno’
|
error conditions are defined for this function:
|
|
‘EAGAIN’
|
Normally, when no input is immediately available, ‘read’ waits
|
for some input. But if the ‘O_NONBLOCK’ flag is set for the
|
file (*note File Status Flags::), ‘read’ returns immediately
|
without reading any data, and reports this error.
|
|
*Compatibility Note:* Most versions of BSD Unix use a
|
different error code for this: ‘EWOULDBLOCK’. In the GNU C
|
Library, ‘EWOULDBLOCK’ is an alias for ‘EAGAIN’, so it doesn’t
|
matter which name you use.
|
|
On some systems, reading a large amount of data from a
|
character special file can also fail with ‘EAGAIN’ if the
|
kernel cannot find enough physical memory to lock down the
|
user’s pages. This is limited to devices that transfer with
|
direct memory access into the user’s memory, which means it
|
does not include terminals, since they always use separate
|
buffers inside the kernel. This problem never happens on
|
GNU/Hurd systems.
|
|
Any condition that could result in ‘EAGAIN’ can instead result
|
in a successful ‘read’ which returns fewer bytes than
|
requested. Calling ‘read’ again immediately would result in
|
‘EAGAIN’.
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor, or is not
|
open for reading.
|
|
‘EINTR’
|
‘read’ was interrupted by a signal while it was waiting for
|
input. *Note Interrupted Primitives::. A signal will not
|
necessarily cause ‘read’ to return ‘EINTR’; it may instead
|
result in a successful ‘read’ which returns fewer bytes than
|
requested.
|
|
‘EIO’
|
For many devices, and for disk files, this error code
|
indicates a hardware error.
|
|
‘EIO’ also occurs when a background process tries to read from
|
the controlling terminal, and the normal action of stopping
|
the process by sending it a ‘SIGTTIN’ signal isn’t working.
|
This might happen if the signal is being blocked or ignored,
|
or because the process group is orphaned. *Note Job
|
Control::, for more information about job control, and *note
|
Signal Handling::, for information about signals.
|
|
‘EINVAL’
|
In some systems, when reading from a character or block
|
device, position and size offsets must be aligned to a
|
particular block size. This error indicates that the offsets
|
were not properly aligned.
|
|
Please note that there is no function named ‘read64’. This is not
|
necessary since this function does not directly modify or handle
|
the possibly wide file offset. Since the kernel handles this state
|
internally, the ‘read’ function can be used for all cases.
|
|
This function is a cancellation point in multi-threaded programs.
|
This is a problem if the thread allocates some resources (like
|
memory, file descriptors, semaphores or whatever) at the time
|
‘read’ is called. If the thread gets canceled these resources stay
|
allocated until the program ends. To avoid this, calls to ‘read’
|
should be protected using cancellation handlers.
|
|
The ‘read’ function is the underlying primitive for all of the
|
functions that read from streams, such as ‘fgetc’.
|
|
-- Function: ssize_t pread (int FILEDES, void *BUFFER, size_t SIZE,
|
off_t OFFSET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘pread’ function is similar to the ‘read’ function. The first
|
three arguments are identical, and the return values and error
|
codes also correspond.
|
|
The difference is the fourth argument and its handling. The data
|
block is not read from the current position of the file descriptor
|
‘filedes’. Instead the data is read from the file starting at
|
position OFFSET. The position of the file descriptor itself is not
|
affected by the operation. The value is the same as before the
|
call.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
|
‘pread’ function is in fact ‘pread64’ and the type ‘off_t’ has 64
|
bits, which makes it possible to handle files up to 2^63 bytes in
|
length.
|
|
The return value of ‘pread’ describes the number of bytes read. In
|
the error case it returns -1 like ‘read’ does and the error codes
|
are also the same, with these additions:
|
|
‘EINVAL’
|
The value given for OFFSET is negative and therefore illegal.
|
|
‘ESPIPE’
|
The file descriptor FILEDES is associated with a pipe or a
|
FIFO and this device does not allow positioning of the file
|
pointer.
|
|
The function is an extension defined in the Unix Single
|
Specification version 2.
|
|
-- Function: ssize_t pread64 (int FILEDES, void *BUFFER, size_t SIZE,
|
off64_t OFFSET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘pread’ function. The difference
|
is that the OFFSET parameter is of type ‘off64_t’ instead of
|
‘off_t’ which makes it possible on 32 bit machines to address files
|
larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
|
‘filedes’ must be opened using ‘open64’ since otherwise the large
|
offsets possible with ‘off64_t’ will lead to errors with a
|
descriptor in small file mode.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ on
|
a 32 bit machine this function is actually available under the name
|
‘pread’ and so transparently replaces the 32 bit interface.
|
|
-- Function: ssize_t write (int FILEDES, const void *BUFFER, size_t
|
SIZE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘write’ function writes up to SIZE bytes from BUFFER to the
|
file with descriptor FILEDES. The data in BUFFER is not
|
necessarily a character string and a null character is output like
|
any other character.
|
|
The return value is the number of bytes actually written. This may
|
be SIZE, but can always be smaller. Your program should always
|
call ‘write’ in a loop, iterating until all the data is written.
|
|
Once ‘write’ returns, the data is enqueued to be written and can be
|
read back right away, but it is not necessarily written out to
|
permanent storage immediately. You can use ‘fsync’ when you need
|
to be sure your data has been permanently stored before continuing.
|
(It is more efficient for the system to batch up consecutive writes
|
and do them all at once when convenient. Normally they will always
|
be written to disk within a minute or less.) Modern systems
|
provide another function ‘fdatasync’ which guarantees integrity
|
only for the file data and is therefore faster. You can use the
|
‘O_FSYNC’ open mode to make ‘write’ always store the data to disk
|
before returning; *note Operating Modes::.
|
|
In the case of an error, ‘write’ returns -1. The following ‘errno’
|
error conditions are defined for this function:
|
|
‘EAGAIN’
|
Normally, ‘write’ blocks until the write operation is
|
complete. But if the ‘O_NONBLOCK’ flag is set for the file
|
(*note Control Operations::), it returns immediately without
|
writing any data and reports this error. An example of a
|
situation that might cause the process to block on output is
|
writing to a terminal device that supports flow control, where
|
output has been suspended by receipt of a STOP character.
|
|
*Compatibility Note:* Most versions of BSD Unix use a
|
different error code for this: ‘EWOULDBLOCK’. In the GNU C
|
Library, ‘EWOULDBLOCK’ is an alias for ‘EAGAIN’, so it doesn’t
|
matter which name you use.
|
|
On some systems, writing a large amount of data from a
|
character special file can also fail with ‘EAGAIN’ if the
|
kernel cannot find enough physical memory to lock down the
|
user’s pages. This is limited to devices that transfer with
|
direct memory access into the user’s memory, which means it
|
does not include terminals, since they always use separate
|
buffers inside the kernel. This problem does not arise on
|
GNU/Hurd systems.
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor, or is not
|
open for writing.
|
|
‘EFBIG’
|
The size of the file would become larger than the
|
implementation can support.
|
|
‘EINTR’
|
The ‘write’ operation was interrupted by a signal while it was
|
blocked waiting for completion. A signal will not necessarily
|
cause ‘write’ to return ‘EINTR’; it may instead result in a
|
successful ‘write’ which writes fewer bytes than requested.
|
*Note Interrupted Primitives::.
|
|
‘EIO’
|
For many devices, and for disk files, this error code
|
indicates a hardware error.
|
|
‘ENOSPC’
|
The device containing the file is full.
|
|
‘EPIPE’
|
This error is returned when you try to write to a pipe or FIFO
|
that isn’t open for reading by any process. When this
|
happens, a ‘SIGPIPE’ signal is also sent to the process; see
|
*note Signal Handling::.
|
|
‘EINVAL’
|
In some systems, when writing to a character or block device,
|
position and size offsets must be aligned to a particular
|
block size. This error indicates that the offsets were not
|
properly aligned.
|
|
Unless you have arranged to prevent ‘EINTR’ failures, you should
|
check ‘errno’ after each failing call to ‘write’, and if the error
|
was ‘EINTR’, you should simply repeat the call. *Note Interrupted
|
Primitives::. The easy way to do this is with the macro
|
‘TEMP_FAILURE_RETRY’, as follows:
|
|
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
|
|
Please note that there is no function named ‘write64’. This is not
|
necessary since this function does not directly modify or handle
|
the possibly wide file offset. Since the kernel handles this state
|
internally the ‘write’ function can be used for all cases.
|
|
This function is a cancellation point in multi-threaded programs.
|
This is a problem if the thread allocates some resources (like
|
memory, file descriptors, semaphores or whatever) at the time
|
‘write’ is called. If the thread gets canceled these resources
|
stay allocated until the program ends. To avoid this, calls to
|
‘write’ should be protected using cancellation handlers.
|
|
The ‘write’ function is the underlying primitive for all of the
|
functions that write to streams, such as ‘fputc’.
|
|
-- Function: ssize_t pwrite (int FILEDES, const void *BUFFER, size_t
|
SIZE, off_t OFFSET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘pwrite’ function is similar to the ‘write’ function. The
|
first three arguments are identical, and the return values and
|
error codes also correspond.
|
|
The difference is the fourth argument and its handling. The data
|
block is not written to the current position of the file descriptor
|
‘filedes’. Instead the data is written to the file starting at
|
position OFFSET. The position of the file descriptor itself is not
|
affected by the operation. The value is the same as before the
|
call.
|
|
However, on Linux, if a file is opened with ‘O_APPEND’, ‘pwrite’
|
appends data to the end of the file, regardless of the value of
|
‘offset’.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
|
‘pwrite’ function is in fact ‘pwrite64’ and the type ‘off_t’ has 64
|
bits, which makes it possible to handle files up to 2^63 bytes in
|
length.
|
|
The return value of ‘pwrite’ describes the number of written bytes.
|
In the error case it returns -1 like ‘write’ does and the error
|
codes are also the same, with these additions:
|
|
‘EINVAL’
|
The value given for OFFSET is negative and therefore illegal.
|
|
‘ESPIPE’
|
The file descriptor FILEDES is associated with a pipe or a
|
FIFO and this device does not allow positioning of the file
|
pointer.
|
|
The function is an extension defined in the Unix Single
|
Specification version 2.
|
|
-- Function: ssize_t pwrite64 (int FILEDES, const void *BUFFER, size_t
|
SIZE, off64_t OFFSET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘pwrite’ function. The difference
|
is that the OFFSET parameter is of type ‘off64_t’ instead of
|
‘off_t’ which makes it possible on 32 bit machines to address files
|
larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
|
‘filedes’ must be opened using ‘open64’ since otherwise the large
|
offsets possible with ‘off64_t’ will lead to errors with a
|
descriptor in small file mode.
|
|
When the source file is compiled using ‘_FILE_OFFSET_BITS == 64’ on
|
a 32 bit machine this function is actually available under the name
|
‘pwrite’ and so transparently replaces the 32 bit interface.
|
|
|
File: libc.info, Node: File Position Primitive, Next: Descriptors and Streams, Prev: I/O Primitives, Up: Low-Level I/O
|
|
13.3 Setting the File Position of a Descriptor
|
==============================================
|
|
Just as you can set the file position of a stream with ‘fseek’, you can
|
set the file position of a descriptor with ‘lseek’. This specifies the
|
position in the file for the next ‘read’ or ‘write’ operation. *Note
|
File Positioning::, for more information on the file position and what
|
it means.
|
|
To read the current file position value from a descriptor, use ‘lseek
|
(DESC, 0, SEEK_CUR)’.
|
|
-- Function: off_t lseek (int FILEDES, off_t OFFSET, int WHENCE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘lseek’ function is used to change the file position of the
|
file with descriptor FILEDES.
|
|
The WHENCE argument specifies how the OFFSET should be interpreted,
|
in the same way as for the ‘fseek’ function, and it must be one of
|
the symbolic constants ‘SEEK_SET’, ‘SEEK_CUR’, or ‘SEEK_END’.
|
|
‘SEEK_SET’
|
Specifies that OFFSET is a count of characters from the
|
beginning of the file.
|
|
‘SEEK_CUR’
|
Specifies that OFFSET is a count of characters from the
|
current file position. This count may be positive or
|
negative.
|
|
‘SEEK_END’
|
Specifies that OFFSET is a count of characters from the end of
|
the file. A negative count specifies a position within the
|
current extent of the file; a positive count specifies a
|
position past the current end. If you set the position past
|
the current end, and actually write data, you will extend the
|
file with zeros up to that position.
|
|
The return value from ‘lseek’ is normally the resulting file
|
position, measured in bytes from the beginning of the file. You
|
can use this feature together with ‘SEEK_CUR’ to read the current
|
file position.
|
|
If you want to append to the file, setting the file position to the
|
current end of file with ‘SEEK_END’ is not sufficient. Another
|
process may write more data after you seek but before you write,
|
extending the file so the position you write onto clobbers their
|
data. Instead, use the ‘O_APPEND’ operating mode; *note Operating
|
Modes::.
|
|
You can set the file position past the current end of the file.
|
This does not by itself make the file longer; ‘lseek’ never changes
|
the file. But subsequent output at that position will extend the
|
file. Characters between the previous end of file and the new
|
position are filled with zeros. Extending the file in this way can
|
create a “hole”: the blocks of zeros are not actually allocated on
|
disk, so the file takes up less space than it appears to; it is
|
then called a “sparse file”.
|
|
If the file position cannot be changed, or the operation is in some
|
way invalid, ‘lseek’ returns a value of -1. The following ‘errno’
|
error conditions are defined for this function:
|
|
‘EBADF’
|
The FILEDES is not a valid file descriptor.
|
|
‘EINVAL’
|
The WHENCE argument value is not valid, or the resulting file
|
offset is not valid. A file offset is invalid.
|
|
‘ESPIPE’
|
The FILEDES corresponds to an object that cannot be
|
positioned, such as a pipe, FIFO or terminal device. (POSIX.1
|
specifies this error only for pipes and FIFOs, but on GNU
|
systems, you always get ‘ESPIPE’ if the object is not
|
seekable.)
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
|
‘lseek’ function is in fact ‘lseek64’ and the type ‘off_t’ has 64
|
bits which makes it possible to handle files up to 2^63 bytes in
|
length.
|
|
This function is a cancellation point in multi-threaded programs.
|
This is a problem if the thread allocates some resources (like
|
memory, file descriptors, semaphores or whatever) at the time
|
‘lseek’ is called. If the thread gets canceled these resources
|
stay allocated until the program ends. To avoid this calls to
|
‘lseek’ should be protected using cancellation handlers.
|
|
The ‘lseek’ function is the underlying primitive for the ‘fseek’,
|
‘fseeko’, ‘ftell’, ‘ftello’ and ‘rewind’ functions, which operate
|
on streams instead of file descriptors.
|
|
-- Function: off64_t lseek64 (int FILEDES, off64_t OFFSET, int WHENCE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘lseek’ function. The difference
|
is that the OFFSET parameter is of type ‘off64_t’ instead of
|
‘off_t’ which makes it possible on 32 bit machines to address files
|
larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
|
‘filedes’ must be opened using ‘open64’ since otherwise the large
|
offsets possible with ‘off64_t’ will lead to errors with a
|
descriptor in small file mode.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ on
|
a 32 bits machine this function is actually available under the
|
name ‘lseek’ and so transparently replaces the 32 bit interface.
|
|
You can have multiple descriptors for the same file if you open the
|
file more than once, or if you duplicate a descriptor with ‘dup’.
|
Descriptors that come from separate calls to ‘open’ have independent
|
file positions; using ‘lseek’ on one descriptor has no effect on the
|
other. For example,
|
|
{
|
int d1, d2;
|
char buf[4];
|
d1 = open ("foo", O_RDONLY);
|
d2 = open ("foo", O_RDONLY);
|
lseek (d1, 1024, SEEK_SET);
|
read (d2, buf, 4);
|
}
|
|
will read the first four characters of the file ‘foo’. (The
|
error-checking code necessary for a real program has been omitted here
|
for brevity.)
|
|
By contrast, descriptors made by duplication share a common file
|
position with the original descriptor that was duplicated. Anything
|
which alters the file position of one of the duplicates, including
|
reading or writing data, affects all of them alike. Thus, for example,
|
|
{
|
int d1, d2, d3;
|
char buf1[4], buf2[4];
|
d1 = open ("foo", O_RDONLY);
|
d2 = dup (d1);
|
d3 = dup (d2);
|
lseek (d3, 1024, SEEK_SET);
|
read (d1, buf1, 4);
|
read (d2, buf2, 4);
|
}
|
|
will read four characters starting with the 1024’th character of ‘foo’,
|
and then four more characters starting with the 1028’th character.
|
|
-- Data Type: off_t
|
|
This is a signed integer type used to represent file sizes. In the
|
GNU C Library, this type is no narrower than ‘int’.
|
|
If the source is compiled with ‘_FILE_OFFSET_BITS == 64’ this type
|
is transparently replaced by ‘off64_t’.
|
|
-- Data Type: off64_t
|
|
This type is used similar to ‘off_t’. The difference is that even
|
on 32 bit machines, where the ‘off_t’ type would have 32 bits,
|
‘off64_t’ has 64 bits and so is able to address files up to 2^63
|
bytes in length.
|
|
When compiling with ‘_FILE_OFFSET_BITS == 64’ this type is
|
available under the name ‘off_t’.
|
|
These 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’.
|
