This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
|
|
This file documents the GNU C Library.
|
|
This is ‘The GNU C Library Reference Manual’, for version 2.25.
|
|
Copyright © 1993–2017 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being “Free Software Needs Free Documentation” and
|
“GNU Lesser General Public License”, the Front-Cover texts being “A GNU
|
Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
|
license is included in the section entitled "GNU Free Documentation
|
License".
|
|
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
|
modify this GNU manual. Buying copies from the FSF supports it in
|
developing GNU and promoting software freedom.”
|
INFO-DIR-SECTION Software libraries
|
START-INFO-DIR-ENTRY
|
* Libc: (libc). C library.
|
END-INFO-DIR-ENTRY
|
|
INFO-DIR-SECTION GNU C library functions and macros
|
START-INFO-DIR-ENTRY
|
* ALTWERASE: (libc)Local Modes.
|
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
|
* ARG_MAX: (libc)General Limits.
|
* BC_BASE_MAX: (libc)Utility Limits.
|
* BC_DIM_MAX: (libc)Utility Limits.
|
* BC_SCALE_MAX: (libc)Utility Limits.
|
* BC_STRING_MAX: (libc)Utility Limits.
|
* BRKINT: (libc)Input Modes.
|
* BUFSIZ: (libc)Controlling Buffering.
|
* CCTS_OFLOW: (libc)Control Modes.
|
* CHILD_MAX: (libc)General Limits.
|
* CIGNORE: (libc)Control Modes.
|
* CLK_TCK: (libc)Processor Time.
|
* CLOCAL: (libc)Control Modes.
|
* CLOCKS_PER_SEC: (libc)CPU Time.
|
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
|
* CPU_CLR: (libc)CPU Affinity.
|
* CPU_ISSET: (libc)CPU Affinity.
|
* CPU_SET: (libc)CPU Affinity.
|
* CPU_SETSIZE: (libc)CPU Affinity.
|
* CPU_ZERO: (libc)CPU Affinity.
|
* CREAD: (libc)Control Modes.
|
* CRTS_IFLOW: (libc)Control Modes.
|
* CS5: (libc)Control Modes.
|
* CS6: (libc)Control Modes.
|
* CS7: (libc)Control Modes.
|
* CS8: (libc)Control Modes.
|
* CSIZE: (libc)Control Modes.
|
* CSTOPB: (libc)Control Modes.
|
* DES_FAILED: (libc)DES Encryption.
|
* DTTOIF: (libc)Directory Entries.
|
* E2BIG: (libc)Error Codes.
|
* EACCES: (libc)Error Codes.
|
* EADDRINUSE: (libc)Error Codes.
|
* EADDRNOTAVAIL: (libc)Error Codes.
|
* EADV: (libc)Error Codes.
|
* EAFNOSUPPORT: (libc)Error Codes.
|
* EAGAIN: (libc)Error Codes.
|
* EALREADY: (libc)Error Codes.
|
* EAUTH: (libc)Error Codes.
|
* EBACKGROUND: (libc)Error Codes.
|
* EBADE: (libc)Error Codes.
|
* EBADF: (libc)Error Codes.
|
* EBADFD: (libc)Error Codes.
|
* EBADMSG: (libc)Error Codes.
|
* EBADR: (libc)Error Codes.
|
* EBADRPC: (libc)Error Codes.
|
* EBADRQC: (libc)Error Codes.
|
* EBADSLT: (libc)Error Codes.
|
* EBFONT: (libc)Error Codes.
|
* EBUSY: (libc)Error Codes.
|
* ECANCELED: (libc)Error Codes.
|
* ECHILD: (libc)Error Codes.
|
* ECHO: (libc)Local Modes.
|
* ECHOCTL: (libc)Local Modes.
|
* ECHOE: (libc)Local Modes.
|
* ECHOK: (libc)Local Modes.
|
* ECHOKE: (libc)Local Modes.
|
* ECHONL: (libc)Local Modes.
|
* ECHOPRT: (libc)Local Modes.
|
* ECHRNG: (libc)Error Codes.
|
* ECOMM: (libc)Error Codes.
|
* ECONNABORTED: (libc)Error Codes.
|
* ECONNREFUSED: (libc)Error Codes.
|
* ECONNRESET: (libc)Error Codes.
|
* ED: (libc)Error Codes.
|
* EDEADLK: (libc)Error Codes.
|
* EDEADLOCK: (libc)Error Codes.
|
* EDESTADDRREQ: (libc)Error Codes.
|
* EDIED: (libc)Error Codes.
|
* EDOM: (libc)Error Codes.
|
* EDOTDOT: (libc)Error Codes.
|
* EDQUOT: (libc)Error Codes.
|
* EEXIST: (libc)Error Codes.
|
* EFAULT: (libc)Error Codes.
|
* EFBIG: (libc)Error Codes.
|
* EFTYPE: (libc)Error Codes.
|
* EGRATUITOUS: (libc)Error Codes.
|
* EGREGIOUS: (libc)Error Codes.
|
* EHOSTDOWN: (libc)Error Codes.
|
* EHOSTUNREACH: (libc)Error Codes.
|
* EHWPOISON: (libc)Error Codes.
|
* EIDRM: (libc)Error Codes.
|
* EIEIO: (libc)Error Codes.
|
* EILSEQ: (libc)Error Codes.
|
* EINPROGRESS: (libc)Error Codes.
|
* EINTR: (libc)Error Codes.
|
* EINVAL: (libc)Error Codes.
|
* EIO: (libc)Error Codes.
|
* EISCONN: (libc)Error Codes.
|
* EISDIR: (libc)Error Codes.
|
* EISNAM: (libc)Error Codes.
|
* EKEYEXPIRED: (libc)Error Codes.
|
* EKEYREJECTED: (libc)Error Codes.
|
* EKEYREVOKED: (libc)Error Codes.
|
* EL2HLT: (libc)Error Codes.
|
* EL2NSYNC: (libc)Error Codes.
|
* EL3HLT: (libc)Error Codes.
|
* EL3RST: (libc)Error Codes.
|
* ELIBACC: (libc)Error Codes.
|
* ELIBBAD: (libc)Error Codes.
|
* ELIBEXEC: (libc)Error Codes.
|
* ELIBMAX: (libc)Error Codes.
|
* ELIBSCN: (libc)Error Codes.
|
* ELNRNG: (libc)Error Codes.
|
* ELOOP: (libc)Error Codes.
|
* EMEDIUMTYPE: (libc)Error Codes.
|
* EMFILE: (libc)Error Codes.
|
* EMLINK: (libc)Error Codes.
|
* EMSGSIZE: (libc)Error Codes.
|
* EMULTIHOP: (libc)Error Codes.
|
* ENAMETOOLONG: (libc)Error Codes.
|
* ENAVAIL: (libc)Error Codes.
|
* ENEEDAUTH: (libc)Error Codes.
|
* ENETDOWN: (libc)Error Codes.
|
* ENETRESET: (libc)Error Codes.
|
* ENETUNREACH: (libc)Error Codes.
|
* ENFILE: (libc)Error Codes.
|
* ENOANO: (libc)Error Codes.
|
* ENOBUFS: (libc)Error Codes.
|
* ENOCSI: (libc)Error Codes.
|
* ENODATA: (libc)Error Codes.
|
* ENODEV: (libc)Error Codes.
|
* ENOENT: (libc)Error Codes.
|
* ENOEXEC: (libc)Error Codes.
|
* ENOKEY: (libc)Error Codes.
|
* ENOLCK: (libc)Error Codes.
|
* ENOLINK: (libc)Error Codes.
|
* ENOMEDIUM: (libc)Error Codes.
|
* ENOMEM: (libc)Error Codes.
|
* ENOMSG: (libc)Error Codes.
|
* ENONET: (libc)Error Codes.
|
* ENOPKG: (libc)Error Codes.
|
* ENOPROTOOPT: (libc)Error Codes.
|
* ENOSPC: (libc)Error Codes.
|
* ENOSR: (libc)Error Codes.
|
* ENOSTR: (libc)Error Codes.
|
* ENOSYS: (libc)Error Codes.
|
* ENOTBLK: (libc)Error Codes.
|
* ENOTCONN: (libc)Error Codes.
|
* ENOTDIR: (libc)Error Codes.
|
* ENOTEMPTY: (libc)Error Codes.
|
* ENOTNAM: (libc)Error Codes.
|
* ENOTRECOVERABLE: (libc)Error Codes.
|
* ENOTSOCK: (libc)Error Codes.
|
* ENOTSUP: (libc)Error Codes.
|
* ENOTTY: (libc)Error Codes.
|
* ENOTUNIQ: (libc)Error Codes.
|
* ENXIO: (libc)Error Codes.
|
* EOF: (libc)EOF and Errors.
|
* EOPNOTSUPP: (libc)Error Codes.
|
* EOVERFLOW: (libc)Error Codes.
|
* EOWNERDEAD: (libc)Error Codes.
|
* EPERM: (libc)Error Codes.
|
* EPFNOSUPPORT: (libc)Error Codes.
|
* EPIPE: (libc)Error Codes.
|
* EPROCLIM: (libc)Error Codes.
|
* EPROCUNAVAIL: (libc)Error Codes.
|
* EPROGMISMATCH: (libc)Error Codes.
|
* EPROGUNAVAIL: (libc)Error Codes.
|
* EPROTO: (libc)Error Codes.
|
* EPROTONOSUPPORT: (libc)Error Codes.
|
* EPROTOTYPE: (libc)Error Codes.
|
* EQUIV_CLASS_MAX: (libc)Utility Limits.
|
* ERANGE: (libc)Error Codes.
|
* EREMCHG: (libc)Error Codes.
|
* EREMOTE: (libc)Error Codes.
|
* EREMOTEIO: (libc)Error Codes.
|
* ERESTART: (libc)Error Codes.
|
* ERFKILL: (libc)Error Codes.
|
* EROFS: (libc)Error Codes.
|
* ERPCMISMATCH: (libc)Error Codes.
|
* ESHUTDOWN: (libc)Error Codes.
|
* ESOCKTNOSUPPORT: (libc)Error Codes.
|
* ESPIPE: (libc)Error Codes.
|
* ESRCH: (libc)Error Codes.
|
* ESRMNT: (libc)Error Codes.
|
* ESTALE: (libc)Error Codes.
|
* ESTRPIPE: (libc)Error Codes.
|
* ETIME: (libc)Error Codes.
|
* ETIMEDOUT: (libc)Error Codes.
|
* ETOOMANYREFS: (libc)Error Codes.
|
* ETXTBSY: (libc)Error Codes.
|
* EUCLEAN: (libc)Error Codes.
|
* EUNATCH: (libc)Error Codes.
|
* EUSERS: (libc)Error Codes.
|
* EWOULDBLOCK: (libc)Error Codes.
|
* EXDEV: (libc)Error Codes.
|
* EXFULL: (libc)Error Codes.
|
* EXIT_FAILURE: (libc)Exit Status.
|
* EXIT_SUCCESS: (libc)Exit Status.
|
* EXPR_NEST_MAX: (libc)Utility Limits.
|
* FD_CLOEXEC: (libc)Descriptor Flags.
|
* FD_CLR: (libc)Waiting for I/O.
|
* FD_ISSET: (libc)Waiting for I/O.
|
* FD_SET: (libc)Waiting for I/O.
|
* FD_SETSIZE: (libc)Waiting for I/O.
|
* FD_ZERO: (libc)Waiting for I/O.
|
* FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
|
* FILENAME_MAX: (libc)Limits for Files.
|
* FLUSHO: (libc)Local Modes.
|
* FOPEN_MAX: (libc)Opening Streams.
|
* FP_ILOGB0: (libc)Exponents and Logarithms.
|
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
|
* FP_LLOGB0: (libc)Exponents and Logarithms.
|
* FP_LLOGBNAN: (libc)Exponents and Logarithms.
|
* F_DUPFD: (libc)Duplicating Descriptors.
|
* F_GETFD: (libc)Descriptor Flags.
|
* F_GETFL: (libc)Getting File Status Flags.
|
* F_GETLK: (libc)File Locks.
|
* F_GETOWN: (libc)Interrupt Input.
|
* F_OFD_GETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLKW: (libc)Open File Description Locks.
|
* F_OK: (libc)Testing File Access.
|
* F_SETFD: (libc)Descriptor Flags.
|
* F_SETFL: (libc)Getting File Status Flags.
|
* F_SETLK: (libc)File Locks.
|
* F_SETLKW: (libc)File Locks.
|
* F_SETOWN: (libc)Interrupt Input.
|
* HUGE_VAL: (libc)Math Error Reporting.
|
* HUGE_VALF: (libc)Math Error Reporting.
|
* HUGE_VALL: (libc)Math Error Reporting.
|
* HUPCL: (libc)Control Modes.
|
* I: (libc)Complex Numbers.
|
* ICANON: (libc)Local Modes.
|
* ICRNL: (libc)Input Modes.
|
* IEXTEN: (libc)Local Modes.
|
* IFNAMSIZ: (libc)Interface Naming.
|
* IFTODT: (libc)Directory Entries.
|
* IGNBRK: (libc)Input Modes.
|
* IGNCR: (libc)Input Modes.
|
* IGNPAR: (libc)Input Modes.
|
* IMAXBEL: (libc)Input Modes.
|
* INADDR_ANY: (libc)Host Address Data Type.
|
* INADDR_BROADCAST: (libc)Host Address Data Type.
|
* INADDR_LOOPBACK: (libc)Host Address Data Type.
|
* INADDR_NONE: (libc)Host Address Data Type.
|
* INFINITY: (libc)Infinity and NaN.
|
* INLCR: (libc)Input Modes.
|
* INPCK: (libc)Input Modes.
|
* IPPORT_RESERVED: (libc)Ports.
|
* IPPORT_USERRESERVED: (libc)Ports.
|
* ISIG: (libc)Local Modes.
|
* ISTRIP: (libc)Input Modes.
|
* IXANY: (libc)Input Modes.
|
* IXOFF: (libc)Input Modes.
|
* IXON: (libc)Input Modes.
|
* LINE_MAX: (libc)Utility Limits.
|
* LINK_MAX: (libc)Limits for Files.
|
* L_ctermid: (libc)Identifying the Terminal.
|
* L_cuserid: (libc)Who Logged In.
|
* L_tmpnam: (libc)Temporary Files.
|
* MAXNAMLEN: (libc)Limits for Files.
|
* MAXSYMLINKS: (libc)Symbolic Links.
|
* MAX_CANON: (libc)Limits for Files.
|
* MAX_INPUT: (libc)Limits for Files.
|
* MB_CUR_MAX: (libc)Selecting the Conversion.
|
* MB_LEN_MAX: (libc)Selecting the Conversion.
|
* MDMBUF: (libc)Control Modes.
|
* MSG_DONTROUTE: (libc)Socket Data Options.
|
* MSG_OOB: (libc)Socket Data Options.
|
* MSG_PEEK: (libc)Socket Data Options.
|
* NAME_MAX: (libc)Limits for Files.
|
* NAN: (libc)Infinity and NaN.
|
* NCCS: (libc)Mode Data Types.
|
* NGROUPS_MAX: (libc)General Limits.
|
* NOFLSH: (libc)Local Modes.
|
* NOKERNINFO: (libc)Local Modes.
|
* NSIG: (libc)Standard Signals.
|
* NULL: (libc)Null Pointer Constant.
|
* ONLCR: (libc)Output Modes.
|
* ONOEOT: (libc)Output Modes.
|
* OPEN_MAX: (libc)General Limits.
|
* OPOST: (libc)Output Modes.
|
* OXTABS: (libc)Output Modes.
|
* O_ACCMODE: (libc)Access Modes.
|
* O_APPEND: (libc)Operating Modes.
|
* O_ASYNC: (libc)Operating Modes.
|
* O_CREAT: (libc)Open-time Flags.
|
* O_EXCL: (libc)Open-time Flags.
|
* O_EXEC: (libc)Access Modes.
|
* O_EXLOCK: (libc)Open-time Flags.
|
* O_FSYNC: (libc)Operating Modes.
|
* O_IGNORE_CTTY: (libc)Open-time Flags.
|
* O_NDELAY: (libc)Operating Modes.
|
* O_NOATIME: (libc)Operating Modes.
|
* O_NOCTTY: (libc)Open-time Flags.
|
* O_NOLINK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Operating Modes.
|
* O_NOTRANS: (libc)Open-time Flags.
|
* O_RDONLY: (libc)Access Modes.
|
* O_RDWR: (libc)Access Modes.
|
* O_READ: (libc)Access Modes.
|
* O_SHLOCK: (libc)Open-time Flags.
|
* O_SYNC: (libc)Operating Modes.
|
* O_TRUNC: (libc)Open-time Flags.
|
* O_WRITE: (libc)Access Modes.
|
* O_WRONLY: (libc)Access Modes.
|
* PARENB: (libc)Control Modes.
|
* PARMRK: (libc)Input Modes.
|
* PARODD: (libc)Control Modes.
|
* PATH_MAX: (libc)Limits for Files.
|
* PA_FLAG_MASK: (libc)Parsing a Template String.
|
* PENDIN: (libc)Local Modes.
|
* PF_FILE: (libc)Local Namespace Details.
|
* PF_INET6: (libc)Internet Namespace.
|
* PF_INET: (libc)Internet Namespace.
|
* PF_LOCAL: (libc)Local Namespace Details.
|
* PF_UNIX: (libc)Local Namespace Details.
|
* PIPE_BUF: (libc)Limits for Files.
|
* P_tmpdir: (libc)Temporary Files.
|
* RAND_MAX: (libc)ISO Random.
|
* RE_DUP_MAX: (libc)General Limits.
|
* RLIM_INFINITY: (libc)Limits on Resources.
|
* R_OK: (libc)Testing File Access.
|
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
|
* SA_ONSTACK: (libc)Flags for Sigaction.
|
* SA_RESTART: (libc)Flags for Sigaction.
|
* SEEK_CUR: (libc)File Positioning.
|
* SEEK_END: (libc)File Positioning.
|
* SEEK_SET: (libc)File Positioning.
|
* SIGABRT: (libc)Program Error Signals.
|
* SIGALRM: (libc)Alarm Signals.
|
* SIGBUS: (libc)Program Error Signals.
|
* SIGCHLD: (libc)Job Control Signals.
|
* SIGCLD: (libc)Job Control Signals.
|
* SIGCONT: (libc)Job Control Signals.
|
* SIGEMT: (libc)Program Error Signals.
|
* SIGFPE: (libc)Program Error Signals.
|
* SIGHUP: (libc)Termination Signals.
|
* SIGILL: (libc)Program Error Signals.
|
* SIGINFO: (libc)Miscellaneous Signals.
|
* SIGINT: (libc)Termination Signals.
|
* SIGIO: (libc)Asynchronous I/O Signals.
|
* SIGIOT: (libc)Program Error Signals.
|
* SIGKILL: (libc)Termination Signals.
|
* SIGLOST: (libc)Operation Error Signals.
|
* SIGPIPE: (libc)Operation Error Signals.
|
* SIGPOLL: (libc)Asynchronous I/O Signals.
|
* SIGPROF: (libc)Alarm Signals.
|
* SIGQUIT: (libc)Termination Signals.
|
* SIGSEGV: (libc)Program Error Signals.
|
* SIGSTOP: (libc)Job Control Signals.
|
* SIGSYS: (libc)Program Error Signals.
|
* SIGTERM: (libc)Termination Signals.
|
* SIGTRAP: (libc)Program Error Signals.
|
* SIGTSTP: (libc)Job Control Signals.
|
* SIGTTIN: (libc)Job Control Signals.
|
* SIGTTOU: (libc)Job Control Signals.
|
* SIGURG: (libc)Asynchronous I/O Signals.
|
* SIGUSR1: (libc)Miscellaneous Signals.
|
* SIGUSR2: (libc)Miscellaneous Signals.
|
* SIGVTALRM: (libc)Alarm Signals.
|
* SIGWINCH: (libc)Miscellaneous Signals.
|
* SIGXCPU: (libc)Operation Error Signals.
|
* SIGXFSZ: (libc)Operation Error Signals.
|
* SIG_ERR: (libc)Basic Signal Handling.
|
* SNAN: (libc)Infinity and NaN.
|
* SNANF: (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.
|
* __va_copy: (libc)Argument Macros.
|
* _exit: (libc)Termination Internals.
|
* _flushlbf: (libc)Flushing Buffers.
|
* _tolower: (libc)Case Conversion.
|
* _toupper: (libc)Case Conversion.
|
* a64l: (libc)Encode Binary Data.
|
* abort: (libc)Aborting a Program.
|
* abs: (libc)Absolute Value.
|
* accept: (libc)Accepting Connections.
|
* access: (libc)Testing File Access.
|
* acos: (libc)Inverse Trig Functions.
|
* acosf: (libc)Inverse Trig Functions.
|
* acosh: (libc)Hyperbolic Functions.
|
* acoshf: (libc)Hyperbolic Functions.
|
* acoshl: (libc)Hyperbolic Functions.
|
* acosl: (libc)Inverse Trig Functions.
|
* addmntent: (libc)mtab.
|
* addseverity: (libc)Adding Severity Classes.
|
* adjtime: (libc)High-Resolution Calendar.
|
* adjtimex: (libc)High-Resolution Calendar.
|
* aio_cancel64: (libc)Cancel AIO Operations.
|
* aio_cancel: (libc)Cancel AIO Operations.
|
* aio_error64: (libc)Status of AIO Operations.
|
* aio_error: (libc)Status of AIO Operations.
|
* aio_fsync64: (libc)Synchronizing AIO Operations.
|
* aio_fsync: (libc)Synchronizing AIO Operations.
|
* aio_init: (libc)Configuration of AIO.
|
* aio_read64: (libc)Asynchronous Reads/Writes.
|
* aio_read: (libc)Asynchronous Reads/Writes.
|
* aio_return64: (libc)Status of AIO Operations.
|
* aio_return: (libc)Status of AIO Operations.
|
* aio_suspend64: (libc)Synchronizing AIO Operations.
|
* aio_suspend: (libc)Synchronizing AIO Operations.
|
* aio_write64: (libc)Asynchronous Reads/Writes.
|
* aio_write: (libc)Asynchronous Reads/Writes.
|
* alarm: (libc)Setting an Alarm.
|
* aligned_alloc: (libc)Aligned Memory Blocks.
|
* alloca: (libc)Variable Size Automatic.
|
* alphasort64: (libc)Scanning Directory Content.
|
* alphasort: (libc)Scanning Directory Content.
|
* argp_error: (libc)Argp Helper Functions.
|
* argp_failure: (libc)Argp Helper Functions.
|
* argp_help: (libc)Argp Help.
|
* argp_parse: (libc)Argp.
|
* argp_state_help: (libc)Argp Helper Functions.
|
* argp_usage: (libc)Argp Helper Functions.
|
* argz_add: (libc)Argz Functions.
|
* argz_add_sep: (libc)Argz Functions.
|
* argz_append: (libc)Argz Functions.
|
* argz_count: (libc)Argz Functions.
|
* argz_create: (libc)Argz Functions.
|
* argz_create_sep: (libc)Argz Functions.
|
* argz_delete: (libc)Argz Functions.
|
* argz_extract: (libc)Argz Functions.
|
* argz_insert: (libc)Argz Functions.
|
* argz_next: (libc)Argz Functions.
|
* argz_replace: (libc)Argz Functions.
|
* argz_stringify: (libc)Argz Functions.
|
* asctime: (libc)Formatting Calendar Time.
|
* asctime_r: (libc)Formatting Calendar Time.
|
* asin: (libc)Inverse Trig Functions.
|
* asinf: (libc)Inverse Trig Functions.
|
* asinh: (libc)Hyperbolic Functions.
|
* asinhf: (libc)Hyperbolic Functions.
|
* asinhl: (libc)Hyperbolic Functions.
|
* asinl: (libc)Inverse Trig Functions.
|
* asprintf: (libc)Dynamic Output.
|
* assert: (libc)Consistency Checking.
|
* assert_perror: (libc)Consistency Checking.
|
* atan2: (libc)Inverse Trig Functions.
|
* atan2f: (libc)Inverse Trig Functions.
|
* atan2l: (libc)Inverse Trig Functions.
|
* atan: (libc)Inverse Trig Functions.
|
* atanf: (libc)Inverse Trig Functions.
|
* atanh: (libc)Hyperbolic Functions.
|
* atanhf: (libc)Hyperbolic Functions.
|
* atanhl: (libc)Hyperbolic Functions.
|
* atanl: (libc)Inverse Trig Functions.
|
* atexit: (libc)Cleanups on Exit.
|
* atof: (libc)Parsing of Floats.
|
* atoi: (libc)Parsing of Integers.
|
* atol: (libc)Parsing of Integers.
|
* atoll: (libc)Parsing of Integers.
|
* backtrace: (libc)Backtraces.
|
* backtrace_symbols: (libc)Backtraces.
|
* backtrace_symbols_fd: (libc)Backtraces.
|
* basename: (libc)Finding Tokens in a String.
|
* basename: (libc)Finding Tokens in a String.
|
* bcmp: (libc)String/Array Comparison.
|
* bcopy: (libc)Copying 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.
|
* cabsl: (libc)Absolute Value.
|
* cacos: (libc)Inverse Trig Functions.
|
* cacosf: (libc)Inverse Trig Functions.
|
* cacosh: (libc)Hyperbolic Functions.
|
* cacoshf: (libc)Hyperbolic Functions.
|
* cacoshl: (libc)Hyperbolic Functions.
|
* cacosl: (libc)Inverse Trig Functions.
|
* calloc: (libc)Allocating Cleared Space.
|
* canonicalize: (libc)FP Bit Twiddling.
|
* canonicalize_file_name: (libc)Symbolic Links.
|
* canonicalizef: (libc)FP Bit Twiddling.
|
* canonicalizel: (libc)FP Bit Twiddling.
|
* carg: (libc)Operations on Complex.
|
* cargf: (libc)Operations on Complex.
|
* cargl: (libc)Operations on Complex.
|
* casin: (libc)Inverse Trig Functions.
|
* casinf: (libc)Inverse Trig Functions.
|
* casinh: (libc)Hyperbolic Functions.
|
* casinhf: (libc)Hyperbolic Functions.
|
* casinhl: (libc)Hyperbolic Functions.
|
* casinl: (libc)Inverse Trig Functions.
|
* catan: (libc)Inverse Trig Functions.
|
* catanf: (libc)Inverse Trig Functions.
|
* catanh: (libc)Hyperbolic Functions.
|
* catanhf: (libc)Hyperbolic Functions.
|
* catanhl: (libc)Hyperbolic Functions.
|
* catanl: (libc)Inverse Trig Functions.
|
* catclose: (libc)The catgets Functions.
|
* catgets: (libc)The catgets Functions.
|
* catopen: (libc)The catgets Functions.
|
* cbc_crypt: (libc)DES Encryption.
|
* cbrt: (libc)Exponents and Logarithms.
|
* cbrtf: (libc)Exponents and Logarithms.
|
* cbrtl: (libc)Exponents and Logarithms.
|
* ccos: (libc)Trig Functions.
|
* ccosf: (libc)Trig Functions.
|
* ccosh: (libc)Hyperbolic Functions.
|
* ccoshf: (libc)Hyperbolic Functions.
|
* ccoshl: (libc)Hyperbolic Functions.
|
* ccosl: (libc)Trig Functions.
|
* ceil: (libc)Rounding Functions.
|
* ceilf: (libc)Rounding Functions.
|
* ceill: (libc)Rounding Functions.
|
* cexp: (libc)Exponents and Logarithms.
|
* cexpf: (libc)Exponents and Logarithms.
|
* cexpl: (libc)Exponents and Logarithms.
|
* cfgetispeed: (libc)Line Speed.
|
* cfgetospeed: (libc)Line Speed.
|
* cfmakeraw: (libc)Noncanonical Input.
|
* cfree: (libc)Freeing after Malloc.
|
* cfsetispeed: (libc)Line Speed.
|
* cfsetospeed: (libc)Line Speed.
|
* cfsetspeed: (libc)Line Speed.
|
* chdir: (libc)Working Directory.
|
* chmod: (libc)Setting Permissions.
|
* chown: (libc)File Owner.
|
* cimag: (libc)Operations on Complex.
|
* cimagf: (libc)Operations on Complex.
|
* cimagl: (libc)Operations on Complex.
|
* clearenv: (libc)Environment Access.
|
* clearerr: (libc)Error Recovery.
|
* clearerr_unlocked: (libc)Error Recovery.
|
* clock: (libc)CPU Time.
|
* clog10: (libc)Exponents and Logarithms.
|
* clog10f: (libc)Exponents and Logarithms.
|
* clog10l: (libc)Exponents and Logarithms.
|
* clog: (libc)Exponents and Logarithms.
|
* clogf: (libc)Exponents and Logarithms.
|
* clogl: (libc)Exponents and Logarithms.
|
* close: (libc)Opening and Closing Files.
|
* closedir: (libc)Reading/Closing Directory.
|
* closelog: (libc)closelog.
|
* confstr: (libc)String Parameters.
|
* conj: (libc)Operations on Complex.
|
* conjf: (libc)Operations on Complex.
|
* conjl: (libc)Operations on Complex.
|
* connect: (libc)Connecting.
|
* copysign: (libc)FP Bit Twiddling.
|
* copysignf: (libc)FP Bit Twiddling.
|
* copysignl: (libc)FP Bit Twiddling.
|
* cos: (libc)Trig Functions.
|
* cosf: (libc)Trig Functions.
|
* cosh: (libc)Hyperbolic Functions.
|
* coshf: (libc)Hyperbolic Functions.
|
* coshl: (libc)Hyperbolic Functions.
|
* cosl: (libc)Trig Functions.
|
* cpow: (libc)Exponents and Logarithms.
|
* cpowf: (libc)Exponents and Logarithms.
|
* cpowl: (libc)Exponents and Logarithms.
|
* cproj: (libc)Operations on Complex.
|
* cprojf: (libc)Operations on Complex.
|
* cprojl: (libc)Operations on Complex.
|
* creal: (libc)Operations on Complex.
|
* crealf: (libc)Operations on Complex.
|
* creall: (libc)Operations on Complex.
|
* creat64: (libc)Opening and Closing Files.
|
* creat: (libc)Opening and Closing Files.
|
* crypt: (libc)crypt.
|
* crypt_r: (libc)crypt.
|
* csin: (libc)Trig Functions.
|
* csinf: (libc)Trig Functions.
|
* csinh: (libc)Hyperbolic Functions.
|
* csinhf: (libc)Hyperbolic Functions.
|
* csinhl: (libc)Hyperbolic Functions.
|
* csinl: (libc)Trig Functions.
|
* csqrt: (libc)Exponents and Logarithms.
|
* csqrtf: (libc)Exponents and Logarithms.
|
* csqrtl: (libc)Exponents and Logarithms.
|
* ctan: (libc)Trig Functions.
|
* ctanf: (libc)Trig Functions.
|
* ctanh: (libc)Hyperbolic Functions.
|
* ctanhf: (libc)Hyperbolic Functions.
|
* ctanhl: (libc)Hyperbolic Functions.
|
* ctanl: (libc)Trig Functions.
|
* ctermid: (libc)Identifying the Terminal.
|
* ctime: (libc)Formatting Calendar Time.
|
* ctime_r: (libc)Formatting Calendar Time.
|
* cuserid: (libc)Who Logged In.
|
* dcgettext: (libc)Translation with gettext.
|
* dcngettext: (libc)Advanced gettext functions.
|
* des_setparity: (libc)DES Encryption.
|
* dgettext: (libc)Translation with gettext.
|
* difftime: (libc)Elapsed Time.
|
* dirfd: (libc)Opening a Directory.
|
* dirname: (libc)Finding Tokens in a String.
|
* div: (libc)Integer Division.
|
* dngettext: (libc)Advanced gettext functions.
|
* drand48: (libc)SVID Random.
|
* drand48_r: (libc)SVID Random.
|
* drem: (libc)Remainder Functions.
|
* dremf: (libc)Remainder Functions.
|
* dreml: (libc)Remainder Functions.
|
* dup2: (libc)Duplicating Descriptors.
|
* dup: (libc)Duplicating Descriptors.
|
* ecb_crypt: (libc)DES Encryption.
|
* ecvt: (libc)System V Number Conversion.
|
* ecvt_r: (libc)System V Number Conversion.
|
* encrypt: (libc)DES Encryption.
|
* encrypt_r: (libc)DES Encryption.
|
* endfsent: (libc)fstab.
|
* endgrent: (libc)Scanning All Groups.
|
* endhostent: (libc)Host Names.
|
* endmntent: (libc)mtab.
|
* endnetent: (libc)Networks Database.
|
* endnetgrent: (libc)Lookup Netgroup.
|
* endprotoent: (libc)Protocols Database.
|
* endpwent: (libc)Scanning All Users.
|
* endservent: (libc)Services Database.
|
* endutent: (libc)Manipulating the Database.
|
* endutxent: (libc)XPG Functions.
|
* envz_add: (libc)Envz Functions.
|
* envz_entry: (libc)Envz Functions.
|
* envz_get: (libc)Envz Functions.
|
* envz_merge: (libc)Envz Functions.
|
* envz_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.
|
* erfcl: (libc)Special Functions.
|
* erff: (libc)Special Functions.
|
* erfl: (libc)Special Functions.
|
* err: (libc)Error Messages.
|
* errno: (libc)Checking for Errors.
|
* error: (libc)Error Messages.
|
* error_at_line: (libc)Error Messages.
|
* errx: (libc)Error Messages.
|
* execl: (libc)Executing a File.
|
* execle: (libc)Executing a File.
|
* execlp: (libc)Executing a File.
|
* execv: (libc)Executing a File.
|
* execve: (libc)Executing a File.
|
* execvp: (libc)Executing a File.
|
* exit: (libc)Normal Termination.
|
* exp10: (libc)Exponents and Logarithms.
|
* exp10f: (libc)Exponents and Logarithms.
|
* exp10l: (libc)Exponents and Logarithms.
|
* exp2: (libc)Exponents and Logarithms.
|
* exp2f: (libc)Exponents and Logarithms.
|
* exp2l: (libc)Exponents and Logarithms.
|
* exp: (libc)Exponents and Logarithms.
|
* expf: (libc)Exponents and Logarithms.
|
* expl: (libc)Exponents and Logarithms.
|
* explicit_bzero: (libc)Erasing Sensitive Data.
|
* expm1: (libc)Exponents and Logarithms.
|
* expm1f: (libc)Exponents and Logarithms.
|
* expm1l: (libc)Exponents and Logarithms.
|
* fabs: (libc)Absolute Value.
|
* fabsf: (libc)Absolute Value.
|
* fabsl: (libc)Absolute Value.
|
* fchdir: (libc)Working Directory.
|
* fchmod: (libc)Setting Permissions.
|
* fchown: (libc)File Owner.
|
* fclose: (libc)Closing Streams.
|
* fcloseall: (libc)Closing Streams.
|
* fcntl: (libc)Control Operations.
|
* fcvt: (libc)System V Number Conversion.
|
* fcvt_r: (libc)System V Number Conversion.
|
* fdatasync: (libc)Synchronizing I/O.
|
* fdim: (libc)Misc FP Arithmetic.
|
* fdimf: (libc)Misc FP Arithmetic.
|
* fdiml: (libc)Misc FP Arithmetic.
|
* fdopen: (libc)Descriptors and Streams.
|
* fdopendir: (libc)Opening a Directory.
|
* feclearexcept: (libc)Status bit operations.
|
* fedisableexcept: (libc)Control Functions.
|
* feenableexcept: (libc)Control Functions.
|
* fegetenv: (libc)Control Functions.
|
* fegetexcept: (libc)Control Functions.
|
* fegetexceptflag: (libc)Status bit operations.
|
* fegetmode: (libc)Control Functions.
|
* fegetround: (libc)Rounding.
|
* feholdexcept: (libc)Control Functions.
|
* feof: (libc)EOF and Errors.
|
* feof_unlocked: (libc)EOF and Errors.
|
* feraiseexcept: (libc)Status bit operations.
|
* ferror: (libc)EOF and Errors.
|
* ferror_unlocked: (libc)EOF and Errors.
|
* fesetenv: (libc)Control Functions.
|
* fesetexcept: (libc)Status bit operations.
|
* fesetexceptflag: (libc)Status bit operations.
|
* fesetmode: (libc)Control Functions.
|
* fesetround: (libc)Rounding.
|
* fetestexcept: (libc)Status bit operations.
|
* fetestexceptflag: (libc)Status bit operations.
|
* feupdateenv: (libc)Control Functions.
|
* fflush: (libc)Flushing Buffers.
|
* fflush_unlocked: (libc)Flushing Buffers.
|
* fgetc: (libc)Character Input.
|
* fgetc_unlocked: (libc)Character Input.
|
* fgetgrent: (libc)Scanning All Groups.
|
* fgetgrent_r: (libc)Scanning All Groups.
|
* fgetpos64: (libc)Portable Positioning.
|
* fgetpos: (libc)Portable Positioning.
|
* fgetpwent: (libc)Scanning All Users.
|
* fgetpwent_r: (libc)Scanning All Users.
|
* fgets: (libc)Line Input.
|
* fgets_unlocked: (libc)Line Input.
|
* fgetwc: (libc)Character Input.
|
* fgetwc_unlocked: (libc)Character Input.
|
* fgetws: (libc)Line Input.
|
* fgetws_unlocked: (libc)Line Input.
|
* fileno: (libc)Descriptors and Streams.
|
* fileno_unlocked: (libc)Descriptors and Streams.
|
* finite: (libc)Floating Point Classes.
|
* finitef: (libc)Floating Point Classes.
|
* finitel: (libc)Floating Point Classes.
|
* flockfile: (libc)Streams and Threads.
|
* floor: (libc)Rounding Functions.
|
* floorf: (libc)Rounding Functions.
|
* floorl: (libc)Rounding Functions.
|
* fma: (libc)Misc FP Arithmetic.
|
* fmaf: (libc)Misc FP Arithmetic.
|
* fmal: (libc)Misc FP Arithmetic.
|
* fmax: (libc)Misc FP Arithmetic.
|
* fmaxf: (libc)Misc FP Arithmetic.
|
* fmaxl: (libc)Misc FP Arithmetic.
|
* fmaxmag: (libc)Misc FP Arithmetic.
|
* fmaxmagf: (libc)Misc FP Arithmetic.
|
* fmaxmagl: (libc)Misc FP Arithmetic.
|
* fmemopen: (libc)String Streams.
|
* fmin: (libc)Misc FP Arithmetic.
|
* fminf: (libc)Misc FP Arithmetic.
|
* fminl: (libc)Misc FP Arithmetic.
|
* fminmag: (libc)Misc FP Arithmetic.
|
* fminmagf: (libc)Misc FP Arithmetic.
|
* fminmagl: (libc)Misc FP Arithmetic.
|
* fmod: (libc)Remainder Functions.
|
* fmodf: (libc)Remainder Functions.
|
* fmodl: (libc)Remainder Functions.
|
* fmtmsg: (libc)Printing Formatted Messages.
|
* fnmatch: (libc)Wildcard Matching.
|
* fopen64: (libc)Opening Streams.
|
* fopen: (libc)Opening Streams.
|
* fopencookie: (libc)Streams and Cookies.
|
* fork: (libc)Creating a Process.
|
* forkpty: (libc)Pseudo-Terminal Pairs.
|
* fpathconf: (libc)Pathconf.
|
* fpclassify: (libc)Floating Point Classes.
|
* fprintf: (libc)Formatted Output Functions.
|
* fputc: (libc)Simple Output.
|
* fputc_unlocked: (libc)Simple Output.
|
* fputs: (libc)Simple Output.
|
* fputs_unlocked: (libc)Simple Output.
|
* fputwc: (libc)Simple Output.
|
* fputwc_unlocked: (libc)Simple Output.
|
* fputws: (libc)Simple Output.
|
* fputws_unlocked: (libc)Simple Output.
|
* fread: (libc)Block Input/Output.
|
* fread_unlocked: (libc)Block Input/Output.
|
* free: (libc)Freeing after Malloc.
|
* freopen64: (libc)Opening Streams.
|
* freopen: (libc)Opening Streams.
|
* frexp: (libc)Normalization Functions.
|
* frexpf: (libc)Normalization Functions.
|
* frexpl: (libc)Normalization Functions.
|
* fromfp: (libc)Rounding Functions.
|
* fromfpf: (libc)Rounding Functions.
|
* fromfpl: (libc)Rounding Functions.
|
* fromfpx: (libc)Rounding Functions.
|
* fromfpxf: (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.
|
* fsync: (libc)Synchronizing I/O.
|
* ftell: (libc)File Positioning.
|
* ftello64: (libc)File Positioning.
|
* ftello: (libc)File Positioning.
|
* ftruncate64: (libc)File Size.
|
* ftruncate: (libc)File Size.
|
* ftrylockfile: (libc)Streams and Threads.
|
* ftw64: (libc)Working with Directory Trees.
|
* ftw: (libc)Working with Directory Trees.
|
* funlockfile: (libc)Streams and Threads.
|
* futimes: (libc)File Times.
|
* fwide: (libc)Streams and I18N.
|
* fwprintf: (libc)Formatted Output Functions.
|
* fwrite: (libc)Block Input/Output.
|
* fwrite_unlocked: (libc)Block Input/Output.
|
* fwscanf: (libc)Formatted Input Functions.
|
* gamma: (libc)Special Functions.
|
* gammaf: (libc)Special Functions.
|
* gammal: (libc)Special Functions.
|
* gcvt: (libc)System V Number Conversion.
|
* get_avphys_pages: (libc)Query Memory Parameters.
|
* get_current_dir_name: (libc)Working Directory.
|
* get_nprocs: (libc)Processor Resources.
|
* get_nprocs_conf: (libc)Processor Resources.
|
* get_phys_pages: (libc)Query Memory Parameters.
|
* getauxval: (libc)Auxiliary Vector.
|
* getc: (libc)Character Input.
|
* getc_unlocked: (libc)Character Input.
|
* getchar: (libc)Character Input.
|
* getchar_unlocked: (libc)Character Input.
|
* getcontext: (libc)System V contexts.
|
* getcwd: (libc)Working Directory.
|
* getdate: (libc)General Time String Parsing.
|
* getdate_r: (libc)General Time String Parsing.
|
* getdelim: (libc)Line Input.
|
* getdomainnname: (libc)Host Identification.
|
* getegid: (libc)Reading Persona.
|
* 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.
|
* getpayloadl: (libc)FP Bit Twiddling.
|
* getpeername: (libc)Who is Connected.
|
* getpgid: (libc)Process Group Functions.
|
* getpgrp: (libc)Process Group Functions.
|
* getpid: (libc)Process Identification.
|
* getppid: (libc)Process Identification.
|
* getpriority: (libc)Traditional Scheduling Functions.
|
* getprotobyname: (libc)Protocols Database.
|
* getprotobynumber: (libc)Protocols Database.
|
* getprotoent: (libc)Protocols Database.
|
* getpt: (libc)Allocation.
|
* getpwent: (libc)Scanning All Users.
|
* getpwent_r: (libc)Scanning All Users.
|
* getpwnam: (libc)Lookup User.
|
* getpwnam_r: (libc)Lookup User.
|
* getpwuid: (libc)Lookup User.
|
* getpwuid_r: (libc)Lookup User.
|
* getrandom: (libc)Unpredictable Bytes.
|
* getrlimit64: (libc)Limits on Resources.
|
* getrlimit: (libc)Limits on Resources.
|
* getrusage: (libc)Resource Usage.
|
* gets: (libc)Line Input.
|
* getservbyname: (libc)Services Database.
|
* getservbyport: (libc)Services Database.
|
* getservent: (libc)Services Database.
|
* getsid: (libc)Process Group Functions.
|
* getsockname: (libc)Reading Address.
|
* getsockopt: (libc)Socket Option Functions.
|
* getsubopt: (libc)Suboptions.
|
* gettext: (libc)Translation with gettext.
|
* gettimeofday: (libc)High-Resolution Calendar.
|
* getuid: (libc)Reading Persona.
|
* getumask: (libc)Setting Permissions.
|
* getutent: (libc)Manipulating the Database.
|
* getutent_r: (libc)Manipulating the Database.
|
* getutid: (libc)Manipulating the Database.
|
* getutid_r: (libc)Manipulating the Database.
|
* getutline: (libc)Manipulating the Database.
|
* getutline_r: (libc)Manipulating the Database.
|
* getutmp: (libc)XPG Functions.
|
* getutmpx: (libc)XPG Functions.
|
* getutxent: (libc)XPG Functions.
|
* getutxid: (libc)XPG Functions.
|
* getutxline: (libc)XPG Functions.
|
* getw: (libc)Character Input.
|
* getwc: (libc)Character Input.
|
* getwc_unlocked: (libc)Character Input.
|
* getwchar: (libc)Character Input.
|
* getwchar_unlocked: (libc)Character Input.
|
* getwd: (libc)Working Directory.
|
* glob64: (libc)Calling Glob.
|
* glob: (libc)Calling Glob.
|
* globfree64: (libc)More Flags for Globbing.
|
* globfree: (libc)More Flags for Globbing.
|
* gmtime: (libc)Broken-down Time.
|
* gmtime_r: (libc)Broken-down Time.
|
* grantpt: (libc)Allocation.
|
* gsignal: (libc)Signaling Yourself.
|
* gtty: (libc)BSD Terminal Modes.
|
* hasmntopt: (libc)mtab.
|
* hcreate: (libc)Hash Search Function.
|
* hcreate_r: (libc)Hash Search Function.
|
* hdestroy: (libc)Hash Search Function.
|
* hdestroy_r: (libc)Hash Search Function.
|
* hsearch: (libc)Hash Search Function.
|
* hsearch_r: (libc)Hash Search Function.
|
* htonl: (libc)Byte Order.
|
* htons: (libc)Byte Order.
|
* hypot: (libc)Exponents and Logarithms.
|
* hypotf: (libc)Exponents and Logarithms.
|
* hypotl: (libc)Exponents and Logarithms.
|
* iconv: (libc)Generic Conversion Interface.
|
* iconv_close: (libc)Generic Conversion Interface.
|
* iconv_open: (libc)Generic Conversion Interface.
|
* if_freenameindex: (libc)Interface Naming.
|
* if_indextoname: (libc)Interface Naming.
|
* if_nameindex: (libc)Interface Naming.
|
* if_nametoindex: (libc)Interface Naming.
|
* ilogb: (libc)Exponents and Logarithms.
|
* ilogbf: (libc)Exponents and Logarithms.
|
* ilogbl: (libc)Exponents and Logarithms.
|
* imaxabs: (libc)Absolute Value.
|
* imaxdiv: (libc)Integer Division.
|
* in6addr_any: (libc)Host Address Data Type.
|
* in6addr_loopback: (libc)Host Address Data Type.
|
* index: (libc)Search Functions.
|
* inet_addr: (libc)Host Address Functions.
|
* inet_aton: (libc)Host Address Functions.
|
* inet_lnaof: (libc)Host Address Functions.
|
* inet_makeaddr: (libc)Host Address Functions.
|
* inet_netof: (libc)Host Address Functions.
|
* inet_network: (libc)Host Address Functions.
|
* inet_ntoa: (libc)Host Address Functions.
|
* inet_ntop: (libc)Host Address Functions.
|
* inet_pton: (libc)Host Address Functions.
|
* initgroups: (libc)Setting Groups.
|
* initstate: (libc)BSD Random.
|
* initstate_r: (libc)BSD Random.
|
* innetgr: (libc)Netgroup Membership.
|
* ioctl: (libc)IOCTLs.
|
* isalnum: (libc)Classification of Characters.
|
* isalpha: (libc)Classification of Characters.
|
* isascii: (libc)Classification of Characters.
|
* isatty: (libc)Is It a Terminal.
|
* isblank: (libc)Classification of Characters.
|
* 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.
|
* j0l: (libc)Special Functions.
|
* j1: (libc)Special Functions.
|
* j1f: (libc)Special Functions.
|
* j1l: (libc)Special Functions.
|
* jn: (libc)Special Functions.
|
* jnf: (libc)Special Functions.
|
* jnl: (libc)Special Functions.
|
* jrand48: (libc)SVID Random.
|
* jrand48_r: (libc)SVID Random.
|
* kill: (libc)Signaling Another Process.
|
* killpg: (libc)Signaling Another Process.
|
* l64a: (libc)Encode Binary Data.
|
* labs: (libc)Absolute Value.
|
* lcong48: (libc)SVID Random.
|
* lcong48_r: (libc)SVID Random.
|
* ldexp: (libc)Normalization Functions.
|
* ldexpf: (libc)Normalization Functions.
|
* ldexpl: (libc)Normalization Functions.
|
* ldiv: (libc)Integer Division.
|
* lfind: (libc)Array Search Function.
|
* lgamma: (libc)Special Functions.
|
* lgamma_r: (libc)Special Functions.
|
* lgammaf: (libc)Special Functions.
|
* lgammaf_r: (libc)Special Functions.
|
* lgammal: (libc)Special Functions.
|
* lgammal_r: (libc)Special Functions.
|
* link: (libc)Hard Links.
|
* lio_listio64: (libc)Asynchronous Reads/Writes.
|
* lio_listio: (libc)Asynchronous Reads/Writes.
|
* listen: (libc)Listening.
|
* llabs: (libc)Absolute Value.
|
* lldiv: (libc)Integer Division.
|
* llogb: (libc)Exponents and Logarithms.
|
* llogbf: (libc)Exponents and Logarithms.
|
* llogbl: (libc)Exponents and Logarithms.
|
* llrint: (libc)Rounding Functions.
|
* llrintf: (libc)Rounding Functions.
|
* llrintl: (libc)Rounding Functions.
|
* llround: (libc)Rounding Functions.
|
* llroundf: (libc)Rounding Functions.
|
* llroundl: (libc)Rounding Functions.
|
* localeconv: (libc)The Lame Way to Locale Data.
|
* localtime: (libc)Broken-down Time.
|
* localtime_r: (libc)Broken-down Time.
|
* log10: (libc)Exponents and Logarithms.
|
* log10f: (libc)Exponents and Logarithms.
|
* log10l: (libc)Exponents and Logarithms.
|
* log1p: (libc)Exponents and Logarithms.
|
* log1pf: (libc)Exponents and Logarithms.
|
* log1pl: (libc)Exponents and Logarithms.
|
* log2: (libc)Exponents and Logarithms.
|
* log2f: (libc)Exponents and Logarithms.
|
* log2l: (libc)Exponents and Logarithms.
|
* log: (libc)Exponents and Logarithms.
|
* logb: (libc)Exponents and Logarithms.
|
* logbf: (libc)Exponents and Logarithms.
|
* logbl: (libc)Exponents and Logarithms.
|
* logf: (libc)Exponents and Logarithms.
|
* login: (libc)Logging In and Out.
|
* login_tty: (libc)Logging In and Out.
|
* logl: (libc)Exponents and Logarithms.
|
* logout: (libc)Logging In and Out.
|
* logwtmp: (libc)Logging In and Out.
|
* longjmp: (libc)Non-Local Details.
|
* lrand48: (libc)SVID Random.
|
* lrand48_r: (libc)SVID Random.
|
* lrint: (libc)Rounding Functions.
|
* lrintf: (libc)Rounding Functions.
|
* lrintl: (libc)Rounding Functions.
|
* lround: (libc)Rounding Functions.
|
* lroundf: (libc)Rounding Functions.
|
* lroundl: (libc)Rounding Functions.
|
* lsearch: (libc)Array Search Function.
|
* lseek64: (libc)File Position Primitive.
|
* lseek: (libc)File Position Primitive.
|
* lstat64: (libc)Reading Attributes.
|
* lstat: (libc)Reading Attributes.
|
* lutimes: (libc)File Times.
|
* madvise: (libc)Memory-mapped I/O.
|
* makecontext: (libc)System V contexts.
|
* mallinfo: (libc)Statistics of Malloc.
|
* malloc: (libc)Basic Allocation.
|
* mallopt: (libc)Malloc Tunable Parameters.
|
* mblen: (libc)Non-reentrant Character Conversion.
|
* mbrlen: (libc)Converting a Character.
|
* mbrtowc: (libc)Converting a Character.
|
* mbsinit: (libc)Keeping the state.
|
* mbsnrtowcs: (libc)Converting Strings.
|
* mbsrtowcs: (libc)Converting Strings.
|
* mbstowcs: (libc)Non-reentrant String Conversion.
|
* mbtowc: (libc)Non-reentrant Character Conversion.
|
* mcheck: (libc)Heap Consistency Checking.
|
* memalign: (libc)Aligned Memory Blocks.
|
* memccpy: (libc)Copying Strings and Arrays.
|
* memchr: (libc)Search Functions.
|
* memcmp: (libc)String/Array Comparison.
|
* memcpy: (libc)Copying Strings and Arrays.
|
* memfrob: (libc)Trivial Encryption.
|
* 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.
|
* mlock: (libc)Page Lock Functions.
|
* mlockall: (libc)Page Lock Functions.
|
* mmap64: (libc)Memory-mapped I/O.
|
* mmap: (libc)Memory-mapped I/O.
|
* modf: (libc)Rounding Functions.
|
* modff: (libc)Rounding Functions.
|
* modfl: (libc)Rounding Functions.
|
* mount: (libc)Mount-Unmount-Remount.
|
* mprobe: (libc)Heap Consistency Checking.
|
* mrand48: (libc)SVID Random.
|
* mrand48_r: (libc)SVID Random.
|
* mremap: (libc)Memory-mapped I/O.
|
* msync: (libc)Memory-mapped I/O.
|
* mtrace: (libc)Tracing malloc.
|
* munlock: (libc)Page Lock Functions.
|
* munlockall: (libc)Page Lock Functions.
|
* munmap: (libc)Memory-mapped I/O.
|
* muntrace: (libc)Tracing malloc.
|
* nan: (libc)FP Bit Twiddling.
|
* nanf: (libc)FP Bit Twiddling.
|
* nanl: (libc)FP Bit Twiddling.
|
* nanosleep: (libc)Sleeping.
|
* nearbyint: (libc)Rounding Functions.
|
* nearbyintf: (libc)Rounding Functions.
|
* nearbyintl: (libc)Rounding Functions.
|
* nextafter: (libc)FP Bit Twiddling.
|
* nextafterf: (libc)FP Bit Twiddling.
|
* nextafterl: (libc)FP Bit Twiddling.
|
* nextdown: (libc)FP Bit Twiddling.
|
* nextdownf: (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.
|
* nextupl: (libc)FP Bit Twiddling.
|
* nftw64: (libc)Working with Directory Trees.
|
* nftw: (libc)Working with Directory Trees.
|
* ngettext: (libc)Advanced gettext functions.
|
* nice: (libc)Traditional Scheduling Functions.
|
* nl_langinfo: (libc)The Elegant and Fast Way.
|
* nrand48: (libc)SVID Random.
|
* nrand48_r: (libc)SVID Random.
|
* ntohl: (libc)Byte Order.
|
* ntohs: (libc)Byte Order.
|
* ntp_adjtime: (libc)High Accuracy Clock.
|
* ntp_gettime: (libc)High Accuracy Clock.
|
* obstack_1grow: (libc)Growing Objects.
|
* obstack_1grow_fast: (libc)Extra Fast Growing.
|
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
|
* obstack_alloc: (libc)Allocation in an Obstack.
|
* obstack_base: (libc)Status of an Obstack.
|
* obstack_blank: (libc)Growing Objects.
|
* obstack_blank_fast: (libc)Extra Fast Growing.
|
* obstack_chunk_size: (libc)Obstack Chunks.
|
* obstack_copy0: (libc)Allocation in an Obstack.
|
* obstack_copy: (libc)Allocation in an Obstack.
|
* obstack_finish: (libc)Growing Objects.
|
* obstack_free: (libc)Freeing Obstack Objects.
|
* obstack_grow0: (libc)Growing Objects.
|
* obstack_grow: (libc)Growing Objects.
|
* obstack_init: (libc)Preparing for Obstacks.
|
* obstack_int_grow: (libc)Growing Objects.
|
* obstack_int_grow_fast: (libc)Extra Fast Growing.
|
* obstack_next_free: (libc)Status of an Obstack.
|
* obstack_object_size: (libc)Growing Objects.
|
* obstack_object_size: (libc)Status of an Obstack.
|
* obstack_printf: (libc)Dynamic Output.
|
* obstack_ptr_grow: (libc)Growing Objects.
|
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
|
* obstack_room: (libc)Extra Fast Growing.
|
* obstack_vprintf: (libc)Variable Arguments Output.
|
* offsetof: (libc)Structure Measurement.
|
* on_exit: (libc)Cleanups on Exit.
|
* open64: (libc)Opening and Closing Files.
|
* open: (libc)Opening and Closing Files.
|
* open_memstream: (libc)String Streams.
|
* opendir: (libc)Opening a Directory.
|
* openlog: (libc)openlog.
|
* openpty: (libc)Pseudo-Terminal Pairs.
|
* parse_printf_format: (libc)Parsing a Template String.
|
* pathconf: (libc)Pathconf.
|
* pause: (libc)Using Pause.
|
* pclose: (libc)Pipe to a Subprocess.
|
* perror: (libc)Error Messages.
|
* pipe: (libc)Creating a Pipe.
|
* popen: (libc)Pipe to a Subprocess.
|
* posix_fallocate64: (libc)Storage Allocation.
|
* posix_fallocate: (libc)Storage Allocation.
|
* posix_memalign: (libc)Aligned Memory Blocks.
|
* pow10: (libc)Exponents and Logarithms.
|
* pow10f: (libc)Exponents and Logarithms.
|
* pow10l: (libc)Exponents and Logarithms.
|
* pow: (libc)Exponents and Logarithms.
|
* powf: (libc)Exponents and Logarithms.
|
* powl: (libc)Exponents and Logarithms.
|
* pread64: (libc)I/O Primitives.
|
* pread: (libc)I/O Primitives.
|
* printf: (libc)Formatted Output Functions.
|
* printf_size: (libc)Predefined Printf Handlers.
|
* printf_size_info: (libc)Predefined Printf Handlers.
|
* psignal: (libc)Signal Messages.
|
* pthread_getattr_default_np: (libc)Default Thread Attributes.
|
* pthread_getspecific: (libc)Thread-specific Data.
|
* pthread_key_create: (libc)Thread-specific Data.
|
* pthread_key_delete: (libc)Thread-specific Data.
|
* pthread_setattr_default_np: (libc)Default Thread Attributes.
|
* pthread_setspecific: (libc)Thread-specific Data.
|
* ptsname: (libc)Allocation.
|
* ptsname_r: (libc)Allocation.
|
* putc: (libc)Simple Output.
|
* putc_unlocked: (libc)Simple Output.
|
* putchar: (libc)Simple Output.
|
* putchar_unlocked: (libc)Simple Output.
|
* putenv: (libc)Environment Access.
|
* putpwent: (libc)Writing a User Entry.
|
* puts: (libc)Simple Output.
|
* pututline: (libc)Manipulating the Database.
|
* pututxline: (libc)XPG Functions.
|
* putw: (libc)Simple Output.
|
* putwc: (libc)Simple Output.
|
* putwc_unlocked: (libc)Simple Output.
|
* putwchar: (libc)Simple Output.
|
* putwchar_unlocked: (libc)Simple Output.
|
* pwrite64: (libc)I/O Primitives.
|
* pwrite: (libc)I/O Primitives.
|
* qecvt: (libc)System V Number Conversion.
|
* qecvt_r: (libc)System V Number Conversion.
|
* qfcvt: (libc)System V Number Conversion.
|
* qfcvt_r: (libc)System V Number Conversion.
|
* qgcvt: (libc)System V Number Conversion.
|
* qsort: (libc)Array Sort Function.
|
* raise: (libc)Signaling Yourself.
|
* rand: (libc)ISO Random.
|
* rand_r: (libc)ISO Random.
|
* random: (libc)BSD Random.
|
* random_r: (libc)BSD Random.
|
* rawmemchr: (libc)Search Functions.
|
* read: (libc)I/O Primitives.
|
* readdir64: (libc)Reading/Closing Directory.
|
* readdir64_r: (libc)Reading/Closing Directory.
|
* readdir: (libc)Reading/Closing Directory.
|
* readdir_r: (libc)Reading/Closing Directory.
|
* readlink: (libc)Symbolic Links.
|
* readv: (libc)Scatter-Gather.
|
* realloc: (libc)Changing Block Size.
|
* realpath: (libc)Symbolic Links.
|
* recv: (libc)Receiving Data.
|
* recvfrom: (libc)Receiving Datagrams.
|
* recvmsg: (libc)Receiving Datagrams.
|
* regcomp: (libc)POSIX Regexp Compilation.
|
* regerror: (libc)Regexp Cleanup.
|
* regexec: (libc)Matching POSIX Regexps.
|
* regfree: (libc)Regexp Cleanup.
|
* register_printf_function: (libc)Registering New Conversions.
|
* remainder: (libc)Remainder Functions.
|
* remainderf: (libc)Remainder Functions.
|
* remainderl: (libc)Remainder Functions.
|
* remove: (libc)Deleting Files.
|
* rename: (libc)Renaming Files.
|
* rewind: (libc)File Positioning.
|
* rewinddir: (libc)Random Access Directory.
|
* rindex: (libc)Search Functions.
|
* rint: (libc)Rounding Functions.
|
* rintf: (libc)Rounding Functions.
|
* rintl: (libc)Rounding Functions.
|
* rmdir: (libc)Deleting Files.
|
* round: (libc)Rounding Functions.
|
* roundeven: (libc)Rounding Functions.
|
* roundevenf: (libc)Rounding Functions.
|
* roundevenl: (libc)Rounding Functions.
|
* roundf: (libc)Rounding Functions.
|
* roundl: (libc)Rounding Functions.
|
* rpmatch: (libc)Yes-or-No Questions.
|
* sbrk: (libc)Resizing the Data Segment.
|
* scalb: (libc)Normalization Functions.
|
* scalbf: (libc)Normalization Functions.
|
* scalbl: (libc)Normalization Functions.
|
* scalbln: (libc)Normalization Functions.
|
* scalblnf: (libc)Normalization Functions.
|
* scalblnl: (libc)Normalization Functions.
|
* scalbn: (libc)Normalization Functions.
|
* scalbnf: (libc)Normalization Functions.
|
* scalbnl: (libc)Normalization Functions.
|
* scandir64: (libc)Scanning Directory Content.
|
* scandir: (libc)Scanning Directory Content.
|
* scanf: (libc)Formatted Input Functions.
|
* sched_get_priority_max: (libc)Basic Scheduling Functions.
|
* sched_get_priority_min: (libc)Basic Scheduling Functions.
|
* sched_getaffinity: (libc)CPU Affinity.
|
* sched_getparam: (libc)Basic Scheduling Functions.
|
* sched_getscheduler: (libc)Basic Scheduling Functions.
|
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
|
* sched_setaffinity: (libc)CPU Affinity.
|
* sched_setparam: (libc)Basic Scheduling Functions.
|
* sched_setscheduler: (libc)Basic Scheduling Functions.
|
* sched_yield: (libc)Basic Scheduling Functions.
|
* secure_getenv: (libc)Environment Access.
|
* seed48: (libc)SVID Random.
|
* seed48_r: (libc)SVID Random.
|
* seekdir: (libc)Random Access Directory.
|
* select: (libc)Waiting for I/O.
|
* 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.
|
* setkey: (libc)DES Encryption.
|
* setkey_r: (libc)DES Encryption.
|
* setlinebuf: (libc)Controlling Buffering.
|
* setlocale: (libc)Setting the Locale.
|
* setlogmask: (libc)setlogmask.
|
* setmntent: (libc)mtab.
|
* setnetent: (libc)Networks Database.
|
* setnetgrent: (libc)Lookup Netgroup.
|
* setpayload: (libc)FP Bit Twiddling.
|
* setpayloadf: (libc)FP Bit Twiddling.
|
* setpayloadl: (libc)FP Bit Twiddling.
|
* setpayloadsig: (libc)FP Bit Twiddling.
|
* setpayloadsigf: (libc)FP Bit Twiddling.
|
* setpayloadsigl: (libc)FP Bit Twiddling.
|
* setpgid: (libc)Process Group Functions.
|
* setpgrp: (libc)Process Group Functions.
|
* setpriority: (libc)Traditional Scheduling Functions.
|
* setprotoent: (libc)Protocols Database.
|
* setpwent: (libc)Scanning All Users.
|
* setregid: (libc)Setting Groups.
|
* setreuid: (libc)Setting User ID.
|
* setrlimit64: (libc)Limits on Resources.
|
* setrlimit: (libc)Limits on Resources.
|
* setservent: (libc)Services Database.
|
* setsid: (libc)Process Group Functions.
|
* setsockopt: (libc)Socket Option Functions.
|
* setstate: (libc)BSD Random.
|
* setstate_r: (libc)BSD Random.
|
* settimeofday: (libc)High-Resolution Calendar.
|
* setuid: (libc)Setting User ID.
|
* setutent: (libc)Manipulating the Database.
|
* setutxent: (libc)XPG Functions.
|
* setvbuf: (libc)Controlling Buffering.
|
* shm_open: (libc)Memory-mapped I/O.
|
* shm_unlink: (libc)Memory-mapped I/O.
|
* shutdown: (libc)Closing a Socket.
|
* sigaction: (libc)Advanced Signal Handling.
|
* sigaddset: (libc)Signal Sets.
|
* sigaltstack: (libc)Signal Stack.
|
* sigblock: (libc)BSD Signal Handling.
|
* sigdelset: (libc)Signal Sets.
|
* sigemptyset: (libc)Signal Sets.
|
* sigfillset: (libc)Signal Sets.
|
* siginterrupt: (libc)BSD Signal Handling.
|
* sigismember: (libc)Signal Sets.
|
* siglongjmp: (libc)Non-Local Exits and Signals.
|
* sigmask: (libc)BSD Signal Handling.
|
* signal: (libc)Basic Signal Handling.
|
* signbit: (libc)FP Bit Twiddling.
|
* significand: (libc)Normalization Functions.
|
* significandf: (libc)Normalization Functions.
|
* significandl: (libc)Normalization Functions.
|
* sigpause: (libc)BSD Signal Handling.
|
* sigpending: (libc)Checking for Pending Signals.
|
* sigprocmask: (libc)Process Signal Mask.
|
* sigsetjmp: (libc)Non-Local Exits and Signals.
|
* sigsetmask: (libc)BSD Signal Handling.
|
* sigstack: (libc)Signal Stack.
|
* sigsuspend: (libc)Sigsuspend.
|
* sin: (libc)Trig Functions.
|
* sincos: (libc)Trig Functions.
|
* sincosf: (libc)Trig Functions.
|
* sincosl: (libc)Trig Functions.
|
* sinf: (libc)Trig Functions.
|
* sinh: (libc)Hyperbolic Functions.
|
* sinhf: (libc)Hyperbolic Functions.
|
* sinhl: (libc)Hyperbolic Functions.
|
* sinl: (libc)Trig Functions.
|
* sleep: (libc)Sleeping.
|
* snprintf: (libc)Formatted Output Functions.
|
* socket: (libc)Creating a Socket.
|
* socketpair: (libc)Socket Pairs.
|
* sprintf: (libc)Formatted Output Functions.
|
* sqrt: (libc)Exponents and Logarithms.
|
* sqrtf: (libc)Exponents and Logarithms.
|
* sqrtl: (libc)Exponents and Logarithms.
|
* srand48: (libc)SVID Random.
|
* srand48_r: (libc)SVID Random.
|
* srand: (libc)ISO Random.
|
* srandom: (libc)BSD Random.
|
* srandom_r: (libc)BSD Random.
|
* sscanf: (libc)Formatted Input Functions.
|
* ssignal: (libc)Basic Signal Handling.
|
* stat64: (libc)Reading Attributes.
|
* stat: (libc)Reading Attributes.
|
* stime: (libc)Simple Calendar Time.
|
* stpcpy: (libc)Copying Strings and Arrays.
|
* stpncpy: (libc)Truncating Strings.
|
* strcasecmp: (libc)String/Array Comparison.
|
* strcasestr: (libc)Search Functions.
|
* strcat: (libc)Concatenating Strings.
|
* strchr: (libc)Search Functions.
|
* strchrnul: (libc)Search Functions.
|
* strcmp: (libc)String/Array Comparison.
|
* strcoll: (libc)Collation Functions.
|
* strcpy: (libc)Copying Strings and Arrays.
|
* strcspn: (libc)Search Functions.
|
* strdup: (libc)Copying Strings and Arrays.
|
* strdupa: (libc)Copying Strings and Arrays.
|
* strerror: (libc)Error Messages.
|
* strerror_r: (libc)Error Messages.
|
* strfmon: (libc)Formatting Numbers.
|
* strfromd: (libc)Printing of Floats.
|
* strfromf: (libc)Printing of Floats.
|
* strfroml: (libc)Printing of Floats.
|
* strfry: (libc)strfry.
|
* 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.
|
* strtoimax: (libc)Parsing of Integers.
|
* strtok: (libc)Finding Tokens in a String.
|
* strtok_r: (libc)Finding Tokens in a String.
|
* strtol: (libc)Parsing of Integers.
|
* strtold: (libc)Parsing of Floats.
|
* strtoll: (libc)Parsing of Integers.
|
* strtoq: (libc)Parsing of Integers.
|
* strtoul: (libc)Parsing of Integers.
|
* strtoull: (libc)Parsing of Integers.
|
* strtoumax: (libc)Parsing of Integers.
|
* strtouq: (libc)Parsing of Integers.
|
* strverscmp: (libc)String/Array Comparison.
|
* strxfrm: (libc)Collation Functions.
|
* stty: (libc)BSD Terminal Modes.
|
* swapcontext: (libc)System V contexts.
|
* swprintf: (libc)Formatted Output Functions.
|
* swscanf: (libc)Formatted Input Functions.
|
* symlink: (libc)Symbolic Links.
|
* sync: (libc)Synchronizing I/O.
|
* syscall: (libc)System Calls.
|
* sysconf: (libc)Sysconf Definition.
|
* sysctl: (libc)System Parameters.
|
* syslog: (libc)syslog; vsyslog.
|
* system: (libc)Running a Command.
|
* sysv_signal: (libc)Basic Signal Handling.
|
* tan: (libc)Trig Functions.
|
* tanf: (libc)Trig Functions.
|
* tanh: (libc)Hyperbolic Functions.
|
* tanhf: (libc)Hyperbolic Functions.
|
* tanhl: (libc)Hyperbolic Functions.
|
* tanl: (libc)Trig Functions.
|
* tcdrain: (libc)Line Control.
|
* tcflow: (libc)Line Control.
|
* tcflush: (libc)Line Control.
|
* tcgetattr: (libc)Mode Functions.
|
* tcgetpgrp: (libc)Terminal Access Functions.
|
* tcgetsid: (libc)Terminal Access Functions.
|
* tcsendbreak: (libc)Line Control.
|
* tcsetattr: (libc)Mode Functions.
|
* tcsetpgrp: (libc)Terminal Access Functions.
|
* tdelete: (libc)Tree Search Function.
|
* tdestroy: (libc)Tree Search Function.
|
* telldir: (libc)Random Access Directory.
|
* tempnam: (libc)Temporary Files.
|
* textdomain: (libc)Locating gettext catalog.
|
* tfind: (libc)Tree Search Function.
|
* tgamma: (libc)Special Functions.
|
* tgammaf: (libc)Special Functions.
|
* tgammal: (libc)Special Functions.
|
* time: (libc)Simple Calendar Time.
|
* timegm: (libc)Broken-down Time.
|
* timelocal: (libc)Broken-down Time.
|
* times: (libc)Processor Time.
|
* tmpfile64: (libc)Temporary Files.
|
* tmpfile: (libc)Temporary Files.
|
* tmpnam: (libc)Temporary Files.
|
* tmpnam_r: (libc)Temporary Files.
|
* toascii: (libc)Case Conversion.
|
* tolower: (libc)Case Conversion.
|
* totalorder: (libc)FP Comparison Functions.
|
* totalorderf: (libc)FP Comparison Functions.
|
* totalorderl: (libc)FP Comparison Functions.
|
* totalordermag: (libc)FP Comparison Functions.
|
* totalordermagf: (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.
|
* truncl: (libc)Rounding Functions.
|
* tsearch: (libc)Tree Search Function.
|
* ttyname: (libc)Is It a Terminal.
|
* ttyname_r: (libc)Is It a Terminal.
|
* twalk: (libc)Tree Search Function.
|
* tzset: (libc)Time Zone Functions.
|
* ufromfp: (libc)Rounding Functions.
|
* ufromfpf: (libc)Rounding Functions.
|
* ufromfpl: (libc)Rounding Functions.
|
* ufromfpx: (libc)Rounding Functions.
|
* ufromfpxf: (libc)Rounding Functions.
|
* ufromfpxl: (libc)Rounding Functions.
|
* ulimit: (libc)Limits on Resources.
|
* umask: (libc)Setting Permissions.
|
* umount2: (libc)Mount-Unmount-Remount.
|
* umount: (libc)Mount-Unmount-Remount.
|
* uname: (libc)Platform Type.
|
* ungetc: (libc)How Unread.
|
* ungetwc: (libc)How Unread.
|
* unlink: (libc)Deleting Files.
|
* unlockpt: (libc)Allocation.
|
* unsetenv: (libc)Environment Access.
|
* updwtmp: (libc)Manipulating the Database.
|
* utime: (libc)File Times.
|
* utimes: (libc)File Times.
|
* utmpname: (libc)Manipulating the Database.
|
* utmpxname: (libc)XPG Functions.
|
* va_arg: (libc)Argument Macros.
|
* va_copy: (libc)Argument Macros.
|
* va_end: (libc)Argument Macros.
|
* va_start: (libc)Argument Macros.
|
* valloc: (libc)Aligned Memory Blocks.
|
* vasprintf: (libc)Variable Arguments Output.
|
* verr: (libc)Error Messages.
|
* verrx: (libc)Error Messages.
|
* versionsort64: (libc)Scanning Directory Content.
|
* versionsort: (libc)Scanning Directory Content.
|
* vfork: (libc)Creating a Process.
|
* vfprintf: (libc)Variable Arguments Output.
|
* vfscanf: (libc)Variable Arguments Input.
|
* vfwprintf: (libc)Variable Arguments Output.
|
* vfwscanf: (libc)Variable Arguments Input.
|
* vlimit: (libc)Limits on Resources.
|
* vprintf: (libc)Variable Arguments Output.
|
* vscanf: (libc)Variable Arguments Input.
|
* vsnprintf: (libc)Variable Arguments Output.
|
* vsprintf: (libc)Variable Arguments Output.
|
* vsscanf: (libc)Variable Arguments Input.
|
* vswprintf: (libc)Variable Arguments Output.
|
* vswscanf: (libc)Variable Arguments Input.
|
* vsyslog: (libc)syslog; vsyslog.
|
* vtimes: (libc)Resource Usage.
|
* vwarn: (libc)Error Messages.
|
* vwarnx: (libc)Error Messages.
|
* vwprintf: (libc)Variable Arguments Output.
|
* vwscanf: (libc)Variable Arguments Input.
|
* wait3: (libc)BSD Wait Functions.
|
* wait4: (libc)Process Completion.
|
* wait: (libc)Process Completion.
|
* waitpid: (libc)Process Completion.
|
* warn: (libc)Error Messages.
|
* warnx: (libc)Error Messages.
|
* wcpcpy: (libc)Copying Strings and Arrays.
|
* wcpncpy: (libc)Truncating Strings.
|
* wcrtomb: (libc)Converting a Character.
|
* wcscasecmp: (libc)String/Array Comparison.
|
* wcscat: (libc)Concatenating Strings.
|
* wcschr: (libc)Search Functions.
|
* wcschrnul: (libc)Search Functions.
|
* wcscmp: (libc)String/Array Comparison.
|
* wcscoll: (libc)Collation Functions.
|
* wcscpy: (libc)Copying Strings and Arrays.
|
* wcscspn: (libc)Search Functions.
|
* wcsdup: (libc)Copying Strings and Arrays.
|
* wcsftime: (libc)Formatting Calendar Time.
|
* wcslen: (libc)String Length.
|
* wcsncasecmp: (libc)String/Array Comparison.
|
* wcsncat: (libc)Truncating Strings.
|
* wcsncmp: (libc)String/Array Comparison.
|
* wcsncpy: (libc)Truncating Strings.
|
* wcsnlen: (libc)String Length.
|
* wcsnrtombs: (libc)Converting Strings.
|
* wcspbrk: (libc)Search Functions.
|
* wcsrchr: (libc)Search Functions.
|
* wcsrtombs: (libc)Converting Strings.
|
* wcsspn: (libc)Search Functions.
|
* wcsstr: (libc)Search Functions.
|
* wcstod: (libc)Parsing of Floats.
|
* wcstof: (libc)Parsing of Floats.
|
* 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.
|
* y0l: (libc)Special Functions.
|
* y1: (libc)Special Functions.
|
* y1f: (libc)Special Functions.
|
* y1l: (libc)Special Functions.
|
* yn: (libc)Special Functions.
|
* ynf: (libc)Special Functions.
|
* ynl: (libc)Special Functions.
|
END-INFO-DIR-ENTRY
|
|
|
File: libc.info, Node: Defining the Output Handler, Next: Printf Extension Example, Prev: Conversion Specifier Options, Up: Customizing Printf
|
|
12.13.3 Defining the Output Handler
|
-----------------------------------
|
|
Now let’s look at how to define the handler and arginfo functions which
|
are passed as arguments to ‘register_printf_function’.
|
|
*Compatibility Note:* The interface changed in the GNU C Library
|
version 2.0. Previously the third argument was of type ‘va_list *’.
|
|
You should define your handler functions with a prototype like:
|
|
int FUNCTION (FILE *stream, const struct printf_info *info,
|
const void *const *args)
|
|
The STREAM argument passed to the handler function is the stream to
|
which it should write output.
|
|
The INFO argument is a pointer to a structure that contains
|
information about the various options that were included with the
|
conversion in the template string. You should not modify this structure
|
inside your handler function. *Note Conversion Specifier Options::, for
|
a description of this data structure.
|
|
The ARGS is a vector of pointers to the arguments data. The number
|
of arguments was determined by calling the argument information function
|
provided by the user.
|
|
Your handler function should return a value just like ‘printf’ does:
|
it should return the number of characters it has written, or a negative
|
value to indicate an error.
|
|
-- Data Type: printf_function
|
This is the data type that a handler function should have.
|
|
If you are going to use ‘parse_printf_format’ in your application,
|
you must also define a function to pass as the ARGINFO-FUNCTION argument
|
for each new conversion you install with ‘register_printf_function’.
|
|
You have to define these functions with a prototype like:
|
|
int FUNCTION (const struct printf_info *info,
|
size_t n, int *argtypes)
|
|
The return value from the function should be the number of arguments
|
the conversion expects. The function should also fill in no more than N
|
elements of the ARGTYPES array with information about the types of each
|
of these arguments. This information is encoded using the various ‘PA_’
|
macros. (You will notice that this is the same calling convention
|
‘parse_printf_format’ itself uses.)
|
|
-- Data Type: printf_arginfo_function
|
This type is used to describe functions that return information
|
about the number and type of arguments used by a conversion
|
specifier.
|
|
|
File: libc.info, Node: Printf Extension Example, Next: Predefined Printf Handlers, Prev: Defining the Output Handler, Up: Customizing Printf
|
|
12.13.4 ‘printf’ Extension Example
|
----------------------------------
|
|
Here is an example showing how to define a ‘printf’ handler function.
|
This program defines a data structure called a ‘Widget’ and defines the
|
‘%W’ conversion to print information about ‘Widget *’ arguments,
|
including the pointer value and the name stored in the data structure.
|
The ‘%W’ conversion supports the minimum field width and
|
left-justification options, but ignores everything else.
|
|
|
#include <stdio.h>
|
#include <stdlib.h>
|
#include <printf.h>
|
|
typedef struct
|
{
|
char *name;
|
}
|
Widget;
|
|
int
|
print_widget (FILE *stream,
|
const struct printf_info *info,
|
const void *const *args)
|
{
|
const Widget *w;
|
char *buffer;
|
int len;
|
|
/* Format the output into a string. */
|
w = *((const Widget **) (args[0]));
|
len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
|
if (len == -1)
|
return -1;
|
|
/* Pad to the minimum field width and print to the stream. */
|
len = fprintf (stream, "%*s",
|
(info->left ? -info->width : info->width),
|
buffer);
|
|
/* Clean up and return. */
|
free (buffer);
|
return len;
|
}
|
|
|
int
|
print_widget_arginfo (const struct printf_info *info, size_t n,
|
int *argtypes)
|
{
|
/* We always take exactly one argument and this is a pointer to the
|
structure.. */
|
if (n > 0)
|
argtypes[0] = PA_POINTER;
|
return 1;
|
}
|
|
|
int
|
main (void)
|
{
|
/* Make a widget to print. */
|
Widget mywidget;
|
mywidget.name = "mywidget";
|
|
/* Register the print function for widgets. */
|
register_printf_function ('W', print_widget, print_widget_arginfo);
|
|
/* Now print the widget. */
|
printf ("|%W|\n", &mywidget);
|
printf ("|%35W|\n", &mywidget);
|
printf ("|%-35W|\n", &mywidget);
|
|
return 0;
|
}
|
|
The output produced by this program looks like:
|
|
|<Widget 0xffeffb7c: mywidget>|
|
| <Widget 0xffeffb7c: mywidget>|
|
|<Widget 0xffeffb7c: mywidget> |
|
|
|
File: libc.info, Node: Predefined Printf Handlers, Prev: Printf Extension Example, Up: Customizing Printf
|
|
12.13.5 Predefined ‘printf’ Handlers
|
------------------------------------
|
|
The GNU C Library also contains a concrete and useful application of the
|
‘printf’ handler extension. There are two functions available which
|
implement a special way to print floating-point numbers.
|
|
-- Function: int printf_size (FILE *FP, const struct printf_info *INFO,
|
const void *const *ARGS)
|
Preliminary: | MT-Safe race:fp locale | AS-Unsafe corrupt heap |
|
AC-Unsafe mem corrupt | *Note POSIX Safety Concepts::.
|
|
Print a given floating point number as for the format ‘%f’ except
|
that there is a postfix character indicating the divisor for the
|
number to make this less than 1000. There are two possible
|
divisors: powers of 1024 or powers of 1000. Which one is used
|
depends on the format character specified while registered this
|
handler. If the character is of lower case, 1024 is used. For
|
upper case characters, 1000 is used.
|
|
The postfix tag corresponds to bytes, kilobytes, megabytes,
|
gigabytes, etc. The full table is:
|
|
low Multiplier From Upper Multiplier
|
’ ’ 1 ’ ’ 1
|
k 2^10 (1024) kilo K 10^3 (1000)
|
m 2^20 mega M 10^6
|
g 2^30 giga G 10^9
|
t 2^40 tera T 10^12
|
p 2^50 peta P 10^15
|
e 2^60 exa E 10^18
|
z 2^70 zetta Z 10^21
|
y 2^80 yotta Y 10^24
|
|
The default precision is 3, i.e., 1024 is printed with a lower-case
|
format character as if it were ‘%.3fk’ and will yield ‘1.000k’.
|
|
Due to the requirements of ‘register_printf_function’ we must also
|
provide the function which returns information about the arguments.
|
|
-- Function: int printf_size_info (const struct printf_info *INFO,
|
size_t N, int *ARGTYPES)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function will return in ARGTYPES the information about the
|
used parameters in the way the ‘vfprintf’ implementation expects
|
it. The format always takes one argument.
|
|
To use these functions both functions must be registered with a call
|
like
|
|
register_printf_function ('B', printf_size, printf_size_info);
|
|
Here we register the functions to print numbers as powers of 1000
|
since the format character ‘'B'’ is an upper-case character. If we
|
would additionally use ‘'b'’ in a line like
|
|
register_printf_function ('b', printf_size, printf_size_info);
|
|
we could also print using a power of 1024. Please note that all that is
|
different in these two lines is the format specifier. The ‘printf_size’
|
function knows about the difference between lower and upper case format
|
specifiers.
|
|
The use of ‘'B'’ and ‘'b'’ is no coincidence. Rather it is the
|
preferred way to use this functionality since it is available on some
|
other systems which also use format specifiers.
|
|
|
File: libc.info, Node: Formatted Input, Next: EOF and Errors, Prev: Customizing Printf, Up: I/O on Streams
|
|
12.14 Formatted Input
|
=====================
|
|
The functions described in this section (‘scanf’ and related functions)
|
provide facilities for formatted input analogous to the formatted output
|
facilities. These functions provide a mechanism for reading arbitrary
|
values under the control of a "format string" or "template string".
|
|
* Menu:
|
|
* Formatted Input Basics:: Some basics to get you started.
|
* Input Conversion Syntax:: Syntax of conversion specifications.
|
* Table of Input Conversions:: Summary of input conversions and what they do.
|
* Numeric Input Conversions:: Details of conversions for reading numbers.
|
* String Input Conversions:: Details of conversions for reading strings.
|
* Dynamic String Input:: String conversions that ‘malloc’ the buffer.
|
* Other Input Conversions:: Details of miscellaneous other conversions.
|
* Formatted Input Functions:: Descriptions of the actual functions.
|
* Variable Arguments Input:: ‘vscanf’ and friends.
|
|
|
File: libc.info, Node: Formatted Input Basics, Next: Input Conversion Syntax, Up: Formatted Input
|
|
12.14.1 Formatted Input Basics
|
------------------------------
|
|
Calls to ‘scanf’ are superficially similar to calls to ‘printf’ in that
|
arbitrary arguments are read under the control of a template string.
|
While the syntax of the conversion specifications in the template is
|
very similar to that for ‘printf’, the interpretation of the template is
|
oriented more towards free-format input and simple pattern matching,
|
rather than fixed-field formatting. For example, most ‘scanf’
|
conversions skip over any amount of “white space” (including spaces,
|
tabs, and newlines) in the input file, and there is no concept of
|
precision for the numeric input conversions as there is for the
|
corresponding output conversions. Ordinarily, non-whitespace characters
|
in the template are expected to match characters in the input stream
|
exactly, but a matching failure is distinct from an input error on the
|
stream.
|
|
Another area of difference between ‘scanf’ and ‘printf’ is that you
|
must remember to supply pointers rather than immediate values as the
|
optional arguments to ‘scanf’; the values that are read are stored in
|
the objects that the pointers point to. Even experienced programmers
|
tend to forget this occasionally, so if your program is getting strange
|
errors that seem to be related to ‘scanf’, you might want to
|
double-check this.
|
|
When a "matching failure" occurs, ‘scanf’ returns immediately,
|
leaving the first non-matching character as the next character to be
|
read from the stream. The normal return value from ‘scanf’ is the
|
number of values that were assigned, so you can use this to determine if
|
a matching error happened before all the expected values were read.
|
|
The ‘scanf’ function is typically used for things like reading in the
|
contents of tables. For example, here is a function that uses ‘scanf’
|
to initialize an array of ‘double’:
|
|
void
|
readarray (double *array, int n)
|
{
|
int i;
|
for (i=0; i<n; i++)
|
if (scanf (" %lf", &(array[i])) != 1)
|
invalid_input_error ();
|
}
|
|
The formatted input functions are not used as frequently as the
|
formatted output functions. Partly, this is because it takes some care
|
to use them properly. Another reason is that it is difficult to recover
|
from a matching error.
|
|
If you are trying to read input that doesn’t match a single, fixed
|
pattern, you may be better off using a tool such as Flex to generate a
|
lexical scanner, or Bison to generate a parser, rather than using
|
‘scanf’. For more information about these tools, see *note
|
(flex.info)Top::, and *note (bison.info)Top::.
|
|
|
File: libc.info, Node: Input Conversion Syntax, Next: Table of Input Conversions, Prev: Formatted Input Basics, Up: Formatted Input
|
|
12.14.2 Input Conversion Syntax
|
-------------------------------
|
|
A ‘scanf’ template string is a string that contains ordinary multibyte
|
characters interspersed with conversion specifications that start with
|
‘%’.
|
|
Any whitespace character (as defined by the ‘isspace’ function; *note
|
Classification of Characters::) in the template causes any number of
|
whitespace characters in the input stream to be read and discarded. The
|
whitespace characters that are matched need not be exactly the same
|
whitespace characters that appear in the template string. For example,
|
write ‘ , ’ in the template to recognize a comma with optional
|
whitespace before and after.
|
|
Other characters in the template string that are not part of
|
conversion specifications must match characters in the input stream
|
exactly; if this is not the case, a matching failure occurs.
|
|
The conversion specifications in a ‘scanf’ template string have the
|
general form:
|
|
% FLAGS WIDTH TYPE CONVERSION
|
|
In more detail, an input conversion specification consists of an
|
initial ‘%’ character followed in sequence by:
|
|
• An optional "flag character" ‘*’, which says to ignore the text
|
read for this specification. When ‘scanf’ finds a conversion
|
specification that uses this flag, it reads input as directed by
|
the rest of the conversion specification, but it discards this
|
input, does not use a pointer argument, and does not increment the
|
count of successful assignments.
|
|
• An optional flag character ‘a’ (valid with string conversions only)
|
which requests allocation of a buffer long enough to store the
|
string in. (This is a GNU extension.) *Note Dynamic String
|
Input::.
|
|
• An optional decimal integer that specifies the "maximum field
|
width". Reading of characters from the input stream stops either
|
when this maximum is reached or when a non-matching character is
|
found, whichever happens first. Most conversions discard initial
|
whitespace characters (those that don’t are explicitly documented),
|
and these discarded characters don’t count towards the maximum
|
field width. String input conversions store a null character to
|
mark the end of the input; the maximum field width does not include
|
this terminator.
|
|
• An optional "type modifier character". For example, you can
|
specify a type modifier of ‘l’ with integer conversions such as
|
‘%d’ to specify that the argument is a pointer to a ‘long int’
|
rather than a pointer to an ‘int’.
|
|
• A character that specifies the conversion to be applied.
|
|
The exact options that are permitted and how they are interpreted
|
vary between the different conversion specifiers. See the descriptions
|
of the individual conversions for information about the particular
|
options that they allow.
|
|
With the ‘-Wformat’ option, the GNU C compiler checks calls to
|
‘scanf’ and related functions. It examines the format string and
|
verifies that the correct number and types of arguments are supplied.
|
There is also a GNU C syntax to tell the compiler that a function you
|
write uses a ‘scanf’-style format string. *Note Declaring Attributes of
|
Functions: (gcc.info)Function Attributes, for more information.
|
|
|
File: libc.info, Node: Table of Input Conversions, Next: Numeric Input Conversions, Prev: Input Conversion Syntax, Up: Formatted Input
|
|
12.14.3 Table of Input Conversions
|
----------------------------------
|
|
Here is a table that summarizes the various conversion specifications:
|
|
‘%d’
|
Matches an optionally signed integer written in decimal. *Note
|
Numeric Input Conversions::.
|
|
‘%i’
|
Matches an optionally signed integer in any of the formats that the
|
C language defines for specifying an integer constant. *Note
|
Numeric Input Conversions::.
|
|
‘%o’
|
Matches an unsigned integer written in octal radix. *Note Numeric
|
Input Conversions::.
|
|
‘%u’
|
Matches an unsigned integer written in decimal radix. *Note
|
Numeric Input Conversions::.
|
|
‘%x’, ‘%X’
|
Matches an unsigned integer written in hexadecimal radix. *Note
|
Numeric Input Conversions::.
|
|
‘%e’, ‘%f’, ‘%g’, ‘%E’, ‘%G’
|
Matches an optionally signed floating-point number. *Note Numeric
|
Input Conversions::.
|
|
‘%s’
|
|
Matches a string containing only non-whitespace characters. *Note
|
String Input Conversions::. The presence of the ‘l’ modifier
|
determines whether the output is stored as a wide character string
|
or a multibyte string. If ‘%s’ is used in a wide character
|
function the string is converted as with multiple calls to
|
‘wcrtomb’ into a multibyte string. This means that the buffer must
|
provide room for ‘MB_CUR_MAX’ bytes for each wide character read.
|
In case ‘%ls’ is used in a multibyte function the result is
|
converted into wide characters as with multiple calls of ‘mbrtowc’
|
before being stored in the user provided buffer.
|
|
‘%S’
|
This is an alias for ‘%ls’ which is supported for compatibility
|
with the Unix standard.
|
|
‘%[’
|
Matches a string of characters that belong to a specified set.
|
*Note String Input Conversions::. The presence of the ‘l’ modifier
|
determines whether the output is stored as a wide character string
|
or a multibyte string. If ‘%[’ is used in a wide character
|
function the string is converted as with multiple calls to
|
‘wcrtomb’ into a multibyte string. This means that the buffer must
|
provide room for ‘MB_CUR_MAX’ bytes for each wide character read.
|
In case ‘%l[’ is used in a multibyte function the result is
|
converted into wide characters as with multiple calls of ‘mbrtowc’
|
before being stored in the user provided buffer.
|
|
‘%c’
|
Matches a string of one or more characters; the number of
|
characters read is controlled by the maximum field width given for
|
the conversion. *Note String Input Conversions::.
|
|
If ‘%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.info)Function
|
Attributes.
|
|
|
File: libc.info, Node: EOF and Errors, Next: Error Recovery, Prev: Formatted Input, Up: I/O on Streams
|
|
12.15 End-Of-File and Errors
|
============================
|
|
Many of the functions described in this chapter return the value of the
|
macro ‘EOF’ to indicate unsuccessful completion of the operation. Since
|
‘EOF’ is used to report both end of file and random errors, it’s often
|
better to use the ‘feof’ function to check explicitly for end of file
|
and ‘ferror’ to check for errors. These functions check indicators that
|
are part of the internal state of the stream object, indicators set if
|
the appropriate condition was detected by a previous I/O operation on
|
that stream.
|
|
-- Macro: int EOF
|
This macro is an integer value that is returned by a number of
|
narrow stream functions to indicate an end-of-file condition, or
|
some other error situation. With the GNU C Library, ‘EOF’ is ‘-1’.
|
In other libraries, its value may be some other negative number.
|
|
This symbol is declared in ‘stdio.h’.
|
|
-- Macro: int WEOF
|
This macro is an integer value that is returned by a number of wide
|
stream functions to indicate an end-of-file condition, or some
|
other error situation. With the GNU C Library, ‘WEOF’ is ‘-1’. In
|
other libraries, its value may be some other negative number.
|
|
This symbol is declared in ‘wchar.h’.
|
|
-- Function: int feof (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
|
Safety Concepts::.
|
|
The ‘feof’ function returns nonzero if and only if the end-of-file
|
indicator for the stream STREAM is set.
|
|
This symbol is declared in ‘stdio.h’.
|
|
-- Function: int feof_unlocked (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘feof_unlocked’ function is equivalent to the ‘feof’ function
|
except that it does not implicitly lock the stream.
|
|
This function is a GNU extension.
|
|
This symbol is declared in ‘stdio.h’.
|
|
-- Function: int ferror (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
|
Safety Concepts::.
|
|
The ‘ferror’ function returns nonzero if and only if the error
|
indicator for the stream STREAM is set, indicating that an error
|
has occurred on a previous operation on the stream.
|
|
This symbol is declared in ‘stdio.h’.
|
|
-- Function: int ferror_unlocked (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘ferror_unlocked’ function is equivalent to the ‘ferror’
|
function except that it does not implicitly lock the stream.
|
|
This function is a GNU extension.
|
|
This symbol is declared in ‘stdio.h’.
|
|
In addition to setting the error indicator associated with the
|
stream, the functions that operate on streams also set ‘errno’ in the
|
same way as the corresponding low-level functions that operate on file
|
descriptors. For example, all of the functions that perform output to a
|
stream—such as ‘fputc’, ‘printf’, and ‘fflush’—are implemented in terms
|
of ‘write’, and all of the ‘errno’ error conditions defined for ‘write’
|
are meaningful for these functions. For more information about the
|
descriptor-level I/O functions, see *note Low-Level I/O::.
|
|
|
File: libc.info, Node: Error Recovery, Next: Binary Streams, Prev: EOF and Errors, Up: I/O on Streams
|
|
12.16 Recovering from errors
|
============================
|
|
You may explicitly clear the error and EOF flags with the ‘clearerr’
|
function.
|
|
-- Function: void clearerr (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
|
Safety Concepts::.
|
|
This function clears the end-of-file and error indicators for the
|
stream STREAM.
|
|
The file positioning functions (*note File Positioning::) also
|
clear the end-of-file indicator for the stream.
|
|
-- Function: void clearerr_unlocked (FILE *STREAM)
|
Preliminary: | MT-Safe race:stream | AS-Safe | AC-Safe | *Note
|
POSIX Safety Concepts::.
|
|
The ‘clearerr_unlocked’ function is equivalent to the ‘clearerr’
|
function except that it does not implicitly lock the stream.
|
|
This function is a GNU extension.
|
|
Note that it is _not_ correct to just clear the error flag and retry
|
a failed stream operation. After a failed write, any number of
|
characters since the last buffer flush may have been committed to the
|
file, while some buffered data may have been discarded. Merely retrying
|
can thus cause lost or repeated data.
|
|
A failed read may leave the file pointer in an inappropriate position
|
for a second try. In both cases, you should seek to a known position
|
before retrying.
|
|
Most errors that can happen are not recoverable — a second try will
|
always fail again in the same way. So usually it is best to give up and
|
report the error to the user, rather than install complicated recovery
|
logic.
|
|
One important exception is ‘EINTR’ (*note Interrupted Primitives::).
|
Many stream I/O implementations will treat it as an ordinary error,
|
which can be quite inconvenient. You can avoid this hassle by
|
installing all signals with the ‘SA_RESTART’ flag.
|
|
For similar reasons, setting nonblocking I/O on a stream’s file
|
descriptor is not usually advisable.
|
|
|
File: libc.info, Node: Binary Streams, Next: File Positioning, Prev: Error Recovery, Up: I/O on Streams
|
|
12.17 Text and Binary Streams
|
=============================
|
|
GNU systems and other POSIX-compatible operating systems organize all
|
files as uniform sequences of characters. However, some other systems
|
make a distinction between files containing text and files containing
|
binary data, and the input and output facilities of ISO C provide for
|
this distinction. This section tells you how to write programs portable
|
to such systems.
|
|
When you open a stream, you can specify either a "text stream" or a
|
"binary stream". You indicate that you want a binary stream by
|
specifying the ‘b’ modifier in the OPENTYPE argument to ‘fopen’; see
|
*note Opening Streams::. Without this option, ‘fopen’ opens the file as
|
a text stream.
|
|
Text and binary streams differ in several ways:
|
|
• The data read from a text stream is divided into "lines" which are
|
terminated by newline (‘'\n'’) characters, while a binary stream is
|
simply a long series of characters. A text stream might on some
|
systems fail to handle lines more than 254 characters long
|
(including the terminating newline character).
|
|
• On some systems, text files can contain only printing characters,
|
horizontal tab characters, and newlines, and so text streams may
|
not support other characters. However, binary streams can handle
|
any character value.
|
|
• Space characters that are written immediately preceding a newline
|
character in a text stream may disappear when the file is read in
|
again.
|
|
• More generally, there need not be a one-to-one mapping between
|
characters that are read from or written to a text stream, and the
|
characters in the actual file.
|
|
Since a binary stream is always more capable and more predictable
|
than a text stream, you might wonder what purpose text streams serve.
|
Why not simply always use binary streams? The answer is that on these
|
operating systems, text and binary streams use different file formats,
|
and the only way to read or write “an ordinary file of text” that can
|
work with other text-oriented programs is through a text stream.
|
|
In the GNU C Library, and on all POSIX systems, there is no
|
difference between text streams and binary streams. When you open a
|
stream, you get the same kind of stream regardless of whether you ask
|
for binary. This stream can handle any file content, and has none of
|
the restrictions that text streams sometimes have.
|
|
|
File: libc.info, Node: File Positioning, Next: Portable Positioning, Prev: Binary Streams, Up: I/O on Streams
|
|
12.18 File Positioning
|
======================
|
|
The "file position" of a stream describes where in the file the stream
|
is currently reading or writing. I/O on the stream advances the file
|
position through the file. On GNU systems, the file position is
|
represented as an integer, which counts the number of bytes from the
|
beginning of the file. *Note File Position::.
|
|
During I/O to an ordinary disk file, you can change the file position
|
whenever you wish, so as to read or write any portion of the file. Some
|
other kinds of files may also permit this. Files which support changing
|
the file position are sometimes referred to as "random-access" files.
|
|
You can use the functions in this section to examine or modify the
|
file position indicator associated with a stream. The symbols listed
|
below are declared in the header file ‘stdio.h’.
|
|
-- Function: long int ftell (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function returns the current file position of the stream
|
STREAM.
|
|
This function can fail if the stream doesn’t support file
|
positioning, or if the file position can’t be represented in a
|
‘long int’, and possibly for other reasons as well. If a failure
|
occurs, a value of ‘-1’ is returned.
|
|
-- Function: off_t ftello (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
The ‘ftello’ function is similar to ‘ftell’, except that it returns
|
a value of type ‘off_t’. Systems which support this type use it to
|
describe all file positions, unlike the POSIX specification which
|
uses a long int. The two are not necessarily the same size.
|
Therefore, using ftell can lead to problems if the implementation
|
is written on top of a POSIX compliant low-level I/O
|
implementation, and using ‘ftello’ is preferable whenever it is
|
available.
|
|
If this function fails it returns ‘(off_t) -1’. This can happen
|
due to missing support for file positioning or internal errors.
|
Otherwise the return value is the current file position.
|
|
The function is an extension defined in the Unix Single
|
Specification version 2.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32 bit system this function is in fact ‘ftello64’. I.e., the LFS
|
interface transparently replaces the old interface.
|
|
-- Function: off64_t ftello64 (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘ftello’ with the only difference that
|
the return value is of type ‘off64_t’. This also requires that the
|
stream STREAM was opened using either ‘fopen64’, ‘freopen64’, or
|
‘tmpfile64’ since otherwise the underlying file operations to
|
position the file pointer beyond the 2^31 bytes limit might fail.
|
|
If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
|
bits machine this function is available under the name ‘ftello’ and
|
so transparently replaces the old interface.
|
|
-- Function: int fseek (FILE *STREAM, long int OFFSET, int WHENCE)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
The ‘fseek’ function is used to change the file position of the
|
stream STREAM. The value of WHENCE must be one of the constants
|
‘SEEK_SET’, ‘SEEK_CUR’, or ‘SEEK_END’, to indicate whether the
|
OFFSET is relative to the beginning of the file, the current file
|
position, or the end of the file, respectively.
|
|
This function returns a value of zero if the operation was
|
successful, and a nonzero value to indicate failure. A successful
|
call also clears the end-of-file indicator of STREAM and discards
|
any characters that were “pushed back” by the use of ‘ungetc’.
|
|
‘fseek’ either flushes any buffered output before setting the file
|
position or else remembers it so it will be written later in its
|
proper place in the file.
|
|
-- Function: int fseeko (FILE *STREAM, off_t OFFSET, int WHENCE)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘fseek’ but it corrects a problem with
|
‘fseek’ in a system with POSIX types. Using a value of type ‘long
|
int’ for the offset is not compatible with POSIX. ‘fseeko’ uses the
|
correct type ‘off_t’ for the OFFSET parameter.
|
|
For this reason it is a good idea to prefer ‘ftello’ whenever it is
|
available since its functionality is (if different at all) closer
|
the underlying definition.
|
|
The functionality and return value 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.
|
* 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.
|
|
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’.
|
|
|
File: libc.info, Node: Descriptors and Streams, Next: Stream/Descriptor Precautions, Prev: File Position Primitive, Up: Low-Level I/O
|
|
13.4 Descriptors and Streams
|
============================
|
|
Given an open file descriptor, you can create a stream for it with the
|
‘fdopen’ function. You can get the underlying file descriptor for an
|
existing stream with the ‘fileno’ function. These functions are
|
declared in the header file ‘stdio.h’.
|
|
-- Function: FILE * fdopen (int FILEDES, const char *OPENTYPE)
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
|
*Note POSIX Safety Concepts::.
|
|
The ‘fdopen’ function returns a new stream for the file descriptor
|
FILEDES.
|
|
The OPENTYPE argument is interpreted in the same way as for the
|
‘fopen’ function (*note Opening Streams::), except that the ‘b’
|
option is not permitted; this is because GNU systems make no
|
distinction between text and binary files. Also, ‘"w"’ and ‘"w+"’
|
do not cause truncation of the file; these have an effect only when
|
opening a file, and in this case the file has already been opened.
|
You must make sure that the OPENTYPE argument matches the actual
|
mode of the open file descriptor.
|
|
The return value is the new stream. If the stream cannot be
|
created (for example, if the modes for the file indicated by the
|
file descriptor do not permit the access specified by the OPENTYPE
|
argument), a null pointer is returned instead.
|
|
In some other systems, ‘fdopen’ may fail to detect that the modes
|
for file descriptors do not permit the access specified by
|
‘opentype’. The GNU C Library always checks for this.
|
|
For an example showing the use of the ‘fdopen’ function, see *note
|
Creating a Pipe::.
|
|
-- Function: int fileno (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function returns the file descriptor associated with the
|
stream STREAM. If an error is detected (for example, if the STREAM
|
is not valid) or if STREAM does not do I/O to a file, ‘fileno’
|
returns -1.
|
|
-- Function: int fileno_unlocked (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘fileno_unlocked’ function is equivalent to the ‘fileno’
|
function except that it does not implicitly lock the stream if the
|
state is ‘FSETLOCKING_INTERNAL’.
|
|
This function is a GNU extension.
|
|
There are also symbolic constants defined in ‘unistd.h’ for the file
|
descriptors belonging to the standard streams ‘stdin’, ‘stdout’, and
|
‘stderr’; see *note Standard Streams::.
|
|
‘STDIN_FILENO’
|
This macro has value ‘0’, which is the file descriptor for standard
|
input.
|
|
‘STDOUT_FILENO’
|
This macro has value ‘1’, which is the file descriptor for standard
|
output.
|
|
‘STDERR_FILENO’
|
This macro has value ‘2’, which is the file descriptor for standard
|
error output.
|
|
|
File: libc.info, Node: Stream/Descriptor Precautions, Next: Scatter-Gather, Prev: Descriptors and Streams, Up: Low-Level I/O
|
|
13.5 Dangers of Mixing Streams and Descriptors
|
==============================================
|
|
You can have multiple file descriptors and streams (let’s call both
|
streams and descriptors “channels” for short) connected to the same
|
file, but you must take care to avoid confusion between channels. There
|
are two cases to consider: "linked" channels that share a single file
|
position value, and "independent" channels that have their own file
|
positions.
|
|
It’s best to use just one channel in your program for actual data
|
transfer to any given file, except when all the access is for input.
|
For example, if you open a pipe (something you can only do at the file
|
descriptor level), either do all I/O with the descriptor, or construct a
|
stream from the descriptor with ‘fdopen’ and then do all I/O with the
|
stream.
|
|
* Menu:
|
|
* Linked Channels:: Dealing with channels sharing a file position.
|
* Independent Channels:: Dealing with separately opened, unlinked channels.
|
* Cleaning Streams:: Cleaning a stream makes it safe to use
|
another channel.
|
|
|
File: libc.info, Node: Linked Channels, Next: Independent Channels, Up: Stream/Descriptor Precautions
|
|
13.5.1 Linked Channels
|
----------------------
|
|
Channels that come from a single opening share the same file position;
|
we call them "linked" channels. Linked channels result when you make a
|
stream from a descriptor using ‘fdopen’, when you get a descriptor from
|
a stream with ‘fileno’, when you copy a descriptor with ‘dup’ or ‘dup2’,
|
and when descriptors are inherited during ‘fork’. For files that don’t
|
support random access, such as terminals and pipes, _all_ channels are
|
effectively linked. On random-access files, all append-type output
|
streams are effectively linked to each other.
|
|
If you have been using a stream for I/O (or have just opened the
|
stream), and you want to do I/O using another channel (either a stream
|
or a descriptor) that is linked to it, you must first "clean up" the
|
stream that you have been using. *Note Cleaning Streams::.
|
|
Terminating a process, or executing a new program in the process,
|
destroys all the streams in the process. If descriptors linked to these
|
streams persist in other processes, their file positions become
|
undefined as a result. To prevent this, you must clean up the streams
|
before destroying them.
|
|
|
File: libc.info, Node: Independent Channels, Next: Cleaning Streams, Prev: Linked Channels, Up: Stream/Descriptor Precautions
|
|
13.5.2 Independent Channels
|
---------------------------
|
|
When you open channels (streams or descriptors) separately on a seekable
|
file, each channel has its own file position. These are called
|
"independent channels".
|
|
The system handles each channel independently. Most of the time,
|
this is quite predictable and natural (especially for input): each
|
channel can read or write sequentially at its own place in the file.
|
However, if some of the channels are streams, you must take these
|
precautions:
|
|
• You should clean an output stream after use, before doing anything
|
else that might read or write from the same part of the file.
|
|
• You should clean an input stream before reading data that may have
|
been modified using an independent channel. Otherwise, you might
|
read obsolete data that had been in the stream’s buffer.
|
|
If you do output to one channel at the end of the file, this will
|
certainly leave the other independent channels positioned somewhere
|
before the new end. You cannot reliably set their file positions to the
|
new end of file before writing, because the file can always be extended
|
by another process between when you set the file position and when you
|
write the data. Instead, use an append-type descriptor or stream; they
|
always output at the current end of the file. In order to make the
|
end-of-file position accurate, you must clean the output channel you
|
were using, if it is a stream.
|
|
It’s impossible for two channels to have separate file pointers for a
|
file that doesn’t support random access. Thus, channels for reading or
|
writing such files are always linked, never independent. Append-type
|
channels are also always linked. For these channels, follow the rules
|
for linked channels; see *note Linked Channels::.
|
|
|
File: libc.info, Node: Cleaning Streams, Prev: Independent Channels, Up: Stream/Descriptor Precautions
|
|
13.5.3 Cleaning Streams
|
-----------------------
|
|
You can use ‘fflush’ to clean a stream in most cases.
|
|
You can skip the ‘fflush’ if you know the stream is already clean. A
|
stream is clean whenever its buffer is empty. For example, an
|
unbuffered stream is always clean. An input stream that is at
|
end-of-file is clean. A line-buffered stream is clean when the last
|
character output was a newline. However, a just-opened input stream
|
might not be clean, as its input buffer might not be empty.
|
|
There is one case in which cleaning a stream is impossible on most
|
systems. This is when the stream is doing input from a file that is not
|
random-access. Such streams typically read ahead, and when the file is
|
not random access, there is no way to give back the excess data already
|
read. When an input stream reads from a random-access file, ‘fflush’
|
does clean the stream, but leaves the file pointer at an unpredictable
|
place; you must set the file pointer before doing any further I/O.
|
|
Closing an output-only stream also does ‘fflush’, so this is a valid
|
way of cleaning an output stream.
|
|
You need not clean a stream before using its descriptor for control
|
operations such as setting terminal modes; these operations don’t affect
|
the file position and are not affected by it. You can use any
|
descriptor for these operations, and all channels are affected
|
simultaneously. However, text already “output” to a stream but still
|
buffered by the stream will be subject to the new terminal modes when
|
subsequently flushed. To make sure “past” output is covered by the
|
terminal settings that were in effect at the time, flush the output
|
streams for that terminal before setting the modes. *Note Terminal
|
Modes::.
|
|
|
File: libc.info, Node: Scatter-Gather, Next: Memory-mapped I/O, Prev: Stream/Descriptor Precautions, Up: Low-Level I/O
|
|
13.6 Fast Scatter-Gather I/O
|
============================
|
|
Some applications may need to read or write data to multiple buffers,
|
which are separated in memory. Although this can be done easily enough
|
with multiple calls to ‘read’ and ‘write’, it is inefficient because
|
there is overhead associated with each kernel call.
|
|
Instead, many platforms provide special high-speed primitives to
|
perform these "scatter-gather" operations in a single kernel call. The
|
GNU C Library will provide an emulation on any system that lacks these
|
primitives, so they are not a portability threat. They are defined in
|
‘sys/uio.h’.
|
|
These functions are controlled with arrays of ‘iovec’ structures,
|
which describe the location and size of each buffer.
|
|
-- Data Type: struct iovec
|
|
The ‘iovec’ structure describes a buffer. It contains two fields:
|
|
‘void *iov_base’
|
Contains the address of a buffer.
|
|
‘size_t iov_len’
|
Contains the length of the buffer.
|
|
-- Function: ssize_t readv (int FILEDES, const struct iovec *VECTOR,
|
int COUNT)
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
The ‘readv’ function reads data from FILEDES and scatters it into
|
the buffers described in VECTOR, which is taken to be COUNT
|
structures long. As each buffer is filled, data is sent to the
|
next.
|
|
Note that ‘readv’ is not guaranteed to fill all the buffers. It
|
may stop at any point, for the same reasons ‘read’ would.
|
|
The return value is a count of bytes (_not_ buffers) read, 0
|
indicating end-of-file, or -1 indicating an error. The possible
|
errors are the same as in ‘read’.
|
|
-- Function: ssize_t writev (int FILEDES, const struct iovec *VECTOR,
|
int COUNT)
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
The ‘writev’ function gathers data from the buffers described in
|
VECTOR, which is taken to be COUNT structures long, and writes them
|
to ‘filedes’. As each buffer is written, it moves on to the next.
|
|
Like ‘readv’, ‘writev’ may stop midstream under the same conditions
|
‘write’ would.
|
|
The return value is a count of bytes written, or -1 indicating an
|
error. The possible errors are the same as in ‘write’.
|
|
Note that if the buffers are small (under about 1kB), high-level
|
streams may be easier to use than these functions. However, ‘readv’ and
|
‘writev’ are more efficient when the individual buffers themselves (as
|
opposed to the total output), are large. In that case, a high-level
|
stream would not be able to cache the data efficiently.
|
|
|
File: libc.info, Node: Memory-mapped I/O, Next: Waiting for I/O, Prev: Scatter-Gather, Up: Low-Level I/O
|
|
13.7 Memory-mapped I/O
|
======================
|
|
On modern operating systems, it is possible to "mmap" (pronounced
|
“em-map”) a file to a region of memory. When this is done, the file can
|
be accessed just like an array in the program.
|
|
This is more efficient than ‘read’ or ‘write’, as only the regions of
|
the file that a program actually accesses are loaded. Accesses to
|
not-yet-loaded parts of the mmapped region are handled in the same way
|
as swapped out pages.
|
|
Since mmapped pages can be stored back to their file when physical
|
memory is low, it is possible to mmap files orders of magnitude larger
|
than both the physical memory _and_ swap space. The only limit is
|
address space. The theoretical limit is 4GB on a 32-bit machine -
|
however, the actual limit will be smaller since some areas will be
|
reserved for other purposes. If the LFS interface is used the file size
|
on 32-bit systems is not limited to 2GB (offsets are signed which
|
reduces the addressable area of 4GB by half); the full 64-bit are
|
available.
|
|
Memory mapping only works on entire pages of memory. Thus, addresses
|
for mapping must be page-aligned, and length values will be rounded up.
|
To determine the size of a page the machine uses one should use
|
|
size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
|
|
These functions are declared in ‘sys/mman.h’.
|
|
-- Function: void * mmap (void *ADDRESS, size_t LENGTH, int PROTECT,
|
int FLAGS, int FILEDES, off_t OFFSET)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘mmap’ function creates a new mapping, connected to bytes
|
(OFFSET) to (OFFSET + LENGTH - 1) in the file open on FILEDES. A
|
new reference for the file specified by FILEDES is created, which
|
is not removed by closing the file.
|
|
ADDRESS gives a preferred starting address for the mapping. ‘NULL’
|
expresses no preference. Any previous mapping at that address is
|
automatically removed. The address you give may still be changed,
|
unless you use the ‘MAP_FIXED’ flag.
|
|
PROTECT contains flags that control what kind of access is
|
permitted. They include ‘PROT_READ’, ‘PROT_WRITE’, and
|
‘PROT_EXEC’, which permit reading, writing, and execution,
|
respectively. Inappropriate access will cause a segfault (*note
|
Program Error Signals::).
|
|
Note that most hardware designs cannot support write permission
|
without read permission, and many do not distinguish read and
|
execute permission. Thus, you may receive wider permissions than
|
you ask for, and mappings of write-only files may be denied even if
|
you do not use ‘PROT_READ’.
|
|
FLAGS contains flags that control the nature of the map. One of
|
‘MAP_SHARED’ or ‘MAP_PRIVATE’ must be specified.
|
|
They include:
|
|
‘MAP_PRIVATE’
|
This specifies that writes to the region should never be
|
written back to the attached file. Instead, a copy is made
|
for the process, and the region will be swapped normally if
|
memory runs low. No other process will see the changes.
|
|
Since private mappings effectively revert to ordinary memory
|
when written to, you must have enough virtual memory for a
|
copy of the entire mmapped region if you use this mode with
|
‘PROT_WRITE’.
|
|
‘MAP_SHARED’
|
This specifies that writes to the region will be written back
|
to the file. Changes made will be shared immediately with
|
other processes mmaping the same file.
|
|
Note that actual writing may take place at any time. You need
|
to use ‘msync’, described below, if it is important that other
|
processes using conventional I/O get a consistent view of the
|
file.
|
|
‘MAP_FIXED’
|
This forces the system to use the exact mapping address
|
specified in ADDRESS and fail if it can’t.
|
|
‘MAP_ANONYMOUS’
|
‘MAP_ANON’
|
This flag tells the system to create an anonymous mapping, not
|
connected to a file. FILEDES and OFFSET are ignored, and the
|
region is initialized with zeros.
|
|
Anonymous maps are used as the basic primitive to extend the
|
heap on some systems. They are also useful to share data
|
between multiple tasks without creating a file.
|
|
On some systems using private anonymous mmaps is more
|
efficient than using ‘malloc’ for large blocks. This is not
|
an issue with the GNU C Library, as the included ‘malloc’
|
automatically uses ‘mmap’ where appropriate.
|
|
‘mmap’ returns the address of the new mapping, or ‘MAP_FAILED’ for
|
an error.
|
|
Possible errors include:
|
|
‘EINVAL’
|
|
Either ADDRESS was unusable, or inconsistent FLAGS were given.
|
|
‘EACCES’
|
|
FILEDES was not open for the type of access specified in
|
PROTECT.
|
|
‘ENOMEM’
|
|
Either there is not enough memory for the operation, or the
|
process is out of address space.
|
|
‘ENODEV’
|
|
This file is of a type that doesn’t support mapping.
|
|
‘ENOEXEC’
|
|
The file is on a filesystem that doesn’t support mapping.
|
|
-- Function: void * mmap64 (void *ADDRESS, size_t LENGTH, int PROTECT,
|
int FLAGS, int FILEDES, off64_t OFFSET)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘mmap64’ function is equivalent to the ‘mmap’ function but the
|
OFFSET parameter is of type ‘off64_t’. On 32-bit systems this
|
allows the file associated with the FILEDES descriptor to be larger
|
than 2GB. FILEDES must be a descriptor returned from a call to
|
‘open64’ or ‘fopen64’ and ‘freopen64’ where the descriptor is
|
retrieved with ‘fileno’.
|
|
When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
|
function is actually available under the name ‘mmap’. I.e., the
|
new, extended API using 64 bit file sizes and offsets transparently
|
replaces the old API.
|
|
-- Function: int munmap (void *ADDR, size_t LENGTH)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘munmap’ removes any memory maps from (ADDR) to (ADDR + LENGTH).
|
LENGTH should be the length of the mapping.
|
|
It is safe to unmap multiple mappings in one command, or include
|
unmapped space in the range. It is also possible to unmap only
|
part of an existing mapping. However, only entire pages can be
|
removed. If LENGTH is not an even number of pages, it will be
|
rounded up.
|
|
It returns 0 for success and -1 for an error.
|
|
One error is possible:
|
|
‘EINVAL’
|
The memory range given was outside the user mmap range or
|
wasn’t page aligned.
|
|
-- Function: int msync (void *ADDRESS, size_t LENGTH, int FLAGS)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
When using shared mappings, the kernel can write the file at any
|
time before the mapping is removed. To be certain data has
|
actually been written to the file and will be accessible to
|
non-memory-mapped I/O, it is necessary to use this function.
|
|
It operates on the region ADDRESS to (ADDRESS + LENGTH). It may be
|
used on part of a mapping or multiple mappings, however the region
|
given should not contain any unmapped space.
|
|
FLAGS can contain some options:
|
|
‘MS_SYNC’
|
|
This flag makes sure the data is actually written _to disk_.
|
Normally ‘msync’ only makes sure that accesses to a file with
|
conventional I/O reflect the recent changes.
|
|
‘MS_ASYNC’
|
|
This tells ‘msync’ to begin the synchronization, but not to
|
wait for it to complete.
|
|
‘msync’ returns 0 for success and -1 for error. Errors include:
|
|
‘EINVAL’
|
An invalid region was given, or the FLAGS were invalid.
|
|
‘EFAULT’
|
There is no existing mapping in at least part of the given
|
region.
|
|
-- Function: void * mremap (void *ADDRESS, size_t LENGTH, size_t
|
NEW_LENGTH, int FLAG)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function can be used to change the size of an existing memory
|
area. ADDRESS and LENGTH must cover a region entirely mapped in
|
the same ‘mmap’ statement. A new mapping with the same
|
characteristics will be returned with the length NEW_LENGTH.
|
|
One option is possible, ‘MREMAP_MAYMOVE’. If it is given in FLAGS,
|
the system may remove the existing mapping and create a new one of
|
the desired length in another location.
|
|
The address of the resulting mapping is returned, or -1. Possible
|
error codes include:
|
|
‘EFAULT’
|
There is no existing mapping in at least part of the original
|
region, or the region covers two or more distinct mappings.
|
|
‘EINVAL’
|
The address given is misaligned or inappropriate.
|
|
‘EAGAIN’
|
The region has pages locked, and if extended it would exceed
|
the process’s resource limit for locked pages. *Note Limits
|
on Resources::.
|
|
‘ENOMEM’
|
The region is private writable, and insufficient virtual
|
memory is available to extend it. Also, this error will occur
|
if ‘MREMAP_MAYMOVE’ is not given and the extension would
|
collide with another mapped region.
|
|
This function is only available on a few systems. Except for
|
performing optional optimizations one should not rely on this function.
|
|
Not all file descriptors may be mapped. Sockets, pipes, and most
|
devices only allow sequential access and do not fit into the mapping
|
abstraction. In addition, some regular files may not be mmapable, and
|
older kernels may not support mapping at all. Thus, programs using
|
‘mmap’ should have a fallback method to use should it fail. *Note
|
(standards)Mmap::.
|
|
-- Function: int madvise (void *ADDR, size_t LENGTH, int ADVICE)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function can be used to provide the system with ADVICE about
|
the intended usage patterns of the memory region starting at ADDR
|
and extending LENGTH bytes.
|
|
The valid BSD values for ADVICE are:
|
|
‘MADV_NORMAL’
|
The region should receive no further special treatment.
|
|
‘MADV_RANDOM’
|
The region will be accessed via random page references. The
|
kernel should page-in the minimal number of pages for each
|
page fault.
|
|
‘MADV_SEQUENTIAL’
|
The region will be accessed via sequential page references.
|
This may cause the kernel to aggressively read-ahead,
|
expecting further sequential references after any page fault
|
within this region.
|
|
‘MADV_WILLNEED’
|
The region will be needed. The pages within this region may
|
be pre-faulted in by the kernel.
|
|
‘MADV_DONTNEED’
|
The region is no longer needed. The kernel may free these
|
pages, causing any changes to the pages to be lost, as well as
|
swapped out pages to be discarded.
|
|
The POSIX names are slightly different, but with the same meanings:
|
|
‘POSIX_MADV_NORMAL’
|
This corresponds with BSD’s ‘MADV_NORMAL’.
|
|
‘POSIX_MADV_RANDOM’
|
This corresponds with BSD’s ‘MADV_RANDOM’.
|
|
‘POSIX_MADV_SEQUENTIAL’
|
This corresponds with BSD’s ‘MADV_SEQUENTIAL’.
|
|
‘POSIX_MADV_WILLNEED’
|
This corresponds with BSD’s ‘MADV_WILLNEED’.
|
|
‘POSIX_MADV_DONTNEED’
|
This corresponds with BSD’s ‘MADV_DONTNEED’.
|
|
‘madvise’ returns 0 for success and -1 for error. Errors include:
|
|
‘EINVAL’
|
An invalid region was given, or the ADVICE was invalid.
|
|
‘EFAULT’
|
There is no existing mapping in at least part of the given
|
region.
|
|
-- Function: int shm_open (const char *NAME, int OFLAG, mode_t MODE)
|
Preliminary: | MT-Safe locale | AS-Unsafe init heap lock |
|
AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
|
|
This function returns a file descriptor that can be used to
|
allocate shared memory via mmap. Unrelated processes can use same
|
NAME to create or open existing shared memory objects.
|
|
A NAME argument specifies the shared memory object to be opened.
|
In the GNU C Library it must be a string smaller than ‘NAME_MAX’
|
bytes starting with an optional slash but containing no other
|
slashes.
|
|
The semantics of OFLAG and MODE arguments is same as in ‘open’.
|
|
‘shm_open’ returns the file descriptor on success or -1 on error.
|
On failure ‘errno’ is set.
|
|
-- Function: int shm_unlink (const char *NAME)
|
Preliminary: | MT-Safe locale | AS-Unsafe init heap lock |
|
AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
|
|
This function is the inverse of ‘shm_open’ and removes the object
|
with the given NAME previously created by ‘shm_open’.
|
|
‘shm_unlink’ returns 0 on success or -1 on error. On failure
|
‘errno’ is set.
|
|
|
File: libc.info, Node: Waiting for I/O, Next: Synchronizing I/O, Prev: Memory-mapped I/O, Up: Low-Level I/O
|
|
13.8 Waiting for Input or Output
|
================================
|
|
Sometimes a program needs to accept input on multiple input channels
|
whenever input arrives. For example, some workstations may have devices
|
such as a digitizing tablet, function button box, or dial box that are
|
connected via normal asynchronous serial interfaces; good user interface
|
style requires responding immediately to input on any device. Another
|
example is a program that acts as a server to several other processes
|
via pipes or sockets.
|
|
You cannot normally use ‘read’ for this purpose, because this blocks
|
the program until input is available on one particular file descriptor;
|
input on other channels won’t wake it up. You could set nonblocking
|
mode and poll each file descriptor in turn, but this is very
|
inefficient.
|
|
A better solution is to use the ‘select’ function. This blocks the
|
program until input or output is ready on a specified set of file
|
descriptors, or until a timer expires, whichever comes first. This
|
facility is declared in the header file ‘sys/types.h’.
|
|
In the case of a server socket (*note Listening::), we say that
|
“input” is available when there are pending connections that could be
|
accepted (*note Accepting Connections::). ‘accept’ for server sockets
|
blocks and interacts with ‘select’ just as ‘read’ does for normal input.
|
|
The file descriptor sets for the ‘select’ function are specified as
|
‘fd_set’ objects. Here is the description of the data type and some
|
macros for manipulating these objects.
|
|
-- Data Type: fd_set
|
The ‘fd_set’ data type represents file descriptor sets for the
|
‘select’ function. It is actually a bit array.
|
|
-- Macro: int FD_SETSIZE
|
The value of this macro is the maximum number of file descriptors
|
that a ‘fd_set’ object can hold information about. On systems with
|
a fixed maximum number, ‘FD_SETSIZE’ is at least that number. On
|
some systems, including GNU, there is no absolute limit on the
|
number of descriptors open, but this macro still has a constant
|
value which controls the number of bits in an ‘fd_set’; if you get
|
a file descriptor with a value as high as ‘FD_SETSIZE’, you cannot
|
put that descriptor into an ‘fd_set’.
|
|
-- Macro: void FD_ZERO (fd_set *SET)
|
Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This macro initializes the file descriptor set SET to be the empty
|
set.
|
|
-- Macro: void FD_SET (int FILEDES, fd_set *SET)
|
Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This macro adds FILEDES to the file descriptor set SET.
|
|
The FILEDES parameter must not have side effects since it is
|
evaluated more than once.
|
|
-- Macro: void FD_CLR (int FILEDES, fd_set *SET)
|
Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This macro removes FILEDES from the file descriptor set SET.
|
|
The FILEDES parameter must not have side effects since it is
|
evaluated more than once.
|
|
-- Macro: int FD_ISSET (int FILEDES, const fd_set *SET)
|
Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This macro returns a nonzero value (true) if FILEDES is a member of
|
the file descriptor set SET, and zero (false) otherwise.
|
|
The FILEDES parameter must not have side effects since it is
|
evaluated more than once.
|
|
Next, here is the description of the ‘select’ function itself.
|
|
-- Function: int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS,
|
fd_set *EXCEPT-FDS, struct timeval *TIMEOUT)
|
Preliminary: | MT-Safe race:read-fds race:write-fds race:except-fds
|
| AS-Safe | AC-Safe | *Note POSIX Safety Concepts::.
|
|
The ‘select’ function blocks the calling process until there is
|
activity on any of the specified sets of file descriptors, or until
|
the timeout period has expired.
|
|
The file descriptors specified by the READ-FDS argument are checked
|
to see if they are ready for reading; the WRITE-FDS file
|
descriptors are checked to see if they are ready for writing; and
|
the EXCEPT-FDS file descriptors are checked for exceptional
|
conditions. You can pass a null pointer for any of these arguments
|
if you are not interested in checking for that kind of condition.
|
|
A file descriptor is considered ready for reading if a ‘read’ call
|
will not block. This usually includes the read offset being at the
|
end of the file or there is an error to report. A server socket is
|
considered ready for reading if there is a pending connection which
|
can be accepted with ‘accept’; *note Accepting Connections::. A
|
client socket is ready for writing when its connection is fully
|
established; *note Connecting::.
|
|
“Exceptional conditions” does not mean errors—errors are reported
|
immediately when an erroneous system call is executed, and do not
|
constitute a state of the descriptor. Rather, they include
|
conditions such as the presence of an urgent message on a socket.
|
(*Note Sockets::, for information on urgent messages.)
|
|
The ‘select’ function checks only the first NFDS file descriptors.
|
The usual thing is to pass ‘FD_SETSIZE’ as the value of this
|
argument.
|
|
The TIMEOUT specifies the maximum time to wait. If you pass a null
|
pointer for this argument, it means to block indefinitely until one
|
of the file descriptors is ready. Otherwise, you should provide
|
the time in ‘struct timeval’ format; see *note High-Resolution
|
Calendar::. Specify zero as the time (a ‘struct timeval’
|
containing all zeros) if you want to find out which descriptors are
|
ready without waiting if none are ready.
|
|
The normal return value from ‘select’ is the total number of ready
|
file descriptors in all of the sets. Each of the argument sets is
|
overwritten with information about the descriptors that are ready
|
for the corresponding operation. Thus, to see if a particular
|
descriptor DESC has input, use ‘FD_ISSET (DESC, READ-FDS)’ after
|
‘select’ returns.
|
|
If ‘select’ returns because the timeout period expires, it returns
|
a value of zero.
|
|
Any signal will cause ‘select’ to return immediately. So if your
|
program uses signals, you can’t rely on ‘select’ to keep waiting
|
for the full time specified. If you want to be sure of waiting for
|
a particular amount of time, you must check for ‘EINTR’ and repeat
|
the ‘select’ with a newly calculated timeout based on the current
|
time. See the example below. See also *note Interrupted
|
Primitives::.
|
|
If an error occurs, ‘select’ returns ‘-1’ and does not modify the
|
argument file descriptor sets. The following ‘errno’ error
|
conditions are defined for this function:
|
|
‘EBADF’
|
One of the file descriptor sets specified an invalid file
|
descriptor.
|
|
‘EINTR’
|
The operation was interrupted by a signal. *Note Interrupted
|
Primitives::.
|
|
‘EINVAL’
|
The TIMEOUT argument is invalid; one of the components is
|
negative or too large.
|
|
*Portability Note:* The ‘select’ function is a BSD Unix feature.
|
|
Here is an example showing how you can use ‘select’ to establish a
|
timeout period for reading from a file descriptor. The ‘input_timeout’
|
function blocks the calling process until input is available on the file
|
descriptor, or until the timeout period expires.
|
|
|
#include <errno.h>
|
#include <stdio.h>
|
#include <unistd.h>
|
#include <sys/types.h>
|
#include <sys/time.h>
|
|
int
|
input_timeout (int filedes, unsigned int seconds)
|
{
|
fd_set set;
|
struct timeval timeout;
|
|
/* Initialize the file descriptor set. */
|
FD_ZERO (&set);
|
FD_SET (filedes, &set);
|
|
/* Initialize the timeout data structure. */
|
timeout.tv_sec = seconds;
|
timeout.tv_usec = 0;
|
|
/* ‘select’ returns 0 if timeout, 1 if input available, -1 if error. */
|
return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
|
&set, NULL, NULL,
|
&timeout));
|
}
|
|
int
|
main (void)
|
{
|
fprintf (stderr, "select returned %d.\n",
|
input_timeout (STDIN_FILENO, 5));
|
return 0;
|
}
|
|
There is another example showing the use of ‘select’ to multiplex
|
input from multiple sockets in *note Server Example::.
|
|
|
File: libc.info, Node: Synchronizing I/O, Next: Asynchronous I/O, Prev: Waiting for I/O, Up: Low-Level I/O
|
|
13.9 Synchronizing I/O operations
|
=================================
|
|
In most modern operating systems, the normal I/O operations are not
|
executed synchronously. I.e., even if a ‘write’ system call returns,
|
this does not mean the data is actually written to the media, e.g., the
|
disk.
|
|
In situations where synchronization points are necessary, you can use
|
special functions which ensure that all operations finish before they
|
return.
|
|
-- Function: void sync (void)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
A call to this function will not return as long as there is data
|
which has not been written to the device. All dirty buffers in the
|
kernel will be written and so an overall consistent system can be
|
achieved (if no other process in parallel writes data).
|
|
A prototype for ‘sync’ can be found in ‘unistd.h’.
|
|
Programs more often want to ensure that data written to a given file
|
is committed, rather than all data in the system. For this, ‘sync’ is
|
overkill.
|
|
-- Function: int fsync (int FILDES)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘fsync’ function can be used to make sure all data associated
|
with the open file FILDES is written to the device associated with
|
the descriptor. The function call does not return unless all
|
actions have finished.
|
|
A prototype for ‘fsync’ can be found in ‘unistd.h’.
|
|
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
|
‘fsync’ is called. If the thread gets canceled these resources
|
stay allocated until the program ends. To avoid this, calls to
|
‘fsync’ should be protected using cancellation handlers.
|
|
The return value of the function is zero if no error occurred.
|
Otherwise it is -1 and the global variable ERRNO is set to the
|
following values:
|
‘EBADF’
|
The descriptor FILDES is not valid.
|
|
‘EINVAL’
|
No synchronization is possible since the system does not
|
implement this.
|
|
Sometimes it is not even necessary to write all data associated with
|
a file descriptor. E.g., in database files which do not change in size
|
it is enough to write all the file content data to the device.
|
Meta-information, like the modification time etc., are not that
|
important and leaving such information uncommitted does not prevent a
|
successful recovery of the file in case of a problem.
|
|
-- Function: int fdatasync (int FILDES)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
When a call to the ‘fdatasync’ function returns, it is ensured that
|
all of the file data is written to the device. For all pending I/O
|
operations, the parts guaranteeing data integrity finished.
|
|
Not all systems implement the ‘fdatasync’ operation. On systems
|
missing this functionality ‘fdatasync’ is emulated by a call to
|
‘fsync’ since the performed actions are a superset of those
|
required by ‘fdatasync’.
|
|
The prototype for ‘fdatasync’ is in ‘unistd.h’.
|
|
The return value of the function is zero if no error occurred.
|
Otherwise it is -1 and the global variable ERRNO is set to the
|
following values:
|
‘EBADF’
|
The descriptor FILDES is not valid.
|
|
‘EINVAL’
|
No synchronization is possible since the system does not
|
implement this.
|
|
|
File: libc.info, Node: Asynchronous I/O, Next: Control Operations, Prev: Synchronizing I/O, Up: Low-Level I/O
|
|
13.10 Perform I/O Operations in Parallel
|
========================================
|
|
The POSIX.1b standard defines a new set of I/O operations which can
|
significantly reduce the time an application spends waiting for I/O. The
|
new functions allow a program to initiate one or more I/O operations and
|
then immediately resume normal work while the I/O operations are
|
executed in parallel. This functionality is available if the ‘unistd.h’
|
file defines the symbol ‘_POSIX_ASYNCHRONOUS_IO’.
|
|
These functions are part of the library with realtime functions named
|
‘librt’. They are not actually part of the ‘libc’ binary. The
|
implementation of these functions can be done using support in the
|
kernel (if available) or using an implementation based on threads at
|
userlevel. In the latter case it might be necessary to link
|
applications with the thread library ‘libpthread’ in addition to
|
‘librt’.
|
|
All AIO operations operate on files which were opened previously.
|
There might be arbitrarily many operations running for one file. The
|
asynchronous I/O operations are controlled using a data structure named
|
‘struct aiocb’ ("AIO control block"). It is defined in ‘aio.h’ as
|
follows.
|
|
-- Data Type: struct aiocb
|
The POSIX.1b standard mandates that the ‘struct aiocb’ structure
|
contains at least the members described in the following table.
|
There might be more elements which are used by the implementation,
|
but depending upon these elements is not portable and is highly
|
deprecated.
|
|
‘int aio_fildes’
|
This element specifies the file descriptor to be used for the
|
operation. It must be a legal descriptor, otherwise the
|
operation will fail.
|
|
The device on which the file is opened must allow the seek
|
operation. I.e., it is not possible to use any of the AIO
|
operations on devices like terminals where an ‘lseek’ call
|
would lead to an error.
|
|
‘off_t aio_offset’
|
This element specifies the offset in the file at which the
|
operation (input or output) is performed. Since the
|
operations are carried out in arbitrary order and more than
|
one operation for one file descriptor can be started, one
|
cannot expect a current read/write position of the file
|
descriptor.
|
|
‘volatile void *aio_buf’
|
This is a pointer to the buffer with the data to be written or
|
the place where the read data is stored.
|
|
‘size_t aio_nbytes’
|
This element specifies the length of the buffer pointed to by
|
‘aio_buf’.
|
|
‘int aio_reqprio’
|
If the platform has defined ‘_POSIX_PRIORITIZED_IO’ and
|
‘_POSIX_PRIORITY_SCHEDULING’, the AIO requests are processed
|
based on the current scheduling priority. The ‘aio_reqprio’
|
element can then be used to lower the priority of the AIO
|
operation.
|
|
‘struct sigevent aio_sigevent’
|
This element specifies how the calling process is notified
|
once the operation terminates. If the ‘sigev_notify’ element
|
is ‘SIGEV_NONE’, no notification is sent. If it is
|
‘SIGEV_SIGNAL’, the signal determined by ‘sigev_signo’ is
|
sent. Otherwise, ‘sigev_notify’ must be ‘SIGEV_THREAD’. In
|
this case, a thread is created which starts executing the
|
function pointed to by ‘sigev_notify_function’.
|
|
‘int aio_lio_opcode’
|
This element is only used by the ‘lio_listio’ and
|
‘lio_listio64’ functions. Since these functions allow an
|
arbitrary number of operations to start at once, and each
|
operation can be input or output (or nothing), the information
|
must be stored in the control block. The possible values are:
|
|
‘LIO_READ’
|
Start a read operation. Read from the file at position
|
‘aio_offset’ and store the next ‘aio_nbytes’ bytes in the
|
buffer pointed to by ‘aio_buf’.
|
|
‘LIO_WRITE’
|
Start a write operation. Write ‘aio_nbytes’ bytes
|
starting at ‘aio_buf’ into the file starting at position
|
‘aio_offset’.
|
|
‘LIO_NOP’
|
Do nothing for this control block. This value is useful
|
sometimes when an array of ‘struct aiocb’ values contains
|
holes, i.e., some of the values must not be handled
|
although the whole array is presented to the ‘lio_listio’
|
function.
|
|
When the sources are compiled using ‘_FILE_OFFSET_BITS == 64’ on a
|
32 bit machine, this type is in fact ‘struct aiocb64’, since the
|
LFS interface transparently replaces the ‘struct aiocb’ definition.
|
|
For use with the AIO functions defined in the LFS, there is a similar
|
type defined which replaces the types of the appropriate members with
|
larger types but otherwise is equivalent to ‘struct aiocb’.
|
Particularly, all member names are the same.
|
|
-- Data Type: struct aiocb64
|
‘int aio_fildes’
|
This element specifies the file descriptor which is used for
|
the operation. It must be a legal descriptor since otherwise
|
the operation fails for obvious reasons.
|
|
The device on which the file is opened must allow the seek
|
operation. I.e., it is not possible to use any of the AIO
|
operations on devices like terminals where an ‘lseek’ call
|
would lead to an error.
|
|
‘off64_t aio_offset’
|
This element specifies at which offset in the file the
|
operation (input or output) is performed. Since the operation
|
are carried in arbitrary order and more than one operation for
|
one file descriptor can be started, one cannot expect a
|
current read/write position of the file descriptor.
|
|
‘volatile void *aio_buf’
|
This is a pointer to the buffer with the data to be written or
|
the place where the read data is stored.
|
|
‘size_t aio_nbytes’
|
This element specifies the length of the buffer pointed to by
|
‘aio_buf’.
|
|
‘int aio_reqprio’
|
If for the platform ‘_POSIX_PRIORITIZED_IO’ and
|
‘_POSIX_PRIORITY_SCHEDULING’ are defined the AIO requests are
|
processed based on the current scheduling priority. The
|
‘aio_reqprio’ element can then be used to lower the priority
|
of the AIO operation.
|
|
‘struct sigevent aio_sigevent’
|
This element specifies how the calling process is notified
|
once the operation terminates. If the ‘sigev_notify’ element
|
is ‘SIGEV_NONE’ no notification is sent. If it is
|
‘SIGEV_SIGNAL’, the signal determined by ‘sigev_signo’ is
|
sent. Otherwise, ‘sigev_notify’ must be ‘SIGEV_THREAD’ in
|
which case a thread is created which starts executing the
|
function pointed to by ‘sigev_notify_function’.
|
|
‘int aio_lio_opcode’
|
This element is only used by the ‘lio_listio’ and
|
‘lio_listio64’ functions. Since these functions allow an
|
arbitrary number of operations to start at once, and since
|
each operation can be input or output (or nothing), the
|
information must be stored in the control block. See the
|
description of ‘struct aiocb’ for a description of the
|
possible values.
|
|
When the sources are compiled using ‘_FILE_OFFSET_BITS == 64’ on a
|
32 bit machine, this type is available under the name ‘struct
|
aiocb64’, since the LFS transparently replaces the old interface.
|
|
* Menu:
|
|
* Asynchronous Reads/Writes:: Asynchronous Read and Write Operations.
|
* Status of AIO Operations:: Getting the Status of AIO Operations.
|
* Synchronizing AIO Operations:: Getting into a consistent state.
|
* Cancel AIO Operations:: Cancellation of AIO Operations.
|
* Configuration of AIO:: How to optimize the AIO implementation.
|
|
|
File: libc.info, Node: Asynchronous Reads/Writes, Next: Status of AIO Operations, Up: Asynchronous I/O
|
|
13.10.1 Asynchronous Read and Write Operations
|
----------------------------------------------
|
|
-- Function: int aio_read (struct aiocb *AIOCBP)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function initiates an asynchronous read operation. It
|
immediately returns after the operation was enqueued or when an
|
error was encountered.
|
|
The first ‘aiocbp->aio_nbytes’ bytes of the file for which
|
‘aiocbp->aio_fildes’ is a descriptor are written to the buffer
|
starting at ‘aiocbp->aio_buf’. Reading starts at the absolute
|
position ‘aiocbp->aio_offset’ in the file.
|
|
If prioritized I/O is supported by the platform the
|
‘aiocbp->aio_reqprio’ value is used to adjust the priority before
|
the request is actually enqueued.
|
|
The calling process is notified about the termination of the read
|
request according to the ‘aiocbp->aio_sigevent’ value.
|
|
When ‘aio_read’ returns, the return value is zero if no error
|
occurred that can be found before the process is enqueued. If such
|
an early error is found, the function returns -1 and sets ‘errno’
|
to one of the following values:
|
|
‘EAGAIN’
|
The request was not enqueued due to (temporarily) exceeded
|
resource limitations.
|
‘ENOSYS’
|
The ‘aio_read’ function is not implemented.
|
‘EBADF’
|
The ‘aiocbp->aio_fildes’ descriptor is not valid. This
|
condition need not be recognized before enqueueing the request
|
and so this error might also be signaled asynchronously.
|
‘EINVAL’
|
The ‘aiocbp->aio_offset’ or ‘aiocbp->aio_reqpiro’ value is
|
invalid. This condition need not be recognized before
|
enqueueing the request and so this error might also be
|
signaled asynchronously.
|
|
If ‘aio_read’ returns zero, the current status of the request can
|
be queried using ‘aio_error’ and ‘aio_return’ functions. As long
|
as the value returned by ‘aio_error’ is ‘EINPROGRESS’ the operation
|
has not yet completed. If ‘aio_error’ returns zero, the operation
|
successfully terminated, otherwise the value is to be interpreted
|
as an error code. If the function terminated, the result of the
|
operation can be obtained using a call to ‘aio_return’. The
|
returned value is the same as an equivalent call to ‘read’ would
|
have returned. Possible error codes returned by ‘aio_error’ are:
|
|
‘EBADF’
|
The ‘aiocbp->aio_fildes’ descriptor is not valid.
|
‘ECANCELED’
|
The operation was canceled before the operation was finished
|
(*note Cancel AIO Operations::)
|
‘EINVAL’
|
The ‘aiocbp->aio_offset’ value is invalid.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is in fact ‘aio_read64’ since the LFS interface
|
transparently replaces the normal implementation.
|
|
-- Function: int aio_read64 (struct aiocb64 *AIOCBP)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function is similar to the ‘aio_read’ function. The only
|
difference is that on 32 bit machines, the file descriptor should
|
be opened in the large file mode. Internally, ‘aio_read64’ uses
|
functionality equivalent to ‘lseek64’ (*note File Position
|
Primitive::) to position the file descriptor correctly for the
|
reading, as opposed to the ‘lseek’ functionality used in
|
‘aio_read’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
|
function is available under the name ‘aio_read’ and so
|
transparently replaces the interface for small files on 32 bit
|
machines.
|
|
To write data asynchronously to a file, there exists an equivalent
|
pair of functions with a very similar interface.
|
|
-- Function: int aio_write (struct aiocb *AIOCBP)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function initiates an asynchronous write operation. The
|
function call immediately returns after the operation was enqueued
|
or if before this happens an error was encountered.
|
|
The first ‘aiocbp->aio_nbytes’ bytes from the buffer starting at
|
‘aiocbp->aio_buf’ are written to the file for which
|
‘aiocbp->aio_fildes’ is a descriptor, starting at the absolute
|
position ‘aiocbp->aio_offset’ in the file.
|
|
If prioritized I/O is supported by the platform, the
|
‘aiocbp->aio_reqprio’ value is used to adjust the priority before
|
the request is actually enqueued.
|
|
The calling process is notified about the termination of the read
|
request according to the ‘aiocbp->aio_sigevent’ value.
|
|
When ‘aio_write’ returns, the return value is zero if no error
|
occurred that can be found before the process is enqueued. If such
|
an early error is found the function returns -1 and sets ‘errno’ to
|
one of the following values.
|
|
‘EAGAIN’
|
The request was not enqueued due to (temporarily) exceeded
|
resource limitations.
|
‘ENOSYS’
|
The ‘aio_write’ function is not implemented.
|
‘EBADF’
|
The ‘aiocbp->aio_fildes’ descriptor is not valid. This
|
condition may not be recognized before enqueueing the request,
|
and so this error might also be signaled asynchronously.
|
‘EINVAL’
|
The ‘aiocbp->aio_offset’ or ‘aiocbp->aio_reqprio’ value is
|
invalid. This condition may not be recognized before
|
enqueueing the request and so this error might also be
|
signaled asynchronously.
|
|
In the case ‘aio_write’ returns zero, the current status of the
|
request can be queried using the ‘aio_error’ and ‘aio_return’
|
functions. As long as the value returned by ‘aio_error’ is
|
‘EINPROGRESS’ the operation has not yet completed. If ‘aio_error’
|
returns zero, the operation successfully terminated, otherwise the
|
value is to be interpreted as an error code. If the function
|
terminated, the result of the operation can be obtained using a
|
call to ‘aio_return’. The returned value is the same as an
|
equivalent call to ‘read’ would have returned. Possible error
|
codes returned by ‘aio_error’ are:
|
|
‘EBADF’
|
The ‘aiocbp->aio_fildes’ descriptor is not valid.
|
‘ECANCELED’
|
The operation was canceled before the operation was finished.
|
(*note Cancel AIO Operations::)
|
‘EINVAL’
|
The ‘aiocbp->aio_offset’ value is invalid.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
|
function is in fact ‘aio_write64’ since the LFS interface
|
transparently replaces the normal implementation.
|
|
-- Function: int aio_write64 (struct aiocb64 *AIOCBP)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function is similar to the ‘aio_write’ function. The only
|
difference is that on 32 bit machines the file descriptor should be
|
opened in the large file mode. Internally ‘aio_write64’ uses
|
functionality equivalent to ‘lseek64’ (*note File Position
|
Primitive::) to position the file descriptor correctly for the
|
writing, as opposed to the ‘lseek’ functionality used in
|
‘aio_write’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
|
function is available under the name ‘aio_write’ and so
|
transparently replaces the interface for small files on 32 bit
|
machines.
|
|
Besides these functions with the more or less traditional interface,
|
POSIX.1b also defines a function which can initiate more than one
|
operation at a time, and which can handle freely mixed read and write
|
operations. It is therefore similar to a combination of ‘readv’ and
|
‘writev’.
|
|
-- Function: int lio_listio (int MODE, struct aiocb *const LIST[], int
|
NENT, struct sigevent *SIG)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
The ‘lio_listio’ function can be used to enqueue an arbitrary
|
number of read and write requests at one time. The requests can
|
all be meant for the same file, all for different files or every
|
solution in between.
|
|
‘lio_listio’ gets the NENT requests from the array pointed to by
|
LIST. The operation to be performed is determined by the
|
‘aio_lio_opcode’ member in each element of LIST. If this field is
|
‘LIO_READ’ a read operation is enqueued, similar to a call of
|
‘aio_read’ for this element of the array (except that the way the
|
termination is signalled is different, as we will see below). If
|
the ‘aio_lio_opcode’ member is ‘LIO_WRITE’ a write operation is
|
enqueued. Otherwise the ‘aio_lio_opcode’ must be ‘LIO_NOP’ in
|
which case this element of LIST is simply ignored. This
|
“operation” is useful in situations where one has a fixed array of
|
‘struct aiocb’ elements from which only a few need to be handled at
|
a time. Another situation is where the ‘lio_listio’ call was
|
canceled before all requests are processed (*note Cancel AIO
|
Operations::) and the remaining requests have to be reissued.
|
|
The other members of each element of the array pointed to by ‘list’
|
must have values suitable for the operation as described in the
|
documentation for ‘aio_read’ and ‘aio_write’ above.
|
|
The MODE argument determines how ‘lio_listio’ behaves after having
|
enqueued all the requests. If MODE is ‘LIO_WAIT’ it waits until
|
all requests terminated. Otherwise MODE must be ‘LIO_NOWAIT’ and
|
in this case the function returns immediately after having enqueued
|
all the requests. In this case the caller gets a notification of
|
the termination of all requests according to the SIG parameter. If
|
SIG is ‘NULL’ no notification is sent. Otherwise a signal is sent
|
or a thread is started, just as described in the description for
|
‘aio_read’ or ‘aio_write’.
|
|
If MODE is ‘LIO_WAIT’, the return value of ‘lio_listio’ is 0 when
|
all requests completed successfully. Otherwise the function
|
returns -1 and ‘errno’ is set accordingly. To find out which
|
request or requests failed one has to use the ‘aio_error’ function
|
on all the elements of the array LIST.
|
|
In case MODE is ‘LIO_NOWAIT’, the function returns 0 if all
|
requests were enqueued correctly. The current state of the
|
requests can be found using ‘aio_error’ and ‘aio_return’ as
|
described above. If ‘lio_listio’ returns -1 in this mode, the
|
global variable ‘errno’ is set accordingly. If a request did not
|
yet terminate, a call to ‘aio_error’ returns ‘EINPROGRESS’. If the
|
value is different, the request is finished and the error value (or
|
0) is returned and the result of the operation can be retrieved
|
using ‘aio_return’.
|
|
Possible values for ‘errno’ are:
|
|
‘EAGAIN’
|
The resources necessary to queue all the requests are not
|
available at the moment. The error status for each element of
|
LIST must be checked to determine which request failed.
|
|
Another reason could be that the system wide limit of AIO
|
requests is exceeded. This cannot be the case for the
|
implementation on GNU systems since no arbitrary limits exist.
|
‘EINVAL’
|
The MODE parameter is invalid or NENT is larger than
|
‘AIO_LISTIO_MAX’.
|
‘EIO’
|
One or more of the request’s I/O operations failed. The error
|
status of each request should be checked to determine which
|
one failed.
|
‘ENOSYS’
|
The ‘lio_listio’ function is not supported.
|
|
If the MODE parameter is ‘LIO_NOWAIT’ and the caller cancels a
|
request, the error status for this request returned by ‘aio_error’
|
is ‘ECANCELED’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
|
function is in fact ‘lio_listio64’ since the LFS interface
|
transparently replaces the normal implementation.
|
|
-- Function: int lio_listio64 (int MODE, struct aiocb64 *const LIST[],
|
int NENT, struct sigevent *SIG)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function is similar to the ‘lio_listio’ function. The only
|
difference is that on 32 bit machines, the file descriptor should
|
be opened in the large file mode. Internally, ‘lio_listio64’ uses
|
functionality equivalent to ‘lseek64’ (*note File Position
|
Primitive::) to position the file descriptor correctly for the
|
reading or writing, as opposed to the ‘lseek’ functionality used in
|
‘lio_listio’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
|
function is available under the name ‘lio_listio’ and so
|
transparently replaces the interface for small files on 32 bit
|
machines.
|
|
|
File: libc.info, Node: Status of AIO Operations, Next: Synchronizing AIO Operations, Prev: Asynchronous Reads/Writes, Up: Asynchronous I/O
|
|
13.10.2 Getting the Status of AIO Operations
|
--------------------------------------------
|
|
As already described in the documentation of the functions in the last
|
section, it must be possible to get information about the status of an
|
I/O request. When the operation is performed truly asynchronously (as
|
with ‘aio_read’ and ‘aio_write’ and with ‘lio_listio’ when the mode is
|
‘LIO_NOWAIT’), one sometimes needs to know whether a specific request
|
already terminated and if so, what the result was. The following two
|
functions allow you to get this kind of information.
|
|
-- Function: int aio_error (const struct aiocb *AIOCBP)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function determines the error state of the request described
|
by the ‘struct aiocb’ variable pointed to by AIOCBP. If the
|
request has not yet terminated the value returned is always
|
‘EINPROGRESS’. Once the request has terminated the value
|
‘aio_error’ returns is either 0 if the request completed
|
successfully or it returns the value which would be stored in the
|
‘errno’ variable if the request would have been done using ‘read’,
|
‘write’, or ‘fsync’.
|
|
The function can return ‘ENOSYS’ if it is not implemented. It
|
could also return ‘EINVAL’ if the AIOCBP parameter does not refer
|
to an asynchronous operation whose return status is not yet known.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is in fact ‘aio_error64’ since the LFS interface
|
transparently replaces the normal implementation.
|
|
-- Function: int aio_error64 (const struct aiocb64 *AIOCBP)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to ‘aio_error’ with the only difference
|
that the argument is a reference to a variable of type ‘struct
|
aiocb64’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is available under the name ‘aio_error’ and so
|
transparently replaces the interface for small files on 32 bit
|
machines.
|
|
-- Function: ssize_t aio_return (struct aiocb *AIOCBP)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function can be used to retrieve the return status of the
|
operation carried out by the request described in the variable
|
pointed to by AIOCBP. As long as the error status of this request
|
as returned by ‘aio_error’ is ‘EINPROGRESS’ the return value of
|
this function is undefined.
|
|
Once the request is finished this function can be used exactly once
|
to retrieve the return value. Following calls might lead to
|
undefined behavior. The return value itself is the value which
|
would have been returned by the ‘read’, ‘write’, or ‘fsync’ call.
|
|
The function can return ‘ENOSYS’ if it is not implemented. It
|
could also return ‘EINVAL’ if the AIOCBP parameter does not refer
|
to an asynchronous operation whose return status is not yet known.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is in fact ‘aio_return64’ since the LFS interface
|
transparently replaces the normal implementation.
|
|
-- Function: ssize_t aio_return64 (struct aiocb64 *AIOCBP)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to ‘aio_return’ with the only difference
|
that the argument is a reference to a variable of type ‘struct
|
aiocb64’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is available under the name ‘aio_return’ and so
|
transparently replaces the interface for small files on 32 bit
|
machines.
|
|
|
File: libc.info, Node: Synchronizing AIO Operations, Next: Cancel AIO Operations, Prev: Status of AIO Operations, Up: Asynchronous I/O
|
|
13.10.3 Getting into a Consistent State
|
---------------------------------------
|
|
When dealing with asynchronous operations it is sometimes necessary to
|
get into a consistent state. This would mean for AIO that one wants to
|
know whether a certain request or a group of requests were processed.
|
This could be done by waiting for the notification sent by the system
|
after the operation terminated, but this sometimes would mean wasting
|
resources (mainly computation time). Instead POSIX.1b defines two
|
functions which will help with most kinds of consistency.
|
|
The ‘aio_fsync’ and ‘aio_fsync64’ functions are only available if the
|
symbol ‘_POSIX_SYNCHRONIZED_IO’ is defined in ‘unistd.h’.
|
|
-- Function: int aio_fsync (int OP, struct aiocb *AIOCBP)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
Calling this function forces all I/O operations queued at the time
|
of the function call operating on the file descriptor
|
‘aiocbp->aio_fildes’ into the synchronized I/O completion state
|
(*note Synchronizing I/O::). The ‘aio_fsync’ function returns
|
immediately but the notification through the method described in
|
‘aiocbp->aio_sigevent’ will happen only after all requests for this
|
file descriptor have terminated and the file is synchronized. This
|
also means that requests for this very same file descriptor which
|
are queued after the synchronization request are not affected.
|
|
If OP is ‘O_DSYNC’ the synchronization happens as with a call to
|
‘fdatasync’. Otherwise OP should be ‘O_SYNC’ and the
|
synchronization happens as with ‘fsync’.
|
|
As long as the synchronization has not happened, a call to
|
‘aio_error’ with the reference to the object pointed to by AIOCBP
|
returns ‘EINPROGRESS’. Once the synchronization is done
|
‘aio_error’ return 0 if the synchronization was not successful.
|
Otherwise the value returned is the value to which the ‘fsync’ or
|
‘fdatasync’ function would have set the ‘errno’ variable. In this
|
case nothing can be assumed about the consistency of the data
|
written to this file descriptor.
|
|
The return value of this function is 0 if the request was
|
successfully enqueued. Otherwise the return value is -1 and
|
‘errno’ is set to one of the following values:
|
|
‘EAGAIN’
|
The request could not be enqueued due to temporary lack of
|
resources.
|
‘EBADF’
|
The file descriptor ‘AIOCBP->aio_fildes’ is not valid.
|
‘EINVAL’
|
The implementation does not support I/O synchronization or the
|
OP parameter is other than ‘O_DSYNC’ and ‘O_SYNC’.
|
‘ENOSYS’
|
This function is not implemented.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is in fact ‘aio_fsync64’ since the LFS interface
|
transparently replaces the normal implementation.
|
|
-- Function: int aio_fsync64 (int OP, struct aiocb64 *AIOCBP)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function is similar to ‘aio_fsync’ with the only difference
|
that the argument is a reference to a variable of type ‘struct
|
aiocb64’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is available under the name ‘aio_fsync’ and so
|
transparently replaces the interface for small files on 32 bit
|
machines.
|
|
Another method of synchronization is to wait until one or more
|
requests of a specific set terminated. This could be achieved by the
|
‘aio_*’ functions to notify the initiating process about the termination
|
but in some situations this is not the ideal solution. In a program
|
which constantly updates clients somehow connected to the server it is
|
not always the best solution to go round robin since some connections
|
might be slow. On the other hand letting the ‘aio_*’ functions notify
|
the caller might also be not the best solution since whenever the
|
process works on preparing data for a client it makes no sense to be
|
interrupted by a notification since the new client will not be handled
|
before the current client is served. For situations like this
|
‘aio_suspend’ should be used.
|
|
-- Function: int aio_suspend (const struct aiocb *const LIST[], int
|
NENT, const struct timespec *TIMEOUT)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
When calling this function, the calling thread is suspended until
|
at least one of the requests pointed to by the NENT elements of the
|
array LIST has completed. If any of the requests has already
|
completed at the time ‘aio_suspend’ is called, the function returns
|
immediately. Whether a request has terminated or not is determined
|
by comparing the error status of the request with ‘EINPROGRESS’.
|
If an element of LIST is ‘NULL’, the entry is simply ignored.
|
|
If no request has finished, the calling process is suspended. If
|
TIMEOUT is ‘NULL’, the process is not woken until a request has
|
finished. If TIMEOUT is not ‘NULL’, the process remains suspended
|
at least as long as specified in TIMEOUT. In this case,
|
‘aio_suspend’ returns with an error.
|
|
The return value of the function is 0 if one or more requests from
|
the LIST have terminated. Otherwise the function returns -1 and
|
‘errno’ is set to one of the following values:
|
|
‘EAGAIN’
|
None of the requests from the LIST completed in the time
|
specified by TIMEOUT.
|
‘EINTR’
|
A signal interrupted the ‘aio_suspend’ function. This signal
|
might also be sent by the AIO implementation while signalling
|
the termination of one of the requests.
|
‘ENOSYS’
|
The ‘aio_suspend’ function is not implemented.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is in fact ‘aio_suspend64’ since the LFS interface
|
transparently replaces the normal implementation.
|
|
-- Function: int aio_suspend64 (const struct aiocb64 *const LIST[], int
|
NENT, const struct timespec *TIMEOUT)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function is similar to ‘aio_suspend’ with the only difference
|
that the argument is a reference to a variable of type ‘struct
|
aiocb64’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is available under the name ‘aio_suspend’ and so
|
transparently replaces the interface for small files on 32 bit
|
machines.
|
|
|
File: libc.info, Node: Cancel AIO Operations, Next: Configuration of AIO, Prev: Synchronizing AIO Operations, Up: Asynchronous I/O
|
|
13.10.4 Cancellation of AIO Operations
|
--------------------------------------
|
|
When one or more requests are asynchronously processed, it might be
|
useful in some situations to cancel a selected operation, e.g., if it
|
becomes obvious that the written data is no longer accurate and would
|
have to be overwritten soon. As an example, assume an application,
|
which writes data in files in a situation where new incoming data would
|
have to be written in a file which will be updated by an enqueued
|
request. The POSIX AIO implementation provides such a function, but
|
this function is not capable of forcing the cancellation of the request.
|
It is up to the implementation to decide whether it is possible to
|
cancel the operation or not. Therefore using this function is merely a
|
hint.
|
|
-- Function: int aio_cancel (int FILDES, struct aiocb *AIOCBP)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
The ‘aio_cancel’ function can be used to cancel one or more
|
outstanding requests. If the AIOCBP parameter is ‘NULL’, the
|
function tries to cancel all of the outstanding requests which
|
would process the file descriptor FILDES (i.e., whose ‘aio_fildes’
|
member is FILDES). If AIOCBP is not ‘NULL’, ‘aio_cancel’ attempts
|
to cancel the specific request pointed to by AIOCBP.
|
|
For requests which were successfully canceled, the normal
|
notification about the termination of the request should take
|
place. I.e., depending on the ‘struct sigevent’ object which
|
controls this, nothing happens, a signal is sent or a thread is
|
started. If the request cannot be canceled, it terminates the
|
usual way after performing the operation.
|
|
After a request is successfully canceled, a call to ‘aio_error’
|
with a reference to this request as the parameter will return
|
‘ECANCELED’ and a call to ‘aio_return’ will return -1. If the
|
request wasn’t canceled and is still running the error status is
|
still ‘EINPROGRESS’.
|
|
The return value of the function is ‘AIO_CANCELED’ if there were
|
requests which haven’t terminated and which were successfully
|
canceled. If there is one or more requests left which couldn’t be
|
canceled, the return value is ‘AIO_NOTCANCELED’. In this case
|
‘aio_error’ must be used to find out which of the, perhaps
|
multiple, requests (if AIOCBP is ‘NULL’) weren’t successfully
|
canceled. If all requests already terminated at the time
|
‘aio_cancel’ is called the return value is ‘AIO_ALLDONE’.
|
|
If an error occurred during the execution of ‘aio_cancel’ the
|
function returns -1 and sets ‘errno’ to one of the following
|
values.
|
|
‘EBADF’
|
The file descriptor FILDES is not valid.
|
‘ENOSYS’
|
‘aio_cancel’ is not implemented.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
|
function is in fact ‘aio_cancel64’ since the LFS interface
|
transparently replaces the normal implementation.
|
|
-- Function: int aio_cancel64 (int FILDES, struct aiocb64 *AIOCBP)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function is similar to ‘aio_cancel’ with the only difference
|
that the argument is a reference to a variable of type ‘struct
|
aiocb64’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
|
function is available under the name ‘aio_cancel’ and so
|
transparently replaces the interface for small files on 32 bit
|
machines.
|
|
|
File: libc.info, Node: Configuration of AIO, Prev: Cancel AIO Operations, Up: Asynchronous I/O
|
|
13.10.5 How to optimize the AIO implementation
|
----------------------------------------------
|
|
The POSIX standard does not specify how the AIO functions are
|
implemented. They could be system calls, but it is also possible to
|
emulate them at userlevel.
|
|
At the time of writing, the available implementation is a user-level
|
implementation which uses threads for handling the enqueued requests.
|
While this implementation requires making some decisions about
|
limitations, hard limitations are something best avoided in the GNU C
|
Library. Therefore, the GNU C Library provides a means for tuning the
|
AIO implementation according to the individual use.
|
|
-- Data Type: struct aioinit
|
This data type is used to pass the configuration or tunable
|
parameters to the implementation. The program has to initialize
|
the members of this struct and pass it to the implementation using
|
the ‘aio_init’ function.
|
|
‘int aio_threads’
|
This member specifies the maximal number of threads which may
|
be used at any one time.
|
‘int aio_num’
|
This number provides an estimate on the maximal number of
|
simultaneously enqueued requests.
|
‘int aio_locks’
|
Unused.
|
‘int aio_usedba’
|
Unused.
|
‘int aio_debug’
|
Unused.
|
‘int aio_numusers’
|
Unused.
|
‘int aio_reserved[2]’
|
Unused.
|
|
-- Function: void aio_init (const struct aioinit *INIT)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function must be called before any other AIO function.
|
Calling it is completely voluntary, as it is only meant to help the
|
AIO implementation perform better.
|
|
Before calling ‘aio_init’, the members of a variable of type
|
‘struct aioinit’ must be initialized. Then a reference to this
|
variable is passed as the parameter to ‘aio_init’ which itself may
|
or may not pay attention to the hints.
|
|
The function has no return value and no error cases are defined.
|
It is an extension which follows a proposal from the SGI
|
implementation in Irix 6. It is not covered by POSIX.1b or Unix98.
|
|
|
File: libc.info, Node: Control Operations, Next: Duplicating Descriptors, Prev: Asynchronous I/O, Up: Low-Level I/O
|
|
13.11 Control Operations on Files
|
=================================
|
|
This section describes how you can perform various other operations on
|
file descriptors, such as inquiring about or setting flags describing
|
the status of the file descriptor, manipulating record locks, and the
|
like. All of these operations are performed by the function ‘fcntl’.
|
|
The second argument to the ‘fcntl’ function is a command that
|
specifies which operation to perform. The function and macros that name
|
various flags that are used with it are declared in the header file
|
‘fcntl.h’. Many of these flags are also used by the ‘open’ function;
|
see *note Opening and Closing Files::.
|
|
-- Function: int fcntl (int FILEDES, int COMMAND, …)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘fcntl’ function performs the operation specified by COMMAND on
|
the file descriptor FILEDES. Some commands require additional
|
arguments to be supplied. These additional arguments and the
|
return value and error conditions are given in the detailed
|
descriptions of the individual commands.
|
|
Briefly, here is a list of what the various commands are.
|
|
‘F_DUPFD’
|
Duplicate the file descriptor (return another file descriptor
|
pointing to the same open file). *Note Duplicating
|
Descriptors::.
|
|
‘F_GETFD’
|
Get flags associated with the file descriptor. *Note
|
Descriptor Flags::.
|
|
‘F_SETFD’
|
Set flags associated with the file descriptor. *Note
|
Descriptor Flags::.
|
|
‘F_GETFL’
|
Get flags associated with the open file. *Note File Status
|
Flags::.
|
|
‘F_SETFL’
|
Set flags associated with the open file. *Note File Status
|
Flags::.
|
|
‘F_GETLK’
|
Test a file lock. *Note File Locks::.
|
|
‘F_SETLK’
|
Set or clear a file lock. *Note File Locks::.
|
|
‘F_SETLKW’
|
Like ‘F_SETLK’, but wait for completion. *Note File Locks::.
|
|
‘F_OFD_GETLK’
|
Test an open file description lock. *Note Open File
|
Description Locks::. Specific to Linux.
|
|
‘F_OFD_SETLK’
|
Set or clear an open file description lock. *Note Open File
|
Description Locks::. Specific to Linux.
|
|
‘F_OFD_SETLKW’
|
Like ‘F_OFD_SETLK’, but block until lock is acquired. *Note
|
Open File Description Locks::. Specific to Linux.
|
|
‘F_GETOWN’
|
Get process or process group ID to receive ‘SIGIO’ signals.
|
*Note Interrupt Input::.
|
|
‘F_SETOWN’
|
Set process or process group ID to receive ‘SIGIO’ signals.
|
*Note Interrupt Input::.
|
|
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
|
‘fcntl’ is called. If the thread gets canceled these resources
|
stay allocated until the program ends. To avoid this calls to
|
‘fcntl’ should be protected using cancellation handlers.
|
|
|
File: libc.info, Node: Duplicating Descriptors, Next: Descriptor Flags, Prev: Control Operations, Up: Low-Level I/O
|
|
13.12 Duplicating Descriptors
|
=============================
|
|
You can "duplicate" a file descriptor, or allocate another file
|
descriptor that refers to the same open file as the original. Duplicate
|
descriptors share one file position and one set of file status flags
|
(*note File Status Flags::), but each has its own set of file descriptor
|
flags (*note Descriptor Flags::).
|
|
The major use of duplicating a file descriptor is to implement
|
"redirection" of input or output: that is, to change the file or pipe
|
that a particular file descriptor corresponds to.
|
|
You can perform this operation using the ‘fcntl’ function with the
|
‘F_DUPFD’ command, but there are also convenient functions ‘dup’ and
|
‘dup2’ for duplicating descriptors.
|
|
The ‘fcntl’ function and flags are declared in ‘fcntl.h’, while
|
prototypes for ‘dup’ and ‘dup2’ are in the header file ‘unistd.h’.
|
|
-- Function: int dup (int OLD)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function copies descriptor OLD to the first available
|
descriptor number (the first number not currently open). It is
|
equivalent to ‘fcntl (OLD, F_DUPFD, 0)’.
|
|
-- Function: int dup2 (int OLD, int NEW)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function copies the descriptor OLD to descriptor number NEW.
|
|
If OLD is an invalid descriptor, then ‘dup2’ does nothing; it does
|
not close NEW. Otherwise, the new duplicate of OLD replaces any
|
previous meaning of descriptor NEW, as if NEW were closed first.
|
|
If OLD and NEW are different numbers, and OLD is a valid descriptor
|
number, then ‘dup2’ is equivalent to:
|
|
close (NEW);
|
fcntl (OLD, F_DUPFD, NEW)
|
|
However, ‘dup2’ does this atomically; there is no instant in the
|
middle of calling ‘dup2’ at which NEW is closed and not yet a
|
duplicate of OLD.
|
|
-- Macro: int F_DUPFD
|
This macro is used as the COMMAND argument to ‘fcntl’, to copy the
|
file descriptor given as the first argument.
|
|
The form of the call in this case is:
|
|
fcntl (OLD, F_DUPFD, NEXT-FILEDES)
|
|
The NEXT-FILEDES argument is of type ‘int’ and specifies that the
|
file descriptor returned should be the next available one greater
|
than or equal to this value.
|
|
The return value from ‘fcntl’ with this command is normally the
|
value of the new file descriptor. A return value of -1 indicates
|
an error. The following ‘errno’ error conditions are defined for
|
this command:
|
|
‘EBADF’
|
The OLD argument is invalid.
|
|
‘EINVAL’
|
The NEXT-FILEDES argument is invalid.
|
|
‘EMFILE’
|
There are no more file descriptors available—your program is
|
already using the maximum. In BSD and GNU, the maximum is
|
controlled by a resource limit that can be changed; *note
|
Limits on Resources::, for more information about the
|
‘RLIMIT_NOFILE’ limit.
|
|
‘ENFILE’ is not a possible error code for ‘dup2’ because ‘dup2’
|
does not create a new opening of a file; duplicate descriptors do
|
not count toward the limit which ‘ENFILE’ indicates. ‘EMFILE’ is
|
possible because it refers to the limit on distinct descriptor
|
numbers in use in one process.
|
|
Here is an example showing how to use ‘dup2’ to do redirection.
|
Typically, redirection of the standard streams (like ‘stdin’) is done by
|
a shell or shell-like program before calling one of the ‘exec’ functions
|
(*note Executing a File::) to execute a new program in a child process.
|
When the new program is executed, it creates and initializes the
|
standard streams to point to the corresponding file descriptors, before
|
its ‘main’ function is invoked.
|
|
So, to redirect standard input to a file, the shell could do
|
something like:
|
|
pid = fork ();
|
if (pid == 0)
|
{
|
char *filename;
|
char *program;
|
int file;
|
…
|
file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
|
dup2 (file, STDIN_FILENO);
|
TEMP_FAILURE_RETRY (close (file));
|
execv (program, NULL);
|
}
|
|
There is also a more detailed example showing how to implement
|
redirection in the context of a pipeline of processes in *note Launching
|
Jobs::.
|
|
|
File: libc.info, Node: Descriptor Flags, Next: File Status Flags, Prev: Duplicating Descriptors, Up: Low-Level I/O
|
|
13.13 File Descriptor Flags
|
===========================
|
|
"File descriptor flags" are miscellaneous attributes of a file
|
descriptor. These flags are associated with particular file
|
descriptors, so that if you have created duplicate file descriptors from
|
a single opening of a file, each descriptor has its own set of flags.
|
|
Currently there is just one file descriptor flag: ‘FD_CLOEXEC’, which
|
causes the descriptor to be closed if you use any of the ‘exec…’
|
functions (*note Executing a File::).
|
|
The symbols in this section are defined in the header file ‘fcntl.h’.
|
|
-- Macro: int F_GETFD
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should return the file descriptor flags associated with the
|
FILEDES argument.
|
|
The normal return value from ‘fcntl’ with this command is a
|
nonnegative number which can be interpreted as the bitwise OR of
|
the individual flags (except that currently there is only one flag
|
to use).
|
|
In case of an error, ‘fcntl’ returns -1. The following ‘errno’
|
error conditions are defined for this command:
|
|
‘EBADF’
|
The FILEDES argument is invalid.
|
|
-- Macro: int F_SETFD
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should set the file descriptor flags associated with the
|
FILEDES argument. This requires a third ‘int’ argument to specify
|
the new flags, so the form of the call is:
|
|
fcntl (FILEDES, F_SETFD, NEW-FLAGS)
|
|
The normal return value from ‘fcntl’ with this command is an
|
unspecified value other than -1, which indicates an error. The
|
flags and error conditions are the same as for the ‘F_GETFD’
|
command.
|
|
The following macro is defined for use as a file descriptor flag with
|
the ‘fcntl’ function. The value is an integer constant usable as a bit
|
mask value.
|
|
-- Macro: int FD_CLOEXEC
|
This flag specifies that the file descriptor should be closed when
|
an ‘exec’ function is invoked; see *note Executing a File::. When
|
a file descriptor is allocated (as with ‘open’ or ‘dup’), this bit
|
is initially cleared on the new file descriptor, meaning that
|
descriptor will survive into the new program after ‘exec’.
|
|
If you want to modify the file descriptor flags, you should get the
|
current flags with ‘F_GETFD’ and modify the value. Don’t assume that
|
the flags listed here are the only ones that are implemented; your
|
program may be run years from now and more flags may exist then. For
|
example, here is a function to set or clear the flag ‘FD_CLOEXEC’
|
without altering any other flags:
|
|
/* Set the ‘FD_CLOEXEC’ flag of DESC if VALUE is nonzero,
|
or clear the flag if VALUE is 0.
|
Return 0 on success, or -1 on error with ‘errno’ set. */
|
|
int
|
set_cloexec_flag (int desc, int value)
|
{
|
int oldflags = fcntl (desc, F_GETFD, 0);
|
/* If reading the flags failed, return error indication now. */
|
if (oldflags < 0)
|
return oldflags;
|
/* Set just the flag we want to set. */
|
if (value != 0)
|
oldflags |= FD_CLOEXEC;
|
else
|
oldflags &= ~FD_CLOEXEC;
|
/* Store modified flag word in the descriptor. */
|
return fcntl (desc, F_SETFD, oldflags);
|
}
|
|
|
File: libc.info, Node: File Status Flags, Next: File Locks, Prev: Descriptor Flags, Up: Low-Level I/O
|
|
13.14 File Status Flags
|
=======================
|
|
"File status flags" are used to specify attributes of the opening of a
|
file. Unlike the file descriptor flags discussed in *note Descriptor
|
Flags::, the file status flags are shared by duplicated file descriptors
|
resulting from a single opening of the file. The file status flags are
|
specified with the FLAGS argument to ‘open’; *note Opening and Closing
|
Files::.
|
|
File status flags fall into three categories, which are described in
|
the following sections.
|
|
• *note Access Modes::, specify what type of access is allowed to the
|
file: reading, writing, or both. They are set by ‘open’ and are
|
returned by ‘fcntl’, but cannot be changed.
|
|
• *note Open-time Flags::, control details of what ‘open’ will do.
|
These flags are not preserved after the ‘open’ call.
|
|
• *note Operating Modes::, affect how operations such as ‘read’ and
|
‘write’ are done. They are set by ‘open’, and can be fetched or
|
changed with ‘fcntl’.
|
|
The symbols in this section are defined in the header file ‘fcntl.h’.
|
|
* Menu:
|
|
* Access Modes:: Whether the descriptor can read or write.
|
* Open-time Flags:: Details of ‘open’.
|
* Operating Modes:: Special modes to control I/O operations.
|
* Getting File Status Flags:: Fetching and changing these flags.
|
|
|
File: libc.info, Node: Access Modes, Next: Open-time Flags, Up: File Status Flags
|
|
13.14.1 File Access Modes
|
-------------------------
|
|
The file access modes allow a file descriptor to be used for reading,
|
writing, or both. (On GNU/Hurd systems, they can also allow none of
|
these, and allow execution of the file as a program.) The access modes
|
are chosen when the file is opened, and never change.
|
|
-- Macro: int O_RDONLY
|
Open the file for read access.
|
|
-- Macro: int O_WRONLY
|
Open the file for write access.
|
|
-- Macro: int O_RDWR
|
Open the file for both reading and writing.
|
|
On GNU/Hurd systems (and not on other systems), ‘O_RDONLY’ and
|
‘O_WRONLY’ are independent bits that can be bitwise-ORed together, and
|
it is valid for either bit to be set or clear. This means that ‘O_RDWR’
|
is the same as ‘O_RDONLY|O_WRONLY’. A file access mode of zero is
|
permissible; it allows no operations that do input or output to the
|
file, but does allow other operations such as ‘fchmod’. On GNU/Hurd
|
systems, since “read-only” or “write-only” is a misnomer, ‘fcntl.h’
|
defines additional names for the file access modes. These names are
|
preferred when writing GNU-specific code. But most programs will want
|
to be portable to other POSIX.1 systems and should use the POSIX.1 names
|
above instead.
|
|
-- Macro: int O_READ
|
Open the file for reading. Same as ‘O_RDONLY’; only defined on
|
GNU.
|
|
-- Macro: int O_WRITE
|
Open the file for writing. Same as ‘O_WRONLY’; only defined on
|
GNU.
|
|
-- Macro: int O_EXEC
|
Open the file for executing. Only defined on GNU.
|
|
To determine the file access mode with ‘fcntl’, you must extract the
|
access mode bits from the retrieved file status flags. On GNU/Hurd
|
systems, you can just test the ‘O_READ’ and ‘O_WRITE’ bits in the flags
|
word. But in other POSIX.1 systems, reading and writing access modes
|
are not stored as distinct bit flags. The portable way to extract the
|
file access mode bits is with ‘O_ACCMODE’.
|
|
-- Macro: int O_ACCMODE
|
This macro stands for a mask that can be bitwise-ANDed with the
|
file status flag value to produce a value representing the file
|
access mode. The mode will be ‘O_RDONLY’, ‘O_WRONLY’, or ‘O_RDWR’.
|
(On GNU/Hurd systems it could also be zero, and it never includes
|
the ‘O_EXEC’ bit.)
|
|
|
File: libc.info, Node: Open-time Flags, Next: Operating Modes, Prev: Access Modes, Up: File Status Flags
|
|
13.14.2 Open-time Flags
|
-----------------------
|
|
The open-time flags specify options affecting how ‘open’ will behave.
|
These options are not preserved once the file is open. The exception to
|
this is ‘O_NONBLOCK’, which is also an I/O operating mode and so it _is_
|
saved. *Note Opening and Closing Files::, for how to call ‘open’.
|
|
There are two sorts of options specified by open-time flags.
|
|
• "File name translation flags" affect how ‘open’ looks up the file
|
name to locate the file, and whether the file can be created.
|
|
• "Open-time action flags" specify extra operations that ‘open’ will
|
perform on the file once it is open.
|
|
Here are the file name translation flags.
|
|
-- Macro: int O_CREAT
|
If set, the file will be created if it doesn’t already exist.
|
|
-- Macro: int O_EXCL
|
If both ‘O_CREAT’ and ‘O_EXCL’ are set, then ‘open’ fails if the
|
specified file already exists. This is guaranteed to never clobber
|
an existing file.
|
|
-- Macro: int O_NONBLOCK
|
This prevents ‘open’ from blocking for a “long time” to open the
|
file. This is only meaningful for some kinds of files, usually
|
devices such as serial ports; when it is not meaningful, it is
|
harmless and ignored. Often, opening a port to a modem blocks
|
until the modem reports carrier detection; if ‘O_NONBLOCK’ is
|
specified, ‘open’ will return immediately without a carrier.
|
|
Note that the ‘O_NONBLOCK’ flag is overloaded as both an I/O
|
operating mode and a file name translation flag. This means that
|
specifying ‘O_NONBLOCK’ in ‘open’ also sets nonblocking I/O mode;
|
*note Operating Modes::. To open the file without blocking but do
|
normal I/O that blocks, you must call ‘open’ with ‘O_NONBLOCK’ set
|
and then call ‘fcntl’ to turn the bit off.
|
|
-- Macro: int O_NOCTTY
|
If the named file is a terminal device, don’t make it the
|
controlling terminal for the process. *Note Job Control::, for
|
information about what it means to be the controlling terminal.
|
|
On GNU/Hurd systems and 4.4 BSD, opening a file never makes it the
|
controlling terminal and ‘O_NOCTTY’ is zero. However, GNU/Linux
|
systems and some other systems use a nonzero value for ‘O_NOCTTY’
|
and set the controlling terminal when you open a file that is a
|
terminal device; so to be portable, use ‘O_NOCTTY’ when it is
|
important to avoid this.
|
|
The following three file name translation flags exist only on
|
GNU/Hurd systems.
|
|
-- Macro: int O_IGNORE_CTTY
|
Do not recognize the named file as the controlling terminal, even
|
if it refers to the process’s existing controlling terminal device.
|
Operations on the new file descriptor will never induce job control
|
signals. *Note Job Control::.
|
|
-- Macro: int O_NOLINK
|
If the named file is a symbolic link, open the link itself instead
|
of the file it refers to. (‘fstat’ on the new file descriptor will
|
return the information returned by ‘lstat’ on the link’s name.)
|
|
-- Macro: int O_NOTRANS
|
If the named file is specially translated, do not invoke the
|
translator. Open the bare file the translator itself sees.
|
|
The open-time action flags tell ‘open’ to do additional operations
|
which are not really related to opening the file. The reason to do them
|
as part of ‘open’ instead of in separate calls is that ‘open’ can do
|
them atomically.
|
|
-- Macro: int O_TRUNC
|
Truncate the file to zero length. This option is only useful for
|
regular files, not special files such as directories or FIFOs.
|
POSIX.1 requires that you open the file for writing to use
|
‘O_TRUNC’. In BSD and GNU you must have permission to write the
|
file to truncate it, but you need not open for write access.
|
|
This is the only open-time action flag specified by POSIX.1. There
|
is no good reason for truncation to be done by ‘open’, instead of
|
by calling ‘ftruncate’ afterwards. The ‘O_TRUNC’ flag existed in
|
Unix before ‘ftruncate’ was invented, and is retained for backward
|
compatibility.
|
|
The remaining operating modes are BSD extensions. They exist only on
|
some systems. On other systems, these macros are not defined.
|
|
-- Macro: int O_SHLOCK
|
Acquire a shared lock on the file, as with ‘flock’. *Note File
|
Locks::.
|
|
If ‘O_CREAT’ is specified, the locking is done atomically when
|
creating the file. You are guaranteed that no other process will
|
get the lock on the new file first.
|
|
-- Macro: int O_EXLOCK
|
Acquire an exclusive lock on the file, as with ‘flock’. *Note File
|
Locks::. This is atomic like ‘O_SHLOCK’.
|
