| This is |
| /tmp/dgboter/bbs/rhev-vm2--rhe6x86_64/buildbot/rhe6x86_64--aarch64-none-linux-gnu/build/build-aarch64-none-linux-gnu/obj/glibc/manual/libc.info, |
| produced by makeinfo version 4.13 from libc.texinfo. |
| |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHAR_BIT: (libc)Width of Type. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * FP_LLOGB0: (libc)Exponents and Logarithms. |
| * FP_LLOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OFD_GETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLKW: (libc)Open File Description Locks. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUGE_VAL_FN: (libc)Math Error Reporting. |
| * HUGE_VAL_FNx: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_DIRECTORY: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TMPFILE: (libc)Open-time Flags. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SNAN: (libc)Infinity and NaN. |
| * SNANF: (libc)Infinity and NaN. |
| * SNANFN: (libc)Infinity and NaN. |
| * SNANFNx: (libc)Infinity and NaN. |
| * SNANL: (libc)Infinity and NaN. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_high: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_set_ppr_very_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __riscv_flush_icache: (libc)RISC-V. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosfN: (libc)Inverse Trig Functions. |
| * acosfNx: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshfN: (libc)Hyperbolic Functions. |
| * acoshfNx: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinfN: (libc)Inverse Trig Functions. |
| * asinfNx: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhfN: (libc)Hyperbolic Functions. |
| * asinhfNx: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2fN: (libc)Inverse Trig Functions. |
| * atan2fNx: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanfN: (libc)Inverse Trig Functions. |
| * atanfNx: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhfN: (libc)Hyperbolic Functions. |
| * atanhfNx: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying Strings and Arrays. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying Strings and Arrays. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsfN: (libc)Absolute Value. |
| * cabsfNx: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosfN: (libc)Inverse Trig Functions. |
| * cacosfNx: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshfN: (libc)Hyperbolic Functions. |
| * cacoshfNx: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * call_once: (libc)Call Once. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize: (libc)FP Bit Twiddling. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * canonicalizef: (libc)FP Bit Twiddling. |
| * canonicalizefN: (libc)FP Bit Twiddling. |
| * canonicalizefNx: (libc)FP Bit Twiddling. |
| * canonicalizel: (libc)FP Bit Twiddling. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargfN: (libc)Operations on Complex. |
| * cargfNx: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinfN: (libc)Inverse Trig Functions. |
| * casinfNx: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhfN: (libc)Hyperbolic Functions. |
| * casinhfNx: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanfN: (libc)Inverse Trig Functions. |
| * catanfNx: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhfN: (libc)Hyperbolic Functions. |
| * catanhfNx: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtfN: (libc)Exponents and Logarithms. |
| * cbrtfNx: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosfN: (libc)Trig Functions. |
| * ccosfNx: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshfN: (libc)Hyperbolic Functions. |
| * ccoshfNx: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceilfN: (libc)Rounding Functions. |
| * ceilfNx: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpfN: (libc)Exponents and Logarithms. |
| * cexpfNx: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagfN: (libc)Operations on Complex. |
| * cimagfNx: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10fN: (libc)Exponents and Logarithms. |
| * clog10fNx: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogfN: (libc)Exponents and Logarithms. |
| * clogfNx: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * cnd_broadcast: (libc)ISO C Condition Variables. |
| * cnd_destroy: (libc)ISO C Condition Variables. |
| * cnd_init: (libc)ISO C Condition Variables. |
| * cnd_signal: (libc)ISO C Condition Variables. |
| * cnd_timedwait: (libc)ISO C Condition Variables. |
| * cnd_wait: (libc)ISO C Condition Variables. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjfN: (libc)Operations on Complex. |
| * conjfNx: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copy_file_range: (libc)Copying File Data. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignfN: (libc)FP Bit Twiddling. |
| * copysignfNx: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosfN: (libc)Trig Functions. |
| * cosfNx: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshfN: (libc)Hyperbolic Functions. |
| * coshfNx: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowfN: (libc)Exponents and Logarithms. |
| * cpowfNx: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojfN: (libc)Operations on Complex. |
| * cprojfNx: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * crealfN: (libc)Operations on Complex. |
| * crealfNx: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)Passphrase Storage. |
| * crypt_r: (libc)Passphrase Storage. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinfN: (libc)Trig Functions. |
| * csinfNx: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhfN: (libc)Hyperbolic Functions. |
| * csinhfNx: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtfN: (libc)Exponents and Logarithms. |
| * csqrtfNx: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanfN: (libc)Trig Functions. |
| * ctanfNx: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhfN: (libc)Hyperbolic Functions. |
| * ctanhfNx: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * daddl: (libc)Misc FP Arithmetic. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * ddivl: (libc)Misc FP Arithmetic. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dmull: (libc)Misc FP Arithmetic. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dsubl: (libc)Misc FP Arithmetic. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_remove: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcfN: (libc)Special Functions. |
| * erfcfNx: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erffN: (libc)Special Functions. |
| * erffNx: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10fN: (libc)Exponents and Logarithms. |
| * exp10fNx: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2fN: (libc)Exponents and Logarithms. |
| * exp2fNx: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expfN: (libc)Exponents and Logarithms. |
| * expfNx: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * explicit_bzero: (libc)Erasing Sensitive Data. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1fN: (libc)Exponents and Logarithms. |
| * expm1fNx: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fMaddfN: (libc)Misc FP Arithmetic. |
| * fMaddfNx: (libc)Misc FP Arithmetic. |
| * fMdivfN: (libc)Misc FP Arithmetic. |
| * fMdivfNx: (libc)Misc FP Arithmetic. |
| * fMmulfN: (libc)Misc FP Arithmetic. |
| * fMmulfNx: (libc)Misc FP Arithmetic. |
| * fMsubfN: (libc)Misc FP Arithmetic. |
| * fMsubfNx: (libc)Misc FP Arithmetic. |
| * fMxaddfN: (libc)Misc FP Arithmetic. |
| * fMxaddfNx: (libc)Misc FP Arithmetic. |
| * fMxdivfN: (libc)Misc FP Arithmetic. |
| * fMxdivfNx: (libc)Misc FP Arithmetic. |
| * fMxmulfN: (libc)Misc FP Arithmetic. |
| * fMxmulfNx: (libc)Misc FP Arithmetic. |
| * fMxsubfN: (libc)Misc FP Arithmetic. |
| * fMxsubfNx: (libc)Misc FP Arithmetic. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsfN: (libc)Absolute Value. |
| * fabsfNx: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fadd: (libc)Misc FP Arithmetic. |
| * faddl: (libc)Misc FP Arithmetic. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdimfN: (libc)Misc FP Arithmetic. |
| * fdimfNx: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdiv: (libc)Misc FP Arithmetic. |
| * fdivl: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetmode: (libc)Control Functions. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexcept: (libc)Status bit operations. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetmode: (libc)Control Functions. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * fetestexceptflag: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorfN: (libc)Rounding Functions. |
| * floorfNx: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmafN: (libc)Misc FP Arithmetic. |
| * fmafNx: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxfN: (libc)Misc FP Arithmetic. |
| * fmaxfNx: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmaxmag: (libc)Misc FP Arithmetic. |
| * fmaxmagf: (libc)Misc FP Arithmetic. |
| * fmaxmagfN: (libc)Misc FP Arithmetic. |
| * fmaxmagfNx: (libc)Misc FP Arithmetic. |
| * fmaxmagl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminfN: (libc)Misc FP Arithmetic. |
| * fminfNx: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fminmag: (libc)Misc FP Arithmetic. |
| * fminmagf: (libc)Misc FP Arithmetic. |
| * fminmagfN: (libc)Misc FP Arithmetic. |
| * fminmagfNx: (libc)Misc FP Arithmetic. |
| * fminmagl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodfN: (libc)Remainder Functions. |
| * fmodfNx: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fmul: (libc)Misc FP Arithmetic. |
| * fmull: (libc)Misc FP Arithmetic. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpfN: (libc)Normalization Functions. |
| * frexpfNx: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fromfp: (libc)Rounding Functions. |
| * fromfpf: (libc)Rounding Functions. |
| * fromfpfN: (libc)Rounding Functions. |
| * fromfpfNx: (libc)Rounding Functions. |
| * fromfpl: (libc)Rounding Functions. |
| * fromfpx: (libc)Rounding Functions. |
| * fromfpxf: (libc)Rounding Functions. |
| * fromfpxfN: (libc)Rounding Functions. |
| * fromfpxfNx: (libc)Rounding Functions. |
| * fromfpxl: (libc)Rounding Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsub: (libc)Misc FP Arithmetic. |
| * fsubl: (libc)Misc FP Arithmetic. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcpu: (libc)CPU Affinity. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdents64: (libc)Low-level Directory Access. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getentropy: (libc)Unpredictable Bytes. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpayload: (libc)FP Bit Twiddling. |
| * getpayloadf: (libc)FP Bit Twiddling. |
| * getpayloadfN: (libc)FP Bit Twiddling. |
| * getpayloadfNx: (libc)FP Bit Twiddling. |
| * getpayloadl: (libc)FP Bit Twiddling. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrandom: (libc)Unpredictable Bytes. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettid: (libc)Process Identification. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotfN: (libc)Exponents and Logarithms. |
| * hypotfNx: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbfN: (libc)Exponents and Logarithms. |
| * ilogbfNx: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscanonical: (libc)Floating Point Classes. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * iseqsig: (libc)FP Comparison Functions. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * issubnormal: (libc)Floating Point Classes. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * iszero: (libc)Floating Point Classes. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0fN: (libc)Special Functions. |
| * j0fNx: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1fN: (libc)Special Functions. |
| * j1fNx: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnfN: (libc)Special Functions. |
| * jnfNx: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpfN: (libc)Normalization Functions. |
| * ldexpfNx: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammafN: (libc)Special Functions. |
| * lgammafN_r: (libc)Special Functions. |
| * lgammafNx: (libc)Special Functions. |
| * lgammafNx_r: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * linkat: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llogb: (libc)Exponents and Logarithms. |
| * llogbf: (libc)Exponents and Logarithms. |
| * llogbfN: (libc)Exponents and Logarithms. |
| * llogbfNx: (libc)Exponents and Logarithms. |
| * llogbl: (libc)Exponents and Logarithms. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintfN: (libc)Rounding Functions. |
| * llrintfNx: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundfN: (libc)Rounding Functions. |
| * llroundfNx: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10fN: (libc)Exponents and Logarithms. |
| * log10fNx: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pfN: (libc)Exponents and Logarithms. |
| * log1pfNx: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2fN: (libc)Exponents and Logarithms. |
| * log2fNx: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbfN: (libc)Exponents and Logarithms. |
| * logbfNx: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * logfN: (libc)Exponents and Logarithms. |
| * logfNx: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintfN: (libc)Rounding Functions. |
| * lrintfNx: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundfN: (libc)Rounding Functions. |
| * lroundfNx: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying Strings and Arrays. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying Strings and Arrays. |
| * memfd_create: (libc)Memory-mapped I/O. |
| * memfrob: (libc)Obfuscating Data. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying Strings and Arrays. |
| * mempcpy: (libc)Copying Strings and Arrays. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying Strings and Arrays. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock2: (libc)Page Lock Functions. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modffN: (libc)Rounding Functions. |
| * modffNx: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mprotect: (libc)Memory Protection. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * mtx_destroy: (libc)ISO C Mutexes. |
| * mtx_init: (libc)ISO C Mutexes. |
| * mtx_lock: (libc)ISO C Mutexes. |
| * mtx_timedlock: (libc)ISO C Mutexes. |
| * mtx_trylock: (libc)ISO C Mutexes. |
| * mtx_unlock: (libc)ISO C Mutexes. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanfN: (libc)FP Bit Twiddling. |
| * nanfNx: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintfN: (libc)Rounding Functions. |
| * nearbyintfNx: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterfN: (libc)FP Bit Twiddling. |
| * nextafterfNx: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nextdown: (libc)FP Bit Twiddling. |
| * nextdownf: (libc)FP Bit Twiddling. |
| * nextdownfN: (libc)FP Bit Twiddling. |
| * nextdownfNx: (libc)FP Bit Twiddling. |
| * nextdownl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nextup: (libc)FP Bit Twiddling. |
| * nextupf: (libc)FP Bit Twiddling. |
| * nextupfN: (libc)FP Bit Twiddling. |
| * nextupfNx: (libc)FP Bit Twiddling. |
| * nextupl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * pkey_alloc: (libc)Memory Protection. |
| * pkey_free: (libc)Memory Protection. |
| * pkey_get: (libc)Memory Protection. |
| * pkey_mprotect: (libc)Memory Protection. |
| * pkey_set: (libc)Memory Protection. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_fallocate64: (libc)Storage Allocation. |
| * posix_fallocate: (libc)Storage Allocation. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powfN: (libc)Exponents and Logarithms. |
| * powfNx: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * preadv2: (libc)Scatter-Gather. |
| * preadv64: (libc)Scatter-Gather. |
| * preadv64v2: (libc)Scatter-Gather. |
| * preadv: (libc)Scatter-Gather. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_cond_clockwait: (libc)Default Thread Attributes. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_rwlock_clockrdlock: (libc)Default Thread Attributes. |
| * pthread_rwlock_clockwrlock: (libc)Default Thread Attributes. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * pwritev2: (libc)Scatter-Gather. |
| * pwritev64: (libc)Scatter-Gather. |
| * pwritev64v2: (libc)Scatter-Gather. |
| * pwritev: (libc)Scatter-Gather. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * reallocarray: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderfN: (libc)Remainder Functions. |
| * remainderfNx: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintfN: (libc)Rounding Functions. |
| * rintfNx: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundeven: (libc)Rounding Functions. |
| * roundevenf: (libc)Rounding Functions. |
| * roundevenfN: (libc)Rounding Functions. |
| * roundevenfNx: (libc)Rounding Functions. |
| * roundevenl: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundfN: (libc)Rounding Functions. |
| * roundfNx: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnfN: (libc)Normalization Functions. |
| * scalblnfNx: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnfN: (libc)Normalization Functions. |
| * scalbnfNx: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * sem_clockwait: (libc)Default Thread Attributes. |
| * sem_close: (libc)Semaphores. |
| * sem_destroy: (libc)Semaphores. |
| * sem_getvalue: (libc)Semaphores. |
| * sem_init: (libc)Semaphores. |
| * sem_open: (libc)Semaphores. |
| * sem_post: (libc)Semaphores. |
| * sem_timedwait: (libc)Semaphores. |
| * sem_trywait: (libc)Semaphores. |
| * sem_unlink: (libc)Semaphores. |
| * sem_wait: (libc)Semaphores. |
| * semctl: (libc)Semaphores. |
| * semget: (libc)Semaphores. |
| * semop: (libc)Semaphores. |
| * semtimedop: (libc)Semaphores. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpayload: (libc)FP Bit Twiddling. |
| * setpayloadf: (libc)FP Bit Twiddling. |
| * setpayloadfN: (libc)FP Bit Twiddling. |
| * setpayloadfNx: (libc)FP Bit Twiddling. |
| * setpayloadl: (libc)FP Bit Twiddling. |
| * setpayloadsig: (libc)FP Bit Twiddling. |
| * setpayloadsigf: (libc)FP Bit Twiddling. |
| * setpayloadsigfN: (libc)FP Bit Twiddling. |
| * setpayloadsigfNx: (libc)FP Bit Twiddling. |
| * setpayloadsigl: (libc)FP Bit Twiddling. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)BSD Signal Handling. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Signal Handling. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)BSD Signal Handling. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)BSD Signal Handling. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)BSD Signal Handling. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosfN: (libc)Trig Functions. |
| * sincosfNx: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinfN: (libc)Trig Functions. |
| * sinfNx: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhfN: (libc)Hyperbolic Functions. |
| * sinhfNx: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtfN: (libc)Exponents and Logarithms. |
| * sqrtfNx: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying Strings and Arrays. |
| * stpncpy: (libc)Truncating Strings. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Concatenating Strings. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying Strings and Arrays. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying Strings and Arrays. |
| * strdupa: (libc)Copying Strings and Arrays. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfromd: (libc)Printing of Floats. |
| * strfromf: (libc)Printing of Floats. |
| * strfromfN: (libc)Printing of Floats. |
| * strfromfNx: (libc)Printing of Floats. |
| * strfroml: (libc)Printing of Floats. |
| * strfry: (libc)Shuffling Bytes. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Truncating Strings. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Truncating Strings. |
| * strndup: (libc)Truncating Strings. |
| * strndupa: (libc)Truncating Strings. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtofN: (libc)Parsing of Floats. |
| * strtofNx: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanfN: (libc)Trig Functions. |
| * tanfNx: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhfN: (libc)Hyperbolic Functions. |
| * tanhfNx: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammafN: (libc)Special Functions. |
| * tgammafNx: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * tgkill: (libc)Signaling Another Process. |
| * thrd_create: (libc)ISO C Thread Management. |
| * thrd_current: (libc)ISO C Thread Management. |
| * thrd_detach: (libc)ISO C Thread Management. |
| * thrd_equal: (libc)ISO C Thread Management. |
| * thrd_exit: (libc)ISO C Thread Management. |
| * thrd_join: (libc)ISO C Thread Management. |
| * thrd_sleep: (libc)ISO C Thread Management. |
| * thrd_yield: (libc)ISO C Thread Management. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * totalorder: (libc)FP Comparison Functions. |
| * totalorderf: (libc)FP Comparison Functions. |
| * totalorderfN: (libc)FP Comparison Functions. |
| * totalorderfNx: (libc)FP Comparison Functions. |
| * totalorderl: (libc)FP Comparison Functions. |
| * totalordermag: (libc)FP Comparison Functions. |
| * totalordermagf: (libc)FP Comparison Functions. |
| * totalordermagfN: (libc)FP Comparison Functions. |
| * totalordermagfNx: (libc)FP Comparison Functions. |
| * totalordermagl: (libc)FP Comparison Functions. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncfN: (libc)Rounding Functions. |
| * truncfNx: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * tss_create: (libc)ISO C Thread-local Storage. |
| * tss_delete: (libc)ISO C Thread-local Storage. |
| * tss_get: (libc)ISO C Thread-local Storage. |
| * tss_set: (libc)ISO C Thread-local Storage. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * twalk_r: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ufromfp: (libc)Rounding Functions. |
| * ufromfpf: (libc)Rounding Functions. |
| * ufromfpfN: (libc)Rounding Functions. |
| * ufromfpfNx: (libc)Rounding Functions. |
| * ufromfpl: (libc)Rounding Functions. |
| * ufromfpx: (libc)Rounding Functions. |
| * ufromfpxf: (libc)Rounding Functions. |
| * ufromfpxfN: (libc)Rounding Functions. |
| * ufromfpxfNx: (libc)Rounding Functions. |
| * ufromfpxl: (libc)Rounding Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying Strings and Arrays. |
| * wcpncpy: (libc)Truncating Strings. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Concatenating Strings. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying Strings and Arrays. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying Strings and Arrays. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Truncating Strings. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Truncating Strings. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstofN: (libc)Parsing of Floats. |
| * wcstofNx: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying Strings and Arrays. |
| * wmemmove: (libc)Copying Strings and Arrays. |
| * wmempcpy: (libc)Copying Strings and Arrays. |
| * wmemset: (libc)Copying Strings and Arrays. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0fN: (libc)Special Functions. |
| * y0fNx: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1fN: (libc)Special Functions. |
| * y1fNx: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynfN: (libc)Special Functions. |
| * ynfNx: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU C Library. |
| |
| This is `The GNU C Library Reference Manual', for version 2.30 |
| (GNU Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10)). |
| |
| Copyright (C) 1993-2019 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version |
| 1.3 or any later version published by the Free Software Foundation; |
| with the Invariant Sections being "Free Software Needs Free |
| Documentation" and "GNU Lesser General Public License", the Front-Cover |
| texts being "A GNU Manual", and with the Back-Cover Texts as in (a) |
| below. A copy of the license is included in the section entitled "GNU |
| Free Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| |
| |
| File: libc.info, Node: 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'.) |
| |
| -- Macro: float SNANF |
| -- Macro: double SNAN |
| -- Macro: long double SNANL |
| -- Macro: _FloatN SNANFN |
| -- Macro: _FloatNx SNANFNx |
| These macros, defined by TS 18661-1:2014 and TS 18661-3:2015, are |
| constant expressions for signaling NaNs. |
| |
| -- Macro: int FE_SNANS_ALWAYS_SIGNAL |
| This macro, defined by TS 18661-1:2014, is defined to `1' in |
| `fenv.h' to indicate that functions and operations with signaling |
| NaN inputs and floating-point results always raise the invalid |
| exception and return a quiet NaN, even in cases (such as `fmax', |
| `hypot' and `pow') where a quiet NaN input can produce a non-NaN |
| result. Because some compiler optimizations may not handle |
| signaling NaNs correctly, this macro is only defined if compiler |
| support for signaling NaNs is enabled. That support can be enabled |
| with the GCC option `-fsignaling-nans'. |
| |
| 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 fesetexcept (int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function sets the supported exception flags indicated by |
| EXCEPTS, like `feraiseexcept', but without causing enabled traps |
| to be taken. `fesetexcept' is from TS 18661-1:2014. |
| |
| 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. |
| |
| -- Function: int fetestexceptflag (const fexcept_t *FLAGP, int EXCEPTS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Test whether the exception flags indicated by the parameter |
| EXCEPTS are set in the variable pointed to by FLAGP. If any of |
| them are, a nonzero value is returned which specifies which |
| exceptions are set. Otherwise the result is zero. |
| `fetestexceptflag' is from TS 18661-1:2014. |
| |
| |
| 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. |
| |
| When a math function has an argument that is a signaling NaN, the |
| GNU C Library does not consider this a domain error, so `errno' is |
| unchanged, but the invalid exception is still raised (except for a few |
| functions that are specified to handle signaling NaNs differently). |
| |
| 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 |
| -- Macro: _FloatN HUGE_VAL_FN |
| -- Macro: _FloatNx HUGE_VAL_FNx |
| 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, or 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. |
| |
| TS 18661-1:2014 defines additional functions to save and restore |
| floating-point control modes (such as the rounding mode and whether |
| traps are enabled) while leaving other status (such as raised flags) |
| unchanged. |
| |
| The special macro `FE_DFL_MODE' may be passed to `fesetmode'. It |
| represents the floating-point control modes at program start. |
| |
| -- Function: int fegetmode (femode_t *MODEP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Store the floating-point control modes in the variable pointed to |
| by MODEP. |
| |
| The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| |
| -- Function: int fesetmode (const femode_t *MODEP) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| Set the floating-point control modes to those described by MODEP. |
| |
| 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 function enables traps for each of the exceptions as |
| indicated by the parameter EXCEPTS. 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 function disables traps for each of the exceptions as |
| indicated by the parameter EXCEPTS. 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'; the `fabs' functions are |
| declared in `math.h'; the `cabs' functions 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) |
| -- Function: _FloatN fabsfN (_FloatN NUMBER) |
| -- Function: _FloatNx fabsfNx (_FloatNx 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) |
| -- Function: _FloatN cabsfN (complex _FloatN Z) |
| -- Function: _FloatNx cabsfNx (complex _FloatNx 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) |
| -- Function: _FloatN frexpfN (_FloatN VALUE, int *EXPONENT) |
| -- Function: _FloatNx frexpfNx (_FloatNx 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) |
| -- Function: _FloatN ldexpfN (_FloatN VALUE, int EXPONENT) |
| -- Function: _FloatNx ldexpfNx (_FloatNx 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. The `_FloatN' |
| and `_FloatN' variants of the following functions come from TS |
| 18661-3:2015. |
| |
| -- 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) |
| -- Function: _FloatN scalbnfN (_FloatN X, int N) |
| -- Function: _FloatNx scalbnfNx (_FloatNx 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) |
| -- Function: _FloatN scalblnfN (_FloatN X, long int N) |
| -- Function: _FloatNx scalblnfNx (_FloatNx 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. |
| |
| The `fromfp' functions use the following macros, from TS |
| 18661-1:2014, to specify the direction of rounding. These correspond |
| to the rounding directions defined in IEEE 754-2008. |
| |
| `FP_INT_UPWARD' |
| Round toward +oo. |
| |
| `FP_INT_DOWNWARD' |
| Round toward -oo. |
| |
| `FP_INT_TOWARDZERO' |
| Round toward zero. |
| |
| `FP_INT_TONEARESTFROMZERO' |
| Round to nearest, ties round away from zero. |
| |
| `FP_INT_TONEAREST' |
| Round to nearest, ties round to even. |
| |
| -- Function: double ceil (double X) |
| -- Function: float ceilf (float X) |
| -- Function: long double ceill (long double X) |
| -- Function: _FloatN ceilfN (_FloatN X) |
| -- Function: _FloatNx ceilfNx (_FloatNx 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) |
| -- Function: _FloatN floorfN (_FloatN X) |
| -- Function: _FloatNx floorfNx (_FloatNx 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) |
| -- Function: _FloatN truncfN (_FloatN X) |
| -- Function: _FloatNx truncfNx (_FloatNx 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) |
| -- Function: _FloatN rintfN (_FloatN X) |
| -- Function: _FloatNx rintfNx (_FloatNx 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) |
| -- Function: _FloatN nearbyintfN (_FloatN X) |
| -- Function: _FloatNx nearbyintfNx (_FloatNx 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) |
| -- Function: _FloatN roundfN (_FloatN X) |
| -- Function: _FloatNx roundfNx (_FloatNx 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: double roundeven (double X) |
| -- Function: float roundevenf (float X) |
| -- Function: long double roundevenl (long double X) |
| -- Function: _FloatN roundevenfN (_FloatN X) |
| -- Function: _FloatNx roundevenfNx (_FloatNx X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, from TS 18661-1:2014 and TS 18661-3:2015, are |
| similar to `round', but they round halfway cases to even instead |
| of away from zero. |
| |
| -- Function: long int lrint (double X) |
| -- Function: long int lrintf (float X) |
| -- Function: long int lrintl (long double X) |
| -- Function: long int lrintfN (_FloatN X) |
| -- Function: long int lrintfNx (_FloatNx 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) |
| -- Function: long long int llrintfN (_FloatN X) |
| -- Function: long long int llrintfNx (_FloatNx 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) |
| -- Function: long int lroundfN (_FloatN X) |
| -- Function: long int lroundfNx (_FloatNx 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) |
| -- Function: long long int llroundfN (_FloatN X) |
| -- Function: long long int llroundfNx (_FloatNx 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: intmax_t fromfp (double X, int ROUND, unsigned int WIDTH) |
| -- Function: intmax_t fromfpf (float X, int ROUND, unsigned int WIDTH) |
| -- Function: intmax_t fromfpl (long double X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: intmax_t fromfpfN (_FloatN X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: intmax_t fromfpfNx (_FloatNx X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: uintmax_t ufromfp (double X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: uintmax_t ufromfpf (float X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: uintmax_t ufromfpl (long double X, int ROUND, unsigned |
| int WIDTH) |
| -- Function: uintmax_t ufromfpfN (_FloatN X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: uintmax_t ufromfpfNx (_FloatNx X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: intmax_t fromfpx (double X, int ROUND, unsigned int WIDTH) |
| -- Function: intmax_t fromfpxf (float X, int ROUND, unsigned int WIDTH) |
| -- Function: intmax_t fromfpxl (long double X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: intmax_t fromfpxfN (_FloatN X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: intmax_t fromfpxfNx (_FloatNx X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: uintmax_t ufromfpx (double X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: uintmax_t ufromfpxf (float X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: uintmax_t ufromfpxl (long double X, int ROUND, unsigned |
| int WIDTH) |
| -- Function: uintmax_t ufromfpxfN (_FloatN X, int ROUND, unsigned int |
| WIDTH) |
| -- Function: uintmax_t ufromfpxfNx (_FloatNx X, int ROUND, unsigned |
| int WIDTH) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, from TS 18661-1:2014 and TS 18661-3:2015, convert |
| a floating-point number to an integer according to the rounding |
| direction ROUND (one of the `FP_INT_*' macros). If the integer is |
| outside the range of a signed or unsigned (depending on the return |
| type of the function) type of width WIDTH bits (or outside the |
| range of the return type, if WIDTH is larger), or if X is infinite |
| or NaN, or if WIDTH is zero, a domain error occurs and an |
| unspecified value is returned. The functions with an `x' in their |
| names raise the inexact exception when a domain error does not |
| occur and the argument is not an integer; the other functions do |
| not raise the inexact exception. |
| |
| -- 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) |
| -- Function: _FloatN modffN (_FloatN VALUE, _FloatN *INTEGER-PART) |
| -- Function: _FloatNx modffNx (_FloatNx VALUE, _FloatNx *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) |
| -- Function: _FloatN fmodfN (_FloatN NUMERATOR, _FloatN DENOMINATOR) |
| -- Function: _FloatNx fmodfNx (_FloatNx NUMERATOR, _FloatNx |
| 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 remainder (double NUMERATOR, double DENOMINATOR) |
| -- Function: float remainderf (float NUMERATOR, float DENOMINATOR) |
| -- Function: long double remainderl (long double NUMERATOR, long |
| double DENOMINATOR) |
| -- Function: _FloatN remainderfN (_FloatN NUMERATOR, _FloatN |
| DENOMINATOR) |
| -- Function: _FloatNx remainderfNx (_FloatNx NUMERATOR, _FloatNx |
| 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, `remainder (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 `remainder (NUMERATOR, DENOMINATOR)' |
| is always either DENOMINATOR, minus DENOMINATOR, or zero. |
| |
| If DENOMINATOR is zero, `remainder' 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::. |
| |
| This function is another name for `remainder'. |
| |
| |
| 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) |
| -- Function: _FloatN copysignfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatNx copysignfNx (_FloatNx X, _FloatNx 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) |
| -- Function: _FloatN nextafterfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatNx nextafterfNx (_FloatNx X, _FloatNx 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 nextup (double X) |
| -- Function: float nextupf (float X) |
| -- Function: long double nextupl (long double X) |
| -- Function: _FloatN nextupfN (_FloatN X) |
| -- Function: _FloatNx nextupfNx (_FloatNx X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `nextup' function returns the next representable neighbor of X |
| in the direction of positive infinity. If X is the smallest |
| negative subnormal number in the type of X the function returns |
| `-0'. If X = `0' the function returns the smallest positive |
| subnormal number in the type of X. If X is NaN, NaN is returned. |
| If X is +oo, +oo is returned. `nextup' is from TS 18661-1:2014 |
| and TS 18661-3:2015. `nextup' never raises an exception except |
| for signaling NaNs. |
| |
| -- Function: double nextdown (double X) |
| -- Function: float nextdownf (float X) |
| -- Function: long double nextdownl (long double X) |
| -- Function: _FloatN nextdownfN (_FloatN X) |
| -- Function: _FloatNx nextdownfNx (_FloatNx X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `nextdown' function returns the next representable neighbor of |
| X in the direction of negative infinity. If X is the smallest |
| positive subnormal number in the type of X the function returns |
| `+0'. If X = `0' the function returns the smallest negative |
| subnormal number in the type of X. If X is NaN, NaN is returned. |
| If X is -oo, -oo is returned. `nextdown' is from TS 18661-1:2014 |
| and TS 18661-3:2015. `nextdown' never raises an exception except |
| for signaling NaNs. |
| |
| -- Function: double nan (const char *TAGP) |
| -- Function: float nanf (const char *TAGP) |
| -- Function: long double nanl (const char *TAGP) |
| -- Function: _FloatN nanfN (const char *TAGP) |
| -- Function: _FloatNx nanfNx (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. |
| |
| -- Function: int canonicalize (double *CX, const double *X) |
| -- Function: int canonicalizef (float *CX, const float *X) |
| -- Function: int canonicalizel (long double *CX, const long double *X) |
| -- Function: int canonicalizefN (_FloatN *CX, const _FloatN *X) |
| -- Function: int canonicalizefNx (_FloatNx *CX, const _FloatNx *X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| In some floating-point formats, some values have canonical |
| (preferred) and noncanonical encodings (for IEEE interchange |
| binary formats, all encodings are canonical). These functions, |
| defined by TS 18661-1:2014 and TS 18661-3:2015, attempt to produce |
| a canonical version of the floating-point value pointed to by X; |
| if that value is a signaling NaN, they raise the invalid exception |
| and produce a quiet NaN. If a canonical value is produced, it is |
| stored in the object pointed to by CX, and these functions return |
| zero. Otherwise (if a canonical value could not be produced |
| because the object pointed to by X is not a valid representation |
| of any floating-point value), the object pointed to by CX is |
| unchanged and a nonzero value is returned. |
| |
| Note that some formats have multiple encodings of a value which are |
| all equally canonical; when such an encoding is used as an input to |
| this function, any such encoding of the same value (or of the |
| corresponding quiet NaN, if that value is a signaling NaN) may be |
| produced as output. |
| |
| -- Function: double getpayload (const double *X) |
| -- Function: float getpayloadf (const float *X) |
| -- Function: long double getpayloadl (const long double *X) |
| -- Function: _FloatN getpayloadfN (const _FloatN *X) |
| -- Function: _FloatNx getpayloadfNx (const _FloatNx *X) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| IEEE 754 defines the "payload" of a NaN to be an integer value |
| encoded in the representation of the NaN. Payloads are typically |
| propagated from NaN inputs to the result of a floating-point |
| operation. These functions, defined by TS 18661-1:2014 and TS |
| 18661-3:2015, return the payload of the NaN pointed to by X |
| (returned as a positive integer, or positive zero, represented as a |
| floating-point number); if X is not a NaN, they return an |
| unspecified value. They raise no floating-point exceptions even |
| for signaling NaNs. |
| |
| -- Function: int setpayload (double *X, double PAYLOAD) |
| -- Function: int setpayloadf (float *X, float PAYLOAD) |
| -- Function: int setpayloadl (long double *X, long double PAYLOAD) |
| -- Function: int setpayloadfN (_FloatN *X, _FloatN PAYLOAD) |
| -- Function: int setpayloadfNx (_FloatNx *X, _FloatNx PAYLOAD) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, defined by TS 18661-1:2014 and TS 18661-3:2015, |
| set the object pointed to by X to a quiet NaN with payload PAYLOAD |
| and a zero sign bit and return zero. If PAYLOAD is not a |
| positive-signed integer that is a valid payload for a quiet NaN of |
| the given type, the object pointed to by X is set to positive zero |
| and a nonzero value is returned. They raise no floating-point |
| exceptions. |
| |
| -- Function: int setpayloadsig (double *X, double PAYLOAD) |
| -- Function: int setpayloadsigf (float *X, float PAYLOAD) |
| -- Function: int setpayloadsigl (long double *X, long double PAYLOAD) |
| -- Function: int setpayloadsigfN (_FloatN *X, _FloatN PAYLOAD) |
| -- Function: int setpayloadsigfNx (_FloatNx *X, _FloatNx PAYLOAD) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, defined by TS 18661-1:2014 and TS 18661-3:2015, |
| set the object pointed to by X to a signaling NaN with payload |
| PAYLOAD and a zero sign bit and return zero. If PAYLOAD is not a |
| positive-signed integer that is a valid payload for a signaling |
| NaN of the given type, the object pointed to by X is set to |
| positive zero and a nonzero value is returned. They raise no |
| floating-point exceptions. |
| |
| |
| 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. TS |
| 18661-1:2014 adds such a macro for an equality comparison that _does_ |
| raise an exception for a NaN argument; it also adds functions that |
| provide a total ordering on all floating-point values, including NaNs, |
| without raising any exceptions even for signaling NaNs. |
| |
| -- 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. |
| |
| -- Macro: int iseqsig (_real-floating_ X, _real-floating_ Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro determines whether its arguments are equal. It is |
| equivalent to `(X) == (Y)', but it raises the invalid exception |
| and sets `errno' to `EDOM' if either argument is a NaN. |
| |
| -- Function: int totalorder (double X, double Y) |
| -- Function: int totalorderf (float X, float Y) |
| -- Function: int totalorderl (long double X, long double Y) |
| -- Function: int totalorderfN (_FloatN X, _FloatN Y) |
| -- Function: int totalorderfNx (_FloatNx X, _FloatNx Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions determine whether the total order relationship, |
| defined in IEEE 754-2008, is true for X and Y, returning nonzero |
| if it is true and zero if it is false. No exceptions are raised |
| even for signaling NaNs. The relationship is true if they are the |
| same floating-point value (including sign for zero and NaNs, and |
| payload for NaNs), or if X comes before Y in the following order: |
| negative quiet NaNs, in order of decreasing payload; negative |
| signaling NaNs, in order of decreasing payload; negative infinity; |
| finite numbers, in ascending order, with negative zero before |
| positive zero; positive infinity; positive signaling NaNs, in |
| order of increasing payload; positive quiet NaNs, in order of |
| increasing payload. |
| |
| -- Function: int totalordermag (double X, double Y) |
| -- Function: int totalordermagf (float X, float Y) |
| -- Function: int totalordermagl (long double X, long double Y) |
| -- Function: int totalordermagfN (_FloatN X, _FloatN Y) |
| -- Function: int totalordermagfNx (_FloatNx X, _FloatNx Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions determine whether the total order relationship, |
| defined in IEEE 754-2008, is true for the absolute values of X and |
| Y, returning nonzero if it is true and zero if it is false. No |
| exceptions are raised even for signaling NaNs. |
| |
| 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) |
| -- Function: _FloatN fminfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatNx fminfNx (_FloatNx X, _FloatNx 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) |
| -- Function: _FloatN fmaxfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatNx fmaxfNx (_FloatNx X, _FloatNx 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 fminmag (double X, double Y) |
| -- Function: float fminmagf (float X, float Y) |
| -- Function: long double fminmagl (long double X, long double Y) |
| -- Function: _FloatN fminmagfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatNx fminmagfNx (_FloatNx X, _FloatNx Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, from TS 18661-1:2014 and TS 18661-3:2015, return |
| whichever of the two values X and Y has the smaller absolute |
| value. If both have the same absolute value, or either is NaN, |
| they behave the same as the `fmin' functions. |
| |
| -- Function: double fmaxmag (double X, double Y) |
| -- Function: float fmaxmagf (float X, float Y) |
| -- Function: long double fmaxmagl (long double X, long double Y) |
| -- Function: _FloatN fmaxmagfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatNx fmaxmagfNx (_FloatNx X, _FloatNx Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, from TS 18661-1:2014, return whichever of the two |
| values X and Y has the greater absolute value. If both have the |
| same absolute value, or either is NaN, they behave the same as the |
| `fmax' functions. |
| |
| -- Function: double fdim (double X, double Y) |
| -- Function: float fdimf (float X, float Y) |
| -- Function: long double fdiml (long double X, long double Y) |
| -- Function: _FloatN fdimfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatNx fdimfNx (_FloatNx X, _FloatNx 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) |
| -- Function: _FloatN fmafN (_FloatN X, _FloatN Y, _FloatN Z) |
| -- Function: _FloatNx fmafNx (_FloatNx X, _FloatNx Y, _FloatNx 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. |
| |
| -- Function: float fadd (double X, double Y) |
| -- Function: float faddl (long double X, long double Y) |
| -- Function: double daddl (long double X, long double Y) |
| -- Function: _FloatM fMaddfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatM fMaddfNx (_FloatNx X, _FloatNx Y) |
| -- Function: _FloatMx fMxaddfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatMx fMxaddfNx (_FloatNx X, _FloatNx Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, from TS 18661-1:2014 and TS 18661-3:2015, return |
| X + Y, rounded once to the return type of the function without any |
| intermediate rounding to the type of the arguments. |
| |
| -- Function: float fsub (double X, double Y) |
| -- Function: float fsubl (long double X, long double Y) |
| -- Function: double dsubl (long double X, long double Y) |
| -- Function: _FloatM fMsubfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatM fMsubfNx (_FloatNx X, _FloatNx Y) |
| -- Function: _FloatMx fMxsubfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatMx fMxsubfNx (_FloatNx X, _FloatNx Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, from TS 18661-1:2014 and TS 18661-3:2015, return |
| X - Y, rounded once to the return type of the function without any |
| intermediate rounding to the type of the arguments. |
| |
| -- Function: float fmul (double X, double Y) |
| -- Function: float fmull (long double X, long double Y) |
| -- Function: double dmull (long double X, long double Y) |
| -- Function: _FloatM fMmulfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatM fMmulfNx (_FloatNx X, _FloatNx Y) |
| -- Function: _FloatMx fMxmulfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatMx fMxmulfNx (_FloatNx X, _FloatNx Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, from TS 18661-1:2014 and TS 18661-3:2015, return |
| X * Y, rounded once to the return type of the function without any |
| intermediate rounding to the type of the arguments. |
| |
| -- Function: float fdiv (double X, double Y) |
| -- Function: float fdivl (long double X, long double Y) |
| -- Function: double ddivl (long double X, long double Y) |
| -- Function: _FloatM fMdivfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatM fMdivfNx (_FloatNx X, _FloatNx Y) |
| -- Function: _FloatMx fMxdivfN (_FloatN X, _FloatN Y) |
| -- Function: _FloatMx fMxdivfNx (_FloatNx X, _FloatNx Y) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| These functions, from TS 18661-1:2014 and TS 18661-3:2015, return |
| X / Y, rounded once to the return type of the function without any |
| intermediate rounding to the type of the arguments. |
| |
| |
| 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'. |
| |
| Likewise, on machines that have support for `_FloatN' or `_FloatNx' |
| enabled, the complex types `_FloatN complex' and `_FloatNx complex' are |
| also available if `complex.h' has been included; *note Mathematics::. |
| |
| 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) |
| -- Function: _FloatN crealfN (complex _FloatN Z) |
| -- Function: _FloatNx crealfNx (complex _FloatNx 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) |
| -- Function: _FloatN cimagfN (complex _FloatN Z) |
| -- Function: _FloatNx cimagfNx (complex _FloatNx 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) |
| -- Function: complex _FloatN conjfN (complex _FloatN Z) |
| -- Function: complex _FloatNx conjfNx (complex _FloatNx 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) |
| -- Function: _FloatN cargfN (complex _FloatN Z) |
| -- Function: _FloatNx cargfNx (complex _FloatNx 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) |
| -- Function: complex _FloatN cprojfN (complex _FloatN Z) |
| -- Function: complex _FloatNx cprojfNx (complex _FloatNx 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: Printing of Floats, 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 *restrict 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: _FloatN strtofN (const char *STRING, char **TAILPTR) |
| -- Function: _FloatNx strtofNx (const char *STRING, char **TAILPTR) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| These functions are like `strtod', except for the return type. |
| |
| They were introduced in ISO/IEC TS 18661-3 and are available on |
| machines that support the related types; *note Mathematics::. |
| |
| -- 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) |
| -- Function: _FloatN wcstofN (const wchar_t *STRING, wchar_t **TAILPTR) |
| -- Function: _FloatNx wcstofNx (const wchar_t *STRING, wchar_t |
| **TAILPTR) |
| Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The `wcstod', `wcstof', `wcstol', `wcstofN', and `wcstofNx' |
| functions are equivalent in nearly all aspects to the `strtod', |
| `strtof', `strtold', `strtofN', and `strtofNx' functions, but they |
| handle wide character strings. |
| |
| The `wcstod' function was introduced in Amendment 1 of ISO C90. |
| The `wcstof' and `wcstold' functions were introduced in ISO C99. |
| |
| The `wcstofN' and `wcstofNx' functions are not in any standard, |
| but are added to provide completeness for the non-deprecated |
| interface of wide character string to floating-point conversion |
| functions. They are only available on machines that support the |
| related types; *note Mathematics::. |
| |
| -- 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: Printing of Floats, Next: System V Number Conversion, Prev: Parsing of Numbers, Up: Arithmetic |
| |
| 20.12 Printing of Floats |
| ======================== |
| |
| The `strfrom' functions are declared in `stdlib.h'. |
| |
| -- Function: int strfromd (char *restrict STRING, size_t SIZE, const |
| char *restrict FORMAT, double VALUE) |
| -- Function: int strfromf (char *restrict STRING, size_t SIZE, const |
| char *restrict FORMAT, float VALUE) |
| -- Function: int strfroml (char *restrict STRING, size_t SIZE, const |
| char *restrict FORMAT, long double VALUE) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| The functions `strfromd' ("string-from-double"), `strfromf' |
| ("string-from-float"), and `strfroml' ("string-from-long-double") |
| convert the floating-point number VALUE to a string of characters |
| and stores them into the area pointed to by STRING. The conversion |
| writes at most SIZE characters and respects the format specified by |
| FORMAT. |
| |
| The format string must start with the character `%'. An optional |
| precision follows, which starts with a period, `.', and may be |
| followed by a decimal integer, representing the precision. If a |
| decimal integer is not specified after the period, the precision |
| is taken to be zero. The character `*' is not allowed. Finally, |
| the format string ends with one of the following conversion |
| specifiers: `a', `A', `e', `E', `f', `F', `g' or `G' (*note Table |
| of Output Conversions::). Invalid format strings result in |
| undefined behavior. |
| |
| These functions return the number of characters that would have |
| been written to STRING had SIZE been sufficiently large, not |
| counting the terminating null character. Thus, the |
| null-terminated output has been completely written if and only if |
| the returned value is less than SIZE. |
| |
| These functions were introduced by ISO/IEC TS 18661-1. |
| |
| -- Function: int strfromfN (char *restrict STRING, size_t SIZE, const |
| char *restrict FORMAT, _FloatN VALUE) |
| -- Function: int strfromfNx (char *restrict STRING, size_t SIZE, const |
| char *restrict FORMAT, _FloatNx VALUE) |
| Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | |
| *Note POSIX Safety Concepts::. |
| |
| These functions are like `strfromd', except for the type of |
| `value'. |
| |
| They were introduced in ISO/IEC TS 18661-3 and are available on |
| machines that support the related types; *note Mathematics::. |
| |
| |
| File: libc.info, Node: System V Number Conversion, Prev: Printing of Floats, Up: Arithmetic |
| |
| 20.13 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: |
| |
| `time_t 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: |
| |
| `time_t 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 (struct timeval *result, struct timeval *x, struct timeval *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 the 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 to by 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, an |
| `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 |
| it returns `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 Statement Exprs: (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 |
| it returns `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 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 alternative 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' |
| With all format specifiers that produce numbers: use the |
| locale's alternative numeric symbols. |
| |
| With `%B', `%b', and `%h': use the grammatical form for month |
| names that is appropriate when the month is named by itself, |
| rather than the form that is appropriate when the month is |
| used as part of a complete date. This is a GNU extension. |
| |
| If the format supports the modifier but no alternative |
| 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, |
| in the grammatical form used when the month is part of a |
| complete date. As a GNU extension, the `O' modifier can be |
| used (`%Ob') to get the grammatical form used when the month |
| is named by itself. |
| |
| `%B' |
| The full month name according to the current locale, in the |
| grammatical form used when the month is part of a complete |
| date. As a GNU extension, the `O' modifier can be used |
| (`%OB') to get the grammatical form used when the month is |
| named by itself. |
| |
| Note that not all languages need two different forms of the |
| month names, so the text produced by `%B' and `%OB', and by |
| `%b' and `%Ob', may or may not be the same, depending on the |
| locale. |
| |
| `%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. |
| |
| If the `E' modifier is specified (`%EC'), instead produces |
| the name of the period for the year (e.g. an era name) in the |
| locale's alternative calendar. |
| |
| 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 spaces |
| (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 spaces (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 spaces (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. |
| |
| If the `E' modifier is specified (`%Ey'), instead produces |
| the year number according to a locale-specific alternative |
| calendar. Unlike `%y', the number is _not_ reduced modulo |
| 100. However, by default it is zero-padded to a minimum of |
| two digits (this can be overridden by an explicit field width |
| or by the `_' and `-' flags). |
| |
| `%Y' |
| The year as a decimal number, using the Gregorian calendar. |
| Years before the year `1' are numbered `0', `-1', and so on. |
| |
| If the `E' modifier is specified (`%EY'), instead produces a |
| complete representation of the year according to the locale's |
| alternative calendar. Generally this will be some |
| combination of the information produced by `%EC' and `%Ey'. |
| As a GNU extension, the formatting flags `_' or `-' may be |
| used with this conversion specifier; they affect how the year |
| number is printed. |
| |
| `%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 characters, 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' |
| A month name according to the current locale. All three |
| specifiers will recognize both abbreviated and full month |
| names. If the locale provides two different grammatical |
| forms of month names, all three specifiers will recognize |
| both forms. |
| |
| As a GNU extension, the `O' modifier can be used with these |
| specifiers; it has no effect, as both grammatical forms of |
| month names are recognized. |
| |
| `%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 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 |
| 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 than 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 Thursday 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 |
| `/usr/share/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 files typically come from the Time Zone |
| Database (http://www.iana.org/time-zones) of time zone and daylight |
| saving time 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 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 was 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 seconds or until a signal |
| is delivered, whichever happens first. |
| |
| If `sleep' 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. |
| |
| 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 higher 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 or 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'. |
| |
| *Portability Note:* In POSIX, the `pid_t' arguments of the functions |
| below refer to process IDs. On Linux, they are actually thread IDs, |
| and control how specific threads are scheduled with regards to the |
| entire system. The resulting behavior does not conform to POSIX. This |
| is why the following description refers to tasks and tasks IDs, and not |
| processes and process IDs. |
| |
| -- 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 task. |
| |
| It assigns the absolute priority value given by PARAM and the |
| scheduling policy POLICY to the task with ID PID, or the calling |
| task 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 task 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 task does not have `CAP_SYS_NICE' permission |
| and its owner is not the target task's owner. I.e., the |
| effective uid of the calling task is neither the |
| effective nor the real uid of task PID. |
| |
| `ESRCH' |
| There is no task 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 task |
| with ID PID, or the calling task 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 task 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 task's 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 task's absolute priority. |
| |
| PID is the task ID of the task whose absolute priority you want to |
| know. |
| |
| PARAM is a pointer to a structure in which the function stores the |
| absolute priority of the task. |
| |
| 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 task with ID 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 task 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 task 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 |
| task with task 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 task's claim on the CPU. |
| |
| Technically, `sched_yield' causes the calling task 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 tasks 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 tasks. |
| |
| If there are no other tasks that share the calling task's 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 |
| 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; |
| } |
| |
| |
| File: libc.info, Node: CPU Affinity, Prev: Traditional Scheduling, Up: Priority |
| |
| 22.3.5 Limiting execution to certain CPUs |
| ----------------------------------------- |
| |
| On a multi-processor system the operating system usually distributes |
| the different processes which are runnable on all available CPUs in a |
| way which allows the system to work most efficiently. Which processes |
| and threads run can be to some extend be control with the scheduling |
| functionality described in the last sections. But which CPU finally |
| executes which process or thread is not covered. |
| |
| There are a number of reasons why a program might want to have |
| control over this aspect of the system as well: |
| |
| * One thread or process is responsible for absolutely critical work |
| which under no circumstances must be interrupted or hindered from |
| making progress by other processes or threads using CPU resources. |
| In this case the special process would be confined to a CPU which |
| no other process or thread is allowed to use. |
| |
| * The access to certain resources (RAM, I/O ports) has different |
| costs from different CPUs. This is the case in NUMA (Non-Uniform |
| Memory Architecture) machines. Preferably memory should be |
| accessed locally but this requirement is usually not visible to |
| the scheduler. Therefore forcing a process or thread to the CPUs |
| which have local access to the most-used memory helps to |
| significantly boost the performance. |
| |
| * In controlled runtimes resource allocation and book-keeping work |
| (for instance garbage collection) is performance local to |
| processors. This can help to reduce locking costs if the |
| resources do not have to be protected from concurrent accesses |
| from different processors. |
| |
| The POSIX standard up to this date is of not much help to solve this |
| problem. The Linux kernel provides a set of interfaces to allow |
| specifying _affinity sets_ for a process. The scheduler will schedule |
| the thread or process on CPUs specified by the affinity masks. The |
| interfaces which the GNU C Library define follow to some extent the |
| Linux kernel interface. |
| |
| -- Data Type: cpu_set_t |
| This data set is a bitset where each bit represents a CPU. How the |
| system's CPUs are mapped to bits in the bitset is system dependent. |
| The data type has a fixed size; in the unlikely case that the |
| number of bits are not sufficient to describe the CPUs of the |
| system a different interface has to be used. |
| |
| This type is a GNU extension and is defined in `sched.h'. |
| |
| To manipulate the bitset, to set and reset bits, a number of macros |
| are defined. Some of the macros take a CPU number as a parameter. Here |
| it is important to never exceed the size of the bitset. The following |
| macro specifies the number of bits in the `cpu_set_t' bitset. |
| |
| -- Macro: int CPU_SETSIZE |
| The value of this macro is the maximum number of CPUs which can be |
| handled with a `cpu_set_t' object. |
| |
| The type `cpu_set_t' should be considered opaque; all manipulation |
| should happen via the next four macros. |
| |
| -- Macro: void CPU_ZERO (cpu_set_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro initializes the CPU set SET to be the empty set. |
| |
| This macro is a GNU extension and is defined in `sched.h'. |
| |
| -- Macro: void CPU_SET (int CPU, cpu_set_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro adds CPU to the CPU set SET. |
| |
| The CPU parameter must not have side effects since it is evaluated |
| more than once. |
| |
| This macro is a GNU extension and is defined in `sched.h'. |
| |
| -- Macro: void CPU_CLR (int CPU, cpu_set_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro removes CPU from the CPU set SET. |
| |
| The CPU parameter must not have side effects since it is evaluated |
| more than once. |
| |
| This macro is a GNU extension and is defined in `sched.h'. |
| |
| -- Macro: int CPU_ISSET (int CPU, const cpu_set_t *SET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value (true) if CPU is a member of |
| the CPU set SET, and zero (false) otherwise. |
| |
| The CPU parameter must not have side effects since it is evaluated |
| more than once. |
| |
| This macro is a GNU extension and is defined in `sched.h'. |
| |
| CPU bitsets can be constructed from scratch or the currently |
| installed affinity mask can be retrieved from the system. |
| |
| -- Function: int sched_getaffinity (pid_t PID, size_t CPUSETSIZE, |
| cpu_set_t *CPUSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function stores the CPU affinity mask for the process or |
| thread with the ID PID in the CPUSETSIZE bytes long bitmap pointed |
| to by CPUSET. If successful, the function always initializes all |
| bits in the `cpu_set_t' object and returns zero. |
| |
| If PID does not correspond to a process or thread on the system |
| the or the function fails for some other reason, it returns `-1' |
| and `errno' is set to represent the error condition. |
| |
| `ESRCH' |
| No process or thread with the given ID found. |
| |
| `EFAULT' |
| The pointer CPUSET does not point to a valid object. |
| |
| This function is a GNU extension and is declared in `sched.h'. |
| |
| Note that it is not portably possible to use this information to |
| retrieve the information for different POSIX threads. A separate |
| interface must be provided for that. |
| |
| -- Function: int sched_setaffinity (pid_t PID, size_t CPUSETSIZE, |
| const cpu_set_t *CPUSET) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This function installs the CPUSETSIZE bytes long affinity mask |
| pointed to by CPUSET for the process or thread with the ID PID. |
| If successful the function returns zero and the scheduler will in |
| the future take the affinity information into account. |
| |
| If the function fails it will return `-1' and `errno' is set to |
| the error code: |
| |
| `ESRCH' |
| No process or thread with the given ID found. |
| |
| `EFAULT' |
| The pointer CPUSET does not point to a valid object. |
| |
| `EINVAL' |
| The bitset is not valid. This might mean that the affinity |
| set might not leave a processor for the process or thread to |
| run on. |
| |
| This function is a GNU extension and is declared in `sched.h'. |
| |
| -- Function: int getcpu (unsigned int *cpu, unsigned int *node) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getcpu' function identifies the processor and node on which |
| the calling thread or process is currently running and writes them |
| into the integers pointed to by the CPU and NODE arguments. The |
| processor is a unique nonnegative integer identifying a CPU. The |
| node is a unique nonnegative integer identifying a NUMA node. |
| When either CPU or NODE is `NULL', nothing is written to the |
| respective pointer. |
| |
| 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 this function. |
| |
| This function is Linux-specific and is declared in `sched.h'. |
| |
| |
| File: libc.info, Node: Memory Resources, Next: Processor Resources, Prev: Priority, Up: Resource Usage And Limitation |
| |
| 22.4 Querying memory available resources |
| ======================================== |
| |
| The amount of memory available in the system and the way it is organized |
| determines oftentimes the way programs can and have to work. For |
| functions like `mmap' it is necessary to know about the size of |
| individual memory pages and knowing how much memory is available enables |
| a program to select appropriate sizes for, say, caches. Before we get |
| into these details a few words about memory subsystems in traditional |
| Unix systems will be given. |
| |
| * Menu: |
| |
| * Memory Subsystem:: Overview about traditional Unix memory handling. |
| * Query Memory Parameters:: How to get information about the memory |
| subsystem? |
| |
| |
| File: libc.info, Node: Memory Subsystem, Next: Query Memory Parameters, Up: Memory Resources |
| |
| 22.4.1 Overview about traditional Unix memory handling |
| ------------------------------------------------------ |
| |
| Unix systems normally provide processes virtual address spaces. This |
| means that the addresses of the memory regions do not have to correspond |
| directly to the addresses of the actual physical memory which stores the |
| data. An extra level of indirection is introduced which translates |
| virtual addresses into physical addresses. This is normally done by the |
| hardware of the processor. |
| |
| Using a virtual address space has several advantages. The most |
| important is process isolation. The different processes running on the |
| system cannot interfere directly with each other. No process can write |
| into the address space of another process (except when shared memory is |
| used but then it is wanted and controlled). |
| |
| Another advantage of virtual memory is that the address space the |
| processes see can actually be larger than the physical memory available. |
| The physical memory can be extended by storage on an external media |
| where the content of currently unused memory regions is stored. The |
| address translation can then intercept accesses to these memory regions |
| and make memory content available again by loading the data back into |
| memory. This concept makes it necessary that programs which have to use |
| lots of memory know the difference between available virtual address |
| space and available physical memory. If the working set of virtual |
| memory of all the processes is larger than the available physical memory |
| the system will slow down dramatically due to constant swapping of |
| memory content from the memory to the storage media and back. This is |
| called "thrashing". |
| |
| A final aspect of virtual memory which is important and follows from |
| what is said in the last paragraph is the granularity of the virtual |
| address space handling. When we said that the virtual address handling |
| stores memory content externally it cannot do this on a byte-by-byte |
| basis. The administrative overhead does not allow this (leaving alone |
| the processor hardware). Instead several thousand bytes are handled |
| together and form a "page". The size of each page is always a power of |
| two bytes. The smallest page size in use today is 4096, with 8192, |
| 16384, and 65536 being other popular sizes. |
| |
| |
| File: libc.info, Node: Query Memory Parameters, Prev: Memory Subsystem, Up: Memory Resources |
| |
| 22.4.2 How to get information about the memory subsystem? |
| --------------------------------------------------------- |
| |
| The page size of the virtual memory the process sees is essential to |
| know in several situations. Some programming interfaces (e.g., `mmap', |
| *note Memory-mapped I/O::) require the user to provide information |
| adjusted to the page size. In the case of `mmap' it is necessary to |
| provide a length argument which is a multiple of the page size. |
| Another place where the knowledge about the page size is useful is in |
| memory allocation. If one allocates pieces of memory in larger chunks |
| which are then subdivided by the application code it is useful to |
| adjust the size of the larger blocks to the page size. If the total |
| memory requirement for the block is close (but not larger) to a multiple |
| of the page size the kernel's memory handling can work more effectively |
| since it only has to allocate memory pages which are fully used. (To do |
| this optimization it is necessary to know a bit about the memory |
| allocator which will require a bit of memory itself for each block and |
| this overhead must not push the total size over the page size multiple.) |
| |
| The page size traditionally was a compile time constant. But recent |
| development of processors changed this. Processors now support |
| different page sizes and they can possibly even vary among different |
| processes on the same system. Therefore the system should be queried at |
| runtime about the current page size and no assumptions (except about it |
| being a power of two) should be made. |
| |
| The correct interface to query about the page size is `sysconf' |
| (*note Sysconf Definition::) with the parameter `_SC_PAGESIZE'. There |
| is a much older interface available, too. |
| |
| -- Function: int getpagesize (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `getpagesize' function returns the page size of the process. |
| This value is fixed for the runtime of the process but can vary in |
| different runs of the application. |
| |
| The function is declared in `unistd.h'. |
| |
| Widely available on System V derived systems is a method to get |
| information about the physical memory the system has. The call |
| |
| sysconf (_SC_PHYS_PAGES) |
| |
| returns the total number of pages of physical memory the system has. |
| This does not mean all this memory is available. This information can |
| be found using |
| |
| sysconf (_SC_AVPHYS_PAGES) |
| |
| These two values help to optimize applications. The value returned |
| for `_SC_AVPHYS_PAGES' is the amount of memory the application can use |
| without hindering any other process (given that no other process |
| increases its memory usage). The value returned for `_SC_PHYS_PAGES' |
| is more or less a hard limit for the working set. If all applications |
| together constantly use more than that amount of memory the system is |
| in trouble. |
| |
| The GNU C Library provides in addition to these already described |
| way to get this information two functions. They are declared in the |
| file `sys/sysinfo.h'. Programmers should prefer to use the `sysconf' |
| method described above. |
| |
| -- Function: long int get_phys_pages (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| The `get_phys_pages' function returns the total number of pages of |
| physical memory the system has. To get the amount of memory this |
| number has to be multiplied by the page size. |
| |
| This function is a GNU extension. |
| |
| -- Function: long int get_avphys_pages (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| The `get_avphys_pages' function returns the number of available |
| pages of physical memory the system has. To get the amount of |
| memory this number has to be multiplied by the page size. |
| |
| This function is a GNU extension. |
| |
| |
| File: libc.info, Node: Processor Resources, Prev: Memory Resources, Up: Resource Usage And Limitation |
| |
| 22.5 Learn about the processors available |
| ========================================= |
| |
| The use of threads or processes with shared memory allows an application |
| to take advantage of all the processing power a system can provide. If |
| the task can be parallelized the optimal way to write an application is |
| to have at any time as many processes running as there are processors. |
| To determine the number of processors available to the system one can |
| run |
| |
| sysconf (_SC_NPROCESSORS_CONF) |
| |
| which returns the number of processors the operating system configured. |
| But it might be possible for the operating system to disable individual |
| processors and so the call |
| |
| sysconf (_SC_NPROCESSORS_ONLN) |
| |
| returns the number of processors which are currently online (i.e., |
| available). |
| |
| For these two pieces of information the GNU C Library also provides |
| functions to get the information directly. The functions are declared |
| in `sys/sysinfo.h'. |
| |
| -- Function: int get_nprocs_conf (void) |
| Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd |
| mem | *Note POSIX Safety Concepts::. |
| |
| The `get_nprocs_conf' function returns the number of processors the |
| operating system configured. |
| |
| This function is a GNU extension. |
| |
| -- Function: int get_nprocs (void) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| The `get_nprocs' function returns the number of available |
| processors. |
| |
| This function is a GNU extension. |
| |
| Before starting more threads it should be checked whether the |
| processors are not already overused. Unix systems calculate something |
| called the "load average". This is a number indicating how many |
| processes were running. This number is an average over different |
| periods of time (normally 1, 5, and 15 minutes). |
| |
| -- Function: int getloadavg (double LOADAVG[], int NELEM) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety |
| Concepts::. |
| |
| This function gets the 1, 5 and 15 minute load averages of the |
| system. The values are placed in LOADAVG. `getloadavg' will |
| place at most NELEM elements into the array but never more than |
| three elements. The return value is the number of elements |
| written to LOADAVG, or -1 on error. |
| |
| This function is declared in `stdlib.h'. |
| |
| |
| File: libc.info, Node: Non-Local Exits, Next: Signal Handling, Prev: Resource Usage And Limitation, Up: Top |
| |
| 23 Non-Local Exits |
| ****************** |
| |
| Sometimes when your program detects an unusual situation inside a deeply |
| nested set of function calls, you would like to be able to immediately |
| return to an outer level of control. This section describes how you can |
| do such "non-local exits" using the `setjmp' and `longjmp' functions. |
| |
| * Menu: |
| |
| * Intro: Non-Local Intro. When and how to use these facilities. |
| * Details: Non-Local Details. Functions for non-local exits. |
| * Non-Local Exits and Signals:: Portability issues. |
| * System V contexts:: Complete context control a la System V. |
| |
| |
| File: libc.info, Node: Non-Local Intro, Next: Non-Local Details, Up: Non-Local Exits |
| |
| 23.1 Introduction to Non-Local Exits |
| ==================================== |
| |
| As an example of a situation where a non-local exit can be useful, |
| suppose you have an interactive program that has a "main loop" that |
| prompts for and executes commands. Suppose the "read" command reads |
| input from a file, doing some lexical analysis and parsing of the input |
| while processing it. If a low-level input error is detected, it would |
| be useful to be able to return immediately to the "main loop" instead |
| of having to make each of the lexical analysis, parsing, and processing |
| phases all have to explicitly deal with error situations initially |
| detected by nested calls. |
| |
| (On the other hand, if each of these phases has to do a substantial |
| amount of cleanup when it exits--such as closing files, deallocating |
| buffers or other data structures, and the like--then it can be more |
| appropriate to do a normal return and have each phase do its own |
| cleanup, because a non-local exit would bypass the intervening phases |
| and their associated cleanup code entirely. Alternatively, you could |
| use a non-local exit but do the cleanup explicitly either before or |
| after returning to the "main loop".) |
| |
| In some ways, a non-local exit is similar to using the `return' |
| statement to return from a function. But while `return' abandons only |
| a single function call, transferring control back to the point at which |
| it was called, a non-local exit can potentially abandon many levels of |
| nested function calls. |
| |
| You identify return points for non-local exits by calling the |
| function `setjmp'. This function saves information about the execution |
| environment in which the call to `setjmp' appears in an object of type |
| `jmp_buf'. Execution of the program continues normally after the call |
| to `setjmp', but if an exit is later made to this return point by |
| calling `longjmp' with the corresponding `jmp_buf' object, control is |
| transferred back to the point where `setjmp' was called. The return |
| value from `setjmp' is used to distinguish between an ordinary return |
| and a return made by a call to `longjmp', so calls to `setjmp' usually |
| appear in an `if' statement. |
| |
| Here is how the example program described above might be set up: |
| |
| |
| #include <setjmp.h> |
| #include <stdlib.h> |
| #include <stdio.h> |
| |
| jmp_buf main_loop; |
| |
| void |
| abort_to_main_loop (int status) |
| { |
| longjmp (main_loop, status); |
| } |
| |
| int |
| main (void) |
| { |
| while (1) |
| if (setjmp (main_loop)) |
| puts ("Back at main loop...."); |
| else |
| do_command (); |
| } |
| |
| |
| void |
| do_command (void) |
| { |
| char buffer[128]; |
| if (fgets (buffer, 128, stdin) == NULL) |
| abort_to_main_loop (-1); |
| else |
| exit (EXIT_SUCCESS); |
| } |
| |
| The function `abort_to_main_loop' causes an immediate transfer of |
| control back to the main loop of the program, no matter where it is |
| called from. |
| |
| The flow of control inside the `main' function may appear a little |
| mysterious at first, but it is actually a common idiom with `setjmp'. |
| A normal call to `setjmp' returns zero, so the "else" clause of the |
| conditional is executed. If `abort_to_main_loop' is called somewhere |
| within the execution of `do_command', then it actually appears as if |
| the _same_ call to `setjmp' in `main' were returning a second time with |
| a value of `-1'. |
| |
| So, the general pattern for using `setjmp' looks something like: |
| |
| if (setjmp (BUFFER)) |
| /* Code to clean up after premature return. */ |
| ... |
| else |
| /* Code to be executed normally after setting up the return point. */ |
| ... |
| |
| |
| File: libc.info, Node: Non-Local Details, Next: Non-Local Exits and Signals, Prev: Non-Local Intro, Up: Non-Local Exits |
| |
| 23.2 Details of Non-Local Exits |
| =============================== |
| |
| Here are the details on the functions and data structures used for |
| performing non-local exits. These facilities are declared in |
| `setjmp.h'. |
| |
| -- Data Type: jmp_buf |
| Objects of type `jmp_buf' hold the state information to be |
| restored by a non-local exit. The contents of a `jmp_buf' |
| identify a specific place to return to. |
| |
| -- Macro: int setjmp (jmp_buf STATE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| When called normally, `setjmp' stores information about the |
| execution state of the program in STATE and returns zero. If |
| `longjmp' is later used to perform a non-local exit to this STATE, |
| `setjmp' returns a nonzero value. |
| |
| -- Function: void longjmp (jmp_buf STATE, int VALUE) |
| Preliminary: | MT-Safe | AS-Unsafe plugin corrupt lock/hurd | |
| AC-Unsafe corrupt lock/hurd | *Note POSIX Safety Concepts::. |
| |
| This function restores current execution to the state saved in |
| STATE, and continues execution from the call to `setjmp' that |
| established that return point. Returning from `setjmp' by means of |
| `longjmp' returns the VALUE argument that was passed to `longjmp', |
| rather than `0'. (But if VALUE is given as `0', `setjmp' returns |
| `1'). |
| |
| There are a lot of obscure but important restrictions on the use of |
| `setjmp' and `longjmp'. Most of these restrictions are present because |
| non-local exits require a fair amount of magic on the part of the C |
| compiler and can interact with other parts of the language in strange |
| ways. |
| |
| The `setjmp' function is actually a macro without an actual function |
| definition, so you shouldn't try to `#undef' it or take its address. |
| In addition, calls to `setjmp' are safe in only the following contexts: |
| |
| * As the test expression of a selection or iteration statement (such |
| as `if', `switch', or `while'). |
| |
| * As one operand of an equality or comparison operator that appears |
| as the test expression of a selection or iteration statement. The |
| other operand must be an integer constant expression. |
| |
| * As the operand of a unary `!' operator, that appears as the test |
| expression of a selection or iteration statement. |
| |
| * By itself as an expression statement. |
| |
| Return points are valid only during the dynamic extent of the |
| function that called `setjmp' to establish them. If you `longjmp' to a |
| return point that was established in a function that has already |
| returned, unpredictable and disastrous things are likely to happen. |
| |
| You should use a nonzero VALUE argument to `longjmp'. While |
| `longjmp' refuses to pass back a zero argument as the return value from |
| `setjmp', this is intended as a safety net against accidental misuse |
| and is not really good programming style. |
| |
| When you perform a non-local exit, accessible objects generally |
| retain whatever values they had at the time `longjmp' was called. The |
| exception is that the values of automatic variables local to the |
| function containing the `setjmp' call that have been changed since the |
| call to `setjmp' are indeterminate, unless you have declared them |
| `volatile'. |
| |
| |
| File: libc.info, Node: Non-Local Exits and Signals, Next: System V contexts, Prev: Non-Local Details, Up: Non-Local Exits |
| |
| 23.3 Non-Local Exits and Signals |
| ================================ |
| |
| In BSD Unix systems, `setjmp' and `longjmp' also save and restore the |
| set of blocked signals; see *note Blocking Signals::. However, the |
| POSIX.1 standard requires `setjmp' and `longjmp' not to change the set |
| of blocked signals, and provides an additional pair of functions |
| (`sigsetjmp' and `siglongjmp') to get the BSD behavior. |
| |
| The behavior of `setjmp' and `longjmp' in the GNU C Library is |
| controlled by feature test macros; see *note Feature Test Macros::. The |
| default in the GNU C Library is the POSIX.1 behavior rather than the BSD |
| behavior. |
| |
| The facilities in this section are declared in the header file |
| `setjmp.h'. |
| |
| -- Data Type: sigjmp_buf |
| This is similar to `jmp_buf', except that it can also store state |
| information about the set of blocked signals. |
| |
| -- Function: int sigsetjmp (sigjmp_buf STATE, int SAVESIGS) |
| Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd |
| | *Note POSIX Safety Concepts::. |
| |
| This is similar to `setjmp'. If SAVESIGS is nonzero, the set of |
| blocked signals is saved in STATE and will be restored if a |
| `siglongjmp' is later performed with this STATE. |
| |
| -- Function: void siglongjmp (sigjmp_buf STATE, int VALUE) |
| Preliminary: | MT-Safe | AS-Unsafe plugin corrupt lock/hurd | |
| AC-Unsafe corrupt lock/hurd | *Note POSIX Safety Concepts::. |
| |
| This is similar to `longjmp' except for the type of its STATE |
| argument. If the `sigsetjmp' call that set this STATE used a |
| nonzero SAVESIGS flag, `siglongjmp' also restores the set of |
| blocked signals. |
| |
| |
| File: libc.info, Node: System V contexts, Prev: Non-Local Exits and Signals, Up: Non-Local Exits |
| |
| 23.4 Complete Context Control |
| ============================= |
| |
| The Unix standard provides one more set of functions to control the |
| execution path and these functions are more powerful than those |
| discussed in this chapter so far. These functions were part of the |
| original System V API and by this route were added to the Unix API. |
| Besides on branded Unix implementations these interfaces are not widely |
| available. Not all platforms and/or architectures the GNU C Library is |
| available on provide this interface. Use `configure' to detect the |
| availability. |
| |
| Similar to the `jmp_buf' and `sigjmp_buf' types used for the |
| variables to contain the state of the `longjmp' functions the |
| interfaces of interest here have an appropriate type as well. Objects |
| of this type are normally much larger since more information is |
| contained. The type is also used in a few more places as we will see. |
| The types and functions described in this section are all defined and |
| declared respectively in the `ucontext.h' header file. |
| |
| -- Data Type: ucontext_t |
| The `ucontext_t' type is defined as a structure with at least the |
| following elements: |
| |
| `ucontext_t *uc_link' |
| This is a pointer to the next context structure which is used |
| if the context described in the current structure returns. |
| |
| `sigset_t uc_sigmask' |
| Set of signals which are blocked when this context is used. |
| |
| `stack_t uc_stack' |
| Stack used for this context. The value need not be (and |
| normally is not) the stack pointer. *Note Signal Stack::. |
| |
| `mcontext_t uc_mcontext' |
| This element contains the actual state of the process. The |
| `mcontext_t' type is also defined in this header but the |
| definition should be treated as opaque. Any use of knowledge |
| of the type makes applications less portable. |
| |
| |
| Objects of this type have to be created by the user. The |
| initialization and modification happens through one of the following |
| functions: |
| |
| -- Function: int getcontext (ucontext_t *UCP) |
| Preliminary: | MT-Safe race:ucp | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The `getcontext' function initializes the variable pointed to by |
| UCP with the context of the calling thread. The context contains |
| the content of the registers, the signal mask, and the current |
| stack. Executing the contents would start at the point where the |
| `getcontext' call just returned. |
| |
| *Compatibility Note:* Depending on the operating system, |
| information about the current context's stack may be in the |
| `uc_stack' field of UCP, or it may instead be in |
| architecture-specific subfields of the `uc_mcontext' field. |
| |
| The function returns `0' if successful. Otherwise it returns `-1' |
| and sets `errno' accordingly. |
| |
| The `getcontext' function is similar to `setjmp' but it does not |
| provide an indication of whether `getcontext' is returning for the |
| first time or whether an initialized context has just been restored. |
| If this is necessary the user has to determine this herself. This must |
| be done carefully since the context contains registers which might |
| contain register variables. This is a good situation to define |
| variables with `volatile'. |
| |
| Once the context variable is initialized it can be used as is or it |
| can be modified using the `makecontext' function. The latter is |
| normally done when implementing co-routines or similar constructs. |
| |
| -- Function: void makecontext (ucontext_t *UCP, void (*FUNC) (void), |
| int ARGC, ...) |
| Preliminary: | MT-Safe race:ucp | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The UCP parameter passed to `makecontext' shall be initialized by |
| a call to `getcontext'. The context will be modified in a way |
| such that if the context is resumed it will start by calling the |
| function `func' which gets ARGC integer arguments passed. The |
| integer arguments which are to be passed should follow the ARGC |
| parameter in the call to `makecontext'. |
| |
| Before the call to this function the `uc_stack' and `uc_link' |
| element of the UCP structure should be initialized. The |
| `uc_stack' element describes the stack which is used for this |
| context. No two contexts which are used at the same time should |
| use the same memory region for a stack. |
| |
| The `uc_link' element of the object pointed to by UCP should be a |
| pointer to the context to be executed when the function FUNC |
| returns or it should be a null pointer. See `setcontext' for more |
| information about the exact use. |
| |
| While allocating the memory for the stack one has to be careful. |
| Most modern processors keep track of whether a certain memory region is |
| allowed to contain code which is executed or not. Data segments and |
| heap memory are normally not tagged to allow this. The result is that |
| programs would fail. Examples for such code include the calling |
| sequences the GNU C compiler generates for calls to nested functions. |
| Safe ways to allocate stacks correctly include using memory on the |
| original thread's stack or explicitly allocating memory tagged for |
| execution using (*note Memory-mapped I/O::). |
| |
| *Compatibility note*: The current Unix standard is very imprecise |
| about the way the stack is allocated. All implementations seem to agree |
| that the `uc_stack' element must be used but the values stored in the |
| elements of the `stack_t' value are unclear. The GNU C Library and |
| most other Unix implementations require the `ss_sp' value of the |
| `uc_stack' element to point to the base of the memory region allocated |
| for the stack and the size of the memory region is stored in `ss_size'. |
| There are implementations out there which require `ss_sp' to be set to |
| the value the stack pointer will have (which can, depending on the |
| direction the stack grows, be different). This difference makes the |
| `makecontext' function hard to use and it requires detection of the |
| platform at compile time. |
| |
| -- Function: int setcontext (const ucontext_t *UCP) |
| Preliminary: | MT-Safe race:ucp | AS-Unsafe corrupt | AC-Unsafe |
| corrupt | *Note POSIX Safety Concepts::. |
| |
| The `setcontext' function restores the context described by UCP. |
| The context is not modified and can be reused as often as wanted. |
| |
| If the context was created by `getcontext' execution resumes with |
| the registers filled with the same values and the same stack as if |
| the `getcontext' call just returned. |
| |
| If the context was modified with a call to `makecontext' execution |
| continues with the function passed to `makecontext' which gets the |
| specified parameters passed. If this function returns execution is |
| resumed in the context which was referenced by the `uc_link' |
| element of the context structure passed to `makecontext' at the |
| time of the call. If `uc_link' was a null pointer the application |
| terminates normally with an exit status value of `EXIT_SUCCESS' |
| (*note Program Termination::). |
| |
| If the context was created by a call to a signal handler or from |
| any other source then the behaviour of `setcontext' is unspecified. |
| |
| Since the context contains information about the stack no two |
| threads should use the same context at the same time. The result |
| in most cases would be disastrous. |
| |
| The `setcontext' function does not return unless an error occurred |
| in which case it returns `-1'. |
| |
| The `setcontext' function simply replaces the current context with |
| the one described by the UCP parameter. This is often useful but there |
| are situations where the current context has to be preserved. |
| |
| -- Function: int swapcontext (ucontext_t *restrict OUCP, const |
| ucontext_t *restrict UCP) |
| Preliminary: | MT-Safe race:oucp race:ucp | AS-Unsafe corrupt | |
| AC-Unsafe corrupt | *Note POSIX Safety Concepts::. |
| |
| The `swapcontext' function is similar to `setcontext' but instead |
| of just replacing the current context the latter is first saved in |
| the object pointed to by OUCP as if this was a call to |
| `getcontext'. The saved context would resume after the call to |
| `swapcontext'. |
| |
| Once the current context is saved the context described in UCP is |
| installed and execution continues as described in this context. |
| |
| If `swapcontext' succeeds the function does not return unless the |
| context OUCP is used without prior modification by `makecontext'. |
| The return value in this case is `0'. If the function fails it |
| returns `-1' and sets `errno' accordingly. |
| |
| Example for SVID Context Handling |
| ================================= |
| |
| The easiest way to use the context handling functions is as a |
| replacement for `setjmp' and `longjmp'. The context contains on most |
| platforms more information which may lead to fewer surprises but this |
| also means using these functions is more expensive (besides being less |
| portable). |
| |
| int |
| random_search (int n, int (*fp) (int, ucontext_t *)) |
| { |
| volatile int cnt = 0; |
| ucontext_t uc; |
| |
| /* Safe current context. */ |
| if (getcontext (&uc) < 0) |
| return -1; |
| |
| /* If we have not tried N times try again. */ |
| if (cnt++ < n) |
| /* Call the function with a new random number |
| and the context. */ |
| if (fp (rand (), &uc) != 0) |
| /* We found what we were looking for. */ |
| return 1; |
| |
| /* Not found. */ |
| return 0; |
| } |
| |
| Using contexts in such a way enables emulating exception handling. |
| The search functions passed in the FP parameter could be very large, |
| nested, and complex which would make it complicated (or at least would |
| require a lot of code) to leave the function with an error value which |
| has to be passed down to the caller. By using the context it is |
| possible to leave the search function in one step and allow restarting |
| the search which also has the nice side effect that it can be |
| significantly faster. |
| |
| Something which is harder to implement with `setjmp' and `longjmp' |
| is to switch temporarily to a different execution path and then resume |
| where execution was stopped. |
| |
| |
| #include <signal.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <ucontext.h> |
| #include <sys/time.h> |
| |
| /* Set by the signal handler. */ |
| static volatile int expired; |
| |
| /* The contexts. */ |
| static ucontext_t uc[3]; |
| |
| /* We do only a certain number of switches. */ |
| static int switches; |
| |
| |
| /* This is the function doing the work. It is just a |
| skeleton, real code has to be filled in. */ |
| static void |
| f (int n) |
| { |
| int m = 0; |
| while (1) |
| { |
| /* This is where the work would be done. */ |
| if (++m % 100 == 0) |
| { |
| putchar ('.'); |
| fflush (stdout); |
| } |
| |
| /* Regularly the EXPIRE variable must be checked. */ |
| if (expired) |
| { |
| /* We do not want the program to run forever. */ |
| if (++switches == 20) |
| return; |
| |
| printf ("\nswitching from %d to %d\n", n, 3 - n); |
| expired = 0; |
| /* Switch to the other context, saving the current one. */ |
| swapcontext (&uc[n], &uc[3 - n]); |
| } |
| } |
| } |
| |
| /* This is the signal handler which simply set the variable. */ |
| void |
| handler (int signal) |
| { |
| expired = 1; |
| } |
| |
| |
| int |
| main (void) |
| { |
| struct sigaction sa; |
| struct itimerval it; |
| char st1[8192]; |
| char st2[8192]; |
| |
| /* Initialize the data structures for the interval timer. */ |
| sa.sa_flags = SA_RESTART; |
| sigfillset (&sa.sa_mask); |
| sa.sa_handler = handler; |
| it.it_interval.tv_sec = 0; |
| it.it_interval.tv_usec = 1; |
| it.it_value = it.it_interval; |
| |
| /* Install the timer and get the context we can manipulate. */ |
| if (sigaction (SIGPROF, &sa, NULL) < 0 |
| || setitimer (ITIMER_PROF, &it, NULL) < 0 |
| || getcontext (&uc[1]) == -1 |
| || getcontext (&uc[2]) == -1) |
| abort (); |
| |
| /* Create a context with a separate stack which causes the |
| function `f' to be call with the parameter `1'. |
| Note that the `uc_link' points to the main context |
| which will cause the program to terminate once the function |
| return. */ |
| uc[1].uc_link = &uc[0]; |
| uc[1].uc_stack.ss_sp = st1; |
| uc[1].uc_stack.ss_size = sizeof st1; |
| makecontext (&uc[1], (void (*) (void)) f, 1, 1); |
| |
| /* Similarly, but `2' is passed as the parameter to `f'. */ |
| uc[2].uc_link = &uc[0]; |
| uc[2].uc_stack.ss_sp = st2; |
| uc[2].uc_stack.ss_size = sizeof st2; |
| makecontext (&uc[2], (void (*) (void)) f, 1, 2); |
| |
| /* Start running. */ |
| swapcontext (&uc[0], &uc[1]); |
| putchar ('\n'); |
| |
| return 0; |
| } |
| |
| This an example how the context functions can be used to implement |
| co-routines or cooperative multi-threading. All that has to be done is |
| to call every once in a while `swapcontext' to continue running a |
| different context. It is not recommended to do the context switching |
| from the signal handler directly since leaving the signal handler via |
| `setcontext' if the signal was delivered during code that was not |
| asynchronous signal safe could lead to problems. Setting a variable in |
| the signal handler and checking it in the body of the functions which |
| are executed is a safer approach. Since `swapcontext' is saving the |
| current context it is possible to have multiple different scheduling |
| points in the code. Execution will always resume where it was left. |
| |
| |
| File: libc.info, Node: Signal Handling, Next: Program Basics, Prev: Non-Local Exits, Up: Top |
| |
| 24 Signal Handling |
| ****************** |
| |
| A "signal" is a software interrupt delivered to a process. The |
| operating system uses signals to report exceptional situations to an |
| executing program. Some signals report errors such as references to |
| invalid memory addresses; others report asynchronous events, such as |
| disconnection of a phone line. |
| |
| The GNU C Library defines a variety of signal types, each for a |
| particular kind of event. Some kinds of events make it inadvisable or |
| impossible for the program to proceed as usual, and the corresponding |
| signals normally abort the program. Other kinds of signals that report |
| harmless events are ignored by default. |
| |
| If you anticipate an event that causes signals, you can define a |
| handler function and tell the operating system to run it when that |
| particular type of signal arrives. |
| |
| Finally, one process can send a signal to another process; this |
| allows a parent process to abort a child, or two related processes to |
| communicate and synchronize. |
| |
| * Menu: |
| |
| * Concepts of Signals:: Introduction to the signal facilities. |
| * Standard Signals:: Particular kinds of signals with |
| standard names and meanings. |
| * Signal Actions:: Specifying what happens when a |
| particular signal is delivered. |
| * Defining Handlers:: How to write a signal handler function. |
| * Interrupted Primitives:: Signal handlers affect use of `open', |
| `read', `write' and other functions. |
| * Generating Signals:: How to send a signal to a process. |
| * Blocking Signals:: Making the system hold signals temporarily. |
| * Waiting for a Signal:: Suspending your program until a signal |
| arrives. |
| * Signal Stack:: Using a Separate Signal Stack. |
| * BSD Signal Handling:: Additional functions for backward |
| compatibility with BSD. |
| |
| |
| File: libc.info, Node: Concepts of Signals, Next: Standard Signals, Up: Signal Handling |
| |
| 24.1 Basic Concepts of Signals |
| ============================== |
| |
| This section explains basic concepts of how signals are generated, what |
| happens after a signal is delivered, and how programs can handle |
| signals. |
| |
| * Menu: |
| |
| * Kinds of Signals:: Some examples of what can cause a signal. |
| * Signal Generation:: Concepts of why and how signals occur. |
| * Delivery of Signal:: Concepts of what a signal does to the |
| process. |
| |
| |
| File: libc.info, Node: Kinds of Signals, Next: Signal Generation, Up: Concepts of Signals |
| |
| 24.1.1 Some Kinds of Signals |
| ---------------------------- |
| |
| A signal reports the occurrence of an exceptional event. These are some |
| of the events that can cause (or "generate", or "raise") a signal: |
| |
| * A program error such as dividing by zero or issuing an address |
| outside the valid range. |
| |
| * A user request to interrupt or terminate the program. Most |
| environments are set up to let a user suspend the program by |
| typing `C-z', or terminate it with `C-c'. Whatever key sequence |
| is used, the operating system sends the proper signal to interrupt |
| the process. |
| |
| * The termination of a child process. |
| |
| * Expiration of a timer or alarm. |
| |
| * A call to `kill' or `raise' by the same process. |
| |
| * A call to `kill' from another process. Signals are a limited but |
| useful form of interprocess communication. |
| |
| * An attempt to perform an I/O operation that cannot be done. |
| Examples are reading from a pipe that has no writer (*note Pipes |
| and FIFOs::), and reading or writing to a terminal in certain |
| situations (*note Job Control::). |
| |
| Each of these kinds of events (excepting explicit calls to `kill' |
| and `raise') generates its own particular kind of signal. The various |
| kinds of signals are listed and described in detail in *note Standard |
| Signals::. |
| |
| |
| File: libc.info, Node: Signal Generation, Next: Delivery of Signal, Prev: Kinds of Signals, Up: Concepts of Signals |
| |
| 24.1.2 Concepts of Signal Generation |
| ------------------------------------ |
| |
| In general, the events that generate signals fall into three major |
| categories: errors, external events, and explicit requests. |
| |
| An error means that a program has done something invalid and cannot |
| continue execution. But not all kinds of errors generate signals--in |
| fact, most do not. For example, opening a nonexistent file is an error, |
| but it does not raise a signal; instead, `open' returns `-1'. In |
| general, errors that are necessarily associated with certain library |
| functions are reported by returning a value that indicates an error. |
| The errors which raise signals are those which can happen anywhere in |
| the program, not just in library calls. These include division by zero |
| and invalid memory addresses. |
| |
| An external event generally has to do with I/O or other processes. |
| These include the arrival of input, the expiration of a timer, and the |
| termination of a child process. |
| |
| An explicit request means the use of a library function such as |
| `kill' whose purpose is specifically to generate a signal. |
| |
| Signals may be generated "synchronously" or "asynchronously". A |
| synchronous signal pertains to a specific action in the program, and is |
| delivered (unless blocked) during that action. Most errors generate |
| signals synchronously, and so do explicit requests by a process to |
| generate a signal for that same process. On some machines, certain |
| kinds of hardware errors (usually floating-point exceptions) are not |
| reported completely synchronously, but may arrive a few instructions |
| later. |
| |
| Asynchronous signals are generated by events outside the control of |
| the process that receives them. These signals arrive at unpredictable |
| times during execution. External events generate signals |
| asynchronously, and so do explicit requests that apply to some other |
| process. |
| |
| A given type of signal is either typically synchronous or typically |
| asynchronous. For example, signals for errors are typically synchronous |
| because errors generate signals synchronously. But any type of signal |
| can be generated synchronously or asynchronously with an explicit |
| request. |
| |
| |
| File: libc.info, Node: Delivery of Signal, Prev: Signal Generation, Up: Concepts of Signals |
| |
| 24.1.3 How Signals Are Delivered |
| -------------------------------- |
| |
| When a signal is generated, it becomes "pending". Normally it remains |
| pending for just a short period of time and then is "delivered" to the |
| process that was signaled. However, if that kind of signal is |
| currently "blocked", it may remain pending indefinitely--until signals |
| of that kind are "unblocked". Once unblocked, it will be delivered |
| immediately. *Note Blocking Signals::. |
| |
| When the signal is delivered, whether right away or after a long |
| delay, the "specified action" for that signal is taken. For certain |
| signals, such as `SIGKILL' and `SIGSTOP', the action is fixed, but for |
| most signals, the program has a choice: ignore the signal, specify a |
| "handler function", or accept the "default action" for that kind of |
| signal. The program specifies its choice using functions such as |
| `signal' or `sigaction' (*note Signal Actions::). We sometimes say |
| that a handler "catches" the signal. While the handler is running, |
| that particular signal is normally blocked. |
| |
| If the specified action for a kind of signal is to ignore it, then |
| any such signal which is generated is discarded immediately. This |
| happens even if the signal is also blocked at the time. A signal |
| discarded in this way will never be delivered, not even if the program |
| subsequently specifies a different action for that kind of signal and |
| then unblocks it. |
| |
| If a signal arrives which the program has neither handled nor |
| ignored, its "default action" takes place. Each kind of signal has its |
| own default action, documented below (*note Standard Signals::). For |
| most kinds of signals, the default action is to terminate the process. |
| For certain kinds of signals that represent "harmless" events, the |
| default action is to do nothing. |
| |
| When a signal terminates a process, its parent process can determine |
| the cause of termination by examining the termination status code |
| reported by the `wait' or `waitpid' functions. (This is discussed in |
| more detail in *note Process Completion::.) The information it can get |
| includes the fact that termination was due to a signal and the kind of |
| signal involved. If a program you run from a shell is terminated by a |
| signal, the shell typically prints some kind of error message. |
| |
| The signals that normally represent program errors have a special |
| property: when one of these signals terminates the process, it also |
| writes a "core dump file" which records the state of the process at the |
| time of termination. You can examine the core dump with a debugger to |
| investigate what caused the error. |
| |
| If you raise a "program error" signal by explicit request, and this |
| terminates the process, it makes a core dump file just as if the signal |
| had been due directly to an error. |
| |
| |
| File: libc.info, Node: Standard Signals, Next: Signal Actions, Prev: Concepts of Signals, Up: Signal Handling |
| |
| 24.2 Standard Signals |
| ===================== |
| |
| This section lists the names for various standard kinds of signals and |
| describes what kind of event they mean. Each signal name is a macro |
| which stands for a positive integer--the "signal number" for that kind |
| of signal. Your programs should never make assumptions about the |
| numeric code for a particular kind of signal, but rather refer to them |
| always by the names defined here. This is because the number for a |
| given kind of signal can vary from system to system, but the meanings of |
| the names are standardized and fairly uniform. |
| |
| The signal names are defined in the header file `signal.h'. |
| |
| -- Macro: int NSIG |
| The value of this symbolic constant is the total number of signals |
| defined. Since the signal numbers are allocated consecutively, |
| `NSIG' is also one greater than the largest defined signal number. |
| |
| * Menu: |
| |
| * Program Error Signals:: Used to report serious program errors. |
| * Termination Signals:: Used to interrupt and/or terminate the |
| program. |
| * Alarm Signals:: Used to indicate expiration of timers. |
| * Asynchronous I/O Signals:: Used to indicate input is available. |
| * Job Control Signals:: Signals used to support job control. |
| * Operation Error Signals:: Used to report operational system errors. |
| * Miscellaneous Signals:: Miscellaneous Signals. |
| * Signal Messages:: Printing a message describing a signal. |
| |
| |
| |
| Local Variables: |
| coding: utf-8 |
| End: |
