This is libc.info, produced by makeinfo version 5.1 from libc.texinfo.
|
|
This is ‘The GNU C Library Reference Manual’, for version 2.33 (GNU).
|
|
Copyright © 1993–2021 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being “Free Software Needs Free Documentation” and
|
“GNU Lesser General Public License”, the Front-Cover texts being “A GNU
|
Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
|
license is included in the section entitled "GNU Free Documentation
|
License".
|
|
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
|
modify this GNU manual. Buying copies from the FSF supports it in
|
developing GNU and promoting software freedom.”
|
INFO-DIR-SECTION Software libraries
|
START-INFO-DIR-ENTRY
|
* Libc: (libc). C library.
|
END-INFO-DIR-ENTRY
|
|
INFO-DIR-SECTION GNU C library functions and macros
|
START-INFO-DIR-ENTRY
|
* ALTWERASE: (libc)Local Modes.
|
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
|
* ARG_MAX: (libc)General Limits.
|
* BC_BASE_MAX: (libc)Utility Limits.
|
* BC_DIM_MAX: (libc)Utility Limits.
|
* BC_SCALE_MAX: (libc)Utility Limits.
|
* BC_STRING_MAX: (libc)Utility Limits.
|
* BRKINT: (libc)Input Modes.
|
* BUFSIZ: (libc)Controlling Buffering.
|
* CCTS_OFLOW: (libc)Control Modes.
|
* CHAR_BIT: (libc)Width of Type.
|
* CHILD_MAX: (libc)General Limits.
|
* CIGNORE: (libc)Control Modes.
|
* CLK_TCK: (libc)Processor Time.
|
* CLOCAL: (libc)Control Modes.
|
* CLOCKS_PER_SEC: (libc)CPU Time.
|
* CLOCK_MONOTONIC: (libc)Getting the Time.
|
* CLOCK_REALTIME: (libc)Getting the Time.
|
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
|
* CPU_CLR: (libc)CPU Affinity.
|
* CPU_FEATURE_USABLE: (libc)X86.
|
* CPU_ISSET: (libc)CPU Affinity.
|
* CPU_SET: (libc)CPU Affinity.
|
* CPU_SETSIZE: (libc)CPU Affinity.
|
* CPU_ZERO: (libc)CPU Affinity.
|
* CREAD: (libc)Control Modes.
|
* CRTS_IFLOW: (libc)Control Modes.
|
* CS5: (libc)Control Modes.
|
* CS6: (libc)Control Modes.
|
* CS7: (libc)Control Modes.
|
* CS8: (libc)Control Modes.
|
* CSIZE: (libc)Control Modes.
|
* CSTOPB: (libc)Control Modes.
|
* DTTOIF: (libc)Directory Entries.
|
* E2BIG: (libc)Error Codes.
|
* EACCES: (libc)Error Codes.
|
* EADDRINUSE: (libc)Error Codes.
|
* EADDRNOTAVAIL: (libc)Error Codes.
|
* EADV: (libc)Error Codes.
|
* EAFNOSUPPORT: (libc)Error Codes.
|
* EAGAIN: (libc)Error Codes.
|
* EALREADY: (libc)Error Codes.
|
* EAUTH: (libc)Error Codes.
|
* EBACKGROUND: (libc)Error Codes.
|
* EBADE: (libc)Error Codes.
|
* EBADF: (libc)Error Codes.
|
* EBADFD: (libc)Error Codes.
|
* EBADMSG: (libc)Error Codes.
|
* EBADR: (libc)Error Codes.
|
* EBADRPC: (libc)Error Codes.
|
* EBADRQC: (libc)Error Codes.
|
* EBADSLT: (libc)Error Codes.
|
* EBFONT: (libc)Error Codes.
|
* EBUSY: (libc)Error Codes.
|
* ECANCELED: (libc)Error Codes.
|
* ECHILD: (libc)Error Codes.
|
* ECHO: (libc)Local Modes.
|
* ECHOCTL: (libc)Local Modes.
|
* ECHOE: (libc)Local Modes.
|
* ECHOK: (libc)Local Modes.
|
* ECHOKE: (libc)Local Modes.
|
* ECHONL: (libc)Local Modes.
|
* ECHOPRT: (libc)Local Modes.
|
* ECHRNG: (libc)Error Codes.
|
* ECOMM: (libc)Error Codes.
|
* ECONNABORTED: (libc)Error Codes.
|
* ECONNREFUSED: (libc)Error Codes.
|
* ECONNRESET: (libc)Error Codes.
|
* ED: (libc)Error Codes.
|
* EDEADLK: (libc)Error Codes.
|
* EDEADLOCK: (libc)Error Codes.
|
* EDESTADDRREQ: (libc)Error Codes.
|
* EDIED: (libc)Error Codes.
|
* EDOM: (libc)Error Codes.
|
* EDOTDOT: (libc)Error Codes.
|
* EDQUOT: (libc)Error Codes.
|
* EEXIST: (libc)Error Codes.
|
* EFAULT: (libc)Error Codes.
|
* EFBIG: (libc)Error Codes.
|
* EFTYPE: (libc)Error Codes.
|
* EGRATUITOUS: (libc)Error Codes.
|
* EGREGIOUS: (libc)Error Codes.
|
* EHOSTDOWN: (libc)Error Codes.
|
* EHOSTUNREACH: (libc)Error Codes.
|
* EHWPOISON: (libc)Error Codes.
|
* EIDRM: (libc)Error Codes.
|
* EIEIO: (libc)Error Codes.
|
* EILSEQ: (libc)Error Codes.
|
* EINPROGRESS: (libc)Error Codes.
|
* EINTR: (libc)Error Codes.
|
* EINVAL: (libc)Error Codes.
|
* EIO: (libc)Error Codes.
|
* EISCONN: (libc)Error Codes.
|
* EISDIR: (libc)Error Codes.
|
* EISNAM: (libc)Error Codes.
|
* EKEYEXPIRED: (libc)Error Codes.
|
* EKEYREJECTED: (libc)Error Codes.
|
* EKEYREVOKED: (libc)Error Codes.
|
* EL2HLT: (libc)Error Codes.
|
* EL2NSYNC: (libc)Error Codes.
|
* EL3HLT: (libc)Error Codes.
|
* EL3RST: (libc)Error Codes.
|
* ELIBACC: (libc)Error Codes.
|
* ELIBBAD: (libc)Error Codes.
|
* ELIBEXEC: (libc)Error Codes.
|
* ELIBMAX: (libc)Error Codes.
|
* ELIBSCN: (libc)Error Codes.
|
* ELNRNG: (libc)Error Codes.
|
* ELOOP: (libc)Error Codes.
|
* EMEDIUMTYPE: (libc)Error Codes.
|
* EMFILE: (libc)Error Codes.
|
* EMLINK: (libc)Error Codes.
|
* EMSGSIZE: (libc)Error Codes.
|
* EMULTIHOP: (libc)Error Codes.
|
* ENAMETOOLONG: (libc)Error Codes.
|
* ENAVAIL: (libc)Error Codes.
|
* ENEEDAUTH: (libc)Error Codes.
|
* ENETDOWN: (libc)Error Codes.
|
* ENETRESET: (libc)Error Codes.
|
* ENETUNREACH: (libc)Error Codes.
|
* ENFILE: (libc)Error Codes.
|
* ENOANO: (libc)Error Codes.
|
* ENOBUFS: (libc)Error Codes.
|
* ENOCSI: (libc)Error Codes.
|
* ENODATA: (libc)Error Codes.
|
* ENODEV: (libc)Error Codes.
|
* ENOENT: (libc)Error Codes.
|
* ENOEXEC: (libc)Error Codes.
|
* ENOKEY: (libc)Error Codes.
|
* ENOLCK: (libc)Error Codes.
|
* ENOLINK: (libc)Error Codes.
|
* ENOMEDIUM: (libc)Error Codes.
|
* ENOMEM: (libc)Error Codes.
|
* ENOMSG: (libc)Error Codes.
|
* ENONET: (libc)Error Codes.
|
* ENOPKG: (libc)Error Codes.
|
* ENOPROTOOPT: (libc)Error Codes.
|
* ENOSPC: (libc)Error Codes.
|
* ENOSR: (libc)Error Codes.
|
* ENOSTR: (libc)Error Codes.
|
* ENOSYS: (libc)Error Codes.
|
* ENOTBLK: (libc)Error Codes.
|
* ENOTCONN: (libc)Error Codes.
|
* ENOTDIR: (libc)Error Codes.
|
* ENOTEMPTY: (libc)Error Codes.
|
* ENOTNAM: (libc)Error Codes.
|
* ENOTRECOVERABLE: (libc)Error Codes.
|
* ENOTSOCK: (libc)Error Codes.
|
* ENOTSUP: (libc)Error Codes.
|
* ENOTTY: (libc)Error Codes.
|
* ENOTUNIQ: (libc)Error Codes.
|
* ENXIO: (libc)Error Codes.
|
* EOF: (libc)EOF and Errors.
|
* EOPNOTSUPP: (libc)Error Codes.
|
* EOVERFLOW: (libc)Error Codes.
|
* EOWNERDEAD: (libc)Error Codes.
|
* EPERM: (libc)Error Codes.
|
* EPFNOSUPPORT: (libc)Error Codes.
|
* EPIPE: (libc)Error Codes.
|
* EPROCLIM: (libc)Error Codes.
|
* EPROCUNAVAIL: (libc)Error Codes.
|
* EPROGMISMATCH: (libc)Error Codes.
|
* EPROGUNAVAIL: (libc)Error Codes.
|
* EPROTO: (libc)Error Codes.
|
* EPROTONOSUPPORT: (libc)Error Codes.
|
* EPROTOTYPE: (libc)Error Codes.
|
* EQUIV_CLASS_MAX: (libc)Utility Limits.
|
* ERANGE: (libc)Error Codes.
|
* EREMCHG: (libc)Error Codes.
|
* EREMOTE: (libc)Error Codes.
|
* EREMOTEIO: (libc)Error Codes.
|
* ERESTART: (libc)Error Codes.
|
* ERFKILL: (libc)Error Codes.
|
* EROFS: (libc)Error Codes.
|
* ERPCMISMATCH: (libc)Error Codes.
|
* ESHUTDOWN: (libc)Error Codes.
|
* ESOCKTNOSUPPORT: (libc)Error Codes.
|
* ESPIPE: (libc)Error Codes.
|
* ESRCH: (libc)Error Codes.
|
* ESRMNT: (libc)Error Codes.
|
* ESTALE: (libc)Error Codes.
|
* ESTRPIPE: (libc)Error Codes.
|
* ETIME: (libc)Error Codes.
|
* ETIMEDOUT: (libc)Error Codes.
|
* ETOOMANYREFS: (libc)Error Codes.
|
* ETXTBSY: (libc)Error Codes.
|
* EUCLEAN: (libc)Error Codes.
|
* EUNATCH: (libc)Error Codes.
|
* EUSERS: (libc)Error Codes.
|
* EWOULDBLOCK: (libc)Error Codes.
|
* EXDEV: (libc)Error Codes.
|
* EXFULL: (libc)Error Codes.
|
* EXIT_FAILURE: (libc)Exit Status.
|
* EXIT_SUCCESS: (libc)Exit Status.
|
* EXPR_NEST_MAX: (libc)Utility Limits.
|
* FD_CLOEXEC: (libc)Descriptor Flags.
|
* FD_CLR: (libc)Waiting for I/O.
|
* FD_ISSET: (libc)Waiting for I/O.
|
* FD_SET: (libc)Waiting for I/O.
|
* FD_SETSIZE: (libc)Waiting for I/O.
|
* FD_ZERO: (libc)Waiting for I/O.
|
* FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
|
* FILENAME_MAX: (libc)Limits for Files.
|
* FLUSHO: (libc)Local Modes.
|
* FOPEN_MAX: (libc)Opening Streams.
|
* FP_ILOGB0: (libc)Exponents and Logarithms.
|
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
|
* FP_LLOGB0: (libc)Exponents and Logarithms.
|
* FP_LLOGBNAN: (libc)Exponents and Logarithms.
|
* F_DUPFD: (libc)Duplicating Descriptors.
|
* F_GETFD: (libc)Descriptor Flags.
|
* F_GETFL: (libc)Getting File Status Flags.
|
* F_GETLK: (libc)File Locks.
|
* F_GETOWN: (libc)Interrupt Input.
|
* F_OFD_GETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLKW: (libc)Open File Description Locks.
|
* F_OK: (libc)Testing File Access.
|
* F_SETFD: (libc)Descriptor Flags.
|
* F_SETFL: (libc)Getting File Status Flags.
|
* F_SETLK: (libc)File Locks.
|
* F_SETLKW: (libc)File Locks.
|
* F_SETOWN: (libc)Interrupt Input.
|
* HAS_CPU_FEATURE: (libc)X86.
|
* HUGE_VAL: (libc)Math Error Reporting.
|
* HUGE_VALF: (libc)Math Error Reporting.
|
* HUGE_VALL: (libc)Math Error Reporting.
|
* HUGE_VAL_FN: (libc)Math Error Reporting.
|
* HUGE_VAL_FNx: (libc)Math Error Reporting.
|
* HUPCL: (libc)Control Modes.
|
* I: (libc)Complex Numbers.
|
* ICANON: (libc)Local Modes.
|
* ICRNL: (libc)Input Modes.
|
* IEXTEN: (libc)Local Modes.
|
* IFNAMSIZ: (libc)Interface Naming.
|
* IFTODT: (libc)Directory Entries.
|
* IGNBRK: (libc)Input Modes.
|
* IGNCR: (libc)Input Modes.
|
* IGNPAR: (libc)Input Modes.
|
* IMAXBEL: (libc)Input Modes.
|
* INADDR_ANY: (libc)Host Address Data Type.
|
* INADDR_BROADCAST: (libc)Host Address Data Type.
|
* INADDR_LOOPBACK: (libc)Host Address Data Type.
|
* INADDR_NONE: (libc)Host Address Data Type.
|
* INFINITY: (libc)Infinity and NaN.
|
* INLCR: (libc)Input Modes.
|
* INPCK: (libc)Input Modes.
|
* IPPORT_RESERVED: (libc)Ports.
|
* IPPORT_USERRESERVED: (libc)Ports.
|
* ISIG: (libc)Local Modes.
|
* ISTRIP: (libc)Input Modes.
|
* IXANY: (libc)Input Modes.
|
* IXOFF: (libc)Input Modes.
|
* IXON: (libc)Input Modes.
|
* LINE_MAX: (libc)Utility Limits.
|
* LINK_MAX: (libc)Limits for Files.
|
* L_ctermid: (libc)Identifying the Terminal.
|
* L_cuserid: (libc)Who Logged In.
|
* L_tmpnam: (libc)Temporary Files.
|
* MAXNAMLEN: (libc)Limits for Files.
|
* MAXSYMLINKS: (libc)Symbolic Links.
|
* MAX_CANON: (libc)Limits for Files.
|
* MAX_INPUT: (libc)Limits for Files.
|
* MB_CUR_MAX: (libc)Selecting the Conversion.
|
* MB_LEN_MAX: (libc)Selecting the Conversion.
|
* MDMBUF: (libc)Control Modes.
|
* MSG_DONTROUTE: (libc)Socket Data Options.
|
* MSG_OOB: (libc)Socket Data Options.
|
* MSG_PEEK: (libc)Socket Data Options.
|
* NAME_MAX: (libc)Limits for Files.
|
* NAN: (libc)Infinity and NaN.
|
* NCCS: (libc)Mode Data Types.
|
* NGROUPS_MAX: (libc)General Limits.
|
* NOFLSH: (libc)Local Modes.
|
* NOKERNINFO: (libc)Local Modes.
|
* NSIG: (libc)Standard Signals.
|
* NULL: (libc)Null Pointer Constant.
|
* ONLCR: (libc)Output Modes.
|
* ONOEOT: (libc)Output Modes.
|
* OPEN_MAX: (libc)General Limits.
|
* OPOST: (libc)Output Modes.
|
* OXTABS: (libc)Output Modes.
|
* O_ACCMODE: (libc)Access Modes.
|
* O_APPEND: (libc)Operating Modes.
|
* O_ASYNC: (libc)Operating Modes.
|
* O_CREAT: (libc)Open-time Flags.
|
* O_DIRECTORY: (libc)Open-time Flags.
|
* O_EXCL: (libc)Open-time Flags.
|
* O_EXEC: (libc)Access Modes.
|
* O_EXLOCK: (libc)Open-time Flags.
|
* O_FSYNC: (libc)Operating Modes.
|
* O_IGNORE_CTTY: (libc)Open-time Flags.
|
* O_NDELAY: (libc)Operating Modes.
|
* O_NOATIME: (libc)Operating Modes.
|
* O_NOCTTY: (libc)Open-time Flags.
|
* O_NOFOLLOW: (libc)Open-time Flags.
|
* O_NOLINK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Operating Modes.
|
* O_NOTRANS: (libc)Open-time Flags.
|
* O_PATH: (libc)Access Modes.
|
* O_RDONLY: (libc)Access Modes.
|
* O_RDWR: (libc)Access Modes.
|
* O_READ: (libc)Access Modes.
|
* O_SHLOCK: (libc)Open-time Flags.
|
* O_SYNC: (libc)Operating Modes.
|
* O_TMPFILE: (libc)Open-time Flags.
|
* O_TRUNC: (libc)Open-time Flags.
|
* O_WRITE: (libc)Access Modes.
|
* O_WRONLY: (libc)Access Modes.
|
* PARENB: (libc)Control Modes.
|
* PARMRK: (libc)Input Modes.
|
* PARODD: (libc)Control Modes.
|
* PATH_MAX: (libc)Limits for Files.
|
* PA_FLAG_MASK: (libc)Parsing a Template String.
|
* PENDIN: (libc)Local Modes.
|
* PF_FILE: (libc)Local Namespace Details.
|
* PF_INET6: (libc)Internet Namespace.
|
* PF_INET: (libc)Internet Namespace.
|
* PF_LOCAL: (libc)Local Namespace Details.
|
* PF_UNIX: (libc)Local Namespace Details.
|
* PIPE_BUF: (libc)Limits for Files.
|
* PTHREAD_ATTR_NO_SIGMASK_NP: (libc)Initial Thread Signal Mask.
|
* P_tmpdir: (libc)Temporary Files.
|
* RAND_MAX: (libc)ISO Random.
|
* RE_DUP_MAX: (libc)General Limits.
|
* RLIM_INFINITY: (libc)Limits on Resources.
|
* R_OK: (libc)Testing File Access.
|
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
|
* SA_ONSTACK: (libc)Flags for Sigaction.
|
* SA_RESTART: (libc)Flags for Sigaction.
|
* SEEK_CUR: (libc)File Positioning.
|
* SEEK_END: (libc)File Positioning.
|
* SEEK_SET: (libc)File Positioning.
|
* SIGABRT: (libc)Program Error Signals.
|
* SIGALRM: (libc)Alarm Signals.
|
* SIGBUS: (libc)Program Error Signals.
|
* SIGCHLD: (libc)Job Control Signals.
|
* SIGCLD: (libc)Job Control Signals.
|
* SIGCONT: (libc)Job Control Signals.
|
* SIGEMT: (libc)Program Error Signals.
|
* SIGFPE: (libc)Program Error Signals.
|
* SIGHUP: (libc)Termination Signals.
|
* SIGILL: (libc)Program Error Signals.
|
* SIGINFO: (libc)Miscellaneous Signals.
|
* SIGINT: (libc)Termination Signals.
|
* SIGIO: (libc)Asynchronous I/O Signals.
|
* SIGIOT: (libc)Program Error Signals.
|
* SIGKILL: (libc)Termination Signals.
|
* SIGLOST: (libc)Operation Error Signals.
|
* SIGPIPE: (libc)Operation Error Signals.
|
* SIGPOLL: (libc)Asynchronous I/O Signals.
|
* SIGPROF: (libc)Alarm Signals.
|
* SIGQUIT: (libc)Termination Signals.
|
* SIGSEGV: (libc)Program Error Signals.
|
* SIGSTOP: (libc)Job Control Signals.
|
* SIGSYS: (libc)Program Error Signals.
|
* SIGTERM: (libc)Termination Signals.
|
* SIGTRAP: (libc)Program Error Signals.
|
* SIGTSTP: (libc)Job Control Signals.
|
* SIGTTIN: (libc)Job Control Signals.
|
* SIGTTOU: (libc)Job Control Signals.
|
* SIGURG: (libc)Asynchronous I/O Signals.
|
* SIGUSR1: (libc)Miscellaneous Signals.
|
* SIGUSR2: (libc)Miscellaneous Signals.
|
* SIGVTALRM: (libc)Alarm Signals.
|
* SIGWINCH: (libc)Miscellaneous Signals.
|
* SIGXCPU: (libc)Operation Error Signals.
|
* SIGXFSZ: (libc)Operation Error Signals.
|
* SIG_ERR: (libc)Basic Signal Handling.
|
* SNAN: (libc)Infinity and NaN.
|
* SNANF: (libc)Infinity and NaN.
|
* SNANFN: (libc)Infinity and NaN.
|
* SNANFNx: (libc)Infinity and NaN.
|
* SNANL: (libc)Infinity and NaN.
|
* SOCK_DGRAM: (libc)Communication Styles.
|
* SOCK_RAW: (libc)Communication Styles.
|
* SOCK_RDM: (libc)Communication Styles.
|
* SOCK_SEQPACKET: (libc)Communication Styles.
|
* SOCK_STREAM: (libc)Communication Styles.
|
* SOL_SOCKET: (libc)Socket-Level Options.
|
* SSIZE_MAX: (libc)General Limits.
|
* STREAM_MAX: (libc)General Limits.
|
* SUN_LEN: (libc)Local Namespace Details.
|
* S_IFMT: (libc)Testing File Type.
|
* S_ISBLK: (libc)Testing File Type.
|
* S_ISCHR: (libc)Testing File Type.
|
* S_ISDIR: (libc)Testing File Type.
|
* S_ISFIFO: (libc)Testing File Type.
|
* S_ISLNK: (libc)Testing File Type.
|
* S_ISREG: (libc)Testing File Type.
|
* S_ISSOCK: (libc)Testing File Type.
|
* S_TYPEISMQ: (libc)Testing File Type.
|
* S_TYPEISSEM: (libc)Testing File Type.
|
* S_TYPEISSHM: (libc)Testing File Type.
|
* TMP_MAX: (libc)Temporary Files.
|
* TOSTOP: (libc)Local Modes.
|
* TZNAME_MAX: (libc)General Limits.
|
* VDISCARD: (libc)Other Special.
|
* VDSUSP: (libc)Signal Characters.
|
* VEOF: (libc)Editing Characters.
|
* VEOL2: (libc)Editing Characters.
|
* VEOL: (libc)Editing Characters.
|
* VERASE: (libc)Editing Characters.
|
* VINTR: (libc)Signal Characters.
|
* VKILL: (libc)Editing Characters.
|
* VLNEXT: (libc)Other Special.
|
* VMIN: (libc)Noncanonical Input.
|
* VQUIT: (libc)Signal Characters.
|
* VREPRINT: (libc)Editing Characters.
|
* VSTART: (libc)Start/Stop Characters.
|
* VSTATUS: (libc)Other Special.
|
* VSTOP: (libc)Start/Stop Characters.
|
* VSUSP: (libc)Signal Characters.
|
* VTIME: (libc)Noncanonical Input.
|
* VWERASE: (libc)Editing Characters.
|
* WCHAR_MAX: (libc)Extended Char Intro.
|
* WCHAR_MIN: (libc)Extended Char Intro.
|
* WCOREDUMP: (libc)Process Completion Status.
|
* WEOF: (libc)EOF and Errors.
|
* WEOF: (libc)Extended Char Intro.
|
* WEXITSTATUS: (libc)Process Completion Status.
|
* WIFEXITED: (libc)Process Completion Status.
|
* WIFSIGNALED: (libc)Process Completion Status.
|
* WIFSTOPPED: (libc)Process Completion Status.
|
* WSTOPSIG: (libc)Process Completion Status.
|
* WTERMSIG: (libc)Process Completion Status.
|
* W_OK: (libc)Testing File Access.
|
* X_OK: (libc)Testing File Access.
|
* _Complex_I: (libc)Complex Numbers.
|
* _Exit: (libc)Termination Internals.
|
* _IOFBF: (libc)Controlling Buffering.
|
* _IOLBF: (libc)Controlling Buffering.
|
* _IONBF: (libc)Controlling Buffering.
|
* _Imaginary_I: (libc)Complex Numbers.
|
* _PATH_UTMP: (libc)Manipulating the Database.
|
* _PATH_WTMP: (libc)Manipulating the Database.
|
* _POSIX2_C_DEV: (libc)System Options.
|
* _POSIX2_C_VERSION: (libc)Version Supported.
|
* _POSIX2_FORT_DEV: (libc)System Options.
|
* _POSIX2_FORT_RUN: (libc)System Options.
|
* _POSIX2_LOCALEDEF: (libc)System Options.
|
* _POSIX2_SW_DEV: (libc)System Options.
|
* _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
|
* _POSIX_JOB_CONTROL: (libc)System Options.
|
* _POSIX_NO_TRUNC: (libc)Options for Files.
|
* _POSIX_SAVED_IDS: (libc)System Options.
|
* _POSIX_VDISABLE: (libc)Options for Files.
|
* _POSIX_VERSION: (libc)Version Supported.
|
* __fbufsize: (libc)Controlling Buffering.
|
* __flbf: (libc)Controlling Buffering.
|
* __fpending: (libc)Controlling Buffering.
|
* __fpurge: (libc)Flushing Buffers.
|
* __freadable: (libc)Opening Streams.
|
* __freading: (libc)Opening Streams.
|
* __fsetlocking: (libc)Streams and Threads.
|
* __fwritable: (libc)Opening Streams.
|
* __fwriting: (libc)Opening Streams.
|
* __gconv_end_fct: (libc)glibc iconv Implementation.
|
* __gconv_fct: (libc)glibc iconv Implementation.
|
* __gconv_init_fct: (libc)glibc iconv Implementation.
|
* __ppc_get_timebase: (libc)PowerPC.
|
* __ppc_get_timebase_freq: (libc)PowerPC.
|
* __ppc_mdoio: (libc)PowerPC.
|
* __ppc_mdoom: (libc)PowerPC.
|
* __ppc_set_ppr_low: (libc)PowerPC.
|
* __ppc_set_ppr_med: (libc)PowerPC.
|
* __ppc_set_ppr_med_high: (libc)PowerPC.
|
* __ppc_set_ppr_med_low: (libc)PowerPC.
|
* __ppc_set_ppr_very_low: (libc)PowerPC.
|
* __ppc_yield: (libc)PowerPC.
|
* __riscv_flush_icache: (libc)RISC-V.
|
* __va_copy: (libc)Argument Macros.
|
* __x86_get_cpuid_feature_leaf: (libc)X86.
|
* _exit: (libc)Termination Internals.
|
* _flushlbf: (libc)Flushing Buffers.
|
* _tolower: (libc)Case Conversion.
|
* _toupper: (libc)Case Conversion.
|
* a64l: (libc)Encode Binary Data.
|
* abort: (libc)Aborting a Program.
|
* abs: (libc)Absolute Value.
|
* accept: (libc)Accepting Connections.
|
* access: (libc)Testing File Access.
|
* acos: (libc)Inverse Trig Functions.
|
* acosf: (libc)Inverse Trig Functions.
|
* acosfN: (libc)Inverse Trig Functions.
|
* acosfNx: (libc)Inverse Trig Functions.
|
* acosh: (libc)Hyperbolic Functions.
|
* acoshf: (libc)Hyperbolic Functions.
|
* acoshfN: (libc)Hyperbolic Functions.
|
* acoshfNx: (libc)Hyperbolic Functions.
|
* acoshl: (libc)Hyperbolic Functions.
|
* acosl: (libc)Inverse Trig Functions.
|
* addmntent: (libc)mtab.
|
* addseverity: (libc)Adding Severity Classes.
|
* adjtime: (libc)Setting and Adjusting the Time.
|
* adjtimex: (libc)Setting and Adjusting the Time.
|
* aio_cancel64: (libc)Cancel AIO Operations.
|
* aio_cancel: (libc)Cancel AIO Operations.
|
* aio_error64: (libc)Status of AIO Operations.
|
* aio_error: (libc)Status of AIO Operations.
|
* aio_fsync64: (libc)Synchronizing AIO Operations.
|
* aio_fsync: (libc)Synchronizing AIO Operations.
|
* aio_init: (libc)Configuration of AIO.
|
* aio_read64: (libc)Asynchronous Reads/Writes.
|
* aio_read: (libc)Asynchronous Reads/Writes.
|
* aio_return64: (libc)Status of AIO Operations.
|
* aio_return: (libc)Status of AIO Operations.
|
* aio_suspend64: (libc)Synchronizing AIO Operations.
|
* aio_suspend: (libc)Synchronizing AIO Operations.
|
* aio_write64: (libc)Asynchronous Reads/Writes.
|
* aio_write: (libc)Asynchronous Reads/Writes.
|
* alarm: (libc)Setting an Alarm.
|
* aligned_alloc: (libc)Aligned Memory Blocks.
|
* alloca: (libc)Variable Size Automatic.
|
* alphasort64: (libc)Scanning Directory Content.
|
* alphasort: (libc)Scanning Directory Content.
|
* argp_error: (libc)Argp Helper Functions.
|
* argp_failure: (libc)Argp Helper Functions.
|
* argp_help: (libc)Argp Help.
|
* argp_parse: (libc)Argp.
|
* argp_state_help: (libc)Argp Helper Functions.
|
* argp_usage: (libc)Argp Helper Functions.
|
* argz_add: (libc)Argz Functions.
|
* argz_add_sep: (libc)Argz Functions.
|
* argz_append: (libc)Argz Functions.
|
* argz_count: (libc)Argz Functions.
|
* argz_create: (libc)Argz Functions.
|
* argz_create_sep: (libc)Argz Functions.
|
* argz_delete: (libc)Argz Functions.
|
* argz_extract: (libc)Argz Functions.
|
* argz_insert: (libc)Argz Functions.
|
* argz_next: (libc)Argz Functions.
|
* argz_replace: (libc)Argz Functions.
|
* argz_stringify: (libc)Argz Functions.
|
* asctime: (libc)Formatting Calendar Time.
|
* asctime_r: (libc)Formatting Calendar Time.
|
* asin: (libc)Inverse Trig Functions.
|
* asinf: (libc)Inverse Trig Functions.
|
* asinfN: (libc)Inverse Trig Functions.
|
* asinfNx: (libc)Inverse Trig Functions.
|
* asinh: (libc)Hyperbolic Functions.
|
* asinhf: (libc)Hyperbolic Functions.
|
* asinhfN: (libc)Hyperbolic Functions.
|
* asinhfNx: (libc)Hyperbolic Functions.
|
* asinhl: (libc)Hyperbolic Functions.
|
* asinl: (libc)Inverse Trig Functions.
|
* asprintf: (libc)Dynamic Output.
|
* assert: (libc)Consistency Checking.
|
* assert_perror: (libc)Consistency Checking.
|
* atan2: (libc)Inverse Trig Functions.
|
* atan2f: (libc)Inverse Trig Functions.
|
* atan2fN: (libc)Inverse Trig Functions.
|
* atan2fNx: (libc)Inverse Trig Functions.
|
* atan2l: (libc)Inverse Trig Functions.
|
* atan: (libc)Inverse Trig Functions.
|
* atanf: (libc)Inverse Trig Functions.
|
* atanfN: (libc)Inverse Trig Functions.
|
* atanfNx: (libc)Inverse Trig Functions.
|
* atanh: (libc)Hyperbolic Functions.
|
* atanhf: (libc)Hyperbolic Functions.
|
* atanhfN: (libc)Hyperbolic Functions.
|
* atanhfNx: (libc)Hyperbolic Functions.
|
* atanhl: (libc)Hyperbolic Functions.
|
* atanl: (libc)Inverse Trig Functions.
|
* atexit: (libc)Cleanups on Exit.
|
* atof: (libc)Parsing of Floats.
|
* atoi: (libc)Parsing of Integers.
|
* atol: (libc)Parsing of Integers.
|
* atoll: (libc)Parsing of Integers.
|
* backtrace: (libc)Backtraces.
|
* backtrace_symbols: (libc)Backtraces.
|
* backtrace_symbols_fd: (libc)Backtraces.
|
* basename: (libc)Finding Tokens in a String.
|
* basename: (libc)Finding Tokens in a String.
|
* bcmp: (libc)String/Array Comparison.
|
* bcopy: (libc)Copying Strings and Arrays.
|
* bind: (libc)Setting Address.
|
* bind_textdomain_codeset: (libc)Charset conversion in gettext.
|
* bindtextdomain: (libc)Locating gettext catalog.
|
* brk: (libc)Resizing the Data Segment.
|
* bsearch: (libc)Array Search Function.
|
* btowc: (libc)Converting a Character.
|
* bzero: (libc)Copying Strings and Arrays.
|
* cabs: (libc)Absolute Value.
|
* cabsf: (libc)Absolute Value.
|
* cabsfN: (libc)Absolute Value.
|
* cabsfNx: (libc)Absolute Value.
|
* cabsl: (libc)Absolute Value.
|
* cacos: (libc)Inverse Trig Functions.
|
* cacosf: (libc)Inverse Trig Functions.
|
* cacosfN: (libc)Inverse Trig Functions.
|
* cacosfNx: (libc)Inverse Trig Functions.
|
* cacosh: (libc)Hyperbolic Functions.
|
* cacoshf: (libc)Hyperbolic Functions.
|
* cacoshfN: (libc)Hyperbolic Functions.
|
* cacoshfNx: (libc)Hyperbolic Functions.
|
* cacoshl: (libc)Hyperbolic Functions.
|
* cacosl: (libc)Inverse Trig Functions.
|
* call_once: (libc)Call Once.
|
* calloc: (libc)Allocating Cleared Space.
|
* canonicalize: (libc)FP Bit Twiddling.
|
* canonicalize_file_name: (libc)Symbolic Links.
|
* canonicalizef: (libc)FP Bit Twiddling.
|
* canonicalizefN: (libc)FP Bit Twiddling.
|
* canonicalizefNx: (libc)FP Bit Twiddling.
|
* canonicalizel: (libc)FP Bit Twiddling.
|
* carg: (libc)Operations on Complex.
|
* cargf: (libc)Operations on Complex.
|
* cargfN: (libc)Operations on Complex.
|
* cargfNx: (libc)Operations on Complex.
|
* cargl: (libc)Operations on Complex.
|
* casin: (libc)Inverse Trig Functions.
|
* casinf: (libc)Inverse Trig Functions.
|
* casinfN: (libc)Inverse Trig Functions.
|
* casinfNx: (libc)Inverse Trig Functions.
|
* casinh: (libc)Hyperbolic Functions.
|
* casinhf: (libc)Hyperbolic Functions.
|
* casinhfN: (libc)Hyperbolic Functions.
|
* casinhfNx: (libc)Hyperbolic Functions.
|
* casinhl: (libc)Hyperbolic Functions.
|
* casinl: (libc)Inverse Trig Functions.
|
* catan: (libc)Inverse Trig Functions.
|
* catanf: (libc)Inverse Trig Functions.
|
* catanfN: (libc)Inverse Trig Functions.
|
* catanfNx: (libc)Inverse Trig Functions.
|
* catanh: (libc)Hyperbolic Functions.
|
* catanhf: (libc)Hyperbolic Functions.
|
* catanhfN: (libc)Hyperbolic Functions.
|
* catanhfNx: (libc)Hyperbolic Functions.
|
* catanhl: (libc)Hyperbolic Functions.
|
* catanl: (libc)Inverse Trig Functions.
|
* catclose: (libc)The catgets Functions.
|
* catgets: (libc)The catgets Functions.
|
* catopen: (libc)The catgets Functions.
|
* cbrt: (libc)Exponents and Logarithms.
|
* cbrtf: (libc)Exponents and Logarithms.
|
* cbrtfN: (libc)Exponents and Logarithms.
|
* cbrtfNx: (libc)Exponents and Logarithms.
|
* cbrtl: (libc)Exponents and Logarithms.
|
* ccos: (libc)Trig Functions.
|
* ccosf: (libc)Trig Functions.
|
* ccosfN: (libc)Trig Functions.
|
* ccosfNx: (libc)Trig Functions.
|
* ccosh: (libc)Hyperbolic Functions.
|
* ccoshf: (libc)Hyperbolic Functions.
|
* ccoshfN: (libc)Hyperbolic Functions.
|
* ccoshfNx: (libc)Hyperbolic Functions.
|
* ccoshl: (libc)Hyperbolic Functions.
|
* ccosl: (libc)Trig Functions.
|
* ceil: (libc)Rounding Functions.
|
* ceilf: (libc)Rounding Functions.
|
* ceilfN: (libc)Rounding Functions.
|
* ceilfNx: (libc)Rounding Functions.
|
* ceill: (libc)Rounding Functions.
|
* cexp: (libc)Exponents and Logarithms.
|
* cexpf: (libc)Exponents and Logarithms.
|
* cexpfN: (libc)Exponents and Logarithms.
|
* cexpfNx: (libc)Exponents and Logarithms.
|
* cexpl: (libc)Exponents and Logarithms.
|
* cfgetispeed: (libc)Line Speed.
|
* cfgetospeed: (libc)Line Speed.
|
* cfmakeraw: (libc)Noncanonical Input.
|
* cfsetispeed: (libc)Line Speed.
|
* cfsetospeed: (libc)Line Speed.
|
* cfsetspeed: (libc)Line Speed.
|
* chdir: (libc)Working Directory.
|
* chmod: (libc)Setting Permissions.
|
* chown: (libc)File Owner.
|
* cimag: (libc)Operations on Complex.
|
* cimagf: (libc)Operations on Complex.
|
* cimagfN: (libc)Operations on Complex.
|
* cimagfNx: (libc)Operations on Complex.
|
* cimagl: (libc)Operations on Complex.
|
* clearenv: (libc)Environment Access.
|
* clearerr: (libc)Error Recovery.
|
* clearerr_unlocked: (libc)Error Recovery.
|
* clock: (libc)CPU Time.
|
* clock_getres: (libc)Getting the Time.
|
* clock_gettime: (libc)Getting the Time.
|
* clock_settime: (libc)Setting and Adjusting the Time.
|
* clog10: (libc)Exponents and Logarithms.
|
* clog10f: (libc)Exponents and Logarithms.
|
* clog10fN: (libc)Exponents and Logarithms.
|
* clog10fNx: (libc)Exponents and Logarithms.
|
* clog10l: (libc)Exponents and Logarithms.
|
* clog: (libc)Exponents and Logarithms.
|
* clogf: (libc)Exponents and Logarithms.
|
* clogfN: (libc)Exponents and Logarithms.
|
* clogfNx: (libc)Exponents and Logarithms.
|
* clogl: (libc)Exponents and Logarithms.
|
* close: (libc)Opening and Closing Files.
|
* closedir: (libc)Reading/Closing Directory.
|
* closelog: (libc)closelog.
|
* cnd_broadcast: (libc)ISO C Condition Variables.
|
* cnd_destroy: (libc)ISO C Condition Variables.
|
* cnd_init: (libc)ISO C Condition Variables.
|
* cnd_signal: (libc)ISO C Condition Variables.
|
* cnd_timedwait: (libc)ISO C Condition Variables.
|
* cnd_wait: (libc)ISO C Condition Variables.
|
* confstr: (libc)String Parameters.
|
* conj: (libc)Operations on Complex.
|
* conjf: (libc)Operations on Complex.
|
* conjfN: (libc)Operations on Complex.
|
* conjfNx: (libc)Operations on Complex.
|
* conjl: (libc)Operations on Complex.
|
* connect: (libc)Connecting.
|
* copy_file_range: (libc)Copying File Data.
|
* copysign: (libc)FP Bit Twiddling.
|
* copysignf: (libc)FP Bit Twiddling.
|
* copysignfN: (libc)FP Bit Twiddling.
|
* copysignfNx: (libc)FP Bit Twiddling.
|
* copysignl: (libc)FP Bit Twiddling.
|
* cos: (libc)Trig Functions.
|
* cosf: (libc)Trig Functions.
|
* cosfN: (libc)Trig Functions.
|
* cosfNx: (libc)Trig Functions.
|
* cosh: (libc)Hyperbolic Functions.
|
* coshf: (libc)Hyperbolic Functions.
|
* coshfN: (libc)Hyperbolic Functions.
|
* coshfNx: (libc)Hyperbolic Functions.
|
* coshl: (libc)Hyperbolic Functions.
|
* cosl: (libc)Trig Functions.
|
* cpow: (libc)Exponents and Logarithms.
|
* cpowf: (libc)Exponents and Logarithms.
|
* cpowfN: (libc)Exponents and Logarithms.
|
* cpowfNx: (libc)Exponents and Logarithms.
|
* cpowl: (libc)Exponents and Logarithms.
|
* cproj: (libc)Operations on Complex.
|
* cprojf: (libc)Operations on Complex.
|
* cprojfN: (libc)Operations on Complex.
|
* cprojfNx: (libc)Operations on Complex.
|
* cprojl: (libc)Operations on Complex.
|
* creal: (libc)Operations on Complex.
|
* crealf: (libc)Operations on Complex.
|
* crealfN: (libc)Operations on Complex.
|
* crealfNx: (libc)Operations on Complex.
|
* creall: (libc)Operations on Complex.
|
* creat64: (libc)Opening and Closing Files.
|
* creat: (libc)Opening and Closing Files.
|
* crypt: (libc)Passphrase Storage.
|
* crypt_r: (libc)Passphrase Storage.
|
* csin: (libc)Trig Functions.
|
* csinf: (libc)Trig Functions.
|
* csinfN: (libc)Trig Functions.
|
* csinfNx: (libc)Trig Functions.
|
* csinh: (libc)Hyperbolic Functions.
|
* csinhf: (libc)Hyperbolic Functions.
|
* csinhfN: (libc)Hyperbolic Functions.
|
* csinhfNx: (libc)Hyperbolic Functions.
|
* csinhl: (libc)Hyperbolic Functions.
|
* csinl: (libc)Trig Functions.
|
* csqrt: (libc)Exponents and Logarithms.
|
* csqrtf: (libc)Exponents and Logarithms.
|
* csqrtfN: (libc)Exponents and Logarithms.
|
* csqrtfNx: (libc)Exponents and Logarithms.
|
* csqrtl: (libc)Exponents and Logarithms.
|
* ctan: (libc)Trig Functions.
|
* ctanf: (libc)Trig Functions.
|
* ctanfN: (libc)Trig Functions.
|
* ctanfNx: (libc)Trig Functions.
|
* ctanh: (libc)Hyperbolic Functions.
|
* ctanhf: (libc)Hyperbolic Functions.
|
* ctanhfN: (libc)Hyperbolic Functions.
|
* ctanhfNx: (libc)Hyperbolic Functions.
|
* ctanhl: (libc)Hyperbolic Functions.
|
* ctanl: (libc)Trig Functions.
|
* ctermid: (libc)Identifying the Terminal.
|
* ctime: (libc)Formatting Calendar Time.
|
* ctime_r: (libc)Formatting Calendar Time.
|
* cuserid: (libc)Who Logged In.
|
* daddl: (libc)Misc FP Arithmetic.
|
* dcgettext: (libc)Translation with gettext.
|
* dcngettext: (libc)Advanced gettext functions.
|
* ddivl: (libc)Misc FP Arithmetic.
|
* dgettext: (libc)Translation with gettext.
|
* difftime: (libc)Calculating Elapsed Time.
|
* dirfd: (libc)Opening a Directory.
|
* dirname: (libc)Finding Tokens in a String.
|
* div: (libc)Integer Division.
|
* dmull: (libc)Misc FP Arithmetic.
|
* dngettext: (libc)Advanced gettext functions.
|
* drand48: (libc)SVID Random.
|
* drand48_r: (libc)SVID Random.
|
* drem: (libc)Remainder Functions.
|
* dremf: (libc)Remainder Functions.
|
* dreml: (libc)Remainder Functions.
|
* dsubl: (libc)Misc FP Arithmetic.
|
* dup2: (libc)Duplicating Descriptors.
|
* dup: (libc)Duplicating Descriptors.
|
* ecvt: (libc)System V Number Conversion.
|
* ecvt_r: (libc)System V Number Conversion.
|
* endfsent: (libc)fstab.
|
* endgrent: (libc)Scanning All Groups.
|
* endhostent: (libc)Host Names.
|
* endmntent: (libc)mtab.
|
* endnetent: (libc)Networks Database.
|
* endnetgrent: (libc)Lookup Netgroup.
|
* endprotoent: (libc)Protocols Database.
|
* endpwent: (libc)Scanning All Users.
|
* endservent: (libc)Services Database.
|
* endutent: (libc)Manipulating the Database.
|
* endutxent: (libc)XPG Functions.
|
* envz_add: (libc)Envz Functions.
|
* envz_entry: (libc)Envz Functions.
|
* envz_get: (libc)Envz Functions.
|
* envz_merge: (libc)Envz Functions.
|
* envz_remove: (libc)Envz Functions.
|
* envz_strip: (libc)Envz Functions.
|
* erand48: (libc)SVID Random.
|
* erand48_r: (libc)SVID Random.
|
* erf: (libc)Special Functions.
|
* erfc: (libc)Special Functions.
|
* erfcf: (libc)Special Functions.
|
* erfcfN: (libc)Special Functions.
|
* erfcfNx: (libc)Special Functions.
|
* erfcl: (libc)Special Functions.
|
* erff: (libc)Special Functions.
|
* erffN: (libc)Special Functions.
|
* erffNx: (libc)Special Functions.
|
* erfl: (libc)Special Functions.
|
* err: (libc)Error Messages.
|
* errno: (libc)Checking for Errors.
|
* error: (libc)Error Messages.
|
* error_at_line: (libc)Error Messages.
|
* errx: (libc)Error Messages.
|
* execl: (libc)Executing a File.
|
* execle: (libc)Executing a File.
|
* execlp: (libc)Executing a File.
|
* execv: (libc)Executing a File.
|
* execve: (libc)Executing a File.
|
* execvp: (libc)Executing a File.
|
* exit: (libc)Normal Termination.
|
* exp10: (libc)Exponents and Logarithms.
|
* exp10f: (libc)Exponents and Logarithms.
|
* exp10fN: (libc)Exponents and Logarithms.
|
* exp10fNx: (libc)Exponents and Logarithms.
|
* exp10l: (libc)Exponents and Logarithms.
|
* exp2: (libc)Exponents and Logarithms.
|
* exp2f: (libc)Exponents and Logarithms.
|
* exp2fN: (libc)Exponents and Logarithms.
|
* exp2fNx: (libc)Exponents and Logarithms.
|
* exp2l: (libc)Exponents and Logarithms.
|
* exp: (libc)Exponents and Logarithms.
|
* expf: (libc)Exponents and Logarithms.
|
* expfN: (libc)Exponents and Logarithms.
|
* expfNx: (libc)Exponents and Logarithms.
|
* expl: (libc)Exponents and Logarithms.
|
* explicit_bzero: (libc)Erasing Sensitive Data.
|
* expm1: (libc)Exponents and Logarithms.
|
* expm1f: (libc)Exponents and Logarithms.
|
* expm1fN: (libc)Exponents and Logarithms.
|
* expm1fNx: (libc)Exponents and Logarithms.
|
* expm1l: (libc)Exponents and Logarithms.
|
* fMaddfN: (libc)Misc FP Arithmetic.
|
* fMaddfNx: (libc)Misc FP Arithmetic.
|
* fMdivfN: (libc)Misc FP Arithmetic.
|
* fMdivfNx: (libc)Misc FP Arithmetic.
|
* fMmulfN: (libc)Misc FP Arithmetic.
|
* fMmulfNx: (libc)Misc FP Arithmetic.
|
* fMsubfN: (libc)Misc FP Arithmetic.
|
* fMsubfNx: (libc)Misc FP Arithmetic.
|
* fMxaddfN: (libc)Misc FP Arithmetic.
|
* fMxaddfNx: (libc)Misc FP Arithmetic.
|
* fMxdivfN: (libc)Misc FP Arithmetic.
|
* fMxdivfNx: (libc)Misc FP Arithmetic.
|
* fMxmulfN: (libc)Misc FP Arithmetic.
|
* fMxmulfNx: (libc)Misc FP Arithmetic.
|
* fMxsubfN: (libc)Misc FP Arithmetic.
|
* fMxsubfNx: (libc)Misc FP Arithmetic.
|
* fabs: (libc)Absolute Value.
|
* fabsf: (libc)Absolute Value.
|
* fabsfN: (libc)Absolute Value.
|
* fabsfNx: (libc)Absolute Value.
|
* fabsl: (libc)Absolute Value.
|
* fadd: (libc)Misc FP Arithmetic.
|
* faddl: (libc)Misc FP Arithmetic.
|
* fchdir: (libc)Working Directory.
|
* fchmod: (libc)Setting Permissions.
|
* fchown: (libc)File Owner.
|
* fclose: (libc)Closing Streams.
|
* fcloseall: (libc)Closing Streams.
|
* fcntl: (libc)Control Operations.
|
* fcvt: (libc)System V Number Conversion.
|
* fcvt_r: (libc)System V Number Conversion.
|
* fdatasync: (libc)Synchronizing I/O.
|
* fdim: (libc)Misc FP Arithmetic.
|
* fdimf: (libc)Misc FP Arithmetic.
|
* fdimfN: (libc)Misc FP Arithmetic.
|
* fdimfNx: (libc)Misc FP Arithmetic.
|
* fdiml: (libc)Misc FP Arithmetic.
|
* fdiv: (libc)Misc FP Arithmetic.
|
* fdivl: (libc)Misc FP Arithmetic.
|
* fdopen: (libc)Descriptors and Streams.
|
* fdopendir: (libc)Opening a Directory.
|
* feclearexcept: (libc)Status bit operations.
|
* fedisableexcept: (libc)Control Functions.
|
* feenableexcept: (libc)Control Functions.
|
* fegetenv: (libc)Control Functions.
|
* fegetexcept: (libc)Control Functions.
|
* fegetexceptflag: (libc)Status bit operations.
|
* fegetmode: (libc)Control Functions.
|
* fegetround: (libc)Rounding.
|
* feholdexcept: (libc)Control Functions.
|
* feof: (libc)EOF and Errors.
|
* feof_unlocked: (libc)EOF and Errors.
|
* feraiseexcept: (libc)Status bit operations.
|
* ferror: (libc)EOF and Errors.
|
* ferror_unlocked: (libc)EOF and Errors.
|
* fesetenv: (libc)Control Functions.
|
* fesetexcept: (libc)Status bit operations.
|
* fesetexceptflag: (libc)Status bit operations.
|
* fesetmode: (libc)Control Functions.
|
* fesetround: (libc)Rounding.
|
* fetestexcept: (libc)Status bit operations.
|
* fetestexceptflag: (libc)Status bit operations.
|
* feupdateenv: (libc)Control Functions.
|
* fexecve: (libc)Executing a File.
|
* fflush: (libc)Flushing Buffers.
|
* fflush_unlocked: (libc)Flushing Buffers.
|
* fgetc: (libc)Character Input.
|
* fgetc_unlocked: (libc)Character Input.
|
* fgetgrent: (libc)Scanning All Groups.
|
* fgetgrent_r: (libc)Scanning All Groups.
|
* fgetpos64: (libc)Portable Positioning.
|
* fgetpos: (libc)Portable Positioning.
|
* fgetpwent: (libc)Scanning All Users.
|
* fgetpwent_r: (libc)Scanning All Users.
|
* fgets: (libc)Line Input.
|
* fgets_unlocked: (libc)Line Input.
|
* fgetwc: (libc)Character Input.
|
* fgetwc_unlocked: (libc)Character Input.
|
* fgetws: (libc)Line Input.
|
* fgetws_unlocked: (libc)Line Input.
|
* fileno: (libc)Descriptors and Streams.
|
* fileno_unlocked: (libc)Descriptors and Streams.
|
* finite: (libc)Floating Point Classes.
|
* finitef: (libc)Floating Point Classes.
|
* finitel: (libc)Floating Point Classes.
|
* flockfile: (libc)Streams and Threads.
|
* floor: (libc)Rounding Functions.
|
* floorf: (libc)Rounding Functions.
|
* floorfN: (libc)Rounding Functions.
|
* floorfNx: (libc)Rounding Functions.
|
* floorl: (libc)Rounding Functions.
|
* fma: (libc)Misc FP Arithmetic.
|
* fmaf: (libc)Misc FP Arithmetic.
|
* fmafN: (libc)Misc FP Arithmetic.
|
* fmafNx: (libc)Misc FP Arithmetic.
|
* fmal: (libc)Misc FP Arithmetic.
|
* fmax: (libc)Misc FP Arithmetic.
|
* fmaxf: (libc)Misc FP Arithmetic.
|
* fmaxfN: (libc)Misc FP Arithmetic.
|
* fmaxfNx: (libc)Misc FP Arithmetic.
|
* fmaxl: (libc)Misc FP Arithmetic.
|
* fmaxmag: (libc)Misc FP Arithmetic.
|
* fmaxmagf: (libc)Misc FP Arithmetic.
|
* fmaxmagfN: (libc)Misc FP Arithmetic.
|
* fmaxmagfNx: (libc)Misc FP Arithmetic.
|
* fmaxmagl: (libc)Misc FP Arithmetic.
|
* fmemopen: (libc)String Streams.
|
* fmin: (libc)Misc FP Arithmetic.
|
* fminf: (libc)Misc FP Arithmetic.
|
* fminfN: (libc)Misc FP Arithmetic.
|
* fminfNx: (libc)Misc FP Arithmetic.
|
* fminl: (libc)Misc FP Arithmetic.
|
* fminmag: (libc)Misc FP Arithmetic.
|
* fminmagf: (libc)Misc FP Arithmetic.
|
* fminmagfN: (libc)Misc FP Arithmetic.
|
* fminmagfNx: (libc)Misc FP Arithmetic.
|
* fminmagl: (libc)Misc FP Arithmetic.
|
* fmod: (libc)Remainder Functions.
|
* fmodf: (libc)Remainder Functions.
|
* fmodfN: (libc)Remainder Functions.
|
* fmodfNx: (libc)Remainder Functions.
|
* fmodl: (libc)Remainder Functions.
|
* fmtmsg: (libc)Printing Formatted Messages.
|
* fmul: (libc)Misc FP Arithmetic.
|
* fmull: (libc)Misc FP Arithmetic.
|
* fnmatch: (libc)Wildcard Matching.
|
* fopen64: (libc)Opening Streams.
|
* fopen: (libc)Opening Streams.
|
* fopencookie: (libc)Streams and Cookies.
|
* fork: (libc)Creating a Process.
|
* forkpty: (libc)Pseudo-Terminal Pairs.
|
* fpathconf: (libc)Pathconf.
|
* fpclassify: (libc)Floating Point Classes.
|
* fprintf: (libc)Formatted Output Functions.
|
* fputc: (libc)Simple Output.
|
* fputc_unlocked: (libc)Simple Output.
|
* fputs: (libc)Simple Output.
|
* fputs_unlocked: (libc)Simple Output.
|
* fputwc: (libc)Simple Output.
|
* fputwc_unlocked: (libc)Simple Output.
|
* fputws: (libc)Simple Output.
|
* fputws_unlocked: (libc)Simple Output.
|
* fread: (libc)Block Input/Output.
|
* fread_unlocked: (libc)Block Input/Output.
|
* free: (libc)Freeing after Malloc.
|
* freopen64: (libc)Opening Streams.
|
* freopen: (libc)Opening Streams.
|
* frexp: (libc)Normalization Functions.
|
* frexpf: (libc)Normalization Functions.
|
* frexpfN: (libc)Normalization Functions.
|
* frexpfNx: (libc)Normalization Functions.
|
* frexpl: (libc)Normalization Functions.
|
* fromfp: (libc)Rounding Functions.
|
* fromfpf: (libc)Rounding Functions.
|
* fromfpfN: (libc)Rounding Functions.
|
* fromfpfNx: (libc)Rounding Functions.
|
* fromfpl: (libc)Rounding Functions.
|
* fromfpx: (libc)Rounding Functions.
|
* fromfpxf: (libc)Rounding Functions.
|
* fromfpxfN: (libc)Rounding Functions.
|
* fromfpxfNx: (libc)Rounding Functions.
|
* fromfpxl: (libc)Rounding Functions.
|
* fscanf: (libc)Formatted Input Functions.
|
* fseek: (libc)File Positioning.
|
* fseeko64: (libc)File Positioning.
|
* fseeko: (libc)File Positioning.
|
* fsetpos64: (libc)Portable Positioning.
|
* fsetpos: (libc)Portable Positioning.
|
* fstat64: (libc)Reading Attributes.
|
* fstat: (libc)Reading Attributes.
|
* fsub: (libc)Misc FP Arithmetic.
|
* fsubl: (libc)Misc FP Arithmetic.
|
* fsync: (libc)Synchronizing I/O.
|
* ftell: (libc)File Positioning.
|
* ftello64: (libc)File Positioning.
|
* ftello: (libc)File Positioning.
|
* ftruncate64: (libc)File Size.
|
* ftruncate: (libc)File Size.
|
* ftrylockfile: (libc)Streams and Threads.
|
* ftw64: (libc)Working with Directory Trees.
|
* ftw: (libc)Working with Directory Trees.
|
* funlockfile: (libc)Streams and Threads.
|
* futimes: (libc)File Times.
|
* fwide: (libc)Streams and I18N.
|
* fwprintf: (libc)Formatted Output Functions.
|
* fwrite: (libc)Block Input/Output.
|
* fwrite_unlocked: (libc)Block Input/Output.
|
* fwscanf: (libc)Formatted Input Functions.
|
* gamma: (libc)Special Functions.
|
* gammaf: (libc)Special Functions.
|
* gammal: (libc)Special Functions.
|
* gcvt: (libc)System V Number Conversion.
|
* get_avphys_pages: (libc)Query Memory Parameters.
|
* get_current_dir_name: (libc)Working Directory.
|
* get_nprocs: (libc)Processor Resources.
|
* get_nprocs_conf: (libc)Processor Resources.
|
* get_phys_pages: (libc)Query Memory Parameters.
|
* getauxval: (libc)Auxiliary Vector.
|
* getc: (libc)Character Input.
|
* getc_unlocked: (libc)Character Input.
|
* getchar: (libc)Character Input.
|
* getchar_unlocked: (libc)Character Input.
|
* getcontext: (libc)System V contexts.
|
* getcpu: (libc)CPU Affinity.
|
* getcwd: (libc)Working Directory.
|
* getdate: (libc)General Time String Parsing.
|
* getdate_r: (libc)General Time String Parsing.
|
* getdelim: (libc)Line Input.
|
* getdents64: (libc)Low-level Directory Access.
|
* getdomainnname: (libc)Host Identification.
|
* getegid: (libc)Reading Persona.
|
* getentropy: (libc)Unpredictable Bytes.
|
* getenv: (libc)Environment Access.
|
* geteuid: (libc)Reading Persona.
|
* getfsent: (libc)fstab.
|
* getfsfile: (libc)fstab.
|
* getfsspec: (libc)fstab.
|
* getgid: (libc)Reading Persona.
|
* getgrent: (libc)Scanning All Groups.
|
* getgrent_r: (libc)Scanning All Groups.
|
* getgrgid: (libc)Lookup Group.
|
* getgrgid_r: (libc)Lookup Group.
|
* getgrnam: (libc)Lookup Group.
|
* getgrnam_r: (libc)Lookup Group.
|
* getgrouplist: (libc)Setting Groups.
|
* getgroups: (libc)Reading Persona.
|
* gethostbyaddr: (libc)Host Names.
|
* gethostbyaddr_r: (libc)Host Names.
|
* gethostbyname2: (libc)Host Names.
|
* gethostbyname2_r: (libc)Host Names.
|
* gethostbyname: (libc)Host Names.
|
* gethostbyname_r: (libc)Host Names.
|
* gethostent: (libc)Host Names.
|
* gethostid: (libc)Host Identification.
|
* gethostname: (libc)Host Identification.
|
* getitimer: (libc)Setting an Alarm.
|
* getline: (libc)Line Input.
|
* getloadavg: (libc)Processor Resources.
|
* getlogin: (libc)Who Logged In.
|
* getmntent: (libc)mtab.
|
* getmntent_r: (libc)mtab.
|
* getnetbyaddr: (libc)Networks Database.
|
* getnetbyname: (libc)Networks Database.
|
* getnetent: (libc)Networks Database.
|
* getnetgrent: (libc)Lookup Netgroup.
|
* getnetgrent_r: (libc)Lookup Netgroup.
|
* getopt: (libc)Using Getopt.
|
* getopt_long: (libc)Getopt Long Options.
|
* getopt_long_only: (libc)Getopt Long Options.
|
* getpagesize: (libc)Query Memory Parameters.
|
* getpass: (libc)getpass.
|
* getpayload: (libc)FP Bit Twiddling.
|
* getpayloadf: (libc)FP Bit Twiddling.
|
* getpayloadfN: (libc)FP Bit Twiddling.
|
* getpayloadfNx: (libc)FP Bit Twiddling.
|
* getpayloadl: (libc)FP Bit Twiddling.
|
* getpeername: (libc)Who is Connected.
|
* getpgid: (libc)Process Group Functions.
|
* getpgrp: (libc)Process Group Functions.
|
* getpid: (libc)Process Identification.
|
* getppid: (libc)Process Identification.
|
* getpriority: (libc)Traditional Scheduling Functions.
|
* getprotobyname: (libc)Protocols Database.
|
* getprotobynumber: (libc)Protocols Database.
|
* getprotoent: (libc)Protocols Database.
|
* getpt: (libc)Allocation.
|
* getpwent: (libc)Scanning All Users.
|
* getpwent_r: (libc)Scanning All Users.
|
* getpwnam: (libc)Lookup User.
|
* getpwnam_r: (libc)Lookup User.
|
* getpwuid: (libc)Lookup User.
|
* getpwuid_r: (libc)Lookup User.
|
* getrandom: (libc)Unpredictable Bytes.
|
* getrlimit64: (libc)Limits on Resources.
|
* getrlimit: (libc)Limits on Resources.
|
* getrusage: (libc)Resource Usage.
|
* gets: (libc)Line Input.
|
* getservbyname: (libc)Services Database.
|
* getservbyport: (libc)Services Database.
|
* getservent: (libc)Services Database.
|
* getsid: (libc)Process Group Functions.
|
* getsockname: (libc)Reading Address.
|
* getsockopt: (libc)Socket Option Functions.
|
* getsubopt: (libc)Suboptions.
|
* gettext: (libc)Translation with gettext.
|
* gettid: (libc)Process Identification.
|
* gettimeofday: (libc)Getting the Time.
|
* getuid: (libc)Reading Persona.
|
* getumask: (libc)Setting Permissions.
|
* getutent: (libc)Manipulating the Database.
|
* getutent_r: (libc)Manipulating the Database.
|
* getutid: (libc)Manipulating the Database.
|
* getutid_r: (libc)Manipulating the Database.
|
* getutline: (libc)Manipulating the Database.
|
* getutline_r: (libc)Manipulating the Database.
|
* getutmp: (libc)XPG Functions.
|
* getutmpx: (libc)XPG Functions.
|
* getutxent: (libc)XPG Functions.
|
* getutxid: (libc)XPG Functions.
|
* getutxline: (libc)XPG Functions.
|
* getw: (libc)Character Input.
|
* getwc: (libc)Character Input.
|
* getwc_unlocked: (libc)Character Input.
|
* getwchar: (libc)Character Input.
|
* getwchar_unlocked: (libc)Character Input.
|
* getwd: (libc)Working Directory.
|
* glob64: (libc)Calling Glob.
|
* glob: (libc)Calling Glob.
|
* globfree64: (libc)More Flags for Globbing.
|
* globfree: (libc)More Flags for Globbing.
|
* gmtime: (libc)Broken-down Time.
|
* gmtime_r: (libc)Broken-down Time.
|
* grantpt: (libc)Allocation.
|
* gsignal: (libc)Signaling Yourself.
|
* gtty: (libc)BSD Terminal Modes.
|
* hasmntopt: (libc)mtab.
|
* hcreate: (libc)Hash Search Function.
|
* hcreate_r: (libc)Hash Search Function.
|
* hdestroy: (libc)Hash Search Function.
|
* hdestroy_r: (libc)Hash Search Function.
|
* hsearch: (libc)Hash Search Function.
|
* hsearch_r: (libc)Hash Search Function.
|
* htonl: (libc)Byte Order.
|
* htons: (libc)Byte Order.
|
* hypot: (libc)Exponents and Logarithms.
|
* hypotf: (libc)Exponents and Logarithms.
|
* hypotfN: (libc)Exponents and Logarithms.
|
* hypotfNx: (libc)Exponents and Logarithms.
|
* hypotl: (libc)Exponents and Logarithms.
|
* iconv: (libc)Generic Conversion Interface.
|
* iconv_close: (libc)Generic Conversion Interface.
|
* iconv_open: (libc)Generic Conversion Interface.
|
* if_freenameindex: (libc)Interface Naming.
|
* if_indextoname: (libc)Interface Naming.
|
* if_nameindex: (libc)Interface Naming.
|
* if_nametoindex: (libc)Interface Naming.
|
* ilogb: (libc)Exponents and Logarithms.
|
* ilogbf: (libc)Exponents and Logarithms.
|
* ilogbfN: (libc)Exponents and Logarithms.
|
* ilogbfNx: (libc)Exponents and Logarithms.
|
* ilogbl: (libc)Exponents and Logarithms.
|
* imaxabs: (libc)Absolute Value.
|
* imaxdiv: (libc)Integer Division.
|
* in6addr_any: (libc)Host Address Data Type.
|
* in6addr_loopback: (libc)Host Address Data Type.
|
* index: (libc)Search Functions.
|
* inet_addr: (libc)Host Address Functions.
|
* inet_aton: (libc)Host Address Functions.
|
* inet_lnaof: (libc)Host Address Functions.
|
* inet_makeaddr: (libc)Host Address Functions.
|
* inet_netof: (libc)Host Address Functions.
|
* inet_network: (libc)Host Address Functions.
|
* inet_ntoa: (libc)Host Address Functions.
|
* inet_ntop: (libc)Host Address Functions.
|
* inet_pton: (libc)Host Address Functions.
|
* initgroups: (libc)Setting Groups.
|
* initstate: (libc)BSD Random.
|
* initstate_r: (libc)BSD Random.
|
* innetgr: (libc)Netgroup Membership.
|
* ioctl: (libc)IOCTLs.
|
* isalnum: (libc)Classification of Characters.
|
* isalpha: (libc)Classification of Characters.
|
* isascii: (libc)Classification of Characters.
|
* isatty: (libc)Is It a Terminal.
|
* isblank: (libc)Classification of Characters.
|
* iscanonical: (libc)Floating Point Classes.
|
* iscntrl: (libc)Classification of Characters.
|
* isdigit: (libc)Classification of Characters.
|
* iseqsig: (libc)FP Comparison Functions.
|
* isfinite: (libc)Floating Point Classes.
|
* isgraph: (libc)Classification of Characters.
|
* isgreater: (libc)FP Comparison Functions.
|
* isgreaterequal: (libc)FP Comparison Functions.
|
* isinf: (libc)Floating Point Classes.
|
* isinff: (libc)Floating Point Classes.
|
* isinfl: (libc)Floating Point Classes.
|
* isless: (libc)FP Comparison Functions.
|
* islessequal: (libc)FP Comparison Functions.
|
* islessgreater: (libc)FP Comparison Functions.
|
* islower: (libc)Classification of Characters.
|
* isnan: (libc)Floating Point Classes.
|
* isnan: (libc)Floating Point Classes.
|
* isnanf: (libc)Floating Point Classes.
|
* isnanl: (libc)Floating Point Classes.
|
* isnormal: (libc)Floating Point Classes.
|
* isprint: (libc)Classification of Characters.
|
* ispunct: (libc)Classification of Characters.
|
* issignaling: (libc)Floating Point Classes.
|
* isspace: (libc)Classification of Characters.
|
* issubnormal: (libc)Floating Point Classes.
|
* isunordered: (libc)FP Comparison Functions.
|
* isupper: (libc)Classification of Characters.
|
* iswalnum: (libc)Classification of Wide Characters.
|
* iswalpha: (libc)Classification of Wide Characters.
|
* iswblank: (libc)Classification of Wide Characters.
|
* iswcntrl: (libc)Classification of Wide Characters.
|
* iswctype: (libc)Classification of Wide Characters.
|
* iswdigit: (libc)Classification of Wide Characters.
|
* iswgraph: (libc)Classification of Wide Characters.
|
* iswlower: (libc)Classification of Wide Characters.
|
* iswprint: (libc)Classification of Wide Characters.
|
* iswpunct: (libc)Classification of Wide Characters.
|
* iswspace: (libc)Classification of Wide Characters.
|
* iswupper: (libc)Classification of Wide Characters.
|
* iswxdigit: (libc)Classification of Wide Characters.
|
* isxdigit: (libc)Classification of Characters.
|
* iszero: (libc)Floating Point Classes.
|
* j0: (libc)Special Functions.
|
* j0f: (libc)Special Functions.
|
* j0fN: (libc)Special Functions.
|
* j0fNx: (libc)Special Functions.
|
* j0l: (libc)Special Functions.
|
* j1: (libc)Special Functions.
|
* j1f: (libc)Special Functions.
|
* j1fN: (libc)Special Functions.
|
* j1fNx: (libc)Special Functions.
|
* j1l: (libc)Special Functions.
|
* jn: (libc)Special Functions.
|
* jnf: (libc)Special Functions.
|
* jnfN: (libc)Special Functions.
|
* jnfNx: (libc)Special Functions.
|
* jnl: (libc)Special Functions.
|
* jrand48: (libc)SVID Random.
|
* jrand48_r: (libc)SVID Random.
|
* kill: (libc)Signaling Another Process.
|
* killpg: (libc)Signaling Another Process.
|
* l64a: (libc)Encode Binary Data.
|
* labs: (libc)Absolute Value.
|
* lcong48: (libc)SVID Random.
|
* lcong48_r: (libc)SVID Random.
|
* ldexp: (libc)Normalization Functions.
|
* ldexpf: (libc)Normalization Functions.
|
* ldexpfN: (libc)Normalization Functions.
|
* ldexpfNx: (libc)Normalization Functions.
|
* ldexpl: (libc)Normalization Functions.
|
* ldiv: (libc)Integer Division.
|
* lfind: (libc)Array Search Function.
|
* lgamma: (libc)Special Functions.
|
* lgamma_r: (libc)Special Functions.
|
* lgammaf: (libc)Special Functions.
|
* lgammafN: (libc)Special Functions.
|
* lgammafN_r: (libc)Special Functions.
|
* lgammafNx: (libc)Special Functions.
|
* lgammafNx_r: (libc)Special Functions.
|
* lgammaf_r: (libc)Special Functions.
|
* lgammal: (libc)Special Functions.
|
* lgammal_r: (libc)Special Functions.
|
* link: (libc)Hard Links.
|
* linkat: (libc)Hard Links.
|
* lio_listio64: (libc)Asynchronous Reads/Writes.
|
* lio_listio: (libc)Asynchronous Reads/Writes.
|
* listen: (libc)Listening.
|
* llabs: (libc)Absolute Value.
|
* lldiv: (libc)Integer Division.
|
* llogb: (libc)Exponents and Logarithms.
|
* llogbf: (libc)Exponents and Logarithms.
|
* llogbfN: (libc)Exponents and Logarithms.
|
* llogbfNx: (libc)Exponents and Logarithms.
|
* llogbl: (libc)Exponents and Logarithms.
|
* llrint: (libc)Rounding Functions.
|
* llrintf: (libc)Rounding Functions.
|
* llrintfN: (libc)Rounding Functions.
|
* llrintfNx: (libc)Rounding Functions.
|
* llrintl: (libc)Rounding Functions.
|
* llround: (libc)Rounding Functions.
|
* llroundf: (libc)Rounding Functions.
|
* llroundfN: (libc)Rounding Functions.
|
* llroundfNx: (libc)Rounding Functions.
|
* llroundl: (libc)Rounding Functions.
|
* localeconv: (libc)The Lame Way to Locale Data.
|
* localtime: (libc)Broken-down Time.
|
* localtime_r: (libc)Broken-down Time.
|
* log10: (libc)Exponents and Logarithms.
|
* log10f: (libc)Exponents and Logarithms.
|
* log10fN: (libc)Exponents and Logarithms.
|
* log10fNx: (libc)Exponents and Logarithms.
|
* log10l: (libc)Exponents and Logarithms.
|
* log1p: (libc)Exponents and Logarithms.
|
* log1pf: (libc)Exponents and Logarithms.
|
* log1pfN: (libc)Exponents and Logarithms.
|
* log1pfNx: (libc)Exponents and Logarithms.
|
* log1pl: (libc)Exponents and Logarithms.
|
* log2: (libc)Exponents and Logarithms.
|
* log2f: (libc)Exponents and Logarithms.
|
* log2fN: (libc)Exponents and Logarithms.
|
* log2fNx: (libc)Exponents and Logarithms.
|
* log2l: (libc)Exponents and Logarithms.
|
* log: (libc)Exponents and Logarithms.
|
* logb: (libc)Exponents and Logarithms.
|
* logbf: (libc)Exponents and Logarithms.
|
* logbfN: (libc)Exponents and Logarithms.
|
* logbfNx: (libc)Exponents and Logarithms.
|
* logbl: (libc)Exponents and Logarithms.
|
* logf: (libc)Exponents and Logarithms.
|
* logfN: (libc)Exponents and Logarithms.
|
* logfNx: (libc)Exponents and Logarithms.
|
* login: (libc)Logging In and Out.
|
* login_tty: (libc)Logging In and Out.
|
* logl: (libc)Exponents and Logarithms.
|
* logout: (libc)Logging In and Out.
|
* logwtmp: (libc)Logging In and Out.
|
* longjmp: (libc)Non-Local Details.
|
* lrand48: (libc)SVID Random.
|
* lrand48_r: (libc)SVID Random.
|
* lrint: (libc)Rounding Functions.
|
* lrintf: (libc)Rounding Functions.
|
* lrintfN: (libc)Rounding Functions.
|
* lrintfNx: (libc)Rounding Functions.
|
* lrintl: (libc)Rounding Functions.
|
* lround: (libc)Rounding Functions.
|
* lroundf: (libc)Rounding Functions.
|
* lroundfN: (libc)Rounding Functions.
|
* lroundfNx: (libc)Rounding Functions.
|
* lroundl: (libc)Rounding Functions.
|
* lsearch: (libc)Array Search Function.
|
* lseek64: (libc)File Position Primitive.
|
* lseek: (libc)File Position Primitive.
|
* lstat64: (libc)Reading Attributes.
|
* lstat: (libc)Reading Attributes.
|
* lutimes: (libc)File Times.
|
* madvise: (libc)Memory-mapped I/O.
|
* makecontext: (libc)System V contexts.
|
* mallinfo2: (libc)Statistics of Malloc.
|
* malloc: (libc)Basic Allocation.
|
* mallopt: (libc)Malloc Tunable Parameters.
|
* mblen: (libc)Non-reentrant Character Conversion.
|
* mbrlen: (libc)Converting a Character.
|
* mbrtowc: (libc)Converting a Character.
|
* mbsinit: (libc)Keeping the state.
|
* mbsnrtowcs: (libc)Converting Strings.
|
* mbsrtowcs: (libc)Converting Strings.
|
* mbstowcs: (libc)Non-reentrant String Conversion.
|
* mbtowc: (libc)Non-reentrant Character Conversion.
|
* mcheck: (libc)Heap Consistency Checking.
|
* memalign: (libc)Aligned Memory Blocks.
|
* memccpy: (libc)Copying Strings and Arrays.
|
* memchr: (libc)Search Functions.
|
* memcmp: (libc)String/Array Comparison.
|
* memcpy: (libc)Copying Strings and Arrays.
|
* memfd_create: (libc)Memory-mapped I/O.
|
* memfrob: (libc)Obfuscating Data.
|
* memmem: (libc)Search Functions.
|
* memmove: (libc)Copying Strings and Arrays.
|
* mempcpy: (libc)Copying Strings and Arrays.
|
* memrchr: (libc)Search Functions.
|
* memset: (libc)Copying Strings and Arrays.
|
* mkdir: (libc)Creating Directories.
|
* mkdtemp: (libc)Temporary Files.
|
* mkfifo: (libc)FIFO Special Files.
|
* mknod: (libc)Making Special Files.
|
* mkstemp: (libc)Temporary Files.
|
* mktemp: (libc)Temporary Files.
|
* mktime: (libc)Broken-down Time.
|
* mlock2: (libc)Page Lock Functions.
|
* mlock: (libc)Page Lock Functions.
|
* mlockall: (libc)Page Lock Functions.
|
* mmap64: (libc)Memory-mapped I/O.
|
* mmap: (libc)Memory-mapped I/O.
|
* modf: (libc)Rounding Functions.
|
* modff: (libc)Rounding Functions.
|
* modffN: (libc)Rounding Functions.
|
* modffNx: (libc)Rounding Functions.
|
* modfl: (libc)Rounding Functions.
|
* mount: (libc)Mount-Unmount-Remount.
|
* mprobe: (libc)Heap Consistency Checking.
|
* mprotect: (libc)Memory Protection.
|
* mrand48: (libc)SVID Random.
|
* mrand48_r: (libc)SVID Random.
|
* mremap: (libc)Memory-mapped I/O.
|
* msync: (libc)Memory-mapped I/O.
|
* mtrace: (libc)Tracing malloc.
|
* mtx_destroy: (libc)ISO C Mutexes.
|
* mtx_init: (libc)ISO C Mutexes.
|
* mtx_lock: (libc)ISO C Mutexes.
|
* mtx_timedlock: (libc)ISO C Mutexes.
|
* mtx_trylock: (libc)ISO C Mutexes.
|
* mtx_unlock: (libc)ISO C Mutexes.
|
* munlock: (libc)Page Lock Functions.
|
* munlockall: (libc)Page Lock Functions.
|
* munmap: (libc)Memory-mapped I/O.
|
* muntrace: (libc)Tracing malloc.
|
* nan: (libc)FP Bit Twiddling.
|
* nanf: (libc)FP Bit Twiddling.
|
* nanfN: (libc)FP Bit Twiddling.
|
* nanfNx: (libc)FP Bit Twiddling.
|
* nanl: (libc)FP Bit Twiddling.
|
* nanosleep: (libc)Sleeping.
|
* nearbyint: (libc)Rounding Functions.
|
* nearbyintf: (libc)Rounding Functions.
|
* nearbyintfN: (libc)Rounding Functions.
|
* nearbyintfNx: (libc)Rounding Functions.
|
* nearbyintl: (libc)Rounding Functions.
|
* nextafter: (libc)FP Bit Twiddling.
|
* nextafterf: (libc)FP Bit Twiddling.
|
* nextafterfN: (libc)FP Bit Twiddling.
|
* nextafterfNx: (libc)FP Bit Twiddling.
|
* nextafterl: (libc)FP Bit Twiddling.
|
* nextdown: (libc)FP Bit Twiddling.
|
* nextdownf: (libc)FP Bit Twiddling.
|
* nextdownfN: (libc)FP Bit Twiddling.
|
* nextdownfNx: (libc)FP Bit Twiddling.
|
* nextdownl: (libc)FP Bit Twiddling.
|
* nexttoward: (libc)FP Bit Twiddling.
|
* nexttowardf: (libc)FP Bit Twiddling.
|
* nexttowardl: (libc)FP Bit Twiddling.
|
* nextup: (libc)FP Bit Twiddling.
|
* nextupf: (libc)FP Bit Twiddling.
|
* nextupfN: (libc)FP Bit Twiddling.
|
* nextupfNx: (libc)FP Bit Twiddling.
|
* nextupl: (libc)FP Bit Twiddling.
|
* nftw64: (libc)Working with Directory Trees.
|
* nftw: (libc)Working with Directory Trees.
|
* ngettext: (libc)Advanced gettext functions.
|
* nice: (libc)Traditional Scheduling Functions.
|
* nl_langinfo: (libc)The Elegant and Fast Way.
|
* nrand48: (libc)SVID Random.
|
* nrand48_r: (libc)SVID Random.
|
* ntohl: (libc)Byte Order.
|
* ntohs: (libc)Byte Order.
|
* ntp_adjtime: (libc)Setting and Adjusting the Time.
|
* ntp_gettime: (libc)Setting and Adjusting the Time.
|
* obstack_1grow: (libc)Growing Objects.
|
* obstack_1grow_fast: (libc)Extra Fast Growing.
|
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
|
* obstack_alloc: (libc)Allocation in an Obstack.
|
* obstack_base: (libc)Status of an Obstack.
|
* obstack_blank: (libc)Growing Objects.
|
* obstack_blank_fast: (libc)Extra Fast Growing.
|
* obstack_chunk_size: (libc)Obstack Chunks.
|
* obstack_copy0: (libc)Allocation in an Obstack.
|
* obstack_copy: (libc)Allocation in an Obstack.
|
* obstack_finish: (libc)Growing Objects.
|
* obstack_free: (libc)Freeing Obstack Objects.
|
* obstack_grow0: (libc)Growing Objects.
|
* obstack_grow: (libc)Growing Objects.
|
* obstack_init: (libc)Preparing for Obstacks.
|
* obstack_int_grow: (libc)Growing Objects.
|
* obstack_int_grow_fast: (libc)Extra Fast Growing.
|
* obstack_next_free: (libc)Status of an Obstack.
|
* obstack_object_size: (libc)Growing Objects.
|
* obstack_object_size: (libc)Status of an Obstack.
|
* obstack_printf: (libc)Dynamic Output.
|
* obstack_ptr_grow: (libc)Growing Objects.
|
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
|
* obstack_room: (libc)Extra Fast Growing.
|
* obstack_vprintf: (libc)Variable Arguments Output.
|
* offsetof: (libc)Structure Measurement.
|
* on_exit: (libc)Cleanups on Exit.
|
* open64: (libc)Opening and Closing Files.
|
* open: (libc)Opening and Closing Files.
|
* open_memstream: (libc)String Streams.
|
* opendir: (libc)Opening a Directory.
|
* openlog: (libc)openlog.
|
* openpty: (libc)Pseudo-Terminal Pairs.
|
* parse_printf_format: (libc)Parsing a Template String.
|
* pathconf: (libc)Pathconf.
|
* pause: (libc)Using Pause.
|
* pclose: (libc)Pipe to a Subprocess.
|
* perror: (libc)Error Messages.
|
* pipe: (libc)Creating a Pipe.
|
* pkey_alloc: (libc)Memory Protection.
|
* pkey_free: (libc)Memory Protection.
|
* pkey_get: (libc)Memory Protection.
|
* pkey_mprotect: (libc)Memory Protection.
|
* pkey_set: (libc)Memory Protection.
|
* popen: (libc)Pipe to a Subprocess.
|
* posix_fallocate64: (libc)Storage Allocation.
|
* posix_fallocate: (libc)Storage Allocation.
|
* posix_memalign: (libc)Aligned Memory Blocks.
|
* pow: (libc)Exponents and Logarithms.
|
* powf: (libc)Exponents and Logarithms.
|
* powfN: (libc)Exponents and Logarithms.
|
* powfNx: (libc)Exponents and Logarithms.
|
* powl: (libc)Exponents and Logarithms.
|
* pread64: (libc)I/O Primitives.
|
* pread: (libc)I/O Primitives.
|
* preadv2: (libc)Scatter-Gather.
|
* preadv64: (libc)Scatter-Gather.
|
* preadv64v2: (libc)Scatter-Gather.
|
* preadv: (libc)Scatter-Gather.
|
* printf: (libc)Formatted Output Functions.
|
* printf_size: (libc)Predefined Printf Handlers.
|
* printf_size_info: (libc)Predefined Printf Handlers.
|
* psignal: (libc)Signal Messages.
|
* pthread_attr_getsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_attr_setsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_clockjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_cond_clockwait: (libc)Waiting with Explicit Clocks.
|
* pthread_getattr_default_np: (libc)Default Thread Attributes.
|
* pthread_getspecific: (libc)Thread-specific Data.
|
* pthread_key_create: (libc)Thread-specific Data.
|
* pthread_key_delete: (libc)Thread-specific Data.
|
* pthread_rwlock_clockrdlock: (libc)Waiting with Explicit Clocks.
|
* pthread_rwlock_clockwrlock: (libc)Waiting with Explicit Clocks.
|
* pthread_setattr_default_np: (libc)Default Thread Attributes.
|
* pthread_setspecific: (libc)Thread-specific Data.
|
* pthread_timedjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_tryjoin_np: (libc)Waiting with Explicit Clocks.
|
* ptsname: (libc)Allocation.
|
* ptsname_r: (libc)Allocation.
|
* putc: (libc)Simple Output.
|
* putc_unlocked: (libc)Simple Output.
|
* putchar: (libc)Simple Output.
|
* putchar_unlocked: (libc)Simple Output.
|
* putenv: (libc)Environment Access.
|
* putpwent: (libc)Writing a User Entry.
|
* puts: (libc)Simple Output.
|
* pututline: (libc)Manipulating the Database.
|
* pututxline: (libc)XPG Functions.
|
* putw: (libc)Simple Output.
|
* putwc: (libc)Simple Output.
|
* putwc_unlocked: (libc)Simple Output.
|
* putwchar: (libc)Simple Output.
|
* putwchar_unlocked: (libc)Simple Output.
|
* pwrite64: (libc)I/O Primitives.
|
* pwrite: (libc)I/O Primitives.
|
* pwritev2: (libc)Scatter-Gather.
|
* pwritev64: (libc)Scatter-Gather.
|
* pwritev64v2: (libc)Scatter-Gather.
|
* pwritev: (libc)Scatter-Gather.
|
* qecvt: (libc)System V Number Conversion.
|
* qecvt_r: (libc)System V Number Conversion.
|
* qfcvt: (libc)System V Number Conversion.
|
* qfcvt_r: (libc)System V Number Conversion.
|
* qgcvt: (libc)System V Number Conversion.
|
* qsort: (libc)Array Sort Function.
|
* raise: (libc)Signaling Yourself.
|
* rand: (libc)ISO Random.
|
* rand_r: (libc)ISO Random.
|
* random: (libc)BSD Random.
|
* random_r: (libc)BSD Random.
|
* rawmemchr: (libc)Search Functions.
|
* read: (libc)I/O Primitives.
|
* readdir64: (libc)Reading/Closing Directory.
|
* readdir64_r: (libc)Reading/Closing Directory.
|
* readdir: (libc)Reading/Closing Directory.
|
* readdir_r: (libc)Reading/Closing Directory.
|
* readlink: (libc)Symbolic Links.
|
* readv: (libc)Scatter-Gather.
|
* realloc: (libc)Changing Block Size.
|
* reallocarray: (libc)Changing Block Size.
|
* realpath: (libc)Symbolic Links.
|
* recv: (libc)Receiving Data.
|
* recvfrom: (libc)Receiving Datagrams.
|
* recvmsg: (libc)Receiving Datagrams.
|
* regcomp: (libc)POSIX Regexp Compilation.
|
* regerror: (libc)Regexp Cleanup.
|
* regexec: (libc)Matching POSIX Regexps.
|
* regfree: (libc)Regexp Cleanup.
|
* register_printf_function: (libc)Registering New Conversions.
|
* remainder: (libc)Remainder Functions.
|
* remainderf: (libc)Remainder Functions.
|
* remainderfN: (libc)Remainder Functions.
|
* remainderfNx: (libc)Remainder Functions.
|
* remainderl: (libc)Remainder Functions.
|
* remove: (libc)Deleting Files.
|
* rename: (libc)Renaming Files.
|
* rewind: (libc)File Positioning.
|
* rewinddir: (libc)Random Access Directory.
|
* rindex: (libc)Search Functions.
|
* rint: (libc)Rounding Functions.
|
* rintf: (libc)Rounding Functions.
|
* rintfN: (libc)Rounding Functions.
|
* rintfNx: (libc)Rounding Functions.
|
* rintl: (libc)Rounding Functions.
|
* rmdir: (libc)Deleting Files.
|
* round: (libc)Rounding Functions.
|
* roundeven: (libc)Rounding Functions.
|
* roundevenf: (libc)Rounding Functions.
|
* roundevenfN: (libc)Rounding Functions.
|
* roundevenfNx: (libc)Rounding Functions.
|
* roundevenl: (libc)Rounding Functions.
|
* roundf: (libc)Rounding Functions.
|
* roundfN: (libc)Rounding Functions.
|
* roundfNx: (libc)Rounding Functions.
|
* roundl: (libc)Rounding Functions.
|
* rpmatch: (libc)Yes-or-No Questions.
|
* sbrk: (libc)Resizing the Data Segment.
|
* scalb: (libc)Normalization Functions.
|
* scalbf: (libc)Normalization Functions.
|
* scalbl: (libc)Normalization Functions.
|
* scalbln: (libc)Normalization Functions.
|
* scalblnf: (libc)Normalization Functions.
|
* scalblnfN: (libc)Normalization Functions.
|
* scalblnfNx: (libc)Normalization Functions.
|
* scalblnl: (libc)Normalization Functions.
|
* scalbn: (libc)Normalization Functions.
|
* scalbnf: (libc)Normalization Functions.
|
* scalbnfN: (libc)Normalization Functions.
|
* scalbnfNx: (libc)Normalization Functions.
|
* scalbnl: (libc)Normalization Functions.
|
* scandir64: (libc)Scanning Directory Content.
|
* scandir: (libc)Scanning Directory Content.
|
* scanf: (libc)Formatted Input Functions.
|
* sched_get_priority_max: (libc)Basic Scheduling Functions.
|
* sched_get_priority_min: (libc)Basic Scheduling Functions.
|
* sched_getaffinity: (libc)CPU Affinity.
|
* sched_getparam: (libc)Basic Scheduling Functions.
|
* sched_getscheduler: (libc)Basic Scheduling Functions.
|
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
|
* sched_setaffinity: (libc)CPU Affinity.
|
* sched_setparam: (libc)Basic Scheduling Functions.
|
* sched_setscheduler: (libc)Basic Scheduling Functions.
|
* sched_yield: (libc)Basic Scheduling Functions.
|
* secure_getenv: (libc)Environment Access.
|
* seed48: (libc)SVID Random.
|
* seed48_r: (libc)SVID Random.
|
* seekdir: (libc)Random Access Directory.
|
* select: (libc)Waiting for I/O.
|
* sem_clockwait: (libc)Waiting with Explicit Clocks.
|
* sem_close: (libc)Semaphores.
|
* sem_destroy: (libc)Semaphores.
|
* sem_getvalue: (libc)Semaphores.
|
* sem_init: (libc)Semaphores.
|
* sem_open: (libc)Semaphores.
|
* sem_post: (libc)Semaphores.
|
* sem_timedwait: (libc)Semaphores.
|
* sem_trywait: (libc)Semaphores.
|
* sem_unlink: (libc)Semaphores.
|
* sem_wait: (libc)Semaphores.
|
* semctl: (libc)Semaphores.
|
* semget: (libc)Semaphores.
|
* semop: (libc)Semaphores.
|
* semtimedop: (libc)Semaphores.
|
* send: (libc)Sending Data.
|
* sendmsg: (libc)Receiving Datagrams.
|
* sendto: (libc)Sending Datagrams.
|
* setbuf: (libc)Controlling Buffering.
|
* setbuffer: (libc)Controlling Buffering.
|
* setcontext: (libc)System V contexts.
|
* setdomainname: (libc)Host Identification.
|
* setegid: (libc)Setting Groups.
|
* setenv: (libc)Environment Access.
|
* seteuid: (libc)Setting User ID.
|
* setfsent: (libc)fstab.
|
* setgid: (libc)Setting Groups.
|
* setgrent: (libc)Scanning All Groups.
|
* setgroups: (libc)Setting Groups.
|
* sethostent: (libc)Host Names.
|
* sethostid: (libc)Host Identification.
|
* sethostname: (libc)Host Identification.
|
* setitimer: (libc)Setting an Alarm.
|
* setjmp: (libc)Non-Local Details.
|
* setlinebuf: (libc)Controlling Buffering.
|
* setlocale: (libc)Setting the Locale.
|
* setlogmask: (libc)setlogmask.
|
* setmntent: (libc)mtab.
|
* setnetent: (libc)Networks Database.
|
* setnetgrent: (libc)Lookup Netgroup.
|
* setpayload: (libc)FP Bit Twiddling.
|
* setpayloadf: (libc)FP Bit Twiddling.
|
* setpayloadfN: (libc)FP Bit Twiddling.
|
* setpayloadfNx: (libc)FP Bit Twiddling.
|
* setpayloadl: (libc)FP Bit Twiddling.
|
* setpayloadsig: (libc)FP Bit Twiddling.
|
* setpayloadsigf: (libc)FP Bit Twiddling.
|
* setpayloadsigfN: (libc)FP Bit Twiddling.
|
* setpayloadsigfNx: (libc)FP Bit Twiddling.
|
* setpayloadsigl: (libc)FP Bit Twiddling.
|
* setpgid: (libc)Process Group Functions.
|
* setpgrp: (libc)Process Group Functions.
|
* setpriority: (libc)Traditional Scheduling Functions.
|
* setprotoent: (libc)Protocols Database.
|
* setpwent: (libc)Scanning All Users.
|
* setregid: (libc)Setting Groups.
|
* setreuid: (libc)Setting User ID.
|
* setrlimit64: (libc)Limits on Resources.
|
* setrlimit: (libc)Limits on Resources.
|
* setservent: (libc)Services Database.
|
* setsid: (libc)Process Group Functions.
|
* setsockopt: (libc)Socket Option Functions.
|
* setstate: (libc)BSD Random.
|
* setstate_r: (libc)BSD Random.
|
* settimeofday: (libc)Setting and Adjusting the Time.
|
* setuid: (libc)Setting User ID.
|
* setutent: (libc)Manipulating the Database.
|
* setutxent: (libc)XPG Functions.
|
* setvbuf: (libc)Controlling Buffering.
|
* shm_open: (libc)Memory-mapped I/O.
|
* shm_unlink: (libc)Memory-mapped I/O.
|
* shutdown: (libc)Closing a Socket.
|
* sigabbrev_np: (libc)Signal Messages.
|
* sigaction: (libc)Advanced Signal Handling.
|
* sigaddset: (libc)Signal Sets.
|
* sigaltstack: (libc)Signal Stack.
|
* sigblock: (libc)BSD Signal Handling.
|
* sigdelset: (libc)Signal Sets.
|
* sigdescr_np: (libc)Signal Messages.
|
* sigemptyset: (libc)Signal Sets.
|
* sigfillset: (libc)Signal Sets.
|
* siginterrupt: (libc)BSD Signal Handling.
|
* sigismember: (libc)Signal Sets.
|
* siglongjmp: (libc)Non-Local Exits and Signals.
|
* sigmask: (libc)BSD Signal Handling.
|
* signal: (libc)Basic Signal Handling.
|
* signbit: (libc)FP Bit Twiddling.
|
* significand: (libc)Normalization Functions.
|
* significandf: (libc)Normalization Functions.
|
* significandl: (libc)Normalization Functions.
|
* sigpause: (libc)BSD Signal Handling.
|
* sigpending: (libc)Checking for Pending Signals.
|
* sigprocmask: (libc)Process Signal Mask.
|
* sigsetjmp: (libc)Non-Local Exits and Signals.
|
* sigsetmask: (libc)BSD Signal Handling.
|
* sigstack: (libc)Signal Stack.
|
* sigsuspend: (libc)Sigsuspend.
|
* sin: (libc)Trig Functions.
|
* sincos: (libc)Trig Functions.
|
* sincosf: (libc)Trig Functions.
|
* sincosfN: (libc)Trig Functions.
|
* sincosfNx: (libc)Trig Functions.
|
* sincosl: (libc)Trig Functions.
|
* sinf: (libc)Trig Functions.
|
* sinfN: (libc)Trig Functions.
|
* sinfNx: (libc)Trig Functions.
|
* sinh: (libc)Hyperbolic Functions.
|
* sinhf: (libc)Hyperbolic Functions.
|
* sinhfN: (libc)Hyperbolic Functions.
|
* sinhfNx: (libc)Hyperbolic Functions.
|
* sinhl: (libc)Hyperbolic Functions.
|
* sinl: (libc)Trig Functions.
|
* sleep: (libc)Sleeping.
|
* snprintf: (libc)Formatted Output Functions.
|
* socket: (libc)Creating a Socket.
|
* socketpair: (libc)Socket Pairs.
|
* sprintf: (libc)Formatted Output Functions.
|
* sqrt: (libc)Exponents and Logarithms.
|
* sqrtf: (libc)Exponents and Logarithms.
|
* sqrtfN: (libc)Exponents and Logarithms.
|
* sqrtfNx: (libc)Exponents and Logarithms.
|
* sqrtl: (libc)Exponents and Logarithms.
|
* srand48: (libc)SVID Random.
|
* srand48_r: (libc)SVID Random.
|
* srand: (libc)ISO Random.
|
* srandom: (libc)BSD Random.
|
* srandom_r: (libc)BSD Random.
|
* sscanf: (libc)Formatted Input Functions.
|
* ssignal: (libc)Basic Signal Handling.
|
* stat64: (libc)Reading Attributes.
|
* stat: (libc)Reading Attributes.
|
* stime: (libc)Setting and Adjusting the Time.
|
* stpcpy: (libc)Copying Strings and Arrays.
|
* stpncpy: (libc)Truncating Strings.
|
* strcasecmp: (libc)String/Array Comparison.
|
* strcasestr: (libc)Search Functions.
|
* strcat: (libc)Concatenating Strings.
|
* strchr: (libc)Search Functions.
|
* strchrnul: (libc)Search Functions.
|
* strcmp: (libc)String/Array Comparison.
|
* strcoll: (libc)Collation Functions.
|
* strcpy: (libc)Copying Strings and Arrays.
|
* strcspn: (libc)Search Functions.
|
* strdup: (libc)Copying Strings and Arrays.
|
* strdupa: (libc)Copying Strings and Arrays.
|
* strerror: (libc)Error Messages.
|
* strerror_r: (libc)Error Messages.
|
* strerrordesc_np: (libc)Error Messages.
|
* strerrorname_np: (libc)Error Messages.
|
* strfmon: (libc)Formatting Numbers.
|
* strfromd: (libc)Printing of Floats.
|
* strfromf: (libc)Printing of Floats.
|
* strfromfN: (libc)Printing of Floats.
|
* strfromfNx: (libc)Printing of Floats.
|
* strfroml: (libc)Printing of Floats.
|
* strfry: (libc)Shuffling Bytes.
|
* strftime: (libc)Formatting Calendar Time.
|
* strlen: (libc)String Length.
|
* strncasecmp: (libc)String/Array Comparison.
|
* strncat: (libc)Truncating Strings.
|
* strncmp: (libc)String/Array Comparison.
|
* strncpy: (libc)Truncating Strings.
|
* strndup: (libc)Truncating Strings.
|
* strndupa: (libc)Truncating Strings.
|
* strnlen: (libc)String Length.
|
* strpbrk: (libc)Search Functions.
|
* strptime: (libc)Low-Level Time String Parsing.
|
* strrchr: (libc)Search Functions.
|
* strsep: (libc)Finding Tokens in a String.
|
* strsignal: (libc)Signal Messages.
|
* strspn: (libc)Search Functions.
|
* strstr: (libc)Search Functions.
|
* strtod: (libc)Parsing of Floats.
|
* strtof: (libc)Parsing of Floats.
|
* strtofN: (libc)Parsing of Floats.
|
* strtofNx: (libc)Parsing of Floats.
|
* strtoimax: (libc)Parsing of Integers.
|
* strtok: (libc)Finding Tokens in a String.
|
* strtok_r: (libc)Finding Tokens in a String.
|
* strtol: (libc)Parsing of Integers.
|
* strtold: (libc)Parsing of Floats.
|
* strtoll: (libc)Parsing of Integers.
|
* strtoq: (libc)Parsing of Integers.
|
* strtoul: (libc)Parsing of Integers.
|
* strtoull: (libc)Parsing of Integers.
|
* strtoumax: (libc)Parsing of Integers.
|
* strtouq: (libc)Parsing of Integers.
|
* strverscmp: (libc)String/Array Comparison.
|
* strxfrm: (libc)Collation Functions.
|
* stty: (libc)BSD Terminal Modes.
|
* swapcontext: (libc)System V contexts.
|
* swprintf: (libc)Formatted Output Functions.
|
* swscanf: (libc)Formatted Input Functions.
|
* symlink: (libc)Symbolic Links.
|
* sync: (libc)Synchronizing I/O.
|
* syscall: (libc)System Calls.
|
* sysconf: (libc)Sysconf Definition.
|
* syslog: (libc)syslog; vsyslog.
|
* system: (libc)Running a Command.
|
* sysv_signal: (libc)Basic Signal Handling.
|
* tan: (libc)Trig Functions.
|
* tanf: (libc)Trig Functions.
|
* tanfN: (libc)Trig Functions.
|
* tanfNx: (libc)Trig Functions.
|
* tanh: (libc)Hyperbolic Functions.
|
* tanhf: (libc)Hyperbolic Functions.
|
* tanhfN: (libc)Hyperbolic Functions.
|
* tanhfNx: (libc)Hyperbolic Functions.
|
* tanhl: (libc)Hyperbolic Functions.
|
* tanl: (libc)Trig Functions.
|
* tcdrain: (libc)Line Control.
|
* tcflow: (libc)Line Control.
|
* tcflush: (libc)Line Control.
|
* tcgetattr: (libc)Mode Functions.
|
* tcgetpgrp: (libc)Terminal Access Functions.
|
* tcgetsid: (libc)Terminal Access Functions.
|
* tcsendbreak: (libc)Line Control.
|
* tcsetattr: (libc)Mode Functions.
|
* tcsetpgrp: (libc)Terminal Access Functions.
|
* tdelete: (libc)Tree Search Function.
|
* tdestroy: (libc)Tree Search Function.
|
* telldir: (libc)Random Access Directory.
|
* tempnam: (libc)Temporary Files.
|
* textdomain: (libc)Locating gettext catalog.
|
* tfind: (libc)Tree Search Function.
|
* tgamma: (libc)Special Functions.
|
* tgammaf: (libc)Special Functions.
|
* tgammafN: (libc)Special Functions.
|
* tgammafNx: (libc)Special Functions.
|
* tgammal: (libc)Special Functions.
|
* tgkill: (libc)Signaling Another Process.
|
* thrd_create: (libc)ISO C Thread Management.
|
* thrd_current: (libc)ISO C Thread Management.
|
* thrd_detach: (libc)ISO C Thread Management.
|
* thrd_equal: (libc)ISO C Thread Management.
|
* thrd_exit: (libc)ISO C Thread Management.
|
* thrd_join: (libc)ISO C Thread Management.
|
* thrd_sleep: (libc)ISO C Thread Management.
|
* thrd_yield: (libc)ISO C Thread Management.
|
* time: (libc)Getting the Time.
|
* timegm: (libc)Broken-down Time.
|
* timelocal: (libc)Broken-down Time.
|
* times: (libc)Processor Time.
|
* tmpfile64: (libc)Temporary Files.
|
* tmpfile: (libc)Temporary Files.
|
* tmpnam: (libc)Temporary Files.
|
* tmpnam_r: (libc)Temporary Files.
|
* toascii: (libc)Case Conversion.
|
* tolower: (libc)Case Conversion.
|
* totalorder: (libc)FP Comparison Functions.
|
* totalorderf: (libc)FP Comparison Functions.
|
* totalorderfN: (libc)FP Comparison Functions.
|
* totalorderfNx: (libc)FP Comparison Functions.
|
* totalorderl: (libc)FP Comparison Functions.
|
* totalordermag: (libc)FP Comparison Functions.
|
* totalordermagf: (libc)FP Comparison Functions.
|
* totalordermagfN: (libc)FP Comparison Functions.
|
* totalordermagfNx: (libc)FP Comparison Functions.
|
* totalordermagl: (libc)FP Comparison Functions.
|
* toupper: (libc)Case Conversion.
|
* towctrans: (libc)Wide Character Case Conversion.
|
* towlower: (libc)Wide Character Case Conversion.
|
* towupper: (libc)Wide Character Case Conversion.
|
* trunc: (libc)Rounding Functions.
|
* truncate64: (libc)File Size.
|
* truncate: (libc)File Size.
|
* truncf: (libc)Rounding Functions.
|
* truncfN: (libc)Rounding Functions.
|
* truncfNx: (libc)Rounding Functions.
|
* truncl: (libc)Rounding Functions.
|
* tsearch: (libc)Tree Search Function.
|
* tss_create: (libc)ISO C Thread-local Storage.
|
* tss_delete: (libc)ISO C Thread-local Storage.
|
* tss_get: (libc)ISO C Thread-local Storage.
|
* tss_set: (libc)ISO C Thread-local Storage.
|
* ttyname: (libc)Is It a Terminal.
|
* ttyname_r: (libc)Is It a Terminal.
|
* twalk: (libc)Tree Search Function.
|
* twalk_r: (libc)Tree Search Function.
|
* tzset: (libc)Time Zone Functions.
|
* ufromfp: (libc)Rounding Functions.
|
* ufromfpf: (libc)Rounding Functions.
|
* ufromfpfN: (libc)Rounding Functions.
|
* ufromfpfNx: (libc)Rounding Functions.
|
* ufromfpl: (libc)Rounding Functions.
|
* ufromfpx: (libc)Rounding Functions.
|
* ufromfpxf: (libc)Rounding Functions.
|
* ufromfpxfN: (libc)Rounding Functions.
|
* ufromfpxfNx: (libc)Rounding Functions.
|
* ufromfpxl: (libc)Rounding Functions.
|
* ulimit: (libc)Limits on Resources.
|
* umask: (libc)Setting Permissions.
|
* umount2: (libc)Mount-Unmount-Remount.
|
* umount: (libc)Mount-Unmount-Remount.
|
* uname: (libc)Platform Type.
|
* ungetc: (libc)How Unread.
|
* ungetwc: (libc)How Unread.
|
* unlink: (libc)Deleting Files.
|
* unlockpt: (libc)Allocation.
|
* unsetenv: (libc)Environment Access.
|
* updwtmp: (libc)Manipulating the Database.
|
* utime: (libc)File Times.
|
* utimes: (libc)File Times.
|
* utmpname: (libc)Manipulating the Database.
|
* utmpxname: (libc)XPG Functions.
|
* va_arg: (libc)Argument Macros.
|
* va_copy: (libc)Argument Macros.
|
* va_end: (libc)Argument Macros.
|
* va_start: (libc)Argument Macros.
|
* valloc: (libc)Aligned Memory Blocks.
|
* vasprintf: (libc)Variable Arguments Output.
|
* verr: (libc)Error Messages.
|
* verrx: (libc)Error Messages.
|
* versionsort64: (libc)Scanning Directory Content.
|
* versionsort: (libc)Scanning Directory Content.
|
* vfork: (libc)Creating a Process.
|
* vfprintf: (libc)Variable Arguments Output.
|
* vfscanf: (libc)Variable Arguments Input.
|
* vfwprintf: (libc)Variable Arguments Output.
|
* vfwscanf: (libc)Variable Arguments Input.
|
* vlimit: (libc)Limits on Resources.
|
* vprintf: (libc)Variable Arguments Output.
|
* vscanf: (libc)Variable Arguments Input.
|
* vsnprintf: (libc)Variable Arguments Output.
|
* vsprintf: (libc)Variable Arguments Output.
|
* vsscanf: (libc)Variable Arguments Input.
|
* vswprintf: (libc)Variable Arguments Output.
|
* vswscanf: (libc)Variable Arguments Input.
|
* vsyslog: (libc)syslog; vsyslog.
|
* vwarn: (libc)Error Messages.
|
* vwarnx: (libc)Error Messages.
|
* vwprintf: (libc)Variable Arguments Output.
|
* vwscanf: (libc)Variable Arguments Input.
|
* wait3: (libc)BSD Wait Functions.
|
* wait4: (libc)Process Completion.
|
* wait: (libc)Process Completion.
|
* waitpid: (libc)Process Completion.
|
* warn: (libc)Error Messages.
|
* warnx: (libc)Error Messages.
|
* wcpcpy: (libc)Copying Strings and Arrays.
|
* wcpncpy: (libc)Truncating Strings.
|
* wcrtomb: (libc)Converting a Character.
|
* wcscasecmp: (libc)String/Array Comparison.
|
* wcscat: (libc)Concatenating Strings.
|
* wcschr: (libc)Search Functions.
|
* wcschrnul: (libc)Search Functions.
|
* wcscmp: (libc)String/Array Comparison.
|
* wcscoll: (libc)Collation Functions.
|
* wcscpy: (libc)Copying Strings and Arrays.
|
* wcscspn: (libc)Search Functions.
|
* wcsdup: (libc)Copying Strings and Arrays.
|
* wcsftime: (libc)Formatting Calendar Time.
|
* wcslen: (libc)String Length.
|
* wcsncasecmp: (libc)String/Array Comparison.
|
* wcsncat: (libc)Truncating Strings.
|
* wcsncmp: (libc)String/Array Comparison.
|
* wcsncpy: (libc)Truncating Strings.
|
* wcsnlen: (libc)String Length.
|
* wcsnrtombs: (libc)Converting Strings.
|
* wcspbrk: (libc)Search Functions.
|
* wcsrchr: (libc)Search Functions.
|
* wcsrtombs: (libc)Converting Strings.
|
* wcsspn: (libc)Search Functions.
|
* wcsstr: (libc)Search Functions.
|
* wcstod: (libc)Parsing of Floats.
|
* wcstof: (libc)Parsing of Floats.
|
* wcstofN: (libc)Parsing of Floats.
|
* wcstofNx: (libc)Parsing of Floats.
|
* wcstoimax: (libc)Parsing of Integers.
|
* wcstok: (libc)Finding Tokens in a String.
|
* wcstol: (libc)Parsing of Integers.
|
* wcstold: (libc)Parsing of Floats.
|
* wcstoll: (libc)Parsing of Integers.
|
* wcstombs: (libc)Non-reentrant String Conversion.
|
* wcstoq: (libc)Parsing of Integers.
|
* wcstoul: (libc)Parsing of Integers.
|
* wcstoull: (libc)Parsing of Integers.
|
* wcstoumax: (libc)Parsing of Integers.
|
* wcstouq: (libc)Parsing of Integers.
|
* wcswcs: (libc)Search Functions.
|
* wcsxfrm: (libc)Collation Functions.
|
* wctob: (libc)Converting a Character.
|
* wctomb: (libc)Non-reentrant Character Conversion.
|
* wctrans: (libc)Wide Character Case Conversion.
|
* wctype: (libc)Classification of Wide Characters.
|
* wmemchr: (libc)Search Functions.
|
* wmemcmp: (libc)String/Array Comparison.
|
* wmemcpy: (libc)Copying Strings and Arrays.
|
* wmemmove: (libc)Copying Strings and Arrays.
|
* wmempcpy: (libc)Copying Strings and Arrays.
|
* wmemset: (libc)Copying Strings and Arrays.
|
* wordexp: (libc)Calling Wordexp.
|
* wordfree: (libc)Calling Wordexp.
|
* wprintf: (libc)Formatted Output Functions.
|
* write: (libc)I/O Primitives.
|
* writev: (libc)Scatter-Gather.
|
* wscanf: (libc)Formatted Input Functions.
|
* y0: (libc)Special Functions.
|
* y0f: (libc)Special Functions.
|
* y0fN: (libc)Special Functions.
|
* y0fNx: (libc)Special Functions.
|
* y0l: (libc)Special Functions.
|
* y1: (libc)Special Functions.
|
* y1f: (libc)Special Functions.
|
* y1fN: (libc)Special Functions.
|
* y1fNx: (libc)Special Functions.
|
* y1l: (libc)Special Functions.
|
* yn: (libc)Special Functions.
|
* ynf: (libc)Special Functions.
|
* ynfN: (libc)Special Functions.
|
* ynfNx: (libc)Special Functions.
|
* ynl: (libc)Special Functions.
|
END-INFO-DIR-ENTRY
|
|
|
File: libc.info, Node: 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: Copying File Data, 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’.
|
|
-- Function: ssize_t preadv (int FD, const struct iovec *IOV, int
|
IOVCNT, off_t OFFSET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘readv’ function, with the
|
difference it adds an extra OFFSET parameter of type ‘off_t’
|
similar to ‘pread’. 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
|
‘preadv’ function is in fact ‘preadv64’ 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 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 ‘readv’ and ‘pread’.
|
|
-- Function: ssize_t preadv64 (int FD, const struct iovec *IOV, int
|
IOVCNT, off64_t OFFSET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘preadv’ function with the
|
difference is that the OFFSET parameter is of type ‘off64_t’
|
instead of ‘off_t’. It 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
|
‘preadv’ and so transparently replaces the 32 bit interface.
|
|
-- Function: ssize_t pwritev (int FD, const struct iovec *IOV, int
|
IOVCNT, off_t OFFSET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘writev’ function, with the
|
difference it adds an extra OFFSET parameter of type ‘off_t’
|
similar to ‘pwrite’. The data is written to the file starting at
|
position OFFSET. The position of the file descriptor itself is not
|
affected by the operation. The value is the same as before the
|
call.
|
|
However, on Linux, if a file is opened with ‘O_APPEND’, ‘pwrite’
|
appends data to the end of the file, regardless of the value of
|
‘offset’.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
|
‘pwritev’ function is in fact ‘pwritev64’ 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 is a count of bytes (_not_ buffers) written, 0
|
indicating end-of-file, or -1 indicating an error. The possible
|
errors are the same as in ‘writev’ and ‘pwrite’.
|
|
-- Function: ssize_t pwritev64 (int FD, const struct iovec *IOV, int
|
IOVCNT, off64_t OFFSET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘pwritev’ function with the
|
difference is that the OFFSET parameter is of type ‘off64_t’
|
instead of ‘off_t’. It 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
|
‘pwritev’ and so transparently replaces the 32 bit interface.
|
|
-- Function: ssize_t preadv2 (int FD, const struct iovec *IOV, int
|
IOVCNT, off_t OFFSET, int FLAGS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘preadv’ function, with the
|
difference it adds an extra FLAGS parameter of type ‘int’.
|
Additionally, if OFFSET is -1, the current file position is used
|
and updated (like the ‘readv’ function).
|
|
The supported FLAGS are dependent of the underlying system. For
|
Linux it supports:
|
|
‘RWF_HIPRI’
|
High priority request. This adds a flag that tells the file
|
system that this is a high priority request for which it is
|
worth to poll the hardware. The flag is purely advisory and
|
can be ignored if not supported. The FD must be opened using
|
‘O_DIRECT’.
|
|
‘RWF_DSYNC’
|
Per-IO synchronization as if the file was opened with
|
‘O_DSYNC’ flag.
|
|
‘RWF_SYNC’
|
Per-IO synchronization as if the file was opened with ‘O_SYNC’
|
flag.
|
|
‘RWF_NOWAIT’
|
Use nonblocking mode for this operation; that is, this call to
|
‘preadv2’ will fail and set ‘errno’ to ‘EAGAIN’ if the
|
operation would block.
|
|
‘RWF_APPEND’
|
Per-IO synchronization as if the file was opened with
|
‘O_APPEND’ flag.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
|
‘preadv2’ function is in fact ‘preadv64v2’ 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 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 ‘preadv’ with the addition of:
|
|
‘EOPNOTSUPP’
|
|
An unsupported FLAGS was used.
|
|
-- Function: ssize_t preadv64v2 (int FD, const struct iovec *IOV, int
|
IOVCNT, off64_t OFFSET, int FLAGS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘preadv2’ function with the
|
difference is that the OFFSET parameter is of type ‘off64_t’
|
instead of ‘off_t’. It 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
|
‘preadv2’ and so transparently replaces the 32 bit interface.
|
|
-- Function: ssize_t pwritev2 (int FD, const struct iovec *IOV, int
|
IOVCNT, off_t OFFSET, int FLAGS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘pwritev’ function, with the
|
difference it adds an extra FLAGS parameter of type ‘int’.
|
Additionally, if OFFSET is -1, the current file position should is
|
used and updated (like the ‘writev’ function).
|
|
The supported FLAGS are dependent of the underlying system. For
|
Linux, the supported flags are the same as those for ‘preadv2’.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
|
‘pwritev2’ function is in fact ‘pwritev64v2’ 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 is a count of bytes (_not_ buffers) write, 0
|
indicating end-of-file, or -1 indicating an error. The possible
|
errors are the same as in ‘preadv2’.
|
|
-- Function: ssize_t pwritev64v2 (int FD, const struct iovec *IOV, int
|
IOVCNT, off64_t OFFSET, int FLAGS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘pwritev2’ function with the
|
difference is that the OFFSET parameter is of type ‘off64_t’
|
instead of ‘off_t’. It 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
|
‘pwritev2’ and so transparently replaces the 32 bit interface.
|
|
|
File: libc.info, Node: Copying File Data, Next: Memory-mapped I/O, Prev: Scatter-Gather, Up: Low-Level I/O
|
|
13.7 Copying data between two files
|
===================================
|
|
A special function is provided to copy data between two files on the
|
same file system. The system can optimize such copy operations. This
|
is particularly important on network file systems, where the data would
|
otherwise have to be transferred twice over the network.
|
|
Note that this function only copies file data, but not metadata such
|
as file permissions or extended attributes.
|
|
-- Function: ssize_t copy_file_range (int INPUTFD, off64_t *INPUTPOS,
|
int OUTPUTFD, off64_t *OUTPUTPOS, ssize_t LENGTH, unsigned int
|
FLAGS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function copies up to LENGTH bytes from the file descriptor
|
INPUTFD to the file descriptor OUTPUTFD.
|
|
The function can operate on both the current file position (like
|
‘read’ and ‘write’) and an explicit offset (like ‘pread’ and
|
‘pwrite’). If the INPUTPOS pointer is null, the file position of
|
INPUTFD is used as the starting point of the copy operation, and
|
the file position is advanced during it. If INPUTPOS is not null,
|
then ‘*INPUTPOS’ is used as the starting point of the copy
|
operation, and ‘*INPUTPOS’ is incremented by the number of copied
|
bytes, but the file position remains unchanged. Similar rules
|
apply to OUTPUTFD and OUTPUTPOS for the output file position.
|
|
The FLAGS argument is currently reserved and must be zero.
|
|
The ‘copy_file_range’ function returns the number of bytes copied.
|
This can be less than the specified LENGTH in case the input file
|
contains fewer remaining bytes than LENGTH, or if a read or write
|
failure occurs. The return value is zero if the end of the input
|
file is encountered immediately.
|
|
If no bytes can be copied, to report an error, ‘copy_file_range’
|
returns the value -1 and sets ‘errno’. The table below lists some
|
of the error conditions for this function.
|
|
‘ENOSYS’
|
The kernel does not implement the required functionality.
|
|
‘EISDIR’
|
At least one of the descriptors INPUTFD or OUTPUTFD refers to
|
a directory.
|
|
‘EINVAL’
|
At least one of the descriptors INPUTFD or OUTPUTFD refers to
|
a non-regular, non-directory file (such as a socket or a
|
FIFO).
|
|
The input or output positions before are after the copy
|
operations are outside of an implementation-defined limit.
|
|
The FLAGS argument is not zero.
|
|
‘EFBIG’
|
The new file size would exceed the process file size limit.
|
*Note Limits on Resources::.
|
|
The input or output positions before are after the copy
|
operations are outside of an implementation-defined limit.
|
This can happen if the file was not opened with large file
|
support (LFS) on 32-bit machines, and the copy operation would
|
create a file which is larger than what ‘off_t’ could
|
represent.
|
|
‘EBADF’
|
The argument INPUTFD is not a valid file descriptor open for
|
reading.
|
|
The argument OUTPUTFD is not a valid file descriptor open for
|
writing, or OUTPUTFD has been opened with ‘O_APPEND’.
|
|
In addition, ‘copy_file_range’ can fail with the error codes which
|
are used by ‘read’, ‘pread’, ‘write’, and ‘pwrite’.
|
|
The ‘copy_file_range’ function is a cancellation point. In case of
|
cancellation, the input location (the file position or the value at
|
‘*INPUTPOS’) is indeterminate.
|
|
|
File: libc.info, Node: Memory-mapped I/O, Next: Waiting for I/O, Prev: Copying File Data, Up: Low-Level I/O
|
|
13.8 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 default size of a page the machine uses one should use:
|
|
size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
|
|
On some systems, mappings can use larger page sizes for certain
|
files, and applications can request larger page sizes for anonymous
|
mappings as well (see the ‘MAP_HUGETLB’ flag below).
|
|
The following 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’. The special flag ‘PROT_NONE’ reserves a region of
|
address space for future use. The ‘mprotect’ function can be used
|
to change the protection flags. *Note Memory Protection::.
|
|
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.
|
|
‘MAP_HUGETLB’
|
|
This requests that the system uses an alternative page size
|
which is larger than the default page size for the mapping.
|
For some workloads, increasing the page size for large
|
mappings improves performance because the system needs to
|
handle far fewer pages. For other workloads which require
|
frequent transfer of pages between storage or different nodes,
|
the decreased page granularity may cause performance problems
|
due to the increased page size and larger transfers.
|
|
In order to create the mapping, the system needs physically
|
contiguous memory of the size of the increased page size. As
|
a result, ‘MAP_HUGETLB’ mappings are affected by memory
|
fragmentation, and their creation can fail even if plenty of
|
memory is available in the system.
|
|
Not all file systems support mappings with an increased page
|
size.
|
|
The ‘MAP_HUGETLB’ flag is specific to Linux.
|
|
‘mmap’ returns the address of the new mapping, or ‘MAP_FAILED’ for
|
an error.
|
|
Possible errors include:
|
|
‘EINVAL’
|
|
Either ADDRESS was unusable (because it is not a multiple of
|
the applicable page size), or inconsistent FLAGS were given.
|
|
If ‘MAP_HUGETLB’ was specified, the file or system does not
|
support large page sizes.
|
|
‘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.
|
|
‘MADV_HUGEPAGE’
|
|
Indicate that it is beneficial to increase the page size for
|
this mapping. This can improve performance for larger
|
mappings because the system needs to handle far fewer pages.
|
However, if parts of the mapping are frequently transferred
|
between storage or different nodes, performance may suffer
|
because individual transfers can become substantially larger
|
due to the increased page size.
|
|
This flag is specific to Linux.
|
|
‘MADV_NOHUGEPAGE’
|
Undo the effect of a previous ‘MADV_HUGEPAGE’ advice. This
|
flag is specific to Linux.
|
|
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.
|
|
-- Function: int memfd_create (const char *NAME, unsigned int FLAGS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘memfd_create’ function returns a file descriptor which can be
|
used to create memory mappings using the ‘mmap’ function. It is
|
similar to the ‘shm_open’ function in the sense that these mappings
|
are not backed by actual files. However, the descriptor returned
|
by ‘memfd_create’ does not correspond to a named object; the NAME
|
argument is used for debugging purposes only (e.g., will appear in
|
‘/proc’), and separate invocations of ‘memfd_create’ with the same
|
NAME will not return descriptors for the same region of memory.
|
The descriptor can also be used to create alias mappings within the
|
same process.
|
|
The descriptor initially refers to a zero-length file. Before
|
mappings can be created which are backed by memory, the file size
|
needs to be increased with the ‘ftruncate’ function. *Note File
|
Size::.
|
|
The FLAGS argument can be a combination of the following flags:
|
|
‘MFD_CLOEXEC’
|
|
The descriptor is created with the ‘O_CLOEXEC’ flag.
|
|
‘MFD_ALLOW_SEALING’
|
|
The descriptor supports the addition of seals using the
|
‘fcntl’ function.
|
|
‘MFD_HUGETLB’
|
|
This requests that mappings created using the returned file
|
descriptor use a larger page size. See ‘MAP_HUGETLB’ above
|
for details.
|
|
This flag is incompatible with ‘MFD_ALLOW_SEALING’.
|
|
‘memfd_create’ returns a file descriptor on success, and -1 on
|
failure.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EINVAL’
|
An invalid combination is specified in FLAGS, or NAME is too
|
long.
|
|
‘EFAULT’
|
The NAME argument does not point to a string.
|
|
‘EMFILE’
|
The operation would exceed the file descriptor limit for this
|
process.
|
|
‘ENFILE’
|
The operation would exceed the system-wide file descriptor
|
limit.
|
|
‘ENOMEM’
|
There is not enough memory for the operation.
|
|
|
File: libc.info, Node: Waiting for I/O, Next: Synchronizing I/O, Prev: Memory-mapped I/O, Up: Low-Level I/O
|
|
13.9 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 Time Types::.
|
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.10 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.11 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.11.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.11.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.11.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.11.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.11.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.12 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
|
for the commands ‘F_SETLKW’ (and the LFS analogous ‘F_SETLKW64’)
|
and ‘F_OFD_SETLKW’. 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.13 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.14 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.15 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.15.1 File Access Modes
|
-------------------------
|
|
The file access mode allows a file descriptor to be used for reading,
|
writing, both, or neither. The access mode is determined 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.
|
|
-- Macro: int O_PATH
|
|
Obtain a file descriptor for the file, but do not open the file for
|
reading or writing. Permission checks for the file itself are
|
skipped when the file is opened (but permission to access the
|
directory that contains it is still needed), and permissions are
|
checked when the descriptor is used later on.
|
|
For example, such descriptors can be used with the ‘fexecve’
|
function (*note Executing a File::).
|
|
This access mode is specific to Linux. On GNU/Hurd systems, it is
|
possible to use ‘O_EXEC’ explicitly, or specify no access modes at
|
all (see below).
|
|
The portable file access modes ‘O_RDONLY’, ‘O_WRONLY’, and ‘O_RDWR’
|
may not correspond to individual bits. To determine the file access
|
mode with ‘fcntl’, you must extract the access mode bits from the
|
retrieved file status flags, using the ‘O_ACCMODE’ mask.
|
|
-- Macro: int O_ACCMODE
|
|
This macro is a mask that can be bitwise-ANDed with the file status
|
flag value to recover the file access mode, assuming that a
|
standard file access mode is in use.
|
|
If a non-standard file access mode is used (such as ‘O_PATH’ or
|
‘O_EXEC’), masking with ‘O_ACCMODE’ may give incorrect results. These
|
non-standard access modes are identified by individual bits and have to
|
be checked directly (without masking with ‘O_ACCMODE’ first).
|
|
On GNU/Hurd systems (but 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.
|
|
-- Macro: int O_READ
|
|
Open the file for reading. Same as ‘O_RDONLY’; only defined on
|
GNU/Hurd.
|
|
-- Macro: int O_WRITE
|
|
Open the file for writing. Same as ‘O_WRONLY’; only defined on
|
GNU/Hurd.
|
|
-- Macro: int O_EXEC
|
|
Open the file for executing. Only defined on GNU/Hurd.
|
|
|
File: libc.info, Node: Open-time Flags, Next: Operating Modes, Prev: Access Modes, Up: File Status Flags
|
|
13.15.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.
|
|
The ‘O_EXCL’ flag has a special meaning in combination with
|
‘O_TMPFILE’; see below.
|
|
-- Macro: int O_DIRECTORY
|
|
If set, the open operation fails if the given name is not the name
|
of a directory. The ‘errno’ variable is set to ‘ENOTDIR’ for this
|
error condition.
|
|
-- Macro: int O_NOFOLLOW
|
|
If set, the open operation fails if the final component of the file
|
name refers to a symbolic link. The ‘errno’ variable is set to
|
‘ELOOP’ for this error condition.
|
|
-- Macro: int O_TMPFILE
|
|
If this flag is specified, functions in the ‘open’ family create an
|
unnamed temporary file. In this case, the pathname argument to the
|
‘open’ family of functions (*note Opening and Closing Files::) is
|
interpreted as the directory in which the temporary file is created
|
(thus determining the file system which provides the storage for
|
the file). The ‘O_TMPFILE’ flag must be combined with ‘O_WRONLY’
|
or ‘O_RDWR’, and the MODE argument is required.
|
|
The temporary file can later be given a name using ‘linkat’,
|
turning it into a regular file. This allows the atomic creation of
|
a file with the specific file attributes (mode and extended
|
attributes) and file contents. If, for security reasons, it is not
|
desirable that a name can be given to the file, the ‘O_EXCL’ flag
|
can be specified along with ‘O_TMPFILE’.
|
|
Not all kernels support this open flag. If this flag is
|
unsupported, an attempt to create an unnamed temporary file fails
|
with an error of ‘EINVAL’. If the underlying file system does not
|
support the ‘O_TMPFILE’ flag, an ‘EOPNOTSUPP’ error is the result.
|
|
The ‘O_TMPFILE’ flag is a GNU extension.
|
|
-- 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’.
|
|
|
File: libc.info, Node: Operating Modes, Next: Getting File Status Flags, Prev: Open-time Flags, Up: File Status Flags
|
|
13.15.3 I/O Operating Modes
|
---------------------------
|
|
The operating modes affect how input and output operations using a file
|
descriptor work. These flags are set by ‘open’ and can be fetched and
|
changed with ‘fcntl’.
|
|
-- Macro: int O_APPEND
|
|
The bit that enables append mode for the file. If set, then all
|
‘write’ operations write the data at the end of the file, extending
|
it, regardless of the current file position. This is the only
|
reliable way to append to a file. In append mode, you are
|
guaranteed that the data you write will always go to the current
|
end of the file, regardless of other processes writing to the file.
|
Conversely, if you simply set the file position to the end of file
|
and write, then another process can extend the file after you set
|
the file position but before you write, resulting in your data
|
appearing someplace before the real end of file.
|
|
-- Macro: int O_NONBLOCK
|
|
The bit that enables nonblocking mode for the file. If this bit is
|
set, ‘read’ requests on the file can return immediately with a
|
failure status if there is no input immediately available, instead
|
of blocking. Likewise, ‘write’ requests can also return
|
immediately with a failure status if the output can’t be written
|
immediately.
|
|
Note that the ‘O_NONBLOCK’ flag is overloaded as both an I/O
|
operating mode and a file name translation flag; *note Open-time
|
Flags::.
|
|
-- Macro: int O_NDELAY
|
|
This is an obsolete name for ‘O_NONBLOCK’, provided for
|
compatibility with BSD. It is not defined by the POSIX.1 standard.
|
|
The remaining operating modes are BSD and GNU extensions. They exist
|
only on some systems. On other systems, these macros are not defined.
|
|
-- Macro: int O_ASYNC
|
|
The bit that enables asynchronous input mode. If set, then ‘SIGIO’
|
signals will be generated when input is available. *Note Interrupt
|
Input::.
|
|
Asynchronous input mode is a BSD feature.
|
|
-- Macro: int O_FSYNC
|
|
The bit that enables synchronous writing for the file. If set,
|
each ‘write’ call will make sure the data is reliably stored on
|
disk before returning.
|
|
Synchronous writing is a BSD feature.
|
|
-- Macro: int O_SYNC
|
|
This is another name for ‘O_FSYNC’. They have the same value.
|
|
-- Macro: int O_NOATIME
|
|
If this bit is set, ‘read’ will not update the access time of the
|
file. *Note File Times::. This is used by programs that do
|
backups, so that backing a file up does not count as reading it.
|
Only the owner of the file or the superuser may use this bit.
|
|
This is a GNU extension.
|
|
|
File: libc.info, Node: Getting File Status Flags, Prev: Operating Modes, Up: File Status Flags
|
|
13.15.4 Getting and Setting File Status Flags
|
---------------------------------------------
|
|
The ‘fcntl’ function can fetch or change file status flags.
|
|
-- Macro: int F_GETFL
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to read the
|
file status flags for the open file with descriptor FILEDES.
|
|
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. Since the file access modes are not
|
single-bit values, you can mask off other bits in the returned
|
flags with ‘O_ACCMODE’ to compare them.
|
|
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_SETFL
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to set the
|
file status flags for the open file corresponding to the FILEDES
|
argument. This command requires a third ‘int’ argument to specify
|
the new flags, so the call looks like this:
|
|
fcntl (FILEDES, F_SETFL, NEW-FLAGS)
|
|
You can’t change the access mode for the file in this way; that is,
|
whether the file descriptor was opened for reading or writing.
|
|
The normal return value from ‘fcntl’ with this command is an
|
unspecified value other than -1, which indicates an error. The
|
error conditions are the same as for the ‘F_GETFL’ command.
|
|
If you want to modify the file status flags, you should get the
|
current flags with ‘F_GETFL’ 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 ‘O_NONBLOCK’
|
without altering any other flags:
|
|
/* Set the ‘O_NONBLOCK’ 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_nonblock_flag (int desc, int value)
|
{
|
int oldflags = fcntl (desc, F_GETFL, 0);
|
/* If reading the flags failed, return error indication now. */
|
if (oldflags == -1)
|
return -1;
|
/* Set just the flag we want to set. */
|
if (value != 0)
|
oldflags |= O_NONBLOCK;
|
else
|
oldflags &= ~O_NONBLOCK;
|
/* Store modified flag word in the descriptor. */
|
return fcntl (desc, F_SETFL, oldflags);
|
}
|
|
|
File: libc.info, Node: File Locks, Next: Open File Description Locks, Prev: File Status Flags, Up: Low-Level I/O
|
|
13.16 File Locks
|
================
|
|
This section describes record locks that are associated with the
|
process. There is also a different type of record lock that is
|
associated with the open file description instead of the process. *Note
|
Open File Description Locks::.
|
|
The remaining ‘fcntl’ commands are used to support "record locking",
|
which permits multiple cooperating programs to prevent each other from
|
simultaneously accessing parts of a file in error-prone ways.
|
|
An "exclusive" or "write" lock gives a process exclusive access for
|
writing to the specified part of the file. While a write lock is in
|
place, no other process can lock that part of the file.
|
|
A "shared" or "read" lock prohibits any other process from requesting
|
a write lock on the specified part of the file. However, other
|
processes can request read locks.
|
|
The ‘read’ and ‘write’ functions do not actually check to see whether
|
there are any locks in place. If you want to implement a locking
|
protocol for a file shared by multiple processes, your application must
|
do explicit ‘fcntl’ calls to request and clear locks at the appropriate
|
points.
|
|
Locks are associated with processes. A process can only have one
|
kind of lock set for each byte of a given file. When any file
|
descriptor for that file is closed by the process, all of the locks that
|
process holds on that file are released, even if the locks were made
|
using other descriptors that remain open. Likewise, locks are released
|
when a process exits, and are not inherited by child processes created
|
using ‘fork’ (*note Creating a Process::).
|
|
When making a lock, use a ‘struct flock’ to specify what kind of lock
|
and where. This data type and the associated macros for the ‘fcntl’
|
function are declared in the header file ‘fcntl.h’.
|
|
-- Data Type: struct flock
|
|
This structure is used with the ‘fcntl’ function to describe a file
|
lock. It has these members:
|
|
‘short int l_type’
|
Specifies the type of the lock; one of ‘F_RDLCK’, ‘F_WRLCK’,
|
or ‘F_UNLCK’.
|
|
‘short int l_whence’
|
This corresponds to the WHENCE argument to ‘fseek’ or ‘lseek’,
|
and specifies what the offset is relative to. Its value can
|
be one of ‘SEEK_SET’, ‘SEEK_CUR’, or ‘SEEK_END’.
|
|
‘off_t l_start’
|
This specifies the offset of the start of the region to which
|
the lock applies, and is given in bytes relative to the point
|
specified by the ‘l_whence’ member.
|
|
‘off_t l_len’
|
This specifies the length of the region to be locked. A value
|
of ‘0’ is treated specially; it means the region extends to
|
the end of the file.
|
|
‘pid_t l_pid’
|
This field is the process ID (*note Process Creation
|
Concepts::) of the process holding the lock. It is filled in
|
by calling ‘fcntl’ with the ‘F_GETLK’ command, but is ignored
|
when making a lock. If the conflicting lock is an open file
|
description lock (*note Open File Description Locks::), then
|
this field will be set to -1.
|
|
-- Macro: int F_GETLK
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should get information about a lock. This command requires
|
a third argument of type ‘struct flock *’ to be passed to ‘fcntl’,
|
so that the form of the call is:
|
|
fcntl (FILEDES, F_GETLK, LOCKP)
|
|
If there is a lock already in place that would block the lock
|
described by the LOCKP argument, information about that lock
|
overwrites ‘*LOCKP’. Existing locks are not reported if they are
|
compatible with making a new lock as specified. Thus, you should
|
specify a lock type of ‘F_WRLCK’ if you want to find out about both
|
read and write locks, or ‘F_RDLCK’ if you want to find out about
|
write locks only.
|
|
There might be more than one lock affecting the region specified by
|
the LOCKP argument, but ‘fcntl’ only returns information about one
|
of them. The ‘l_whence’ member of the LOCKP structure is set to
|
‘SEEK_SET’ and the ‘l_start’ and ‘l_len’ fields set to identify the
|
locked region.
|
|
If no lock applies, the only change to the LOCKP structure is to
|
update the ‘l_type’ to a value of ‘F_UNLCK’.
|
|
The normal return value from ‘fcntl’ with this command is an
|
unspecified value other than -1, which is reserved to indicate an
|
error. The following ‘errno’ error conditions are defined for this
|
command:
|
|
‘EBADF’
|
The FILEDES argument is invalid.
|
|
‘EINVAL’
|
Either the LOCKP argument doesn’t specify valid lock
|
information, or the file associated with FILEDES doesn’t
|
support locks.
|
|
-- Macro: int F_SETLK
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should set or clear a lock. This command requires a third
|
argument of type ‘struct flock *’ to be passed to ‘fcntl’, so that
|
the form of the call is:
|
|
fcntl (FILEDES, F_SETLK, LOCKP)
|
|
If the process already has a lock on any part of the region, the
|
old lock on that part is replaced with the new lock. You can
|
remove a lock by specifying a lock type of ‘F_UNLCK’.
|
|
If the lock cannot be set, ‘fcntl’ returns immediately with a value
|
of -1. This function does not block while waiting for other
|
processes to release locks. If ‘fcntl’ succeeds, it returns a
|
value other than -1.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EAGAIN’
|
‘EACCES’
|
The lock cannot be set because it is blocked by an existing
|
lock on the file. Some systems use ‘EAGAIN’ in this case, and
|
other systems use ‘EACCES’; your program should treat them
|
alike, after ‘F_SETLK’. (GNU/Linux and GNU/Hurd systems
|
always use ‘EAGAIN’.)
|
|
‘EBADF’
|
Either: the FILEDES argument is invalid; you requested a read
|
lock but the FILEDES is not open for read access; or, you
|
requested a write lock but the FILEDES is not open for write
|
access.
|
|
‘EINVAL’
|
Either the LOCKP argument doesn’t specify valid lock
|
information, or the file associated with FILEDES doesn’t
|
support locks.
|
|
‘ENOLCK’
|
The system has run out of file lock resources; there are
|
already too many file locks in place.
|
|
Well-designed file systems never report this error, because
|
they have no limitation on the number of locks. However, you
|
must still take account of the possibility of this error, as
|
it could result from network access to a file system on
|
another machine.
|
|
-- Macro: int F_SETLKW
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should set or clear a lock. It is just like the ‘F_SETLK’
|
command, but causes the process to block (or wait) until the
|
request can be specified.
|
|
This command requires a third argument of type ‘struct flock *’, as
|
for the ‘F_SETLK’ command.
|
|
The ‘fcntl’ return values and errors are the same as for the
|
‘F_SETLK’ command, but these additional ‘errno’ error conditions
|
are defined for this command:
|
|
‘EINTR’
|
The function was interrupted by a signal while it was waiting.
|
*Note Interrupted Primitives::.
|
|
‘EDEADLK’
|
The specified region is being locked by another process. But
|
that process is waiting to lock a region which the current
|
process has locked, so waiting for the lock would result in
|
deadlock. The system does not guarantee that it will detect
|
all such conditions, but it lets you know if it notices one.
|
|
The following macros are defined for use as values for the ‘l_type’
|
member of the ‘flock’ structure. The values are integer constants.
|
|
‘F_RDLCK’
|
|
This macro is used to specify a read (or shared) lock.
|
|
‘F_WRLCK’
|
|
This macro is used to specify a write (or exclusive) lock.
|
|
‘F_UNLCK’
|
|
This macro is used to specify that the region is unlocked.
|
|
As an example of a situation where file locking is useful, consider a
|
program that can be run simultaneously by several different users, that
|
logs status information to a common file. One example of such a program
|
might be a game that uses a file to keep track of high scores. Another
|
example might be a program that records usage or accounting information
|
for billing purposes.
|
|
Having multiple copies of the program simultaneously writing to the
|
file could cause the contents of the file to become mixed up. But you
|
can prevent this kind of problem by setting a write lock on the file
|
before actually writing to the file.
|
|
If the program also needs to read the file and wants to make sure
|
that the contents of the file are in a consistent state, then it can
|
also use a read lock. While the read lock is set, no other process can
|
lock that part of the file for writing.
|
|
Remember that file locks are only an _advisory_ protocol for
|
controlling access to a file. There is still potential for access to
|
the file by programs that don’t use the lock protocol.
|
|
|
File: libc.info, Node: Open File Description Locks, Next: Open File Description Locks Example, Prev: File Locks, Up: Low-Level I/O
|
|
13.17 Open File Description Locks
|
=================================
|
|
In contrast to process-associated record locks (*note File Locks::),
|
open file description record locks are associated with an open file
|
description rather than a process.
|
|
Using ‘fcntl’ to apply an open file description lock on a region that
|
already has an existing open file description lock that was created via
|
the same file descriptor will never cause a lock conflict.
|
|
Open file description locks are also inherited by child processes
|
across ‘fork’, or ‘clone’ with ‘CLONE_FILES’ set (*note Creating a
|
Process::), along with the file descriptor.
|
|
It is important to distinguish between the open file _description_
|
(an instance of an open file, usually created by a call to ‘open’) and
|
an open file _descriptor_, which is a numeric value that refers to the
|
open file description. The locks described here are associated with the
|
open file _description_ and not the open file _descriptor_.
|
|
Using ‘dup’ (*note Duplicating Descriptors::) to copy a file
|
descriptor does not give you a new open file description, but rather
|
copies a reference to an existing open file description and assigns it
|
to a new file descriptor. Thus, open file description locks set on a
|
file descriptor cloned by ‘dup’ will never conflict with open file
|
description locks set on the original descriptor since they refer to the
|
same open file description. Depending on the range and type of lock
|
involved, the original lock may be modified by a ‘F_OFD_SETLK’ or
|
‘F_OFD_SETLKW’ command in this situation however.
|
|
Open file description locks always conflict with process-associated
|
locks, even if acquired by the same process or on the same open file
|
descriptor.
|
|
Open file description locks use the same ‘struct flock’ as
|
process-associated locks as an argument (*note File Locks::) and the
|
macros for the ‘command’ values are also declared in the header file
|
‘fcntl.h’. To use them, the macro ‘_GNU_SOURCE’ must be defined prior
|
to including any header file.
|
|
In contrast to process-associated locks, any ‘struct flock’ used as
|
an argument to open file description lock commands must have the ‘l_pid’
|
value set to 0. Also, when returning information about an open file
|
description lock in a ‘F_GETLK’ or ‘F_OFD_GETLK’ request, the ‘l_pid’
|
field in ‘struct flock’ will be set to -1 to indicate that the lock is
|
not associated with a process.
|
|
When the same ‘struct flock’ is reused as an argument to a
|
‘F_OFD_SETLK’ or ‘F_OFD_SETLKW’ request after being used for an
|
‘F_OFD_GETLK’ request, it is necessary to inspect and reset the ‘l_pid’
|
field to 0.
|
|
-- Macro: int F_OFD_GETLK
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should get information about a lock. This command requires
|
a third argument of type ‘struct flock *’ to be passed to ‘fcntl’,
|
so that the form of the call is:
|
|
fcntl (FILEDES, F_OFD_GETLK, LOCKP)
|
|
If there is a lock already in place that would block the lock
|
described by the LOCKP argument, information about that lock is
|
written to ‘*LOCKP’. Existing locks are not reported if they are
|
compatible with making a new lock as specified. Thus, you should
|
specify a lock type of ‘F_WRLCK’ if you want to find out about both
|
read and write locks, or ‘F_RDLCK’ if you want to find out about
|
write locks only.
|
|
There might be more than one lock affecting the region specified by
|
the LOCKP argument, but ‘fcntl’ only returns information about one
|
of them. Which lock is returned in this situation is undefined.
|
|
The ‘l_whence’ member of the LOCKP structure are set to ‘SEEK_SET’
|
and the ‘l_start’ and ‘l_len’ fields are set to identify the locked
|
region.
|
|
If no conflicting lock exists, the only change to the LOCKP
|
structure is to update the ‘l_type’ field to the value ‘F_UNLCK’.
|
|
The normal return value from ‘fcntl’ with this command is either 0
|
on success or -1, which indicates an error. The following ‘errno’
|
error conditions are defined for this command:
|
|
‘EBADF’
|
The FILEDES argument is invalid.
|
|
‘EINVAL’
|
Either the LOCKP argument doesn’t specify valid lock
|
information, the operating system kernel doesn’t support open
|
file description locks, or the file associated with FILEDES
|
doesn’t support locks.
|
|
-- Macro: int F_OFD_SETLK
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should set or clear a lock. This command requires a third
|
argument of type ‘struct flock *’ to be passed to ‘fcntl’, so that
|
the form of the call is:
|
|
fcntl (FILEDES, F_OFD_SETLK, LOCKP)
|
|
If the open file already has a lock on any part of the region, the
|
old lock on that part is replaced with the new lock. You can
|
remove a lock by specifying a lock type of ‘F_UNLCK’.
|
|
If the lock cannot be set, ‘fcntl’ returns immediately with a value
|
of -1. This command does not wait for other tasks to release
|
locks. If ‘fcntl’ succeeds, it returns 0.
|
|
The following ‘errno’ error conditions are defined for this
|
command:
|
|
‘EAGAIN’
|
The lock cannot be set because it is blocked by an existing
|
lock on the file.
|
|
‘EBADF’
|
Either: the FILEDES argument is invalid; you requested a read
|
lock but the FILEDES is not open for read access; or, you
|
requested a write lock but the FILEDES is not open for write
|
access.
|
|
‘EINVAL’
|
Either the LOCKP argument doesn’t specify valid lock
|
information, the operating system kernel doesn’t support open
|
file description locks, or the file associated with FILEDES
|
doesn’t support locks.
|
|
‘ENOLCK’
|
The system has run out of file lock resources; there are
|
already too many file locks in place.
|
|
Well-designed file systems never report this error, because
|
they have no limitation on the number of locks. However, you
|
must still take account of the possibility of this error, as
|
it could result from network access to a file system on
|
another machine.
|
|
-- Macro: int F_OFD_SETLKW
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should set or clear a lock. It is just like the
|
‘F_OFD_SETLK’ command, but causes the process to wait until the
|
request can be completed.
|
|
This command requires a third argument of type ‘struct flock *’, as
|
for the ‘F_OFD_SETLK’ command.
|
|
The ‘fcntl’ return values and errors are the same as for the
|
‘F_OFD_SETLK’ command, but these additional ‘errno’ error
|
conditions are defined for this command:
|
|
‘EINTR’
|
The function was interrupted by a signal while it was waiting.
|
*Note Interrupted Primitives::.
|
|
Open file description locks are useful in the same sorts of
|
situations as process-associated locks. They can also be used to
|
synchronize file access between threads within the same process by
|
having each thread perform its own ‘open’ of the file, to obtain its own
|
open file description.
|
|
Because open file description locks are automatically freed only upon
|
closing the last file descriptor that refers to the open file
|
description, this locking mechanism avoids the possibility that locks
|
are inadvertently released due to a library routine opening and closing
|
a file without the application being aware.
|
|
As with process-associated locks, open file description locks are
|
advisory.
|
|
|
File: libc.info, Node: Open File Description Locks Example, Next: Interrupt Input, Prev: Open File Description Locks, Up: Low-Level I/O
|
|
13.18 Open File Description Locks Example
|
=========================================
|
|
Here is an example of using open file description locks in a threaded
|
program. If this program used process-associated locks, then it would
|
be subject to data corruption because process-associated locks are
|
shared by the threads inside a process, and thus cannot be used by one
|
thread to lock out another thread in the same process.
|
|
Proper error handling has been omitted in the following program for
|
brevity.
|
|
|
#define _GNU_SOURCE
|
#include <stdio.h>
|
#include <sys/types.h>
|
#include <sys/stat.h>
|
#include <unistd.h>
|
#include <fcntl.h>
|
#include <pthread.h>
|
|
#define FILENAME "/tmp/foo"
|
#define NUM_THREADS 3
|
#define ITERATIONS 5
|
|
void *
|
thread_start (void *arg)
|
{
|
int i, fd, len;
|
long tid = (long) arg;
|
char buf[256];
|
struct flock lck = {
|
.l_whence = SEEK_SET,
|
.l_start = 0,
|
.l_len = 1,
|
};
|
|
fd = open ("/tmp/foo", O_RDWR | O_CREAT, 0666);
|
|
for (i = 0; i < ITERATIONS; i++)
|
{
|
lck.l_type = F_WRLCK;
|
fcntl (fd, F_OFD_SETLKW, &lck);
|
|
len = sprintf (buf, "%d: tid=%ld fd=%d\n", i, tid, fd);
|
|
lseek (fd, 0, SEEK_END);
|
write (fd, buf, len);
|
fsync (fd);
|
|
lck.l_type = F_UNLCK;
|
fcntl (fd, F_OFD_SETLK, &lck);
|
|
/* sleep to ensure lock is yielded to another thread */
|
usleep (1);
|
}
|
pthread_exit (NULL);
|
}
|
|
int
|
main (int argc, char **argv)
|
{
|
long i;
|
pthread_t threads[NUM_THREADS];
|
|
truncate (FILENAME, 0);
|
|
for (i = 0; i < NUM_THREADS; i++)
|
pthread_create (&threads[i], NULL, thread_start, (void *) i);
|
|
pthread_exit (NULL);
|
return 0;
|
}
|
|
This example creates three threads each of which loops five times,
|
appending to the file. Access to the file is serialized via open file
|
description locks. If we compile and run the above program, we’ll end
|
up with /tmp/foo that has 15 lines in it.
|
|
If we, however, were to replace the ‘F_OFD_SETLK’ and ‘F_OFD_SETLKW’
|
commands with their process-associated lock equivalents, the locking
|
essentially becomes a noop since it is all done within the context of
|
the same process. That leads to data corruption (typically manifested
|
as missing lines) as some threads race in and overwrite the data written
|
by others.
|
|
|
File: libc.info, Node: Interrupt Input, Next: IOCTLs, Prev: Open File Description Locks Example, Up: Low-Level I/O
|
|
13.19 Interrupt-Driven Input
|
============================
|
|
If you set the ‘O_ASYNC’ status flag on a file descriptor (*note File
|
Status Flags::), a ‘SIGIO’ signal is sent whenever input or output
|
becomes possible on that file descriptor. The process or process group
|
to receive the signal can be selected by using the ‘F_SETOWN’ command to
|
the ‘fcntl’ function. If the file descriptor is a socket, this also
|
selects the recipient of ‘SIGURG’ signals that are delivered when
|
out-of-band data arrives on that socket; see *note Out-of-Band Data::.
|
(‘SIGURG’ is sent in any situation where ‘select’ would report the
|
socket as having an “exceptional condition”. *Note Waiting for I/O::.)
|
|
If the file descriptor corresponds to a terminal device, then ‘SIGIO’
|
signals are sent to the foreground process group of the terminal. *Note
|
Job Control::.
|
|
The symbols in this section are defined in the header file ‘fcntl.h’.
|
|
-- Macro: int F_GETOWN
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should get information about the process or process group
|
to which ‘SIGIO’ signals are sent. (For a terminal, this is
|
actually the foreground process group ID, which you can get using
|
‘tcgetpgrp’; see *note Terminal Access Functions::.)
|
|
The return value is interpreted as a process ID; if negative, its
|
absolute value is the process group ID.
|
|
The following ‘errno’ error condition is defined for this command:
|
|
‘EBADF’
|
The FILEDES argument is invalid.
|
|
-- Macro: int F_SETOWN
|
|
This macro is used as the COMMAND argument to ‘fcntl’, to specify
|
that it should set the process or process group to which ‘SIGIO’
|
signals are sent. This command requires a third argument of type
|
‘pid_t’ to be passed to ‘fcntl’, so that the form of the call is:
|
|
fcntl (FILEDES, F_SETOWN, PID)
|
|
The PID argument should be a process ID. You can also pass a
|
negative number whose absolute value is a process group ID.
|
|
The return value from ‘fcntl’ with this command is -1 in case of
|
error and some other value if successful. The following ‘errno’
|
error conditions are defined for this command:
|
|
‘EBADF’
|
The FILEDES argument is invalid.
|
|
‘ESRCH’
|
There is no process or process group corresponding to PID.
|
|
|
File: libc.info, Node: IOCTLs, Prev: Interrupt Input, Up: Low-Level I/O
|
|
13.20 Generic I/O Control operations
|
====================================
|
|
GNU systems can handle most input/output operations on many different
|
devices and objects in terms of a few file primitives - ‘read’, ‘write’
|
and ‘lseek’. However, most devices also have a few peculiar operations
|
which do not fit into this model. Such as:
|
|
• Changing the character font used on a terminal.
|
|
• Telling a magnetic tape system to rewind or fast forward. (Since
|
they cannot move in byte increments, ‘lseek’ is inapplicable).
|
|
• Ejecting a disk from a drive.
|
|
• Playing an audio track from a CD-ROM drive.
|
|
• Maintaining routing tables for a network.
|
|
Although some such objects such as sockets and terminals (1) have
|
special functions of their own, it would not be practical to create
|
functions for all these cases.
|
|
Instead these minor operations, known as "IOCTL"s, are assigned code
|
numbers and multiplexed through the ‘ioctl’ function, defined in
|
‘sys/ioctl.h’. The code numbers themselves are defined in many
|
different headers.
|
|
-- Function: int ioctl (int FILEDES, int COMMAND, …)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘ioctl’ function performs the generic I/O operation COMMAND on
|
FILEDES.
|
|
A third argument is usually present, either a single number or a
|
pointer to a structure. The meaning of this argument, the returned
|
value, and any error codes depends upon the command used. Often -1
|
is returned for a failure.
|
|
On some systems, IOCTLs used by different devices share the same
|
numbers. Thus, although use of an inappropriate IOCTL _usually_ only
|
produces an error, you should not attempt to use device-specific IOCTLs
|
on an unknown device.
|
|
Most IOCTLs are OS-specific and/or only used in special system
|
utilities, and are thus beyond the scope of this document. For an
|
example of the use of an IOCTL, see *note Out-of-Band Data::.
|
|
---------- Footnotes ----------
|
|
(1) Actually, the terminal-specific functions are implemented with
|
IOCTLs on many platforms.
|
|
|
File: libc.info, Node: File System Interface, Next: Pipes and FIFOs, Prev: Low-Level I/O, Up: Top
|
|
14 File System Interface
|
************************
|
|
This chapter describes the GNU C Library’s functions for manipulating
|
files. Unlike the input and output functions (*note I/O on Streams::;
|
*note Low-Level I/O::), these functions are concerned with operating on
|
the files themselves rather than on their contents.
|
|
Among the facilities described in this chapter are functions for
|
examining or modifying directories, functions for renaming and deleting
|
files, and functions for examining and setting file attributes such as
|
access permissions and modification times.
|
|
* Menu:
|
|
* Working Directory:: This is used to resolve relative
|
file names.
|
* Accessing Directories:: Finding out what files a directory
|
contains.
|
* Working with Directory Trees:: Apply actions to all files or a selectable
|
subset of a directory hierarchy.
|
* Hard Links:: Adding alternate names to a file.
|
* Symbolic Links:: A file that “points to” a file name.
|
* Deleting Files:: How to delete a file, and what that means.
|
* Renaming Files:: Changing a file’s name.
|
* Creating Directories:: A system call just for creating a directory.
|
* File Attributes:: Attributes of individual files.
|
* Making Special Files:: How to create special files.
|
* Temporary Files:: Naming and creating temporary files.
|
|
|
File: libc.info, Node: Working Directory, Next: Accessing Directories, Up: File System Interface
|
|
14.1 Working Directory
|
======================
|
|
Each process has associated with it a directory, called its "current
|
working directory" or simply "working directory", that is used in the
|
resolution of relative file names (*note File Name Resolution::).
|
|
When you log in and begin a new session, your working directory is
|
initially set to the home directory associated with your login account
|
in the system user database. You can find any user’s home directory
|
using the ‘getpwuid’ or ‘getpwnam’ functions; see *note User Database::.
|
|
Users can change the working directory using shell commands like
|
‘cd’. The functions described in this section are the primitives used
|
by those commands and by other programs for examining and changing the
|
working directory.
|
|
Prototypes for these functions are declared in the header file
|
‘unistd.h’.
|
|
-- Function: char * getcwd (char *BUFFER, size_t SIZE)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
The ‘getcwd’ function returns an absolute file name representing
|
the current working directory, storing it in the character array
|
BUFFER that you provide. The SIZE argument is how you tell the
|
system the allocation size of BUFFER.
|
|
The GNU C Library version of this function also permits you to
|
specify a null pointer for the BUFFER argument. Then ‘getcwd’
|
allocates a buffer automatically, as with ‘malloc’ (*note
|
Unconstrained Allocation::). If the SIZE is greater than zero,
|
then the buffer is that large; otherwise, the buffer is as large as
|
necessary to hold the result.
|
|
The return value is BUFFER on success and a null pointer on
|
failure. The following ‘errno’ error conditions are defined for
|
this function:
|
|
‘EINVAL’
|
The SIZE argument is zero and BUFFER is not a null pointer.
|
|
‘ERANGE’
|
The SIZE argument is less than the length of the working
|
directory name. You need to allocate a bigger array and try
|
again.
|
|
‘EACCES’
|
Permission to read or search a component of the file name was
|
denied.
|
|
You could implement the behavior of GNU’s ‘getcwd (NULL, 0)’ using
|
only the standard behavior of ‘getcwd’:
|
|
char *
|
gnu_getcwd ()
|
{
|
size_t size = 100;
|
|
while (1)
|
{
|
char *buffer = (char *) xmalloc (size);
|
if (getcwd (buffer, size) == buffer)
|
return buffer;
|
free (buffer);
|
if (errno != ERANGE)
|
return 0;
|
size *= 2;
|
}
|
}
|
|
*Note Malloc Examples::, for information about ‘xmalloc’, which is not a
|
library function but is a customary name used in most GNU software.
|
|
-- Deprecated Function: char * getwd (char *BUFFER)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap i18n | AC-Unsafe mem fd |
|
*Note POSIX Safety Concepts::.
|
|
This is similar to ‘getcwd’, but has no way to specify the size of
|
the buffer. The GNU C Library provides ‘getwd’ only for backwards
|
compatibility with BSD.
|
|
The BUFFER argument should be a pointer to an array at least
|
‘PATH_MAX’ bytes long (*note Limits for Files::). On GNU/Hurd
|
systems there is no limit to the size of a file name, so this is
|
not necessarily enough space to contain the directory name. That
|
is why this function is deprecated.
|
|
-- Function: char * get_current_dir_name (void)
|
|
Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem fd |
|
*Note POSIX Safety Concepts::.
|
|
The ‘get_current_dir_name’ function is basically equivalent to
|
‘getcwd (NULL, 0)’, except the value of the ‘PWD’ environment
|
variable is first examined, and if it does in fact correspond to
|
the current directory, that value is returned. This is a subtle
|
difference which is visible if the path described by the value in
|
‘PWD’ is using one or more symbolic links, in which case the value
|
returned by ‘getcwd’ would resolve the symbolic links and therefore
|
yield a different result.
|
|
This function is a GNU extension.
|
|
-- Function: int chdir (const char *FILENAME)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is used to set the process’s working directory to
|
FILENAME.
|
|
The normal, successful return value from ‘chdir’ is ‘0’. A value
|
of ‘-1’ is returned to indicate an error. The ‘errno’ error
|
conditions defined for this function are the usual file name syntax
|
errors (*note File Name Errors::), plus ‘ENOTDIR’ if the file
|
FILENAME is not a directory.
|
|
-- Function: int fchdir (int FILEDES)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is used to set the process’s working directory to
|
directory associated with the file descriptor FILEDES.
|
|
The normal, successful return value from ‘fchdir’ is ‘0’. A value
|
of ‘-1’ is returned to indicate an error. The following ‘errno’
|
error conditions are defined for this function:
|
|
‘EACCES’
|
Read permission is denied for the directory named by
|
‘dirname’.
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor.
|
|
‘ENOTDIR’
|
The file descriptor FILEDES is not associated with a
|
directory.
|
|
‘EINTR’
|
The function call was interrupt by a signal.
|
|
‘EIO’
|
An I/O error occurred.
|
|
|
File: libc.info, Node: Accessing Directories, Next: Working with Directory Trees, Prev: Working Directory, Up: File System Interface
|
|
14.2 Accessing Directories
|
==========================
|
|
The facilities described in this section let you read the contents of a
|
directory file. This is useful if you want your program to list all the
|
files in a directory, perhaps as part of a menu.
|
|
The ‘opendir’ function opens a "directory stream" whose elements are
|
directory entries. Alternatively ‘fdopendir’ can be used which can have
|
advantages if the program needs to have more control over the way the
|
directory is opened for reading. This allows, for instance, to pass the
|
‘O_NOATIME’ flag to ‘open’.
|
|
You use the ‘readdir’ function on the directory stream to retrieve
|
these entries, represented as ‘struct dirent’ objects. The name of the
|
file for each entry is stored in the ‘d_name’ member of this structure.
|
There are obvious parallels here to the stream facilities for ordinary
|
files, described in *note I/O on Streams::.
|
|
* Menu:
|
|
* Directory Entries:: Format of one directory entry.
|
* Opening a Directory:: How to open a directory stream.
|
* Reading/Closing Directory:: How to read directory entries from the stream.
|
* Simple Directory Lister:: A very simple directory listing program.
|
* Random Access Directory:: Rereading part of the directory
|
already read with the same stream.
|
* Scanning Directory Content:: Get entries for user selected subset of
|
contents in given directory.
|
* Simple Directory Lister Mark II:: Revised version of the program.
|
* Low-level Directory Access:: AS-Safe functions for directory access.
|
|
|
File: libc.info, Node: Directory Entries, Next: Opening a Directory, Up: Accessing Directories
|
|
14.2.1 Format of a Directory Entry
|
----------------------------------
|
|
This section describes what you find in a single directory entry, as you
|
might obtain it from a directory stream. All the symbols are declared
|
in the header file ‘dirent.h’.
|
|
-- Data Type: struct dirent
|
|
This is a structure type used to return information about directory
|
entries. It contains the following fields:
|
|
‘char d_name[]’
|
This is the null-terminated file name component. This is the
|
only field you can count on in all POSIX systems.
|
|
‘ino_t d_fileno’
|
This is the file serial number. For BSD compatibility, you
|
can also refer to this member as ‘d_ino’. On GNU/Linux and
|
GNU/Hurd systems and most POSIX systems, for most files this
|
the same as the ‘st_ino’ member that ‘stat’ will return for
|
the file. *Note File Attributes::.
|
|
‘unsigned char d_namlen’
|
This is the length of the file name, not including the
|
terminating null character. Its type is ‘unsigned char’
|
because that is the integer type of the appropriate size.
|
This member is a BSD extension. The symbol
|
‘_DIRENT_HAVE_D_NAMLEN’ is defined if this member is
|
available.
|
|
‘unsigned char d_type’
|
This is the type of the file, possibly unknown. The following
|
constants are defined for its value:
|
|
‘DT_UNKNOWN’
|
The type is unknown. Only some filesystems have full
|
support to return the type of the file, others might
|
always return this value.
|
|
‘DT_REG’
|
A regular file.
|
|
‘DT_DIR’
|
A directory.
|
|
‘DT_FIFO’
|
A named pipe, or FIFO. *Note FIFO Special Files::.
|
|
‘DT_SOCK’
|
A local-domain socket.
|
|
‘DT_CHR’
|
A character device.
|
|
‘DT_BLK’
|
A block device.
|
|
‘DT_LNK’
|
A symbolic link.
|
|
This member is a BSD extension. The symbol
|
‘_DIRENT_HAVE_D_TYPE’ is defined if this member is available.
|
On systems where it is used, it corresponds to the file type
|
bits in the ‘st_mode’ member of ‘struct stat’. If the value
|
cannot be determined the member value is DT_UNKNOWN. These two
|
macros convert between ‘d_type’ values and ‘st_mode’ values:
|
|
-- Function: int IFTODT (mode_t MODE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This returns the ‘d_type’ value corresponding to MODE.
|
|
-- Function: mode_t DTTOIF (int DTYPE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This returns the ‘st_mode’ value corresponding to DTYPE.
|
|
This structure may contain additional members in the future. Their
|
availability is always announced in the compilation environment by
|
a macro named ‘_DIRENT_HAVE_D_XXX’ where XXX is replaced by the
|
name of the new member. For instance, the member ‘d_reclen’
|
available on some systems is announced through the macro
|
‘_DIRENT_HAVE_D_RECLEN’.
|
|
When a file has multiple names, each name has its own directory
|
entry. The only way you can tell that the directory entries belong
|
to a single file is that they have the same value for the
|
‘d_fileno’ field.
|
|
File attributes such as size, modification times etc., are part of
|
the file itself, not of any particular directory entry. *Note File
|
Attributes::.
|
|
|
File: libc.info, Node: Opening a Directory, Next: Reading/Closing Directory, Prev: Directory Entries, Up: Accessing Directories
|
|
14.2.2 Opening a Directory Stream
|
---------------------------------
|
|
This section describes how to open a directory stream. All the symbols
|
are declared in the header file ‘dirent.h’.
|
|
-- Data Type: DIR
|
|
The ‘DIR’ data type represents a directory stream.
|
|
You shouldn’t ever allocate objects of the ‘struct dirent’ or ‘DIR’
|
data types, since the directory access functions do that for you.
|
Instead, you refer to these objects using the pointers returned by the
|
following functions.
|
|
Directory streams are a high-level interface. On Linux, alternative
|
interfaces for accessing directories using file descriptors are
|
available. *Note Low-level Directory Access::.
|
|
-- Function: DIR * opendir (const char *DIRNAME)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
The ‘opendir’ function opens and returns a directory stream for
|
reading the directory whose file name is DIRNAME. The stream has
|
type ‘DIR *’.
|
|
If unsuccessful, ‘opendir’ returns a null pointer. In addition to
|
the usual file name errors (*note File Name Errors::), the
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EACCES’
|
Read permission is denied for the directory named by
|
‘dirname’.
|
|
‘EMFILE’
|
The process has too many files open.
|
|
‘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.)
|
|
‘ENOMEM’
|
Not enough memory available.
|
|
The ‘DIR’ type is typically implemented using a file descriptor,
|
and the ‘opendir’ function in terms of the ‘open’ function. *Note
|
Low-Level I/O::. Directory streams and the underlying file
|
descriptors are closed on ‘exec’ (*note Executing a File::).
|
|
The directory which is opened for reading by ‘opendir’ is identified
|
by the name. In some situations this is not sufficient. Or the way
|
‘opendir’ implicitly creates a file descriptor for the directory is not
|
the way a program might want it. In these cases an alternative
|
interface can be used.
|
|
-- Function: DIR * fdopendir (int FD)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
The ‘fdopendir’ function works just like ‘opendir’ but instead of
|
taking a file name and opening a file descriptor for the directory
|
the caller is required to provide a file descriptor. This file
|
descriptor is then used in subsequent uses of the returned
|
directory stream object.
|
|
The caller must make sure the file descriptor is associated with a
|
directory and it allows reading.
|
|
If the ‘fdopendir’ call returns successfully the file descriptor is
|
now under the control of the system. It can be used in the same
|
way the descriptor implicitly created by ‘opendir’ can be used but
|
the program must not close the descriptor.
|
|
In case the function is unsuccessful it returns a null pointer and
|
the file descriptor remains to be usable by the program. The
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EBADF’
|
The file descriptor is not valid.
|
|
‘ENOTDIR’
|
The file descriptor is not associated with a directory.
|
|
‘EINVAL’
|
The descriptor does not allow reading the directory content.
|
|
‘ENOMEM’
|
Not enough memory available.
|
|
In some situations it can be desirable to get hold of the file
|
descriptor which is created by the ‘opendir’ call. For instance, to
|
switch the current working directory to the directory just read the
|
‘fchdir’ function could be used. Historically the ‘DIR’ type was
|
exposed and programs could access the fields. This does not happen in
|
the GNU C Library. Instead a separate function is provided to allow
|
access.
|
|
-- Function: int dirfd (DIR *DIRSTREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The function ‘dirfd’ returns the file descriptor associated with
|
the directory stream DIRSTREAM. This descriptor can be used until
|
the directory is closed with ‘closedir’. If the directory stream
|
implementation is not using file descriptors the return value is
|
‘-1’.
|
|
|
File: libc.info, Node: Reading/Closing Directory, Next: Simple Directory Lister, Prev: Opening a Directory, Up: Accessing Directories
|
|
14.2.3 Reading and Closing a Directory Stream
|
---------------------------------------------
|
|
This section describes how to read directory entries from a directory
|
stream, and how to close the stream when you are done with it. All the
|
symbols are declared in the header file ‘dirent.h’.
|
|
-- Function: struct dirent * readdir (DIR *DIRSTREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function reads the next entry from the directory. It normally
|
returns a pointer to a structure containing information about the
|
file. This structure is associated with the DIRSTREAM handle and
|
can be rewritten by a subsequent call.
|
|
*Portability Note:* On some systems ‘readdir’ may not return
|
entries for ‘.’ and ‘..’, even though these are always valid file
|
names in any directory. *Note File Name Resolution::.
|
|
If there are no more entries in the directory or an error is
|
detected, ‘readdir’ returns a null pointer. The following ‘errno’
|
error conditions are defined for this function:
|
|
‘EBADF’
|
The DIRSTREAM argument is not valid.
|
|
To distinguish between an end-of-directory condition or an error,
|
you must set ‘errno’ to zero before calling ‘readdir’. To avoid
|
entering an infinite loop, you should stop reading from the
|
directory after the first error.
|
|
*Caution:* The pointer returned by ‘readdir’ points to a buffer
|
within the ‘DIR’ object. The data in that buffer will be
|
overwritten by the next call to ‘readdir’. You must take care, for
|
instance, to copy the ‘d_name’ string if you need it later.
|
|
Because of this, it is not safe to share a ‘DIR’ object among
|
multiple threads, unless you use your own locking to ensure that no
|
thread calls ‘readdir’ while another thread is still using the data
|
from the previous call. In the GNU C Library, it is safe to call
|
‘readdir’ from multiple threads as long as each thread uses its own
|
‘DIR’ object. POSIX.1-2008 does not require this to be safe, but
|
we are not aware of any operating systems where it does not work.
|
|
‘readdir_r’ allows you to provide your own buffer for the ‘struct
|
dirent’, but it is less portable than ‘readdir’, and has problems
|
with very long filenames (see below). We recommend you use
|
‘readdir’, but do not share ‘DIR’ objects.
|
|
-- Function: int readdir_r (DIR *DIRSTREAM, struct dirent *ENTRY,
|
struct dirent **RESULT)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function is a version of ‘readdir’ which performs internal
|
locking. Like ‘readdir’ it returns the next entry from the
|
directory. To prevent conflicts between simultaneously running
|
threads the result is stored inside the ENTRY object.
|
|
*Portability Note:* ‘readdir_r’ is deprecated. It is recommended
|
to use ‘readdir’ instead of ‘readdir_r’ for the following reasons:
|
|
• On systems which do not define ‘NAME_MAX’, it may not be
|
possible to use ‘readdir_r’ safely because the caller does not
|
specify the length of the buffer for the directory entry.
|
|
• On some systems, ‘readdir_r’ cannot read directory entries
|
with very long names. If such a name is encountered, the GNU
|
C Library implementation of ‘readdir_r’ returns with an error
|
code of ‘ENAMETOOLONG’ after the final directory entry has
|
been read. On other systems, ‘readdir_r’ may return
|
successfully, but the ‘d_name’ member may not be
|
NUL-terminated or may be truncated.
|
|
• POSIX-1.2008 does not guarantee that ‘readdir’ is thread-safe,
|
even when access to the same DIRSTREAM is serialized. But in
|
current implementations (including the GNU C Library), it is
|
safe to call ‘readdir’ concurrently on different DIRSTREAMs,
|
so there is no need to use ‘readdir_r’ in most multi-threaded
|
programs. In the rare case that multiple threads need to read
|
from the same DIRSTREAM, it is still better to use ‘readdir’
|
and external synchronization.
|
|
• It is expected that future versions of POSIX will obsolete
|
‘readdir_r’ and mandate the level of thread safety for
|
‘readdir’ which is provided by the GNU C Library and other
|
implementations today.
|
|
Normally ‘readdir_r’ returns zero and sets ‘*RESULT’ to ENTRY. If
|
there are no more entries in the directory or an error is detected,
|
‘readdir_r’ sets ‘*RESULT’ to a null pointer and returns a nonzero
|
error code, also stored in ‘errno’, as described for ‘readdir’.
|
|
It is also important to look at the definition of the ‘struct
|
dirent’ type. Simply passing a pointer to an object of this type
|
for the second parameter of ‘readdir_r’ might not be enough. Some
|
systems don’t define the ‘d_name’ element sufficiently long. In
|
this case the user has to provide additional space. There must be
|
room for at least ‘NAME_MAX + 1’ characters in the ‘d_name’ array.
|
Code to call ‘readdir_r’ could look like this:
|
|
union
|
{
|
struct dirent d;
|
char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
|
} u;
|
|
if (readdir_r (dir, &u.d, &res) == 0)
|
…
|
|
To support large filesystems on 32-bit machines there are LFS
|
variants of the last two functions.
|
|
-- Function: struct dirent64 * readdir64 (DIR *DIRSTREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
The ‘readdir64’ function is just like the ‘readdir’ function except
|
that it returns a pointer to a record of type ‘struct dirent64’.
|
Some of the members of this data type (notably ‘d_ino’) might have
|
a different size to allow large filesystems.
|
|
In all other aspects this function is equivalent to ‘readdir’.
|
|
-- Function: int readdir64_r (DIR *DIRSTREAM, struct dirent64 *ENTRY,
|
struct dirent64 **RESULT)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
The deprecated ‘readdir64_r’ function is equivalent to the
|
‘readdir_r’ function except that it takes parameters of base type
|
‘struct dirent64’ instead of ‘struct dirent’ in the second and
|
third position. The same precautions mentioned in the
|
documentation of ‘readdir_r’ also apply here.
|
|
-- Function: int closedir (DIR *DIRSTREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock/hurd | AC-Unsafe mem
|
fd lock/hurd | *Note POSIX Safety Concepts::.
|
|
This function closes the directory stream DIRSTREAM. It returns
|
‘0’ on success and ‘-1’ on failure.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EBADF’
|
The DIRSTREAM argument is not valid.
|
|
|
File: libc.info, Node: Simple Directory Lister, Next: Random Access Directory, Prev: Reading/Closing Directory, Up: Accessing Directories
|
|
14.2.4 Simple Program to List a Directory
|
-----------------------------------------
|
|
Here’s a simple program that prints the names of the files in the
|
current working directory:
|
|
|
#include <stdio.h>
|
#include <sys/types.h>
|
#include <dirent.h>
|
|
int
|
main (void)
|
{
|
DIR *dp;
|
struct dirent *ep;
|
|
dp = opendir ("./");
|
if (dp != NULL)
|
{
|
while (ep = readdir (dp))
|
puts (ep->d_name);
|
(void) closedir (dp);
|
}
|
else
|
perror ("Couldn't open the directory");
|
|
return 0;
|
}
|
|
The order in which files appear in a directory tends to be fairly
|
random. A more useful program would sort the entries (perhaps by
|
alphabetizing them) before printing them; see *note Scanning Directory
|
Content::, and *note Array Sort Function::.
|
|
|
File: libc.info, Node: Random Access Directory, Next: Scanning Directory Content, Prev: Simple Directory Lister, Up: Accessing Directories
|
|
14.2.5 Random Access in a Directory Stream
|
------------------------------------------
|
|
This section describes how to reread parts of a directory that you have
|
already read from an open directory stream. All the symbols are
|
declared in the header file ‘dirent.h’.
|
|
-- Function: void rewinddir (DIR *DIRSTREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
The ‘rewinddir’ function is used to reinitialize the directory
|
stream DIRSTREAM, so that if you call ‘readdir’ it returns
|
information about the first entry in the directory again. This
|
function also notices if files have been added or removed to the
|
directory since it was opened with ‘opendir’. (Entries for these
|
files might or might not be returned by ‘readdir’ if they were
|
added or removed since you last called ‘opendir’ or ‘rewinddir’.)
|
|
-- Function: long int telldir (DIR *DIRSTREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap/bsd lock/bsd | AC-Unsafe
|
mem/bsd lock/bsd | *Note POSIX Safety Concepts::.
|
|
The ‘telldir’ function returns the file position of the directory
|
stream DIRSTREAM. You can use this value with ‘seekdir’ to restore
|
the directory stream to that position.
|
|
-- Function: void seekdir (DIR *DIRSTREAM, long int POS)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap/bsd lock/bsd | AC-Unsafe
|
mem/bsd lock/bsd | *Note POSIX Safety Concepts::.
|
|
The ‘seekdir’ function sets the file position of the directory
|
stream DIRSTREAM to POS. The value POS must be the result of a
|
previous call to ‘telldir’ on this particular stream; closing and
|
reopening the directory can invalidate values returned by
|
‘telldir’.
|
|
|
File: libc.info, Node: Scanning Directory Content, Next: Simple Directory Lister Mark II, Prev: Random Access Directory, Up: Accessing Directories
|
|
14.2.6 Scanning the Content of a Directory
|
------------------------------------------
|
|
A higher-level interface to the directory handling functions is the
|
‘scandir’ function. With its help one can select a subset of the
|
entries in a directory, possibly sort them and get a list of names as
|
the result.
|
|
-- Function: int scandir (const char *DIR, struct dirent ***NAMELIST,
|
int (*SELECTOR) (const struct dirent *), int (*CMP) (const
|
struct dirent **, const struct dirent **))
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
The ‘scandir’ function scans the contents of the directory selected
|
by DIR. The result in *NAMELIST is an array of pointers to
|
structures of type ‘struct dirent’ which describe all selected
|
directory entries and which is allocated using ‘malloc’. Instead
|
of always getting all directory entries returned, the user supplied
|
function SELECTOR can be used to decide which entries are in the
|
result. Only the entries for which SELECTOR returns a non-zero
|
value are selected.
|
|
Finally the entries in *NAMELIST are sorted using the user-supplied
|
function CMP. The arguments passed to the CMP function are of type
|
‘struct dirent **’, therefore one cannot directly use the ‘strcmp’
|
or ‘strcoll’ functions; instead see the functions ‘alphasort’ and
|
‘versionsort’ below.
|
|
The return value of the function is the number of entries placed in
|
*NAMELIST. If it is ‘-1’ an error occurred (either the directory
|
could not be opened for reading or the malloc call failed) and the
|
global variable ‘errno’ contains more information on the error.
|
|
As described above, the fourth argument to the ‘scandir’ function
|
must be a pointer to a sorting function. For the convenience of the
|
programmer the GNU C Library contains implementations of functions which
|
are very helpful for this purpose.
|
|
-- Function: int alphasort (const struct dirent **A, const struct
|
dirent **B)
|
|
Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
|
*Note POSIX Safety Concepts::.
|
|
The ‘alphasort’ function behaves like the ‘strcoll’ function (*note
|
String/Array Comparison::). The difference is that the arguments
|
are not string pointers but instead they are of type ‘struct dirent
|
**’.
|
|
The return value of ‘alphasort’ is less than, equal to, or greater
|
than zero depending on the order of the two entries A and B.
|
|
-- Function: int versionsort (const struct dirent **A, const struct
|
dirent **B)
|
|
Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
The ‘versionsort’ function is like ‘alphasort’ except that it uses
|
the ‘strverscmp’ function internally.
|
|
If the filesystem supports large files we cannot use the ‘scandir’
|
anymore since the ‘dirent’ structure might not able to contain all the
|
information. The LFS provides the new type ‘struct dirent64’. To use
|
this we need a new function.
|
|
-- Function: int scandir64 (const char *DIR, struct dirent64
|
***NAMELIST, int (*SELECTOR) (const struct dirent64 *), int
|
(*CMP) (const struct dirent64 **, const struct dirent64 **))
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
The ‘scandir64’ function works like the ‘scandir’ function except
|
that the directory entries it returns are described by elements of
|
type ‘struct dirent64’. The function pointed to by SELECTOR is
|
again used to select the desired entries, except that SELECTOR now
|
must point to a function which takes a ‘struct dirent64 *’
|
parameter.
|
|
Similarly the CMP function should expect its two arguments to be of
|
type ‘struct dirent64 **’.
|
|
As CMP is now a function of a different type, the functions
|
‘alphasort’ and ‘versionsort’ cannot be supplied for that argument.
|
Instead we provide the two replacement functions below.
|
|
-- Function: int alphasort64 (const struct dirent64 **A, const struct
|
dirent **B)
|
|
Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
|
*Note POSIX Safety Concepts::.
|
|
The ‘alphasort64’ function behaves like the ‘strcoll’ function
|
(*note String/Array Comparison::). The difference is that the
|
arguments are not string pointers but instead they are of type
|
‘struct dirent64 **’.
|
|
Return value of ‘alphasort64’ is less than, equal to, or greater
|
than zero depending on the order of the two entries A and B.
|
|
-- Function: int versionsort64 (const struct dirent64 **A, const struct
|
dirent64 **B)
|
|
Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
The ‘versionsort64’ function is like ‘alphasort64’, excepted that
|
it uses the ‘strverscmp’ function internally.
|
|
It is important not to mix the use of ‘scandir’ and the 64-bit
|
comparison functions or vice versa. There are systems on which this
|
works but on others it will fail miserably.
|
|
|
File: libc.info, Node: Simple Directory Lister Mark II, Next: Low-level Directory Access, Prev: Scanning Directory Content, Up: Accessing Directories
|
|
14.2.7 Simple Program to List a Directory, Mark II
|
--------------------------------------------------
|
|
Here is a revised version of the directory lister found above (*note
|
Simple Directory Lister::). Using the ‘scandir’ function we can avoid
|
the functions which work directly with the directory contents. After
|
the call the returned entries are available for direct use.
|
|
|
#include <stdio.h>
|
#include <dirent.h>
|
|
static int
|
one (const struct dirent *unused)
|
{
|
return 1;
|
}
|
|
int
|
main (void)
|
{
|
struct dirent **eps;
|
int n;
|
|
n = scandir ("./", &eps, one, alphasort);
|
if (n >= 0)
|
{
|
int cnt;
|
for (cnt = 0; cnt < n; ++cnt)
|
puts (eps[cnt]->d_name);
|
}
|
else
|
perror ("Couldn't open the directory");
|
|
return 0;
|
}
|
|
Note the simple selector function in this example. Since we want to
|
see all directory entries we always return ‘1’.
|
|
|
File: libc.info, Node: Low-level Directory Access, Prev: Simple Directory Lister Mark II, Up: Accessing Directories
|
|
14.2.8 Low-level Directory Access
|
---------------------------------
|
|
The stream-based directory functions are not AS-Safe and cannot be used
|
after ‘vfork’. *Note POSIX Safety Concepts::. The functions below
|
provide an alternative that can be used in these contexts.
|
|
Directory data is obtained from a file descriptor, as created by the
|
‘open’ function, with or without the ‘O_DIRECTORY’ flag. *Note Opening
|
and Closing Files::.
|
|
-- Function: ssize_t getdents64 (int FD, void *BUFFER, size_t LENGTH)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getdents64’ function reads at most LENGTH bytes of directory
|
entry data from the file descriptor FD and stores it into the byte
|
array starting at BUFFER.
|
|
On success, the function returns the number of bytes written to the
|
buffer. This number is zero if FD is already at the end of the
|
directory stream. On error, the function returns ‘-1’ and sets
|
‘errno’ to the appropriate error code.
|
|
The data is stored as a sequence of ‘struct dirent64’ records,
|
which can be traversed using the ‘d_reclen’ member. The buffer
|
should be large enough to hold the largest possible directory
|
entry. Note that some file systems support file names longer than
|
‘NAME_MAX’ bytes (e.g., because they support up to 255 Unicode
|
characters), so a buffer size of at least 1024 is recommended.
|
|
This function is specific to Linux.
|
|
|
File: libc.info, Node: Working with Directory Trees, Next: Hard Links, Prev: Accessing Directories, Up: File System Interface
|
|
14.3 Working with Directory Trees
|
=================================
|
|
The functions described so far for handling the files in a directory
|
have allowed you to either retrieve the information bit by bit, or to
|
process all the files as a group (see ‘scandir’). Sometimes it is
|
useful to process whole hierarchies of directories and their contained
|
files. The X/Open specification defines two functions to do this. The
|
simpler form is derived from an early definition in System V systems and
|
therefore this function is available on SVID-derived systems. The
|
prototypes and required definitions can be found in the ‘ftw.h’ header.
|
|
There are four functions in this family: ‘ftw’, ‘nftw’ and their
|
64-bit counterparts ‘ftw64’ and ‘nftw64’. These functions take as one
|
of their arguments a pointer to a callback function of the appropriate
|
type.
|
|
-- Data Type: __ftw_func_t
|
|
int (*) (const char *, const struct stat *, int)
|
|
The type of callback functions given to the ‘ftw’ function. The
|
first parameter points to the file name, the second parameter to an
|
object of type ‘struct stat’ which is filled in for the file named
|
in the first parameter.
|
|
The last parameter is a flag giving more information about the
|
current file. It can have the following values:
|
|
‘FTW_F’
|
The item is either a normal file or a file which does not fit
|
into one of the following categories. This could be special
|
files, sockets etc.
|
‘FTW_D’
|
The item is a directory.
|
‘FTW_NS’
|
The ‘stat’ call failed and so the information pointed to by
|
the second parameter is invalid.
|
‘FTW_DNR’
|
The item is a directory which cannot be read.
|
‘FTW_SL’
|
The item is a symbolic link. Since symbolic links are
|
normally followed seeing this value in a ‘ftw’ callback
|
function means the referenced file does not exist. The
|
situation for ‘nftw’ is different.
|
|
This value is only available if the program is compiled with
|
‘_XOPEN_EXTENDED’ defined before including the first header.
|
The original SVID systems do not have symbolic links.
|
|
If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
type is in fact ‘__ftw64_func_t’ since this mode changes ‘struct
|
stat’ to be ‘struct stat64’.
|
|
For the LFS interface and for use in the function ‘ftw64’, the header
|
‘ftw.h’ defines another function type.
|
|
-- Data Type: __ftw64_func_t
|
|
int (*) (const char *, const struct stat64 *, int)
|
|
This type is used just like ‘__ftw_func_t’ for the callback
|
function, but this time is called from ‘ftw64’. The second
|
parameter to the function is a pointer to a variable of type
|
‘struct stat64’ which is able to represent the larger values.
|
|
-- Data Type: __nftw_func_t
|
|
int (*) (const char *, const struct stat *, int, struct FTW *)
|
|
The first three arguments are the same as for the ‘__ftw_func_t’
|
type. However for the third argument some additional values are
|
defined to allow finer differentiation:
|
‘FTW_DP’
|
The current item is a directory and all subdirectories have
|
already been visited and reported. This flag is returned
|
instead of ‘FTW_D’ if the ‘FTW_DEPTH’ flag is passed to ‘nftw’
|
(see below).
|
‘FTW_SLN’
|
The current item is a stale symbolic link. The file it points
|
to does not exist.
|
|
The last parameter of the callback function is a pointer to a
|
structure with some extra information as described below.
|
|
If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
type is in fact ‘__nftw64_func_t’ since this mode changes ‘struct
|
stat’ to be ‘struct stat64’.
|
|
For the LFS interface there is also a variant of this data type
|
available which has to be used with the ‘nftw64’ function.
|
|
-- Data Type: __nftw64_func_t
|
|
int (*) (const char *, const struct stat64 *, int, struct FTW *)
|
|
This type is used just like ‘__nftw_func_t’ for the callback
|
function, but this time is called from ‘nftw64’. The second
|
parameter to the function is this time a pointer to a variable of
|
type ‘struct stat64’ which is able to represent the larger values.
|
|
-- Data Type: struct FTW
|
|
The information contained in this structure helps in interpreting
|
the name parameter and gives some information about the current
|
state of the traversal of the directory hierarchy.
|
|
‘int base’
|
The value is the offset into the string passed in the first
|
parameter to the callback function of the beginning of the
|
file name. The rest of the string is the path of the file.
|
This information is especially important if the ‘FTW_CHDIR’
|
flag was set in calling ‘nftw’ since then the current
|
directory is the one the current item is found in.
|
‘int level’
|
Whilst processing, the code tracks how many directories down
|
it has gone to find the current file. This nesting level
|
starts at 0 for files in the initial directory (or is zero for
|
the initial file if a file was passed).
|
|
-- Function: int ftw (const char *FILENAME, __ftw_func_t FUNC, int
|
DESCRIPTORS)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
The ‘ftw’ function calls the callback function given in the
|
parameter FUNC for every item which is found in the directory
|
specified by FILENAME and all directories below. The function
|
follows symbolic links if necessary but does not process an item
|
twice. If FILENAME is not a directory then it itself is the only
|
object returned to the callback function.
|
|
The file name passed to the callback function is constructed by
|
taking the FILENAME parameter and appending the names of all passed
|
directories and then the local file name. So the callback function
|
can use this parameter to access the file. ‘ftw’ also calls ‘stat’
|
for the file and passes that information on to the callback
|
function. If this ‘stat’ call is not successful the failure is
|
indicated by setting the third argument of the callback function to
|
‘FTW_NS’. Otherwise it is set according to the description given
|
in the account of ‘__ftw_func_t’ above.
|
|
The callback function is expected to return 0 to indicate that no
|
error occurred and that processing should continue. If an error
|
occurred in the callback function or it wants ‘ftw’ to return
|
immediately, the callback function can return a value other than 0.
|
This is the only correct way to stop the function. The program
|
must not use ‘setjmp’ or similar techniques to continue from
|
another place. This would leave resources allocated by the ‘ftw’
|
function unfreed.
|
|
The DESCRIPTORS parameter to ‘ftw’ specifies how many file
|
descriptors it is allowed to consume. The function runs faster the
|
more descriptors it can use. For each level in the directory
|
hierarchy at most one descriptor is used, but for very deep ones
|
any limit on open file descriptors for the process or the system
|
may be exceeded. Moreover, file descriptor limits in a
|
multi-threaded program apply to all the threads as a group, and
|
therefore it is a good idea to supply a reasonable limit to the
|
number of open descriptors.
|
|
The return value of the ‘ftw’ function is 0 if all callback
|
function calls returned 0 and all actions performed by the ‘ftw’
|
succeeded. If a function call failed (other than calling ‘stat’ on
|
an item) the function returns -1. If a callback function returns a
|
value other than 0 this value is returned as the return value of
|
‘ftw’.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32-bit system this function is in fact ‘ftw64’, i.e., the LFS
|
interface transparently replaces the old interface.
|
|
-- Function: int ftw64 (const char *FILENAME, __ftw64_func_t FUNC, int
|
DESCRIPTORS)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
This function is similar to ‘ftw’ but it can work on filesystems
|
with large files. File information is reported using a variable of
|
type ‘struct stat64’ which is passed by reference to the callback
|
function.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32-bit system this function is available under the name ‘ftw’ and
|
transparently replaces the old implementation.
|
|
-- Function: int nftw (const char *FILENAME, __nftw_func_t FUNC, int
|
DESCRIPTORS, int FLAG)
|
|
Preliminary: | MT-Safe cwd | AS-Unsafe heap | AC-Unsafe mem fd cwd
|
| *Note POSIX Safety Concepts::.
|
|
The ‘nftw’ function works like the ‘ftw’ functions. They call the
|
callback function FUNC for all items found in the directory
|
FILENAME and below. At most DESCRIPTORS file descriptors are
|
consumed during the ‘nftw’ call.
|
|
One difference is that the callback function is of a different
|
type. It is of type ‘struct FTW *’ and provides the callback
|
function with the extra information described above.
|
|
A second difference is that ‘nftw’ takes a fourth argument, which
|
is 0 or a bitwise-OR combination of any of the following values.
|
|
‘FTW_PHYS’
|
While traversing the directory symbolic links are not
|
followed. Instead symbolic links are reported using the
|
‘FTW_SL’ value for the type parameter to the callback
|
function. If the file referenced by a symbolic link does not
|
exist ‘FTW_SLN’ is returned instead.
|
‘FTW_MOUNT’
|
The callback function is only called for items which are on
|
the same mounted filesystem as the directory given by the
|
FILENAME parameter to ‘nftw’.
|
‘FTW_CHDIR’
|
If this flag is given the current working directory is changed
|
to the directory of the reported object before the callback
|
function is called. When ‘ntfw’ finally returns the current
|
directory is restored to its original value.
|
‘FTW_DEPTH’
|
If this option is specified then all subdirectories and files
|
within them are processed before processing the top directory
|
itself (depth-first processing). This also means the type
|
flag given to the callback function is ‘FTW_DP’ and not
|
‘FTW_D’.
|
‘FTW_ACTIONRETVAL’
|
If this option is specified then return values from callbacks
|
are handled differently. If the callback returns
|
‘FTW_CONTINUE’, walking continues normally. ‘FTW_STOP’ means
|
walking stops and ‘FTW_STOP’ is returned to the caller. If
|
‘FTW_SKIP_SUBTREE’ is returned by the callback with ‘FTW_D’
|
argument, the subtree is skipped and walking continues with
|
next sibling of the directory. If ‘FTW_SKIP_SIBLINGS’ is
|
returned by the callback, all siblings of the current entry
|
are skipped and walking continues in its parent. No other
|
return values should be returned from the callbacks if this
|
option is set. This option is a GNU extension.
|
|
The return value is computed in the same way as for ‘ftw’. ‘nftw’
|
returns 0 if no failures occurred and all callback functions
|
returned 0. In case of internal errors, such as memory problems,
|
the return value is -1 and ‘errno’ is set accordingly. If the
|
return value of a callback invocation was non-zero then that value
|
is returned.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32-bit system this function is in fact ‘nftw64’, i.e., the LFS
|
interface transparently replaces the old interface.
|
|
-- Function: int nftw64 (const char *FILENAME, __nftw64_func_t FUNC,
|
int DESCRIPTORS, int FLAG)
|
|
Preliminary: | MT-Safe cwd | AS-Unsafe heap | AC-Unsafe mem fd cwd
|
| *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘nftw’ but it can work on filesystems
|
with large files. File information is reported using a variable of
|
type ‘struct stat64’ which is passed by reference to the callback
|
function.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32-bit system this function is available under the name ‘nftw’ and
|
transparently replaces the old implementation.
|
|
|
File: libc.info, Node: Hard Links, Next: Symbolic Links, Prev: Working with Directory Trees, Up: File System Interface
|
|
14.4 Hard Links
|
===============
|
|
In POSIX systems, one file can have many names at the same time. All of
|
the names are equally real, and no one of them is preferred to the
|
others.
|
|
To add a name to a file, use the ‘link’ function. (The new name is
|
also called a "hard link" to the file.) Creating a new link to a file
|
does not copy the contents of the file; it simply makes a new name by
|
which the file can be known, in addition to the file’s existing name or
|
names.
|
|
One file can have names in several directories, so the organization
|
of the file system is not a strict hierarchy or tree.
|
|
In most implementations, it is not possible to have hard links to the
|
same file in multiple file systems. ‘link’ reports an error if you try
|
to make a hard link to the file from another file system when this
|
cannot be done.
|
|
The prototype for the ‘link’ function is declared in the header file
|
‘unistd.h’.
|
|
-- Function: int link (const char *OLDNAME, const char *NEWNAME)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘link’ function makes a new link to the existing file named by
|
OLDNAME, under the new name NEWNAME.
|
|
This function returns a value of ‘0’ if it is successful and ‘-1’
|
on failure. In addition to the usual file name errors (*note File
|
Name Errors::) for both OLDNAME and NEWNAME, the following ‘errno’
|
error conditions are defined for this function:
|
|
‘EACCES’
|
You are not allowed to write to the directory in which the new
|
link is to be written.
|
|
‘EEXIST’
|
There is already a file named NEWNAME. If you want to replace
|
this link with a new link, you must remove the old link
|
explicitly first.
|
|
‘EMLINK’
|
There are already too many links to the file named by OLDNAME.
|
(The maximum number of links to a file is ‘LINK_MAX’; see
|
*note Limits for Files::.)
|
|
‘ENOENT’
|
The file named by OLDNAME doesn’t exist. You can’t make a
|
link to a file that doesn’t exist.
|
|
‘ENOSPC’
|
The directory or file system that would contain the new link
|
is full and cannot be extended.
|
|
‘EPERM’
|
On GNU/Linux and GNU/Hurd systems and some others, you cannot
|
make links to directories. Many systems allow only privileged
|
users to do so. This error is used to report the problem.
|
|
‘EROFS’
|
The directory containing the new link can’t be modified
|
because it’s on a read-only file system.
|
|
‘EXDEV’
|
The directory specified in NEWNAME is on a different file
|
system than the existing file.
|
|
‘EIO’
|
A hardware error occurred while trying to read or write the to
|
filesystem.
|
|
-- Function: int linkat (int oldfd, const char *OLDNAME, int newfd,
|
const char *NEWNAME, int flags)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘linkat’ function is analogous to the ‘link’ function, except
|
that it identifies its source and target using a combination of a
|
file descriptor (referring to a directory) and a pathname. If a
|
pathnames is not absolute, it is resolved relative to the
|
corresponding file descriptor. The special file descriptor
|
‘AT_FDCWD’ denotes the current directory.
|
|
The FLAGS argument is a combination of the following flags:
|
|
‘AT_SYMLINK_FOLLOW’
|
If the source path identified by OLDFD and OLDNAME is a
|
symbolic link, ‘linkat’ follows the symbolic link and creates
|
a link to its target. If the flag is not set, a link for the
|
symbolic link itself is created; this is not supported by all
|
file systems and ‘linkat’ can fail in this case.
|
|
‘AT_EMPTY_PATH’
|
If this flag is specified, OLDNAME can be an empty string. In
|
this case, a new link to the file denoted by the descriptor
|
OLDFD is created, which may have been opened with ‘O_PATH’ or
|
‘O_TMPFILE’. This flag is a GNU extension.
|
|
|
File: libc.info, Node: Symbolic Links, Next: Deleting Files, Prev: Hard Links, Up: File System Interface
|
|
14.5 Symbolic Links
|
===================
|
|
GNU systems support "soft links" or "symbolic links". This is a kind of
|
“file” that is essentially a pointer to another file name. Unlike hard
|
links, symbolic links can be made to directories or across file systems
|
with no restrictions. You can also make a symbolic link to a name which
|
is not the name of any file. (Opening this link will fail until a file
|
by that name is created.) Likewise, if the symbolic link points to an
|
existing file which is later deleted, the symbolic link continues to
|
point to the same file name even though the name no longer names any
|
file.
|
|
The reason symbolic links work the way they do is that special things
|
happen when you try to open the link. The ‘open’ function realizes you
|
have specified the name of a link, reads the file name contained in the
|
link, and opens that file name instead. The ‘stat’ function likewise
|
operates on the file that the symbolic link points to, instead of on the
|
link itself.
|
|
By contrast, other operations such as deleting or renaming the file
|
operate on the link itself. The functions ‘readlink’ and ‘lstat’ also
|
refrain from following symbolic links, because their purpose is to
|
obtain information about the link. ‘link’, the function that makes a
|
hard link, does too. It makes a hard link to the symbolic link, which
|
one rarely wants.
|
|
Some systems have, for some functions operating on files, a limit on
|
how many symbolic links are followed when resolving a path name. The
|
limit if it exists is published in the ‘sys/param.h’ header file.
|
|
-- Macro: int MAXSYMLINKS
|
|
The macro ‘MAXSYMLINKS’ specifies how many symlinks some function
|
will follow before returning ‘ELOOP’. Not all functions behave the
|
same and this value is not the same as that returned for
|
‘_SC_SYMLOOP’ by ‘sysconf’. In fact, the ‘sysconf’ result can
|
indicate that there is no fixed limit although ‘MAXSYMLINKS’ exists
|
and has a finite value.
|
|
Prototypes for most of the functions listed in this section are in
|
‘unistd.h’.
|
|
-- Function: int symlink (const char *OLDNAME, const char *NEWNAME)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘symlink’ function makes a symbolic link to OLDNAME named
|
NEWNAME.
|
|
The normal return value from ‘symlink’ is ‘0’. A return value of
|
‘-1’ indicates an error. In addition to the usual file name syntax
|
errors (*note File Name Errors::), the following ‘errno’ error
|
conditions are defined for this function:
|
|
‘EEXIST’
|
There is already an existing file named NEWNAME.
|
|
‘EROFS’
|
The file NEWNAME would exist on a read-only file system.
|
|
‘ENOSPC’
|
The directory or file system cannot be extended to make the
|
new link.
|
|
‘EIO’
|
A hardware error occurred while reading or writing data on the
|
disk.
|
|
-- Function: ssize_t readlink (const char *FILENAME, char *BUFFER,
|
size_t SIZE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘readlink’ function gets the value of the symbolic link
|
FILENAME. The file name that the link points to is copied into
|
BUFFER. This file name string is _not_ null-terminated; ‘readlink’
|
normally returns the number of characters copied. The SIZE
|
argument specifies the maximum number of characters to copy,
|
usually the allocation size of BUFFER.
|
|
If the return value equals SIZE, you cannot tell whether or not
|
there was room to return the entire name. So make a bigger buffer
|
and call ‘readlink’ again. Here is an example:
|
|
char *
|
readlink_malloc (const char *filename)
|
{
|
int size = 100;
|
char *buffer = NULL;
|
|
while (1)
|
{
|
buffer = (char *) xrealloc (buffer, size);
|
int nchars = readlink (filename, buffer, size);
|
if (nchars < 0)
|
{
|
free (buffer);
|
return NULL;
|
}
|
if (nchars < size)
|
return buffer;
|
size *= 2;
|
}
|
}
|
|
A value of ‘-1’ is returned in case of error. In addition to the
|
usual file name errors (*note File Name Errors::), the following
|
‘errno’ error conditions are defined for this function:
|
|
‘EINVAL’
|
The named file is not a symbolic link.
|
|
‘EIO’
|
A hardware error occurred while reading or writing data on the
|
disk.
|
|
In some situations it is desirable to resolve all the symbolic links
|
to get the real name of a file where no prefix names a symbolic link
|
which is followed and no filename in the path is ‘.’ or ‘..’. This is
|
for instance desirable if files have to be compared in which case
|
different names can refer to the same inode.
|
|
-- Function: char * canonicalize_file_name (const char *NAME)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
The ‘canonicalize_file_name’ function returns the absolute name of
|
the file named by NAME which contains no ‘.’, ‘..’ components nor
|
any repeated path separators (‘/’) or symlinks. The result is
|
passed back as the return value of the function in a block of
|
memory allocated with ‘malloc’. If the result is not used anymore
|
the memory should be freed with a call to ‘free’.
|
|
If any of the path components are missing the function returns a
|
NULL pointer. This is also what is returned if the length of the
|
path reaches or exceeds ‘PATH_MAX’ characters. In any case ‘errno’
|
is set accordingly.
|
|
‘ENAMETOOLONG’
|
The resulting path is too long. This error only occurs on
|
systems which have a limit on the file name length.
|
|
‘EACCES’
|
At least one of the path components is not readable.
|
|
‘ENOENT’
|
The input file name is empty.
|
|
‘ENOENT’
|
At least one of the path components does not exist.
|
|
‘ELOOP’
|
More than ‘MAXSYMLINKS’ many symlinks have been followed.
|
|
This function is a GNU extension and is declared in ‘stdlib.h’.
|
|
The Unix standard includes a similar function which differs from
|
‘canonicalize_file_name’ in that the user has to provide the buffer
|
where the result is placed in.
|
|
-- Function: char * realpath (const char *restrict NAME, char *restrict
|
RESOLVED)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
A call to ‘realpath’ where the RESOLVED parameter is ‘NULL’ behaves
|
exactly like ‘canonicalize_file_name’. The function allocates a
|
buffer for the file name and returns a pointer to it. If RESOLVED
|
is not ‘NULL’ it points to a buffer into which the result is
|
copied. It is the callers responsibility to allocate a buffer
|
which is large enough. On systems which define ‘PATH_MAX’ this
|
means the buffer must be large enough for a pathname of this size.
|
For systems without limitations on the pathname length the
|
requirement cannot be met and programs should not call ‘realpath’
|
with anything but ‘NULL’ for the second parameter.
|
|
One other difference is that the buffer RESOLVED (if nonzero) will
|
contain the part of the path component which does not exist or is
|
not readable if the function returns ‘NULL’ and ‘errno’ is set to
|
‘EACCES’ or ‘ENOENT’.
|
|
This function is declared in ‘stdlib.h’.
|
|
The advantage of using this function is that it is more widely
|
available. The drawback is that it reports failures for long paths on
|
systems which have no limits on the file name length.
|
|
|
File: libc.info, Node: Deleting Files, Next: Renaming Files, Prev: Symbolic Links, Up: File System Interface
|
|
14.6 Deleting Files
|
===================
|
|
You can delete a file with ‘unlink’ or ‘remove’.
|
|
Deletion actually deletes a file name. If this is the file’s only
|
name, then the file is deleted as well. If the file has other remaining
|
names (*note Hard Links::), it remains accessible under those names.
|
|
-- Function: int unlink (const char *FILENAME)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘unlink’ function deletes the file name FILENAME. If this is a
|
file’s sole name, the file itself is also deleted. (Actually, if
|
any process has the file open when this happens, deletion is
|
postponed until all processes have closed the file.)
|
|
The function ‘unlink’ is declared in the header file ‘unistd.h’.
|
|
This function returns ‘0’ on successful completion, and ‘-1’ on
|
error. In addition to the usual file name errors (*note File Name
|
Errors::), the following ‘errno’ error conditions are defined for
|
this function:
|
|
‘EACCES’
|
Write permission is denied for the directory from which the
|
file is to be removed, or the directory has the sticky bit set
|
and you do not own the file.
|
|
‘EBUSY’
|
This error indicates that the file is being used by the system
|
in such a way that it can’t be unlinked. For example, you
|
might see this error if the file name specifies the root
|
directory or a mount point for a file system.
|
|
‘ENOENT’
|
The file name to be deleted doesn’t exist.
|
|
‘EPERM’
|
On some systems ‘unlink’ cannot be used to delete the name of
|
a directory, or at least can only be used this way by a
|
privileged user. To avoid such problems, use ‘rmdir’ to
|
delete directories. (On GNU/Linux and GNU/Hurd systems
|
‘unlink’ can never delete the name of a directory.)
|
|
‘EROFS’
|
The directory containing the file name to be deleted is on a
|
read-only file system and can’t be modified.
|
|
-- Function: int rmdir (const char *FILENAME)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘rmdir’ function deletes a directory. The directory must be
|
empty before it can be removed; in other words, it can only contain
|
entries for ‘.’ and ‘..’.
|
|
In most other respects, ‘rmdir’ behaves like ‘unlink’. There are
|
two additional ‘errno’ error conditions defined for ‘rmdir’:
|
|
‘ENOTEMPTY’
|
‘EEXIST’
|
The directory to be deleted is not empty.
|
|
These two error codes are synonymous; some systems use one, and
|
some use the other. GNU/Linux and GNU/Hurd systems always use
|
‘ENOTEMPTY’.
|
|
The prototype for this function is declared in the header file
|
‘unistd.h’.
|
|
-- Function: int remove (const char *FILENAME)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This is the ISO C function to remove a file. It works like
|
‘unlink’ for files and like ‘rmdir’ for directories. ‘remove’ is
|
declared in ‘stdio.h’.
|
|
|
File: libc.info, Node: Renaming Files, Next: Creating Directories, Prev: Deleting Files, Up: File System Interface
|
|
14.7 Renaming Files
|
===================
|
|
The ‘rename’ function is used to change a file’s name.
|
|
-- Function: int rename (const char *OLDNAME, const char *NEWNAME)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘rename’ function renames the file OLDNAME to NEWNAME. The
|
file formerly accessible under the name OLDNAME is afterwards
|
accessible as NEWNAME instead. (If the file had any other names
|
aside from OLDNAME, it continues to have those names.)
|
|
The directory containing the name NEWNAME must be on the same file
|
system as the directory containing the name OLDNAME.
|
|
One special case for ‘rename’ is when OLDNAME and NEWNAME are two
|
names for the same file. The consistent way to handle this case is
|
to delete OLDNAME. However, in this case POSIX requires that
|
‘rename’ do nothing and report success—which is inconsistent. We
|
don’t know what your operating system will do.
|
|
If OLDNAME is not a directory, then any existing file named NEWNAME
|
is removed during the renaming operation. However, if NEWNAME is
|
the name of a directory, ‘rename’ fails in this case.
|
|
If OLDNAME is a directory, then either NEWNAME must not exist or it
|
must name a directory that is empty. In the latter case, the
|
existing directory named NEWNAME is deleted first. The name
|
NEWNAME must not specify a subdirectory of the directory ‘oldname’
|
which is being renamed.
|
|
One useful feature of ‘rename’ is that the meaning of NEWNAME
|
changes “atomically” from any previously existing file by that name
|
to its new meaning (i.e., the file that was called OLDNAME). There
|
is no instant at which NEWNAME is non-existent “in between” the old
|
meaning and the new meaning. If there is a system crash during the
|
operation, it is possible for both names to still exist; but
|
NEWNAME will always be intact if it exists at all.
|
|
If ‘rename’ fails, it returns ‘-1’. In addition to the usual file
|
name errors (*note File Name Errors::), the following ‘errno’ error
|
conditions are defined for this function:
|
|
‘EACCES’
|
One of the directories containing NEWNAME or OLDNAME refuses
|
write permission; or NEWNAME and OLDNAME are directories and
|
write permission is refused for one of them.
|
|
‘EBUSY’
|
A directory named by OLDNAME or NEWNAME is being used by the
|
system in a way that prevents the renaming from working. This
|
includes directories that are mount points for filesystems,
|
and directories that are the current working directories of
|
processes.
|
|
‘ENOTEMPTY’
|
‘EEXIST’
|
The directory NEWNAME isn’t empty. GNU/Linux and GNU/Hurd
|
systems always return ‘ENOTEMPTY’ for this, but some other
|
systems return ‘EEXIST’.
|
|
‘EINVAL’
|
OLDNAME is a directory that contains NEWNAME.
|
|
‘EISDIR’
|
NEWNAME is a directory but the OLDNAME isn’t.
|
|
‘EMLINK’
|
The parent directory of NEWNAME would have too many links
|
(entries).
|
|
‘ENOENT’
|
The file OLDNAME doesn’t exist.
|
|
‘ENOSPC’
|
The directory that would contain NEWNAME has no room for
|
another entry, and there is no space left in the file system
|
to expand it.
|
|
‘EROFS’
|
The operation would involve writing to a directory on a
|
read-only file system.
|
|
‘EXDEV’
|
The two file names NEWNAME and OLDNAME are on different file
|
systems.
|
|
|
File: libc.info, Node: Creating Directories, Next: File Attributes, Prev: Renaming Files, Up: File System Interface
|
|
14.8 Creating Directories
|
=========================
|
|
Directories are created with the ‘mkdir’ function. (There is also a
|
shell command ‘mkdir’ which does the same thing.)
|
|
-- Function: int mkdir (const char *FILENAME, mode_t MODE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘mkdir’ function creates a new, empty directory with name
|
FILENAME.
|
|
The argument MODE specifies the file permissions for the new
|
directory file. *Note Permission Bits::, for more information
|
about this.
|
|
A return value of ‘0’ indicates successful completion, and ‘-1’
|
indicates failure. In addition to the usual file name syntax
|
errors (*note File Name Errors::), the following ‘errno’ error
|
conditions are defined for this function:
|
|
‘EACCES’
|
Write permission is denied for the parent directory in which
|
the new directory is to be added.
|
|
‘EEXIST’
|
A file named FILENAME already exists.
|
|
‘EMLINK’
|
The parent directory has too many links (entries).
|
|
Well-designed file systems never report this error, because
|
they permit more links than your disk could possibly hold.
|
However, you must still take account of the possibility of
|
this error, as it could result from network access to a file
|
system on another machine.
|
|
‘ENOSPC’
|
The file system doesn’t have enough room to create the new
|
directory.
|
|
‘EROFS’
|
The parent directory of the directory being created is on a
|
read-only file system and cannot be modified.
|
|
To use this function, your program should include the header file
|
‘sys/stat.h’.
|
