| This is |
| /tmp/dgboter/bbs/rhev-vm2--rhe6x86_64/buildbot/rhe6x86_64--aarch64-none-linux-gnu/build/build-aarch64-none-linux-gnu/obj/glibc/manual/libc.info, |
| produced by makeinfo version 4.13 from libc.texinfo. |
| |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHAR_BIT: (libc)Width of Type. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * FP_LLOGB0: (libc)Exponents and Logarithms. |
| * FP_LLOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OFD_GETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLKW: (libc)Open File Description Locks. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUGE_VAL_FN: (libc)Math Error Reporting. |
| * HUGE_VAL_FNx: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_DIRECTORY: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TMPFILE: (libc)Open-time Flags. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SNAN: (libc)Infinity and NaN. |
| * SNANF: (libc)Infinity and NaN. |
| * SNANFN: (libc)Infinity and NaN. |
| * SNANFNx: (libc)Infinity and NaN. |
| * SNANL: (libc)Infinity and NaN. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_high: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_set_ppr_very_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __riscv_flush_icache: (libc)RISC-V. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosfN: (libc)Inverse Trig Functions. |
| * acosfNx: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshfN: (libc)Hyperbolic Functions. |
| * acoshfNx: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinfN: (libc)Inverse Trig Functions. |
| * asinfNx: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhfN: (libc)Hyperbolic Functions. |
| * asinhfNx: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2fN: (libc)Inverse Trig Functions. |
| * atan2fNx: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanfN: (libc)Inverse Trig Functions. |
| * atanfNx: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhfN: (libc)Hyperbolic Functions. |
| * atanhfNx: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying Strings and Arrays. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying Strings and Arrays. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsfN: (libc)Absolute Value. |
| * cabsfNx: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosfN: (libc)Inverse Trig Functions. |
| * cacosfNx: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshfN: (libc)Hyperbolic Functions. |
| * cacoshfNx: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * call_once: (libc)Call Once. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize: (libc)FP Bit Twiddling. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * canonicalizef: (libc)FP Bit Twiddling. |
| * canonicalizefN: (libc)FP Bit Twiddling. |
| * canonicalizefNx: (libc)FP Bit Twiddling. |
| * canonicalizel: (libc)FP Bit Twiddling. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargfN: (libc)Operations on Complex. |
| * cargfNx: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinfN: (libc)Inverse Trig Functions. |
| * casinfNx: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhfN: (libc)Hyperbolic Functions. |
| * casinhfNx: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanfN: (libc)Inverse Trig Functions. |
| * catanfNx: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhfN: (libc)Hyperbolic Functions. |
| * catanhfNx: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtfN: (libc)Exponents and Logarithms. |
| * cbrtfNx: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosfN: (libc)Trig Functions. |
| * ccosfNx: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshfN: (libc)Hyperbolic Functions. |
| * ccoshfNx: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceilfN: (libc)Rounding Functions. |
| * ceilfNx: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpfN: (libc)Exponents and Logarithms. |
| * cexpfNx: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagfN: (libc)Operations on Complex. |
| * cimagfNx: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10fN: (libc)Exponents and Logarithms. |
| * clog10fNx: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogfN: (libc)Exponents and Logarithms. |
| * clogfNx: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * cnd_broadcast: (libc)ISO C Condition Variables. |
| * cnd_destroy: (libc)ISO C Condition Variables. |
| * cnd_init: (libc)ISO C Condition Variables. |
| * cnd_signal: (libc)ISO C Condition Variables. |
| * cnd_timedwait: (libc)ISO C Condition Variables. |
| * cnd_wait: (libc)ISO C Condition Variables. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjfN: (libc)Operations on Complex. |
| * conjfNx: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copy_file_range: (libc)Copying File Data. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignfN: (libc)FP Bit Twiddling. |
| * copysignfNx: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosfN: (libc)Trig Functions. |
| * cosfNx: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshfN: (libc)Hyperbolic Functions. |
| * coshfNx: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowfN: (libc)Exponents and Logarithms. |
| * cpowfNx: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojfN: (libc)Operations on Complex. |
| * cprojfNx: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * crealfN: (libc)Operations on Complex. |
| * crealfNx: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)Passphrase Storage. |
| * crypt_r: (libc)Passphrase Storage. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinfN: (libc)Trig Functions. |
| * csinfNx: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhfN: (libc)Hyperbolic Functions. |
| * csinhfNx: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtfN: (libc)Exponents and Logarithms. |
| * csqrtfNx: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanfN: (libc)Trig Functions. |
| * ctanfNx: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhfN: (libc)Hyperbolic Functions. |
| * ctanhfNx: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * daddl: (libc)Misc FP Arithmetic. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * ddivl: (libc)Misc FP Arithmetic. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dmull: (libc)Misc FP Arithmetic. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dsubl: (libc)Misc FP Arithmetic. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_remove: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcfN: (libc)Special Functions. |
| * erfcfNx: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erffN: (libc)Special Functions. |
| * erffNx: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10fN: (libc)Exponents and Logarithms. |
| * exp10fNx: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2fN: (libc)Exponents and Logarithms. |
| * exp2fNx: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expfN: (libc)Exponents and Logarithms. |
| * expfNx: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * explicit_bzero: (libc)Erasing Sensitive Data. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1fN: (libc)Exponents and Logarithms. |
| * expm1fNx: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fMaddfN: (libc)Misc FP Arithmetic. |
| * fMaddfNx: (libc)Misc FP Arithmetic. |
| * fMdivfN: (libc)Misc FP Arithmetic. |
| * fMdivfNx: (libc)Misc FP Arithmetic. |
| * fMmulfN: (libc)Misc FP Arithmetic. |
| * fMmulfNx: (libc)Misc FP Arithmetic. |
| * fMsubfN: (libc)Misc FP Arithmetic. |
| * fMsubfNx: (libc)Misc FP Arithmetic. |
| * fMxaddfN: (libc)Misc FP Arithmetic. |
| * fMxaddfNx: (libc)Misc FP Arithmetic. |
| * fMxdivfN: (libc)Misc FP Arithmetic. |
| * fMxdivfNx: (libc)Misc FP Arithmetic. |
| * fMxmulfN: (libc)Misc FP Arithmetic. |
| * fMxmulfNx: (libc)Misc FP Arithmetic. |
| * fMxsubfN: (libc)Misc FP Arithmetic. |
| * fMxsubfNx: (libc)Misc FP Arithmetic. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsfN: (libc)Absolute Value. |
| * fabsfNx: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fadd: (libc)Misc FP Arithmetic. |
| * faddl: (libc)Misc FP Arithmetic. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdimfN: (libc)Misc FP Arithmetic. |
| * fdimfNx: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdiv: (libc)Misc FP Arithmetic. |
| * fdivl: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetmode: (libc)Control Functions. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexcept: (libc)Status bit operations. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetmode: (libc)Control Functions. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * fetestexceptflag: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorfN: (libc)Rounding Functions. |
| * floorfNx: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmafN: (libc)Misc FP Arithmetic. |
| * fmafNx: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxfN: (libc)Misc FP Arithmetic. |
| * fmaxfNx: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmaxmag: (libc)Misc FP Arithmetic. |
| * fmaxmagf: (libc)Misc FP Arithmetic. |
| * fmaxmagfN: (libc)Misc FP Arithmetic. |
| * fmaxmagfNx: (libc)Misc FP Arithmetic. |
| * fmaxmagl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminfN: (libc)Misc FP Arithmetic. |
| * fminfNx: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fminmag: (libc)Misc FP Arithmetic. |
| * fminmagf: (libc)Misc FP Arithmetic. |
| * fminmagfN: (libc)Misc FP Arithmetic. |
| * fminmagfNx: (libc)Misc FP Arithmetic. |
| * fminmagl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodfN: (libc)Remainder Functions. |
| * fmodfNx: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fmul: (libc)Misc FP Arithmetic. |
| * fmull: (libc)Misc FP Arithmetic. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpfN: (libc)Normalization Functions. |
| * frexpfNx: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fromfp: (libc)Rounding Functions. |
| * fromfpf: (libc)Rounding Functions. |
| * fromfpfN: (libc)Rounding Functions. |
| * fromfpfNx: (libc)Rounding Functions. |
| * fromfpl: (libc)Rounding Functions. |
| * fromfpx: (libc)Rounding Functions. |
| * fromfpxf: (libc)Rounding Functions. |
| * fromfpxfN: (libc)Rounding Functions. |
| * fromfpxfNx: (libc)Rounding Functions. |
| * fromfpxl: (libc)Rounding Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsub: (libc)Misc FP Arithmetic. |
| * fsubl: (libc)Misc FP Arithmetic. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcpu: (libc)CPU Affinity. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdents64: (libc)Low-level Directory Access. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getentropy: (libc)Unpredictable Bytes. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpayload: (libc)FP Bit Twiddling. |
| * getpayloadf: (libc)FP Bit Twiddling. |
| * getpayloadfN: (libc)FP Bit Twiddling. |
| * getpayloadfNx: (libc)FP Bit Twiddling. |
| * getpayloadl: (libc)FP Bit Twiddling. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrandom: (libc)Unpredictable Bytes. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettid: (libc)Process Identification. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotfN: (libc)Exponents and Logarithms. |
| * hypotfNx: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbfN: (libc)Exponents and Logarithms. |
| * ilogbfNx: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscanonical: (libc)Floating Point Classes. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * iseqsig: (libc)FP Comparison Functions. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * issubnormal: (libc)Floating Point Classes. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * iszero: (libc)Floating Point Classes. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0fN: (libc)Special Functions. |
| * j0fNx: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1fN: (libc)Special Functions. |
| * j1fNx: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnfN: (libc)Special Functions. |
| * jnfNx: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpfN: (libc)Normalization Functions. |
| * ldexpfNx: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammafN: (libc)Special Functions. |
| * lgammafN_r: (libc)Special Functions. |
| * lgammafNx: (libc)Special Functions. |
| * lgammafNx_r: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * linkat: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llogb: (libc)Exponents and Logarithms. |
| * llogbf: (libc)Exponents and Logarithms. |
| * llogbfN: (libc)Exponents and Logarithms. |
| * llogbfNx: (libc)Exponents and Logarithms. |
| * llogbl: (libc)Exponents and Logarithms. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintfN: (libc)Rounding Functions. |
| * llrintfNx: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundfN: (libc)Rounding Functions. |
| * llroundfNx: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10fN: (libc)Exponents and Logarithms. |
| * log10fNx: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pfN: (libc)Exponents and Logarithms. |
| * log1pfNx: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2fN: (libc)Exponents and Logarithms. |
| * log2fNx: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbfN: (libc)Exponents and Logarithms. |
| * logbfNx: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * logfN: (libc)Exponents and Logarithms. |
| * logfNx: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintfN: (libc)Rounding Functions. |
| * lrintfNx: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundfN: (libc)Rounding Functions. |
| * lroundfNx: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying Strings and Arrays. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying Strings and Arrays. |
| * memfd_create: (libc)Memory-mapped I/O. |
| * memfrob: (libc)Obfuscating Data. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying Strings and Arrays. |
| * mempcpy: (libc)Copying Strings and Arrays. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying Strings and Arrays. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock2: (libc)Page Lock Functions. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modffN: (libc)Rounding Functions. |
| * modffNx: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mprotect: (libc)Memory Protection. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * mtx_destroy: (libc)ISO C Mutexes. |
| * mtx_init: (libc)ISO C Mutexes. |
| * mtx_lock: (libc)ISO C Mutexes. |
| * mtx_timedlock: (libc)ISO C Mutexes. |
| * mtx_trylock: (libc)ISO C Mutexes. |
| * mtx_unlock: (libc)ISO C Mutexes. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanfN: (libc)FP Bit Twiddling. |
| * nanfNx: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintfN: (libc)Rounding Functions. |
| * nearbyintfNx: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterfN: (libc)FP Bit Twiddling. |
| * nextafterfNx: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nextdown: (libc)FP Bit Twiddling. |
| * nextdownf: (libc)FP Bit Twiddling. |
| * nextdownfN: (libc)FP Bit Twiddling. |
| * nextdownfNx: (libc)FP Bit Twiddling. |
| * nextdownl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nextup: (libc)FP Bit Twiddling. |
| * nextupf: (libc)FP Bit Twiddling. |
| * nextupfN: (libc)FP Bit Twiddling. |
| * nextupfNx: (libc)FP Bit Twiddling. |
| * nextupl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * pkey_alloc: (libc)Memory Protection. |
| * pkey_free: (libc)Memory Protection. |
| * pkey_get: (libc)Memory Protection. |
| * pkey_mprotect: (libc)Memory Protection. |
| * pkey_set: (libc)Memory Protection. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_fallocate64: (libc)Storage Allocation. |
| * posix_fallocate: (libc)Storage Allocation. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powfN: (libc)Exponents and Logarithms. |
| * powfNx: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * preadv2: (libc)Scatter-Gather. |
| * preadv64: (libc)Scatter-Gather. |
| * preadv64v2: (libc)Scatter-Gather. |
| * preadv: (libc)Scatter-Gather. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_cond_clockwait: (libc)Default Thread Attributes. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_rwlock_clockrdlock: (libc)Default Thread Attributes. |
| * pthread_rwlock_clockwrlock: (libc)Default Thread Attributes. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * pwritev2: (libc)Scatter-Gather. |
| * pwritev64: (libc)Scatter-Gather. |
| * pwritev64v2: (libc)Scatter-Gather. |
| * pwritev: (libc)Scatter-Gather. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * reallocarray: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderfN: (libc)Remainder Functions. |
| * remainderfNx: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintfN: (libc)Rounding Functions. |
| * rintfNx: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundeven: (libc)Rounding Functions. |
| * roundevenf: (libc)Rounding Functions. |
| * roundevenfN: (libc)Rounding Functions. |
| * roundevenfNx: (libc)Rounding Functions. |
| * roundevenl: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundfN: (libc)Rounding Functions. |
| * roundfNx: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnfN: (libc)Normalization Functions. |
| * scalblnfNx: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnfN: (libc)Normalization Functions. |
| * scalbnfNx: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * sem_clockwait: (libc)Default Thread Attributes. |
| * sem_close: (libc)Semaphores. |
| * sem_destroy: (libc)Semaphores. |
| * sem_getvalue: (libc)Semaphores. |
| * sem_init: (libc)Semaphores. |
| * sem_open: (libc)Semaphores. |
| * sem_post: (libc)Semaphores. |
| * sem_timedwait: (libc)Semaphores. |
| * sem_trywait: (libc)Semaphores. |
| * sem_unlink: (libc)Semaphores. |
| * sem_wait: (libc)Semaphores. |
| * semctl: (libc)Semaphores. |
| * semget: (libc)Semaphores. |
| * semop: (libc)Semaphores. |
| * semtimedop: (libc)Semaphores. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpayload: (libc)FP Bit Twiddling. |
| * setpayloadf: (libc)FP Bit Twiddling. |
| * setpayloadfN: (libc)FP Bit Twiddling. |
| * setpayloadfNx: (libc)FP Bit Twiddling. |
| * setpayloadl: (libc)FP Bit Twiddling. |
| * setpayloadsig: (libc)FP Bit Twiddling. |
| * setpayloadsigf: (libc)FP Bit Twiddling. |
| * setpayloadsigfN: (libc)FP Bit Twiddling. |
| * setpayloadsigfNx: (libc)FP Bit Twiddling. |
| * setpayloadsigl: (libc)FP Bit Twiddling. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)BSD Signal Handling. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Signal Handling. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)BSD Signal Handling. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)BSD Signal Handling. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)BSD Signal Handling. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosfN: (libc)Trig Functions. |
| * sincosfNx: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinfN: (libc)Trig Functions. |
| * sinfNx: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhfN: (libc)Hyperbolic Functions. |
| * sinhfNx: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtfN: (libc)Exponents and Logarithms. |
| * sqrtfNx: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying Strings and Arrays. |
| * stpncpy: (libc)Truncating Strings. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Concatenating Strings. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying Strings and Arrays. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying Strings and Arrays. |
| * strdupa: (libc)Copying Strings and Arrays. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfromd: (libc)Printing of Floats. |
| * strfromf: (libc)Printing of Floats. |
| * strfromfN: (libc)Printing of Floats. |
| * strfromfNx: (libc)Printing of Floats. |
| * strfroml: (libc)Printing of Floats. |
| * strfry: (libc)Shuffling Bytes. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Truncating Strings. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Truncating Strings. |
| * strndup: (libc)Truncating Strings. |
| * strndupa: (libc)Truncating Strings. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtofN: (libc)Parsing of Floats. |
| * strtofNx: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanfN: (libc)Trig Functions. |
| * tanfNx: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhfN: (libc)Hyperbolic Functions. |
| * tanhfNx: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammafN: (libc)Special Functions. |
| * tgammafNx: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * tgkill: (libc)Signaling Another Process. |
| * thrd_create: (libc)ISO C Thread Management. |
| * thrd_current: (libc)ISO C Thread Management. |
| * thrd_detach: (libc)ISO C Thread Management. |
| * thrd_equal: (libc)ISO C Thread Management. |
| * thrd_exit: (libc)ISO C Thread Management. |
| * thrd_join: (libc)ISO C Thread Management. |
| * thrd_sleep: (libc)ISO C Thread Management. |
| * thrd_yield: (libc)ISO C Thread Management. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * totalorder: (libc)FP Comparison Functions. |
| * totalorderf: (libc)FP Comparison Functions. |
| * totalorderfN: (libc)FP Comparison Functions. |
| * totalorderfNx: (libc)FP Comparison Functions. |
| * totalorderl: (libc)FP Comparison Functions. |
| * totalordermag: (libc)FP Comparison Functions. |
| * totalordermagf: (libc)FP Comparison Functions. |
| * totalordermagfN: (libc)FP Comparison Functions. |
| * totalordermagfNx: (libc)FP Comparison Functions. |
| * totalordermagl: (libc)FP Comparison Functions. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncfN: (libc)Rounding Functions. |
| * truncfNx: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * tss_create: (libc)ISO C Thread-local Storage. |
| * tss_delete: (libc)ISO C Thread-local Storage. |
| * tss_get: (libc)ISO C Thread-local Storage. |
| * tss_set: (libc)ISO C Thread-local Storage. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * twalk_r: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ufromfp: (libc)Rounding Functions. |
| * ufromfpf: (libc)Rounding Functions. |
| * ufromfpfN: (libc)Rounding Functions. |
| * ufromfpfNx: (libc)Rounding Functions. |
| * ufromfpl: (libc)Rounding Functions. |
| * ufromfpx: (libc)Rounding Functions. |
| * ufromfpxf: (libc)Rounding Functions. |
| * ufromfpxfN: (libc)Rounding Functions. |
| * ufromfpxfNx: (libc)Rounding Functions. |
| * ufromfpxl: (libc)Rounding Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying Strings and Arrays. |
| * wcpncpy: (libc)Truncating Strings. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Concatenating Strings. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying Strings and Arrays. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying Strings and Arrays. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Truncating Strings. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Truncating Strings. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstofN: (libc)Parsing of Floats. |
| * wcstofNx: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying Strings and Arrays. |
| * wmemmove: (libc)Copying Strings and Arrays. |
| * wmempcpy: (libc)Copying Strings and Arrays. |
| * wmemset: (libc)Copying Strings and Arrays. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0fN: (libc)Special Functions. |
| * y0fNx: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1fN: (libc)Special Functions. |
| * y1fNx: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynfN: (libc)Special Functions. |
| * ynfNx: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU C Library. |
| |
| This is `The GNU C Library Reference Manual', for version 2.30 |
| (GNU Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10)). |
| |
| Copyright (C) 1993-2019 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version |
| 1.3 or any later version published by the Free Software Foundation; |
| with the Invariant Sections being "Free Software Needs Free |
| Documentation" and "GNU Lesser General Public License", the Front-Cover |
| texts being "A GNU Manual", and with the Back-Cover Texts as in (a) |
| below. A copy of the license is included in the section entitled "GNU |
| Free Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| |
| |
| File: libc.info, Node: Locale Information, Next: Formatting Numbers, Prev: Locale Names, Up: Locales |
| |
| 7.7 Accessing Locale Information |
| ================================ |
| |
| There are several ways to access locale information. The simplest way |
| is to let the C library itself do the work. Several of the functions |
| in this library implicitly access the locale data, and use what |
| information is provided by the currently selected locale. This is how |
| the locale model is meant to work normally. |
| |
| As an example take the `strftime' function, which is meant to nicely |
| format date and time information (*note Formatting Calendar Time::). |
| Part of the standard information contained in the `LC_TIME' category is |
| the names of the months. Instead of requiring the programmer to take |
| care of providing the translations the `strftime' function does this |
| all by itself. `%A' in the format string is replaced by the |
| appropriate weekday name of the locale currently selected by `LC_TIME'. |
| This is an easy example, and wherever possible functions do things |
| automatically in this way. |
| |
| But there are quite often situations when there is simply no function |
| to perform the task, or it is simply not possible to do the work |
| automatically. For these cases it is necessary to access the |
| information in the locale directly. To do this the C library provides |
| two functions: `localeconv' and `nl_langinfo'. The former is part of |
| ISO C and therefore portable, but has a brain-damaged interface. The |
| second is part of the Unix interface and is portable in as far as the |
| system follows the Unix standards. |
| |
| * Menu: |
| |
| * The Lame Way to Locale Data:: ISO C's `localeconv'. |
| * The Elegant and Fast Way:: X/Open's `nl_langinfo'. |
| |
| |
| File: libc.info, Node: The Lame Way to Locale Data, Next: The Elegant and Fast Way, Up: Locale Information |
| |
| 7.7.1 `localeconv': It is portable but ... |
| ------------------------------------------ |
| |
| Together with the `setlocale' function the ISO C people invented the |
| `localeconv' function. It is a masterpiece of poor design. It is |
| expensive to use, not extensible, and not generally usable as it |
| provides access to only `LC_MONETARY' and `LC_NUMERIC' related |
| information. Nevertheless, if it is applicable to a given situation it |
| should be used since it is very portable. The function `strfmon' |
| formats monetary amounts according to the selected locale using this |
| information. |
| |
| -- Function: struct lconv * localeconv (void) |
| Preliminary: | MT-Unsafe race:localeconv locale | AS-Unsafe | |
| AC-Safe | *Note POSIX Safety Concepts::. |
| |
| The `localeconv' function returns a pointer to a structure whose |
| components contain information about how numeric and monetary |
| values should be formatted in the current locale. |
| |
| You should not modify the structure or its contents. The |
| structure might be overwritten by subsequent calls to |
| `localeconv', or by calls to `setlocale', but no other function in |
| the library overwrites this value. |
| |
| -- Data Type: struct lconv |
| `localeconv''s return value is of this data type. Its elements are |
| described in the following subsections. |
| |
| If a member of the structure `struct lconv' has type `char', and the |
| value is `CHAR_MAX', it means that the current locale has no value for |
| that parameter. |
| |
| * Menu: |
| |
| * General Numeric:: Parameters for formatting numbers and |
| currency amounts. |
| * Currency Symbol:: How to print the symbol that identifies an |
| amount of money (e.g. `$'). |
| * Sign of Money Amount:: How to print the (positive or negative) sign |
| for a monetary amount, if one exists. |
| |
| |
| File: libc.info, Node: General Numeric, Next: Currency Symbol, Up: The Lame Way to Locale Data |
| |
| 7.7.1.1 Generic Numeric Formatting Parameters |
| ............................................. |
| |
| These are the standard members of `struct lconv'; there may be others. |
| |
| `char *decimal_point' |
| `char *mon_decimal_point' |
| These are the decimal-point separators used in formatting |
| non-monetary and monetary quantities, respectively. In the `C' |
| locale, the value of `decimal_point' is `"."', and the value of |
| `mon_decimal_point' is `""'. |
| |
| `char *thousands_sep' |
| `char *mon_thousands_sep' |
| These are the separators used to delimit groups of digits to the |
| left of the decimal point in formatting non-monetary and monetary |
| quantities, respectively. In the `C' locale, both members have a |
| value of `""' (the empty string). |
| |
| `char *grouping' |
| `char *mon_grouping' |
| These are strings that specify how to group the digits to the left |
| of the decimal point. `grouping' applies to non-monetary |
| quantities and `mon_grouping' applies to monetary quantities. Use |
| either `thousands_sep' or `mon_thousands_sep' to separate the digit |
| groups. |
| |
| Each member of these strings is to be interpreted as an integer |
| value of type `char'. Successive numbers (from left to right) |
| give the sizes of successive groups (from right to left, starting |
| at the decimal point.) The last member is either `0', in which |
| case the previous member is used over and over again for all the |
| remaining groups, or `CHAR_MAX', in which case there is no more |
| grouping--or, put another way, any remaining digits form one large |
| group without separators. |
| |
| For example, if `grouping' is `"\04\03\02"', the correct grouping |
| for the number `123456787654321' is `12', `34', `56', `78', `765', |
| `4321'. This uses a group of 4 digits at the end, preceded by a |
| group of 3 digits, preceded by groups of 2 digits (as many as |
| needed). With a separator of `,', the number would be printed as |
| `12,34,56,78,765,4321'. |
| |
| A value of `"\03"' indicates repeated groups of three digits, as |
| normally used in the U.S. |
| |
| In the standard `C' locale, both `grouping' and `mon_grouping' |
| have a value of `""'. This value specifies no grouping at all. |
| |
| `char int_frac_digits' |
| `char frac_digits' |
| These are small integers indicating how many fractional digits (to |
| the right of the decimal point) should be displayed in a monetary |
| value in international and local formats, respectively. (Most |
| often, both members have the same value.) |
| |
| In the standard `C' locale, both of these members have the value |
| `CHAR_MAX', meaning "unspecified". The ISO standard doesn't say |
| what to do when you find this value; we recommend printing no |
| fractional digits. (This locale also specifies the empty string |
| for `mon_decimal_point', so printing any fractional digits would be |
| confusing!) |
| |
| |
| File: libc.info, Node: Currency Symbol, Next: Sign of Money Amount, Prev: General Numeric, Up: The Lame Way to Locale Data |
| |
| 7.7.1.2 Printing the Currency Symbol |
| .................................... |
| |
| These members of the `struct lconv' structure specify how to print the |
| symbol to identify a monetary value--the international analog of `$' |
| for US dollars. |
| |
| Each country has two standard currency symbols. The "local currency |
| symbol" is used commonly within the country, while the "international |
| currency symbol" is used internationally to refer to that country's |
| currency when it is necessary to indicate the country unambiguously. |
| |
| For example, many countries use the dollar as their monetary unit, |
| and when dealing with international currencies it's important to specify |
| that one is dealing with (say) Canadian dollars instead of U.S. dollars |
| or Australian dollars. But when the context is known to be Canada, |
| there is no need to make this explicit--dollar amounts are implicitly |
| assumed to be in Canadian dollars. |
| |
| `char *currency_symbol' |
| The local currency symbol for the selected locale. |
| |
| In the standard `C' locale, this member has a value of `""' (the |
| empty string), meaning "unspecified". The ISO standard doesn't |
| say what to do when you find this value; we recommend you simply |
| print the empty string as you would print any other string pointed |
| to by this variable. |
| |
| `char *int_curr_symbol' |
| The international currency symbol for the selected locale. |
| |
| The value of `int_curr_symbol' should normally consist of a |
| three-letter abbreviation determined by the international standard |
| `ISO 4217 Codes for the Representation of Currency and Funds', |
| followed by a one-character separator (often a space). |
| |
| In the standard `C' locale, this member has a value of `""' (the |
| empty string), meaning "unspecified". We recommend you simply |
| print the empty string as you would print any other string pointed |
| to by this variable. |
| |
| `char p_cs_precedes' |
| `char n_cs_precedes' |
| `char int_p_cs_precedes' |
| `char int_n_cs_precedes' |
| These members are `1' if the `currency_symbol' or |
| `int_curr_symbol' strings should precede the value of a monetary |
| amount, or `0' if the strings should follow the value. The |
| `p_cs_precedes' and `int_p_cs_precedes' members apply to positive |
| amounts (or zero), and the `n_cs_precedes' and `int_n_cs_precedes' |
| members apply to negative amounts. |
| |
| In the standard `C' locale, all of these members have a value of |
| `CHAR_MAX', meaning "unspecified". The ISO standard doesn't say |
| what to do when you find this value. We recommend printing the |
| currency symbol before the amount, which is right for most |
| countries. In other words, treat all nonzero values alike in |
| these members. |
| |
| The members with the `int_' prefix apply to the `int_curr_symbol' |
| while the other two apply to `currency_symbol'. |
| |
| `char p_sep_by_space' |
| `char n_sep_by_space' |
| `char int_p_sep_by_space' |
| `char int_n_sep_by_space' |
| These members are `1' if a space should appear between the |
| `currency_symbol' or `int_curr_symbol' strings and the amount, or |
| `0' if no space should appear. The `p_sep_by_space' and |
| `int_p_sep_by_space' members apply to positive amounts (or zero), |
| and the `n_sep_by_space' and `int_n_sep_by_space' members apply to |
| negative amounts. |
| |
| In the standard `C' locale, all of these members have a value of |
| `CHAR_MAX', meaning "unspecified". The ISO standard doesn't say |
| what you should do when you find this value; we suggest you treat |
| it as 1 (print a space). In other words, treat all nonzero values |
| alike in these members. |
| |
| The members with the `int_' prefix apply to the `int_curr_symbol' |
| while the other two apply to `currency_symbol'. There is one |
| specialty with the `int_curr_symbol', though. Since all legal |
| values contain a space at the end of the string one either prints |
| this space (if the currency symbol must appear in front and must |
| be separated) or one has to avoid printing this character at all |
| (especially when at the end of the string). |
| |
| |
| File: libc.info, Node: Sign of Money Amount, Prev: Currency Symbol, Up: The Lame Way to Locale Data |
| |
| 7.7.1.3 Printing the Sign of a Monetary Amount |
| .............................................. |
| |
| These members of the `struct lconv' structure specify how to print the |
| sign (if any) of a monetary value. |
| |
| `char *positive_sign' |
| `char *negative_sign' |
| These are strings used to indicate positive (or zero) and negative |
| monetary quantities, respectively. |
| |
| In the standard `C' locale, both of these members have a value of |
| `""' (the empty string), meaning "unspecified". |
| |
| The ISO standard doesn't say what to do when you find this value; |
| we recommend printing `positive_sign' as you find it, even if it is |
| empty. For a negative value, print `negative_sign' as you find it |
| unless both it and `positive_sign' are empty, in which case print |
| `-' instead. (Failing to indicate the sign at all seems rather |
| unreasonable.) |
| |
| `char p_sign_posn' |
| `char n_sign_posn' |
| `char int_p_sign_posn' |
| `char int_n_sign_posn' |
| These members are small integers that indicate how to position the |
| sign for nonnegative and negative monetary quantities, |
| respectively. (The string used for the sign is what was specified |
| with `positive_sign' or `negative_sign'.) The possible values are |
| as follows: |
| |
| `0' |
| The currency symbol and quantity should be surrounded by |
| parentheses. |
| |
| `1' |
| Print the sign string before the quantity and currency symbol. |
| |
| `2' |
| Print the sign string after the quantity and currency symbol. |
| |
| `3' |
| Print the sign string right before the currency symbol. |
| |
| `4' |
| Print the sign string right after the currency symbol. |
| |
| `CHAR_MAX' |
| "Unspecified". Both members have this value in the standard |
| `C' locale. |
| |
| The ISO standard doesn't say what you should do when the value is |
| `CHAR_MAX'. We recommend you print the sign after the currency |
| symbol. |
| |
| The members with the `int_' prefix apply to the `int_curr_symbol' |
| while the other two apply to `currency_symbol'. |
| |
| |
| File: libc.info, Node: The Elegant and Fast Way, Prev: The Lame Way to Locale Data, Up: Locale Information |
| |
| 7.7.2 Pinpoint Access to Locale Data |
| ------------------------------------ |
| |
| When writing the X/Open Portability Guide the authors realized that the |
| `localeconv' function is not enough to provide reasonable access to |
| locale information. The information which was meant to be available in |
| the locale (as later specified in the POSIX.1 standard) requires more |
| ways to access it. Therefore the `nl_langinfo' function was introduced. |
| |
| -- Function: char * nl_langinfo (nl_item ITEM) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The `nl_langinfo' function can be used to access individual |
| elements of the locale categories. Unlike the `localeconv' |
| function, which returns all the information, `nl_langinfo' lets |
| the caller select what information it requires. This is very fast |
| and it is not a problem to call this function multiple times. |
| |
| A second advantage is that in addition to the numeric and monetary |
| formatting information, information from the `LC_TIME' and |
| `LC_MESSAGES' categories is available. |
| |
| The type `nl_item' is defined in `nl_types.h'. The argument ITEM |
| is a numeric value defined in the header `langinfo.h'. The X/Open |
| standard defines the following values: |
| |
| `CODESET' |
| `nl_langinfo' returns a string with the name of the coded |
| character set used in the selected locale. |
| |
| `ABDAY_1' |
| `ABDAY_2' |
| `ABDAY_3' |
| `ABDAY_4' |
| `ABDAY_5' |
| `ABDAY_6' |
| `ABDAY_7' |
| `nl_langinfo' returns the abbreviated weekday name. `ABDAY_1' |
| corresponds to Sunday. |
| |
| `DAY_1' |
| `DAY_2' |
| `DAY_3' |
| `DAY_4' |
| `DAY_5' |
| `DAY_6' |
| `DAY_7' |
| Similar to `ABDAY_1', etc., but here the return value is the |
| unabbreviated weekday name. |
| |
| `ABMON_1' |
| `ABMON_2' |
| `ABMON_3' |
| `ABMON_4' |
| `ABMON_5' |
| `ABMON_6' |
| `ABMON_7' |
| `ABMON_8' |
| `ABMON_9' |
| `ABMON_10' |
| `ABMON_11' |
| `ABMON_12' |
| The return value is the abbreviated name of the month, in the |
| grammatical form used when the month forms part of a complete |
| date. `ABMON_1' corresponds to January. |
| |
| `MON_1' |
| `MON_2' |
| `MON_3' |
| `MON_4' |
| `MON_5' |
| `MON_6' |
| `MON_7' |
| `MON_8' |
| `MON_9' |
| `MON_10' |
| `MON_11' |
| `MON_12' |
| Similar to `ABMON_1', etc., but here the month names are not |
| abbreviated. Here the first value `MON_1' also corresponds to |
| January. |
| |
| `ALTMON_1' |
| `ALTMON_2' |
| `ALTMON_3' |
| `ALTMON_4' |
| `ALTMON_5' |
| `ALTMON_6' |
| `ALTMON_7' |
| `ALTMON_8' |
| `ALTMON_9' |
| `ALTMON_10' |
| `ALTMON_11' |
| `ALTMON_12' |
| Similar to `MON_1', etc., but here the month names are in the |
| grammatical form used when the month is named by itself. The |
| `strftime' functions use these month names for the conversion |
| specifier `%OB' (*note Formatting Calendar Time::). |
| |
| Note that not all languages need two different forms of the |
| month names, so the strings returned for `MON_...' and |
| `ALTMON_...' may or may not be the same, depending on the |
| locale. |
| |
| *NB:* `ABALTMON_...' constants corresponding to the `%Ob' |
| conversion specifier are not currently provided, but are |
| expected to be in a future release. In the meantime, it is |
| possible to use `_NL_ABALTMON_...'. |
| |
| `AM_STR' |
| `PM_STR' |
| The return values are strings which can be used in the |
| representation of time as an hour from 1 to 12 plus an am/pm |
| specifier. |
| |
| Note that in locales which do not use this time representation |
| these strings might be empty, in which case the am/pm format |
| cannot be used at all. |
| |
| `D_T_FMT' |
| The return value can be used as a format string for |
| `strftime' to represent time and date in a locale-specific |
| way. |
| |
| `D_FMT' |
| The return value can be used as a format string for |
| `strftime' to represent a date in a locale-specific way. |
| |
| `T_FMT' |
| The return value can be used as a format string for |
| `strftime' to represent time in a locale-specific way. |
| |
| `T_FMT_AMPM' |
| The return value can be used as a format string for |
| `strftime' to represent time in the am/pm format. |
| |
| Note that if the am/pm format does not make any sense for the |
| selected locale, the return value might be the same as the |
| one for `T_FMT'. |
| |
| `ERA' |
| The return value represents the era used in the current |
| locale. |
| |
| Most locales do not define this value. An example of a |
| locale which does define this value is the Japanese one. In |
| Japan, the traditional representation of dates includes the |
| name of the era corresponding to the then-emperor's reign. |
| |
| Normally it should not be necessary to use this value |
| directly. Specifying the `E' modifier in their format |
| strings causes the `strftime' functions to use this |
| information. The format of the returned string is not |
| specified, and therefore you should not assume knowledge of |
| it on different systems. |
| |
| `ERA_YEAR' |
| The return value gives the year in the relevant era of the |
| locale. As for `ERA' it should not be necessary to use this |
| value directly. |
| |
| `ERA_D_T_FMT' |
| This return value can be used as a format string for |
| `strftime' to represent dates and times in a locale-specific |
| era-based way. |
| |
| `ERA_D_FMT' |
| This return value can be used as a format string for |
| `strftime' to represent a date in a locale-specific era-based |
| way. |
| |
| `ERA_T_FMT' |
| This return value can be used as a format string for |
| `strftime' to represent time in a locale-specific era-based |
| way. |
| |
| `ALT_DIGITS' |
| The return value is a representation of up to 100 values used |
| to represent the values 0 to 99. As for `ERA' this value is |
| not intended to be used directly, but instead indirectly |
| through the `strftime' function. When the modifier `O' is |
| used in a format which would otherwise use numerals to |
| represent hours, minutes, seconds, weekdays, months, or |
| weeks, the appropriate value for the locale is used instead. |
| |
| `INT_CURR_SYMBOL' |
| The same as the value returned by `localeconv' in the |
| `int_curr_symbol' element of the `struct lconv'. |
| |
| `CURRENCY_SYMBOL' |
| `CRNCYSTR' |
| The same as the value returned by `localeconv' in the |
| `currency_symbol' element of the `struct lconv'. |
| |
| `CRNCYSTR' is a deprecated alias still required by Unix98. |
| |
| `MON_DECIMAL_POINT' |
| The same as the value returned by `localeconv' in the |
| `mon_decimal_point' element of the `struct lconv'. |
| |
| `MON_THOUSANDS_SEP' |
| The same as the value returned by `localeconv' in the |
| `mon_thousands_sep' element of the `struct lconv'. |
| |
| `MON_GROUPING' |
| The same as the value returned by `localeconv' in the |
| `mon_grouping' element of the `struct lconv'. |
| |
| `POSITIVE_SIGN' |
| The same as the value returned by `localeconv' in the |
| `positive_sign' element of the `struct lconv'. |
| |
| `NEGATIVE_SIGN' |
| The same as the value returned by `localeconv' in the |
| `negative_sign' element of the `struct lconv'. |
| |
| `INT_FRAC_DIGITS' |
| The same as the value returned by `localeconv' in the |
| `int_frac_digits' element of the `struct lconv'. |
| |
| `FRAC_DIGITS' |
| The same as the value returned by `localeconv' in the |
| `frac_digits' element of the `struct lconv'. |
| |
| `P_CS_PRECEDES' |
| The same as the value returned by `localeconv' in the |
| `p_cs_precedes' element of the `struct lconv'. |
| |
| `P_SEP_BY_SPACE' |
| The same as the value returned by `localeconv' in the |
| `p_sep_by_space' element of the `struct lconv'. |
| |
| `N_CS_PRECEDES' |
| The same as the value returned by `localeconv' in the |
| `n_cs_precedes' element of the `struct lconv'. |
| |
| `N_SEP_BY_SPACE' |
| The same as the value returned by `localeconv' in the |
| `n_sep_by_space' element of the `struct lconv'. |
| |
| `P_SIGN_POSN' |
| The same as the value returned by `localeconv' in the |
| `p_sign_posn' element of the `struct lconv'. |
| |
| `N_SIGN_POSN' |
| The same as the value returned by `localeconv' in the |
| `n_sign_posn' element of the `struct lconv'. |
| |
| `INT_P_CS_PRECEDES' |
| The same as the value returned by `localeconv' in the |
| `int_p_cs_precedes' element of the `struct lconv'. |
| |
| `INT_P_SEP_BY_SPACE' |
| The same as the value returned by `localeconv' in the |
| `int_p_sep_by_space' element of the `struct lconv'. |
| |
| `INT_N_CS_PRECEDES' |
| The same as the value returned by `localeconv' in the |
| `int_n_cs_precedes' element of the `struct lconv'. |
| |
| `INT_N_SEP_BY_SPACE' |
| The same as the value returned by `localeconv' in the |
| `int_n_sep_by_space' element of the `struct lconv'. |
| |
| `INT_P_SIGN_POSN' |
| The same as the value returned by `localeconv' in the |
| `int_p_sign_posn' element of the `struct lconv'. |
| |
| `INT_N_SIGN_POSN' |
| The same as the value returned by `localeconv' in the |
| `int_n_sign_posn' element of the `struct lconv'. |
| |
| `DECIMAL_POINT' |
| `RADIXCHAR' |
| The same as the value returned by `localeconv' in the |
| `decimal_point' element of the `struct lconv'. |
| |
| The name `RADIXCHAR' is a deprecated alias still used in |
| Unix98. |
| |
| `THOUSANDS_SEP' |
| `THOUSEP' |
| The same as the value returned by `localeconv' in the |
| `thousands_sep' element of the `struct lconv'. |
| |
| The name `THOUSEP' is a deprecated alias still used in Unix98. |
| |
| `GROUPING' |
| The same as the value returned by `localeconv' in the |
| `grouping' element of the `struct lconv'. |
| |
| `YESEXPR' |
| The return value is a regular expression which can be used |
| with the `regex' function to recognize a positive response to |
| a yes/no question. The GNU C Library provides the `rpmatch' |
| function for easier handling in applications. |
| |
| `NOEXPR' |
| The return value is a regular expression which can be used |
| with the `regex' function to recognize a negative response to |
| a yes/no question. |
| |
| `YESSTR' |
| The return value is a locale-specific translation of the |
| positive response to a yes/no question. |
| |
| Using this value is deprecated since it is a very special |
| case of message translation, and is better handled by the |
| message translation functions (*note Message Translation::). |
| |
| The use of this symbol is deprecated. Instead message |
| translation should be used. |
| |
| `NOSTR' |
| The return value is a locale-specific translation of the |
| negative response to a yes/no question. What is said for |
| `YESSTR' is also true here. |
| |
| The use of this symbol is deprecated. Instead message |
| translation should be used. |
| |
| The file `langinfo.h' defines a lot more symbols but none of them |
| are official. Using them is not portable, and the format of the |
| return values might change. Therefore we recommended you not use |
| them. |
| |
| Note that the return value for any valid argument can be used in |
| all situations (with the possible exception of the am/pm time |
| formatting codes). If the user has not selected any locale for the |
| appropriate category, `nl_langinfo' returns the information from |
| the `"C"' locale. It is therefore possible to use this function as |
| shown in the example below. |
| |
| If the argument ITEM is not valid, a pointer to an empty string is |
| returned. |
| |
| An example of `nl_langinfo' usage is a function which has to print a |
| given date and time in a locale-specific way. At first one might think |
| that, since `strftime' internally uses the locale information, writing |
| something like the following is enough: |
| |
| size_t |
| i18n_time_n_data (char *s, size_t len, const struct tm *tp) |
| { |
| return strftime (s, len, "%X %D", tp); |
| } |
| |
| The format contains no weekday or month names and therefore is |
| internationally usable. Wrong! The output produced is something like |
| `"hh:mm:ss MM/DD/YY"'. This format is only recognizable in the USA. |
| Other countries use different formats. Therefore the function should |
| be rewritten like this: |
| |
| size_t |
| i18n_time_n_data (char *s, size_t len, const struct tm *tp) |
| { |
| return strftime (s, len, nl_langinfo (D_T_FMT), tp); |
| } |
| |
| Now it uses the date and time format of the locale selected when the |
| program runs. If the user selects the locale correctly there should |
| never be a misunderstanding over the time and date format. |
| |
| |
| File: libc.info, Node: Formatting Numbers, Next: Yes-or-No Questions, Prev: Locale Information, Up: Locales |
| |
| 7.8 A dedicated function to format numbers |
| ========================================== |
| |
| We have seen that the structure returned by `localeconv' as well as the |
| values given to `nl_langinfo' allow you to retrieve the various pieces |
| of locale-specific information to format numbers and monetary amounts. |
| We have also seen that the underlying rules are quite complex. |
| |
| Therefore the X/Open standards introduce a function which uses such |
| locale information, making it easier for the user to format numbers |
| according to these rules. |
| |
| -- Function: ssize_t strfmon (char *S, size_t MAXSIZE, const char |
| *FORMAT, ...) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `strfmon' function is similar to the `strftime' function in |
| that it takes a buffer, its size, a format string, and values to |
| write into the buffer as text in a form specified by the format |
| string. Like `strftime', the function also returns the number of |
| bytes written into the buffer. |
| |
| There are two differences: `strfmon' can take more than one |
| argument, and, of course, the format specification is different. |
| Like `strftime', the format string consists of normal text, which |
| is output as is, and format specifiers, which are indicated by a |
| `%'. Immediately after the `%', you can optionally specify |
| various flags and formatting information before the main |
| formatting character, in a similar way to `printf': |
| |
| * Immediately following the `%' there can be one or more of the |
| following flags: |
| `=F' |
| The single byte character F is used for this field as |
| the numeric fill character. By default this character |
| is a space character. Filling with this character is |
| only performed if a left precision is specified. It is |
| not just to fill to the given field width. |
| |
| `^' |
| The number is printed without grouping the digits |
| according to the rules of the current locale. By |
| default grouping is enabled. |
| |
| `+', `(' |
| At most one of these flags can be used. They select |
| which format to represent the sign of a currency amount. |
| By default, and if `+' is given, the locale equivalent |
| of +/- is used. If `(' is given, negative amounts are |
| enclosed in parentheses. The exact format is determined |
| by the values of the `LC_MONETARY' category of the |
| locale selected at program runtime. |
| |
| `!' |
| The output will not contain the currency symbol. |
| |
| `-' |
| The output will be formatted left-justified instead of |
| right-justified if it does not fill the entire field |
| width. |
| |
| The next part of the specification is an optional field width. If |
| no width is specified 0 is taken. During output, the function |
| first determines how much space is required. If it requires at |
| least as many characters as given by the field width, it is output |
| using as much space as necessary. Otherwise, it is extended to |
| use the full width by filling with the space character. The |
| presence or absence of the `-' flag determines the side at which |
| such padding occurs. If present, the spaces are added at the |
| right making the output left-justified, and vice versa. |
| |
| So far the format looks familiar, being similar to the `printf' and |
| `strftime' formats. However, the next two optional fields |
| introduce something new. The first one is a `#' character followed |
| by a decimal digit string. The value of the digit string |
| specifies the number of _digit_ positions to the left of the |
| decimal point (or equivalent). This does _not_ include the |
| grouping character when the `^' flag is not given. If the space |
| needed to print the number does not fill the whole width, the |
| field is padded at the left side with the fill character, which |
| can be selected using the `=' flag and by default is a space. For |
| example, if the field width is selected as 6 and the number is |
| 123, the fill character is `*' the result will be `***123'. |
| |
| The second optional field starts with a `.' (period) and consists |
| of another decimal digit string. Its value describes the number of |
| characters printed after the decimal point. The default is |
| selected from the current locale (`frac_digits', |
| `int_frac_digits', see *note General Numeric::). If the exact |
| representation needs more digits than given by the field width, |
| the displayed value is rounded. If the number of fractional |
| digits is selected to be zero, no decimal point is printed. |
| |
| As a GNU extension, the `strfmon' implementation in the GNU C |
| Library allows an optional `L' next as a format modifier. If this |
| modifier is given, the argument is expected to be a `long double' |
| instead of a `double' value. |
| |
| Finally, the last component is a format specifier. There are three |
| specifiers defined: |
| |
| `i' |
| Use the locale's rules for formatting an international |
| currency value. |
| |
| `n' |
| Use the locale's rules for formatting a national currency |
| value. |
| |
| `%' |
| Place a `%' in the output. There must be no flag, width |
| specifier or modifier given, only `%%' is allowed. |
| |
| As for `printf', the function reads the format string from left to |
| right and uses the values passed to the function following the |
| format string. The values are expected to be either of type |
| `double' or `long double', depending on the presence of the |
| modifier `L'. The result is stored in the buffer pointed to by S. |
| At most MAXSIZE characters are stored. |
| |
| The return value of the function is the number of characters |
| stored in S, including the terminating `NULL' byte. If the number |
| of characters stored would exceed MAXSIZE, the function returns -1 |
| and the content of the buffer S is unspecified. In this case |
| `errno' is set to `E2BIG'. |
| |
| A few examples should make clear how the function works. It is |
| assumed that all the following pieces of code are executed in a program |
| which uses the USA locale (`en_US'). The simplest form of the format |
| is this: |
| |
| strfmon (buf, 100, "@%n@%n@%n@", 123.45, -567.89, 12345.678); |
| |
| The output produced is |
| "@$123.45@-$567.89@$12,345.68@" |
| |
| We can notice several things here. First, the widths of the output |
| numbers are different. We have not specified a width in the format |
| string, and so this is no wonder. Second, the third number is printed |
| using thousands separators. The thousands separator for the `en_US' |
| locale is a comma. The number is also rounded. .678 is rounded to .68 |
| since the format does not specify a precision and the default value in |
| the locale is 2. Finally, note that the national currency symbol is |
| printed since `%n' was used, not `i'. The next example shows how we |
| can align the output. |
| |
| strfmon (buf, 100, "@%=*11n@%=*11n@%=*11n@", 123.45, -567.89, 12345.678); |
| |
| The output this time is: |
| |
| "@ $123.45@ -$567.89@ $12,345.68@" |
| |
| Two things stand out. Firstly, all fields have the same width |
| (eleven characters) since this is the width given in the format and |
| since no number required more characters to be printed. The second |
| important point is that the fill character is not used. This is |
| correct since the white space was not used to achieve a precision given |
| by a `#' modifier, but instead to fill to the given width. The |
| difference becomes obvious if we now add a width specification. |
| |
| strfmon (buf, 100, "@%=*11#5n@%=*11#5n@%=*11#5n@", |
| 123.45, -567.89, 12345.678); |
| |
| The output is |
| |
| "@ $***123.45@-$***567.89@ $12,456.68@" |
| |
| Here we can see that all the currency symbols are now aligned, and |
| that the space between the currency sign and the number is filled with |
| the selected fill character. Note that although the width is selected |
| to be 5 and 123.45 has three digits left of the decimal point, the |
| space is filled with three asterisks. This is correct since, as |
| explained above, the width does not include the positions used to store |
| thousands separators. One last example should explain the remaining |
| functionality. |
| |
| strfmon (buf, 100, "@%=0(16#5.3i@%=0(16#5.3i@%=0(16#5.3i@", |
| 123.45, -567.89, 12345.678); |
| |
| This rather complex format string produces the following output: |
| |
| "@ USD 000123,450 @(USD 000567.890)@ USD 12,345.678 @" |
| |
| The most noticeable change is the alternative way of representing |
| negative numbers. In financial circles this is often done using |
| parentheses, and this is what the `(' flag selected. The fill |
| character is now `0'. Note that this `0' character is not regarded as |
| a numeric zero, and therefore the first and second numbers are not |
| printed using a thousands separator. Since we used the format |
| specifier `i' instead of `n', the international form of the currency |
| symbol is used. This is a four letter string, in this case `"USD "'. |
| The last point is that since the precision right of the decimal point |
| is selected to be three, the first and second numbers are printed with |
| an extra zero at the end and the third number is printed without |
| rounding. |
| |
| |
| File: libc.info, Node: Yes-or-No Questions, Prev: Formatting Numbers, Up: Locales |
| |
| 7.9 Yes-or-No Questions |
| ======================= |
| |
| Some non GUI programs ask a yes-or-no question. If the messages |
| (especially the questions) are translated into foreign languages, be |
| sure that you localize the answers too. It would be very bad habit to |
| ask a question in one language and request the answer in another, often |
| English. |
| |
| The GNU C Library contains `rpmatch' to give applications easy |
| access to the corresponding locale definitions. |
| |
| -- Function: int rpmatch (const char *RESPONSE) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen |
| | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::. |
| |
| The function `rpmatch' checks the string in RESPONSE for whether |
| or not it is a correct yes-or-no answer and if yes, which one. The |
| check uses the `YESEXPR' and `NOEXPR' data in the `LC_MESSAGES' |
| category of the currently selected locale. The return value is as |
| follows: |
| |
| `1' |
| The user entered an affirmative answer. |
| |
| `0' |
| The user entered a negative answer. |
| |
| `-1' |
| The answer matched neither the `YESEXPR' nor the `NOEXPR' |
| regular expression. |
| |
| This function is not standardized but available beside in the GNU |
| C Library at least also in the IBM AIX library. |
| |
| This function would normally be used like this: |
| |
| ... |
| /* Use a safe default. */ |
| _Bool doit = false; |
| |
| fputs (gettext ("Do you really want to do this? "), stdout); |
| fflush (stdout); |
| /* Prepare the `getline' call. */ |
| line = NULL; |
| len = 0; |
| while (getline (&line, &len, stdin) >= 0) |
| { |
| /* Check the response. */ |
| int res = rpmatch (line); |
| if (res >= 0) |
| { |
| /* We got a definitive answer. */ |
| if (res > 0) |
| doit = true; |
| break; |
| } |
| } |
| /* Free what `getline' allocated. */ |
| free (line); |
| |
| Note that the loop continues until a read error is detected or until |
| a definitive (positive or negative) answer is read. |
| |
| |
| File: libc.info, Node: Message Translation, Next: Searching and Sorting, Prev: Locales, Up: Top |
| |
| 8 Message Translation |
| ********************* |
| |
| The program's interface with the user should be designed to ease the |
| user's task. One way to ease the user's task is to use messages in |
| whatever language the user prefers. |
| |
| Printing messages in different languages can be implemented in |
| different ways. One could add all the different languages in the |
| source code and choose among the variants every time a message has to |
| be printed. This is certainly not a good solution since extending the |
| set of languages is cumbersome (the code must be changed) and the code |
| itself can become really big with dozens of message sets. |
| |
| A better solution is to keep the message sets for each language in |
| separate files which are loaded at runtime depending on the language |
| selection of the user. |
| |
| The GNU C Library provides two different sets of functions to support |
| message translation. The problem is that neither of the interfaces is |
| officially defined by the POSIX standard. The `catgets' family of |
| functions is defined in the X/Open standard but this is derived from |
| industry decisions and therefore not necessarily based on reasonable |
| decisions. |
| |
| As mentioned above, the message catalog handling provides easy |
| extendability by using external data files which contain the message |
| translations. I.e., these files contain for each of the messages used |
| in the program a translation for the appropriate language. So the tasks |
| of the message handling functions are |
| |
| * locate the external data file with the appropriate translations |
| |
| * load the data and make it possible to address the messages |
| |
| * map a given key to the translated message |
| |
| The two approaches mainly differ in the implementation of this last |
| step. Decisions made in the last step influence the rest of the design. |
| |
| * Menu: |
| |
| * Message catalogs a la X/Open:: The `catgets' family of functions. |
| * The Uniforum approach:: The `gettext' family of functions. |
| |
| |
| File: libc.info, Node: Message catalogs a la X/Open, Next: The Uniforum approach, Up: Message Translation |
| |
| 8.1 X/Open Message Catalog Handling |
| =================================== |
| |
| The `catgets' functions are based on the simple scheme: |
| |
| Associate every message to translate in the source code with a |
| unique identifier. To retrieve a message from a catalog file |
| solely the identifier is used. |
| |
| This means for the author of the program that s/he will have to make |
| sure the meaning of the identifier in the program code and in the |
| message catalogs is always the same. |
| |
| Before a message can be translated the catalog file must be located. |
| The user of the program must be able to guide the responsible function |
| to find whatever catalog the user wants. This is separated from what |
| the programmer had in mind. |
| |
| All the types, constants and functions for the `catgets' functions |
| are defined/declared in the `nl_types.h' header file. |
| |
| * Menu: |
| |
| * The catgets Functions:: The `catgets' function family. |
| * The message catalog files:: Format of the message catalog files. |
| * The gencat program:: How to generate message catalogs files which |
| can be used by the functions. |
| * Common Usage:: How to use the `catgets' interface. |
| |
| |
| File: libc.info, Node: The catgets Functions, Next: The message catalog files, Up: Message catalogs a la X/Open |
| |
| 8.1.1 The `catgets' function family |
| ----------------------------------- |
| |
| -- Function: nl_catd catopen (const char *CAT_NAME, int FLAG) |
| Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `catopen' function tries to locate the message data file named |
| CAT_NAME and loads it when found. The return value is of an |
| opaque type and can be used in calls to the other functions to |
| refer to this loaded catalog. |
| |
| The return value is `(nl_catd) -1' in case the function failed and |
| no catalog was loaded. The global variable `errno' contains a code |
| for the error causing the failure. But even if the function call |
| succeeded this does not mean that all messages can be translated. |
| |
| Locating the catalog file must happen in a way which lets the user |
| of the program influence the decision. It is up to the user to |
| decide about the language to use and sometimes it is useful to use |
| alternate catalog files. All this can be specified by the user by |
| setting some environment variables. |
| |
| The first problem is to find out where all the message catalogs are |
| stored. Every program could have its own place to keep all the |
| different files but usually the catalog files are grouped by |
| languages and the catalogs for all programs are kept in the same |
| place. |
| |
| To tell the `catopen' function where the catalog for the program |
| can be found the user can set the environment variable `NLSPATH' to |
| a value which describes her/his choice. Since this value must be |
| usable for different languages and locales it cannot be a simple |
| string. Instead it is a format string (similar to `printf''s). |
| An example is |
| |
| /usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N |
| |
| First one can see that more than one directory can be specified |
| (with the usual syntax of separating them by colons). The next |
| things to observe are the format string, `%L' and `%N' in this |
| case. The `catopen' function knows about several of them and the |
| replacement for all of them is of course different. |
| |
| `%N' |
| This format element is substituted with the name of the |
| catalog file. This is the value of the CAT_NAME argument |
| given to `catgets'. |
| |
| `%L' |
| This format element is substituted with the name of the |
| currently selected locale for translating messages. How this |
| is determined is explained below. |
| |
| `%l' |
| (This is the lowercase ell.) This format element is |
| substituted with the language element of the locale name. |
| The string describing the selected locale is expected to have |
| the form `LANG[_TERR[.CODESET]]' and this format uses the |
| first part LANG. |
| |
| `%t' |
| This format element is substituted by the territory part TERR |
| of the name of the currently selected locale. See the |
| explanation of the format above. |
| |
| `%c' |
| This format element is substituted by the codeset part |
| CODESET of the name of the currently selected locale. See |
| the explanation of the format above. |
| |
| `%%' |
| Since `%' is used as a meta character there must be a way to |
| express the `%' character in the result itself. Using `%%' |
| does this just like it works for `printf'. |
| |
| Using `NLSPATH' allows arbitrary directories to be searched for |
| message catalogs while still allowing different languages to be |
| used. If the `NLSPATH' environment variable is not set, the |
| default value is |
| |
| PREFIX/share/locale/%L/%N:PREFIX/share/locale/%L/LC_MESSAGES/%N |
| |
| where PREFIX is given to `configure' while installing the GNU C |
| Library (this value is in many cases `/usr' or the empty string). |
| |
| The remaining problem is to decide which must be used. The value |
| decides about the substitution of the format elements mentioned |
| above. First of all the user can specify a path in the message |
| catalog name (i.e., the name contains a slash character). In this |
| situation the `NLSPATH' environment variable is not used. The |
| catalog must exist as specified in the program, perhaps relative |
| to the current working directory. This situation in not desirable |
| and catalogs names never should be written this way. Beside this, |
| this behavior is not portable to all other platforms providing the |
| `catgets' interface. |
| |
| Otherwise the values of environment variables from the standard |
| environment are examined (*note Standard Environment::). Which |
| variables are examined is decided by the FLAG parameter of |
| `catopen'. If the value is `NL_CAT_LOCALE' (which is defined in |
| `nl_types.h') then the `catopen' function uses the name of the |
| locale currently selected for the `LC_MESSAGES' category. |
| |
| If FLAG is zero the `LANG' environment variable is examined. This |
| is a left-over from the early days when the concept of locales had |
| not even reached the level of POSIX locales. |
| |
| The environment variable and the locale name should have a value |
| of the form `LANG[_TERR[.CODESET]]' as explained above. If no |
| environment variable is set the `"C"' locale is used which |
| prevents any translation. |
| |
| The return value of the function is in any case a valid string. |
| Either it is a translation from a message catalog or it is the |
| same as the STRING parameter. So a piece of code to decide |
| whether a translation actually happened must look like this: |
| |
| { |
| char *trans = catgets (desc, set, msg, input_string); |
| if (trans == input_string) |
| { |
| /* Something went wrong. */ |
| } |
| } |
| |
| When an error occurs the global variable `errno' is set to |
| |
| EBADF |
| The catalog does not exist. |
| |
| ENOMSG |
| The set/message tuple does not name an existing element in the |
| message catalog. |
| |
| While it sometimes can be useful to test for errors programs |
| normally will avoid any test. If the translation is not available |
| it is no big problem if the original, untranslated message is |
| printed. Either the user understands this as well or s/he will |
| look for the reason why the messages are not translated. |
| |
| Please note that the currently selected locale does not depend on a |
| call to the `setlocale' function. It is not necessary that the locale |
| data files for this locale exist and calling `setlocale' succeeds. The |
| `catopen' function directly reads the values of the environment |
| variables. |
| |
| -- Function: char * catgets (nl_catd CATALOG_DESC, int SET, int |
| MESSAGE, const char *STRING) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The function `catgets' has to be used to access the message catalog |
| previously opened using the `catopen' function. The CATALOG_DESC |
| parameter must be a value previously returned by `catopen'. |
| |
| The next two parameters, SET and MESSAGE, reflect the internal |
| organization of the message catalog files. This will be explained |
| in detail below. For now it is interesting to know that a catalog |
| can consist of several sets and the messages in each thread are |
| individually numbered using numbers. Neither the set number nor |
| the message number must be consecutive. They can be arbitrarily |
| chosen. But each message (unless equal to another one) must have |
| its own unique pair of set and message numbers. |
| |
| Since it is not guaranteed that the message catalog for the |
| language selected by the user exists the last parameter STRING |
| helps to handle this case gracefully. If no matching string can |
| be found STRING is returned. This means for the programmer that |
| |
| * the STRING parameters should contain reasonable text (this |
| also helps to understand the program seems otherwise there |
| would be no hint on the string which is expected to be |
| returned. |
| |
| * all STRING arguments should be written in the same language. |
| |
| It is somewhat uncomfortable to write a program using the `catgets' |
| functions if no supporting functionality is available. Since each |
| set/message number tuple must be unique the programmer must keep lists |
| of the messages at the same time the code is written. And the work |
| between several people working on the same project must be coordinated. |
| We will see how some of these problems can be relaxed a bit (*note |
| Common Usage::). |
| |
| -- Function: int catclose (nl_catd CATALOG_DESC) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe corrupt mem | |
| *Note POSIX Safety Concepts::. |
| |
| The `catclose' function can be used to free the resources |
| associated with a message catalog which previously was opened by a |
| call to `catopen'. If the resources can be successfully freed the |
| function returns `0'. Otherwise it returns `-1' and the global |
| variable `errno' is set. Errors can occur if the catalog |
| descriptor CATALOG_DESC is not valid in which case `errno' is set |
| to `EBADF'. |
| |
| |
| 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. |
| |
| 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::). |
| |
| |
| File: libc.info, Node: Character Input, Next: Line Input, Prev: Simple Output, Up: I/O on Streams |
| |
| 12.8 Character Input |
| ==================== |
| |
| This section describes functions for performing character-oriented |
| input. These narrow stream functions are declared in the header file |
| `stdio.h' and the wide character functions are declared in `wchar.h'. |
| |
| These functions return an `int' or `wint_t' value (for narrow and |
| wide stream functions respectively) that is either a character of |
| input, or the special value `EOF'/`WEOF' (usually -1). For the narrow |
| stream functions it is important to store the result of these functions |
| in a variable of type `int' instead of `char', even when you plan to |
| use it only as a character. Storing `EOF' in a `char' variable |
| truncates its value to the size of a character, so that it is no longer |
| distinguishable from the valid character `(char) -1'. So always use an |
| `int' for the result of `getc' and friends, and check for `EOF' after |
| the call; once you've verified that the result is not `EOF', you can be |
| sure that it will fit in a `char' variable without loss of information. |
| |
| -- Function: int fgetc (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function reads the next character as an `unsigned char' from |
| the stream STREAM and returns its value, converted to an `int'. |
| If an end-of-file condition or read error occurs, `EOF' is |
| returned instead. |
| |
| -- Function: wint_t fgetwc (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function reads the next wide character from the stream STREAM |
| and returns its value. If an end-of-file condition or read error |
| occurs, `WEOF' is returned instead. |
| |
| -- Function: int fgetc_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `fgetc_unlocked' function is equivalent to the `fgetc' |
| function except that it does not implicitly lock the stream. |
| |
| -- Function: wint_t fgetwc_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `fgetwc_unlocked' function is equivalent to the `fgetwc' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| -- Function: int getc (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This is just like `fgetc', except that it is permissible (and |
| typical) for it to be implemented as a macro that evaluates the |
| STREAM argument more than once. `getc' is often highly optimized, |
| so it is usually the best function to use to read a single |
| character. |
| |
| -- Function: wint_t getwc (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This is just like `fgetwc', except that it is permissible for it to |
| be implemented as a macro that evaluates the STREAM argument more |
| than once. `getwc' can be highly optimized, so it is usually the |
| best function to use to read a single wide character. |
| |
| -- Function: int getc_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `getc_unlocked' function is equivalent to the `getc' function |
| except that it does not implicitly lock the stream. |
| |
| -- Function: wint_t getwc_unlocked (FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `getwc_unlocked' function is equivalent to the `getwc' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| -- Function: int getchar (void) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `getchar' function is equivalent to `getc' with `stdin' as the |
| value of the STREAM argument. |
| |
| -- Function: wint_t getwchar (void) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `getwchar' function is equivalent to `getwc' with `stdin' as |
| the value of the STREAM argument. |
| |
| -- Function: int getchar_unlocked (void) |
| Preliminary: | MT-Unsafe race:stdin | AS-Unsafe corrupt | |
| AC-Unsafe corrupt | *Note POSIX Safety Concepts::. |
| |
| The `getchar_unlocked' function is equivalent to the `getchar' |
| function except that it does not implicitly lock the stream. |
| |
| -- Function: wint_t getwchar_unlocked (void) |
| Preliminary: | MT-Unsafe race:stdin | AS-Unsafe corrupt | |
| AC-Unsafe corrupt | *Note POSIX Safety Concepts::. |
| |
| The `getwchar_unlocked' function is equivalent to the `getwchar' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| Here is an example of a function that does input using `fgetc'. It |
| would work just as well using `getc' instead, or using `getchar ()' |
| instead of `fgetc (stdin)'. The code would also work the same for the |
| wide character stream functions. |
| |
| int |
| y_or_n_p (const char *question) |
| { |
| fputs (question, stdout); |
| while (1) |
| { |
| int c, answer; |
| /* Write a space to separate answer from question. */ |
| fputc (' ', stdout); |
| /* Read the first character of the line. |
| This should be the answer character, but might not be. */ |
| c = tolower (fgetc (stdin)); |
| answer = c; |
| /* Discard rest of input line. */ |
| while (c != '\n' && c != EOF) |
| c = fgetc (stdin); |
| /* Obey the answer if it was valid. */ |
| if (answer == 'y') |
| return 1; |
| if (answer == 'n') |
| return 0; |
| /* Answer was invalid: ask for valid answer. */ |
| fputs ("Please answer y or n:", stdout); |
| } |
| } |
| |
| -- Function: int getw (FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function reads a word (that is, an `int') from STREAM. It's |
| provided for compatibility with SVID. We recommend you use |
| `fread' instead (*note Block Input/Output::). Unlike `getc', any |
| `int' value could be a valid result. `getw' returns `EOF' when it |
| encounters end-of-file or an error, but there is no way to |
| distinguish this from an input word with value -1. |
| |
| |
| File: libc.info, Node: Line Input, Next: Unreading, Prev: Character Input, Up: I/O on Streams |
| |
| 12.9 Line-Oriented Input |
| ======================== |
| |
| Since many programs interpret input on the basis of lines, it is |
| convenient to have functions to read a line of text from a stream. |
| |
| Standard C has functions to do this, but they aren't very safe: null |
| characters and even (for `gets') long lines can confuse them. So the |
| GNU C Library provides the nonstandard `getline' function that makes it |
| easy to read lines reliably. |
| |
| Another GNU extension, `getdelim', generalizes `getline'. It reads |
| a delimited record, defined as everything through the next occurrence |
| of a specified delimiter character. |
| |
| All these functions are declared in `stdio.h'. |
| |
| -- Function: ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| This function reads an entire line from STREAM, storing the text |
| (including the newline and a terminating null character) in a |
| buffer and storing the buffer address in `*LINEPTR'. |
| |
| Before calling `getline', you should place in `*LINEPTR' the |
| address of a buffer `*N' bytes long, allocated with `malloc'. If |
| this buffer is long enough to hold the line, `getline' stores the |
| line in this buffer. Otherwise, `getline' makes the buffer bigger |
| using `realloc', storing the new buffer address back in `*LINEPTR' |
| and the increased size back in `*N'. *Note Unconstrained |
| Allocation::. |
| |
| If you set `*LINEPTR' to a null pointer, and `*N' to zero, before |
| the call, then `getline' allocates the initial buffer for you by |
| calling `malloc'. This buffer remains allocated even if `getline' |
| encounters errors and is unable to read any bytes. |
| |
| In either case, when `getline' returns, `*LINEPTR' is a `char *' |
| which points to the text of the line. |
| |
| When `getline' is successful, it returns the number of characters |
| read (including the newline, but not including the terminating |
| null). This value enables you to distinguish null characters that |
| are part of the line from the null character inserted as a |
| terminator. |
| |
| This function is a GNU extension, but it is the recommended way to |
| read lines from a stream. The alternative standard functions are |
| unreliable. |
| |
| If an error occurs or end of file is reached without any bytes |
| read, `getline' returns `-1'. |
| |
| -- Function: ssize_t getdelim (char **LINEPTR, size_t *N, int |
| DELIMITER, FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock |
| corrupt mem | *Note POSIX Safety Concepts::. |
| |
| This function is like `getline' except that the character which |
| tells it to stop reading is not necessarily newline. The argument |
| DELIMITER specifies the delimiter character; `getdelim' keeps |
| reading until it sees that character (or end of file). |
| |
| The text is stored in LINEPTR, including the delimiter character |
| and a terminating null. Like `getline', `getdelim' makes LINEPTR |
| bigger if it isn't big enough. |
| |
| `getline' is in fact implemented in terms of `getdelim', just like |
| this: |
| |
| ssize_t |
| getline (char **lineptr, size_t *n, FILE *stream) |
| { |
| return getdelim (lineptr, n, '\n', stream); |
| } |
| |
| -- Function: char * fgets (char *S, int COUNT, FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `fgets' function reads characters from the stream STREAM up to |
| and including a newline character and stores them in the string S, |
| adding a null character to mark the end of the string. You must |
| supply COUNT characters worth of space in S, but the number of |
| characters read is at most COUNT - 1. The extra character space |
| is used to hold the null character at the end of the string. |
| |
| If the system is already at end of file when you call `fgets', then |
| the contents of the array S are unchanged and a null pointer is |
| returned. A null pointer is also returned if a read error occurs. |
| Otherwise, the return value is the pointer S. |
| |
| *Warning:* If the input data has a null character, you can't tell. |
| So don't use `fgets' unless you know the data cannot contain a |
| null. Don't use it to read files edited by the user because, if |
| the user inserts a null character, you should either handle it |
| properly or print a clear error message. We recommend using |
| `getline' instead of `fgets'. |
| |
| -- Function: wchar_t * fgetws (wchar_t *WS, int COUNT, FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `fgetws' function reads wide characters from the stream STREAM |
| up to and including a newline character and stores them in the |
| string WS, adding a null wide character to mark the end of the |
| string. You must supply COUNT wide characters worth of space in |
| WS, but the number of characters read is at most COUNT - 1. The |
| extra character space is used to hold the null wide character at |
| the end of the string. |
| |
| If the system is already at end of file when you call `fgetws', |
| then the contents of the array WS are unchanged and a null pointer |
| is returned. A null pointer is also returned if a read error |
| occurs. Otherwise, the return value is the pointer WS. |
| |
| *Warning:* If the input data has a null wide character (which are |
| null bytes in the input stream), you can't tell. So don't use |
| `fgetws' unless you know the data cannot contain a null. Don't use |
| it to read files edited by the user because, if the user inserts a |
| null character, you should either handle it properly or print a |
| clear error message. |
| |
| -- Function: char * fgets_unlocked (char *S, int COUNT, FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `fgets_unlocked' function is equivalent to the `fgets' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| -- Function: wchar_t * fgetws_unlocked (wchar_t *WS, int COUNT, FILE |
| *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `fgetws_unlocked' function is equivalent to the `fgetws' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| -- Deprecated function: char * gets (char *S) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The function `gets' reads characters from the stream `stdin' up to |
| the next newline character, and stores them in the string S. The |
| newline character is discarded (note that this differs from the |
| behavior of `fgets', which copies the newline character into the |
| string). If `gets' encounters a read error or end-of-file, it |
| returns a null pointer; otherwise it returns S. |
| |
| *Warning:* The `gets' function is *very dangerous* because it |
| provides no protection against overflowing the string S. The GNU |
| C Library includes it for compatibility only. You should *always* |
| use `fgets' or `getline' instead. To remind you of this, the |
| linker (if using GNU `ld') will issue a warning whenever you use |
| `gets'. |
| |
| |
| File: libc.info, Node: Unreading, Next: Block Input/Output, Prev: Line Input, Up: I/O on Streams |
| |
| 12.10 Unreading |
| =============== |
| |
| In parser programs it is often useful to examine the next character in |
| the input stream without removing it from the stream. This is called |
| "peeking ahead" at the input because your program gets a glimpse of the |
| input it will read next. |
| |
| Using stream I/O, you can peek ahead at input by first reading it and |
| then "unreading" it (also called "pushing it back" on the stream). |
| Unreading a character makes it available to be input again from the |
| stream, by the next call to `fgetc' or other input function on that |
| stream. |
| |
| * Menu: |
| |
| * Unreading Idea:: An explanation of unreading with pictures. |
| * How Unread:: How to call `ungetc' to do unreading. |
| |
| |
| File: libc.info, Node: Unreading Idea, Next: How Unread, Up: Unreading |
| |
| 12.10.1 What Unreading Means |
| ---------------------------- |
| |
| Here is a pictorial explanation of unreading. Suppose you have a |
| stream reading a file that contains just six characters, the letters |
| `foobar'. Suppose you have read three characters so far. The |
| situation looks like this: |
| |
| f o o b a r |
| ^ |
| |
| so the next input character will be `b'. |
| |
| If instead of reading `b' you unread the letter `o', you get a |
| situation like this: |
| |
| f o o b a r |
| | |
| o-- |
| ^ |
| |
| so that the next input characters will be `o' and `b'. |
| |
| If you unread `9' instead of `o', you get this situation: |
| |
| f o o b a r |
| | |
| 9-- |
| ^ |
| |
| so that the next input characters will be `9' and `b'. |
| |
| |
| File: libc.info, Node: How Unread, Prev: Unreading Idea, Up: Unreading |
| |
| 12.10.2 Using `ungetc' To Do Unreading |
| -------------------------------------- |
| |
| The function to unread a character is called `ungetc', because it |
| reverses the action of `getc'. |
| |
| -- Function: int ungetc (int C, FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `ungetc' function pushes back the character C onto the input |
| stream STREAM. So the next input from STREAM will read C before |
| anything else. |
| |
| If C is `EOF', `ungetc' does nothing and just returns `EOF'. This |
| lets you call `ungetc' with the return value of `getc' without |
| needing to check for an error from `getc'. |
| |
| The character that you push back doesn't have to be the same as |
| the last character that was actually read from the stream. In |
| fact, it isn't necessary to actually read any characters from the |
| stream before unreading them with `ungetc'! But that is a strange |
| way to write a program; usually `ungetc' is used only to unread a |
| character that was just read from the same stream. The GNU C |
| Library supports this even on files opened in binary mode, but |
| other systems might not. |
| |
| The GNU C Library only supports one character of pushback--in other |
| words, it does not work to call `ungetc' twice without doing input |
| in between. Other systems might let you push back multiple |
| characters; then reading from the stream retrieves the characters |
| in the reverse order that they were pushed. |
| |
| Pushing back characters doesn't alter the file; only the internal |
| buffering for the stream is affected. If a file positioning |
| function (such as `fseek', `fseeko' or `rewind'; *note File |
| Positioning::) is called, any pending pushed-back characters are |
| discarded. |
| |
| Unreading a character on a stream that is at end of file clears the |
| end-of-file indicator for the stream, because it makes the |
| character of input available. After you read that character, |
| trying to read again will encounter end of file. |
| |
| -- Function: wint_t ungetwc (wint_t WC, FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| The `ungetwc' function behaves just like `ungetc' just that it |
| pushes back a wide character. |
| |
| Here is an example showing the use of `getc' and `ungetc' to skip |
| over whitespace characters. When this function reaches a |
| non-whitespace character, it unreads that character to be seen again on |
| the next read operation on the stream. |
| |
| #include <stdio.h> |
| #include <ctype.h> |
| |
| void |
| skip_whitespace (FILE *stream) |
| { |
| int c; |
| do |
| /* No need to check for `EOF' because it is not |
| `isspace', and `ungetc' ignores `EOF'. */ |
| c = getc (stream); |
| while (isspace (c)); |
| ungetc (c, stream); |
| } |
| |
| |
| File: libc.info, Node: Block Input/Output, Next: Formatted Output, Prev: Unreading, Up: I/O on Streams |
| |
| 12.11 Block Input/Output |
| ======================== |
| |
| This section describes how to do input and output operations on blocks |
| of data. You can use these functions to read and write binary data, as |
| well as to read and write text in fixed-size blocks instead of by |
| characters or lines. |
| |
| Binary files are typically used to read and write blocks of data in |
| the same format as is used to represent the data in a running program. |
| In other words, arbitrary blocks of memory--not just character or string |
| objects--can be written to a binary file, and meaningfully read in |
| again by the same program. |
| |
| Storing data in binary form is often considerably more efficient than |
| using the formatted I/O functions. Also, for floating-point numbers, |
| the binary form avoids possible loss of precision in the conversion |
| process. On the other hand, binary files can't be examined or modified |
| easily using many standard file utilities (such as text editors), and |
| are not portable between different implementations of the language, or |
| different kinds of computers. |
| |
| These functions are declared in `stdio.h'. |
| |
| -- Function: size_t fread (void *DATA, size_t SIZE, size_t COUNT, FILE |
| *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function reads up to COUNT objects of size SIZE into the |
| array DATA, from the stream STREAM. It returns the number of |
| objects actually read, which might be less than COUNT if a read |
| error occurs or the end of the file is reached. This function |
| returns a value of zero (and doesn't read anything) if either SIZE |
| or COUNT is zero. |
| |
| If `fread' encounters end of file in the middle of an object, it |
| returns the number of complete objects read, and discards the |
| partial object. Therefore, the stream remains at the actual end |
| of the file. |
| |
| -- Function: size_t fread_unlocked (void *DATA, size_t SIZE, size_t |
| COUNT, FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `fread_unlocked' function is equivalent to the `fread' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| -- Function: size_t fwrite (const void *DATA, size_t SIZE, size_t |
| COUNT, FILE *STREAM) |
| Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt |
| | *Note POSIX Safety Concepts::. |
| |
| This function writes up to COUNT objects of size SIZE from the |
| array DATA, to the stream STREAM. The return value is normally |
| COUNT, if the call succeeds. Any other value indicates some sort |
| of error, such as running out of space. |
| |
| -- Function: size_t fwrite_unlocked (const void *DATA, size_t SIZE, |
| size_t COUNT, FILE *STREAM) |
| Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `fwrite_unlocked' function is equivalent to the `fwrite' |
| function except that it does not implicitly lock the stream. |
| |
| This function is a GNU extension. |
| |
| |
| File: libc.info, Node: Formatted Output, Next: Customizing Printf, Prev: Block Input/Output, Up: I/O on Streams |
| |
| 12.12 Formatted Output |
| ====================== |
| |
| The functions described in this section (`printf' and related |
| functions) provide a convenient way to perform formatted output. You |
| call `printf' with a "format string" or "template string" that |
| specifies how to format the values of the remaining arguments. |
| |
| Unless your program is a filter that specifically performs line- or |
| character-oriented processing, using `printf' or one of the other |
| related functions described in this section is usually the easiest and |
| most concise way to perform output. These functions are especially |
| useful for printing error messages, tables of data, and the like. |
| |
| * Menu: |
| |
| * Formatted Output Basics:: Some examples to get you started. |
| * Output Conversion Syntax:: General syntax of conversion |
| specifications. |
| * Table of Output Conversions:: Summary of output conversions and |
| what they do. |
| * Integer Conversions:: Details about formatting of integers. |
| * Floating-Point Conversions:: Details about formatting of |
| floating-point numbers. |
| * Other Output Conversions:: Details about formatting of strings, |
| characters, pointers, and the like. |
| * Formatted Output Functions:: Descriptions of the actual functions. |
| * Dynamic Output:: Functions that allocate memory for the output. |
| * Variable Arguments Output:: `vprintf' and friends. |
| * Parsing a Template String:: What kinds of args does a given template |
| call for? |
| * Example of Parsing:: Sample program using `parse_printf_format'. |
| |
| |
| File: libc.info, Node: Formatted Output Basics, Next: Output Conversion Syntax, Up: Formatted Output |
| |
| 12.12.1 Formatted Output Basics |
| ------------------------------- |
| |
| The `printf' function can be used to print any number of arguments. |
| The template string argument you supply in a call provides information |
| not only about the number of additional arguments, but also about their |
| types and what style should be used for printing them. |
| |
| Ordinary characters in the template string are simply written to the |
| output stream as-is, while "conversion specifications" introduced by a |
| `%' character in the template cause subsequent arguments to be |
| formatted and written to the output stream. For example, |
| |
| int pct = 37; |
| char filename[] = "foo.txt"; |
| printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n", |
| filename, pct); |
| |
| produces output like |
| |
| Processing of `foo.txt' is 37% finished. |
| Please be patient. |
| |
| This example shows the use of the `%d' conversion to specify that an |
| `int' argument should be printed in decimal notation, the `%s' |
| conversion to specify printing of a string argument, and the `%%' |
| conversion to print a literal `%' character. |
| |
| There are also conversions for printing an integer argument as an |
| unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or |
| `%x', respectively); or as a character value (`%c'). |
| |
| Floating-point numbers can be printed in normal, fixed-point notation |
| using the `%f' conversion or in exponential notation using the `%e' |
| conversion. The `%g' conversion uses either `%e' or `%f' format, |
| depending on what is more appropriate for the magnitude of the |
| particular number. |
| |
| You can control formatting more precisely by writing "modifiers" |
| between the `%' and the character that indicates which conversion to |
| apply. These slightly alter the ordinary behavior of the conversion. |
| For example, most conversion specifications permit you to specify a |
| minimum field width and a flag indicating whether you want the result |
| left- or right-justified within the field. |
| |
| The specific flags and modifiers that are permitted and their |
| interpretation vary depending on the particular conversion. They're all |
| described in more detail in the following sections. Don't worry if this |
| all seems excessively complicated at first; you can almost always get |
| reasonable free-format output without using any of the modifiers at all. |
| The modifiers are mostly used to make the output look "prettier" in |
| tables. |
| |
| |
| File: libc.info, Node: Output Conversion Syntax, Next: Table of Output Conversions, Prev: Formatted Output Basics, Up: Formatted Output |
| |
| 12.12.2 Output Conversion Syntax |
| -------------------------------- |
| |
| This section provides details about the precise syntax of conversion |
| specifications that can appear in a `printf' template string. |
| |
| Characters in the template string that are not part of a conversion |
| specification are printed as-is to the output stream. Multibyte |
| character sequences (*note Character Set Handling::) are permitted in a |
| template string. |
| |
| The conversion specifications in a `printf' template string have the |
| general form: |
| |
| % [ PARAM-NO $] FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION |
| |
| or |
| |
| % [ PARAM-NO $] FLAGS WIDTH . * [ PARAM-NO $] TYPE CONVERSION |
| |
| For example, in the conversion specifier `%-10.8ld', the `-' is a |
| flag, `10' specifies the field width, the precision is `8', the letter |
| `l' is a type modifier, and `d' specifies the conversion style. (This |
| particular type specifier says to print a `long int' argument in |
| decimal notation, with a minimum of 8 digits left-justified in a field |
| at least 10 characters wide.) |
| |
| In more detail, output conversion specifications consist of an |
| initial `%' character followed in sequence by: |
| |
| * An optional specification of the parameter used for this format. |
| Normally the parameters to the `printf' function are assigned to |
| the formats in the order of appearance in the format string. But |
| in some situations (such as message translation) this is not |
| desirable and this extension allows an explicit parameter to be |
| specified. |
| |
| The PARAM-NO parts of the format must be integers in the range of |
| 1 to the maximum number of arguments present to the function call. |
| Some implementations limit this number to a certain upper bound. |
| The exact limit can be retrieved by the following constant. |
| |
| -- Macro: NL_ARGMAX |
| The value of `NL_ARGMAX' is the maximum value allowed for the |
| specification of a positional parameter in a `printf' call. |
| The actual value in effect at runtime can be retrieved by |
| using `sysconf' using the `_SC_NL_ARGMAX' parameter *note |
| Sysconf Definition::. |
| |
| Some systems have a quite low limit such as 9 for System V |
| systems. The GNU C Library has no real limit. |
| |
| If any of the formats has a specification for the parameter |
| position all of them in the format string shall have one. |
| Otherwise the behavior is undefined. |
| |
| * Zero or more "flag characters" that modify the normal behavior of |
| the conversion specification. |
| |
| * An optional decimal integer specifying the "minimum field width". |
| If the normal conversion produces fewer characters than this, the |
| field is padded with spaces to the specified width. This is a |
| _minimum_ value; if the normal conversion produces more characters |
| than this, the field is _not_ truncated. Normally, the output is |
| right-justified within the field. |
| |
| You can also specify a field width of `*'. This means that the |
| next argument in the argument list (before the actual value to be |
| printed) is used as the field width. The value must be an `int'. |
| If the value is negative, this means to set the `-' flag (see |
| below) and to use the absolute value as the field width. |
| |
| * An optional "precision" to specify the number of digits to be |
| written for the numeric conversions. If the precision is |
| specified, it consists of a period (`.') followed optionally by a |
| decimal integer (which defaults to zero if omitted). |
| |
| You can also specify a precision of `*'. This means that the next |
| argument in the argument list (before the actual value to be |
| printed) is used as the precision. The value must be an `int', |
| and is ignored if it is negative. If you specify `*' for both the |
| field width and precision, the field width argument precedes the |
| precision argument. Other C library versions may not recognize |
| this syntax. |
| |
| * An optional "type modifier character", which is used to specify the |
| data type of the corresponding argument if it differs from the |
| default type. (For example, the integer conversions assume a type |
| of `int', but you can specify `h', `l', or `L' for other integer |
| types.) |
| |
| * A character that specifies the conversion to be applied. |
| |
| The exact options that are permitted and how they are interpreted |
| vary between the different conversion specifiers. See the descriptions |
| of the individual conversions for information about the particular |
| options that they use. |
| |
| With the `-Wformat' option, the GNU C compiler checks calls to |
| `printf' and related functions. It examines the format string and |
| verifies that the correct number and types of arguments are supplied. |
| There is also a GNU C syntax to tell the compiler that a function you |
| write uses a `printf'-style format string. *Note Declaring Attributes |
| of Functions: (gcc)Function Attributes, for more information. |
| |
| |
| File: libc.info, Node: Table of Output Conversions, Next: Integer Conversions, Prev: Output Conversion Syntax, Up: Formatted Output |
| |
| 12.12.3 Table of Output Conversions |
| ----------------------------------- |
| |
| Here is a table summarizing what all the different conversions do: |
| |
| `%d', `%i' |
| Print an integer as a signed decimal number. *Note Integer |
| Conversions::, for details. `%d' and `%i' are synonymous for |
| output, but are different when used with `scanf' for input (*note |
| Table of Input Conversions::). |
| |
| `%o' |
| Print an integer as an unsigned octal number. *Note Integer |
| Conversions::, for details. |
| |
| `%u' |
| Print an integer as an unsigned decimal number. *Note Integer |
| Conversions::, for details. |
| |
| `%x', `%X' |
| Print an integer as an unsigned hexadecimal number. `%x' uses |
| lower-case letters and `%X' uses upper-case. *Note Integer |
| Conversions::, for details. |
| |
| `%f' |
| Print a floating-point number in normal (fixed-point) notation. |
| *Note Floating-Point Conversions::, for details. |
| |
| `%e', `%E' |
| Print a floating-point number in exponential notation. `%e' uses |
| lower-case letters and `%E' uses upper-case. *Note Floating-Point |
| Conversions::, for details. |
| |
| `%g', `%G' |
| Print a floating-point number in either normal or exponential |
| notation, whichever is more appropriate for its magnitude. `%g' |
| uses lower-case letters and `%G' uses upper-case. *Note |
| Floating-Point Conversions::, for details. |
| |
| `%a', `%A' |
| Print a floating-point number in a hexadecimal fractional notation |
| with the exponent to base 2 represented in decimal digits. `%a' |
| uses lower-case letters and `%A' uses upper-case. *Note |
| Floating-Point Conversions::, for details. |
| |
| `%c' |
| Print a single character. *Note Other Output Conversions::. |
| |
| `%C' |
| This is an alias for `%lc' which is supported for compatibility |
| with the Unix standard. |
| |
| `%s' |
| Print a string. *Note Other Output Conversions::. |
| |
| `%S' |
| This is an alias for `%ls' which is supported for compatibility |
| with the Unix standard. |
| |
| `%p' |
| Print the value of a pointer. *Note Other Output Conversions::. |
| |
| `%n' |
| Get the number of characters printed so far. *Note Other Output |
| Conversions::. Note that this conversion specification never |
| produces any output. |
| |
| `%m' |
| Print the string corresponding to the value of `errno'. (This is |
| a GNU extension.) *Note Other Output Conversions::. |
| |
| `%%' |
| Print a literal `%' character. *Note Other Output Conversions::. |
| |
| If the syntax of a conversion specification is invalid, unpredictable |
| things will happen, so don't do this. If there aren't enough function |
| arguments provided to supply values for all the conversion |
| specifications in the template string, or if the arguments are not of |
| the correct types, the results are unpredictable. If you supply more |
| arguments than conversion specifications, the extra argument values are |
| simply ignored; this is sometimes useful. |
| |
| |
| |
| Local Variables: |
| coding: utf-8 |
| End: |
