| This is libc.info, produced by makeinfo version 5.2 from libc.texinfo. |
| |
| This file documents the GNU C Library. |
| |
| This is 'The GNU C Library Reference Manual', for version |
| 2.19-2014.08-1-git (EGLIBC). |
| |
| Copyright (C) 1993-2014 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software Needs Free Documentation" and |
| "GNU Lesser General Public License", the Front-Cover texts being "A GNU |
| Manual", and with the Back-Cover Texts as in (a) below. A copy of the |
| license is included in the section entitled "GNU Free Documentation |
| License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DES_FAILED: (libc)DES Encryption. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * SV_INTERRUPT: (libc)BSD Handler. |
| * SV_ONSTACK: (libc)BSD Handler. |
| * SV_RESETHAND: (libc)BSD Handler. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying and Concatenation. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying and Concatenation. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbc_crypt: (libc)DES Encryption. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfree: (libc)Freeing after Malloc. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)crypt. |
| * crypt_r: (libc)crypt. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * des_setparity: (libc)DES Encryption. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecb_crypt: (libc)DES Encryption. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * encrypt: (libc)DES Encryption. |
| * encrypt_r: (libc)DES Encryption. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying and Concatenation. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying and Concatenation. |
| * memfrob: (libc)Trivial Encryption. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying and Concatenation. |
| * mempcpy: (libc)Copying and Concatenation. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying and Concatenation. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow10: (libc)Exponents and Logarithms. |
| * pow10f: (libc)Exponents and Logarithms. |
| * pow10l: (libc)Exponents and Logarithms. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setkey: (libc)DES Encryption. |
| * setkey_r: (libc)DES Encryption. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)Blocking in BSD. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Handler. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)Blocking in BSD. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)Blocking in BSD. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)Blocking in BSD. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sigvec: (libc)BSD Handler. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying and Concatenation. |
| * stpncpy: (libc)Copying and Concatenation. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Copying and Concatenation. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying and Concatenation. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying and Concatenation. |
| * strdupa: (libc)Copying and Concatenation. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfry: (libc)strfry. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Copying and Concatenation. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Copying and Concatenation. |
| * strndup: (libc)Copying and Concatenation. |
| * strndupa: (libc)Copying and Concatenation. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying and Concatenation. |
| * wcpncpy: (libc)Copying and Concatenation. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Copying and Concatenation. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying and Concatenation. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying and Concatenation. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Copying and Concatenation. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Copying and Concatenation. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying and Concatenation. |
| * wmemmove: (libc)Copying and Concatenation. |
| * wmempcpy: (libc)Copying and Concatenation. |
| * wmemset: (libc)Copying and Concatenation. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| |
| File: libc.info, Node: Portable Positioning, Next: Stream Buffering, Prev: File Positioning, Up: I/O on Streams |
| |
| 12.19 Portable File-Position Functions |
| ====================================== |
| |
| On GNU systems, the file position is truly a character count. You can |
| specify any character count value as an argument to 'fseek' or 'fseeko' |
| and get reliable results for any random access file. However, some ISO C |
| systems do not represent file positions in this way. |
| |
| On some systems where text streams truly differ from binary streams, |
| it is impossible to represent the file position of a text stream as a |
| count of characters from the beginning of the file. For example, the |
| file position on some systems must encode both a record offset within |
| the file, and a character offset within the record. |
| |
| As a consequence, if you want your programs to be portable to these |
| systems, you must observe certain rules: |
| |
| * The value returned from 'ftell' on a text stream has no predictable |
| relationship to the number of characters you have read so far. The |
| only thing you can rely on is that you can use it subsequently as |
| the OFFSET argument to 'fseek' or 'fseeko' to move back to the same |
| file position. |
| |
| * In a call to 'fseek' or 'fseeko' on a text stream, either the |
| OFFSET must be zero, or WHENCE must be 'SEEK_SET' and the OFFSET |
| must be the result of an earlier call to 'ftell' on the same |
| stream. |
| |
| * The value of the file position indicator of a text stream is |
| undefined while there are characters that have been pushed back |
| with 'ungetc' that haven't been read or discarded. *Note |
| Unreading::. |
| |
| But even if you observe these rules, you may still have trouble for |
| long files, because 'ftell' and 'fseek' use a 'long int' value to |
| represent the file position. This type may not have room to encode all |
| the file positions in a large file. Using the 'ftello' and 'fseeko' |
| functions might help here since the 'off_t' type is expected to be able |
| to hold all file position values but this still does not help to handle |
| additional information which must be associated with a file position. |
| |
| So if you do want to support systems with peculiar encodings for the |
| file positions, it is better to use the functions 'fgetpos' and |
| 'fsetpos' instead. These functions represent the file position using |
| the data type 'fpos_t', whose internal representation varies from system |
| to system. |
| |
| These symbols are declared in the header file 'stdio.h'. |
| |
| -- Data Type: fpos_t |
| This is the type of an object that can encode information about the |
| file position of a stream, for use by the functions 'fgetpos' and |
| 'fsetpos'. |
| |
| In the GNU C Library, 'fpos_t' is an opaque data structure that |
| contains internal data to represent file offset and conversion |
| state information. In other systems, it might have a different |
| internal representation. |
| |
| When compiling with '_FILE_OFFSET_BITS == 64' on a 32 bit machine |
| this type is in fact equivalent to 'fpos64_t' since the LFS |
| interface transparently replaces the old interface. |
| |
| -- Data Type: fpos64_t |
| This is the type of an object that can encode information about the |
| file position of a stream, for use by the functions 'fgetpos64' and |
| 'fsetpos64'. |
| |
| In the GNU C Library, 'fpos64_t' is an opaque data structure that |
| contains internal data to represent file offset and conversion |
| state information. In other systems, it might have a different |
| internal representation. |
| |
| -- Function: int fgetpos (FILE *STREAM, fpos_t *POSITION) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function stores the value of the file position indicator for |
| the stream STREAM in the 'fpos_t' object pointed to by POSITION. |
| If successful, 'fgetpos' returns zero; otherwise it returns a |
| nonzero value and stores an implementation-defined positive value |
| in 'errno'. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' on a |
| 32 bit system the function is in fact 'fgetpos64'. I.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: int fgetpos64 (FILE *STREAM, fpos64_t *POSITION) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to 'fgetpos' but the file position is |
| returned in a variable of type 'fpos64_t' to which POSITION points. |
| |
| If the sources are compiled with '_FILE_OFFSET_BITS == 64' on a 32 |
| bits machine this function is available under the name 'fgetpos' |
| and so transparently replaces the old interface. |
| |
| -- Function: int fsetpos (FILE *STREAM, const fpos_t *POSITION) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function sets the file position indicator for the stream |
| STREAM to the position POSITION, which must have been set by a |
| previous call to 'fgetpos' on the same stream. If successful, |
| 'fsetpos' clears the end-of-file indicator on the stream, discards |
| any characters that were "pushed back" by the use of 'ungetc', and |
| returns a value of zero. Otherwise, 'fsetpos' returns a nonzero |
| value and stores an implementation-defined positive value in |
| 'errno'. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' on a |
| 32 bit system the function is in fact 'fsetpos64'. I.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: int fsetpos64 (FILE *STREAM, const fpos64_t *POSITION) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to 'fsetpos' but the file position used |
| for positioning is provided in a variable of type 'fpos64_t' to |
| which POSITION points. |
| |
| If the sources are compiled with '_FILE_OFFSET_BITS == 64' on a 32 |
| bits machine this function is available under the name 'fsetpos' |
| and so transparently replaces the old interface. |
| |
| |
| File: libc.info, Node: Stream Buffering, Next: Other Kinds of Streams, Prev: Portable Positioning, Up: I/O on Streams |
| |
| 12.20 Stream Buffering |
| ====================== |
| |
| Characters that are written to a stream are normally accumulated and |
| transmitted asynchronously to the file in a block, instead of appearing |
| as soon as they are output by the application program. Similarly, |
| streams often retrieve input from the host environment in blocks rather |
| than on a character-by-character basis. This is called "buffering". |
| |
| If you are writing programs that do interactive input and output |
| using streams, you need to understand how buffering works when you |
| design the user interface to your program. Otherwise, you might find |
| that output (such as progress or prompt messages) doesn't appear when |
| you intended it to, or displays some other unexpected behavior. |
| |
| This section deals only with controlling when characters are |
| transmitted between the stream and the file or device, and _not_ with |
| how things like echoing, flow control, and the like are handled on |
| specific classes of devices. For information on common control |
| operations on terminal devices, see *note Low-Level Terminal |
| Interface::. |
| |
| You can bypass the stream buffering facilities altogether by using |
| the low-level input and output functions that operate on file |
| descriptors instead. *Note Low-Level I/O::. |
| |
| * Menu: |
| |
| * Buffering Concepts:: Terminology is defined here. |
| * Flushing Buffers:: How to ensure that output buffers are flushed. |
| * Controlling Buffering:: How to specify what kind of buffering to use. |
| |
| |
| File: libc.info, Node: Buffering Concepts, Next: Flushing Buffers, Up: Stream Buffering |
| |
| 12.20.1 Buffering Concepts |
| -------------------------- |
| |
| There are three different kinds of buffering strategies: |
| |
| * Characters written to or read from an "unbuffered" stream are |
| transmitted individually to or from the file as soon as possible. |
| |
| * Characters written to a "line buffered" stream are transmitted to |
| the file in blocks when a newline character is encountered. |
| |
| * Characters written to or read from a "fully buffered" stream are |
| transmitted to or from the file in blocks of arbitrary size. |
| |
| Newly opened streams are normally fully buffered, with one exception: |
| a stream connected to an interactive device such as a terminal is |
| initially line buffered. *Note Controlling Buffering::, for information |
| on how to select a different kind of buffering. Usually the automatic |
| selection gives you the most convenient kind of buffering for the file |
| or device you open. |
| |
| The use of line buffering for interactive devices implies that output |
| messages ending in a newline will appear immediately--which is usually |
| what you want. Output that doesn't end in a newline might or might not |
| show up immediately, so if you want them to appear immediately, you |
| should flush buffered output explicitly with 'fflush', as described in |
| *note Flushing Buffers::. |
| |
| |
| File: libc.info, Node: Flushing Buffers, Next: Controlling Buffering, Prev: Buffering Concepts, Up: Stream Buffering |
| |
| 12.20.2 Flushing Buffers |
| ------------------------ |
| |
| "Flushing" output on a buffered stream means transmitting all |
| accumulated characters to the file. There are many circumstances when |
| buffered output on a stream is flushed automatically: |
| |
| * When you try to do output and the output buffer is full. |
| |
| * When the stream is closed. *Note Closing Streams::. |
| |
| * When the program terminates by calling 'exit'. *Note Normal |
| Termination::. |
| |
| * When a newline is written, if the stream is line buffered. |
| |
| * Whenever an input operation on _any_ stream actually reads data |
| from its file. |
| |
| If you want to flush the buffered output at another time, call |
| 'fflush', which is declared in the header file 'stdio.h'. |
| |
| -- Function: int fflush (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function causes any buffered output on STREAM to be delivered |
| to the file. If STREAM is a null pointer, then 'fflush' causes |
| buffered output on _all_ open output streams to be flushed. |
| |
| This function returns 'EOF' if a write error occurs, or zero |
| otherwise. |
| |
| -- Function: int fflush_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The 'fflush_unlocked' function is equivalent to the 'fflush' |
| function except that it does not implicitly lock the stream. |
| |
| The 'fflush' function can be used to flush all streams currently |
| opened. While this is useful in some situations it does often more than |
| necessary since it might be done in situations when terminal input is |
| required and the program wants to be sure that all output is visible on |
| the terminal. But this means that only line buffered streams have to be |
| flushed. Solaris introduced a function especially for this. It was |
| always available in the GNU C Library in some form but never officially |
| exported. |
| |
| -- Function: void _flushlbf (void) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The '_flushlbf' function flushes all line buffered streams |
| currently opened. |
| |
| This function is declared in the 'stdio_ext.h' header. |
| |
| *Compatibility Note:* Some brain-damaged operating systems have been |
| known to be so thoroughly fixated on line-oriented input and output that |
| flushing a line buffered stream causes a newline to be written! |
| Fortunately, this "feature" seems to be becoming less common. You do |
| not need to worry about this with the GNU C Library. |
| |
| In some situations it might be useful to not flush the output pending |
| for a stream but instead simply forget it. If transmission is costly |
| and the output is not needed anymore this is valid reasoning. In this |
| situation a non-standard function introduced in Solaris and available in |
| the GNU C Library can be used. |
| |
| -- Function: void __fpurge (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The '__fpurge' function causes the buffer of the stream STREAM to |
| be emptied. If the stream is currently in read mode all input in |
| the buffer is lost. If the stream is in output mode the buffered |
| output is not written to the device (or whatever other underlying |
| storage) and the buffer the cleared. |
| |
| This function is declared in 'stdio_ext.h'. |
| |
| |
| File: libc.info, Node: Controlling Buffering, Prev: Flushing Buffers, Up: Stream Buffering |
| |
| 12.20.3 Controlling Which Kind of Buffering |
| ------------------------------------------- |
| |
| After opening a stream (but before any other operations have been |
| performed on it), you can explicitly specify what kind of buffering you |
| want it to have using the 'setvbuf' function. |
| |
| The facilities listed in this section are declared in the header file |
| 'stdio.h'. |
| |
| -- Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t |
| SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is used to specify that the stream STREAM should have |
| the buffering mode MODE, which can be either '_IOFBF' (for full |
| buffering), '_IOLBF' (for line buffering), or '_IONBF' (for |
| unbuffered input/output). |
| |
| If you specify a null pointer as the BUF argument, then 'setvbuf' |
| allocates a buffer itself using 'malloc'. This buffer will be |
| freed when you close the stream. |
| |
| Otherwise, BUF should be a character array that can hold at least |
| SIZE characters. You should not free the space for this array as |
| long as the stream remains open and this array remains its buffer. |
| You should usually either allocate it statically, or 'malloc' |
| (*note Unconstrained Allocation::) the buffer. Using an automatic |
| array is not a good idea unless you close the file before exiting |
| the block that declares the array. |
| |
| While the array remains a stream buffer, the stream I/O functions |
| will use the buffer for their internal purposes. You shouldn't try |
| to access the values in the array directly while the stream is |
| using it for buffering. |
| |
| The 'setvbuf' function returns zero on success, or a nonzero value |
| if the value of MODE is not valid or if the request could not be |
| honored. |
| |
| -- Macro: int _IOFBF |
| The value of this macro is an integer constant expression that can |
| be used as the MODE argument to the 'setvbuf' function to specify |
| that the stream should be fully buffered. |
| |
| -- Macro: int _IOLBF |
| The value of this macro is an integer constant expression that can |
| be used as the MODE argument to the 'setvbuf' function to specify |
| that the stream should be line buffered. |
| |
| -- Macro: int _IONBF |
| The value of this macro is an integer constant expression that can |
| be used as the MODE argument to the 'setvbuf' function to specify |
| that the stream should be unbuffered. |
| |
| -- Macro: int BUFSIZ |
| The value of this macro is an integer constant expression that is |
| good to use for the SIZE argument to 'setvbuf'. This value is |
| guaranteed to be at least '256'. |
| |
| The value of 'BUFSIZ' is chosen on each system so as to make stream |
| I/O efficient. So it is a good idea to use 'BUFSIZ' as the size |
| for the buffer when you call 'setvbuf'. |
| |
| Actually, you can get an even better value to use for the buffer |
| size by means of the 'fstat' system call: it is found in the |
| 'st_blksize' field of the file attributes. *Note Attribute |
| Meanings::. |
| |
| Sometimes people also use 'BUFSIZ' as the allocation size of |
| buffers used for related purposes, such as strings used to receive |
| a line of input with 'fgets' (*note Character Input::). There is |
| no particular reason to use 'BUFSIZ' for this instead of any other |
| integer, except that it might lead to doing I/O in chunks of an |
| efficient size. |
| |
| -- Function: void setbuf (FILE *STREAM, char *BUF) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| If BUF is a null pointer, the effect of this function is equivalent |
| to calling 'setvbuf' with a MODE argument of '_IONBF'. Otherwise, |
| it is equivalent to calling 'setvbuf' with BUF, and a MODE of |
| '_IOFBF' and a SIZE argument of 'BUFSIZ'. |
| |
| The 'setbuf' function is provided for compatibility with old code; |
| use 'setvbuf' in all new programs. |
| |
| -- Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| If BUF is a null pointer, this function makes STREAM unbuffered. |
| Otherwise, it makes STREAM fully buffered using BUF as the buffer. |
| The SIZE argument specifies the length of BUF. |
| |
| This function is provided for compatibility with old BSD code. Use |
| 'setvbuf' instead. |
| |
| -- Function: void setlinebuf (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function makes STREAM be line buffered, and allocates the |
| buffer for you. |
| |
| This function is provided for compatibility with old BSD code. Use |
| 'setvbuf' instead. |
| |
| It is possible to query whether a given stream is line buffered or |
| not using a non-standard function introduced in Solaris and available in |
| the GNU C Library. |
| |
| -- Function: int __flbf (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The '__flbf' function will return a nonzero value in case the |
| stream STREAM is line buffered. Otherwise the return value is |
| zero. |
| |
| This function is declared in the 'stdio_ext.h' header. |
| |
| Two more extensions allow to determine the size of the buffer and how |
| much of it is used. These functions were also introduced in Solaris. |
| |
| -- Function: size_t __fbufsize (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| The '__fbufsize' function return the size of the buffer in the |
| stream STREAM. This value can be used to optimize the use of the |
| stream. |
| |
| This function is declared in the 'stdio_ext.h' header. |
| |
| -- Function: size_t __fpending (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| The '__fpending' function returns the number of bytes currently in |
| the output buffer. For wide-oriented stream the measuring unit is |
| wide characters. This function should not be used on buffers in |
| read mode or opened read-only. |
| |
| This function is declared in the 'stdio_ext.h' header. |
| |
| |
| File: libc.info, Node: Other Kinds of Streams, Next: Formatted Messages, Prev: Stream Buffering, Up: I/O on Streams |
| |
| 12.21 Other Kinds of Streams |
| ============================ |
| |
| The GNU C Library provides ways for you to define additional kinds of |
| streams that do not necessarily correspond to an open file. |
| |
| One such type of stream takes input from or writes output to a |
| string. These kinds of streams are used internally to implement the |
| 'sprintf' and 'sscanf' functions. You can also create such a stream |
| explicitly, using the functions described in *note String Streams::. |
| |
| More generally, you can define streams that do input/output to |
| arbitrary objects using functions supplied by your program. This |
| protocol is discussed in *note Custom Streams::. |
| |
| *Portability Note:* The facilities described in this section are |
| specific to GNU. Other systems or C implementations might or might not |
| provide equivalent functionality. |
| |
| * Menu: |
| |
| * String Streams:: Streams that get data from or put data in |
| a string or memory buffer. |
| * Custom Streams:: Defining your own streams with an arbitrary |
| input data source and/or output data sink. |
| |
| |
| File: libc.info, Node: String Streams, Next: Custom Streams, Up: Other Kinds of Streams |
| |
| 12.21.1 String Streams |
| ---------------------- |
| |
| The 'fmemopen' and 'open_memstream' functions allow you to do I/O to a |
| string or memory buffer. These facilities are declared in 'stdio.h'. |
| |
| -- Function: FILE * fmemopen (void *BUF, size_t SIZE, const char |
| *OPENTYPE) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock | |
| *Note POSIX Safety Concepts::. |
| |
| This function opens a stream that allows the access specified by |
| the OPENTYPE argument, that reads from or writes to the buffer |
| specified by the argument BUF. This array must be at least SIZE |
| bytes long. |
| |
| If you specify a null pointer as the BUF argument, 'fmemopen' |
| dynamically allocates an array SIZE bytes long (as with 'malloc'; |
| *note Unconstrained Allocation::). This is really only useful if |
| you are going to write things to the buffer and then read them back |
| in again, because you have no way of actually getting a pointer to |
| the buffer (for this, try 'open_memstream', below). The buffer is |
| freed when the stream is closed. |
| |
| The argument OPENTYPE is the same as in 'fopen' (*note Opening |
| Streams::). If the OPENTYPE specifies append mode, then the |
| initial file position is set to the first null character in the |
| buffer. Otherwise the initial file position is at the beginning of |
| the buffer. |
| |
| When a stream open for writing is flushed or closed, a null |
| character (zero byte) is written at the end of the buffer if it |
| fits. You should add an extra byte to the SIZE argument to account |
| for this. Attempts to write more than SIZE bytes to the buffer |
| result in an error. |
| |
| For a stream open for reading, null characters (zero bytes) in the |
| buffer do not count as "end of file". Read operations indicate end |
| of file only when the file position advances past SIZE bytes. So, |
| if you want to read characters from a null-terminated string, you |
| should supply the length of the string as the SIZE argument. |
| |
| Here is an example of using 'fmemopen' to create a stream for reading |
| from a string: |
| |
| |
| #include <stdio.h> |
| |
| static char buffer[] = "foobar"; |
| |
| int |
| main (void) |
| { |
| int ch; |
| FILE *stream; |
| |
| stream = fmemopen (buffer, strlen (buffer), "r"); |
| while ((ch = fgetc (stream)) != EOF) |
| printf ("Got %c\n", ch); |
| fclose (stream); |
| |
| return 0; |
| } |
| |
| This program produces the following output: |
| |
| Got f |
| Got o |
| Got o |
| Got b |
| Got a |
| Got r |
| |
| -- Function: FILE * open_memstream (char **PTR, size_t *SIZELOC) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note |
| POSIX Safety Concepts::. |
| |
| This function opens a stream for writing to a buffer. The buffer |
| is allocated dynamically and grown as necessary, using 'malloc'. |
| After you've closed the stream, this buffer is your responsibility |
| to clean up using 'free' or 'realloc'. *Note Unconstrained |
| Allocation::. |
| |
| When the stream is closed with 'fclose' or flushed with 'fflush', |
| the locations PTR and SIZELOC are updated to contain the pointer to |
| the buffer and its size. The values thus stored remain valid only |
| as long as no further output on the stream takes place. If you do |
| more output, you must flush the stream again to store new values |
| before you use them again. |
| |
| A null character is written at the end of the buffer. This null |
| character is _not_ included in the size value stored at SIZELOC. |
| |
| You can move the stream's file position with 'fseek' or 'fseeko' |
| (*note File Positioning::). Moving the file position past the end |
| of the data already written fills the intervening space with |
| zeroes. |
| |
| Here is an example of using 'open_memstream': |
| |
| |
| #include <stdio.h> |
| |
| int |
| main (void) |
| { |
| char *bp; |
| size_t size; |
| FILE *stream; |
| |
| stream = open_memstream (&bp, &size); |
| fprintf (stream, "hello"); |
| fflush (stream); |
| printf ("buf = `%s', size = %d\n", bp, size); |
| fprintf (stream, ", world"); |
| fclose (stream); |
| printf ("buf = `%s', size = %d\n", bp, size); |
| |
| return 0; |
| } |
| |
| This program produces the following output: |
| |
| buf = `hello', size = 5 |
| buf = `hello, world', size = 12 |
| |
| |
| File: libc.info, Node: Custom Streams, Prev: String Streams, Up: Other Kinds of Streams |
| |
| 12.21.2 Programming Your Own Custom Streams |
| ------------------------------------------- |
| |
| This section describes how you can make a stream that gets input from an |
| arbitrary data source or writes output to an arbitrary data sink |
| programmed by you. We call these "custom streams". The functions and |
| types described here are all GNU extensions. |
| |
| * Menu: |
| |
| * Streams and Cookies:: The "cookie" records where to fetch or |
| store data that is read or written. |
| * Hook Functions:: How you should define the four "hook |
| functions" that a custom stream needs. |
| |
| |
| File: libc.info, Node: Streams and Cookies, Next: Hook Functions, Up: Custom Streams |
| |
| 12.21.2.1 Custom Streams and Cookies |
| .................................... |
| |
| Inside every custom stream is a special object called the "cookie". |
| This is an object supplied by you which records where to fetch or store |
| the data read or written. It is up to you to define a data type to use |
| for the cookie. The stream functions in the library never refer |
| directly to its contents, and they don't even know what the type is; |
| they record its address with type 'void *'. |
| |
| To implement a custom stream, you must specify _how_ to fetch or |
| store the data in the specified place. You do this by defining "hook |
| functions" to read, write, change "file position", and close the stream. |
| All four of these functions will be passed the stream's cookie so they |
| can tell where to fetch or store the data. The library functions don't |
| know what's inside the cookie, but your functions will know. |
| |
| When you create a custom stream, you must specify the cookie pointer, |
| and also the four hook functions stored in a structure of type |
| 'cookie_io_functions_t'. |
| |
| These facilities are declared in 'stdio.h'. |
| |
| -- Data Type: cookie_io_functions_t |
| This is a structure type that holds the functions that define the |
| communications protocol between the stream and its cookie. It has |
| the following members: |
| |
| 'cookie_read_function_t *read' |
| This is the function that reads data from the cookie. If the |
| value is a null pointer instead of a function, then read |
| operations on this stream always return 'EOF'. |
| |
| 'cookie_write_function_t *write' |
| This is the function that writes data to the cookie. If the |
| value is a null pointer instead of a function, then data |
| written to the stream is discarded. |
| |
| 'cookie_seek_function_t *seek' |
| This is the function that performs the equivalent of file |
| positioning on the cookie. If the value is a null pointer |
| instead of a function, calls to 'fseek' or 'fseeko' on this |
| stream can only seek to locations within the buffer; any |
| attempt to seek outside the buffer will return an 'ESPIPE' |
| error. |
| |
| 'cookie_close_function_t *close' |
| This function performs any appropriate cleanup on the cookie |
| when closing the stream. If the value is a null pointer |
| instead of a function, nothing special is done to close the |
| cookie when the stream is closed. |
| |
| -- Function: FILE * fopencookie (void *COOKIE, const char *OPENTYPE, |
| cookie_io_functions_t IO-FUNCTIONS) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock | |
| *Note POSIX Safety Concepts::. |
| |
| This function actually creates the stream for communicating with |
| the COOKIE using the functions in the IO-FUNCTIONS argument. The |
| OPENTYPE argument is interpreted as for 'fopen'; see *note Opening |
| Streams::. (But note that the "truncate on open" option is |
| ignored.) The new stream is fully buffered. |
| |
| The 'fopencookie' function returns the newly created stream, or a |
| null pointer in case of an error. |
| |
| |
| File: libc.info, Node: Hook Functions, Prev: Streams and Cookies, Up: Custom Streams |
| |
| 12.21.2.2 Custom Stream Hook Functions |
| ...................................... |
| |
| Here are more details on how you should define the four hook functions |
| that a custom stream needs. |
| |
| You should define the function to read data from the cookie as: |
| |
| ssize_t READER (void *COOKIE, char *BUFFER, size_t SIZE) |
| |
| This is very similar to the 'read' function; see *note I/O |
| Primitives::. Your function should transfer up to SIZE bytes into the |
| BUFFER, and return the number of bytes read, or zero to indicate |
| end-of-file. You can return a value of '-1' to indicate an error. |
| |
| You should define the function to write data to the cookie as: |
| |
| ssize_t WRITER (void *COOKIE, const char *BUFFER, size_t SIZE) |
| |
| This is very similar to the 'write' function; see *note I/O |
| Primitives::. Your function should transfer up to SIZE bytes from the |
| buffer, and return the number of bytes written. You can return a value |
| of '0' to indicate an error. You must not return any negative value. |
| |
| You should define the function to perform seek operations on the |
| cookie as: |
| |
| int SEEKER (void *COOKIE, off64_t *POSITION, int WHENCE) |
| |
| For this function, the POSITION and WHENCE arguments are interpreted |
| as for 'fgetpos'; see *note Portable Positioning::. |
| |
| After doing the seek operation, your function should store the |
| resulting file position relative to the beginning of the file in |
| POSITION. Your function should return a value of '0' on success and |
| '-1' to indicate an error. |
| |
| You should define the function to do cleanup operations on the cookie |
| appropriate for closing the stream as: |
| |
| int CLEANER (void *COOKIE) |
| |
| Your function should return '-1' to indicate an error, and '0' |
| otherwise. |
| |
| -- Data Type: cookie_read_function |
| This is the data type that the read function for a custom stream |
| should have. If you declare the function as shown above, this is |
| the type it will have. |
| |
| -- Data Type: cookie_write_function |
| The data type of the write function for a custom stream. |
| |
| -- Data Type: cookie_seek_function |
| The data type of the seek function for a custom stream. |
| |
| -- Data Type: cookie_close_function |
| The data type of the close function for a custom stream. |
| |
| |
| File: libc.info, Node: Formatted Messages, Prev: Other Kinds of Streams, Up: I/O on Streams |
| |
| 12.22 Formatted Messages |
| ======================== |
| |
| On systems which are based on System V messages of programs (especially |
| the system tools) are printed in a strict form using the 'fmtmsg' |
| function. The uniformity sometimes helps the user to interpret messages |
| and the strictness tests of the 'fmtmsg' function ensure that the |
| programmer follows some minimal requirements. |
| |
| * Menu: |
| |
| * Printing Formatted Messages:: The 'fmtmsg' function. |
| * Adding Severity Classes:: Add more severity classes. |
| * Example:: How to use 'fmtmsg' and 'addseverity'. |
| |
| |
| File: libc.info, Node: Printing Formatted Messages, Next: Adding Severity Classes, Up: Formatted Messages |
| |
| 12.22.1 Printing Formatted Messages |
| ----------------------------------- |
| |
| Messages can be printed to standard error and/or to the console. To |
| select the destination the programmer can use the following two values, |
| bitwise OR combined if wanted, for the CLASSIFICATION parameter of |
| 'fmtmsg': |
| |
| 'MM_PRINT' |
| Display the message in standard error. |
| 'MM_CONSOLE' |
| Display the message on the system console. |
| |
| The erroneous piece of the system can be signalled by exactly one of |
| the following values which also is bitwise ORed with the CLASSIFICATION |
| parameter to 'fmtmsg': |
| |
| 'MM_HARD' |
| The source of the condition is some hardware. |
| 'MM_SOFT' |
| The source of the condition is some software. |
| 'MM_FIRM' |
| The source of the condition is some firmware. |
| |
| A third component of the CLASSIFICATION parameter to 'fmtmsg' can |
| describe the part of the system which detects the problem. This is done |
| by using exactly one of the following values: |
| |
| 'MM_APPL' |
| The erroneous condition is detected by the application. |
| 'MM_UTIL' |
| The erroneous condition is detected by a utility. |
| 'MM_OPSYS' |
| The erroneous condition is detected by the operating system. |
| |
| A last component of CLASSIFICATION can signal the results of this |
| message. Exactly one of the following values can be used: |
| |
| 'MM_RECOVER' |
| It is a recoverable error. |
| 'MM_NRECOV' |
| It is a non-recoverable error. |
| |
| -- Function: int fmtmsg (long int CLASSIFICATION, const char *LABEL, |
| int SEVERITY, const char *TEXT, const char *ACTION, const char |
| *TAG) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Display a message described by its parameters on the device(s) |
| specified in the CLASSIFICATION parameter. The LABEL parameter |
| identifies the source of the message. The string should consist of |
| two colon separated parts where the first part has not more than 10 |
| and the second part not more than 14 characters. The TEXT |
| parameter describes the condition of the error, the ACTION |
| parameter possible steps to recover from the error and the TAG |
| parameter is a reference to the online documentation where more |
| information can be found. It should contain the LABEL value and a |
| unique identification number. |
| |
| Each of the parameters can be a special value which means this |
| value is to be omitted. The symbolic names for these values are: |
| |
| 'MM_NULLLBL' |
| Ignore LABEL parameter. |
| 'MM_NULLSEV' |
| Ignore SEVERITY parameter. |
| 'MM_NULLMC' |
| Ignore CLASSIFICATION parameter. This implies that nothing is |
| actually printed. |
| 'MM_NULLTXT' |
| Ignore TEXT parameter. |
| 'MM_NULLACT' |
| Ignore ACTION parameter. |
| 'MM_NULLTAG' |
| Ignore TAG parameter. |
| |
| There is another way certain fields can be omitted from the output |
| to standard error. This is described below in the description of |
| environment variables influencing the behavior. |
| |
| The SEVERITY parameter can have one of the values in the following |
| table: |
| |
| 'MM_NOSEV' |
| Nothing is printed, this value is the same as 'MM_NULLSEV'. |
| 'MM_HALT' |
| This value is printed as 'HALT'. |
| 'MM_ERROR' |
| This value is printed as 'ERROR'. |
| 'MM_WARNING' |
| This value is printed as 'WARNING'. |
| 'MM_INFO' |
| This value is printed as 'INFO'. |
| |
| The numeric value of these five macros are between '0' and '4'. |
| Using the environment variable 'SEV_LEVEL' or using the |
| 'addseverity' function one can add more severity levels with their |
| corresponding string to print. This is described below (*note |
| Adding Severity Classes::). |
| |
| If no parameter is ignored the output looks like this: |
| |
| LABEL: SEVERITY-STRING: TEXT |
| TO FIX: ACTION TAG |
| |
| The colons, new line characters and the 'TO FIX' string are |
| inserted if necessary, i.e., if the corresponding parameter is not |
| ignored. |
| |
| This function is specified in the X/Open Portability Guide. It is |
| also available on all systems derived from System V. |
| |
| The function returns the value 'MM_OK' if no error occurred. If |
| only the printing to standard error failed, it returns 'MM_NOMSG'. |
| If printing to the console fails, it returns 'MM_NOCON'. If |
| nothing is printed 'MM_NOTOK' is returned. Among situations where |
| all outputs fail this last value is also returned if a parameter |
| value is incorrect. |
| |
| There are two environment variables which influence the behavior of |
| 'fmtmsg'. The first is 'MSGVERB'. It is used to control the output |
| actually happening on standard error (_not_ the console output). Each |
| of the five fields can explicitly be enabled. To do this the user has |
| to put the 'MSGVERB' variable with a format like the following in the |
| environment before calling the 'fmtmsg' function the first time: |
| |
| MSGVERB=KEYWORD[:KEYWORD[:...]] |
| |
| Valid KEYWORDs are 'label', 'severity', 'text', 'action', and 'tag'. |
| If the environment variable is not given or is the empty string, a not |
| supported keyword is given or the value is somehow else invalid, no part |
| of the message is masked out. |
| |
| The second environment variable which influences the behavior of |
| 'fmtmsg' is 'SEV_LEVEL'. This variable and the change in the behavior |
| of 'fmtmsg' is not specified in the X/Open Portability Guide. It is |
| available in System V systems, though. It can be used to introduce new |
| severity levels. By default, only the five severity levels described |
| above are available. Any other numeric value would make 'fmtmsg' print |
| nothing. |
| |
| If the user puts 'SEV_LEVEL' with a format like |
| |
| SEV_LEVEL=[DESCRIPTION[:DESCRIPTION[:...]]] |
| |
| in the environment of the process before the first call to 'fmtmsg', |
| where DESCRIPTION has a value of the form |
| |
| SEVERITY-KEYWORD,LEVEL,PRINTSTRING |
| |
| The SEVERITY-KEYWORD part is not used by 'fmtmsg' but it has to be |
| present. The LEVEL part is a string representation of a number. The |
| numeric value must be a number greater than 4. This value must be used |
| in the SEVERITY parameter of 'fmtmsg' to select this class. It is not |
| possible to overwrite any of the predefined classes. The PRINTSTRING is |
| the string printed when a message of this class is processed by 'fmtmsg' |
| (see above, 'fmtsmg' does not print the numeric value but instead the |
| string representation). |
| |
| |
| File: libc.info, Node: Adding Severity Classes, Next: Example, Prev: Printing Formatted Messages, Up: Formatted Messages |
| |
| 12.22.2 Adding Severity Classes |
| ------------------------------- |
| |
| There is another possibility to introduce severity classes besides using |
| the environment variable 'SEV_LEVEL'. This simplifies the task of |
| introducing new classes in a running program. One could use the |
| 'setenv' or 'putenv' function to set the environment variable, but this |
| is toilsome. |
| |
| -- Function: int addseverity (int SEVERITY, const char *STRING) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function allows the introduction of new severity classes which |
| can be addressed by the SEVERITY parameter of the 'fmtmsg' |
| function. The SEVERITY parameter of 'addseverity' must match the |
| value for the parameter with the same name of 'fmtmsg', and STRING |
| is the string printed in the actual messages instead of the numeric |
| value. |
| |
| If STRING is 'NULL' the severity class with the numeric value |
| according to SEVERITY is removed. |
| |
| It is not possible to overwrite or remove one of the default |
| severity classes. All calls to 'addseverity' with SEVERITY set to |
| one of the values for the default classes will fail. |
| |
| The return value is 'MM_OK' if the task was successfully performed. |
| If the return value is 'MM_NOTOK' something went wrong. This could |
| mean that no more memory is available or a class is not available |
| when it has to be removed. |
| |
| This function is not specified in the X/Open Portability Guide |
| although the 'fmtsmg' function is. It is available on System V |
| systems. |
| |
| |
| File: libc.info, Node: Example, Prev: Adding Severity Classes, Up: Formatted Messages |
| |
| 12.22.3 How to use 'fmtmsg' and 'addseverity' |
| --------------------------------------------- |
| |
| Here is a simple example program to illustrate the use of the both |
| functions described in this section. |
| |
| |
| #include <fmtmsg.h> |
| |
| int |
| main (void) |
| { |
| addseverity (5, "NOTE2"); |
| fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2"); |
| fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual", |
| "UX:cat:001"); |
| fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag"); |
| return 0; |
| } |
| |
| The second call to 'fmtmsg' illustrates a use of this function as it |
| usually occurs on System V systems, which heavily use this function. It |
| seems worthwhile to give a short explanation here of how this system |
| works on System V. The value of the LABEL field ('UX:cat') says that the |
| error occurred in the Unix program 'cat'. The explanation of the error |
| follows and the value for the ACTION parameter is '"refer to manual"'. |
| One could be more specific here, if necessary. The TAG field contains, |
| as proposed above, the value of the string given for the LABEL |
| parameter, and additionally a unique ID ('001' in this case). For a GNU |
| environment this string could contain a reference to the corresponding |
| node in the Info page for the program. |
| |
| Running this program without specifying the 'MSGVERB' and 'SEV_LEVEL' |
| function produces the following output: |
| |
| UX:cat: NOTE2: invalid syntax |
| TO FIX: refer to manual UX:cat:001 |
| |
| We see the different fields of the message and how the extra glue |
| (the colons and the 'TO FIX' string) are printed. But only one of the |
| three calls to 'fmtmsg' produced output. The first call does not print |
| anything because the LABEL parameter is not in the correct form. The |
| string must contain two fields, separated by a colon (*note Printing |
| Formatted Messages::). The third 'fmtmsg' call produced no output since |
| the class with the numeric value '6' is not defined. Although a class |
| with numeric value '5' is also not defined by default, the call to |
| 'addseverity' introduces it and the second call to 'fmtmsg' produces the |
| above output. |
| |
| When we change the environment of the program to contain |
| 'SEV_LEVEL=XXX,6,NOTE' when running it we get a different result: |
| |
| UX:cat: NOTE2: invalid syntax |
| TO FIX: refer to manual UX:cat:001 |
| label:foo: NOTE: text |
| TO FIX: action tag |
| |
| Now the third call to 'fmtmsg' produced some output and we see how |
| the string 'NOTE' from the environment variable appears in the message. |
| |
| Now we can reduce the output by specifying which fields we are |
| interested in. If we additionally set the environment variable |
| 'MSGVERB' to the value 'severity:label:action' we get the following |
| output: |
| |
| UX:cat: NOTE2 |
| TO FIX: refer to manual |
| label:foo: NOTE |
| TO FIX: action |
| |
| I.e., the output produced by the TEXT and the TAG parameters to 'fmtmsg' |
| vanished. Please also note that now there is no colon after the 'NOTE' |
| and 'NOTE2' strings in the output. This is not necessary since there is |
| no more output on this line because the text is missing. |
| |
| |
| File: libc.info, Node: Low-Level I/O, Next: File System Interface, Prev: I/O on Streams, Up: Top |
| |
| 13 Low-Level Input/Output |
| ************************* |
| |
| This chapter describes functions for performing low-level input/output |
| operations on file descriptors. These functions include the primitives |
| for the higher-level I/O functions described in *note I/O on Streams::, |
| as well as functions for performing low-level control operations for |
| which there are no equivalents on streams. |
| |
| Stream-level I/O is more flexible and usually more convenient; |
| therefore, programmers generally use the descriptor-level functions only |
| when necessary. These are some of the usual reasons: |
| |
| * For reading binary files in large chunks. |
| |
| * For reading an entire file into core before parsing it. |
| |
| * To perform operations other than data transfer, which can only be |
| done with a descriptor. (You can use 'fileno' to get the |
| descriptor corresponding to a stream.) |
| |
| * To pass descriptors to a child process. (The child can create its |
| own stream to use a descriptor that it inherits, but cannot inherit |
| a stream directly.) |
| |
| * Menu: |
| |
| * Opening and Closing Files:: How to open and close file |
| descriptors. |
| * I/O Primitives:: Reading and writing data. |
| * File Position Primitive:: Setting a descriptor's file |
| position. |
| * Descriptors and Streams:: Converting descriptor to stream |
| or vice-versa. |
| * Stream/Descriptor Precautions:: Precautions needed if you use both |
| descriptors and streams. |
| * Scatter-Gather:: Fast I/O to discontinuous buffers. |
| * Memory-mapped I/O:: Using files like memory. |
| * Waiting for I/O:: How to check for input or output |
| on multiple file descriptors. |
| * Synchronizing I/O:: Making sure all I/O actions completed. |
| * Asynchronous I/O:: Perform I/O in parallel. |
| * Control Operations:: Various other operations on file |
| descriptors. |
| * Duplicating Descriptors:: Fcntl commands for duplicating |
| file descriptors. |
| * Descriptor Flags:: Fcntl commands for manipulating |
| flags associated with file |
| descriptors. |
| * File Status Flags:: Fcntl commands for manipulating |
| flags associated with open files. |
| * File Locks:: Fcntl commands for implementing |
| file locking. |
| * Interrupt Input:: Getting an asynchronous signal when |
| input arrives. |
| * IOCTLs:: Generic I/O Control operations. |
| |
| |
| File: libc.info, Node: Opening and Closing Files, Next: I/O Primitives, Up: Low-Level I/O |
| |
| 13.1 Opening and Closing Files |
| ============================== |
| |
| This section describes the primitives for opening and closing files |
| using file descriptors. The 'open' and 'creat' functions are declared |
| in the header file 'fcntl.h', while 'close' is declared in 'unistd.h'. |
| |
| -- Function: int open (const char *FILENAME, int FLAGS[, mode_t MODE]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The 'open' function creates and returns a new file descriptor for |
| the file named by FILENAME. Initially, the file position indicator |
| for the file is at the beginning of the file. The argument MODE |
| (*note Permission Bits::) is used only when a file is created, but |
| it doesn't hurt to supply the argument in any case. |
| |
| The FLAGS argument controls how the file is to be opened. This is |
| a bit mask; you create the value by the bitwise OR of the |
| appropriate parameters (using the '|' operator in C). *Note File |
| Status Flags::, for the parameters available. |
| |
| The normal return value from 'open' is a non-negative integer file |
| descriptor. In the case of an error, a value of -1 is returned |
| instead. In addition to the usual file name errors (*note File |
| Name Errors::), the following 'errno' error conditions are defined |
| for this function: |
| |
| 'EACCES' |
| The file exists but is not readable/writable as requested by |
| the FLAGS argument, the file does not exist and the directory |
| is unwritable so it cannot be created. |
| |
| 'EEXIST' |
| Both 'O_CREAT' and 'O_EXCL' are set, and the named file |
| already exists. |
| |
| 'EINTR' |
| The 'open' operation was interrupted by a signal. *Note |
| Interrupted Primitives::. |
| |
| 'EISDIR' |
| The FLAGS argument specified write access, and the file is a |
| directory. |
| |
| 'EMFILE' |
| The process has too many files open. The maximum number of |
| file descriptors is controlled by the 'RLIMIT_NOFILE' resource |
| limit; *note Limits on Resources::. |
| |
| 'ENFILE' |
| The entire system, or perhaps the file system which contains |
| the directory, cannot support any additional open files at the |
| moment. (This problem cannot happen on GNU/Hurd systems.) |
| |
| 'ENOENT' |
| The named file does not exist, and 'O_CREAT' is not specified. |
| |
| 'ENOSPC' |
| The directory or file system that would contain the new file |
| cannot be extended, because there is no disk space left. |
| |
| 'ENXIO' |
| 'O_NONBLOCK' and 'O_WRONLY' are both set in the FLAGS |
| argument, the file named by FILENAME is a FIFO (*note Pipes |
| and FIFOs::), and no process has the file open for reading. |
| |
| 'EROFS' |
| The file resides on a read-only file system and any of |
| 'O_WRONLY', 'O_RDWR', and 'O_TRUNC' are set in the FLAGS |
| argument, or 'O_CREAT' is set and the file does not already |
| exist. |
| |
| If on a 32 bit machine the sources are translated with |
| '_FILE_OFFSET_BITS == 64' the function 'open' returns a file |
| descriptor opened in the large file mode which enables the file |
| handling functions to use files up to 2^63 bytes in size and offset |
| from -2^63 to 2^63. This happens transparently for the user since |
| all of the lowlevel file handling functions are equally replaced. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'open' is called. If the thread gets canceled these resources stay |
| allocated until the program ends. To avoid this calls to 'open' |
| should be protected using cancellation handlers. |
| |
| The 'open' function is the underlying primitive for the 'fopen' and |
| 'freopen' functions, that create streams. |
| |
| -- Function: int open64 (const char *FILENAME, int FLAGS[, mode_t |
| MODE]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to 'open'. It returns a file descriptor |
| which can be used to access the file named by FILENAME. The only |
| difference is that on 32 bit systems the file is opened in the |
| large file mode. I.e., file length and file offsets can exceed 31 |
| bits. |
| |
| When the sources are translated with '_FILE_OFFSET_BITS == 64' this |
| function is actually available under the name 'open'. I.e., the |
| new, extended API using 64 bit file sizes and offsets transparently |
| replaces the old API. |
| |
| -- Obsolete function: int creat (const char *FILENAME, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is obsolete. The call: |
| |
| creat (FILENAME, MODE) |
| |
| is equivalent to: |
| |
| open (FILENAME, O_WRONLY | O_CREAT | O_TRUNC, MODE) |
| |
| If on a 32 bit machine the sources are translated with |
| '_FILE_OFFSET_BITS == 64' the function 'creat' returns a file |
| descriptor opened in the large file mode which enables the file |
| handling functions to use files up to 2^63 in size and offset from |
| -2^63 to 2^63. This happens transparently for the user since all |
| of the lowlevel file handling functions are equally replaced. |
| |
| -- Obsolete function: int creat64 (const char *FILENAME, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to 'creat'. It returns a file descriptor |
| which can be used to access the file named by FILENAME. The only |
| the difference is that on 32 bit systems the file is opened in the |
| large file mode. I.e., file length and file offsets can exceed 31 |
| bits. |
| |
| To use this file descriptor one must not use the normal operations |
| but instead the counterparts named '*64', e.g., 'read64'. |
| |
| When the sources are translated with '_FILE_OFFSET_BITS == 64' this |
| function is actually available under the name 'open'. I.e., the |
| new, extended API using 64 bit file sizes and offsets transparently |
| replaces the old API. |
| |
| -- Function: int close (int FILEDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The function 'close' closes the file descriptor FILEDES. Closing a |
| file has the following consequences: |
| |
| * The file descriptor is deallocated. |
| |
| * Any record locks owned by the process on the file are |
| unlocked. |
| |
| * When all file descriptors associated with a pipe or FIFO have |
| been closed, any unread data is discarded. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'close' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this, calls to |
| 'close' should be protected using cancellation handlers. |
| |
| The normal return value from 'close' is 0; a value of -1 is |
| returned in case of failure. The following 'errno' error |
| conditions are defined for this function: |
| |
| 'EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| 'EINTR' |
| The 'close' call was interrupted by a signal. *Note |
| Interrupted Primitives::. Here is an example of how to handle |
| 'EINTR' properly: |
| |
| TEMP_FAILURE_RETRY (close (desc)); |
| |
| 'ENOSPC' |
| 'EIO' |
| 'EDQUOT' |
| When the file is accessed by NFS, these errors from 'write' |
| can sometimes not be detected until 'close'. *Note I/O |
| Primitives::, for details on their meaning. |
| |
| Please note that there is _no_ separate 'close64' function. This |
| is not necessary since this function does not determine nor depend |
| on the mode of the file. The kernel which performs the 'close' |
| operation knows which mode the descriptor is used for and can |
| handle this situation. |
| |
| To close a stream, call 'fclose' (*note Closing Streams::) instead of |
| trying to close its underlying file descriptor with 'close'. This |
| flushes any buffered output and updates the stream object to indicate |
| that it is closed. |
| |
| |
| File: libc.info, Node: I/O Primitives, Next: File Position Primitive, Prev: Opening and Closing Files, Up: Low-Level I/O |
| |
| 13.2 Input and Output Primitives |
| ================================ |
| |
| This section describes the functions for performing primitive input and |
| output operations on file descriptors: 'read', 'write', and 'lseek'. |
| These functions are declared in the header file 'unistd.h'. |
| |
| -- Data Type: ssize_t |
| This data type is used to represent the sizes of blocks that can be |
| read or written in a single operation. It is similar to 'size_t', |
| but must be a signed type. |
| |
| -- Function: ssize_t read (int FILEDES, void *BUFFER, size_t SIZE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'read' function reads up to SIZE bytes from the file with |
| descriptor FILEDES, storing the results in the BUFFER. (This is |
| not necessarily a character string, and no terminating null |
| character is added.) |
| |
| The return value is the number of bytes actually read. This might |
| be less than SIZE; for example, if there aren't that many bytes |
| left in the file or if there aren't that many bytes immediately |
| available. The exact behavior depends on what kind of file it is. |
| Note that reading less than SIZE bytes is not an error. |
| |
| A value of zero indicates end-of-file (except if the value of the |
| SIZE argument is also zero). This is not considered an error. If |
| you keep calling 'read' while at end-of-file, it will keep |
| returning zero and doing nothing else. |
| |
| If 'read' returns at least one character, there is no way you can |
| tell whether end-of-file was reached. But if you did reach the |
| end, the next read will return zero. |
| |
| In case of an error, 'read' returns -1. The following 'errno' |
| error conditions are defined for this function: |
| |
| 'EAGAIN' |
| Normally, when no input is immediately available, 'read' waits |
| for some input. But if the 'O_NONBLOCK' flag is set for the |
| file (*note File Status Flags::), 'read' returns immediately |
| without reading any data, and reports this error. |
| |
| *Compatibility Note:* Most versions of BSD Unix use a |
| different error code for this: 'EWOULDBLOCK'. In the GNU C |
| Library, 'EWOULDBLOCK' is an alias for 'EAGAIN', so it doesn't |
| matter which name you use. |
| |
| On some systems, reading a large amount of data from a |
| character special file can also fail with 'EAGAIN' if the |
| kernel cannot find enough physical memory to lock down the |
| user's pages. This is limited to devices that transfer with |
| direct memory access into the user's memory, which means it |
| does not include terminals, since they always use separate |
| buffers inside the kernel. This problem never happens on |
| GNU/Hurd systems. |
| |
| Any condition that could result in 'EAGAIN' can instead result |
| in a successful 'read' which returns fewer bytes than |
| requested. Calling 'read' again immediately would result in |
| 'EAGAIN'. |
| |
| 'EBADF' |
| The FILEDES argument is not a valid file descriptor, or is not |
| open for reading. |
| |
| 'EINTR' |
| 'read' was interrupted by a signal while it was waiting for |
| input. *Note Interrupted Primitives::. A signal will not |
| necessary cause 'read' to return 'EINTR'; it may instead |
| result in a successful 'read' which returns fewer bytes than |
| requested. |
| |
| 'EIO' |
| For many devices, and for disk files, this error code |
| indicates a hardware error. |
| |
| 'EIO' also occurs when a background process tries to read from |
| the controlling terminal, and the normal action of stopping |
| the process by sending it a 'SIGTTIN' signal isn't working. |
| This might happen if the signal is being blocked or ignored, |
| or because the process group is orphaned. *Note Job |
| Control::, for more information about job control, and *note |
| Signal Handling::, for information about signals. |
| |
| 'EINVAL' |
| In some systems, when reading from a character or block |
| device, position and size offsets must be aligned to a |
| particular block size. This error indicates that the offsets |
| were not properly aligned. |
| |
| Please note that there is no function named 'read64'. This is not |
| necessary since this function does not directly modify or handle |
| the possibly wide file offset. Since the kernel handles this state |
| internally, the 'read' function can be used for all cases. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'read' is called. If the thread gets canceled these resources stay |
| allocated until the program ends. To avoid this, calls to 'read' |
| should be protected using cancellation handlers. |
| |
| The 'read' function is the underlying primitive for all of the |
| functions that read from streams, such as 'fgetc'. |
| |
| -- Function: ssize_t pread (int FILEDES, void *BUFFER, size_t SIZE, |
| off_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'pread' function is similar to the 'read' function. The first |
| three arguments are identical, and the return values and error |
| codes also correspond. |
| |
| The difference is the fourth argument and its handling. The data |
| block is not read from the current position of the file descriptor |
| 'filedes'. Instead the data is read from the file starting at |
| position OFFSET. The position of the file descriptor itself is not |
| affected by the operation. The value is the same as before the |
| call. |
| |
| When the source file is compiled with '_FILE_OFFSET_BITS == 64' the |
| 'pread' function is in fact 'pread64' and the type 'off_t' has 64 |
| bits, which makes it possible to handle files up to 2^63 bytes in |
| length. |
| |
| The return value of 'pread' describes the number of bytes read. In |
| the error case it returns -1 like 'read' does and the error codes |
| are also the same, with these additions: |
| |
| 'EINVAL' |
| The value given for OFFSET is negative and therefore illegal. |
| |
| 'ESPIPE' |
| The file descriptor FILEDES is associate with a pipe or a FIFO |
| and this device does not allow positioning of the file |
| pointer. |
| |
| The function is an extension defined in the Unix Single |
| Specification version 2. |
| |
| -- Function: ssize_t pread64 (int FILEDES, void *BUFFER, size_t SIZE, |
| off64_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the 'pread' function. The difference |
| is that the OFFSET parameter is of type 'off64_t' instead of |
| 'off_t' which makes it possible on 32 bit machines to address files |
| larger than 2^31 bytes and up to 2^63 bytes. The file descriptor |
| 'filedes' must be opened using 'open64' since otherwise the large |
| offsets possible with 'off64_t' will lead to errors with a |
| descriptor in small file mode. |
| |
| When the source file is compiled with '_FILE_OFFSET_BITS == 64' on |
| a 32 bit machine this function is actually available under the name |
| 'pread' and so transparently replaces the 32 bit interface. |
| |
| -- Function: ssize_t write (int FILEDES, const void *BUFFER, size_t |
| SIZE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'write' function writes up to SIZE bytes from BUFFER to the |
| file with descriptor FILEDES. The data in BUFFER is not |
| necessarily a character string and a null character is output like |
| any other character. |
| |
| The return value is the number of bytes actually written. This may |
| be SIZE, but can always be smaller. Your program should always |
| call 'write' in a loop, iterating until all the data is written. |
| |
| Once 'write' returns, the data is enqueued to be written and can be |
| read back right away, but it is not necessarily written out to |
| permanent storage immediately. You can use 'fsync' when you need |
| to be sure your data has been permanently stored before continuing. |
| (It is more efficient for the system to batch up consecutive writes |
| and do them all at once when convenient. Normally they will always |
| be written to disk within a minute or less.) Modern systems |
| provide another function 'fdatasync' which guarantees integrity |
| only for the file data and is therefore faster. You can use the |
| 'O_FSYNC' open mode to make 'write' always store the data to disk |
| before returning; *note Operating Modes::. |
| |
| In the case of an error, 'write' returns -1. The following 'errno' |
| error conditions are defined for this function: |
| |
| 'EAGAIN' |
| Normally, 'write' blocks until the write operation is |
| complete. But if the 'O_NONBLOCK' flag is set for the file |
| (*note Control Operations::), it returns immediately without |
| writing any data and reports this error. An example of a |
| situation that might cause the process to block on output is |
| writing to a terminal device that supports flow control, where |
| output has been suspended by receipt of a STOP character. |
| |
| *Compatibility Note:* Most versions of BSD Unix use a |
| different error code for this: 'EWOULDBLOCK'. In the GNU C |
| Library, 'EWOULDBLOCK' is an alias for 'EAGAIN', so it doesn't |
| matter which name you use. |
| |
| On some systems, writing a large amount of data from a |
| character special file can also fail with 'EAGAIN' if the |
| kernel cannot find enough physical memory to lock down the |
| user's pages. This is limited to devices that transfer with |
| direct memory access into the user's memory, which means it |
| does not include terminals, since they always use separate |
| buffers inside the kernel. This problem does not arise on |
| GNU/Hurd systems. |
| |
| 'EBADF' |
| The FILEDES argument is not a valid file descriptor, or is not |
| open for writing. |
| |
| 'EFBIG' |
| The size of the file would become larger than the |
| implementation can support. |
| |
| 'EINTR' |
| The 'write' operation was interrupted by a signal while it was |
| blocked waiting for completion. A signal will not necessarily |
| cause 'write' to return 'EINTR'; it may instead result in a |
| successful 'write' which writes fewer bytes than requested. |
| *Note Interrupted Primitives::. |
| |
| 'EIO' |
| For many devices, and for disk files, this error code |
| indicates a hardware error. |
| |
| 'ENOSPC' |
| The device containing the file is full. |
| |
| 'EPIPE' |
| This error is returned when you try to write to a pipe or FIFO |
| that isn't open for reading by any process. When this |
| happens, a 'SIGPIPE' signal is also sent to the process; see |
| *note Signal Handling::. |
| |
| 'EINVAL' |
| In some systems, when writing to a character or block device, |
| position and size offsets must be aligned to a particular |
| block size. This error indicates that the offsets were not |
| properly aligned. |
| |
| Unless you have arranged to prevent 'EINTR' failures, you should |
| check 'errno' after each failing call to 'write', and if the error |
| was 'EINTR', you should simply repeat the call. *Note Interrupted |
| Primitives::. The easy way to do this is with the macro |
| 'TEMP_FAILURE_RETRY', as follows: |
| |
| nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count)); |
| |
| Please note that there is no function named 'write64'. This is not |
| necessary since this function does not directly modify or handle |
| the possibly wide file offset. Since the kernel handles this state |
| internally the 'write' function can be used for all cases. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'write' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this, calls to |
| 'write' should be protected using cancellation handlers. |
| |
| The 'write' function is the underlying primitive for all of the |
| functions that write to streams, such as 'fputc'. |
| |
| -- Function: ssize_t pwrite (int FILEDES, const void *BUFFER, size_t |
| SIZE, off_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'pwrite' function is similar to the 'write' function. The |
| first three arguments are identical, and the return values and |
| error codes also correspond. |
| |
| The difference is the fourth argument and its handling. The data |
| block is not written to the current position of the file descriptor |
| 'filedes'. Instead the data is written to the file starting at |
| position OFFSET. The position of the file descriptor itself is not |
| affected by the operation. The value is the same as before the |
| call. |
| |
| When the source file is compiled with '_FILE_OFFSET_BITS == 64' the |
| 'pwrite' function is in fact 'pwrite64' and the type 'off_t' has 64 |
| bits, which makes it possible to handle files up to 2^63 bytes in |
| length. |
| |
| The return value of 'pwrite' describes the number of written bytes. |
| In the error case it returns -1 like 'write' does and the error |
| codes are also the same, with these additions: |
| |
| 'EINVAL' |
| The value given for OFFSET is negative and therefore illegal. |
| |
| 'ESPIPE' |
| The file descriptor FILEDES is associated with a pipe or a |
| FIFO and this device does not allow positioning of the file |
| pointer. |
| |
| The function is an extension defined in the Unix Single |
| Specification version 2. |
| |
| -- Function: ssize_t pwrite64 (int FILEDES, const void *BUFFER, size_t |
| SIZE, off64_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the 'pwrite' function. The difference |
| is that the OFFSET parameter is of type 'off64_t' instead of |
| 'off_t' which makes it possible on 32 bit machines to address files |
| larger than 2^31 bytes and up to 2^63 bytes. The file descriptor |
| 'filedes' must be opened using 'open64' since otherwise the large |
| offsets possible with 'off64_t' will lead to errors with a |
| descriptor in small file mode. |
| |
| When the source file is compiled using '_FILE_OFFSET_BITS == 64' on |
| a 32 bit machine this function is actually available under the name |
| 'pwrite' and so transparently replaces the 32 bit interface. |
| |
| |
| File: libc.info, Node: File Position Primitive, Next: Descriptors and Streams, Prev: I/O Primitives, Up: Low-Level I/O |
| |
| 13.3 Setting the File Position of a Descriptor |
| ============================================== |
| |
| Just as you can set the file position of a stream with 'fseek', you can |
| set the file position of a descriptor with 'lseek'. This specifies the |
| position in the file for the next 'read' or 'write' operation. *Note |
| File Positioning::, for more information on the file position and what |
| it means. |
| |
| To read the current file position value from a descriptor, use 'lseek |
| (DESC, 0, SEEK_CUR)'. |
| |
| -- Function: off_t lseek (int FILEDES, off_t OFFSET, int WHENCE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'lseek' function is used to change the file position of the |
| file with descriptor FILEDES. |
| |
| The WHENCE argument specifies how the OFFSET should be interpreted, |
| in the same way as for the 'fseek' function, and it must be one of |
| the symbolic constants 'SEEK_SET', 'SEEK_CUR', or 'SEEK_END'. |
| |
| 'SEEK_SET' |
| Specifies that OFFSET is a count of characters from the |
| beginning of the file. |
| |
| 'SEEK_CUR' |
| Specifies that OFFSET is a count of characters from the |
| current file position. This count may be positive or |
| negative. |
| |
| 'SEEK_END' |
| Specifies that OFFSET is a count of characters from the end of |
| the file. A negative count specifies a position within the |
| current extent of the file; a positive count specifies a |
| position past the current end. If you set the position past |
| the current end, and actually write data, you will extend the |
| file with zeros up to that position. |
| |
| The return value from 'lseek' is normally the resulting file |
| position, measured in bytes from the beginning of the file. You |
| can use this feature together with 'SEEK_CUR' to read the current |
| file position. |
| |
| If you want to append to the file, setting the file position to the |
| current end of file with 'SEEK_END' is not sufficient. Another |
| process may write more data after you seek but before you write, |
| extending the file so the position you write onto clobbers their |
| data. Instead, use the 'O_APPEND' operating mode; *note Operating |
| Modes::. |
| |
| You can set the file position past the current end of the file. |
| This does not by itself make the file longer; 'lseek' never changes |
| the file. But subsequent output at that position will extend the |
| file. Characters between the previous end of file and the new |
| position are filled with zeros. Extending the file in this way can |
| create a "hole": the blocks of zeros are not actually allocated on |
| disk, so the file takes up less space than it appears to; it is |
| then called a "sparse file". |
| |
| If the file position cannot be changed, or the operation is in some |
| way invalid, 'lseek' returns a value of -1. The following 'errno' |
| error conditions are defined for this function: |
| |
| 'EBADF' |
| The FILEDES is not a valid file descriptor. |
| |
| 'EINVAL' |
| The WHENCE argument value is not valid, or the resulting file |
| offset is not valid. A file offset is invalid. |
| |
| 'ESPIPE' |
| The FILEDES corresponds to an object that cannot be |
| positioned, such as a pipe, FIFO or terminal device. (POSIX.1 |
| specifies this error only for pipes and FIFOs, but on GNU |
| systems, you always get 'ESPIPE' if the object is not |
| seekable.) |
| |
| When the source file is compiled with '_FILE_OFFSET_BITS == 64' the |
| 'lseek' function is in fact 'lseek64' and the type 'off_t' has 64 |
| bits which makes it possible to handle files up to 2^63 bytes in |
| length. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'lseek' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this calls to |
| 'lseek' should be protected using cancellation handlers. |
| |
| The 'lseek' function is the underlying primitive for the 'fseek', |
| 'fseeko', 'ftell', 'ftello' and 'rewind' functions, which operate |
| on streams instead of file descriptors. |
| |
| -- Function: off64_t lseek64 (int FILEDES, off64_t OFFSET, int WHENCE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the 'lseek' function. The difference |
| is that the OFFSET parameter is of type 'off64_t' instead of |
| 'off_t' which makes it possible on 32 bit machines to address files |
| larger than 2^31 bytes and up to 2^63 bytes. The file descriptor |
| 'filedes' must be opened using 'open64' since otherwise the large |
| offsets possible with 'off64_t' will lead to errors with a |
| descriptor in small file mode. |
| |
| When the source file is compiled with '_FILE_OFFSET_BITS == 64' on |
| a 32 bits machine this function is actually available under the |
| name 'lseek' and so transparently replaces the 32 bit interface. |
| |
| You can have multiple descriptors for the same file if you open the |
| file more than once, or if you duplicate a descriptor with 'dup'. |
| Descriptors that come from separate calls to 'open' have independent |
| file positions; using 'lseek' on one descriptor has no effect on the |
| other. For example, |
| |
| { |
| int d1, d2; |
| char buf[4]; |
| d1 = open ("foo", O_RDONLY); |
| d2 = open ("foo", O_RDONLY); |
| lseek (d1, 1024, SEEK_SET); |
| read (d2, buf, 4); |
| } |
| |
| will read the first four characters of the file 'foo'. (The |
| error-checking code necessary for a real program has been omitted here |
| for brevity.) |
| |
| By contrast, descriptors made by duplication share a common file |
| position with the original descriptor that was duplicated. Anything |
| which alters the file position of one of the duplicates, including |
| reading or writing data, affects all of them alike. Thus, for example, |
| |
| { |
| int d1, d2, d3; |
| char buf1[4], buf2[4]; |
| d1 = open ("foo", O_RDONLY); |
| d2 = dup (d1); |
| d3 = dup (d2); |
| lseek (d3, 1024, SEEK_SET); |
| read (d1, buf1, 4); |
| read (d2, buf2, 4); |
| } |
| |
| will read four characters starting with the 1024'th character of 'foo', |
| and then four more characters starting with the 1028'th character. |
| |
| -- Data Type: off_t |
| This is a signed integer type used to represent file sizes. In the |
| GNU C Library, this type is no narrower than 'int'. |
| |
| If the source is compiled with '_FILE_OFFSET_BITS == 64' this type |
| is transparently replaced by 'off64_t'. |
| |
| -- Data Type: off64_t |
| This type is used similar to 'off_t'. The difference is that even |
| on 32 bit machines, where the 'off_t' type would have 32 bits, |
| 'off64_t' has 64 bits and so is able to address files up to 2^63 |
| bytes in length. |
| |
| When compiling with '_FILE_OFFSET_BITS == 64' this type is |
| available under the name 'off_t'. |
| |
| These aliases for the 'SEEK_...' constants exist for the sake of |
| compatibility with older BSD systems. They are defined in two different |
| header files: 'fcntl.h' and 'sys/file.h'. |
| |
| 'L_SET' |
| An alias for 'SEEK_SET'. |
| |
| 'L_INCR' |
| An alias for 'SEEK_CUR'. |
| |
| 'L_XTND' |
| An alias for 'SEEK_END'. |
| |
| |
| File: libc.info, Node: Descriptors and Streams, Next: Stream/Descriptor Precautions, Prev: File Position Primitive, Up: Low-Level I/O |
| |
| 13.4 Descriptors and Streams |
| ============================ |
| |
| Given an open file descriptor, you can create a stream for it with the |
| 'fdopen' function. You can get the underlying file descriptor for an |
| existing stream with the 'fileno' function. These functions are |
| declared in the header file 'stdio.h'. |
| |
| -- Function: FILE * fdopen (int FILEDES, const char *OPENTYPE) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock | |
| *Note POSIX Safety Concepts::. |
| |
| The 'fdopen' function returns a new stream for the file descriptor |
| FILEDES. |
| |
| The OPENTYPE argument is interpreted in the same way as for the |
| 'fopen' function (*note Opening Streams::), except that the 'b' |
| option is not permitted; this is because GNU systems make no |
| distinction between text and binary files. Also, '"w"' and '"w+"' |
| do not cause truncation of the file; these have an effect only when |
| opening a file, and in this case the file has already been opened. |
| You must make sure that the OPENTYPE argument matches the actual |
| mode of the open file descriptor. |
| |
| The return value is the new stream. If the stream cannot be |
| created (for example, if the modes for the file indicated by the |
| file descriptor do not permit the access specified by the OPENTYPE |
| argument), a null pointer is returned instead. |
| |
| In some other systems, 'fdopen' may fail to detect that the modes |
| for file descriptor do not permit the access specified by |
| 'opentype'. The GNU C Library always checks for this. |
| |
| For an example showing the use of the 'fdopen' function, see *note |
| Creating a Pipe::. |
| |
| -- Function: int fileno (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the file descriptor associated with the |
| stream STREAM. If an error is detected (for example, if the STREAM |
| is not valid) or if STREAM does not do I/O to a file, 'fileno' |
| returns -1. |
| |
| -- Function: int fileno_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'fileno_unlocked' function is equivalent to the 'fileno' |
| function except that it does not implicitly lock the stream if the |
| state is 'FSETLOCKING_INTERNAL'. |
| |
| This function is a GNU extension. |
| |
| There are also symbolic constants defined in 'unistd.h' for the file |
| descriptors belonging to the standard streams 'stdin', 'stdout', and |
| 'stderr'; see *note Standard Streams::. |
| |
| 'STDIN_FILENO' |
| This macro has value '0', which is the file descriptor for standard |
| input. |
| |
| 'STDOUT_FILENO' |
| This macro has value '1', which is the file descriptor for standard |
| output. |
| |
| 'STDERR_FILENO' |
| This macro has value '2', which is the file descriptor for standard |
| error output. |
| |
| |
| File: libc.info, Node: Stream/Descriptor Precautions, Next: Scatter-Gather, Prev: Descriptors and Streams, Up: Low-Level I/O |
| |
| 13.5 Dangers of Mixing Streams and Descriptors |
| ============================================== |
| |
| You can have multiple file descriptors and streams (let's call both |
| streams and descriptors "channels" for short) connected to the same |
| file, but you must take care to avoid confusion between channels. There |
| are two cases to consider: "linked" channels that share a single file |
| position value, and "independent" channels that have their own file |
| positions. |
| |
| It's best to use just one channel in your program for actual data |
| transfer to any given file, except when all the access is for input. |
| For example, if you open a pipe (something you can only do at the file |
| descriptor level), either do all I/O with the descriptor, or construct a |
| stream from the descriptor with 'fdopen' and then do all I/O with the |
| stream. |
| |
| * Menu: |
| |
| * Linked Channels:: Dealing with channels sharing a file position. |
| * Independent Channels:: Dealing with separately opened, unlinked channels. |
| * Cleaning Streams:: Cleaning a stream makes it safe to use |
| another channel. |
| |
| |
| File: libc.info, Node: Linked Channels, Next: Independent Channels, Up: Stream/Descriptor Precautions |
| |
| 13.5.1 Linked Channels |
| ---------------------- |
| |
| Channels that come from a single opening share the same file position; |
| we call them "linked" channels. Linked channels result when you make a |
| stream from a descriptor using 'fdopen', when you get a descriptor from |
| a stream with 'fileno', when you copy a descriptor with 'dup' or 'dup2', |
| and when descriptors are inherited during 'fork'. For files that don't |
| support random access, such as terminals and pipes, _all_ channels are |
| effectively linked. On random-access files, all append-type output |
| streams are effectively linked to each other. |
| |
| If you have been using a stream for I/O (or have just opened the |
| stream), and you want to do I/O using another channel (either a stream |
| or a descriptor) that is linked to it, you must first "clean up" the |
| stream that you have been using. *Note Cleaning Streams::. |
| |
| Terminating a process, or executing a new program in the process, |
| destroys all the streams in the process. If descriptors linked to these |
| streams persist in other processes, their file positions become |
| undefined as a result. To prevent this, you must clean up the streams |
| before destroying them. |
| |
| |
| File: libc.info, Node: Independent Channels, Next: Cleaning Streams, Prev: Linked Channels, Up: Stream/Descriptor Precautions |
| |
| 13.5.2 Independent Channels |
| --------------------------- |
| |
| When you open channels (streams or descriptors) separately on a seekable |
| file, each channel has its own file position. These are called |
| "independent channels". |
| |
| The system handles each channel independently. Most of the time, |
| this is quite predictable and natural (especially for input): each |
| channel can read or write sequentially at its own place in the file. |
| However, if some of the channels are streams, you must take these |
| precautions: |
| |
| * You should clean an output stream after use, before doing anything |
| else that might read or write from the same part of the file. |
| |
| * You should clean an input stream before reading data that may have |
| been modified using an independent channel. Otherwise, you might |
| read obsolete data that had been in the stream's buffer. |
| |
| If you do output to one channel at the end of the file, this will |
| certainly leave the other independent channels positioned somewhere |
| before the new end. You cannot reliably set their file positions to the |
| new end of file before writing, because the file can always be extended |
| by another process between when you set the file position and when you |
| write the data. Instead, use an append-type descriptor or stream; they |
| always output at the current end of the file. In order to make the |
| end-of-file position accurate, you must clean the output channel you |
| were using, if it is a stream. |
| |
| It's impossible for two channels to have separate file pointers for a |
| file that doesn't support random access. Thus, channels for reading or |
| writing such files are always linked, never independent. Append-type |
| channels are also always linked. For these channels, follow the rules |
| for linked channels; see *note Linked Channels::. |
| |
| |
| File: libc.info, Node: Cleaning Streams, Prev: Independent Channels, Up: Stream/Descriptor Precautions |
| |
| 13.5.3 Cleaning Streams |
| ----------------------- |
| |
| You can use 'fflush' to clean a stream in most cases. |
| |
| You can skip the 'fflush' if you know the stream is already clean. A |
| stream is clean whenever its buffer is empty. For example, an |
| unbuffered stream is always clean. An input stream that is at |
| end-of-file is clean. A line-buffered stream is clean when the last |
| character output was a newline. However, a just-opened input stream |
| might not be clean, as its input buffer might not be empty. |
| |
| There is one case in which cleaning a stream is impossible on most |
| systems. This is when the stream is doing input from a file that is not |
| random-access. Such streams typically read ahead, and when the file is |
| not random access, there is no way to give back the excess data already |
| read. When an input stream reads from a random-access file, 'fflush' |
| does clean the stream, but leaves the file pointer at an unpredictable |
| place; you must set the file pointer before doing any further I/O. |
| |
| Closing an output-only stream also does 'fflush', so this is a valid |
| way of cleaning an output stream. |
| |
| You need not clean a stream before using its descriptor for control |
| operations such as setting terminal modes; these operations don't affect |
| the file position and are not affected by it. You can use any |
| descriptor for these operations, and all channels are affected |
| simultaneously. However, text already "output" to a stream but still |
| buffered by the stream will be subject to the new terminal modes when |
| subsequently flushed. To make sure "past" output is covered by the |
| terminal settings that were in effect at the time, flush the output |
| streams for that terminal before setting the modes. *Note Terminal |
| Modes::. |
| |
| |
| File: libc.info, Node: Scatter-Gather, Next: Memory-mapped I/O, Prev: Stream/Descriptor Precautions, Up: Low-Level I/O |
| |
| 13.6 Fast Scatter-Gather I/O |
| ============================ |
| |
| Some applications may need to read or write data to multiple buffers, |
| which are separated in memory. Although this can be done easily enough |
| with multiple calls to 'read' and 'write', it is inefficient because |
| there is overhead associated with each kernel call. |
| |
| Instead, many platforms provide special high-speed primitives to |
| perform these "scatter-gather" operations in a single kernel call. The |
| GNU C Library will provide an emulation on any system that lacks these |
| primitives, so they are not a portability threat. They are defined in |
| 'sys/uio.h'. |
| |
| These functions are controlled with arrays of 'iovec' structures, |
| which describe the location and size of each buffer. |
| |
| -- Data Type: struct iovec |
| |
| The 'iovec' structure describes a buffer. It contains two fields: |
| |
| 'void *iov_base' |
| Contains the address of a buffer. |
| |
| 'size_t iov_len' |
| Contains the length of the buffer. |
| |
| -- Function: ssize_t readv (int FILEDES, const struct iovec *VECTOR, |
| int COUNT) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note |
| POSIX Safety Concepts::. |
| |
| The 'readv' function reads data from FILEDES and scatters it into |
| the buffers described in VECTOR, which is taken to be COUNT |
| structures long. As each buffer is filled, data is sent to the |
| next. |
| |
| Note that 'readv' is not guaranteed to fill all the buffers. It |
| may stop at any point, for the same reasons 'read' would. |
| |
| The return value is a count of bytes (_not_ buffers) read, 0 |
| indicating end-of-file, or -1 indicating an error. The possible |
| errors are the same as in 'read'. |
| |
| -- Function: ssize_t writev (int FILEDES, const struct iovec *VECTOR, |
| int COUNT) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note |
| POSIX Safety Concepts::. |
| |
| The 'writev' function gathers data from the buffers described in |
| VECTOR, which is taken to be COUNT structures long, and writes them |
| to 'filedes'. As each buffer is written, it moves on to the next. |
| |
| Like 'readv', 'writev' may stop midstream under the same conditions |
| 'write' would. |
| |
| The return value is a count of bytes written, or -1 indicating an |
| error. The possible errors are the same as in 'write'. |
| |
| Note that if the buffers are small (under about 1kB), high-level |
| streams may be easier to use than these functions. However, 'readv' and |
| 'writev' are more efficient when the individual buffers themselves (as |
| opposed to the total output), are large. In that case, a high-level |
| stream would not be able to cache the data effectively. |
| |
| |
| File: libc.info, Node: Memory-mapped I/O, Next: Waiting for I/O, Prev: Scatter-Gather, Up: Low-Level I/O |
| |
| 13.7 Memory-mapped I/O |
| ====================== |
| |
| On modern operating systems, it is possible to "mmap" (pronounced |
| "em-map") a file to a region of memory. When this is done, the file can |
| be accessed just like an array in the program. |
| |
| This is more efficient than 'read' or 'write', as only the regions of |
| the file that a program actually accesses are loaded. Accesses to |
| not-yet-loaded parts of the mmapped region are handled in the same way |
| as swapped out pages. |
| |
| Since mmapped pages can be stored back to their file when physical |
| memory is low, it is possible to mmap files orders of magnitude larger |
| than both the physical memory _and_ swap space. The only limit is |
| address space. The theoretical limit is 4GB on a 32-bit machine - |
| however, the actual limit will be smaller since some areas will be |
| reserved for other purposes. If the LFS interface is used the file size |
| on 32-bit systems is not limited to 2GB (offsets are signed which |
| reduces the addressable area of 4GB by half); the full 64-bit are |
| available. |
| |
| Memory mapping only works on entire pages of memory. Thus, addresses |
| for mapping must be page-aligned, and length values will be rounded up. |
| To determine the size of a page the machine uses one should use |
| |
| size_t page_size = (size_t) sysconf (_SC_PAGESIZE); |
| |
| These functions are declared in 'sys/mman.h'. |
| |
| -- Function: void * mmap (void *ADDRESS, size_t LENGTH, int PROTECT, |
| int FLAGS, int FILEDES, off_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'mmap' function creates a new mapping, connected to bytes |
| (OFFSET) to (OFFSET + LENGTH - 1) in the file open on FILEDES. A |
| new reference for the file specified by FILEDES is created, which |
| is not removed by closing the file. |
| |
| ADDRESS gives a preferred starting address for the mapping. 'NULL' |
| expresses no preference. Any previous mapping at that address is |
| automatically removed. The address you give may still be changed, |
| unless you use the 'MAP_FIXED' flag. |
| |
| PROTECT contains flags that control what kind of access is |
| permitted. They include 'PROT_READ', 'PROT_WRITE', and |
| 'PROT_EXEC', which permit reading, writing, and execution, |
| respectively. Inappropriate access will cause a segfault (*note |
| Program Error Signals::). |
| |
| Note that most hardware designs cannot support write permission |
| without read permission, and many do not distinguish read and |
| execute permission. Thus, you may receive wider permissions than |
| you ask for, and mappings of write-only files may be denied even if |
| you do not use 'PROT_READ'. |
| |
| FLAGS contains flags that control the nature of the map. One of |
| 'MAP_SHARED' or 'MAP_PRIVATE' must be specified. |
| |
| They include: |
| |
| 'MAP_PRIVATE' |
| This specifies that writes to the region should never be |
| written back to the attached file. Instead, a copy is made |
| for the process, and the region will be swapped normally if |
| memory runs low. No other process will see the changes. |
| |
| Since private mappings effectively revert to ordinary memory |
| when written to, you must have enough virtual memory for a |
| copy of the entire mmapped region if you use this mode with |
| 'PROT_WRITE'. |
| |
| 'MAP_SHARED' |
| This specifies that writes to the region will be written back |
| to the file. Changes made will be shared immediately with |
| other processes mmaping the same file. |
| |
| Note that actual writing may take place at any time. You need |
| to use 'msync', described below, if it is important that other |
| processes using conventional I/O get a consistent view of the |
| file. |
| |
| 'MAP_FIXED' |
| This forces the system to use the exact mapping address |
| specified in ADDRESS and fail if it can't. |
| |
| 'MAP_ANONYMOUS' |
| 'MAP_ANON' |
| This flag tells the system to create an anonymous mapping, not |
| connected to a file. FILEDES and OFF are ignored, and the |
| region is initialized with zeros. |
| |
| Anonymous maps are used as the basic primitive to extend the |
| heap on some systems. They are also useful to share data |
| between multiple tasks without creating a file. |
| |
| On some systems using private anonymous mmaps is more |
| efficient than using 'malloc' for large blocks. This is not |
| an issue with the GNU C Library, as the included 'malloc' |
| automatically uses 'mmap' where appropriate. |
| |
| 'mmap' returns the address of the new mapping, or 'MAP_FAILED' for |
| an error. |
| |
| Possible errors include: |
| |
| 'EINVAL' |
| |
| Either ADDRESS was unusable, or inconsistent FLAGS were given. |
| |
| 'EACCES' |
| |
| FILEDES was not open for the type of access specified in |
| PROTECT. |
| |
| 'ENOMEM' |
| |
| Either there is not enough memory for the operation, or the |
| process is out of address space. |
| |
| 'ENODEV' |
| |
| This file is of a type that doesn't support mapping. |
| |
| 'ENOEXEC' |
| |
| The file is on a filesystem that doesn't support mapping. |
| |
| -- Function: void * mmap64 (void *ADDRESS, size_t LENGTH, int PROTECT, |
| int FLAGS, int FILEDES, off64_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'mmap64' function is equivalent to the 'mmap' function but the |
| OFFSET parameter is of type 'off64_t'. On 32-bit systems this |
| allows the file associated with the FILEDES descriptor to be larger |
| than 2GB. FILEDES must be a descriptor returned from a call to |
| 'open64' or 'fopen64' and 'freopen64' where the descriptor is |
| retrieved with 'fileno'. |
| |
| When the sources are translated with '_FILE_OFFSET_BITS == 64' this |
| function is actually available under the name 'mmap'. I.e., the |
| new, extended API using 64 bit file sizes and offsets transparently |
| replaces the old API. |
| |
| -- Function: int munmap (void *ADDR, size_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'munmap' removes any memory maps from (ADDR) to (ADDR + LENGTH). |
| LENGTH should be the length of the mapping. |
| |
| It is safe to unmap multiple mappings in one command, or include |
| unmapped space in the range. It is also possible to unmap only |
| part of an existing mapping. However, only entire pages can be |
| removed. If LENGTH is not an even number of pages, it will be |
| rounded up. |
| |
| It returns 0 for success and -1 for an error. |
| |
| One error is possible: |
| |
| 'EINVAL' |
| The memory range given was outside the user mmap range or |
| wasn't page aligned. |
| |
| -- Function: int msync (void *ADDRESS, size_t LENGTH, int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| When using shared mappings, the kernel can write the file at any |
| time before the mapping is removed. To be certain data has |
| actually been written to the file and will be accessible to |
| non-memory-mapped I/O, it is necessary to use this function. |
| |
| It operates on the region ADDRESS to (ADDRESS + LENGTH). It may be |
| used on part of a mapping or multiple mappings, however the region |
| given should not contain any unmapped space. |
| |
| FLAGS can contain some options: |
| |
| 'MS_SYNC' |
| |
| This flag makes sure the data is actually written _to disk_. |
| Normally 'msync' only makes sure that accesses to a file with |
| conventional I/O reflect the recent changes. |
| |
| 'MS_ASYNC' |
| |
| This tells 'msync' to begin the synchronization, but not to |
| wait for it to complete. |
| |
| 'msync' returns 0 for success and -1 for error. Errors include: |
| |
| 'EINVAL' |
| An invalid region was given, or the FLAGS were invalid. |
| |
| 'EFAULT' |
| There is no existing mapping in at least part of the given |
| region. |
| |
| -- Function: void * mremap (void *ADDRESS, size_t LENGTH, size_t |
| NEW_LENGTH, int FLAG) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function can be used to change the size of an existing memory |
| area. ADDRESS and LENGTH must cover a region entirely mapped in |
| the same 'mmap' statement. A new mapping with the same |
| characteristics will be returned with the length NEW_LENGTH. |
| |
| One option is possible, 'MREMAP_MAYMOVE'. If it is given in FLAGS, |
| the system may remove the existing mapping and create a new one of |
| the desired length in another location. |
| |
| The address of the resulting mapping is returned, or -1. Possible |
| error codes include: |
| |
| 'EFAULT' |
| There is no existing mapping in at least part of the original |
| region, or the region covers two or more distinct mappings. |
| |
| 'EINVAL' |
| The address given is misaligned or inappropriate. |
| |
| 'EAGAIN' |
| The region has pages locked, and if extended it would exceed |
| the process's resource limit for locked pages. *Note Limits |
| on Resources::. |
| |
| 'ENOMEM' |
| The region is private writable, and insufficient virtual |
| memory is available to extend it. Also, this error will occur |
| if 'MREMAP_MAYMOVE' is not given and the extension would |
| collide with another mapped region. |
| |
| This function is only available on a few systems. Except for |
| performing optional optimizations one should not rely on this function. |
| |
| Not all file descriptors may be mapped. Sockets, pipes, and most |
| devices only allow sequential access and do not fit into the mapping |
| abstraction. In addition, some regular files may not be mmapable, and |
| older kernels may not support mapping at all. Thus, programs using |
| 'mmap' should have a fallback method to use should it fail. *Note |
| (standards)Mmap::. |
| |
| -- Function: int madvise (void *ADDR, size_t LENGTH, int ADVICE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function can be used to provide the system with ADVICE about |
| the intended usage patterns of the memory region starting at ADDR |
| and extending LENGTH bytes. |
| |
| The valid BSD values for ADVICE are: |
| |
| 'MADV_NORMAL' |
| The region should receive no further special treatment. |
| |
| 'MADV_RANDOM' |
| The region will be accessed via random page references. The |
| kernel should page-in the minimal number of pages for each |
| page fault. |
| |
| 'MADV_SEQUENTIAL' |
| The region will be accessed via sequential page references. |
| This may cause the kernel to aggressively read-ahead, |
| expecting further sequential references after any page fault |
| within this region. |
| |
| 'MADV_WILLNEED' |
| The region will be needed. The pages within this region may |
| be pre-faulted in by the kernel. |
| |
| 'MADV_DONTNEED' |
| The region is no longer needed. The kernel may free these |
| pages, causing any changes to the pages to be lost, as well as |
| swapped out pages to be discarded. |
| |
| The POSIX names are slightly different, but with the same meanings: |
| |
| 'POSIX_MADV_NORMAL' |
| This corresponds with BSD's 'MADV_NORMAL'. |
| |
| 'POSIX_MADV_RANDOM' |
| This corresponds with BSD's 'MADV_RANDOM'. |
| |
| 'POSIX_MADV_SEQUENTIAL' |
| This corresponds with BSD's 'MADV_SEQUENTIAL'. |
| |
| 'POSIX_MADV_WILLNEED' |
| This corresponds with BSD's 'MADV_WILLNEED'. |
| |
| 'POSIX_MADV_DONTNEED' |
| This corresponds with BSD's 'MADV_DONTNEED'. |
| |
| 'madvise' returns 0 for success and -1 for error. Errors include: |
| |
| 'EINVAL' |
| An invalid region was given, or the ADVICE was invalid. |
| |
| 'EFAULT' |
| There is no existing mapping in at least part of the given |
| region. |
| |
| -- Function: int shm_open (const char *NAME, int OFLAG, mode_t MODE) |
| Preliminary: | MT-Safe locale | AS-Unsafe init heap lock | |
| AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function returns a file descriptor that can be used to |
| allocate shared memory via mmap. Unrelated processes can use same |
| NAME to create or open existing shared memory objects. |
| |
| A NAME argument specifies the shared memory object to be opened. |
| In the GNU C Library it must be a string smaller than 'NAME_MAX' |
| bytes starting with an optional slash but containing no other |
| slashes. |
| |
| The semantics of OFLAG and MODE arguments is same as in 'open'. |
| |
| 'shm_open' returns the file descriptor on success or -1 on error. |
| On failure 'errno' is set. |
| |
| -- Function: int shm_unlink (const char *NAME) |
| Preliminary: | MT-Safe locale | AS-Unsafe init heap lock | |
| AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function is inverse of 'shm_open' and removes the object with |
| the given NAME previously created by 'shm_open'. |
| |
| 'shm_unlink' returns 0 on success or -1 on error. On failure |
| 'errno' is set. |
| |
| |
| File: libc.info, Node: Waiting for I/O, Next: Synchronizing I/O, Prev: Memory-mapped I/O, Up: Low-Level I/O |
| |
| 13.8 Waiting for Input or Output |
| ================================ |
| |
| Sometimes a program needs to accept input on multiple input channels |
| whenever input arrives. For example, some workstations may have devices |
| such as a digitizing tablet, function button box, or dial box that are |
| connected via normal asynchronous serial interfaces; good user interface |
| style requires responding immediately to input on any device. Another |
| example is a program that acts as a server to several other processes |
| via pipes or sockets. |
| |
| You cannot normally use 'read' for this purpose, because this blocks |
| the program until input is available on one particular file descriptor; |
| input on other channels won't wake it up. You could set nonblocking |
| mode and poll each file descriptor in turn, but this is very |
| inefficient. |
| |
| A better solution is to use the 'select' function. This blocks the |
| program until input or output is ready on a specified set of file |
| descriptors, or until a timer expires, whichever comes first. This |
| facility is declared in the header file 'sys/types.h'. |
| |
| In the case of a server socket (*note Listening::), we say that |
| "input" is available when there are pending connections that could be |
| accepted (*note Accepting Connections::). 'accept' for server sockets |
| blocks and interacts with 'select' just as 'read' does for normal input. |
| |
| The file descriptor sets for the 'select' function are specified as |
| 'fd_set' objects. Here is the description of the data type and some |
| macros for manipulating these objects. |
| |
| -- Data Type: fd_set |
| The 'fd_set' data type represents file descriptor sets for the |
| 'select' function. It is actually a bit array. |
| |
| -- Macro: int FD_SETSIZE |
| The value of this macro is the maximum number of file descriptors |
| that a 'fd_set' object can hold information about. On systems with |
| a fixed maximum number, 'FD_SETSIZE' is at least that number. On |
| some systems, including GNU, there is no absolute limit on the |
| number of descriptors open, but this macro still has a constant |
| value which controls the number of bits in an 'fd_set'; if you get |
| a file descriptor with a value as high as 'FD_SETSIZE', you cannot |
| put that descriptor into an 'fd_set'. |
| |
| -- Macro: void FD_ZERO (fd_set *SET) |
| Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This macro initializes the file descriptor set SET to be the empty |
| set. |
| |
| -- Macro: void FD_SET (int FILEDES, fd_set *SET) |
| Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This macro adds FILEDES to the file descriptor set SET. |
| |
| The FILEDES parameter must not have side effects since it is |
| evaluated more than once. |
| |
| -- Macro: void FD_CLR (int FILEDES, fd_set *SET) |
| Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This macro removes FILEDES from the file descriptor set SET. |
| |
| The FILEDES parameter must not have side effects since it is |
| evaluated more than once. |
| |
| -- Macro: int FD_ISSET (int FILEDES, const fd_set *SET) |
| Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This macro returns a nonzero value (true) if FILEDES is a member of |
| the file descriptor set SET, and zero (false) otherwise. |
| |
| The FILEDES parameter must not have side effects since it is |
| evaluated more than once. |
| |
| Next, here is the description of the 'select' function itself. |
| |
| -- Function: int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS, |
| fd_set *EXCEPT-FDS, struct timeval *TIMEOUT) |
| Preliminary: | MT-Safe race:read-fds race:write-fds race:except-fds |
| | AS-Safe | AC-Safe | *Note POSIX Safety Concepts::. |
| |
| The 'select' function blocks the calling process until there is |
| activity on any of the specified sets of file descriptors, or until |
| the timeout period has expired. |
| |
| The file descriptors specified by the READ-FDS argument are checked |
| to see if they are ready for reading; the WRITE-FDS file |
| descriptors are checked to see if they are ready for writing; and |
| the EXCEPT-FDS file descriptors are checked for exceptional |
| conditions. You can pass a null pointer for any of these arguments |
| if you are not interested in checking for that kind of condition. |
| |
| A file descriptor is considered ready for reading if a 'read' call |
| will not block. This usually includes the read offset being at the |
| end of the file or there is an error to report. A server socket is |
| considered ready for reading if there is a pending connection which |
| can be accepted with 'accept'; *note Accepting Connections::. A |
| client socket is ready for writing when its connection is fully |
| established; *note Connecting::. |
| |
| "Exceptional conditions" does not mean errors--errors are reported |
| immediately when an erroneous system call is executed, and do not |
| constitute a state of the descriptor. Rather, they include |
| conditions such as the presence of an urgent message on a socket. |
| (*Note Sockets::, for information on urgent messages.) |
| |
| The 'select' function checks only the first NFDS file descriptors. |
| The usual thing is to pass 'FD_SETSIZE' as the value of this |
| argument. |
| |
| The TIMEOUT specifies the maximum time to wait. If you pass a null |
| pointer for this argument, it means to block indefinitely until one |
| of the file descriptors is ready. Otherwise, you should provide |
| the time in 'struct timeval' format; see *note High-Resolution |
| Calendar::. Specify zero as the time (a 'struct timeval' |
| containing all zeros) if you want to find out which descriptors are |
| ready without waiting if none are ready. |
| |
| The normal return value from 'select' is the total number of ready |
| file descriptors in all of the sets. Each of the argument sets is |
| overwritten with information about the descriptors that are ready |
| for the corresponding operation. Thus, to see if a particular |
| descriptor DESC has input, use 'FD_ISSET (DESC, READ-FDS)' after |
| 'select' returns. |
| |
| If 'select' returns because the timeout period expires, it returns |
| a value of zero. |
| |
| Any signal will cause 'select' to return immediately. So if your |
| program uses signals, you can't rely on 'select' to keep waiting |
| for the full time specified. If you want to be sure of waiting for |
| a particular amount of time, you must check for 'EINTR' and repeat |
| the 'select' with a newly calculated timeout based on the current |
| time. See the example below. See also *note Interrupted |
| Primitives::. |
| |
| If an error occurs, 'select' returns '-1' and does not modify the |
| argument file descriptor sets. The following 'errno' error |
| conditions are defined for this function: |
| |
| 'EBADF' |
| One of the file descriptor sets specified an invalid file |
| descriptor. |
| |
| 'EINTR' |
| The operation was interrupted by a signal. *Note Interrupted |
| Primitives::. |
| |
| 'EINVAL' |
| The TIMEOUT argument is invalid; one of the components is |
| negative or too large. |
| |
| *Portability Note:* The 'select' function is a BSD Unix feature. |
| |
| Here is an example showing how you can use 'select' to establish a |
| timeout period for reading from a file descriptor. The 'input_timeout' |
| function blocks the calling process until input is available on the file |
| descriptor, or until the timeout period expires. |
| |
| |
| #include <errno.h> |
| #include <stdio.h> |
| #include <unistd.h> |
| #include <sys/types.h> |
| #include <sys/time.h> |
| |
| int |
| input_timeout (int filedes, unsigned int seconds) |
| { |
| fd_set set; |
| struct timeval timeout; |
| |
| /* Initialize the file descriptor set. */ |
| FD_ZERO (&set); |
| FD_SET (filedes, &set); |
| |
| /* Initialize the timeout data structure. */ |
| timeout.tv_sec = seconds; |
| timeout.tv_usec = 0; |
| |
| /* 'select' returns 0 if timeout, 1 if input available, -1 if error. */ |
| return TEMP_FAILURE_RETRY (select (FD_SETSIZE, |
| &set, NULL, NULL, |
| &timeout)); |
| } |
| |
| int |
| main (void) |
| { |
| fprintf (stderr, "select returned %d.\n", |
| input_timeout (STDIN_FILENO, 5)); |
| return 0; |
| } |
| |
| There is another example showing the use of 'select' to multiplex |
| input from multiple sockets in *note Server Example::. |
| |
| |
| File: libc.info, Node: Synchronizing I/O, Next: Asynchronous I/O, Prev: Waiting for I/O, Up: Low-Level I/O |
| |
| 13.9 Synchronizing I/O operations |
| ================================= |
| |
| In most modern operating systems, the normal I/O operations are not |
| executed synchronously. I.e., even if a 'write' system call returns, |
| this does not mean the data is actually written to the media, e.g., the |
| disk. |
| |
| In situations where synchronization points are necessary, you can use |
| special functions which ensure that all operations finish before they |
| return. |
| |
| -- Function: void sync (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| A call to this function will not return as long as there is data |
| which has not been written to the device. All dirty buffers in the |
| kernel will be written and so an overall consistent system can be |
| achieved (if no other process in parallel writes data). |
| |
| A prototype for 'sync' can be found in 'unistd.h'. |
| |
| Programs more often want to ensure that data written to a given file |
| is committed, rather than all data in the system. For this, 'sync' is |
| overkill. |
| |
| -- Function: int fsync (int FILDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'fsync' function can be used to make sure all data associated |
| with the open file FILDES is written to the device associated with |
| the descriptor. The function call does not return unless all |
| actions have finished. |
| |
| A prototype for 'fsync' can be found in 'unistd.h'. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'fsync' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this, calls to |
| 'fsync' should be protected using cancellation handlers. |
| |
| The return value of the function is zero if no error occurred. |
| Otherwise it is -1 and the global variable ERRNO is set to the |
| following values: |
| 'EBADF' |
| The descriptor FILDES is not valid. |
| |
| 'EINVAL' |
| No synchronization is possible since the system does not |
| implement this. |
| |
| Sometimes it is not even necessary to write all data associated with |
| a file descriptor. E.g., in database files which do not change in size |
| it is enough to write all the file content data to the device. |
| Meta-information, like the modification time etc., are not that |
| important and leaving such information uncommitted does not prevent a |
| successful recovering of the file in case of a problem. |
| |
| -- Function: int fdatasync (int FILDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| When a call to the 'fdatasync' function returns, it is ensured that |
| all of the file data is written to the device. For all pending I/O |
| operations, the parts guaranteeing data integrity finished. |
| |
| Not all systems implement the 'fdatasync' operation. On systems |
| missing this functionality 'fdatasync' is emulated by a call to |
| 'fsync' since the performed actions are a superset of those |
| required by 'fdatasync'. |
| |
| The prototype for 'fdatasync' is in 'unistd.h'. |
| |
| The return value of the function is zero if no error occurred. |
| Otherwise it is -1 and the global variable ERRNO is set to the |
| following values: |
| 'EBADF' |
| The descriptor FILDES is not valid. |
| |
| 'EINVAL' |
| No synchronization is possible since the system does not |
| implement this. |
| |
| |
| File: libc.info, Node: Asynchronous I/O, Next: Control Operations, Prev: Synchronizing I/O, Up: Low-Level I/O |
| |
| 13.10 Perform I/O Operations in Parallel |
| ======================================== |
| |
| The POSIX.1b standard defines a new set of I/O operations which can |
| significantly reduce the time an application spends waiting at 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 which starts executing the function |
| pointed to by 'sigev_notify_function'. |
| |
| 'int aio_lio_opcode' |
| This element is only used by the 'lio_listio' and |
| '[lio_listio64' functions. Since these functions allow an |
| arbitrary number of operations to start at once, and since |
| each operation can be input or output (or nothing), the |
| information must be stored in the control block. See the |
| description of 'struct aiocb' for a description of the |
| possible values. |
| |
| When the sources are compiled using '_FILE_OFFSET_BITS == 64' on a |
| 32 bit machine, this type is available under the name 'struct |
| aiocb64', since the LFS transparently replaces the old interface. |
| |
| * Menu: |
| |
| * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations. |
| * Status of AIO Operations:: Getting the Status of AIO Operations. |
| * Synchronizing AIO Operations:: Getting into a consistent state. |
| * Cancel AIO Operations:: Cancellation of AIO Operations. |
| * Configuration of AIO:: How to optimize the AIO implementation. |
| |
| |
| File: libc.info, Node: Asynchronous Reads/Writes, Next: Status of AIO Operations, Up: Asynchronous I/O |
| |
| 13.10.1 Asynchronous Read and Write Operations |
| ---------------------------------------------- |
| |
| -- Function: int aio_read (struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function initiates an asynchronous read operation. It |
| immediately returns after the operation was enqueued or when an |
| error was encountered. |
| |
| The first 'aiocbp->aio_nbytes' bytes of the file for which |
| 'aiocbp->aio_fildes' is a descriptor are written to the buffer |
| starting at 'aiocbp->aio_buf'. Reading starts at the absolute |
| position 'aiocbp->aio_offset' in the file. |
| |
| If prioritized I/O is supported by the platform the |
| 'aiocbp->aio_reqprio' value is used to adjust the priority before |
| the request is actually enqueued. |
| |
| The calling process is notified about the termination of the read |
| request according to the 'aiocbp->aio_sigevent' value. |
| |
| When 'aio_read' returns, the return value is zero if no error |
| occurred that can be found before the process is enqueued. If such |
| an early error is found, the function returns -1 and sets 'errno' |
| to one of the following values: |
| |
| 'EAGAIN' |
| The request was not enqueued due to (temporarily) exceeded |
| resource limitations. |
| 'ENOSYS' |
| The 'aio_read' function is not implemented. |
| 'EBADF' |
| The 'aiocbp->aio_fildes' descriptor is not valid. This |
| condition need not be recognized before enqueueing the request |
| and so this error might also be signaled asynchronously. |
| 'EINVAL' |
| The 'aiocbp->aio_offset' or 'aiocbp->aio_reqpiro' value is |
| invalid. This condition need not be recognized before |
| enqueueing the request and so this error might also be |
| signaled asynchronously. |
| |
| If 'aio_read' returns zero, the current status of the request can |
| be queried using 'aio_error' and 'aio_return' functions. As long |
| as the value returned by 'aio_error' is 'EINPROGRESS' the operation |
| has not yet completed. If 'aio_error' returns zero, the operation |
| successfully terminated, otherwise the value is to be interpreted |
| as an error code. If the function terminated, the result of the |
| operation can be obtained using a call to 'aio_return'. The |
| returned value is the same as an equivalent call to 'read' would |
| have returned. Possible error codes returned by 'aio_error' are: |
| |
| 'EBADF' |
| The 'aiocbp->aio_fildes' descriptor is not valid. |
| 'ECANCELED' |
| The operation was canceled before the operation was finished |
| (*note Cancel AIO Operations::) |
| 'EINVAL' |
| The 'aiocbp->aio_offset' value is invalid. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' this |
| function is in fact 'aio_read64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_read64 (struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function is similar to the 'aio_read' function. The only |
| difference is that on 32 bit machines, the file descriptor should |
| be opened in the large file mode. Internally, 'aio_read64' uses |
| functionality equivalent to 'lseek64' (*note File Position |
| Primitive::) to position the file descriptor correctly for the |
| reading, as opposed to '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 '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 get 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 '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 send. 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 return |
| -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 'lseek' functionality used in |
| 'lio_listio'. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64', this |
| function is available under the name 'lio_listio' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| |
| File: libc.info, Node: Status of AIO Operations, Next: Synchronizing AIO Operations, Prev: Asynchronous Reads/Writes, Up: Asynchronous I/O |
| |
| 13.10.2 Getting the Status of AIO Operations |
| -------------------------------------------- |
| |
| As already described in the documentation of the functions in the last |
| section, it must be possible to get information about the status of an |
| I/O request. When the operation is performed truly asynchronously (as |
| with 'aio_read' and 'aio_write' and with 'lio_listio' when the mode is |
| 'LIO_NOWAIT'), one sometimes needs to know whether a specific request |
| already terminated and if so, what the result was. The following two |
| functions allow you to get this kind of information. |
| |
| -- Function: int aio_error (const struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function determines the error state of the request described |
| by the 'struct aiocb' variable pointed to by AIOCBP. If the |
| request has not yet terminated the value returned is always |
| 'EINPROGRESS'. Once the request has terminated the value |
| 'aio_error' returns is either 0 if the request completed |
| successfully or it returns the value which would be stored in the |
| 'errno' variable if the request would have been done using 'read', |
| 'write', or 'fsync'. |
| |
| The function can return 'ENOSYS' if it is not implemented. It |
| could also return 'EINVAL' if the AIOCBP parameter does not refer |
| to an asynchronous operation whose return status is not yet known. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' this |
| function is in fact 'aio_error64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_error64 (const struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to 'aio_error' with the only difference |
| that the argument is a reference to a variable of type 'struct |
| aiocb64'. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' this |
| function is available under the name 'aio_error' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| -- Function: ssize_t aio_return (struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function can be used to retrieve the return status of the |
| operation carried out by the request described in the variable |
| pointed to by AIOCBP. As long as the error status of this request |
| as returned by 'aio_error' is 'EINPROGRESS' the return of this |
| function is undefined. |
| |
| Once the request is finished this function can be used exactly once |
| to retrieve the return value. Following calls might lead to |
| undefined behavior. The return value itself is the value which |
| would have been returned by the 'read', 'write', or 'fsync' call. |
| |
| The function can return 'ENOSYS' if it is not implemented. It |
| could also return 'EINVAL' if the AIOCBP parameter does not refer |
| to an asynchronous operation whose return status is not yet known. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' this |
| function is in fact 'aio_return64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: ssize_t aio_return64 (struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to 'aio_return' with the only difference |
| that the argument is a reference to a variable of type 'struct |
| aiocb64'. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' this |
| function is available under the name 'aio_return' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| |
| File: libc.info, Node: Synchronizing AIO Operations, Next: Cancel AIO Operations, Prev: Status of AIO Operations, Up: Asynchronous I/O |
| |
| 13.10.3 Getting into a Consistent State |
| --------------------------------------- |
| |
| When dealing with asynchronous operations it is sometimes necessary to |
| get into a consistent state. This would mean for AIO that one wants to |
| know whether a certain request or a group of request 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 operating 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 for 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_*' function notify |
| the caller might also be not the best solution since whenever the |
| process works on preparing data for on client it makes no sense to be |
| interrupted by a notification since the new client will not be handled |
| before the current client is served. For situations like this |
| 'aio_suspend' should be used. |
| |
| -- Function: int aio_suspend (const struct aiocb *const LIST[], int |
| NENT, const struct timespec *TIMEOUT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| When calling this function, the calling thread is suspended until |
| at least one of the requests pointed to by the NENT elements of the |
| array LIST has completed. If any of the requests has already |
| completed at the time 'aio_suspend' is called, the function returns |
| immediately. Whether a request has terminated or not is determined |
| by comparing the error status of the request with 'EINPROGRESS'. |
| If an element of LIST is 'NULL', the entry is simply ignored. |
| |
| If no request has finished, the calling process is suspended. If |
| TIMEOUT is 'NULL', the process is not woken until a request has |
| finished. If TIMEOUT is not 'NULL', the process remains suspended |
| at least as long as specified in TIMEOUT. In this case, |
| 'aio_suspend' returns with an error. |
| |
| The return value of the function is 0 if one or more requests from |
| the LIST have terminated. Otherwise the function returns -1 and |
| 'errno' is set to one of the following values: |
| |
| 'EAGAIN' |
| None of the requests from the LIST completed in the time |
| specified by TIMEOUT. |
| 'EINTR' |
| A signal interrupted the 'aio_suspend' function. This signal |
| might also be sent by the AIO implementation while signalling |
| the termination of one of the requests. |
| 'ENOSYS' |
| The 'aio_suspend' function is not implemented. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' this |
| function is in fact 'aio_suspend64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_suspend64 (const struct aiocb64 *const LIST[], int |
| NENT, const struct timespec *TIMEOUT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function is similar to 'aio_suspend' with the only difference |
| that the argument is a reference to a variable of type 'struct |
| aiocb64'. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' this |
| function is available under the name 'aio_suspend' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| |
| File: libc.info, Node: Cancel AIO Operations, Next: Configuration of AIO, Prev: Synchronizing AIO Operations, Up: Asynchronous I/O |
| |
| 13.10.4 Cancellation of AIO Operations |
| -------------------------------------- |
| |
| When one or more requests are asynchronously processed, it might be |
| useful in some situations to cancel a selected operation, e.g., if it |
| becomes obvious that the written data is no longer accurate and would |
| have to be overwritten soon. As an example, assume an application, |
| which writes data in files in a situation where new incoming data would |
| have to be written in a file which will be updated by an enqueued |
| request. The POSIX AIO implementation provides such a function, but |
| this function is not capable of forcing the cancellation of the request. |
| It is up to the implementation to decide whether it is possible to |
| cancel the operation or not. Therefore using this function is merely a |
| hint. |
| |
| -- Function: int aio_cancel (int FILDES, struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem | |
| *Note POSIX Safety Concepts::. |
| |
| The 'aio_cancel' function can be used to cancel one or more |
| outstanding requests. If the AIOCBP parameter is 'NULL', the |
| function tries to cancel all of the outstanding requests which |
| would process the file descriptor FILDES (i.e., whose 'aio_fildes' |
| member is FILDES). If AIOCBP is not 'NULL', 'aio_cancel' attempts |
| to cancel the specific request pointed to by AIOCBP. |
| |
| For requests which were successfully canceled, the normal |
| notification about the termination of the request should take |
| place. I.e., depending on the 'struct sigevent' object which |
| controls this, nothing happens, a signal is sent or a thread is |
| started. If the request cannot be canceled, it terminates the |
| usual way after performing the operation. |
| |
| After a request is successfully canceled, a call to 'aio_error' |
| with a reference to this request as the parameter will return |
| 'ECANCELED' and a call to 'aio_return' will return -1. If the |
| request wasn't canceled and is still running the error status is |
| still 'EINPROGRESS'. |
| |
| The return value of the function is 'AIO_CANCELED' if there were |
| requests which haven't terminated and which were successfully |
| canceled. If there is one or more requests left which couldn't be |
| canceled, the return value is 'AIO_NOTCANCELED'. In this case |
| 'aio_error' must be used to find out which of the, perhaps |
| multiple, requests (in AIOCBP is 'NULL') weren't successfully |
| canceled. If all requests already terminated at the time |
| 'aio_cancel' is called the return value is 'AIO_ALLDONE'. |
| |
| If an error occurred during the execution of 'aio_cancel' the |
| function returns -1 and sets 'errno' to one of the following |
| values. |
| |
| 'EBADF' |
| The file descriptor FILDES is not valid. |
| 'ENOSYS' |
| 'aio_cancel' is not implemented. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64', this |
| function is in fact 'aio_cancel64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_cancel64 (int FILDES, struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function is similar to 'aio_cancel' with the only difference |
| that the argument is a reference to a variable of type 'struct |
| aiocb64'. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64', this |
| function is available under the name 'aio_cancel' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| |
| File: libc.info, Node: Configuration of AIO, Prev: Cancel AIO Operations, Up: Asynchronous I/O |
| |
| 13.10.5 How to optimize the AIO implementation |
| ---------------------------------------------- |
| |
| The POSIX standard does not specify how the AIO functions are |
| implemented. They could be system calls, but it is also possible to |
| emulate them at userlevel. |
| |
| At the point of this writing, the available implementation is a |
| userlevel implementation which uses threads for handling the enqueued |
| requests. While this implementation requires making some decisions |
| about limitations, hard limitations are something which is 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 the 'aio_init', function 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 a extension which follows a proposal from the SGI |
| implementation in Irix 6. It is not covered by POSIX.1b or Unix98. |
| |
| |
| File: libc.info, Node: Control Operations, Next: Duplicating Descriptors, Prev: Asynchronous I/O, Up: Low-Level I/O |
| |
| 13.11 Control Operations on Files |
| ================================= |
| |
| This section describes how you can perform various other operations on |
| file descriptors, such as inquiring about or setting flags describing |
| the status of the file descriptor, manipulating record locks, and the |
| like. All of these operations are performed by the function 'fcntl'. |
| |
| The second argument to the 'fcntl' function is a command that |
| specifies which operation to perform. The function and macros that name |
| various flags that are used with it are declared in the header file |
| 'fcntl.h'. Many of these flags are also used by the 'open' function; |
| see *note Opening and Closing Files::. |
| |
| -- Function: int fcntl (int FILEDES, int COMMAND, ...) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'fcntl' function performs the operation specified by COMMAND on |
| the file descriptor FILEDES. Some commands require additional |
| arguments to be supplied. These additional arguments and the |
| return value and error conditions are given in the detailed |
| descriptions of the individual commands. |
| |
| Briefly, here is a list of what the various commands are. |
| |
| 'F_DUPFD' |
| Duplicate the file descriptor (return another file descriptor |
| pointing to the same open file). *Note Duplicating |
| Descriptors::. |
| |
| 'F_GETFD' |
| Get flags associated with the file descriptor. *Note |
| Descriptor Flags::. |
| |
| 'F_SETFD' |
| Set flags associated with the file descriptor. *Note |
| Descriptor Flags::. |
| |
| 'F_GETFL' |
| Get flags associated with the open file. *Note File Status |
| Flags::. |
| |
| 'F_SETFL' |
| Set flags associated with the open file. *Note File Status |
| Flags::. |
| |
| 'F_GETLK' |
| Get 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_GETOWN' |
| Get process or process group ID to receive 'SIGIO' signals. |
| *Note Interrupt Input::. |
| |
| 'F_SETOWN' |
| Set process or process group ID to receive 'SIGIO' signals. |
| *Note Interrupt Input::. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'fcntl' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this calls to |
| 'fcntl' should be protected using cancellation handlers. |
| |
| |
| File: libc.info, Node: Duplicating Descriptors, Next: Descriptor Flags, Prev: Control Operations, Up: Low-Level I/O |
| |
| 13.12 Duplicating Descriptors |
| ============================= |
| |
| You can "duplicate" a file descriptor, or allocate another file |
| descriptor that refers to the same open file as the original. Duplicate |
| descriptors share one file position and one set of file status flags |
| (*note File Status Flags::), but each has its own set of file descriptor |
| flags (*note Descriptor Flags::). |
| |
| The major use of duplicating a file descriptor is to implement |
| "redirection" of input or output: that is, to change the file or pipe |
| that a particular file descriptor corresponds to. |
| |
| You can perform this operation using the 'fcntl' function with the |
| 'F_DUPFD' command, but there are also convenient functions 'dup' and |
| 'dup2' for duplicating descriptors. |
| |
| The 'fcntl' function and flags are declared in 'fcntl.h', while |
| prototypes for 'dup' and 'dup2' are in the header file 'unistd.h'. |
| |
| -- Function: int dup (int OLD) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function copies descriptor OLD to the first available |
| descriptor number (the first number not currently open). It is |
| equivalent to 'fcntl (OLD, F_DUPFD, 0)'. |
| |
| -- Function: int dup2 (int OLD, int NEW) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function copies the descriptor OLD to descriptor number NEW. |
| |
| If OLD is an invalid descriptor, then 'dup2' does nothing; it does |
| not close NEW. Otherwise, the new duplicate of OLD replaces any |
| previous meaning of descriptor NEW, as if NEW were closed first. |
| |
| If OLD and NEW are different numbers, and OLD is a valid descriptor |
| number, then 'dup2' is equivalent to: |
| |
| close (NEW); |
| fcntl (OLD, F_DUPFD, NEW) |
| |
| However, 'dup2' does this atomically; there is no instant in the |
| middle of calling 'dup2' at which NEW is closed and not yet a |
| duplicate of OLD. |
| |
| -- Macro: int F_DUPFD |
| This macro is used as the COMMAND argument to 'fcntl', to copy the |
| file descriptor given as the first argument. |
| |
| The form of the call in this case is: |
| |
| fcntl (OLD, F_DUPFD, NEXT-FILEDES) |
| |
| The NEXT-FILEDES argument is of type 'int' and specifies that the |
| file descriptor returned should be the next available one greater |
| than or equal to this value. |
| |
| The return value from 'fcntl' with this command is normally the |
| value of the new file descriptor. A return value of -1 indicates |
| an error. The following 'errno' error conditions are defined for |
| this command: |
| |
| 'EBADF' |
| The OLD argument is invalid. |
| |
| 'EINVAL' |
| The NEXT-FILEDES argument is invalid. |
| |
| 'EMFILE' |
| There are no more file descriptors available--your program is |
| already using the maximum. In BSD and GNU, the maximum is |
| controlled by a resource limit that can be changed; *note |
| Limits on Resources::, for more information about the |
| 'RLIMIT_NOFILE' limit. |
| |
| 'ENFILE' is not a possible error code for 'dup2' because 'dup2' |
| does not create a new opening of a file; duplicate descriptors do |
| not count toward the limit which 'ENFILE' indicates. 'EMFILE' is |
| possible because it refers to the limit on distinct descriptor |
| numbers in use in one process. |
| |
| Here is an example showing how to use 'dup2' to do redirection. |
| Typically, redirection of the standard streams (like 'stdin') is done by |
| a shell or shell-like program before calling one of the 'exec' functions |
| (*note Executing a File::) to execute a new program in a child process. |
| When the new program is executed, it creates and initializes the |
| standard streams to point to the corresponding file descriptors, before |
| its 'main' function is invoked. |
| |
| So, to redirect standard input to a file, the shell could do |
| something like: |
| |
| pid = fork (); |
| if (pid == 0) |
| { |
| char *filename; |
| char *program; |
| int file; |
| ... |
| file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY)); |
| dup2 (file, STDIN_FILENO); |
| TEMP_FAILURE_RETRY (close (file)); |
| execv (program, NULL); |
| } |
| |
| There is also a more detailed example showing how to implement |
| redirection in the context of a pipeline of processes in *note Launching |
| Jobs::. |
| |
| |
| File: libc.info, Node: Descriptor Flags, Next: File Status Flags, Prev: Duplicating Descriptors, Up: Low-Level I/O |
| |
| 13.13 File Descriptor Flags |
| =========================== |
| |
| "File descriptor flags" are miscellaneous attributes of a file |
| descriptor. These flags are associated with particular file |
| descriptors, so that if you have created duplicate file descriptors from |
| a single opening of a file, each descriptor has its own set of flags. |
| |
| Currently there is just one file descriptor flag: 'FD_CLOEXEC', which |
| causes the descriptor to be closed if you use any of the 'exec...' |
| functions (*note Executing a File::). |
| |
| The symbols in this section are defined in the header file 'fcntl.h'. |
| |
| -- Macro: int F_GETFD |
| This macro is used as the COMMAND argument to 'fcntl', to specify |
| that it should return the file descriptor flags associated with the |
| FILEDES argument. |
| |
| The normal return value from 'fcntl' with this command is a |
| nonnegative number which can be interpreted as the bitwise OR of |
| the individual flags (except that currently there is only one flag |
| to use). |
| |
| In case of an error, 'fcntl' returns -1. The following 'errno' |
| error conditions are defined for this command: |
| |
| 'EBADF' |
| The FILEDES argument is invalid. |
| |
| -- Macro: int F_SETFD |
| This macro is used as the COMMAND argument to 'fcntl', to specify |
| that it should set the file descriptor flags associated with the |
| FILEDES argument. This requires a third 'int' argument to specify |
| the new flags, so the form of the call is: |
| |
| fcntl (FILEDES, F_SETFD, NEW-FLAGS) |
| |
| The normal return value from 'fcntl' with this command is an |
| unspecified value other than -1, which indicates an error. The |
| flags and error conditions are the same as for the 'F_GETFD' |
| command. |
| |
| The following macro is defined for use as a file descriptor flag with |
| the 'fcntl' function. The value is an integer constant usable as a bit |
| mask value. |
| |
| -- Macro: int FD_CLOEXEC |
| This flag specifies that the file descriptor should be closed when |
| an 'exec' function is invoked; see *note Executing a File::. When |
| a file descriptor is allocated (as with 'open' or 'dup'), this bit |
| is initially cleared on the new file descriptor, meaning that |
| descriptor will survive into the new program after 'exec'. |
| |
| If you want to modify the file descriptor flags, you should get the |
| current flags with 'F_GETFD' and modify the value. Don't assume that |
| the flags listed here are the only ones that are implemented; your |
| program may be run years from now and more flags may exist then. For |
| example, here is a function to set or clear the flag 'FD_CLOEXEC' |
| without altering any other flags: |
| |
| /* Set the 'FD_CLOEXEC' flag of DESC if VALUE is nonzero, |
| or clear the flag if VALUE is 0. |
| Return 0 on success, or -1 on error with 'errno' set. */ |
| |
| int |
| set_cloexec_flag (int desc, int value) |
| { |
| int oldflags = fcntl (desc, F_GETFD, 0); |
| /* If reading the flags failed, return error indication now. */ |
| if (oldflags < 0) |
| return oldflags; |
| /* Set just the flag we want to set. */ |
| if (value != 0) |
| oldflags |= FD_CLOEXEC; |
| else |
| oldflags &= ~FD_CLOEXEC; |
| /* Store modified flag word in the descriptor. */ |
| return fcntl (desc, F_SETFD, oldflags); |
| } |
| |
| |
| File: libc.info, Node: File Status Flags, Next: File Locks, Prev: Descriptor Flags, Up: Low-Level I/O |
| |
| 13.14 File Status Flags |
| ======================= |
| |
| "File status flags" are used to specify attributes of the opening of a |
| file. Unlike the file descriptor flags discussed in *note Descriptor |
| Flags::, the file status flags are shared by duplicated file descriptors |
| resulting from a single opening of the file. The file status flags are |
| specified with the FLAGS argument to 'open'; *note Opening and Closing |
| Files::. |
| |
| File status flags fall into three categories, which are described in |
| the following sections. |
| |
| * *note Access Modes::, specify what type of access is allowed to the |
| file: reading, writing, or both. They are set by 'open' and are |
| returned by 'fcntl', but cannot be changed. |
| |
| * *note Open-time Flags::, control details of what 'open' will do. |
| These flags are not preserved after the 'open' call. |
| |
| * *note Operating Modes::, affect how operations such as 'read' and |
| 'write' are done. They are set by 'open', and can be fetched or |
| changed with 'fcntl'. |
| |
| The symbols in this section are defined in the header file 'fcntl.h'. |
| |
| * Menu: |
| |
| * Access Modes:: Whether the descriptor can read or write. |
| * Open-time Flags:: Details of 'open'. |
| * Operating Modes:: Special modes to control I/O operations. |
| * Getting File Status Flags:: Fetching and changing these flags. |
| |
| |
| File: libc.info, Node: Access Modes, Next: Open-time Flags, Up: File Status Flags |
| |
| 13.14.1 File Access Modes |
| ------------------------- |
| |
| The file access modes allow a file descriptor to be used for reading, |
| writing, or both. (On GNU/Hurd systems, they can also allow none of |
| these, and allow execution of the file as a program.) The access modes |
| are chosen when the file is opened, and never change. |
| |
| -- Macro: int O_RDONLY |
| Open the file for read access. |
| |
| -- Macro: int O_WRONLY |
| Open the file for write access. |
| |
| -- Macro: int O_RDWR |
| Open the file for both reading and writing. |
| |
| On GNU/Hurd systems (and not on other systems), 'O_RDONLY' and |
| 'O_WRONLY' are independent bits that can be bitwise-ORed together, and |
| it is valid for either bit to be set or clear. This means that 'O_RDWR' |
| is the same as 'O_RDONLY|O_WRONLY'. A file access mode of zero is |
| permissible; it allows no operations that do input or output to the |
| file, but does allow other operations such as 'fchmod'. On GNU/Hurd |
| systems, since "read-only" or "write-only" is a misnomer, 'fcntl.h' |
| defines additional names for the file access modes. These names are |
| preferred when writing GNU-specific code. But most programs will want |
| to be portable to other POSIX.1 systems and should use the POSIX.1 names |
| above instead. |
| |
| -- Macro: int O_READ |
| Open the file for reading. Same as 'O_RDONLY'; only defined on |
| GNU. |
| |
| -- Macro: int O_WRITE |
| Open the file for writing. Same as 'O_WRONLY'; only defined on |
| GNU. |
| |
| -- Macro: int O_EXEC |
| Open the file for executing. Only defined on GNU. |
| |
| To determine the file access mode with 'fcntl', you must extract the |
| access mode bits from the retrieved file status flags. On GNU/Hurd |
| systems, you can just test the 'O_READ' and 'O_WRITE' bits in the flags |
| word. But in other POSIX.1 systems, reading and writing access modes |
| are not stored as distinct bit flags. The portable way to extract the |
| file access mode bits is with 'O_ACCMODE'. |
| |
| -- Macro: int O_ACCMODE |
| This macro stands for a mask that can be bitwise-ANDed with the |
| file status flag value to produce a value representing the file |
| access mode. The mode will be 'O_RDONLY', 'O_WRONLY', or 'O_RDWR'. |
| (On GNU/Hurd systems it could also be zero, and it never includes |
| the 'O_EXEC' bit.) |
| |
| |
| File: libc.info, Node: Open-time Flags, Next: Operating Modes, Prev: Access Modes, Up: File Status Flags |
| |
| 13.14.2 Open-time Flags |
| ----------------------- |
| |
| The open-time flags specify options affecting how 'open' will behave. |
| These options are not preserved once the file is open. The exception to |
| this is 'O_NONBLOCK', which is also an I/O operating mode and so it _is_ |
| saved. *Note Opening and Closing Files::, for how to call 'open'. |
| |
| There are two sorts of options specified by open-time flags. |
| |
| * "File name translation flags" affect how 'open' looks up the file |
| name to locate the file, and whether the file can be created. |
| |
| * "Open-time action flags" specify extra operations that 'open' will |
| perform on the file once it is open. |
| |
| Here are the file name translation flags. |
| |
| -- Macro: int O_CREAT |
| If set, the file will be created if it doesn't already exist. |
| |
| -- Macro: int O_EXCL |
| If both 'O_CREAT' and 'O_EXCL' are set, then 'open' fails if the |
| specified file already exists. This is guaranteed to never clobber |
| an existing file. |
| |
| -- Macro: int O_NONBLOCK |
| This prevents 'open' from blocking for a "long time" to open the |
| file. This is only meaningful for some kinds of files, usually |
| devices such as serial ports; when it is not meaningful, it is |
| harmless and ignored. Often opening a port to a modem blocks until |
| the modem reports carrier detection; if 'O_NONBLOCK' is specified, |
| 'open' will return immediately without a carrier. |
| |
| Note that the 'O_NONBLOCK' flag is overloaded as both an I/O |
| operating mode and a file name translation flag. This means that |
| specifying 'O_NONBLOCK' in 'open' also sets nonblocking I/O mode; |
| *note Operating Modes::. To open the file without blocking but do |
| normal I/O that blocks, you must call 'open' with 'O_NONBLOCK' set |
| and then call 'fcntl' to turn the bit off. |
| |
| -- Macro: int O_NOCTTY |
| If the named file is a terminal device, don't make it the |
| controlling terminal for the process. *Note Job Control::, for |
| information about what it means to be the controlling terminal. |
| |
| On GNU/Hurd systems and 4.4 BSD, opening a file never makes it the |
| controlling terminal and 'O_NOCTTY' is zero. However, GNU/Linux |
| systems and some other systems use a nonzero value for 'O_NOCTTY' |
| and set the controlling terminal when you open a file that is a |
| terminal device; so to be portable, use 'O_NOCTTY' when it is |
| important to avoid this. |
| |
| The following three file name translation flags exist only on |
| GNU/Hurd systems. |
| |
| -- Macro: int O_IGNORE_CTTY |
| Do not recognize the named file as the controlling terminal, even |
| if it refers to the process's existing controlling terminal device. |
| Operations on the new file descriptor will never induce job control |
| signals. *Note Job Control::. |
| |
| -- Macro: int O_NOLINK |
| If the named file is a symbolic link, open the link itself instead |
| of the file it refers to. ('fstat' on the new file descriptor will |
| return the information returned by 'lstat' on the link's name.) |
| |
| -- Macro: int O_NOTRANS |
| If the named file is specially translated, do not invoke the |
| translator. Open the bare file the translator itself sees. |
| |
| The open-time action flags tell 'open' to do additional operations |
| which are not really related to opening the file. The reason to do them |
| as part of 'open' instead of in separate calls is that 'open' can do |
| them atomically. |
| |
| -- Macro: int O_TRUNC |
| Truncate the file to zero length. This option is only useful for |
| regular files, not special files such as directories or FIFOs. |
| POSIX.1 requires that you open the file for writing to use |
| 'O_TRUNC'. In BSD and GNU you must have permission to write the |
| file to truncate it, but you need not open for write access. |
| |
| This is the only open-time action flag specified by POSIX.1. There |
| is no good reason for truncation to be done by 'open', instead of |
| by calling 'ftruncate' afterwards. The 'O_TRUNC' flag existed in |
| Unix before 'ftruncate' was invented, and is retained for backward |
| compatibility. |
| |
| The remaining operating modes are BSD extensions. They exist only on |
| some systems. On other systems, these macros are not defined. |
| |
| -- Macro: int O_SHLOCK |
| Acquire a shared lock on the file, as with 'flock'. *Note File |
| Locks::. |
| |
| If 'O_CREAT' is specified, the locking is done atomically when |
| creating the file. You are guaranteed that no other process will |
| get the lock on the new file first. |
| |
| -- Macro: int O_EXLOCK |
| Acquire an exclusive lock on the file, as with 'flock'. *Note File |
| Locks::. This is atomic like 'O_SHLOCK'. |
| |
| |
| File: libc.info, Node: Operating Modes, Next: Getting File Status Flags, Prev: Open-time Flags, Up: File Status Flags |
| |
| 13.14.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.14.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: Interrupt Input, Prev: File Status Flags, Up: Low-Level I/O |
| |
| 13.15 File 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 '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. |
| |
| -- 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 waiting for other processes to |
| release locks. If 'fcntl' succeeds, it return 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 a _voluntary_ 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: Interrupt Input, Next: IOCTLs, Prev: File Locks, Up: Low-Level I/O |
| |
| 13.16 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.17 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::. |
| |
| This 'get_current_dir_name' function is basically equivalent to |
| 'getcwd (NULL, 0)'. The only difference is that the value of the |
| 'PWD' variable is returned if this value is correct. This is a |
| subtle difference which is visible if the path described by the |
| 'PWD' value is using one or more symbol links in which case the |
| value returned by 'getcwd' can resolve the symbol 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. |
| |
| |
| 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 determine 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 names '_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. |
| |
| -- 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-Unsafe race:dirstream | 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. |
| |
| In POSIX.1-2008, 'readdir' is not thread-safe. In the GNU C |
| Library implementation, it is safe to call 'readdir' concurrently |
| on different DIRSTREAMs, but multiple threads accessing the same |
| DIRSTREAM result in undefined behavior. 'readdir_r' is a fully |
| thread-safe alternative, but suffers from poor portability (see |
| below). It is recommended that you use 'readdir', with external |
| locking if multiple threads access the same DIRSTREAM. |
| |
| -- 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:* 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-Unsafe race:dirstream | 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 '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 |
| structure 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 void *A, const void *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 void *A, const void *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 void *A, const void *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 void *A, const void *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, 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: 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 paramater 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 |
| '_BSD_SOURCE' or '_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 was 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. |
| |