| This is |
| /tmp/dgboter/bbs/rhev-vm2--rhe6x86_64/buildbot/rhe6x86_64--aarch64-none-linux-gnu/build/build-aarch64-none-linux-gnu/obj/glibc/manual/libc.info, |
| produced by makeinfo version 4.13 from libc.texinfo. |
| |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHAR_BIT: (libc)Width of Type. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * 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. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * FP_LLOGB0: (libc)Exponents and Logarithms. |
| * FP_LLOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OFD_GETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLKW: (libc)Open File Description Locks. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUGE_VAL_FN: (libc)Math Error Reporting. |
| * HUGE_VAL_FNx: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_DIRECTORY: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_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_TMPFILE: (libc)Open-time Flags. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SNAN: (libc)Infinity and NaN. |
| * SNANF: (libc)Infinity and NaN. |
| * SNANFN: (libc)Infinity and NaN. |
| * SNANFNx: (libc)Infinity and NaN. |
| * SNANL: (libc)Infinity and NaN. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_high: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_set_ppr_very_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __riscv_flush_icache: (libc)RISC-V. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosfN: (libc)Inverse Trig Functions. |
| * acosfNx: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshfN: (libc)Hyperbolic Functions. |
| * acoshfNx: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)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. |
| * asinfN: (libc)Inverse Trig Functions. |
| * asinfNx: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhfN: (libc)Hyperbolic Functions. |
| * asinhfNx: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2fN: (libc)Inverse Trig Functions. |
| * atan2fNx: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanfN: (libc)Inverse Trig Functions. |
| * atanfNx: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhfN: (libc)Hyperbolic Functions. |
| * atanhfNx: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying Strings and Arrays. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying Strings and Arrays. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsfN: (libc)Absolute Value. |
| * cabsfNx: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosfN: (libc)Inverse Trig Functions. |
| * cacosfNx: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshfN: (libc)Hyperbolic Functions. |
| * cacoshfNx: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * call_once: (libc)Call Once. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize: (libc)FP Bit Twiddling. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * canonicalizef: (libc)FP Bit Twiddling. |
| * canonicalizefN: (libc)FP Bit Twiddling. |
| * canonicalizefNx: (libc)FP Bit Twiddling. |
| * canonicalizel: (libc)FP Bit Twiddling. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargfN: (libc)Operations on Complex. |
| * cargfNx: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinfN: (libc)Inverse Trig Functions. |
| * casinfNx: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhfN: (libc)Hyperbolic Functions. |
| * casinhfNx: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanfN: (libc)Inverse Trig Functions. |
| * catanfNx: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhfN: (libc)Hyperbolic Functions. |
| * catanhfNx: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtfN: (libc)Exponents and Logarithms. |
| * cbrtfNx: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosfN: (libc)Trig Functions. |
| * ccosfNx: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshfN: (libc)Hyperbolic Functions. |
| * ccoshfNx: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceilfN: (libc)Rounding Functions. |
| * ceilfNx: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpfN: (libc)Exponents and Logarithms. |
| * cexpfNx: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagfN: (libc)Operations on Complex. |
| * cimagfNx: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10fN: (libc)Exponents and Logarithms. |
| * clog10fNx: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogfN: (libc)Exponents and Logarithms. |
| * clogfNx: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * cnd_broadcast: (libc)ISO C Condition Variables. |
| * cnd_destroy: (libc)ISO C Condition Variables. |
| * cnd_init: (libc)ISO C Condition Variables. |
| * cnd_signal: (libc)ISO C Condition Variables. |
| * cnd_timedwait: (libc)ISO C Condition Variables. |
| * cnd_wait: (libc)ISO C Condition Variables. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjfN: (libc)Operations on Complex. |
| * conjfNx: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copy_file_range: (libc)Copying File Data. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignfN: (libc)FP Bit Twiddling. |
| * copysignfNx: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosfN: (libc)Trig Functions. |
| * cosfNx: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshfN: (libc)Hyperbolic Functions. |
| * coshfNx: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowfN: (libc)Exponents and Logarithms. |
| * cpowfNx: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojfN: (libc)Operations on Complex. |
| * cprojfNx: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * crealfN: (libc)Operations on Complex. |
| * crealfNx: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)Passphrase Storage. |
| * crypt_r: (libc)Passphrase Storage. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinfN: (libc)Trig Functions. |
| * csinfNx: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhfN: (libc)Hyperbolic Functions. |
| * csinhfNx: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtfN: (libc)Exponents and Logarithms. |
| * csqrtfNx: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanfN: (libc)Trig Functions. |
| * ctanfNx: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhfN: (libc)Hyperbolic Functions. |
| * ctanhfNx: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * daddl: (libc)Misc FP Arithmetic. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * ddivl: (libc)Misc FP Arithmetic. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dmull: (libc)Misc FP Arithmetic. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dsubl: (libc)Misc FP Arithmetic. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_remove: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcfN: (libc)Special Functions. |
| * erfcfNx: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erffN: (libc)Special Functions. |
| * erffNx: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10fN: (libc)Exponents and Logarithms. |
| * exp10fNx: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2fN: (libc)Exponents and Logarithms. |
| * exp2fNx: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expfN: (libc)Exponents and Logarithms. |
| * expfNx: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * explicit_bzero: (libc)Erasing Sensitive Data. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1fN: (libc)Exponents and Logarithms. |
| * expm1fNx: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fMaddfN: (libc)Misc FP Arithmetic. |
| * fMaddfNx: (libc)Misc FP Arithmetic. |
| * fMdivfN: (libc)Misc FP Arithmetic. |
| * fMdivfNx: (libc)Misc FP Arithmetic. |
| * fMmulfN: (libc)Misc FP Arithmetic. |
| * fMmulfNx: (libc)Misc FP Arithmetic. |
| * fMsubfN: (libc)Misc FP Arithmetic. |
| * fMsubfNx: (libc)Misc FP Arithmetic. |
| * fMxaddfN: (libc)Misc FP Arithmetic. |
| * fMxaddfNx: (libc)Misc FP Arithmetic. |
| * fMxdivfN: (libc)Misc FP Arithmetic. |
| * fMxdivfNx: (libc)Misc FP Arithmetic. |
| * fMxmulfN: (libc)Misc FP Arithmetic. |
| * fMxmulfNx: (libc)Misc FP Arithmetic. |
| * fMxsubfN: (libc)Misc FP Arithmetic. |
| * fMxsubfNx: (libc)Misc FP Arithmetic. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsfN: (libc)Absolute Value. |
| * fabsfNx: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fadd: (libc)Misc FP Arithmetic. |
| * faddl: (libc)Misc FP Arithmetic. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdimfN: (libc)Misc FP Arithmetic. |
| * fdimfNx: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdiv: (libc)Misc FP Arithmetic. |
| * fdivl: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetmode: (libc)Control Functions. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexcept: (libc)Status bit operations. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetmode: (libc)Control Functions. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * fetestexceptflag: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorfN: (libc)Rounding Functions. |
| * floorfNx: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmafN: (libc)Misc FP Arithmetic. |
| * fmafNx: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxfN: (libc)Misc FP Arithmetic. |
| * fmaxfNx: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmaxmag: (libc)Misc FP Arithmetic. |
| * fmaxmagf: (libc)Misc FP Arithmetic. |
| * fmaxmagfN: (libc)Misc FP Arithmetic. |
| * fmaxmagfNx: (libc)Misc FP Arithmetic. |
| * fmaxmagl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminfN: (libc)Misc FP Arithmetic. |
| * fminfNx: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fminmag: (libc)Misc FP Arithmetic. |
| * fminmagf: (libc)Misc FP Arithmetic. |
| * fminmagfN: (libc)Misc FP Arithmetic. |
| * fminmagfNx: (libc)Misc FP Arithmetic. |
| * fminmagl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodfN: (libc)Remainder Functions. |
| * fmodfNx: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fmul: (libc)Misc FP Arithmetic. |
| * fmull: (libc)Misc FP Arithmetic. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpfN: (libc)Normalization Functions. |
| * frexpfNx: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fromfp: (libc)Rounding Functions. |
| * fromfpf: (libc)Rounding Functions. |
| * fromfpfN: (libc)Rounding Functions. |
| * fromfpfNx: (libc)Rounding Functions. |
| * fromfpl: (libc)Rounding Functions. |
| * fromfpx: (libc)Rounding Functions. |
| * fromfpxf: (libc)Rounding Functions. |
| * fromfpxfN: (libc)Rounding Functions. |
| * fromfpxfNx: (libc)Rounding Functions. |
| * fromfpxl: (libc)Rounding Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsub: (libc)Misc FP Arithmetic. |
| * fsubl: (libc)Misc FP Arithmetic. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcpu: (libc)CPU Affinity. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdents64: (libc)Low-level Directory Access. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getentropy: (libc)Unpredictable Bytes. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpayload: (libc)FP Bit Twiddling. |
| * getpayloadf: (libc)FP Bit Twiddling. |
| * getpayloadfN: (libc)FP Bit Twiddling. |
| * getpayloadfNx: (libc)FP Bit Twiddling. |
| * getpayloadl: (libc)FP Bit Twiddling. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrandom: (libc)Unpredictable Bytes. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettid: (libc)Process Identification. |
| * gettimeofday: (libc)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. |
| * hypotfN: (libc)Exponents and Logarithms. |
| * hypotfNx: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbfN: (libc)Exponents and Logarithms. |
| * ilogbfNx: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscanonical: (libc)Floating Point Classes. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * iseqsig: (libc)FP Comparison Functions. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * issubnormal: (libc)Floating Point Classes. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * iszero: (libc)Floating Point Classes. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0fN: (libc)Special Functions. |
| * j0fNx: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1fN: (libc)Special Functions. |
| * j1fNx: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnfN: (libc)Special Functions. |
| * jnfNx: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpfN: (libc)Normalization Functions. |
| * ldexpfNx: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammafN: (libc)Special Functions. |
| * lgammafN_r: (libc)Special Functions. |
| * lgammafNx: (libc)Special Functions. |
| * lgammafNx_r: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * linkat: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llogb: (libc)Exponents and Logarithms. |
| * llogbf: (libc)Exponents and Logarithms. |
| * llogbfN: (libc)Exponents and Logarithms. |
| * llogbfNx: (libc)Exponents and Logarithms. |
| * llogbl: (libc)Exponents and Logarithms. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintfN: (libc)Rounding Functions. |
| * llrintfNx: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundfN: (libc)Rounding Functions. |
| * llroundfNx: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10fN: (libc)Exponents and Logarithms. |
| * log10fNx: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pfN: (libc)Exponents and Logarithms. |
| * log1pfNx: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2fN: (libc)Exponents and Logarithms. |
| * log2fNx: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbfN: (libc)Exponents and Logarithms. |
| * logbfNx: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * logfN: (libc)Exponents and Logarithms. |
| * logfNx: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintfN: (libc)Rounding Functions. |
| * lrintfNx: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundfN: (libc)Rounding Functions. |
| * lroundfNx: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying Strings and Arrays. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying Strings and Arrays. |
| * memfd_create: (libc)Memory-mapped I/O. |
| * memfrob: (libc)Obfuscating Data. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying Strings and Arrays. |
| * mempcpy: (libc)Copying Strings and Arrays. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying Strings and Arrays. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock2: (libc)Page Lock Functions. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modffN: (libc)Rounding Functions. |
| * modffNx: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mprotect: (libc)Memory Protection. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * mtx_destroy: (libc)ISO C Mutexes. |
| * mtx_init: (libc)ISO C Mutexes. |
| * mtx_lock: (libc)ISO C Mutexes. |
| * mtx_timedlock: (libc)ISO C Mutexes. |
| * mtx_trylock: (libc)ISO C Mutexes. |
| * mtx_unlock: (libc)ISO C Mutexes. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanfN: (libc)FP Bit Twiddling. |
| * nanfNx: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintfN: (libc)Rounding Functions. |
| * nearbyintfNx: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterfN: (libc)FP Bit Twiddling. |
| * nextafterfNx: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nextdown: (libc)FP Bit Twiddling. |
| * nextdownf: (libc)FP Bit Twiddling. |
| * nextdownfN: (libc)FP Bit Twiddling. |
| * nextdownfNx: (libc)FP Bit Twiddling. |
| * nextdownl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nextup: (libc)FP Bit Twiddling. |
| * nextupf: (libc)FP Bit Twiddling. |
| * nextupfN: (libc)FP Bit Twiddling. |
| * nextupfNx: (libc)FP Bit Twiddling. |
| * nextupl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)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. |
| * pkey_alloc: (libc)Memory Protection. |
| * pkey_free: (libc)Memory Protection. |
| * pkey_get: (libc)Memory Protection. |
| * pkey_mprotect: (libc)Memory Protection. |
| * pkey_set: (libc)Memory Protection. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_fallocate64: (libc)Storage Allocation. |
| * posix_fallocate: (libc)Storage Allocation. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powfN: (libc)Exponents and Logarithms. |
| * powfNx: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * preadv2: (libc)Scatter-Gather. |
| * preadv64: (libc)Scatter-Gather. |
| * preadv64v2: (libc)Scatter-Gather. |
| * preadv: (libc)Scatter-Gather. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_cond_clockwait: (libc)Default Thread Attributes. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_rwlock_clockrdlock: (libc)Default Thread Attributes. |
| * pthread_rwlock_clockwrlock: (libc)Default Thread Attributes. |
| * 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. |
| * pwritev2: (libc)Scatter-Gather. |
| * pwritev64: (libc)Scatter-Gather. |
| * pwritev64v2: (libc)Scatter-Gather. |
| * pwritev: (libc)Scatter-Gather. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * reallocarray: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderfN: (libc)Remainder Functions. |
| * remainderfNx: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintfN: (libc)Rounding Functions. |
| * rintfNx: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundeven: (libc)Rounding Functions. |
| * roundevenf: (libc)Rounding Functions. |
| * roundevenfN: (libc)Rounding Functions. |
| * roundevenfNx: (libc)Rounding Functions. |
| * roundevenl: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundfN: (libc)Rounding Functions. |
| * roundfNx: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnfN: (libc)Normalization Functions. |
| * scalblnfNx: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnfN: (libc)Normalization Functions. |
| * scalbnfNx: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * sem_clockwait: (libc)Default Thread Attributes. |
| * sem_close: (libc)Semaphores. |
| * sem_destroy: (libc)Semaphores. |
| * sem_getvalue: (libc)Semaphores. |
| * sem_init: (libc)Semaphores. |
| * sem_open: (libc)Semaphores. |
| * sem_post: (libc)Semaphores. |
| * sem_timedwait: (libc)Semaphores. |
| * sem_trywait: (libc)Semaphores. |
| * sem_unlink: (libc)Semaphores. |
| * sem_wait: (libc)Semaphores. |
| * semctl: (libc)Semaphores. |
| * semget: (libc)Semaphores. |
| * semop: (libc)Semaphores. |
| * semtimedop: (libc)Semaphores. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpayload: (libc)FP Bit Twiddling. |
| * setpayloadf: (libc)FP Bit Twiddling. |
| * setpayloadfN: (libc)FP Bit Twiddling. |
| * setpayloadfNx: (libc)FP Bit Twiddling. |
| * setpayloadl: (libc)FP Bit Twiddling. |
| * setpayloadsig: (libc)FP Bit Twiddling. |
| * setpayloadsigf: (libc)FP Bit Twiddling. |
| * setpayloadsigfN: (libc)FP Bit Twiddling. |
| * setpayloadsigfNx: (libc)FP Bit Twiddling. |
| * setpayloadsigl: (libc)FP Bit Twiddling. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)BSD Signal Handling. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Signal Handling. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)BSD Signal Handling. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)BSD Signal Handling. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)BSD Signal Handling. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosfN: (libc)Trig Functions. |
| * sincosfNx: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinfN: (libc)Trig Functions. |
| * sinfNx: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhfN: (libc)Hyperbolic Functions. |
| * sinhfNx: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtfN: (libc)Exponents and Logarithms. |
| * sqrtfNx: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying Strings and Arrays. |
| * stpncpy: (libc)Truncating Strings. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Concatenating Strings. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying Strings and Arrays. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying Strings and Arrays. |
| * strdupa: (libc)Copying Strings and Arrays. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfromd: (libc)Printing of Floats. |
| * strfromf: (libc)Printing of Floats. |
| * strfromfN: (libc)Printing of Floats. |
| * strfromfNx: (libc)Printing of Floats. |
| * strfroml: (libc)Printing of Floats. |
| * strfry: (libc)Shuffling Bytes. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Truncating Strings. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Truncating Strings. |
| * strndup: (libc)Truncating Strings. |
| * strndupa: (libc)Truncating Strings. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtofN: (libc)Parsing of Floats. |
| * strtofNx: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * 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. |
| * tanfN: (libc)Trig Functions. |
| * tanfNx: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhfN: (libc)Hyperbolic Functions. |
| * tanhfNx: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammafN: (libc)Special Functions. |
| * tgammafNx: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * tgkill: (libc)Signaling Another Process. |
| * thrd_create: (libc)ISO C Thread Management. |
| * thrd_current: (libc)ISO C Thread Management. |
| * thrd_detach: (libc)ISO C Thread Management. |
| * thrd_equal: (libc)ISO C Thread Management. |
| * thrd_exit: (libc)ISO C Thread Management. |
| * thrd_join: (libc)ISO C Thread Management. |
| * thrd_sleep: (libc)ISO C Thread Management. |
| * thrd_yield: (libc)ISO C Thread Management. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * totalorder: (libc)FP Comparison Functions. |
| * totalorderf: (libc)FP Comparison Functions. |
| * totalorderfN: (libc)FP Comparison Functions. |
| * totalorderfNx: (libc)FP Comparison Functions. |
| * totalorderl: (libc)FP Comparison Functions. |
| * totalordermag: (libc)FP Comparison Functions. |
| * totalordermagf: (libc)FP Comparison Functions. |
| * totalordermagfN: (libc)FP Comparison Functions. |
| * totalordermagfNx: (libc)FP Comparison Functions. |
| * totalordermagl: (libc)FP Comparison Functions. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncfN: (libc)Rounding Functions. |
| * truncfNx: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * tss_create: (libc)ISO C Thread-local Storage. |
| * tss_delete: (libc)ISO C Thread-local Storage. |
| * tss_get: (libc)ISO C Thread-local Storage. |
| * tss_set: (libc)ISO C Thread-local Storage. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * twalk_r: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ufromfp: (libc)Rounding Functions. |
| * ufromfpf: (libc)Rounding Functions. |
| * ufromfpfN: (libc)Rounding Functions. |
| * ufromfpfNx: (libc)Rounding Functions. |
| * ufromfpl: (libc)Rounding Functions. |
| * ufromfpx: (libc)Rounding Functions. |
| * ufromfpxf: (libc)Rounding Functions. |
| * ufromfpxfN: (libc)Rounding Functions. |
| * ufromfpxfNx: (libc)Rounding Functions. |
| * ufromfpxl: (libc)Rounding Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying Strings and Arrays. |
| * wcpncpy: (libc)Truncating Strings. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Concatenating Strings. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying Strings and Arrays. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying Strings and Arrays. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Truncating Strings. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Truncating Strings. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstofN: (libc)Parsing of Floats. |
| * wcstofNx: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying Strings and Arrays. |
| * wmemmove: (libc)Copying Strings and Arrays. |
| * wmempcpy: (libc)Copying Strings and Arrays. |
| * wmemset: (libc)Copying Strings and Arrays. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0fN: (libc)Special Functions. |
| * y0fNx: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1fN: (libc)Special Functions. |
| * y1fNx: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynfN: (libc)Special Functions. |
| * ynfNx: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU C Library. |
| |
| This is `The GNU C Library Reference Manual', for version 2.30 |
| (GNU Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10)). |
| |
| Copyright (C) 1993-2019 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." |
| |
| |
| File: libc.info, Node: Integer Conversions, Next: Floating-Point Conversions, Prev: Table of Output Conversions, Up: Formatted Output |
| |
| 12.12.4 Integer Conversions |
| --------------------------- |
| |
| This section describes the options for the `%d', `%i', `%o', `%u', |
| `%x', and `%X' conversion specifications. These conversions print |
| integers in various formats. |
| |
| The `%d' and `%i' conversion specifications both print an `int' |
| argument as a signed decimal number; while `%o', `%u', and `%x' print |
| the argument as an unsigned octal, decimal, or hexadecimal number |
| (respectively). The `%X' conversion specification is just like `%x' |
| except that it uses the characters `ABCDEF' as digits instead of |
| `abcdef'. |
| |
| The following flags are meaningful: |
| |
| `-' |
| Left-justify the result in the field (instead of the normal |
| right-justification). |
| |
| `+' |
| For the signed `%d' and `%i' conversions, print a plus sign if the |
| value is positive. |
| |
| ` ' |
| For the signed `%d' and `%i' conversions, if the result doesn't |
| start with a plus or minus sign, prefix it with a space character |
| instead. Since the `+' flag ensures that the result includes a |
| sign, this flag is ignored if you supply both of them. |
| |
| `#' |
| For the `%o' conversion, this forces the leading digit to be `0', |
| as if by increasing the precision. For `%x' or `%X', this |
| prefixes a leading `0x' or `0X' (respectively) to the result. |
| This doesn't do anything useful for the `%d', `%i', or `%u' |
| conversions. Using this flag produces output which can be parsed |
| by the `strtoul' function (*note Parsing of Integers::) and |
| `scanf' with the `%i' conversion (*note Numeric Input |
| Conversions::). |
| |
| `'' |
| Separate the digits into groups as specified by the locale |
| specified for the `LC_NUMERIC' category; *note General Numeric::. |
| This flag is a GNU extension. |
| |
| `0' |
| Pad the field with zeros instead of spaces. The zeros are placed |
| after any indication of sign or base. This flag is ignored if the |
| `-' flag is also specified, or if a precision is specified. |
| |
| If a precision is supplied, it specifies the minimum number of |
| digits to appear; leading zeros are produced if necessary. If you |
| don't specify a precision, the number is printed with as many digits as |
| it needs. If you convert a value of zero with an explicit precision of |
| zero, then no characters at all are produced. |
| |
| Without a type modifier, the corresponding argument is treated as an |
| `int' (for the signed conversions `%i' and `%d') or `unsigned int' (for |
| the unsigned conversions `%o', `%u', `%x', and `%X'). Recall that |
| since `printf' and friends are variadic, any `char' and `short' |
| arguments are automatically converted to `int' by the default argument |
| promotions. For arguments of other integer types, you can use these |
| modifiers: |
| |
| `hh' |
| Specifies that the argument is a `signed char' or `unsigned char', |
| as appropriate. A `char' argument is converted to an `int' or |
| `unsigned int' by the default argument promotions anyway, but the |
| `hh' modifier says to convert it back to a `char' again. |
| |
| This modifier was introduced in ISO C99. |
| |
| `h' |
| Specifies that the argument is a `short int' or `unsigned short |
| int', as appropriate. A `short' argument is converted to an `int' |
| or `unsigned int' by the default argument promotions anyway, but |
| the `h' modifier says to convert it back to a `short' again. |
| |
| `j' |
| Specifies that the argument is a `intmax_t' or `uintmax_t', as |
| appropriate. |
| |
| This modifier was introduced in ISO C99. |
| |
| `l' |
| Specifies that the argument is a `long int' or `unsigned long |
| int', as appropriate. Two `l' characters are like the `L' |
| modifier, below. |
| |
| If used with `%c' or `%s' the corresponding parameter is |
| considered as a wide character or wide character string |
| respectively. This use of `l' was introduced in Amendment 1 to |
| ISO C90. |
| |
| `L' |
| `ll' |
| `q' |
| Specifies that the argument is a `long long int'. (This type is |
| an extension supported by the GNU C compiler. On systems that |
| don't support extra-long integers, this is the same as `long int'.) |
| |
| The `q' modifier is another name for the same thing, which comes |
| from 4.4 BSD; a `long long int' is sometimes called a "quad" `int'. |
| |
| `t' |
| Specifies that the argument is a `ptrdiff_t'. |
| |
| This modifier was introduced in ISO C99. |
| |
| `z' |
| `Z' |
| Specifies that the argument is a `size_t'. |
| |
| `z' was introduced in ISO C99. `Z' is a GNU extension predating |
| this addition and should not be used in new code. |
| |
| Here is an example. Using the template string: |
| |
| "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n" |
| |
| to print numbers using the different options for the `%d' conversion |
| gives results like: |
| |
| | 0|0 | +0|+0 | 0|00000| | 00|0| |
| | 1|1 | +1|+1 | 1|00001| 1| 01|1| |
| | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1| |
| |100000|100000|+100000|+100000| 100000|100000|100000|100000|100000| |
| |
| In particular, notice what happens in the last case where the number |
| is too large to fit in the minimum field width specified. |
| |
| Here are some more examples showing how unsigned integers print under |
| various format options, using the template string: |
| |
| "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n" |
| |
| | 0| 0| 0| 0| 0| 0| 0| 00000000| |
| | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001| |
| |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0| |
| |
| |
| File: libc.info, Node: Floating-Point Conversions, Next: Other Output Conversions, Prev: Integer Conversions, Up: Formatted Output |
| |
| 12.12.5 Floating-Point Conversions |
| ---------------------------------- |
| |
| This section discusses the conversion specifications for floating-point |
| numbers: the `%f', `%e', `%E', `%g', and `%G' conversions. |
| |
| The `%f' conversion prints its argument in fixed-point notation, |
| producing output of the form [`-']DDD`.'DDD, where the number of digits |
| following the decimal point is controlled by the precision you specify. |
| |
| The `%e' conversion prints its argument in exponential notation, |
| producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD. Again, the |
| number of digits following the decimal point is controlled by the |
| precision. The exponent always contains at least two digits. The `%E' |
| conversion is similar but the exponent is marked with the letter `E' |
| instead of `e'. |
| |
| The `%g' and `%G' conversions print the argument in the style of |
| `%e' or `%E' (respectively) if the exponent would be less than -4 or |
| greater than or equal to the precision; otherwise they use the `%f' |
| style. A precision of `0', is taken as 1. Trailing zeros are removed |
| from the fractional portion of the result and a decimal-point character |
| appears only if it is followed by a digit. |
| |
| The `%a' and `%A' conversions are meant for representing |
| floating-point numbers exactly in textual form so that they can be |
| exchanged as texts between different programs and/or machines. The |
| numbers are represented in the form [`-']`0x'H`.'HHH`p'[`+'|`-']DD. At |
| the left of the decimal-point character exactly one digit is print. |
| This character is only `0' if the number is denormalized. Otherwise |
| the value is unspecified; it is implementation dependent how many bits |
| are used. The number of hexadecimal digits on the right side of the |
| decimal-point character is equal to the precision. If the precision is |
| zero it is determined to be large enough to provide an exact |
| representation of the number (or it is large enough to distinguish two |
| adjacent values if the `FLT_RADIX' is not a power of 2, *note Floating |
| Point Parameters::). For the `%a' conversion lower-case characters are |
| used to represent the hexadecimal number and the prefix and exponent |
| sign are printed as `0x' and `p' respectively. Otherwise upper-case |
| characters are used and `0X' and `P' are used for the representation of |
| prefix and exponent string. The exponent to the base of two is printed |
| as a decimal number using at least one digit but at most as many digits |
| as necessary to represent the value exactly. |
| |
| If the value to be printed represents infinity or a NaN, the output |
| is [`-']`inf' or `nan' respectively if the conversion specifier is |
| `%a', `%e', `%f', or `%g' and it is [`-']`INF' or `NAN' respectively if |
| the conversion is `%A', `%E', or `%G'. |
| |
| The following flags can be used to modify the behavior: |
| |
| `-' |
| Left-justify the result in the field. Normally the result is |
| right-justified. |
| |
| `+' |
| Always include a plus or minus sign in the result. |
| |
| ` ' |
| If the result doesn't start with a plus or minus sign, prefix it |
| with a space instead. Since the `+' flag ensures that the result |
| includes a sign, this flag is ignored if you supply both of them. |
| |
| `#' |
| Specifies that the result should always include a decimal point, |
| even if no digits follow it. For the `%g' and `%G' conversions, |
| this also forces trailing zeros after the decimal point to be left |
| in place where they would otherwise be removed. |
| |
| `'' |
| Separate the digits of the integer part of the result into groups |
| as specified by the locale specified for the `LC_NUMERIC' category; |
| *note General Numeric::. This flag is a GNU extension. |
| |
| `0' |
| Pad the field with zeros instead of spaces; the zeros are placed |
| after any sign. This flag is ignored if the `-' flag is also |
| specified. |
| |
| The precision specifies how many digits follow the decimal-point |
| character for the `%f', `%e', and `%E' conversions. For these |
| conversions, the default precision is `6'. If the precision is |
| explicitly `0', this suppresses the decimal point character entirely. |
| For the `%g' and `%G' conversions, the precision specifies how many |
| significant digits to print. Significant digits are the first digit |
| before the decimal point, and all the digits after it. If the |
| precision is `0' or not specified for `%g' or `%G', it is treated like |
| a value of `1'. If the value being printed cannot be expressed |
| accurately in the specified number of digits, the value is rounded to |
| the nearest number that fits. |
| |
| Without a type modifier, the floating-point conversions use an |
| argument of type `double'. (By the default argument promotions, any |
| `float' arguments are automatically converted to `double'.) The |
| following type modifier is supported: |
| |
| `L' |
| An uppercase `L' specifies that the argument is a `long double'. |
| |
| Here are some examples showing how numbers print using the various |
| floating-point conversions. All of the numbers were printed using this |
| template string: |
| |
| "|%13.4a|%13.4f|%13.4e|%13.4g|\n" |
| |
| Here is the output: |
| |
| | 0x0.0000p+0| 0.0000| 0.0000e+00| 0| |
| | 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5| |
| | 0x1.0000p+0| 1.0000| 1.0000e+00| 1| |
| | -0x1.0000p+0| -1.0000| -1.0000e+00| -1| |
| | 0x1.9000p+6| 100.0000| 1.0000e+02| 100| |
| | 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000| |
| | 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04| |
| | 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04| |
| | 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05| |
| | 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05| |
| |
| Notice how the `%g' conversion drops trailing zeros. |
| |
| |
| File: libc.info, Node: Other Output Conversions, Next: Formatted Output Functions, Prev: Floating-Point Conversions, Up: Formatted Output |
| |
| 12.12.6 Other Output Conversions |
| -------------------------------- |
| |
| This section describes miscellaneous conversions for `printf'. |
| |
| The `%c' conversion prints a single character. In case there is no |
| `l' modifier the `int' argument is first converted to an `unsigned |
| char'. Then, if used in a wide stream function, the character is |
| converted into the corresponding wide character. The `-' flag can be |
| used to specify left-justification in the field, but no other flags are |
| defined, and no precision or type modifier can be given. For example: |
| |
| printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o'); |
| |
| prints `hello'. |
| |
| If there is an `l' modifier present the argument is expected to be |
| of type `wint_t'. If used in a multibyte function the wide character |
| is converted into a multibyte character before being added to the |
| output. In this case more than one output byte can be produced. |
| |
| The `%s' conversion prints a string. If no `l' modifier is present |
| the corresponding argument must be of type `char *' (or `const char |
| *'). If used in a wide stream function the string is first converted |
| to a wide character string. A precision can be specified to indicate |
| the maximum number of characters to write; otherwise characters in the |
| string up to but not including the terminating null character are |
| written to the output stream. The `-' flag can be used to specify |
| left-justification in the field, but no other flags or type modifiers |
| are defined for this conversion. For example: |
| |
| printf ("%3s%-6s", "no", "where"); |
| |
| prints ` nowhere '. |
| |
| If there is an `l' modifier present, the argument is expected to be |
| of type `wchar_t' (or `const wchar_t *'). |
| |
| If you accidentally pass a null pointer as the argument for a `%s' |
| conversion, the GNU C Library prints it as `(null)'. We think this is |
| more useful than crashing. But it's not good practice to pass a null |
| argument intentionally. |
| |
| The `%m' conversion prints the string corresponding to the error |
| code in `errno'. *Note Error Messages::. Thus: |
| |
| fprintf (stderr, "can't open `%s': %m\n", filename); |
| |
| is equivalent to: |
| |
| fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno)); |
| |
| The `%m' conversion is a GNU C Library extension. |
| |
| The `%p' conversion prints a pointer value. The corresponding |
| argument must be of type `void *'. In practice, you can use any type |
| of pointer. |
| |
| In the GNU C Library, non-null pointers are printed as unsigned |
| integers, as if a `%#x' conversion were used. Null pointers print as |
| `(nil)'. (Pointers might print differently in other systems.) |
| |
| For example: |
| |
| printf ("%p", "testing"); |
| |
| prints `0x' followed by a hexadecimal number--the address of the string |
| constant `"testing"'. It does not print the word `testing'. |
| |
| You can supply the `-' flag with the `%p' conversion to specify |
| left-justification, but no other flags, precision, or type modifiers |
| are defined. |
| |
| The `%n' conversion is unlike any of the other output conversions. |
| It uses an argument which must be a pointer to an `int', but instead of |
| printing anything it stores the number of characters printed so far by |
| this call at that location. The `h' and `l' type modifiers are |
| permitted to specify that the argument is of type `short int *' or |
| `long int *' instead of `int *', but no flags, field width, or |
| precision are permitted. |
| |
| For example, |
| |
| int nchar; |
| printf ("%d %s%n\n", 3, "bears", &nchar); |
| |
| prints: |
| |
| 3 bears |
| |
| and sets `nchar' to `7', because `3 bears' is seven characters. |
| |
| The `%%' conversion prints a literal `%' character. This conversion |
| doesn't use an argument, and no flags, field width, precision, or type |
| modifiers are permitted. |
| |
| |
| File: libc.info, Node: Formatted Output Functions, Next: Dynamic Output, Prev: Other Output Conversions, Up: Formatted Output |
| |
| 12.12.7 Formatted Output Functions |
| ---------------------------------- |
| |
| This section describes how to call `printf' and related functions. |
| Prototypes for these functions are in the header file `stdio.h'. |
| Because these functions take a variable number of arguments, you _must_ |
| declare prototypes for them before using them. Of course, the easiest |
| way to make sure you have all the right prototypes is to just include |
| `stdio.h'. |
| |
| -- Function: int printf (const char *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| The `printf' function prints the optional arguments under the |
| control of the template string TEMPLATE to the stream `stdout'. |
| It returns the number of characters printed, or a negative value |
| if there was an output error. |
| |
| -- Function: int wprintf (const wchar_t *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| The `wprintf' function prints the optional arguments under the |
| control of the wide template string TEMPLATE to the stream |
| `stdout'. It returns the number of wide characters printed, or a |
| negative value if there was an output error. |
| |
| -- Function: int fprintf (FILE *STREAM, const char *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This function is just like `printf', except that the output is |
| written to the stream STREAM instead of `stdout'. |
| |
| -- Function: int fwprintf (FILE *STREAM, const wchar_t *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This function is just like `wprintf', except that the output is |
| written to the stream STREAM instead of `stdout'. |
| |
| -- Function: int sprintf (char *S, const char *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is like `printf', except that the output is stored in the |
| character array S instead of written to a stream. A null |
| character is written to mark the end of the string. |
| |
| The `sprintf' function returns the number of characters stored in |
| the array S, not including the terminating null character. |
| |
| The behavior of this function is undefined if copying takes place |
| between objects that overlap--for example, if S is also given as |
| an argument to be printed under control of the `%s' conversion. |
| *Note Copying Strings and Arrays::. |
| |
| *Warning:* The `sprintf' function can be *dangerous* because it |
| can potentially output more characters than can fit in the |
| allocation size of the string S. Remember that the field width |
| given in a conversion specification is only a _minimum_ value. |
| |
| To avoid this problem, you can use `snprintf' or `asprintf', |
| described below. |
| |
| -- Function: int swprintf (wchar_t *WS, size_t SIZE, const wchar_t |
| *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is like `wprintf', except that the output is stored in the |
| wide character array WS instead of written to a stream. A null |
| wide character is written to mark the end of the string. The SIZE |
| argument specifies the maximum number of characters to produce. |
| The trailing null character is counted towards this limit, so you |
| should allocate at least SIZE wide characters for the string WS. |
| |
| The return value is the number of characters generated for the |
| given input, excluding the trailing null. If not all output fits |
| into the provided buffer a negative value is returned. You should |
| try again with a bigger output string. _Note:_ this is different |
| from how `snprintf' handles this situation. |
| |
| Note that the corresponding narrow stream function takes fewer |
| parameters. `swprintf' in fact corresponds to the `snprintf' |
| function. Since the `sprintf' function can be dangerous and should |
| be avoided the ISO C committee refused to make the same mistake |
| again and decided to not define a function exactly corresponding to |
| `sprintf'. |
| |
| -- Function: int snprintf (char *S, size_t SIZE, const char *TEMPLATE, |
| ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `snprintf' function is similar to `sprintf', except that the |
| SIZE argument specifies the maximum number of characters to |
| produce. The trailing null character is counted towards this |
| limit, so you should allocate at least SIZE characters for the |
| string S. If SIZE is zero, nothing, not even the null byte, shall |
| be written and S may be a null pointer. |
| |
| The return value is the number of characters which would be |
| generated for the given input, excluding the trailing null. If |
| this value is greater than or equal to SIZE, not all characters |
| from the result have been stored in S. You should try again with |
| a bigger output string. Here is an example of doing this: |
| |
| /* Construct a message describing the value of a variable |
| whose name is NAME and whose value is VALUE. */ |
| char * |
| make_message (char *name, char *value) |
| { |
| /* Guess we need no more than 100 chars of space. */ |
| int size = 100; |
| char *buffer = (char *) xmalloc (size); |
| int nchars; |
| if (buffer == NULL) |
| return NULL; |
| |
| /* Try to print in the allocated space. */ |
| nchars = snprintf (buffer, size, "value of %s is %s", |
| name, value); |
| if (nchars >= size) |
| { |
| /* Reallocate buffer now that we know |
| how much space is needed. */ |
| size = nchars + 1; |
| buffer = (char *) xrealloc (buffer, size); |
| |
| if (buffer != NULL) |
| /* Try again. */ |
| snprintf (buffer, size, "value of %s is %s", |
| name, value); |
| } |
| /* The last call worked, return the string. */ |
| return buffer; |
| } |
| |
| In practice, it is often easier just to use `asprintf', below. |
| |
| *Attention:* In versions of the GNU C Library prior to 2.1 the |
| return value is the number of characters stored, not including the |
| terminating null; unless there was not enough space in S to store |
| the result in which case `-1' is returned. This was changed in |
| order to comply with the ISO C99 standard. |
| |
| |
| File: libc.info, Node: Dynamic Output, Next: Variable Arguments Output, Prev: Formatted Output Functions, Up: Formatted Output |
| |
| 12.12.8 Dynamically Allocating Formatted Output |
| ----------------------------------------------- |
| |
| The functions in this section do formatted output and place the results |
| in dynamically allocated memory. |
| |
| -- Function: int asprintf (char **PTR, const char *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This function is similar to `sprintf', except that it dynamically |
| allocates a string (as with `malloc'; *note Unconstrained |
| Allocation::) to hold the output, instead of putting the output in |
| a buffer you allocate in advance. The PTR argument should be the |
| address of a `char *' object, and a successful call to `asprintf' |
| stores a pointer to the newly allocated string at that location. |
| |
| The return value is the number of characters allocated for the |
| buffer, or less than zero if an error occurred. Usually this |
| means that the buffer could not be allocated. |
| |
| Here is how to use `asprintf' to get the same result as the |
| `snprintf' example, but more easily: |
| |
| /* Construct a message describing the value of a variable |
| whose name is NAME and whose value is VALUE. */ |
| char * |
| make_message (char *name, char *value) |
| { |
| char *result; |
| if (asprintf (&result, "value of %s is %s", name, value) < 0) |
| return NULL; |
| return result; |
| } |
| |
| -- Function: int obstack_printf (struct obstack *OBSTACK, const char |
| *TEMPLATE, ...) |
| Preliminary: | MT-Safe race:obstack locale | AS-Unsafe corrupt heap |
| | AC-Unsafe corrupt mem | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `asprintf', except that it uses the |
| obstack OBSTACK to allocate the space. *Note Obstacks::. |
| |
| The characters are written onto the end of the current object. To |
| get at them, you must finish the object with `obstack_finish' |
| (*note Growing Objects::). |
| |
| |
| File: libc.info, Node: Variable Arguments Output, Next: Parsing a Template String, Prev: Dynamic Output, Up: Formatted Output |
| |
| 12.12.9 Variable Arguments Output Functions |
| ------------------------------------------- |
| |
| The functions `vprintf' and friends are provided so that you can define |
| your own variadic `printf'-like functions that make use of the same |
| internals as the built-in formatted output functions. |
| |
| The most natural way to define such functions would be to use a |
| language construct to say, "Call `printf' and pass this template plus |
| all of my arguments after the first five." But there is no way to do |
| this in C, and it would be hard to provide a way, since at the C |
| language level there is no way to tell how many arguments your function |
| received. |
| |
| Since that method is impossible, we provide alternative functions, |
| the `vprintf' series, which lets you pass a `va_list' to describe "all |
| of my arguments after the first five." |
| |
| When it is sufficient to define a macro rather than a real function, |
| the GNU C compiler provides a way to do this much more easily with |
| macros. For example: |
| |
| #define myprintf(a, b, c, d, e, rest...) \ |
| printf (mytemplate , ## rest) |
| |
| *Note Variadic Macros: (cpp)Variadic Macros, for details. But this is |
| limited to macros, and does not apply to real functions at all. |
| |
| Before calling `vprintf' or the other functions listed in this |
| section, you _must_ call `va_start' (*note Variadic Functions::) to |
| initialize a pointer to the variable arguments. Then you can call |
| `va_arg' to fetch the arguments that you want to handle yourself. This |
| advances the pointer past those arguments. |
| |
| Once your `va_list' pointer is pointing at the argument of your |
| choice, you are ready to call `vprintf'. That argument and all |
| subsequent arguments that were passed to your function are used by |
| `vprintf' along with the template that you specified separately. |
| |
| *Portability Note:* The value of the `va_list' pointer is |
| undetermined after the call to `vprintf', so you must not use `va_arg' |
| after you call `vprintf'. Instead, you should call `va_end' to retire |
| the pointer from service. You can call `va_start' again and begin |
| fetching the arguments from the start of the variable argument list. |
| (Alternatively, you can use `va_copy' to make a copy of the `va_list' |
| pointer before calling `vfprintf'.) Calling `vprintf' does not destroy |
| the argument list of your function, merely the particular pointer that |
| you passed to it. |
| |
| Prototypes for these functions are declared in `stdio.h'. |
| |
| -- Function: int vprintf (const char *TEMPLATE, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `printf' except that, instead of taking |
| a variable number of arguments directly, it takes an argument list |
| pointer AP. |
| |
| -- Function: int vwprintf (const wchar_t *TEMPLATE, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `wprintf' except that, instead of |
| taking a variable number of arguments directly, it takes an |
| argument list pointer AP. |
| |
| -- Function: int vfprintf (FILE *STREAM, const char *TEMPLATE, va_list |
| AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `fprintf' with the variable argument list |
| specified directly as for `vprintf'. |
| |
| -- Function: int vfwprintf (FILE *STREAM, const wchar_t *TEMPLATE, |
| va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `fwprintf' with the variable argument |
| list specified directly as for `vwprintf'. |
| |
| -- Function: int vsprintf (char *S, const char *TEMPLATE, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `sprintf' with the variable argument list |
| specified directly as for `vprintf'. |
| |
| -- Function: int vswprintf (wchar_t *WS, size_t SIZE, const wchar_t |
| *TEMPLATE, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `swprintf' with the variable argument |
| list specified directly as for `vwprintf'. |
| |
| -- Function: int vsnprintf (char *S, size_t SIZE, const char |
| *TEMPLATE, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `snprintf' with the variable argument |
| list specified directly as for `vprintf'. |
| |
| -- Function: int vasprintf (char **PTR, const char *TEMPLATE, va_list |
| AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `vasprintf' function is the equivalent of `asprintf' with the |
| variable argument list specified directly as for `vprintf'. |
| |
| -- Function: int obstack_vprintf (struct obstack *OBSTACK, const char |
| *TEMPLATE, va_list AP) |
| Preliminary: | MT-Safe race:obstack locale | AS-Unsafe corrupt heap |
| | AC-Unsafe corrupt mem | *Note POSIX Safety Concepts::. |
| |
| The `obstack_vprintf' function is the equivalent of |
| `obstack_printf' with the variable argument list specified directly |
| as for `vprintf'. |
| |
| Here's an example showing how you might use `vfprintf'. This is a |
| function that prints error messages to the stream `stderr', along with |
| a prefix indicating the name of the program (*note Error Messages::, |
| for a description of `program_invocation_short_name'). |
| |
| #include <stdio.h> |
| #include <stdarg.h> |
| |
| void |
| eprintf (const char *template, ...) |
| { |
| va_list ap; |
| extern char *program_invocation_short_name; |
| |
| fprintf (stderr, "%s: ", program_invocation_short_name); |
| va_start (ap, template); |
| vfprintf (stderr, template, ap); |
| va_end (ap); |
| } |
| |
| You could call `eprintf' like this: |
| |
| eprintf ("file `%s' does not exist\n", filename); |
| |
| In GNU C, there is a special construct you can use to let the |
| compiler know that a function uses a `printf'-style format string. |
| Then it can check the number and types of arguments in each call to the |
| function, and warn you when they do not match the format string. For |
| example, take this declaration of `eprintf': |
| |
| void eprintf (const char *template, ...) |
| __attribute__ ((format (printf, 1, 2))); |
| |
| This tells the compiler that `eprintf' uses a format string like |
| `printf' (as opposed to `scanf'; *note Formatted Input::); the format |
| string appears as the first argument; and the arguments to satisfy the |
| format begin with the second. *Note Declaring Attributes of Functions: |
| (gcc)Function Attributes, for more information. |
| |
| |
| File: libc.info, Node: Parsing a Template String, Next: Example of Parsing, Prev: Variable Arguments Output, Up: Formatted Output |
| |
| 12.12.10 Parsing a Template String |
| ---------------------------------- |
| |
| You can use the function `parse_printf_format' to obtain information |
| about the number and types of arguments that are expected by a given |
| template string. This function permits interpreters that provide |
| interfaces to `printf' to avoid passing along invalid arguments from |
| the user's program, which could cause a crash. |
| |
| All the symbols described in this section are declared in the header |
| file `printf.h'. |
| |
| -- Function: size_t parse_printf_format (const char *TEMPLATE, size_t |
| N, int *ARGTYPES) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns information about the number and types of |
| arguments expected by the `printf' template string TEMPLATE. The |
| information is stored in the array ARGTYPES; each element of this |
| array describes one argument. This information is encoded using |
| the various `PA_' macros, listed below. |
| |
| The argument N specifies the number of elements in the array |
| ARGTYPES. This is the maximum number of elements that |
| `parse_printf_format' will try to write. |
| |
| `parse_printf_format' returns the total number of arguments |
| required by TEMPLATE. If this number is greater than N, then the |
| information returned describes only the first N arguments. If you |
| want information about additional arguments, allocate a bigger |
| array and call `parse_printf_format' again. |
| |
| The argument types are encoded as a combination of a basic type and |
| modifier flag bits. |
| |
| -- Macro: int PA_FLAG_MASK |
| This macro is a bitmask for the type modifier flag bits. You can |
| write the expression `(argtypes[i] & PA_FLAG_MASK)' to extract |
| just the flag bits for an argument, or `(argtypes[i] & |
| ~PA_FLAG_MASK)' to extract just the basic type code. |
| |
| Here are symbolic constants that represent the basic types; they |
| stand for integer values. |
| |
| `PA_INT' |
| This specifies that the base type is `int'. |
| |
| `PA_CHAR' |
| This specifies that the base type is `int', cast to `char'. |
| |
| `PA_STRING' |
| This specifies that the base type is `char *', a null-terminated |
| string. |
| |
| `PA_POINTER' |
| This specifies that the base type is `void *', an arbitrary |
| pointer. |
| |
| `PA_FLOAT' |
| This specifies that the base type is `float'. |
| |
| `PA_DOUBLE' |
| This specifies that the base type is `double'. |
| |
| `PA_LAST' |
| You can define additional base types for your own programs as |
| offsets from `PA_LAST'. For example, if you have data types `foo' |
| and `bar' with their own specialized `printf' conversions, you |
| could define encodings for these types as: |
| |
| #define PA_FOO PA_LAST |
| #define PA_BAR (PA_LAST + 1) |
| |
| Here are the flag bits that modify a basic type. They are combined |
| with the code for the basic type using inclusive-or. |
| |
| `PA_FLAG_PTR' |
| If this bit is set, it indicates that the encoded type is a |
| pointer to the base type, rather than an immediate value. For |
| example, `PA_INT|PA_FLAG_PTR' represents the type `int *'. |
| |
| `PA_FLAG_SHORT' |
| If this bit is set, it indicates that the base type is modified |
| with `short'. (This corresponds to the `h' type modifier.) |
| |
| `PA_FLAG_LONG' |
| If this bit is set, it indicates that the base type is modified |
| with `long'. (This corresponds to the `l' type modifier.) |
| |
| `PA_FLAG_LONG_LONG' |
| If this bit is set, it indicates that the base type is modified |
| with `long long'. (This corresponds to the `L' type modifier.) |
| |
| `PA_FLAG_LONG_DOUBLE' |
| This is a synonym for `PA_FLAG_LONG_LONG', used by convention with |
| a base type of `PA_DOUBLE' to indicate a type of `long double'. |
| |
| For an example of using these facilities, see *note Example of |
| Parsing::. |
| |
| |
| File: libc.info, Node: Example of Parsing, Prev: Parsing a Template String, Up: Formatted Output |
| |
| 12.12.11 Example of Parsing a Template String |
| --------------------------------------------- |
| |
| Here is an example of decoding argument types for a format string. We |
| assume this is part of an interpreter which contains arguments of type |
| `NUMBER', `CHAR', `STRING' and `STRUCTURE' (and perhaps others which |
| are not valid here). |
| |
| /* Test whether the NARGS specified objects |
| in the vector ARGS are valid |
| for the format string FORMAT: |
| if so, return 1. |
| If not, return 0 after printing an error message. */ |
| |
| int |
| validate_args (char *format, int nargs, OBJECT *args) |
| { |
| int *argtypes; |
| int nwanted; |
| |
| /* Get the information about the arguments. |
| Each conversion specification must be at least two characters |
| long, so there cannot be more specifications than half the |
| length of the string. */ |
| |
| argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int)); |
| nwanted = parse_printf_format (string, nelts, argtypes); |
| |
| /* Check the number of arguments. */ |
| if (nwanted > nargs) |
| { |
| error ("too few arguments (at least %d required)", nwanted); |
| return 0; |
| } |
| |
| /* Check the C type wanted for each argument |
| and see if the object given is suitable. */ |
| for (i = 0; i < nwanted; i++) |
| { |
| int wanted; |
| |
| if (argtypes[i] & PA_FLAG_PTR) |
| wanted = STRUCTURE; |
| else |
| switch (argtypes[i] & ~PA_FLAG_MASK) |
| { |
| case PA_INT: |
| case PA_FLOAT: |
| case PA_DOUBLE: |
| wanted = NUMBER; |
| break; |
| case PA_CHAR: |
| wanted = CHAR; |
| break; |
| case PA_STRING: |
| wanted = STRING; |
| break; |
| case PA_POINTER: |
| wanted = STRUCTURE; |
| break; |
| } |
| if (TYPE (args[i]) != wanted) |
| { |
| error ("type mismatch for arg number %d", i); |
| return 0; |
| } |
| } |
| return 1; |
| } |
| |
| |
| File: libc.info, Node: Customizing Printf, Next: Formatted Input, Prev: Formatted Output, Up: I/O on Streams |
| |
| 12.13 Customizing `printf' |
| ========================== |
| |
| The GNU C Library lets you define your own custom conversion specifiers |
| for `printf' template strings, to teach `printf' clever ways to print |
| the important data structures of your program. |
| |
| The way you do this is by registering the conversion with the |
| function `register_printf_function'; see *note Registering New |
| Conversions::. One of the arguments you pass to this function is a |
| pointer to a handler function that produces the actual output; see |
| *note Defining the Output Handler::, for information on how to write |
| this function. |
| |
| You can also install a function that just returns information about |
| the number and type of arguments expected by the conversion specifier. |
| *Note Parsing a Template String::, for information about this. |
| |
| The facilities of this section are declared in the header file |
| `printf.h'. |
| |
| * Menu: |
| |
| * Registering New Conversions:: Using `register_printf_function' |
| to register a new output conversion. |
| * Conversion Specifier Options:: The handler must be able to get |
| the options specified in the |
| template when it is called. |
| * Defining the Output Handler:: Defining the handler and arginfo |
| functions that are passed as arguments |
| to `register_printf_function'. |
| * Printf Extension Example:: How to define a `printf' |
| handler function. |
| * Predefined Printf Handlers:: Predefined `printf' handlers. |
| |
| *Portability Note:* The ability to extend the syntax of `printf' |
| template strings is a GNU extension. ISO standard C has nothing |
| similar. When using the GNU C compiler or any other compiler that |
| interprets calls to standard I/O functions according to the rules of |
| the language standard it is necessary to disable such handling by the |
| appropriate compiler option. Otherwise the behavior of a program that |
| relies on the extension is undefined. |
| |
| |
| File: libc.info, Node: Registering New Conversions, Next: Conversion Specifier Options, Up: Customizing Printf |
| |
| 12.13.1 Registering New Conversions |
| ----------------------------------- |
| |
| The function to register a new output conversion is |
| `register_printf_function', declared in `printf.h'. |
| |
| -- Function: int register_printf_function (int SPEC, printf_function |
| HANDLER-FUNCTION, printf_arginfo_function ARGINFO-FUNCTION) |
| Preliminary: | MT-Unsafe const:printfext | AS-Unsafe heap lock | |
| AC-Unsafe mem lock | *Note POSIX Safety Concepts::. |
| |
| This function defines the conversion specifier character SPEC. |
| Thus, if SPEC is `'Y'', it defines the conversion `%Y'. You can |
| redefine the built-in conversions like `%s', but flag characters |
| like `#' and type modifiers like `l' can never be used as |
| conversions; calling `register_printf_function' for those |
| characters has no effect. It is advisable not to use lowercase |
| letters, since the ISO C standard warns that additional lowercase |
| letters may be standardized in future editions of the standard. |
| |
| The HANDLER-FUNCTION is the function called by `printf' and |
| friends when this conversion appears in a template string. *Note |
| Defining the Output Handler::, for information about how to define |
| a function to pass as this argument. If you specify a null |
| pointer, any existing handler function for SPEC is removed. |
| |
| The ARGINFO-FUNCTION is the function called by |
| `parse_printf_format' when this conversion appears in a template |
| string. *Note Parsing a Template String::, for information about |
| this. |
| |
| *Attention:* In the GNU C Library versions before 2.0 the |
| ARGINFO-FUNCTION function did not need to be installed unless the |
| user used the `parse_printf_format' function. This has changed. |
| Now a call to any of the `printf' functions will call this |
| function when this format specifier appears in the format string. |
| |
| The return value is `0' on success, and `-1' on failure (which |
| occurs if SPEC is out of range). |
| |
| *Portability Note:* It is possible to redefine the standard output |
| conversions but doing so is strongly discouraged because it may |
| interfere with the behavior of programs and compiler |
| implementations that assume the effects of the conversions conform |
| to the relevant language standards. In addition, conforming |
| compilers need not guarantee that the function registered for a |
| standard conversion will be called for each such conversion in |
| every format string in a program. |
| |
| |
| File: libc.info, Node: Conversion Specifier Options, Next: Defining the Output Handler, Prev: Registering New Conversions, Up: Customizing Printf |
| |
| 12.13.2 Conversion Specifier Options |
| ------------------------------------ |
| |
| If you define a meaning for `%A', what if the template contains `%+23A' |
| or `%-#A'? To implement a sensible meaning for these, the handler when |
| called needs to be able to get the options specified in the template. |
| |
| Both the HANDLER-FUNCTION and ARGINFO-FUNCTION accept an argument |
| that points to a `struct printf_info', which contains information about |
| the options appearing in an instance of the conversion specifier. This |
| data type is declared in the header file `printf.h'. |
| |
| -- Type: struct printf_info |
| This structure is used to pass information about the options |
| appearing in an instance of a conversion specifier in a `printf' |
| template string to the handler and arginfo functions for that |
| specifier. It contains the following members: |
| |
| `int prec' |
| This is the precision specified. The value is `-1' if no |
| precision was specified. If the precision was given as `*', |
| the `printf_info' structure passed to the handler function |
| contains the actual value retrieved from the argument list. |
| But the structure passed to the arginfo function contains a |
| value of `INT_MIN', since the actual value is not known. |
| |
| `int width' |
| This is the minimum field width specified. The value is `0' |
| if no width was specified. If the field width was given as |
| `*', the `printf_info' structure passed to the handler |
| function contains the actual value retrieved from the |
| argument list. But the structure passed to the arginfo |
| function contains a value of `INT_MIN', since the actual |
| value is not known. |
| |
| `wchar_t spec' |
| This is the conversion specifier character specified. It's |
| stored in the structure so that you can register the same |
| handler function for multiple characters, but still have a |
| way to tell them apart when the handler function is called. |
| |
| `unsigned int is_long_double' |
| This is a boolean that is true if the `L', `ll', or `q' type |
| modifier was specified. For integer conversions, this |
| indicates `long long int', as opposed to `long double' for |
| floating point conversions. |
| |
| `unsigned int is_char' |
| This is a boolean that is true if the `hh' type modifier was |
| specified. |
| |
| `unsigned int is_short' |
| This is a boolean that is true if the `h' type modifier was |
| specified. |
| |
| `unsigned int is_long' |
| This is a boolean that is true if the `l' type modifier was |
| specified. |
| |
| `unsigned int alt' |
| This is a boolean that is true if the `#' flag was specified. |
| |
| `unsigned int space' |
| This is a boolean that is true if the ` ' flag was specified. |
| |
| `unsigned int left' |
| This is a boolean that is true if the `-' flag was specified. |
| |
| `unsigned int showsign' |
| This is a boolean that is true if the `+' flag was specified. |
| |
| `unsigned int group' |
| This is a boolean that is true if the `'' flag was specified. |
| |
| `unsigned int extra' |
| This flag has a special meaning depending on the context. It |
| could be used freely by the user-defined handlers but when |
| called from the `printf' function this variable always |
| contains the value `0'. |
| |
| `unsigned int wide' |
| This flag is set if the stream is wide oriented. |
| |
| `wchar_t pad' |
| This is the character to use for padding the output to the |
| minimum field width. The value is `'0'' if the `0' flag was |
| specified, and `' '' otherwise. |
| |
| |
| File: libc.info, Node: Defining the Output Handler, Next: Printf Extension Example, Prev: Conversion Specifier Options, Up: Customizing Printf |
| |
| 12.13.3 Defining the Output Handler |
| ----------------------------------- |
| |
| Now let's look at how to define the handler and arginfo functions which |
| are passed as arguments to `register_printf_function'. |
| |
| *Compatibility Note:* The interface changed in the GNU C Library |
| version 2.0. Previously the third argument was of type `va_list *'. |
| |
| You should define your handler functions with a prototype like: |
| |
| int FUNCTION (FILE *stream, const struct printf_info *info, |
| const void *const *args) |
| |
| The STREAM argument passed to the handler function is the stream to |
| which it should write output. |
| |
| The INFO argument is a pointer to a structure that contains |
| information about the various options that were included with the |
| conversion in the template string. You should not modify this structure |
| inside your handler function. *Note Conversion Specifier Options::, for |
| a description of this data structure. |
| |
| The ARGS is a vector of pointers to the arguments data. The number |
| of arguments was determined by calling the argument information |
| function provided by the user. |
| |
| Your handler function should return a value just like `printf' does: |
| it should return the number of characters it has written, or a negative |
| value to indicate an error. |
| |
| -- Data Type: printf_function |
| This is the data type that a handler function should have. |
| |
| If you are going to use `parse_printf_format' in your application, |
| you must also define a function to pass as the ARGINFO-FUNCTION |
| argument for each new conversion you install with |
| `register_printf_function'. |
| |
| You have to define these functions with a prototype like: |
| |
| int FUNCTION (const struct printf_info *info, |
| size_t n, int *argtypes) |
| |
| The return value from the function should be the number of arguments |
| the conversion expects. The function should also fill in no more than |
| N elements of the ARGTYPES array with information about the types of |
| each of these arguments. This information is encoded using the various |
| `PA_' macros. (You will notice that this is the same calling |
| convention `parse_printf_format' itself uses.) |
| |
| -- Data Type: printf_arginfo_function |
| This type is used to describe functions that return information |
| about the number and type of arguments used by a conversion |
| specifier. |
| |
| |
| File: libc.info, Node: Printf Extension Example, Next: Predefined Printf Handlers, Prev: Defining the Output Handler, Up: Customizing Printf |
| |
| 12.13.4 `printf' Extension Example |
| ---------------------------------- |
| |
| Here is an example showing how to define a `printf' handler function. |
| This program defines a data structure called a `Widget' and defines the |
| `%W' conversion to print information about `Widget *' arguments, |
| including the pointer value and the name stored in the data structure. |
| The `%W' conversion supports the minimum field width and |
| left-justification options, but ignores everything else. |
| |
| |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <printf.h> |
| |
| typedef struct |
| { |
| char *name; |
| } |
| Widget; |
| |
| int |
| print_widget (FILE *stream, |
| const struct printf_info *info, |
| const void *const *args) |
| { |
| const Widget *w; |
| char *buffer; |
| int len; |
| |
| /* Format the output into a string. */ |
| w = *((const Widget **) (args[0])); |
| len = asprintf (&buffer, "<Widget %p: %s>", w, w->name); |
| if (len == -1) |
| return -1; |
| |
| /* Pad to the minimum field width and print to the stream. */ |
| len = fprintf (stream, "%*s", |
| (info->left ? -info->width : info->width), |
| buffer); |
| |
| /* Clean up and return. */ |
| free (buffer); |
| return len; |
| } |
| |
| |
| int |
| print_widget_arginfo (const struct printf_info *info, size_t n, |
| int *argtypes) |
| { |
| /* We always take exactly one argument and this is a pointer to the |
| structure.. */ |
| if (n > 0) |
| argtypes[0] = PA_POINTER; |
| return 1; |
| } |
| |
| |
| int |
| main (void) |
| { |
| /* Make a widget to print. */ |
| Widget mywidget; |
| mywidget.name = "mywidget"; |
| |
| /* Register the print function for widgets. */ |
| register_printf_function ('W', print_widget, print_widget_arginfo); |
| |
| /* Now print the widget. */ |
| printf ("|%W|\n", &mywidget); |
| printf ("|%35W|\n", &mywidget); |
| printf ("|%-35W|\n", &mywidget); |
| |
| return 0; |
| } |
| |
| The output produced by this program looks like: |
| |
| |<Widget 0xffeffb7c: mywidget>| |
| | <Widget 0xffeffb7c: mywidget>| |
| |<Widget 0xffeffb7c: mywidget> | |
| |
| |
| File: libc.info, Node: Predefined Printf Handlers, Prev: Printf Extension Example, Up: Customizing Printf |
| |
| 12.13.5 Predefined `printf' Handlers |
| ------------------------------------ |
| |
| The GNU C Library also contains a concrete and useful application of the |
| `printf' handler extension. There are two functions available which |
| implement a special way to print floating-point numbers. |
| |
| -- Function: int printf_size (FILE *FP, const struct printf_info |
| *INFO, const void *const *ARGS) |
| Preliminary: | MT-Safe race:fp locale | AS-Unsafe corrupt heap | |
| AC-Unsafe mem corrupt | *Note POSIX Safety Concepts::. |
| |
| Print a given floating point number as for the format `%f' except |
| that there is a postfix character indicating the divisor for the |
| number to make this less than 1000. There are two possible |
| divisors: powers of 1024 or powers of 1000. Which one is used |
| depends on the format character specified while registered this |
| handler. If the character is of lower case, 1024 is used. For |
| upper case characters, 1000 is used. |
| |
| The postfix tag corresponds to bytes, kilobytes, megabytes, |
| gigabytes, etc. The full table is: |
| |
| low Multiplier From Upper Multiplier |
| ' ' 1 ' ' 1 |
| k 2^10 (1024) kilo K 10^3 (1000) |
| m 2^20 mega M 10^6 |
| g 2^30 giga G 10^9 |
| t 2^40 tera T 10^12 |
| p 2^50 peta P 10^15 |
| e 2^60 exa E 10^18 |
| z 2^70 zetta Z 10^21 |
| y 2^80 yotta Y 10^24 |
| |
| The default precision is 3, i.e., 1024 is printed with a lower-case |
| format character as if it were `%.3fk' and will yield `1.000k'. |
| |
| Due to the requirements of `register_printf_function' we must also |
| provide the function which returns information about the arguments. |
| |
| -- Function: int printf_size_info (const struct printf_info *INFO, |
| size_t N, int *ARGTYPES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function will return in ARGTYPES the information about the |
| used parameters in the way the `vfprintf' implementation expects |
| it. The format always takes one argument. |
| |
| To use these functions both functions must be registered with a call |
| like |
| |
| register_printf_function ('B', printf_size, printf_size_info); |
| |
| Here we register the functions to print numbers as powers of 1000 |
| since the format character `'B'' is an upper-case character. If we |
| would additionally use `'b'' in a line like |
| |
| register_printf_function ('b', printf_size, printf_size_info); |
| |
| we could also print using a power of 1024. Please note that all that is |
| different in these two lines is the format specifier. The |
| `printf_size' function knows about the difference between lower and |
| upper case format specifiers. |
| |
| The use of `'B'' and `'b'' is no coincidence. Rather it is the |
| preferred way to use this functionality since it is available on some |
| other systems which also use format specifiers. |
| |
| |
| File: libc.info, Node: Formatted Input, Next: EOF and Errors, Prev: Customizing Printf, Up: I/O on Streams |
| |
| 12.14 Formatted Input |
| ===================== |
| |
| The functions described in this section (`scanf' and related functions) |
| provide facilities for formatted input analogous to the formatted |
| output facilities. These functions provide a mechanism for reading |
| arbitrary values under the control of a "format string" or "template |
| string". |
| |
| * Menu: |
| |
| * Formatted Input Basics:: Some basics to get you started. |
| * Input Conversion Syntax:: Syntax of conversion specifications. |
| * Table of Input Conversions:: Summary of input conversions and what they do. |
| * Numeric Input Conversions:: Details of conversions for reading numbers. |
| * String Input Conversions:: Details of conversions for reading strings. |
| * Dynamic String Input:: String conversions that `malloc' the buffer. |
| * Other Input Conversions:: Details of miscellaneous other conversions. |
| * Formatted Input Functions:: Descriptions of the actual functions. |
| * Variable Arguments Input:: `vscanf' and friends. |
| |
| |
| File: libc.info, Node: Formatted Input Basics, Next: Input Conversion Syntax, Up: Formatted Input |
| |
| 12.14.1 Formatted Input Basics |
| ------------------------------ |
| |
| Calls to `scanf' are superficially similar to calls to `printf' in that |
| arbitrary arguments are read under the control of a template string. |
| While the syntax of the conversion specifications in the template is |
| very similar to that for `printf', the interpretation of the template |
| is oriented more towards free-format input and simple pattern matching, |
| rather than fixed-field formatting. For example, most `scanf' |
| conversions skip over any amount of "white space" (including spaces, |
| tabs, and newlines) in the input file, and there is no concept of |
| precision for the numeric input conversions as there is for the |
| corresponding output conversions. Ordinarily, non-whitespace |
| characters in the template are expected to match characters in the |
| input stream exactly, but a matching failure is distinct from an input |
| error on the stream. |
| |
| Another area of difference between `scanf' and `printf' is that you |
| must remember to supply pointers rather than immediate values as the |
| optional arguments to `scanf'; the values that are read are stored in |
| the objects that the pointers point to. Even experienced programmers |
| tend to forget this occasionally, so if your program is getting strange |
| errors that seem to be related to `scanf', you might want to |
| double-check this. |
| |
| When a "matching failure" occurs, `scanf' returns immediately, |
| leaving the first non-matching character as the next character to be |
| read from the stream. The normal return value from `scanf' is the |
| number of values that were assigned, so you can use this to determine if |
| a matching error happened before all the expected values were read. |
| |
| The `scanf' function is typically used for things like reading in |
| the contents of tables. For example, here is a function that uses |
| `scanf' to initialize an array of `double': |
| |
| void |
| readarray (double *array, int n) |
| { |
| int i; |
| for (i=0; i<n; i++) |
| if (scanf (" %lf", &(array[i])) != 1) |
| invalid_input_error (); |
| } |
| |
| The formatted input functions are not used as frequently as the |
| formatted output functions. Partly, this is because it takes some care |
| to use them properly. Another reason is that it is difficult to recover |
| from a matching error. |
| |
| If you are trying to read input that doesn't match a single, fixed |
| pattern, you may be better off using a tool such as Flex to generate a |
| lexical scanner, or Bison to generate a parser, rather than using |
| `scanf'. For more information about these tools, see *note Top: |
| (flex.info)Top, and *note Top: (bison.info)Top. |
| |
| |
| File: libc.info, Node: Input Conversion Syntax, Next: Table of Input Conversions, Prev: Formatted Input Basics, Up: Formatted Input |
| |
| 12.14.2 Input Conversion Syntax |
| ------------------------------- |
| |
| A `scanf' template string is a string that contains ordinary multibyte |
| characters interspersed with conversion specifications that start with |
| `%'. |
| |
| Any whitespace character (as defined by the `isspace' function; |
| *note Classification of Characters::) in the template causes any number |
| of whitespace characters in the input stream to be read and discarded. |
| The whitespace characters that are matched need not be exactly the same |
| whitespace characters that appear in the template string. For example, |
| write ` , ' in the template to recognize a comma with optional |
| whitespace before and after. |
| |
| Other characters in the template string that are not part of |
| conversion specifications must match characters in the input stream |
| exactly; if this is not the case, a matching failure occurs. |
| |
| The conversion specifications in a `scanf' template string have the |
| general form: |
| |
| % FLAGS WIDTH TYPE CONVERSION |
| |
| In more detail, an input conversion specification consists of an |
| initial `%' character followed in sequence by: |
| |
| * An optional "flag character" `*', which says to ignore the text |
| read for this specification. When `scanf' finds a conversion |
| specification that uses this flag, it reads input as directed by |
| the rest of the conversion specification, but it discards this |
| input, does not use a pointer argument, and does not increment the |
| count of successful assignments. |
| |
| * An optional flag character `a' (valid with string conversions only) |
| which requests allocation of a buffer long enough to store the |
| string in. (This is a GNU extension.) *Note Dynamic String |
| Input::. |
| |
| * An optional decimal integer that specifies the "maximum field |
| width". Reading of characters from the input stream stops either |
| when this maximum is reached or when a non-matching character is |
| found, whichever happens first. Most conversions discard initial |
| whitespace characters (those that don't are explicitly |
| documented), and these discarded characters don't count towards |
| the maximum field width. String input conversions store a null |
| character to mark the end of the input; the maximum field width |
| does not include this terminator. |
| |
| * An optional "type modifier character". For example, you can |
| specify a type modifier of `l' with integer conversions such as |
| `%d' to specify that the argument is a pointer to a `long int' |
| rather than a pointer to an `int'. |
| |
| * A character that specifies the conversion to be applied. |
| |
| The exact options that are permitted and how they are interpreted |
| vary between the different conversion specifiers. See the descriptions |
| of the individual conversions for information about the particular |
| options that they allow. |
| |
| With the `-Wformat' option, the GNU C compiler checks calls to |
| `scanf' and related functions. It examines the format string and |
| verifies that the correct number and types of arguments are supplied. |
| There is also a GNU C syntax to tell the compiler that a function you |
| write uses a `scanf'-style format string. *Note Declaring Attributes |
| of Functions: (gcc)Function Attributes, for more information. |
| |
| |
| File: libc.info, Node: Table of Input Conversions, Next: Numeric Input Conversions, Prev: Input Conversion Syntax, Up: Formatted Input |
| |
| 12.14.3 Table of Input Conversions |
| ---------------------------------- |
| |
| Here is a table that summarizes the various conversion specifications: |
| |
| `%d' |
| Matches an optionally signed integer written in decimal. *Note |
| Numeric Input Conversions::. |
| |
| `%i' |
| Matches an optionally signed integer in any of the formats that |
| the C language defines for specifying an integer constant. *Note |
| Numeric Input Conversions::. |
| |
| `%o' |
| Matches an unsigned integer written in octal radix. *Note Numeric |
| Input Conversions::. |
| |
| `%u' |
| Matches an unsigned integer written in decimal radix. *Note |
| Numeric Input Conversions::. |
| |
| `%x', `%X' |
| Matches an unsigned integer written in hexadecimal radix. *Note |
| Numeric Input Conversions::. |
| |
| `%e', `%f', `%g', `%E', `%G' |
| Matches an optionally signed floating-point number. *Note Numeric |
| Input Conversions::. |
| |
| `%s' |
| Matches a string containing only non-whitespace characters. *Note |
| String Input Conversions::. The presence of the `l' modifier |
| determines whether the output is stored as a wide character string |
| or a multibyte string. If `%s' is used in a wide character |
| function the string is converted as with multiple calls to |
| `wcrtomb' into a multibyte string. This means that the buffer |
| must provide room for `MB_CUR_MAX' bytes for each wide character |
| read. In case `%ls' is used in a multibyte function the result is |
| converted into wide characters as with multiple calls of `mbrtowc' |
| before being stored in the user provided buffer. |
| |
| `%S' |
| This is an alias for `%ls' which is supported for compatibility |
| with the Unix standard. |
| |
| `%[' |
| Matches a string of characters that belong to a specified set. |
| *Note String Input Conversions::. The presence of the `l' modifier |
| determines whether the output is stored as a wide character string |
| or a multibyte string. If `%[' is used in a wide character |
| function the string is converted as with multiple calls to |
| `wcrtomb' into a multibyte string. This means that the buffer |
| must provide room for `MB_CUR_MAX' bytes for each wide character |
| read. In case `%l[' is used in a multibyte function the result is |
| converted into wide characters as with multiple calls of `mbrtowc' |
| before being stored in the user provided buffer. |
| |
| `%c' |
| Matches a string of one or more characters; the number of |
| characters read is controlled by the maximum field width given for |
| the conversion. *Note String Input Conversions::. |
| |
| If `%c' is used in a wide stream function the read value is |
| converted from a wide character to the corresponding multibyte |
| character before storing it. Note that this conversion can |
| produce more than one byte of output and therefore the provided |
| buffer must be large enough for up to `MB_CUR_MAX' bytes for each |
| character. If `%lc' is used in a multibyte function the input is |
| treated as a multibyte sequence (and not bytes) and the result is |
| converted as with calls to `mbrtowc'. |
| |
| `%C' |
| This is an alias for `%lc' which is supported for compatibility |
| with the Unix standard. |
| |
| `%p' |
| Matches a pointer value in the same implementation-defined format |
| used by the `%p' output conversion for `printf'. *Note Other |
| Input Conversions::. |
| |
| `%n' |
| This conversion doesn't read any characters; it records the number |
| of characters read so far by this call. *Note Other Input |
| Conversions::. |
| |
| `%%' |
| This matches a literal `%' character in the input stream. No |
| corresponding argument is used. *Note Other Input Conversions::. |
| |
| If the syntax of a conversion specification is invalid, the behavior |
| is undefined. If there aren't enough function arguments provided to |
| supply addresses for all the conversion specifications in the template |
| strings that perform assignments, or if the arguments are not of the |
| correct types, the behavior is also undefined. On the other hand, extra |
| arguments are simply ignored. |
| |
| |
| File: libc.info, Node: Numeric Input Conversions, Next: String Input Conversions, Prev: Table of Input Conversions, Up: Formatted Input |
| |
| 12.14.4 Numeric Input Conversions |
| --------------------------------- |
| |
| This section describes the `scanf' conversions for reading numeric |
| values. |
| |
| The `%d' conversion matches an optionally signed integer in decimal |
| radix. The syntax that is recognized is the same as that for the |
| `strtol' function (*note Parsing of Integers::) with the value `10' for |
| the BASE argument. |
| |
| The `%i' conversion matches an optionally signed integer in any of |
| the formats that the C language defines for specifying an integer |
| constant. The syntax that is recognized is the same as that for the |
| `strtol' function (*note Parsing of Integers::) with the value `0' for |
| the BASE argument. (You can print integers in this syntax with |
| `printf' by using the `#' flag character with the `%x', `%o', or `%d' |
| conversion. *Note Integer Conversions::.) |
| |
| For example, any of the strings `10', `0xa', or `012' could be read |
| in as integers under the `%i' conversion. Each of these specifies a |
| number with decimal value `10'. |
| |
| The `%o', `%u', and `%x' conversions match unsigned integers in |
| octal, decimal, and hexadecimal radices, respectively. The syntax that |
| is recognized is the same as that for the `strtoul' function (*note |
| Parsing of Integers::) with the appropriate value (`8', `10', or `16') |
| for the BASE argument. |
| |
| The `%X' conversion is identical to the `%x' conversion. They both |
| permit either uppercase or lowercase letters to be used as digits. |
| |
| The default type of the corresponding argument for the `%d' and `%i' |
| conversions is `int *', and `unsigned int *' for the other integer |
| conversions. You can use the following type modifiers to specify other |
| sizes of integer: |
| |
| `hh' |
| Specifies that the argument is a `signed char *' or `unsigned char |
| *'. |
| |
| This modifier was introduced in ISO C99. |
| |
| `h' |
| Specifies that the argument is a `short int *' or `unsigned short |
| int *'. |
| |
| `j' |
| Specifies that the argument is a `intmax_t *' or `uintmax_t *'. |
| |
| This modifier was introduced in ISO C99. |
| |
| `l' |
| Specifies that the argument is a `long int *' or `unsigned long |
| int *'. Two `l' characters is like the `L' modifier, below. |
| |
| If used with `%c' or `%s' the corresponding parameter is |
| considered as a pointer to a wide character or wide character |
| string respectively. This use of `l' was introduced in |
| Amendment 1 to ISO C90. |
| |
| `ll' |
| `L' |
| `q' |
| Specifies that the argument is a `long long int *' or `unsigned |
| long long int *'. (The `long long' type is an extension supported |
| by the GNU C compiler. For systems that don't provide extra-long |
| integers, this is the same as `long int'.) |
| |
| The `q' modifier is another name for the same thing, which comes |
| from 4.4 BSD; a `long long int' is sometimes called a "quad" `int'. |
| |
| `t' |
| Specifies that the argument is a `ptrdiff_t *'. |
| |
| This modifier was introduced in ISO C99. |
| |
| `z' |
| Specifies that the argument is a `size_t *'. |
| |
| This modifier was introduced in ISO C99. |
| |
| All of the `%e', `%f', `%g', `%E', and `%G' input conversions are |
| interchangeable. They all match an optionally signed floating point |
| number, in the same syntax as for the `strtod' function (*note Parsing |
| of Floats::). |
| |
| For the floating-point input conversions, the default argument type |
| is `float *'. (This is different from the corresponding output |
| conversions, where the default type is `double'; remember that `float' |
| arguments to `printf' are converted to `double' by the default argument |
| promotions, but `float *' arguments are not promoted to `double *'.) |
| You can specify other sizes of float using these type modifiers: |
| |
| `l' |
| Specifies that the argument is of type `double *'. |
| |
| `L' |
| Specifies that the argument is of type `long double *'. |
| |
| For all the above number parsing formats there is an additional |
| optional flag `''. When this flag is given the `scanf' function |
| expects the number represented in the input string to be formatted |
| according to the grouping rules of the currently selected locale (*note |
| General Numeric::). |
| |
| If the `"C"' or `"POSIX"' locale is selected there is no difference. |
| But for a locale which specifies values for the appropriate fields in |
| the locale the input must have the correct form in the input. |
| Otherwise the longest prefix with a correct form is processed. |
| |
| |
| File: libc.info, Node: String Input Conversions, Next: Dynamic String Input, Prev: Numeric Input Conversions, Up: Formatted Input |
| |
| 12.14.5 String Input Conversions |
| -------------------------------- |
| |
| This section describes the `scanf' input conversions for reading string |
| and character values: `%s', `%S', `%[', `%c', and `%C'. |
| |
| You have two options for how to receive the input from these |
| conversions: |
| |
| * Provide a buffer to store it in. This is the default. You should |
| provide an argument of type `char *' or `wchar_t *' (the latter if |
| the `l' modifier is present). |
| |
| *Warning:* To make a robust program, you must make sure that the |
| input (plus its terminating null) cannot possibly exceed the size |
| of the buffer you provide. In general, the only way to do this is |
| to specify a maximum field width one less than the buffer size. |
| *If you provide the buffer, always specify a maximum field width |
| to prevent overflow.* |
| |
| * Ask `scanf' to allocate a big enough buffer, by specifying the `a' |
| flag character. This is a GNU extension. You should provide an |
| argument of type `char **' for the buffer address to be stored in. |
| *Note Dynamic String Input::. |
| |
| The `%c' conversion is the simplest: it matches a fixed number of |
| characters, always. The maximum field width says how many characters to |
| read; if you don't specify the maximum, the default is 1. This |
| conversion doesn't append a null character to the end of the text it |
| reads. It also does not skip over initial whitespace characters. It |
| reads precisely the next N characters, and fails if it cannot get that |
| many. Since there is always a maximum field width with `%c' (whether |
| specified, or 1 by default), you can always prevent overflow by making |
| the buffer long enough. |
| |
| If the format is `%lc' or `%C' the function stores wide characters |
| which are converted using the conversion determined at the time the |
| stream was opened from the external byte stream. The number of bytes |
| read from the medium is limited by `MB_CUR_LEN * N' but at most N wide |
| characters get stored in the output string. |
| |
| The `%s' conversion matches a string of non-whitespace characters. |
| It skips and discards initial whitespace, but stops when it encounters |
| more whitespace after having read something. It stores a null character |
| at the end of the text that it reads. |
| |
| For example, reading the input: |
| |
| hello, world |
| |
| with the conversion `%10c' produces `" hello, wo"', but reading the |
| same input with the conversion `%10s' produces `"hello,"'. |
| |
| *Warning:* If you do not specify a field width for `%s', then the |
| number of characters read is limited only by where the next whitespace |
| character appears. This almost certainly means that invalid input can |
| make your program crash--which is a bug. |
| |
| The `%ls' and `%S' format are handled just like `%s' except that the |
| external byte sequence is converted using the conversion associated |
| with the stream to wide characters with their own encoding. A width or |
| precision specified with the format do not directly determine how many |
| bytes are read from the stream since they measure wide characters. But |
| an upper limit can be computed by multiplying the value of the width or |
| precision by `MB_CUR_MAX'. |
| |
| To read in characters that belong to an arbitrary set of your choice, |
| use the `%[' conversion. You specify the set between the `[' character |
| and a following `]' character, using the same syntax used in regular |
| expressions for explicit sets of characters. As special cases: |
| |
| * A literal `]' character can be specified as the first character of |
| the set. |
| |
| * An embedded `-' character (that is, one that is not the first or |
| last character of the set) is used to specify a range of |
| characters. |
| |
| * If a caret character `^' immediately follows the initial `[', then |
| the set of allowed input characters is everything _except_ the |
| characters listed. |
| |
| The `%[' conversion does not skip over initial whitespace characters. |
| |
| Note that the "character class" syntax available in character sets |
| that appear inside regular expressions (such as `[:alpha:]') is _not_ |
| available in the `%[' conversion. |
| |
| Here are some examples of `%[' conversions and what they mean: |
| |
| `%25[1234567890]' |
| Matches a string of up to 25 digits. |
| |
| `%25[][]' |
| Matches a string of up to 25 square brackets. |
| |
| `%25[^ \f\n\r\t\v]' |
| Matches a string up to 25 characters long that doesn't contain any |
| of the standard whitespace characters. This is slightly different |
| from `%s', because if the input begins with a whitespace character, |
| `%[' reports a matching failure while `%s' simply discards the |
| initial whitespace. |
| |
| `%25[a-z]' |
| Matches up to 25 lowercase characters. |
| |
| As for `%c' and `%s' the `%[' format is also modified to produce |
| wide characters if the `l' modifier is present. All what is said about |
| `%ls' above is true for `%l['. |
| |
| One more reminder: the `%s' and `%[' conversions are *dangerous* if |
| you don't specify a maximum width or use the `a' flag, because input |
| too long would overflow whatever buffer you have provided for it. No |
| matter how long your buffer is, a user could supply input that is |
| longer. A well-written program reports invalid input with a |
| comprehensible error message, not with a crash. |
| |
| |
| File: libc.info, Node: Dynamic String Input, Next: Other Input Conversions, Prev: String Input Conversions, Up: Formatted Input |
| |
| 12.14.6 Dynamically Allocating String Conversions |
| ------------------------------------------------- |
| |
| A GNU extension to formatted input lets you safely read a string with no |
| maximum size. Using this feature, you don't supply a buffer; instead, |
| `scanf' allocates a buffer big enough to hold the data and gives you |
| its address. To use this feature, write `a' as a flag character, as in |
| `%as' or `%a[0-9a-z]'. |
| |
| The pointer argument you supply for where to store the input should |
| have type `char **'. The `scanf' function allocates a buffer and |
| stores its address in the word that the argument points to. You should |
| free the buffer with `free' when you no longer need it. |
| |
| Here is an example of using the `a' flag with the `%[...]' |
| conversion specification to read a "variable assignment" of the form |
| `VARIABLE = VALUE'. |
| |
| { |
| char *variable, *value; |
| |
| if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n", |
| &variable, &value)) |
| { |
| invalid_input_error (); |
| return 0; |
| } |
| |
| ... |
| } |
| |
| |
| File: libc.info, Node: Other Input Conversions, Next: Formatted Input Functions, Prev: Dynamic String Input, Up: Formatted Input |
| |
| 12.14.7 Other Input Conversions |
| ------------------------------- |
| |
| This section describes the miscellaneous input conversions. |
| |
| The `%p' conversion is used to read a pointer value. It recognizes |
| the same syntax used by the `%p' output conversion for `printf' (*note |
| Other Output Conversions::); that is, a hexadecimal number just as the |
| `%x' conversion accepts. The corresponding argument should be of type |
| `void **'; that is, the address of a place to store a pointer. |
| |
| The resulting pointer value is not guaranteed to be valid if it was |
| not originally written during the same program execution that reads it |
| in. |
| |
| The `%n' conversion produces the number of characters read so far by |
| this call. The corresponding argument should be of type `int *'. This |
| conversion works in the same way as the `%n' conversion for `printf'; |
| see *note Other Output Conversions::, for an example. |
| |
| The `%n' conversion is the only mechanism for determining the |
| success of literal matches or conversions with suppressed assignments. |
| If the `%n' follows the locus of a matching failure, then no value is |
| stored for it since `scanf' returns before processing the `%n'. If you |
| store `-1' in that argument slot before calling `scanf', the presence |
| of `-1' after `scanf' indicates an error occurred before the `%n' was |
| reached. |
| |
| Finally, the `%%' conversion matches a literal `%' character in the |
| input stream, without using an argument. This conversion does not |
| permit any flags, field width, or type modifier to be specified. |
| |
| |
| File: libc.info, Node: Formatted Input Functions, Next: Variable Arguments Input, Prev: Other Input Conversions, Up: Formatted Input |
| |
| 12.14.8 Formatted Input Functions |
| --------------------------------- |
| |
| Here are the descriptions of the functions for performing formatted |
| input. Prototypes for these functions are in the header file `stdio.h'. |
| |
| -- Function: int scanf (const char *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| The `scanf' function reads formatted input from the stream `stdin' |
| under the control of the template string TEMPLATE. The optional |
| arguments are pointers to the places which receive the resulting |
| values. |
| |
| The return value is normally the number of successful assignments. |
| If an end-of-file condition is detected before any matches are |
| performed, including matches against whitespace and literal |
| characters in the template, then `EOF' is returned. |
| |
| -- Function: int wscanf (const wchar_t *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| The `wscanf' function reads formatted input from the stream |
| `stdin' under the control of the template string TEMPLATE. The |
| optional arguments are pointers to the places which receive the |
| resulting values. |
| |
| The return value is normally the number of successful assignments. |
| If an end-of-file condition is detected before any matches are |
| performed, including matches against whitespace and literal |
| characters in the template, then `WEOF' is returned. |
| |
| -- Function: int fscanf (FILE *STREAM, const char *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This function is just like `scanf', except that the input is read |
| from the stream STREAM instead of `stdin'. |
| |
| -- Function: int fwscanf (FILE *STREAM, const wchar_t *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This function is just like `wscanf', except that the input is read |
| from the stream STREAM instead of `stdin'. |
| |
| -- Function: int sscanf (const char *S, const char *TEMPLATE, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is like `scanf', except that the characters are taken from the |
| null-terminated string S instead of from a stream. Reaching the |
| end of the string is treated as an end-of-file condition. |
| |
| The behavior of this function is undefined if copying takes place |
| between objects that overlap--for example, if S is also given as |
| an argument to receive a string read under control of the `%s', |
| `%S', or `%[' conversion. |
| |
| -- Function: int swscanf (const wchar_t *WS, const wchar_t *TEMPLATE, |
| ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is like `wscanf', except that the characters are taken from |
| the null-terminated string WS instead of from a stream. Reaching |
| the end of the string is treated as an end-of-file condition. |
| |
| The behavior of this function is undefined if copying takes place |
| between objects that overlap--for example, if WS is also given as |
| an argument to receive a string read under control of the `%s', |
| `%S', or `%[' conversion. |
| |
| |
| File: libc.info, Node: Variable Arguments Input, Prev: Formatted Input Functions, Up: Formatted Input |
| |
| 12.14.9 Variable Arguments Input Functions |
| ------------------------------------------ |
| |
| The functions `vscanf' and friends are provided so that you can define |
| your own variadic `scanf'-like functions that make use of the same |
| internals as the built-in formatted output functions. These functions |
| are analogous to the `vprintf' series of output functions. *Note |
| Variable Arguments Output::, for important information on how to use |
| them. |
| |
| *Portability Note:* The functions listed in this section were |
| introduced in ISO C99 and were before available as GNU extensions. |
| |
| -- Function: int vscanf (const char *TEMPLATE, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `scanf', but instead of taking a |
| variable number of arguments directly, it takes an argument list |
| pointer AP of type `va_list' (*note Variadic Functions::). |
| |
| -- Function: int vwscanf (const wchar_t *TEMPLATE, va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `wscanf', but instead of taking a |
| variable number of arguments directly, it takes an argument list |
| pointer AP of type `va_list' (*note Variadic Functions::). |
| |
| -- Function: int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list |
| AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `fscanf' with the variable argument list |
| specified directly as for `vscanf'. |
| |
| -- Function: int vfwscanf (FILE *STREAM, const wchar_t *TEMPLATE, |
| va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe |
| mem lock corrupt | *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `fwscanf' with the variable argument list |
| specified directly as for `vwscanf'. |
| |
| -- Function: int vsscanf (const char *S, const char *TEMPLATE, va_list |
| AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `sscanf' with the variable argument list |
| specified directly as for `vscanf'. |
| |
| -- Function: int vswscanf (const wchar_t *S, const wchar_t *TEMPLATE, |
| va_list AP) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| This is the equivalent of `swscanf' with the variable argument list |
| specified directly as for `vwscanf'. |
| |
| In GNU C, there is a special construct you can use to let the |
| compiler know that a function uses a `scanf'-style format string. Then |
| it can check the number and types of arguments in each call to the |
| function, and warn you when they do not match the format string. For |
| details, see *note Declaring Attributes of Functions: (gcc)Function |
| Attributes. |
| |
| |
| File: libc.info, Node: EOF and Errors, Next: Error Recovery, Prev: Formatted Input, Up: I/O on Streams |
| |
| 12.15 End-Of-File and Errors |
| ============================ |
| |
| Many of the functions described in this chapter return the value of the |
| macro `EOF' to indicate unsuccessful completion of the operation. |
| Since `EOF' is used to report both end of file and random errors, it's |
| often better to use the `feof' function to check explicitly for end of |
| file and `ferror' to check for errors. These functions check |
| indicators that are part of the internal state of the stream object, |
| indicators set if the appropriate condition was detected by a previous |
| I/O operation on that stream. |
| |
| -- Macro: int EOF |
| This macro is an integer value that is returned by a number of |
| narrow stream functions to indicate an end-of-file condition, or |
| some other error situation. With the GNU C Library, `EOF' is |
| `-1'. In other libraries, its value may be some other negative |
| number. |
| |
| This symbol is declared in `stdio.h'. |
| |
| -- Macro: int WEOF |
| This macro is an integer value that is returned by a number of wide |
| stream functions to indicate an end-of-file condition, or some |
| other error situation. With the GNU C Library, `WEOF' is `-1'. In |
| other libraries, its value may be some other negative number. |
| |
| This symbol is declared in `wchar.h'. |
| |
| -- Function: int feof (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX |
| Safety Concepts::. |
| |
| The `feof' function returns nonzero if and only if the end-of-file |
| indicator for the stream STREAM is set. |
| |
| This symbol is declared in `stdio.h'. |
| |
| -- Function: int feof_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `feof_unlocked' function is equivalent to the `feof' function |
| except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| This symbol is declared in `stdio.h'. |
| |
| -- Function: int ferror (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX |
| Safety Concepts::. |
| |
| The `ferror' function returns nonzero if and only if the error |
| indicator for the stream STREAM is set, indicating that an error |
| has occurred on a previous operation on the stream. |
| |
| This symbol is declared in `stdio.h'. |
| |
| -- Function: int ferror_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `ferror_unlocked' function is equivalent to the `ferror' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| This symbol is declared in `stdio.h'. |
| |
| In addition to setting the error indicator associated with the |
| stream, the functions that operate on streams also set `errno' in the |
| same way as the corresponding low-level functions that operate on file |
| descriptors. For example, all of the functions that perform output to a |
| stream--such as `fputc', `printf', and `fflush'--are implemented in |
| terms of `write', and all of the `errno' error conditions defined for |
| `write' are meaningful for these functions. For more information about |
| the descriptor-level I/O functions, see *note Low-Level I/O::. |
| |
| |
| File: libc.info, Node: Error Recovery, Next: Binary Streams, Prev: EOF and Errors, Up: I/O on Streams |
| |
| 12.16 Recovering from errors |
| ============================ |
| |
| You may explicitly clear the error and EOF flags with the `clearerr' |
| function. |
| |
| -- Function: void clearerr (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX |
| Safety Concepts::. |
| |
| This function clears the end-of-file and error indicators for the |
| stream STREAM. |
| |
| The file positioning functions (*note File Positioning::) also |
| clear the end-of-file indicator for the stream. |
| |
| -- Function: void clearerr_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Safe | AC-Safe | *Note |
| POSIX Safety Concepts::. |
| |
| The `clearerr_unlocked' function is equivalent to the `clearerr' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| Note that it is _not_ correct to just clear the error flag and retry |
| a failed stream operation. After a failed write, any number of |
| characters since the last buffer flush may have been committed to the |
| file, while some buffered data may have been discarded. Merely retrying |
| can thus cause lost or repeated data. |
| |
| A failed read may leave the file pointer in an inappropriate |
| position for a second try. In both cases, you should seek to a known |
| position before retrying. |
| |
| Most errors that can happen are not recoverable -- a second try will |
| always fail again in the same way. So usually it is best to give up and |
| report the error to the user, rather than install complicated recovery |
| logic. |
| |
| One important exception is `EINTR' (*note Interrupted Primitives::). |
| Many stream I/O implementations will treat it as an ordinary error, |
| which can be quite inconvenient. You can avoid this hassle by |
| installing all signals with the `SA_RESTART' flag. |
| |
| For similar reasons, setting nonblocking I/O on a stream's file |
| descriptor is not usually advisable. |
| |
| |
| File: libc.info, Node: Binary Streams, Next: File Positioning, Prev: Error Recovery, Up: I/O on Streams |
| |
| 12.17 Text and Binary Streams |
| ============================= |
| |
| GNU systems and other POSIX-compatible operating systems organize all |
| files as uniform sequences of characters. However, some other systems |
| make a distinction between files containing text and files containing |
| binary data, and the input and output facilities of ISO C provide for |
| this distinction. This section tells you how to write programs portable |
| to such systems. |
| |
| When you open a stream, you can specify either a "text stream" or a |
| "binary stream". You indicate that you want a binary stream by |
| specifying the `b' modifier in the OPENTYPE argument to `fopen'; see |
| *note Opening Streams::. Without this option, `fopen' opens the file |
| as a text stream. |
| |
| Text and binary streams differ in several ways: |
| |
| * The data read from a text stream is divided into "lines" which are |
| terminated by newline (`'\n'') characters, while a binary stream is |
| simply a long series of characters. A text stream might on some |
| systems fail to handle lines more than 254 characters long |
| (including the terminating newline character). |
| |
| * On some systems, text files can contain only printing characters, |
| horizontal tab characters, and newlines, and so text streams may |
| not support other characters. However, binary streams can handle |
| any character value. |
| |
| * Space characters that are written immediately preceding a newline |
| character in a text stream may disappear when the file is read in |
| again. |
| |
| * More generally, there need not be a one-to-one mapping between |
| characters that are read from or written to a text stream, and the |
| characters in the actual file. |
| |
| Since a binary stream is always more capable and more predictable |
| than a text stream, you might wonder what purpose text streams serve. |
| Why not simply always use binary streams? The answer is that on these |
| operating systems, text and binary streams use different file formats, |
| and the only way to read or write "an ordinary file of text" that can |
| work with other text-oriented programs is through a text stream. |
| |
| In the GNU C Library, and on all POSIX systems, there is no |
| difference between text streams and binary streams. When you open a |
| stream, you get the same kind of stream regardless of whether you ask |
| for binary. This stream can handle any file content, and has none of |
| the restrictions that text streams sometimes have. |
| |
| |
| File: libc.info, Node: File Positioning, Next: Portable Positioning, Prev: Binary Streams, Up: I/O on Streams |
| |
| 12.18 File Positioning |
| ====================== |
| |
| The "file position" of a stream describes where in the file the stream |
| is currently reading or writing. I/O on the stream advances the file |
| position through the file. On GNU systems, the file position is |
| represented as an integer, which counts the number of bytes from the |
| beginning of the file. *Note File Position::. |
| |
| During I/O to an ordinary disk file, you can change the file position |
| whenever you wish, so as to read or write any portion of the file. Some |
| other kinds of files may also permit this. Files which support changing |
| the file position are sometimes referred to as "random-access" files. |
| |
| You can use the functions in this section to examine or modify the |
| file position indicator associated with a stream. The symbols listed |
| below are declared in the header file `stdio.h'. |
| |
| -- Function: long int ftell (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function returns the current file position of the stream |
| STREAM. |
| |
| This function can fail if the stream doesn't support file |
| positioning, or if the file position can't be represented in a |
| `long int', and possibly for other reasons as well. If a failure |
| occurs, a value of `-1' is returned. |
| |
| -- Function: off_t ftello (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `ftello' function is similar to `ftell', except that it |
| returns a value of type `off_t'. Systems which support this type |
| use it to describe all file positions, unlike the POSIX |
| specification which uses a long int. The two are not necessarily |
| the same size. Therefore, using ftell can lead to problems if the |
| implementation is written on top of a POSIX compliant low-level |
| I/O implementation, and using `ftello' is preferable whenever it |
| is available. |
| |
| If this function fails it returns `(off_t) -1'. This can happen |
| due to missing support for file positioning or internal errors. |
| Otherwise the return value is the current file position. |
| |
| The function is an extension defined in the Unix Single |
| Specification version 2. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32 bit system this function is in fact `ftello64'. I.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: off64_t ftello64 (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `ftello' with the only difference that |
| the return value is of type `off64_t'. This also requires that the |
| stream STREAM was opened using either `fopen64', `freopen64', or |
| `tmpfile64' since otherwise the underlying file operations to |
| position the file pointer beyond the 2^31 bytes limit might fail. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32 |
| bits machine this function is available under the name `ftello' |
| and so transparently replaces the old interface. |
| |
| -- Function: int fseek (FILE *STREAM, long int OFFSET, int WHENCE) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `fseek' function is used to change the file position of the |
| stream STREAM. The value of WHENCE must be one of the constants |
| `SEEK_SET', `SEEK_CUR', or `SEEK_END', to indicate whether the |
| OFFSET is relative to the beginning of the file, the current file |
| position, or the end of the file, respectively. |
| |
| This function returns a value of zero if the operation was |
| successful, and a nonzero value to indicate failure. A successful |
| call also clears the end-of-file indicator of STREAM and discards |
| any characters that were "pushed back" by the use of `ungetc'. |
| |
| `fseek' either flushes any buffered output before setting the file |
| position or else remembers it so it will be written later in its |
| proper place in the file. |
| |
| -- Function: int fseeko (FILE *STREAM, off_t OFFSET, int WHENCE) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `fseek' but it corrects a problem with |
| `fseek' in a system with POSIX types. Using a value of type `long |
| int' for the offset is not compatible with POSIX. `fseeko' uses |
| the correct type `off_t' for the OFFSET parameter. |
| |
| For this reason it is a good idea to prefer `ftello' whenever it is |
| available since its functionality is (if different at all) closer |
| the underlying definition. |
| |
| The functionality and return value are the same as for `fseek'. |
| |
| The function is an extension defined in the Unix Single |
| Specification version 2. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32 bit system this function is in fact `fseeko64'. I.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: int fseeko64 (FILE *STREAM, off64_t OFFSET, int WHENCE) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `fseeko' with the only difference that |
| the OFFSET parameter is of type `off64_t'. This also requires |
| that the stream STREAM was opened using either `fopen64', |
| `freopen64', or `tmpfile64' since otherwise the underlying file |
| operations to position the file pointer beyond the 2^31 bytes |
| limit might fail. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32 |
| bits machine this function is available under the name `fseeko' |
| and so transparently replaces the old interface. |
| |
| *Portability Note:* In non-POSIX systems, `ftell', `ftello', `fseek' |
| and `fseeko' might work reliably only on binary streams. *Note Binary |
| Streams::. |
| |
| The following symbolic constants are defined for use as the WHENCE |
| argument to `fseek'. They are also used with the `lseek' function |
| (*note I/O Primitives::) and to specify offsets for file locks (*note |
| Control Operations::). |
| |
| -- Macro: int SEEK_SET |
| This is an integer constant which, when used as the WHENCE |
| argument to the `fseek' or `fseeko' functions, specifies that the |
| offset provided is relative to the beginning of the file. |
| |
| -- Macro: int SEEK_CUR |
| This is an integer constant which, when used as the WHENCE |
| argument to the `fseek' or `fseeko' functions, specifies that the |
| offset provided is relative to the current file position. |
| |
| -- Macro: int SEEK_END |
| This is an integer constant which, when used as the WHENCE |
| argument to the `fseek' or `fseeko' functions, specifies that the |
| offset provided is relative to the end of the file. |
| |
| -- Function: void rewind (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `rewind' function positions the stream STREAM at the beginning |
| of the file. It is equivalent to calling `fseek' or `fseeko' on |
| the STREAM with an OFFSET argument of `0L' and a WHENCE argument |
| of `SEEK_SET', except that the return value is discarded and the |
| error indicator for the stream is reset. |
| |
| These three aliases for the `SEEK_...' constants exist for the sake |
| of compatibility with older BSD systems. They are defined in two |
| different header files: `fcntl.h' and `sys/file.h'. |
| |
| `L_SET' |
| An alias for `SEEK_SET'. |
| |
| `L_INCR' |
| An alias for `SEEK_CUR'. |
| |
| `L_XTND' |
| An alias for `SEEK_END'. |
| |
| |
| File: libc.info, Node: Portable Positioning, Next: Stream Buffering, Prev: File Positioning, Up: I/O on Streams |
| |
| 12.19 Portable File-Position Functions |
| ====================================== |
| |
| On GNU systems, the file position is truly a character count. You can |
| specify any character count value as an argument to `fseek' or `fseeko' |
| and get reliable results for any random access file. However, some |
| ISO C systems do not represent file positions in this way. |
| |
| On some systems where text streams truly differ from binary streams, |
| it is impossible to represent the file position of a text stream as a |
| count of characters from the beginning of the file. For example, the |
| file position on some systems must encode both a record offset within |
| the file, and a character offset within the record. |
| |
| As a consequence, if you want your programs to be portable to these |
| systems, you must observe certain rules: |
| |
| * The value returned from `ftell' on a text stream has no predictable |
| relationship to the number of characters you have read so far. |
| The only thing you can rely on is that you can use it subsequently |
| as the OFFSET argument to `fseek' or `fseeko' to move back to the |
| same file position. |
| |
| * In a call to `fseek' or `fseeko' on a text stream, either the |
| OFFSET must be zero, or WHENCE must be `SEEK_SET' and the OFFSET |
| must be the result of an earlier call to `ftell' on the same |
| stream. |
| |
| * The value of the file position indicator of a text stream is |
| undefined while there are characters that have been pushed back |
| with `ungetc' that haven't been read or discarded. *Note |
| Unreading::. |
| |
| But even if you observe these rules, you may still have trouble for |
| long files, because `ftell' and `fseek' use a `long int' value to |
| represent the file position. This type may not have room to encode all |
| the file positions in a large file. Using the `ftello' and `fseeko' |
| functions might help here since the `off_t' type is expected to be able |
| to hold all file position values but this still does not help to handle |
| additional information which must be associated with a file position. |
| |
| So if you do want to support systems with peculiar encodings for the |
| file positions, it is better to use the functions `fgetpos' and |
| `fsetpos' instead. These functions represent the file position using |
| the data type `fpos_t', whose internal representation varies from |
| system to system. |
| |
| These symbols are declared in the header file `stdio.h'. |
| |
| -- Data Type: fpos_t |
| This is the type of an object that can encode information about the |
| file position of a stream, for use by the functions `fgetpos' and |
| `fsetpos'. |
| |
| In the GNU C Library, `fpos_t' is an opaque data structure that |
| contains internal data to represent file offset and conversion |
| state information. In other systems, it might have a different |
| internal representation. |
| |
| When compiling with `_FILE_OFFSET_BITS == 64' on a 32 bit machine |
| this type is in fact equivalent to `fpos64_t' since the LFS |
| interface transparently replaces the old interface. |
| |
| -- Data Type: fpos64_t |
| This is the type of an object that can encode information about the |
| file position of a stream, for use by the functions `fgetpos64' and |
| `fsetpos64'. |
| |
| In the GNU C Library, `fpos64_t' is an opaque data structure that |
| contains internal data to represent file offset and conversion |
| state information. In other systems, it might have a different |
| internal representation. |
| |
| -- Function: int fgetpos (FILE *STREAM, fpos_t *POSITION) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function stores the value of the file position indicator for |
| the stream STREAM in the `fpos_t' object pointed to by POSITION. |
| If successful, `fgetpos' returns zero; otherwise it returns a |
| nonzero value and stores an implementation-defined positive value |
| in `errno'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32 bit system the function is in fact `fgetpos64'. I.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: int fgetpos64 (FILE *STREAM, fpos64_t *POSITION) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `fgetpos' but the file position is |
| returned in a variable of type `fpos64_t' to which POSITION points. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32 |
| bits machine this function is available under the name `fgetpos' |
| and so transparently replaces the old interface. |
| |
| -- Function: int fsetpos (FILE *STREAM, const fpos_t *POSITION) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function sets the file position indicator for the stream |
| STREAM to the position POSITION, which must have been set by a |
| previous call to `fgetpos' on the same stream. If successful, |
| `fsetpos' clears the end-of-file indicator on the stream, discards |
| any characters that were "pushed back" by the use of `ungetc', and |
| returns a value of zero. Otherwise, `fsetpos' returns a nonzero |
| value and stores an implementation-defined positive value in |
| `errno'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a |
| 32 bit system the function is in fact `fsetpos64'. I.e., the LFS |
| interface transparently replaces the old interface. |
| |
| -- Function: int fsetpos64 (FILE *STREAM, const fpos64_t *POSITION) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `fsetpos' but the file position used |
| for positioning is provided in a variable of type `fpos64_t' to |
| which POSITION points. |
| |
| If the sources are compiled with `_FILE_OFFSET_BITS == 64' on a 32 |
| bits machine this function is available under the name `fsetpos' |
| and so transparently replaces the old interface. |
| |
| |
| File: libc.info, Node: Stream Buffering, Next: Other Kinds of Streams, Prev: Portable Positioning, Up: I/O on Streams |
| |
| 12.20 Stream Buffering |
| ====================== |
| |
| Characters that are written to a stream are normally accumulated and |
| transmitted asynchronously to the file in a block, instead of appearing |
| as soon as they are output by the application program. Similarly, |
| streams often retrieve input from the host environment in blocks rather |
| than on a character-by-character basis. This is called "buffering". |
| |
| If you are writing programs that do interactive input and output |
| using streams, you need to understand how buffering works when you |
| design the user interface to your program. Otherwise, you might find |
| that output (such as progress or prompt messages) doesn't appear when |
| you intended it to, or displays some other unexpected behavior. |
| |
| This section deals only with controlling when characters are |
| transmitted between the stream and the file or device, and _not_ with |
| how things like echoing, flow control, and the like are handled on |
| specific classes of devices. For information on common control |
| operations on terminal devices, see *note Low-Level Terminal |
| Interface::. |
| |
| You can bypass the stream buffering facilities altogether by using |
| the low-level input and output functions that operate on file |
| descriptors instead. *Note Low-Level I/O::. |
| |
| * Menu: |
| |
| * Buffering Concepts:: Terminology is defined here. |
| * Flushing Buffers:: How to ensure that output buffers are flushed. |
| * Controlling Buffering:: How to specify what kind of buffering to use. |
| |
| |
| File: libc.info, Node: Buffering Concepts, Next: Flushing Buffers, Up: Stream Buffering |
| |
| 12.20.1 Buffering Concepts |
| -------------------------- |
| |
| There are three different kinds of buffering strategies: |
| |
| * Characters written to or read from an "unbuffered" stream are |
| transmitted individually to or from the file as soon as possible. |
| |
| * Characters written to a "line buffered" stream are transmitted to |
| the file in blocks when a newline character is encountered. |
| |
| * Characters written to or read from a "fully buffered" stream are |
| transmitted to or from the file in blocks of arbitrary size. |
| |
| Newly opened streams are normally fully buffered, with one |
| exception: a stream connected to an interactive device such as a |
| terminal is initially line buffered. *Note Controlling Buffering::, |
| for information on how to select a different kind of buffering. |
| Usually the automatic selection gives you the most convenient kind of |
| buffering for the file or device you open. |
| |
| The use of line buffering for interactive devices implies that output |
| messages ending in a newline will appear immediately--which is usually |
| what you want. Output that doesn't end in a newline might or might not |
| show up immediately, so if you want them to appear immediately, you |
| should flush buffered output explicitly with `fflush', as described in |
| *note Flushing Buffers::. |
| |
| |
| File: libc.info, Node: Flushing Buffers, Next: Controlling Buffering, Prev: Buffering Concepts, Up: Stream Buffering |
| |
| 12.20.2 Flushing Buffers |
| ------------------------ |
| |
| "Flushing" output on a buffered stream means transmitting all |
| accumulated characters to the file. There are many circumstances when |
| buffered output on a stream is flushed automatically: |
| |
| * When you try to do output and the output buffer is full. |
| |
| * When the stream is closed. *Note Closing Streams::. |
| |
| * When the program terminates by calling `exit'. *Note Normal |
| Termination::. |
| |
| * When a newline is written, if the stream is line buffered. |
| |
| * Whenever an input operation on _any_ stream actually reads data |
| from its file. |
| |
| If you want to flush the buffered output at another time, call |
| `fflush', which is declared in the header file `stdio.h'. |
| |
| -- Function: int fflush (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function causes any buffered output on STREAM to be delivered |
| to the file. If STREAM is a null pointer, then `fflush' causes |
| buffered output on _all_ open output streams to be flushed. |
| |
| This function returns `EOF' if a write error occurs, or zero |
| otherwise. |
| |
| -- Function: int fflush_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `fflush_unlocked' function is equivalent to the `fflush' |
| function except that it does not implicitly lock the stream. |
| |
| The `fflush' function can be used to flush all streams currently |
| opened. While this is useful in some situations it does often more than |
| necessary since it might be done in situations when terminal input is |
| required and the program wants to be sure that all output is visible on |
| the terminal. But this means that only line buffered streams have to be |
| flushed. Solaris introduced a function especially for this. It was |
| always available in the GNU C Library in some form but never officially |
| exported. |
| |
| -- Function: void _flushlbf (void) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `_flushlbf' function flushes all line buffered streams |
| currently opened. |
| |
| This function is declared in the `stdio_ext.h' header. |
| |
| *Compatibility Note:* Some brain-damaged operating systems have been |
| known to be so thoroughly fixated on line-oriented input and output |
| that flushing a line buffered stream causes a newline to be written! |
| Fortunately, this "feature" seems to be becoming less common. You do |
| not need to worry about this with the GNU C Library. |
| |
| In some situations it might be useful to not flush the output pending |
| for a stream but instead simply forget it. If transmission is costly |
| and the output is not needed anymore this is valid reasoning. In this |
| situation a non-standard function introduced in Solaris and available in |
| the GNU C Library can be used. |
| |
| -- Function: void __fpurge (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `__fpurge' function causes the buffer of the stream STREAM to |
| be emptied. If the stream is currently in read mode all input in |
| the buffer is lost. If the stream is in output mode the buffered |
| output is not written to the device (or whatever other underlying |
| storage) and the buffer is cleared. |
| |
| This function is declared in `stdio_ext.h'. |
| |
| |
| File: libc.info, Node: Controlling Buffering, Prev: Flushing Buffers, Up: Stream Buffering |
| |
| 12.20.3 Controlling Which Kind of Buffering |
| ------------------------------------------- |
| |
| After opening a stream (but before any other operations have been |
| performed on it), you can explicitly specify what kind of buffering you |
| want it to have using the `setvbuf' function. |
| |
| The facilities listed in this section are declared in the header |
| file `stdio.h'. |
| |
| -- Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t |
| SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function is used to specify that the stream STREAM should |
| have the buffering mode MODE, which can be either `_IOFBF' (for |
| full buffering), `_IOLBF' (for line buffering), or `_IONBF' (for |
| unbuffered input/output). |
| |
| If you specify a null pointer as the BUF argument, then `setvbuf' |
| allocates a buffer itself using `malloc'. This buffer will be |
| freed when you close the stream. |
| |
| Otherwise, BUF should be a character array that can hold at least |
| SIZE characters. You should not free the space for this array as |
| long as the stream remains open and this array remains its buffer. |
| You should usually either allocate it statically, or `malloc' |
| (*note Unconstrained Allocation::) the buffer. Using an automatic |
| array is not a good idea unless you close the file before exiting |
| the block that declares the array. |
| |
| While the array remains a stream buffer, the stream I/O functions |
| will use the buffer for their internal purposes. You shouldn't |
| try to access the values in the array directly while the stream is |
| using it for buffering. |
| |
| The `setvbuf' function returns zero on success, or a nonzero value |
| if the value of MODE is not valid or if the request could not be |
| honored. |
| |
| -- Macro: int _IOFBF |
| The value of this macro is an integer constant expression that can |
| be used as the MODE argument to the `setvbuf' function to specify |
| that the stream should be fully buffered. |
| |
| -- Macro: int _IOLBF |
| The value of this macro is an integer constant expression that can |
| be used as the MODE argument to the `setvbuf' function to specify |
| that the stream should be line buffered. |
| |
| -- Macro: int _IONBF |
| The value of this macro is an integer constant expression that can |
| be used as the MODE argument to the `setvbuf' function to specify |
| that the stream should be unbuffered. |
| |
| -- Macro: int BUFSIZ |
| The value of this macro is an integer constant expression that is |
| good to use for the SIZE argument to `setvbuf'. This value is |
| guaranteed to be at least `256'. |
| |
| The value of `BUFSIZ' is chosen on each system so as to make stream |
| I/O efficient. So it is a good idea to use `BUFSIZ' as the size |
| for the buffer when you call `setvbuf'. |
| |
| Actually, you can get an even better value to use for the buffer |
| size by means of the `fstat' system call: it is found in the |
| `st_blksize' field of the file attributes. *Note Attribute |
| Meanings::. |
| |
| Sometimes people also use `BUFSIZ' as the allocation size of |
| buffers used for related purposes, such as strings used to receive |
| a line of input with `fgets' (*note Character Input::). There is |
| no particular reason to use `BUFSIZ' for this instead of any other |
| integer, except that it might lead to doing I/O in chunks of an |
| efficient size. |
| |
| -- Function: void setbuf (FILE *STREAM, char *BUF) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| If BUF is a null pointer, the effect of this function is |
| equivalent to calling `setvbuf' with a MODE argument of `_IONBF'. |
| Otherwise, it is equivalent to calling `setvbuf' with BUF, and a |
| MODE of `_IOFBF' and a SIZE argument of `BUFSIZ'. |
| |
| The `setbuf' function is provided for compatibility with old code; |
| use `setvbuf' in all new programs. |
| |
| -- Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| If BUF is a null pointer, this function makes STREAM unbuffered. |
| Otherwise, it makes STREAM fully buffered using BUF as the buffer. |
| The SIZE argument specifies the length of BUF. |
| |
| This function is provided for compatibility with old BSD code. Use |
| `setvbuf' instead. |
| |
| -- Function: void setlinebuf (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function makes STREAM be line buffered, and allocates the |
| buffer for you. |
| |
| This function is provided for compatibility with old BSD code. Use |
| `setvbuf' instead. |
| |
| It is possible to query whether a given stream is line buffered or |
| not using a non-standard function introduced in Solaris and available in |
| the GNU C Library. |
| |
| -- Function: int __flbf (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `__flbf' function will return a nonzero value in case the |
| stream STREAM is line buffered. Otherwise the return value is |
| zero. |
| |
| This function is declared in the `stdio_ext.h' header. |
| |
| Two more extensions allow to determine the size of the buffer and how |
| much of it is used. These functions were also introduced in Solaris. |
| |
| -- Function: size_t __fbufsize (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| The `__fbufsize' function return the size of the buffer in the |
| stream STREAM. This value can be used to optimize the use of the |
| stream. |
| |
| This function is declared in the `stdio_ext.h' header. |
| |
| -- Function: size_t __fpending (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| The `__fpending' function returns the number of bytes currently in |
| the output buffer. For wide-oriented streams the measuring unit |
| is wide characters. This function should not be used on buffers |
| in read mode or opened read-only. |
| |
| This function is declared in the `stdio_ext.h' header. |
| |
| |
| File: libc.info, Node: Other Kinds of Streams, Next: Formatted Messages, Prev: Stream Buffering, Up: I/O on Streams |
| |
| 12.21 Other Kinds of Streams |
| ============================ |
| |
| The GNU C Library provides ways for you to define additional kinds of |
| streams that do not necessarily correspond to an open file. |
| |
| One such type of stream takes input from or writes output to a |
| string. These kinds of streams are used internally to implement the |
| `sprintf' and `sscanf' functions. You can also create such a stream |
| explicitly, using the functions described in *note String Streams::. |
| |
| More generally, you can define streams that do input/output to |
| arbitrary objects using functions supplied by your program. This |
| protocol is discussed in *note Custom Streams::. |
| |
| *Portability Note:* The facilities described in this section are |
| specific to GNU. Other systems or C implementations might or might not |
| provide equivalent functionality. |
| |
| * Menu: |
| |
| * String Streams:: Streams that get data from or put data in |
| a string or memory buffer. |
| * Custom Streams:: Defining your own streams with an arbitrary |
| input data source and/or output data sink. |
| |
| |
| File: libc.info, Node: String Streams, Next: Custom Streams, Up: Other Kinds of Streams |
| |
| 12.21.1 String Streams |
| ---------------------- |
| |
| The `fmemopen' and `open_memstream' functions allow you to do I/O to a |
| string or memory buffer. These facilities are declared in `stdio.h'. |
| |
| -- Function: FILE * fmemopen (void *BUF, size_t SIZE, const char |
| *OPENTYPE) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
| | *Note POSIX Safety Concepts::. |
| |
| This function opens a stream that allows the access specified by |
| the OPENTYPE argument, that reads from or writes to the buffer |
| specified by the argument BUF. This array must be at least SIZE |
| bytes long. |
| |
| If you specify a null pointer as the BUF argument, `fmemopen' |
| dynamically allocates an array SIZE bytes long (as with `malloc'; |
| *note Unconstrained Allocation::). This is really only useful if |
| you are going to write things to the buffer and then read them back |
| in again, because you have no way of actually getting a pointer to |
| the buffer (for this, try `open_memstream', below). The buffer is |
| freed when the stream is closed. |
| |
| The argument OPENTYPE is the same as in `fopen' (*note Opening |
| Streams::). If the OPENTYPE specifies append mode, then the |
| initial file position is set to the first null character in the |
| buffer. Otherwise the initial file position is at the beginning |
| of the buffer. |
| |
| When a stream open for writing is flushed or closed, a null |
| character (zero byte) is written at the end of the buffer if it |
| fits. You should add an extra byte to the SIZE argument to |
| account for this. Attempts to write more than SIZE bytes to the |
| buffer result in an error. |
| |
| For a stream open for reading, null characters (zero bytes) in the |
| buffer do not count as "end of file". Read operations indicate |
| end of file only when the file position advances past SIZE bytes. |
| So, if you want to read characters from a null-terminated string, |
| you should supply the length of the string as the SIZE argument. |
| |
| Here is an example of using `fmemopen' to create a stream for |
| reading from a string: |
| |
| |
| #include <stdio.h> |
| |
| static char buffer[] = "foobar"; |
| |
| int |
| main (void) |
| { |
| int ch; |
| FILE *stream; |
| |
| stream = fmemopen (buffer, strlen (buffer), "r"); |
| while ((ch = fgetc (stream)) != EOF) |
| printf ("Got %c\n", ch); |
| fclose (stream); |
| |
| return 0; |
| } |
| |
| This program produces the following output: |
| |
| Got f |
| Got o |
| Got o |
| Got b |
| Got a |
| Got r |
| |
| -- Function: FILE * open_memstream (char **PTR, size_t *SIZELOC) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note |
| POSIX Safety Concepts::. |
| |
| This function opens a stream for writing to a buffer. The buffer |
| is allocated dynamically and grown as necessary, using `malloc'. |
| After you've closed the stream, this buffer is your responsibility |
| to clean up using `free' or `realloc'. *Note Unconstrained |
| Allocation::. |
| |
| When the stream is closed with `fclose' or flushed with `fflush', |
| the locations PTR and SIZELOC are updated to contain the pointer |
| to the buffer and its size. The values thus stored remain valid |
| only as long as no further output on the stream takes place. If |
| you do more output, you must flush the stream again to store new |
| values before you use them again. |
| |
| A null character is written at the end of the buffer. This null |
| character is _not_ included in the size value stored at SIZELOC. |
| |
| You can move the stream's file position with `fseek' or `fseeko' |
| (*note File Positioning::). Moving the file position past the end |
| of the data already written fills the intervening space with |
| zeroes. |
| |
| Here is an example of using `open_memstream': |
| |
| |
| #include <stdio.h> |
| |
| int |
| main (void) |
| { |
| char *bp; |
| size_t size; |
| FILE *stream; |
| |
| stream = open_memstream (&bp, &size); |
| fprintf (stream, "hello"); |
| fflush (stream); |
| printf ("buf = `%s', size = %zu\n", bp, size); |
| fprintf (stream, ", world"); |
| fclose (stream); |
| printf ("buf = `%s', size = %zu\n", bp, size); |
| |
| return 0; |
| } |
| |
| This program produces the following output: |
| |
| buf = `hello', size = 5 |
| buf = `hello, world', size = 12 |
| |
| |
| File: libc.info, Node: Custom Streams, Prev: String Streams, Up: Other Kinds of Streams |
| |
| 12.21.2 Programming Your Own Custom Streams |
| ------------------------------------------- |
| |
| This section describes how you can make a stream that gets input from an |
| arbitrary data source or writes output to an arbitrary data sink |
| programmed by you. We call these "custom streams". The functions and |
| types described here are all GNU extensions. |
| |
| * Menu: |
| |
| * Streams and Cookies:: The "cookie" records where to fetch or |
| store data that is read or written. |
| * Hook Functions:: How you should define the four "hook |
| functions" that a custom stream needs. |
| |
| |
| File: libc.info, Node: Streams and Cookies, Next: Hook Functions, Up: Custom Streams |
| |
| 12.21.2.1 Custom Streams and Cookies |
| .................................... |
| |
| Inside every custom stream is a special object called the "cookie". |
| This is an object supplied by you which records where to fetch or store |
| the data read or written. It is up to you to define a data type to use |
| for the cookie. The stream functions in the library never refer |
| directly to its contents, and they don't even know what the type is; |
| they record its address with type `void *'. |
| |
| To implement a custom stream, you must specify _how_ to fetch or |
| store the data in the specified place. You do this by defining "hook |
| functions" to read, write, change "file position", and close the |
| stream. All four of these functions will be passed the stream's cookie |
| so they can tell where to fetch or store the data. The library |
| functions don't know what's inside the cookie, but your functions will |
| know. |
| |
| When you create a custom stream, you must specify the cookie pointer, |
| and also the four hook functions stored in a structure of type |
| `cookie_io_functions_t'. |
| |
| These facilities are declared in `stdio.h'. |
| |
| -- Data Type: cookie_io_functions_t |
| This is a structure type that holds the functions that define the |
| communications protocol between the stream and its cookie. It has |
| the following members: |
| |
| `cookie_read_function_t *read' |
| This is the function that reads data from the cookie. If the |
| value is a null pointer instead of a function, then read |
| operations on this stream always return `EOF'. |
| |
| `cookie_write_function_t *write' |
| This is the function that writes data to the cookie. If the |
| value is a null pointer instead of a function, then data |
| written to the stream is discarded. |
| |
| `cookie_seek_function_t *seek' |
| This is the function that performs the equivalent of file |
| positioning on the cookie. If the value is a null pointer |
| instead of a function, calls to `fseek' or `fseeko' on this |
| stream can only seek to locations within the buffer; any |
| attempt to seek outside the buffer will return an `ESPIPE' |
| error. |
| |
| `cookie_close_function_t *close' |
| This function performs any appropriate cleanup on the cookie |
| when closing the stream. If the value is a null pointer |
| instead of a function, nothing special is done to close the |
| cookie when the stream is closed. |
| |
| -- Function: FILE * fopencookie (void *COOKIE, const char *OPENTYPE, |
| cookie_io_functions_t IO-FUNCTIONS) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
| | *Note POSIX Safety Concepts::. |
| |
| This function actually creates the stream for communicating with |
| the COOKIE using the functions in the IO-FUNCTIONS argument. The |
| OPENTYPE argument is interpreted as for `fopen'; see *note Opening |
| Streams::. (But note that the "truncate on open" option is |
| ignored.) The new stream is fully buffered. |
| |
| The `fopencookie' function returns the newly created stream, or a |
| null pointer in case of an error. |
| |
| |
| File: libc.info, Node: Hook Functions, Prev: Streams and Cookies, Up: Custom Streams |
| |
| 12.21.2.2 Custom Stream Hook Functions |
| ...................................... |
| |
| Here are more details on how you should define the four hook functions |
| that a custom stream needs. |
| |
| You should define the function to read data from the cookie as: |
| |
| ssize_t READER (void *COOKIE, char *BUFFER, size_t SIZE) |
| |
| This is very similar to the `read' function; see *note I/O |
| Primitives::. Your function should transfer up to SIZE bytes into the |
| BUFFER, and return the number of bytes read, or zero to indicate |
| end-of-file. You can return a value of `-1' to indicate an error. |
| |
| You should define the function to write data to the cookie as: |
| |
| ssize_t WRITER (void *COOKIE, const char *BUFFER, size_t SIZE) |
| |
| This is very similar to the `write' function; see *note I/O |
| Primitives::. Your function should transfer up to SIZE bytes from the |
| buffer, and return the number of bytes written. You can return a value |
| of `0' to indicate an error. You must not return any negative value. |
| |
| You should define the function to perform seek operations on the |
| cookie as: |
| |
| int SEEKER (void *COOKIE, off64_t *POSITION, int WHENCE) |
| |
| For this function, the POSITION and WHENCE arguments are interpreted |
| as for `fgetpos'; see *note Portable Positioning::. |
| |
| After doing the seek operation, your function should store the |
| resulting file position relative to the beginning of the file in |
| POSITION. Your function should return a value of `0' on success and |
| `-1' to indicate an error. |
| |
| You should define the function to do cleanup operations on the cookie |
| appropriate for closing the stream as: |
| |
| int CLEANER (void *COOKIE) |
| |
| Your function should return `-1' to indicate an error, and `0' |
| otherwise. |
| |
| -- Data Type: cookie_read_function_t |
| This is the data type that the read function for a custom stream |
| should have. If you declare the function as shown above, this is |
| the type it will have. |
| |
| -- Data Type: cookie_write_function_t |
| The data type of the write function for a custom stream. |
| |
| -- Data Type: cookie_seek_function_t |
| The data type of the seek function for a custom stream. |
| |
| -- Data Type: cookie_close_function_t |
| The data type of the close function for a custom stream. |
| |
| |
| File: libc.info, Node: Formatted Messages, Prev: Other Kinds of Streams, Up: I/O on Streams |
| |
| 12.22 Formatted Messages |
| ======================== |
| |
| On systems which are based on System V messages of programs (especially |
| the system tools) are printed in a strict form using the `fmtmsg' |
| function. The uniformity sometimes helps the user to interpret messages |
| and the strictness tests of the `fmtmsg' function ensure that the |
| programmer follows some minimal requirements. |
| |
| * Menu: |
| |
| * Printing Formatted Messages:: The `fmtmsg' function. |
| * Adding Severity Classes:: Add more severity classes. |
| * Example:: How to use `fmtmsg' and `addseverity'. |
| |
| |
| File: libc.info, Node: Printing Formatted Messages, Next: Adding Severity Classes, Up: Formatted Messages |
| |
| 12.22.1 Printing Formatted Messages |
| ----------------------------------- |
| |
| Messages can be printed to standard error and/or to the console. To |
| select the destination the programmer can use the following two values, |
| bitwise OR combined if wanted, for the CLASSIFICATION parameter of |
| `fmtmsg': |
| |
| `MM_PRINT' |
| Display the message in standard error. |
| |
| `MM_CONSOLE' |
| Display the message on the system console. |
| |
| The erroneous piece of the system can be signalled by exactly one of |
| the following values which also is bitwise ORed with the CLASSIFICATION |
| parameter to `fmtmsg': |
| |
| `MM_HARD' |
| The source of the condition is some hardware. |
| |
| `MM_SOFT' |
| The source of the condition is some software. |
| |
| `MM_FIRM' |
| The source of the condition is some firmware. |
| |
| A third component of the CLASSIFICATION parameter to `fmtmsg' can |
| describe the part of the system which detects the problem. This is |
| done by using exactly one of the following values: |
| |
| `MM_APPL' |
| The erroneous condition is detected by the application. |
| |
| `MM_UTIL' |
| The erroneous condition is detected by a utility. |
| |
| `MM_OPSYS' |
| The erroneous condition is detected by the operating system. |
| |
| A last component of CLASSIFICATION can signal the results of this |
| message. Exactly one of the following values can be used: |
| |
| `MM_RECOVER' |
| It is a recoverable error. |
| |
| `MM_NRECOV' |
| It is a non-recoverable error. |
| |
| -- Function: int fmtmsg (long int CLASSIFICATION, const char *LABEL, |
| int SEVERITY, const char *TEXT, const char *ACTION, const |
| char *TAG) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| Display a message described by its parameters on the device(s) |
| specified in the CLASSIFICATION parameter. The LABEL parameter |
| identifies the source of the message. The string should consist |
| of two colon separated parts where the first part has not more |
| than 10 and the second part not more than 14 characters. The TEXT |
| parameter describes the condition of the error, the ACTION |
| parameter possible steps to recover from the error and the TAG |
| parameter is a reference to the online documentation where more |
| information can be found. It should contain the LABEL value and a |
| unique identification number. |
| |
| Each of the parameters can be a special value which means this |
| value is to be omitted. The symbolic names for these values are: |
| |
| `MM_NULLLBL' |
| Ignore LABEL parameter. |
| |
| `MM_NULLSEV' |
| Ignore SEVERITY parameter. |
| |
| `MM_NULLMC' |
| Ignore CLASSIFICATION parameter. This implies that nothing is |
| actually printed. |
| |
| `MM_NULLTXT' |
| Ignore TEXT parameter. |
| |
| `MM_NULLACT' |
| Ignore ACTION parameter. |
| |
| `MM_NULLTAG' |
| Ignore TAG parameter. |
| |
| There is another way certain fields can be omitted from the output |
| to standard error. This is described below in the description of |
| environment variables influencing the behavior. |
| |
| The SEVERITY parameter can have one of the values in the following |
| table: |
| |
| `MM_NOSEV' |
| Nothing is printed, this value is the same as `MM_NULLSEV'. |
| |
| `MM_HALT' |
| This value is printed as `HALT'. |
| |
| `MM_ERROR' |
| This value is printed as `ERROR'. |
| |
| `MM_WARNING' |
| This value is printed as `WARNING'. |
| |
| `MM_INFO' |
| This value is printed as `INFO'. |
| |
| The numeric value of these five macros are between `0' and `4'. |
| Using the environment variable `SEV_LEVEL' or using the |
| `addseverity' function one can add more severity levels with their |
| corresponding string to print. This is described below (*note |
| Adding Severity Classes::). |
| |
| If no parameter is ignored the output looks like this: |
| |
| LABEL: SEVERITY-STRING: TEXT |
| TO FIX: ACTION TAG |
| |
| The colons, new line characters and the `TO FIX' string are |
| inserted if necessary, i.e., if the corresponding parameter is not |
| ignored. |
| |
| This function is specified in the X/Open Portability Guide. It is |
| also available on all systems derived from System V. |
| |
| The function returns the value `MM_OK' if no error occurred. If |
| only the printing to standard error failed, it returns `MM_NOMSG'. |
| If printing to the console fails, it returns `MM_NOCON'. If |
| nothing is printed `MM_NOTOK' is returned. Among situations where |
| all outputs fail this last value is also returned if a parameter |
| value is incorrect. |
| |
| There are two environment variables which influence the behavior of |
| `fmtmsg'. The first is `MSGVERB'. It is used to control the output |
| actually happening on standard error (_not_ the console output). Each |
| of the five fields can explicitly be enabled. To do this the user has |
| to put the `MSGVERB' variable with a format like the following in the |
| environment before calling the `fmtmsg' function the first time: |
| |
| MSGVERB=KEYWORD[:KEYWORD[:...]] |
| |
| Valid KEYWORDs are `label', `severity', `text', `action', and `tag'. |
| If the environment variable is not given or is the empty string, a not |
| supported keyword is given or the value is somehow else invalid, no |
| part of the message is masked out. |
| |
| The second environment variable which influences the behavior of |
| `fmtmsg' is `SEV_LEVEL'. This variable and the change in the behavior |
| of `fmtmsg' is not specified in the X/Open Portability Guide. It is |
| available in System V systems, though. It can be used to introduce new |
| severity levels. By default, only the five severity levels described |
| above are available. Any other numeric value would make `fmtmsg' print |
| nothing. |
| |
| If the user puts `SEV_LEVEL' with a format like |
| |
| SEV_LEVEL=[DESCRIPTION[:DESCRIPTION[:...]]] |
| |
| in the environment of the process before the first call to `fmtmsg', |
| where DESCRIPTION has a value of the form |
| |
| SEVERITY-KEYWORD,LEVEL,PRINTSTRING |
| |
| The SEVERITY-KEYWORD part is not used by `fmtmsg' but it has to be |
| present. The LEVEL part is a string representation of a number. The |
| numeric value must be a number greater than 4. This value must be used |
| in the SEVERITY parameter of `fmtmsg' to select this class. It is not |
| possible to overwrite any of the predefined classes. The PRINTSTRING |
| is the string printed when a message of this class is processed by |
| `fmtmsg' (see above, `fmtsmg' does not print the numeric value but |
| instead the string representation). |
| |
| |
| File: libc.info, Node: Adding Severity Classes, Next: Example, Prev: Printing Formatted Messages, Up: Formatted Messages |
| |
| 12.22.2 Adding Severity Classes |
| ------------------------------- |
| |
| There is another possibility to introduce severity classes besides using |
| the environment variable `SEV_LEVEL'. This simplifies the task of |
| introducing new classes in a running program. One could use the |
| `setenv' or `putenv' function to set the environment variable, but this |
| is toilsome. |
| |
| -- Function: int addseverity (int SEVERITY, const char *STRING) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function allows the introduction of new severity classes |
| which can be addressed by the SEVERITY parameter of the `fmtmsg' |
| function. The SEVERITY parameter of `addseverity' must match the |
| value for the parameter with the same name of `fmtmsg', and STRING |
| is the string printed in the actual messages instead of the numeric |
| value. |
| |
| If STRING is `NULL' the severity class with the numeric value |
| according to SEVERITY is removed. |
| |
| It is not possible to overwrite or remove one of the default |
| severity classes. All calls to `addseverity' with SEVERITY set to |
| one of the values for the default classes will fail. |
| |
| The return value is `MM_OK' if the task was successfully performed. |
| If the return value is `MM_NOTOK' something went wrong. This could |
| mean that no more memory is available or a class is not available |
| when it has to be removed. |
| |
| This function is not specified in the X/Open Portability Guide |
| although the `fmtsmg' function is. It is available on System V |
| systems. |
| |
| |
| File: libc.info, Node: Example, Prev: Adding Severity Classes, Up: Formatted Messages |
| |
| 12.22.3 How to use `fmtmsg' and `addseverity' |
| --------------------------------------------- |
| |
| Here is a simple example program to illustrate the use of both |
| functions described in this section. |
| |
| |
| #include <fmtmsg.h> |
| |
| int |
| main (void) |
| { |
| addseverity (5, "NOTE2"); |
| fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2"); |
| fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual", |
| "UX:cat:001"); |
| fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag"); |
| return 0; |
| } |
| |
| The second call to `fmtmsg' illustrates a use of this function as it |
| usually occurs on System V systems, which heavily use this function. |
| It seems worthwhile to give a short explanation here of how this system |
| works on System V. The value of the LABEL field (`UX:cat') says that |
| the error occurred in the Unix program `cat'. The explanation of the |
| error follows and the value for the ACTION parameter is `"refer to |
| manual"'. One could be more specific here, if necessary. The TAG |
| field contains, as proposed above, the value of the string given for |
| the LABEL parameter, and additionally a unique ID (`001' in this case). |
| For a GNU environment this string could contain a reference to the |
| corresponding node in the Info page for the program. |
| |
| Running this program without specifying the `MSGVERB' and `SEV_LEVEL' |
| function produces the following output: |
| |
| UX:cat: NOTE2: invalid syntax |
| TO FIX: refer to manual UX:cat:001 |
| |
| We see the different fields of the message and how the extra glue |
| (the colons and the `TO FIX' string) is printed. But only one of the |
| three calls to `fmtmsg' produced output. The first call does not print |
| anything because the LABEL parameter is not in the correct form. The |
| string must contain two fields, separated by a colon (*note Printing |
| Formatted Messages::). The third `fmtmsg' call produced no output |
| since the class with the numeric value `6' is not defined. Although a |
| class with numeric value `5' is also not defined by default, the call |
| to `addseverity' introduces it and the second call to `fmtmsg' produces |
| the above output. |
| |
| When we change the environment of the program to contain |
| `SEV_LEVEL=XXX,6,NOTE' when running it we get a different result: |
| |
| UX:cat: NOTE2: invalid syntax |
| TO FIX: refer to manual UX:cat:001 |
| label:foo: NOTE: text |
| TO FIX: action tag |
| |
| Now the third call to `fmtmsg' produced some output and we see how |
| the string `NOTE' from the environment variable appears in the message. |
| |
| Now we can reduce the output by specifying which fields we are |
| interested in. If we additionally set the environment variable |
| `MSGVERB' to the value `severity:label:action' we get the following |
| output: |
| |
| UX:cat: NOTE2 |
| TO FIX: refer to manual |
| label:foo: NOTE |
| TO FIX: action |
| |
| I.e., the output produced by the TEXT and the TAG parameters to |
| `fmtmsg' vanished. Please also note that now there is no colon after |
| the `NOTE' and `NOTE2' strings in the output. This is not necessary |
| since there is no more output on this line because the text is missing. |
| |
| |
| File: libc.info, Node: Low-Level I/O, Next: File System Interface, Prev: I/O on Streams, Up: Top |
| |
| 13 Low-Level Input/Output |
| ************************* |
| |
| This chapter describes functions for performing low-level input/output |
| operations on file descriptors. These functions include the primitives |
| for the higher-level I/O functions described in *note I/O on Streams::, |
| as well as functions for performing low-level control operations for |
| which there are no equivalents on streams. |
| |
| Stream-level I/O is more flexible and usually more convenient; |
| therefore, programmers generally use the descriptor-level functions only |
| when necessary. These are some of the usual reasons: |
| |
| * For reading binary files in large chunks. |
| |
| * For reading an entire file into core before parsing it. |
| |
| * To perform operations other than data transfer, which can only be |
| done with a descriptor. (You can use `fileno' to get the |
| descriptor corresponding to a stream.) |
| |
| * To pass descriptors to a child process. (The child can create its |
| own stream to use a descriptor that it inherits, but cannot |
| inherit a stream directly.) |
| |
| * Menu: |
| |
| * Opening and Closing Files:: How to open and close file |
| descriptors. |
| * I/O Primitives:: Reading and writing data. |
| * File Position Primitive:: Setting a descriptor's file |
| position. |
| * Descriptors and Streams:: Converting descriptor to stream |
| or vice-versa. |
| * Stream/Descriptor Precautions:: Precautions needed if you use both |
| descriptors and streams. |
| * Scatter-Gather:: Fast I/O to discontinuous buffers. |
| * Copying File Data:: Copying data between files. |
| * Memory-mapped I/O:: Using files like memory. |
| * Waiting for I/O:: How to check for input or output |
| on multiple file descriptors. |
| * Synchronizing I/O:: Making sure all I/O actions completed. |
| * Asynchronous I/O:: Perform I/O in parallel. |
| * Control Operations:: Various other operations on file |
| descriptors. |
| * Duplicating Descriptors:: Fcntl commands for duplicating |
| file descriptors. |
| * Descriptor Flags:: Fcntl commands for manipulating |
| flags associated with file |
| descriptors. |
| * File Status Flags:: Fcntl commands for manipulating |
| flags associated with open files. |
| * File Locks:: Fcntl commands for implementing |
| file locking. |
| * Open File Description Locks:: Fcntl commands for implementing |
| open file description locking. |
| * Open File Description Locks Example:: An example of open file description lock |
| usage |
| * Interrupt Input:: Getting an asynchronous signal when |
| input arrives. |
| * IOCTLs:: Generic I/O Control operations. |
| |
| |
| File: libc.info, Node: Opening and Closing Files, Next: I/O Primitives, Up: Low-Level I/O |
| |
| 13.1 Opening and Closing Files |
| ============================== |
| |
| This section describes the primitives for opening and closing files |
| using file descriptors. The `open' and `creat' functions are declared |
| in the header file `fcntl.h', while `close' is declared in `unistd.h'. |
| |
| -- Function: int open (const char *FILENAME, int FLAGS[, mode_t MODE]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The `open' function creates and returns a new file descriptor for |
| the file named by FILENAME. Initially, the file position |
| indicator for the file is at the beginning of the file. The |
| argument MODE (*note Permission Bits::) is used only when a file is |
| created, but it doesn't hurt to supply the argument in any case. |
| |
| The FLAGS argument controls how the file is to be opened. This is |
| a bit mask; you create the value by the bitwise OR of the |
| appropriate parameters (using the `|' operator in C). *Note File |
| Status Flags::, for the parameters available. |
| |
| The normal return value from `open' is a non-negative integer file |
| descriptor. In the case of an error, a value of -1 is returned |
| instead. In addition to the usual file name errors (*note File |
| Name Errors::), the following `errno' error conditions are defined |
| for this function: |
| |
| `EACCES' |
| The file exists but is not readable/writable as requested by |
| the FLAGS argument, or the file does not exist and the |
| directory is unwritable so it cannot be created. |
| |
| `EEXIST' |
| Both `O_CREAT' and `O_EXCL' are set, and the named file |
| already exists. |
| |
| `EINTR' |
| The `open' operation was interrupted by a signal. *Note |
| Interrupted Primitives::. |
| |
| `EISDIR' |
| The FLAGS argument specified write access, and the file is a |
| directory. |
| |
| `EMFILE' |
| The process has too many files open. The maximum number of |
| file descriptors is controlled by the `RLIMIT_NOFILE' |
| resource limit; *note Limits on Resources::. |
| |
| `ENFILE' |
| The entire system, or perhaps the file system which contains |
| the directory, cannot support any additional open files at |
| the moment. (This problem cannot happen on GNU/Hurd systems.) |
| |
| `ENOENT' |
| The named file does not exist, and `O_CREAT' is not specified. |
| |
| `ENOSPC' |
| The directory or file system that would contain the new file |
| cannot be extended, because there is no disk space left. |
| |
| `ENXIO' |
| `O_NONBLOCK' and `O_WRONLY' are both set in the FLAGS |
| argument, the file named by FILENAME is a FIFO (*note Pipes |
| and FIFOs::), and no process has the file open for reading. |
| |
| `EROFS' |
| The file resides on a read-only file system and any of |
| `O_WRONLY', `O_RDWR', and `O_TRUNC' are set in the FLAGS |
| argument, or `O_CREAT' is set and the file does not already |
| exist. |
| |
| If on a 32 bit machine the sources are translated with |
| `_FILE_OFFSET_BITS == 64' the function `open' returns a file |
| descriptor opened in the large file mode which enables the file |
| handling functions to use files up to 2^63 bytes in size and |
| offset from -2^63 to 2^63. This happens transparently for the user |
| since all of the low-level file handling functions are equally |
| replaced. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| `open' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this calls to |
| `open' should be protected using cancellation handlers. |
| |
| The `open' function is the underlying primitive for the `fopen' |
| and `freopen' functions, that create streams. |
| |
| -- Function: int open64 (const char *FILENAME, int FLAGS[, mode_t |
| MODE]) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `open'. It returns a file descriptor |
| which can be used to access the file named by FILENAME. The only |
| difference is that on 32 bit systems the file is opened in the |
| large file mode. I.e., file length and file offsets can exceed 31 |
| bits. |
| |
| When the sources are translated with `_FILE_OFFSET_BITS == 64' this |
| function is actually available under the name `open'. I.e., the |
| new, extended API using 64 bit file sizes and offsets transparently |
| replaces the old API. |
| |
| -- Obsolete function: int creat (const char *FILENAME, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is obsolete. The call: |
| |
| creat (FILENAME, MODE) |
| |
| is equivalent to: |
| |
| open (FILENAME, O_WRONLY | O_CREAT | O_TRUNC, MODE) |
| |
| If on a 32 bit machine the sources are translated with |
| `_FILE_OFFSET_BITS == 64' the function `creat' returns a file |
| descriptor opened in the large file mode which enables the file |
| handling functions to use files up to 2^63 in size and offset from |
| -2^63 to 2^63. This happens transparently for the user since all |
| of the low-level file handling functions are equally replaced. |
| |
| -- Obsolete function: int creat64 (const char *FILENAME, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `creat'. It returns a file descriptor |
| which can be used to access the file named by FILENAME. The only |
| difference is that on 32 bit systems the file is opened in the |
| large file mode. I.e., file length and file offsets can exceed 31 |
| bits. |
| |
| To use this file descriptor one must not use the normal operations |
| but instead the counterparts named `*64', e.g., `read64'. |
| |
| When the sources are translated with `_FILE_OFFSET_BITS == 64' this |
| function is actually available under the name `open'. I.e., the |
| new, extended API using 64 bit file sizes and offsets transparently |
| replaces the old API. |
| |
| -- Function: int close (int FILEDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The function `close' closes the file descriptor FILEDES. Closing |
| a file has the following consequences: |
| |
| * The file descriptor is deallocated. |
| |
| * Any record locks owned by the process on the file are |
| unlocked. |
| |
| * When all file descriptors associated with a pipe or FIFO have |
| been closed, any unread data is discarded. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| `close' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this, calls to |
| `close' should be protected using cancellation handlers. |
| |
| The normal return value from `close' is 0; a value of -1 is |
| returned in case of failure. The following `errno' error |
| conditions are defined for this function: |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor. |
| |
| `EINTR' |
| The `close' call was interrupted by a signal. *Note |
| Interrupted Primitives::. Here is an example of how to |
| handle `EINTR' properly: |
| |
| TEMP_FAILURE_RETRY (close (desc)); |
| |
| `ENOSPC' |
| `EIO' |
| `EDQUOT' |
| When the file is accessed by NFS, these errors from `write' |
| can sometimes not be detected until `close'. *Note I/O |
| Primitives::, for details on their meaning. |
| |
| Please note that there is _no_ separate `close64' function. This |
| is not necessary since this function does not determine nor depend |
| on the mode of the file. The kernel which performs the `close' |
| operation knows which mode the descriptor is used for and can |
| handle this situation. |
| |
| To close a stream, call `fclose' (*note Closing Streams::) instead |
| of trying to close its underlying file descriptor with `close'. This |
| flushes any buffered output and updates the stream object to indicate |
| that it is closed. |
| |
| |
| File: libc.info, Node: I/O Primitives, Next: File Position Primitive, Prev: Opening and Closing Files, Up: Low-Level I/O |
| |
| 13.2 Input and Output Primitives |
| ================================ |
| |
| This section describes the functions for performing primitive input and |
| output operations on file descriptors: `read', `write', and `lseek'. |
| These functions are declared in the header file `unistd.h'. |
| |
| -- Data Type: ssize_t |
| This data type is used to represent the sizes of blocks that can be |
| read or written in a single operation. It is similar to `size_t', |
| but must be a signed type. |
| |
| -- Function: ssize_t read (int FILEDES, void *BUFFER, size_t SIZE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `read' function reads up to SIZE bytes from the file with |
| descriptor FILEDES, storing the results in the BUFFER. (This is |
| not necessarily a character string, and no terminating null |
| character is added.) |
| |
| The return value is the number of bytes actually read. This might |
| be less than SIZE; for example, if there aren't that many bytes |
| left in the file or if there aren't that many bytes immediately |
| available. The exact behavior depends on what kind of file it is. |
| Note that reading less than SIZE bytes is not an error. |
| |
| A value of zero indicates end-of-file (except if the value of the |
| SIZE argument is also zero). This is not considered an error. If |
| you keep calling `read' while at end-of-file, it will keep |
| returning zero and doing nothing else. |
| |
| If `read' returns at least one character, there is no way you can |
| tell whether end-of-file was reached. But if you did reach the |
| end, the next read will return zero. |
| |
| In case of an error, `read' returns -1. The following `errno' |
| error conditions are defined for this function: |
| |
| `EAGAIN' |
| Normally, when no input is immediately available, `read' |
| waits for some input. But if the `O_NONBLOCK' flag is set |
| for the file (*note File Status Flags::), `read' returns |
| immediately without reading any data, and reports this error. |
| |
| *Compatibility Note:* Most versions of BSD Unix use a |
| different error code for this: `EWOULDBLOCK'. In the GNU C |
| Library, `EWOULDBLOCK' is an alias for `EAGAIN', so it |
| doesn't matter which name you use. |
| |
| On some systems, reading a large amount of data from a |
| character special file can also fail with `EAGAIN' if the |
| kernel cannot find enough physical memory to lock down the |
| user's pages. This is limited to devices that transfer with |
| direct memory access into the user's memory, which means it |
| does not include terminals, since they always use separate |
| buffers inside the kernel. This problem never happens on |
| GNU/Hurd systems. |
| |
| Any condition that could result in `EAGAIN' can instead |
| result in a successful `read' which returns fewer bytes than |
| requested. Calling `read' again immediately would result in |
| `EAGAIN'. |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor, or is |
| not open for reading. |
| |
| `EINTR' |
| `read' was interrupted by a signal while it was waiting for |
| input. *Note Interrupted Primitives::. A signal will not |
| necessarily cause `read' to return `EINTR'; it may instead |
| result in a successful `read' which returns fewer bytes than |
| requested. |
| |
| `EIO' |
| For many devices, and for disk files, this error code |
| indicates a hardware error. |
| |
| `EIO' also occurs when a background process tries to read |
| from the controlling terminal, and the normal action of |
| stopping the process by sending it a `SIGTTIN' signal isn't |
| working. This might happen if the signal is being blocked or |
| ignored, or because the process group is orphaned. *Note Job |
| Control::, for more information about job control, and *note |
| Signal Handling::, for information about signals. |
| |
| `EINVAL' |
| In some systems, when reading from a character or block |
| device, position and size offsets must be aligned to a |
| particular block size. This error indicates that the offsets |
| were not properly aligned. |
| |
| Please note that there is no function named `read64'. This is not |
| necessary since this function does not directly modify or handle |
| the possibly wide file offset. Since the kernel handles this state |
| internally, the `read' function can be used for all cases. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| `read' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this, calls to |
| `read' should be protected using cancellation handlers. |
| |
| The `read' function is the underlying primitive for all of the |
| functions that read from streams, such as `fgetc'. |
| |
| -- Function: ssize_t pread (int FILEDES, void *BUFFER, size_t SIZE, |
| off_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `pread' function is similar to the `read' function. The first |
| three arguments are identical, and the return values and error |
| codes also correspond. |
| |
| The difference is the fourth argument and its handling. The data |
| block is not read from the current position of the file descriptor |
| `filedes'. Instead the data is read from the file starting at |
| position OFFSET. The position of the file descriptor itself is |
| not affected by the operation. The value is the same as before |
| the call. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `pread' function is in fact `pread64' and the type `off_t' has 64 |
| bits, which makes it possible to handle files up to 2^63 bytes in |
| length. |
| |
| The return value of `pread' describes the number of bytes read. |
| In the error case it returns -1 like `read' does and the error |
| codes are also the same, with these additions: |
| |
| `EINVAL' |
| The value given for OFFSET is negative and therefore illegal. |
| |
| `ESPIPE' |
| The file descriptor FILEDES is associated with a pipe or a |
| FIFO and this device does not allow positioning of the file |
| pointer. |
| |
| The function is an extension defined in the Unix Single |
| Specification version 2. |
| |
| -- Function: ssize_t pread64 (int FILEDES, void *BUFFER, size_t SIZE, |
| off64_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `pread' function. The difference |
| is that the OFFSET parameter is of type `off64_t' instead of |
| `off_t' which makes it possible on 32 bit machines to address |
| files larger than 2^31 bytes and up to 2^63 bytes. The file |
| descriptor `filedes' must be opened using `open64' since otherwise |
| the large offsets possible with `off64_t' will lead to errors with |
| a descriptor in small file mode. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' on |
| a 32 bit machine this function is actually available under the name |
| `pread' and so transparently replaces the 32 bit interface. |
| |
| -- Function: ssize_t write (int FILEDES, const void *BUFFER, size_t |
| SIZE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `write' function writes up to SIZE bytes from BUFFER to the |
| file with descriptor FILEDES. The data in BUFFER is not |
| necessarily a character string and a null character is output like |
| any other character. |
| |
| The return value is the number of bytes actually written. This |
| may be SIZE, but can always be smaller. Your program should |
| always call `write' in a loop, iterating until all the data is |
| written. |
| |
| Once `write' returns, the data is enqueued to be written and can be |
| read back right away, but it is not necessarily written out to |
| permanent storage immediately. You can use `fsync' when you need |
| to be sure your data has been permanently stored before |
| continuing. (It is more efficient for the system to batch up |
| consecutive writes and do them all at once when convenient. |
| Normally they will always be written to disk within a minute or |
| less.) Modern systems provide another function `fdatasync' which |
| guarantees integrity only for the file data and is therefore |
| faster. You can use the `O_FSYNC' open mode to make `write' always |
| store the data to disk before returning; *note Operating Modes::. |
| |
| In the case of an error, `write' returns -1. The following |
| `errno' error conditions are defined for this function: |
| |
| `EAGAIN' |
| Normally, `write' blocks until the write operation is |
| complete. But if the `O_NONBLOCK' flag is set for the file |
| (*note Control Operations::), it returns immediately without |
| writing any data and reports this error. An example of a |
| situation that might cause the process to block on output is |
| writing to a terminal device that supports flow control, |
| where output has been suspended by receipt of a STOP |
| character. |
| |
| *Compatibility Note:* Most versions of BSD Unix use a |
| different error code for this: `EWOULDBLOCK'. In the GNU C |
| Library, `EWOULDBLOCK' is an alias for `EAGAIN', so it |
| doesn't matter which name you use. |
| |
| On some systems, writing a large amount of data from a |
| character special file can also fail with `EAGAIN' if the |
| kernel cannot find enough physical memory to lock down the |
| user's pages. This is limited to devices that transfer with |
| direct memory access into the user's memory, which means it |
| does not include terminals, since they always use separate |
| buffers inside the kernel. This problem does not arise on |
| GNU/Hurd systems. |
| |
| `EBADF' |
| The FILEDES argument is not a valid file descriptor, or is |
| not open for writing. |
| |
| `EFBIG' |
| The size of the file would become larger than the |
| implementation can support. |
| |
| `EINTR' |
| The `write' operation was interrupted by a signal while it was |
| blocked waiting for completion. A signal will not |
| necessarily cause `write' to return `EINTR'; it may instead |
| result in a successful `write' which writes fewer bytes than |
| requested. *Note Interrupted Primitives::. |
| |
| `EIO' |
| For many devices, and for disk files, this error code |
| indicates a hardware error. |
| |
| `ENOSPC' |
| The device containing the file is full. |
| |
| `EPIPE' |
| This error is returned when you try to write to a pipe or |
| FIFO that isn't open for reading by any process. When this |
| happens, a `SIGPIPE' signal is also sent to the process; see |
| *note Signal Handling::. |
| |
| `EINVAL' |
| In some systems, when writing to a character or block device, |
| position and size offsets must be aligned to a particular |
| block size. This error indicates that the offsets were not |
| properly aligned. |
| |
| Unless you have arranged to prevent `EINTR' failures, you should |
| check `errno' after each failing call to `write', and if the error |
| was `EINTR', you should simply repeat the call. *Note Interrupted |
| Primitives::. The easy way to do this is with the macro |
| `TEMP_FAILURE_RETRY', as follows: |
| |
| nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count)); |
| |
| Please note that there is no function named `write64'. This is not |
| necessary since this function does not directly modify or handle |
| the possibly wide file offset. Since the kernel handles this state |
| internally the `write' function can be used for all cases. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| `write' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this, calls to |
| `write' should be protected using cancellation handlers. |
| |
| The `write' function is the underlying primitive for all of the |
| functions that write to streams, such as `fputc'. |
| |
| -- Function: ssize_t pwrite (int FILEDES, const void *BUFFER, size_t |
| SIZE, off_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `pwrite' function is similar to the `write' function. The |
| first three arguments are identical, and the return values and |
| error codes also correspond. |
| |
| The difference is the fourth argument and its handling. The data |
| block is not written to the current position of the file descriptor |
| `filedes'. Instead the data is written to the file starting at |
| position OFFSET. The position of the file descriptor itself is |
| not affected by the operation. The value is the same as before |
| the call. |
| |
| However, on Linux, if a file is opened with `O_APPEND', `pwrite' |
| appends data to the end of the file, regardless of the value of |
| `offset'. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `pwrite' function is in fact `pwrite64' and the type `off_t' has |
| 64 bits, which makes it possible to handle files up to 2^63 bytes |
| in length. |
| |
| The return value of `pwrite' describes the number of written bytes. |
| In the error case it returns -1 like `write' does and the error |
| codes are also the same, with these additions: |
| |
| `EINVAL' |
| The value given for OFFSET is negative and therefore illegal. |
| |
| `ESPIPE' |
| The file descriptor FILEDES is associated with a pipe or a |
| FIFO and this device does not allow positioning of the file |
| pointer. |
| |
| The function is an extension defined in the Unix Single |
| Specification version 2. |
| |
| -- Function: ssize_t pwrite64 (int FILEDES, const void *BUFFER, size_t |
| SIZE, off64_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `pwrite' function. The difference |
| is that the OFFSET parameter is of type `off64_t' instead of |
| `off_t' which makes it possible on 32 bit machines to address |
| files larger than 2^31 bytes and up to 2^63 bytes. The file |
| descriptor `filedes' must be opened using `open64' since otherwise |
| the large offsets possible with `off64_t' will lead to errors with |
| a descriptor in small file mode. |
| |
| When the source file is compiled using `_FILE_OFFSET_BITS == 64' |
| on a 32 bit machine this function is actually available under the |
| name `pwrite' and so transparently replaces the 32 bit interface. |
| |
| |
| File: libc.info, Node: File Position Primitive, Next: Descriptors and Streams, Prev: I/O Primitives, Up: Low-Level I/O |
| |
| 13.3 Setting the File Position of a Descriptor |
| ============================================== |
| |
| Just as you can set the file position of a stream with `fseek', you can |
| set the file position of a descriptor with `lseek'. This specifies the |
| position in the file for the next `read' or `write' operation. *Note |
| File Positioning::, for more information on the file position and what |
| it means. |
| |
| To read the current file position value from a descriptor, use |
| `lseek (DESC, 0, SEEK_CUR)'. |
| |
| -- Function: off_t lseek (int FILEDES, off_t OFFSET, int WHENCE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `lseek' function is used to change the file position of the |
| file with descriptor FILEDES. |
| |
| The WHENCE argument specifies how the OFFSET should be |
| interpreted, in the same way as for the `fseek' function, and it |
| must be one of the symbolic constants `SEEK_SET', `SEEK_CUR', or |
| `SEEK_END'. |
| |
| `SEEK_SET' |
| Specifies that OFFSET is a count of characters from the |
| beginning of the file. |
| |
| `SEEK_CUR' |
| Specifies that OFFSET is a count of characters from the |
| current file position. This count may be positive or |
| negative. |
| |
| `SEEK_END' |
| Specifies that OFFSET is a count of characters from the end of |
| the file. A negative count specifies a position within the |
| current extent of the file; a positive count specifies a |
| position past the current end. If you set the position past |
| the current end, and actually write data, you will extend the |
| file with zeros up to that position. |
| |
| The return value from `lseek' is normally the resulting file |
| position, measured in bytes from the beginning of the file. You |
| can use this feature together with `SEEK_CUR' to read the current |
| file position. |
| |
| If you want to append to the file, setting the file position to the |
| current end of file with `SEEK_END' is not sufficient. Another |
| process may write more data after you seek but before you write, |
| extending the file so the position you write onto clobbers their |
| data. Instead, use the `O_APPEND' operating mode; *note Operating |
| Modes::. |
| |
| You can set the file position past the current end of the file. |
| This does not by itself make the file longer; `lseek' never |
| changes the file. But subsequent output at that position will |
| extend the file. Characters between the previous end of file and |
| the new position are filled with zeros. Extending the file in |
| this way can create a "hole": the blocks of zeros are not actually |
| allocated on disk, so the file takes up less space than it appears |
| to; it is then called a "sparse file". |
| |
| If the file position cannot be changed, or the operation is in |
| some way invalid, `lseek' returns a value of -1. The following |
| `errno' error conditions are defined for this function: |
| |
| `EBADF' |
| The FILEDES is not a valid file descriptor. |
| |
| `EINVAL' |
| The WHENCE argument value is not valid, or the resulting file |
| offset is not valid. A file offset is invalid. |
| |
| `ESPIPE' |
| The FILEDES corresponds to an object that cannot be |
| positioned, such as a pipe, FIFO or terminal device. |
| (POSIX.1 specifies this error only for pipes and FIFOs, but |
| on GNU systems, you always get `ESPIPE' if the object is not |
| seekable.) |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `lseek' function is in fact `lseek64' and the type `off_t' has 64 |
| bits which makes it possible to handle files up to 2^63 bytes in |
| length. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| `lseek' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this calls to |
| `lseek' should be protected using cancellation handlers. |
| |
| The `lseek' function is the underlying primitive for the `fseek', |
| `fseeko', `ftell', `ftello' and `rewind' functions, which operate |
| on streams instead of file descriptors. |
| |
| -- Function: off64_t lseek64 (int FILEDES, off64_t OFFSET, int WHENCE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `lseek' function. The difference |
| is that the OFFSET parameter is of type `off64_t' instead of |
| `off_t' which makes it possible on 32 bit machines to address |
| files larger than 2^31 bytes and up to 2^63 bytes. The file |
| descriptor `filedes' must be opened using `open64' since otherwise |
| the large offsets possible with `off64_t' will lead to errors with |
| a descriptor in small file mode. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' on |
| a 32 bits machine this function is actually available under the |
| name `lseek' and so transparently replaces the 32 bit interface. |
| |
| You can have multiple descriptors for the same file if you open the |
| file more than once, or if you duplicate a descriptor with `dup'. |
| Descriptors that come from separate calls to `open' have independent |
| file positions; using `lseek' on one descriptor has no effect on the |
| other. For example, |
| |
| { |
| int d1, d2; |
| char buf[4]; |
| d1 = open ("foo", O_RDONLY); |
| d2 = open ("foo", O_RDONLY); |
| lseek (d1, 1024, SEEK_SET); |
| read (d2, buf, 4); |
| } |
| |
| will read the first four characters of the file `foo'. (The |
| error-checking code necessary for a real program has been omitted here |
| for brevity.) |
| |
| By contrast, descriptors made by duplication share a common file |
| position with the original descriptor that was duplicated. Anything |
| which alters the file position of one of the duplicates, including |
| reading or writing data, affects all of them alike. Thus, for example, |
| |
| { |
| int d1, d2, d3; |
| char buf1[4], buf2[4]; |
| d1 = open ("foo", O_RDONLY); |
| d2 = dup (d1); |
| d3 = dup (d2); |
| lseek (d3, 1024, SEEK_SET); |
| read (d1, buf1, 4); |
| read (d2, buf2, 4); |
| } |
| |
| will read four characters starting with the 1024'th character of `foo', |
| and then four more characters starting with the 1028'th character. |
| |
| -- Data Type: off_t |
| This is a signed integer type used to represent file sizes. In |
| the GNU C Library, this type is no narrower than `int'. |
| |
| If the source is compiled with `_FILE_OFFSET_BITS == 64' this type |
| is transparently replaced by `off64_t'. |
| |
| -- Data Type: off64_t |
| This type is used similar to `off_t'. The difference is that even |
| on 32 bit machines, where the `off_t' type would have 32 bits, |
| `off64_t' has 64 bits and so is able to address files up to 2^63 |
| bytes in length. |
| |
| When compiling with `_FILE_OFFSET_BITS == 64' this type is |
| available under the name `off_t'. |
| |
| These aliases for the `SEEK_...' constants exist for the sake of |
| compatibility with older BSD systems. They are defined in two |
| different header files: `fcntl.h' and `sys/file.h'. |
| |
| `L_SET' |
| An alias for `SEEK_SET'. |
| |
| `L_INCR' |
| An alias for `SEEK_CUR'. |
| |
| `L_XTND' |
| An alias for `SEEK_END'. |
| |
| |
| File: libc.info, Node: Descriptors and Streams, Next: Stream/Descriptor Precautions, Prev: File Position Primitive, Up: Low-Level I/O |
| |
| 13.4 Descriptors and Streams |
| ============================ |
| |
| Given an open file descriptor, you can create a stream for it with the |
| `fdopen' function. You can get the underlying file descriptor for an |
| existing stream with the `fileno' function. These functions are |
| declared in the header file `stdio.h'. |
| |
| -- Function: FILE * fdopen (int FILEDES, const char *OPENTYPE) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
| | *Note POSIX Safety Concepts::. |
| |
| The `fdopen' function returns a new stream for the file descriptor |
| FILEDES. |
| |
| The OPENTYPE argument is interpreted in the same way as for the |
| `fopen' function (*note Opening Streams::), except that the `b' |
| option is not permitted; this is because GNU systems make no |
| distinction between text and binary files. Also, `"w"' and `"w+"' |
| do not cause truncation of the file; these have an effect only |
| when opening a file, and in this case the file has already been |
| opened. You must make sure that the OPENTYPE argument matches the |
| actual mode of the open file descriptor. |
| |
| The return value is the new stream. If the stream cannot be |
| created (for example, if the modes for the file indicated by the |
| file descriptor do not permit the access specified by the OPENTYPE |
| argument), a null pointer is returned instead. |
| |
| In some other systems, `fdopen' may fail to detect that the modes |
| for file descriptors do not permit the access specified by |
| `opentype'. The GNU C Library always checks for this. |
| |
| For an example showing the use of the `fdopen' function, see *note |
| Creating a Pipe::. |
| |
| -- Function: int fileno (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the file descriptor associated with the |
| stream STREAM. If an error is detected (for example, if the STREAM |
| is not valid) or if STREAM does not do I/O to a file, `fileno' |
| returns -1. |
| |
| -- Function: int fileno_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `fileno_unlocked' function is equivalent to the `fileno' |
| function except that it does not implicitly lock the stream if the |
| state is `FSETLOCKING_INTERNAL'. |
| |
| This function is a GNU extension. |
| |
| There are also symbolic constants defined in `unistd.h' for the file |
| descriptors belonging to the standard streams `stdin', `stdout', and |
| `stderr'; see *note Standard Streams::. |
| |
| `STDIN_FILENO' |
| This macro has value `0', which is the file descriptor for |
| standard input. |
| |
| `STDOUT_FILENO' |
| This macro has value `1', which is the file descriptor for |
| standard output. |
| |
| `STDERR_FILENO' |
| This macro has value `2', which is the file descriptor for |
| standard error output. |
| |
| |
| File: libc.info, Node: Stream/Descriptor Precautions, Next: Scatter-Gather, Prev: Descriptors and Streams, Up: Low-Level I/O |
| |
| 13.5 Dangers of Mixing Streams and Descriptors |
| ============================================== |
| |
| You can have multiple file descriptors and streams (let's call both |
| streams and descriptors "channels" for short) connected to the same |
| file, but you must take care to avoid confusion between channels. There |
| are two cases to consider: "linked" channels that share a single file |
| position value, and "independent" channels that have their own file |
| positions. |
| |
| It's best to use just one channel in your program for actual data |
| transfer to any given file, except when all the access is for input. |
| For example, if you open a pipe (something you can only do at the file |
| descriptor level), either do all I/O with the descriptor, or construct a |
| stream from the descriptor with `fdopen' and then do all I/O with the |
| stream. |
| |
| * Menu: |
| |
| * Linked Channels:: Dealing with channels sharing a file position. |
| * Independent Channels:: Dealing with separately opened, unlinked channels. |
| * Cleaning Streams:: Cleaning a stream makes it safe to use |
| another channel. |
| |
| |
| File: libc.info, Node: Linked Channels, Next: Independent Channels, Up: Stream/Descriptor Precautions |
| |
| 13.5.1 Linked Channels |
| ---------------------- |
| |
| Channels that come from a single opening share the same file position; |
| we call them "linked" channels. Linked channels result when you make a |
| stream from a descriptor using `fdopen', when you get a descriptor from |
| a stream with `fileno', when you copy a descriptor with `dup' or |
| `dup2', and when descriptors are inherited during `fork'. For files |
| that don't support random access, such as terminals and pipes, _all_ |
| channels are effectively linked. On random-access files, all |
| append-type output streams are effectively linked to each other. |
| |
| If you have been using a stream for I/O (or have just opened the |
| stream), and you want to do I/O using another channel (either a stream |
| or a descriptor) that is linked to it, you must first "clean up" the |
| stream that you have been using. *Note Cleaning Streams::. |
| |
| Terminating a process, or executing a new program in the process, |
| destroys all the streams in the process. If descriptors linked to these |
| streams persist in other processes, their file positions become |
| undefined as a result. To prevent this, you must clean up the streams |
| before destroying them. |
| |
| |
| File: libc.info, Node: Independent Channels, Next: Cleaning Streams, Prev: Linked Channels, Up: Stream/Descriptor Precautions |
| |
| 13.5.2 Independent Channels |
| --------------------------- |
| |
| When you open channels (streams or descriptors) separately on a seekable |
| file, each channel has its own file position. These are called |
| "independent channels". |
| |
| The system handles each channel independently. Most of the time, |
| this is quite predictable and natural (especially for input): each |
| channel can read or write sequentially at its own place in the file. |
| However, if some of the channels are streams, you must take these |
| precautions: |
| |
| * You should clean an output stream after use, before doing anything |
| else that might read or write from the same part of the file. |
| |
| * You should clean an input stream before reading data that may have |
| been modified using an independent channel. Otherwise, you might |
| read obsolete data that had been in the stream's buffer. |
| |
| If you do output to one channel at the end of the file, this will |
| certainly leave the other independent channels positioned somewhere |
| before the new end. You cannot reliably set their file positions to the |
| new end of file before writing, because the file can always be extended |
| by another process between when you set the file position and when you |
| write the data. Instead, use an append-type descriptor or stream; they |
| always output at the current end of the file. In order to make the |
| end-of-file position accurate, you must clean the output channel you |
| were using, if it is a stream. |
| |
| It's impossible for two channels to have separate file pointers for a |
| file that doesn't support random access. Thus, channels for reading or |
| writing such files are always linked, never independent. Append-type |
| channels are also always linked. For these channels, follow the rules |
| for linked channels; see *note Linked Channels::. |
| |
| |
| File: libc.info, Node: Cleaning Streams, Prev: Independent Channels, Up: Stream/Descriptor Precautions |
| |
| 13.5.3 Cleaning Streams |
| ----------------------- |
| |
| You can use `fflush' to clean a stream in most cases. |
| |
| You can skip the `fflush' if you know the stream is already clean. |
| A stream is clean whenever its buffer is empty. For example, an |
| unbuffered stream is always clean. An input stream that is at |
| end-of-file is clean. A line-buffered stream is clean when the last |
| character output was a newline. However, a just-opened input stream |
| might not be clean, as its input buffer might not be empty. |
| |
| There is one case in which cleaning a stream is impossible on most |
| systems. This is when the stream is doing input from a file that is not |
| random-access. Such streams typically read ahead, and when the file is |
| not random access, there is no way to give back the excess data already |
| read. When an input stream reads from a random-access file, `fflush' |
| does clean the stream, but leaves the file pointer at an unpredictable |
| place; you must set the file pointer before doing any further I/O. |
| |
| Closing an output-only stream also does `fflush', so this is a valid |
| way of cleaning an output stream. |
| |
| You need not clean a stream before using its descriptor for control |
| operations such as setting terminal modes; these operations don't affect |
| the file position and are not affected by it. You can use any |
| descriptor for these operations, and all channels are affected |
| simultaneously. However, text already "output" to a stream but still |
| buffered by the stream will be subject to the new terminal modes when |
| subsequently flushed. To make sure "past" output is covered by the |
| terminal settings that were in effect at the time, flush the output |
| streams for that terminal before setting the modes. *Note Terminal |
| Modes::. |
| |
| |
| File: libc.info, Node: Scatter-Gather, Next: Copying File Data, Prev: Stream/Descriptor Precautions, Up: Low-Level I/O |
| |
| 13.6 Fast Scatter-Gather I/O |
| ============================ |
| |
| Some applications may need to read or write data to multiple buffers, |
| which are separated in memory. Although this can be done easily enough |
| with multiple calls to `read' and `write', it is inefficient because |
| there is overhead associated with each kernel call. |
| |
| Instead, many platforms provide special high-speed primitives to |
| perform these "scatter-gather" operations in a single kernel call. The |
| GNU C Library will provide an emulation on any system that lacks these |
| primitives, so they are not a portability threat. They are defined in |
| `sys/uio.h'. |
| |
| These functions are controlled with arrays of `iovec' structures, |
| which describe the location and size of each buffer. |
| |
| -- Data Type: struct iovec |
| The `iovec' structure describes a buffer. It contains two fields: |
| |
| `void *iov_base' |
| Contains the address of a buffer. |
| |
| `size_t iov_len' |
| Contains the length of the buffer. |
| |
| |
| -- Function: ssize_t readv (int FILEDES, const struct iovec *VECTOR, |
| int COUNT) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note |
| POSIX Safety Concepts::. |
| |
| The `readv' function reads data from FILEDES and scatters it into |
| the buffers described in VECTOR, which is taken to be COUNT |
| structures long. As each buffer is filled, data is sent to the |
| next. |
| |
| Note that `readv' is not guaranteed to fill all the buffers. It |
| may stop at any point, for the same reasons `read' would. |
| |
| The return value is a count of bytes (_not_ buffers) read, 0 |
| indicating end-of-file, or -1 indicating an error. The possible |
| errors are the same as in `read'. |
| |
| |
| -- Function: ssize_t writev (int FILEDES, const struct iovec *VECTOR, |
| int COUNT) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note |
| POSIX Safety Concepts::. |
| |
| The `writev' function gathers data from the buffers described in |
| VECTOR, which is taken to be COUNT structures long, and writes |
| them to `filedes'. As each buffer is written, it moves on to the |
| next. |
| |
| Like `readv', `writev' may stop midstream under the same |
| conditions `write' would. |
| |
| The return value is a count of bytes written, or -1 indicating an |
| error. The possible errors are the same as in `write'. |
| |
| |
| -- Function: ssize_t preadv (int FD, const struct iovec *IOV, int |
| IOVCNT, off_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `readv' function, with the |
| difference it adds an extra OFFSET parameter of type `off_t' |
| similar to `pread'. The data is written to the file starting at |
| position OFFSET. The position of the file descriptor itself is |
| not affected by the operation. The value is the same as before |
| the call. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `preadv' function is in fact `preadv64' and the type `off_t' has |
| 64 bits, which makes it possible to handle files up to 2^63 bytes |
| in length. |
| |
| The return value is a count of bytes (_not_ buffers) read, 0 |
| indicating end-of-file, or -1 indicating an error. The possible |
| errors are the same as in `readv' and `pread'. |
| |
| -- Function: ssize_t preadv64 (int FD, const struct iovec *IOV, int |
| IOVCNT, off64_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `preadv' function with the |
| difference is that the OFFSET parameter is of type `off64_t' |
| instead of `off_t'. It makes it possible on 32 bit machines to |
| address files larger than 2^31 bytes and up to 2^63 bytes. The |
| file descriptor `filedes' must be opened using `open64' since |
| otherwise the large offsets possible with `off64_t' will lead to |
| errors with a descriptor in small file mode. |
| |
| When the source file is compiled using `_FILE_OFFSET_BITS == 64' |
| on a 32 bit machine this function is actually available under the |
| name `preadv' and so transparently replaces the 32 bit interface. |
| |
| -- Function: ssize_t pwritev (int FD, const struct iovec *IOV, int |
| IOVCNT, off_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `writev' function, with the |
| difference it adds an extra OFFSET parameter of type `off_t' |
| similar to `pwrite'. The data is written to the file starting at |
| position OFFSET. The position of the file descriptor itself is |
| not affected by the operation. The value is the same as before |
| the call. |
| |
| However, on Linux, if a file is opened with `O_APPEND', `pwrite' |
| appends data to the end of the file, regardless of the value of |
| `offset'. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `pwritev' function is in fact `pwritev64' and the type `off_t' has |
| 64 bits, which makes it possible to handle files up to 2^63 bytes |
| in length. |
| |
| The return value is a count of bytes (_not_ buffers) written, 0 |
| indicating end-of-file, or -1 indicating an error. The possible |
| errors are the same as in `writev' and `pwrite'. |
| |
| -- Function: ssize_t pwritev64 (int FD, const struct iovec *IOV, int |
| IOVCNT, off64_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `pwritev' function with the |
| difference is that the OFFSET parameter is of type `off64_t' |
| instead of `off_t'. It makes it possible on 32 bit machines to |
| address files larger than 2^31 bytes and up to 2^63 bytes. The |
| file descriptor `filedes' must be opened using `open64' since |
| otherwise the large offsets possible with `off64_t' will lead to |
| errors with a descriptor in small file mode. |
| |
| When the source file is compiled using `_FILE_OFFSET_BITS == 64' |
| on a 32 bit machine this function is actually available under the |
| name `pwritev' and so transparently replaces the 32 bit interface. |
| |
| -- Function: ssize_t preadv2 (int FD, const struct iovec *IOV, int |
| IOVCNT, off_t OFFSET, int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `preadv' function, with the |
| difference it adds an extra FLAGS parameter of type `int'. |
| Additionally, if OFFSET is -1, the current file position is used |
| and updated (like the `readv' function). |
| |
| The supported FLAGS are dependent of the underlying system. For |
| Linux it supports: |
| |
| `RWF_HIPRI' |
| High priority request. This adds a flag that tells the file |
| system that this is a high priority request for which it is |
| worth to poll the hardware. The flag is purely advisory and |
| can be ignored if not supported. The FD must be opened using |
| `O_DIRECT'. |
| |
| `RWF_DSYNC' |
| Per-IO synchronization as if the file was opened with |
| `O_DSYNC' flag. |
| |
| `RWF_SYNC' |
| Per-IO synchronization as if the file was opened with |
| `O_SYNC' flag. |
| |
| `RWF_NOWAIT' |
| Use nonblocking mode for this operation; that is, this call |
| to `preadv2' will fail and set `errno' to `EAGAIN' if the |
| operation would block. |
| |
| `RWF_APPEND' |
| Per-IO synchronization as if the file was opened with |
| `O_APPEND' flag. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `preadv2' function is in fact `preadv64v2' and the type `off_t' |
| has 64 bits, which makes it possible to handle files up to 2^63 |
| bytes in length. |
| |
| The return value is a count of bytes (_not_ buffers) read, 0 |
| indicating end-of-file, or -1 indicating an error. The possible |
| errors are the same as in `preadv' with the addition of: |
| |
| `EOPNOTSUPP' |
| An unsupported FLAGS was used. |
| |
| |
| |
| -- Function: ssize_t preadv64v2 (int FD, const struct iovec *IOV, int |
| IOVCNT, off64_t OFFSET, int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `preadv2' function with the |
| difference is that the OFFSET parameter is of type `off64_t' |
| instead of `off_t'. It makes it possible on 32 bit machines to |
| address files larger than 2^31 bytes and up to 2^63 bytes. The |
| file descriptor `filedes' must be opened using `open64' since |
| otherwise the large offsets possible with `off64_t' will lead to |
| errors with a descriptor in small file mode. |
| |
| When the source file is compiled using `_FILE_OFFSET_BITS == 64' |
| on a 32 bit machine this function is actually available under the |
| name `preadv2' and so transparently replaces the 32 bit interface. |
| |
| -- Function: ssize_t pwritev2 (int FD, const struct iovec *IOV, int |
| IOVCNT, off_t OFFSET, int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `pwritev' function, with the |
| difference it adds an extra FLAGS parameter of type `int'. |
| Additionally, if OFFSET is -1, the current file position should is |
| used and updated (like the `writev' function). |
| |
| The supported FLAGS are dependent of the underlying system. For |
| Linux, the supported flags are the same as those for `preadv2'. |
| |
| When the source file is compiled with `_FILE_OFFSET_BITS == 64' the |
| `pwritev2' function is in fact `pwritev64v2' and the type `off_t' |
| has 64 bits, which makes it possible to handle files up to 2^63 |
| bytes in length. |
| |
| The return value is a count of bytes (_not_ buffers) write, 0 |
| indicating end-of-file, or -1 indicating an error. The possible |
| errors are the same as in `preadv2'. |
| |
| -- Function: ssize_t pwritev64v2 (int FD, const struct iovec *IOV, int |
| IOVCNT, off64_t OFFSET, int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the `pwritev2' function with the |
| difference is that the OFFSET parameter is of type `off64_t' |
| instead of `off_t'. It makes it possible on 32 bit machines to |
| address files larger than 2^31 bytes and up to 2^63 bytes. The |
| file descriptor `filedes' must be opened using `open64' since |
| otherwise the large offsets possible with `off64_t' will lead to |
| errors with a descriptor in small file mode. |
| |
| When the source file is compiled using `_FILE_OFFSET_BITS == 64' |
| on a 32 bit machine this function is actually available under the |
| name `pwritev2' and so transparently replaces the 32 bit interface. |
| |
| |
| File: libc.info, Node: Copying File Data, Next: Memory-mapped I/O, Prev: Scatter-Gather, Up: Low-Level I/O |
| |
| 13.7 Copying data between two files |
| =================================== |
| |
| A special function is provided to copy data between two files on the |
| same file system. The system can optimize such copy operations. This |
| is particularly important on network file systems, where the data would |
| otherwise have to be transferred twice over the network. |
| |
| Note that this function only copies file data, but not metadata such |
| as file permissions or extended attributes. |
| |
| -- Function: ssize_t copy_file_range (int INPUTFD, off64_t *INPUTPOS, |
| int OUTPUTFD, off64_t *OUTPUTPOS, ssize_t LENGTH, unsigned |
| int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function copies up to LENGTH bytes from the file descriptor |
| INPUTFD to the file descriptor OUTPUTFD. |
| |
| The function can operate on both the current file position (like |
| `read' and `write') and an explicit offset (like `pread' and |
| `pwrite'). If the INPUTPOS pointer is null, the file position of |
| INPUTFD is used as the starting point of the copy operation, and |
| the file position is advanced during it. If INPUTPOS is not null, |
| then `*INPUTPOS' is used as the starting point of the copy |
| operation, and `*INPUTPOS' is incremented by the number of copied |
| bytes, but the file position remains unchanged. Similar rules |
| apply to OUTPUTFD and OUTPUTPOS for the output file position. |
| |
| The FLAGS argument is currently reserved and must be zero. |
| |
| The `copy_file_range' function returns the number of bytes copied. |
| This can be less than the specified LENGTH in case the input file |
| contains fewer remaining bytes than LENGTH, or if a read or write |
| failure occurs. The return value is zero if the end of the input |
| file is encountered immediately. |
| |
| If no bytes can be copied, to report an error, `copy_file_range' |
| returns the value -1 and sets `errno'. The table below lists some |
| of the error conditions for this function. |
| |
| `ENOSYS' |
| The kernel does not implement the required functionality. |
| |
| `EISDIR' |
| At least one of the descriptors INPUTFD or OUTPUTFD refers to |
| a directory. |
| |
| `EINVAL' |
| At least one of the descriptors INPUTFD or OUTPUTFD refers to |
| a non-regular, non-directory file (such as a socket or a |
| FIFO). |
| |
| The input or output positions before are after the copy |
| operations are outside of an implementation-defined limit. |
| |
| The FLAGS argument is not zero. |
| |
| `EFBIG' |
| The new file size would exceed the process file size limit. |
| *Note Limits on Resources::. |
| |
| The input or output positions before are after the copy |
| operations are outside of an implementation-defined limit. |
| This can happen if the file was not opened with large file |
| support (LFS) on 32-bit machines, and the copy operation |
| would create a file which is larger than what `off_t' could |
| represent. |
| |
| `EBADF' |
| The argument INPUTFD is not a valid file descriptor open for |
| reading. |
| |
| The argument OUTPUTFD is not a valid file descriptor open for |
| writing, or OUTPUTFD has been opened with `O_APPEND'. |
| |
| In addition, `copy_file_range' can fail with the error codes which |
| are used by `read', `pread', `write', and `pwrite'. |
| |
| The `copy_file_range' function is a cancellation point. In case of |
| cancellation, the input location (the file position or the value at |
| `*INPUTPOS') is indeterminate. |
| |
| |
| File: libc.info, Node: Memory-mapped I/O, Next: Waiting for I/O, Prev: Copying File Data, Up: Low-Level I/O |
| |
| 13.8 Memory-mapped I/O |
| ====================== |
| |
| On modern operating systems, it is possible to "mmap" (pronounced |
| "em-map") a file to a region of memory. When this is done, the file can |
| be accessed just like an array in the program. |
| |
| This is more efficient than `read' or `write', as only the regions |
| of the file that a program actually accesses are loaded. Accesses to |
| not-yet-loaded parts of the mmapped region are handled in the same way |
| as swapped out pages. |
| |
| Since mmapped pages can be stored back to their file when physical |
| memory is low, it is possible to mmap files orders of magnitude larger |
| than both the physical memory _and_ swap space. The only limit is |
| address space. The theoretical limit is 4GB on a 32-bit machine - |
| however, the actual limit will be smaller since some areas will be |
| reserved for other purposes. If the LFS interface is used the file size |
| on 32-bit systems is not limited to 2GB (offsets are signed which |
| reduces the addressable area of 4GB by half); the full 64-bit are |
| available. |
| |
| Memory mapping only works on entire pages of memory. Thus, addresses |
| for mapping must be page-aligned, and length values will be rounded up. |
| To determine the default size of a page the machine uses one should use: |
| |
| size_t page_size = (size_t) sysconf (_SC_PAGESIZE); |
| |
| On some systems, mappings can use larger page sizes for certain |
| files, and applications can request larger page sizes for anonymous |
| mappings as well (see the `MAP_HUGETLB' flag below). |
| |
| The following functions are declared in `sys/mman.h': |
| |
| -- Function: void * mmap (void *ADDRESS, size_t LENGTH, int PROTECT, |
| int FLAGS, int FILEDES, off_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `mmap' function creates a new mapping, connected to bytes |
| (OFFSET) to (OFFSET + LENGTH - 1) in the file open on FILEDES. A |
| new reference for the file specified by FILEDES is created, which |
| is not removed by closing the file. |
| |
| ADDRESS gives a preferred starting address for the mapping. |
| `NULL' expresses no preference. Any previous mapping at that |
| address is automatically removed. The address you give may still |
| be changed, unless you use the `MAP_FIXED' flag. |
| |
| PROTECT contains flags that control what kind of access is |
| permitted. They include `PROT_READ', `PROT_WRITE', and |
| `PROT_EXEC'. The special flag `PROT_NONE' reserves a region of |
| address space for future use. The `mprotect' function can be used |
| to change the protection flags. *Note Memory Protection::. |
| |
| FLAGS contains flags that control the nature of the map. One of |
| `MAP_SHARED' or `MAP_PRIVATE' must be specified. |
| |
| They include: |
| |
| `MAP_PRIVATE' |
| This specifies that writes to the region should never be |
| written back to the attached file. Instead, a copy is made |
| for the process, and the region will be swapped normally if |
| memory runs low. No other process will see the changes. |
| |
| Since private mappings effectively revert to ordinary memory |
| when written to, you must have enough virtual memory for a |
| copy of the entire mmapped region if you use this mode with |
| `PROT_WRITE'. |
| |
| `MAP_SHARED' |
| This specifies that writes to the region will be written back |
| to the file. Changes made will be shared immediately with |
| other processes mmaping the same file. |
| |
| Note that actual writing may take place at any time. You |
| need to use `msync', described below, if it is important that |
| other processes using conventional I/O get a consistent view |
| of the file. |
| |
| `MAP_FIXED' |
| This forces the system to use the exact mapping address |
| specified in ADDRESS and fail if it can't. |
| |
| `MAP_ANONYMOUS' |
| `MAP_ANON' |
| This flag tells the system to create an anonymous mapping, |
| not connected to a file. FILEDES and OFFSET are ignored, and |
| the region is initialized with zeros. |
| |
| Anonymous maps are used as the basic primitive to extend the |
| heap on some systems. They are also useful to share data |
| between multiple tasks without creating a file. |
| |
| On some systems using private anonymous mmaps is more |
| efficient than using `malloc' for large blocks. This is not |
| an issue with the GNU C Library, as the included `malloc' |
| automatically uses `mmap' where appropriate. |
| |
| `MAP_HUGETLB' |
| This requests that the system uses an alternative page size |
| which is larger than the default page size for the mapping. |
| For some workloads, increasing the page size for large |
| mappings improves performance because the system needs to |
| handle far fewer pages. For other workloads which require |
| frequent transfer of pages between storage or different nodes, |
| the decreased page granularity may cause performance problems |
| due to the increased page size and larger transfers. |
| |
| In order to create the mapping, the system needs physically |
| contiguous memory of the size of the increased page size. As |
| a result, `MAP_HUGETLB' mappings are affected by memory |
| fragmentation, and their creation can fail even if plenty of |
| memory is available in the system. |
| |
| Not all file systems support mappings with an increased page |
| size. |
| |
| The `MAP_HUGETLB' flag is specific to Linux. |
| |
| |
| `mmap' returns the address of the new mapping, or `MAP_FAILED' for |
| an error. |
| |
| Possible errors include: |
| |
| `EINVAL' |
| Either ADDRESS was unusable (because it is not a multiple of |
| the applicable page size), or inconsistent FLAGS were given. |
| |
| If `MAP_HUGETLB' was specified, the file or system does not |
| support large page sizes. |
| |
| `EACCES' |
| FILEDES was not open for the type of access specified in |
| PROTECT. |
| |
| `ENOMEM' |
| Either there is not enough memory for the operation, or the |
| process is out of address space. |
| |
| `ENODEV' |
| This file is of a type that doesn't support mapping. |
| |
| `ENOEXEC' |
| The file is on a filesystem that doesn't support mapping. |
| |
| |
| |
| -- Function: void * mmap64 (void *ADDRESS, size_t LENGTH, int PROTECT, |
| int FLAGS, int FILEDES, off64_t OFFSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `mmap64' function is equivalent to the `mmap' function but the |
| OFFSET parameter is of type `off64_t'. On 32-bit systems this |
| allows the file associated with the FILEDES descriptor to be |
| larger than 2GB. FILEDES must be a descriptor returned from a |
| call to `open64' or `fopen64' and `freopen64' where the descriptor |
| is retrieved with `fileno'. |
| |
| When the sources are translated with `_FILE_OFFSET_BITS == 64' this |
| function is actually available under the name `mmap'. I.e., the |
| new, extended API using 64 bit file sizes and offsets transparently |
| replaces the old API. |
| |
| -- Function: int munmap (void *ADDR, size_t LENGTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| `munmap' removes any memory maps from (ADDR) to (ADDR + LENGTH). |
| LENGTH should be the length of the mapping. |
| |
| It is safe to unmap multiple mappings in one command, or include |
| unmapped space in the range. It is also possible to unmap only |
| part of an existing mapping. However, only entire pages can be |
| removed. If LENGTH is not an even number of pages, it will be |
| rounded up. |
| |
| It returns 0 for success and -1 for an error. |
| |
| One error is possible: |
| |
| `EINVAL' |
| The memory range given was outside the user mmap range or |
| wasn't page aligned. |
| |
| |
| |
| -- Function: int msync (void *ADDRESS, size_t LENGTH, int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| When using shared mappings, the kernel can write the file at any |
| time before the mapping is removed. To be certain data has |
| actually been written to the file and will be accessible to |
| non-memory-mapped I/O, it is necessary to use this function. |
| |
| It operates on the region ADDRESS to (ADDRESS + LENGTH). It may |
| be used on part of a mapping or multiple mappings, however the |
| region given should not contain any unmapped space. |
| |
| FLAGS can contain some options: |
| |
| `MS_SYNC' |
| This flag makes sure the data is actually written _to disk_. |
| Normally `msync' only makes sure that accesses to a file with |
| conventional I/O reflect the recent changes. |
| |
| `MS_ASYNC' |
| This tells `msync' to begin the synchronization, but not to |
| wait for it to complete. |
| |
| |
| `msync' returns 0 for success and -1 for error. Errors include: |
| |
| `EINVAL' |
| An invalid region was given, or the FLAGS were invalid. |
| |
| `EFAULT' |
| There is no existing mapping in at least part of the given |
| region. |
| |
| |
| |
| -- Function: void * mremap (void *ADDRESS, size_t LENGTH, size_t |
| NEW_LENGTH, int FLAG) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function can be used to change the size of an existing memory |
| area. ADDRESS and LENGTH must cover a region entirely mapped in |
| the same `mmap' statement. A new mapping with the same |
| characteristics will be returned with the length NEW_LENGTH. |
| |
| One option is possible, `MREMAP_MAYMOVE'. If it is given in |
| FLAGS, the system may remove the existing mapping and create a new |
| one of the desired length in another location. |
| |
| The address of the resulting mapping is returned, or -1. Possible |
| error codes include: |
| |
| `EFAULT' |
| There is no existing mapping in at least part of the original |
| region, or the region covers two or more distinct mappings. |
| |
| `EINVAL' |
| The address given is misaligned or inappropriate. |
| |
| `EAGAIN' |
| The region has pages locked, and if extended it would exceed |
| the process's resource limit for locked pages. *Note Limits |
| on Resources::. |
| |
| `ENOMEM' |
| The region is private writable, and insufficient virtual |
| memory is available to extend it. Also, this error will |
| occur if `MREMAP_MAYMOVE' is not given and the extension |
| would collide with another mapped region. |
| |
| |
| This function is only available on a few systems. Except for |
| performing optional optimizations one should not rely on this function. |
| |
| Not all file descriptors may be mapped. Sockets, pipes, and most |
| devices only allow sequential access and do not fit into the mapping |
| abstraction. In addition, some regular files may not be mmapable, and |
| older kernels may not support mapping at all. Thus, programs using |
| `mmap' should have a fallback method to use should it fail. *Note Mmap: |
| (standards)Mmap. |
| |
| -- Function: int madvise (void *ADDR, size_t LENGTH, int ADVICE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function can be used to provide the system with ADVICE about |
| the intended usage patterns of the memory region starting at ADDR |
| and extending LENGTH bytes. |
| |
| The valid BSD values for ADVICE are: |
| |
| `MADV_NORMAL' |
| The region should receive no further special treatment. |
| |
| `MADV_RANDOM' |
| The region will be accessed via random page references. The |
| kernel should page-in the minimal number of pages for each |
| page fault. |
| |
| `MADV_SEQUENTIAL' |
| The region will be accessed via sequential page references. |
| This may cause the kernel to aggressively read-ahead, |
| expecting further sequential references after any page fault |
| within this region. |
| |
| `MADV_WILLNEED' |
| The region will be needed. The pages within this region may |
| be pre-faulted in by the kernel. |
| |
| `MADV_DONTNEED' |
| The region is no longer needed. The kernel may free these |
| pages, causing any changes to the pages to be lost, as well |
| as swapped out pages to be discarded. |
| |
| `MADV_HUGEPAGE' |
| Indicate that it is beneficial to increase the page size for |
| this mapping. This can improve performance for larger |
| mappings because the system needs to handle far fewer pages. |
| However, if parts of the mapping are frequently transferred |
| between storage or different nodes, performance may suffer |
| because individual transfers can become substantially larger |
| due to the increased page size. |
| |
| This flag is specific to Linux. |
| |
| `MADV_NOHUGEPAGE' |
| Undo the effect of a previous `MADV_HUGEPAGE' advice. This |
| flag is specific to Linux. |
| |
| |
| The POSIX names are slightly different, but with the same meanings: |
| |
| `POSIX_MADV_NORMAL' |
| This corresponds with BSD's `MADV_NORMAL'. |
| |
| `POSIX_MADV_RANDOM' |
| This corresponds with BSD's `MADV_RANDOM'. |
| |
| `POSIX_MADV_SEQUENTIAL' |
| This corresponds with BSD's `MADV_SEQUENTIAL'. |
| |
| `POSIX_MADV_WILLNEED' |
| This corresponds with BSD's `MADV_WILLNEED'. |
| |
| `POSIX_MADV_DONTNEED' |
| This corresponds with BSD's `MADV_DONTNEED'. |
| |
| |
| `madvise' returns 0 for success and -1 for error. Errors include: |
| `EINVAL' |
| An invalid region was given, or the ADVICE was invalid. |
| |
| `EFAULT' |
| There is no existing mapping in at least part of the given |
| region. |
| |
| |
| -- Function: int shm_open (const char *NAME, int OFLAG, mode_t MODE) |
| Preliminary: | MT-Safe locale | AS-Unsafe init heap lock | |
| AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function returns a file descriptor that can be used to |
| allocate shared memory via mmap. Unrelated processes can use same |
| NAME to create or open existing shared memory objects. |
| |
| A NAME argument specifies the shared memory object to be opened. |
| In the GNU C Library it must be a string smaller than `NAME_MAX' |
| bytes starting with an optional slash but containing no other |
| slashes. |
| |
| The semantics of OFLAG and MODE arguments is same as in `open'. |
| |
| `shm_open' returns the file descriptor on success or -1 on error. |
| On failure `errno' is set. |
| |
| -- Function: int shm_unlink (const char *NAME) |
| Preliminary: | MT-Safe locale | AS-Unsafe init heap lock | |
| AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function is the inverse of `shm_open' and removes the object |
| with the given NAME previously created by `shm_open'. |
| |
| `shm_unlink' returns 0 on success or -1 on error. On failure |
| `errno' is set. |
| |
| -- Function: int memfd_create (const char *NAME, unsigned int FLAGS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The `memfd_create' function returns a file descriptor which can be |
| used to create memory mappings using the `mmap' function. It is |
| similar to the `shm_open' function in the sense that these mappings |
| are not backed by actual files. However, the descriptor returned |
| by `memfd_create' does not correspond to a named object; the NAME |
| argument is used for debugging purposes only (e.g., will appear in |
| `/proc'), and separate invocations of `memfd_create' with the same |
| NAME will not return descriptors for the same region of memory. |
| The descriptor can also be used to create alias mappings within |
| the same process. |
| |
| The descriptor initially refers to a zero-length file. Before |
| mappings can be created which are backed by memory, the file size |
| needs to be increased with the `ftruncate' function. *Note File |
| Size::. |
| |
| The FLAGS argument can be a combination of the following flags: |
| |
| `MFD_CLOEXEC' |
| The descriptor is created with the `O_CLOEXEC' flag. |
| |
| `MFD_ALLOW_SEALING' |
| The descriptor supports the addition of seals using the |
| `fcntl' function. |
| |
| `MFD_HUGETLB' |
| This requests that mappings created using the returned file |
| descriptor use a larger page size. See `MAP_HUGETLB' above |
| for details. |
| |
| This flag is incompatible with `MFD_ALLOW_SEALING'. |
| |
| `memfd_create' returns a file descriptor on success, and -1 on |
| failure. |
| |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EINVAL' |
| An invalid combination is specified in FLAGS, or NAME is too |
| long. |
| |
| `EFAULT' |
| The NAME argument does not point to a string. |
| |
| `EMFILE' |
| The operation would exceed the file descriptor limit for this |
| process. |
| |
| `ENFILE' |
| The operation would exceed the system-wide file descriptor |
| limit. |
| |
| `ENOMEM' |
| There is not enough memory for the operation. |
| |
| |
| File: libc.info, Node: Waiting for I/O, Next: Synchronizing I/O, Prev: Memory-mapped I/O, Up: Low-Level I/O |
| |
| 13.9 Waiting for Input or Output |
| ================================ |
| |
| Sometimes a program needs to accept input on multiple input channels |
| whenever input arrives. For example, some workstations may have devices |
| such as a digitizing tablet, function button box, or dial box that are |
| connected via normal asynchronous serial interfaces; good user interface |
| style requires responding immediately to input on any device. Another |
| example is a program that acts as a server to several other processes |
| via pipes or sockets. |
| |
| You cannot normally use `read' for this purpose, because this blocks |
| the program until input is available on one particular file descriptor; |
| input on other channels won't wake it up. You could set nonblocking |
| mode and poll each file descriptor in turn, but this is very |
| inefficient. |
| |
| A better solution is to use the `select' function. This blocks the |
| program until input or output is ready on a specified set of file |
| descriptors, or until a timer expires, whichever comes first. This |
| facility is declared in the header file `sys/types.h'. |
| |
| In the case of a server socket (*note Listening::), we say that |
| "input" is available when there are pending connections that could be |
| accepted (*note Accepting Connections::). `accept' for server sockets |
| blocks and interacts with `select' just as `read' does for normal input. |
| |
| The file descriptor sets for the `select' function are specified as |
| `fd_set' objects. Here is the description of the data type and some |
| macros for manipulating these objects. |
| |
| -- Data Type: fd_set |
| The `fd_set' data type represents file descriptor sets for the |
| `select' function. It is actually a bit array. |
| |
| -- Macro: int FD_SETSIZE |
| The value of this macro is the maximum number of file descriptors |
| that a `fd_set' object can hold information about. On systems |
| with a fixed maximum number, `FD_SETSIZE' is at least that number. |
| On some systems, including GNU, there is no absolute limit on the |
| number of descriptors open, but this macro still has a constant |
| value which controls the number of bits in an `fd_set'; if you get |
| a file descriptor with a value as high as `FD_SETSIZE', you cannot |
| put that descriptor into an `fd_set'. |
| |
| -- Macro: void FD_ZERO (fd_set *SET) |
| Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This macro initializes the file descriptor set SET to be the empty |
| set. |
| |
| -- Macro: void FD_SET (int FILEDES, fd_set *SET) |
| Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This macro adds FILEDES to the file descriptor set SET. |
| |
| The FILEDES parameter must not have side effects since it is |
| evaluated more than once. |
| |
| -- Macro: void FD_CLR (int FILEDES, fd_set *SET) |
| Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This macro removes FILEDES from the file descriptor set SET. |
| |
| The FILEDES parameter must not have side effects since it is |
| evaluated more than once. |
| |
| -- Macro: int FD_ISSET (int FILEDES, const fd_set *SET) |
| Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This macro returns a nonzero value (true) if FILEDES is a member |
| of the file descriptor set SET, and zero (false) otherwise. |
| |
| The FILEDES parameter must not have side effects since it is |
| evaluated more than once. |
| |
| Next, here is the description of the `select' function itself. |
| |
| -- Function: int select (int NFDS, fd_set *READ-FDS, fd_set |
| *WRITE-FDS, fd_set *EXCEPT-FDS, struct timeval *TIMEOUT) |
| Preliminary: | MT-Safe race:read-fds race:write-fds race:except-fds |
| | AS-Safe | AC-Safe | *Note POSIX Safety Concepts::. |
| |
| The `select' function blocks the calling process until there is |
| activity on any of the specified sets of file descriptors, or |
| until the timeout period has expired. |
| |
| The file descriptors specified by the READ-FDS argument are |
| checked to see if they are ready for reading; the WRITE-FDS file |
| descriptors are checked to see if they are ready for writing; and |
| the EXCEPT-FDS file descriptors are checked for exceptional |
| conditions. You can pass a null pointer for any of these |
| arguments if you are not interested in checking for that kind of |
| condition. |
| |
| A file descriptor is considered ready for reading if a `read' call |
| will not block. This usually includes the read offset being at |
| the end of the file or there is an error to report. A server |
| socket is considered ready for reading if there is a pending |
| connection which can be accepted with `accept'; *note Accepting |
| Connections::. A client socket is ready for writing when its |
| connection is fully established; *note Connecting::. |
| |
| "Exceptional conditions" does not mean errors--errors are reported |
| immediately when an erroneous system call is executed, and do not |
| constitute a state of the descriptor. Rather, they include |
| conditions such as the presence of an urgent message on a socket. |
| (*Note Sockets::, for information on urgent messages.) |
| |
| The `select' function checks only the first NFDS file descriptors. |
| The usual thing is to pass `FD_SETSIZE' as the value of this |
| argument. |
| |
| The TIMEOUT specifies the maximum time to wait. If you pass a |
| null pointer for this argument, it means to block indefinitely |
| until one of the file descriptors is ready. Otherwise, you should |
| provide the time in `struct timeval' format; see *note |
| 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.10 Synchronizing I/O operations |
| ================================== |
| |
| In most modern operating systems, the normal I/O operations are not |
| executed synchronously. I.e., even if a `write' system call returns, |
| this does not mean the data is actually written to the media, e.g., the |
| disk. |
| |
| In situations where synchronization points are necessary, you can use |
| special functions which ensure that all operations finish before they |
| return. |
| |
| -- Function: void sync (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| A call to this function will not return as long as there is data |
| which has not been written to the device. All dirty buffers in |
| the kernel will be written and so an overall consistent system can |
| be achieved (if no other process in parallel writes data). |
| |
| A prototype for `sync' can be found in `unistd.h'. |
| |
| Programs more often want to ensure that data written to a given file |
| is committed, rather than all data in the system. For this, `sync' is |
| overkill. |
| |
| -- Function: int fsync (int FILDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `fsync' function can be used to make sure all data associated |
| with the open file FILDES is written to the device associated with |
| the descriptor. The function call does not return unless all |
| actions have finished. |
| |
| A prototype for `fsync' can be found in `unistd.h'. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| `fsync' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this, calls to |
| `fsync' should be protected using cancellation handlers. |
| |
| The return value of the function is zero if no error occurred. |
| Otherwise it is -1 and the global variable `errno' is set to the |
| following values: |
| `EBADF' |
| The descriptor FILDES is not valid. |
| |
| `EINVAL' |
| No synchronization is possible since the system does not |
| implement this. |
| |
| Sometimes it is not even necessary to write all data associated with |
| a file descriptor. E.g., in database files which do not change in size |
| it is enough to write all the file content data to the device. |
| Meta-information, like the modification time etc., are not that |
| important and leaving such information uncommitted does not prevent a |
| successful recovery of the file in case of a problem. |
| |
| -- Function: int fdatasync (int FILDES) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| When a call to the `fdatasync' function returns, it is ensured |
| that all of the file data is written to the device. For all |
| pending I/O operations, the parts guaranteeing data integrity |
| finished. |
| |
| Not all systems implement the `fdatasync' operation. On systems |
| missing this functionality `fdatasync' is emulated by a call to |
| `fsync' since the performed actions are a superset of those |
| required by `fdatasync'. |
| |
| The prototype for `fdatasync' is in `unistd.h'. |
| |
| The return value of the function is zero if no error occurred. |
| Otherwise it is -1 and the global variable `errno' is set to the |
| following values: |
| `EBADF' |
| The descriptor FILDES is not valid. |
| |
| `EINVAL' |
| No synchronization is possible since the system does not |
| implement this. |
| |
| |
| File: libc.info, Node: Asynchronous I/O, Next: Control Operations, Prev: Synchronizing I/O, Up: Low-Level I/O |
| |
| 13.11 Perform I/O Operations in Parallel |
| ======================================== |
| |
| The POSIX.1b standard defines a new set of I/O operations which can |
| significantly reduce the time an application spends waiting for I/O. |
| The new functions allow a program to initiate one or more I/O |
| operations and then immediately resume normal work while the I/O |
| operations are executed in parallel. This functionality is available |
| if the `unistd.h' file defines the symbol `_POSIX_ASYNCHRONOUS_IO'. |
| |
| These functions are part of the library with realtime functions named |
| `librt'. They are not actually part of the `libc' binary. The |
| implementation of these functions can be done using support in the |
| kernel (if available) or using an implementation based on threads at |
| userlevel. In the latter case it might be necessary to link |
| applications with the thread library `libpthread' in addition to |
| `librt'. |
| |
| All AIO operations operate on files which were opened previously. |
| There might be arbitrarily many operations running for one file. The |
| asynchronous I/O operations are controlled using a data structure named |
| `struct aiocb' ("AIO control block"). It is defined in `aio.h' as |
| follows. |
| |
| -- Data Type: struct aiocb |
| The POSIX.1b standard mandates that the `struct aiocb' structure |
| contains at least the members described in the following table. |
| There might be more elements which are used by the implementation, |
| but depending upon these elements is not portable and is highly |
| deprecated. |
| |
| `int aio_fildes' |
| This element specifies the file descriptor to be used for the |
| operation. It must be a legal descriptor, otherwise the |
| operation will fail. |
| |
| The device on which the file is opened must allow the seek |
| operation. I.e., it is not possible to use any of the AIO |
| operations on devices like terminals where an `lseek' call |
| would lead to an error. |
| |
| `off_t aio_offset' |
| This element specifies the offset in the file at which the |
| operation (input or output) is performed. Since the |
| operations are carried out in arbitrary order and more than |
| one operation for one file descriptor can be started, one |
| cannot expect a current read/write position of the file |
| descriptor. |
| |
| `volatile void *aio_buf' |
| This is a pointer to the buffer with the data to be written |
| or the place where the read data is stored. |
| |
| `size_t aio_nbytes' |
| This element specifies the length of the buffer pointed to by |
| `aio_buf'. |
| |
| `int aio_reqprio' |
| If the platform has defined `_POSIX_PRIORITIZED_IO' and |
| `_POSIX_PRIORITY_SCHEDULING', the AIO requests are processed |
| based on the current scheduling priority. The `aio_reqprio' |
| element can then be used to lower the priority of the AIO |
| operation. |
| |
| `struct sigevent aio_sigevent' |
| This element specifies how the calling process is notified |
| once the operation terminates. If the `sigev_notify' element |
| is `SIGEV_NONE', no notification is sent. If it is |
| `SIGEV_SIGNAL', the signal determined by `sigev_signo' is |
| sent. Otherwise, `sigev_notify' must be `SIGEV_THREAD'. In |
| this case, a thread is created which starts executing the |
| function pointed to by `sigev_notify_function'. |
| |
| `int aio_lio_opcode' |
| This element is only used by the `lio_listio' and |
| `lio_listio64' functions. Since these functions allow an |
| arbitrary number of operations to start at once, and each |
| operation can be input or output (or nothing), the |
| information must be stored in the control block. The |
| possible values are: |
| |
| `LIO_READ' |
| Start a read operation. Read from the file at position |
| `aio_offset' and store the next `aio_nbytes' bytes in the |
| buffer pointed to by `aio_buf'. |
| |
| `LIO_WRITE' |
| Start a write operation. Write `aio_nbytes' bytes |
| starting at `aio_buf' into the file starting at position |
| `aio_offset'. |
| |
| `LIO_NOP' |
| Do nothing for this control block. This value is useful |
| sometimes when an array of `struct aiocb' values |
| contains holes, i.e., some of the values must not be |
| handled although the whole array is presented to the |
| `lio_listio' function. |
| |
| When the sources are compiled using `_FILE_OFFSET_BITS == 64' on a |
| 32 bit machine, this type is in fact `struct aiocb64', since the |
| LFS interface transparently replaces the `struct aiocb' definition. |
| |
| For use with the AIO functions defined in the LFS, there is a |
| similar type defined which replaces the types of the appropriate |
| members with larger types but otherwise is equivalent to `struct |
| aiocb'. Particularly, all member names are the same. |
| |
| -- Data Type: struct aiocb64 |
| `int aio_fildes' |
| This element specifies the file descriptor which is used for |
| the operation. It must be a legal descriptor since otherwise |
| the operation fails for obvious reasons. |
| |
| The device on which the file is opened must allow the seek |
| operation. I.e., it is not possible to use any of the AIO |
| operations on devices like terminals where an `lseek' call |
| would lead to an error. |
| |
| `off64_t aio_offset' |
| This element specifies at which offset in the file the |
| operation (input or output) is performed. Since the |
| operation are carried in arbitrary order and more than one |
| operation for one file descriptor can be started, one cannot |
| expect a current read/write position of the file descriptor. |
| |
| `volatile void *aio_buf' |
| This is a pointer to the buffer with the data to be written |
| or the place where the read data is stored. |
| |
| `size_t aio_nbytes' |
| This element specifies the length of the buffer pointed to by |
| `aio_buf'. |
| |
| `int aio_reqprio' |
| If for the platform `_POSIX_PRIORITIZED_IO' and |
| `_POSIX_PRIORITY_SCHEDULING' are defined the AIO requests are |
| processed based on the current scheduling priority. The |
| `aio_reqprio' element can then be used to lower the priority |
| of the AIO operation. |
| |
| `struct sigevent aio_sigevent' |
| This element specifies how the calling process is notified |
| once the operation terminates. If the `sigev_notify' element |
| is `SIGEV_NONE' no notification is sent. If it is |
| `SIGEV_SIGNAL', the signal determined by `sigev_signo' is |
| sent. Otherwise, `sigev_notify' must be `SIGEV_THREAD' in |
| which case a thread is created which starts executing the |
| function pointed to by `sigev_notify_function'. |
| |
| `int aio_lio_opcode' |
| This element is only used by the `lio_listio' and |
| `lio_listio64' functions. Since these functions allow an |
| arbitrary number of operations to start at once, and since |
| each operation can be input or output (or nothing), the |
| information must be stored in the control block. See the |
| description of `struct aiocb' for a description of the |
| possible values. |
| |
| When the sources are compiled using `_FILE_OFFSET_BITS == 64' on a |
| 32 bit machine, this type is available under the name `struct |
| aiocb64', since the LFS transparently replaces the old interface. |
| |
| * Menu: |
| |
| * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations. |
| * Status of AIO Operations:: Getting the Status of AIO Operations. |
| * Synchronizing AIO Operations:: Getting into a consistent state. |
| * Cancel AIO Operations:: Cancellation of AIO Operations. |
| * Configuration of AIO:: How to optimize the AIO implementation. |
| |
| |
| File: libc.info, Node: Asynchronous Reads/Writes, Next: Status of AIO Operations, Up: Asynchronous I/O |
| |
| 13.11.1 Asynchronous Read and Write Operations |
| ---------------------------------------------- |
| |
| -- Function: int aio_read (struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function initiates an asynchronous read operation. It |
| immediately returns after the operation was enqueued or when an |
| error was encountered. |
| |
| The first `aiocbp->aio_nbytes' bytes of the file for which |
| `aiocbp->aio_fildes' is a descriptor are written to the buffer |
| starting at `aiocbp->aio_buf'. Reading starts at the absolute |
| position `aiocbp->aio_offset' in the file. |
| |
| If prioritized I/O is supported by the platform the |
| `aiocbp->aio_reqprio' value is used to adjust the priority before |
| the request is actually enqueued. |
| |
| The calling process is notified about the termination of the read |
| request according to the `aiocbp->aio_sigevent' value. |
| |
| When `aio_read' returns, the return value is zero if no error |
| occurred that can be found before the process is enqueued. If |
| such an early error is found, the function returns -1 and sets |
| `errno' to one of the following values: |
| |
| `EAGAIN' |
| The request was not enqueued due to (temporarily) exceeded |
| resource limitations. |
| |
| `ENOSYS' |
| The `aio_read' function is not implemented. |
| |
| `EBADF' |
| The `aiocbp->aio_fildes' descriptor is not valid. This |
| condition need not be recognized before enqueueing the |
| request and so this error might also be signaled |
| asynchronously. |
| |
| `EINVAL' |
| The `aiocbp->aio_offset' or `aiocbp->aio_reqpiro' value is |
| invalid. This condition need not be recognized before |
| enqueueing the request and so this error might also be |
| signaled asynchronously. |
| |
| If `aio_read' returns zero, the current status of the request can |
| be queried using `aio_error' and `aio_return' functions. As long |
| as the value returned by `aio_error' is `EINPROGRESS' the |
| operation has not yet completed. If `aio_error' returns zero, the |
| operation successfully terminated, otherwise the value is to be |
| interpreted as an error code. If the function terminated, the |
| result of the operation can be obtained using a call to |
| `aio_return'. The returned value is the same as an equivalent |
| call to `read' would have returned. Possible error codes returned |
| by `aio_error' are: |
| |
| `EBADF' |
| The `aiocbp->aio_fildes' descriptor is not valid. |
| |
| `ECANCELED' |
| The operation was canceled before the operation was finished |
| (*note Cancel AIO Operations::) |
| |
| `EINVAL' |
| The `aiocbp->aio_offset' value is invalid. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is in fact `aio_read64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_read64 (struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to the `aio_read' function. The only |
| difference is that on 32 bit machines, the file descriptor should |
| be opened in the large file mode. Internally, `aio_read64' uses |
| functionality equivalent to `lseek64' (*note File Position |
| Primitive::) to position the file descriptor correctly for the |
| reading, as opposed to the `lseek' functionality used in |
| `aio_read'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64', this |
| function is available under the name `aio_read' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| To write data asynchronously to a file, there exists an equivalent |
| pair of functions with a very similar interface. |
| |
| -- Function: int aio_write (struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function initiates an asynchronous write operation. The |
| function call immediately returns after the operation was enqueued |
| or if before this happens an error was encountered. |
| |
| The first `aiocbp->aio_nbytes' bytes from the buffer starting at |
| `aiocbp->aio_buf' are written to the file for which |
| `aiocbp->aio_fildes' is a descriptor, starting at the absolute |
| position `aiocbp->aio_offset' in the file. |
| |
| If prioritized I/O is supported by the platform, the |
| `aiocbp->aio_reqprio' value is used to adjust the priority before |
| the request is actually enqueued. |
| |
| The calling process is notified about the termination of the read |
| request according to the `aiocbp->aio_sigevent' value. |
| |
| When `aio_write' returns, the return value is zero if no error |
| occurred that can be found before the process is enqueued. If |
| such an early error is found the function returns -1 and sets |
| `errno' to one of the following values. |
| |
| `EAGAIN' |
| The request was not enqueued due to (temporarily) exceeded |
| resource limitations. |
| |
| `ENOSYS' |
| The `aio_write' function is not implemented. |
| |
| `EBADF' |
| The `aiocbp->aio_fildes' descriptor is not valid. This |
| condition may not be recognized before enqueueing the |
| request, and so this error might also be signaled |
| asynchronously. |
| |
| `EINVAL' |
| The `aiocbp->aio_offset' or `aiocbp->aio_reqprio' value is |
| invalid. This condition may not be recognized before |
| enqueueing the request and so this error might also be |
| signaled asynchronously. |
| |
| In the case `aio_write' returns zero, the current status of the |
| request can be queried using the `aio_error' and `aio_return' |
| functions. As long as the value returned by `aio_error' is |
| `EINPROGRESS' the operation has not yet completed. If `aio_error' |
| returns zero, the operation successfully terminated, otherwise the |
| value is to be interpreted as an error code. If the function |
| terminated, the result of the operation can be obtained using a |
| call to `aio_return'. The returned value is the same as an |
| equivalent call to `read' would have returned. Possible error |
| codes returned by `aio_error' are: |
| |
| `EBADF' |
| The `aiocbp->aio_fildes' descriptor is not valid. |
| |
| `ECANCELED' |
| The operation was canceled before the operation was finished. |
| (*note Cancel AIO Operations::) |
| |
| `EINVAL' |
| The `aiocbp->aio_offset' value is invalid. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64', this |
| function is in fact `aio_write64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_write64 (struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to the `aio_write' function. The only |
| difference is that on 32 bit machines the file descriptor should |
| be opened in the large file mode. Internally `aio_write64' uses |
| functionality equivalent to `lseek64' (*note File Position |
| Primitive::) to position the file descriptor correctly for the |
| writing, as opposed to the `lseek' functionality used in |
| `aio_write'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64', this |
| function is available under the name `aio_write' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| Besides these functions with the more or less traditional interface, |
| POSIX.1b also defines a function which can initiate more than one |
| operation at a time, and which can handle freely mixed read and write |
| operations. It is therefore similar to a combination of `readv' and |
| `writev'. |
| |
| -- Function: int lio_listio (int MODE, struct aiocb *const LIST[], int |
| NENT, struct sigevent *SIG) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| The `lio_listio' function can be used to enqueue an arbitrary |
| number of read and write requests at one time. The requests can |
| all be meant for the same file, all for different files or every |
| solution in between. |
| |
| `lio_listio' gets the NENT requests from the array pointed to by |
| LIST. The operation to be performed is determined by the |
| `aio_lio_opcode' member in each element of LIST. If this field is |
| `LIO_READ' a read operation is enqueued, similar to a call of |
| `aio_read' for this element of the array (except that the way the |
| termination is signalled is different, as we will see below). If |
| the `aio_lio_opcode' member is `LIO_WRITE' a write operation is |
| enqueued. Otherwise the `aio_lio_opcode' must be `LIO_NOP' in |
| which case this element of LIST is simply ignored. This |
| "operation" is useful in situations where one has a fixed array of |
| `struct aiocb' elements from which only a few need to be handled at |
| a time. Another situation is where the `lio_listio' call was |
| canceled before all requests are processed (*note Cancel AIO |
| Operations::) and the remaining requests have to be reissued. |
| |
| The other members of each element of the array pointed to by |
| `list' must have values suitable for the operation as described in |
| the documentation for `aio_read' and `aio_write' above. |
| |
| The MODE argument determines how `lio_listio' behaves after having |
| enqueued all the requests. If MODE is `LIO_WAIT' it waits until |
| all requests terminated. Otherwise MODE must be `LIO_NOWAIT' and |
| in this case the function returns immediately after having |
| enqueued all the requests. In this case the caller gets a |
| notification of the termination of all requests according to the |
| SIG parameter. If SIG is `NULL' no notification is sent. |
| Otherwise a signal is sent or a thread is started, just as |
| described in the description for `aio_read' or `aio_write'. |
| |
| If MODE is `LIO_WAIT', the return value of `lio_listio' is 0 when |
| all requests completed successfully. Otherwise the function |
| returns -1 and `errno' is set accordingly. To find out which |
| request or requests failed one has to use the `aio_error' function |
| on all the elements of the array LIST. |
| |
| In case MODE is `LIO_NOWAIT', the function returns 0 if all |
| requests were enqueued correctly. The current state of the |
| requests can be found using `aio_error' and `aio_return' as |
| described above. If `lio_listio' returns -1 in this mode, the |
| global variable `errno' is set accordingly. If a request did not |
| yet terminate, a call to `aio_error' returns `EINPROGRESS'. If |
| the value is different, the request is finished and the error |
| value (or 0) is returned and the result of the operation can be |
| retrieved using `aio_return'. |
| |
| Possible values for `errno' are: |
| |
| `EAGAIN' |
| The resources necessary to queue all the requests are not |
| available at the moment. The error status for each element |
| of LIST must be checked to determine which request failed. |
| |
| Another reason could be that the system wide limit of AIO |
| requests is exceeded. This cannot be the case for the |
| implementation on GNU systems since no arbitrary limits exist. |
| |
| `EINVAL' |
| The MODE parameter is invalid or NENT is larger than |
| `AIO_LISTIO_MAX'. |
| |
| `EIO' |
| One or more of the request's I/O operations failed. The |
| error status of each request should be checked to determine |
| which one failed. |
| |
| `ENOSYS' |
| The `lio_listio' function is not supported. |
| |
| If the MODE parameter is `LIO_NOWAIT' and the caller cancels a |
| request, the error status for this request returned by `aio_error' |
| is `ECANCELED'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64', this |
| function is in fact `lio_listio64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int lio_listio64 (int MODE, struct aiocb64 *const LIST[], |
| int NENT, struct sigevent *SIG) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to the `lio_listio' function. The only |
| difference is that on 32 bit machines, the file descriptor should |
| be opened in the large file mode. Internally, `lio_listio64' uses |
| functionality equivalent to `lseek64' (*note File Position |
| Primitive::) to position the file descriptor correctly for the |
| reading or writing, as opposed to the `lseek' functionality used in |
| `lio_listio'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64', this |
| function is available under the name `lio_listio' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| |
| File: libc.info, Node: Status of AIO Operations, Next: Synchronizing AIO Operations, Prev: Asynchronous Reads/Writes, Up: Asynchronous I/O |
| |
| 13.11.2 Getting the Status of AIO Operations |
| -------------------------------------------- |
| |
| As already described in the documentation of the functions in the last |
| section, it must be possible to get information about the status of an |
| I/O request. When the operation is performed truly asynchronously (as |
| with `aio_read' and `aio_write' and with `lio_listio' when the mode is |
| `LIO_NOWAIT'), one sometimes needs to know whether a specific request |
| already terminated and if so, what the result was. The following two |
| functions allow you to get this kind of information. |
| |
| -- Function: int aio_error (const struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function determines the error state of the request described |
| by the `struct aiocb' variable pointed to by AIOCBP. If the |
| request has not yet terminated the value returned is always |
| `EINPROGRESS'. Once the request has terminated the value |
| `aio_error' returns is either 0 if the request completed |
| successfully or it returns the value which would be stored in the |
| `errno' variable if the request would have been done using `read', |
| `write', or `fsync'. |
| |
| The function can return `ENOSYS' if it is not implemented. It |
| could also return `EINVAL' if the AIOCBP parameter does not refer |
| to an asynchronous operation whose return status is not yet known. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is in fact `aio_error64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_error64 (const struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `aio_error' with the only difference |
| that the argument is a reference to a variable of type `struct |
| aiocb64'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is available under the name `aio_error' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| -- Function: ssize_t aio_return (struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function can be used to retrieve the return status of the |
| operation carried out by the request described in the variable |
| pointed to by AIOCBP. As long as the error status of this request |
| as returned by `aio_error' is `EINPROGRESS' the return value of |
| this function is undefined. |
| |
| Once the request is finished this function can be used exactly |
| once to retrieve the return value. Following calls might lead to |
| undefined behavior. The return value itself is the value which |
| would have been returned by the `read', `write', or `fsync' call. |
| |
| The function can return `ENOSYS' if it is not implemented. It |
| could also return `EINVAL' if the AIOCBP parameter does not refer |
| to an asynchronous operation whose return status is not yet known. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is in fact `aio_return64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: ssize_t aio_return64 (struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to `aio_return' with the only difference |
| that the argument is a reference to a variable of type `struct |
| aiocb64'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is available under the name `aio_return' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| |
| File: libc.info, Node: Synchronizing AIO Operations, Next: Cancel AIO Operations, Prev: Status of AIO Operations, Up: Asynchronous I/O |
| |
| 13.11.3 Getting into a Consistent State |
| --------------------------------------- |
| |
| When dealing with asynchronous operations it is sometimes necessary to |
| get into a consistent state. This would mean for AIO that one wants to |
| know whether a certain request or a group of requests were processed. |
| This could be done by waiting for the notification sent by the system |
| after the operation terminated, but this sometimes would mean wasting |
| resources (mainly computation time). Instead POSIX.1b defines two |
| functions which will help with most kinds of consistency. |
| |
| The `aio_fsync' and `aio_fsync64' functions are only available if |
| the symbol `_POSIX_SYNCHRONIZED_IO' is defined in `unistd.h'. |
| |
| -- Function: int aio_fsync (int OP, struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| Calling this function forces all I/O operations queued at the time |
| of the function call operating on the file descriptor |
| `aiocbp->aio_fildes' into the synchronized I/O completion state |
| (*note Synchronizing I/O::). The `aio_fsync' function returns |
| immediately but the notification through the method described in |
| `aiocbp->aio_sigevent' will happen only after all requests for this |
| file descriptor have terminated and the file is synchronized. |
| This also means that requests for this very same file descriptor |
| which are queued after the synchronization request are not |
| affected. |
| |
| If OP is `O_DSYNC' the synchronization happens as with a call to |
| `fdatasync'. Otherwise OP should be `O_SYNC' and the |
| synchronization happens as with `fsync'. |
| |
| As long as the synchronization has not happened, a call to |
| `aio_error' with the reference to the object pointed to by AIOCBP |
| returns `EINPROGRESS'. Once the synchronization is done |
| `aio_error' return 0 if the synchronization was not successful. |
| Otherwise the value returned is the value to which the `fsync' or |
| `fdatasync' function would have set the `errno' variable. In this |
| case nothing can be assumed about the consistency of the data |
| written to this file descriptor. |
| |
| The return value of this function is 0 if the request was |
| successfully enqueued. Otherwise the return value is -1 and |
| `errno' is set to one of the following values: |
| |
| `EAGAIN' |
| The request could not be enqueued due to temporary lack of |
| resources. |
| |
| `EBADF' |
| The file descriptor `AIOCBP->aio_fildes' is not valid. |
| |
| `EINVAL' |
| The implementation does not support I/O synchronization or |
| the OP parameter is other than `O_DSYNC' and `O_SYNC'. |
| |
| `ENOSYS' |
| This function is not implemented. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is in fact `aio_fsync64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_fsync64 (int OP, struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `aio_fsync' with the only difference |
| that the argument is a reference to a variable of type `struct |
| aiocb64'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is available under the name `aio_fsync' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| Another method of synchronization is to wait until one or more |
| requests of a specific set terminated. This could be achieved by the |
| `aio_*' functions to notify the initiating process about the |
| termination but in some situations this is not the ideal solution. In |
| a program which constantly updates clients somehow connected to the |
| server it is not always the best solution to go round robin since some |
| connections might be slow. On the other hand letting the `aio_*' |
| functions notify the caller might also be not the best solution since |
| whenever the process works on preparing data for a client it makes no |
| sense to be interrupted by a notification since the new client will not |
| be handled before the current client is served. For situations like |
| this `aio_suspend' should be used. |
| |
| -- Function: int aio_suspend (const struct aiocb *const LIST[], int |
| NENT, const struct timespec *TIMEOUT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| When calling this function, the calling thread is suspended until |
| at least one of the requests pointed to by the NENT elements of the |
| array LIST has completed. If any of the requests has already |
| completed at the time `aio_suspend' is called, the function returns |
| immediately. Whether a request has terminated or not is |
| determined by comparing the error status of the request with |
| `EINPROGRESS'. If an element of LIST is `NULL', the entry is |
| simply ignored. |
| |
| If no request has finished, the calling process is suspended. If |
| TIMEOUT is `NULL', the process is not woken until a request has |
| finished. If TIMEOUT is not `NULL', the process remains suspended |
| at least as long as specified in TIMEOUT. In this case, |
| `aio_suspend' returns with an error. |
| |
| The return value of the function is 0 if one or more requests from |
| the LIST have terminated. Otherwise the function returns -1 and |
| `errno' is set to one of the following values: |
| |
| `EAGAIN' |
| None of the requests from the LIST completed in the time |
| specified by TIMEOUT. |
| |
| `EINTR' |
| A signal interrupted the `aio_suspend' function. This signal |
| might also be sent by the AIO implementation while signalling |
| the termination of one of the requests. |
| |
| `ENOSYS' |
| The `aio_suspend' function is not implemented. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is in fact `aio_suspend64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_suspend64 (const struct aiocb64 *const LIST[], |
| int NENT, const struct timespec *TIMEOUT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function is similar to `aio_suspend' with the only difference |
| that the argument is a reference to a variable of type `struct |
| aiocb64'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64' this |
| function is available under the name `aio_suspend' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| |
| File: libc.info, Node: Cancel AIO Operations, Next: Configuration of AIO, Prev: Synchronizing AIO Operations, Up: Asynchronous I/O |
| |
| 13.11.4 Cancellation of AIO Operations |
| -------------------------------------- |
| |
| When one or more requests are asynchronously processed, it might be |
| useful in some situations to cancel a selected operation, e.g., if it |
| becomes obvious that the written data is no longer accurate and would |
| have to be overwritten soon. As an example, assume an application, |
| which writes data in files in a situation where new incoming data would |
| have to be written in a file which will be updated by an enqueued |
| request. The POSIX AIO implementation provides such a function, but |
| this function is not capable of forcing the cancellation of the |
| request. It is up to the implementation to decide whether it is |
| possible to cancel the operation or not. Therefore using this function |
| is merely a hint. |
| |
| -- Function: int aio_cancel (int FILDES, struct aiocb *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| The `aio_cancel' function can be used to cancel one or more |
| outstanding requests. If the AIOCBP parameter is `NULL', the |
| function tries to cancel all of the outstanding requests which |
| would process the file descriptor FILDES (i.e., whose `aio_fildes' |
| member is FILDES). If AIOCBP is not `NULL', `aio_cancel' attempts |
| to cancel the specific request pointed to by AIOCBP. |
| |
| For requests which were successfully canceled, the normal |
| notification about the termination of the request should take |
| place. I.e., depending on the `struct sigevent' object which |
| controls this, nothing happens, a signal is sent or a thread is |
| started. If the request cannot be canceled, it terminates the |
| usual way after performing the operation. |
| |
| After a request is successfully canceled, a call to `aio_error' |
| with a reference to this request as the parameter will return |
| `ECANCELED' and a call to `aio_return' will return -1. If the |
| request wasn't canceled and is still running the error status is |
| still `EINPROGRESS'. |
| |
| The return value of the function is `AIO_CANCELED' if there were |
| requests which haven't terminated and which were successfully |
| canceled. If there is one or more requests left which couldn't be |
| canceled, the return value is `AIO_NOTCANCELED'. In this case |
| `aio_error' must be used to find out which of the, perhaps |
| multiple, requests (if AIOCBP is `NULL') weren't successfully |
| canceled. If all requests already terminated at the time |
| `aio_cancel' is called the return value is `AIO_ALLDONE'. |
| |
| If an error occurred during the execution of `aio_cancel' the |
| function returns -1 and sets `errno' to one of the following |
| values. |
| |
| `EBADF' |
| The file descriptor FILDES is not valid. |
| |
| `ENOSYS' |
| `aio_cancel' is not implemented. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64', this |
| function is in fact `aio_cancel64' since the LFS interface |
| transparently replaces the normal implementation. |
| |
| -- Function: int aio_cancel64 (int FILDES, struct aiocb64 *AIOCBP) |
| Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
| | *Note POSIX Safety Concepts::. |
| |
| This function is similar to `aio_cancel' with the only difference |
| that the argument is a reference to a variable of type `struct |
| aiocb64'. |
| |
| When the sources are compiled with `_FILE_OFFSET_BITS == 64', this |
| function is available under the name `aio_cancel' and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| |
| |
| File: libc.info, Node: Configuration of AIO, Prev: Cancel AIO Operations, Up: Asynchronous I/O |
| |
| 13.11.5 How to optimize the AIO implementation |
| ---------------------------------------------- |
| |
| The POSIX standard does not specify how the AIO functions are |
| implemented. They could be system calls, but it is also possible to |
| emulate them at userlevel. |
| |
| At the time of writing, the available implementation is a user-level |
| implementation which uses threads for handling the enqueued requests. |
| While this implementation requires making some decisions about |
| limitations, hard limitations are something best avoided in the GNU C |
| Library. Therefore, the GNU C Library provides a means for tuning the |
| AIO implementation according to the individual use. |
| |
| -- Data Type: struct aioinit |
| This data type is used to pass the configuration or tunable |
| parameters to the implementation. The program has to initialize |
| the members of this struct and pass it to the implementation using |
| the `aio_init' function. |
| |
| `int aio_threads' |
| This member specifies the maximal number of threads which may |
| be used at any one time. |
| |
| `int aio_num' |
| This number provides an estimate on the maximal number of |
| simultaneously enqueued requests. |
| |
| `int aio_locks' |
| Unused. |
| |
| `int aio_usedba' |
| Unused. |
| |
| `int aio_debug' |
| Unused. |
| |
| `int aio_numusers' |
| Unused. |
| |
| `int aio_reserved[2]' |
| Unused. |
| |
| -- Function: void aio_init (const struct aioinit *INIT) |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| This function must be called before any other AIO function. |
| Calling it is completely voluntary, as it is only meant to help |
| the AIO implementation perform better. |
| |
| Before calling `aio_init', the members of a variable of type |
| `struct aioinit' must be initialized. Then a reference to this |
| variable is passed as the parameter to `aio_init' which itself may |
| or may not pay attention to the hints. |
| |
| The function has no return value and no error cases are defined. |
| It is an extension which follows a proposal from the SGI |
| implementation in Irix 6. It is not covered by POSIX.1b or Unix98. |
| |
| |
| File: libc.info, Node: Control Operations, Next: Duplicating Descriptors, Prev: Asynchronous I/O, Up: Low-Level I/O |
| |
| 13.12 Control Operations on Files |
| ================================= |
| |
| This section describes how you can perform various other operations on |
| file descriptors, such as inquiring about or setting flags describing |
| the status of the file descriptor, manipulating record locks, and the |
| like. All of these operations are performed by the function `fcntl'. |
| |
| The second argument to the `fcntl' function is a command that |
| specifies which operation to perform. The function and macros that name |
| various flags that are used with it are declared in the header file |
| `fcntl.h'. Many of these flags are also used by the `open' function; |
| see *note Opening and Closing Files::. |
| |
| -- Function: int fcntl (int FILEDES, int COMMAND, ...) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `fcntl' function performs the operation specified by COMMAND |
| on the file descriptor FILEDES. Some commands require additional |
| arguments to be supplied. These additional arguments and the |
| return value and error conditions are given in the detailed |
| descriptions of the individual commands. |
| |
| Briefly, here is a list of what the various commands are. |
| |
| `F_DUPFD' |
| Duplicate the file descriptor (return another file descriptor |
| pointing to the same open file). *Note Duplicating |
| Descriptors::. |
| |
| `F_GETFD' |
| Get flags associated with the file descriptor. *Note |
| Descriptor Flags::. |
| |
| `F_SETFD' |
| Set flags associated with the file descriptor. *Note |
| Descriptor Flags::. |
| |
| `F_GETFL' |
| Get flags associated with the open file. *Note File Status |
| Flags::. |
| |
| `F_SETFL' |
| Set flags associated with the open file. *Note File Status |
| Flags::. |
| |
| `F_GETLK' |
| Test a file lock. *Note File Locks::. |
| |
| `F_SETLK' |
| Set or clear a file lock. *Note File Locks::. |
| |
| `F_SETLKW' |
| Like `F_SETLK', but wait for completion. *Note File Locks::. |
| |
| `F_OFD_GETLK' |
| Test an open file description lock. *Note Open File |
| Description Locks::. Specific to Linux. |
| |
| `F_OFD_SETLK' |
| Set or clear an open file description lock. *Note Open File |
| Description Locks::. Specific to Linux. |
| |
| `F_OFD_SETLKW' |
| Like `F_OFD_SETLK', but block until lock is acquired. *Note |
| Open File Description Locks::. Specific to Linux. |
| |
| `F_GETOWN' |
| Get process or process group ID to receive `SIGIO' signals. |
| *Note Interrupt Input::. |
| |
| `F_SETOWN' |
| Set process or process group ID to receive `SIGIO' signals. |
| *Note Interrupt Input::. |
| |
| This function is a cancellation point in multi-threaded programs |
| for the commands `F_SETLKW' (and the LFS analogous `F_SETLKW64') |
| and `F_OFD_SETLKW'. This is a problem if the thread allocates some |
| resources (like memory, file descriptors, semaphores or whatever) |
| at the time `fcntl' is called. If the thread gets canceled these |
| resources stay allocated until the program ends. To avoid this |
| calls to `fcntl' should be protected using cancellation handlers. |
| |
| |
| File: libc.info, Node: Duplicating Descriptors, Next: Descriptor Flags, Prev: Control Operations, Up: Low-Level I/O |
| |
| 13.13 Duplicating Descriptors |
| ============================= |
| |
| You can "duplicate" a file descriptor, or allocate another file |
| descriptor that refers to the same open file as the original. Duplicate |
| descriptors share one file position and one set of file status flags |
| (*note File Status Flags::), but each has its own set of file descriptor |
| flags (*note Descriptor Flags::). |
| |
| The major use of duplicating a file descriptor is to implement |
| "redirection" of input or output: that is, to change the file or pipe |
| that a particular file descriptor corresponds to. |
| |
| You can perform this operation using the `fcntl' function with the |
| `F_DUPFD' command, but there are also convenient functions `dup' and |
| `dup2' for duplicating descriptors. |
| |
| The `fcntl' function and flags are declared in `fcntl.h', while |
| prototypes for `dup' and `dup2' are in the header file `unistd.h'. |
| |
| -- Function: int dup (int OLD) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function copies descriptor OLD to the first available |
| descriptor number (the first number not currently open). It is |
| equivalent to `fcntl (OLD, F_DUPFD, 0)'. |
| |
| -- Function: int dup2 (int OLD, int NEW) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function copies the descriptor OLD to descriptor number NEW. |
| |
| If OLD is an invalid descriptor, then `dup2' does nothing; it does |
| not close NEW. Otherwise, the new duplicate of OLD replaces any |
| previous meaning of descriptor NEW, as if NEW were closed first. |
| |
| If OLD and NEW are different numbers, and OLD is a valid |
| descriptor number, then `dup2' is equivalent to: |
| |
| close (NEW); |
| fcntl (OLD, F_DUPFD, NEW) |
| |
| However, `dup2' does this atomically; there is no instant in the |
| middle of calling `dup2' at which NEW is closed and not yet a |
| duplicate of OLD. |
| |
| -- Macro: int F_DUPFD |
| This macro is used as the COMMAND argument to `fcntl', to copy the |
| file descriptor given as the first argument. |
| |
| The form of the call in this case is: |
| |
| fcntl (OLD, F_DUPFD, NEXT-FILEDES) |
| |
| The NEXT-FILEDES argument is of type `int' and specifies that the |
| file descriptor returned should be the next available one greater |
| than or equal to this value. |
| |
| The return value from `fcntl' with this command is normally the |
| value of the new file descriptor. A return value of -1 indicates |
| an error. The following `errno' error conditions are defined for |
| this command: |
| |
| `EBADF' |
| The OLD argument is invalid. |
| |
| `EINVAL' |
| The NEXT-FILEDES argument is invalid. |
| |
| `EMFILE' |
| There are no more file descriptors available--your program is |
| already using the maximum. In BSD and GNU, the maximum is |
| controlled by a resource limit that can be changed; *note |
| Limits on Resources::, for more information about the |
| `RLIMIT_NOFILE' limit. |
| |
| `ENFILE' is not a possible error code for `dup2' because `dup2' |
| does not create a new opening of a file; duplicate descriptors do |
| not count toward the limit which `ENFILE' indicates. `EMFILE' is |
| possible because it refers to the limit on distinct descriptor |
| numbers in use in one process. |
| |
| Here is an example showing how to use `dup2' to do redirection. |
| Typically, redirection of the standard streams (like `stdin') is done |
| by a shell or shell-like program before calling one of the `exec' |
| functions (*note Executing a File::) to execute a new program in a |
| child process. When the new program is executed, it creates and |
| initializes the standard streams to point to the corresponding file |
| descriptors, before its `main' function is invoked. |
| |
| So, to redirect standard input to a file, the shell could do |
| something like: |
| |
| pid = fork (); |
| if (pid == 0) |
| { |
| char *filename; |
| char *program; |
| int file; |
| ... |
| file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY)); |
| dup2 (file, STDIN_FILENO); |
| TEMP_FAILURE_RETRY (close (file)); |
| execv (program, NULL); |
| } |
| |
| There is also a more detailed example showing how to implement |
| redirection in the context of a pipeline of processes in *note |
| Launching Jobs::. |
| |
| |
| File: libc.info, Node: Descriptor Flags, Next: File Status Flags, Prev: Duplicating Descriptors, Up: Low-Level I/O |
| |
| 13.14 File Descriptor Flags |
| =========================== |
| |
| "File descriptor flags" are miscellaneous attributes of a file |
| descriptor. These flags are associated with particular file |
| descriptors, so that if you have created duplicate file descriptors |
| from a single opening of a file, each descriptor has its own set of |
| flags. |
| |
| Currently there is just one file descriptor flag: `FD_CLOEXEC', |
| which causes the descriptor to be closed if you use any of the |
| `exec...' functions (*note Executing a File::). |
| |
| The symbols in this section are defined in the header file `fcntl.h'. |
| |
| -- Macro: int F_GETFD |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should return the file descriptor flags associated with |
| the FILEDES argument. |
| |
| The normal return value from `fcntl' with this command is a |
| nonnegative number which can be interpreted as the bitwise OR of |
| the individual flags (except that currently there is only one flag |
| to use). |
| |
| In case of an error, `fcntl' returns -1. The following `errno' |
| error conditions are defined for this command: |
| |
| `EBADF' |
| The FILEDES argument is invalid. |
| |
| -- Macro: int F_SETFD |
| This macro is used as the COMMAND argument to `fcntl', to specify |
| that it should set the file descriptor flags associated with the |
| FILEDES argument. This requires a third `int' argument to specify |
| the new flags, so the form of the call is: |
| |
| fcntl (FILEDES, F_SETFD, NEW-FLAGS) |
| |
| The normal return value from `fcntl' with this command is an |
| unspecified value other than -1, which indicates an error. The |
| flags and error conditions are the same as for the `F_GETFD' |
| command. |
| |
| The following macro is defined for use as a file descriptor flag with |
| the `fcntl' function. The value is an integer constant usable as a bit |
| mask value. |
| |
| -- Macro: int FD_CLOEXEC |
| This flag specifies that the file descriptor should be closed when |
| an `exec' function is invoked; see *note Executing a File::. When |
| a file descriptor is allocated (as with `open' or `dup'), this bit |
| is initially cleared on the new file descriptor, meaning that |
| descriptor will survive into the new program after `exec'. |
| |
| If you want to modify the file descriptor flags, you should get the |
| current flags with `F_GETFD' and modify the value. Don't assume that |
| the flags listed here are the only ones that are implemented; your |
| program may be run years from now and more flags may exist then. For |
| example, here is a function to set or clear the flag `FD_CLOEXEC' |
| without altering any other flags: |
| |
| /* Set the `FD_CLOEXEC' flag of DESC if VALUE is nonzero, |
| or clear the flag if VALUE is 0. |
| Return 0 on success, or -1 on error with `errno' set. */ |
| |
| int |
| set_cloexec_flag (int desc, int value) |
| { |
| int oldflags = fcntl (desc, F_GETFD, 0); |
| /* If reading the flags failed, return error indication now. */ |
| if (oldflags < 0) |
| return oldflags; |
| /* Set just the flag we want to set. */ |
| if (value != 0) |
| oldflags |= FD_CLOEXEC; |
| else |
| oldflags &= ~FD_CLOEXEC; |
| /* Store modified flag word in the descriptor. */ |
| return fcntl (desc, F_SETFD, oldflags); |
| } |
| |
| |
| File: libc.info, Node: File Status Flags, Next: File Locks, Prev: Descriptor Flags, Up: Low-Level I/O |
| |
| 13.15 File Status Flags |
| ======================= |
| |
| "File status flags" are used to specify attributes of the opening of a |
| file. Unlike the file descriptor flags discussed in *note Descriptor |
| Flags::, the file status flags are shared by duplicated file descriptors |
| resulting from a single opening of the file. The file status flags are |
| specified with the FLAGS argument to `open'; *note Opening and Closing |
| Files::. |
| |
| File status flags fall into three categories, which are described in |
| the following sections. |
| |
| * *note Access Modes::, specify what type of access is allowed to the |
| file: reading, writing, or both. They are set by `open' and are |
| returned by `fcntl', but cannot be changed. |
| |
| * *note Open-time Flags::, control details of what `open' will do. |
| These flags are not preserved after the `open' call. |
| |
| * *note Operating Modes::, affect how operations such as `read' and |
| `write' are done. They are set by `open', and can be fetched or |
| changed with `fcntl'. |
| |
| The symbols in this section are defined in the header file `fcntl.h'. |
| |
| * Menu: |
| |
| * Access Modes:: Whether the descriptor can read or write. |
| * Open-time Flags:: Details of `open'. |
| * Operating Modes:: Special modes to control I/O operations. |
| * Getting File Status Flags:: Fetching and changing these flags. |
| |
| |
| File: libc.info, Node: Access Modes, Next: Open-time Flags, Up: File Status Flags |
| |
| 13.15.1 File Access Modes |
| ------------------------- |
| |
| The file access 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.15.2 Open-time Flags |
| ----------------------- |
| |
| The open-time flags specify options affecting how `open' will behave. |
| These options are not preserved once the file is open. The exception to |
| this is `O_NONBLOCK', which is also an I/O operating mode and so it |
| _is_ saved. *Note Opening and Closing Files::, for how to call `open'. |
| |
| There are two sorts of options specified by open-time flags. |
| |
| * "File name translation flags" affect how `open' looks up the file |
| name to locate the file, and whether the file can be created. |
| |
| * "Open-time action flags" specify extra operations that `open' will |
| perform on the file once it is open. |
| |
| Here are the file name translation flags. |
| |
| -- Macro: int O_CREAT |
| If set, the file will be created if it doesn't already exist. |
| |
| -- Macro: int O_EXCL |
| If both `O_CREAT' and `O_EXCL' are set, then `open' fails if the |
| specified file already exists. This is guaranteed to never |
| clobber an existing file. |
| |
| The `O_EXCL' flag has a special meaning in combination with |
| `O_TMPFILE'; see below. |
| |
| -- Macro: int O_DIRECTORY |
| If set, the open operation fails if the given name is not the name |
| of a directory. The `errno' variable is set to `ENOTDIR' for this |
| error condition. |
| |
| -- Macro: int O_TMPFILE |
| If this flag is specified, functions in the `open' family create an |
| unnamed temporary file. In this case, the pathname argument to the |
| `open' family of functions (*note Opening and Closing Files::) is |
| interpreted as the directory in which the temporary file is created |
| (thus determining the file system which provides the storage for |
| the file). The `O_TMPFILE' flag must be combined with `O_WRONLY' |
| or `O_RDWR', and the MODE argument is required. |
| |
| The temporary file can later be given a name using `linkat', |
| turning it into a regular file. This allows the atomic creation |
| of a file with the specific file attributes (mode and extended |
| attributes) and file contents. If, for security reasons, it is |
| not desirable that a name can be given to the file, the `O_EXCL' |
| flag can be specified along with `O_TMPFILE'. |
| |
| Not all kernels support this open flag. If this flag is |
| unsupported, an attempt to create an unnamed temporary file fails |
| with an error of `EINVAL'. If the underlying file system does not |
| support the `O_TMPFILE' flag, an `EOPNOTSUPP' error is the result. |
| |
| The `O_TMPFILE' flag is a GNU extension. |
| |
| -- Macro: int O_NONBLOCK |
| This prevents `open' from blocking for a "long time" to open the |
| file. This is only meaningful for some kinds of files, usually |
| devices such as serial ports; when it is not meaningful, it is |
| harmless and ignored. Often, opening a port to a modem blocks |
| until the modem reports carrier detection; if `O_NONBLOCK' is |
| specified, `open' will return immediately without a carrier. |
| |
| Note that the `O_NONBLOCK' flag is overloaded as both an I/O |
| operating mode and a file name translation flag. This means that |
| specifying `O_NONBLOCK' in `open' also sets nonblocking I/O mode; |
| *note Operating Modes::. To open the file without blocking but do |
| normal I/O that blocks, you must call `open' with `O_NONBLOCK' set |
| and then call `fcntl' to turn the bit off. |
| |
| -- Macro: int O_NOCTTY |
| If the named file is a terminal device, don't make it the |
| controlling terminal for the process. *Note Job Control::, for |
| information about what it means to be the controlling terminal. |
| |
| On GNU/Hurd systems and 4.4 BSD, opening a file never makes it the |
| controlling terminal and `O_NOCTTY' is zero. However, GNU/Linux |
| systems and some other systems use a nonzero value for `O_NOCTTY' |
| and set the controlling terminal when you open a file that is a |
| terminal device; so to be portable, use `O_NOCTTY' when it is |
| important to avoid this. |
| |
| The following three file name translation flags exist only on |
| GNU/Hurd systems. |
| |
| -- Macro: int O_IGNORE_CTTY |
| Do not recognize the named file as the controlling terminal, even |
| if it refers to the process's existing controlling terminal |
| device. Operations on the new file descriptor will never induce |
| job control signals. *Note Job Control::. |
| |
| -- Macro: int O_NOLINK |
| If the named file is a symbolic link, open the link itself instead |
| of the file it refers to. (`fstat' on the new file descriptor will |
| return the information returned by `lstat' on the link's name.) |
| |
| -- Macro: int O_NOTRANS |
| If the named file is specially translated, do not invoke the |
| translator. Open the bare file the translator itself sees. |
| |
| The open-time action flags tell `open' to do additional operations |
| which are not really related to opening the file. The reason to do them |
| as part of `open' instead of in separate calls is that `open' can do |
| them atomically. |
| |
| -- Macro: int O_TRUNC |
| Truncate the file to zero length. This option is only useful for |
| regular files, not special files such as directories or FIFOs. |
| POSIX.1 requires that you open the file for writing to use |
| `O_TRUNC'. In BSD and GNU you must have permission to write the |
| file to truncate it, but you need not open for write access. |
| |
| This is the only open-time action flag specified by POSIX.1. |
| There is no good reason for truncation to be done by `open', |
| instead of by calling `ftruncate' afterwards. The `O_TRUNC' flag |
| existed in Unix before `ftruncate' was invented, and is retained |
| for backward compatibility. |
| |
| The remaining operating modes are BSD extensions. They exist only |
| on some systems. On other systems, these macros are not defined. |
| |
| -- Macro: int O_SHLOCK |
| Acquire a shared lock on the file, as with `flock'. *Note File |
| Locks::. |
| |
| If `O_CREAT' is specified, the locking is done atomically when |
| creating the file. You are guaranteed that no other process will |
| get the lock on the new file first. |
| |
| -- Macro: int O_EXLOCK |
| Acquire an exclusive lock on the file, as with `flock'. *Note |
| File Locks::. This is atomic like `O_SHLOCK'. |
| |
| |
| File: libc.info, Node: Operating Modes, Next: Getting File Status Flags, Prev: Open-time Flags, Up: File Status Flags |
| |
| 13.15.3 I/O Operating Modes |
| --------------------------- |
| |
| The operating modes affect how input and output operations using a file |
| descriptor work. These flags are set by `open' and can be fetched and |
| changed with `fcntl'. |
| |
| -- Macro: int O_APPEND |
| The bit that enables append mode for the file. If set, then all |
| `write' operations write the data at the end of the file, extending |
| it, regardless of the current file position. This is the only |
| reliable way to append to a file. In append mode, you are |
| guaranteed that the data you write will always go to the current |
| end of the file, regardless of other processes writing to the |
| file. Conversely, if you simply set the file position to the end |
| of file and write, then another process can extend the file after |
| you set the file position but before you write, resulting in your |
| data appearing someplace before the real end of file. |
| |
| -- Macro: int O_NONBLOCK |
| The bit that enables nonblocking mode for the file. If this bit |
| is set, `read' requests on the file can return immediately with a |
| failure status if there is no input immediately available, instead |
| of blocking. Likewise, `write' requests can also return |
| immediately with a failure status if the output can't be written |
| immediately. |
| |
| Note that the `O_NONBLOCK' flag is overloaded as both an I/O |
| operating mode and a file name translation flag; *note Open-time |
| Flags::. |
| |
| -- Macro: int O_NDELAY |
| This is an obsolete name for `O_NONBLOCK', provided for |
| compatibility with BSD. It is not defined by the POSIX.1 standard. |
| |
| The remaining operating modes are BSD and GNU extensions. They |
| exist only on some systems. On other systems, these macros are not |
| defined. |
| |
| -- Macro: int O_ASYNC |
| The bit that enables asynchronous input mode. If set, then `SIGIO' |
| signals will be generated when input is available. *Note |
| Interrupt Input::. |
| |
| Asynchronous input mode is a BSD feature. |
| |
| -- Macro: int O_FSYNC |
| The bit that enables synchronous writing for the file. If set, |
| each `write' call will make sure the data is reliably stored on |
| disk before returning. Synchronous writing is a BSD feature. |
| |
| -- Macro: int O_SYNC |
| This is another name for `O_FSYNC'. They have the same value. |
| |
| -- Macro: int O_NOATIME |
| If this bit is set, `read' will not update the access time of the |
| file. *Note File Times::. This is used by programs that do |
| backups, so that backing a file up does not count as reading it. |
| Only the owner of the file or the superuser may use this bit. |
| |
| This is a GNU extension. |
| |
| |
| File: libc.info, Node: Getting File Status Flags, Prev: Operating Modes, Up: File Status Flags |
| |
| 13.15.4 Getting and Setting File Status Flags |
| --------------------------------------------- |
| |
| The `fcntl' function can fetch or change file status flags. |
| |
| -- Macro: int F_GETFL |
| This macro is used as the COMMAND argument to `fcntl', to read the |
| file status flags for the open file with descriptor FILEDES. |
| |
| The normal return value from `fcntl' with this command is a |
| nonnegative number which can be interpreted as the bitwise OR of |
| the individual flags. Since the file access modes are not |
| single-bit values, you can mask off other bits in the returned |
| flags with `O_ACCMODE' to compare them. |
| |
| In case of an error, `fcntl' returns -1. The following `errno' |
| error conditions are defined for this command: |
| |
| `EBADF' |
| The FILEDES argument is invalid. |
| |
| -- Macro: int F_SETFL |
| This macro is used as the COMMAND argument to `fcntl', to set the |
| file status flags for the open file corresponding to the FILEDES |
| argument. This command requires a third `int' argument to specify |
| the new flags, so the call looks like this: |
| |
| fcntl (FILEDES, F_SETFL, NEW-FLAGS) |
| |
| You can't change the access mode for the file in this way; that is, |
| whether the file descriptor was opened for reading or writing. |
| |
| The normal return value from `fcntl' with this command is an |
| unspecified value other than -1, which indicates an error. The |
| error conditions are the same as for the `F_GETFL' command. |
| |
| If you want to modify the file status flags, you should get the |
| current flags with `F_GETFL' and modify the value. Don't assume that |
| the flags listed here are the only ones that are implemented; your |
| program may be run years from now and more flags may exist then. For |
| example, here is a function to set or clear the flag `O_NONBLOCK' |
| without altering any other flags: |
| |
| /* Set the `O_NONBLOCK' flag of DESC if VALUE is nonzero, |
| or clear the flag if VALUE is 0. |
| Return 0 on success, or -1 on error with `errno' set. */ |
| |
| int |
| set_nonblock_flag (int desc, int value) |
| { |
| int oldflags = fcntl (desc, F_GETFL, 0); |
| /* If reading the flags failed, return error indication now. */ |
| if (oldflags == -1) |
| return -1; |
| /* Set just the flag we want to set. */ |
| if (value != 0) |
| oldflags |= O_NONBLOCK; |
| else |
| oldflags &= ~O_NONBLOCK; |
| /* Store modified flag word in the descriptor. */ |
| return fcntl (desc, F_SETFL, oldflags); |
| } |
| |
| |
| |
| Local Variables: |
| coding: utf-8 |
| End: |
