This is libc.info, produced by makeinfo version 5.1 from libc.texinfo.
|
|
This is ‘The GNU C Library Reference Manual’, for version 2.33 (GNU).
|
|
Copyright © 1993–2021 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being “Free Software Needs Free Documentation” and
|
“GNU Lesser General Public License”, the Front-Cover texts being “A GNU
|
Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
|
license is included in the section entitled "GNU Free Documentation
|
License".
|
|
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
|
modify this GNU manual. Buying copies from the FSF supports it in
|
developing GNU and promoting software freedom.”
|
INFO-DIR-SECTION Software libraries
|
START-INFO-DIR-ENTRY
|
* Libc: (libc). C library.
|
END-INFO-DIR-ENTRY
|
|
INFO-DIR-SECTION GNU C library functions and macros
|
START-INFO-DIR-ENTRY
|
* ALTWERASE: (libc)Local Modes.
|
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
|
* ARG_MAX: (libc)General Limits.
|
* BC_BASE_MAX: (libc)Utility Limits.
|
* BC_DIM_MAX: (libc)Utility Limits.
|
* BC_SCALE_MAX: (libc)Utility Limits.
|
* BC_STRING_MAX: (libc)Utility Limits.
|
* BRKINT: (libc)Input Modes.
|
* BUFSIZ: (libc)Controlling Buffering.
|
* CCTS_OFLOW: (libc)Control Modes.
|
* CHAR_BIT: (libc)Width of Type.
|
* CHILD_MAX: (libc)General Limits.
|
* CIGNORE: (libc)Control Modes.
|
* CLK_TCK: (libc)Processor Time.
|
* CLOCAL: (libc)Control Modes.
|
* CLOCKS_PER_SEC: (libc)CPU Time.
|
* CLOCK_MONOTONIC: (libc)Getting the Time.
|
* CLOCK_REALTIME: (libc)Getting the Time.
|
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
|
* CPU_CLR: (libc)CPU Affinity.
|
* CPU_FEATURE_USABLE: (libc)X86.
|
* CPU_ISSET: (libc)CPU Affinity.
|
* CPU_SET: (libc)CPU Affinity.
|
* CPU_SETSIZE: (libc)CPU Affinity.
|
* CPU_ZERO: (libc)CPU Affinity.
|
* CREAD: (libc)Control Modes.
|
* CRTS_IFLOW: (libc)Control Modes.
|
* CS5: (libc)Control Modes.
|
* CS6: (libc)Control Modes.
|
* CS7: (libc)Control Modes.
|
* CS8: (libc)Control Modes.
|
* CSIZE: (libc)Control Modes.
|
* CSTOPB: (libc)Control Modes.
|
* DTTOIF: (libc)Directory Entries.
|
* E2BIG: (libc)Error Codes.
|
* EACCES: (libc)Error Codes.
|
* EADDRINUSE: (libc)Error Codes.
|
* EADDRNOTAVAIL: (libc)Error Codes.
|
* EADV: (libc)Error Codes.
|
* EAFNOSUPPORT: (libc)Error Codes.
|
* EAGAIN: (libc)Error Codes.
|
* EALREADY: (libc)Error Codes.
|
* EAUTH: (libc)Error Codes.
|
* EBACKGROUND: (libc)Error Codes.
|
* EBADE: (libc)Error Codes.
|
* EBADF: (libc)Error Codes.
|
* EBADFD: (libc)Error Codes.
|
* EBADMSG: (libc)Error Codes.
|
* EBADR: (libc)Error Codes.
|
* EBADRPC: (libc)Error Codes.
|
* EBADRQC: (libc)Error Codes.
|
* EBADSLT: (libc)Error Codes.
|
* EBFONT: (libc)Error Codes.
|
* EBUSY: (libc)Error Codes.
|
* ECANCELED: (libc)Error Codes.
|
* ECHILD: (libc)Error Codes.
|
* ECHO: (libc)Local Modes.
|
* ECHOCTL: (libc)Local Modes.
|
* ECHOE: (libc)Local Modes.
|
* ECHOK: (libc)Local Modes.
|
* ECHOKE: (libc)Local Modes.
|
* ECHONL: (libc)Local Modes.
|
* ECHOPRT: (libc)Local Modes.
|
* ECHRNG: (libc)Error Codes.
|
* ECOMM: (libc)Error Codes.
|
* ECONNABORTED: (libc)Error Codes.
|
* ECONNREFUSED: (libc)Error Codes.
|
* ECONNRESET: (libc)Error Codes.
|
* ED: (libc)Error Codes.
|
* EDEADLK: (libc)Error Codes.
|
* EDEADLOCK: (libc)Error Codes.
|
* EDESTADDRREQ: (libc)Error Codes.
|
* EDIED: (libc)Error Codes.
|
* EDOM: (libc)Error Codes.
|
* EDOTDOT: (libc)Error Codes.
|
* EDQUOT: (libc)Error Codes.
|
* EEXIST: (libc)Error Codes.
|
* EFAULT: (libc)Error Codes.
|
* EFBIG: (libc)Error Codes.
|
* EFTYPE: (libc)Error Codes.
|
* EGRATUITOUS: (libc)Error Codes.
|
* EGREGIOUS: (libc)Error Codes.
|
* EHOSTDOWN: (libc)Error Codes.
|
* EHOSTUNREACH: (libc)Error Codes.
|
* EHWPOISON: (libc)Error Codes.
|
* EIDRM: (libc)Error Codes.
|
* EIEIO: (libc)Error Codes.
|
* EILSEQ: (libc)Error Codes.
|
* EINPROGRESS: (libc)Error Codes.
|
* EINTR: (libc)Error Codes.
|
* EINVAL: (libc)Error Codes.
|
* EIO: (libc)Error Codes.
|
* EISCONN: (libc)Error Codes.
|
* EISDIR: (libc)Error Codes.
|
* EISNAM: (libc)Error Codes.
|
* EKEYEXPIRED: (libc)Error Codes.
|
* EKEYREJECTED: (libc)Error Codes.
|
* EKEYREVOKED: (libc)Error Codes.
|
* EL2HLT: (libc)Error Codes.
|
* EL2NSYNC: (libc)Error Codes.
|
* EL3HLT: (libc)Error Codes.
|
* EL3RST: (libc)Error Codes.
|
* ELIBACC: (libc)Error Codes.
|
* ELIBBAD: (libc)Error Codes.
|
* ELIBEXEC: (libc)Error Codes.
|
* ELIBMAX: (libc)Error Codes.
|
* ELIBSCN: (libc)Error Codes.
|
* ELNRNG: (libc)Error Codes.
|
* ELOOP: (libc)Error Codes.
|
* EMEDIUMTYPE: (libc)Error Codes.
|
* EMFILE: (libc)Error Codes.
|
* EMLINK: (libc)Error Codes.
|
* EMSGSIZE: (libc)Error Codes.
|
* EMULTIHOP: (libc)Error Codes.
|
* ENAMETOOLONG: (libc)Error Codes.
|
* ENAVAIL: (libc)Error Codes.
|
* ENEEDAUTH: (libc)Error Codes.
|
* ENETDOWN: (libc)Error Codes.
|
* ENETRESET: (libc)Error Codes.
|
* ENETUNREACH: (libc)Error Codes.
|
* ENFILE: (libc)Error Codes.
|
* ENOANO: (libc)Error Codes.
|
* ENOBUFS: (libc)Error Codes.
|
* ENOCSI: (libc)Error Codes.
|
* ENODATA: (libc)Error Codes.
|
* ENODEV: (libc)Error Codes.
|
* ENOENT: (libc)Error Codes.
|
* ENOEXEC: (libc)Error Codes.
|
* ENOKEY: (libc)Error Codes.
|
* ENOLCK: (libc)Error Codes.
|
* ENOLINK: (libc)Error Codes.
|
* ENOMEDIUM: (libc)Error Codes.
|
* ENOMEM: (libc)Error Codes.
|
* ENOMSG: (libc)Error Codes.
|
* ENONET: (libc)Error Codes.
|
* ENOPKG: (libc)Error Codes.
|
* ENOPROTOOPT: (libc)Error Codes.
|
* ENOSPC: (libc)Error Codes.
|
* ENOSR: (libc)Error Codes.
|
* ENOSTR: (libc)Error Codes.
|
* ENOSYS: (libc)Error Codes.
|
* ENOTBLK: (libc)Error Codes.
|
* ENOTCONN: (libc)Error Codes.
|
* ENOTDIR: (libc)Error Codes.
|
* ENOTEMPTY: (libc)Error Codes.
|
* ENOTNAM: (libc)Error Codes.
|
* ENOTRECOVERABLE: (libc)Error Codes.
|
* ENOTSOCK: (libc)Error Codes.
|
* ENOTSUP: (libc)Error Codes.
|
* ENOTTY: (libc)Error Codes.
|
* ENOTUNIQ: (libc)Error Codes.
|
* ENXIO: (libc)Error Codes.
|
* EOF: (libc)EOF and Errors.
|
* EOPNOTSUPP: (libc)Error Codes.
|
* EOVERFLOW: (libc)Error Codes.
|
* EOWNERDEAD: (libc)Error Codes.
|
* EPERM: (libc)Error Codes.
|
* EPFNOSUPPORT: (libc)Error Codes.
|
* EPIPE: (libc)Error Codes.
|
* EPROCLIM: (libc)Error Codes.
|
* EPROCUNAVAIL: (libc)Error Codes.
|
* EPROGMISMATCH: (libc)Error Codes.
|
* EPROGUNAVAIL: (libc)Error Codes.
|
* EPROTO: (libc)Error Codes.
|
* EPROTONOSUPPORT: (libc)Error Codes.
|
* EPROTOTYPE: (libc)Error Codes.
|
* EQUIV_CLASS_MAX: (libc)Utility Limits.
|
* ERANGE: (libc)Error Codes.
|
* EREMCHG: (libc)Error Codes.
|
* EREMOTE: (libc)Error Codes.
|
* EREMOTEIO: (libc)Error Codes.
|
* ERESTART: (libc)Error Codes.
|
* ERFKILL: (libc)Error Codes.
|
* EROFS: (libc)Error Codes.
|
* ERPCMISMATCH: (libc)Error Codes.
|
* ESHUTDOWN: (libc)Error Codes.
|
* ESOCKTNOSUPPORT: (libc)Error Codes.
|
* ESPIPE: (libc)Error Codes.
|
* ESRCH: (libc)Error Codes.
|
* ESRMNT: (libc)Error Codes.
|
* ESTALE: (libc)Error Codes.
|
* ESTRPIPE: (libc)Error Codes.
|
* ETIME: (libc)Error Codes.
|
* ETIMEDOUT: (libc)Error Codes.
|
* ETOOMANYREFS: (libc)Error Codes.
|
* ETXTBSY: (libc)Error Codes.
|
* EUCLEAN: (libc)Error Codes.
|
* EUNATCH: (libc)Error Codes.
|
* EUSERS: (libc)Error Codes.
|
* EWOULDBLOCK: (libc)Error Codes.
|
* EXDEV: (libc)Error Codes.
|
* EXFULL: (libc)Error Codes.
|
* EXIT_FAILURE: (libc)Exit Status.
|
* EXIT_SUCCESS: (libc)Exit Status.
|
* EXPR_NEST_MAX: (libc)Utility Limits.
|
* FD_CLOEXEC: (libc)Descriptor Flags.
|
* FD_CLR: (libc)Waiting for I/O.
|
* FD_ISSET: (libc)Waiting for I/O.
|
* FD_SET: (libc)Waiting for I/O.
|
* FD_SETSIZE: (libc)Waiting for I/O.
|
* FD_ZERO: (libc)Waiting for I/O.
|
* FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
|
* FILENAME_MAX: (libc)Limits for Files.
|
* FLUSHO: (libc)Local Modes.
|
* FOPEN_MAX: (libc)Opening Streams.
|
* FP_ILOGB0: (libc)Exponents and Logarithms.
|
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
|
* FP_LLOGB0: (libc)Exponents and Logarithms.
|
* FP_LLOGBNAN: (libc)Exponents and Logarithms.
|
* F_DUPFD: (libc)Duplicating Descriptors.
|
* F_GETFD: (libc)Descriptor Flags.
|
* F_GETFL: (libc)Getting File Status Flags.
|
* F_GETLK: (libc)File Locks.
|
* F_GETOWN: (libc)Interrupt Input.
|
* F_OFD_GETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLKW: (libc)Open File Description Locks.
|
* F_OK: (libc)Testing File Access.
|
* F_SETFD: (libc)Descriptor Flags.
|
* F_SETFL: (libc)Getting File Status Flags.
|
* F_SETLK: (libc)File Locks.
|
* F_SETLKW: (libc)File Locks.
|
* F_SETOWN: (libc)Interrupt Input.
|
* HAS_CPU_FEATURE: (libc)X86.
|
* HUGE_VAL: (libc)Math Error Reporting.
|
* HUGE_VALF: (libc)Math Error Reporting.
|
* HUGE_VALL: (libc)Math Error Reporting.
|
* HUGE_VAL_FN: (libc)Math Error Reporting.
|
* HUGE_VAL_FNx: (libc)Math Error Reporting.
|
* HUPCL: (libc)Control Modes.
|
* I: (libc)Complex Numbers.
|
* ICANON: (libc)Local Modes.
|
* ICRNL: (libc)Input Modes.
|
* IEXTEN: (libc)Local Modes.
|
* IFNAMSIZ: (libc)Interface Naming.
|
* IFTODT: (libc)Directory Entries.
|
* IGNBRK: (libc)Input Modes.
|
* IGNCR: (libc)Input Modes.
|
* IGNPAR: (libc)Input Modes.
|
* IMAXBEL: (libc)Input Modes.
|
* INADDR_ANY: (libc)Host Address Data Type.
|
* INADDR_BROADCAST: (libc)Host Address Data Type.
|
* INADDR_LOOPBACK: (libc)Host Address Data Type.
|
* INADDR_NONE: (libc)Host Address Data Type.
|
* INFINITY: (libc)Infinity and NaN.
|
* INLCR: (libc)Input Modes.
|
* INPCK: (libc)Input Modes.
|
* IPPORT_RESERVED: (libc)Ports.
|
* IPPORT_USERRESERVED: (libc)Ports.
|
* ISIG: (libc)Local Modes.
|
* ISTRIP: (libc)Input Modes.
|
* IXANY: (libc)Input Modes.
|
* IXOFF: (libc)Input Modes.
|
* IXON: (libc)Input Modes.
|
* LINE_MAX: (libc)Utility Limits.
|
* LINK_MAX: (libc)Limits for Files.
|
* L_ctermid: (libc)Identifying the Terminal.
|
* L_cuserid: (libc)Who Logged In.
|
* L_tmpnam: (libc)Temporary Files.
|
* MAXNAMLEN: (libc)Limits for Files.
|
* MAXSYMLINKS: (libc)Symbolic Links.
|
* MAX_CANON: (libc)Limits for Files.
|
* MAX_INPUT: (libc)Limits for Files.
|
* MB_CUR_MAX: (libc)Selecting the Conversion.
|
* MB_LEN_MAX: (libc)Selecting the Conversion.
|
* MDMBUF: (libc)Control Modes.
|
* MSG_DONTROUTE: (libc)Socket Data Options.
|
* MSG_OOB: (libc)Socket Data Options.
|
* MSG_PEEK: (libc)Socket Data Options.
|
* NAME_MAX: (libc)Limits for Files.
|
* NAN: (libc)Infinity and NaN.
|
* NCCS: (libc)Mode Data Types.
|
* NGROUPS_MAX: (libc)General Limits.
|
* NOFLSH: (libc)Local Modes.
|
* NOKERNINFO: (libc)Local Modes.
|
* NSIG: (libc)Standard Signals.
|
* NULL: (libc)Null Pointer Constant.
|
* ONLCR: (libc)Output Modes.
|
* ONOEOT: (libc)Output Modes.
|
* OPEN_MAX: (libc)General Limits.
|
* OPOST: (libc)Output Modes.
|
* OXTABS: (libc)Output Modes.
|
* O_ACCMODE: (libc)Access Modes.
|
* O_APPEND: (libc)Operating Modes.
|
* O_ASYNC: (libc)Operating Modes.
|
* O_CREAT: (libc)Open-time Flags.
|
* O_DIRECTORY: (libc)Open-time Flags.
|
* O_EXCL: (libc)Open-time Flags.
|
* O_EXEC: (libc)Access Modes.
|
* O_EXLOCK: (libc)Open-time Flags.
|
* O_FSYNC: (libc)Operating Modes.
|
* O_IGNORE_CTTY: (libc)Open-time Flags.
|
* O_NDELAY: (libc)Operating Modes.
|
* O_NOATIME: (libc)Operating Modes.
|
* O_NOCTTY: (libc)Open-time Flags.
|
* O_NOFOLLOW: (libc)Open-time Flags.
|
* O_NOLINK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Operating Modes.
|
* O_NOTRANS: (libc)Open-time Flags.
|
* O_PATH: (libc)Access Modes.
|
* O_RDONLY: (libc)Access Modes.
|
* O_RDWR: (libc)Access Modes.
|
* O_READ: (libc)Access Modes.
|
* O_SHLOCK: (libc)Open-time Flags.
|
* O_SYNC: (libc)Operating Modes.
|
* O_TMPFILE: (libc)Open-time Flags.
|
* O_TRUNC: (libc)Open-time Flags.
|
* O_WRITE: (libc)Access Modes.
|
* O_WRONLY: (libc)Access Modes.
|
* PARENB: (libc)Control Modes.
|
* PARMRK: (libc)Input Modes.
|
* PARODD: (libc)Control Modes.
|
* PATH_MAX: (libc)Limits for Files.
|
* PA_FLAG_MASK: (libc)Parsing a Template String.
|
* PENDIN: (libc)Local Modes.
|
* PF_FILE: (libc)Local Namespace Details.
|
* PF_INET6: (libc)Internet Namespace.
|
* PF_INET: (libc)Internet Namespace.
|
* PF_LOCAL: (libc)Local Namespace Details.
|
* PF_UNIX: (libc)Local Namespace Details.
|
* PIPE_BUF: (libc)Limits for Files.
|
* PTHREAD_ATTR_NO_SIGMASK_NP: (libc)Initial Thread Signal Mask.
|
* P_tmpdir: (libc)Temporary Files.
|
* RAND_MAX: (libc)ISO Random.
|
* RE_DUP_MAX: (libc)General Limits.
|
* RLIM_INFINITY: (libc)Limits on Resources.
|
* R_OK: (libc)Testing File Access.
|
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
|
* SA_ONSTACK: (libc)Flags for Sigaction.
|
* SA_RESTART: (libc)Flags for Sigaction.
|
* SEEK_CUR: (libc)File Positioning.
|
* SEEK_END: (libc)File Positioning.
|
* SEEK_SET: (libc)File Positioning.
|
* SIGABRT: (libc)Program Error Signals.
|
* SIGALRM: (libc)Alarm Signals.
|
* SIGBUS: (libc)Program Error Signals.
|
* SIGCHLD: (libc)Job Control Signals.
|
* SIGCLD: (libc)Job Control Signals.
|
* SIGCONT: (libc)Job Control Signals.
|
* SIGEMT: (libc)Program Error Signals.
|
* SIGFPE: (libc)Program Error Signals.
|
* SIGHUP: (libc)Termination Signals.
|
* SIGILL: (libc)Program Error Signals.
|
* SIGINFO: (libc)Miscellaneous Signals.
|
* SIGINT: (libc)Termination Signals.
|
* SIGIO: (libc)Asynchronous I/O Signals.
|
* SIGIOT: (libc)Program Error Signals.
|
* SIGKILL: (libc)Termination Signals.
|
* SIGLOST: (libc)Operation Error Signals.
|
* SIGPIPE: (libc)Operation Error Signals.
|
* SIGPOLL: (libc)Asynchronous I/O Signals.
|
* SIGPROF: (libc)Alarm Signals.
|
* SIGQUIT: (libc)Termination Signals.
|
* SIGSEGV: (libc)Program Error Signals.
|
* SIGSTOP: (libc)Job Control Signals.
|
* SIGSYS: (libc)Program Error Signals.
|
* SIGTERM: (libc)Termination Signals.
|
* SIGTRAP: (libc)Program Error Signals.
|
* SIGTSTP: (libc)Job Control Signals.
|
* SIGTTIN: (libc)Job Control Signals.
|
* SIGTTOU: (libc)Job Control Signals.
|
* SIGURG: (libc)Asynchronous I/O Signals.
|
* SIGUSR1: (libc)Miscellaneous Signals.
|
* SIGUSR2: (libc)Miscellaneous Signals.
|
* SIGVTALRM: (libc)Alarm Signals.
|
* SIGWINCH: (libc)Miscellaneous Signals.
|
* SIGXCPU: (libc)Operation Error Signals.
|
* SIGXFSZ: (libc)Operation Error Signals.
|
* SIG_ERR: (libc)Basic Signal Handling.
|
* SNAN: (libc)Infinity and NaN.
|
* SNANF: (libc)Infinity and NaN.
|
* SNANFN: (libc)Infinity and NaN.
|
* SNANFNx: (libc)Infinity and NaN.
|
* SNANL: (libc)Infinity and NaN.
|
* SOCK_DGRAM: (libc)Communication Styles.
|
* SOCK_RAW: (libc)Communication Styles.
|
* SOCK_RDM: (libc)Communication Styles.
|
* SOCK_SEQPACKET: (libc)Communication Styles.
|
* SOCK_STREAM: (libc)Communication Styles.
|
* SOL_SOCKET: (libc)Socket-Level Options.
|
* SSIZE_MAX: (libc)General Limits.
|
* STREAM_MAX: (libc)General Limits.
|
* SUN_LEN: (libc)Local Namespace Details.
|
* S_IFMT: (libc)Testing File Type.
|
* S_ISBLK: (libc)Testing File Type.
|
* S_ISCHR: (libc)Testing File Type.
|
* S_ISDIR: (libc)Testing File Type.
|
* S_ISFIFO: (libc)Testing File Type.
|
* S_ISLNK: (libc)Testing File Type.
|
* S_ISREG: (libc)Testing File Type.
|
* S_ISSOCK: (libc)Testing File Type.
|
* S_TYPEISMQ: (libc)Testing File Type.
|
* S_TYPEISSEM: (libc)Testing File Type.
|
* S_TYPEISSHM: (libc)Testing File Type.
|
* TMP_MAX: (libc)Temporary Files.
|
* TOSTOP: (libc)Local Modes.
|
* TZNAME_MAX: (libc)General Limits.
|
* VDISCARD: (libc)Other Special.
|
* VDSUSP: (libc)Signal Characters.
|
* VEOF: (libc)Editing Characters.
|
* VEOL2: (libc)Editing Characters.
|
* VEOL: (libc)Editing Characters.
|
* VERASE: (libc)Editing Characters.
|
* VINTR: (libc)Signal Characters.
|
* VKILL: (libc)Editing Characters.
|
* VLNEXT: (libc)Other Special.
|
* VMIN: (libc)Noncanonical Input.
|
* VQUIT: (libc)Signal Characters.
|
* VREPRINT: (libc)Editing Characters.
|
* VSTART: (libc)Start/Stop Characters.
|
* VSTATUS: (libc)Other Special.
|
* VSTOP: (libc)Start/Stop Characters.
|
* VSUSP: (libc)Signal Characters.
|
* VTIME: (libc)Noncanonical Input.
|
* VWERASE: (libc)Editing Characters.
|
* WCHAR_MAX: (libc)Extended Char Intro.
|
* WCHAR_MIN: (libc)Extended Char Intro.
|
* WCOREDUMP: (libc)Process Completion Status.
|
* WEOF: (libc)EOF and Errors.
|
* WEOF: (libc)Extended Char Intro.
|
* WEXITSTATUS: (libc)Process Completion Status.
|
* WIFEXITED: (libc)Process Completion Status.
|
* WIFSIGNALED: (libc)Process Completion Status.
|
* WIFSTOPPED: (libc)Process Completion Status.
|
* WSTOPSIG: (libc)Process Completion Status.
|
* WTERMSIG: (libc)Process Completion Status.
|
* W_OK: (libc)Testing File Access.
|
* X_OK: (libc)Testing File Access.
|
* _Complex_I: (libc)Complex Numbers.
|
* _Exit: (libc)Termination Internals.
|
* _IOFBF: (libc)Controlling Buffering.
|
* _IOLBF: (libc)Controlling Buffering.
|
* _IONBF: (libc)Controlling Buffering.
|
* _Imaginary_I: (libc)Complex Numbers.
|
* _PATH_UTMP: (libc)Manipulating the Database.
|
* _PATH_WTMP: (libc)Manipulating the Database.
|
* _POSIX2_C_DEV: (libc)System Options.
|
* _POSIX2_C_VERSION: (libc)Version Supported.
|
* _POSIX2_FORT_DEV: (libc)System Options.
|
* _POSIX2_FORT_RUN: (libc)System Options.
|
* _POSIX2_LOCALEDEF: (libc)System Options.
|
* _POSIX2_SW_DEV: (libc)System Options.
|
* _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
|
* _POSIX_JOB_CONTROL: (libc)System Options.
|
* _POSIX_NO_TRUNC: (libc)Options for Files.
|
* _POSIX_SAVED_IDS: (libc)System Options.
|
* _POSIX_VDISABLE: (libc)Options for Files.
|
* _POSIX_VERSION: (libc)Version Supported.
|
* __fbufsize: (libc)Controlling Buffering.
|
* __flbf: (libc)Controlling Buffering.
|
* __fpending: (libc)Controlling Buffering.
|
* __fpurge: (libc)Flushing Buffers.
|
* __freadable: (libc)Opening Streams.
|
* __freading: (libc)Opening Streams.
|
* __fsetlocking: (libc)Streams and Threads.
|
* __fwritable: (libc)Opening Streams.
|
* __fwriting: (libc)Opening Streams.
|
* __gconv_end_fct: (libc)glibc iconv Implementation.
|
* __gconv_fct: (libc)glibc iconv Implementation.
|
* __gconv_init_fct: (libc)glibc iconv Implementation.
|
* __ppc_get_timebase: (libc)PowerPC.
|
* __ppc_get_timebase_freq: (libc)PowerPC.
|
* __ppc_mdoio: (libc)PowerPC.
|
* __ppc_mdoom: (libc)PowerPC.
|
* __ppc_set_ppr_low: (libc)PowerPC.
|
* __ppc_set_ppr_med: (libc)PowerPC.
|
* __ppc_set_ppr_med_high: (libc)PowerPC.
|
* __ppc_set_ppr_med_low: (libc)PowerPC.
|
* __ppc_set_ppr_very_low: (libc)PowerPC.
|
* __ppc_yield: (libc)PowerPC.
|
* __riscv_flush_icache: (libc)RISC-V.
|
* __va_copy: (libc)Argument Macros.
|
* __x86_get_cpuid_feature_leaf: (libc)X86.
|
* _exit: (libc)Termination Internals.
|
* _flushlbf: (libc)Flushing Buffers.
|
* _tolower: (libc)Case Conversion.
|
* _toupper: (libc)Case Conversion.
|
* a64l: (libc)Encode Binary Data.
|
* abort: (libc)Aborting a Program.
|
* abs: (libc)Absolute Value.
|
* accept: (libc)Accepting Connections.
|
* access: (libc)Testing File Access.
|
* acos: (libc)Inverse Trig Functions.
|
* acosf: (libc)Inverse Trig Functions.
|
* acosfN: (libc)Inverse Trig Functions.
|
* acosfNx: (libc)Inverse Trig Functions.
|
* acosh: (libc)Hyperbolic Functions.
|
* acoshf: (libc)Hyperbolic Functions.
|
* acoshfN: (libc)Hyperbolic Functions.
|
* acoshfNx: (libc)Hyperbolic Functions.
|
* acoshl: (libc)Hyperbolic Functions.
|
* acosl: (libc)Inverse Trig Functions.
|
* addmntent: (libc)mtab.
|
* addseverity: (libc)Adding Severity Classes.
|
* adjtime: (libc)Setting and Adjusting the Time.
|
* adjtimex: (libc)Setting and Adjusting the Time.
|
* aio_cancel64: (libc)Cancel AIO Operations.
|
* aio_cancel: (libc)Cancel AIO Operations.
|
* aio_error64: (libc)Status of AIO Operations.
|
* aio_error: (libc)Status of AIO Operations.
|
* aio_fsync64: (libc)Synchronizing AIO Operations.
|
* aio_fsync: (libc)Synchronizing AIO Operations.
|
* aio_init: (libc)Configuration of AIO.
|
* aio_read64: (libc)Asynchronous Reads/Writes.
|
* aio_read: (libc)Asynchronous Reads/Writes.
|
* aio_return64: (libc)Status of AIO Operations.
|
* aio_return: (libc)Status of AIO Operations.
|
* aio_suspend64: (libc)Synchronizing AIO Operations.
|
* aio_suspend: (libc)Synchronizing AIO Operations.
|
* aio_write64: (libc)Asynchronous Reads/Writes.
|
* aio_write: (libc)Asynchronous Reads/Writes.
|
* alarm: (libc)Setting an Alarm.
|
* aligned_alloc: (libc)Aligned Memory Blocks.
|
* alloca: (libc)Variable Size Automatic.
|
* alphasort64: (libc)Scanning Directory Content.
|
* alphasort: (libc)Scanning Directory Content.
|
* argp_error: (libc)Argp Helper Functions.
|
* argp_failure: (libc)Argp Helper Functions.
|
* argp_help: (libc)Argp Help.
|
* argp_parse: (libc)Argp.
|
* argp_state_help: (libc)Argp Helper Functions.
|
* argp_usage: (libc)Argp Helper Functions.
|
* argz_add: (libc)Argz Functions.
|
* argz_add_sep: (libc)Argz Functions.
|
* argz_append: (libc)Argz Functions.
|
* argz_count: (libc)Argz Functions.
|
* argz_create: (libc)Argz Functions.
|
* argz_create_sep: (libc)Argz Functions.
|
* argz_delete: (libc)Argz Functions.
|
* argz_extract: (libc)Argz Functions.
|
* argz_insert: (libc)Argz Functions.
|
* argz_next: (libc)Argz Functions.
|
* argz_replace: (libc)Argz Functions.
|
* argz_stringify: (libc)Argz Functions.
|
* asctime: (libc)Formatting Calendar Time.
|
* asctime_r: (libc)Formatting Calendar Time.
|
* asin: (libc)Inverse Trig Functions.
|
* asinf: (libc)Inverse Trig Functions.
|
* asinfN: (libc)Inverse Trig Functions.
|
* asinfNx: (libc)Inverse Trig Functions.
|
* asinh: (libc)Hyperbolic Functions.
|
* asinhf: (libc)Hyperbolic Functions.
|
* asinhfN: (libc)Hyperbolic Functions.
|
* asinhfNx: (libc)Hyperbolic Functions.
|
* asinhl: (libc)Hyperbolic Functions.
|
* asinl: (libc)Inverse Trig Functions.
|
* asprintf: (libc)Dynamic Output.
|
* assert: (libc)Consistency Checking.
|
* assert_perror: (libc)Consistency Checking.
|
* atan2: (libc)Inverse Trig Functions.
|
* atan2f: (libc)Inverse Trig Functions.
|
* atan2fN: (libc)Inverse Trig Functions.
|
* atan2fNx: (libc)Inverse Trig Functions.
|
* atan2l: (libc)Inverse Trig Functions.
|
* atan: (libc)Inverse Trig Functions.
|
* atanf: (libc)Inverse Trig Functions.
|
* atanfN: (libc)Inverse Trig Functions.
|
* atanfNx: (libc)Inverse Trig Functions.
|
* atanh: (libc)Hyperbolic Functions.
|
* atanhf: (libc)Hyperbolic Functions.
|
* atanhfN: (libc)Hyperbolic Functions.
|
* atanhfNx: (libc)Hyperbolic Functions.
|
* atanhl: (libc)Hyperbolic Functions.
|
* atanl: (libc)Inverse Trig Functions.
|
* atexit: (libc)Cleanups on Exit.
|
* atof: (libc)Parsing of Floats.
|
* atoi: (libc)Parsing of Integers.
|
* atol: (libc)Parsing of Integers.
|
* atoll: (libc)Parsing of Integers.
|
* backtrace: (libc)Backtraces.
|
* backtrace_symbols: (libc)Backtraces.
|
* backtrace_symbols_fd: (libc)Backtraces.
|
* basename: (libc)Finding Tokens in a String.
|
* basename: (libc)Finding Tokens in a String.
|
* bcmp: (libc)String/Array Comparison.
|
* bcopy: (libc)Copying Strings and Arrays.
|
* bind: (libc)Setting Address.
|
* bind_textdomain_codeset: (libc)Charset conversion in gettext.
|
* bindtextdomain: (libc)Locating gettext catalog.
|
* brk: (libc)Resizing the Data Segment.
|
* bsearch: (libc)Array Search Function.
|
* btowc: (libc)Converting a Character.
|
* bzero: (libc)Copying Strings and Arrays.
|
* cabs: (libc)Absolute Value.
|
* cabsf: (libc)Absolute Value.
|
* cabsfN: (libc)Absolute Value.
|
* cabsfNx: (libc)Absolute Value.
|
* cabsl: (libc)Absolute Value.
|
* cacos: (libc)Inverse Trig Functions.
|
* cacosf: (libc)Inverse Trig Functions.
|
* cacosfN: (libc)Inverse Trig Functions.
|
* cacosfNx: (libc)Inverse Trig Functions.
|
* cacosh: (libc)Hyperbolic Functions.
|
* cacoshf: (libc)Hyperbolic Functions.
|
* cacoshfN: (libc)Hyperbolic Functions.
|
* cacoshfNx: (libc)Hyperbolic Functions.
|
* cacoshl: (libc)Hyperbolic Functions.
|
* cacosl: (libc)Inverse Trig Functions.
|
* call_once: (libc)Call Once.
|
* calloc: (libc)Allocating Cleared Space.
|
* canonicalize: (libc)FP Bit Twiddling.
|
* canonicalize_file_name: (libc)Symbolic Links.
|
* canonicalizef: (libc)FP Bit Twiddling.
|
* canonicalizefN: (libc)FP Bit Twiddling.
|
* canonicalizefNx: (libc)FP Bit Twiddling.
|
* canonicalizel: (libc)FP Bit Twiddling.
|
* carg: (libc)Operations on Complex.
|
* cargf: (libc)Operations on Complex.
|
* cargfN: (libc)Operations on Complex.
|
* cargfNx: (libc)Operations on Complex.
|
* cargl: (libc)Operations on Complex.
|
* casin: (libc)Inverse Trig Functions.
|
* casinf: (libc)Inverse Trig Functions.
|
* casinfN: (libc)Inverse Trig Functions.
|
* casinfNx: (libc)Inverse Trig Functions.
|
* casinh: (libc)Hyperbolic Functions.
|
* casinhf: (libc)Hyperbolic Functions.
|
* casinhfN: (libc)Hyperbolic Functions.
|
* casinhfNx: (libc)Hyperbolic Functions.
|
* casinhl: (libc)Hyperbolic Functions.
|
* casinl: (libc)Inverse Trig Functions.
|
* catan: (libc)Inverse Trig Functions.
|
* catanf: (libc)Inverse Trig Functions.
|
* catanfN: (libc)Inverse Trig Functions.
|
* catanfNx: (libc)Inverse Trig Functions.
|
* catanh: (libc)Hyperbolic Functions.
|
* catanhf: (libc)Hyperbolic Functions.
|
* catanhfN: (libc)Hyperbolic Functions.
|
* catanhfNx: (libc)Hyperbolic Functions.
|
* catanhl: (libc)Hyperbolic Functions.
|
* catanl: (libc)Inverse Trig Functions.
|
* catclose: (libc)The catgets Functions.
|
* catgets: (libc)The catgets Functions.
|
* catopen: (libc)The catgets Functions.
|
* cbrt: (libc)Exponents and Logarithms.
|
* cbrtf: (libc)Exponents and Logarithms.
|
* cbrtfN: (libc)Exponents and Logarithms.
|
* cbrtfNx: (libc)Exponents and Logarithms.
|
* cbrtl: (libc)Exponents and Logarithms.
|
* ccos: (libc)Trig Functions.
|
* ccosf: (libc)Trig Functions.
|
* ccosfN: (libc)Trig Functions.
|
* ccosfNx: (libc)Trig Functions.
|
* ccosh: (libc)Hyperbolic Functions.
|
* ccoshf: (libc)Hyperbolic Functions.
|
* ccoshfN: (libc)Hyperbolic Functions.
|
* ccoshfNx: (libc)Hyperbolic Functions.
|
* ccoshl: (libc)Hyperbolic Functions.
|
* ccosl: (libc)Trig Functions.
|
* ceil: (libc)Rounding Functions.
|
* ceilf: (libc)Rounding Functions.
|
* ceilfN: (libc)Rounding Functions.
|
* ceilfNx: (libc)Rounding Functions.
|
* ceill: (libc)Rounding Functions.
|
* cexp: (libc)Exponents and Logarithms.
|
* cexpf: (libc)Exponents and Logarithms.
|
* cexpfN: (libc)Exponents and Logarithms.
|
* cexpfNx: (libc)Exponents and Logarithms.
|
* cexpl: (libc)Exponents and Logarithms.
|
* cfgetispeed: (libc)Line Speed.
|
* cfgetospeed: (libc)Line Speed.
|
* cfmakeraw: (libc)Noncanonical Input.
|
* cfsetispeed: (libc)Line Speed.
|
* cfsetospeed: (libc)Line Speed.
|
* cfsetspeed: (libc)Line Speed.
|
* chdir: (libc)Working Directory.
|
* chmod: (libc)Setting Permissions.
|
* chown: (libc)File Owner.
|
* cimag: (libc)Operations on Complex.
|
* cimagf: (libc)Operations on Complex.
|
* cimagfN: (libc)Operations on Complex.
|
* cimagfNx: (libc)Operations on Complex.
|
* cimagl: (libc)Operations on Complex.
|
* clearenv: (libc)Environment Access.
|
* clearerr: (libc)Error Recovery.
|
* clearerr_unlocked: (libc)Error Recovery.
|
* clock: (libc)CPU Time.
|
* clock_getres: (libc)Getting the Time.
|
* clock_gettime: (libc)Getting the Time.
|
* clock_settime: (libc)Setting and Adjusting the Time.
|
* clog10: (libc)Exponents and Logarithms.
|
* clog10f: (libc)Exponents and Logarithms.
|
* clog10fN: (libc)Exponents and Logarithms.
|
* clog10fNx: (libc)Exponents and Logarithms.
|
* clog10l: (libc)Exponents and Logarithms.
|
* clog: (libc)Exponents and Logarithms.
|
* clogf: (libc)Exponents and Logarithms.
|
* clogfN: (libc)Exponents and Logarithms.
|
* clogfNx: (libc)Exponents and Logarithms.
|
* clogl: (libc)Exponents and Logarithms.
|
* close: (libc)Opening and Closing Files.
|
* closedir: (libc)Reading/Closing Directory.
|
* closelog: (libc)closelog.
|
* cnd_broadcast: (libc)ISO C Condition Variables.
|
* cnd_destroy: (libc)ISO C Condition Variables.
|
* cnd_init: (libc)ISO C Condition Variables.
|
* cnd_signal: (libc)ISO C Condition Variables.
|
* cnd_timedwait: (libc)ISO C Condition Variables.
|
* cnd_wait: (libc)ISO C Condition Variables.
|
* confstr: (libc)String Parameters.
|
* conj: (libc)Operations on Complex.
|
* conjf: (libc)Operations on Complex.
|
* conjfN: (libc)Operations on Complex.
|
* conjfNx: (libc)Operations on Complex.
|
* conjl: (libc)Operations on Complex.
|
* connect: (libc)Connecting.
|
* copy_file_range: (libc)Copying File Data.
|
* copysign: (libc)FP Bit Twiddling.
|
* copysignf: (libc)FP Bit Twiddling.
|
* copysignfN: (libc)FP Bit Twiddling.
|
* copysignfNx: (libc)FP Bit Twiddling.
|
* copysignl: (libc)FP Bit Twiddling.
|
* cos: (libc)Trig Functions.
|
* cosf: (libc)Trig Functions.
|
* cosfN: (libc)Trig Functions.
|
* cosfNx: (libc)Trig Functions.
|
* cosh: (libc)Hyperbolic Functions.
|
* coshf: (libc)Hyperbolic Functions.
|
* coshfN: (libc)Hyperbolic Functions.
|
* coshfNx: (libc)Hyperbolic Functions.
|
* coshl: (libc)Hyperbolic Functions.
|
* cosl: (libc)Trig Functions.
|
* cpow: (libc)Exponents and Logarithms.
|
* cpowf: (libc)Exponents and Logarithms.
|
* cpowfN: (libc)Exponents and Logarithms.
|
* cpowfNx: (libc)Exponents and Logarithms.
|
* cpowl: (libc)Exponents and Logarithms.
|
* cproj: (libc)Operations on Complex.
|
* cprojf: (libc)Operations on Complex.
|
* cprojfN: (libc)Operations on Complex.
|
* cprojfNx: (libc)Operations on Complex.
|
* cprojl: (libc)Operations on Complex.
|
* creal: (libc)Operations on Complex.
|
* crealf: (libc)Operations on Complex.
|
* crealfN: (libc)Operations on Complex.
|
* crealfNx: (libc)Operations on Complex.
|
* creall: (libc)Operations on Complex.
|
* creat64: (libc)Opening and Closing Files.
|
* creat: (libc)Opening and Closing Files.
|
* crypt: (libc)Passphrase Storage.
|
* crypt_r: (libc)Passphrase Storage.
|
* csin: (libc)Trig Functions.
|
* csinf: (libc)Trig Functions.
|
* csinfN: (libc)Trig Functions.
|
* csinfNx: (libc)Trig Functions.
|
* csinh: (libc)Hyperbolic Functions.
|
* csinhf: (libc)Hyperbolic Functions.
|
* csinhfN: (libc)Hyperbolic Functions.
|
* csinhfNx: (libc)Hyperbolic Functions.
|
* csinhl: (libc)Hyperbolic Functions.
|
* csinl: (libc)Trig Functions.
|
* csqrt: (libc)Exponents and Logarithms.
|
* csqrtf: (libc)Exponents and Logarithms.
|
* csqrtfN: (libc)Exponents and Logarithms.
|
* csqrtfNx: (libc)Exponents and Logarithms.
|
* csqrtl: (libc)Exponents and Logarithms.
|
* ctan: (libc)Trig Functions.
|
* ctanf: (libc)Trig Functions.
|
* ctanfN: (libc)Trig Functions.
|
* ctanfNx: (libc)Trig Functions.
|
* ctanh: (libc)Hyperbolic Functions.
|
* ctanhf: (libc)Hyperbolic Functions.
|
* ctanhfN: (libc)Hyperbolic Functions.
|
* ctanhfNx: (libc)Hyperbolic Functions.
|
* ctanhl: (libc)Hyperbolic Functions.
|
* ctanl: (libc)Trig Functions.
|
* ctermid: (libc)Identifying the Terminal.
|
* ctime: (libc)Formatting Calendar Time.
|
* ctime_r: (libc)Formatting Calendar Time.
|
* cuserid: (libc)Who Logged In.
|
* daddl: (libc)Misc FP Arithmetic.
|
* dcgettext: (libc)Translation with gettext.
|
* dcngettext: (libc)Advanced gettext functions.
|
* ddivl: (libc)Misc FP Arithmetic.
|
* dgettext: (libc)Translation with gettext.
|
* difftime: (libc)Calculating Elapsed Time.
|
* dirfd: (libc)Opening a Directory.
|
* dirname: (libc)Finding Tokens in a String.
|
* div: (libc)Integer Division.
|
* dmull: (libc)Misc FP Arithmetic.
|
* dngettext: (libc)Advanced gettext functions.
|
* drand48: (libc)SVID Random.
|
* drand48_r: (libc)SVID Random.
|
* drem: (libc)Remainder Functions.
|
* dremf: (libc)Remainder Functions.
|
* dreml: (libc)Remainder Functions.
|
* dsubl: (libc)Misc FP Arithmetic.
|
* dup2: (libc)Duplicating Descriptors.
|
* dup: (libc)Duplicating Descriptors.
|
* ecvt: (libc)System V Number Conversion.
|
* ecvt_r: (libc)System V Number Conversion.
|
* endfsent: (libc)fstab.
|
* endgrent: (libc)Scanning All Groups.
|
* endhostent: (libc)Host Names.
|
* endmntent: (libc)mtab.
|
* endnetent: (libc)Networks Database.
|
* endnetgrent: (libc)Lookup Netgroup.
|
* endprotoent: (libc)Protocols Database.
|
* endpwent: (libc)Scanning All Users.
|
* endservent: (libc)Services Database.
|
* endutent: (libc)Manipulating the Database.
|
* endutxent: (libc)XPG Functions.
|
* envz_add: (libc)Envz Functions.
|
* envz_entry: (libc)Envz Functions.
|
* envz_get: (libc)Envz Functions.
|
* envz_merge: (libc)Envz Functions.
|
* envz_remove: (libc)Envz Functions.
|
* envz_strip: (libc)Envz Functions.
|
* erand48: (libc)SVID Random.
|
* erand48_r: (libc)SVID Random.
|
* erf: (libc)Special Functions.
|
* erfc: (libc)Special Functions.
|
* erfcf: (libc)Special Functions.
|
* erfcfN: (libc)Special Functions.
|
* erfcfNx: (libc)Special Functions.
|
* erfcl: (libc)Special Functions.
|
* erff: (libc)Special Functions.
|
* erffN: (libc)Special Functions.
|
* erffNx: (libc)Special Functions.
|
* erfl: (libc)Special Functions.
|
* err: (libc)Error Messages.
|
* errno: (libc)Checking for Errors.
|
* error: (libc)Error Messages.
|
* error_at_line: (libc)Error Messages.
|
* errx: (libc)Error Messages.
|
* execl: (libc)Executing a File.
|
* execle: (libc)Executing a File.
|
* execlp: (libc)Executing a File.
|
* execv: (libc)Executing a File.
|
* execve: (libc)Executing a File.
|
* execvp: (libc)Executing a File.
|
* exit: (libc)Normal Termination.
|
* exp10: (libc)Exponents and Logarithms.
|
* exp10f: (libc)Exponents and Logarithms.
|
* exp10fN: (libc)Exponents and Logarithms.
|
* exp10fNx: (libc)Exponents and Logarithms.
|
* exp10l: (libc)Exponents and Logarithms.
|
* exp2: (libc)Exponents and Logarithms.
|
* exp2f: (libc)Exponents and Logarithms.
|
* exp2fN: (libc)Exponents and Logarithms.
|
* exp2fNx: (libc)Exponents and Logarithms.
|
* exp2l: (libc)Exponents and Logarithms.
|
* exp: (libc)Exponents and Logarithms.
|
* expf: (libc)Exponents and Logarithms.
|
* expfN: (libc)Exponents and Logarithms.
|
* expfNx: (libc)Exponents and Logarithms.
|
* expl: (libc)Exponents and Logarithms.
|
* explicit_bzero: (libc)Erasing Sensitive Data.
|
* expm1: (libc)Exponents and Logarithms.
|
* expm1f: (libc)Exponents and Logarithms.
|
* expm1fN: (libc)Exponents and Logarithms.
|
* expm1fNx: (libc)Exponents and Logarithms.
|
* expm1l: (libc)Exponents and Logarithms.
|
* fMaddfN: (libc)Misc FP Arithmetic.
|
* fMaddfNx: (libc)Misc FP Arithmetic.
|
* fMdivfN: (libc)Misc FP Arithmetic.
|
* fMdivfNx: (libc)Misc FP Arithmetic.
|
* fMmulfN: (libc)Misc FP Arithmetic.
|
* fMmulfNx: (libc)Misc FP Arithmetic.
|
* fMsubfN: (libc)Misc FP Arithmetic.
|
* fMsubfNx: (libc)Misc FP Arithmetic.
|
* fMxaddfN: (libc)Misc FP Arithmetic.
|
* fMxaddfNx: (libc)Misc FP Arithmetic.
|
* fMxdivfN: (libc)Misc FP Arithmetic.
|
* fMxdivfNx: (libc)Misc FP Arithmetic.
|
* fMxmulfN: (libc)Misc FP Arithmetic.
|
* fMxmulfNx: (libc)Misc FP Arithmetic.
|
* fMxsubfN: (libc)Misc FP Arithmetic.
|
* fMxsubfNx: (libc)Misc FP Arithmetic.
|
* fabs: (libc)Absolute Value.
|
* fabsf: (libc)Absolute Value.
|
* fabsfN: (libc)Absolute Value.
|
* fabsfNx: (libc)Absolute Value.
|
* fabsl: (libc)Absolute Value.
|
* fadd: (libc)Misc FP Arithmetic.
|
* faddl: (libc)Misc FP Arithmetic.
|
* fchdir: (libc)Working Directory.
|
* fchmod: (libc)Setting Permissions.
|
* fchown: (libc)File Owner.
|
* fclose: (libc)Closing Streams.
|
* fcloseall: (libc)Closing Streams.
|
* fcntl: (libc)Control Operations.
|
* fcvt: (libc)System V Number Conversion.
|
* fcvt_r: (libc)System V Number Conversion.
|
* fdatasync: (libc)Synchronizing I/O.
|
* fdim: (libc)Misc FP Arithmetic.
|
* fdimf: (libc)Misc FP Arithmetic.
|
* fdimfN: (libc)Misc FP Arithmetic.
|
* fdimfNx: (libc)Misc FP Arithmetic.
|
* fdiml: (libc)Misc FP Arithmetic.
|
* fdiv: (libc)Misc FP Arithmetic.
|
* fdivl: (libc)Misc FP Arithmetic.
|
* fdopen: (libc)Descriptors and Streams.
|
* fdopendir: (libc)Opening a Directory.
|
* feclearexcept: (libc)Status bit operations.
|
* fedisableexcept: (libc)Control Functions.
|
* feenableexcept: (libc)Control Functions.
|
* fegetenv: (libc)Control Functions.
|
* fegetexcept: (libc)Control Functions.
|
* fegetexceptflag: (libc)Status bit operations.
|
* fegetmode: (libc)Control Functions.
|
* fegetround: (libc)Rounding.
|
* feholdexcept: (libc)Control Functions.
|
* feof: (libc)EOF and Errors.
|
* feof_unlocked: (libc)EOF and Errors.
|
* feraiseexcept: (libc)Status bit operations.
|
* ferror: (libc)EOF and Errors.
|
* ferror_unlocked: (libc)EOF and Errors.
|
* fesetenv: (libc)Control Functions.
|
* fesetexcept: (libc)Status bit operations.
|
* fesetexceptflag: (libc)Status bit operations.
|
* fesetmode: (libc)Control Functions.
|
* fesetround: (libc)Rounding.
|
* fetestexcept: (libc)Status bit operations.
|
* fetestexceptflag: (libc)Status bit operations.
|
* feupdateenv: (libc)Control Functions.
|
* fexecve: (libc)Executing a File.
|
* fflush: (libc)Flushing Buffers.
|
* fflush_unlocked: (libc)Flushing Buffers.
|
* fgetc: (libc)Character Input.
|
* fgetc_unlocked: (libc)Character Input.
|
* fgetgrent: (libc)Scanning All Groups.
|
* fgetgrent_r: (libc)Scanning All Groups.
|
* fgetpos64: (libc)Portable Positioning.
|
* fgetpos: (libc)Portable Positioning.
|
* fgetpwent: (libc)Scanning All Users.
|
* fgetpwent_r: (libc)Scanning All Users.
|
* fgets: (libc)Line Input.
|
* fgets_unlocked: (libc)Line Input.
|
* fgetwc: (libc)Character Input.
|
* fgetwc_unlocked: (libc)Character Input.
|
* fgetws: (libc)Line Input.
|
* fgetws_unlocked: (libc)Line Input.
|
* fileno: (libc)Descriptors and Streams.
|
* fileno_unlocked: (libc)Descriptors and Streams.
|
* finite: (libc)Floating Point Classes.
|
* finitef: (libc)Floating Point Classes.
|
* finitel: (libc)Floating Point Classes.
|
* flockfile: (libc)Streams and Threads.
|
* floor: (libc)Rounding Functions.
|
* floorf: (libc)Rounding Functions.
|
* floorfN: (libc)Rounding Functions.
|
* floorfNx: (libc)Rounding Functions.
|
* floorl: (libc)Rounding Functions.
|
* fma: (libc)Misc FP Arithmetic.
|
* fmaf: (libc)Misc FP Arithmetic.
|
* fmafN: (libc)Misc FP Arithmetic.
|
* fmafNx: (libc)Misc FP Arithmetic.
|
* fmal: (libc)Misc FP Arithmetic.
|
* fmax: (libc)Misc FP Arithmetic.
|
* fmaxf: (libc)Misc FP Arithmetic.
|
* fmaxfN: (libc)Misc FP Arithmetic.
|
* fmaxfNx: (libc)Misc FP Arithmetic.
|
* fmaxl: (libc)Misc FP Arithmetic.
|
* fmaxmag: (libc)Misc FP Arithmetic.
|
* fmaxmagf: (libc)Misc FP Arithmetic.
|
* fmaxmagfN: (libc)Misc FP Arithmetic.
|
* fmaxmagfNx: (libc)Misc FP Arithmetic.
|
* fmaxmagl: (libc)Misc FP Arithmetic.
|
* fmemopen: (libc)String Streams.
|
* fmin: (libc)Misc FP Arithmetic.
|
* fminf: (libc)Misc FP Arithmetic.
|
* fminfN: (libc)Misc FP Arithmetic.
|
* fminfNx: (libc)Misc FP Arithmetic.
|
* fminl: (libc)Misc FP Arithmetic.
|
* fminmag: (libc)Misc FP Arithmetic.
|
* fminmagf: (libc)Misc FP Arithmetic.
|
* fminmagfN: (libc)Misc FP Arithmetic.
|
* fminmagfNx: (libc)Misc FP Arithmetic.
|
* fminmagl: (libc)Misc FP Arithmetic.
|
* fmod: (libc)Remainder Functions.
|
* fmodf: (libc)Remainder Functions.
|
* fmodfN: (libc)Remainder Functions.
|
* fmodfNx: (libc)Remainder Functions.
|
* fmodl: (libc)Remainder Functions.
|
* fmtmsg: (libc)Printing Formatted Messages.
|
* fmul: (libc)Misc FP Arithmetic.
|
* fmull: (libc)Misc FP Arithmetic.
|
* fnmatch: (libc)Wildcard Matching.
|
* fopen64: (libc)Opening Streams.
|
* fopen: (libc)Opening Streams.
|
* fopencookie: (libc)Streams and Cookies.
|
* fork: (libc)Creating a Process.
|
* forkpty: (libc)Pseudo-Terminal Pairs.
|
* fpathconf: (libc)Pathconf.
|
* fpclassify: (libc)Floating Point Classes.
|
* fprintf: (libc)Formatted Output Functions.
|
* fputc: (libc)Simple Output.
|
* fputc_unlocked: (libc)Simple Output.
|
* fputs: (libc)Simple Output.
|
* fputs_unlocked: (libc)Simple Output.
|
* fputwc: (libc)Simple Output.
|
* fputwc_unlocked: (libc)Simple Output.
|
* fputws: (libc)Simple Output.
|
* fputws_unlocked: (libc)Simple Output.
|
* fread: (libc)Block Input/Output.
|
* fread_unlocked: (libc)Block Input/Output.
|
* free: (libc)Freeing after Malloc.
|
* freopen64: (libc)Opening Streams.
|
* freopen: (libc)Opening Streams.
|
* frexp: (libc)Normalization Functions.
|
* frexpf: (libc)Normalization Functions.
|
* frexpfN: (libc)Normalization Functions.
|
* frexpfNx: (libc)Normalization Functions.
|
* frexpl: (libc)Normalization Functions.
|
* fromfp: (libc)Rounding Functions.
|
* fromfpf: (libc)Rounding Functions.
|
* fromfpfN: (libc)Rounding Functions.
|
* fromfpfNx: (libc)Rounding Functions.
|
* fromfpl: (libc)Rounding Functions.
|
* fromfpx: (libc)Rounding Functions.
|
* fromfpxf: (libc)Rounding Functions.
|
* fromfpxfN: (libc)Rounding Functions.
|
* fromfpxfNx: (libc)Rounding Functions.
|
* fromfpxl: (libc)Rounding Functions.
|
* fscanf: (libc)Formatted Input Functions.
|
* fseek: (libc)File Positioning.
|
* fseeko64: (libc)File Positioning.
|
* fseeko: (libc)File Positioning.
|
* fsetpos64: (libc)Portable Positioning.
|
* fsetpos: (libc)Portable Positioning.
|
* fstat64: (libc)Reading Attributes.
|
* fstat: (libc)Reading Attributes.
|
* fsub: (libc)Misc FP Arithmetic.
|
* fsubl: (libc)Misc FP Arithmetic.
|
* fsync: (libc)Synchronizing I/O.
|
* ftell: (libc)File Positioning.
|
* ftello64: (libc)File Positioning.
|
* ftello: (libc)File Positioning.
|
* ftruncate64: (libc)File Size.
|
* ftruncate: (libc)File Size.
|
* ftrylockfile: (libc)Streams and Threads.
|
* ftw64: (libc)Working with Directory Trees.
|
* ftw: (libc)Working with Directory Trees.
|
* funlockfile: (libc)Streams and Threads.
|
* futimes: (libc)File Times.
|
* fwide: (libc)Streams and I18N.
|
* fwprintf: (libc)Formatted Output Functions.
|
* fwrite: (libc)Block Input/Output.
|
* fwrite_unlocked: (libc)Block Input/Output.
|
* fwscanf: (libc)Formatted Input Functions.
|
* gamma: (libc)Special Functions.
|
* gammaf: (libc)Special Functions.
|
* gammal: (libc)Special Functions.
|
* gcvt: (libc)System V Number Conversion.
|
* get_avphys_pages: (libc)Query Memory Parameters.
|
* get_current_dir_name: (libc)Working Directory.
|
* get_nprocs: (libc)Processor Resources.
|
* get_nprocs_conf: (libc)Processor Resources.
|
* get_phys_pages: (libc)Query Memory Parameters.
|
* getauxval: (libc)Auxiliary Vector.
|
* getc: (libc)Character Input.
|
* getc_unlocked: (libc)Character Input.
|
* getchar: (libc)Character Input.
|
* getchar_unlocked: (libc)Character Input.
|
* getcontext: (libc)System V contexts.
|
* getcpu: (libc)CPU Affinity.
|
* getcwd: (libc)Working Directory.
|
* getdate: (libc)General Time String Parsing.
|
* getdate_r: (libc)General Time String Parsing.
|
* getdelim: (libc)Line Input.
|
* getdents64: (libc)Low-level Directory Access.
|
* getdomainnname: (libc)Host Identification.
|
* getegid: (libc)Reading Persona.
|
* getentropy: (libc)Unpredictable Bytes.
|
* getenv: (libc)Environment Access.
|
* geteuid: (libc)Reading Persona.
|
* getfsent: (libc)fstab.
|
* getfsfile: (libc)fstab.
|
* getfsspec: (libc)fstab.
|
* getgid: (libc)Reading Persona.
|
* getgrent: (libc)Scanning All Groups.
|
* getgrent_r: (libc)Scanning All Groups.
|
* getgrgid: (libc)Lookup Group.
|
* getgrgid_r: (libc)Lookup Group.
|
* getgrnam: (libc)Lookup Group.
|
* getgrnam_r: (libc)Lookup Group.
|
* getgrouplist: (libc)Setting Groups.
|
* getgroups: (libc)Reading Persona.
|
* gethostbyaddr: (libc)Host Names.
|
* gethostbyaddr_r: (libc)Host Names.
|
* gethostbyname2: (libc)Host Names.
|
* gethostbyname2_r: (libc)Host Names.
|
* gethostbyname: (libc)Host Names.
|
* gethostbyname_r: (libc)Host Names.
|
* gethostent: (libc)Host Names.
|
* gethostid: (libc)Host Identification.
|
* gethostname: (libc)Host Identification.
|
* getitimer: (libc)Setting an Alarm.
|
* getline: (libc)Line Input.
|
* getloadavg: (libc)Processor Resources.
|
* getlogin: (libc)Who Logged In.
|
* getmntent: (libc)mtab.
|
* getmntent_r: (libc)mtab.
|
* getnetbyaddr: (libc)Networks Database.
|
* getnetbyname: (libc)Networks Database.
|
* getnetent: (libc)Networks Database.
|
* getnetgrent: (libc)Lookup Netgroup.
|
* getnetgrent_r: (libc)Lookup Netgroup.
|
* getopt: (libc)Using Getopt.
|
* getopt_long: (libc)Getopt Long Options.
|
* getopt_long_only: (libc)Getopt Long Options.
|
* getpagesize: (libc)Query Memory Parameters.
|
* getpass: (libc)getpass.
|
* getpayload: (libc)FP Bit Twiddling.
|
* getpayloadf: (libc)FP Bit Twiddling.
|
* getpayloadfN: (libc)FP Bit Twiddling.
|
* getpayloadfNx: (libc)FP Bit Twiddling.
|
* getpayloadl: (libc)FP Bit Twiddling.
|
* getpeername: (libc)Who is Connected.
|
* getpgid: (libc)Process Group Functions.
|
* getpgrp: (libc)Process Group Functions.
|
* getpid: (libc)Process Identification.
|
* getppid: (libc)Process Identification.
|
* getpriority: (libc)Traditional Scheduling Functions.
|
* getprotobyname: (libc)Protocols Database.
|
* getprotobynumber: (libc)Protocols Database.
|
* getprotoent: (libc)Protocols Database.
|
* getpt: (libc)Allocation.
|
* getpwent: (libc)Scanning All Users.
|
* getpwent_r: (libc)Scanning All Users.
|
* getpwnam: (libc)Lookup User.
|
* getpwnam_r: (libc)Lookup User.
|
* getpwuid: (libc)Lookup User.
|
* getpwuid_r: (libc)Lookup User.
|
* getrandom: (libc)Unpredictable Bytes.
|
* getrlimit64: (libc)Limits on Resources.
|
* getrlimit: (libc)Limits on Resources.
|
* getrusage: (libc)Resource Usage.
|
* gets: (libc)Line Input.
|
* getservbyname: (libc)Services Database.
|
* getservbyport: (libc)Services Database.
|
* getservent: (libc)Services Database.
|
* getsid: (libc)Process Group Functions.
|
* getsockname: (libc)Reading Address.
|
* getsockopt: (libc)Socket Option Functions.
|
* getsubopt: (libc)Suboptions.
|
* gettext: (libc)Translation with gettext.
|
* gettid: (libc)Process Identification.
|
* gettimeofday: (libc)Getting the Time.
|
* getuid: (libc)Reading Persona.
|
* getumask: (libc)Setting Permissions.
|
* getutent: (libc)Manipulating the Database.
|
* getutent_r: (libc)Manipulating the Database.
|
* getutid: (libc)Manipulating the Database.
|
* getutid_r: (libc)Manipulating the Database.
|
* getutline: (libc)Manipulating the Database.
|
* getutline_r: (libc)Manipulating the Database.
|
* getutmp: (libc)XPG Functions.
|
* getutmpx: (libc)XPG Functions.
|
* getutxent: (libc)XPG Functions.
|
* getutxid: (libc)XPG Functions.
|
* getutxline: (libc)XPG Functions.
|
* getw: (libc)Character Input.
|
* getwc: (libc)Character Input.
|
* getwc_unlocked: (libc)Character Input.
|
* getwchar: (libc)Character Input.
|
* getwchar_unlocked: (libc)Character Input.
|
* getwd: (libc)Working Directory.
|
* glob64: (libc)Calling Glob.
|
* glob: (libc)Calling Glob.
|
* globfree64: (libc)More Flags for Globbing.
|
* globfree: (libc)More Flags for Globbing.
|
* gmtime: (libc)Broken-down Time.
|
* gmtime_r: (libc)Broken-down Time.
|
* grantpt: (libc)Allocation.
|
* gsignal: (libc)Signaling Yourself.
|
* gtty: (libc)BSD Terminal Modes.
|
* hasmntopt: (libc)mtab.
|
* hcreate: (libc)Hash Search Function.
|
* hcreate_r: (libc)Hash Search Function.
|
* hdestroy: (libc)Hash Search Function.
|
* hdestroy_r: (libc)Hash Search Function.
|
* hsearch: (libc)Hash Search Function.
|
* hsearch_r: (libc)Hash Search Function.
|
* htonl: (libc)Byte Order.
|
* htons: (libc)Byte Order.
|
* hypot: (libc)Exponents and Logarithms.
|
* hypotf: (libc)Exponents and Logarithms.
|
* hypotfN: (libc)Exponents and Logarithms.
|
* hypotfNx: (libc)Exponents and Logarithms.
|
* hypotl: (libc)Exponents and Logarithms.
|
* iconv: (libc)Generic Conversion Interface.
|
* iconv_close: (libc)Generic Conversion Interface.
|
* iconv_open: (libc)Generic Conversion Interface.
|
* if_freenameindex: (libc)Interface Naming.
|
* if_indextoname: (libc)Interface Naming.
|
* if_nameindex: (libc)Interface Naming.
|
* if_nametoindex: (libc)Interface Naming.
|
* ilogb: (libc)Exponents and Logarithms.
|
* ilogbf: (libc)Exponents and Logarithms.
|
* ilogbfN: (libc)Exponents and Logarithms.
|
* ilogbfNx: (libc)Exponents and Logarithms.
|
* ilogbl: (libc)Exponents and Logarithms.
|
* imaxabs: (libc)Absolute Value.
|
* imaxdiv: (libc)Integer Division.
|
* in6addr_any: (libc)Host Address Data Type.
|
* in6addr_loopback: (libc)Host Address Data Type.
|
* index: (libc)Search Functions.
|
* inet_addr: (libc)Host Address Functions.
|
* inet_aton: (libc)Host Address Functions.
|
* inet_lnaof: (libc)Host Address Functions.
|
* inet_makeaddr: (libc)Host Address Functions.
|
* inet_netof: (libc)Host Address Functions.
|
* inet_network: (libc)Host Address Functions.
|
* inet_ntoa: (libc)Host Address Functions.
|
* inet_ntop: (libc)Host Address Functions.
|
* inet_pton: (libc)Host Address Functions.
|
* initgroups: (libc)Setting Groups.
|
* initstate: (libc)BSD Random.
|
* initstate_r: (libc)BSD Random.
|
* innetgr: (libc)Netgroup Membership.
|
* ioctl: (libc)IOCTLs.
|
* isalnum: (libc)Classification of Characters.
|
* isalpha: (libc)Classification of Characters.
|
* isascii: (libc)Classification of Characters.
|
* isatty: (libc)Is It a Terminal.
|
* isblank: (libc)Classification of Characters.
|
* iscanonical: (libc)Floating Point Classes.
|
* iscntrl: (libc)Classification of Characters.
|
* isdigit: (libc)Classification of Characters.
|
* iseqsig: (libc)FP Comparison Functions.
|
* isfinite: (libc)Floating Point Classes.
|
* isgraph: (libc)Classification of Characters.
|
* isgreater: (libc)FP Comparison Functions.
|
* isgreaterequal: (libc)FP Comparison Functions.
|
* isinf: (libc)Floating Point Classes.
|
* isinff: (libc)Floating Point Classes.
|
* isinfl: (libc)Floating Point Classes.
|
* isless: (libc)FP Comparison Functions.
|
* islessequal: (libc)FP Comparison Functions.
|
* islessgreater: (libc)FP Comparison Functions.
|
* islower: (libc)Classification of Characters.
|
* isnan: (libc)Floating Point Classes.
|
* isnan: (libc)Floating Point Classes.
|
* isnanf: (libc)Floating Point Classes.
|
* isnanl: (libc)Floating Point Classes.
|
* isnormal: (libc)Floating Point Classes.
|
* isprint: (libc)Classification of Characters.
|
* ispunct: (libc)Classification of Characters.
|
* issignaling: (libc)Floating Point Classes.
|
* isspace: (libc)Classification of Characters.
|
* issubnormal: (libc)Floating Point Classes.
|
* isunordered: (libc)FP Comparison Functions.
|
* isupper: (libc)Classification of Characters.
|
* iswalnum: (libc)Classification of Wide Characters.
|
* iswalpha: (libc)Classification of Wide Characters.
|
* iswblank: (libc)Classification of Wide Characters.
|
* iswcntrl: (libc)Classification of Wide Characters.
|
* iswctype: (libc)Classification of Wide Characters.
|
* iswdigit: (libc)Classification of Wide Characters.
|
* iswgraph: (libc)Classification of Wide Characters.
|
* iswlower: (libc)Classification of Wide Characters.
|
* iswprint: (libc)Classification of Wide Characters.
|
* iswpunct: (libc)Classification of Wide Characters.
|
* iswspace: (libc)Classification of Wide Characters.
|
* iswupper: (libc)Classification of Wide Characters.
|
* iswxdigit: (libc)Classification of Wide Characters.
|
* isxdigit: (libc)Classification of Characters.
|
* iszero: (libc)Floating Point Classes.
|
* j0: (libc)Special Functions.
|
* j0f: (libc)Special Functions.
|
* j0fN: (libc)Special Functions.
|
* j0fNx: (libc)Special Functions.
|
* j0l: (libc)Special Functions.
|
* j1: (libc)Special Functions.
|
* j1f: (libc)Special Functions.
|
* j1fN: (libc)Special Functions.
|
* j1fNx: (libc)Special Functions.
|
* j1l: (libc)Special Functions.
|
* jn: (libc)Special Functions.
|
* jnf: (libc)Special Functions.
|
* jnfN: (libc)Special Functions.
|
* jnfNx: (libc)Special Functions.
|
* jnl: (libc)Special Functions.
|
* jrand48: (libc)SVID Random.
|
* jrand48_r: (libc)SVID Random.
|
* kill: (libc)Signaling Another Process.
|
* killpg: (libc)Signaling Another Process.
|
* l64a: (libc)Encode Binary Data.
|
* labs: (libc)Absolute Value.
|
* lcong48: (libc)SVID Random.
|
* lcong48_r: (libc)SVID Random.
|
* ldexp: (libc)Normalization Functions.
|
* ldexpf: (libc)Normalization Functions.
|
* ldexpfN: (libc)Normalization Functions.
|
* ldexpfNx: (libc)Normalization Functions.
|
* ldexpl: (libc)Normalization Functions.
|
* ldiv: (libc)Integer Division.
|
* lfind: (libc)Array Search Function.
|
* lgamma: (libc)Special Functions.
|
* lgamma_r: (libc)Special Functions.
|
* lgammaf: (libc)Special Functions.
|
* lgammafN: (libc)Special Functions.
|
* lgammafN_r: (libc)Special Functions.
|
* lgammafNx: (libc)Special Functions.
|
* lgammafNx_r: (libc)Special Functions.
|
* lgammaf_r: (libc)Special Functions.
|
* lgammal: (libc)Special Functions.
|
* lgammal_r: (libc)Special Functions.
|
* link: (libc)Hard Links.
|
* linkat: (libc)Hard Links.
|
* lio_listio64: (libc)Asynchronous Reads/Writes.
|
* lio_listio: (libc)Asynchronous Reads/Writes.
|
* listen: (libc)Listening.
|
* llabs: (libc)Absolute Value.
|
* lldiv: (libc)Integer Division.
|
* llogb: (libc)Exponents and Logarithms.
|
* llogbf: (libc)Exponents and Logarithms.
|
* llogbfN: (libc)Exponents and Logarithms.
|
* llogbfNx: (libc)Exponents and Logarithms.
|
* llogbl: (libc)Exponents and Logarithms.
|
* llrint: (libc)Rounding Functions.
|
* llrintf: (libc)Rounding Functions.
|
* llrintfN: (libc)Rounding Functions.
|
* llrintfNx: (libc)Rounding Functions.
|
* llrintl: (libc)Rounding Functions.
|
* llround: (libc)Rounding Functions.
|
* llroundf: (libc)Rounding Functions.
|
* llroundfN: (libc)Rounding Functions.
|
* llroundfNx: (libc)Rounding Functions.
|
* llroundl: (libc)Rounding Functions.
|
* localeconv: (libc)The Lame Way to Locale Data.
|
* localtime: (libc)Broken-down Time.
|
* localtime_r: (libc)Broken-down Time.
|
* log10: (libc)Exponents and Logarithms.
|
* log10f: (libc)Exponents and Logarithms.
|
* log10fN: (libc)Exponents and Logarithms.
|
* log10fNx: (libc)Exponents and Logarithms.
|
* log10l: (libc)Exponents and Logarithms.
|
* log1p: (libc)Exponents and Logarithms.
|
* log1pf: (libc)Exponents and Logarithms.
|
* log1pfN: (libc)Exponents and Logarithms.
|
* log1pfNx: (libc)Exponents and Logarithms.
|
* log1pl: (libc)Exponents and Logarithms.
|
* log2: (libc)Exponents and Logarithms.
|
* log2f: (libc)Exponents and Logarithms.
|
* log2fN: (libc)Exponents and Logarithms.
|
* log2fNx: (libc)Exponents and Logarithms.
|
* log2l: (libc)Exponents and Logarithms.
|
* log: (libc)Exponents and Logarithms.
|
* logb: (libc)Exponents and Logarithms.
|
* logbf: (libc)Exponents and Logarithms.
|
* logbfN: (libc)Exponents and Logarithms.
|
* logbfNx: (libc)Exponents and Logarithms.
|
* logbl: (libc)Exponents and Logarithms.
|
* logf: (libc)Exponents and Logarithms.
|
* logfN: (libc)Exponents and Logarithms.
|
* logfNx: (libc)Exponents and Logarithms.
|
* login: (libc)Logging In and Out.
|
* login_tty: (libc)Logging In and Out.
|
* logl: (libc)Exponents and Logarithms.
|
* logout: (libc)Logging In and Out.
|
* logwtmp: (libc)Logging In and Out.
|
* longjmp: (libc)Non-Local Details.
|
* lrand48: (libc)SVID Random.
|
* lrand48_r: (libc)SVID Random.
|
* lrint: (libc)Rounding Functions.
|
* lrintf: (libc)Rounding Functions.
|
* lrintfN: (libc)Rounding Functions.
|
* lrintfNx: (libc)Rounding Functions.
|
* lrintl: (libc)Rounding Functions.
|
* lround: (libc)Rounding Functions.
|
* lroundf: (libc)Rounding Functions.
|
* lroundfN: (libc)Rounding Functions.
|
* lroundfNx: (libc)Rounding Functions.
|
* lroundl: (libc)Rounding Functions.
|
* lsearch: (libc)Array Search Function.
|
* lseek64: (libc)File Position Primitive.
|
* lseek: (libc)File Position Primitive.
|
* lstat64: (libc)Reading Attributes.
|
* lstat: (libc)Reading Attributes.
|
* lutimes: (libc)File Times.
|
* madvise: (libc)Memory-mapped I/O.
|
* makecontext: (libc)System V contexts.
|
* mallinfo2: (libc)Statistics of Malloc.
|
* malloc: (libc)Basic Allocation.
|
* mallopt: (libc)Malloc Tunable Parameters.
|
* mblen: (libc)Non-reentrant Character Conversion.
|
* mbrlen: (libc)Converting a Character.
|
* mbrtowc: (libc)Converting a Character.
|
* mbsinit: (libc)Keeping the state.
|
* mbsnrtowcs: (libc)Converting Strings.
|
* mbsrtowcs: (libc)Converting Strings.
|
* mbstowcs: (libc)Non-reentrant String Conversion.
|
* mbtowc: (libc)Non-reentrant Character Conversion.
|
* mcheck: (libc)Heap Consistency Checking.
|
* memalign: (libc)Aligned Memory Blocks.
|
* memccpy: (libc)Copying Strings and Arrays.
|
* memchr: (libc)Search Functions.
|
* memcmp: (libc)String/Array Comparison.
|
* memcpy: (libc)Copying Strings and Arrays.
|
* memfd_create: (libc)Memory-mapped I/O.
|
* memfrob: (libc)Obfuscating Data.
|
* memmem: (libc)Search Functions.
|
* memmove: (libc)Copying Strings and Arrays.
|
* mempcpy: (libc)Copying Strings and Arrays.
|
* memrchr: (libc)Search Functions.
|
* memset: (libc)Copying Strings and Arrays.
|
* mkdir: (libc)Creating Directories.
|
* mkdtemp: (libc)Temporary Files.
|
* mkfifo: (libc)FIFO Special Files.
|
* mknod: (libc)Making Special Files.
|
* mkstemp: (libc)Temporary Files.
|
* mktemp: (libc)Temporary Files.
|
* mktime: (libc)Broken-down Time.
|
* mlock2: (libc)Page Lock Functions.
|
* mlock: (libc)Page Lock Functions.
|
* mlockall: (libc)Page Lock Functions.
|
* mmap64: (libc)Memory-mapped I/O.
|
* mmap: (libc)Memory-mapped I/O.
|
* modf: (libc)Rounding Functions.
|
* modff: (libc)Rounding Functions.
|
* modffN: (libc)Rounding Functions.
|
* modffNx: (libc)Rounding Functions.
|
* modfl: (libc)Rounding Functions.
|
* mount: (libc)Mount-Unmount-Remount.
|
* mprobe: (libc)Heap Consistency Checking.
|
* mprotect: (libc)Memory Protection.
|
* mrand48: (libc)SVID Random.
|
* mrand48_r: (libc)SVID Random.
|
* mremap: (libc)Memory-mapped I/O.
|
* msync: (libc)Memory-mapped I/O.
|
* mtrace: (libc)Tracing malloc.
|
* mtx_destroy: (libc)ISO C Mutexes.
|
* mtx_init: (libc)ISO C Mutexes.
|
* mtx_lock: (libc)ISO C Mutexes.
|
* mtx_timedlock: (libc)ISO C Mutexes.
|
* mtx_trylock: (libc)ISO C Mutexes.
|
* mtx_unlock: (libc)ISO C Mutexes.
|
* munlock: (libc)Page Lock Functions.
|
* munlockall: (libc)Page Lock Functions.
|
* munmap: (libc)Memory-mapped I/O.
|
* muntrace: (libc)Tracing malloc.
|
* nan: (libc)FP Bit Twiddling.
|
* nanf: (libc)FP Bit Twiddling.
|
* nanfN: (libc)FP Bit Twiddling.
|
* nanfNx: (libc)FP Bit Twiddling.
|
* nanl: (libc)FP Bit Twiddling.
|
* nanosleep: (libc)Sleeping.
|
* nearbyint: (libc)Rounding Functions.
|
* nearbyintf: (libc)Rounding Functions.
|
* nearbyintfN: (libc)Rounding Functions.
|
* nearbyintfNx: (libc)Rounding Functions.
|
* nearbyintl: (libc)Rounding Functions.
|
* nextafter: (libc)FP Bit Twiddling.
|
* nextafterf: (libc)FP Bit Twiddling.
|
* nextafterfN: (libc)FP Bit Twiddling.
|
* nextafterfNx: (libc)FP Bit Twiddling.
|
* nextafterl: (libc)FP Bit Twiddling.
|
* nextdown: (libc)FP Bit Twiddling.
|
* nextdownf: (libc)FP Bit Twiddling.
|
* nextdownfN: (libc)FP Bit Twiddling.
|
* nextdownfNx: (libc)FP Bit Twiddling.
|
* nextdownl: (libc)FP Bit Twiddling.
|
* nexttoward: (libc)FP Bit Twiddling.
|
* nexttowardf: (libc)FP Bit Twiddling.
|
* nexttowardl: (libc)FP Bit Twiddling.
|
* nextup: (libc)FP Bit Twiddling.
|
* nextupf: (libc)FP Bit Twiddling.
|
* nextupfN: (libc)FP Bit Twiddling.
|
* nextupfNx: (libc)FP Bit Twiddling.
|
* nextupl: (libc)FP Bit Twiddling.
|
* nftw64: (libc)Working with Directory Trees.
|
* nftw: (libc)Working with Directory Trees.
|
* ngettext: (libc)Advanced gettext functions.
|
* nice: (libc)Traditional Scheduling Functions.
|
* nl_langinfo: (libc)The Elegant and Fast Way.
|
* nrand48: (libc)SVID Random.
|
* nrand48_r: (libc)SVID Random.
|
* ntohl: (libc)Byte Order.
|
* ntohs: (libc)Byte Order.
|
* ntp_adjtime: (libc)Setting and Adjusting the Time.
|
* ntp_gettime: (libc)Setting and Adjusting the Time.
|
* obstack_1grow: (libc)Growing Objects.
|
* obstack_1grow_fast: (libc)Extra Fast Growing.
|
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
|
* obstack_alloc: (libc)Allocation in an Obstack.
|
* obstack_base: (libc)Status of an Obstack.
|
* obstack_blank: (libc)Growing Objects.
|
* obstack_blank_fast: (libc)Extra Fast Growing.
|
* obstack_chunk_size: (libc)Obstack Chunks.
|
* obstack_copy0: (libc)Allocation in an Obstack.
|
* obstack_copy: (libc)Allocation in an Obstack.
|
* obstack_finish: (libc)Growing Objects.
|
* obstack_free: (libc)Freeing Obstack Objects.
|
* obstack_grow0: (libc)Growing Objects.
|
* obstack_grow: (libc)Growing Objects.
|
* obstack_init: (libc)Preparing for Obstacks.
|
* obstack_int_grow: (libc)Growing Objects.
|
* obstack_int_grow_fast: (libc)Extra Fast Growing.
|
* obstack_next_free: (libc)Status of an Obstack.
|
* obstack_object_size: (libc)Growing Objects.
|
* obstack_object_size: (libc)Status of an Obstack.
|
* obstack_printf: (libc)Dynamic Output.
|
* obstack_ptr_grow: (libc)Growing Objects.
|
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
|
* obstack_room: (libc)Extra Fast Growing.
|
* obstack_vprintf: (libc)Variable Arguments Output.
|
* offsetof: (libc)Structure Measurement.
|
* on_exit: (libc)Cleanups on Exit.
|
* open64: (libc)Opening and Closing Files.
|
* open: (libc)Opening and Closing Files.
|
* open_memstream: (libc)String Streams.
|
* opendir: (libc)Opening a Directory.
|
* openlog: (libc)openlog.
|
* openpty: (libc)Pseudo-Terminal Pairs.
|
* parse_printf_format: (libc)Parsing a Template String.
|
* pathconf: (libc)Pathconf.
|
* pause: (libc)Using Pause.
|
* pclose: (libc)Pipe to a Subprocess.
|
* perror: (libc)Error Messages.
|
* pipe: (libc)Creating a Pipe.
|
* pkey_alloc: (libc)Memory Protection.
|
* pkey_free: (libc)Memory Protection.
|
* pkey_get: (libc)Memory Protection.
|
* pkey_mprotect: (libc)Memory Protection.
|
* pkey_set: (libc)Memory Protection.
|
* popen: (libc)Pipe to a Subprocess.
|
* posix_fallocate64: (libc)Storage Allocation.
|
* posix_fallocate: (libc)Storage Allocation.
|
* posix_memalign: (libc)Aligned Memory Blocks.
|
* pow: (libc)Exponents and Logarithms.
|
* powf: (libc)Exponents and Logarithms.
|
* powfN: (libc)Exponents and Logarithms.
|
* powfNx: (libc)Exponents and Logarithms.
|
* powl: (libc)Exponents and Logarithms.
|
* pread64: (libc)I/O Primitives.
|
* pread: (libc)I/O Primitives.
|
* preadv2: (libc)Scatter-Gather.
|
* preadv64: (libc)Scatter-Gather.
|
* preadv64v2: (libc)Scatter-Gather.
|
* preadv: (libc)Scatter-Gather.
|
* printf: (libc)Formatted Output Functions.
|
* printf_size: (libc)Predefined Printf Handlers.
|
* printf_size_info: (libc)Predefined Printf Handlers.
|
* psignal: (libc)Signal Messages.
|
* pthread_attr_getsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_attr_setsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_clockjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_cond_clockwait: (libc)Waiting with Explicit Clocks.
|
* pthread_getattr_default_np: (libc)Default Thread Attributes.
|
* pthread_getspecific: (libc)Thread-specific Data.
|
* pthread_key_create: (libc)Thread-specific Data.
|
* pthread_key_delete: (libc)Thread-specific Data.
|
* pthread_rwlock_clockrdlock: (libc)Waiting with Explicit Clocks.
|
* pthread_rwlock_clockwrlock: (libc)Waiting with Explicit Clocks.
|
* pthread_setattr_default_np: (libc)Default Thread Attributes.
|
* pthread_setspecific: (libc)Thread-specific Data.
|
* pthread_timedjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_tryjoin_np: (libc)Waiting with Explicit Clocks.
|
* ptsname: (libc)Allocation.
|
* ptsname_r: (libc)Allocation.
|
* putc: (libc)Simple Output.
|
* putc_unlocked: (libc)Simple Output.
|
* putchar: (libc)Simple Output.
|
* putchar_unlocked: (libc)Simple Output.
|
* putenv: (libc)Environment Access.
|
* putpwent: (libc)Writing a User Entry.
|
* puts: (libc)Simple Output.
|
* pututline: (libc)Manipulating the Database.
|
* pututxline: (libc)XPG Functions.
|
* putw: (libc)Simple Output.
|
* putwc: (libc)Simple Output.
|
* putwc_unlocked: (libc)Simple Output.
|
* putwchar: (libc)Simple Output.
|
* putwchar_unlocked: (libc)Simple Output.
|
* pwrite64: (libc)I/O Primitives.
|
* pwrite: (libc)I/O Primitives.
|
* pwritev2: (libc)Scatter-Gather.
|
* pwritev64: (libc)Scatter-Gather.
|
* pwritev64v2: (libc)Scatter-Gather.
|
* pwritev: (libc)Scatter-Gather.
|
* qecvt: (libc)System V Number Conversion.
|
* qecvt_r: (libc)System V Number Conversion.
|
* qfcvt: (libc)System V Number Conversion.
|
* qfcvt_r: (libc)System V Number Conversion.
|
* qgcvt: (libc)System V Number Conversion.
|
* qsort: (libc)Array Sort Function.
|
* raise: (libc)Signaling Yourself.
|
* rand: (libc)ISO Random.
|
* rand_r: (libc)ISO Random.
|
* random: (libc)BSD Random.
|
* random_r: (libc)BSD Random.
|
* rawmemchr: (libc)Search Functions.
|
* read: (libc)I/O Primitives.
|
* readdir64: (libc)Reading/Closing Directory.
|
* readdir64_r: (libc)Reading/Closing Directory.
|
* readdir: (libc)Reading/Closing Directory.
|
* readdir_r: (libc)Reading/Closing Directory.
|
* readlink: (libc)Symbolic Links.
|
* readv: (libc)Scatter-Gather.
|
* realloc: (libc)Changing Block Size.
|
* reallocarray: (libc)Changing Block Size.
|
* realpath: (libc)Symbolic Links.
|
* recv: (libc)Receiving Data.
|
* recvfrom: (libc)Receiving Datagrams.
|
* recvmsg: (libc)Receiving Datagrams.
|
* regcomp: (libc)POSIX Regexp Compilation.
|
* regerror: (libc)Regexp Cleanup.
|
* regexec: (libc)Matching POSIX Regexps.
|
* regfree: (libc)Regexp Cleanup.
|
* register_printf_function: (libc)Registering New Conversions.
|
* remainder: (libc)Remainder Functions.
|
* remainderf: (libc)Remainder Functions.
|
* remainderfN: (libc)Remainder Functions.
|
* remainderfNx: (libc)Remainder Functions.
|
* remainderl: (libc)Remainder Functions.
|
* remove: (libc)Deleting Files.
|
* rename: (libc)Renaming Files.
|
* rewind: (libc)File Positioning.
|
* rewinddir: (libc)Random Access Directory.
|
* rindex: (libc)Search Functions.
|
* rint: (libc)Rounding Functions.
|
* rintf: (libc)Rounding Functions.
|
* rintfN: (libc)Rounding Functions.
|
* rintfNx: (libc)Rounding Functions.
|
* rintl: (libc)Rounding Functions.
|
* rmdir: (libc)Deleting Files.
|
* round: (libc)Rounding Functions.
|
* roundeven: (libc)Rounding Functions.
|
* roundevenf: (libc)Rounding Functions.
|
* roundevenfN: (libc)Rounding Functions.
|
* roundevenfNx: (libc)Rounding Functions.
|
* roundevenl: (libc)Rounding Functions.
|
* roundf: (libc)Rounding Functions.
|
* roundfN: (libc)Rounding Functions.
|
* roundfNx: (libc)Rounding Functions.
|
* roundl: (libc)Rounding Functions.
|
* rpmatch: (libc)Yes-or-No Questions.
|
* sbrk: (libc)Resizing the Data Segment.
|
* scalb: (libc)Normalization Functions.
|
* scalbf: (libc)Normalization Functions.
|
* scalbl: (libc)Normalization Functions.
|
* scalbln: (libc)Normalization Functions.
|
* scalblnf: (libc)Normalization Functions.
|
* scalblnfN: (libc)Normalization Functions.
|
* scalblnfNx: (libc)Normalization Functions.
|
* scalblnl: (libc)Normalization Functions.
|
* scalbn: (libc)Normalization Functions.
|
* scalbnf: (libc)Normalization Functions.
|
* scalbnfN: (libc)Normalization Functions.
|
* scalbnfNx: (libc)Normalization Functions.
|
* scalbnl: (libc)Normalization Functions.
|
* scandir64: (libc)Scanning Directory Content.
|
* scandir: (libc)Scanning Directory Content.
|
* scanf: (libc)Formatted Input Functions.
|
* sched_get_priority_max: (libc)Basic Scheduling Functions.
|
* sched_get_priority_min: (libc)Basic Scheduling Functions.
|
* sched_getaffinity: (libc)CPU Affinity.
|
* sched_getparam: (libc)Basic Scheduling Functions.
|
* sched_getscheduler: (libc)Basic Scheduling Functions.
|
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
|
* sched_setaffinity: (libc)CPU Affinity.
|
* sched_setparam: (libc)Basic Scheduling Functions.
|
* sched_setscheduler: (libc)Basic Scheduling Functions.
|
* sched_yield: (libc)Basic Scheduling Functions.
|
* secure_getenv: (libc)Environment Access.
|
* seed48: (libc)SVID Random.
|
* seed48_r: (libc)SVID Random.
|
* seekdir: (libc)Random Access Directory.
|
* select: (libc)Waiting for I/O.
|
* sem_clockwait: (libc)Waiting with Explicit Clocks.
|
* sem_close: (libc)Semaphores.
|
* sem_destroy: (libc)Semaphores.
|
* sem_getvalue: (libc)Semaphores.
|
* sem_init: (libc)Semaphores.
|
* sem_open: (libc)Semaphores.
|
* sem_post: (libc)Semaphores.
|
* sem_timedwait: (libc)Semaphores.
|
* sem_trywait: (libc)Semaphores.
|
* sem_unlink: (libc)Semaphores.
|
* sem_wait: (libc)Semaphores.
|
* semctl: (libc)Semaphores.
|
* semget: (libc)Semaphores.
|
* semop: (libc)Semaphores.
|
* semtimedop: (libc)Semaphores.
|
* send: (libc)Sending Data.
|
* sendmsg: (libc)Receiving Datagrams.
|
* sendto: (libc)Sending Datagrams.
|
* setbuf: (libc)Controlling Buffering.
|
* setbuffer: (libc)Controlling Buffering.
|
* setcontext: (libc)System V contexts.
|
* setdomainname: (libc)Host Identification.
|
* setegid: (libc)Setting Groups.
|
* setenv: (libc)Environment Access.
|
* seteuid: (libc)Setting User ID.
|
* setfsent: (libc)fstab.
|
* setgid: (libc)Setting Groups.
|
* setgrent: (libc)Scanning All Groups.
|
* setgroups: (libc)Setting Groups.
|
* sethostent: (libc)Host Names.
|
* sethostid: (libc)Host Identification.
|
* sethostname: (libc)Host Identification.
|
* setitimer: (libc)Setting an Alarm.
|
* setjmp: (libc)Non-Local Details.
|
* setlinebuf: (libc)Controlling Buffering.
|
* setlocale: (libc)Setting the Locale.
|
* setlogmask: (libc)setlogmask.
|
* setmntent: (libc)mtab.
|
* setnetent: (libc)Networks Database.
|
* setnetgrent: (libc)Lookup Netgroup.
|
* setpayload: (libc)FP Bit Twiddling.
|
* setpayloadf: (libc)FP Bit Twiddling.
|
* setpayloadfN: (libc)FP Bit Twiddling.
|
* setpayloadfNx: (libc)FP Bit Twiddling.
|
* setpayloadl: (libc)FP Bit Twiddling.
|
* setpayloadsig: (libc)FP Bit Twiddling.
|
* setpayloadsigf: (libc)FP Bit Twiddling.
|
* setpayloadsigfN: (libc)FP Bit Twiddling.
|
* setpayloadsigfNx: (libc)FP Bit Twiddling.
|
* setpayloadsigl: (libc)FP Bit Twiddling.
|
* setpgid: (libc)Process Group Functions.
|
* setpgrp: (libc)Process Group Functions.
|
* setpriority: (libc)Traditional Scheduling Functions.
|
* setprotoent: (libc)Protocols Database.
|
* setpwent: (libc)Scanning All Users.
|
* setregid: (libc)Setting Groups.
|
* setreuid: (libc)Setting User ID.
|
* setrlimit64: (libc)Limits on Resources.
|
* setrlimit: (libc)Limits on Resources.
|
* setservent: (libc)Services Database.
|
* setsid: (libc)Process Group Functions.
|
* setsockopt: (libc)Socket Option Functions.
|
* setstate: (libc)BSD Random.
|
* setstate_r: (libc)BSD Random.
|
* settimeofday: (libc)Setting and Adjusting the Time.
|
* setuid: (libc)Setting User ID.
|
* setutent: (libc)Manipulating the Database.
|
* setutxent: (libc)XPG Functions.
|
* setvbuf: (libc)Controlling Buffering.
|
* shm_open: (libc)Memory-mapped I/O.
|
* shm_unlink: (libc)Memory-mapped I/O.
|
* shutdown: (libc)Closing a Socket.
|
* sigabbrev_np: (libc)Signal Messages.
|
* sigaction: (libc)Advanced Signal Handling.
|
* sigaddset: (libc)Signal Sets.
|
* sigaltstack: (libc)Signal Stack.
|
* sigblock: (libc)BSD Signal Handling.
|
* sigdelset: (libc)Signal Sets.
|
* sigdescr_np: (libc)Signal Messages.
|
* sigemptyset: (libc)Signal Sets.
|
* sigfillset: (libc)Signal Sets.
|
* siginterrupt: (libc)BSD Signal Handling.
|
* sigismember: (libc)Signal Sets.
|
* siglongjmp: (libc)Non-Local Exits and Signals.
|
* sigmask: (libc)BSD Signal Handling.
|
* signal: (libc)Basic Signal Handling.
|
* signbit: (libc)FP Bit Twiddling.
|
* significand: (libc)Normalization Functions.
|
* significandf: (libc)Normalization Functions.
|
* significandl: (libc)Normalization Functions.
|
* sigpause: (libc)BSD Signal Handling.
|
* sigpending: (libc)Checking for Pending Signals.
|
* sigprocmask: (libc)Process Signal Mask.
|
* sigsetjmp: (libc)Non-Local Exits and Signals.
|
* sigsetmask: (libc)BSD Signal Handling.
|
* sigstack: (libc)Signal Stack.
|
* sigsuspend: (libc)Sigsuspend.
|
* sin: (libc)Trig Functions.
|
* sincos: (libc)Trig Functions.
|
* sincosf: (libc)Trig Functions.
|
* sincosfN: (libc)Trig Functions.
|
* sincosfNx: (libc)Trig Functions.
|
* sincosl: (libc)Trig Functions.
|
* sinf: (libc)Trig Functions.
|
* sinfN: (libc)Trig Functions.
|
* sinfNx: (libc)Trig Functions.
|
* sinh: (libc)Hyperbolic Functions.
|
* sinhf: (libc)Hyperbolic Functions.
|
* sinhfN: (libc)Hyperbolic Functions.
|
* sinhfNx: (libc)Hyperbolic Functions.
|
* sinhl: (libc)Hyperbolic Functions.
|
* sinl: (libc)Trig Functions.
|
* sleep: (libc)Sleeping.
|
* snprintf: (libc)Formatted Output Functions.
|
* socket: (libc)Creating a Socket.
|
* socketpair: (libc)Socket Pairs.
|
* sprintf: (libc)Formatted Output Functions.
|
* sqrt: (libc)Exponents and Logarithms.
|
* sqrtf: (libc)Exponents and Logarithms.
|
* sqrtfN: (libc)Exponents and Logarithms.
|
* sqrtfNx: (libc)Exponents and Logarithms.
|
* sqrtl: (libc)Exponents and Logarithms.
|
* srand48: (libc)SVID Random.
|
* srand48_r: (libc)SVID Random.
|
* srand: (libc)ISO Random.
|
* srandom: (libc)BSD Random.
|
* srandom_r: (libc)BSD Random.
|
* sscanf: (libc)Formatted Input Functions.
|
* ssignal: (libc)Basic Signal Handling.
|
* stat64: (libc)Reading Attributes.
|
* stat: (libc)Reading Attributes.
|
* stime: (libc)Setting and Adjusting the Time.
|
* stpcpy: (libc)Copying Strings and Arrays.
|
* stpncpy: (libc)Truncating Strings.
|
* strcasecmp: (libc)String/Array Comparison.
|
* strcasestr: (libc)Search Functions.
|
* strcat: (libc)Concatenating Strings.
|
* strchr: (libc)Search Functions.
|
* strchrnul: (libc)Search Functions.
|
* strcmp: (libc)String/Array Comparison.
|
* strcoll: (libc)Collation Functions.
|
* strcpy: (libc)Copying Strings and Arrays.
|
* strcspn: (libc)Search Functions.
|
* strdup: (libc)Copying Strings and Arrays.
|
* strdupa: (libc)Copying Strings and Arrays.
|
* strerror: (libc)Error Messages.
|
* strerror_r: (libc)Error Messages.
|
* strerrordesc_np: (libc)Error Messages.
|
* strerrorname_np: (libc)Error Messages.
|
* strfmon: (libc)Formatting Numbers.
|
* strfromd: (libc)Printing of Floats.
|
* strfromf: (libc)Printing of Floats.
|
* strfromfN: (libc)Printing of Floats.
|
* strfromfNx: (libc)Printing of Floats.
|
* strfroml: (libc)Printing of Floats.
|
* strfry: (libc)Shuffling Bytes.
|
* strftime: (libc)Formatting Calendar Time.
|
* strlen: (libc)String Length.
|
* strncasecmp: (libc)String/Array Comparison.
|
* strncat: (libc)Truncating Strings.
|
* strncmp: (libc)String/Array Comparison.
|
* strncpy: (libc)Truncating Strings.
|
* strndup: (libc)Truncating Strings.
|
* strndupa: (libc)Truncating Strings.
|
* strnlen: (libc)String Length.
|
* strpbrk: (libc)Search Functions.
|
* strptime: (libc)Low-Level Time String Parsing.
|
* strrchr: (libc)Search Functions.
|
* strsep: (libc)Finding Tokens in a String.
|
* strsignal: (libc)Signal Messages.
|
* strspn: (libc)Search Functions.
|
* strstr: (libc)Search Functions.
|
* strtod: (libc)Parsing of Floats.
|
* strtof: (libc)Parsing of Floats.
|
* strtofN: (libc)Parsing of Floats.
|
* strtofNx: (libc)Parsing of Floats.
|
* strtoimax: (libc)Parsing of Integers.
|
* strtok: (libc)Finding Tokens in a String.
|
* strtok_r: (libc)Finding Tokens in a String.
|
* strtol: (libc)Parsing of Integers.
|
* strtold: (libc)Parsing of Floats.
|
* strtoll: (libc)Parsing of Integers.
|
* strtoq: (libc)Parsing of Integers.
|
* strtoul: (libc)Parsing of Integers.
|
* strtoull: (libc)Parsing of Integers.
|
* strtoumax: (libc)Parsing of Integers.
|
* strtouq: (libc)Parsing of Integers.
|
* strverscmp: (libc)String/Array Comparison.
|
* strxfrm: (libc)Collation Functions.
|
* stty: (libc)BSD Terminal Modes.
|
* swapcontext: (libc)System V contexts.
|
* swprintf: (libc)Formatted Output Functions.
|
* swscanf: (libc)Formatted Input Functions.
|
* symlink: (libc)Symbolic Links.
|
* sync: (libc)Synchronizing I/O.
|
* syscall: (libc)System Calls.
|
* sysconf: (libc)Sysconf Definition.
|
* syslog: (libc)syslog; vsyslog.
|
* system: (libc)Running a Command.
|
* sysv_signal: (libc)Basic Signal Handling.
|
* tan: (libc)Trig Functions.
|
* tanf: (libc)Trig Functions.
|
* tanfN: (libc)Trig Functions.
|
* tanfNx: (libc)Trig Functions.
|
* tanh: (libc)Hyperbolic Functions.
|
* tanhf: (libc)Hyperbolic Functions.
|
* tanhfN: (libc)Hyperbolic Functions.
|
* tanhfNx: (libc)Hyperbolic Functions.
|
* tanhl: (libc)Hyperbolic Functions.
|
* tanl: (libc)Trig Functions.
|
* tcdrain: (libc)Line Control.
|
* tcflow: (libc)Line Control.
|
* tcflush: (libc)Line Control.
|
* tcgetattr: (libc)Mode Functions.
|
* tcgetpgrp: (libc)Terminal Access Functions.
|
* tcgetsid: (libc)Terminal Access Functions.
|
* tcsendbreak: (libc)Line Control.
|
* tcsetattr: (libc)Mode Functions.
|
* tcsetpgrp: (libc)Terminal Access Functions.
|
* tdelete: (libc)Tree Search Function.
|
* tdestroy: (libc)Tree Search Function.
|
* telldir: (libc)Random Access Directory.
|
* tempnam: (libc)Temporary Files.
|
* textdomain: (libc)Locating gettext catalog.
|
* tfind: (libc)Tree Search Function.
|
* tgamma: (libc)Special Functions.
|
* tgammaf: (libc)Special Functions.
|
* tgammafN: (libc)Special Functions.
|
* tgammafNx: (libc)Special Functions.
|
* tgammal: (libc)Special Functions.
|
* tgkill: (libc)Signaling Another Process.
|
* thrd_create: (libc)ISO C Thread Management.
|
* thrd_current: (libc)ISO C Thread Management.
|
* thrd_detach: (libc)ISO C Thread Management.
|
* thrd_equal: (libc)ISO C Thread Management.
|
* thrd_exit: (libc)ISO C Thread Management.
|
* thrd_join: (libc)ISO C Thread Management.
|
* thrd_sleep: (libc)ISO C Thread Management.
|
* thrd_yield: (libc)ISO C Thread Management.
|
* time: (libc)Getting the Time.
|
* timegm: (libc)Broken-down Time.
|
* timelocal: (libc)Broken-down Time.
|
* times: (libc)Processor Time.
|
* tmpfile64: (libc)Temporary Files.
|
* tmpfile: (libc)Temporary Files.
|
* tmpnam: (libc)Temporary Files.
|
* tmpnam_r: (libc)Temporary Files.
|
* toascii: (libc)Case Conversion.
|
* tolower: (libc)Case Conversion.
|
* totalorder: (libc)FP Comparison Functions.
|
* totalorderf: (libc)FP Comparison Functions.
|
* totalorderfN: (libc)FP Comparison Functions.
|
* totalorderfNx: (libc)FP Comparison Functions.
|
* totalorderl: (libc)FP Comparison Functions.
|
* totalordermag: (libc)FP Comparison Functions.
|
* totalordermagf: (libc)FP Comparison Functions.
|
* totalordermagfN: (libc)FP Comparison Functions.
|
* totalordermagfNx: (libc)FP Comparison Functions.
|
* totalordermagl: (libc)FP Comparison Functions.
|
* toupper: (libc)Case Conversion.
|
* towctrans: (libc)Wide Character Case Conversion.
|
* towlower: (libc)Wide Character Case Conversion.
|
* towupper: (libc)Wide Character Case Conversion.
|
* trunc: (libc)Rounding Functions.
|
* truncate64: (libc)File Size.
|
* truncate: (libc)File Size.
|
* truncf: (libc)Rounding Functions.
|
* truncfN: (libc)Rounding Functions.
|
* truncfNx: (libc)Rounding Functions.
|
* truncl: (libc)Rounding Functions.
|
* tsearch: (libc)Tree Search Function.
|
* tss_create: (libc)ISO C Thread-local Storage.
|
* tss_delete: (libc)ISO C Thread-local Storage.
|
* tss_get: (libc)ISO C Thread-local Storage.
|
* tss_set: (libc)ISO C Thread-local Storage.
|
* ttyname: (libc)Is It a Terminal.
|
* ttyname_r: (libc)Is It a Terminal.
|
* twalk: (libc)Tree Search Function.
|
* twalk_r: (libc)Tree Search Function.
|
* tzset: (libc)Time Zone Functions.
|
* ufromfp: (libc)Rounding Functions.
|
* ufromfpf: (libc)Rounding Functions.
|
* ufromfpfN: (libc)Rounding Functions.
|
* ufromfpfNx: (libc)Rounding Functions.
|
* ufromfpl: (libc)Rounding Functions.
|
* ufromfpx: (libc)Rounding Functions.
|
* ufromfpxf: (libc)Rounding Functions.
|
* ufromfpxfN: (libc)Rounding Functions.
|
* ufromfpxfNx: (libc)Rounding Functions.
|
* ufromfpxl: (libc)Rounding Functions.
|
* ulimit: (libc)Limits on Resources.
|
* umask: (libc)Setting Permissions.
|
* umount2: (libc)Mount-Unmount-Remount.
|
* umount: (libc)Mount-Unmount-Remount.
|
* uname: (libc)Platform Type.
|
* ungetc: (libc)How Unread.
|
* ungetwc: (libc)How Unread.
|
* unlink: (libc)Deleting Files.
|
* unlockpt: (libc)Allocation.
|
* unsetenv: (libc)Environment Access.
|
* updwtmp: (libc)Manipulating the Database.
|
* utime: (libc)File Times.
|
* utimes: (libc)File Times.
|
* utmpname: (libc)Manipulating the Database.
|
* utmpxname: (libc)XPG Functions.
|
* va_arg: (libc)Argument Macros.
|
* va_copy: (libc)Argument Macros.
|
* va_end: (libc)Argument Macros.
|
* va_start: (libc)Argument Macros.
|
* valloc: (libc)Aligned Memory Blocks.
|
* vasprintf: (libc)Variable Arguments Output.
|
* verr: (libc)Error Messages.
|
* verrx: (libc)Error Messages.
|
* versionsort64: (libc)Scanning Directory Content.
|
* versionsort: (libc)Scanning Directory Content.
|
* vfork: (libc)Creating a Process.
|
* vfprintf: (libc)Variable Arguments Output.
|
* vfscanf: (libc)Variable Arguments Input.
|
* vfwprintf: (libc)Variable Arguments Output.
|
* vfwscanf: (libc)Variable Arguments Input.
|
* vlimit: (libc)Limits on Resources.
|
* vprintf: (libc)Variable Arguments Output.
|
* vscanf: (libc)Variable Arguments Input.
|
* vsnprintf: (libc)Variable Arguments Output.
|
* vsprintf: (libc)Variable Arguments Output.
|
* vsscanf: (libc)Variable Arguments Input.
|
* vswprintf: (libc)Variable Arguments Output.
|
* vswscanf: (libc)Variable Arguments Input.
|
* vsyslog: (libc)syslog; vsyslog.
|
* vwarn: (libc)Error Messages.
|
* vwarnx: (libc)Error Messages.
|
* vwprintf: (libc)Variable Arguments Output.
|
* vwscanf: (libc)Variable Arguments Input.
|
* wait3: (libc)BSD Wait Functions.
|
* wait4: (libc)Process Completion.
|
* wait: (libc)Process Completion.
|
* waitpid: (libc)Process Completion.
|
* warn: (libc)Error Messages.
|
* warnx: (libc)Error Messages.
|
* wcpcpy: (libc)Copying Strings and Arrays.
|
* wcpncpy: (libc)Truncating Strings.
|
* wcrtomb: (libc)Converting a Character.
|
* wcscasecmp: (libc)String/Array Comparison.
|
* wcscat: (libc)Concatenating Strings.
|
* wcschr: (libc)Search Functions.
|
* wcschrnul: (libc)Search Functions.
|
* wcscmp: (libc)String/Array Comparison.
|
* wcscoll: (libc)Collation Functions.
|
* wcscpy: (libc)Copying Strings and Arrays.
|
* wcscspn: (libc)Search Functions.
|
* wcsdup: (libc)Copying Strings and Arrays.
|
* wcsftime: (libc)Formatting Calendar Time.
|
* wcslen: (libc)String Length.
|
* wcsncasecmp: (libc)String/Array Comparison.
|
* wcsncat: (libc)Truncating Strings.
|
* wcsncmp: (libc)String/Array Comparison.
|
* wcsncpy: (libc)Truncating Strings.
|
* wcsnlen: (libc)String Length.
|
* wcsnrtombs: (libc)Converting Strings.
|
* wcspbrk: (libc)Search Functions.
|
* wcsrchr: (libc)Search Functions.
|
* wcsrtombs: (libc)Converting Strings.
|
* wcsspn: (libc)Search Functions.
|
* wcsstr: (libc)Search Functions.
|
* wcstod: (libc)Parsing of Floats.
|
* wcstof: (libc)Parsing of Floats.
|
* wcstofN: (libc)Parsing of Floats.
|
* wcstofNx: (libc)Parsing of Floats.
|
* wcstoimax: (libc)Parsing of Integers.
|
* wcstok: (libc)Finding Tokens in a String.
|
* wcstol: (libc)Parsing of Integers.
|
* wcstold: (libc)Parsing of Floats.
|
* wcstoll: (libc)Parsing of Integers.
|
* wcstombs: (libc)Non-reentrant String Conversion.
|
* wcstoq: (libc)Parsing of Integers.
|
* wcstoul: (libc)Parsing of Integers.
|
* wcstoull: (libc)Parsing of Integers.
|
* wcstoumax: (libc)Parsing of Integers.
|
* wcstouq: (libc)Parsing of Integers.
|
* wcswcs: (libc)Search Functions.
|
* wcsxfrm: (libc)Collation Functions.
|
* wctob: (libc)Converting a Character.
|
* wctomb: (libc)Non-reentrant Character Conversion.
|
* wctrans: (libc)Wide Character Case Conversion.
|
* wctype: (libc)Classification of Wide Characters.
|
* wmemchr: (libc)Search Functions.
|
* wmemcmp: (libc)String/Array Comparison.
|
* wmemcpy: (libc)Copying Strings and Arrays.
|
* wmemmove: (libc)Copying Strings and Arrays.
|
* wmempcpy: (libc)Copying Strings and Arrays.
|
* wmemset: (libc)Copying Strings and Arrays.
|
* wordexp: (libc)Calling Wordexp.
|
* wordfree: (libc)Calling Wordexp.
|
* wprintf: (libc)Formatted Output Functions.
|
* write: (libc)I/O Primitives.
|
* writev: (libc)Scatter-Gather.
|
* wscanf: (libc)Formatted Input Functions.
|
* y0: (libc)Special Functions.
|
* y0f: (libc)Special Functions.
|
* y0fN: (libc)Special Functions.
|
* y0fNx: (libc)Special Functions.
|
* y0l: (libc)Special Functions.
|
* y1: (libc)Special Functions.
|
* y1f: (libc)Special Functions.
|
* y1fN: (libc)Special Functions.
|
* y1fNx: (libc)Special Functions.
|
* y1l: (libc)Special Functions.
|
* yn: (libc)Special Functions.
|
* ynf: (libc)Special Functions.
|
* ynfN: (libc)Special Functions.
|
* ynfNx: (libc)Special Functions.
|
* ynl: (libc)Special Functions.
|
END-INFO-DIR-ENTRY
|
|
|
File: libc.info, Node: The message catalog files, Next: The gencat program, Prev: The catgets Functions, Up: Message catalogs a la X/Open
|
|
8.1.2 Format of the message catalog files
|
-----------------------------------------
|
|
The only reasonable way to translate all the messages of a function and
|
store the result in a message catalog file which can be read by the
|
‘catopen’ function is to write all the message text to the translator
|
and let her/him translate them all. I.e., we must have a file with
|
entries which associate the set/message tuple with a specific
|
translation. This file format is specified in the X/Open standard and
|
is as follows:
|
|
• Lines containing only whitespace characters or empty lines are
|
ignored.
|
|
• Lines which contain as the first non-whitespace character a ‘$’
|
followed by a whitespace character are comment and are also
|
ignored.
|
|
• If a line contains as the first non-whitespace characters the
|
sequence ‘$set’ followed by a whitespace character an additional
|
argument is required to follow. This argument can either be:
|
|
− a number. In this case the value of this number determines
|
the set to which the following messages are added.
|
|
− an identifier consisting of alphanumeric characters plus the
|
underscore character. In this case the set get automatically
|
a number assigned. This value is one added to the largest set
|
number which so far appeared.
|
|
How to use the symbolic names is explained in section *note
|
Common Usage::.
|
|
It is an error if a symbol name appears more than once. All
|
following messages are placed in a set with this number.
|
|
• If a line contains as the first non-whitespace characters the
|
sequence ‘$delset’ followed by a whitespace character an additional
|
argument is required to follow. This argument can either be:
|
|
− a number. In this case the value of this number determines
|
the set which will be deleted.
|
|
− an identifier consisting of alphanumeric characters plus the
|
underscore character. This symbolic identifier must match a
|
name for a set which previously was defined. It is an error
|
if the name is unknown.
|
|
In both cases all messages in the specified set will be removed.
|
They will not appear in the output. But if this set is later again
|
selected with a ‘$set’ command again messages could be added and
|
these messages will appear in the output.
|
|
• If a line contains after leading whitespaces the sequence ‘$quote’,
|
the quoting character used for this input file is changed to the
|
first non-whitespace character following ‘$quote’. If no
|
non-whitespace character is present before the line ends quoting is
|
disabled.
|
|
By default no quoting character is used. In this mode strings are
|
terminated with the first unescaped line break. If there is a
|
‘$quote’ sequence present newline need not be escaped. Instead a
|
string is terminated with the first unescaped appearance of the
|
quote character.
|
|
A common usage of this feature would be to set the quote character
|
to ‘"’. Then any appearance of the ‘"’ in the strings must be
|
escaped using the backslash (i.e., ‘\"’ must be written).
|
|
• Any other line must start with a number or an alphanumeric
|
identifier (with the underscore character included). The following
|
characters (starting after the first whitespace character) will
|
form the string which gets associated with the currently selected
|
set and the message number represented by the number and identifier
|
respectively.
|
|
If the start of the line is a number the message number is obvious.
|
It is an error if the same message number already appeared for this
|
set.
|
|
If the leading token was an identifier the message number gets
|
automatically assigned. The value is the current maximum message
|
number for this set plus one. It is an error if the identifier was
|
already used for a message in this set. It is OK to reuse the
|
identifier for a message in another thread. How to use the
|
symbolic identifiers will be explained below (*note Common
|
Usage::). There is one limitation with the identifier: it must not
|
be ‘Set’. The reason will be explained below.
|
|
The text of the messages can contain escape characters. The usual
|
bunch of characters known from the ISO C language are recognized
|
(‘\n’, ‘\t’, ‘\v’, ‘\b’, ‘\r’, ‘\f’, ‘\\’, and ‘\NNN’, where NNN is
|
the octal coding of a character code).
|
|
*Important:* The handling of identifiers instead of numbers for the
|
set and messages is a GNU extension. Systems strictly following the
|
X/Open specification do not have this feature. An example for a message
|
catalog file is this:
|
|
$ This is a leading comment.
|
$quote "
|
|
$set SetOne
|
1 Message with ID 1.
|
two " Message with ID \"two\", which gets the value 2 assigned"
|
|
$set SetTwo
|
$ Since the last set got the number 1 assigned this set has number 2.
|
4000 "The numbers can be arbitrary, they need not start at one."
|
|
This small example shows various aspects:
|
• Lines 1 and 9 are comments since they start with ‘$’ followed by a
|
whitespace.
|
• The quoting character is set to ‘"’. Otherwise the quotes in the
|
message definition would have to be omitted and in this case the
|
message with the identifier ‘two’ would lose its leading
|
whitespace.
|
• Mixing numbered messages with messages having symbolic names is no
|
problem and the numbering happens automatically.
|
|
While this file format is pretty easy it is not the best possible for
|
use in a running program. The ‘catopen’ function would have to parse
|
the file and handle syntactic errors gracefully. This is not so easy
|
and the whole process is pretty slow. Therefore the ‘catgets’ functions
|
expect the data in another more compact and ready-to-use file format.
|
There is a special program ‘gencat’ which is explained in detail in the
|
next section.
|
|
Files in this other format are not human readable. To be easy to use
|
by programs it is a binary file. But the format is byte order
|
independent so translation files can be shared by systems of arbitrary
|
architecture (as long as they use the GNU C Library).
|
|
Details about the binary file format are not important to know since
|
these files are always created by the ‘gencat’ program. The sources of
|
the GNU C Library also provide the sources for the ‘gencat’ program and
|
so the interested reader can look through these source files to learn
|
about the file format.
|
|
|
File: libc.info, Node: The gencat program, Next: Common Usage, Prev: The message catalog files, Up: Message catalogs a la X/Open
|
|
8.1.3 Generate Message Catalogs files
|
-------------------------------------
|
|
The ‘gencat’ program is specified in the X/Open standard and the GNU
|
implementation follows this specification and so processes all correctly
|
formed input files. Additionally some extension are implemented which
|
help to work in a more reasonable way with the ‘catgets’ functions.
|
|
The ‘gencat’ program can be invoked in two ways:
|
|
`gencat [OPTION …] [OUTPUT-FILE [INPUT-FILE …]]`
|
|
This is the interface defined in the X/Open standard. If no
|
INPUT-FILE parameter is given, input will be read from standard input.
|
Multiple input files will be read as if they were concatenated. If
|
OUTPUT-FILE is also missing, the output will be written to standard
|
output. To provide the interface one is used to from other programs a
|
second interface is provided.
|
|
`gencat [OPTION …] -o OUTPUT-FILE [INPUT-FILE …]`
|
|
The option ‘-o’ is used to specify the output file and all file
|
arguments are used as input files.
|
|
Beside this one can use ‘-’ or ‘/dev/stdin’ for INPUT-FILE to denote
|
the standard input. Corresponding one can use ‘-’ and ‘/dev/stdout’ for
|
OUTPUT-FILE to denote standard output. Using ‘-’ as a file name is
|
allowed in X/Open while using the device names is a GNU extension.
|
|
The ‘gencat’ program works by concatenating all input files and then
|
*merging* the resulting collection of message sets with a possibly
|
existing output file. This is done by removing all messages with
|
set/message number tuples matching any of the generated messages from
|
the output file and then adding all the new messages. To regenerate a
|
catalog file while ignoring the old contents therefore requires removing
|
the output file if it exists. If the output is written to standard
|
output no merging takes place.
|
|
The following table shows the options understood by the ‘gencat’
|
program. The X/Open standard does not specify any options for the
|
program so all of these are GNU extensions.
|
|
‘-V’
|
‘--version’
|
Print the version information and exit.
|
‘-h’
|
‘--help’
|
Print a usage message listing all available options, then exit
|
successfully.
|
‘--new’
|
Do not merge the new messages from the input files with the old
|
content of the output file. The old content of the output file is
|
discarded.
|
‘-H’
|
‘--header=name’
|
This option is used to emit the symbolic names given to sets and
|
messages in the input files for use in the program. Details about
|
how to use this are given in the next section. The NAME parameter
|
to this option specifies the name of the output file. It will
|
contain a number of C preprocessor ‘#define’s to associate a name
|
with a number.
|
|
Please note that the generated file only contains the symbols from
|
the input files. If the output is merged with the previous content
|
of the output file the possibly existing symbols from the file(s)
|
which generated the old output files are not in the generated
|
header file.
|
|
|
File: libc.info, Node: Common Usage, Prev: The gencat program, Up: Message catalogs a la X/Open
|
|
8.1.4 How to use the ‘catgets’ interface
|
----------------------------------------
|
|
The ‘catgets’ functions can be used in two different ways. By following
|
slavishly the X/Open specs and not relying on the extension and by using
|
the GNU extensions. We will take a look at the former method first to
|
understand the benefits of extensions.
|
|
8.1.4.1 Not using symbolic names
|
................................
|
|
Since the X/Open format of the message catalog files does not allow
|
symbol names we have to work with numbers all the time. When we start
|
writing a program we have to replace all appearances of translatable
|
strings with something like
|
|
catgets (catdesc, set, msg, "string")
|
|
CATGETS is retrieved from a call to ‘catopen’ which is normally done
|
once at the program start. The ‘"string"’ is the string we want to
|
translate. The problems start with the set and message numbers.
|
|
In a bigger program several programmers usually work at the same time
|
on the program and so coordinating the number allocation is crucial.
|
Though no two different strings must be indexed by the same tuple of
|
numbers it is highly desirable to reuse the numbers for equal strings
|
with equal translations (please note that there might be strings which
|
are equal in one language but have different translations due to
|
difference contexts).
|
|
The allocation process can be relaxed a bit by different set numbers
|
for different parts of the program. So the number of developers who
|
have to coordinate the allocation can be reduced. But still lists must
|
be keep track of the allocation and errors can easily happen. These
|
errors cannot be discovered by the compiler or the ‘catgets’ functions.
|
Only the user of the program might see wrong messages printed. In the
|
worst cases the messages are so irritating that they cannot be
|
recognized as wrong. Think about the translations for ‘"true"’ and
|
‘"false"’ being exchanged. This could result in a disaster.
|
|
8.1.4.2 Using symbolic names
|
............................
|
|
The problems mentioned in the last section derive from the fact that:
|
|
1. the numbers are allocated once and due to the possibly frequent use
|
of them it is difficult to change a number later.
|
2. the numbers do not allow guessing anything about the string and
|
therefore collisions can easily happen.
|
|
By constantly using symbolic names and by providing a method which
|
maps the string content to a symbolic name (however this will happen)
|
one can prevent both problems above. The cost of this is that the
|
programmer has to write a complete message catalog file while s/he is
|
writing the program itself.
|
|
This is necessary since the symbolic names must be mapped to numbers
|
before the program sources can be compiled. In the last section it was
|
described how to generate a header containing the mapping of the names.
|
E.g., for the example message file given in the last section we could
|
call the ‘gencat’ program as follows (assume ‘ex.msg’ contains the
|
sources).
|
|
gencat -H ex.h -o ex.cat ex.msg
|
|
This generates a header file with the following content:
|
|
#define SetTwoSet 0x2 /* ex.msg:8 */
|
|
#define SetOneSet 0x1 /* ex.msg:4 */
|
#define SetOnetwo 0x2 /* ex.msg:6 */
|
|
As can be seen the various symbols given in the source file are
|
mangled to generate unique identifiers and these identifiers get numbers
|
assigned. Reading the source file and knowing about the rules will
|
allow to predict the content of the header file (it is deterministic)
|
but this is not necessary. The ‘gencat’ program can take care for
|
everything. All the programmer has to do is to put the generated header
|
file in the dependency list of the source files of her/his project and
|
add a rule to regenerate the header if any of the input files change.
|
|
One word about the symbol mangling. Every symbol consists of two
|
parts: the name of the message set plus the name of the message or the
|
special string ‘Set’. So ‘SetOnetwo’ means this macro can be used to
|
access the translation with identifier ‘two’ in the message set
|
‘SetOne’.
|
|
The other names denote the names of the message sets. The special
|
string ‘Set’ is used in the place of the message identifier.
|
|
If in the code the second string of the set ‘SetOne’ is used the C
|
code should look like this:
|
|
catgets (catdesc, SetOneSet, SetOnetwo,
|
" Message with ID \"two\", which gets the value 2 assigned")
|
|
Writing the function this way will allow to change the message number
|
and even the set number without requiring any change in the C source
|
code. (The text of the string is normally not the same; this is only
|
for this example.)
|
|
8.1.4.3 How does to this allow to develop
|
.........................................
|
|
To illustrate the usual way to work with the symbolic version numbers
|
here is a little example. Assume we want to write the very complex and
|
famous greeting program. We start by writing the code as usual:
|
|
#include <stdio.h>
|
int
|
main (void)
|
{
|
printf ("Hello, world!\n");
|
return 0;
|
}
|
|
Now we want to internationalize the message and therefore replace the
|
message with whatever the user wants.
|
|
#include <nl_types.h>
|
#include <stdio.h>
|
#include "msgnrs.h"
|
int
|
main (void)
|
{
|
nl_catd catdesc = catopen ("hello.cat", NL_CAT_LOCALE);
|
printf (catgets (catdesc, SetMainSet, SetMainHello,
|
"Hello, world!\n"));
|
catclose (catdesc);
|
return 0;
|
}
|
|
We see how the catalog object is opened and the returned descriptor
|
used in the other function calls. It is not really necessary to check
|
for failure of any of the functions since even in these situations the
|
functions will behave reasonable. They simply will be return a
|
translation.
|
|
What remains unspecified here are the constants ‘SetMainSet’ and
|
‘SetMainHello’. These are the symbolic names describing the message.
|
To get the actual definitions which match the information in the catalog
|
file we have to create the message catalog source file and process it
|
using the ‘gencat’ program.
|
|
$ Messages for the famous greeting program.
|
$quote "
|
|
$set Main
|
Hello "Hallo, Welt!\n"
|
|
Now we can start building the program (assume the message catalog
|
source file is named ‘hello.msg’ and the program source file ‘hello.c’):
|
|
% gencat -H msgnrs.h -o hello.cat hello.msg
|
% cat msgnrs.h
|
#define MainSet 0x1 /* hello.msg:4 */
|
#define MainHello 0x1 /* hello.msg:5 */
|
% gcc -o hello hello.c -I.
|
% cp hello.cat /usr/share/locale/de/LC_MESSAGES
|
% echo $LC_ALL
|
de
|
% ./hello
|
Hallo, Welt!
|
%
|
|
The call of the ‘gencat’ program creates the missing header file
|
‘msgnrs.h’ as well as the message catalog binary. The former is used in
|
the compilation of ‘hello.c’ while the later is placed in a directory in
|
which the ‘catopen’ function will try to locate it. Please check the
|
‘LC_ALL’ environment variable and the default path for ‘catopen’
|
presented in the description above.
|
|
|
File: libc.info, Node: The Uniforum approach, Prev: Message catalogs a la X/Open, Up: Message Translation
|
|
8.2 The Uniforum approach to Message Translation
|
================================================
|
|
Sun Microsystems tried to standardize a different approach to message
|
translation in the Uniforum group. There never was a real standard
|
defined but still the interface was used in Sun’s operating systems.
|
Since this approach fits better in the development process of free
|
software it is also used throughout the GNU project and the GNU
|
‘gettext’ package provides support for this outside the GNU C Library.
|
|
The code of the ‘libintl’ from GNU ‘gettext’ is the same as the code
|
in the GNU C Library. So the documentation in the GNU ‘gettext’ manual
|
is also valid for the functionality here. The following text will
|
describe the library functions in detail. But the numerous helper
|
programs are not described in this manual. Instead people should read
|
the GNU ‘gettext’ manual (*note GNU gettext utilities: (gettext)Top.).
|
We will only give a short overview.
|
|
Though the ‘catgets’ functions are available by default on more
|
systems the ‘gettext’ interface is at least as portable as the former.
|
The GNU ‘gettext’ package can be used wherever the functions are not
|
available.
|
|
* Menu:
|
|
* Message catalogs with gettext:: The ‘gettext’ family of functions.
|
* Helper programs for gettext:: Programs to handle message catalogs
|
for ‘gettext’.
|
|
|
File: libc.info, Node: Message catalogs with gettext, Next: Helper programs for gettext, Up: The Uniforum approach
|
|
8.2.1 The ‘gettext’ family of functions
|
---------------------------------------
|
|
The paradigms underlying the ‘gettext’ approach to message translations
|
is different from that of the ‘catgets’ functions the basic functionally
|
is equivalent. There are functions of the following categories:
|
|
* Menu:
|
|
* Translation with gettext:: What has to be done to translate a message.
|
* Locating gettext catalog:: How to determine which catalog to be used.
|
* Advanced gettext functions:: Additional functions for more complicated
|
situations.
|
* Charset conversion in gettext:: How to specify the output character set
|
‘gettext’ uses.
|
* GUI program problems:: How to use ‘gettext’ in GUI programs.
|
* Using gettextized software:: The possibilities of the user to influence
|
the way ‘gettext’ works.
|
|
|
File: libc.info, Node: Translation with gettext, Next: Locating gettext catalog, Up: Message catalogs with gettext
|
|
8.2.1.1 What has to be done to translate a message?
|
...................................................
|
|
The ‘gettext’ functions have a very simple interface. The most basic
|
function just takes the string which shall be translated as the argument
|
and it returns the translation. This is fundamentally different from
|
the ‘catgets’ approach where an extra key is necessary and the original
|
string is only used for the error case.
|
|
If the string which has to be translated is the only argument this of
|
course means the string itself is the key. I.e., the translation will
|
be selected based on the original string. The message catalogs must
|
therefore contain the original strings plus one translation for any such
|
string. The task of the ‘gettext’ function is to compare the argument
|
string with the available strings in the catalog and return the
|
appropriate translation. Of course this process is optimized so that
|
this process is not more expensive than an access using an atomic key
|
like in ‘catgets’.
|
|
The ‘gettext’ approach has some advantages but also some
|
disadvantages. Please see the GNU ‘gettext’ manual for a detailed
|
discussion of the pros and cons.
|
|
All the definitions and declarations for ‘gettext’ can be found in
|
the ‘libintl.h’ header file. On systems where these functions are not
|
part of the C library they can be found in a separate library named
|
‘libintl.a’ (or accordingly different for shared libraries).
|
|
-- Function: char * gettext (const char *MSGID)
|
|
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘gettext’ function searches the currently selected message
|
catalogs for a string which is equal to MSGID. If there is such a
|
string available it is returned. Otherwise the argument string
|
MSGID is returned.
|
|
Please note that although the return value is ‘char *’ the returned
|
string must not be changed. This broken type results from the
|
history of the function and does not reflect the way the function
|
should be used.
|
|
Please note that above we wrote “message catalogs” (plural). This
|
is a specialty of the GNU implementation of these functions and we
|
will say more about this when we talk about the ways message
|
catalogs are selected (*note Locating gettext catalog::).
|
|
The ‘gettext’ function does not modify the value of the global
|
‘errno’ variable. This is necessary to make it possible to write
|
something like
|
|
printf (gettext ("Operation failed: %m\n"));
|
|
Here the ‘errno’ value is used in the ‘printf’ function while
|
processing the ‘%m’ format element and if the ‘gettext’ function
|
would change this value (it is called before ‘printf’ is called) we
|
would get a wrong message.
|
|
So there is no easy way to detect a missing message catalog besides
|
comparing the argument string with the result. But it is normally
|
the task of the user to react on missing catalogs. The program
|
cannot guess when a message catalog is really necessary since for a
|
user who speaks the language the program was developed in, the
|
message does not need any translation.
|
|
The remaining two functions to access the message catalog add some
|
functionality to select a message catalog which is not the default one.
|
This is important if parts of the program are developed independently.
|
Every part can have its own message catalog and all of them can be used
|
at the same time. The C library itself is an example: internally it
|
uses the ‘gettext’ functions but since it must not depend on a currently
|
selected default message catalog it must specify all ambiguous
|
information.
|
|
-- Function: char * dgettext (const char *DOMAINNAME, const char
|
*MSGID)
|
|
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘dgettext’ function acts just like the ‘gettext’ function. It
|
only takes an additional first argument DOMAINNAME which guides the
|
selection of the message catalogs which are searched for the
|
translation. If the DOMAINNAME parameter is the null pointer the
|
‘dgettext’ function is exactly equivalent to ‘gettext’ since the
|
default value for the domain name is used.
|
|
As for ‘gettext’ the return value type is ‘char *’ which is an
|
anachronism. The returned string must never be modified.
|
|
-- Function: char * dcgettext (const char *DOMAINNAME, const char
|
*MSGID, int CATEGORY)
|
|
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘dcgettext’ adds another argument to those which ‘dgettext’
|
takes. This argument CATEGORY specifies the last piece of
|
information needed to localize the message catalog. I.e., the
|
domain name and the locale category exactly specify which message
|
catalog has to be used (relative to a given directory, see below).
|
|
The ‘dgettext’ function can be expressed in terms of ‘dcgettext’ by
|
using
|
|
dcgettext (domain, string, LC_MESSAGES)
|
|
instead of
|
|
dgettext (domain, string)
|
|
This also shows which values are expected for the third parameter.
|
One has to use the available selectors for the categories available
|
in ‘locale.h’. Normally the available values are ‘LC_CTYPE’,
|
‘LC_COLLATE’, ‘LC_MESSAGES’, ‘LC_MONETARY’, ‘LC_NUMERIC’, and
|
‘LC_TIME’. Please note that ‘LC_ALL’ must not be used and even
|
though the names might suggest this, there is no relation to the
|
environment variable of this name.
|
|
The ‘dcgettext’ function is only implemented for compatibility with
|
other systems which have ‘gettext’ functions. There is not really
|
any situation where it is necessary (or useful) to use a different
|
value than ‘LC_MESSAGES’ for the CATEGORY parameter. We are
|
dealing with messages here and any other choice can only be
|
irritating.
|
|
As for ‘gettext’ the return value type is ‘char *’ which is an
|
anachronism. The returned string must never be modified.
|
|
When using the three functions above in a program it is a frequent
|
case that the MSGID argument is a constant string. So it is worthwhile
|
to optimize this case. Thinking shortly about this one will realize
|
that as long as no new message catalog is loaded the translation of a
|
message will not change. This optimization is actually implemented by
|
the ‘gettext’, ‘dgettext’ and ‘dcgettext’ functions.
|
|
|
File: libc.info, Node: Locating gettext catalog, Next: Advanced gettext functions, Prev: Translation with gettext, Up: Message catalogs with gettext
|
|
8.2.1.2 How to determine which catalog to be used
|
.................................................
|
|
The functions to retrieve the translations for a given message have a
|
remarkable simple interface. But to provide the user of the program
|
still the opportunity to select exactly the translation s/he wants and
|
also to provide the programmer the possibility to influence the way to
|
locate the search for catalogs files there is a quite complicated
|
underlying mechanism which controls all this. The code is complicated
|
the use is easy.
|
|
Basically we have two different tasks to perform which can also be
|
performed by the ‘catgets’ functions:
|
|
1. Locate the set of message catalogs. There are a number of files
|
for different languages which all belong to the package. Usually
|
they are all stored in the filesystem below a certain directory.
|
|
There can be arbitrarily many packages installed and they can
|
follow different guidelines for the placement of their files.
|
|
2. Relative to the location specified by the package the actual
|
translation files must be searched, based on the wishes of the
|
user. I.e., for each language the user selects the program should
|
be able to locate the appropriate file.
|
|
This is the functionality required by the specifications for
|
‘gettext’ and this is also what the ‘catgets’ functions are able to do.
|
But there are some problems unresolved:
|
|
• The language to be used can be specified in several different ways.
|
There is no generally accepted standard for this and the user
|
always expects the program to understand what s/he means. E.g., to
|
select the German translation one could write ‘de’, ‘german’, or
|
‘deutsch’ and the program should always react the same.
|
|
• Sometimes the specification of the user is too detailed. If s/he,
|
e.g., specifies ‘de_DE.ISO-8859-1’ which means German, spoken in
|
Germany, coded using the ISO 8859-1 character set there is the
|
possibility that a message catalog matching this exactly is not
|
available. But there could be a catalog matching ‘de’ and if the
|
character set used on the machine is always ISO 8859-1 there is no
|
reason why this later message catalog should not be used. (We call
|
this "message inheritance".)
|
|
• If a catalog for a wanted language is not available it is not
|
always the second best choice to fall back on the language of the
|
developer and simply not translate any message. Instead a user
|
might be better able to read the messages in another language and
|
so the user of the program should be able to define a precedence
|
order of languages.
|
|
We can divide the configuration actions in two parts: the one is
|
performed by the programmer, the other by the user. We will start with
|
the functions the programmer can use since the user configuration will
|
be based on this.
|
|
As the functions described in the last sections already mention
|
separate sets of messages can be selected by a "domain name". This is a
|
simple string which should be unique for each program part that uses a
|
separate domain. It is possible to use in one program arbitrarily many
|
domains at the same time. E.g., the GNU C Library itself uses a domain
|
named ‘libc’ while the program using the C Library could use a domain
|
named ‘foo’. The important point is that at any time exactly one domain
|
is active. This is controlled with the following function.
|
|
-- Function: char * textdomain (const char *DOMAINNAME)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
The ‘textdomain’ function sets the default domain, which is used in
|
all future ‘gettext’ calls, to DOMAINNAME. Please note that
|
‘dgettext’ and ‘dcgettext’ calls are not influenced if the
|
DOMAINNAME parameter of these functions is not the null pointer.
|
|
Before the first call to ‘textdomain’ the default domain is
|
‘messages’. This is the name specified in the specification of the
|
‘gettext’ API. This name is as good as any other name. No program
|
should ever really use a domain with this name since this can only
|
lead to problems.
|
|
The function returns the value which is from now on taken as the
|
default domain. If the system went out of memory the returned
|
value is ‘NULL’ and the global variable ‘errno’ is set to ‘ENOMEM’.
|
Despite the return value type being ‘char *’ the return string must
|
not be changed. It is allocated internally by the ‘textdomain’
|
function.
|
|
If the DOMAINNAME parameter is the null pointer no new default
|
domain is set. Instead the currently selected default domain is
|
returned.
|
|
If the DOMAINNAME parameter is the empty string the default domain
|
is reset to its initial value, the domain with the name ‘messages’.
|
This possibility is questionable to use since the domain ‘messages’
|
really never should be used.
|
|
-- Function: char * bindtextdomain (const char *DOMAINNAME, const char
|
*DIRNAME)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
The ‘bindtextdomain’ function can be used to specify the directory
|
which contains the message catalogs for domain DOMAINNAME for the
|
different languages. To be correct, this is the directory where
|
the hierarchy of directories is expected. Details are explained
|
below.
|
|
For the programmer it is important to note that the translations
|
which come with the program have to be placed in a directory
|
hierarchy starting at, say, ‘/foo/bar’. Then the program should
|
make a ‘bindtextdomain’ call to bind the domain for the current
|
program to this directory. So it is made sure the catalogs are
|
found. A correctly running program does not depend on the user
|
setting an environment variable.
|
|
The ‘bindtextdomain’ function can be used several times and if the
|
DOMAINNAME argument is different the previously bound domains will
|
not be overwritten.
|
|
If the program which wish to use ‘bindtextdomain’ at some point of
|
time use the ‘chdir’ function to change the current working
|
directory it is important that the DIRNAME strings ought to be an
|
absolute pathname. Otherwise the addressed directory might vary
|
with the time.
|
|
If the DIRNAME parameter is the null pointer ‘bindtextdomain’
|
returns the currently selected directory for the domain with the
|
name DOMAINNAME.
|
|
The ‘bindtextdomain’ function returns a pointer to a string
|
containing the name of the selected directory name. The string is
|
allocated internally in the function and must not be changed by the
|
user. If the system went out of core during the execution of
|
‘bindtextdomain’ the return value is ‘NULL’ and the global variable
|
‘errno’ is set accordingly.
|
|
|
File: libc.info, Node: Advanced gettext functions, Next: Charset conversion in gettext, Prev: Locating gettext catalog, Up: Message catalogs with gettext
|
|
8.2.1.3 Additional functions for more complicated situations
|
............................................................
|
|
The functions of the ‘gettext’ family described so far (and all the
|
‘catgets’ functions as well) have one problem in the real world which
|
has been neglected completely in all existing approaches. What is meant
|
here is the handling of plural forms.
|
|
Looking through Unix source code before the time anybody thought
|
about internationalization (and, sadly, even afterwards) one can often
|
find code similar to the following:
|
|
printf ("%d file%s deleted", n, n == 1 ? "" : "s");
|
|
After the first complaints from people internationalizing the code
|
people either completely avoided formulations like this or used strings
|
like ‘"file(s)"’. Both look unnatural and should be avoided. First
|
tries to solve the problem correctly looked like this:
|
|
if (n == 1)
|
printf ("%d file deleted", n);
|
else
|
printf ("%d files deleted", n);
|
|
But this does not solve the problem. It helps languages where the
|
plural form of a noun is not simply constructed by adding an ‘s’ but
|
that is all. Once again people fell into the trap of believing the
|
rules their language uses are universal. But the handling of plural
|
forms differs widely between the language families. There are two
|
things we can differ between (and even inside language families);
|
|
• The form how plural forms are build differs. This is a problem
|
with language which have many irregularities. German, for
|
instance, is a drastic case. Though English and German are part of
|
the same language family (Germanic), the almost regular forming of
|
plural noun forms (appending an ‘s’) is hardly found in German.
|
|
• The number of plural forms differ. This is somewhat surprising for
|
those who only have experiences with Romanic and Germanic languages
|
since here the number is the same (there are two).
|
|
But other language families have only one form or many forms. More
|
information on this in an extra section.
|
|
The consequence of this is that application writers should not try to
|
solve the problem in their code. This would be localization since it is
|
only usable for certain, hardcoded language environments. Instead the
|
extended ‘gettext’ interface should be used.
|
|
These extra functions are taking instead of the one key string two
|
strings and a numerical argument. The idea behind this is that using
|
the numerical argument and the first string as a key, the implementation
|
can select using rules specified by the translator the right plural
|
form. The two string arguments then will be used to provide a return
|
value in case no message catalog is found (similar to the normal
|
‘gettext’ behavior). In this case the rules for Germanic language are
|
used and it is assumed that the first string argument is the singular
|
form, the second the plural form.
|
|
This has the consequence that programs without language catalogs can
|
display the correct strings only if the program itself is written using
|
a Germanic language. This is a limitation but since the GNU C Library
|
(as well as the GNU ‘gettext’ package) is written as part of the GNU
|
package and the coding standards for the GNU project require programs to
|
be written in English, this solution nevertheless fulfills its purpose.
|
|
-- Function: char * ngettext (const char *MSGID1, const char *MSGID2,
|
unsigned long int N)
|
|
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘ngettext’ function is similar to the ‘gettext’ function as it
|
finds the message catalogs in the same way. But it takes two extra
|
arguments. The MSGID1 parameter must contain the singular form of
|
the string to be converted. It is also used as the key for the
|
search in the catalog. The MSGID2 parameter is the plural form.
|
The parameter N is used to determine the plural form. If no
|
message catalog is found MSGID1 is returned if ‘n == 1’, otherwise
|
‘msgid2’.
|
|
An example for the use of this function is:
|
|
printf (ngettext ("%d file removed", "%d files removed", n), n);
|
|
Please note that the numeric value N has to be passed to the
|
‘printf’ function as well. It is not sufficient to pass it only to
|
‘ngettext’.
|
|
-- Function: char * dngettext (const char *DOMAIN, const char *MSGID1,
|
const char *MSGID2, unsigned long int N)
|
|
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘dngettext’ is similar to the ‘dgettext’ function in the way
|
the message catalog is selected. The difference is that it takes
|
two extra parameters to provide the correct plural form. These two
|
parameters are handled in the same way ‘ngettext’ handles them.
|
|
-- Function: char * dcngettext (const char *DOMAIN, const char *MSGID1,
|
const char *MSGID2, unsigned long int N, int CATEGORY)
|
|
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘dcngettext’ is similar to the ‘dcgettext’ function in the way
|
the message catalog is selected. The difference is that it takes
|
two extra parameters to provide the correct plural form. These two
|
parameters are handled in the same way ‘ngettext’ handles them.
|
|
The problem of plural forms
|
...........................
|
|
A description of the problem can be found at the beginning of the last
|
section. Now there is the question how to solve it. Without the input
|
of linguists (which was not available) it was not possible to determine
|
whether there are only a few different forms in which plural forms are
|
formed or whether the number can increase with every new supported
|
language.
|
|
Therefore the solution implemented is to allow the translator to
|
specify the rules of how to select the plural form. Since the formula
|
varies with every language this is the only viable solution except for
|
hardcoding the information in the code (which still would require the
|
possibility of extensions to not prevent the use of new languages). The
|
details are explained in the GNU ‘gettext’ manual. Here only a bit of
|
information is provided.
|
|
The information about the plural form selection has to be stored in
|
the header entry (the one with the empty ‘msgid’ string). It looks like
|
this:
|
|
Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
|
|
The ‘nplurals’ value must be a decimal number which specifies how
|
many different plural forms exist for this language. The string
|
following ‘plural’ is an expression using the C language syntax.
|
Exceptions are that no negative numbers are allowed, numbers must be
|
decimal, and the only variable allowed is ‘n’. This expression will be
|
evaluated whenever one of the functions ‘ngettext’, ‘dngettext’, or
|
‘dcngettext’ is called. The numeric value passed to these functions is
|
then substituted for all uses of the variable ‘n’ in the expression.
|
The resulting value then must be greater or equal to zero and smaller
|
than the value given as the value of ‘nplurals’.
|
|
The following rules are known at this point. The language with families
|
are listed. But this does not necessarily mean the information can be
|
generalized for the whole family (as can be easily seen in the table
|
below).(1)
|
|
Only one form:
|
Some languages only require one single form. There is no
|
distinction between the singular and plural form. An appropriate
|
header entry would look like this:
|
|
Plural-Forms: nplurals=1; plural=0;
|
|
Languages with this property include:
|
|
Finno-Ugric family
|
Hungarian
|
Asian family
|
Japanese, Korean
|
Turkic/Altaic family
|
Turkish
|
|
Two forms, singular used for one only
|
This is the form used in most existing programs since it is what
|
English uses. A header entry would look like this:
|
|
Plural-Forms: nplurals=2; plural=n != 1;
|
|
(Note: this uses the feature of C expressions that boolean
|
expressions have to value zero or one.)
|
|
Languages with this property include:
|
|
Germanic family
|
Danish, Dutch, English, German, Norwegian, Swedish
|
Finno-Ugric family
|
Estonian, Finnish
|
Latin/Greek family
|
Greek
|
Semitic family
|
Hebrew
|
Romance family
|
Italian, Portuguese, Spanish
|
Artificial
|
Esperanto
|
|
Two forms, singular used for zero and one
|
Exceptional case in the language family. The header entry would
|
be:
|
|
Plural-Forms: nplurals=2; plural=n>1;
|
|
Languages with this property include:
|
|
Romanic family
|
French, Brazilian Portuguese
|
|
Three forms, special case for zero
|
The header entry would be:
|
|
Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
|
|
Languages with this property include:
|
|
Baltic family
|
Latvian
|
|
Three forms, special cases for one and two
|
The header entry would be:
|
|
Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
|
|
Languages with this property include:
|
|
Celtic
|
Gaeilge (Irish)
|
|
Three forms, special case for numbers ending in 1[2-9]
|
The header entry would look like this:
|
|
Plural-Forms: nplurals=3; \
|
plural=n%10==1 && n%100!=11 ? 0 : \
|
n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
|
|
Languages with this property include:
|
|
Baltic family
|
Lithuanian
|
|
Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
|
The header entry would look like this:
|
|
Plural-Forms: nplurals=3; \
|
plural=n%100/10==1 ? 2 : n%10==1 ? 0 : (n+9)%10>3 ? 2 : 1;
|
|
Languages with this property include:
|
|
Slavic family
|
Croatian, Czech, Russian, Ukrainian
|
|
Three forms, special cases for 1 and 2, 3, 4
|
The header entry would look like this:
|
|
Plural-Forms: nplurals=3; \
|
plural=(n==1) ? 1 : (n>=2 && n<=4) ? 2 : 0;
|
|
Languages with this property include:
|
|
Slavic family
|
Slovak
|
|
Three forms, special case for one and some numbers ending in 2, 3, or 4
|
The header entry would look like this:
|
|
Plural-Forms: nplurals=3; \
|
plural=n==1 ? 0 : \
|
n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
|
|
Languages with this property include:
|
|
Slavic family
|
Polish
|
|
Four forms, special case for one and all numbers ending in 02, 03, or 04
|
The header entry would look like this:
|
|
Plural-Forms: nplurals=4; \
|
plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
|
|
Languages with this property include:
|
|
Slavic family
|
Slovenian
|
|
---------- Footnotes ----------
|
|
(1) Additions are welcome. Send appropriate information to
|
<bug-glibc-manual@gnu.org>.
|
|
|
File: libc.info, Node: Charset conversion in gettext, Next: GUI program problems, Prev: Advanced gettext functions, Up: Message catalogs with gettext
|
|
8.2.1.4 How to specify the output character set ‘gettext’ uses
|
..............................................................
|
|
‘gettext’ not only looks up a translation in a message catalog, it also
|
converts the translation on the fly to the desired output character set.
|
This is useful if the user is working in a different character set than
|
the translator who created the message catalog, because it avoids
|
distributing variants of message catalogs which differ only in the
|
character set.
|
|
The output character set is, by default, the value of ‘nl_langinfo
|
(CODESET)’, which depends on the ‘LC_CTYPE’ part of the current locale.
|
But programs which store strings in a locale independent way (e.g.
|
UTF-8) can request that ‘gettext’ and related functions return the
|
translations in that encoding, by use of the ‘bind_textdomain_codeset’
|
function.
|
|
Note that the MSGID argument to ‘gettext’ is not subject to character
|
set conversion. Also, when ‘gettext’ does not find a translation for
|
MSGID, it returns MSGID unchanged – independently of the current output
|
character set. It is therefore recommended that all MSGIDs be US-ASCII
|
strings.
|
|
-- Function: char * bind_textdomain_codeset (const char *DOMAINNAME,
|
const char *CODESET)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
The ‘bind_textdomain_codeset’ function can be used to specify the
|
output character set for message catalogs for domain DOMAINNAME.
|
The CODESET argument must be a valid codeset name which can be used
|
for the ‘iconv_open’ function, or a null pointer.
|
|
If the CODESET parameter is the null pointer,
|
‘bind_textdomain_codeset’ returns the currently selected codeset
|
for the domain with the name DOMAINNAME. It returns ‘NULL’ if no
|
codeset has yet been selected.
|
|
The ‘bind_textdomain_codeset’ function can be used several times.
|
If used multiple times with the same DOMAINNAME argument, the later
|
call overrides the settings made by the earlier one.
|
|
The ‘bind_textdomain_codeset’ function returns a pointer to a
|
string containing the name of the selected codeset. The string is
|
allocated internally in the function and must not be changed by the
|
user. If the system went out of core during the execution of
|
‘bind_textdomain_codeset’, the return value is ‘NULL’ and the
|
global variable ‘errno’ is set accordingly.
|
|
|
File: libc.info, Node: GUI program problems, Next: Using gettextized software, Prev: Charset conversion in gettext, Up: Message catalogs with gettext
|
|
8.2.1.5 How to use ‘gettext’ in GUI programs
|
............................................
|
|
One place where the ‘gettext’ functions, if used normally, have big
|
problems is within programs with graphical user interfaces (GUIs). The
|
problem is that many of the strings which have to be translated are very
|
short. They have to appear in pull-down menus which restricts the
|
length. But strings which are not containing entire sentences or at
|
least large fragments of a sentence may appear in more than one
|
situation in the program but might have different translations. This is
|
especially true for the one-word strings which are frequently used in
|
GUI programs.
|
|
As a consequence many people say that the ‘gettext’ approach is wrong
|
and instead ‘catgets’ should be used which indeed does not have this
|
problem. But there is a very simple and powerful method to handle these
|
kind of problems with the ‘gettext’ functions.
|
|
As an example consider the following fictional situation. A GUI program
|
has a menu bar with the following entries:
|
|
+------------+------------+--------------------------------------+
|
| File | Printer | |
|
+------------+------------+--------------------------------------+
|
| Open | | Select |
|
| New | | Open |
|
+----------+ | Connect |
|
+----------+
|
|
To have the strings ‘File’, ‘Printer’, ‘Open’, ‘New’, ‘Select’, and
|
‘Connect’ translated there has to be at some point in the code a call to
|
a function of the ‘gettext’ family. But in two places the string passed
|
into the function would be ‘Open’. The translations might not be the
|
same and therefore we are in the dilemma described above.
|
|
One solution to this problem is to artificially extend the strings to
|
make them unambiguous. But what would the program do if no translation
|
is available? The extended string is not what should be printed. So we
|
should use a slightly modified version of the functions.
|
|
To extend the strings a uniform method should be used. E.g., in the
|
example above, the strings could be chosen as
|
|
Menu|File
|
Menu|Printer
|
Menu|File|Open
|
Menu|File|New
|
Menu|Printer|Select
|
Menu|Printer|Open
|
Menu|Printer|Connect
|
|
Now all the strings are different and if now instead of ‘gettext’ the
|
following little wrapper function is used, everything works just fine:
|
|
char *
|
sgettext (const char *msgid)
|
{
|
char *msgval = gettext (msgid);
|
if (msgval == msgid)
|
msgval = strrchr (msgid, '|') + 1;
|
return msgval;
|
}
|
|
What this little function does is to recognize the case when no
|
translation is available. This can be done very efficiently by a
|
pointer comparison since the return value is the input value. If there
|
is no translation we know that the input string is in the format we used
|
for the Menu entries and therefore contains a ‘|’ character. We simply
|
search for the last occurrence of this character and return a pointer to
|
the character following it. That’s it!
|
|
If one now consistently uses the extended string form and replaces
|
the ‘gettext’ calls with calls to ‘sgettext’ (this is normally limited
|
to very few places in the GUI implementation) then it is possible to
|
produce a program which can be internationalized.
|
|
With advanced compilers (such as GNU C) one can write the ‘sgettext’
|
functions as an inline function or as a macro like this:
|
|
#define sgettext(msgid) \
|
({ const char *__msgid = (msgid); \
|
char *__msgstr = gettext (__msgid); \
|
if (__msgval == __msgid) \
|
__msgval = strrchr (__msgid, '|') + 1; \
|
__msgval; })
|
|
The other ‘gettext’ functions (‘dgettext’, ‘dcgettext’ and the
|
‘ngettext’ equivalents) can and should have corresponding functions as
|
well which look almost identical, except for the parameters and the call
|
to the underlying function.
|
|
Now there is of course the question why such functions do not exist
|
in the GNU C Library? There are two parts of the answer to this
|
question.
|
|
• They are easy to write and therefore can be provided by the project
|
they are used in. This is not an answer by itself and must be seen
|
together with the second part which is:
|
|
• There is no way the C library can contain a version which can work
|
everywhere. The problem is the selection of the character to
|
separate the prefix from the actual string in the extended string.
|
The examples above used ‘|’ which is a quite good choice because it
|
resembles a notation frequently used in this context and it also is
|
a character not often used in message strings.
|
|
But what if the character is used in message strings. Or if the
|
chose character is not available in the character set on the
|
machine one compiles (e.g., ‘|’ is not required to exist for ISO C;
|
this is why the ‘iso646.h’ file exists in ISO C programming
|
environments).
|
|
There is only one more comment to make left. The wrapper function
|
above requires that the translations strings are not extended
|
themselves. This is only logical. There is no need to disambiguate the
|
strings (since they are never used as keys for a search) and one also
|
saves quite some memory and disk space by doing this.
|
|
|
File: libc.info, Node: Using gettextized software, Prev: GUI program problems, Up: Message catalogs with gettext
|
|
8.2.1.6 User influence on ‘gettext’
|
...................................
|
|
The last sections described what the programmer can do to
|
internationalize the messages of the program. But it is finally up to
|
the user to select the message s/he wants to see. S/He must understand
|
them.
|
|
The POSIX locale model uses the environment variables ‘LC_COLLATE’,
|
‘LC_CTYPE’, ‘LC_MESSAGES’, ‘LC_MONETARY’, ‘LC_NUMERIC’, and ‘LC_TIME’ to
|
select the locale which is to be used. This way the user can influence
|
lots of functions. As we mentioned above, the ‘gettext’ functions also
|
take advantage of this.
|
|
To understand how this happens it is necessary to take a look at the
|
various components of the filename which gets computed to locate a
|
message catalog. It is composed as follows:
|
|
DIR_NAME/LOCALE/LC_CATEGORY/DOMAIN_NAME.mo
|
|
The default value for DIR_NAME is system specific. It is computed
|
from the value given as the prefix while configuring the C library.
|
This value normally is ‘/usr’ or ‘/’. For the former the complete
|
DIR_NAME is:
|
|
/usr/share/locale
|
|
We can use ‘/usr/share’ since the ‘.mo’ files containing the message
|
catalogs are system independent, so all systems can use the same files.
|
If the program executed the ‘bindtextdomain’ function for the message
|
domain that is currently handled, the ‘dir_name’ component is exactly
|
the value which was given to the function as the second parameter.
|
I.e., ‘bindtextdomain’ allows overwriting the only system dependent and
|
fixed value to make it possible to address files anywhere in the
|
filesystem.
|
|
The CATEGORY is the name of the locale category which was selected in
|
the program code. For ‘gettext’ and ‘dgettext’ this is always
|
‘LC_MESSAGES’, for ‘dcgettext’ this is selected by the value of the
|
third parameter. As said above it should be avoided to ever use a
|
category other than ‘LC_MESSAGES’.
|
|
The LOCALE component is computed based on the category used. Just
|
like for the ‘setlocale’ function here comes the user selection into the
|
play. Some environment variables are examined in a fixed order and the
|
first environment variable set determines the return value of the lookup
|
process. In detail, for the category ‘LC_xxx’ the following variables
|
in this order are examined:
|
|
‘LANGUAGE’
|
‘LC_ALL’
|
‘LC_xxx’
|
‘LANG’
|
|
This looks very familiar. With the exception of the ‘LANGUAGE’
|
environment variable this is exactly the lookup order the ‘setlocale’
|
function uses. But why introduce the ‘LANGUAGE’ variable?
|
|
The reason is that the syntax of the values these variables can have
|
is different to what is expected by the ‘setlocale’ function. If we
|
would set ‘LC_ALL’ to a value following the extended syntax that would
|
mean the ‘setlocale’ function will never be able to use the value of
|
this variable as well. An additional variable removes this problem plus
|
we can select the language independently of the locale setting which
|
sometimes is useful.
|
|
While for the ‘LC_xxx’ variables the value should consist of exactly
|
one specification of a locale the ‘LANGUAGE’ variable’s value can
|
consist of a colon separated list of locale names. The attentive reader
|
will realize that this is the way we manage to implement one of our
|
additional demands above: we want to be able to specify an ordered list
|
of languages.
|
|
Back to the constructed filename we have only one component missing.
|
The DOMAIN_NAME part is the name which was either registered using the
|
‘textdomain’ function or which was given to ‘dgettext’ or ‘dcgettext’ as
|
the first parameter. Now it becomes obvious that a good choice for the
|
domain name in the program code is a string which is closely related to
|
the program/package name. E.g., for the GNU C Library the domain name
|
is ‘libc’.
|
|
A limited piece of example code should show how the program is supposed
|
to work:
|
|
{
|
setlocale (LC_ALL, "");
|
textdomain ("test-package");
|
bindtextdomain ("test-package", "/usr/local/share/locale");
|
puts (gettext ("Hello, world!"));
|
}
|
|
At the program start the default domain is ‘messages’, and the
|
default locale is "C". The ‘setlocale’ call sets the locale according to
|
the user’s environment variables; remember that correct functioning of
|
‘gettext’ relies on the correct setting of the ‘LC_MESSAGES’ locale (for
|
looking up the message catalog) and of the ‘LC_CTYPE’ locale (for the
|
character set conversion). The ‘textdomain’ call changes the default
|
domain to ‘test-package’. The ‘bindtextdomain’ call specifies that the
|
message catalogs for the domain ‘test-package’ can be found below the
|
directory ‘/usr/local/share/locale’.
|
|
If the user sets in her/his environment the variable ‘LANGUAGE’ to
|
‘de’ the ‘gettext’ function will try to use the translations from the
|
file
|
|
/usr/local/share/locale/de/LC_MESSAGES/test-package.mo
|
|
From the above descriptions it should be clear which component of
|
this filename is determined by which source.
|
|
In the above example we assumed the ‘LANGUAGE’ environment variable
|
to be ‘de’. This might be an appropriate selection but what happens if
|
the user wants to use ‘LC_ALL’ because of the wider usability and here
|
the required value is ‘de_DE.ISO-8859-1’? We already mentioned above
|
that a situation like this is not infrequent. E.g., a person might
|
prefer reading a dialect and if this is not available fall back on the
|
standard language.
|
|
The ‘gettext’ functions know about situations like this and can
|
handle them gracefully. The functions recognize the format of the value
|
of the environment variable. It can split the value is different pieces
|
and by leaving out the only or the other part it can construct new
|
values. This happens of course in a predictable way. To understand
|
this one must know the format of the environment variable value. There
|
is one more or less standardized form, originally from the X/Open
|
specification:
|
|
‘language[_territory[.codeset]][@modifier]’
|
|
Less specific locale names will be stripped in the order of the
|
following list:
|
|
1. ‘codeset’
|
2. ‘normalized codeset’
|
3. ‘territory’
|
4. ‘modifier’
|
|
The ‘language’ field will never be dropped for obvious reasons.
|
|
The only new thing is the ‘normalized codeset’ entry. This is
|
another goodie which is introduced to help reduce the chaos which
|
derives from the inability of people to standardize the names of
|
character sets. Instead of ISO-8859-1 one can often see 8859-1, 88591,
|
iso8859-1, or iso_8859-1. The ‘normalized codeset’ value is generated
|
from the user-provided character set name by applying the following
|
rules:
|
|
1. Remove all characters besides numbers and letters.
|
2. Fold letters to lowercase.
|
3. If the same only contains digits prepend the string ‘"iso"’.
|
|
So all of the above names will be normalized to ‘iso88591’. This allows
|
the program user much more freedom in choosing the locale name.
|
|
Even this extended functionality still does not help to solve the
|
problem that completely different names can be used to denote the same
|
locale (e.g., ‘de’ and ‘german’). To be of help in this situation the
|
locale implementation and also the ‘gettext’ functions know about
|
aliases.
|
|
The file ‘/usr/share/locale/locale.alias’ (replace ‘/usr’ with
|
whatever prefix you used for configuring the C library) contains a
|
mapping of alternative names to more regular names. The system manager
|
is free to add new entries to fill her/his own needs. The selected
|
locale from the environment is compared with the entries in the first
|
column of this file ignoring the case. If they match, the value of the
|
second column is used instead for the further handling.
|
|
In the description of the format of the environment variables we
|
already mentioned the character set as a factor in the selection of the
|
message catalog. In fact, only catalogs which contain text written
|
using the character set of the system/program can be used (directly;
|
there will come a solution for this some day). This means for the user
|
that s/he will always have to take care of this. If in the collection
|
of the message catalogs there are files for the same language but coded
|
using different character sets the user has to be careful.
|
|
|
File: libc.info, Node: Helper programs for gettext, Prev: Message catalogs with gettext, Up: The Uniforum approach
|
|
8.2.2 Programs to handle message catalogs for ‘gettext’
|
-------------------------------------------------------
|
|
The GNU C Library does not contain the source code for the programs to
|
handle message catalogs for the ‘gettext’ functions. As part of the GNU
|
project the GNU gettext package contains everything the developer needs.
|
The functionality provided by the tools in this package by far exceeds
|
the abilities of the ‘gencat’ program described above for the ‘catgets’
|
functions.
|
|
There is a program ‘msgfmt’ which is the equivalent program to the
|
‘gencat’ program. It generates from the human-readable and -editable
|
form of the message catalog a binary file which can be used by the
|
‘gettext’ functions. But there are several more programs available.
|
|
The ‘xgettext’ program can be used to automatically extract the
|
translatable messages from a source file. I.e., the programmer need not
|
take care of the translations and the list of messages which have to be
|
translated. S/He will simply wrap the translatable string in calls to
|
‘gettext’ et.al and the rest will be done by ‘xgettext’. This program
|
has a lot of options which help to customize the output or help to
|
understand the input better.
|
|
Other programs help to manage the development cycle when new messages
|
appear in the source files or when a new translation of the messages
|
appears. Here it should only be noted that using all the tools in GNU
|
gettext it is possible to _completely_ automate the handling of message
|
catalogs. Besides marking the translatable strings in the source code
|
and generating the translations the developers do not have anything to
|
do themselves.
|
|
|
File: libc.info, Node: Searching and Sorting, Next: Pattern Matching, Prev: Message Translation, Up: Top
|
|
9 Searching and Sorting
|
***********************
|
|
This chapter describes functions for searching and sorting arrays of
|
arbitrary objects. You pass the appropriate comparison function to be
|
applied as an argument, along with the size of the objects in the array
|
and the total number of elements.
|
|
* Menu:
|
|
* Comparison Functions:: Defining how to compare two objects.
|
Since the sort and search facilities
|
are general, you have to specify the
|
ordering.
|
* Array Search Function:: The ‘bsearch’ function.
|
* Array Sort Function:: The ‘qsort’ function.
|
* Search/Sort Example:: An example program.
|
* Hash Search Function:: The ‘hsearch’ function.
|
* Tree Search Function:: The ‘tsearch’ function.
|
|
|
File: libc.info, Node: Comparison Functions, Next: Array Search Function, Up: Searching and Sorting
|
|
9.1 Defining the Comparison Function
|
====================================
|
|
In order to use the sorted array library functions, you have to describe
|
how to compare the elements of the array.
|
|
To do this, you supply a comparison function to compare two elements
|
of the array. The library will call this function, passing as arguments
|
pointers to two array elements to be compared. Your comparison function
|
should return a value the way ‘strcmp’ (*note String/Array Comparison::)
|
does: negative if the first argument is “less” than the second, zero if
|
they are “equal”, and positive if the first argument is “greater”.
|
|
Here is an example of a comparison function which works with an array
|
of numbers of type ‘double’:
|
|
int
|
compare_doubles (const void *a, const void *b)
|
{
|
const double *da = (const double *) a;
|
const double *db = (const double *) b;
|
|
return (*da > *db) - (*da < *db);
|
}
|
|
The header file ‘stdlib.h’ defines a name for the data type of
|
comparison functions. This type is a GNU extension.
|
|
int comparison_fn_t (const void *, const void *);
|
|
|
File: libc.info, Node: Array Search Function, Next: Array Sort Function, Prev: Comparison Functions, Up: Searching and Sorting
|
|
9.2 Array Search Function
|
=========================
|
|
Generally searching for a specific element in an array means that
|
potentially all elements must be checked. The GNU C Library contains
|
functions to perform linear search. The prototypes for the following
|
two functions can be found in ‘search.h’.
|
|
-- Function: void * lfind (const void *KEY, const void *BASE, size_t
|
*NMEMB, size_t SIZE, comparison_fn_t COMPAR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘lfind’ function searches in the array with ‘*NMEMB’ elements
|
of SIZE bytes pointed to by BASE for an element which matches the
|
one pointed to by KEY. The function pointed to by COMPAR is used
|
to decide whether two elements match.
|
|
The return value is a pointer to the matching element in the array
|
starting at BASE if it is found. If no matching element is
|
available ‘NULL’ is returned.
|
|
The mean runtime of this function is ‘*NMEMB’/2. This function
|
should only be used if elements often get added to or deleted from
|
the array in which case it might not be useful to sort the array
|
before searching.
|
|
-- Function: void * lsearch (const void *KEY, void *BASE, size_t
|
*NMEMB, size_t SIZE, comparison_fn_t COMPAR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘lsearch’ function is similar to the ‘lfind’ function. It
|
searches the given array for an element and returns it if found.
|
The difference is that if no matching element is found the
|
‘lsearch’ function adds the object pointed to by KEY (with a size
|
of SIZE bytes) at the end of the array and it increments the value
|
of ‘*NMEMB’ to reflect this addition.
|
|
This means for the caller that if it is not sure that the array
|
contains the element one is searching for the memory allocated for
|
the array starting at BASE must have room for at least SIZE more
|
bytes. If one is sure the element is in the array it is better to
|
use ‘lfind’ so having more room in the array is always necessary
|
when calling ‘lsearch’.
|
|
To search a sorted array for an element matching the key, use the
|
‘bsearch’ function. The prototype for this function is in the header
|
file ‘stdlib.h’.
|
|
-- Function: void * bsearch (const void *KEY, const void *ARRAY, size_t
|
COUNT, size_t SIZE, comparison_fn_t COMPARE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘bsearch’ function searches the sorted array ARRAY for an
|
object that is equivalent to KEY. The array contains COUNT
|
elements, each of which is of size SIZE bytes.
|
|
The COMPARE function is used to perform the comparison. This
|
function is called with two pointer arguments and should return an
|
integer less than, equal to, or greater than zero corresponding to
|
whether its first argument is considered less than, equal to, or
|
greater than its second argument. The elements of the ARRAY must
|
already be sorted in ascending order according to this comparison
|
function.
|
|
The return value is a pointer to the matching array element, or a
|
null pointer if no match is found. If the array contains more than
|
one element that matches, the one that is returned is unspecified.
|
|
This function derives its name from the fact that it is implemented
|
using the binary search algorithm.
|
|
|
File: libc.info, Node: Array Sort Function, Next: Search/Sort Example, Prev: Array Search Function, Up: Searching and Sorting
|
|
9.3 Array Sort Function
|
=======================
|
|
To sort an array using an arbitrary comparison function, use the ‘qsort’
|
function. The prototype for this function is in ‘stdlib.h’.
|
|
-- Function: void qsort (void *ARRAY, size_t COUNT, size_t SIZE,
|
comparison_fn_t COMPARE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Unsafe corrupt | *Note POSIX
|
Safety Concepts::.
|
|
The ‘qsort’ function sorts the array ARRAY. The array contains
|
COUNT elements, each of which is of size SIZE.
|
|
The COMPARE function is used to perform the comparison on the array
|
elements. This function is called with two pointer arguments and
|
should return an integer less than, equal to, or greater than zero
|
corresponding to whether its first argument is considered less
|
than, equal to, or greater than its second argument.
|
|
*Warning:* If two objects compare as equal, their order after
|
sorting is unpredictable. That is to say, the sorting is not
|
stable. This can make a difference when the comparison considers
|
only part of the elements. Two elements with the same sort key may
|
differ in other respects.
|
|
Although the object addresses passed to the comparison function lie
|
within the array, they need not correspond with the original
|
locations of those objects because the sorting algorithm may swap
|
around objects in the array before making some comparisons. The
|
only way to perform a stable sort with ‘qsort’ is to first augment
|
the objects with a monotonic counter of some kind.
|
|
Here is a simple example of sorting an array of doubles in
|
numerical order, using the comparison function defined above (*note
|
Comparison Functions::):
|
|
{
|
double *array;
|
int size;
|
…
|
qsort (array, size, sizeof (double), compare_doubles);
|
}
|
|
The ‘qsort’ function derives its name from the fact that it was
|
originally implemented using the “quick sort” algorithm.
|
|
The implementation of ‘qsort’ in this library might not be an
|
in-place sort and might thereby use an extra amount of memory to
|
store the array.
|
|
|
File: libc.info, Node: Search/Sort Example, Next: Hash Search Function, Prev: Array Sort Function, Up: Searching and Sorting
|
|
9.4 Searching and Sorting Example
|
=================================
|
|
Here is an example showing the use of ‘qsort’ and ‘bsearch’ with an
|
array of structures. The objects in the array are sorted by comparing
|
their ‘name’ fields with the ‘strcmp’ function. Then, we can look up
|
individual objects based on their names.
|
|
|
#include <stdlib.h>
|
#include <stdio.h>
|
#include <string.h>
|
|
/* Define an array of critters to sort. */
|
|
struct critter
|
{
|
const char *name;
|
const char *species;
|
};
|
|
struct critter muppets[] =
|
{
|
{"Kermit", "frog"},
|
{"Piggy", "pig"},
|
{"Gonzo", "whatever"},
|
{"Fozzie", "bear"},
|
{"Sam", "eagle"},
|
{"Robin", "frog"},
|
{"Animal", "animal"},
|
{"Camilla", "chicken"},
|
{"Sweetums", "monster"},
|
{"Dr. Strangepork", "pig"},
|
{"Link Hogthrob", "pig"},
|
{"Zoot", "human"},
|
{"Dr. Bunsen Honeydew", "human"},
|
{"Beaker", "human"},
|
{"Swedish Chef", "human"}
|
};
|
|
int count = sizeof (muppets) / sizeof (struct critter);
|
|
|
|
/* This is the comparison function used for sorting and searching. */
|
|
int
|
critter_cmp (const void *v1, const void *v2)
|
{
|
const struct critter *c1 = v1;
|
const struct critter *c2 = v2;
|
|
return strcmp (c1->name, c2->name);
|
}
|
|
|
/* Print information about a critter. */
|
|
void
|
print_critter (const struct critter *c)
|
{
|
printf ("%s, the %s\n", c->name, c->species);
|
}
|
|
|
/* Do the lookup into the sorted array. */
|
|
void
|
find_critter (const char *name)
|
{
|
struct critter target, *result;
|
target.name = name;
|
result = bsearch (&target, muppets, count, sizeof (struct critter),
|
critter_cmp);
|
if (result)
|
print_critter (result);
|
else
|
printf ("Couldn't find %s.\n", name);
|
}
|
|
/* Main program. */
|
|
int
|
main (void)
|
{
|
int i;
|
|
for (i = 0; i < count; i++)
|
print_critter (&muppets[i]);
|
printf ("\n");
|
|
qsort (muppets, count, sizeof (struct critter), critter_cmp);
|
|
for (i = 0; i < count; i++)
|
print_critter (&muppets[i]);
|
printf ("\n");
|
|
find_critter ("Kermit");
|
find_critter ("Gonzo");
|
find_critter ("Janice");
|
|
return 0;
|
}
|
|
The output from this program looks like:
|
|
Kermit, the frog
|
Piggy, the pig
|
Gonzo, the whatever
|
Fozzie, the bear
|
Sam, the eagle
|
Robin, the frog
|
Animal, the animal
|
Camilla, the chicken
|
Sweetums, the monster
|
Dr. Strangepork, the pig
|
Link Hogthrob, the pig
|
Zoot, the human
|
Dr. Bunsen Honeydew, the human
|
Beaker, the human
|
Swedish Chef, the human
|
|
Animal, the animal
|
Beaker, the human
|
Camilla, the chicken
|
Dr. Bunsen Honeydew, the human
|
Dr. Strangepork, the pig
|
Fozzie, the bear
|
Gonzo, the whatever
|
Kermit, the frog
|
Link Hogthrob, the pig
|
Piggy, the pig
|
Robin, the frog
|
Sam, the eagle
|
Swedish Chef, the human
|
Sweetums, the monster
|
Zoot, the human
|
|
Kermit, the frog
|
Gonzo, the whatever
|
Couldn't find Janice.
|
|
|
File: libc.info, Node: Hash Search Function, Next: Tree Search Function, Prev: Search/Sort Example, Up: Searching and Sorting
|
|
9.5 The ‘hsearch’ function.
|
===========================
|
|
The functions mentioned so far in this chapter are for searching in a
|
sorted or unsorted array. There are other methods to organize
|
information which later should be searched. The costs of insert, delete
|
and search differ. One possible implementation is using hashing tables.
|
The following functions are declared in the header file ‘search.h’.
|
|
-- Function: int hcreate (size_t NEL)
|
|
Preliminary: | MT-Unsafe race:hsearch | AS-Unsafe heap | AC-Unsafe
|
corrupt mem | *Note POSIX Safety Concepts::.
|
|
The ‘hcreate’ function creates a hashing table which can contain at
|
least NEL elements. There is no possibility to grow this table so
|
it is necessary to choose the value for NEL wisely. The method
|
used to implement this function might make it necessary to make the
|
number of elements in the hashing table larger than the expected
|
maximal number of elements. Hashing tables usually work
|
inefficiently if they are filled 80% or more. The constant access
|
time guaranteed by hashing can only be achieved if few collisions
|
exist. See Knuth’s “The Art of Computer Programming, Part 3:
|
Searching and Sorting” for more information.
|
|
The weakest aspect of this function is that there can be at most
|
one hashing table used through the whole program. The table is
|
allocated in local memory out of control of the programmer. As an
|
extension the GNU C Library provides an additional set of functions
|
with a reentrant interface which provides a similar interface but
|
which allows keeping arbitrarily many hashing tables.
|
|
It is possible to use more than one hashing table in the program
|
run if the former table is first destroyed by a call to ‘hdestroy’.
|
|
The function returns a non-zero value if successful. If it returns
|
zero, something went wrong. This could either mean there is
|
already a hashing table in use or the program ran out of memory.
|
|
-- Function: void hdestroy (void)
|
|
Preliminary: | MT-Unsafe race:hsearch | AS-Unsafe heap | AC-Unsafe
|
corrupt mem | *Note POSIX Safety Concepts::.
|
|
The ‘hdestroy’ function can be used to free all the resources
|
allocated in a previous call of ‘hcreate’. After a call to this
|
function it is again possible to call ‘hcreate’ and allocate a new
|
table with possibly different size.
|
|
It is important to remember that the elements contained in the
|
hashing table at the time ‘hdestroy’ is called are _not_ freed by
|
this function. It is the responsibility of the program code to
|
free those strings (if necessary at all). Freeing all the element
|
memory is not possible without extra, separately kept information
|
since there is no function to iterate through all available
|
elements in the hashing table. If it is really necessary to free a
|
table and all elements the programmer has to keep a list of all
|
table elements and before calling ‘hdestroy’ s/he has to free all
|
element’s data using this list. This is a very unpleasant
|
mechanism and it also shows that this kind of hashing table is
|
mainly meant for tables which are created once and used until the
|
end of the program run.
|
|
Entries of the hashing table and keys for the search are defined
|
using this type:
|
|
-- Data type: struct ENTRY
|
Both elements of this structure are pointers to zero-terminated
|
strings. This is a limiting restriction of the functionality of
|
the ‘hsearch’ functions. They can only be used for data sets which
|
use the NUL character always and solely to terminate the records.
|
It is not possible to handle general binary data.
|
|
‘char *key’
|
Pointer to a zero-terminated string of characters describing
|
the key for the search or the element in the hashing table.
|
‘char *data’
|
Pointer to a zero-terminated string of characters describing
|
the data. If the functions will be called only for searching
|
an existing entry this element might stay undefined since it
|
is not used.
|
|
-- Function: ENTRY * hsearch (ENTRY ITEM, ACTION ACTION)
|
|
Preliminary: | MT-Unsafe race:hsearch | AS-Unsafe | AC-Unsafe
|
corrupt/action==ENTER | *Note POSIX Safety Concepts::.
|
|
To search in a hashing table created using ‘hcreate’ the ‘hsearch’
|
function must be used. This function can perform a simple search
|
for an element (if ACTION has the value ‘FIND’) or it can
|
alternatively insert the key element into the hashing table.
|
Entries are never replaced.
|
|
The key is denoted by a pointer to an object of type ‘ENTRY’. For
|
locating the corresponding position in the hashing table only the
|
‘key’ element of the structure is used.
|
|
If an entry with a matching key is found the ACTION parameter is
|
irrelevant. The found entry is returned. If no matching entry is
|
found and the ACTION parameter has the value ‘FIND’ the function
|
returns a ‘NULL’ pointer. If no entry is found and the ACTION
|
parameter has the value ‘ENTER’ a new entry is added to the hashing
|
table which is initialized with the parameter ITEM. A pointer to
|
the newly added entry is returned.
|
|
As mentioned before, the hashing table used by the functions
|
described so far is global and there can be at any time at most one
|
hashing table in the program. A solution is to use the following
|
functions which are a GNU extension. All have in common that they
|
operate on a hashing table which is described by the content of an
|
object of the type ‘struct hsearch_data’. This type should be treated
|
as opaque, none of its members should be changed directly.
|
|
-- Function: int hcreate_r (size_t NEL, struct hsearch_data *HTAB)
|
|
Preliminary: | MT-Safe race:htab | AS-Unsafe heap | AC-Unsafe
|
corrupt mem | *Note POSIX Safety Concepts::.
|
|
The ‘hcreate_r’ function initializes the object pointed to by HTAB
|
to contain a hashing table with at least NEL elements. So this
|
function is equivalent to the ‘hcreate’ function except that the
|
initialized data structure is controlled by the user.
|
|
This allows having more than one hashing table at one time. The
|
memory necessary for the ‘struct hsearch_data’ object can be
|
allocated dynamically. It must be initialized with zero before
|
calling this function.
|
|
The return value is non-zero if the operation was successful. If
|
the return value is zero, something went wrong, which probably
|
means the program ran out of memory.
|
|
-- Function: void hdestroy_r (struct hsearch_data *HTAB)
|
|
Preliminary: | MT-Safe race:htab | AS-Unsafe heap | AC-Unsafe
|
corrupt mem | *Note POSIX Safety Concepts::.
|
|
The ‘hdestroy_r’ function frees all resources allocated by the
|
‘hcreate_r’ function for this very same object HTAB. As for
|
‘hdestroy’ it is the program’s responsibility to free the strings
|
for the elements of the table.
|
|
-- Function: int hsearch_r (ENTRY ITEM, ACTION ACTION, ENTRY **RETVAL,
|
struct hsearch_data *HTAB)
|
|
Preliminary: | MT-Safe race:htab | AS-Safe | AC-Unsafe
|
corrupt/action==ENTER | *Note POSIX Safety Concepts::.
|
|
The ‘hsearch_r’ function is equivalent to ‘hsearch’. The meaning
|
of the first two arguments is identical. But instead of operating
|
on a single global hashing table the function works on the table
|
described by the object pointed to by HTAB (which is initialized by
|
a call to ‘hcreate_r’).
|
|
Another difference to ‘hcreate’ is that the pointer to the found
|
entry in the table is not the return value of the function. It is
|
returned by storing it in a pointer variable pointed to by the
|
RETVAL parameter. The return value of the function is an integer
|
value indicating success if it is non-zero and failure if it is
|
zero. In the latter case the global variable ‘errno’ signals the
|
reason for the failure.
|
|
‘ENOMEM’
|
The table is filled and ‘hsearch_r’ was called with a so far
|
unknown key and ACTION set to ‘ENTER’.
|
‘ESRCH’
|
The ACTION parameter is ‘FIND’ and no corresponding element is
|
found in the table.
|
|
|
File: libc.info, Node: Tree Search Function, Prev: Hash Search Function, Up: Searching and Sorting
|
|
9.6 The ‘tsearch’ function.
|
===========================
|
|
Another common form to organize data for efficient search is to use
|
trees. The ‘tsearch’ function family provides a nice interface to
|
functions to organize possibly large amounts of data by providing a mean
|
access time proportional to the logarithm of the number of elements.
|
The GNU C Library implementation even guarantees that this bound is
|
never exceeded even for input data which cause problems for simple
|
binary tree implementations.
|
|
The functions described in the chapter are all described in the System V
|
and X/Open specifications and are therefore quite portable.
|
|
In contrast to the ‘hsearch’ functions the ‘tsearch’ functions can be
|
used with arbitrary data and not only zero-terminated strings.
|
|
The ‘tsearch’ functions have the advantage that no function to
|
initialize data structures is necessary. A simple pointer of type ‘void
|
*’ initialized to ‘NULL’ is a valid tree and can be extended or
|
searched. The prototypes for these functions can be found in the header
|
file ‘search.h’.
|
|
-- Function: void * tsearch (const void *KEY, void **ROOTP,
|
comparison_fn_t COMPAR)
|
|
Preliminary: | MT-Safe race:rootp | AS-Unsafe heap | AC-Unsafe
|
corrupt mem | *Note POSIX Safety Concepts::.
|
|
The ‘tsearch’ function searches in the tree pointed to by ‘*ROOTP’
|
for an element matching KEY. The function pointed to by COMPAR is
|
used to determine whether two elements match. *Note Comparison
|
Functions::, for a specification of the functions which can be used
|
for the COMPAR parameter.
|
|
If the tree does not contain a matching entry the KEY value will be
|
added to the tree. ‘tsearch’ does not make a copy of the object
|
pointed to by KEY (how could it since the size is unknown).
|
Instead it adds a reference to this object which means the object
|
must be available as long as the tree data structure is used.
|
|
The tree is represented by a pointer to a pointer since it is
|
sometimes necessary to change the root node of the tree. So it
|
must not be assumed that the variable pointed to by ROOTP has the
|
same value after the call. This also shows that it is not safe to
|
call the ‘tsearch’ function more than once at the same time using
|
the same tree. It is no problem to run it more than once at a time
|
on different trees.
|
|
The return value is a pointer to the matching element in the tree.
|
If a new element was created the pointer points to the new data
|
(which is in fact KEY). If an entry had to be created and the
|
program ran out of space ‘NULL’ is returned.
|
|
-- Function: void * tfind (const void *KEY, void *const *ROOTP,
|
comparison_fn_t COMPAR)
|
|
Preliminary: | MT-Safe race:rootp | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
The ‘tfind’ function is similar to the ‘tsearch’ function. It
|
locates an element matching the one pointed to by KEY and returns a
|
pointer to this element. But if no matching element is available
|
no new element is entered (note that the ROOTP parameter points to
|
a constant pointer). Instead the function returns ‘NULL’.
|
|
Another advantage of the ‘tsearch’ functions in contrast to the
|
‘hsearch’ functions is that there is an easy way to remove elements.
|
|
-- Function: void * tdelete (const void *KEY, void **ROOTP,
|
comparison_fn_t COMPAR)
|
|
Preliminary: | MT-Safe race:rootp | AS-Unsafe heap | AC-Unsafe
|
corrupt mem | *Note POSIX Safety Concepts::.
|
|
To remove a specific element matching KEY from the tree ‘tdelete’
|
can be used. It locates the matching element using the same method
|
as ‘tfind’. The corresponding element is then removed and a
|
pointer to the parent of the deleted node is returned by the
|
function. If there is no matching entry in the tree nothing can be
|
deleted and the function returns ‘NULL’. If the root of the tree
|
is deleted ‘tdelete’ returns some unspecified value not equal to
|
‘NULL’.
|
|
-- Function: void tdestroy (void *VROOT, __free_fn_t FREEFCT)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
If the complete search tree has to be removed one can use
|
‘tdestroy’. It frees all resources allocated by the ‘tsearch’
|
functions to generate the tree pointed to by VROOT.
|
|
For the data in each tree node the function FREEFCT is called. The
|
pointer to the data is passed as the argument to the function. If
|
no such work is necessary FREEFCT must point to a function doing
|
nothing. It is called in any case.
|
|
This function is a GNU extension and not covered by the System V or
|
X/Open specifications.
|
|
In addition to the functions to create and destroy the tree data
|
structure, there is another function which allows you to apply a
|
function to all elements of the tree. The function must have this type:
|
|
void __action_fn_t (const void *nodep, VISIT value, int level);
|
|
The NODEP is the data value of the current node (once given as the
|
KEY argument to ‘tsearch’). LEVEL is a numeric value which corresponds
|
to the depth of the current node in the tree. The root node has the
|
depth 0 and its children have a depth of 1 and so on. The ‘VISIT’ type
|
is an enumeration type.
|
|
-- Data Type: VISIT
|
The ‘VISIT’ value indicates the status of the current node in the
|
tree and how the function is called. The status of a node is
|
either ‘leaf’ or ‘internal node’. For each leaf node the function
|
is called exactly once, for each internal node it is called three
|
times: before the first child is processed, after the first child
|
is processed and after both children are processed. This makes it
|
possible to handle all three methods of tree traversal (or even a
|
combination of them).
|
|
‘preorder’
|
The current node is an internal node and the function is
|
called before the first child was processed.
|
‘postorder’
|
The current node is an internal node and the function is
|
called after the first child was processed.
|
‘endorder’
|
The current node is an internal node and the function is
|
called after the second child was processed.
|
‘leaf’
|
The current node is a leaf.
|
|
-- Function: void twalk (const void *ROOT, __action_fn_t ACTION)
|
|
Preliminary: | MT-Safe race:root | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
For each node in the tree with a node pointed to by ROOT, the
|
‘twalk’ function calls the function provided by the parameter
|
ACTION. For leaf nodes the function is called exactly once with
|
VALUE set to ‘leaf’. For internal nodes the function is called
|
three times, setting the VALUE parameter or ACTION to the
|
appropriate value. The LEVEL argument for the ACTION function is
|
computed while descending the tree by increasing the value by one
|
for each descent to a child, starting with the value 0 for the root
|
node.
|
|
Since the functions used for the ACTION parameter to ‘twalk’ must
|
not modify the tree data, it is safe to run ‘twalk’ in more than
|
one thread at the same time, working on the same tree. It is also
|
safe to call ‘tfind’ in parallel. Functions which modify the tree
|
must not be used, otherwise the behavior is undefined. However, it
|
is difficult to pass data external to the tree to the callback
|
function without resorting to global variables (and thread safety
|
issues), so see the ‘twalk_r’ function below.
|
|
-- Function: void twalk_r (const void *ROOT, void (*ACTION) (const void
|
*KEY, VISIT WHICH, void *CLOSURE), void *CLOSURE)
|
|
Preliminary: | MT-Safe race:root | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
For each node in the tree with a node pointed to by ROOT, the
|
‘twalk_r’ function calls the function provided by the parameter
|
ACTION. For leaf nodes the function is called exactly once with
|
WHICH set to ‘leaf’. For internal nodes the function is called
|
three times, setting the WHICH parameter of ACTION to the
|
appropriate value. The CLOSURE parameter is passed down to each
|
call of the ACTION function, unmodified.
|
|
It is possible to implement the ‘twalk’ function on top of the
|
‘twalk_r’ function, which is why there is no separate level
|
parameter.
|
|
|
#include <search.h>
|
|
struct twalk_with_twalk_r_closure
|
{
|
void (*action) (const void *, VISIT, int);
|
int depth;
|
};
|
|
static void
|
twalk_with_twalk_r_action (const void *nodep, VISIT which, void *closure0)
|
{
|
struct twalk_with_twalk_r_closure *closure = closure0;
|
|
switch (which)
|
{
|
case leaf:
|
closure->action (nodep, which, closure->depth);
|
break;
|
case preorder:
|
closure->action (nodep, which, closure->depth);
|
++closure->depth;
|
break;
|
case postorder:
|
/* The preorder action incremented the depth. */
|
closure->action (nodep, which, closure->depth - 1);
|
break;
|
case endorder:
|
--closure->depth;
|
closure->action (nodep, which, closure->depth);
|
break;
|
}
|
}
|
|
void
|
twalk (const void *root, void (*action) (const void *, VISIT, int))
|
{
|
struct twalk_with_twalk_r_closure closure = { action, 0 };
|
twalk_r (root, twalk_with_twalk_r_action, &closure);
|
}
|
|
|
File: libc.info, Node: Pattern Matching, Next: I/O Overview, Prev: Searching and Sorting, Up: Top
|
|
10 Pattern Matching
|
*******************
|
|
The GNU C Library provides pattern matching facilities for two kinds of
|
patterns: regular expressions and file-name wildcards. The library also
|
provides a facility for expanding variable and command references and
|
parsing text into words in the way the shell does.
|
|
* Menu:
|
|
* Wildcard Matching:: Matching a wildcard pattern against a single string.
|
* Globbing:: Finding the files that match a wildcard pattern.
|
* Regular Expressions:: Matching regular expressions against strings.
|
* Word Expansion:: Expanding shell variables, nested commands,
|
arithmetic, and wildcards.
|
This is what the shell does with shell commands.
|
|
|
File: libc.info, Node: Wildcard Matching, Next: Globbing, Up: Pattern Matching
|
|
10.1 Wildcard Matching
|
======================
|
|
This section describes how to match a wildcard pattern against a
|
particular string. The result is a yes or no answer: does the string
|
fit the pattern or not. The symbols described here are all declared in
|
‘fnmatch.h’.
|
|
-- Function: int fnmatch (const char *PATTERN, const char *STRING, int
|
FLAGS)
|
|
Preliminary: | MT-Safe env locale | AS-Unsafe heap | AC-Unsafe mem
|
| *Note POSIX Safety Concepts::.
|
|
This function tests whether the string STRING matches the pattern
|
PATTERN. It returns ‘0’ if they do match; otherwise, it returns
|
the nonzero value ‘FNM_NOMATCH’. The arguments PATTERN and STRING
|
are both strings.
|
|
The argument FLAGS is a combination of flag bits that alter the
|
details of matching. See below for a list of the defined flags.
|
|
In the GNU C Library, ‘fnmatch’ might sometimes report “errors” by
|
returning nonzero values that are not equal to ‘FNM_NOMATCH’.
|
|
These are the available flags for the FLAGS argument:
|
|
‘FNM_FILE_NAME’
|
|
Treat the ‘/’ character specially, for matching file names. If
|
this flag is set, wildcard constructs in PATTERN cannot match ‘/’
|
in STRING. Thus, the only way to match ‘/’ is with an explicit ‘/’
|
in PATTERN.
|
|
‘FNM_PATHNAME’
|
|
This is an alias for ‘FNM_FILE_NAME’; it comes from POSIX.2. We
|
don’t recommend this name because we don’t use the term “pathname”
|
for file names.
|
|
‘FNM_PERIOD’
|
|
Treat the ‘.’ character specially if it appears at the beginning of
|
STRING. If this flag is set, wildcard constructs in PATTERN cannot
|
match ‘.’ as the first character of STRING.
|
|
If you set both ‘FNM_PERIOD’ and ‘FNM_FILE_NAME’, then the special
|
treatment applies to ‘.’ following ‘/’ as well as to ‘.’ at the
|
beginning of STRING. (The shell uses the ‘FNM_PERIOD’ and
|
‘FNM_FILE_NAME’ flags together for matching file names.)
|
|
‘FNM_NOESCAPE’
|
|
Don’t treat the ‘\’ character specially in patterns. Normally, ‘\’
|
quotes the following character, turning off its special meaning (if
|
any) so that it matches only itself. When quoting is enabled, the
|
pattern ‘\?’ matches only the string ‘?’, because the question mark
|
in the pattern acts like an ordinary character.
|
|
If you use ‘FNM_NOESCAPE’, then ‘\’ is an ordinary character.
|
|
‘FNM_LEADING_DIR’
|
|
Ignore a trailing sequence of characters starting with a ‘/’ in
|
STRING; that is to say, test whether STRING starts with a directory
|
name that PATTERN matches.
|
|
If this flag is set, either ‘foo*’ or ‘foobar’ as a pattern would
|
match the string ‘foobar/frobozz’.
|
|
‘FNM_CASEFOLD’
|
|
Ignore case in comparing STRING to PATTERN.
|
|
‘FNM_EXTMATCH’
|
|
Besides the normal patterns, also recognize the extended patterns
|
introduced in ‘ksh’. The patterns are written in the form
|
explained in the following table where PATTERN-LIST is a ‘|’
|
separated list of patterns.
|
|
‘?(PATTERN-LIST)’
|
The pattern matches if zero or one occurrences of any of the
|
patterns in the PATTERN-LIST allow matching the input string.
|
|
‘*(PATTERN-LIST)’
|
The pattern matches if zero or more occurrences of any of the
|
patterns in the PATTERN-LIST allow matching the input string.
|
|
‘+(PATTERN-LIST)’
|
The pattern matches if one or more occurrences of any of the
|
patterns in the PATTERN-LIST allow matching the input string.
|
|
‘@(PATTERN-LIST)’
|
The pattern matches if exactly one occurrence of any of the
|
patterns in the PATTERN-LIST allows matching the input string.
|
|
‘!(PATTERN-LIST)’
|
The pattern matches if the input string cannot be matched with
|
any of the patterns in the PATTERN-LIST.
|
|
|
File: libc.info, Node: Globbing, Next: Regular Expressions, Prev: Wildcard Matching, Up: Pattern Matching
|
|
10.2 Globbing
|
=============
|
|
The archetypal use of wildcards is for matching against the files in a
|
directory, and making a list of all the matches. This is called
|
"globbing".
|
|
You could do this using ‘fnmatch’, by reading the directory entries
|
one by one and testing each one with ‘fnmatch’. But that would be slow
|
(and complex, since you would have to handle subdirectories by hand).
|
|
The library provides a function ‘glob’ to make this particular use of
|
wildcards convenient. ‘glob’ and the other symbols in this section are
|
declared in ‘glob.h’.
|
|
* Menu:
|
|
* Calling Glob:: Basic use of ‘glob’.
|
* Flags for Globbing:: Flags that enable various options in ‘glob’.
|
* More Flags for Globbing:: GNU specific extensions to ‘glob’.
|
|
|
File: libc.info, Node: Calling Glob, Next: Flags for Globbing, Up: Globbing
|
|
10.2.1 Calling ‘glob’
|
---------------------
|
|
The result of globbing is a vector of file names (strings). To return
|
this vector, ‘glob’ uses a special data type, ‘glob_t’, which is a
|
structure. You pass ‘glob’ the address of the structure, and it fills
|
in the structure’s fields to tell you about the results.
|
|
-- Data Type: glob_t
|
|
This data type holds a pointer to a word vector. More precisely,
|
it records both the address of the word vector and its size. The
|
GNU implementation contains some more fields which are non-standard
|
extensions.
|
|
‘gl_pathc’
|
The number of elements in the vector, excluding the initial
|
null entries if the GLOB_DOOFFS flag is used (see gl_offs
|
below).
|
|
‘gl_pathv’
|
The address of the vector. This field has type ‘char **’.
|
|
‘gl_offs’
|
The offset of the first real element of the vector, from its
|
nominal address in the ‘gl_pathv’ field. Unlike the other
|
fields, this is always an input to ‘glob’, rather than an
|
output from it.
|
|
If you use a nonzero offset, then that many elements at the
|
beginning of the vector are left empty. (The ‘glob’ function
|
fills them with null pointers.)
|
|
The ‘gl_offs’ field is meaningful only if you use the
|
‘GLOB_DOOFFS’ flag. Otherwise, the offset is always zero
|
regardless of what is in this field, and the first real
|
element comes at the beginning of the vector.
|
|
‘gl_closedir’
|
The address of an alternative implementation of the ‘closedir’
|
function. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in
|
the flag parameter. The type of this field is
|
‘void (*) (void *)’.
|
|
This is a GNU extension.
|
|
‘gl_readdir’
|
The address of an alternative implementation of the ‘readdir’
|
function used to read the contents of a directory. It is used
|
if the ‘GLOB_ALTDIRFUNC’ bit is set in the flag parameter.
|
The type of this field is ‘struct dirent *(*) (void *)’.
|
|
An implementation of ‘gl_readdir’ needs to initialize the
|
following members of the ‘struct dirent’ object:
|
|
‘d_type’
|
This member should be set to the file type of the entry
|
if it is known. Otherwise, the value ‘DT_UNKNOWN’ can be
|
used. The ‘glob’ function may use the specified file
|
type to avoid callbacks in cases where the file type
|
indicates that the data is not required.
|
|
‘d_ino’
|
This member needs to be non-zero, otherwise ‘glob’ may
|
skip the current entry and call the ‘gl_readdir’ callback
|
function again to retrieve another entry.
|
|
‘d_name’
|
This member must be set to the name of the entry. It
|
must be null-terminated.
|
|
The example below shows how to allocate a ‘struct dirent’
|
object containing a given name.
|
|
|
#include <dirent.h>
|
#include <errno.h>
|
#include <stddef.h>
|
#include <stdlib.h>
|
#include <string.h>
|
|
struct dirent *
|
mkdirent (const char *name)
|
{
|
size_t dirent_size = offsetof (struct dirent, d_name) + 1;
|
size_t name_length = strlen (name);
|
size_t total_size = dirent_size + name_length;
|
if (total_size < dirent_size)
|
{
|
errno = ENOMEM;
|
return NULL;
|
}
|
struct dirent *result = malloc (total_size);
|
if (result == NULL)
|
return NULL;
|
result->d_type = DT_UNKNOWN;
|
result->d_ino = 1; /* Do not skip this entry. */
|
memcpy (result->d_name, name, name_length + 1);
|
return result;
|
}
|
|
The ‘glob’ function reads the ‘struct dirent’ members listed
|
above and makes a copy of the file name in the ‘d_name’ member
|
immediately after the ‘gl_readdir’ callback function returns.
|
Future invocations of any of the callback functions may
|
dealloacte or reuse the buffer. It is the responsibility of
|
the caller of the ‘glob’ function to allocate and deallocate
|
the buffer, around the call to ‘glob’ or using the callback
|
functions. For example, an application could allocate the
|
buffer in the ‘gl_readdir’ callback function, and deallocate
|
it in the ‘gl_closedir’ callback function.
|
|
The ‘gl_readdir’ member is a GNU extension.
|
|
‘gl_opendir’
|
The address of an alternative implementation of the ‘opendir’
|
function. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in
|
the flag parameter. The type of this field is
|
‘void *(*) (const char *)’.
|
|
This is a GNU extension.
|
|
‘gl_stat’
|
The address of an alternative implementation of the ‘stat’
|
function to get information about an object in the filesystem.
|
It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in the flag
|
parameter. The type of this field is
|
‘int (*) (const char *, struct stat *)’.
|
|
This is a GNU extension.
|
|
‘gl_lstat’
|
The address of an alternative implementation of the ‘lstat’
|
function to get information about an object in the
|
filesystems, not following symbolic links. It is used if the
|
‘GLOB_ALTDIRFUNC’ bit is set in the flag parameter. The type
|
of this field is ‘int (*) (const char *, struct stat *)’.
|
|
This is a GNU extension.
|
|
‘gl_flags’
|
The flags used when ‘glob’ was called. In addition,
|
‘GLOB_MAGCHAR’ might be set. See *note Flags for Globbing::
|
for more details.
|
|
This is a GNU extension.
|
|
For use in the ‘glob64’ function ‘glob.h’ contains another definition
|
for a very similar type. ‘glob64_t’ differs from ‘glob_t’ only in the
|
types of the members ‘gl_readdir’, ‘gl_stat’, and ‘gl_lstat’.
|
|
-- Data Type: glob64_t
|
|
This data type holds a pointer to a word vector. More precisely,
|
it records both the address of the word vector and its size. The
|
GNU implementation contains some more fields which are non-standard
|
extensions.
|
|
‘gl_pathc’
|
The number of elements in the vector, excluding the initial
|
null entries if the GLOB_DOOFFS flag is used (see gl_offs
|
below).
|
|
‘gl_pathv’
|
The address of the vector. This field has type ‘char **’.
|
|
‘gl_offs’
|
The offset of the first real element of the vector, from its
|
nominal address in the ‘gl_pathv’ field. Unlike the other
|
fields, this is always an input to ‘glob’, rather than an
|
output from it.
|
|
If you use a nonzero offset, then that many elements at the
|
beginning of the vector are left empty. (The ‘glob’ function
|
fills them with null pointers.)
|
|
The ‘gl_offs’ field is meaningful only if you use the
|
‘GLOB_DOOFFS’ flag. Otherwise, the offset is always zero
|
regardless of what is in this field, and the first real
|
element comes at the beginning of the vector.
|
|
‘gl_closedir’
|
The address of an alternative implementation of the ‘closedir’
|
function. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in
|
the flag parameter. The type of this field is
|
‘void (*) (void *)’.
|
|
This is a GNU extension.
|
|
‘gl_readdir’
|
The address of an alternative implementation of the
|
‘readdir64’ function used to read the contents of a directory.
|
It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in the flag
|
parameter. The type of this field is
|
‘struct dirent64 *(*) (void *)’.
|
|
This is a GNU extension.
|
|
‘gl_opendir’
|
The address of an alternative implementation of the ‘opendir’
|
function. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in
|
the flag parameter. The type of this field is
|
‘void *(*) (const char *)’.
|
|
This is a GNU extension.
|
|
‘gl_stat’
|
The address of an alternative implementation of the ‘stat64’
|
function to get information about an object in the filesystem.
|
It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in the flag
|
parameter. The type of this field is
|
‘int (*) (const char *, struct stat64 *)’.
|
|
This is a GNU extension.
|
|
‘gl_lstat’
|
The address of an alternative implementation of the ‘lstat64’
|
function to get information about an object in the
|
filesystems, not following symbolic links. It is used if the
|
‘GLOB_ALTDIRFUNC’ bit is set in the flag parameter. The type
|
of this field is ‘int (*) (const char *, struct stat64 *)’.
|
|
This is a GNU extension.
|
|
‘gl_flags’
|
The flags used when ‘glob’ was called. In addition,
|
‘GLOB_MAGCHAR’ might be set. See *note Flags for Globbing::
|
for more details.
|
|
This is a GNU extension.
|
|
-- Function: int glob (const char *PATTERN, int FLAGS, int (*ERRFUNC)
|
(const char *FILENAME, int ERROR-CODE), glob_t *VECTOR-PTR)
|
|
Preliminary: | MT-Unsafe race:utent env sig:ALRM timer locale |
|
AS-Unsafe dlopen plugin corrupt heap lock | AC-Unsafe corrupt lock
|
fd mem | *Note POSIX Safety Concepts::.
|
|
The function ‘glob’ does globbing using the pattern PATTERN in the
|
current directory. It puts the result in a newly allocated vector,
|
and stores the size and address of this vector into ‘*VECTOR-PTR’.
|
The argument FLAGS is a combination of bit flags; see *note Flags
|
for Globbing::, for details of the flags.
|
|
The result of globbing is a sequence of file names. The function
|
‘glob’ allocates a string for each resulting word, then allocates a
|
vector of type ‘char **’ to store the addresses of these strings.
|
The last element of the vector is a null pointer. This vector is
|
called the "word vector".
|
|
To return this vector, ‘glob’ stores both its address and its
|
length (number of elements, not counting the terminating null
|
pointer) into ‘*VECTOR-PTR’.
|
|
Normally, ‘glob’ sorts the file names alphabetically before
|
returning them. You can turn this off with the flag ‘GLOB_NOSORT’
|
if you want to get the information as fast as possible. Usually
|
it’s a good idea to let ‘glob’ sort them—if you process the files
|
in alphabetical order, the users will have a feel for the rate of
|
progress that your application is making.
|
|
If ‘glob’ succeeds, it returns 0. Otherwise, it returns one of
|
these error codes:
|
|
‘GLOB_ABORTED’
|
|
There was an error opening a directory, and you used the flag
|
‘GLOB_ERR’ or your specified ERRFUNC returned a nonzero value.
|
*Note Flags for Globbing::, for an explanation of the
|
‘GLOB_ERR’ flag and ERRFUNC.
|
|
‘GLOB_NOMATCH’
|
|
The pattern didn’t match any existing files. If you use the
|
‘GLOB_NOCHECK’ flag, then you never get this error code,
|
because that flag tells ‘glob’ to _pretend_ that the pattern
|
matched at least one file.
|
|
‘GLOB_NOSPACE’
|
|
It was impossible to allocate memory to hold the result.
|
|
In the event of an error, ‘glob’ stores information in
|
‘*VECTOR-PTR’ about all the matches it has found so far.
|
|
It is important to notice that the ‘glob’ function will not fail if
|
it encounters directories or files which cannot be handled without
|
the LFS interfaces. The implementation of ‘glob’ is supposed to
|
use these functions internally. This at least is the assumption
|
made by the Unix standard. The GNU extension of allowing the user
|
to provide their own directory handling and ‘stat’ functions
|
complicates things a bit. If these callback functions are used and
|
a large file or directory is encountered ‘glob’ _can_ fail.
|
|
-- Function: int glob64 (const char *PATTERN, int FLAGS, int (*ERRFUNC)
|
(const char *FILENAME, int ERROR-CODE), glob64_t *VECTOR-PTR)
|
|
Preliminary: | MT-Unsafe race:utent env sig:ALRM timer locale |
|
AS-Unsafe dlopen corrupt heap lock | AC-Unsafe corrupt lock fd mem
|
| *Note POSIX Safety Concepts::.
|
|
The ‘glob64’ function was added as part of the Large File Summit
|
extensions but is not part of the original LFS proposal. The
|
reason for this is simple: it is not necessary. The necessity for
|
a ‘glob64’ function is added by the extensions of the GNU ‘glob’
|
implementation which allows the user to provide their own directory
|
handling and ‘stat’ functions. The ‘readdir’ and ‘stat’ functions
|
do depend on the choice of ‘_FILE_OFFSET_BITS’ since the definition
|
of the types ‘struct dirent’ and ‘struct stat’ will change
|
depending on the choice.
|
|
Besides this difference, ‘glob64’ works just like ‘glob’ in all
|
aspects.
|
|
This function is a GNU extension.
|
|
|
File: libc.info, Node: Flags for Globbing, Next: More Flags for Globbing, Prev: Calling Glob, Up: Globbing
|
|
10.2.2 Flags for Globbing
|
-------------------------
|
|
This section describes the standard flags that you can specify in the
|
FLAGS argument to ‘glob’. Choose the flags you want, and combine them
|
with the C bitwise OR operator ‘|’.
|
|
Note that there are *note More Flags for Globbing:: available as GNU
|
extensions.
|
|
‘GLOB_APPEND’
|
|
Append the words from this expansion to the vector of words
|
produced by previous calls to ‘glob’. This way you can effectively
|
expand several words as if they were concatenated with spaces
|
between them.
|
|
In order for appending to work, you must not modify the contents of
|
the word vector structure between calls to ‘glob’. And, if you set
|
‘GLOB_DOOFFS’ in the first call to ‘glob’, you must also set it
|
when you append to the results.
|
|
Note that the pointer stored in ‘gl_pathv’ may no longer be valid
|
after you call ‘glob’ the second time, because ‘glob’ might have
|
relocated the vector. So always fetch ‘gl_pathv’ from the ‘glob_t’
|
structure after each ‘glob’ call; *never* save the pointer across
|
calls.
|
|
‘GLOB_DOOFFS’
|
|
Leave blank slots at the beginning of the vector of words. The
|
‘gl_offs’ field says how many slots to leave. The blank slots
|
contain null pointers.
|
|
‘GLOB_ERR’
|
|
Give up right away and report an error if there is any difficulty
|
reading the directories that must be read in order to expand
|
PATTERN fully. Such difficulties might include a directory in
|
which you don’t have the requisite access. Normally, ‘glob’ tries
|
its best to keep on going despite any errors, reading whatever
|
directories it can.
|
|
You can exercise even more control than this by specifying an
|
error-handler function ERRFUNC when you call ‘glob’. If ERRFUNC is
|
not a null pointer, then ‘glob’ doesn’t give up right away when it
|
can’t read a directory; instead, it calls ERRFUNC with two
|
arguments, like this:
|
|
(*ERRFUNC) (FILENAME, ERROR-CODE)
|
|
The argument FILENAME is the name of the directory that ‘glob’
|
couldn’t open or couldn’t read, and ERROR-CODE is the ‘errno’ value
|
that was reported to ‘glob’.
|
|
If the error handler function returns nonzero, then ‘glob’ gives up
|
right away. Otherwise, it continues.
|
|
‘GLOB_MARK’
|
|
If the pattern matches the name of a directory, append ‘/’ to the
|
directory’s name when returning it.
|
|
‘GLOB_NOCHECK’
|
|
If the pattern doesn’t match any file names, return the pattern
|
itself as if it were a file name that had been matched. (Normally,
|
when the pattern doesn’t match anything, ‘glob’ returns that there
|
were no matches.)
|
|
‘GLOB_NOESCAPE’
|
|
Don’t treat the ‘\’ character specially in patterns. Normally, ‘\’
|
quotes the following character, turning off its special meaning (if
|
any) so that it matches only itself. When quoting is enabled, the
|
pattern ‘\?’ matches only the string ‘?’, because the question mark
|
in the pattern acts like an ordinary character.
|
|
If you use ‘GLOB_NOESCAPE’, then ‘\’ is an ordinary character.
|
|
‘glob’ does its work by calling the function ‘fnmatch’ repeatedly.
|
It handles the flag ‘GLOB_NOESCAPE’ by turning on the
|
‘FNM_NOESCAPE’ flag in calls to ‘fnmatch’.
|
|
‘GLOB_NOSORT’
|
|
Don’t sort the file names; return them in no particular order. (In
|
practice, the order will depend on the order of the entries in the
|
directory.) The only reason _not_ to sort is to save time.
|
|
|
File: libc.info, Node: More Flags for Globbing, Prev: Flags for Globbing, Up: Globbing
|
|
10.2.3 More Flags for Globbing
|
------------------------------
|
|
Beside the flags described in the last section, the GNU implementation
|
of ‘glob’ allows a few more flags which are also defined in the ‘glob.h’
|
file. Some of the extensions implement functionality which is available
|
in modern shell implementations.
|
|
‘GLOB_PERIOD’
|
|
The ‘.’ character (period) is treated special. It cannot be
|
matched by wildcards. *Note Wildcard Matching::, ‘FNM_PERIOD’.
|
|
‘GLOB_MAGCHAR’
|
|
The ‘GLOB_MAGCHAR’ value is not to be given to ‘glob’ in the FLAGS
|
parameter. Instead, ‘glob’ sets this bit in the GL_FLAGS element
|
of the GLOB_T structure provided as the result if the pattern used
|
for matching contains any wildcard character.
|
|
‘GLOB_ALTDIRFUNC’
|
|
Instead of using the normal functions for accessing the filesystem
|
the ‘glob’ implementation uses the user-supplied functions
|
specified in the structure pointed to by PGLOB parameter. For more
|
information about the functions refer to the sections about
|
directory handling see *note Accessing Directories::, and *note
|
Reading Attributes::.
|
|
‘GLOB_BRACE’
|
|
If this flag is given, the handling of braces in the pattern is
|
changed. It is now required that braces appear correctly grouped.
|
I.e., for each opening brace there must be a closing one. Braces
|
can be used recursively. So it is possible to define one brace
|
expression in another one. It is important to note that the range
|
of each brace expression is completely contained in the outer brace
|
expression (if there is one).
|
|
The string between the matching braces is separated into single
|
expressions by splitting at ‘,’ (comma) characters. The commas
|
themselves are discarded. Please note what we said above about
|
recursive brace expressions. The commas used to separate the
|
subexpressions must be at the same level. Commas in brace
|
subexpressions are not matched. They are used during expansion of
|
the brace expression of the deeper level. The example below shows
|
this
|
|
glob ("{foo/{,bar,biz},baz}", GLOB_BRACE, NULL, &result)
|
|
is equivalent to the sequence
|
|
glob ("foo/", GLOB_BRACE, NULL, &result)
|
glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)
|
glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
|
glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
|
|
if we leave aside error handling.
|
|
‘GLOB_NOMAGIC’
|
|
If the pattern contains no wildcard constructs (it is a literal
|
file name), return it as the sole “matching” word, even if no file
|
exists by that name.
|
|
‘GLOB_TILDE’
|
|
If this flag is used the character ‘~’ (tilde) is handled specially
|
if it appears at the beginning of the pattern. Instead of being
|
taken verbatim it is used to represent the home directory of a
|
known user.
|
|
If ‘~’ is the only character in pattern or it is followed by a ‘/’
|
(slash), the home directory of the process owner is substituted.
|
Using ‘getlogin’ and ‘getpwnam’ the information is read from the
|
system databases. As an example take user ‘bart’ with his home
|
directory at ‘/home/bart’. For him a call like
|
|
glob ("~/bin/*", GLOB_TILDE, NULL, &result)
|
|
would return the contents of the directory ‘/home/bart/bin’.
|
Instead of referring to the own home directory it is also possible
|
to name the home directory of other users. To do so one has to
|
append the user name after the tilde character. So the contents of
|
user ‘homer’’s ‘bin’ directory can be retrieved by
|
|
glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)
|
|
If the user name is not valid or the home directory cannot be
|
determined for some reason the pattern is left untouched and itself
|
used as the result. I.e., if in the last example ‘home’ is not
|
available the tilde expansion yields to ‘"~homer/bin/*"’ and ‘glob’
|
is not looking for a directory named ‘~homer’.
|
|
This functionality is equivalent to what is available in C-shells
|
if the ‘nonomatch’ flag is set.
|
|
‘GLOB_TILDE_CHECK’
|
|
If this flag is used ‘glob’ behaves as if ‘GLOB_TILDE’ is given.
|
The only difference is that if the user name is not available or
|
the home directory cannot be determined for other reasons this
|
leads to an error. ‘glob’ will return ‘GLOB_NOMATCH’ instead of
|
using the pattern itself as the name.
|
|
This functionality is equivalent to what is available in C-shells
|
if the ‘nonomatch’ flag is not set.
|
|
‘GLOB_ONLYDIR’
|
|
If this flag is used the globbing function takes this as a *hint*
|
that the caller is only interested in directories matching the
|
pattern. If the information about the type of the file is easily
|
available non-directories will be rejected but no extra work will
|
be done to determine the information for each file. I.e., the
|
caller must still be able to filter directories out.
|
|
This functionality is only available with the GNU ‘glob’
|
implementation. It is mainly used internally to increase the
|
performance but might be useful for a user as well and therefore is
|
documented here.
|
|
Calling ‘glob’ will in most cases allocate resources which are used
|
to represent the result of the function call. If the same object of
|
type ‘glob_t’ is used in multiple call to ‘glob’ the resources are freed
|
or reused so that no leaks appear. But this does not include the time
|
when all ‘glob’ calls are done.
|
|
-- Function: void globfree (glob_t *PGLOB)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe corrupt
|
mem | *Note POSIX Safety Concepts::.
|
|
The ‘globfree’ function frees all resources allocated by previous
|
calls to ‘glob’ associated with the object pointed to by PGLOB.
|
This function should be called whenever the currently used ‘glob_t’
|
typed object isn’t used anymore.
|
|
-- Function: void globfree64 (glob64_t *PGLOB)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt lock | AC-Unsafe corrupt
|
lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function is equivalent to ‘globfree’ but it frees records of
|
type ‘glob64_t’ which were allocated by ‘glob64’.
|
|
|
File: libc.info, Node: Regular Expressions, Next: Word Expansion, Prev: Globbing, Up: Pattern Matching
|
|
10.3 Regular Expression Matching
|
================================
|
|
The GNU C Library supports two interfaces for matching regular
|
expressions. One is the standard POSIX.2 interface, and the other is
|
what the GNU C Library has had for many years.
|
|
Both interfaces are declared in the header file ‘regex.h’. If you
|
define ‘_POSIX_C_SOURCE’, then only the POSIX.2 functions, structures,
|
and constants are declared.
|
|
* Menu:
|
|
* POSIX Regexp Compilation:: Using ‘regcomp’ to prepare to match.
|
* Flags for POSIX Regexps:: Syntax variations for ‘regcomp’.
|
* Matching POSIX Regexps:: Using ‘regexec’ to match the compiled
|
pattern that you get from ‘regcomp’.
|
* Regexp Subexpressions:: Finding which parts of the string were matched.
|
* Subexpression Complications:: Find points of which parts were matched.
|
* Regexp Cleanup:: Freeing storage; reporting errors.
|
|
|
File: libc.info, Node: POSIX Regexp Compilation, Next: Flags for POSIX Regexps, Up: Regular Expressions
|
|
10.3.1 POSIX Regular Expression Compilation
|
-------------------------------------------
|
|
Before you can actually match a regular expression, you must "compile"
|
it. This is not true compilation—it produces a special data structure,
|
not machine instructions. But it is like ordinary compilation in that
|
its purpose is to enable you to “execute” the pattern fast. (*Note
|
Matching POSIX Regexps::, for how to use the compiled regular expression
|
for matching.)
|
|
There is a special data type for compiled regular expressions:
|
|
-- Data Type: regex_t
|
|
This type of object holds a compiled regular expression. It is
|
actually a structure. It has just one field that your programs
|
should look at:
|
|
‘re_nsub’
|
This field holds the number of parenthetical subexpressions in
|
the regular expression that was compiled.
|
|
There are several other fields, but we don’t describe them here,
|
because only the functions in the library should use them.
|
|
After you create a ‘regex_t’ object, you can compile a regular
|
expression into it by calling ‘regcomp’.
|
|
-- Function: int regcomp (regex_t *restrict COMPILED, const char
|
*restrict PATTERN, int CFLAGS)
|
|
Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
|
| AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
|
|
The function ‘regcomp’ “compiles” a regular expression into a data
|
structure that you can use with ‘regexec’ to match against a
|
string. The compiled regular expression format is designed for
|
efficient matching. ‘regcomp’ stores it into ‘*COMPILED’.
|
|
It’s up to you to allocate an object of type ‘regex_t’ and pass its
|
address to ‘regcomp’.
|
|
The argument CFLAGS lets you specify various options that control
|
the syntax and semantics of regular expressions. *Note Flags for
|
POSIX Regexps::.
|
|
If you use the flag ‘REG_NOSUB’, then ‘regcomp’ omits from the
|
compiled regular expression the information necessary to record how
|
subexpressions actually match. In this case, you might as well
|
pass ‘0’ for the MATCHPTR and NMATCH arguments when you call
|
‘regexec’.
|
|
If you don’t use ‘REG_NOSUB’, then the compiled regular expression
|
does have the capacity to record how subexpressions match. Also,
|
‘regcomp’ tells you how many subexpressions PATTERN has, by storing
|
the number in ‘COMPILED->re_nsub’. You can use that value to
|
decide how long an array to allocate to hold information about
|
subexpression matches.
|
|
‘regcomp’ returns ‘0’ if it succeeds in compiling the regular
|
expression; otherwise, it returns a nonzero error code (see the
|
table below). You can use ‘regerror’ to produce an error message
|
string describing the reason for a nonzero value; see *note Regexp
|
Cleanup::.
|
|
Here are the possible nonzero values that ‘regcomp’ can return:
|
|
‘REG_BADBR’
|
|
There was an invalid ‘\{…\}’ construct in the regular expression.
|
A valid ‘\{…\}’ construct must contain either a single number, or
|
two numbers in increasing order separated by a comma.
|
|
‘REG_BADPAT’
|
|
There was a syntax error in the regular expression.
|
|
‘REG_BADRPT’
|
|
A repetition operator such as ‘?’ or ‘*’ appeared in a bad position
|
(with no preceding subexpression to act on).
|
|
‘REG_ECOLLATE’
|
|
The regular expression referred to an invalid collating element
|
(one not defined in the current locale for string collation).
|
*Note Locale Categories::.
|
|
‘REG_ECTYPE’
|
|
The regular expression referred to an invalid character class name.
|
|
‘REG_EESCAPE’
|
|
The regular expression ended with ‘\’.
|
|
‘REG_ESUBREG’
|
|
There was an invalid number in the ‘\DIGIT’ construct.
|
|
‘REG_EBRACK’
|
|
There were unbalanced square brackets in the regular expression.
|
|
‘REG_EPAREN’
|
|
An extended regular expression had unbalanced parentheses, or a
|
basic regular expression had unbalanced ‘\(’ and ‘\)’.
|
|
‘REG_EBRACE’
|
|
The regular expression had unbalanced ‘\{’ and ‘\}’.
|
|
‘REG_ERANGE’
|
|
One of the endpoints in a range expression was invalid.
|
|
‘REG_ESPACE’
|
|
‘regcomp’ ran out of memory.
|
|
|
File: libc.info, Node: Flags for POSIX Regexps, Next: Matching POSIX Regexps, Prev: POSIX Regexp Compilation, Up: Regular Expressions
|
|
10.3.2 Flags for POSIX Regular Expressions
|
------------------------------------------
|
|
These are the bit flags that you can use in the CFLAGS operand when
|
compiling a regular expression with ‘regcomp’.
|
|
‘REG_EXTENDED’
|
|
Treat the pattern as an extended regular expression, rather than as
|
a basic regular expression.
|
|
‘REG_ICASE’
|
|
Ignore case when matching letters.
|
|
‘REG_NOSUB’
|
|
Don’t bother storing the contents of the MATCHPTR array.
|
|
‘REG_NEWLINE’
|
|
Treat a newline in STRING as dividing STRING into multiple lines,
|
so that ‘$’ can match before the newline and ‘^’ can match after.
|
Also, don’t permit ‘.’ to match a newline, and don’t permit ‘[^…]’
|
to match a newline.
|
|
Otherwise, newline acts like any other ordinary character.
|
|
|
File: libc.info, Node: Matching POSIX Regexps, Next: Regexp Subexpressions, Prev: Flags for POSIX Regexps, Up: Regular Expressions
|
|
10.3.3 Matching a Compiled POSIX Regular Expression
|
---------------------------------------------------
|
|
Once you have compiled a regular expression, as described in *note POSIX
|
Regexp Compilation::, you can match it against strings using ‘regexec’.
|
A match anywhere inside the string counts as success, unless the regular
|
expression contains anchor characters (‘^’ or ‘$’).
|
|
-- Function: int regexec (const regex_t *restrict COMPILED, const char
|
*restrict STRING, size_t NMATCH, regmatch_t
|
MATCHPTR[restrict], int EFLAGS)
|
|
Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
|
| AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
|
|
This function tries to match the compiled regular expression
|
‘*COMPILED’ against STRING.
|
|
‘regexec’ returns ‘0’ if the regular expression matches; otherwise,
|
it returns a nonzero value. See the table below for what nonzero
|
values mean. You can use ‘regerror’ to produce an error message
|
string describing the reason for a nonzero value; see *note Regexp
|
Cleanup::.
|
|
The argument EFLAGS is a word of bit flags that enable various
|
options.
|
|
If you want to get information about what part of STRING actually
|
matched the regular expression or its subexpressions, use the
|
arguments MATCHPTR and NMATCH. Otherwise, pass ‘0’ for NMATCH, and
|
‘NULL’ for MATCHPTR. *Note Regexp Subexpressions::.
|
|
You must match the regular expression with the same set of current
|
locales that were in effect when you compiled the regular expression.
|
|
The function ‘regexec’ accepts the following flags in the EFLAGS
|
argument:
|
|
‘REG_NOTBOL’
|
|
Do not regard the beginning of the specified string as the
|
beginning of a line; more generally, don’t make any assumptions
|
about what text might precede it.
|
|
‘REG_NOTEOL’
|
|
Do not regard the end of the specified string as the end of a line;
|
more generally, don’t make any assumptions about what text might
|
follow it.
|
|
Here are the possible nonzero values that ‘regexec’ can return:
|
|
‘REG_NOMATCH’
|
|
The pattern didn’t match the string. This isn’t really an error.
|
|
‘REG_ESPACE’
|
|
‘regexec’ ran out of memory.
|
|
|
File: libc.info, Node: Regexp Subexpressions, Next: Subexpression Complications, Prev: Matching POSIX Regexps, Up: Regular Expressions
|
|
10.3.4 Match Results with Subexpressions
|
----------------------------------------
|
|
When ‘regexec’ matches parenthetical subexpressions of PATTERN, it
|
records which parts of STRING they match. It returns that information
|
by storing the offsets into an array whose elements are structures of
|
type ‘regmatch_t’. The first element of the array (index ‘0’) records
|
the part of the string that matched the entire regular expression. Each
|
other element of the array records the beginning and end of the part
|
that matched a single parenthetical subexpression.
|
|
-- Data Type: regmatch_t
|
|
This is the data type of the MATCHPTR array that you pass to
|
‘regexec’. It contains two structure fields, as follows:
|
|
‘rm_so’
|
The offset in STRING of the beginning of a substring. Add
|
this value to STRING to get the address of that part.
|
|
‘rm_eo’
|
The offset in STRING of the end of the substring.
|
|
-- Data Type: regoff_t
|
|
‘regoff_t’ is an alias for another signed integer type. The fields
|
of ‘regmatch_t’ have type ‘regoff_t’.
|
|
The ‘regmatch_t’ elements correspond to subexpressions positionally;
|
the first element (index ‘1’) records where the first subexpression
|
matched, the second element records the second subexpression, and so on.
|
The order of the subexpressions is the order in which they begin.
|
|
When you call ‘regexec’, you specify how long the MATCHPTR array is,
|
with the NMATCH argument. This tells ‘regexec’ how many elements to
|
store. If the actual regular expression has more than NMATCH
|
subexpressions, then you won’t get offset information about the rest of
|
them. But this doesn’t alter whether the pattern matches a particular
|
string or not.
|
|
If you don’t want ‘regexec’ to return any information about where the
|
subexpressions matched, you can either supply ‘0’ for NMATCH, or use the
|
flag ‘REG_NOSUB’ when you compile the pattern with ‘regcomp’.
|
|
|
File: libc.info, Node: Subexpression Complications, Next: Regexp Cleanup, Prev: Regexp Subexpressions, Up: Regular Expressions
|
|
10.3.5 Complications in Subexpression Matching
|
----------------------------------------------
|
|
Sometimes a subexpression matches a substring of no characters. This
|
happens when ‘f\(o*\)’ matches the string ‘fum’. (It really matches
|
just the ‘f’.) In this case, both of the offsets identify the point in
|
the string where the null substring was found. In this example, the
|
offsets are both ‘1’.
|
|
Sometimes the entire regular expression can match without using some
|
of its subexpressions at all—for example, when ‘ba\(na\)*’ matches the
|
string ‘ba’, the parenthetical subexpression is not used. When this
|
happens, ‘regexec’ stores ‘-1’ in both fields of the element for that
|
subexpression.
|
|
Sometimes matching the entire regular expression can match a
|
particular subexpression more than once—for example, when ‘ba\(na\)*’
|
matches the string ‘bananana’, the parenthetical subexpression matches
|
three times. When this happens, ‘regexec’ usually stores the offsets of
|
the last part of the string that matched the subexpression. In the case
|
of ‘bananana’, these offsets are ‘6’ and ‘8’.
|
|
But the last match is not always the one that is chosen. It’s more
|
accurate to say that the last _opportunity_ to match is the one that
|
takes precedence. What this means is that when one subexpression
|
appears within another, then the results reported for the inner
|
subexpression reflect whatever happened on the last match of the outer
|
subexpression. For an example, consider ‘\(ba\(na\)*s \)*’ matching the
|
string ‘bananas bas ’. The last time the inner expression actually
|
matches is near the end of the first word. But it is _considered_ again
|
in the second word, and fails to match there. ‘regexec’ reports nonuse
|
of the “na” subexpression.
|
|
Another place where this rule applies is when the regular expression
|
\(ba\(na\)*s \|nefer\(ti\)* \)*
|
matches ‘bananas nefertiti’. The “na” subexpression does match in the
|
first word, but it doesn’t match in the second word because the other
|
alternative is used there. Once again, the second repetition of the
|
outer subexpression overrides the first, and within that second
|
repetition, the “na” subexpression is not used. So ‘regexec’ reports
|
nonuse of the “na” subexpression.
|
|
|
File: libc.info, Node: Regexp Cleanup, Prev: Subexpression Complications, Up: Regular Expressions
|
|
10.3.6 POSIX Regexp Matching Cleanup
|
------------------------------------
|
|
When you are finished using a compiled regular expression, you can free
|
the storage it uses by calling ‘regfree’.
|
|
-- Function: void regfree (regex_t *COMPILED)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
Calling ‘regfree’ frees all the storage that ‘*COMPILED’ points to.
|
This includes various internal fields of the ‘regex_t’ structure
|
that aren’t documented in this manual.
|
|
‘regfree’ does not free the object ‘*COMPILED’ itself.
|
|
You should always free the space in a ‘regex_t’ structure with
|
‘regfree’ before using the structure to compile another regular
|
expression.
|
|
When ‘regcomp’ or ‘regexec’ reports an error, you can use the
|
function ‘regerror’ to turn it into an error message string.
|
|
-- Function: size_t regerror (int ERRCODE, const regex_t *restrict
|
COMPILED, char *restrict BUFFER, size_t LENGTH)
|
|
Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function produces an error message string for the error code
|
ERRCODE, and stores the string in LENGTH bytes of memory starting
|
at BUFFER. For the COMPILED argument, supply the same compiled
|
regular expression structure that ‘regcomp’ or ‘regexec’ was
|
working with when it got the error. Alternatively, you can supply
|
‘NULL’ for COMPILED; you will still get a meaningful error message,
|
but it might not be as detailed.
|
|
If the error message can’t fit in LENGTH bytes (including a
|
terminating null character), then ‘regerror’ truncates it. The
|
string that ‘regerror’ stores is always null-terminated even if it
|
has been truncated.
|
|
The return value of ‘regerror’ is the minimum length needed to
|
store the entire error message. If this is less than LENGTH, then
|
the error message was not truncated, and you can use it.
|
Otherwise, you should call ‘regerror’ again with a larger buffer.
|
|
Here is a function which uses ‘regerror’, but always dynamically
|
allocates a buffer for the error message:
|
|
char *get_regerror (int errcode, regex_t *compiled)
|
{
|
size_t length = regerror (errcode, compiled, NULL, 0);
|
char *buffer = xmalloc (length);
|
(void) regerror (errcode, compiled, buffer, length);
|
return buffer;
|
}
|
|
|
File: libc.info, Node: Word Expansion, Prev: Regular Expressions, Up: Pattern Matching
|
|
10.4 Shell-Style Word Expansion
|
===============================
|
|
"Word expansion" means the process of splitting a string into "words"
|
and substituting for variables, commands, and wildcards just as the
|
shell does.
|
|
For example, when you write ‘ls -l foo.c’, this string is split into
|
three separate words—‘ls’, ‘-l’ and ‘foo.c’. This is the most basic
|
function of word expansion.
|
|
When you write ‘ls *.c’, this can become many words, because the word
|
‘*.c’ can be replaced with any number of file names. This is called
|
"wildcard expansion", and it is also a part of word expansion.
|
|
When you use ‘echo $PATH’ to print your path, you are taking
|
advantage of "variable substitution", which is also part of word
|
expansion.
|
|
Ordinary programs can perform word expansion just like the shell by
|
calling the library function ‘wordexp’.
|
|
* Menu:
|
|
* Expansion Stages:: What word expansion does to a string.
|
* Calling Wordexp:: How to call ‘wordexp’.
|
* Flags for Wordexp:: Options you can enable in ‘wordexp’.
|
* Wordexp Example:: A sample program that does word expansion.
|
* Tilde Expansion:: Details of how tilde expansion works.
|
* Variable Substitution:: Different types of variable substitution.
|
|
|
File: libc.info, Node: Expansion Stages, Next: Calling Wordexp, Up: Word Expansion
|
|
10.4.1 The Stages of Word Expansion
|
-----------------------------------
|
|
When word expansion is applied to a sequence of words, it performs the
|
following transformations in the order shown here:
|
|
1. "Tilde expansion": Replacement of ‘~foo’ with the name of the home
|
directory of ‘foo’.
|
|
2. Next, three different transformations are applied in the same step,
|
from left to right:
|
|
• "Variable substitution": Environment variables are substituted
|
for references such as ‘$foo’.
|
|
• "Command substitution": Constructs such as ‘`cat foo`’ and the
|
equivalent ‘$(cat foo)’ are replaced with the output from the
|
inner command.
|
|
• "Arithmetic expansion": Constructs such as ‘$(($x-1))’ are
|
replaced with the result of the arithmetic computation.
|
|
3. "Field splitting": subdivision of the text into "words".
|
|
4. "Wildcard expansion": The replacement of a construct such as ‘*.c’
|
with a list of ‘.c’ file names. Wildcard expansion applies to an
|
entire word at a time, and replaces that word with 0 or more file
|
names that are themselves words.
|
|
5. "Quote removal": The deletion of string-quotes, now that they have
|
done their job by inhibiting the above transformations when
|
appropriate.
|
|
For the details of these transformations, and how to write the
|
constructs that use them, see ‘The BASH Manual’ (to appear).
|
|
|
File: libc.info, Node: Calling Wordexp, Next: Flags for Wordexp, Prev: Expansion Stages, Up: Word Expansion
|
|
10.4.2 Calling ‘wordexp’
|
------------------------
|
|
All the functions, constants and data types for word expansion are
|
declared in the header file ‘wordexp.h’.
|
|
Word expansion produces a vector of words (strings). To return this
|
vector, ‘wordexp’ uses a special data type, ‘wordexp_t’, which is a
|
structure. You pass ‘wordexp’ the address of the structure, and it
|
fills in the structure’s fields to tell you about the results.
|
|
-- Data Type: wordexp_t
|
|
This data type holds a pointer to a word vector. More precisely,
|
it records both the address of the word vector and its size.
|
|
‘we_wordc’
|
The number of elements in the vector.
|
|
‘we_wordv’
|
The address of the vector. This field has type ‘char **’.
|
|
‘we_offs’
|
The offset of the first real element of the vector, from its
|
nominal address in the ‘we_wordv’ field. Unlike the other
|
fields, this is always an input to ‘wordexp’, rather than an
|
output from it.
|
|
If you use a nonzero offset, then that many elements at the
|
beginning of the vector are left empty. (The ‘wordexp’
|
function fills them with null pointers.)
|
|
The ‘we_offs’ field is meaningful only if you use the
|
‘WRDE_DOOFFS’ flag. Otherwise, the offset is always zero
|
regardless of what is in this field, and the first real
|
element comes at the beginning of the vector.
|
|
-- Function: int wordexp (const char *WORDS, wordexp_t
|
*WORD-VECTOR-PTR, int FLAGS)
|
|
Preliminary: | MT-Unsafe race:utent const:env env sig:ALRM timer
|
locale | AS-Unsafe dlopen plugin i18n heap corrupt lock | AC-Unsafe
|
corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
Perform word expansion on the string WORDS, putting the result in a
|
newly allocated vector, and store the size and address of this
|
vector into ‘*WORD-VECTOR-PTR’. The argument FLAGS is a
|
combination of bit flags; see *note Flags for Wordexp::, for
|
details of the flags.
|
|
You shouldn’t use any of the characters ‘|&;<>’ in the string WORDS
|
unless they are quoted; likewise for newline. If you use these
|
characters unquoted, you will get the ‘WRDE_BADCHAR’ error code.
|
Don’t use parentheses or braces unless they are quoted or part of a
|
word expansion construct. If you use quotation characters ‘'"`’,
|
they should come in pairs that balance.
|
|
The results of word expansion are a sequence of words. The
|
function ‘wordexp’ allocates a string for each resulting word, then
|
allocates a vector of type ‘char **’ to store the addresses of
|
these strings. The last element of the vector is a null pointer.
|
This vector is called the "word vector".
|
|
To return this vector, ‘wordexp’ stores both its address and its
|
length (number of elements, not counting the terminating null
|
pointer) into ‘*WORD-VECTOR-PTR’.
|
|
If ‘wordexp’ succeeds, it returns 0. Otherwise, it returns one of
|
these error codes:
|
|
‘WRDE_BADCHAR’
|
|
The input string WORDS contains an unquoted invalid character
|
such as ‘|’.
|
|
‘WRDE_BADVAL’
|
|
The input string refers to an undefined shell variable, and
|
you used the flag ‘WRDE_UNDEF’ to forbid such references.
|
|
‘WRDE_CMDSUB’
|
|
The input string uses command substitution, and you used the
|
flag ‘WRDE_NOCMD’ to forbid command substitution.
|
|
‘WRDE_NOSPACE’
|
|
It was impossible to allocate memory to hold the result. In
|
this case, ‘wordexp’ can store part of the results—as much as
|
it could allocate room for.
|
|
‘WRDE_SYNTAX’
|
|
There was a syntax error in the input string. For example, an
|
unmatched quoting character is a syntax error. This error
|
code is also used to signal division by zero and overflow in
|
arithmetic expansion.
|
|
-- Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe corrupt
|
mem | *Note POSIX Safety Concepts::.
|
|
Free the storage used for the word-strings and vector that
|
‘*WORD-VECTOR-PTR’ points to. This does not free the structure
|
‘*WORD-VECTOR-PTR’ itself—only the other data it points to.
|
|
|
File: libc.info, Node: Flags for Wordexp, Next: Wordexp Example, Prev: Calling Wordexp, Up: Word Expansion
|
|
10.4.3 Flags for Word Expansion
|
-------------------------------
|
|
This section describes the flags that you can specify in the FLAGS
|
argument to ‘wordexp’. Choose the flags you want, and combine them with
|
the C operator ‘|’.
|
|
‘WRDE_APPEND’
|
|
Append the words from this expansion to the vector of words
|
produced by previous calls to ‘wordexp’. This way you can
|
effectively expand several words as if they were concatenated with
|
spaces between them.
|
|
In order for appending to work, you must not modify the contents of
|
the word vector structure between calls to ‘wordexp’. And, if you
|
set ‘WRDE_DOOFFS’ in the first call to ‘wordexp’, you must also set
|
it when you append to the results.
|
|
‘WRDE_DOOFFS’
|
|
Leave blank slots at the beginning of the vector of words. The
|
‘we_offs’ field says how many slots to leave. The blank slots
|
contain null pointers.
|
|
‘WRDE_NOCMD’
|
|
Don’t do command substitution; if the input requests command
|
substitution, report an error.
|
|
‘WRDE_REUSE’
|
|
Reuse a word vector made by a previous call to ‘wordexp’. Instead
|
of allocating a new vector of words, this call to ‘wordexp’ will
|
use the vector that already exists (making it larger if necessary).
|
|
Note that the vector may move, so it is not safe to save an old
|
pointer and use it again after calling ‘wordexp’. You must fetch
|
‘we_pathv’ anew after each call.
|
|
‘WRDE_SHOWERR’
|
|
Do show any error messages printed by commands run by command
|
substitution. More precisely, allow these commands to inherit the
|
standard error output stream of the current process. By default,
|
‘wordexp’ gives these commands a standard error stream that
|
discards all output.
|
|
‘WRDE_UNDEF’
|
|
If the input refers to a shell variable that is not defined, report
|
an error.
|
|
|
File: libc.info, Node: Wordexp Example, Next: Tilde Expansion, Prev: Flags for Wordexp, Up: Word Expansion
|
|
10.4.4 ‘wordexp’ Example
|
------------------------
|
|
Here is an example of using ‘wordexp’ to expand several strings and use
|
the results to run a shell command. It also shows the use of
|
‘WRDE_APPEND’ to concatenate the expansions and of ‘wordfree’ to free
|
the space allocated by ‘wordexp’.
|
|
int
|
expand_and_execute (const char *program, const char **options)
|
{
|
wordexp_t result;
|
pid_t pid
|
int status, i;
|
|
/* Expand the string for the program to run. */
|
switch (wordexp (program, &result, 0))
|
{
|
case 0: /* Successful. */
|
break;
|
case WRDE_NOSPACE:
|
/* If the error was ‘WRDE_NOSPACE’,
|
then perhaps part of the result was allocated. */
|
wordfree (&result);
|
default: /* Some other error. */
|
return -1;
|
}
|
|
/* Expand the strings specified for the arguments. */
|
for (i = 0; options[i] != NULL; i++)
|
{
|
if (wordexp (options[i], &result, WRDE_APPEND))
|
{
|
wordfree (&result);
|
return -1;
|
}
|
}
|
|
pid = fork ();
|
if (pid == 0)
|
{
|
/* This is the child process. Execute the command. */
|
execv (result.we_wordv[0], result.we_wordv);
|
exit (EXIT_FAILURE);
|
}
|
else if (pid < 0)
|
/* The fork failed. Report failure. */
|
status = -1;
|
else
|
/* This is the parent process. Wait for the child to complete. */
|
if (waitpid (pid, &status, 0) != pid)
|
status = -1;
|
|
wordfree (&result);
|
return status;
|
}
|
|
|
File: libc.info, Node: Tilde Expansion, Next: Variable Substitution, Prev: Wordexp Example, Up: Word Expansion
|
|
10.4.5 Details of Tilde Expansion
|
---------------------------------
|
|
It’s a standard part of shell syntax that you can use ‘~’ at the
|
beginning of a file name to stand for your own home directory. You can
|
use ‘~USER’ to stand for USER’s home directory.
|
|
"Tilde expansion" is the process of converting these abbreviations to
|
the directory names that they stand for.
|
|
Tilde expansion applies to the ‘~’ plus all following characters up
|
to whitespace or a slash. It takes place only at the beginning of a
|
word, and only if none of the characters to be transformed is quoted in
|
any way.
|
|
Plain ‘~’ uses the value of the environment variable ‘HOME’ as the
|
proper home directory name. ‘~’ followed by a user name uses
|
‘getpwname’ to look up that user in the user database, and uses whatever
|
directory is recorded there. Thus, ‘~’ followed by your own name can
|
give different results from plain ‘~’, if the value of ‘HOME’ is not
|
really your home directory.
|
|
|
File: libc.info, Node: Variable Substitution, Prev: Tilde Expansion, Up: Word Expansion
|
|
10.4.6 Details of Variable Substitution
|
---------------------------------------
|
|
Part of ordinary shell syntax is the use of ‘$VARIABLE’ to substitute
|
the value of a shell variable into a command. This is called "variable
|
substitution", and it is one part of doing word expansion.
|
|
There are two basic ways you can write a variable reference for
|
substitution:
|
|
‘${VARIABLE}’
|
If you write braces around the variable name, then it is completely
|
unambiguous where the variable name ends. You can concatenate
|
additional letters onto the end of the variable value by writing
|
them immediately after the close brace. For example, ‘${foo}s’
|
expands into ‘tractors’.
|
|
‘$VARIABLE’
|
If you do not put braces around the variable name, then the
|
variable name consists of all the alphanumeric characters and
|
underscores that follow the ‘$’. The next punctuation character
|
ends the variable name. Thus, ‘$foo-bar’ refers to the variable
|
‘foo’ and expands into ‘tractor-bar’.
|
|
When you use braces, you can also use various constructs to modify
|
the value that is substituted, or test it in various ways.
|
|
‘${VARIABLE:-DEFAULT}’
|
Substitute the value of VARIABLE, but if that is empty or
|
undefined, use DEFAULT instead.
|
|
‘${VARIABLE:=DEFAULT}’
|
Substitute the value of VARIABLE, but if that is empty or
|
undefined, use DEFAULT instead and set the variable to DEFAULT.
|
|
‘${VARIABLE:?MESSAGE}’
|
If VARIABLE is defined and not empty, substitute its value.
|
|
Otherwise, print MESSAGE as an error message on the standard error
|
stream, and consider word expansion a failure.
|
|
‘${VARIABLE:+REPLACEMENT}’
|
Substitute REPLACEMENT, but only if VARIABLE is defined and
|
nonempty. Otherwise, substitute nothing for this construct.
|
|
‘${#VARIABLE}’
|
Substitute a numeral which expresses in base ten the number of
|
characters in the value of VARIABLE. ‘${#foo}’ stands for ‘7’,
|
because ‘tractor’ is seven characters.
|
|
These variants of variable substitution let you remove part of the
|
variable’s value before substituting it. The PREFIX and SUFFIX are not
|
mere strings; they are wildcard patterns, just like the patterns that
|
you use to match multiple file names. But in this context, they match
|
against parts of the variable value rather than against file names.
|
|
‘${VARIABLE%%SUFFIX}’
|
Substitute the value of VARIABLE, but first discard from that
|
variable any portion at the end that matches the pattern SUFFIX.
|
|
If there is more than one alternative for how to match against
|
SUFFIX, this construct uses the longest possible match.
|
|
Thus, ‘${foo%%r*}’ substitutes ‘t’, because the largest match for
|
‘r*’ at the end of ‘tractor’ is ‘ractor’.
|
|
‘${VARIABLE%SUFFIX}’
|
Substitute the value of VARIABLE, but first discard from that
|
variable any portion at the end that matches the pattern SUFFIX.
|
|
If there is more than one alternative for how to match against
|
SUFFIX, this construct uses the shortest possible alternative.
|
|
Thus, ‘${foo%r*}’ substitutes ‘tracto’, because the shortest match
|
for ‘r*’ at the end of ‘tractor’ is just ‘r’.
|
|
‘${VARIABLE##PREFIX}’
|
Substitute the value of VARIABLE, but first discard from that
|
variable any portion at the beginning that matches the pattern
|
PREFIX.
|
|
If there is more than one alternative for how to match against
|
PREFIX, this construct uses the longest possible match.
|
|
Thus, ‘${foo##*t}’ substitutes ‘or’, because the largest match for
|
‘*t’ at the beginning of ‘tractor’ is ‘tract’.
|
|
‘${VARIABLE#PREFIX}’
|
Substitute the value of VARIABLE, but first discard from that
|
variable any portion at the beginning that matches the pattern
|
PREFIX.
|
|
If there is more than one alternative for how to match against
|
PREFIX, this construct uses the shortest possible alternative.
|
|
Thus, ‘${foo#*t}’ substitutes ‘ractor’, because the shortest match
|
for ‘*t’ at the beginning of ‘tractor’ is just ‘t’.
|
|
|
File: libc.info, Node: I/O Overview, Next: I/O on Streams, Prev: Pattern Matching, Up: Top
|
|
11 Input/Output Overview
|
************************
|
|
Most programs need to do either input (reading data) or output (writing
|
data), or most frequently both, in order to do anything useful. The GNU
|
C Library provides such a large selection of input and output functions
|
that the hardest part is often deciding which function is most
|
appropriate!
|
|
This chapter introduces concepts and terminology relating to input
|
and output. Other chapters relating to the GNU I/O facilities are:
|
|
• *note I/O on Streams::, which covers the high-level functions that
|
operate on streams, including formatted input and output.
|
|
• *note Low-Level I/O::, which covers the basic I/O and control
|
functions on file descriptors.
|
|
• *note File System Interface::, which covers functions for operating
|
on directories and for manipulating file attributes such as access
|
modes and ownership.
|
|
• *note Pipes and FIFOs::, which includes information on the basic
|
interprocess communication facilities.
|
|
• *note Sockets::, which covers a more complicated interprocess
|
communication facility with support for networking.
|
|
• *note Low-Level Terminal Interface::, which covers functions for
|
changing how input and output to terminals or other serial devices
|
are processed.
|
|
* Menu:
|
|
* I/O Concepts:: Some basic information and terminology.
|
* File Names:: How to refer to a file.
|
|
|
File: libc.info, Node: I/O Concepts, Next: File Names, Up: I/O Overview
|
|
11.1 Input/Output Concepts
|
==========================
|
|
Before you can read or write the contents of a file, you must establish
|
a connection or communications channel to the file. This process is
|
called "opening" the file. You can open a file for reading, writing, or
|
both.
|
|
The connection to an open file is represented either as a stream or
|
as a file descriptor. You pass this as an argument to the functions
|
that do the actual read or write operations, to tell them which file to
|
operate on. Certain functions expect streams, and others are designed
|
to operate on file descriptors.
|
|
When you have finished reading to or writing from the file, you can
|
terminate the connection by "closing" the file. Once you have closed a
|
stream or file descriptor, you cannot do any more input or output
|
operations on it.
|
|
* Menu:
|
|
* Streams and File Descriptors:: The GNU C Library provides two ways
|
to access the contents of files.
|
* File Position:: The number of bytes from the
|
beginning of the file.
|
|
|
File: libc.info, Node: Streams and File Descriptors, Next: File Position, Up: I/O Concepts
|
|
11.1.1 Streams and File Descriptors
|
-----------------------------------
|
|
When you want to do input or output to a file, you have a choice of two
|
basic mechanisms for representing the connection between your program
|
and the file: file descriptors and streams. File descriptors are
|
represented as objects of type ‘int’, while streams are represented as
|
‘FILE *’ objects.
|
|
File descriptors provide a primitive, low-level interface to input
|
and output operations. Both file descriptors and streams can represent
|
a connection to a device (such as a terminal), or a pipe or socket for
|
communicating with another process, as well as a normal file. But, if
|
you want to do control operations that are specific to a particular kind
|
of device, you must use a file descriptor; there are no facilities to
|
use streams in this way. You must also use file descriptors if your
|
program needs to do input or output in special modes, such as
|
nonblocking (or polled) input (*note File Status Flags::).
|
|
Streams provide a higher-level interface, layered on top of the
|
primitive file descriptor facilities. The stream interface treats all
|
kinds of files pretty much alike—the sole exception being the three
|
styles of buffering that you can choose (*note Stream Buffering::).
|
|
The main advantage of using the stream interface is that the set of
|
functions for performing actual input and output operations (as opposed
|
to control operations) on streams is much richer and more powerful than
|
the corresponding facilities for file descriptors. The file descriptor
|
interface provides only simple functions for transferring blocks of
|
characters, but the stream interface also provides powerful formatted
|
input and output functions (‘printf’ and ‘scanf’) as well as functions
|
for character- and line-oriented input and output.
|
|
Since streams are implemented in terms of file descriptors, you can
|
extract the file descriptor from a stream and perform low-level
|
operations directly on the file descriptor. You can also initially open
|
a connection as a file descriptor and then make a stream associated with
|
that file descriptor.
|
|
In general, you should stick with using streams rather than file
|
descriptors, unless there is some specific operation you want to do that
|
can only be done on a file descriptor. If you are a beginning
|
programmer and aren’t sure what functions to use, we suggest that you
|
concentrate on the formatted input functions (*note Formatted Input::)
|
and formatted output functions (*note Formatted Output::).
|
|
If you are concerned about portability of your programs to systems
|
other than GNU, you should also be aware that file descriptors are not
|
as portable as streams. You can expect any system running ISO C to
|
support streams, but non-GNU systems may not support file descriptors at
|
all, or may only implement a subset of the GNU functions that operate on
|
file descriptors. Most of the file descriptor functions in the GNU C
|
Library are included in the POSIX.1 standard, however.
|
|
|
File: libc.info, Node: File Position, Prev: Streams and File Descriptors, Up: I/O Concepts
|
|
11.1.2 File Position
|
--------------------
|
|
One of the attributes of an open file is its "file position" that keeps
|
track of where in the file the next character is to be read or written.
|
On GNU systems, and all POSIX.1 systems, the file position is simply an
|
integer representing the number of bytes from the beginning of the file.
|
|
The file position is normally set to the beginning of the file when
|
it is opened, and each time a character is read or written, the file
|
position is incremented. In other words, access to the file is normally
|
"sequential".
|
|
Ordinary files permit read or write operations at any position within
|
the file. Some other kinds of files may also permit this. Files which
|
do permit this are sometimes referred to as "random-access" files. You
|
can change the file position using the ‘fseek’ function on a stream
|
(*note File Positioning::) or the ‘lseek’ function on a file descriptor
|
(*note I/O Primitives::). If you try to change the file position on a
|
file that doesn’t support random access, you get the ‘ESPIPE’ error.
|
|
Streams and descriptors that are opened for "append access" are
|
treated specially for output: output to such files is _always_ appended
|
sequentially to the _end_ of the file, regardless of the file position.
|
However, the file position is still used to control where in the file
|
reading is done.
|
|
If you think about it, you’ll realize that several programs can read
|
a given file at the same time. In order for each program to be able to
|
read the file at its own pace, each program must have its own file
|
pointer, which is not affected by anything the other programs do.
|
|
In fact, each opening of a file creates a separate file position.
|
Thus, if you open a file twice even in the same program, you get two
|
streams or descriptors with independent file positions.
|
|
By contrast, if you open a descriptor and then duplicate it to get
|
another descriptor, these two descriptors share the same file position:
|
changing the file position of one descriptor will affect the other.
|
|
|
File: libc.info, Node: File Names, Prev: I/O Concepts, Up: I/O Overview
|
|
11.2 File Names
|
===============
|
|
In order to open a connection to a file, or to perform other operations
|
such as deleting a file, you need some way to refer to the file. Nearly
|
all files have names that are strings—even files which are actually
|
devices such as tape drives or terminals. These strings are called
|
"file names". You specify the file name to say which file you want to
|
open or operate on.
|
|
This section describes the conventions for file names and how the
|
operating system works with them.
|
|
* Menu:
|
|
* Directories:: Directories contain entries for files.
|
* File Name Resolution:: A file name specifies how to look up a file.
|
* File Name Errors:: Error conditions relating to file names.
|
* File Name Portability:: File name portability and syntax issues.
|
|
|
File: libc.info, Node: Directories, Next: File Name Resolution, Up: File Names
|
|
11.2.1 Directories
|
------------------
|
|
In order to understand the syntax of file names, you need to understand
|
how the file system is organized into a hierarchy of directories.
|
|
A "directory" is a file that contains information to associate other
|
files with names; these associations are called "links" or "directory
|
entries". Sometimes, people speak of “files in a directory”, but in
|
reality, a directory only contains pointers to files, not the files
|
themselves.
|
|
The name of a file contained in a directory entry is called a "file
|
name component". In general, a file name consists of a sequence of one
|
or more such components, separated by the slash character (‘/’). A file
|
name which is just one component names a file with respect to its
|
directory. A file name with multiple components names a directory, and
|
then a file in that directory, and so on.
|
|
Some other documents, such as the POSIX standard, use the term
|
"pathname" for what we call a file name, and either "filename" or
|
"pathname component" for what this manual calls a file name component.
|
We don’t use this terminology because a “path” is something completely
|
different (a list of directories to search), and we think that
|
“pathname” used for something else will confuse users. We always use
|
“file name” and “file name component” (or sometimes just “component”,
|
where the context is obvious) in GNU documentation. Some macros use the
|
POSIX terminology in their names, such as ‘PATH_MAX’. These macros are
|
defined by the POSIX standard, so we cannot change their names.
|
|
You can find more detailed information about operations on
|
directories in *note File System Interface::.
|
|
|
File: libc.info, Node: File Name Resolution, Next: File Name Errors, Prev: Directories, Up: File Names
|
|
11.2.2 File Name Resolution
|
---------------------------
|
|
A file name consists of file name components separated by slash (‘/’)
|
characters. On the systems that the GNU C Library supports, multiple
|
successive ‘/’ characters are equivalent to a single ‘/’ character.
|
|
The process of determining what file a file name refers to is called
|
"file name resolution". This is performed by examining the components
|
that make up a file name in left-to-right order, and locating each
|
successive component in the directory named by the previous component.
|
Of course, each of the files that are referenced as directories must
|
actually exist, be directories instead of regular files, and have the
|
appropriate permissions to be accessible by the process; otherwise the
|
file name resolution fails.
|
|
If a file name begins with a ‘/’, the first component in the file
|
name is located in the "root directory" of the process (usually all
|
processes on the system have the same root directory). Such a file name
|
is called an "absolute file name".
|
|
Otherwise, the first component in the file name is located in the
|
current working directory (*note Working Directory::). This kind of
|
file name is called a "relative file name".
|
|
The file name components ‘.’ (“dot”) and ‘..’ (“dot-dot”) have
|
special meanings. Every directory has entries for these file name
|
components. The file name component ‘.’ refers to the directory itself,
|
while the file name component ‘..’ refers to its "parent directory" (the
|
directory that contains the link for the directory in question). As a
|
special case, ‘..’ in the root directory refers to the root directory
|
itself, since it has no parent; thus ‘/..’ is the same as ‘/’.
|
|
Here are some examples of file names:
|
|
‘/a’
|
The file named ‘a’, in the root directory.
|
|
‘/a/b’
|
The file named ‘b’, in the directory named ‘a’ in the root
|
directory.
|
|
‘a’
|
The file named ‘a’, in the current working directory.
|
|
‘/a/./b’
|
This is the same as ‘/a/b’.
|
|
‘./a’
|
The file named ‘a’, in the current working directory.
|
|
‘../a’
|
The file named ‘a’, in the parent directory of the current working
|
directory.
|
|
A file name that names a directory may optionally end in a ‘/’. You
|
can specify a file name of ‘/’ to refer to the root directory, but the
|
empty string is not a meaningful file name. If you want to refer to the
|
current working directory, use a file name of ‘.’ or ‘./’.
|
|
Unlike some other operating systems, GNU systems don’t have any
|
built-in support for file types (or extensions) or file versions as part
|
of its file name syntax. Many programs and utilities use conventions
|
for file names—for example, files containing C source code usually have
|
names suffixed with ‘.c’—but there is nothing in the file system itself
|
that enforces this kind of convention.
|
|
|
File: libc.info, Node: File Name Errors, Next: File Name Portability, Prev: File Name Resolution, Up: File Names
|
|
11.2.3 File Name Errors
|
-----------------------
|
|
Functions that accept file name arguments usually detect these ‘errno’
|
error conditions relating to the file name syntax or trouble finding the
|
named file. These errors are referred to throughout this manual as the
|
"usual file name errors".
|
|
‘EACCES’
|
The process does not have search permission for a directory
|
component of the file name.
|
|
‘ENAMETOOLONG’
|
This error is used when either the total length of a file name is
|
greater than ‘PATH_MAX’, or when an individual file name component
|
has a length greater than ‘NAME_MAX’. *Note Limits for Files::.
|
|
On GNU/Hurd systems, there is no imposed limit on overall file name
|
length, but some file systems may place limits on the length of a
|
component.
|
|
‘ENOENT’
|
This error is reported when a file referenced as a directory
|
component in the file name doesn’t exist, or when a component is a
|
symbolic link whose target file does not exist. *Note Symbolic
|
Links::.
|
|
‘ENOTDIR’
|
A file that is referenced as a directory component in the file name
|
exists, but it isn’t a directory.
|
|
‘ELOOP’
|
Too many symbolic links were resolved while trying to look up the
|
file name. The system has an arbitrary limit on the number of
|
symbolic links that may be resolved in looking up a single file
|
name, as a primitive way to detect loops. *Note Symbolic Links::.
|
|
|
File: libc.info, Node: File Name Portability, Prev: File Name Errors, Up: File Names
|
|
11.2.4 Portability of File Names
|
--------------------------------
|
|
The rules for the syntax of file names discussed in *note File Names::,
|
are the rules normally used by GNU systems and by other POSIX systems.
|
However, other operating systems may use other conventions.
|
|
There are two reasons why it can be important for you to be aware of
|
file name portability issues:
|
|
• If your program makes assumptions about file name syntax, or
|
contains embedded literal file name strings, it is more difficult
|
to get it to run under other operating systems that use different
|
syntax conventions.
|
|
• Even if you are not concerned about running your program on
|
machines that run other operating systems, it may still be possible
|
to access files that use different naming conventions. For
|
example, you may be able to access file systems on another computer
|
running a different operating system over a network, or read and
|
write disks in formats used by other operating systems.
|
|
The ISO C standard says very little about file name syntax, only that
|
file names are strings. In addition to varying restrictions on the
|
length of file names and what characters can validly appear in a file
|
name, different operating systems use different conventions and syntax
|
for concepts such as structured directories and file types or
|
extensions. Some concepts such as file versions might be supported in
|
some operating systems and not by others.
|
|
The POSIX.1 standard allows implementations to put additional
|
restrictions on file name syntax, concerning what characters are
|
permitted in file names and on the length of file name and file name
|
component strings. However, on GNU systems, any character except the
|
null character is permitted in a file name string, and on GNU/Hurd
|
systems there are no limits on the length of file name strings.
|
|
|
File: libc.info, Node: I/O on Streams, Next: Low-Level I/O, Prev: I/O Overview, Up: Top
|
|
12 Input/Output on Streams
|
**************************
|
|
This chapter describes the functions for creating streams and performing
|
input and output operations on them. As discussed in *note I/O
|
Overview::, a stream is a fairly abstract, high-level concept
|
representing a communications channel to a file, device, or process.
|
|
* Menu:
|
|
* Streams:: About the data type representing a stream.
|
* Standard Streams:: Streams to the standard input and output
|
devices are created for you.
|
* Opening Streams:: How to create a stream to talk to a file.
|
* Closing Streams:: Close a stream when you are finished with it.
|
* Streams and Threads:: Issues with streams in threaded programs.
|
* Streams and I18N:: Streams in internationalized applications.
|
* Simple Output:: Unformatted output by characters and lines.
|
* Character Input:: Unformatted input by characters and words.
|
* Line Input:: Reading a line or a record from a stream.
|
* Unreading:: Peeking ahead/pushing back input just read.
|
* Block Input/Output:: Input and output operations on blocks of data.
|
* Formatted Output:: ‘printf’ and related functions.
|
* Customizing Printf:: You can define new conversion specifiers for
|
‘printf’ and friends.
|
* Formatted Input:: ‘scanf’ and related functions.
|
* EOF and Errors:: How you can tell if an I/O error happens.
|
* Error Recovery:: What you can do about errors.
|
* Binary Streams:: Some systems distinguish between text files
|
and binary files.
|
* File Positioning:: About random-access streams.
|
* Portable Positioning:: Random access on peculiar ISO C systems.
|
* Stream Buffering:: How to control buffering of streams.
|
* Other Kinds of Streams:: Streams that do not necessarily correspond
|
to an open file.
|
* Formatted Messages:: Print strictly formatted messages.
|
|
|
File: libc.info, Node: Streams, Next: Standard Streams, Up: I/O on Streams
|
|
12.1 Streams
|
============
|
|
For historical reasons, the type of the C data structure that represents
|
a stream is called ‘FILE’ rather than “stream”. Since most of the
|
library functions deal with objects of type ‘FILE *’, sometimes the term
|
"file pointer" is also used to mean “stream”. This leads to unfortunate
|
confusion over terminology in many books on C. This manual, however, is
|
careful to use the terms “file” and “stream” only in the technical
|
sense.
|
|
The ‘FILE’ type is declared in the header file ‘stdio.h’.
|
|
-- Data Type: FILE
|
|
This is the data type used to represent stream objects. A ‘FILE’
|
object holds all of the internal state information about the
|
connection to the associated file, including such things as the
|
file position indicator and buffering information. Each stream
|
also has error and end-of-file status indicators that can be tested
|
with the ‘ferror’ and ‘feof’ functions; see *note EOF and Errors::.
|
|
‘FILE’ objects are allocated and managed internally by the
|
input/output library functions. Don’t try to create your own objects of
|
type ‘FILE’; let the library do it. Your programs should deal only with
|
pointers to these objects (that is, ‘FILE *’ values) rather than the
|
objects themselves.
|
|
|
File: libc.info, Node: Standard Streams, Next: Opening Streams, Prev: Streams, Up: I/O on Streams
|
|
12.2 Standard Streams
|
=====================
|
|
When the ‘main’ function of your program is invoked, it already has
|
three predefined streams open and available for use. These represent
|
the “standard” input and output channels that have been established for
|
the process.
|
|
These streams are declared in the header file ‘stdio.h’.
|
|
-- Variable: FILE * stdin
|
|
The "standard input" stream, which is the normal source of input
|
for the program.
|
|
-- Variable: FILE * stdout
|
|
The "standard output" stream, which is used for normal output from
|
the program.
|
|
-- Variable: FILE * stderr
|
|
The "standard error" stream, which is used for error messages and
|
diagnostics issued by the program.
|
|
On GNU systems, you can specify what files or processes correspond to
|
these streams using the pipe and redirection facilities provided by the
|
shell. (The primitives shells use to implement these facilities are
|
described in *note File System Interface::.) Most other operating
|
systems provide similar mechanisms, but the details of how to use them
|
can vary.
|
|
In the GNU C Library, ‘stdin’, ‘stdout’, and ‘stderr’ are normal
|
variables which you can set just like any others. For example, to
|
redirect the standard output to a file, you could do:
|
|
fclose (stdout);
|
stdout = fopen ("standard-output-file", "w");
|
|
Note however, that in other systems ‘stdin’, ‘stdout’, and ‘stderr’
|
are macros that you cannot assign to in the normal way. But you can use
|
‘freopen’ to get the effect of closing one and reopening it. *Note
|
Opening Streams::.
|
|
The three streams ‘stdin’, ‘stdout’, and ‘stderr’ are not unoriented
|
at program start (*note Streams and I18N::).
|
|
|
File: libc.info, Node: Opening Streams, Next: Closing Streams, Prev: Standard Streams, Up: I/O on Streams
|
|
12.3 Opening Streams
|
====================
|
|
Opening a file with the ‘fopen’ function creates a new stream and
|
establishes a connection between the stream and a file. This may
|
involve creating a new file.
|
|
Everything described in this section is declared in the header file
|
‘stdio.h’.
|
|
-- Function: FILE * fopen (const char *FILENAME, const char *OPENTYPE)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
|
lock | *Note POSIX Safety Concepts::.
|
|
The ‘fopen’ function opens a stream for I/O to the file FILENAME,
|
and returns a pointer to the stream.
|
|
The OPENTYPE argument is a string that controls how the file is
|
opened and specifies attributes of the resulting stream. It must
|
begin with one of the following sequences of characters:
|
|
‘r’
|
Open an existing file for reading only.
|
|
‘w’
|
Open the file for writing only. If the file already exists,
|
it is truncated to zero length. Otherwise a new file is
|
created.
|
|
‘a’
|
Open a file for append access; that is, writing at the end of
|
file only. If the file already exists, its initial contents
|
are unchanged and output to the stream is appended to the end
|
of the file. Otherwise, a new, empty file is created.
|
|
‘r+’
|
Open an existing file for both reading and writing. The
|
initial contents of the file are unchanged and the initial
|
file position is at the beginning of the file.
|
|
‘w+’
|
Open a file for both reading and writing. If the file already
|
exists, it is truncated to zero length. Otherwise, a new file
|
is created.
|
|
‘a+’
|
Open or create file for both reading and appending. If the
|
file exists, its initial contents are unchanged. Otherwise, a
|
new file is created. The initial file position for reading is
|
at the beginning of the file, but output is always appended to
|
the end of the file.
|
|
As you can see, ‘+’ requests a stream that can do both input and
|
output. When using such a stream, you must call ‘fflush’ (*note
|
Stream Buffering::) or a file positioning function such as ‘fseek’
|
(*note File Positioning::) when switching from reading to writing
|
or vice versa. Otherwise, internal buffers might not be emptied
|
properly.
|
|
Additional characters may appear after these to specify flags for
|
the call. Always put the mode (‘r’, ‘w+’, etc.) first; that is
|
the only part you are guaranteed will be understood by all systems.
|
|
The GNU C Library defines additional characters for use in
|
OPENTYPE:
|
|
‘c’
|
The file is opened with cancellation in the I/O functions
|
disabled.
|
|
‘e’
|
The underlying file descriptor will be closed if you use any
|
of the ‘exec…’ functions (*note Executing a File::). (This is
|
equivalent to having set ‘FD_CLOEXEC’ on that descriptor.
|
*Note Descriptor Flags::.)
|
|
‘m’
|
The file is opened and accessed using ‘mmap’. This is only
|
supported with files opened for reading.
|
|
‘x’
|
Insist on creating a new file—if a file FILENAME already
|
exists, ‘fopen’ fails rather than opening it. If you use ‘x’
|
you are guaranteed that you will not clobber an existing file.
|
This is equivalent to the ‘O_EXCL’ option to the ‘open’
|
function (*note Opening and Closing Files::).
|
|
The ‘x’ modifier is part of ISO C11, which says the file is
|
created with exclusive access; in the GNU C Library this means
|
the equivalent of ‘O_EXCL’.
|
|
The character ‘b’ in OPENTYPE has a standard meaning; it requests a
|
binary stream rather than a text stream. But this makes no
|
difference in POSIX systems (including GNU systems). If both ‘+’
|
and ‘b’ are specified, they can appear in either order. *Note
|
Binary Streams::.
|
|
If the OPENTYPE string contains the sequence ‘,ccs=STRING’ then
|
STRING is taken as the name of a coded character set and ‘fopen’
|
will mark the stream as wide-oriented with appropriate conversion
|
functions in place to convert from and to the character set STRING.
|
Any other stream is opened initially unoriented and the orientation
|
is decided with the first file operation. If the first operation
|
is a wide character operation, the stream is not only marked as
|
wide-oriented, also the conversion functions to convert to the
|
coded character set used for the current locale are loaded. This
|
will not change anymore from this point on even if the locale
|
selected for the ‘LC_CTYPE’ category is changed.
|
|
Any other characters in OPENTYPE are simply ignored. They may be
|
meaningful in other systems.
|
|
If the open fails, ‘fopen’ returns a null pointer.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32 bit machine this function is in fact ‘fopen64’ since the LFS
|
interface replaces transparently the old interface.
|
|
You can have multiple streams (or file descriptors) pointing to the
|
same file open at the same time. If you do only input, this works
|
straightforwardly, but you must be careful if any output streams are
|
included. *Note Stream/Descriptor Precautions::. This is equally true
|
whether the streams are in one program (not usual) or in several
|
programs (which can easily happen). It may be advantageous to use the
|
file locking facilities to avoid simultaneous access. *Note File
|
Locks::.
|
|
-- Function: FILE * fopen64 (const char *FILENAME, const char
|
*OPENTYPE)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
|
lock | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘fopen’ but the stream it returns a
|
pointer for is opened using ‘open64’. Therefore this stream can be
|
used even on files larger than 2^31 bytes on 32 bit machines.
|
|
Please note that the return type is still ‘FILE *’. There is no
|
special ‘FILE’ type for the LFS interface.
|
|
If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
|
bits machine this function is available under the name ‘fopen’ and
|
so transparently replaces the old interface.
|
|
-- Macro: int FOPEN_MAX
|
|
The value of this macro is an integer constant expression that
|
represents the minimum number of streams that the implementation
|
guarantees can be open simultaneously. You might be able to open
|
more than this many streams, but that is not guaranteed. The value
|
of this constant is at least eight, which includes the three
|
standard streams ‘stdin’, ‘stdout’, and ‘stderr’. In POSIX.1
|
systems this value is determined by the ‘OPEN_MAX’ parameter; *note
|
General Limits::. In BSD and GNU, it is controlled by the
|
‘RLIMIT_NOFILE’ resource limit; *note Limits on Resources::.
|
|
-- Function: FILE * freopen (const char *FILENAME, const char
|
*OPENTYPE, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt fd |
|
*Note POSIX Safety Concepts::.
|
|
This function is like a combination of ‘fclose’ and ‘fopen’. It
|
first closes the stream referred to by STREAM, ignoring any errors
|
that are detected in the process. (Because errors are ignored, you
|
should not use ‘freopen’ on an output stream if you have actually
|
done any output using the stream.) Then the file named by FILENAME
|
is opened with mode OPENTYPE as for ‘fopen’, and associated with
|
the same stream object STREAM.
|
|
If the operation fails, a null pointer is returned; otherwise,
|
‘freopen’ returns STREAM. On Linux, ‘freopen’ may also fail and
|
set ‘errno’ to ‘EBUSY’ when the kernel structure for the old file
|
descriptor was not initialized completely before ‘freopen’ was
|
called. This can only happen in multi-threaded programs, when two
|
threads race to allocate the same file descriptor number. To avoid
|
the possibility of this race, do not use ‘close’ to close the
|
underlying file descriptor for a ‘FILE’; either use ‘freopen’ while
|
the file is still open, or use ‘open’ and then ‘dup2’ to install
|
the new file descriptor.
|
|
‘freopen’ has traditionally been used to connect a standard stream
|
such as ‘stdin’ with a file of your own choice. This is useful in
|
programs in which use of a standard stream for certain purposes is
|
hard-coded. In the GNU C Library, you can simply close the
|
standard streams and open new ones with ‘fopen’. But other systems
|
lack this ability, so using ‘freopen’ is more portable.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32 bit machine this function is in fact ‘freopen64’ since the LFS
|
interface replaces transparently the old interface.
|
|
-- Function: FILE * freopen64 (const char *FILENAME, const char
|
*OPENTYPE, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt fd |
|
*Note POSIX Safety Concepts::.
|
|
This function is similar to ‘freopen’. The only difference is that
|
on 32 bit machine the stream returned is able to read beyond the
|
2^31 bytes limits imposed by the normal interface. It should be
|
noted that the stream pointed to by STREAM need not be opened using
|
‘fopen64’ or ‘freopen64’ since its mode is not important for this
|
function.
|
|
If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
|
bits machine this function is available under the name ‘freopen’
|
and so transparently replaces the old interface.
|
|
In some situations it is useful to know whether a given stream is
|
available for reading or writing. This information is normally not
|
available and would have to be remembered separately. Solaris
|
introduced a few functions to get this information from the stream
|
descriptor and these functions are also available in the GNU C Library.
|
|
-- Function: int __freadable (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘__freadable’ function determines whether the stream STREAM was
|
opened to allow reading. In this case the return value is nonzero.
|
For write-only streams the function returns zero.
|
|
This function is declared in ‘stdio_ext.h’.
|
|
-- Function: int __fwritable (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘__fwritable’ function determines whether the stream STREAM was
|
opened to allow writing. In this case the return value is nonzero.
|
For read-only streams the function returns zero.
|
|
This function is declared in ‘stdio_ext.h’.
|
|
For slightly different kinds of problems there are two more
|
functions. They provide even finer-grained information.
|
|
-- Function: int __freading (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘__freading’ function determines whether the stream STREAM was
|
last read from or whether it is opened read-only. In this case the
|
return value is nonzero, otherwise it is zero. Determining whether
|
a stream opened for reading and writing was last used for writing
|
allows to draw conclusions about the content about the buffer,
|
among other things.
|
|
This function is declared in ‘stdio_ext.h’.
|
|
-- Function: int __fwriting (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘__fwriting’ function determines whether the stream STREAM was
|
last written to or whether it is opened write-only. In this case
|
the return value is nonzero, otherwise it is zero.
|
|
This function is declared in ‘stdio_ext.h’.
|
|
|
File: libc.info, Node: Closing Streams, Next: Streams and Threads, Prev: Opening Streams, Up: I/O on Streams
|
|
12.4 Closing Streams
|
====================
|
|
When a stream is closed with ‘fclose’, the connection between the stream
|
and the file is canceled. After you have closed a stream, you cannot
|
perform any additional operations on it.
|
|
-- Function: int fclose (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem
|
fd | *Note POSIX Safety Concepts::.
|
|
This function causes STREAM to be closed and the connection to the
|
corresponding file to be broken. Any buffered output is written
|
and any buffered input is discarded. The ‘fclose’ function returns
|
a value of ‘0’ if the file was closed successfully, and ‘EOF’ if an
|
error was detected.
|
|
It is important to check for errors when you call ‘fclose’ to close
|
an output stream, because real, everyday errors can be detected at
|
this time. For example, when ‘fclose’ writes the remaining
|
buffered output, it might get an error because the disk is full.
|
Even if you know the buffer is empty, errors can still occur when
|
closing a file if you are using NFS.
|
|
The function ‘fclose’ is declared in ‘stdio.h’.
|
|
To close all streams currently available the GNU C Library provides
|
another function.
|
|
-- Function: int fcloseall (void)
|
|
Preliminary: | MT-Unsafe race:streams | AS-Unsafe | AC-Safe | *Note
|
POSIX Safety Concepts::.
|
|
This function causes all open streams of the process to be closed
|
and the connections to corresponding files to be broken. All
|
buffered data is written and any buffered input is discarded. The
|
‘fcloseall’ function returns a value of ‘0’ if all the files were
|
closed successfully, and ‘EOF’ if an error was detected.
|
|
This function should be used only in special situations, e.g., when
|
an error occurred and the program must be aborted. Normally each
|
single stream should be closed separately so that problems with
|
individual streams can be identified. It is also problematic since
|
the standard streams (*note Standard Streams::) will also be
|
closed.
|
|
The function ‘fcloseall’ is declared in ‘stdio.h’.
|
|
If the ‘main’ function to your program returns, or if you call the
|
‘exit’ function (*note Normal Termination::), all open streams are
|
automatically closed properly. If your program terminates in any other
|
manner, such as by calling the ‘abort’ function (*note Aborting a
|
Program::) or from a fatal signal (*note Signal Handling::), open
|
streams might not be closed properly. Buffered output might not be
|
flushed and files may be incomplete. For more information on buffering
|
of streams, see *note Stream Buffering::.
|
|
|
File: libc.info, Node: Streams and Threads, Next: Streams and I18N, Prev: Closing Streams, Up: I/O on Streams
|
|
12.5 Streams and Threads
|
========================
|
|
Streams can be used in multi-threaded applications in the same way they
|
are used in single-threaded applications. But the programmer must be
|
aware of the possible complications. It is important to know about
|
these also if the program one writes never use threads since the design
|
and implementation of many stream functions are heavily influenced by
|
the requirements added by multi-threaded programming.
|
|
The POSIX standard requires that by default the stream operations are
|
atomic. I.e., issuing two stream operations for the same stream in two
|
threads at the same time will cause the operations to be executed as if
|
they were issued sequentially. The buffer operations performed while
|
reading or writing are protected from other uses of the same stream. To
|
do this each stream has an internal lock object which has to be
|
(implicitly) acquired before any work can be done.
|
|
But there are situations where this is not enough and there are also
|
situations where this is not wanted. The implicit locking is not enough
|
if the program requires more than one stream function call to happen
|
atomically. One example would be if an output line a program wants to
|
generate is created by several function calls. The functions by
|
themselves would ensure only atomicity of their own operation, but not
|
atomicity over all the function calls. For this it is necessary to
|
perform the stream locking in the application code.
|
|
-- Function: void flockfile (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
|
Safety Concepts::.
|
|
The ‘flockfile’ function acquires the internal locking object
|
associated with the stream STREAM. This ensures that no other
|
thread can explicitly through ‘flockfile’/‘ftrylockfile’ or
|
implicitly through the call of a stream function lock the stream.
|
The thread will block until the lock is acquired. An explicit call
|
to ‘funlockfile’ has to be used to release the lock.
|
|
-- Function: int ftrylockfile (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
|
Safety Concepts::.
|
|
The ‘ftrylockfile’ function tries to acquire the internal locking
|
object associated with the stream STREAM just like ‘flockfile’.
|
But unlike ‘flockfile’ this function does not block if the lock is
|
not available. ‘ftrylockfile’ returns zero if the lock was
|
successfully acquired. Otherwise the stream is locked by another
|
thread.
|
|
-- Function: void funlockfile (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
|
Safety Concepts::.
|
|
The ‘funlockfile’ function releases the internal locking object of
|
the stream STREAM. The stream must have been locked before by a
|
call to ‘flockfile’ or a successful call of ‘ftrylockfile’. The
|
implicit locking performed by the stream operations do not count.
|
The ‘funlockfile’ function does not return an error status and the
|
behavior of a call for a stream which is not locked by the current
|
thread is undefined.
|
|
The following example shows how the functions above can be used to
|
generate an output line atomically even in multi-threaded applications
|
(yes, the same job could be done with one ‘fprintf’ call but it is
|
sometimes not possible):
|
|
FILE *fp;
|
{
|
…
|
flockfile (fp);
|
fputs ("This is test number ", fp);
|
fprintf (fp, "%d\n", test);
|
funlockfile (fp)
|
}
|
|
Without the explicit locking it would be possible for another thread
|
to use the stream FP after the ‘fputs’ call returns and before ‘fprintf’
|
was called with the result that the number does not follow the word
|
‘number’.
|
|
From this description it might already be clear that the locking
|
objects in streams are no simple mutexes. Since locking the same stream
|
twice in the same thread is allowed the locking objects must be
|
equivalent to recursive mutexes. These mutexes keep track of the owner
|
and the number of times the lock is acquired. The same number of
|
‘funlockfile’ calls by the same threads is necessary to unlock the
|
stream completely. For instance:
|
|
void
|
foo (FILE *fp)
|
{
|
ftrylockfile (fp);
|
fputs ("in foo\n", fp);
|
/* This is very wrong!!! */
|
funlockfile (fp);
|
}
|
|
It is important here that the ‘funlockfile’ function is only called
|
if the ‘ftrylockfile’ function succeeded in locking the stream. It is
|
therefore always wrong to ignore the result of ‘ftrylockfile’. And it
|
makes no sense since otherwise one would use ‘flockfile’. The result of
|
code like that above is that either ‘funlockfile’ tries to free a stream
|
that hasn’t been locked by the current thread or it frees the stream
|
prematurely. The code should look like this:
|
|
void
|
foo (FILE *fp)
|
{
|
if (ftrylockfile (fp) == 0)
|
{
|
fputs ("in foo\n", fp);
|
funlockfile (fp);
|
}
|
}
|
|
Now that we covered why it is necessary to have locking it is
|
necessary to talk about situations when locking is unwanted and what can
|
be done. The locking operations (explicit or implicit) don’t come for
|
free. Even if a lock is not taken the cost is not zero. The operations
|
which have to be performed require memory operations that are safe in
|
multi-processor environments. With the many local caches involved in
|
such systems this is quite costly. So it is best to avoid the locking
|
completely if it is not needed – because the code in question is never
|
used in a context where two or more threads may use a stream at a time.
|
This can be determined most of the time for application code; for
|
library code which can be used in many contexts one should default to be
|
conservative and use locking.
|
|
There are two basic mechanisms to avoid locking. The first is to use
|
the ‘_unlocked’ variants of the stream operations. The POSIX standard
|
defines quite a few of those and the GNU C Library adds a few more.
|
These variants of the functions behave just like the functions with the
|
name without the suffix except that they do not lock the stream. Using
|
these functions is very desirable since they are potentially much
|
faster. This is not only because the locking operation itself is
|
avoided. More importantly, functions like ‘putc’ and ‘getc’ are very
|
simple and traditionally (before the introduction of threads) were
|
implemented as macros which are very fast if the buffer is not empty.
|
With the addition of locking requirements these functions are no longer
|
implemented as macros since they would expand to too much code. But
|
these macros are still available with the same functionality under the
|
new names ‘putc_unlocked’ and ‘getc_unlocked’. This possibly huge
|
difference of speed also suggests the use of the ‘_unlocked’ functions
|
even if locking is required. The difference is that the locking then
|
has to be performed in the program:
|
|
void
|
foo (FILE *fp, char *buf)
|
{
|
flockfile (fp);
|
while (*buf != '/')
|
putc_unlocked (*buf++, fp);
|
funlockfile (fp);
|
}
|
|
If in this example the ‘putc’ function would be used and the explicit
|
locking would be missing the ‘putc’ function would have to acquire the
|
lock in every call, potentially many times depending on when the loop
|
terminates. Writing it the way illustrated above allows the
|
‘putc_unlocked’ macro to be used which means no locking and direct
|
manipulation of the buffer of the stream.
|
|
A second way to avoid locking is by using a non-standard function
|
which was introduced in Solaris and is available in the GNU C Library as
|
well.
|
|
-- Function: int __fsetlocking (FILE *STREAM, int TYPE)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe lock | AC-Safe |
|
*Note POSIX Safety Concepts::.
|
|
The ‘__fsetlocking’ function can be used to select whether the
|
stream operations will implicitly acquire the locking object of the
|
stream STREAM. By default this is done but it can be disabled and
|
reinstated using this function. There are three values defined for
|
the TYPE parameter.
|
|
‘FSETLOCKING_INTERNAL’
|
The stream ‘stream’ will from now on use the default internal
|
locking. Every stream operation with exception of the
|
‘_unlocked’ variants will implicitly lock the stream.
|
|
‘FSETLOCKING_BYCALLER’
|
After the ‘__fsetlocking’ function returns, the user is
|
responsible for locking the stream. None of the stream
|
operations will implicitly do this anymore until the state is
|
set back to ‘FSETLOCKING_INTERNAL’.
|
|
‘FSETLOCKING_QUERY’
|
‘__fsetlocking’ only queries the current locking state of the
|
stream. The return value will be ‘FSETLOCKING_INTERNAL’ or
|
‘FSETLOCKING_BYCALLER’ depending on the state.
|
|
The return value of ‘__fsetlocking’ is either
|
‘FSETLOCKING_INTERNAL’ or ‘FSETLOCKING_BYCALLER’ depending on the
|
state of the stream before the call.
|
|
This function and the values for the TYPE parameter are declared in
|
‘stdio_ext.h’.
|
|
This function is especially useful when program code has to be used
|
which is written without knowledge about the ‘_unlocked’ functions (or
|
if the programmer was too lazy to use them).
|
|
|
File: libc.info, Node: Streams and I18N, Next: Simple Output, Prev: Streams and Threads, Up: I/O on Streams
|
|
12.6 Streams in Internationalized Applications
|
==============================================
|
|
ISO C90 introduced the new type ‘wchar_t’ to allow handling larger
|
character sets. What was missing was a possibility to output strings of
|
‘wchar_t’ directly. One had to convert them into multibyte strings
|
using ‘mbstowcs’ (there was no ‘mbsrtowcs’ yet) and then use the normal
|
stream functions. While this is doable it is very cumbersome since
|
performing the conversions is not trivial and greatly increases program
|
complexity and size.
|
|
The Unix standard early on (I think in XPG4.2) introduced two
|
additional format specifiers for the ‘printf’ and ‘scanf’ families of
|
functions. Printing and reading of single wide characters was made
|
possible using the ‘%C’ specifier and wide character strings can be
|
handled with ‘%S’. These modifiers behave just like ‘%c’ and ‘%s’ only
|
that they expect the corresponding argument to have the wide character
|
type and that the wide character and string are transformed into/from
|
multibyte strings before being used.
|
|
This was a beginning but it is still not good enough. Not always is
|
it desirable to use ‘printf’ and ‘scanf’. The other, smaller and faster
|
functions cannot handle wide characters. Second, it is not possible to
|
have a format string for ‘printf’ and ‘scanf’ consisting of wide
|
characters. The result is that format strings would have to be
|
generated if they have to contain non-basic characters.
|
|
In the Amendment 1 to ISO C90 a whole new set of functions was added
|
to solve the problem. Most of the stream functions got a counterpart
|
which take a wide character or wide character string instead of a
|
character or string respectively. The new functions operate on the same
|
streams (like ‘stdout’). This is different from the model of the C++
|
runtime library where separate streams for wide and normal I/O are used.
|
|
Being able to use the same stream for wide and normal operations
|
comes with a restriction: a stream can be used either for wide
|
operations or for normal operations. Once it is decided there is no way
|
back. Only a call to ‘freopen’ or ‘freopen64’ can reset the
|
"orientation". The orientation can be decided in three ways:
|
|
• If any of the normal character functions are used (this includes
|
the ‘fread’ and ‘fwrite’ functions) the stream is marked as not
|
wide oriented.
|
|
• If any of the wide character functions are used the stream is
|
marked as wide oriented.
|
|
• The ‘fwide’ function can be used to set the orientation either way.
|
|
It is important to never mix the use of wide and not wide operations
|
on a stream. There are no diagnostics issued. The application behavior
|
will simply be strange or the application will simply crash. The
|
‘fwide’ function can help avoid this.
|
|
-- Function: int fwide (FILE *STREAM, int MODE)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
The ‘fwide’ function can be used to set and query the state of the
|
orientation of the stream STREAM. If the MODE parameter has a
|
positive value the streams get wide oriented, for negative values
|
narrow oriented. It is not possible to overwrite previous
|
orientations with ‘fwide’. I.e., if the stream STREAM was already
|
oriented before the call nothing is done.
|
|
If MODE is zero the current orientation state is queried and
|
nothing is changed.
|
|
The ‘fwide’ function returns a negative value, zero, or a positive
|
value if the stream is narrow, not at all, or wide oriented
|
respectively.
|
|
This function was introduced in Amendment 1 to ISO C90 and is
|
declared in ‘wchar.h’.
|
|
It is generally a good idea to orient a stream as early as possible.
|
This can prevent surprise especially for the standard streams ‘stdin’,
|
‘stdout’, and ‘stderr’. If some library function in some situations
|
uses one of these streams and this use orients the stream in a different
|
way the rest of the application expects it one might end up with hard to
|
reproduce errors. Remember that no errors are signal if the streams are
|
used incorrectly. Leaving a stream unoriented after creation is
|
normally only necessary for library functions which create streams which
|
can be used in different contexts.
|
|
When writing code which uses streams and which can be used in
|
different contexts it is important to query the orientation of the
|
stream before using it (unless the rules of the library interface demand
|
a specific orientation). The following little, silly function
|
illustrates this.
|
|
void
|
print_f (FILE *fp)
|
{
|
if (fwide (fp, 0) > 0)
|
/* Positive return value means wide orientation. */
|
fputwc (L'f', fp);
|
else
|
fputc ('f', fp);
|
}
|
|
Note that in this case the function ‘print_f’ decides about the
|
orientation of the stream if it was unoriented before (will not happen
|
if the advice above is followed).
|
|
The encoding used for the ‘wchar_t’ values is unspecified and the
|
user must not make any assumptions about it. For I/O of ‘wchar_t’
|
values this means that it is impossible to write these values directly
|
to the stream. This is not what follows from the ISO C locale model
|
either. What happens instead is that the bytes read from or written to
|
the underlying media are first converted into the internal encoding
|
chosen by the implementation for ‘wchar_t’. The external encoding is
|
determined by the ‘LC_CTYPE’ category of the current locale or by the
|
‘ccs’ part of the mode specification given to ‘fopen’, ‘fopen64’,
|
‘freopen’, or ‘freopen64’. How and when the conversion happens is
|
unspecified and it happens invisibly to the user.
|
|
Since a stream is created in the unoriented state it has at that
|
point no conversion associated with it. The conversion which will be
|
used is determined by the ‘LC_CTYPE’ category selected at the time the
|
stream is oriented. If the locales are changed at the runtime this
|
might produce surprising results unless one pays attention. This is
|
just another good reason to orient the stream explicitly as soon as
|
possible, perhaps with a call to ‘fwide’.
|
|
|
File: libc.info, Node: Simple Output, Next: Character Input, Prev: Streams and I18N, Up: I/O on Streams
|
|
12.7 Simple Output by Characters or Lines
|
=========================================
|
|
This section describes functions for performing character- and
|
line-oriented output.
|
|
These narrow stream functions are declared in the header file
|
‘stdio.h’ and the wide stream functions in ‘wchar.h’.
|
|
-- Function: int fputc (int C, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
The ‘fputc’ function converts the character C to type ‘unsigned
|
char’, and writes it to the stream STREAM. ‘EOF’ is returned if a
|
write error occurs; otherwise the character C is returned.
|
|
-- Function: wint_t fputwc (wchar_t WC, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
The ‘fputwc’ function writes the wide character WC to the stream
|
STREAM. ‘WEOF’ is returned if a write error occurs; otherwise the
|
character WC is returned.
|
|
-- Function: int fputc_unlocked (int C, FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘fputc_unlocked’ function is equivalent to the ‘fputc’ function
|
except that it does not implicitly lock the stream.
|
|
-- Function: wint_t fputwc_unlocked (wchar_t WC, FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘fputwc_unlocked’ function is equivalent to the ‘fputwc’
|
function except that it does not implicitly lock the stream.
|
|
This function is a GNU extension.
|
|
-- Function: int putc (int C, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
This is just like ‘fputc’, except that most systems implement it as
|
a macro, making it faster. One consequence is that it may evaluate
|
the STREAM argument more than once, which is an exception to the
|
general rule for macros. ‘putc’ is usually the best function to
|
use for writing a single character.
|
|
-- Function: wint_t putwc (wchar_t WC, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
This is just like ‘fputwc’, except that it can be implement as a
|
macro, making it faster. One consequence is that it may evaluate
|
the STREAM argument more than once, which is an exception to the
|
general rule for macros. ‘putwc’ is usually the best function to
|
use for writing a single wide character.
|
|
-- Function: int putc_unlocked (int C, FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘putc_unlocked’ function is equivalent to the ‘putc’ function
|
except that it does not implicitly lock the stream.
|
|
-- Function: wint_t putwc_unlocked (wchar_t WC, FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘putwc_unlocked’ function is equivalent to the ‘putwc’ function
|
except that it does not implicitly lock the stream.
|
|
This function is a GNU extension.
|
|
-- Function: int putchar (int C)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
The ‘putchar’ function is equivalent to ‘putc’ with ‘stdout’ as the
|
value of the STREAM argument.
|
|
-- Function: wint_t putwchar (wchar_t WC)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
The ‘putwchar’ function is equivalent to ‘putwc’ with ‘stdout’ as
|
the value of the STREAM argument.
|
|
-- Function: int putchar_unlocked (int C)
|
|
Preliminary: | MT-Unsafe race:stdout | AS-Unsafe corrupt |
|
AC-Unsafe corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘putchar_unlocked’ function is equivalent to the ‘putchar’
|
function except that it does not implicitly lock the stream.
|
|
-- Function: wint_t putwchar_unlocked (wchar_t WC)
|
|
Preliminary: | MT-Unsafe race:stdout | AS-Unsafe corrupt |
|
AC-Unsafe corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘putwchar_unlocked’ function is equivalent to the ‘putwchar’
|
function except that it does not implicitly lock the stream.
|
|
This function is a GNU extension.
|
|
-- Function: int fputs (const char *S, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
The function ‘fputs’ writes the string S to the stream STREAM. The
|
terminating null character is not written. This function does
|
_not_ add a newline character, either. It outputs only the
|
characters in the string.
|
|
This function returns ‘EOF’ if a write error occurs, and otherwise
|
a non-negative value.
|
|
For example:
|
|
fputs ("Are ", stdout);
|
fputs ("you ", stdout);
|
fputs ("hungry?\n", stdout);
|
|
outputs the text ‘Are you hungry?’ followed by a newline.
|
|
-- Function: int fputws (const wchar_t *WS, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
The function ‘fputws’ writes the wide character string WS to the
|
stream STREAM. The terminating null character is not written.
|
This function does _not_ add a newline character, either. It
|
outputs only the characters in the string.
|
|
This function returns ‘WEOF’ if a write error occurs, and otherwise
|
a non-negative value.
|
|
-- Function: int fputs_unlocked (const char *S, FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘fputs_unlocked’ function is equivalent to the ‘fputs’ function
|
except that it does not implicitly lock the stream.
|
|
This function is a GNU extension.
|
|
-- Function: int fputws_unlocked (const wchar_t *WS, FILE *STREAM)
|
|
Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘fputws_unlocked’ function is equivalent to the ‘fputws’
|
function except that it does not implicitly lock the stream.
|
|
This function is a GNU extension.
|
|
-- Function: int puts (const char *S)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
The ‘puts’ function writes the string S to the stream ‘stdout’
|
followed by a newline. The terminating null character of the
|
string is not written. (Note that ‘fputs’ does _not_ write a
|
newline as this function does.)
|
|
‘puts’ is the most convenient function for printing simple
|
messages. For example:
|
|
puts ("This is a message.");
|
|
outputs the text ‘This is a message.’ followed by a newline.
|
|
-- Function: int putw (int W, FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
This function writes the word W (that is, an ‘int’) to STREAM. It
|
is provided for compatibility with SVID, but we recommend you use
|
‘fwrite’ instead (*note Block Input/Output::).
|
