| This is libc.info, produced by makeinfo version 5.2 from libc.texinfo. |
| |
| This file documents the GNU C Library. |
| |
| This is 'The GNU C Library Reference Manual', for version 2.19 |
| (Buildroot). |
| |
| Copyright (C) 1993-2014 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software Needs Free Documentation" and |
| "GNU Lesser General Public License", the Front-Cover texts being "A GNU |
| Manual", and with the Back-Cover Texts as in (a) below. A copy of the |
| license is included in the section entitled "GNU Free Documentation |
| License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DES_FAILED: (libc)DES Encryption. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * SV_INTERRUPT: (libc)BSD Handler. |
| * SV_ONSTACK: (libc)BSD Handler. |
| * SV_RESETHAND: (libc)BSD Handler. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying and Concatenation. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying and Concatenation. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbc_crypt: (libc)DES Encryption. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfree: (libc)Freeing after Malloc. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)crypt. |
| * crypt_r: (libc)crypt. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * des_setparity: (libc)DES Encryption. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecb_crypt: (libc)DES Encryption. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * encrypt: (libc)DES Encryption. |
| * encrypt_r: (libc)DES Encryption. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying and Concatenation. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying and Concatenation. |
| * memfrob: (libc)Trivial Encryption. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying and Concatenation. |
| * mempcpy: (libc)Copying and Concatenation. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying and Concatenation. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow10: (libc)Exponents and Logarithms. |
| * pow10f: (libc)Exponents and Logarithms. |
| * pow10l: (libc)Exponents and Logarithms. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setkey: (libc)DES Encryption. |
| * setkey_r: (libc)DES Encryption. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)Blocking in BSD. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Handler. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)Blocking in BSD. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)Blocking in BSD. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)Blocking in BSD. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sigvec: (libc)BSD Handler. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying and Concatenation. |
| * stpncpy: (libc)Copying and Concatenation. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Copying and Concatenation. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying and Concatenation. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying and Concatenation. |
| * strdupa: (libc)Copying and Concatenation. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfry: (libc)strfry. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Copying and Concatenation. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Copying and Concatenation. |
| * strndup: (libc)Copying and Concatenation. |
| * strndupa: (libc)Copying and Concatenation. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying and Concatenation. |
| * wcpncpy: (libc)Copying and Concatenation. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Copying and Concatenation. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying and Concatenation. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying and Concatenation. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Copying and Concatenation. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Copying and Concatenation. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying and Concatenation. |
| * wmemmove: (libc)Copying and Concatenation. |
| * wmempcpy: (libc)Copying and Concatenation. |
| * wmemset: (libc)Copying and Concatenation. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| |
| |
| File: libc.info, Node: Arithmetic, Next: Date and Time, Prev: Mathematics, Up: Top |
| |
| 20 Arithmetic Functions |
| *********************** |
| |
| This chapter contains information about functions for doing basic |
| arithmetic operations, such as splitting a float into its integer and |
| fractional parts or retrieving the imaginary part of a complex value. |
| These functions are declared in the header files 'math.h' and |
| 'complex.h'. |
| |
| * Menu: |
| |
| * Integers:: Basic integer types and concepts |
| * Integer Division:: Integer division with guaranteed rounding. |
| * Floating Point Numbers:: Basic concepts. IEEE 754. |
| * Floating Point Classes:: The five kinds of floating-point number. |
| * Floating Point Errors:: When something goes wrong in a calculation. |
| * Rounding:: Controlling how results are rounded. |
| * Control Functions:: Saving and restoring the FPU's state. |
| * Arithmetic Functions:: Fundamental operations provided by the library. |
| * Complex Numbers:: The types. Writing complex constants. |
| * Operations on Complex:: Projection, conjugation, decomposition. |
| * Parsing of Numbers:: Converting strings to numbers. |
| * System V Number Conversion:: An archaic way to convert numbers to strings. |
| |
| |
| File: libc.info, Node: Integers, Next: Integer Division, Up: Arithmetic |
| |
| 20.1 Integers |
| ============= |
| |
| The C language defines several integer data types: integer, short |
| integer, long integer, and character, all in both signed and unsigned |
| varieties. The GNU C compiler extends the language to contain long long |
| integers as well. |
| |
| The C integer types were intended to allow code to be portable among |
| machines with different inherent data sizes (word sizes), so each type |
| may have different ranges on different machines. The problem with this |
| is that a program often needs to be written for a particular range of |
| integers, and sometimes must be written for a particular size of |
| storage, regardless of what machine the program runs on. |
| |
| To address this problem, the GNU C Library contains C type |
| definitions you can use to declare integers that meet your exact needs. |
| Because the GNU C Library header files are customized to a specific |
| machine, your program source code doesn't have to be. |
| |
| These 'typedef's are in 'stdint.h'. |
| |
| If you require that an integer be represented in exactly N bits, use |
| one of the following types, with the obvious mapping to bit size and |
| signedness: |
| |
| * int8_t |
| * int16_t |
| * int32_t |
| * int64_t |
| * uint8_t |
| * uint16_t |
| * uint32_t |
| * uint64_t |
| |
| If your C compiler and target machine do not allow integers of a |
| certain size, the corresponding above type does not exist. |
| |
| If you don't need a specific storage size, but want the smallest data |
| structure with _at least_ N bits, use one of these: |
| |
| * int_least8_t |
| * int_least16_t |
| * int_least32_t |
| * int_least64_t |
| * uint_least8_t |
| * uint_least16_t |
| * uint_least32_t |
| * uint_least64_t |
| |
| If you don't need a specific storage size, but want the data |
| structure that allows the fastest access while having at least N bits |
| (and among data structures with the same access speed, the smallest |
| one), use one of these: |
| |
| * int_fast8_t |
| * int_fast16_t |
| * int_fast32_t |
| * int_fast64_t |
| * uint_fast8_t |
| * uint_fast16_t |
| * uint_fast32_t |
| * uint_fast64_t |
| |
| If you want an integer with the widest range possible on the platform |
| on which it is being used, use one of the following. If you use these, |
| you should write code that takes into account the variable size and |
| range of the integer. |
| |
| * intmax_t |
| * uintmax_t |
| |
| The GNU C Library also provides macros that tell you the maximum and |
| minimum possible values for each integer data type. The macro names |
| follow these examples: 'INT32_MAX', 'UINT8_MAX', 'INT_FAST32_MIN', |
| 'INT_LEAST64_MIN', 'UINTMAX_MAX', 'INTMAX_MAX', 'INTMAX_MIN'. Note that |
| there are no macros for unsigned integer minima. These are always zero. |
| |
| There are similar macros for use with C's built in integer types |
| which should come with your C compiler. These are described in *note |
| Data Type Measurements::. |
| |
| Don't forget you can use the C 'sizeof' function with any of these |
| data types to get the number of bytes of storage each uses. |
| |
| |
| File: libc.info, Node: Integer Division, Next: Floating Point Numbers, Prev: Integers, Up: Arithmetic |
| |
| 20.2 Integer Division |
| ===================== |
| |
| This section describes functions for performing integer division. These |
| functions are redundant when GNU CC is used, because in GNU C the '/' |
| operator always rounds towards zero. But in other C implementations, |
| '/' may round differently with negative arguments. 'div' and 'ldiv' are |
| useful because they specify how to round the quotient: towards zero. |
| The remainder has the same sign as the numerator. |
| |
| These functions are specified to return a result R such that the |
| value 'R.quot*DENOMINATOR + R.rem' equals NUMERATOR. |
| |
| To use these facilities, you should include the header file |
| 'stdlib.h' in your program. |
| |
| -- Data Type: div_t |
| This is a structure type used to hold the result returned by the |
| 'div' function. It has the following members: |
| |
| 'int quot' |
| The quotient from the division. |
| |
| 'int rem' |
| The remainder from the division. |
| |
| -- Function: div_t div (int NUMERATOR, int DENOMINATOR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function 'div' computes the quotient and remainder from the |
| division of NUMERATOR by DENOMINATOR, returning the result in a |
| structure of type 'div_t'. |
| |
| If the result cannot be represented (as in a division by zero), the |
| behavior is undefined. |
| |
| Here is an example, albeit not a very useful one. |
| |
| div_t result; |
| result = div (20, -6); |
| |
| Now 'result.quot' is '-3' and 'result.rem' is '2'. |
| |
| -- Data Type: ldiv_t |
| This is a structure type used to hold the result returned by the |
| 'ldiv' function. It has the following members: |
| |
| 'long int quot' |
| The quotient from the division. |
| |
| 'long int rem' |
| The remainder from the division. |
| |
| (This is identical to 'div_t' except that the components are of |
| type 'long int' rather than 'int'.) |
| |
| -- Function: ldiv_t ldiv (long int NUMERATOR, long int DENOMINATOR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'ldiv' function is similar to 'div', except that the arguments |
| are of type 'long int' and the result is returned as a structure of |
| type 'ldiv_t'. |
| |
| -- Data Type: lldiv_t |
| This is a structure type used to hold the result returned by the |
| 'lldiv' function. It has the following members: |
| |
| 'long long int quot' |
| The quotient from the division. |
| |
| 'long long int rem' |
| The remainder from the division. |
| |
| (This is identical to 'div_t' except that the components are of |
| type 'long long int' rather than 'int'.) |
| |
| -- Function: lldiv_t lldiv (long long int NUMERATOR, long long int |
| DENOMINATOR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'lldiv' function is like the 'div' function, but the arguments |
| are of type 'long long int' and the result is returned as a |
| structure of type 'lldiv_t'. |
| |
| The 'lldiv' function was added in ISO C99. |
| |
| -- Data Type: imaxdiv_t |
| This is a structure type used to hold the result returned by the |
| 'imaxdiv' function. It has the following members: |
| |
| 'intmax_t quot' |
| The quotient from the division. |
| |
| 'intmax_t rem' |
| The remainder from the division. |
| |
| (This is identical to 'div_t' except that the components are of |
| type 'intmax_t' rather than 'int'.) |
| |
| See *note Integers:: for a description of the 'intmax_t' type. |
| |
| -- Function: imaxdiv_t imaxdiv (intmax_t NUMERATOR, intmax_t |
| DENOMINATOR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'imaxdiv' function is like the 'div' function, but the |
| arguments are of type 'intmax_t' and the result is returned as a |
| structure of type 'imaxdiv_t'. |
| |
| See *note Integers:: for a description of the 'intmax_t' type. |
| |
| The 'imaxdiv' function was added in ISO C99. |
| |
| |
| File: libc.info, Node: Floating Point Numbers, Next: Floating Point Classes, Prev: Integer Division, Up: Arithmetic |
| |
| 20.3 Floating Point Numbers |
| =========================== |
| |
| Most computer hardware has support for two different kinds of numbers: |
| integers (...-3, -2, -1, 0, 1, 2, 3...) and floating-point numbers. |
| Floating-point numbers have three parts: the "mantissa", the "exponent", |
| and the "sign bit". The real number represented by a floating-point |
| value is given by (s ? -1 : 1) * 2^e * M where s is the sign bit, e the |
| exponent, and M the mantissa. *Note Floating Point Concepts::, for |
| details. (It is possible to have a different "base" for the exponent, |
| but all modern hardware uses 2.) |
| |
| Floating-point numbers can represent a finite subset of the real |
| numbers. While this subset is large enough for most purposes, it is |
| important to remember that the only reals that can be represented |
| exactly are rational numbers that have a terminating binary expansion |
| shorter than the width of the mantissa. Even simple fractions such as |
| 1/5 can only be approximated by floating point. |
| |
| Mathematical operations and functions frequently need to produce |
| values that are not representable. Often these values can be |
| approximated closely enough for practical purposes, but sometimes they |
| can't. Historically there was no way to tell when the results of a |
| calculation were inaccurate. Modern computers implement the IEEE 754 |
| standard for numerical computations, which defines a framework for |
| indicating to the program when the results of calculation are not |
| trustworthy. This framework consists of a set of "exceptions" that |
| indicate why a result could not be represented, and the special values |
| "infinity" and "not a number" (NaN). |
| |
| |
| File: libc.info, Node: Floating Point Classes, Next: Floating Point Errors, Prev: Floating Point Numbers, Up: Arithmetic |
| |
| 20.4 Floating-Point Number Classification Functions |
| =================================================== |
| |
| ISO C99 defines macros that let you determine what sort of |
| floating-point number a variable holds. |
| |
| -- Macro: int fpclassify (_float-type_ X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is a generic macro which works on all floating-point types and |
| which returns a value of type 'int'. The possible values are: |
| |
| 'FP_NAN' |
| The floating-point number X is "Not a Number" (*note Infinity |
| and NaN::) |
| 'FP_INFINITE' |
| The value of X is either plus or minus infinity (*note |
| Infinity and NaN::) |
| 'FP_ZERO' |
| The value of X is zero. In floating-point formats like |
| IEEE 754, where zero can be signed, this value is also |
| returned if X is negative zero. |
| 'FP_SUBNORMAL' |
| Numbers whose absolute value is too small to be represented in |
| the normal format are represented in an alternate, |
| "denormalized" format (*note Floating Point Concepts::). This |
| format is less precise but can represent values closer to |
| zero. 'fpclassify' returns this value for values of X in this |
| alternate format. |
| 'FP_NORMAL' |
| This value is returned for all other values of X. It |
| indicates that there is nothing special about the number. |
| |
| 'fpclassify' is most useful if more than one property of a number |
| must be tested. There are more specific macros which only test one |
| property at a time. Generally these macros execute faster than |
| 'fpclassify', since there is special hardware support for them. You |
| should therefore use the specific macros whenever possible. |
| |
| -- Macro: int isfinite (_float-type_ X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value if X is finite: not plus or |
| minus infinity, and not NaN. It is equivalent to |
| |
| (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE) |
| |
| 'isfinite' is implemented as a macro which accepts any |
| floating-point type. |
| |
| -- Macro: int isnormal (_float-type_ X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value if X is finite and normalized. |
| It is equivalent to |
| |
| (fpclassify (x) == FP_NORMAL) |
| |
| -- Macro: int isnan (_float-type_ X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value if X is NaN. It is equivalent to |
| |
| (fpclassify (x) == FP_NAN) |
| |
| -- Macro: int issignaling (_float-type_ X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value if X is a signaling NaN (sNaN). |
| It is based on draft TS 18661 and currently enabled as a GNU |
| extension. |
| |
| Another set of floating-point classification functions was provided |
| by BSD. The GNU C Library also supports these functions; however, we |
| recommend that you use the ISO C99 macros in new code. Those are |
| standard and will be available more widely. Also, since they are |
| macros, you do not have to worry about the type of their argument. |
| |
| -- Function: int isinf (double X) |
| -- Function: int isinff (float X) |
| -- Function: int isinfl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns '-1' if X represents negative infinity, '1' |
| if X represents positive infinity, and '0' otherwise. |
| |
| -- Function: int isnan (double X) |
| -- Function: int isnanf (float X) |
| -- Function: int isnanl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns a nonzero value if X is a "not a number" |
| value, and zero otherwise. |
| |
| *NB:* The 'isnan' macro defined by ISO C99 overrides the BSD |
| function. This is normally not a problem, because the two routines |
| behave identically. However, if you really need to get the BSD |
| function for some reason, you can write |
| |
| (isnan) (x) |
| |
| -- Function: int finite (double X) |
| -- Function: int finitef (float X) |
| -- Function: int finitel (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns a nonzero value if X is finite or a "not a |
| number" value, and zero otherwise. |
| |
| *Portability Note:* The functions listed in this section are BSD |
| extensions. |
| |
| |
| File: libc.info, Node: Floating Point Errors, Next: Rounding, Prev: Floating Point Classes, Up: Arithmetic |
| |
| 20.5 Errors in Floating-Point Calculations |
| ========================================== |
| |
| * Menu: |
| |
| * FP Exceptions:: IEEE 754 math exceptions and how to detect them. |
| * Infinity and NaN:: Special values returned by calculations. |
| * Status bit operations:: Checking for exceptions after the fact. |
| * Math Error Reporting:: How the math functions report errors. |
| |
| |
| File: libc.info, Node: FP Exceptions, Next: Infinity and NaN, Up: Floating Point Errors |
| |
| 20.5.1 FP Exceptions |
| -------------------- |
| |
| The IEEE 754 standard defines five "exceptions" that can occur during a |
| calculation. Each corresponds to a particular sort of error, such as |
| overflow. |
| |
| When exceptions occur (when exceptions are "raised", in the language |
| of the standard), one of two things can happen. By default the |
| exception is simply noted in the floating-point "status word", and the |
| program continues as if nothing had happened. The operation produces a |
| default value, which depends on the exception (see the table below). |
| Your program can check the status word to find out which exceptions |
| happened. |
| |
| Alternatively, you can enable "traps" for exceptions. In that case, |
| when an exception is raised, your program will receive the 'SIGFPE' |
| signal. The default action for this signal is to terminate the program. |
| *Note Signal Handling::, for how you can change the effect of the |
| signal. |
| |
| In the System V math library, the user-defined function 'matherr' is |
| called when certain exceptions occur inside math library functions. |
| However, the Unix98 standard deprecates this interface. We support it |
| for historical compatibility, but recommend that you do not use it in |
| new programs. When this interface is used, exceptions may not be |
| raised. |
| |
| The exceptions defined in IEEE 754 are: |
| |
| 'Invalid Operation' |
| This exception is raised if the given operands are invalid for the |
| operation to be performed. Examples are (see IEEE 754, section 7): |
| 1. Addition or subtraction: oo - oo. (But oo + oo = oo). |
| 2. Multiplication: 0 * oo. |
| 3. Division: 0/0 or oo/oo. |
| 4. Remainder: x REM y, where y is zero or x is infinite. |
| 5. Square root if the operand is less then zero. More generally, |
| any mathematical function evaluated outside its domain |
| produces this exception. |
| 6. Conversion of a floating-point number to an integer or decimal |
| string, when the number cannot be represented in the target |
| format (due to overflow, infinity, or NaN). |
| 7. Conversion of an unrecognizable input string. |
| 8. Comparison via predicates involving < or >, when one or other |
| of the operands is NaN. You can prevent this exception by |
| using the unordered comparison functions instead; see *note FP |
| Comparison Functions::. |
| |
| If the exception does not trap, the result of the operation is NaN. |
| |
| 'Division by Zero' |
| This exception is raised when a finite nonzero number is divided by |
| zero. If no trap occurs the result is either +oo or -oo, depending |
| on the signs of the operands. |
| |
| 'Overflow' |
| This exception is raised whenever the result cannot be represented |
| as a finite value in the precision format of the destination. If |
| no trap occurs the result depends on the sign of the intermediate |
| result and the current rounding mode (IEEE 754, section 7.3): |
| 1. Round to nearest carries all overflows to oo with the sign of |
| the intermediate result. |
| 2. Round toward 0 carries all overflows to the largest |
| representable finite number with the sign of the intermediate |
| result. |
| 3. Round toward -oo carries positive overflows to the largest |
| representable finite number and negative overflows to -oo. |
| |
| 4. Round toward oo carries negative overflows to the most |
| negative representable finite number and positive overflows to |
| oo. |
| |
| Whenever the overflow exception is raised, the inexact exception is |
| also raised. |
| |
| 'Underflow' |
| The underflow exception is raised when an intermediate result is |
| too small to be calculated accurately, or if the operation's result |
| rounded to the destination precision is too small to be normalized. |
| |
| When no trap is installed for the underflow exception, underflow is |
| signaled (via the underflow flag) only when both tininess and loss |
| of accuracy have been detected. If no trap handler is installed |
| the operation continues with an imprecise small value, or zero if |
| the destination precision cannot hold the small exact result. |
| |
| 'Inexact' |
| This exception is signalled if a rounded result is not exact (such |
| as when calculating the square root of two) or a result overflows |
| without an overflow trap. |
| |
| |
| File: libc.info, Node: Infinity and NaN, Next: Status bit operations, Prev: FP Exceptions, Up: Floating Point Errors |
| |
| 20.5.2 Infinity and NaN |
| ----------------------- |
| |
| IEEE 754 floating point numbers can represent positive or negative |
| infinity, and "NaN" (not a number). These three values arise from |
| calculations whose result is undefined or cannot be represented |
| accurately. You can also deliberately set a floating-point variable to |
| any of them, which is sometimes useful. Some examples of calculations |
| that produce infinity or NaN: |
| |
| 1/0 = oo |
| log (0) = -oo |
| sqrt (-1) = NaN |
| |
| When a calculation produces any of these values, an exception also |
| occurs; see *note FP Exceptions::. |
| |
| The basic operations and math functions all accept infinity and NaN |
| and produce sensible output. Infinities propagate through calculations |
| as one would expect: for example, 2 + oo = oo, 4/oo = 0, atan (oo) = |
| pi/2. NaN, on the other hand, infects any calculation that involves it. |
| Unless the calculation would produce the same result no matter what real |
| value replaced NaN, the result is NaN. |
| |
| In comparison operations, positive infinity is larger than all values |
| except itself and NaN, and negative infinity is smaller than all values |
| except itself and NaN. NaN is "unordered": it is not equal to, greater |
| than, or less than anything, _including itself_. 'x == x' is false if |
| the value of 'x' is NaN. You can use this to test whether a value is NaN |
| or not, but the recommended way to test for NaN is with the 'isnan' |
| function (*note Floating Point Classes::). In addition, '<', '>', '<=', |
| and '>=' will raise an exception when applied to NaNs. |
| |
| 'math.h' defines macros that allow you to explicitly set a variable |
| to infinity or NaN. |
| |
| -- Macro: float INFINITY |
| An expression representing positive infinity. It is equal to the |
| value produced by mathematical operations like '1.0 / 0.0'. |
| '-INFINITY' represents negative infinity. |
| |
| You can test whether a floating-point value is infinite by |
| comparing it to this macro. However, this is not recommended; you |
| should use the 'isfinite' macro instead. *Note Floating Point |
| Classes::. |
| |
| This macro was introduced in the ISO C99 standard. |
| |
| -- Macro: float NAN |
| An expression representing a value which is "not a number". This |
| macro is a GNU extension, available only on machines that support |
| the "not a number" value--that is to say, on all machines that |
| support IEEE floating point. |
| |
| You can use '#ifdef NAN' to test whether the machine supports NaN. |
| (Of course, you must arrange for GNU extensions to be visible, such |
| as by defining '_GNU_SOURCE', and then you must include 'math.h'.) |
| |
| IEEE 754 also allows for another unusual value: negative zero. This |
| value is produced when you divide a positive number by negative |
| infinity, or when a negative result is smaller than the limits of |
| representation. |
| |
| |
| File: libc.info, Node: Status bit operations, Next: Math Error Reporting, Prev: Infinity and NaN, Up: Floating Point Errors |
| |
| 20.5.3 Examining the FPU status word |
| ------------------------------------ |
| |
| ISO C99 defines functions to query and manipulate the floating-point |
| status word. You can use these functions to check for untrapped |
| exceptions when it's convenient, rather than worrying about them in the |
| middle of a calculation. |
| |
| These constants represent the various IEEE 754 exceptions. Not all |
| FPUs report all the different exceptions. Each constant is defined if |
| and only if the FPU you are compiling for supports that exception, so |
| you can test for FPU support with '#ifdef'. They are defined in |
| 'fenv.h'. |
| |
| 'FE_INEXACT' |
| The inexact exception. |
| 'FE_DIVBYZERO' |
| The divide by zero exception. |
| 'FE_UNDERFLOW' |
| The underflow exception. |
| 'FE_OVERFLOW' |
| The overflow exception. |
| 'FE_INVALID' |
| The invalid exception. |
| |
| The macro 'FE_ALL_EXCEPT' is the bitwise OR of all exception macros |
| which are supported by the FP implementation. |
| |
| These functions allow you to clear exception flags, test for |
| exceptions, and save and restore the set of exceptions flagged. |
| |
| -- Function: int feclearexcept (int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe !posix | AC-Safe !posix | *Note |
| POSIX Safety Concepts::. |
| |
| This function clears all of the supported exception flags indicated |
| by EXCEPTS. |
| |
| The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| |
| -- Function: int feraiseexcept (int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function raises the supported exceptions indicated by EXCEPTS. |
| If more than one exception bit in EXCEPTS is set the order in which |
| the exceptions are raised is undefined except that overflow |
| ('FE_OVERFLOW') or underflow ('FE_UNDERFLOW') are raised before |
| inexact ('FE_INEXACT'). Whether for overflow or underflow the |
| inexact exception is also raised is also implementation dependent. |
| |
| The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| |
| -- Function: int fetestexcept (int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Test whether the exception flags indicated by the parameter EXCEPT |
| are currently set. If any of them are, a nonzero value is returned |
| which specifies which exceptions are set. Otherwise the result is |
| zero. |
| |
| To understand these functions, imagine that the status word is an |
| integer variable named STATUS. 'feclearexcept' is then equivalent to |
| 'status &= ~excepts' and 'fetestexcept' is equivalent to '(status & |
| excepts)'. The actual implementation may be very different, of course. |
| |
| Exception flags are only cleared when the program explicitly requests |
| it, by calling 'feclearexcept'. If you want to check for exceptions |
| from a set of calculations, you should clear all the flags first. Here |
| is a simple example of the way to use 'fetestexcept': |
| |
| { |
| double f; |
| int raised; |
| feclearexcept (FE_ALL_EXCEPT); |
| f = compute (); |
| raised = fetestexcept (FE_OVERFLOW | FE_INVALID); |
| if (raised & FE_OVERFLOW) { /* ... */ } |
| if (raised & FE_INVALID) { /* ... */ } |
| /* ... */ |
| } |
| |
| You cannot explicitly set bits in the status word. You can, however, |
| save the entire status word and restore it later. This is done with the |
| following functions: |
| |
| -- Function: int fegetexceptflag (fexcept_t *FLAGP, int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function stores in the variable pointed to by FLAGP an |
| implementation-defined value representing the current setting of |
| the exception flags indicated by EXCEPTS. |
| |
| The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| |
| -- Function: int fesetexceptflag (const fexcept_t *FLAGP, int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function restores the flags for the exceptions indicated by |
| EXCEPTS to the values stored in the variable pointed to by FLAGP. |
| |
| The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| |
| Note that the value stored in 'fexcept_t' bears no resemblance to the |
| bit mask returned by 'fetestexcept'. The type may not even be an |
| integer. Do not attempt to modify an 'fexcept_t' variable. |
| |
| |
| File: libc.info, Node: Math Error Reporting, Prev: Status bit operations, Up: Floating Point Errors |
| |
| 20.5.4 Error Reporting by Mathematical Functions |
| ------------------------------------------------ |
| |
| Many of the math functions are defined only over a subset of the real or |
| complex numbers. Even if they are mathematically defined, their result |
| may be larger or smaller than the range representable by their return |
| type without loss of accuracy. These are known as "domain errors", |
| "overflows", and "underflows", respectively. Math functions do several |
| things when one of these errors occurs. In this manual we will refer to |
| the complete response as "signalling" a domain error, overflow, or |
| underflow. |
| |
| When a math function suffers a domain error, it raises the invalid |
| exception and returns NaN. It also sets ERRNO to 'EDOM'; this is for |
| compatibility with old systems that do not support IEEE 754 exception |
| handling. Likewise, when overflow occurs, math functions raise the |
| overflow exception and, in the default rounding mode, return oo or -oo |
| as appropriate (in other rounding modes, the largest finite value of the |
| appropriate sign is returned when appropriate for that rounding mode). |
| They also set ERRNO to 'ERANGE' if returning oo or -oo; ERRNO may or may |
| not be set to 'ERANGE' when a finite value is returned on overflow. |
| When underflow occurs, the underflow exception is raised, and zero |
| (appropriately signed) or a subnormal value, as appropriate for the |
| mathematical result of the function and the rounding mode, is returned. |
| ERRNO may be set to 'ERANGE', but this is not guaranteed; it is intended |
| that the GNU C Library should set it when the underflow is to an |
| appropriately signed zero, but not necessarily for other underflows. |
| |
| Some of the math functions are defined mathematically to result in a |
| complex value over parts of their domains. The most familiar example of |
| this is taking the square root of a negative number. The complex math |
| functions, such as 'csqrt', will return the appropriate complex value in |
| this case. The real-valued functions, such as 'sqrt', will signal a |
| domain error. |
| |
| Some older hardware does not support infinities. On that hardware, |
| overflows instead return a particular very large number (usually the |
| largest representable number). 'math.h' defines macros you can use to |
| test for overflow on both old and new hardware. |
| |
| -- Macro: double HUGE_VAL |
| -- Macro: float HUGE_VALF |
| -- Macro: long double HUGE_VALL |
| An expression representing a particular very large number. On |
| machines that use IEEE 754 floating point format, 'HUGE_VAL' is |
| infinity. On other machines, it's typically the largest positive |
| number that can be represented. |
| |
| Mathematical functions return the appropriately typed version of |
| 'HUGE_VAL' or '-HUGE_VAL' when the result is too large to be |
| represented. |
| |
| |
| File: libc.info, Node: Rounding, Next: Control Functions, Prev: Floating Point Errors, Up: Arithmetic |
| |
| 20.6 Rounding Modes |
| =================== |
| |
| Floating-point calculations are carried out internally with extra |
| precision, and then rounded to fit into the destination type. This |
| ensures that results are as precise as the input data. IEEE 754 defines |
| four possible rounding modes: |
| |
| Round to nearest. |
| This is the default mode. It should be used unless there is a |
| specific need for one of the others. In this mode results are |
| rounded to the nearest representable value. If the result is |
| midway between two representable values, the even representable is |
| chosen. "Even" here means the lowest-order bit is zero. This |
| rounding mode prevents statistical bias and guarantees numeric |
| stability: round-off errors in a lengthy calculation will remain |
| smaller than half of 'FLT_EPSILON'. |
| |
| Round toward plus Infinity. |
| All results are rounded to the smallest representable value which |
| is greater than the result. |
| |
| Round toward minus Infinity. |
| All results are rounded to the largest representable value which is |
| less than the result. |
| |
| Round toward zero. |
| All results are rounded to the largest representable value whose |
| magnitude is less than that of the result. In other words, if the |
| result is negative it is rounded up; if it is positive, it is |
| rounded down. |
| |
| 'fenv.h' defines constants which you can use to refer to the various |
| rounding modes. Each one will be defined if and only if the FPU |
| supports the corresponding rounding mode. |
| |
| 'FE_TONEAREST' |
| Round to nearest. |
| |
| 'FE_UPWARD' |
| Round toward +oo. |
| |
| 'FE_DOWNWARD' |
| Round toward -oo. |
| |
| 'FE_TOWARDZERO' |
| Round toward zero. |
| |
| Underflow is an unusual case. Normally, IEEE 754 floating point |
| numbers are always normalized (*note Floating Point Concepts::). |
| Numbers smaller than 2^r (where r is the minimum exponent, |
| 'FLT_MIN_RADIX-1' for FLOAT) cannot be represented as normalized |
| numbers. Rounding all such numbers to zero or 2^r would cause some |
| algorithms to fail at 0. Therefore, they are left in denormalized form. |
| That produces loss of precision, since some bits of the mantissa are |
| stolen to indicate the decimal point. |
| |
| If a result is too small to be represented as a denormalized number, |
| it is rounded to zero. However, the sign of the result is preserved; if |
| the calculation was negative, the result is "negative zero". Negative |
| zero can also result from some operations on infinity, such as 4/-oo. |
| |
| At any time one of the above four rounding modes is selected. You |
| can find out which one with this function: |
| |
| -- Function: int fegetround (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Returns the currently selected rounding mode, represented by one of |
| the values of the defined rounding mode macros. |
| |
| To change the rounding mode, use this function: |
| |
| -- Function: int fesetround (int ROUND) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Changes the currently selected rounding mode to ROUND. If ROUND |
| does not correspond to one of the supported rounding modes nothing |
| is changed. 'fesetround' returns zero if it changed the rounding |
| mode, a nonzero value if the mode is not supported. |
| |
| You should avoid changing the rounding mode if possible. It can be |
| an expensive operation; also, some hardware requires you to compile your |
| program differently for it to work. The resulting code may run slower. |
| See your compiler documentation for details. |
| |
| |
| File: libc.info, Node: Control Functions, Next: Arithmetic Functions, Prev: Rounding, Up: Arithmetic |
| |
| 20.7 Floating-Point Control Functions |
| ===================================== |
| |
| IEEE 754 floating-point implementations allow the programmer to decide |
| whether traps will occur for each of the exceptions, by setting bits in |
| the "control word". In C, traps result in the program receiving the |
| 'SIGFPE' signal; see *note Signal Handling::. |
| |
| *NB:* IEEE 754 says that trap handlers are given details of the |
| exceptional situation, and can set the result value. C signals do not |
| provide any mechanism to pass this information back and forth. Trapping |
| exceptions in C is therefore not very useful. |
| |
| It is sometimes necessary to save the state of the floating-point |
| unit while you perform some calculation. The library provides functions |
| which save and restore the exception flags, the set of exceptions that |
| generate traps, and the rounding mode. This information is known as the |
| "floating-point environment". |
| |
| The functions to save and restore the floating-point environment all |
| use a variable of type 'fenv_t' to store information. This type is |
| defined in 'fenv.h'. Its size and contents are implementation-defined. |
| You should not attempt to manipulate a variable of this type directly. |
| |
| To save the state of the FPU, use one of these functions: |
| |
| -- Function: int fegetenv (fenv_t *ENVP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Store the floating-point environment in the variable pointed to by |
| ENVP. |
| |
| The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| |
| -- Function: int feholdexcept (fenv_t *ENVP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Store the current floating-point environment in the object pointed |
| to by ENVP. Then clear all exception flags, and set the FPU to |
| trap no exceptions. Not all FPUs support trapping no exceptions; |
| if 'feholdexcept' cannot set this mode, it returns nonzero value. |
| If it succeeds, it returns zero. |
| |
| The functions which restore the floating-point environment can take |
| these kinds of arguments: |
| |
| * Pointers to 'fenv_t' objects, which were initialized previously by |
| a call to 'fegetenv' or 'feholdexcept'. |
| * The special macro 'FE_DFL_ENV' which represents the floating-point |
| environment as it was available at program start. |
| * Implementation defined macros with names starting with 'FE_' and |
| having type 'fenv_t *'. |
| |
| If possible, the GNU C Library defines a macro 'FE_NOMASK_ENV' |
| which represents an environment where every exception raised causes |
| a trap to occur. You can test for this macro using '#ifdef'. It |
| is only defined if '_GNU_SOURCE' is defined. |
| |
| Some platforms might define other predefined environments. |
| |
| To set the floating-point environment, you can use either of these |
| functions: |
| |
| -- Function: int fesetenv (const fenv_t *ENVP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Set the floating-point environment to that described by ENVP. |
| |
| The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| |
| -- Function: int feupdateenv (const fenv_t *ENVP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Like 'fesetenv', this function sets the floating-point environment |
| to that described by ENVP. However, if any exceptions were flagged |
| in the status word before 'feupdateenv' was called, they remain |
| flagged after the call. In other words, after 'feupdateenv' is |
| called, the status word is the bitwise OR of the previous status |
| word and the one saved in ENVP. |
| |
| The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| |
| To control for individual exceptions if raising them causes a trap to |
| occur, you can use the following two functions. |
| |
| *Portability Note:* These functions are all GNU extensions. |
| |
| -- Function: int feenableexcept (int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This functions enables traps for each of the exceptions as |
| indicated by the parameter EXCEPT. The individual exceptions are |
| described in *note Status bit operations::. Only the specified |
| exceptions are enabled, the status of the other exceptions is not |
| changed. |
| |
| The function returns the previous enabled exceptions in case the |
| operation was successful, '-1' otherwise. |
| |
| -- Function: int fedisableexcept (int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This functions disables traps for each of the exceptions as |
| indicated by the parameter EXCEPT. The individual exceptions are |
| described in *note Status bit operations::. Only the specified |
| exceptions are disabled, the status of the other exceptions is not |
| changed. |
| |
| The function returns the previous enabled exceptions in case the |
| operation was successful, '-1' otherwise. |
| |
| -- Function: int fegetexcept (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The function returns a bitmask of all currently enabled exceptions. |
| It returns '-1' in case of failure. |
| |
| |
| File: libc.info, Node: Arithmetic Functions, Next: Complex Numbers, Prev: Control Functions, Up: Arithmetic |
| |
| 20.8 Arithmetic Functions |
| ========================= |
| |
| The C library provides functions to do basic operations on |
| floating-point numbers. These include absolute value, maximum and |
| minimum, normalization, bit twiddling, rounding, and a few others. |
| |
| * Menu: |
| |
| * Absolute Value:: Absolute values of integers and floats. |
| * Normalization Functions:: Extracting exponents and putting them back. |
| * Rounding Functions:: Rounding floats to integers. |
| * Remainder Functions:: Remainders on division, precisely defined. |
| * FP Bit Twiddling:: Sign bit adjustment. Adding epsilon. |
| * FP Comparison Functions:: Comparisons without risk of exceptions. |
| * Misc FP Arithmetic:: Max, min, positive difference, multiply-add. |
| |
| |
| File: libc.info, Node: Absolute Value, Next: Normalization Functions, Up: Arithmetic Functions |
| |
| 20.8.1 Absolute Value |
| --------------------- |
| |
| These functions are provided for obtaining the "absolute value" (or |
| "magnitude") of a number. The absolute value of a real number X is X if |
| X is positive, -X if X is negative. For a complex number Z, whose real |
| part is X and whose imaginary part is Y, the absolute value is |
| 'sqrt (X*X + Y*Y)'. |
| |
| Prototypes for 'abs', 'labs' and 'llabs' are in 'stdlib.h'; 'imaxabs' |
| is declared in 'inttypes.h'; 'fabs', 'fabsf' and 'fabsl' are declared in |
| 'math.h'. 'cabs', 'cabsf' and 'cabsl' are declared in 'complex.h'. |
| |
| -- Function: int abs (int NUMBER) |
| -- Function: long int labs (long int NUMBER) |
| -- Function: long long int llabs (long long int NUMBER) |
| -- Function: intmax_t imaxabs (intmax_t NUMBER) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the absolute value of NUMBER. |
| |
| Most computers use a two's complement integer representation, in |
| which the absolute value of 'INT_MIN' (the smallest possible 'int') |
| cannot be represented; thus, 'abs (INT_MIN)' is not defined. |
| |
| 'llabs' and 'imaxdiv' are new to ISO C99. |
| |
| See *note Integers:: for a description of the 'intmax_t' type. |
| |
| -- Function: double fabs (double NUMBER) |
| -- Function: float fabsf (float NUMBER) |
| -- Function: long double fabsl (long double NUMBER) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the absolute value of the floating-point |
| number NUMBER. |
| |
| -- Function: double cabs (complex double Z) |
| -- Function: float cabsf (complex float Z) |
| -- Function: long double cabsl (complex long double Z) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the absolute value of the complex number Z |
| (*note Complex Numbers::). The absolute value of a complex number |
| is: |
| |
| sqrt (creal (Z) * creal (Z) + cimag (Z) * cimag (Z)) |
| |
| This function should always be used instead of the direct formula |
| because it takes special care to avoid losing precision. It may |
| also take advantage of hardware support for this operation. See |
| 'hypot' in *note Exponents and Logarithms::. |
| |
| |
| File: libc.info, Node: Normalization Functions, Next: Rounding Functions, Prev: Absolute Value, Up: Arithmetic Functions |
| |
| 20.8.2 Normalization Functions |
| ------------------------------ |
| |
| The functions described in this section are primarily provided as a way |
| to efficiently perform certain low-level manipulations on floating point |
| numbers that are represented internally using a binary radix; see *note |
| Floating Point Concepts::. These functions are required to have |
| equivalent behavior even if the representation does not use a radix of |
| 2, but of course they are unlikely to be particularly efficient in those |
| cases. |
| |
| All these functions are declared in 'math.h'. |
| |
| -- Function: double frexp (double VALUE, int *EXPONENT) |
| -- Function: float frexpf (float VALUE, int *EXPONENT) |
| -- Function: long double frexpl (long double VALUE, int *EXPONENT) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions are used to split the number VALUE into a |
| normalized fraction and an exponent. |
| |
| If the argument VALUE is not zero, the return value is VALUE times |
| a power of two, and its magnitude is always in the range 1/2 |
| (inclusive) to 1 (exclusive). The corresponding exponent is stored |
| in '*EXPONENT'; the return value multiplied by 2 raised to this |
| exponent equals the original number VALUE. |
| |
| For example, 'frexp (12.8, &exponent)' returns '0.8' and stores '4' |
| in 'exponent'. |
| |
| If VALUE is zero, then the return value is zero and zero is stored |
| in '*EXPONENT'. |
| |
| -- Function: double ldexp (double VALUE, int EXPONENT) |
| -- Function: float ldexpf (float VALUE, int EXPONENT) |
| -- Function: long double ldexpl (long double VALUE, int EXPONENT) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the result of multiplying the floating-point |
| number VALUE by 2 raised to the power EXPONENT. (It can be used to |
| reassemble floating-point numbers that were taken apart by |
| 'frexp'.) |
| |
| For example, 'ldexp (0.8, 4)' returns '12.8'. |
| |
| The following functions, which come from BSD, provide facilities |
| equivalent to those of 'ldexp' and 'frexp'. See also the ISO C function |
| 'logb' which originally also appeared in BSD. |
| |
| -- Function: double scalb (double VALUE, double EXPONENT) |
| -- Function: float scalbf (float VALUE, float EXPONENT) |
| -- Function: long double scalbl (long double VALUE, long double |
| EXPONENT) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'scalb' function is the BSD name for 'ldexp'. |
| |
| -- Function: double scalbn (double X, int N) |
| -- Function: float scalbnf (float X, int N) |
| -- Function: long double scalbnl (long double X, int N) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'scalbn' is identical to 'scalb', except that the exponent N is an |
| 'int' instead of a floating-point number. |
| |
| -- Function: double scalbln (double X, long int N) |
| -- Function: float scalblnf (float X, long int N) |
| -- Function: long double scalblnl (long double X, long int N) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'scalbln' is identical to 'scalb', except that the exponent N is a |
| 'long int' instead of a floating-point number. |
| |
| -- Function: double significand (double X) |
| -- Function: float significandf (float X) |
| -- Function: long double significandl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'significand' returns the mantissa of X scaled to the range [1, 2). |
| It is equivalent to 'scalb (X, (double) -ilogb (X))'. |
| |
| This function exists mainly for use in certain standardized tests |
| of IEEE 754 conformance. |
| |
| |
| File: libc.info, Node: Rounding Functions, Next: Remainder Functions, Prev: Normalization Functions, Up: Arithmetic Functions |
| |
| 20.8.3 Rounding Functions |
| ------------------------- |
| |
| The functions listed here perform operations such as rounding and |
| truncation of floating-point values. Some of these functions convert |
| floating point numbers to integer values. They are all declared in |
| 'math.h'. |
| |
| You can also convert floating-point numbers to integers simply by |
| casting them to 'int'. This discards the fractional part, effectively |
| rounding towards zero. However, this only works if the result can |
| actually be represented as an 'int'--for very large numbers, this is |
| impossible. The functions listed here return the result as a 'double' |
| instead to get around this problem. |
| |
| -- Function: double ceil (double X) |
| -- Function: float ceilf (float X) |
| -- Function: long double ceill (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions round X upwards to the nearest integer, returning |
| that value as a 'double'. Thus, 'ceil (1.5)' is '2.0'. |
| |
| -- Function: double floor (double X) |
| -- Function: float floorf (float X) |
| -- Function: long double floorl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions round X downwards to the nearest integer, returning |
| that value as a 'double'. Thus, 'floor (1.5)' is '1.0' and 'floor |
| (-1.5)' is '-2.0'. |
| |
| -- Function: double trunc (double X) |
| -- Function: float truncf (float X) |
| -- Function: long double truncl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'trunc' functions round X towards zero to the nearest integer |
| (returned in floating-point format). Thus, 'trunc (1.5)' is '1.0' |
| and 'trunc (-1.5)' is '-1.0'. |
| |
| -- Function: double rint (double X) |
| -- Function: float rintf (float X) |
| -- Function: long double rintl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions round X to an integer value according to the |
| current rounding mode. *Note Floating Point Parameters::, for |
| information about the various rounding modes. The default rounding |
| mode is to round to the nearest integer; some machines support |
| other modes, but round-to-nearest is always used unless you |
| explicitly select another. |
| |
| If X was not initially an integer, these functions raise the |
| inexact exception. |
| |
| -- Function: double nearbyint (double X) |
| -- Function: float nearbyintf (float X) |
| -- Function: long double nearbyintl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the same value as the 'rint' functions, but |
| do not raise the inexact exception if X is not an integer. |
| |
| -- Function: double round (double X) |
| -- Function: float roundf (float X) |
| -- Function: long double roundl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions are similar to 'rint', but they round halfway cases |
| away from zero instead of to the nearest integer (or other current |
| rounding mode). |
| |
| -- Function: long int lrint (double X) |
| -- Function: long int lrintf (float X) |
| -- Function: long int lrintl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions are just like 'rint', but they return a 'long int' |
| instead of a floating-point number. |
| |
| -- Function: long long int llrint (double X) |
| -- Function: long long int llrintf (float X) |
| -- Function: long long int llrintl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions are just like 'rint', but they return a 'long long |
| int' instead of a floating-point number. |
| |
| -- Function: long int lround (double X) |
| -- Function: long int lroundf (float X) |
| -- Function: long int lroundl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions are just like 'round', but they return a 'long int' |
| instead of a floating-point number. |
| |
| -- Function: long long int llround (double X) |
| -- Function: long long int llroundf (float X) |
| -- Function: long long int llroundl (long double X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions are just like 'round', but they return a 'long long |
| int' instead of a floating-point number. |
| |
| -- Function: double modf (double VALUE, double *INTEGER-PART) |
| -- Function: float modff (float VALUE, float *INTEGER-PART) |
| -- Function: long double modfl (long double VALUE, long double |
| *INTEGER-PART) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions break the argument VALUE into an integer part and a |
| fractional part (between '-1' and '1', exclusive). Their sum |
| equals VALUE. Each of the parts has the same sign as VALUE, and |
| the integer part is always rounded toward zero. |
| |
| 'modf' stores the integer part in '*INTEGER-PART', and returns the |
| fractional part. For example, 'modf (2.5, &intpart)' returns '0.5' |
| and stores '2.0' into 'intpart'. |
| |
| |
| File: libc.info, Node: Remainder Functions, Next: FP Bit Twiddling, Prev: Rounding Functions, Up: Arithmetic Functions |
| |
| 20.8.4 Remainder Functions |
| -------------------------- |
| |
| The functions in this section compute the remainder on division of two |
| floating-point numbers. Each is a little different; pick the one that |
| suits your problem. |
| |
| -- Function: double fmod (double NUMERATOR, double DENOMINATOR) |
| -- Function: float fmodf (float NUMERATOR, float DENOMINATOR) |
| -- Function: long double fmodl (long double NUMERATOR, long double |
| DENOMINATOR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions compute the remainder from the division of |
| NUMERATOR by DENOMINATOR. Specifically, the return value is |
| 'NUMERATOR - N * DENOMINATOR', where N is the quotient of NUMERATOR |
| divided by DENOMINATOR, rounded towards zero to an integer. Thus, 'fmod (6.5, 2.3)' |
| returns '1.9', which is '6.5' minus '4.6'. |
| |
| The result has the same sign as the NUMERATOR and has magnitude |
| less than the magnitude of the DENOMINATOR. |
| |
| If DENOMINATOR is zero, 'fmod' signals a domain error. |
| |
| -- Function: double drem (double NUMERATOR, double DENOMINATOR) |
| -- Function: float dremf (float NUMERATOR, float DENOMINATOR) |
| -- Function: long double dreml (long double NUMERATOR, long double |
| DENOMINATOR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions are like 'fmod' except that they round the internal |
| quotient N to the nearest integer instead of towards zero to an |
| integer. For example, 'drem (6.5, 2.3)' returns '-0.4', which is |
| '6.5' minus '6.9'. |
| |
| The absolute value of the result is less than or equal to half the |
| absolute value of the DENOMINATOR. The difference between 'fmod |
| (NUMERATOR, DENOMINATOR)' and 'drem (NUMERATOR, DENOMINATOR)' is |
| always either DENOMINATOR, minus DENOMINATOR, or zero. |
| |
| If DENOMINATOR is zero, 'drem' signals a domain error. |
| |
| -- Function: double remainder (double NUMERATOR, double DENOMINATOR) |
| -- Function: float remainderf (float NUMERATOR, float DENOMINATOR) |
| -- Function: long double remainderl (long double NUMERATOR, long double |
| DENOMINATOR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is another name for 'drem'. |
| |
| |
| File: libc.info, Node: FP Bit Twiddling, Next: FP Comparison Functions, Prev: Remainder Functions, Up: Arithmetic Functions |
| |
| 20.8.5 Setting and modifying single bits of FP values |
| ----------------------------------------------------- |
| |
| There are some operations that are too complicated or expensive to |
| perform by hand on floating-point numbers. ISO C99 defines functions to |
| do these operations, which mostly involve changing single bits. |
| |
| -- Function: double copysign (double X, double Y) |
| -- Function: float copysignf (float X, float Y) |
| -- Function: long double copysignl (long double X, long double Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return X but with the sign of Y. They work even if |
| X or Y are NaN or zero. Both of these can carry a sign (although |
| not all implementations support it) and this is one of the few |
| operations that can tell the difference. |
| |
| 'copysign' never raises an exception. |
| |
| This function is defined in IEC 559 (and the appendix with |
| recommended functions in IEEE 754/IEEE 854). |
| |
| -- Function: int signbit (_float-type_ X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'signbit' is a generic macro which can work on all floating-point |
| types. It returns a nonzero value if the value of X has its sign |
| bit set. |
| |
| This is not the same as 'x < 0.0', because IEEE 754 floating point |
| allows zero to be signed. The comparison '-0.0 < 0.0' is false, |
| but 'signbit (-0.0)' will return a nonzero value. |
| |
| -- Function: double nextafter (double X, double Y) |
| -- Function: float nextafterf (float X, float Y) |
| -- Function: long double nextafterl (long double X, long double Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'nextafter' function returns the next representable neighbor of |
| X in the direction towards Y. The size of the step between X and |
| the result depends on the type of the result. If X = Y the |
| function simply returns Y. If either value is 'NaN', 'NaN' is |
| returned. Otherwise a value corresponding to the value of the |
| least significant bit in the mantissa is added or subtracted, |
| depending on the direction. 'nextafter' will signal overflow or |
| underflow if the result goes outside of the range of normalized |
| numbers. |
| |
| This function is defined in IEC 559 (and the appendix with |
| recommended functions in IEEE 754/IEEE 854). |
| |
| -- Function: double nexttoward (double X, long double Y) |
| -- Function: float nexttowardf (float X, long double Y) |
| -- Function: long double nexttowardl (long double X, long double Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions are identical to the corresponding versions of |
| 'nextafter' except that their second argument is a 'long double'. |
| |
| -- Function: double nan (const char *TAGP) |
| -- Function: float nanf (const char *TAGP) |
| -- Function: long double nanl (const char *TAGP) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'nan' function returns a representation of NaN, provided that |
| NaN is supported by the target platform. 'nan ("N-CHAR-SEQUENCE")' |
| is equivalent to 'strtod ("NAN(N-CHAR-SEQUENCE)")'. |
| |
| The argument TAGP is used in an unspecified manner. On IEEE 754 |
| systems, there are many representations of NaN, and TAGP selects |
| one. On other systems it may do nothing. |
| |
| |
| File: libc.info, Node: FP Comparison Functions, Next: Misc FP Arithmetic, Prev: FP Bit Twiddling, Up: Arithmetic Functions |
| |
| 20.8.6 Floating-Point Comparison Functions |
| ------------------------------------------ |
| |
| The standard C comparison operators provoke exceptions when one or other |
| of the operands is NaN. For example, |
| |
| int v = a < 1.0; |
| |
| will raise an exception if A is NaN. (This does _not_ happen with '==' |
| and '!='; those merely return false and true, respectively, when NaN is |
| examined.) Frequently this exception is undesirable. ISO C99 therefore |
| defines comparison functions that do not raise exceptions when NaN is |
| examined. All of the functions are implemented as macros which allow |
| their arguments to be of any floating-point type. The macros are |
| guaranteed to evaluate their arguments only once. |
| |
| -- Macro: int isgreater (_real-floating_ X, _real-floating_ Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro determines whether the argument X is greater than Y. It |
| is equivalent to '(X) > (Y)', but no exception is raised if X or Y |
| are NaN. |
| |
| -- Macro: int isgreaterequal (_real-floating_ X, _real-floating_ Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro determines whether the argument X is greater than or |
| equal to Y. It is equivalent to '(X) >= (Y)', but no exception is |
| raised if X or Y are NaN. |
| |
| -- Macro: int isless (_real-floating_ X, _real-floating_ Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro determines whether the argument X is less than Y. It is |
| equivalent to '(X) < (Y)', but no exception is raised if X or Y are |
| NaN. |
| |
| -- Macro: int islessequal (_real-floating_ X, _real-floating_ Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro determines whether the argument X is less than or equal |
| to Y. It is equivalent to '(X) <= (Y)', but no exception is raised |
| if X or Y are NaN. |
| |
| -- Macro: int islessgreater (_real-floating_ X, _real-floating_ Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro determines whether the argument X is less or greater |
| than Y. It is equivalent to '(X) < (Y) || (X) > (Y)' (although it |
| only evaluates X and Y once), but no exception is raised if X or Y |
| are NaN. |
| |
| This macro is not equivalent to 'X != Y', because that expression |
| is true if X or Y are NaN. |
| |
| -- Macro: int isunordered (_real-floating_ X, _real-floating_ Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro determines whether its arguments are unordered. In |
| other words, it is true if X or Y are NaN, and false otherwise. |
| |
| Not all machines provide hardware support for these operations. On |
| machines that don't, the macros can be very slow. Therefore, you should |
| not use these functions when NaN is not a concern. |
| |
| *NB:* There are no macros 'isequal' or 'isunequal'. They are |
| unnecessary, because the '==' and '!=' operators do _not_ throw an |
| exception if one or both of the operands are NaN. |
| |
| |
| File: libc.info, Node: Misc FP Arithmetic, Prev: FP Comparison Functions, Up: Arithmetic Functions |
| |
| 20.8.7 Miscellaneous FP arithmetic functions |
| -------------------------------------------- |
| |
| The functions in this section perform miscellaneous but common |
| operations that are awkward to express with C operators. On some |
| processors these functions can use special machine instructions to |
| perform these operations faster than the equivalent C code. |
| |
| -- Function: double fmin (double X, double Y) |
| -- Function: float fminf (float X, float Y) |
| -- Function: long double fminl (long double X, long double Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'fmin' function returns the lesser of the two values X and Y. |
| It is similar to the expression |
| ((x) < (y) ? (x) : (y)) |
| except that X and Y are only evaluated once. |
| |
| If an argument is NaN, the other argument is returned. If both |
| arguments are NaN, NaN is returned. |
| |
| -- Function: double fmax (double X, double Y) |
| -- Function: float fmaxf (float X, float Y) |
| -- Function: long double fmaxl (long double X, long double Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'fmax' function returns the greater of the two values X and Y. |
| |
| If an argument is NaN, the other argument is returned. If both |
| arguments are NaN, NaN is returned. |
| |
| -- Function: double fdim (double X, double Y) |
| -- Function: float fdimf (float X, float Y) |
| -- Function: long double fdiml (long double X, long double Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'fdim' function returns the positive difference between X and |
| Y. The positive difference is X - Y if X is greater than Y, and 0 |
| otherwise. |
| |
| If X, Y, or both are NaN, NaN is returned. |
| |
| -- Function: double fma (double X, double Y, double Z) |
| -- Function: float fmaf (float X, float Y, float Z) |
| -- Function: long double fmal (long double X, long double Y, long |
| double Z) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'fma' function performs floating-point multiply-add. This is |
| the operation (X * Y) + Z, but the intermediate result is not |
| rounded to the destination type. This can sometimes improve the |
| precision of a calculation. |
| |
| This function was introduced because some processors have a special |
| instruction to perform multiply-add. The C compiler cannot use it |
| directly, because the expression 'x*y + z' is defined to round the |
| intermediate result. 'fma' lets you choose when you want to round |
| only once. |
| |
| On processors which do not implement multiply-add in hardware, |
| 'fma' can be very slow since it must avoid intermediate rounding. |
| 'math.h' defines the symbols 'FP_FAST_FMA', 'FP_FAST_FMAF', and |
| 'FP_FAST_FMAL' when the corresponding version of 'fma' is no slower |
| than the expression 'x*y + z'. In the GNU C Library, this always |
| means the operation is implemented in hardware. |
| |
| |
| File: libc.info, Node: Complex Numbers, Next: Operations on Complex, Prev: Arithmetic Functions, Up: Arithmetic |
| |
| 20.9 Complex Numbers |
| ==================== |
| |
| ISO C99 introduces support for complex numbers in C. This is done with a |
| new type qualifier, 'complex'. It is a keyword if and only if |
| 'complex.h' has been included. There are three complex types, |
| corresponding to the three real types: 'float complex', 'double |
| complex', and 'long double complex'. |
| |
| To construct complex numbers you need a way to indicate the imaginary |
| part of a number. There is no standard notation for an imaginary |
| floating point constant. Instead, 'complex.h' defines two macros that |
| can be used to create complex numbers. |
| |
| -- Macro: const float complex _Complex_I |
| This macro is a representation of the complex number "0+1i". |
| Multiplying a real floating-point value by '_Complex_I' gives a |
| complex number whose value is purely imaginary. You can use this |
| to construct complex constants: |
| |
| 3.0 + 4.0i = 3.0 + 4.0 * _Complex_I |
| |
| Note that '_Complex_I * _Complex_I' has the value '-1', but the |
| type of that value is 'complex'. |
| |
| '_Complex_I' is a bit of a mouthful. 'complex.h' also defines a shorter |
| name for the same constant. |
| |
| -- Macro: const float complex I |
| This macro has exactly the same value as '_Complex_I'. Most of the |
| time it is preferable. However, it causes problems if you want to |
| use the identifier 'I' for something else. You can safely write |
| |
| #include <complex.h> |
| #undef I |
| |
| if you need 'I' for your own purposes. (In that case we recommend |
| you also define some other short name for '_Complex_I', such as |
| 'J'.) |
| |
| |
| File: libc.info, Node: Operations on Complex, Next: Parsing of Numbers, Prev: Complex Numbers, Up: Arithmetic |
| |
| 20.10 Projections, Conjugates, and Decomposing of Complex Numbers |
| ================================================================= |
| |
| ISO C99 also defines functions that perform basic operations on complex |
| numbers, such as decomposition and conjugation. The prototypes for all |
| these functions are in 'complex.h'. All functions are available in |
| three variants, one for each of the three complex types. |
| |
| -- Function: double creal (complex double Z) |
| -- Function: float crealf (complex float Z) |
| -- Function: long double creall (complex long double Z) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the real part of the complex number Z. |
| |
| -- Function: double cimag (complex double Z) |
| -- Function: float cimagf (complex float Z) |
| -- Function: long double cimagl (complex long double Z) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the imaginary part of the complex number Z. |
| |
| -- Function: complex double conj (complex double Z) |
| -- Function: complex float conjf (complex float Z) |
| -- Function: complex long double conjl (complex long double Z) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the conjugate value of the complex number Z. |
| The conjugate of a complex number has the same real part and a |
| negated imaginary part. In other words, 'conj(a + bi) = a + -bi'. |
| |
| -- Function: double carg (complex double Z) |
| -- Function: float cargf (complex float Z) |
| -- Function: long double cargl (complex long double Z) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the argument of the complex number Z. The |
| argument of a complex number is the angle in the complex plane |
| between the positive real axis and a line passing through zero and |
| the number. This angle is measured in the usual fashion and ranges |
| from -pi to pi. |
| |
| 'carg' has a branch cut along the negative real axis. |
| |
| -- Function: complex double cproj (complex double Z) |
| -- Function: complex float cprojf (complex float Z) |
| -- Function: complex long double cprojl (complex long double Z) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions return the projection of the complex value Z onto |
| the Riemann sphere. Values with an infinite imaginary part are |
| projected to positive infinity on the real axis, even if the real |
| part is NaN. If the real part is infinite, the result is equivalent |
| to |
| |
| INFINITY + I * copysign (0.0, cimag (z)) |
| |
| |
| File: libc.info, Node: Parsing of Numbers, Next: System V Number Conversion, Prev: Operations on Complex, Up: Arithmetic |
| |
| 20.11 Parsing of Numbers |
| ======================== |
| |
| This section describes functions for "reading" integer and |
| floating-point numbers from a string. It may be more convenient in some |
| cases to use 'sscanf' or one of the related functions; see *note |
| Formatted Input::. But often you can make a program more robust by |
| finding the tokens in the string by hand, then converting the numbers |
| one by one. |
| |
| * Menu: |
| |
| * Parsing of Integers:: Functions for conversion of integer values. |
| * Parsing of Floats:: Functions for conversion of floating-point |
| values. |
| |
| |
| File: libc.info, Node: Parsing of Integers, Next: Parsing of Floats, Up: Parsing of Numbers |
| |
| 20.11.1 Parsing of Integers |
| --------------------------- |
| |
| The 'str' functions are declared in 'stdlib.h' and those beginning with |
| 'wcs' are declared in 'wchar.h'. One might wonder about the use of |
| 'restrict' in the prototypes of the functions in this section. It is |
| seemingly useless but the ISO C standard uses it (for the functions |
| defined there) so we have to do it as well. |
| |
| -- Function: long int strtol (const char *restrict STRING, char |
| **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'strtol' ("string-to-long") function converts the initial part |
| of STRING to a signed integer, which is returned as a value of type |
| 'long int'. |
| |
| This function attempts to decompose STRING as follows: |
| |
| * A (possibly empty) sequence of whitespace characters. Which |
| characters are whitespace is determined by the 'isspace' |
| function (*note Classification of Characters::). These are |
| discarded. |
| |
| * An optional plus or minus sign ('+' or '-'). |
| |
| * A nonempty sequence of digits in the radix specified by BASE. |
| |
| If BASE is zero, decimal radix is assumed unless the series of |
| digits begins with '0' (specifying octal radix), or '0x' or |
| '0X' (specifying hexadecimal radix); in other words, the same |
| syntax used for integer constants in C. |
| |
| Otherwise BASE must have a value between '2' and '36'. If |
| BASE is '16', the digits may optionally be preceded by '0x' or |
| '0X'. If base has no legal value the value returned is '0l' |
| and the global variable 'errno' is set to 'EINVAL'. |
| |
| * Any remaining characters in the string. If TAILPTR is not a |
| null pointer, 'strtol' stores a pointer to this tail in |
| '*TAILPTR'. |
| |
| If the string is empty, contains only whitespace, or does not |
| contain an initial substring that has the expected syntax for an |
| integer in the specified BASE, no conversion is performed. In this |
| case, 'strtol' returns a value of zero and the value stored in |
| '*TAILPTR' is the value of STRING. |
| |
| In a locale other than the standard '"C"' locale, this function may |
| recognize additional implementation-dependent syntax. |
| |
| If the string has valid syntax for an integer but the value is not |
| representable because of overflow, 'strtol' returns either |
| 'LONG_MAX' or 'LONG_MIN' (*note Range of Type::), as appropriate |
| for the sign of the value. It also sets 'errno' to 'ERANGE' to |
| indicate there was overflow. |
| |
| You should not check for errors by examining the return value of |
| 'strtol', because the string might be a valid representation of |
| '0l', 'LONG_MAX', or 'LONG_MIN'. Instead, check whether TAILPTR |
| points to what you expect after the number (e.g. ''\0'' if the |
| string should end after the number). You also need to clear ERRNO |
| before the call and check it afterward, in case there was overflow. |
| |
| There is an example at the end of this section. |
| |
| -- Function: long int wcstol (const wchar_t *restrict STRING, wchar_t |
| **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstol' function is equivalent to the 'strtol' function in |
| nearly all aspects but handles wide character strings. |
| |
| The 'wcstol' function was introduced in Amendment 1 of ISO C90. |
| |
| -- Function: unsigned long int strtoul (const char *retrict STRING, |
| char **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'strtoul' ("string-to-unsigned-long") function is like 'strtol' |
| except it converts to an 'unsigned long int' value. The syntax is |
| the same as described above for 'strtol'. The value returned on |
| overflow is 'ULONG_MAX' (*note Range of Type::). |
| |
| If STRING depicts a negative number, 'strtoul' acts the same as |
| STRTOL but casts the result to an unsigned integer. That means for |
| example that 'strtoul' on '"-1"' returns 'ULONG_MAX' and an input |
| more negative than 'LONG_MIN' returns ('ULONG_MAX' + 1) / 2. |
| |
| 'strtoul' sets ERRNO to 'EINVAL' if BASE is out of range, or |
| 'ERANGE' on overflow. |
| |
| -- Function: unsigned long int wcstoul (const wchar_t *restrict STRING, |
| wchar_t **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstoul' function is equivalent to the 'strtoul' function in |
| nearly all aspects but handles wide character strings. |
| |
| The 'wcstoul' function was introduced in Amendment 1 of ISO C90. |
| |
| -- Function: long long int strtoll (const char *restrict STRING, char |
| **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'strtoll' function is like 'strtol' except that it returns a |
| 'long long int' value, and accepts numbers with a correspondingly |
| larger range. |
| |
| If the string has valid syntax for an integer but the value is not |
| representable because of overflow, 'strtoll' returns either |
| 'LLONG_MAX' or 'LLONG_MIN' (*note Range of Type::), as appropriate |
| for the sign of the value. It also sets 'errno' to 'ERANGE' to |
| indicate there was overflow. |
| |
| The 'strtoll' function was introduced in ISO C99. |
| |
| -- Function: long long int wcstoll (const wchar_t *restrict STRING, |
| wchar_t **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstoll' function is equivalent to the 'strtoll' function in |
| nearly all aspects but handles wide character strings. |
| |
| The 'wcstoll' function was introduced in Amendment 1 of ISO C90. |
| |
| -- Function: long long int strtoq (const char *restrict STRING, char |
| **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| 'strtoq' ("string-to-quad-word") is the BSD name for 'strtoll'. |
| |
| -- Function: long long int wcstoq (const wchar_t *restrict STRING, |
| wchar_t **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstoq' function is equivalent to the 'strtoq' function in |
| nearly all aspects but handles wide character strings. |
| |
| The 'wcstoq' function is a GNU extension. |
| |
| -- Function: unsigned long long int strtoull (const char *restrict |
| STRING, char **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'strtoull' function is related to 'strtoll' the same way |
| 'strtoul' is related to 'strtol'. |
| |
| The 'strtoull' function was introduced in ISO C99. |
| |
| -- Function: unsigned long long int wcstoull (const wchar_t *restrict |
| STRING, wchar_t **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstoull' function is equivalent to the 'strtoull' function in |
| nearly all aspects but handles wide character strings. |
| |
| The 'wcstoull' function was introduced in Amendment 1 of ISO C90. |
| |
| -- Function: unsigned long long int strtouq (const char *restrict |
| STRING, char **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| 'strtouq' is the BSD name for 'strtoull'. |
| |
| -- Function: unsigned long long int wcstouq (const wchar_t *restrict |
| STRING, wchar_t **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstouq' function is equivalent to the 'strtouq' function in |
| nearly all aspects but handles wide character strings. |
| |
| The 'wcstouq' function is a GNU extension. |
| |
| -- Function: intmax_t strtoimax (const char *restrict STRING, char |
| **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'strtoimax' function is like 'strtol' except that it returns a |
| 'intmax_t' value, and accepts numbers of a corresponding range. |
| |
| If the string has valid syntax for an integer but the value is not |
| representable because of overflow, 'strtoimax' returns either |
| 'INTMAX_MAX' or 'INTMAX_MIN' (*note Integers::), as appropriate for |
| the sign of the value. It also sets 'errno' to 'ERANGE' to |
| indicate there was overflow. |
| |
| See *note Integers:: for a description of the 'intmax_t' type. The |
| 'strtoimax' function was introduced in ISO C99. |
| |
| -- Function: intmax_t wcstoimax (const wchar_t *restrict STRING, |
| wchar_t **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstoimax' function is equivalent to the 'strtoimax' function |
| in nearly all aspects but handles wide character strings. |
| |
| The 'wcstoimax' function was introduced in ISO C99. |
| |
| -- Function: uintmax_t strtoumax (const char *restrict STRING, char |
| **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'strtoumax' function is related to 'strtoimax' the same way |
| that 'strtoul' is related to 'strtol'. |
| |
| See *note Integers:: for a description of the 'intmax_t' type. The |
| 'strtoumax' function was introduced in ISO C99. |
| |
| -- Function: uintmax_t wcstoumax (const wchar_t *restrict STRING, |
| wchar_t **restrict TAILPTR, int BASE) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstoumax' function is equivalent to the 'strtoumax' function |
| in nearly all aspects but handles wide character strings. |
| |
| The 'wcstoumax' function was introduced in ISO C99. |
| |
| -- Function: long int atol (const char *STRING) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function is similar to the 'strtol' function with a BASE |
| argument of '10', except that it need not detect overflow errors. |
| The 'atol' function is provided mostly for compatibility with |
| existing code; using 'strtol' is more robust. |
| |
| -- Function: int atoi (const char *STRING) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function is like 'atol', except that it returns an 'int'. The |
| 'atoi' function is also considered obsolete; use 'strtol' instead. |
| |
| -- Function: long long int atoll (const char *STRING) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function is similar to 'atol', except it returns a 'long long |
| int'. |
| |
| The 'atoll' function was introduced in ISO C99. It too is obsolete |
| (despite having just been added); use 'strtoll' instead. |
| |
| All the functions mentioned in this section so far do not handle |
| alternative representations of characters as described in the locale |
| data. Some locales specify thousands separator and the way they have to |
| be used which can help to make large numbers more readable. To read |
| such numbers one has to use the 'scanf' functions with the ''' flag. |
| |
| Here is a function which parses a string as a sequence of integers |
| and returns the sum of them: |
| |
| int |
| sum_ints_from_string (char *string) |
| { |
| int sum = 0; |
| |
| while (1) { |
| char *tail; |
| int next; |
| |
| /* Skip whitespace by hand, to detect the end. */ |
| while (isspace (*string)) string++; |
| if (*string == 0) |
| break; |
| |
| /* There is more nonwhitespace, */ |
| /* so it ought to be another number. */ |
| errno = 0; |
| /* Parse it. */ |
| next = strtol (string, &tail, 0); |
| /* Add it in, if not overflow. */ |
| if (errno) |
| printf ("Overflow\n"); |
| else |
| sum += next; |
| /* Advance past it. */ |
| string = tail; |
| } |
| |
| return sum; |
| } |
| |
| |
| File: libc.info, Node: Parsing of Floats, Prev: Parsing of Integers, Up: Parsing of Numbers |
| |
| 20.11.2 Parsing of Floats |
| ------------------------- |
| |
| The 'str' functions are declared in 'stdlib.h' and those beginning with |
| 'wcs' are declared in 'wchar.h'. One might wonder about the use of |
| 'restrict' in the prototypes of the functions in this section. It is |
| seemingly useless but the ISO C standard uses it (for the functions |
| defined there) so we have to do it as well. |
| |
| -- Function: double strtod (const char *restrict STRING, char |
| **restrict TAILPTR) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'strtod' ("string-to-double") function converts the initial |
| part of STRING to a floating-point number, which is returned as a |
| value of type 'double'. |
| |
| This function attempts to decompose STRING as follows: |
| |
| * A (possibly empty) sequence of whitespace characters. Which |
| characters are whitespace is determined by the 'isspace' |
| function (*note Classification of Characters::). These are |
| discarded. |
| |
| * An optional plus or minus sign ('+' or '-'). |
| |
| * A floating point number in decimal or hexadecimal format. The |
| decimal format is: |
| |
| - A nonempty sequence of digits optionally containing a |
| decimal-point character--normally '.', but it depends on |
| the locale (*note General Numeric::). |
| |
| - An optional exponent part, consisting of a character 'e' |
| or 'E', an optional sign, and a sequence of digits. |
| |
| The hexadecimal format is as follows: |
| |
| - A 0x or 0X followed by a nonempty sequence of hexadecimal |
| digits optionally containing a decimal-point |
| character--normally '.', but it depends on the locale |
| (*note General Numeric::). |
| |
| - An optional binary-exponent part, consisting of a |
| character 'p' or 'P', an optional sign, and a sequence of |
| digits. |
| |
| * Any remaining characters in the string. If TAILPTR is not a |
| null pointer, a pointer to this tail of the string is stored |
| in '*TAILPTR'. |
| |
| If the string is empty, contains only whitespace, or does not |
| contain an initial substring that has the expected syntax for a |
| floating-point number, no conversion is performed. In this case, |
| 'strtod' returns a value of zero and the value returned in |
| '*TAILPTR' is the value of STRING. |
| |
| In a locale other than the standard '"C"' or '"POSIX"' locales, |
| this function may recognize additional locale-dependent syntax. |
| |
| If the string has valid syntax for a floating-point number but the |
| value is outside the range of a 'double', 'strtod' will signal |
| overflow or underflow as described in *note Math Error Reporting::. |
| |
| 'strtod' recognizes four special input strings. The strings |
| '"inf"' and '"infinity"' are converted to oo, or to the largest |
| representable value if the floating-point format doesn't support |
| infinities. You can prepend a '"+"' or '"-"' to specify the sign. |
| Case is ignored when scanning these strings. |
| |
| The strings '"nan"' and '"nan(CHARS...)"' are converted to NaN. |
| Again, case is ignored. If CHARS... are provided, they are used in |
| some unspecified fashion to select a particular representation of |
| NaN (there can be several). |
| |
| Since zero is a valid result as well as the value returned on |
| error, you should check for errors in the same way as for 'strtol', |
| by examining ERRNO and TAILPTR. |
| |
| -- Function: float strtof (const char *STRING, char **TAILPTR) |
| -- Function: long double strtold (const char *STRING, char **TAILPTR) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| These functions are analogous to 'strtod', but return 'float' and |
| 'long double' values respectively. They report errors in the same |
| way as 'strtod'. 'strtof' can be substantially faster than |
| 'strtod', but has less precision; conversely, 'strtold' can be much |
| slower but has more precision (on systems where 'long double' is a |
| separate type). |
| |
| These functions have been GNU extensions and are new to ISO C99. |
| |
| -- Function: double wcstod (const wchar_t *restrict STRING, wchar_t |
| **restrict TAILPTR) |
| -- Function: float wcstof (const wchar_t *STRING, wchar_t **TAILPTR) |
| -- Function: long double wcstold (const wchar_t *STRING, wchar_t |
| **TAILPTR) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'wcstod', 'wcstof', and 'wcstol' functions are equivalent in |
| nearly all aspect to the 'strtod', 'strtof', and 'strtold' |
| functions but it handles wide character string. |
| |
| The 'wcstod' function was introduced in Amendment 1 of ISO C90. |
| The 'wcstof' and 'wcstold' functions were introduced in ISO C99. |
| |
| -- Function: double atof (const char *STRING) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function is similar to the 'strtod' function, except that it |
| need not detect overflow and underflow errors. The 'atof' function |
| is provided mostly for compatibility with existing code; using |
| 'strtod' is more robust. |
| |
| The GNU C Library also provides '_l' versions of these functions, |
| which take an additional argument, the locale to use in conversion. |
| |
| See also *note Parsing of Integers::. |
| |
| |
| File: libc.info, Node: System V Number Conversion, Prev: Parsing of Numbers, Up: Arithmetic |
| |
| 20.12 Old-fashioned System V number-to-string functions |
| ======================================================= |
| |
| The old System V C library provided three functions to convert numbers |
| to strings, with unusual and hard-to-use semantics. The GNU C Library |
| also provides these functions and some natural extensions. |
| |
| These functions are only available in the GNU C Library and on |
| systems descended from AT&T Unix. Therefore, unless these functions do |
| precisely what you need, it is better to use 'sprintf', which is |
| standard. |
| |
| All these functions are defined in 'stdlib.h'. |
| |
| -- Function: char * ecvt (double VALUE, int NDIGIT, int *DECPT, int |
| *NEG) |
| Preliminary: | MT-Unsafe race:ecvt | AS-Unsafe | AC-Safe | *Note |
| POSIX Safety Concepts::. |
| |
| The function 'ecvt' converts the floating-point number VALUE to a |
| string with at most NDIGIT decimal digits. The returned string |
| contains no decimal point or sign. The first digit of the string |
| is non-zero (unless VALUE is actually zero) and the last digit is |
| rounded to nearest. '*DECPT' is set to the index in the string of |
| the first digit after the decimal point. '*NEG' is set to a |
| nonzero value if VALUE is negative, zero otherwise. |
| |
| If NDIGIT decimal digits would exceed the precision of a 'double' |
| it is reduced to a system-specific value. |
| |
| The returned string is statically allocated and overwritten by each |
| call to 'ecvt'. |
| |
| If VALUE is zero, it is implementation defined whether '*DECPT' is |
| '0' or '1'. |
| |
| For example: 'ecvt (12.3, 5, &d, &n)' returns '"12300"' and sets D |
| to '2' and N to '0'. |
| |
| -- Function: char * fcvt (double VALUE, int NDIGIT, int *DECPT, int |
| *NEG) |
| Preliminary: | MT-Unsafe race:fcvt | AS-Unsafe heap | AC-Unsafe mem |
| | *Note POSIX Safety Concepts::. |
| |
| The function 'fcvt' is like 'ecvt', but NDIGIT specifies the number |
| of digits after the decimal point. If NDIGIT is less than zero, |
| VALUE is rounded to the NDIGIT+1'th place to the left of the |
| decimal point. For example, if NDIGIT is '-1', VALUE will be |
| rounded to the nearest 10. If NDIGIT is negative and larger than |
| the number of digits to the left of the decimal point in VALUE, |
| VALUE will be rounded to one significant digit. |
| |
| If NDIGIT decimal digits would exceed the precision of a 'double' |
| it is reduced to a system-specific value. |
| |
| The returned string is statically allocated and overwritten by each |
| call to 'fcvt'. |
| |
| -- Function: char * gcvt (double VALUE, int NDIGIT, char *BUF) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'gcvt' is functionally equivalent to 'sprintf(buf, "%*g", ndigit, |
| value'. It is provided only for compatibility's sake. It returns |
| BUF. |
| |
| If NDIGIT decimal digits would exceed the precision of a 'double' |
| it is reduced to a system-specific value. |
| |
| As extensions, the GNU C Library provides versions of these three |
| functions that take 'long double' arguments. |
| |
| -- Function: char * qecvt (long double VALUE, int NDIGIT, int *DECPT, |
| int *NEG) |
| Preliminary: | MT-Unsafe race:qecvt | AS-Unsafe | AC-Safe | *Note |
| POSIX Safety Concepts::. |
| |
| This function is equivalent to 'ecvt' except that it takes a 'long |
| double' for the first parameter and that NDIGIT is restricted by |
| the precision of a 'long double'. |
| |
| -- Function: char * qfcvt (long double VALUE, int NDIGIT, int *DECPT, |
| int *NEG) |
| Preliminary: | MT-Unsafe race:qfcvt | AS-Unsafe heap | AC-Unsafe |
| mem | *Note POSIX Safety Concepts::. |
| |
| This function is equivalent to 'fcvt' except that it takes a 'long |
| double' for the first parameter and that NDIGIT is restricted by |
| the precision of a 'long double'. |
| |
| -- Function: char * qgcvt (long double VALUE, int NDIGIT, char *BUF) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is equivalent to 'gcvt' except that it takes a 'long |
| double' for the first parameter and that NDIGIT is restricted by |
| the precision of a 'long double'. |
| |
| The 'ecvt' and 'fcvt' functions, and their 'long double' equivalents, |
| all return a string located in a static buffer which is overwritten by |
| the next call to the function. The GNU C Library provides another set |
| of extended functions which write the converted string into a |
| user-supplied buffer. These have the conventional '_r' suffix. |
| |
| 'gcvt_r' is not necessary, because 'gcvt' already uses a |
| user-supplied buffer. |
| |
| -- Function: int ecvt_r (double VALUE, int NDIGIT, int *DECPT, int |
| *NEG, char *BUF, size_t LEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'ecvt_r' function is the same as 'ecvt', except that it places |
| its result into the user-specified buffer pointed to by BUF, with |
| length LEN. The return value is '-1' in case of an error and zero |
| otherwise. |
| |
| This function is a GNU extension. |
| |
| -- Function: int fcvt_r (double VALUE, int NDIGIT, int *DECPT, int |
| *NEG, char *BUF, size_t LEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'fcvt_r' function is the same as 'fcvt', except that it places |
| its result into the user-specified buffer pointed to by BUF, with |
| length LEN. The return value is '-1' in case of an error and zero |
| otherwise. |
| |
| This function is a GNU extension. |
| |
| -- Function: int qecvt_r (long double VALUE, int NDIGIT, int *DECPT, |
| int *NEG, char *BUF, size_t LEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'qecvt_r' function is the same as 'qecvt', except that it |
| places its result into the user-specified buffer pointed to by BUF, |
| with length LEN. The return value is '-1' in case of an error and |
| zero otherwise. |
| |
| This function is a GNU extension. |
| |
| -- Function: int qfcvt_r (long double VALUE, int NDIGIT, int *DECPT, |
| int *NEG, char *BUF, size_t LEN) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'qfcvt_r' function is the same as 'qfcvt', except that it |
| places its result into the user-specified buffer pointed to by BUF, |
| with length LEN. The return value is '-1' in case of an error and |
| zero otherwise. |
| |
| This function is a GNU extension. |
| |
| |
| File: libc.info, Node: Date and Time, Next: Resource Usage And Limitation, Prev: Arithmetic, Up: Top |
| |
| 21 Date and Time |
| **************** |
| |
| This chapter describes functions for manipulating dates and times, |
| including functions for determining what time it is and conversion |
| between different time representations. |
| |
| * Menu: |
| |
| * Time Basics:: Concepts and definitions. |
| * Elapsed Time:: Data types to represent elapsed times |
| * Processor And CPU Time:: Time a program has spent executing. |
| * Calendar Time:: Manipulation of "real" dates and times. |
| * Setting an Alarm:: Sending a signal after a specified time. |
| * Sleeping:: Waiting for a period of time. |
| |
| |
| File: libc.info, Node: Time Basics, Next: Elapsed Time, Up: Date and Time |
| |
| 21.1 Time Basics |
| ================ |
| |
| Discussing time in a technical manual can be difficult because the word |
| "time" in English refers to lots of different things. In this manual, |
| we use a rigorous terminology to avoid confusion, and the only thing we |
| use the simple word "time" for is to talk about the abstract concept. |
| |
| A "calendar time" is a point in the time continuum, for example |
| November 4, 1990 at 18:02.5 UTC. Sometimes this is called "absolute |
| time". |
| |
| We don't speak of a "date", because that is inherent in a calendar |
| time. |
| |
| An "interval" is a contiguous part of the time continuum between two |
| calendar times, for example the hour between 9:00 and 10:00 on July 4, |
| 1980. |
| |
| An "elapsed time" is the length of an interval, for example, 35 |
| minutes. People sometimes sloppily use the word "interval" to refer to |
| the elapsed time of some interval. |
| |
| An "amount of time" is a sum of elapsed times, which need not be of |
| any specific intervals. For example, the amount of time it takes to |
| read a book might be 9 hours, independently of when and in how many |
| sittings it is read. |
| |
| A "period" is the elapsed time of an interval between two events, |
| especially when they are part of a sequence of regularly repeating |
| events. |
| |
| "CPU time" is like calendar time, except that it is based on the |
| subset of the time continuum when a particular process is actively using |
| a CPU. CPU time is, therefore, relative to a process. |
| |
| "Processor time" is an amount of time that a CPU is in use. In fact, |
| it's a basic system resource, since there's a limit to how much can |
| exist in any given interval (that limit is the elapsed time of the |
| interval times the number of CPUs in the processor). People often call |
| this CPU time, but we reserve the latter term in this manual for the |
| definition above. |
| |
| |
| File: libc.info, Node: Elapsed Time, Next: Processor And CPU Time, Prev: Time Basics, Up: Date and Time |
| |
| 21.2 Elapsed Time |
| ================= |
| |
| One way to represent an elapsed time is with a simple arithmetic data |
| type, as with the following function to compute the elapsed time between |
| two calendar times. This function is declared in 'time.h'. |
| |
| -- Function: double difftime (time_t TIME1, time_t TIME0) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'difftime' function returns the number of seconds of elapsed |
| time between calendar time TIME1 and calendar time TIME0, as a |
| value of type 'double'. The difference ignores leap seconds unless |
| leap second support is enabled. |
| |
| In the GNU C Library, you can simply subtract 'time_t' values. But |
| on other systems, the 'time_t' data type might use some other |
| encoding where subtraction doesn't work directly. |
| |
| The GNU C Library provides two data types specifically for |
| representing an elapsed time. They are used by various GNU C Library |
| functions, and you can use them for your own purposes too. They're |
| exactly the same except that one has a resolution in microseconds, and |
| the other, newer one, is in nanoseconds. |
| |
| -- Data Type: struct timeval |
| The 'struct timeval' structure represents an elapsed time. It is |
| declared in 'sys/time.h' and has the following members: |
| |
| 'long int tv_sec' |
| This represents the number of whole seconds of elapsed time. |
| |
| 'long int tv_usec' |
| This is the rest of the elapsed time (a fraction of a second), |
| represented as the number of microseconds. It is always less |
| than one million. |
| |
| -- Data Type: struct timespec |
| The 'struct timespec' structure represents an elapsed time. It is |
| declared in 'time.h' and has the following members: |
| |
| 'long int tv_sec' |
| This represents the number of whole seconds of elapsed time. |
| |
| 'long int tv_nsec' |
| This is the rest of the elapsed time (a fraction of a second), |
| represented as the number of nanoseconds. It is always less |
| than one billion. |
| |
| It is often necessary to subtract two values of type 'struct timeval' |
| or 'struct timespec'. Here is the best way to do this. It works even |
| on some peculiar operating systems where the 'tv_sec' member has an |
| unsigned type. |
| |
| |
| /* Subtract the 'struct timeval' values X and Y, |
| storing the result in RESULT. |
| Return 1 if the difference is negative, otherwise 0. */ |
| |
| int |
| timeval_subtract (result, x, y) |
| struct timeval *result, *x, *y; |
| { |
| /* Perform the carry for the later subtraction by updating Y. */ |
| if (x->tv_usec < y->tv_usec) { |
| int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1; |
| y->tv_usec -= 1000000 * nsec; |
| y->tv_sec += nsec; |
| } |
| if (x->tv_usec - y->tv_usec > 1000000) { |
| int nsec = (x->tv_usec - y->tv_usec) / 1000000; |
| y->tv_usec += 1000000 * nsec; |
| y->tv_sec -= nsec; |
| } |
| |
| /* Compute the time remaining to wait. |
| 'tv_usec' is certainly positive. */ |
| result->tv_sec = x->tv_sec - y->tv_sec; |
| result->tv_usec = x->tv_usec - y->tv_usec; |
| |
| /* Return 1 if result is negative. */ |
| return x->tv_sec < y->tv_sec; |
| } |
| |
| Common functions that use 'struct timeval' are 'gettimeofday' and |
| 'settimeofday'. |
| |
| There are no GNU C Library functions specifically oriented toward |
| dealing with elapsed times, but the calendar time, processor time, and |
| alarm and sleeping functions have a lot to do with them. |
| |
| |
| File: libc.info, Node: Processor And CPU Time, Next: Calendar Time, Prev: Elapsed Time, Up: Date and Time |
| |
| 21.3 Processor And CPU Time |
| =========================== |
| |
| If you're trying to optimize your program or measure its efficiency, |
| it's very useful to know how much processor time it uses. For that, |
| calendar time and elapsed times are useless because a process may spend |
| time waiting for I/O or for other processes to use the CPU. However, you |
| can get the information with the functions in this section. |
| |
| CPU time (*note Time Basics::) is represented by the data type |
| 'clock_t', which is a number of "clock ticks". It gives the total |
| amount of time a process has actively used a CPU since some arbitrary |
| event. On GNU systems, that event is the creation of the process. |
| While arbitrary in general, the event is always the same event for any |
| particular process, so you can always measure how much time on the CPU a |
| particular computation takes by examining the process' CPU time before |
| and after the computation. |
| |
| On GNU/Linux and GNU/Hurd systems, 'clock_t' is equivalent to 'long |
| int' and 'CLOCKS_PER_SEC' is an integer value. But in other systems, |
| both 'clock_t' and the macro 'CLOCKS_PER_SEC' can be either integer or |
| floating-point types. Casting CPU time values to 'double', as in the |
| example above, makes sure that operations such as arithmetic and |
| printing work properly and consistently no matter what the underlying |
| representation is. |
| |
| Note that the clock can wrap around. On a 32bit system with |
| 'CLOCKS_PER_SEC' set to one million this function will return the same |
| value approximately every 72 minutes. |
| |
| For additional functions to examine a process' use of processor time, |
| and to control it, see *note Resource Usage And Limitation::. |
| |
| * Menu: |
| |
| * CPU Time:: The 'clock' function. |
| * Processor Time:: The 'times' function. |
| |
| |
| File: libc.info, Node: CPU Time, Next: Processor Time, Up: Processor And CPU Time |
| |
| 21.3.1 CPU Time Inquiry |
| ----------------------- |
| |
| To get a process' CPU time, you can use the 'clock' function. This |
| facility is declared in the header file 'time.h'. |
| |
| In typical usage, you call the 'clock' function at the beginning and |
| end of the interval you want to time, subtract the values, and then |
| divide by 'CLOCKS_PER_SEC' (the number of clock ticks per second) to get |
| processor time, like this: |
| |
| #include <time.h> |
| |
| clock_t start, end; |
| double cpu_time_used; |
| |
| start = clock(); |
| ... /* Do the work. */ |
| end = clock(); |
| cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC; |
| |
| Do not use a single CPU time as an amount of time; it doesn't work |
| that way. Either do a subtraction as shown above or query processor |
| time directly. *Note Processor Time::. |
| |
| Different computers and operating systems vary wildly in how they |
| keep track of CPU time. It's common for the internal processor clock to |
| have a resolution somewhere between a hundredth and millionth of a |
| second. |
| |
| -- Macro: int CLOCKS_PER_SEC |
| The value of this macro is the number of clock ticks per second |
| measured by the 'clock' function. POSIX requires that this value |
| be one million independent of the actual resolution. |
| |
| -- Data Type: clock_t |
| This is the type of the value returned by the 'clock' function. |
| Values of type 'clock_t' are numbers of clock ticks. |
| |
| -- Function: clock_t clock (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the calling process' current CPU time. If |
| the CPU time is not available or cannot be represented, 'clock' |
| returns the value '(clock_t)(-1)'. |
| |
| |
| File: libc.info, Node: Processor Time, Prev: CPU Time, Up: Processor And CPU Time |
| |
| 21.3.2 Processor Time Inquiry |
| ----------------------------- |
| |
| The 'times' function returns information about a process' consumption of |
| processor time in a 'struct tms' object, in addition to the process' CPU |
| time. *Note Time Basics::. You should include the header file |
| 'sys/times.h' to use this facility. |
| |
| -- Data Type: struct tms |
| The 'tms' structure is used to return information about process |
| times. It contains at least the following members: |
| |
| 'clock_t tms_utime' |
| This is the total processor time the calling process has used |
| in executing the instructions of its program. |
| |
| 'clock_t tms_stime' |
| This is the processor time the system has used on behalf of |
| the calling process. |
| |
| 'clock_t tms_cutime' |
| This is the sum of the 'tms_utime' values and the 'tms_cutime' |
| values of all terminated child processes of the calling |
| process, whose status has been reported to the parent process |
| by 'wait' or 'waitpid'; see *note Process Completion::. In |
| other words, it represents the total processor time used in |
| executing the instructions of all the terminated child |
| processes of the calling process, excluding child processes |
| which have not yet been reported by 'wait' or 'waitpid'. |
| |
| 'clock_t tms_cstime' |
| This is similar to 'tms_cutime', but represents the total |
| processor time system has used on behalf of all the terminated |
| child processes of the calling process. |
| |
| All of the times are given in numbers of clock ticks. Unlike CPU |
| time, these are the actual amounts of time; not relative to any |
| event. *Note Creating a Process::. |
| |
| -- Macro: int CLK_TCK |
| This is an obsolete name for the number of clock ticks per second. |
| Use 'sysconf (_SC_CLK_TCK)' instead. |
| |
| -- Function: clock_t times (struct tms *BUFFER) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'times' function stores the processor time information for the |
| calling process in BUFFER. |
| |
| The return value is the number of clock ticks since an arbitrary |
| point in the past, e.g. since system start-up. 'times' returns |
| '(clock_t)(-1)' to indicate failure. |
| |
| *Portability Note:* The 'clock' function described in *note CPU |
| Time:: is specified by the ISO C standard. The 'times' function is a |
| feature of POSIX.1. On GNU systems, the CPU time is defined to be |
| equivalent to the sum of the 'tms_utime' and 'tms_stime' fields returned |
| by 'times'. |
| |
| |
| File: libc.info, Node: Calendar Time, Next: Setting an Alarm, Prev: Processor And CPU Time, Up: Date and Time |
| |
| 21.4 Calendar Time |
| ================== |
| |
| This section describes facilities for keeping track of calendar time. |
| *Note Time Basics::. |
| |
| The GNU C Library represents calendar time three ways: |
| |
| * "Simple time" (the 'time_t' data type) is a compact representation, |
| typically giving the number of seconds of elapsed time since some |
| implementation-specific base time. |
| |
| * There is also a "high-resolution time" representation. Like simple |
| time, this represents a calendar time as an elapsed time since a |
| base time, but instead of measuring in whole seconds, it uses a |
| 'struct timeval' data type, which includes fractions of a second. |
| Use this time representation instead of simple time when you need |
| greater precision. |
| |
| * "Local time" or "broken-down time" (the 'struct tm' data type) |
| represents a calendar time as a set of components specifying the |
| year, month, and so on in the Gregorian calendar, for a specific |
| time zone. This calendar time representation is usually used only |
| to communicate with people. |
| |
| * Menu: |
| |
| * Simple Calendar Time:: Facilities for manipulating calendar time. |
| * High-Resolution Calendar:: A time representation with greater precision. |
| * Broken-down Time:: Facilities for manipulating local time. |
| * High Accuracy Clock:: Maintaining a high accuracy system clock. |
| * Formatting Calendar Time:: Converting times to strings. |
| * Parsing Date and Time:: Convert textual time and date information back |
| into broken-down time values. |
| * TZ Variable:: How users specify the time zone. |
| * Time Zone Functions:: Functions to examine or specify the time zone. |
| * Time Functions Example:: An example program showing use of some of |
| the time functions. |
| |
| |
| File: libc.info, Node: Simple Calendar Time, Next: High-Resolution Calendar, Up: Calendar Time |
| |
| 21.4.1 Simple Calendar Time |
| --------------------------- |
| |
| This section describes the 'time_t' data type for representing calendar |
| time as simple time, and the functions which operate on simple time |
| objects. These facilities are declared in the header file 'time.h'. |
| |
| -- Data Type: time_t |
| This is the data type used to represent simple time. Sometimes, it |
| also represents an elapsed time. When interpreted as a calendar |
| time value, it represents the number of seconds elapsed since |
| 00:00:00 on January 1, 1970, Coordinated Universal Time. (This |
| calendar time is sometimes referred to as the "epoch".) POSIX |
| requires that this count not include leap seconds, but on some |
| systems this count includes leap seconds if you set 'TZ' to certain |
| values (*note TZ Variable::). |
| |
| Note that a simple time has no concept of local time zone. |
| Calendar Time T is the same instant in time regardless of where on |
| the globe the computer is. |
| |
| In the GNU C Library, 'time_t' is equivalent to 'long int'. In |
| other systems, 'time_t' might be either an integer or |
| floating-point type. |
| |
| The function 'difftime' tells you the elapsed time between two simple |
| calendar times, which is not always as easy to compute as just |
| subtracting. *Note Elapsed Time::. |
| |
| -- Function: time_t time (time_t *RESULT) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'time' function returns the current calendar time as a value of |
| type 'time_t'. If the argument RESULT is not a null pointer, the |
| calendar time value is also stored in '*RESULT'. If the current |
| calendar time is not available, the value '(time_t)(-1)' is |
| returned. |
| |
| -- Function: int stime (const time_t *NEWTIME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'stime' sets the system clock, i.e., it tells the system that the |
| current calendar time is NEWTIME, where 'newtime' is interpreted as |
| described in the above definition of 'time_t'. |
| |
| 'settimeofday' is a newer function which sets the system clock to |
| better than one second precision. 'settimeofday' is generally a |
| better choice than 'stime'. *Note High-Resolution Calendar::. |
| |
| Only the superuser can set the system clock. |
| |
| If the function succeeds, the return value is zero. Otherwise, it |
| is '-1' and 'errno' is set accordingly: |
| |
| 'EPERM' |
| The process is not superuser. |
| |
| |
| File: libc.info, Node: High-Resolution Calendar, Next: Broken-down Time, Prev: Simple Calendar Time, Up: Calendar Time |
| |
| 21.4.2 High-Resolution Calendar |
| ------------------------------- |
| |
| The 'time_t' data type used to represent simple times has a resolution |
| of only one second. Some applications need more precision. |
| |
| So, the GNU C Library also contains functions which are capable of |
| representing calendar times to a higher resolution than one second. The |
| functions and the associated data types described in this section are |
| declared in 'sys/time.h'. |
| |
| -- Data Type: struct timezone |
| The 'struct timezone' structure is used to hold minimal information |
| about the local time zone. It has the following members: |
| |
| 'int tz_minuteswest' |
| This is the number of minutes west of UTC. |
| |
| 'int tz_dsttime' |
| If nonzero, Daylight Saving Time applies during some part of |
| the year. |
| |
| The 'struct timezone' type is obsolete and should never be used. |
| Instead, use the facilities described in *note Time Zone |
| Functions::. |
| |
| -- Function: int gettimeofday (struct timeval *TP, struct timezone |
| *TZP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'gettimeofday' function returns the current calendar time as |
| the elapsed time since the epoch in the 'struct timeval' structure |
| indicated by TP. (*note Elapsed Time:: for a description of |
| 'struct timeval'). Information about the time zone is returned in |
| the structure pointed at TZP. If the TZP argument is a null |
| pointer, time zone information is ignored. |
| |
| The return value is '0' on success and '-1' on failure. The |
| following 'errno' error condition is defined for this function: |
| |
| 'ENOSYS' |
| The operating system does not support getting time zone |
| information, and TZP is not a null pointer. GNU systems do |
| not support using 'struct timezone' to represent time zone |
| information; that is an obsolete feature of 4.3 BSD. Instead, |
| use the facilities described in *note Time Zone Functions::. |
| |
| -- Function: int settimeofday (const struct timeval *TP, const struct |
| timezone *TZP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'settimeofday' function sets the current calendar time in the |
| system clock according to the arguments. As for 'gettimeofday', |
| the calendar time is represented as the elapsed time since the |
| epoch. As for 'gettimeofday', time zone information is ignored if |
| TZP is a null pointer. |
| |
| You must be a privileged user in order to use 'settimeofday'. |
| |
| Some kernels automatically set the system clock from some source |
| such as a hardware clock when they start up. Others, including |
| Linux, place the system clock in an "invalid" state (in which |
| attempts to read the clock fail). A call of 'stime' removes the |
| system clock from an invalid state, and system startup scripts |
| typically run a program that calls 'stime'. |
| |
| 'settimeofday' causes a sudden jump forwards or backwards, which |
| can cause a variety of problems in a system. Use 'adjtime' (below) |
| to make a smooth transition from one time to another by temporarily |
| speeding up or slowing down the clock. |
| |
| With a Linux kernel, 'adjtimex' does the same thing and can also |
| make permanent changes to the speed of the system clock so it |
| doesn't need to be corrected as often. |
| |
| The return value is '0' on success and '-1' on failure. The |
| following 'errno' error conditions are defined for this function: |
| |
| 'EPERM' |
| This process cannot set the clock because it is not |
| privileged. |
| |
| 'ENOSYS' |
| The operating system does not support setting time zone |
| information, and TZP is not a null pointer. |
| |
| -- Function: int adjtime (const struct timeval *DELTA, struct timeval |
| *OLDDELTA) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function speeds up or slows down the system clock in order to |
| make a gradual adjustment. This ensures that the calendar time |
| reported by the system clock is always monotonically increasing, |
| which might not happen if you simply set the clock. |
| |
| The DELTA argument specifies a relative adjustment to be made to |
| the clock time. If negative, the system clock is slowed down for a |
| while until it has lost this much elapsed time. If positive, the |
| system clock is speeded up for a while. |
| |
| If the OLDDELTA argument is not a null pointer, the 'adjtime' |
| function returns information about any previous time adjustment |
| that has not yet completed. |
| |
| This function is typically used to synchronize the clocks of |
| computers in a local network. You must be a privileged user to use |
| it. |
| |
| With a Linux kernel, you can use the 'adjtimex' function to |
| permanently change the clock speed. |
| |
| The return value is '0' on success and '-1' on failure. The |
| following 'errno' error condition is defined for this function: |
| |
| 'EPERM' |
| You do not have privilege to set the time. |
| |
| *Portability Note:* The 'gettimeofday', 'settimeofday', and 'adjtime' |
| functions are derived from BSD. |
| |
| Symbols for the following function are declared in 'sys/timex.h'. |
| |
| -- Function: int adjtimex (struct timex *TIMEX) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'adjtimex' is functionally identical to 'ntp_adjtime'. *Note High |
| Accuracy Clock::. |
| |
| This function is present only with a Linux kernel. |
| |
| |
| File: libc.info, Node: Broken-down Time, Next: High Accuracy Clock, Prev: High-Resolution Calendar, Up: Calendar Time |
| |
| 21.4.3 Broken-down Time |
| ----------------------- |
| |
| Calendar time is represented by the usual GNU C Library functions as an |
| elapsed time since a fixed base calendar time. This is convenient for |
| computation, but has no relation to the way people normally think of |
| calendar time. By contrast, "broken-down time" is a binary |
| representation of calendar time separated into year, month, day, and so |
| on. Broken-down time values are not useful for calculations, but they |
| are useful for printing human readable time information. |
| |
| A broken-down time value is always relative to a choice of time zone, |
| and it also indicates which time zone that is. |
| |
| The symbols in this section are declared in the header file 'time.h'. |
| |
| -- Data Type: struct tm |
| This is the data type used to represent a broken-down time. The |
| structure contains at least the following members, which can appear |
| in any order. |
| |
| 'int tm_sec' |
| This is the number of full seconds since the top of the minute |
| (normally in the range '0' through '59', but the actual upper |
| limit is '60', to allow for leap seconds if leap second |
| support is available). |
| |
| 'int tm_min' |
| This is the number of full minutes since the top of the hour |
| (in the range '0' through '59'). |
| |
| 'int tm_hour' |
| This is the number of full hours past midnight (in the range |
| '0' through '23'). |
| |
| 'int tm_mday' |
| This is the ordinal day of the month (in the range '1' through |
| '31'). Watch out for this one! As the only ordinal number in |
| the structure, it is inconsistent with the rest of the |
| structure. |
| |
| 'int tm_mon' |
| This is the number of full calendar months since the beginning |
| of the year (in the range '0' through '11'). Watch out for |
| this one! People usually use ordinal numbers for |
| month-of-year (where January = 1). |
| |
| 'int tm_year' |
| This is the number of full calendar years since 1900. |
| |
| 'int tm_wday' |
| This is the number of full days since Sunday (in the range '0' |
| through '6'). |
| |
| 'int tm_yday' |
| This is the number of full days since the beginning of the |
| year (in the range '0' through '365'). |
| |
| 'int tm_isdst' |
| This is a flag that indicates whether Daylight Saving Time is |
| (or was, or will be) in effect at the time described. The |
| value is positive if Daylight Saving Time is in effect, zero |
| if it is not, and negative if the information is not |
| available. |
| |
| 'long int tm_gmtoff' |
| This field describes the time zone that was used to compute |
| this broken-down time value, including any adjustment for |
| daylight saving; it is the number of seconds that you must add |
| to UTC to get local time. You can also think of this as the |
| number of seconds east of UTC. For example, for U.S. Eastern |
| Standard Time, the value is '-5*60*60'. The 'tm_gmtoff' field |
| is derived from BSD and is a GNU library extension; it is not |
| visible in a strict ISO C environment. |
| |
| 'const char *tm_zone' |
| This field is the name for the time zone that was used to |
| compute this broken-down time value. Like 'tm_gmtoff', this |
| field is a BSD and GNU extension, and is not visible in a |
| strict ISO C environment. |
| |
| -- Function: struct tm * localtime (const time_t *TIME) |
| Preliminary: | MT-Unsafe race:tmbuf env locale | AS-Unsafe heap |
| lock | AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::. |
| |
| The 'localtime' function converts the simple time pointed to by |
| TIME to broken-down time representation, expressed relative to the |
| user's specified time zone. |
| |
| The return value is a pointer to a static broken-down time |
| structure, which might be overwritten by subsequent calls to |
| 'ctime', 'gmtime', or 'localtime'. (But no other library function |
| overwrites the contents of this object.) |
| |
| The return value is the null pointer if TIME cannot be represented |
| as a broken-down time; typically this is because the year cannot |
| fit into an 'int'. |
| |
| Calling 'localtime' also sets the current time zone as if 'tzset' |
| were called. *Note Time Zone Functions::. |
| |
| Using the 'localtime' function is a big problem in multi-threaded |
| programs. The result is returned in a static buffer and this is used in |
| all threads. POSIX.1c introduced a variant of this function. |
| |
| -- Function: struct tm * localtime_r (const time_t *TIME, struct tm |
| *RESULTP) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| The 'localtime_r' function works just like the 'localtime' |
| function. It takes a pointer to a variable containing a simple |
| time and converts it to the broken-down time format. |
| |
| But the result is not placed in a static buffer. Instead it is |
| placed in the object of type 'struct tm' to which the parameter |
| RESULTP points. |
| |
| If the conversion is successful the function returns a pointer to |
| the object the result was written into, i.e., it returns RESULTP. |
| |
| -- Function: struct tm * gmtime (const time_t *TIME) |
| Preliminary: | MT-Unsafe race:tmbuf env locale | AS-Unsafe heap |
| lock | AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function is similar to 'localtime', except that the |
| broken-down time is expressed as Coordinated Universal Time (UTC) |
| (formerly called Greenwich Mean Time (GMT)) rather than relative to |
| a local time zone. |
| |
| As for the 'localtime' function we have the problem that the result |
| is placed in a static variable. POSIX.1c also provides a replacement |
| for 'gmtime'. |
| |
| -- Function: struct tm * gmtime_r (const time_t *TIME, struct tm |
| *RESULTP) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function is similar to 'localtime_r', except that it converts |
| just like 'gmtime' the given time as Coordinated Universal Time. |
| |
| If the conversion is successful the function returns a pointer to |
| the object the result was written into, i.e., it returns RESULTP. |
| |
| -- Function: time_t mktime (struct tm *BROKENTIME) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| The 'mktime' function converts a broken-down time structure to a |
| simple time representation. It also normalizes the contents of the |
| broken-down time structure, and fills in some components based on |
| the values of the others. |
| |
| The 'mktime' function ignores the specified contents of the |
| 'tm_wday', 'tm_yday', 'tm_gmtoff', and 'tm_zone' members of the |
| broken-down time structure. It uses the values of the other |
| components to determine the calendar time; it's permissible for |
| these components to have unnormalized values outside their normal |
| ranges. The last thing that 'mktime' does is adjust the components |
| of the BROKENTIME structure, including the members that were |
| initially ignored. |
| |
| If the specified broken-down time cannot be represented as a simple |
| time, 'mktime' returns a value of '(time_t)(-1)' and does not |
| modify the contents of BROKENTIME. |
| |
| Calling 'mktime' also sets the current time zone as if 'tzset' were |
| called; 'mktime' uses this information instead of BROKENTIME's |
| initial 'tm_gmtoff' and 'tm_zone' members. *Note Time Zone |
| Functions::. |
| |
| -- Function: time_t timelocal (struct tm *BROKENTIME) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| 'timelocal' is functionally identical to 'mktime', but more |
| mnemonically named. Note that it is the inverse of the 'localtime' |
| function. |
| |
| *Portability note:* 'mktime' is essentially universally available. |
| 'timelocal' is rather rare. |
| |
| -- Function: time_t timegm (struct tm *BROKENTIME) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| 'timegm' is functionally identical to 'mktime' except it always |
| takes the input values to be Coordinated Universal Time (UTC) |
| regardless of any local time zone setting. |
| |
| Note that 'timegm' is the inverse of 'gmtime'. |
| |
| *Portability note:* 'mktime' is essentially universally available. |
| 'timegm' is rather rare. For the most portable conversion from a |
| UTC broken-down time to a simple time, set the 'TZ' environment |
| variable to UTC, call 'mktime', then set 'TZ' back. |
| |
| |
| File: libc.info, Node: High Accuracy Clock, Next: Formatting Calendar Time, Prev: Broken-down Time, Up: Calendar Time |
| |
| 21.4.4 High Accuracy Clock |
| -------------------------- |
| |
| The 'ntp_gettime' and 'ntp_adjtime' functions provide an interface to |
| monitor and manipulate the system clock to maintain high accuracy time. |
| For example, you can fine tune the speed of the clock or synchronize it |
| with another time source. |
| |
| A typical use of these functions is by a server implementing the |
| Network Time Protocol to synchronize the clocks of multiple systems and |
| high precision clocks. |
| |
| These functions are declared in 'sys/timex.h'. |
| |
| -- Data Type: struct ntptimeval |
| This structure is used for information about the system clock. It |
| contains the following members: |
| 'struct timeval time' |
| This is the current calendar time, expressed as the elapsed |
| time since the epoch. The 'struct timeval' data type is |
| described in *note Elapsed Time::. |
| |
| 'long int maxerror' |
| This is the maximum error, measured in microseconds. Unless |
| updated via 'ntp_adjtime' periodically, this value will reach |
| some platform-specific maximum value. |
| |
| 'long int esterror' |
| This is the estimated error, measured in microseconds. This |
| value can be set by 'ntp_adjtime' to indicate the estimated |
| offset of the system clock from the true calendar time. |
| |
| -- Function: int ntp_gettime (struct ntptimeval *TPTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'ntp_gettime' function sets the structure pointed to by TPTR to |
| current values. The elements of the structure afterwards contain |
| the values the timer implementation in the kernel assumes. They |
| might or might not be correct. If they are not a 'ntp_adjtime' |
| call is necessary. |
| |
| The return value is '0' on success and other values on failure. |
| The following 'errno' error conditions are defined for this |
| function: |
| |
| 'TIME_ERROR' |
| The precision clock model is not properly set up at the |
| moment, thus the clock must be considered unsynchronized, and |
| the values should be treated with care. |
| |
| -- Data Type: struct timex |
| This structure is used to control and monitor the system clock. It |
| contains the following members: |
| 'unsigned int modes' |
| This variable controls whether and which values are set. |
| Several symbolic constants have to be combined with _binary |
| or_ to specify the effective mode. These constants start with |
| 'MOD_'. |
| |
| 'long int offset' |
| This value indicates the current offset of the system clock |
| from the true calendar time. The value is given in |
| microseconds. If bit 'MOD_OFFSET' is set in 'modes', the |
| offset (and possibly other dependent values) can be set. The |
| offset's absolute value must not exceed 'MAXPHASE'. |
| |
| 'long int frequency' |
| This value indicates the difference in frequency between the |
| true calendar time and the system clock. The value is |
| expressed as scaled PPM (parts per million, 0.0001%). The |
| scaling is '1 << SHIFT_USEC'. The value can be set with bit |
| 'MOD_FREQUENCY', but the absolute value must not exceed |
| 'MAXFREQ'. |
| |
| 'long int maxerror' |
| This is the maximum error, measured in microseconds. A new |
| value can be set using bit 'MOD_MAXERROR'. Unless updated via |
| 'ntp_adjtime' periodically, this value will increase steadily |
| and reach some platform-specific maximum value. |
| |
| 'long int esterror' |
| This is the estimated error, measured in microseconds. This |
| value can be set using bit 'MOD_ESTERROR'. |
| |
| 'int status' |
| This variable reflects the various states of the clock |
| machinery. There are symbolic constants for the significant |
| bits, starting with 'STA_'. Some of these flags can be |
| updated using the 'MOD_STATUS' bit. |
| |
| 'long int constant' |
| This value represents the bandwidth or stiffness of the PLL |
| (phase locked loop) implemented in the kernel. The value can |
| be changed using bit 'MOD_TIMECONST'. |
| |
| 'long int precision' |
| This value represents the accuracy or the maximum error when |
| reading the system clock. The value is expressed in |
| microseconds. |
| |
| 'long int tolerance' |
| This value represents the maximum frequency error of the |
| system clock in scaled PPM. This value is used to increase the |
| 'maxerror' every second. |
| |
| 'struct timeval time' |
| The current calendar time. |
| |
| 'long int tick' |
| The elapsed time between clock ticks in microseconds. A clock |
| tick is a periodic timer interrupt on which the system clock |
| is based. |
| |
| 'long int ppsfreq' |
| This is the first of a few optional variables that are present |
| only if the system clock can use a PPS (pulse per second) |
| signal to discipline the system clock. The value is expressed |
| in scaled PPM and it denotes the difference in frequency |
| between the system clock and the PPS signal. |
| |
| 'long int jitter' |
| This value expresses a median filtered average of the PPS |
| signal's dispersion in microseconds. |
| |
| 'int shift' |
| This value is a binary exponent for the duration of the PPS |
| calibration interval, ranging from 'PPS_SHIFT' to |
| 'PPS_SHIFTMAX'. |
| |
| 'long int stabil' |
| This value represents the median filtered dispersion of the |
| PPS frequency in scaled PPM. |
| |
| 'long int jitcnt' |
| This counter represents the number of pulses where the jitter |
| exceeded the allowed maximum 'MAXTIME'. |
| |
| 'long int calcnt' |
| This counter reflects the number of successful calibration |
| intervals. |
| |
| 'long int errcnt' |
| This counter represents the number of calibration errors |
| (caused by large offsets or jitter). |
| |
| 'long int stbcnt' |
| This counter denotes the number of calibrations where the |
| stability exceeded the threshold. |
| |
| -- Function: int ntp_adjtime (struct timex *TPTR) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'ntp_adjtime' function sets the structure specified by TPTR to |
| current values. |
| |
| In addition, 'ntp_adjtime' updates some settings to match what you |
| pass to it in *TPTR. Use the 'modes' element of *TPTR to select |
| what settings to update. You can set 'offset', 'freq', 'maxerror', |
| 'esterror', 'status', 'constant', and 'tick'. |
| |
| 'modes' = zero means set nothing. |
| |
| Only the superuser can update settings. |
| |
| The return value is '0' on success and other values on failure. |
| The following 'errno' error conditions are defined for this |
| function: |
| |
| 'TIME_ERROR' |
| The high accuracy clock model is not properly set up at the |
| moment, thus the clock must be considered unsynchronized, and |
| the values should be treated with care. Another reason could |
| be that the specified new values are not allowed. |
| |
| 'EPERM' |
| The process specified a settings update, but is not superuser. |
| |
| For more details see RFC1305 (Network Time Protocol, Version 3) and |
| related documents. |
| |
| *Portability note:* Early versions of the GNU C Library did not |
| have this function but did have the synonymous 'adjtimex'. |
| |
| |
| File: libc.info, Node: Formatting Calendar Time, Next: Parsing Date and Time, Prev: High Accuracy Clock, Up: Calendar Time |
| |
| 21.4.5 Formatting Calendar Time |
| ------------------------------- |
| |
| The functions described in this section format calendar time values as |
| strings. These functions are declared in the header file 'time.h'. |
| |
| -- Function: char * asctime (const struct tm *BROKENTIME) |
| Preliminary: | MT-Unsafe race:asctime locale | AS-Unsafe | AC-Safe |
| | *Note POSIX Safety Concepts::. |
| |
| The 'asctime' function converts the broken-down time value that |
| BROKENTIME points to into a string in a standard format: |
| |
| "Tue May 21 13:46:22 1991\n" |
| |
| The abbreviations for the days of week are: 'Sun', 'Mon', 'Tue', |
| 'Wed', 'Thu', 'Fri', and 'Sat'. |
| |
| The abbreviations for the months are: 'Jan', 'Feb', 'Mar', 'Apr', |
| 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', and 'Dec'. |
| |
| The return value points to a statically allocated string, which |
| might be overwritten by subsequent calls to 'asctime' or 'ctime'. |
| (But no other library function overwrites the contents of this |
| string.) |
| |
| -- Function: char * asctime_r (const struct tm *BROKENTIME, char |
| *BUFFER) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| This function is similar to 'asctime' but instead of placing the |
| result in a static buffer it writes the string in the buffer |
| pointed to by the parameter BUFFER. This buffer should have room |
| for at least 26 bytes, including the terminating null. |
| |
| If no error occurred the function returns a pointer to the string |
| the result was written into, i.e., it returns BUFFER. Otherwise |
| return 'NULL'. |
| |
| -- Function: char * ctime (const time_t *TIME) |
| Preliminary: | MT-Unsafe race:tmbuf race:asctime env locale | |
| AS-Unsafe heap lock | AC-Unsafe lock mem fd | *Note POSIX Safety |
| Concepts::. |
| |
| The 'ctime' function is similar to 'asctime', except that you |
| specify the calendar time argument as a 'time_t' simple time value |
| rather than in broken-down local time format. It is equivalent to |
| |
| asctime (localtime (TIME)) |
| |
| Calling 'ctime' also sets the current time zone as if 'tzset' were |
| called. *Note Time Zone Functions::. |
| |
| -- Function: char * ctime_r (const time_t *TIME, char *BUFFER) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| This function is similar to 'ctime', but places the result in the |
| string pointed to by BUFFER. It is equivalent to (written using |
| gcc extensions, *note (gcc)Statement Exprs::): |
| |
| ({ struct tm tm; asctime_r (localtime_r (time, &tm), buf); }) |
| |
| If no error occurred the function returns a pointer to the string |
| the result was written into, i.e., it returns BUFFER. Otherwise |
| return 'NULL'. |
| |
| -- Function: size_t strftime (char *S, size_t SIZE, const char |
| *TEMPLATE, const struct tm *BROKENTIME) |
| Preliminary: | MT-Safe env locale | AS-Unsafe corrupt heap lock |
| dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to the 'sprintf' function (*note Formatted |
| Input::), but the conversion specifications that can appear in the |
| format template TEMPLATE are specialized for printing components of |
| the date and time BROKENTIME according to the locale currently |
| specified for time conversion (*note Locales::) and the current |
| time zone (*note Time Zone Functions::). |
| |
| Ordinary characters appearing in the TEMPLATE are copied to the |
| output string S; this can include multibyte character sequences. |
| Conversion specifiers are introduced by a '%' character, followed |
| by an optional flag which can be one of the following. These flags |
| are all GNU extensions. The first three affect only the output of |
| numbers: |
| |
| '_' |
| The number is padded with spaces. |
| |
| '-' |
| The number is not padded at all. |
| |
| '0' |
| The number is padded with zeros even if the format specifies |
| padding with spaces. |
| |
| '^' |
| The output uses uppercase characters, but only if this is |
| possible (*note Case Conversion::). |
| |
| The default action is to pad the number with zeros to keep it a |
| constant width. Numbers that do not have a range indicated below |
| are never padded, since there is no natural width for them. |
| |
| Following the flag an optional specification of the width is |
| possible. This is specified in decimal notation. If the natural |
| size of the output is of the field has less than the specified |
| number of characters, the result is written right adjusted and |
| space padded to the given size. |
| |
| An optional modifier can follow the optional flag and width |
| specification. The modifiers, which were first standardized by |
| POSIX.2-1992 and by ISO C99, are: |
| |
| 'E' |
| Use the locale's alternate representation for date and time. |
| This modifier applies to the '%c', '%C', '%x', '%X', '%y' and |
| '%Y' format specifiers. In a Japanese locale, for example, |
| '%Ex' might yield a date format based on the Japanese |
| Emperors' reigns. |
| |
| 'O' |
| Use the locale's alternate numeric symbols for numbers. This |
| modifier applies only to numeric format specifiers. |
| |
| If the format supports the modifier but no alternate representation |
| is available, it is ignored. |
| |
| The conversion specifier ends with a format specifier taken from |
| the following list. The whole '%' sequence is replaced in the |
| output string as follows: |
| |
| '%a' |
| The abbreviated weekday name according to the current locale. |
| |
| '%A' |
| The full weekday name according to the current locale. |
| |
| '%b' |
| The abbreviated month name according to the current locale. |
| |
| '%B' |
| The full month name according to the current locale. |
| |
| Using '%B' together with '%d' produces grammatically incorrect |
| results for some locales. |
| |
| '%c' |
| The preferred calendar time representation for the current |
| locale. |
| |
| '%C' |
| The century of the year. This is equivalent to the greatest |
| integer not greater than the year divided by 100. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%d' |
| The day of the month as a decimal number (range '01' through |
| '31'). |
| |
| '%D' |
| The date using the format '%m/%d/%y'. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%e' |
| The day of the month like with '%d', but padded with blank |
| (range ' 1' through '31'). |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%F' |
| The date using the format '%Y-%m-%d'. This is the form |
| specified in the ISO 8601 standard and is the preferred form |
| for all uses. |
| |
| This format was first standardized by ISO C99 and by |
| POSIX.1-2001. |
| |
| '%g' |
| The year corresponding to the ISO week number, but without the |
| century (range '00' through '99'). This has the same format |
| and value as '%y', except that if the ISO week number (see |
| '%V') belongs to the previous or next year, that year is used |
| instead. |
| |
| This format was first standardized by ISO C99 and by |
| POSIX.1-2001. |
| |
| '%G' |
| The year corresponding to the ISO week number. This has the |
| same format and value as '%Y', except that if the ISO week |
| number (see '%V') belongs to the previous or next year, that |
| year is used instead. |
| |
| This format was first standardized by ISO C99 and by |
| POSIX.1-2001 but was previously available as a GNU extension. |
| |
| '%h' |
| The abbreviated month name according to the current locale. |
| The action is the same as for '%b'. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%H' |
| The hour as a decimal number, using a 24-hour clock (range |
| '00' through '23'). |
| |
| '%I' |
| The hour as a decimal number, using a 12-hour clock (range |
| '01' through '12'). |
| |
| '%j' |
| The day of the year as a decimal number (range '001' through |
| '366'). |
| |
| '%k' |
| The hour as a decimal number, using a 24-hour clock like '%H', |
| but padded with blank (range ' 0' through '23'). |
| |
| This format is a GNU extension. |
| |
| '%l' |
| The hour as a decimal number, using a 12-hour clock like '%I', |
| but padded with blank (range ' 1' through '12'). |
| |
| This format is a GNU extension. |
| |
| '%m' |
| The month as a decimal number (range '01' through '12'). |
| |
| '%M' |
| The minute as a decimal number (range '00' through '59'). |
| |
| '%n' |
| A single '\n' (newline) character. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%p' |
| Either 'AM' or 'PM', according to the given time value; or the |
| corresponding strings for the current locale. Noon is treated |
| as 'PM' and midnight as 'AM'. In most locales 'AM'/'PM' |
| format is not supported, in such cases '"%p"' yields an empty |
| string. |
| |
| '%P' |
| Either 'am' or 'pm', according to the given time value; or the |
| corresponding strings for the current locale, printed in |
| lowercase characters. Noon is treated as 'pm' and midnight as |
| 'am'. In most locales 'AM'/'PM' format is not supported, in |
| such cases '"%P"' yields an empty string. |
| |
| This format is a GNU extension. |
| |
| '%r' |
| The complete calendar time using the AM/PM format of the |
| current locale. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. In the POSIX locale, this format is equivalent to |
| '%I:%M:%S %p'. |
| |
| '%R' |
| The hour and minute in decimal numbers using the format |
| '%H:%M'. |
| |
| This format was first standardized by ISO C99 and by |
| POSIX.1-2001 but was previously available as a GNU extension. |
| |
| '%s' |
| The number of seconds since the epoch, i.e., since 1970-01-01 |
| 00:00:00 UTC. Leap seconds are not counted unless leap second |
| support is available. |
| |
| This format is a GNU extension. |
| |
| '%S' |
| The seconds as a decimal number (range '00' through '60'). |
| |
| '%t' |
| A single '\t' (tabulator) character. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%T' |
| The time of day using decimal numbers using the format |
| '%H:%M:%S'. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%u' |
| The day of the week as a decimal number (range '1' through |
| '7'), Monday being '1'. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%U' |
| The week number of the current year as a decimal number (range |
| '00' through '53'), starting with the first Sunday as the |
| first day of the first week. Days preceding the first Sunday |
| in the year are considered to be in week '00'. |
| |
| '%V' |
| The ISO 8601:1988 week number as a decimal number (range '01' |
| through '53'). ISO weeks start with Monday and end with |
| Sunday. Week '01' of a year is the first week which has the |
| majority of its days in that year; this is equivalent to the |
| week containing the year's first Thursday, and it is also |
| equivalent to the week containing January 4. Week '01' of a |
| year can contain days from the previous year. The week before |
| week '01' of a year is the last week ('52' or '53') of the |
| previous year even if it contains days from the new year. |
| |
| This format was first standardized by POSIX.2-1992 and by |
| ISO C99. |
| |
| '%w' |
| The day of the week as a decimal number (range '0' through |
| '6'), Sunday being '0'. |
| |
| '%W' |
| The week number of the current year as a decimal number (range |
| '00' through '53'), starting with the first Monday as the |
| first day of the first week. All days preceding the first |
| Monday in the year are considered to be in week '00'. |
| |
| '%x' |
| The preferred date representation for the current locale. |
| |
| '%X' |
| The preferred time of day representation for the current |
| locale. |
| |
| '%y' |
| The year without a century as a decimal number (range '00' |
| through '99'). This is equivalent to the year modulo 100. |
| |
| '%Y' |
| The year as a decimal number, using the Gregorian calendar. |
| Years before the year '1' are numbered '0', '-1', and so on. |
| |
| '%z' |
| RFC 822/ISO 8601:1988 style numeric time zone (e.g., '-0600' |
| or '+0100'), or nothing if no time zone is determinable. |
| |
| This format was first standardized by ISO C99 and by |
| POSIX.1-2001 but was previously available as a GNU extension. |
| |
| In the POSIX locale, a full RFC 822 timestamp is generated by |
| the format '"%a, %d %b %Y %H:%M:%S %z"' (or the equivalent |
| '"%a, %d %b %Y %T %z"'). |
| |
| '%Z' |
| The time zone abbreviation (empty if the time zone can't be |
| determined). |
| |
| '%%' |
| A literal '%' character. |
| |
| The SIZE parameter can be used to specify the maximum number of |
| characters to be stored in the array S, including the terminating |
| null character. If the formatted time requires more than SIZE |
| characters, 'strftime' returns zero and the contents of the array S |
| are undefined. Otherwise the return value indicates the number of |
| characters placed in the array S, not including the terminating |
| null character. |
| |
| _Warning:_ This convention for the return value which is prescribed |
| in ISO C can lead to problems in some situations. For certain |
| format strings and certain locales the output really can be the |
| empty string and this cannot be discovered by testing the return |
| value only. E.g., in most locales the AM/PM time format is not |
| supported (most of the world uses the 24 hour time representation). |
| In such locales '"%p"' will return the empty string, i.e., the |
| return value is zero. To detect situations like this something |
| similar to the following code should be used: |
| |
| buf[0] = '\1'; |
| len = strftime (buf, bufsize, format, tp); |
| if (len == 0 && buf[0] != '\0') |
| { |
| /* Something went wrong in the strftime call. */ |
| ... |
| } |
| |
| If S is a null pointer, 'strftime' does not actually write |
| anything, but instead returns the number of characters it would |
| have written. |
| |
| Calling 'strftime' also sets the current time zone as if 'tzset' |
| were called; 'strftime' uses this information instead of |
| BROKENTIME's 'tm_gmtoff' and 'tm_zone' members. *Note Time Zone |
| Functions::. |
| |
| For an example of 'strftime', see *note Time Functions Example::. |
| |
| -- Function: size_t wcsftime (wchar_t *S, size_t SIZE, const wchar_t |
| *TEMPLATE, const struct tm *BROKENTIME) |
| Preliminary: | MT-Safe env locale | AS-Unsafe corrupt heap lock |
| dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety |
| Concepts::. |
| |
| The 'wcsftime' function is equivalent to the 'strftime' function |
| with the difference that it operates on wide character strings. |
| The buffer where the result is stored, pointed to by S, must be an |
| array of wide characters. The parameter SIZE which specifies the |
| size of the output buffer gives the number of wide character, not |
| the number of bytes. |
| |
| Also the format string TEMPLATE is a wide character string. Since |
| all characters needed to specify the format string are in the basic |
| character set it is portably possible to write format strings in |
| the C source code using the 'L"..."' notation. The parameter |
| BROKENTIME has the same meaning as in the 'strftime' call. |
| |
| The 'wcsftime' function supports the same flags, modifiers, and |
| format specifiers as the 'strftime' function. |
| |
| The return value of 'wcsftime' is the number of wide characters |
| stored in 's'. When more characters would have to be written than |
| can be placed in the buffer S the return value is zero, with the |
| same problems indicated in the 'strftime' documentation. |
| |
| |
| File: libc.info, Node: Parsing Date and Time, Next: TZ Variable, Prev: Formatting Calendar Time, Up: Calendar Time |
| |
| 21.4.6 Convert textual time and date information back |
| ----------------------------------------------------- |
| |
| The ISO C standard does not specify any functions which can convert the |
| output of the 'strftime' function back into a binary format. This led |
| to a variety of more-or-less successful implementations with different |
| interfaces over the years. Then the Unix standard was extended by the |
| addition of two functions: 'strptime' and 'getdate'. Both have strange |
| interfaces but at least they are widely available. |
| |
| * Menu: |
| |
| * Low-Level Time String Parsing:: Interpret string according to given format. |
| * General Time String Parsing:: User-friendly function to parse data and |
| time strings. |
| |
| |
| File: libc.info, Node: Low-Level Time String Parsing, Next: General Time String Parsing, Up: Parsing Date and Time |
| |
| 21.4.6.1 Interpret string according to given format |
| ................................................... |
| |
| The first function is rather low-level. It is nevertheless frequently |
| used in software since it is better known. Its interface and |
| implementation are heavily influenced by the 'getdate' function, which |
| is defined and implemented in terms of calls to 'strptime'. |
| |
| -- Function: char * strptime (const char *S, const char *FMT, struct tm |
| *TP) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| The 'strptime' function parses the input string S according to the |
| format string FMT and stores its results in the structure TP. |
| |
| The input string could be generated by a 'strftime' call or |
| obtained any other way. It does not need to be in a |
| human-recognizable format; e.g. a date passed as '"02:1999:9"' is |
| acceptable, even though it is ambiguous without context. As long |
| as the format string FMT matches the input string the function will |
| succeed. |
| |
| The user has to make sure, though, that the input can be parsed in |
| a unambiguous way. The string '"1999112"' can be parsed using the |
| format '"%Y%m%d"' as 1999-1-12, 1999-11-2, or even 19991-1-2. It |
| is necessary to add appropriate separators to reliably get results. |
| |
| The format string consists of the same components as the format |
| string of the 'strftime' function. The only difference is that the |
| flags '_', '-', '0', and '^' are not allowed. Several of the |
| distinct formats of 'strftime' do the same work in 'strptime' since |
| differences like case of the input do not matter. For reasons of |
| symmetry all formats are supported, though. |
| |
| The modifiers 'E' and 'O' are also allowed everywhere the |
| 'strftime' function allows them. |
| |
| The formats are: |
| |
| '%a' |
| '%A' |
| The weekday name according to the current locale, in |
| abbreviated form or the full name. |
| |
| '%b' |
| '%B' |
| '%h' |
| The month name according to the current locale, in abbreviated |
| form or the full name. |
| |
| '%c' |
| The date and time representation for the current locale. |
| |
| '%Ec' |
| Like '%c' but the locale's alternative date and time format is |
| used. |
| |
| '%C' |
| The century of the year. |
| |
| It makes sense to use this format only if the format string |
| also contains the '%y' format. |
| |
| '%EC' |
| The locale's representation of the period. |
| |
| Unlike '%C' it sometimes makes sense to use this format since |
| some cultures represent years relative to the beginning of |
| eras instead of using the Gregorian years. |
| |
| '%d' |
| '%e' |
| The day of the month as a decimal number (range '1' through |
| '31'). Leading zeroes are permitted but not required. |
| |
| '%Od' |
| '%Oe' |
| Same as '%d' but using the locale's alternative numeric |
| symbols. |
| |
| Leading zeroes are permitted but not required. |
| |
| '%D' |
| Equivalent to '%m/%d/%y'. |
| |
| '%F' |
| Equivalent to '%Y-%m-%d', which is the ISO 8601 date format. |
| |
| This is a GNU extension following an ISO C99 extension to |
| 'strftime'. |
| |
| '%g' |
| The year corresponding to the ISO week number, but without the |
| century (range '00' through '99'). |
| |
| _Note:_ Currently, this is not fully implemented. The format |
| is recognized, input is consumed but no field in TM is set. |
| |
| This format is a GNU extension following a GNU extension of |
| 'strftime'. |
| |
| '%G' |
| The year corresponding to the ISO week number. |
| |
| _Note:_ Currently, this is not fully implemented. The format |
| is recognized, input is consumed but no field in TM is set. |
| |
| This format is a GNU extension following a GNU extension of |
| 'strftime'. |
| |
| '%H' |
| '%k' |
| The hour as a decimal number, using a 24-hour clock (range |
| '00' through '23'). |
| |
| '%k' is a GNU extension following a GNU extension of |
| 'strftime'. |
| |
| '%OH' |
| Same as '%H' but using the locale's alternative numeric |
| symbols. |
| |
| '%I' |
| '%l' |
| The hour as a decimal number, using a 12-hour clock (range |
| '01' through '12'). |
| |
| '%l' is a GNU extension following a GNU extension of |
| 'strftime'. |
| |
| '%OI' |
| Same as '%I' but using the locale's alternative numeric |
| symbols. |
| |
| '%j' |
| The day of the year as a decimal number (range '1' through |
| '366'). |
| |
| Leading zeroes are permitted but not required. |
| |
| '%m' |
| The month as a decimal number (range '1' through '12'). |
| |
| Leading zeroes are permitted but not required. |
| |
| '%Om' |
| Same as '%m' but using the locale's alternative numeric |
| symbols. |
| |
| '%M' |
| The minute as a decimal number (range '0' through '59'). |
| |
| Leading zeroes are permitted but not required. |
| |
| '%OM' |
| Same as '%M' but using the locale's alternative numeric |
| symbols. |
| |
| '%n' |
| '%t' |
| Matches any white space. |
| |
| '%p' |
| '%P' |
| The locale-dependent equivalent to 'AM' or 'PM'. |
| |
| This format is not useful unless '%I' or '%l' is also used. |
| Another complication is that the locale might not define these |
| values at all and therefore the conversion fails. |
| |
| '%P' is a GNU extension following a GNU extension to |
| 'strftime'. |
| |
| '%r' |
| The complete time using the AM/PM format of the current |
| locale. |
| |
| A complication is that the locale might not define this format |
| at all and therefore the conversion fails. |
| |
| '%R' |
| The hour and minute in decimal numbers using the format |
| '%H:%M'. |
| |
| '%R' is a GNU extension following a GNU extension to |
| 'strftime'. |
| |
| '%s' |
| The number of seconds since the epoch, i.e., since 1970-01-01 |
| 00:00:00 UTC. Leap seconds are not counted unless leap second |
| support is available. |
| |
| '%s' is a GNU extension following a GNU extension to |
| 'strftime'. |
| |
| '%S' |
| The seconds as a decimal number (range '0' through '60'). |
| |
| Leading zeroes are permitted but not required. |
| |
| *NB:* The Unix specification says the upper bound on this |
| value is '61', a result of a decision to allow double leap |
| seconds. You will not see the value '61' because no minute |
| has more than one leap second, but the myth persists. |
| |
| '%OS' |
| Same as '%S' but using the locale's alternative numeric |
| symbols. |
| |
| '%T' |
| Equivalent to the use of '%H:%M:%S' in this place. |
| |
| '%u' |
| The day of the week as a decimal number (range '1' through |
| '7'), Monday being '1'. |
| |
| Leading zeroes are permitted but not required. |
| |
| _Note:_ Currently, this is not fully implemented. The format |
| is recognized, input is consumed but no field in TM is set. |
| |
| '%U' |
| The week number of the current year as a decimal number (range |
| '0' through '53'). |
| |
| Leading zeroes are permitted but not required. |
| |
| '%OU' |
| Same as '%U' but using the locale's alternative numeric |
| symbols. |
| |
| '%V' |
| The ISO 8601:1988 week number as a decimal number (range '1' |
| through '53'). |
| |
| Leading zeroes are permitted but not required. |
| |
| _Note:_ Currently, this is not fully implemented. The format |
| is recognized, input is consumed but no field in TM is set. |
| |
| '%w' |
| The day of the week as a decimal number (range '0' through |
| '6'), Sunday being '0'. |
| |
| Leading zeroes are permitted but not required. |
| |
| _Note:_ Currently, this is not fully implemented. The format |
| is recognized, input is consumed but no field in TM is set. |
| |
| '%Ow' |
| Same as '%w' but using the locale's alternative numeric |
| symbols. |
| |
| '%W' |
| The week number of the current year as a decimal number (range |
| '0' through '53'). |
| |
| Leading zeroes are permitted but not required. |
| |
| _Note:_ Currently, this is not fully implemented. The format |
| is recognized, input is consumed but no field in TM is set. |
| |
| '%OW' |
| Same as '%W' but using the locale's alternative numeric |
| symbols. |
| |
| '%x' |
| The date using the locale's date format. |
| |
| '%Ex' |
| Like '%x' but the locale's alternative data representation is |
| used. |
| |
| '%X' |
| The time using the locale's time format. |
| |
| '%EX' |
| Like '%X' but the locale's alternative time representation is |
| used. |
| |
| '%y' |
| The year without a century as a decimal number (range '0' |
| through '99'). |
| |
| Leading zeroes are permitted but not required. |
| |
| Note that it is questionable to use this format without the |
| '%C' format. The 'strptime' function does regard input values |
| in the range 68 to 99 as the years 1969 to 1999 and the values |
| 0 to 68 as the years 2000 to 2068. But maybe this heuristic |
| fails for some input data. |
| |
| Therefore it is best to avoid '%y' completely and use '%Y' |
| instead. |
| |
| '%Ey' |
| The offset from '%EC' in the locale's alternative |
| representation. |
| |
| '%Oy' |
| The offset of the year (from '%C') using the locale's |
| alternative numeric symbols. |
| |
| '%Y' |
| The year as a decimal number, using the Gregorian calendar. |
| |
| '%EY' |
| The full alternative year representation. |
| |
| '%z' |
| The offset from GMT in ISO 8601/RFC822 format. |
| |
| '%Z' |
| The timezone name. |
| |
| _Note:_ Currently, this is not fully implemented. The format |
| is recognized, input is consumed but no field in TM is set. |
| |
| '%%' |
| A literal '%' character. |
| |
| All other characters in the format string must have a matching |
| character in the input string. Exceptions are white spaces in the |
| input string which can match zero or more whitespace characters in |
| the format string. |
| |
| *Portability Note:* The XPG standard advises applications to use at |
| least one whitespace character (as specified by 'isspace') or other |
| non-alphanumeric characters between any two conversion |
| specifications. The GNU C Library does not have this limitation |
| but other libraries might have trouble parsing formats like |
| '"%d%m%Y%H%M%S"'. |
| |
| The 'strptime' function processes the input string from right to |
| left. Each of the three possible input elements (white space, |
| literal, or format) are handled one after the other. If the input |
| cannot be matched to the format string the function stops. The |
| remainder of the format and input strings are not processed. |
| |
| The function returns a pointer to the first character it was unable |
| to process. If the input string contains more characters than |
| required by the format string the return value points right after |
| the last consumed input character. If the whole input string is |
| consumed the return value points to the 'NULL' byte at the end of |
| the string. If an error occurs, i.e., 'strptime' fails to match |
| all of the format string, the function returns 'NULL'. |
| |
| The specification of the function in the XPG standard is rather |
| vague, leaving out a few important pieces of information. Most |
| importantly, it does not specify what happens to those elements of TM |
| which are not directly initialized by the different formats. The |
| implementations on different Unix systems vary here. |
| |
| The GNU C Library implementation does not touch those fields which |
| are not directly initialized. Exceptions are the 'tm_wday' and |
| 'tm_yday' elements, which are recomputed if any of the year, month, or |
| date elements changed. This has two implications: |
| |
| * Before calling the 'strptime' function for a new input string, you |
| should prepare the TM structure you pass. Normally this will mean |
| initializing all values are to zero. Alternatively, you can set |
| all fields to values like 'INT_MAX', allowing you to determine |
| which elements were set by the function call. Zero does not work |
| here since it is a valid value for many of the fields. |
| |
| Careful initialization is necessary if you want to find out whether |
| a certain field in TM was initialized by the function call. |
| |
| * You can construct a 'struct tm' value with several consecutive |
| 'strptime' calls. A useful application of this is e.g. the |
| parsing of two separate strings, one containing date information |
| and the other time information. By parsing one after the other |
| without clearing the structure in-between, you can construct a |
| complete broken-down time. |
| |
| The following example shows a function which parses a string which is |
| contains the date information in either US style or ISO 8601 form: |
| |
| const char * |
| parse_date (const char *input, struct tm *tm) |
| { |
| const char *cp; |
| |
| /* First clear the result structure. */ |
| memset (tm, '\0', sizeof (*tm)); |
| |
| /* Try the ISO format first. */ |
| cp = strptime (input, "%F", tm); |
| if (cp == NULL) |
| { |
| /* Does not match. Try the US form. */ |
| cp = strptime (input, "%D", tm); |
| } |
| |
| return cp; |
| } |
| |
| |
| File: libc.info, Node: General Time String Parsing, Prev: Low-Level Time String Parsing, Up: Parsing Date and Time |
| |
| 21.4.6.2 A More User-friendly Way to Parse Times and Dates |
| .......................................................... |
| |
| The Unix standard defines another function for parsing date strings. |
| The interface is weird, but if the function happens to suit your |
| application it is just fine. It is problematic to use this function in |
| multi-threaded programs or libraries, since it returns a pointer to a |
| static variable, and uses a global variable and global state (an |
| environment variable). |
| |
| -- Variable: getdate_err |
| This variable of type 'int' contains the error code of the last |
| unsuccessful call to 'getdate'. Defined values are: |
| |
| 1 |
| The environment variable 'DATEMSK' is not defined or null. |
| 2 |
| The template file denoted by the 'DATEMSK' environment |
| variable cannot be opened. |
| 3 |
| Information about the template file cannot retrieved. |
| 4 |
| The template file is not a regular file. |
| 5 |
| An I/O error occurred while reading the template file. |
| 6 |
| Not enough memory available to execute the function. |
| 7 |
| The template file contains no matching template. |
| 8 |
| The input date is invalid, but would match a template |
| otherwise. This includes dates like February 31st, and dates |
| which cannot be represented in a 'time_t' variable. |
| |
| -- Function: struct tm * getdate (const char *STRING) |
| Preliminary: | MT-Unsafe race:getdate env locale | AS-Unsafe heap |
| lock | AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::. |
| |
| The interface to 'getdate' is the simplest possible for a function |
| to parse a string and return the value. STRING is the input string |
| and the result is returned in a statically-allocated variable. |
| |
| The details about how the string is processed are hidden from the |
| user. In fact, they can be outside the control of the program. |
| Which formats are recognized is controlled by the file named by the |
| environment variable 'DATEMSK'. This file should contain lines of |
| valid format strings which could be passed to 'strptime'. |
| |
| The 'getdate' function reads these format strings one after the |
| other and tries to match the input string. The first line which |
| completely matches the input string is used. |
| |
| Elements not initialized through the format string retain the |
| values present at the time of the 'getdate' function call. |
| |
| The formats recognized by 'getdate' are the same as for 'strptime'. |
| See above for an explanation. There are only a few extensions to |
| the 'strptime' behavior: |
| |
| * If the '%Z' format is given the broken-down time is based on |
| the current time of the timezone matched, not of the current |
| timezone of the runtime environment. |
| |
| _Note_: This is not implemented (currently). The problem is |
| that timezone names are not unique. If a fixed timezone is |
| assumed for a given string (say 'EST' meaning US East Coast |
| time), then uses for countries other than the USA will fail. |
| So far we have found no good solution to this. |
| |
| * If only the weekday is specified the selected day depends on |
| the current date. If the current weekday is greater or equal |
| to the 'tm_wday' value the current week's day is chosen, |
| otherwise the day next week is chosen. |
| |
| * A similar heuristic is used when only the month is given and |
| not the year. If the month is greater than or equal to the |
| current month, then the current year is used. Otherwise it |
| wraps to next year. The first day of the month is assumed if |
| one is not explicitly specified. |
| |
| * The current hour, minute, and second are used if the |
| appropriate value is not set through the format. |
| |
| * If no date is given tomorrow's date is used if the time is |
| smaller than the current time. Otherwise today's date is |
| taken. |
| |
| It should be noted that the format in the template file need not |
| only contain format elements. The following is a list of possible |
| format strings (taken from the Unix standard): |
| |
| %m |
| %A %B %d, %Y %H:%M:%S |
| %A |
| %B |
| %m/%d/%y %I %p |
| %d,%m,%Y %H:%M |
| at %A the %dst of %B in %Y |
| run job at %I %p,%B %dnd |
| %A den %d. %B %Y %H.%M Uhr |
| |
| As you can see, the template list can contain very specific strings |
| like 'run job at %I %p,%B %dnd'. Using the above list of templates |
| and assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we |
| can obtain the following results for the given input. |
| |
| Input Match Result |
| Mon %a Mon Sep 22 12:19:47 EDT 1986 |
| Sun %a Sun Sep 28 12:19:47 EDT 1986 |
| Fri %a Fri Sep 26 12:19:47 EDT 1986 |
| September %B Mon Sep 1 12:19:47 EDT 1986 |
| January %B Thu Jan 1 12:19:47 EST 1987 |
| December %B Mon Dec 1 12:19:47 EST 1986 |
| Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986 |
| Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987 |
| Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986 |
| Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989 |
| Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986 |
| Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987 |
| 10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986 |
| 13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986 |
| |
| The return value of the function is a pointer to a static variable |
| of type 'struct tm', or a null pointer if an error occurred. The |
| result is only valid until the next 'getdate' call, making this |
| function unusable in multi-threaded applications. |
| |
| The 'errno' variable is _not_ changed. Error conditions are stored |
| in the global variable 'getdate_err'. See the description above |
| for a list of the possible error values. |
| |
| _Warning:_ The 'getdate' function should _never_ be used in |
| SUID-programs. The reason is obvious: using the 'DATEMSK' |
| environment variable you can get the function to open any arbitrary |
| file and chances are high that with some bogus input (such as a |
| binary file) the program will crash. |
| |
| -- Function: int getdate_r (const char *STRING, struct tm *TP) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| The 'getdate_r' function is the reentrant counterpart of 'getdate'. |
| It does not use the global variable 'getdate_err' to signal an |
| error, but instead returns an error code. The same error codes as |
| described in the 'getdate_err' documentation above are used, with 0 |
| meaning success. |
| |
| Moreover, 'getdate_r' stores the broken-down time in the variable |
| of type 'struct tm' pointed to by the second argument, rather than |
| in a static variable. |
| |
| This function is not defined in the Unix standard. Nevertheless it |
| is available on some other Unix systems as well. |
| |
| The warning against using 'getdate' in SUID-programs applies to |
| 'getdate_r' as well. |
| |
| |
| File: libc.info, Node: TZ Variable, Next: Time Zone Functions, Prev: Parsing Date and Time, Up: Calendar Time |
| |
| 21.4.7 Specifying the Time Zone with 'TZ' |
| ----------------------------------------- |
| |
| In POSIX systems, a user can specify the time zone by means of the 'TZ' |
| environment variable. For information about how to set environment |
| variables, see *note Environment Variables::. The functions for |
| accessing the time zone are declared in 'time.h'. |
| |
| You should not normally need to set 'TZ'. If the system is |
| configured properly, the default time zone will be correct. You might |
| set 'TZ' if you are using a computer over a network from a different |
| time zone, and would like times reported to you in the time zone local |
| to you, rather than what is local to the computer. |
| |
| In POSIX.1 systems the value of the 'TZ' variable can be in one of |
| three formats. With the GNU C Library, the most common format is the |
| last one, which can specify a selection from a large database of time |
| zone information for many regions of the world. The first two formats |
| are used to describe the time zone information directly, which is both |
| more cumbersome and less precise. But the POSIX.1 standard only |
| specifies the details of the first two formats, so it is good to be |
| familiar with them in case you come across a POSIX.1 system that doesn't |
| support a time zone information database. |
| |
| The first format is used when there is no Daylight Saving Time (or |
| summer time) in the local time zone: |
| |
| STD OFFSET |
| |
| The STD string specifies the name of the time zone. It must be three |
| or more characters long and must not contain a leading colon, embedded |
| digits, commas, nor plus and minus signs. There is no space character |
| separating the time zone name from the OFFSET, so these restrictions are |
| necessary to parse the specification correctly. |
| |
| The OFFSET specifies the time value you must add to the local time to |
| get a Coordinated Universal Time value. It has syntax like |
| ['+'|'-']HH[':'MM[':'SS]]. This is positive if the local time zone is |
| west of the Prime Meridian and negative if it is east. The hour must be |
| between '0' and '24', and the minute and seconds between '0' and '59'. |
| |
| For example, here is how we would specify Eastern Standard Time, but |
| without any Daylight Saving Time alternative: |
| |
| EST+5 |
| |
| The second format is used when there is Daylight Saving Time: |
| |
| STD OFFSET DST [OFFSET]','START['/'TIME]','END['/'TIME] |
| |
| The initial STD and OFFSET specify the standard time zone, as |
| described above. The DST string and OFFSET specify the name and offset |
| for the corresponding Daylight Saving Time zone; if the OFFSET is |
| omitted, it defaults to one hour ahead of standard time. |
| |
| The remainder of the specification describes when Daylight Saving |
| Time is in effect. The START field is when Daylight Saving Time goes |
| into effect and the END field is when the change is made back to |
| standard time. The following formats are recognized for these fields: |
| |
| 'JN' |
| This specifies the Julian day, with N between '1' and '365'. |
| February 29 is never counted, even in leap years. |
| |
| 'N' |
| This specifies the Julian day, with N between '0' and '365'. |
| February 29 is counted in leap years. |
| |
| 'MM.W.D' |
| This specifies day D of week W of month M. The day D must be |
| between '0' (Sunday) and '6'. The week W must be between '1' and |
| '5'; week '1' is the first week in which day D occurs, and week '5' |
| specifies the _last_ D day in the month. The month M should be |
| between '1' and '12'. |
| |
| The TIME fields specify when, in the local time currently in effect, |
| the change to the other time occurs. If omitted, the default is |
| '02:00:00'. The hours part of the time fields can range from -167 |
| through 167; this is an extension to POSIX.1, which allows only the |
| range 0 through 24. |
| |
| Here are some example 'TZ' values, including the appropriate Daylight |
| Saving Time and its dates of applicability. In North American Eastern |
| Standard Time (EST) and Eastern Daylight Time (EDT), the normal offset |
| from UTC is 5 hours; since this is west of the prime meridian, the sign |
| is positive. Summer time begins on March's second Sunday at 2:00am, and |
| ends on November's first Sunday at 2:00am. |
| |
| EST+5EDT,M3.2.0/2,M11.1.0/2 |
| |
| Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours |
| ahead of the prime meridian in winter, springing forward an hour on |
| March's fourth Tuesday at 26:00 (i.e., 02:00 on the first Friday on or |
| after March 23), and falling back on October's last Sunday at 02:00. |
| |
| IST-2IDT,M3.4.4/26,M10.5.0 |
| |
| Western Argentina Summer Time (WARST) is 3 hours behind the prime |
| meridian all year. There is a dummy fall-back transition on December 31 |
| at 25:00 daylight saving time (i.e., 24:00 standard time, equivalent to |
| January 1 at 00:00 standard time), and a simultaneous spring-forward |
| transition on January 1 at 00:00 standard time, so daylight saving time |
| is in effect all year and the initial 'WART' is a placeholder. |
| |
| WART4WARST,J1/0,J365/25 |
| |
| Western Greenland Time (WGT) and Western Greenland Summer Time (WGST) |
| are 3 hours behind UTC in the winter. Its clocks follow the European |
| Union rules of springing forward by one hour on March's last Sunday at |
| 01:00 UTC (-02:00 local time) and falling back on October's last Sunday |
| at 01:00 UTC (-01:00 local time). |
| |
| WGT3WGST,M3.5.0/-2,M10.5.0/-1 |
| |
| The schedule of Daylight Saving Time in any particular jurisdiction |
| has changed over the years. To be strictly correct, the conversion of |
| dates and times in the past should be based on the schedule that was in |
| effect then. However, this format has no facilities to let you specify |
| how the schedule has changed from year to year. The most you can do is |
| specify one particular schedule--usually the present day schedule--and |
| this is used to convert any date, no matter when. For precise time zone |
| specifications, it is best to use the time zone information database |
| (see below). |
| |
| The third format looks like this: |
| |
| :CHARACTERS |
| |
| Each operating system interprets this format differently; in the GNU |
| C Library, CHARACTERS is the name of a file which describes the time |
| zone. |
| |
| If the 'TZ' environment variable does not have a value, the operation |
| chooses a time zone by default. In the GNU C Library, the default time |
| zone is like the specification 'TZ=:/etc/localtime' (or |
| 'TZ=:/usr/local/etc/localtime', depending on how the GNU C Library was |
| configured; *note Installation::). Other C libraries use their own rule |
| for choosing the default time zone, so there is little we can say about |
| them. |
| |
| If CHARACTERS begins with a slash, it is an absolute file name; |
| otherwise the library looks for the file |
| '/share/lib/zoneinfo/CHARACTERS'. The 'zoneinfo' directory contains |
| data files describing local time zones in many different parts of the |
| world. The names represent major cities, with subdirectories for |
| geographical areas; for example, 'America/New_York', 'Europe/London', |
| 'Asia/Hong_Kong'. These data files are installed by the system |
| administrator, who also sets '/etc/localtime' to point to the data file |
| for the local time zone. The GNU C Library comes with a large database |
| of time zone information for most regions of the world, which is |
| maintained by a community of volunteers and put in the public domain. |
| |
| |
| File: libc.info, Node: Time Zone Functions, Next: Time Functions Example, Prev: TZ Variable, Up: Calendar Time |
| |
| 21.4.8 Functions and Variables for Time Zones |
| --------------------------------------------- |
| |
| -- Variable: char * tzname [2] |
| The array 'tzname' contains two strings, which are the standard |
| names of the pair of time zones (standard and Daylight Saving) that |
| the user has selected. 'tzname[0]' is the name of the standard |
| time zone (for example, '"EST"'), and 'tzname[1]' is the name for |
| the time zone when Daylight Saving Time is in use (for example, |
| '"EDT"'). These correspond to the STD and DST strings |
| (respectively) from the 'TZ' environment variable. If Daylight |
| Saving Time is never used, 'tzname[1]' is the empty string. |
| |
| The 'tzname' array is initialized from the 'TZ' environment |
| variable whenever 'tzset', 'ctime', 'strftime', 'mktime', or |
| 'localtime' is called. If multiple abbreviations have been used |
| (e.g. '"EWT"' and '"EDT"' for U.S. Eastern War Time and Eastern |
| Daylight Time), the array contains the most recent abbreviation. |
| |
| The 'tzname' array is required for POSIX.1 compatibility, but in |
| GNU programs it is better to use the 'tm_zone' member of the |
| broken-down time structure, since 'tm_zone' reports the correct |
| abbreviation even when it is not the latest one. |
| |
| Though the strings are declared as 'char *' the user must refrain |
| from modifying these strings. Modifying the strings will almost |
| certainly lead to trouble. |
| |
| -- Function: void tzset (void) |
| Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe |
| lock mem fd | *Note POSIX Safety Concepts::. |
| |
| The 'tzset' function initializes the 'tzname' variable from the |
| value of the 'TZ' environment variable. It is not usually |
| necessary for your program to call this function, because it is |
| called automatically when you use the other time conversion |
| functions that depend on the time zone. |
| |
| The following variables are defined for compatibility with System V |
| Unix. Like 'tzname', these variables are set by calling 'tzset' or the |
| other time conversion functions. |
| |
| -- Variable: long int timezone |
| This contains the difference between UTC and the latest local |
| standard time, in seconds west of UTC. For example, in the U.S. |
| Eastern time zone, the value is '5*60*60'. Unlike the 'tm_gmtoff' |
| member of the broken-down time structure, this value is not |
| adjusted for daylight saving, and its sign is reversed. In GNU |
| programs it is better to use 'tm_gmtoff', since it contains the |
| correct offset even when it is not the latest one. |
| |
| -- Variable: int daylight |
| This variable has a nonzero value if Daylight Saving Time rules |
| apply. A nonzero value does not necessarily mean that Daylight |
| Saving Time is now in effect; it means only that Daylight Saving |
| Time is sometimes in effect. |
| |
| |
| File: libc.info, Node: Time Functions Example, Prev: Time Zone Functions, Up: Calendar Time |
| |
| 21.4.9 Time Functions Example |
| ----------------------------- |
| |
| Here is an example program showing the use of some of the calendar time |
| functions. |
| |
| |
| #include <time.h> |
| #include <stdio.h> |
| |
| #define SIZE 256 |
| |
| int |
| main (void) |
| { |
| char buffer[SIZE]; |
| time_t curtime; |
| struct tm *loctime; |
| |
| /* Get the current time. */ |
| curtime = time (NULL); |
| |
| /* Convert it to local time representation. */ |
| loctime = localtime (&curtime); |
| |
| /* Print out the date and time in the standard format. */ |
| fputs (asctime (loctime), stdout); |
| |
| /* Print it out in a nice format. */ |
| strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime); |
| fputs (buffer, stdout); |
| strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime); |
| fputs (buffer, stdout); |
| |
| return 0; |
| } |
| |
| It produces output like this: |
| |
| Wed Jul 31 13:02:36 1991 |
| Today is Wednesday, July 31. |
| The time is 01:02 PM. |
| |
| |
| File: libc.info, Node: Setting an Alarm, Next: Sleeping, Prev: Calendar Time, Up: Date and Time |
| |
| 21.5 Setting an Alarm |
| ===================== |
| |
| The 'alarm' and 'setitimer' functions provide a mechanism for a process |
| to interrupt itself in the future. They do this by setting a timer; |
| when the timer expires, the process receives a signal. |
| |
| Each process has three independent interval timers available: |
| |
| * A real-time timer that counts elapsed time. This timer sends a |
| 'SIGALRM' signal to the process when it expires. |
| |
| * A virtual timer that counts processor time used by the process. |
| This timer sends a 'SIGVTALRM' signal to the process when it |
| expires. |
| |
| * A profiling timer that counts both processor time used by the |
| process, and processor time spent in system calls on behalf of the |
| process. This timer sends a 'SIGPROF' signal to the process when |
| it expires. |
| |
| This timer is useful for profiling in interpreters. The interval |
| timer mechanism does not have the fine granularity necessary for |
| profiling native code. |
| |
| You can only have one timer of each kind set at any given time. If |
| you set a timer that has not yet expired, that timer is simply reset to |
| the new value. |
| |
| You should establish a handler for the appropriate alarm signal using |
| 'signal' or 'sigaction' before issuing a call to 'setitimer' or 'alarm'. |
| Otherwise, an unusual chain of events could cause the timer to expire |
| before your program establishes the handler. In this case it would be |
| terminated, since termination is the default action for the alarm |
| signals. *Note Signal Handling::. |
| |
| To be able to use the alarm function to interrupt a system call which |
| might block otherwise indefinitely it is important to _not_ set the |
| 'SA_RESTART' flag when registering the signal handler using 'sigaction'. |
| When not using 'sigaction' things get even uglier: the 'signal' function |
| has to fixed semantics with respect to restarts. The BSD semantics for |
| this function is to set the flag. Therefore, if 'sigaction' for |
| whatever reason cannot be used, it is necessary to use 'sysv_signal' and |
| not 'signal'. |
| |
| The 'setitimer' function is the primary means for setting an alarm. |
| This facility is declared in the header file 'sys/time.h'. The 'alarm' |
| function, declared in 'unistd.h', provides a somewhat simpler interface |
| for setting the real-time timer. |
| |
| -- Data Type: struct itimerval |
| This structure is used to specify when a timer should expire. It |
| contains the following members: |
| 'struct timeval it_interval' |
| This is the period between successive timer interrupts. If |
| zero, the alarm will only be sent once. |
| |
| 'struct timeval it_value' |
| This is the period between now and the first timer interrupt. |
| If zero, the alarm is disabled. |
| |
| The 'struct timeval' data type is described in *note Elapsed |
| Time::. |
| |
| -- Function: int setitimer (int WHICH, const struct itimerval *NEW, |
| struct itimerval *OLD) |
| Preliminary: | MT-Safe timer | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'setitimer' function sets the timer specified by WHICH |
| according to NEW. The WHICH argument can have a value of |
| 'ITIMER_REAL', 'ITIMER_VIRTUAL', or 'ITIMER_PROF'. |
| |
| If OLD is not a null pointer, 'setitimer' returns information about |
| any previous unexpired timer of the same kind in the structure it |
| points to. |
| |
| The return value is '0' on success and '-1' on failure. The |
| following 'errno' error conditions are defined for this function: |
| |
| 'EINVAL' |
| The timer period is too large. |
| |
| -- Function: int getitimer (int WHICH, struct itimerval *OLD) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'getitimer' function stores information about the timer |
| specified by WHICH in the structure pointed at by OLD. |
| |
| The return value and error conditions are the same as for |
| 'setitimer'. |
| |
| 'ITIMER_REAL' |
| This constant can be used as the WHICH argument to the 'setitimer' |
| and 'getitimer' functions to specify the real-time timer. |
| |
| 'ITIMER_VIRTUAL' |
| This constant can be used as the WHICH argument to the 'setitimer' |
| and 'getitimer' functions to specify the virtual timer. |
| |
| 'ITIMER_PROF' |
| This constant can be used as the WHICH argument to the 'setitimer' |
| and 'getitimer' functions to specify the profiling timer. |
| |
| -- Function: unsigned int alarm (unsigned int SECONDS) |
| Preliminary: | MT-Safe timer | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The 'alarm' function sets the real-time timer to expire in SECONDS |
| seconds. If you want to cancel any existing alarm, you can do this |
| by calling 'alarm' with a SECONDS argument of zero. |
| |
| The return value indicates how many seconds remain before the |
| previous alarm would have been sent. If there is no previous |
| alarm, 'alarm' returns zero. |
| |
| The 'alarm' function could be defined in terms of 'setitimer' like |
| this: |
| |
| unsigned int |
| alarm (unsigned int seconds) |
| { |
| struct itimerval old, new; |
| new.it_interval.tv_usec = 0; |
| new.it_interval.tv_sec = 0; |
| new.it_value.tv_usec = 0; |
| new.it_value.tv_sec = (long int) seconds; |
| if (setitimer (ITIMER_REAL, &new, &old) < 0) |
| return 0; |
| else |
| return old.it_value.tv_sec; |
| } |
| |
| There is an example showing the use of the 'alarm' function in *note |
| Handler Returns::. |
| |
| If you simply want your process to wait for a given number of |
| seconds, you should use the 'sleep' function. *Note Sleeping::. |
| |
| You shouldn't count on the signal arriving precisely when the timer |
| expires. In a multiprocessing environment there is typically some |
| amount of delay involved. |
| |
| *Portability Note:* The 'setitimer' and 'getitimer' functions are |
| derived from BSD Unix, while the 'alarm' function is specified by the |
| POSIX.1 standard. 'setitimer' is more powerful than 'alarm', but |
| 'alarm' is more widely used. |
| |
| |
| File: libc.info, Node: Sleeping, Prev: Setting an Alarm, Up: Date and Time |
| |
| 21.6 Sleeping |
| ============= |
| |
| The function 'sleep' gives a simple way to make the program wait for a |
| short interval. If your program doesn't use signals (except to |
| terminate), then you can expect 'sleep' to wait reliably throughout the |
| specified interval. Otherwise, 'sleep' can return sooner if a signal |
| arrives; if you want to wait for a given interval regardless of signals, |
| use 'select' (*note Waiting for I/O::) and don't specify any descriptors |
| to wait for. |
| |
| -- Function: unsigned int sleep (unsigned int SECONDS) |
| Preliminary: | MT-Unsafe sig:SIGCHLD/linux | AS-Unsafe | AC-Unsafe |
| | *Note POSIX Safety Concepts::. |
| |
| The 'sleep' function waits for SECONDS or until a signal is |
| delivered, whichever happens first. |
| |
| If 'sleep' function returns because the requested interval is over, |
| it returns a value of zero. If it returns because of delivery of a |
| signal, its return value is the remaining time in the sleep |
| interval. |
| |
| The 'sleep' function is declared in 'unistd.h'. |
| |
| Resist the temptation to implement a sleep for a fixed amount of time |
| by using the return value of 'sleep', when nonzero, to call 'sleep' |
| again. This will work with a certain amount of accuracy as long as |
| signals arrive infrequently. But each signal can cause the eventual |
| wakeup time to be off by an additional second or so. Suppose a few |
| signals happen to arrive in rapid succession by bad luck--there is no |
| limit on how much this could shorten or lengthen the wait. |
| |
| Instead, compute the calendar time at which the program should stop |
| waiting, and keep trying to wait until that calendar time. This won't |
| be off by more than a second. With just a little more work, you can use |
| 'select' and make the waiting period quite accurate. (Of course, heavy |
| system load can cause additional unavoidable delays--unless the machine |
| is dedicated to one application, there is no way you can avoid this.) |
| |
| On some systems, 'sleep' can do strange things if your program uses |
| 'SIGALRM' explicitly. Even if 'SIGALRM' signals are being ignored or |
| blocked when 'sleep' is called, 'sleep' might return prematurely on |
| delivery of a 'SIGALRM' signal. If you have established a handler for |
| 'SIGALRM' signals and a 'SIGALRM' signal is delivered while the process |
| is sleeping, the action taken might be just to cause 'sleep' to return |
| instead of invoking your handler. And, if 'sleep' is interrupted by |
| delivery of a signal whose handler requests an alarm or alters the |
| handling of 'SIGALRM', this handler and 'sleep' will interfere. |
| |
| On GNU systems, it is safe to use 'sleep' and 'SIGALRM' in the same |
| program, because 'sleep' does not work by means of 'SIGALRM'. |
| |
| -- Function: int nanosleep (const struct timespec *REQUESTED_TIME, |
| struct timespec *REMAINING) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If resolution to seconds is not enough the 'nanosleep' function can |
| be used. As the name suggests the sleep interval can be specified |
| in nanoseconds. The actual elapsed time of the sleep interval |
| might be longer since the system rounds the elapsed time you |
| request up to the next integer multiple of the actual resolution |
| the system can deliver. |
| |
| *'requested_time' is the elapsed time of the interval you want to |
| sleep. |
| |
| The function returns as *'remaining' the elapsed time left in the |
| interval for which you requested to sleep. If the interval |
| completed without getting interrupted by a signal, this is zero. |
| |
| 'struct timespec' is described in *Note Elapsed Time::. |
| |
| If the function returns because the interval is over the return |
| value is zero. If the function returns -1 the global variable |
| ERRNO is set to the following values: |
| |
| 'EINTR' |
| The call was interrupted because a signal was delivered to the |
| thread. If the REMAINING parameter is not the null pointer |
| the structure pointed to by REMAINING is updated to contain |
| the remaining elapsed time. |
| |
| 'EINVAL' |
| The nanosecond value in the REQUESTED_TIME parameter contains |
| an illegal value. Either the value is negative or greater |
| than or equal to 1000 million. |
| |
| This function is a cancellation point in multi-threaded programs. |
| This is a problem if the thread allocates some resources (like |
| memory, file descriptors, semaphores or whatever) at the time |
| 'nanosleep' is called. If the thread gets canceled these resources |
| stay allocated until the program ends. To avoid this calls to |
| 'nanosleep' should be protected using cancellation handlers. |
| |
| The 'nanosleep' function is declared in 'time.h'. |
| |
| |
| File: libc.info, Node: Resource Usage And Limitation, Next: Non-Local Exits, Prev: Date and Time, Up: Top |
| |
| 22 Resource Usage And Limitation |
| ******************************** |
| |
| This chapter describes functions for examining how much of various kinds |
| of resources (CPU time, memory, etc.) a process has used and getting |
| and setting limits on future usage. |
| |
| * Menu: |
| |
| * Resource Usage:: Measuring various resources used. |
| * Limits on Resources:: Specifying limits on resource usage. |
| * Priority:: Reading or setting process run priority. |
| * Memory Resources:: Querying memory available resources. |
| * Processor Resources:: Learn about the processors available. |
| |
| |
| File: libc.info, Node: Resource Usage, Next: Limits on Resources, Up: Resource Usage And Limitation |
| |
| 22.1 Resource Usage |
| =================== |
| |
| The function 'getrusage' and the data type 'struct rusage' are used to |
| examine the resource usage of a process. They are declared in |
| 'sys/resource.h'. |
| |
| -- Function: int getrusage (int PROCESSES, struct rusage *RUSAGE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function reports resource usage totals for processes specified |
| by PROCESSES, storing the information in '*RUSAGE'. |
| |
| In most systems, PROCESSES has only two valid values: |
| |
| 'RUSAGE_SELF' |
| Just the current process. |
| |
| 'RUSAGE_CHILDREN' |
| All child processes (direct and indirect) that have already |
| terminated. |
| |
| The return value of 'getrusage' is zero for success, and '-1' for |
| failure. |
| |
| 'EINVAL' |
| The argument PROCESSES is not valid. |
| |
| One way of getting resource usage for a particular child process is |
| with the function 'wait4', which returns totals for a child when it |
| terminates. *Note BSD Wait Functions::. |
| |
| -- Data Type: struct rusage |
| This data type stores various resource usage statistics. It has |
| the following members, and possibly others: |
| |
| 'struct timeval ru_utime' |
| Time spent executing user instructions. |
| |
| 'struct timeval ru_stime' |
| Time spent in operating system code on behalf of PROCESSES. |
| |
| 'long int ru_maxrss' |
| The maximum resident set size used, in kilobytes. That is, |
| the maximum number of kilobytes of physical memory that |
| PROCESSES used simultaneously. |
| |
| 'long int ru_ixrss' |
| An integral value expressed in kilobytes times ticks of |
| execution, which indicates the amount of memory used by text |
| that was shared with other processes. |
| |
| 'long int ru_idrss' |
| An integral value expressed the same way, which is the amount |
| of unshared memory used for data. |
| |
| 'long int ru_isrss' |
| An integral value expressed the same way, which is the amount |
| of unshared memory used for stack space. |
| |
| 'long int ru_minflt' |
| The number of page faults which were serviced without |
| requiring any I/O. |
| |
| 'long int ru_majflt' |
| The number of page faults which were serviced by doing I/O. |
| |
| 'long int ru_nswap' |
| The number of times PROCESSES was swapped entirely out of main |
| memory. |
| |
| 'long int ru_inblock' |
| The number of times the file system had to read from the disk |
| on behalf of PROCESSES. |
| |
| 'long int ru_oublock' |
| The number of times the file system had to write to the disk |
| on behalf of PROCESSES. |
| |
| 'long int ru_msgsnd' |
| Number of IPC messages sent. |
| |
| 'long int ru_msgrcv' |
| Number of IPC messages received. |
| |
| 'long int ru_nsignals' |
| Number of signals received. |
| |
| 'long int ru_nvcsw' |
| The number of times PROCESSES voluntarily invoked a context |
| switch (usually to wait for some service). |
| |
| 'long int ru_nivcsw' |
| The number of times an involuntary context switch took place |
| (because a time slice expired, or another process of higher |
| priority was scheduled). |
| |
| 'vtimes' is a historical function that does some of what 'getrusage' |
| does. 'getrusage' is a better choice. |
| |
| 'vtimes' and its 'vtimes' data structure are declared in |
| 'sys/vtimes.h'. |
| |
| -- Function: int vtimes (struct vtimes *CURRENT, struct vtimes *CHILD) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'vtimes' reports resource usage totals for a process. |
| |
| If CURRENT is non-null, 'vtimes' stores resource usage totals for |
| the invoking process alone in the structure to which it points. If |
| CHILD is non-null, 'vtimes' stores resource usage totals for all |
| past children (which have terminated) of the invoking process in |
| the structure to which it points. |
| |
| -- Data Type: struct vtimes |
| This data type contains information about the resource usage |
| of a process. Each member corresponds to a member of the |
| 'struct rusage' data type described above. |
| |
| 'vm_utime' |
| User CPU time. Analogous to 'ru_utime' in 'struct |
| rusage' |
| 'vm_stime' |
| System CPU time. Analogous to 'ru_stime' in 'struct |
| rusage' |
| 'vm_idsrss' |
| Data and stack memory. The sum of the values that would |
| be reported as 'ru_idrss' and 'ru_isrss' in 'struct |
| rusage' |
| 'vm_ixrss' |
| Shared memory. Analogous to 'ru_ixrss' in 'struct |
| rusage' |
| 'vm_maxrss' |
| Maximent resident set size. Analogous to 'ru_maxrss' in |
| 'struct rusage' |
| 'vm_majflt' |
| Major page faults. Analogous to 'ru_majflt' in 'struct |
| rusage' |
| 'vm_minflt' |
| Minor page faults. Analogous to 'ru_minflt' in 'struct |
| rusage' |
| 'vm_nswap' |
| Swap count. Analogous to 'ru_nswap' in 'struct rusage' |
| 'vm_inblk' |
| Disk reads. Analogous to 'ru_inblk' in 'struct rusage' |
| 'vm_oublk' |
| Disk writes. Analogous to 'ru_oublk' in 'struct rusage' |
| |
| The return value is zero if the function succeeds; '-1' otherwise. |
| |
| An additional historical function for examining resource usage, |
| 'vtimes', is supported but not documented here. It is declared in |
| 'sys/vtimes.h'. |
| |
| |
| File: libc.info, Node: Limits on Resources, Next: Priority, Prev: Resource Usage, Up: Resource Usage And Limitation |
| |
| 22.2 Limiting Resource Usage |
| ============================ |
| |
| You can specify limits for the resource usage of a process. When the |
| process tries to exceed a limit, it may get a signal, or the system call |
| by which it tried to do so may fail, depending on the resource. Each |
| process initially inherits its limit values from its parent, but it can |
| subsequently change them. |
| |
| There are two per-process limits associated with a resource: |
| |
| "current limit" |
| The current limit is the value the system will not allow usage to |
| exceed. It is also called the "soft limit" because the process |
| being limited can generally raise the current limit at will. |
| |
| "maximum limit" |
| The maximum limit is the maximum value to which a process is |
| allowed to set its current limit. It is also called the "hard |
| limit" because there is no way for a process to get around it. A |
| process may lower its own maximum limit, but only the superuser may |
| increase a maximum limit. |
| |
| The symbols for use with 'getrlimit', 'setrlimit', 'getrlimit64', and |
| 'setrlimit64' are defined in 'sys/resource.h'. |
| |
| -- Function: int getrlimit (int RESOURCE, struct rlimit *RLP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Read the current and maximum limits for the resource RESOURCE and |
| store them in '*RLP'. |
| |
| The return value is '0' on success and '-1' on failure. The only |
| possible 'errno' error condition is 'EFAULT'. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is in fact 'getrlimit64'. Thus, the |
| LFS interface transparently replaces the old interface. |
| |
| -- Function: int getrlimit64 (int RESOURCE, struct rlimit64 *RLP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to 'getrlimit' but its second parameter is |
| a pointer to a variable of type 'struct rlimit64', which allows it |
| to read values which wouldn't fit in the member of a 'struct |
| rlimit'. |
| |
| If the sources are compiled with '_FILE_OFFSET_BITS == 64' on a |
| 32-bit machine, this function is available under the name |
| 'getrlimit' and so transparently replaces the old interface. |
| |
| -- Function: int setrlimit (int RESOURCE, const struct rlimit *RLP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Store the current and maximum limits for the resource RESOURCE in |
| '*RLP'. |
| |
| The return value is '0' on success and '-1' on failure. The |
| following 'errno' error condition is possible: |
| |
| 'EPERM' |
| * The process tried to raise a current limit beyond the |
| maximum limit. |
| |
| * The process tried to raise a maximum limit, but is not |
| superuser. |
| |
| When the sources are compiled with '_FILE_OFFSET_BITS == 64' on a |
| 32-bit system this function is in fact 'setrlimit64'. Thus, the |
| LFS interface transparently replaces the old interface. |
| |
| -- Function: int setrlimit64 (int RESOURCE, const struct rlimit64 *RLP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function is similar to 'setrlimit' but its second parameter is |
| a pointer to a variable of type 'struct rlimit64' which allows it |
| to set values which wouldn't fit in the member of a 'struct |
| rlimit'. |
| |
| If the sources are compiled with '_FILE_OFFSET_BITS == 64' on a |
| 32-bit machine this function is available under the name |
| 'setrlimit' and so transparently replaces the old interface. |
| |
| -- Data Type: struct rlimit |
| This structure is used with 'getrlimit' to receive limit values, |
| and with 'setrlimit' to specify limit values for a particular |
| process and resource. It has two fields: |
| |
| 'rlim_t rlim_cur' |
| The current limit |
| |
| 'rlim_t rlim_max' |
| The maximum limit. |
| |
| For 'getrlimit', the structure is an output; it receives the |
| current values. For 'setrlimit', it specifies the new values. |
| |
| For the LFS functions a similar type is defined in 'sys/resource.h'. |
| |
| -- Data Type: struct rlimit64 |
| This structure is analogous to the 'rlimit' structure above, but |
| its components have wider ranges. It has two fields: |
| |
| 'rlim64_t rlim_cur' |
| This is analogous to 'rlimit.rlim_cur', but with a different |
| type. |
| |
| 'rlim64_t rlim_max' |
| This is analogous to 'rlimit.rlim_max', but with a different |
| type. |
| |
| Here is a list of resources for which you can specify a limit. |
| Memory and file sizes are measured in bytes. |
| |
| 'RLIMIT_CPU' |
| The maximum amount of CPU time the process can use. If it runs for |
| longer than this, it gets a signal: 'SIGXCPU'. The value is |
| measured in seconds. *Note Operation Error Signals::. |
| |
| 'RLIMIT_FSIZE' |
| The maximum size of file the process can create. Trying to write a |
| larger file causes a signal: 'SIGXFSZ'. *Note Operation Error |
| Signals::. |
| |
| 'RLIMIT_DATA' |
| The maximum size of data memory for the process. If the process |
| tries to allocate data memory beyond this amount, the allocation |
| function fails. |
| |
| 'RLIMIT_STACK' |
| The maximum stack size for the process. If the process tries to |
| extend its stack past this size, it gets a 'SIGSEGV' signal. *Note |
| Program Error Signals::. |
| |
| 'RLIMIT_CORE' |
| The maximum size core file that this process can create. If the |
| process terminates and would dump a core file larger than this, |
| then no core file is created. So setting this limit to zero |
| prevents core files from ever being created. |
| |
| 'RLIMIT_RSS' |
| The maximum amount of physical memory that this process should get. |
| This parameter is a guide for the system's scheduler and memory |
| allocator; the system may give the process more memory when there |
| is a surplus. |
| |
| 'RLIMIT_MEMLOCK' |
| The maximum amount of memory that can be locked into physical |
| memory (so it will never be paged out). |
| |
| 'RLIMIT_NPROC' |
| The maximum number of processes that can be created with the same |
| user ID. If you have reached the limit for your user ID, 'fork' |
| will fail with 'EAGAIN'. *Note Creating a Process::. |
| |
| 'RLIMIT_NOFILE' |
| 'RLIMIT_OFILE' |
| The maximum number of files that the process can open. If it tries |
| to open more files than this, its open attempt fails with 'errno' |
| 'EMFILE'. *Note Error Codes::. Not all systems support this |
| limit; GNU does, and 4.4 BSD does. |
| |
| 'RLIMIT_AS' |
| The maximum size of total memory that this process should get. If |
| the process tries to allocate more memory beyond this amount with, |
| for example, 'brk', 'malloc', 'mmap' or 'sbrk', the allocation |
| function fails. |
| |
| 'RLIM_NLIMITS' |
| The number of different resource limits. Any valid RESOURCE |
| operand must be less than 'RLIM_NLIMITS'. |
| |
| -- Constant: rlim_t RLIM_INFINITY |
| This constant stands for a value of "infinity" when supplied as the |
| limit value in 'setrlimit'. |
| |
| The following are historical functions to do some of what the |
| functions above do. The functions above are better choices. |
| |
| 'ulimit' and the command symbols are declared in 'ulimit.h'. |
| |
| -- Function: long int ulimit (int CMD, ...) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| 'ulimit' gets the current limit or sets the current and maximum |
| limit for a particular resource for the calling process according |
| to the command CMD.a |
| |
| If you are getting a limit, the command argument is the only |
| argument. If you are setting a limit, there is a second argument: |
| 'long int' LIMIT which is the value to which you are setting the |
| limit. |
| |
| The CMD values and the operations they specify are: |
| |
| 'GETFSIZE' |
| Get the current limit on the size of a file, in units of 512 |
| bytes. |
| |
| 'SETFSIZE' |
| Set the current and maximum limit on the size of a file to |
| LIMIT * 512 bytes. |
| |
| There are also some other CMD values that may do things on some |
| systems, but they are not supported. |
| |
| Only the superuser may increase a maximum limit. |
| |
| When you successfully get a limit, the return value of 'ulimit' is |
| that limit, which is never negative. When you successfully set a |
| limit, the return value is zero. When the function fails, the |
| return value is '-1' and 'errno' is set according to the reason: |
| |
| 'EPERM' |
| A process tried to increase a maximum limit, but is not |
| superuser. |
| |
| 'vlimit' and its resource symbols are declared in 'sys/vlimit.h'. |
| |
| -- Function: int vlimit (int RESOURCE, int LIMIT) |
| Preliminary: | MT-Unsafe race:setrlimit | AS-Unsafe | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| 'vlimit' sets the current limit for a resource for a process. |
| |
| RESOURCE identifies the resource: |
| |
| 'LIM_CPU' |
| Maximum CPU time. Same as 'RLIMIT_CPU' for 'setrlimit'. |
| 'LIM_FSIZE' |
| Maximum file size. Same as 'RLIMIT_FSIZE' for 'setrlimit'. |
| 'LIM_DATA' |
| Maximum data memory. Same as 'RLIMIT_DATA' for 'setrlimit'. |
| 'LIM_STACK' |
| Maximum stack size. Same as 'RLIMIT_STACK' for 'setrlimit'. |
| 'LIM_CORE' |
| Maximum core file size. Same as 'RLIMIT_COR' for 'setrlimit'. |
| 'LIM_MAXRSS' |
| Maximum physical memory. Same as 'RLIMIT_RSS' for |
| 'setrlimit'. |
| |
| The return value is zero for success, and '-1' with 'errno' set |
| accordingly for failure: |
| |
| 'EPERM' |
| The process tried to set its current limit beyond its maximum |
| limit. |
| |
| |
| File: libc.info, Node: Priority, Next: Memory Resources, Prev: Limits on Resources, Up: Resource Usage And Limitation |
| |
| 22.3 Process CPU Priority And Scheduling |
| ======================================== |
| |
| When multiple processes simultaneously require CPU time, the system's |
| scheduling policy and process CPU priorities determine which processes |
| get it. This section describes how that determination is made and GNU C |
| Library functions to control it. |
| |
| It is common to refer to CPU scheduling simply as scheduling and a |
| process' CPU priority simply as the process' priority, with the CPU |
| resource being implied. Bear in mind, though, that CPU time is not the |
| only resource a process uses or that processes contend for. In some |
| cases, it is not even particularly important. Giving a process a high |
| "priority" may have very little effect on how fast a process runs with |
| respect to other processes. The priorities discussed in this section |
| apply only to CPU time. |
| |
| CPU scheduling is a complex issue and different systems do it in |
| wildly different ways. New ideas continually develop and find their way |
| into the intricacies of the various systems' scheduling algorithms. |
| This section discusses the general concepts, some specifics of systems |
| that commonly use the GNU C Library, and some standards. |
| |
| For simplicity, we talk about CPU contention as if there is only one |
| CPU in the system. But all the same principles apply when a processor |
| has multiple CPUs, and knowing that the number of processes that can run |
| at any one time is equal to the number of CPUs, you can easily |
| extrapolate the information. |
| |
| The functions described in this section are all defined by the |
| POSIX.1 and POSIX.1b standards (the 'sched...' functions are POSIX.1b). |
| However, POSIX does not define any semantics for the values that these |
| functions get and set. In this chapter, the semantics are based on the |
| Linux kernel's implementation of the POSIX standard. As you will see, |
| the Linux implementation is quite the inverse of what the authors of the |
| POSIX syntax had in mind. |
| |
| * Menu: |
| |
| * Absolute Priority:: The first tier of priority. Posix |
| * Realtime Scheduling:: Scheduling among the process nobility |
| * Basic Scheduling Functions:: Get/set scheduling policy, priority |
| * Traditional Scheduling:: Scheduling among the vulgar masses |
| * CPU Affinity:: Limiting execution to certain CPUs |
| |
| |
| File: libc.info, Node: Absolute Priority, Next: Realtime Scheduling, Up: Priority |
| |
| 22.3.1 Absolute Priority |
| ------------------------ |
| |
| Every process has an absolute priority, and it is represented by a |
| number. The higher the number, the higher the absolute priority. |
| |
| On systems of the past, and most systems today, all processes have |
| absolute priority 0 and this section is irrelevant. In that case, *Note |
| Traditional Scheduling::. Absolute priorities were invented to |
| accommodate realtime systems, in which it is vital that certain |
| processes be able to respond to external events happening in real time, |
| which means they cannot wait around while some other process that _wants |
| to_, but doesn't _need to_ run occupies the CPU. |
| |
| When two processes are in contention to use the CPU at any instant, |
| the one with the higher absolute priority always gets it. This is true |
| even if the process with the lower priority is already using the CPU |
| (i.e., the scheduling is preemptive). Of course, we're only talking |
| about processes that are running or "ready to run," which means they are |
| ready to execute instructions right now. When a process blocks to wait |
| for something like I/O, its absolute priority is irrelevant. |
| |
| *NB:* The term "runnable" is a synonym for "ready to run." |
| |
| When two processes are running or ready to run and both have the same |
| absolute priority, it's more interesting. In that case, who gets the |
| CPU is determined by the scheduling policy. If the processes have |
| absolute priority 0, the traditional scheduling policy described in |
| *note Traditional Scheduling:: applies. Otherwise, the policies |
| described in *note Realtime Scheduling:: apply. |
| |
| You normally give an absolute priority above 0 only to a process that |
| can be trusted not to hog the CPU. Such processes are designed to block |
| (or terminate) after relatively short CPU runs. |
| |
| A process begins life with the same absolute priority as its parent |
| process. Functions described in *note Basic Scheduling Functions:: can |
| change it. |
| |
| Only a privileged process can change a process' absolute priority to |
| something other than '0'. Only a privileged process or the target |
| process' owner can change its absolute priority at all. |
| |
| POSIX requires absolute priority values used with the realtime |
| scheduling policies to be consecutive with a range of at least 32. On |
| Linux, they are 1 through 99. The functions 'sched_get_priority_max' |
| and 'sched_set_priority_min' portably tell you what the range is on a |
| particular system. |
| |
| 22.3.1.1 Using Absolute Priority |
| ................................ |
| |
| One thing you must keep in mind when designing real time applications is |
| that having higher absolute priority than any other process doesn't |
| guarantee the process can run continuously. Two things that can wreck a |
| good CPU run are interrupts and page faults. |
| |
| Interrupt handlers live in that limbo between processes. The CPU is |
| executing instructions, but they aren't part of any process. An |
| interrupt will stop even the highest priority process. So you must |
| allow for slight delays and make sure that no device in the system has |
| an interrupt handler that could cause too long a delay between |
| instructions for your process. |
| |
| Similarly, a page fault causes what looks like a straightforward |
| sequence of instructions to take a long time. The fact that other |
| processes get to run while the page faults in is of no consequence, |
| because as soon as the I/O is complete, the high priority process will |
| kick them out and run again, but the wait for the I/O itself could be a |
| problem. To neutralize this threat, use 'mlock' or 'mlockall'. |
| |
| There are a few ramifications of the absoluteness of this priority on |
| a single-CPU system that you need to keep in mind when you choose to set |
| a priority and also when you're working on a program that runs with high |
| absolute priority. Consider a process that has higher absolute priority |
| than any other process in the system and due to a bug in its program, it |
| gets into an infinite loop. It will never cede the CPU. You can't run a |
| command to kill it because your command would need to get the CPU in |
| order to run. The errant program is in complete control. It controls |
| the vertical, it controls the horizontal. |
| |
| There are two ways to avoid this: 1) keep a shell running somewhere |
| with a higher absolute priority. 2) keep a controlling terminal |
| attached to the high priority process group. All the priority in the |
| world won't stop an interrupt handler from running and delivering a |
| signal to the process if you hit Control-C. |
| |
| Some systems use absolute priority as a means of allocating a fixed |
| percentage of CPU time to a process. To do this, a super high priority |
| privileged process constantly monitors the process' CPU usage and raises |
| its absolute priority when the process isn't getting its entitled share |
| and lowers it when the process is exceeding it. |
| |
| *NB:* The absolute priority is sometimes called the "static |
| priority." We don't use that term in this manual because it misses the |
| most important feature of the absolute priority: its absoluteness. |
| |
| |
| File: libc.info, Node: Realtime Scheduling, Next: Basic Scheduling Functions, Prev: Absolute Priority, Up: Priority |
| |
| 22.3.2 Realtime Scheduling |
| -------------------------- |
| |
| Whenever two processes with the same absolute priority are ready to run, |
| the kernel has a decision to make, because only one can run at a time. |
| If the processes have absolute priority 0, the kernel makes this |
| decision as described in *note Traditional Scheduling::. Otherwise, the |
| decision is as described in this section. |
| |
| If two processes are ready to run but have different absolute |
| priorities, the decision is much simpler, and is described in *note |
| Absolute Priority::. |
| |
| Each process has a scheduling policy. For processes with absolute |
| priority other than zero, there are two available: |
| |
| 1. First Come First Served |
| 2. Round Robin |
| |
| The most sensible case is where all the processes with a certain |
| absolute priority have the same scheduling policy. We'll discuss that |
| first. |
| |
| In Round Robin, processes share the CPU, each one running for a small |
| quantum of time ("time slice") and then yielding to another in a |
| circular fashion. Of course, only processes that are ready to run and |
| have the same absolute priority are in this circle. |
| |
| In First Come First Served, the process that has been waiting the |
| longest to run gets the CPU, and it keeps it until it voluntarily |
| relinquishes the CPU, runs out of things to do (blocks), or gets |
| preempted by a higher priority process. |
| |
| First Come First Served, along with maximal absolute priority and |
| careful control of interrupts and page faults, is the one to use when a |
| process absolutely, positively has to run at full CPU speed or not at |
| all. |
| |
| Judicious use of 'sched_yield' function invocations by processes with |
| First Come First Served scheduling policy forms a good compromise |
| between Round Robin and First Come First Served. |
| |
| To understand how scheduling works when processes of different |
| scheduling policies occupy the same absolute priority, you have to know |
| the nitty gritty details of how processes enter and exit the ready to |
| run list: |
| |
| In both cases, the ready to run list is organized as a true queue, |
| where a process gets pushed onto the tail when it becomes ready to run |
| and is popped off the head when the scheduler decides to run it. Note |
| that ready to run and running are two mutually exclusive states. When |
| the scheduler runs a process, that process is no longer ready to run and |
| no longer in the ready to run list. When the process stops running, it |
| may go back to being ready to run again. |
| |
| The only difference between a process that is assigned the Round |
| Robin scheduling policy and a process that is assigned First Come First |
| Serve is that in the former case, the process is automatically booted |
| off the CPU after a certain amount of time. When that happens, the |
| process goes back to being ready to run, which means it enters the queue |
| at the tail. The time quantum we're talking about is small. Really |
| small. This is not your father's timesharing. For example, with the |
| Linux kernel, the round robin time slice is a thousand times shorter |
| than its typical time slice for traditional scheduling. |
| |
| A process begins life with the same scheduling policy as its parent |
| process. Functions described in *note Basic Scheduling Functions:: can |
| change it. |
| |
| Only a privileged process can set the scheduling policy of a process |
| that has absolute priority higher than 0. |
| |
| |
| File: libc.info, Node: Basic Scheduling Functions, Next: Traditional Scheduling, Prev: Realtime Scheduling, Up: Priority |
| |
| 22.3.3 Basic Scheduling Functions |
| --------------------------------- |
| |
| This section describes functions in the GNU C Library for setting the |
| absolute priority and scheduling policy of a process. |
| |
| *Portability Note:* On systems that have the functions in this |
| section, the macro _POSIX_PRIORITY_SCHEDULING is defined in |
| '<unistd.h>'. |
| |
| For the case that the scheduling policy is traditional scheduling, |
| more functions to fine tune the scheduling are in *note Traditional |
| Scheduling::. |
| |
| Don't try to make too much out of the naming and structure of these |
| functions. They don't match the concepts described in this manual |
| because the functions are as defined by POSIX.1b, but the implementation |
| on systems that use the GNU C Library is the inverse of what the POSIX |
| structure contemplates. The POSIX scheme assumes that the primary |
| scheduling parameter is the scheduling policy and that the priority |
| value, if any, is a parameter of the scheduling policy. In the |
| implementation, though, the priority value is king and the scheduling |
| policy, if anything, only fine tunes the effect of that priority. |
| |
| The symbols in this section are declared by including file 'sched.h'. |
| |
| -- Data Type: struct sched_param |
| This structure describes an absolute priority. |
| 'int sched_priority' |
| absolute priority value |
| |
| -- Function: int sched_setscheduler (pid_t PID, int POLICY, const |
| struct sched_param *PARAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function sets both the absolute priority and the scheduling |
| policy for a process. |
| |
| It assigns the absolute priority value given by PARAM and the |
| scheduling policy POLICY to the process with Process ID PID, or the |
| calling process if PID is zero. If POLICY is negative, |
| 'sched_setscheduler' keeps the existing scheduling policy. |
| |
| The following macros represent the valid values for POLICY: |
| |
| 'SCHED_OTHER' |
| Traditional Scheduling |
| 'SCHED_FIFO' |
| First In First Out |
| 'SCHED_RR' |
| Round Robin |
| |
| On success, the return value is '0'. Otherwise, it is '-1' and |
| 'ERRNO' is set accordingly. The 'errno' values specific to this |
| function are: |
| |
| 'EPERM' |
| * The calling process does not have 'CAP_SYS_NICE' |
| permission and POLICY is not 'SCHED_OTHER' (or it's |
| negative and the existing policy is not 'SCHED_OTHER'. |
| |
| * The calling process does not have 'CAP_SYS_NICE' |
| permission and its owner is not the target process' |
| owner. I.e., the effective uid of the calling process is |
| neither the effective nor the real uid of process PID. |
| |
| 'ESRCH' |
| There is no process with pid PID and PID is not zero. |
| |
| 'EINVAL' |
| * POLICY does not identify an existing scheduling policy. |
| |
| * The absolute priority value identified by *PARAM is |
| outside the valid range for the scheduling policy POLICY |
| (or the existing scheduling policy if POLICY is negative) |
| or PARAM is null. 'sched_get_priority_max' and |
| 'sched_get_priority_min' tell you what the valid range |
| is. |
| |
| * PID is negative. |
| |
| -- Function: int sched_getscheduler (pid_t PID) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the scheduling policy assigned to the process |
| with Process ID (pid) PID, or the calling process if PID is zero. |
| |
| The return value is the scheduling policy. See |
| 'sched_setscheduler' for the possible values. |
| |
| If the function fails, the return value is instead '-1' and 'errno' |
| is set accordingly. |
| |
| The 'errno' values specific to this function are: |
| |
| 'ESRCH' |
| There is no process with pid PID and it is not zero. |
| |
| 'EINVAL' |
| PID is negative. |
| |
| Note that this function is not an exact mate to |
| 'sched_setscheduler' because while that function sets the |
| scheduling policy and the absolute priority, this function gets |
| only the scheduling policy. To get the absolute priority, use |
| 'sched_getparam'. |
| |
| -- Function: int sched_setparam (pid_t PID, const struct sched_param |
| *PARAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function sets a process' absolute priority. |
| |
| It is functionally identical to 'sched_setscheduler' with POLICY = |
| '-1'. |
| |
| -- Function: int sched_getparam (pid_t PID, struct sched_param *PARAM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns a process' absolute priority. |
| |
| PID is the Process ID (pid) of the process whose absolute priority |
| you want to know. |
| |
| PARAM is a pointer to a structure in which the function stores the |
| absolute priority of the process. |
| |
| On success, the return value is '0'. Otherwise, it is '-1' and |
| 'ERRNO' is set accordingly. The 'errno' values specific to this |
| function are: |
| |
| 'ESRCH' |
| There is no process with pid PID and it is not zero. |
| |
| 'EINVAL' |
| PID is negative. |
| |
| -- Function: int sched_get_priority_min (int POLICY) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the lowest absolute priority value that is |
| allowable for a process with scheduling policy POLICY. |
| |
| On Linux, it is 0 for SCHED_OTHER and 1 for everything else. |
| |
| On success, the return value is '0'. Otherwise, it is '-1' and |
| 'ERRNO' is set accordingly. The 'errno' values specific to this |
| function are: |
| |
| 'EINVAL' |
| POLICY does not identify an existing scheduling policy. |
| |
| -- Function: int sched_get_priority_max (int POLICY) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the highest absolute priority value that is |
| allowable for a process that with scheduling policy POLICY. |
| |
| On Linux, it is 0 for SCHED_OTHER and 99 for everything else. |
| |
| On success, the return value is '0'. Otherwise, it is '-1' and |
| 'ERRNO' is set accordingly. The 'errno' values specific to this |
| function are: |
| |
| 'EINVAL' |
| POLICY does not identify an existing scheduling policy. |
| |
| -- Function: int sched_rr_get_interval (pid_t PID, struct timespec |
| *INTERVAL) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function returns the length of the quantum (time slice) used |
| with the Round Robin scheduling policy, if it is used, for the |
| process with Process ID PID. |
| |
| It returns the length of time as INTERVAL. |
| |
| With a Linux kernel, the round robin time slice is always 150 |
| microseconds, and PID need not even be a real pid. |
| |
| The return value is '0' on success and in the pathological case |
| that it fails, the return value is '-1' and 'errno' is set |
| accordingly. There is nothing specific that can go wrong with this |
| function, so there are no specific 'errno' values. |
| |
| -- Function: int sched_yield (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function voluntarily gives up the process' claim on the CPU. |
| |
| Technically, 'sched_yield' causes the calling process to be made |
| immediately ready to run (as opposed to running, which is what it |
| was before). This means that if it has absolute priority higher |
| than 0, it gets pushed onto the tail of the queue of processes that |
| share its absolute priority and are ready to run, and it will run |
| again when its turn next arrives. If its absolute priority is 0, |
| it is more complicated, but still has the effect of yielding the |
| CPU to other processes. |
| |
| If there are no other processes that share the calling process' |
| absolute priority, this function doesn't have any effect. |
| |
| To the extent that the containing program is oblivious to what |
| other processes in the system are doing and how fast it executes, |
| this function appears as a no-op. |
| |
| The return value is '0' on success and in the pathological case |
| that it fails, the return value is '-1' and 'errno' is set |
| accordingly. There is nothing specific that can go wrong with this |
| function, so there are no specific 'errno' values. |
| |
| |
| File: libc.info, Node: Traditional Scheduling, Next: CPU Affinity, Prev: Basic Scheduling Functions, Up: Priority |
| |
| 22.3.4 Traditional Scheduling |
| ----------------------------- |
| |
| This section is about the scheduling among processes whose absolute |
| priority is 0. When the system hands out the scraps of CPU time that |
| are left over after the processes with higher absolute priority have |
| taken all they want, the scheduling described herein determines who |
| among the great unwashed processes gets them. |
| |
| * Menu: |
| |
| * Traditional Scheduling Intro:: |
| * Traditional Scheduling Functions:: |
| |
| |
| File: libc.info, Node: Traditional Scheduling Intro, Next: Traditional Scheduling Functions, Up: Traditional Scheduling |
| |
| 22.3.4.1 Introduction To Traditional Scheduling |
| ............................................... |
| |
| Long before there was absolute priority (See *note Absolute Priority::), |
| Unix systems were scheduling the CPU using this system. When Posix came |
| in like the Romans and imposed absolute priorities to accommodate the |
| needs of realtime processing, it left the indigenous Absolute Priority |
| Zero processes to govern themselves by their own familiar scheduling |
| policy. |
| |
| Indeed, absolute priorities higher than zero are not available on |
| many systems today and are not typically used when they are, being |
| intended mainly for computers that do realtime processing. So this |
| section describes the only scheduling many programmers need to be |
| concerned about. |
| |
| But just to be clear about the scope of this scheduling: Any time a |
| process with an absolute priority of 0 and a process with an absolute |
| priority higher than 0 are ready to run at the same time, the one with |
| absolute priority 0 does not run. If it's already running when the |
| higher priority ready-to-run process comes into existence, it stops |
| immediately. |
| |
| In addition to its absolute priority of zero, every process has |
| another priority, which we will refer to as "dynamic priority" because |
| it changes over time. The dynamic priority is meaningless for processes |
| with an absolute priority higher than zero. |
| |
| The dynamic priority sometimes determines who gets the next turn on |
| the CPU. Sometimes it determines how long turns last. Sometimes it |
| determines whether a process can kick another off the CPU. |
| |
| In Linux, the value is a combination of these things, but mostly it |
| is just determines the length of the time slice. The higher a process' |
| dynamic priority, the longer a shot it gets on the CPU when it gets one. |
| If it doesn't use up its time slice before giving up the CPU to do |
| something like wait for I/O, it is favored for getting the CPU back when |
| it's ready for it, to finish out its time slice. Other than that, |
| selection of processes for new time slices is basically round robin. |
| But the scheduler does throw a bone to the low priority processes: A |
| process' dynamic priority rises every time it is snubbed in the |
| scheduling process. In Linux, even the fat kid gets to play. |
| |
| The fluctuation of a process' dynamic priority is regulated by |
| another value: The "nice" value. The nice value is an integer, usually |
| in the range -20 to 20, and represents an upper limit on a process' |
| dynamic priority. The higher the nice number, the lower that limit. |
| |
| On a typical Linux system, for example, a process with a nice value |
| of 20 can get only 10 milliseconds on the CPU at a time, whereas a |
| process with a nice value of -20 can achieve a high enough priority to |
| get 400 milliseconds. |
| |
| The idea of the nice value is deferential courtesy. In the |
| beginning, in the Unix garden of Eden, all processes shared equally in |
| the bounty of the computer system. But not all processes really need |
| the same share of CPU time, so the nice value gave a courteous process |
| the ability to refuse its equal share of CPU time that others might |
| prosper. Hence, the higher a process' nice value, the nicer the process |
| is. (Then a snake came along and offered some process a negative nice |
| value and the system became the crass resource allocation system we know |
| today). |
| |
| Dynamic priorities tend upward and downward with an objective of |
| smoothing out allocation of CPU time and giving quick response time to |
| infrequent requests. But they never exceed their nice limits, so on a |
| heavily loaded CPU, the nice value effectively determines how fast a |
| process runs. |
| |
| In keeping with the socialistic heritage of Unix process priority, a |
| process begins life with the same nice value as its parent process and |
| can raise it at will. A process can also raise the nice value of any |
| other process owned by the same user (or effective user). But only a |
| privileged process can lower its nice value. A privileged process can |
| also raise or lower another process' nice value. |
| |
| GNU C Library functions for getting and setting nice values are |
| described in *Note Traditional Scheduling Functions::. |
| |
| |
| File: libc.info, Node: Traditional Scheduling Functions, Prev: Traditional Scheduling Intro, Up: Traditional Scheduling |
| |
| 22.3.4.2 Functions For Traditional Scheduling |
| ............................................. |
| |
| This section describes how you can read and set the nice value of a |
| process. All these symbols are declared in 'sys/resource.h'. |
| |
| The function and macro names are defined by POSIX, and refer to |
| "priority," but the functions actually have to do with nice values, as |
| the terms are used both in the manual and POSIX. |
| |
| The range of valid nice values depends on the kernel, but typically |
| it runs from '-20' to '20'. A lower nice value corresponds to higher |
| priority for the process. These constants describe the range of |
| priority values: |
| |
| 'PRIO_MIN' |
| The lowest valid nice value. |
| |
| 'PRIO_MAX' |
| The highest valid nice value. |
| |
| -- Function: int getpriority (int CLASS, int ID) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Return the nice value of a set of processes; CLASS and ID specify |
| which ones (see below). If the processes specified do not all have |
| the same nice value, this returns the lowest value that any of them |
| has. |
| |
| On success, the return value is '0'. Otherwise, it is '-1' and |
| 'ERRNO' is set accordingly. The 'errno' values specific to this |
| function are: |
| |
| 'ESRCH' |
| The combination of CLASS and ID does not match any existing |
| process. |
| |
| 'EINVAL' |
| The value of CLASS is not valid. |
| |
| If the return value is '-1', it could indicate failure, or it could |
| be the nice value. The only way to make certain is to set 'errno = |
| 0' before calling 'getpriority', then use 'errno != 0' afterward as |
| the criterion for failure. |
| |
| -- Function: int setpriority (int CLASS, int ID, int NICEVAL) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Set the nice value of a set of processes to NICEVAL; CLASS and ID |
| specify which ones (see below). |
| |
| The return value is '0' on success, and '-1' on failure. The |
| following 'errno' error condition are possible for this function: |
| |
| 'ESRCH' |
| The combination of CLASS and ID does not match any existing |
| process. |
| |
| 'EINVAL' |
| The value of CLASS is not valid. |
| |
| 'EPERM' |
| The call would set the nice value of a process which is owned |
| by a different user than the calling process (i.e., the target |
| process' real or effective uid does not match the calling |
| process' effective uid) and the calling process does not have |
| 'CAP_SYS_NICE' permission. |
| |
| 'EACCES' |
| The call would lower the process' nice value and the process |
| does not have 'CAP_SYS_NICE' permission. |
| |
| The arguments CLASS and ID together specify a set of processes in |
| which you are interested. These are the possible values of CLASS: |
| |
| 'PRIO_PROCESS' |
| One particular process. The argument ID is a process ID (pid). |
| |
| 'PRIO_PGRP' |
| All the processes in a particular process group. The argument ID |
| is a process group ID (pgid). |
| |
| 'PRIO_USER' |
| All the processes owned by a particular user (i.e., whose real uid |
| indicates the user). The argument ID is a user ID (uid). |
| |
| If the argument ID is 0, it stands for the calling process, its |
| process group, or its owner (real uid), according to CLASS. |
| |
| -- Function: int nice (int INCREMENT) |
| Preliminary: | MT-Unsafe race:setpriority | AS-Unsafe | AC-Safe | |
| *Note POSIX Safety Concepts::. |
| |
| Increment the nice value of the calling process by INCREMENT. The |
| return value is the new nice value on success, and '-1' on failure. |
| In the case of failure, 'errno' will be set to the same values as |
| for 'setpriority'. |
| |
| Here is an equivalent definition of 'nice': |
| |
| int |
| nice (int increment) |
| { |
| int result, old = getpriority (PRIO_PROCESS, 0); |
| result = setpriority (PRIO_PROCESS, 0, old + increment); |
| if (result != -1) |
| return old + increment; |
| else |
| return -1; |
| } |
| |