This is libc.info, produced by makeinfo version 5.1 from libc.texinfo.
|
|
This is ‘The GNU C Library Reference Manual’, for version 2.33 (GNU).
|
|
Copyright © 1993–2021 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being “Free Software Needs Free Documentation” and
|
“GNU Lesser General Public License”, the Front-Cover texts being “A GNU
|
Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
|
license is included in the section entitled "GNU Free Documentation
|
License".
|
|
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
|
modify this GNU manual. Buying copies from the FSF supports it in
|
developing GNU and promoting software freedom.”
|
INFO-DIR-SECTION Software libraries
|
START-INFO-DIR-ENTRY
|
* Libc: (libc). C library.
|
END-INFO-DIR-ENTRY
|
|
INFO-DIR-SECTION GNU C library functions and macros
|
START-INFO-DIR-ENTRY
|
* ALTWERASE: (libc)Local Modes.
|
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
|
* ARG_MAX: (libc)General Limits.
|
* BC_BASE_MAX: (libc)Utility Limits.
|
* BC_DIM_MAX: (libc)Utility Limits.
|
* BC_SCALE_MAX: (libc)Utility Limits.
|
* BC_STRING_MAX: (libc)Utility Limits.
|
* BRKINT: (libc)Input Modes.
|
* BUFSIZ: (libc)Controlling Buffering.
|
* CCTS_OFLOW: (libc)Control Modes.
|
* CHAR_BIT: (libc)Width of Type.
|
* CHILD_MAX: (libc)General Limits.
|
* CIGNORE: (libc)Control Modes.
|
* CLK_TCK: (libc)Processor Time.
|
* CLOCAL: (libc)Control Modes.
|
* CLOCKS_PER_SEC: (libc)CPU Time.
|
* CLOCK_MONOTONIC: (libc)Getting the Time.
|
* CLOCK_REALTIME: (libc)Getting the Time.
|
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
|
* CPU_CLR: (libc)CPU Affinity.
|
* CPU_FEATURE_USABLE: (libc)X86.
|
* CPU_ISSET: (libc)CPU Affinity.
|
* CPU_SET: (libc)CPU Affinity.
|
* CPU_SETSIZE: (libc)CPU Affinity.
|
* CPU_ZERO: (libc)CPU Affinity.
|
* CREAD: (libc)Control Modes.
|
* CRTS_IFLOW: (libc)Control Modes.
|
* CS5: (libc)Control Modes.
|
* CS6: (libc)Control Modes.
|
* CS7: (libc)Control Modes.
|
* CS8: (libc)Control Modes.
|
* CSIZE: (libc)Control Modes.
|
* CSTOPB: (libc)Control Modes.
|
* DTTOIF: (libc)Directory Entries.
|
* E2BIG: (libc)Error Codes.
|
* EACCES: (libc)Error Codes.
|
* EADDRINUSE: (libc)Error Codes.
|
* EADDRNOTAVAIL: (libc)Error Codes.
|
* EADV: (libc)Error Codes.
|
* EAFNOSUPPORT: (libc)Error Codes.
|
* EAGAIN: (libc)Error Codes.
|
* EALREADY: (libc)Error Codes.
|
* EAUTH: (libc)Error Codes.
|
* EBACKGROUND: (libc)Error Codes.
|
* EBADE: (libc)Error Codes.
|
* EBADF: (libc)Error Codes.
|
* EBADFD: (libc)Error Codes.
|
* EBADMSG: (libc)Error Codes.
|
* EBADR: (libc)Error Codes.
|
* EBADRPC: (libc)Error Codes.
|
* EBADRQC: (libc)Error Codes.
|
* EBADSLT: (libc)Error Codes.
|
* EBFONT: (libc)Error Codes.
|
* EBUSY: (libc)Error Codes.
|
* ECANCELED: (libc)Error Codes.
|
* ECHILD: (libc)Error Codes.
|
* ECHO: (libc)Local Modes.
|
* ECHOCTL: (libc)Local Modes.
|
* ECHOE: (libc)Local Modes.
|
* ECHOK: (libc)Local Modes.
|
* ECHOKE: (libc)Local Modes.
|
* ECHONL: (libc)Local Modes.
|
* ECHOPRT: (libc)Local Modes.
|
* ECHRNG: (libc)Error Codes.
|
* ECOMM: (libc)Error Codes.
|
* ECONNABORTED: (libc)Error Codes.
|
* ECONNREFUSED: (libc)Error Codes.
|
* ECONNRESET: (libc)Error Codes.
|
* ED: (libc)Error Codes.
|
* EDEADLK: (libc)Error Codes.
|
* EDEADLOCK: (libc)Error Codes.
|
* EDESTADDRREQ: (libc)Error Codes.
|
* EDIED: (libc)Error Codes.
|
* EDOM: (libc)Error Codes.
|
* EDOTDOT: (libc)Error Codes.
|
* EDQUOT: (libc)Error Codes.
|
* EEXIST: (libc)Error Codes.
|
* EFAULT: (libc)Error Codes.
|
* EFBIG: (libc)Error Codes.
|
* EFTYPE: (libc)Error Codes.
|
* EGRATUITOUS: (libc)Error Codes.
|
* EGREGIOUS: (libc)Error Codes.
|
* EHOSTDOWN: (libc)Error Codes.
|
* EHOSTUNREACH: (libc)Error Codes.
|
* EHWPOISON: (libc)Error Codes.
|
* EIDRM: (libc)Error Codes.
|
* EIEIO: (libc)Error Codes.
|
* EILSEQ: (libc)Error Codes.
|
* EINPROGRESS: (libc)Error Codes.
|
* EINTR: (libc)Error Codes.
|
* EINVAL: (libc)Error Codes.
|
* EIO: (libc)Error Codes.
|
* EISCONN: (libc)Error Codes.
|
* EISDIR: (libc)Error Codes.
|
* EISNAM: (libc)Error Codes.
|
* EKEYEXPIRED: (libc)Error Codes.
|
* EKEYREJECTED: (libc)Error Codes.
|
* EKEYREVOKED: (libc)Error Codes.
|
* EL2HLT: (libc)Error Codes.
|
* EL2NSYNC: (libc)Error Codes.
|
* EL3HLT: (libc)Error Codes.
|
* EL3RST: (libc)Error Codes.
|
* ELIBACC: (libc)Error Codes.
|
* ELIBBAD: (libc)Error Codes.
|
* ELIBEXEC: (libc)Error Codes.
|
* ELIBMAX: (libc)Error Codes.
|
* ELIBSCN: (libc)Error Codes.
|
* ELNRNG: (libc)Error Codes.
|
* ELOOP: (libc)Error Codes.
|
* EMEDIUMTYPE: (libc)Error Codes.
|
* EMFILE: (libc)Error Codes.
|
* EMLINK: (libc)Error Codes.
|
* EMSGSIZE: (libc)Error Codes.
|
* EMULTIHOP: (libc)Error Codes.
|
* ENAMETOOLONG: (libc)Error Codes.
|
* ENAVAIL: (libc)Error Codes.
|
* ENEEDAUTH: (libc)Error Codes.
|
* ENETDOWN: (libc)Error Codes.
|
* ENETRESET: (libc)Error Codes.
|
* ENETUNREACH: (libc)Error Codes.
|
* ENFILE: (libc)Error Codes.
|
* ENOANO: (libc)Error Codes.
|
* ENOBUFS: (libc)Error Codes.
|
* ENOCSI: (libc)Error Codes.
|
* ENODATA: (libc)Error Codes.
|
* ENODEV: (libc)Error Codes.
|
* ENOENT: (libc)Error Codes.
|
* ENOEXEC: (libc)Error Codes.
|
* ENOKEY: (libc)Error Codes.
|
* ENOLCK: (libc)Error Codes.
|
* ENOLINK: (libc)Error Codes.
|
* ENOMEDIUM: (libc)Error Codes.
|
* ENOMEM: (libc)Error Codes.
|
* ENOMSG: (libc)Error Codes.
|
* ENONET: (libc)Error Codes.
|
* ENOPKG: (libc)Error Codes.
|
* ENOPROTOOPT: (libc)Error Codes.
|
* ENOSPC: (libc)Error Codes.
|
* ENOSR: (libc)Error Codes.
|
* ENOSTR: (libc)Error Codes.
|
* ENOSYS: (libc)Error Codes.
|
* ENOTBLK: (libc)Error Codes.
|
* ENOTCONN: (libc)Error Codes.
|
* ENOTDIR: (libc)Error Codes.
|
* ENOTEMPTY: (libc)Error Codes.
|
* ENOTNAM: (libc)Error Codes.
|
* ENOTRECOVERABLE: (libc)Error Codes.
|
* ENOTSOCK: (libc)Error Codes.
|
* ENOTSUP: (libc)Error Codes.
|
* ENOTTY: (libc)Error Codes.
|
* ENOTUNIQ: (libc)Error Codes.
|
* ENXIO: (libc)Error Codes.
|
* EOF: (libc)EOF and Errors.
|
* EOPNOTSUPP: (libc)Error Codes.
|
* EOVERFLOW: (libc)Error Codes.
|
* EOWNERDEAD: (libc)Error Codes.
|
* EPERM: (libc)Error Codes.
|
* EPFNOSUPPORT: (libc)Error Codes.
|
* EPIPE: (libc)Error Codes.
|
* EPROCLIM: (libc)Error Codes.
|
* EPROCUNAVAIL: (libc)Error Codes.
|
* EPROGMISMATCH: (libc)Error Codes.
|
* EPROGUNAVAIL: (libc)Error Codes.
|
* EPROTO: (libc)Error Codes.
|
* EPROTONOSUPPORT: (libc)Error Codes.
|
* EPROTOTYPE: (libc)Error Codes.
|
* EQUIV_CLASS_MAX: (libc)Utility Limits.
|
* ERANGE: (libc)Error Codes.
|
* EREMCHG: (libc)Error Codes.
|
* EREMOTE: (libc)Error Codes.
|
* EREMOTEIO: (libc)Error Codes.
|
* ERESTART: (libc)Error Codes.
|
* ERFKILL: (libc)Error Codes.
|
* EROFS: (libc)Error Codes.
|
* ERPCMISMATCH: (libc)Error Codes.
|
* ESHUTDOWN: (libc)Error Codes.
|
* ESOCKTNOSUPPORT: (libc)Error Codes.
|
* ESPIPE: (libc)Error Codes.
|
* ESRCH: (libc)Error Codes.
|
* ESRMNT: (libc)Error Codes.
|
* ESTALE: (libc)Error Codes.
|
* ESTRPIPE: (libc)Error Codes.
|
* ETIME: (libc)Error Codes.
|
* ETIMEDOUT: (libc)Error Codes.
|
* ETOOMANYREFS: (libc)Error Codes.
|
* ETXTBSY: (libc)Error Codes.
|
* EUCLEAN: (libc)Error Codes.
|
* EUNATCH: (libc)Error Codes.
|
* EUSERS: (libc)Error Codes.
|
* EWOULDBLOCK: (libc)Error Codes.
|
* EXDEV: (libc)Error Codes.
|
* EXFULL: (libc)Error Codes.
|
* EXIT_FAILURE: (libc)Exit Status.
|
* EXIT_SUCCESS: (libc)Exit Status.
|
* EXPR_NEST_MAX: (libc)Utility Limits.
|
* FD_CLOEXEC: (libc)Descriptor Flags.
|
* FD_CLR: (libc)Waiting for I/O.
|
* FD_ISSET: (libc)Waiting for I/O.
|
* FD_SET: (libc)Waiting for I/O.
|
* FD_SETSIZE: (libc)Waiting for I/O.
|
* FD_ZERO: (libc)Waiting for I/O.
|
* FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
|
* FILENAME_MAX: (libc)Limits for Files.
|
* FLUSHO: (libc)Local Modes.
|
* FOPEN_MAX: (libc)Opening Streams.
|
* FP_ILOGB0: (libc)Exponents and Logarithms.
|
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
|
* FP_LLOGB0: (libc)Exponents and Logarithms.
|
* FP_LLOGBNAN: (libc)Exponents and Logarithms.
|
* F_DUPFD: (libc)Duplicating Descriptors.
|
* F_GETFD: (libc)Descriptor Flags.
|
* F_GETFL: (libc)Getting File Status Flags.
|
* F_GETLK: (libc)File Locks.
|
* F_GETOWN: (libc)Interrupt Input.
|
* F_OFD_GETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLKW: (libc)Open File Description Locks.
|
* F_OK: (libc)Testing File Access.
|
* F_SETFD: (libc)Descriptor Flags.
|
* F_SETFL: (libc)Getting File Status Flags.
|
* F_SETLK: (libc)File Locks.
|
* F_SETLKW: (libc)File Locks.
|
* F_SETOWN: (libc)Interrupt Input.
|
* HAS_CPU_FEATURE: (libc)X86.
|
* HUGE_VAL: (libc)Math Error Reporting.
|
* HUGE_VALF: (libc)Math Error Reporting.
|
* HUGE_VALL: (libc)Math Error Reporting.
|
* HUGE_VAL_FN: (libc)Math Error Reporting.
|
* HUGE_VAL_FNx: (libc)Math Error Reporting.
|
* HUPCL: (libc)Control Modes.
|
* I: (libc)Complex Numbers.
|
* ICANON: (libc)Local Modes.
|
* ICRNL: (libc)Input Modes.
|
* IEXTEN: (libc)Local Modes.
|
* IFNAMSIZ: (libc)Interface Naming.
|
* IFTODT: (libc)Directory Entries.
|
* IGNBRK: (libc)Input Modes.
|
* IGNCR: (libc)Input Modes.
|
* IGNPAR: (libc)Input Modes.
|
* IMAXBEL: (libc)Input Modes.
|
* INADDR_ANY: (libc)Host Address Data Type.
|
* INADDR_BROADCAST: (libc)Host Address Data Type.
|
* INADDR_LOOPBACK: (libc)Host Address Data Type.
|
* INADDR_NONE: (libc)Host Address Data Type.
|
* INFINITY: (libc)Infinity and NaN.
|
* INLCR: (libc)Input Modes.
|
* INPCK: (libc)Input Modes.
|
* IPPORT_RESERVED: (libc)Ports.
|
* IPPORT_USERRESERVED: (libc)Ports.
|
* ISIG: (libc)Local Modes.
|
* ISTRIP: (libc)Input Modes.
|
* IXANY: (libc)Input Modes.
|
* IXOFF: (libc)Input Modes.
|
* IXON: (libc)Input Modes.
|
* LINE_MAX: (libc)Utility Limits.
|
* LINK_MAX: (libc)Limits for Files.
|
* L_ctermid: (libc)Identifying the Terminal.
|
* L_cuserid: (libc)Who Logged In.
|
* L_tmpnam: (libc)Temporary Files.
|
* MAXNAMLEN: (libc)Limits for Files.
|
* MAXSYMLINKS: (libc)Symbolic Links.
|
* MAX_CANON: (libc)Limits for Files.
|
* MAX_INPUT: (libc)Limits for Files.
|
* MB_CUR_MAX: (libc)Selecting the Conversion.
|
* MB_LEN_MAX: (libc)Selecting the Conversion.
|
* MDMBUF: (libc)Control Modes.
|
* MSG_DONTROUTE: (libc)Socket Data Options.
|
* MSG_OOB: (libc)Socket Data Options.
|
* MSG_PEEK: (libc)Socket Data Options.
|
* NAME_MAX: (libc)Limits for Files.
|
* NAN: (libc)Infinity and NaN.
|
* NCCS: (libc)Mode Data Types.
|
* NGROUPS_MAX: (libc)General Limits.
|
* NOFLSH: (libc)Local Modes.
|
* NOKERNINFO: (libc)Local Modes.
|
* NSIG: (libc)Standard Signals.
|
* NULL: (libc)Null Pointer Constant.
|
* ONLCR: (libc)Output Modes.
|
* ONOEOT: (libc)Output Modes.
|
* OPEN_MAX: (libc)General Limits.
|
* OPOST: (libc)Output Modes.
|
* OXTABS: (libc)Output Modes.
|
* O_ACCMODE: (libc)Access Modes.
|
* O_APPEND: (libc)Operating Modes.
|
* O_ASYNC: (libc)Operating Modes.
|
* O_CREAT: (libc)Open-time Flags.
|
* O_DIRECTORY: (libc)Open-time Flags.
|
* O_EXCL: (libc)Open-time Flags.
|
* O_EXEC: (libc)Access Modes.
|
* O_EXLOCK: (libc)Open-time Flags.
|
* O_FSYNC: (libc)Operating Modes.
|
* O_IGNORE_CTTY: (libc)Open-time Flags.
|
* O_NDELAY: (libc)Operating Modes.
|
* O_NOATIME: (libc)Operating Modes.
|
* O_NOCTTY: (libc)Open-time Flags.
|
* O_NOFOLLOW: (libc)Open-time Flags.
|
* O_NOLINK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Operating Modes.
|
* O_NOTRANS: (libc)Open-time Flags.
|
* O_PATH: (libc)Access Modes.
|
* O_RDONLY: (libc)Access Modes.
|
* O_RDWR: (libc)Access Modes.
|
* O_READ: (libc)Access Modes.
|
* O_SHLOCK: (libc)Open-time Flags.
|
* O_SYNC: (libc)Operating Modes.
|
* O_TMPFILE: (libc)Open-time Flags.
|
* O_TRUNC: (libc)Open-time Flags.
|
* O_WRITE: (libc)Access Modes.
|
* O_WRONLY: (libc)Access Modes.
|
* PARENB: (libc)Control Modes.
|
* PARMRK: (libc)Input Modes.
|
* PARODD: (libc)Control Modes.
|
* PATH_MAX: (libc)Limits for Files.
|
* PA_FLAG_MASK: (libc)Parsing a Template String.
|
* PENDIN: (libc)Local Modes.
|
* PF_FILE: (libc)Local Namespace Details.
|
* PF_INET6: (libc)Internet Namespace.
|
* PF_INET: (libc)Internet Namespace.
|
* PF_LOCAL: (libc)Local Namespace Details.
|
* PF_UNIX: (libc)Local Namespace Details.
|
* PIPE_BUF: (libc)Limits for Files.
|
* PTHREAD_ATTR_NO_SIGMASK_NP: (libc)Initial Thread Signal Mask.
|
* P_tmpdir: (libc)Temporary Files.
|
* RAND_MAX: (libc)ISO Random.
|
* RE_DUP_MAX: (libc)General Limits.
|
* RLIM_INFINITY: (libc)Limits on Resources.
|
* R_OK: (libc)Testing File Access.
|
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
|
* SA_ONSTACK: (libc)Flags for Sigaction.
|
* SA_RESTART: (libc)Flags for Sigaction.
|
* SEEK_CUR: (libc)File Positioning.
|
* SEEK_END: (libc)File Positioning.
|
* SEEK_SET: (libc)File Positioning.
|
* SIGABRT: (libc)Program Error Signals.
|
* SIGALRM: (libc)Alarm Signals.
|
* SIGBUS: (libc)Program Error Signals.
|
* SIGCHLD: (libc)Job Control Signals.
|
* SIGCLD: (libc)Job Control Signals.
|
* SIGCONT: (libc)Job Control Signals.
|
* SIGEMT: (libc)Program Error Signals.
|
* SIGFPE: (libc)Program Error Signals.
|
* SIGHUP: (libc)Termination Signals.
|
* SIGILL: (libc)Program Error Signals.
|
* SIGINFO: (libc)Miscellaneous Signals.
|
* SIGINT: (libc)Termination Signals.
|
* SIGIO: (libc)Asynchronous I/O Signals.
|
* SIGIOT: (libc)Program Error Signals.
|
* SIGKILL: (libc)Termination Signals.
|
* SIGLOST: (libc)Operation Error Signals.
|
* SIGPIPE: (libc)Operation Error Signals.
|
* SIGPOLL: (libc)Asynchronous I/O Signals.
|
* SIGPROF: (libc)Alarm Signals.
|
* SIGQUIT: (libc)Termination Signals.
|
* SIGSEGV: (libc)Program Error Signals.
|
* SIGSTOP: (libc)Job Control Signals.
|
* SIGSYS: (libc)Program Error Signals.
|
* SIGTERM: (libc)Termination Signals.
|
* SIGTRAP: (libc)Program Error Signals.
|
* SIGTSTP: (libc)Job Control Signals.
|
* SIGTTIN: (libc)Job Control Signals.
|
* SIGTTOU: (libc)Job Control Signals.
|
* SIGURG: (libc)Asynchronous I/O Signals.
|
* SIGUSR1: (libc)Miscellaneous Signals.
|
* SIGUSR2: (libc)Miscellaneous Signals.
|
* SIGVTALRM: (libc)Alarm Signals.
|
* SIGWINCH: (libc)Miscellaneous Signals.
|
* SIGXCPU: (libc)Operation Error Signals.
|
* SIGXFSZ: (libc)Operation Error Signals.
|
* SIG_ERR: (libc)Basic Signal Handling.
|
* SNAN: (libc)Infinity and NaN.
|
* SNANF: (libc)Infinity and NaN.
|
* SNANFN: (libc)Infinity and NaN.
|
* SNANFNx: (libc)Infinity and NaN.
|
* SNANL: (libc)Infinity and NaN.
|
* SOCK_DGRAM: (libc)Communication Styles.
|
* SOCK_RAW: (libc)Communication Styles.
|
* SOCK_RDM: (libc)Communication Styles.
|
* SOCK_SEQPACKET: (libc)Communication Styles.
|
* SOCK_STREAM: (libc)Communication Styles.
|
* SOL_SOCKET: (libc)Socket-Level Options.
|
* SSIZE_MAX: (libc)General Limits.
|
* STREAM_MAX: (libc)General Limits.
|
* SUN_LEN: (libc)Local Namespace Details.
|
* S_IFMT: (libc)Testing File Type.
|
* S_ISBLK: (libc)Testing File Type.
|
* S_ISCHR: (libc)Testing File Type.
|
* S_ISDIR: (libc)Testing File Type.
|
* S_ISFIFO: (libc)Testing File Type.
|
* S_ISLNK: (libc)Testing File Type.
|
* S_ISREG: (libc)Testing File Type.
|
* S_ISSOCK: (libc)Testing File Type.
|
* S_TYPEISMQ: (libc)Testing File Type.
|
* S_TYPEISSEM: (libc)Testing File Type.
|
* S_TYPEISSHM: (libc)Testing File Type.
|
* TMP_MAX: (libc)Temporary Files.
|
* TOSTOP: (libc)Local Modes.
|
* TZNAME_MAX: (libc)General Limits.
|
* VDISCARD: (libc)Other Special.
|
* VDSUSP: (libc)Signal Characters.
|
* VEOF: (libc)Editing Characters.
|
* VEOL2: (libc)Editing Characters.
|
* VEOL: (libc)Editing Characters.
|
* VERASE: (libc)Editing Characters.
|
* VINTR: (libc)Signal Characters.
|
* VKILL: (libc)Editing Characters.
|
* VLNEXT: (libc)Other Special.
|
* VMIN: (libc)Noncanonical Input.
|
* VQUIT: (libc)Signal Characters.
|
* VREPRINT: (libc)Editing Characters.
|
* VSTART: (libc)Start/Stop Characters.
|
* VSTATUS: (libc)Other Special.
|
* VSTOP: (libc)Start/Stop Characters.
|
* VSUSP: (libc)Signal Characters.
|
* VTIME: (libc)Noncanonical Input.
|
* VWERASE: (libc)Editing Characters.
|
* WCHAR_MAX: (libc)Extended Char Intro.
|
* WCHAR_MIN: (libc)Extended Char Intro.
|
* WCOREDUMP: (libc)Process Completion Status.
|
* WEOF: (libc)EOF and Errors.
|
* WEOF: (libc)Extended Char Intro.
|
* WEXITSTATUS: (libc)Process Completion Status.
|
* WIFEXITED: (libc)Process Completion Status.
|
* WIFSIGNALED: (libc)Process Completion Status.
|
* WIFSTOPPED: (libc)Process Completion Status.
|
* WSTOPSIG: (libc)Process Completion Status.
|
* WTERMSIG: (libc)Process Completion Status.
|
* W_OK: (libc)Testing File Access.
|
* X_OK: (libc)Testing File Access.
|
* _Complex_I: (libc)Complex Numbers.
|
* _Exit: (libc)Termination Internals.
|
* _IOFBF: (libc)Controlling Buffering.
|
* _IOLBF: (libc)Controlling Buffering.
|
* _IONBF: (libc)Controlling Buffering.
|
* _Imaginary_I: (libc)Complex Numbers.
|
* _PATH_UTMP: (libc)Manipulating the Database.
|
* _PATH_WTMP: (libc)Manipulating the Database.
|
* _POSIX2_C_DEV: (libc)System Options.
|
* _POSIX2_C_VERSION: (libc)Version Supported.
|
* _POSIX2_FORT_DEV: (libc)System Options.
|
* _POSIX2_FORT_RUN: (libc)System Options.
|
* _POSIX2_LOCALEDEF: (libc)System Options.
|
* _POSIX2_SW_DEV: (libc)System Options.
|
* _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
|
* _POSIX_JOB_CONTROL: (libc)System Options.
|
* _POSIX_NO_TRUNC: (libc)Options for Files.
|
* _POSIX_SAVED_IDS: (libc)System Options.
|
* _POSIX_VDISABLE: (libc)Options for Files.
|
* _POSIX_VERSION: (libc)Version Supported.
|
* __fbufsize: (libc)Controlling Buffering.
|
* __flbf: (libc)Controlling Buffering.
|
* __fpending: (libc)Controlling Buffering.
|
* __fpurge: (libc)Flushing Buffers.
|
* __freadable: (libc)Opening Streams.
|
* __freading: (libc)Opening Streams.
|
* __fsetlocking: (libc)Streams and Threads.
|
* __fwritable: (libc)Opening Streams.
|
* __fwriting: (libc)Opening Streams.
|
* __gconv_end_fct: (libc)glibc iconv Implementation.
|
* __gconv_fct: (libc)glibc iconv Implementation.
|
* __gconv_init_fct: (libc)glibc iconv Implementation.
|
* __ppc_get_timebase: (libc)PowerPC.
|
* __ppc_get_timebase_freq: (libc)PowerPC.
|
* __ppc_mdoio: (libc)PowerPC.
|
* __ppc_mdoom: (libc)PowerPC.
|
* __ppc_set_ppr_low: (libc)PowerPC.
|
* __ppc_set_ppr_med: (libc)PowerPC.
|
* __ppc_set_ppr_med_high: (libc)PowerPC.
|
* __ppc_set_ppr_med_low: (libc)PowerPC.
|
* __ppc_set_ppr_very_low: (libc)PowerPC.
|
* __ppc_yield: (libc)PowerPC.
|
* __riscv_flush_icache: (libc)RISC-V.
|
* __va_copy: (libc)Argument Macros.
|
* __x86_get_cpuid_feature_leaf: (libc)X86.
|
* _exit: (libc)Termination Internals.
|
* _flushlbf: (libc)Flushing Buffers.
|
* _tolower: (libc)Case Conversion.
|
* _toupper: (libc)Case Conversion.
|
* a64l: (libc)Encode Binary Data.
|
* abort: (libc)Aborting a Program.
|
* abs: (libc)Absolute Value.
|
* accept: (libc)Accepting Connections.
|
* access: (libc)Testing File Access.
|
* acos: (libc)Inverse Trig Functions.
|
* acosf: (libc)Inverse Trig Functions.
|
* acosfN: (libc)Inverse Trig Functions.
|
* acosfNx: (libc)Inverse Trig Functions.
|
* acosh: (libc)Hyperbolic Functions.
|
* acoshf: (libc)Hyperbolic Functions.
|
* acoshfN: (libc)Hyperbolic Functions.
|
* acoshfNx: (libc)Hyperbolic Functions.
|
* acoshl: (libc)Hyperbolic Functions.
|
* acosl: (libc)Inverse Trig Functions.
|
* addmntent: (libc)mtab.
|
* addseverity: (libc)Adding Severity Classes.
|
* adjtime: (libc)Setting and Adjusting the Time.
|
* adjtimex: (libc)Setting and Adjusting the Time.
|
* aio_cancel64: (libc)Cancel AIO Operations.
|
* aio_cancel: (libc)Cancel AIO Operations.
|
* aio_error64: (libc)Status of AIO Operations.
|
* aio_error: (libc)Status of AIO Operations.
|
* aio_fsync64: (libc)Synchronizing AIO Operations.
|
* aio_fsync: (libc)Synchronizing AIO Operations.
|
* aio_init: (libc)Configuration of AIO.
|
* aio_read64: (libc)Asynchronous Reads/Writes.
|
* aio_read: (libc)Asynchronous Reads/Writes.
|
* aio_return64: (libc)Status of AIO Operations.
|
* aio_return: (libc)Status of AIO Operations.
|
* aio_suspend64: (libc)Synchronizing AIO Operations.
|
* aio_suspend: (libc)Synchronizing AIO Operations.
|
* aio_write64: (libc)Asynchronous Reads/Writes.
|
* aio_write: (libc)Asynchronous Reads/Writes.
|
* alarm: (libc)Setting an Alarm.
|
* aligned_alloc: (libc)Aligned Memory Blocks.
|
* alloca: (libc)Variable Size Automatic.
|
* alphasort64: (libc)Scanning Directory Content.
|
* alphasort: (libc)Scanning Directory Content.
|
* argp_error: (libc)Argp Helper Functions.
|
* argp_failure: (libc)Argp Helper Functions.
|
* argp_help: (libc)Argp Help.
|
* argp_parse: (libc)Argp.
|
* argp_state_help: (libc)Argp Helper Functions.
|
* argp_usage: (libc)Argp Helper Functions.
|
* argz_add: (libc)Argz Functions.
|
* argz_add_sep: (libc)Argz Functions.
|
* argz_append: (libc)Argz Functions.
|
* argz_count: (libc)Argz Functions.
|
* argz_create: (libc)Argz Functions.
|
* argz_create_sep: (libc)Argz Functions.
|
* argz_delete: (libc)Argz Functions.
|
* argz_extract: (libc)Argz Functions.
|
* argz_insert: (libc)Argz Functions.
|
* argz_next: (libc)Argz Functions.
|
* argz_replace: (libc)Argz Functions.
|
* argz_stringify: (libc)Argz Functions.
|
* asctime: (libc)Formatting Calendar Time.
|
* asctime_r: (libc)Formatting Calendar Time.
|
* asin: (libc)Inverse Trig Functions.
|
* asinf: (libc)Inverse Trig Functions.
|
* asinfN: (libc)Inverse Trig Functions.
|
* asinfNx: (libc)Inverse Trig Functions.
|
* asinh: (libc)Hyperbolic Functions.
|
* asinhf: (libc)Hyperbolic Functions.
|
* asinhfN: (libc)Hyperbolic Functions.
|
* asinhfNx: (libc)Hyperbolic Functions.
|
* asinhl: (libc)Hyperbolic Functions.
|
* asinl: (libc)Inverse Trig Functions.
|
* asprintf: (libc)Dynamic Output.
|
* assert: (libc)Consistency Checking.
|
* assert_perror: (libc)Consistency Checking.
|
* atan2: (libc)Inverse Trig Functions.
|
* atan2f: (libc)Inverse Trig Functions.
|
* atan2fN: (libc)Inverse Trig Functions.
|
* atan2fNx: (libc)Inverse Trig Functions.
|
* atan2l: (libc)Inverse Trig Functions.
|
* atan: (libc)Inverse Trig Functions.
|
* atanf: (libc)Inverse Trig Functions.
|
* atanfN: (libc)Inverse Trig Functions.
|
* atanfNx: (libc)Inverse Trig Functions.
|
* atanh: (libc)Hyperbolic Functions.
|
* atanhf: (libc)Hyperbolic Functions.
|
* atanhfN: (libc)Hyperbolic Functions.
|
* atanhfNx: (libc)Hyperbolic Functions.
|
* atanhl: (libc)Hyperbolic Functions.
|
* atanl: (libc)Inverse Trig Functions.
|
* atexit: (libc)Cleanups on Exit.
|
* atof: (libc)Parsing of Floats.
|
* atoi: (libc)Parsing of Integers.
|
* atol: (libc)Parsing of Integers.
|
* atoll: (libc)Parsing of Integers.
|
* backtrace: (libc)Backtraces.
|
* backtrace_symbols: (libc)Backtraces.
|
* backtrace_symbols_fd: (libc)Backtraces.
|
* basename: (libc)Finding Tokens in a String.
|
* basename: (libc)Finding Tokens in a String.
|
* bcmp: (libc)String/Array Comparison.
|
* bcopy: (libc)Copying Strings and Arrays.
|
* bind: (libc)Setting Address.
|
* bind_textdomain_codeset: (libc)Charset conversion in gettext.
|
* bindtextdomain: (libc)Locating gettext catalog.
|
* brk: (libc)Resizing the Data Segment.
|
* bsearch: (libc)Array Search Function.
|
* btowc: (libc)Converting a Character.
|
* bzero: (libc)Copying Strings and Arrays.
|
* cabs: (libc)Absolute Value.
|
* cabsf: (libc)Absolute Value.
|
* cabsfN: (libc)Absolute Value.
|
* cabsfNx: (libc)Absolute Value.
|
* cabsl: (libc)Absolute Value.
|
* cacos: (libc)Inverse Trig Functions.
|
* cacosf: (libc)Inverse Trig Functions.
|
* cacosfN: (libc)Inverse Trig Functions.
|
* cacosfNx: (libc)Inverse Trig Functions.
|
* cacosh: (libc)Hyperbolic Functions.
|
* cacoshf: (libc)Hyperbolic Functions.
|
* cacoshfN: (libc)Hyperbolic Functions.
|
* cacoshfNx: (libc)Hyperbolic Functions.
|
* cacoshl: (libc)Hyperbolic Functions.
|
* cacosl: (libc)Inverse Trig Functions.
|
* call_once: (libc)Call Once.
|
* calloc: (libc)Allocating Cleared Space.
|
* canonicalize: (libc)FP Bit Twiddling.
|
* canonicalize_file_name: (libc)Symbolic Links.
|
* canonicalizef: (libc)FP Bit Twiddling.
|
* canonicalizefN: (libc)FP Bit Twiddling.
|
* canonicalizefNx: (libc)FP Bit Twiddling.
|
* canonicalizel: (libc)FP Bit Twiddling.
|
* carg: (libc)Operations on Complex.
|
* cargf: (libc)Operations on Complex.
|
* cargfN: (libc)Operations on Complex.
|
* cargfNx: (libc)Operations on Complex.
|
* cargl: (libc)Operations on Complex.
|
* casin: (libc)Inverse Trig Functions.
|
* casinf: (libc)Inverse Trig Functions.
|
* casinfN: (libc)Inverse Trig Functions.
|
* casinfNx: (libc)Inverse Trig Functions.
|
* casinh: (libc)Hyperbolic Functions.
|
* casinhf: (libc)Hyperbolic Functions.
|
* casinhfN: (libc)Hyperbolic Functions.
|
* casinhfNx: (libc)Hyperbolic Functions.
|
* casinhl: (libc)Hyperbolic Functions.
|
* casinl: (libc)Inverse Trig Functions.
|
* catan: (libc)Inverse Trig Functions.
|
* catanf: (libc)Inverse Trig Functions.
|
* catanfN: (libc)Inverse Trig Functions.
|
* catanfNx: (libc)Inverse Trig Functions.
|
* catanh: (libc)Hyperbolic Functions.
|
* catanhf: (libc)Hyperbolic Functions.
|
* catanhfN: (libc)Hyperbolic Functions.
|
* catanhfNx: (libc)Hyperbolic Functions.
|
* catanhl: (libc)Hyperbolic Functions.
|
* catanl: (libc)Inverse Trig Functions.
|
* catclose: (libc)The catgets Functions.
|
* catgets: (libc)The catgets Functions.
|
* catopen: (libc)The catgets Functions.
|
* cbrt: (libc)Exponents and Logarithms.
|
* cbrtf: (libc)Exponents and Logarithms.
|
* cbrtfN: (libc)Exponents and Logarithms.
|
* cbrtfNx: (libc)Exponents and Logarithms.
|
* cbrtl: (libc)Exponents and Logarithms.
|
* ccos: (libc)Trig Functions.
|
* ccosf: (libc)Trig Functions.
|
* ccosfN: (libc)Trig Functions.
|
* ccosfNx: (libc)Trig Functions.
|
* ccosh: (libc)Hyperbolic Functions.
|
* ccoshf: (libc)Hyperbolic Functions.
|
* ccoshfN: (libc)Hyperbolic Functions.
|
* ccoshfNx: (libc)Hyperbolic Functions.
|
* ccoshl: (libc)Hyperbolic Functions.
|
* ccosl: (libc)Trig Functions.
|
* ceil: (libc)Rounding Functions.
|
* ceilf: (libc)Rounding Functions.
|
* ceilfN: (libc)Rounding Functions.
|
* ceilfNx: (libc)Rounding Functions.
|
* ceill: (libc)Rounding Functions.
|
* cexp: (libc)Exponents and Logarithms.
|
* cexpf: (libc)Exponents and Logarithms.
|
* cexpfN: (libc)Exponents and Logarithms.
|
* cexpfNx: (libc)Exponents and Logarithms.
|
* cexpl: (libc)Exponents and Logarithms.
|
* cfgetispeed: (libc)Line Speed.
|
* cfgetospeed: (libc)Line Speed.
|
* cfmakeraw: (libc)Noncanonical Input.
|
* cfsetispeed: (libc)Line Speed.
|
* cfsetospeed: (libc)Line Speed.
|
* cfsetspeed: (libc)Line Speed.
|
* chdir: (libc)Working Directory.
|
* chmod: (libc)Setting Permissions.
|
* chown: (libc)File Owner.
|
* cimag: (libc)Operations on Complex.
|
* cimagf: (libc)Operations on Complex.
|
* cimagfN: (libc)Operations on Complex.
|
* cimagfNx: (libc)Operations on Complex.
|
* cimagl: (libc)Operations on Complex.
|
* clearenv: (libc)Environment Access.
|
* clearerr: (libc)Error Recovery.
|
* clearerr_unlocked: (libc)Error Recovery.
|
* clock: (libc)CPU Time.
|
* clock_getres: (libc)Getting the Time.
|
* clock_gettime: (libc)Getting the Time.
|
* clock_settime: (libc)Setting and Adjusting the Time.
|
* clog10: (libc)Exponents and Logarithms.
|
* clog10f: (libc)Exponents and Logarithms.
|
* clog10fN: (libc)Exponents and Logarithms.
|
* clog10fNx: (libc)Exponents and Logarithms.
|
* clog10l: (libc)Exponents and Logarithms.
|
* clog: (libc)Exponents and Logarithms.
|
* clogf: (libc)Exponents and Logarithms.
|
* clogfN: (libc)Exponents and Logarithms.
|
* clogfNx: (libc)Exponents and Logarithms.
|
* clogl: (libc)Exponents and Logarithms.
|
* close: (libc)Opening and Closing Files.
|
* closedir: (libc)Reading/Closing Directory.
|
* closelog: (libc)closelog.
|
* cnd_broadcast: (libc)ISO C Condition Variables.
|
* cnd_destroy: (libc)ISO C Condition Variables.
|
* cnd_init: (libc)ISO C Condition Variables.
|
* cnd_signal: (libc)ISO C Condition Variables.
|
* cnd_timedwait: (libc)ISO C Condition Variables.
|
* cnd_wait: (libc)ISO C Condition Variables.
|
* confstr: (libc)String Parameters.
|
* conj: (libc)Operations on Complex.
|
* conjf: (libc)Operations on Complex.
|
* conjfN: (libc)Operations on Complex.
|
* conjfNx: (libc)Operations on Complex.
|
* conjl: (libc)Operations on Complex.
|
* connect: (libc)Connecting.
|
* copy_file_range: (libc)Copying File Data.
|
* copysign: (libc)FP Bit Twiddling.
|
* copysignf: (libc)FP Bit Twiddling.
|
* copysignfN: (libc)FP Bit Twiddling.
|
* copysignfNx: (libc)FP Bit Twiddling.
|
* copysignl: (libc)FP Bit Twiddling.
|
* cos: (libc)Trig Functions.
|
* cosf: (libc)Trig Functions.
|
* cosfN: (libc)Trig Functions.
|
* cosfNx: (libc)Trig Functions.
|
* cosh: (libc)Hyperbolic Functions.
|
* coshf: (libc)Hyperbolic Functions.
|
* coshfN: (libc)Hyperbolic Functions.
|
* coshfNx: (libc)Hyperbolic Functions.
|
* coshl: (libc)Hyperbolic Functions.
|
* cosl: (libc)Trig Functions.
|
* cpow: (libc)Exponents and Logarithms.
|
* cpowf: (libc)Exponents and Logarithms.
|
* cpowfN: (libc)Exponents and Logarithms.
|
* cpowfNx: (libc)Exponents and Logarithms.
|
* cpowl: (libc)Exponents and Logarithms.
|
* cproj: (libc)Operations on Complex.
|
* cprojf: (libc)Operations on Complex.
|
* cprojfN: (libc)Operations on Complex.
|
* cprojfNx: (libc)Operations on Complex.
|
* cprojl: (libc)Operations on Complex.
|
* creal: (libc)Operations on Complex.
|
* crealf: (libc)Operations on Complex.
|
* crealfN: (libc)Operations on Complex.
|
* crealfNx: (libc)Operations on Complex.
|
* creall: (libc)Operations on Complex.
|
* creat64: (libc)Opening and Closing Files.
|
* creat: (libc)Opening and Closing Files.
|
* crypt: (libc)Passphrase Storage.
|
* crypt_r: (libc)Passphrase Storage.
|
* csin: (libc)Trig Functions.
|
* csinf: (libc)Trig Functions.
|
* csinfN: (libc)Trig Functions.
|
* csinfNx: (libc)Trig Functions.
|
* csinh: (libc)Hyperbolic Functions.
|
* csinhf: (libc)Hyperbolic Functions.
|
* csinhfN: (libc)Hyperbolic Functions.
|
* csinhfNx: (libc)Hyperbolic Functions.
|
* csinhl: (libc)Hyperbolic Functions.
|
* csinl: (libc)Trig Functions.
|
* csqrt: (libc)Exponents and Logarithms.
|
* csqrtf: (libc)Exponents and Logarithms.
|
* csqrtfN: (libc)Exponents and Logarithms.
|
* csqrtfNx: (libc)Exponents and Logarithms.
|
* csqrtl: (libc)Exponents and Logarithms.
|
* ctan: (libc)Trig Functions.
|
* ctanf: (libc)Trig Functions.
|
* ctanfN: (libc)Trig Functions.
|
* ctanfNx: (libc)Trig Functions.
|
* ctanh: (libc)Hyperbolic Functions.
|
* ctanhf: (libc)Hyperbolic Functions.
|
* ctanhfN: (libc)Hyperbolic Functions.
|
* ctanhfNx: (libc)Hyperbolic Functions.
|
* ctanhl: (libc)Hyperbolic Functions.
|
* ctanl: (libc)Trig Functions.
|
* ctermid: (libc)Identifying the Terminal.
|
* ctime: (libc)Formatting Calendar Time.
|
* ctime_r: (libc)Formatting Calendar Time.
|
* cuserid: (libc)Who Logged In.
|
* daddl: (libc)Misc FP Arithmetic.
|
* dcgettext: (libc)Translation with gettext.
|
* dcngettext: (libc)Advanced gettext functions.
|
* ddivl: (libc)Misc FP Arithmetic.
|
* dgettext: (libc)Translation with gettext.
|
* difftime: (libc)Calculating Elapsed Time.
|
* dirfd: (libc)Opening a Directory.
|
* dirname: (libc)Finding Tokens in a String.
|
* div: (libc)Integer Division.
|
* dmull: (libc)Misc FP Arithmetic.
|
* dngettext: (libc)Advanced gettext functions.
|
* drand48: (libc)SVID Random.
|
* drand48_r: (libc)SVID Random.
|
* drem: (libc)Remainder Functions.
|
* dremf: (libc)Remainder Functions.
|
* dreml: (libc)Remainder Functions.
|
* dsubl: (libc)Misc FP Arithmetic.
|
* dup2: (libc)Duplicating Descriptors.
|
* dup: (libc)Duplicating Descriptors.
|
* ecvt: (libc)System V Number Conversion.
|
* ecvt_r: (libc)System V Number Conversion.
|
* endfsent: (libc)fstab.
|
* endgrent: (libc)Scanning All Groups.
|
* endhostent: (libc)Host Names.
|
* endmntent: (libc)mtab.
|
* endnetent: (libc)Networks Database.
|
* endnetgrent: (libc)Lookup Netgroup.
|
* endprotoent: (libc)Protocols Database.
|
* endpwent: (libc)Scanning All Users.
|
* endservent: (libc)Services Database.
|
* endutent: (libc)Manipulating the Database.
|
* endutxent: (libc)XPG Functions.
|
* envz_add: (libc)Envz Functions.
|
* envz_entry: (libc)Envz Functions.
|
* envz_get: (libc)Envz Functions.
|
* envz_merge: (libc)Envz Functions.
|
* envz_remove: (libc)Envz Functions.
|
* envz_strip: (libc)Envz Functions.
|
* erand48: (libc)SVID Random.
|
* erand48_r: (libc)SVID Random.
|
* erf: (libc)Special Functions.
|
* erfc: (libc)Special Functions.
|
* erfcf: (libc)Special Functions.
|
* erfcfN: (libc)Special Functions.
|
* erfcfNx: (libc)Special Functions.
|
* erfcl: (libc)Special Functions.
|
* erff: (libc)Special Functions.
|
* erffN: (libc)Special Functions.
|
* erffNx: (libc)Special Functions.
|
* erfl: (libc)Special Functions.
|
* err: (libc)Error Messages.
|
* errno: (libc)Checking for Errors.
|
* error: (libc)Error Messages.
|
* error_at_line: (libc)Error Messages.
|
* errx: (libc)Error Messages.
|
* execl: (libc)Executing a File.
|
* execle: (libc)Executing a File.
|
* execlp: (libc)Executing a File.
|
* execv: (libc)Executing a File.
|
* execve: (libc)Executing a File.
|
* execvp: (libc)Executing a File.
|
* exit: (libc)Normal Termination.
|
* exp10: (libc)Exponents and Logarithms.
|
* exp10f: (libc)Exponents and Logarithms.
|
* exp10fN: (libc)Exponents and Logarithms.
|
* exp10fNx: (libc)Exponents and Logarithms.
|
* exp10l: (libc)Exponents and Logarithms.
|
* exp2: (libc)Exponents and Logarithms.
|
* exp2f: (libc)Exponents and Logarithms.
|
* exp2fN: (libc)Exponents and Logarithms.
|
* exp2fNx: (libc)Exponents and Logarithms.
|
* exp2l: (libc)Exponents and Logarithms.
|
* exp: (libc)Exponents and Logarithms.
|
* expf: (libc)Exponents and Logarithms.
|
* expfN: (libc)Exponents and Logarithms.
|
* expfNx: (libc)Exponents and Logarithms.
|
* expl: (libc)Exponents and Logarithms.
|
* explicit_bzero: (libc)Erasing Sensitive Data.
|
* expm1: (libc)Exponents and Logarithms.
|
* expm1f: (libc)Exponents and Logarithms.
|
* expm1fN: (libc)Exponents and Logarithms.
|
* expm1fNx: (libc)Exponents and Logarithms.
|
* expm1l: (libc)Exponents and Logarithms.
|
* fMaddfN: (libc)Misc FP Arithmetic.
|
* fMaddfNx: (libc)Misc FP Arithmetic.
|
* fMdivfN: (libc)Misc FP Arithmetic.
|
* fMdivfNx: (libc)Misc FP Arithmetic.
|
* fMmulfN: (libc)Misc FP Arithmetic.
|
* fMmulfNx: (libc)Misc FP Arithmetic.
|
* fMsubfN: (libc)Misc FP Arithmetic.
|
* fMsubfNx: (libc)Misc FP Arithmetic.
|
* fMxaddfN: (libc)Misc FP Arithmetic.
|
* fMxaddfNx: (libc)Misc FP Arithmetic.
|
* fMxdivfN: (libc)Misc FP Arithmetic.
|
* fMxdivfNx: (libc)Misc FP Arithmetic.
|
* fMxmulfN: (libc)Misc FP Arithmetic.
|
* fMxmulfNx: (libc)Misc FP Arithmetic.
|
* fMxsubfN: (libc)Misc FP Arithmetic.
|
* fMxsubfNx: (libc)Misc FP Arithmetic.
|
* fabs: (libc)Absolute Value.
|
* fabsf: (libc)Absolute Value.
|
* fabsfN: (libc)Absolute Value.
|
* fabsfNx: (libc)Absolute Value.
|
* fabsl: (libc)Absolute Value.
|
* fadd: (libc)Misc FP Arithmetic.
|
* faddl: (libc)Misc FP Arithmetic.
|
* fchdir: (libc)Working Directory.
|
* fchmod: (libc)Setting Permissions.
|
* fchown: (libc)File Owner.
|
* fclose: (libc)Closing Streams.
|
* fcloseall: (libc)Closing Streams.
|
* fcntl: (libc)Control Operations.
|
* fcvt: (libc)System V Number Conversion.
|
* fcvt_r: (libc)System V Number Conversion.
|
* fdatasync: (libc)Synchronizing I/O.
|
* fdim: (libc)Misc FP Arithmetic.
|
* fdimf: (libc)Misc FP Arithmetic.
|
* fdimfN: (libc)Misc FP Arithmetic.
|
* fdimfNx: (libc)Misc FP Arithmetic.
|
* fdiml: (libc)Misc FP Arithmetic.
|
* fdiv: (libc)Misc FP Arithmetic.
|
* fdivl: (libc)Misc FP Arithmetic.
|
* fdopen: (libc)Descriptors and Streams.
|
* fdopendir: (libc)Opening a Directory.
|
* feclearexcept: (libc)Status bit operations.
|
* fedisableexcept: (libc)Control Functions.
|
* feenableexcept: (libc)Control Functions.
|
* fegetenv: (libc)Control Functions.
|
* fegetexcept: (libc)Control Functions.
|
* fegetexceptflag: (libc)Status bit operations.
|
* fegetmode: (libc)Control Functions.
|
* fegetround: (libc)Rounding.
|
* feholdexcept: (libc)Control Functions.
|
* feof: (libc)EOF and Errors.
|
* feof_unlocked: (libc)EOF and Errors.
|
* feraiseexcept: (libc)Status bit operations.
|
* ferror: (libc)EOF and Errors.
|
* ferror_unlocked: (libc)EOF and Errors.
|
* fesetenv: (libc)Control Functions.
|
* fesetexcept: (libc)Status bit operations.
|
* fesetexceptflag: (libc)Status bit operations.
|
* fesetmode: (libc)Control Functions.
|
* fesetround: (libc)Rounding.
|
* fetestexcept: (libc)Status bit operations.
|
* fetestexceptflag: (libc)Status bit operations.
|
* feupdateenv: (libc)Control Functions.
|
* fexecve: (libc)Executing a File.
|
* fflush: (libc)Flushing Buffers.
|
* fflush_unlocked: (libc)Flushing Buffers.
|
* fgetc: (libc)Character Input.
|
* fgetc_unlocked: (libc)Character Input.
|
* fgetgrent: (libc)Scanning All Groups.
|
* fgetgrent_r: (libc)Scanning All Groups.
|
* fgetpos64: (libc)Portable Positioning.
|
* fgetpos: (libc)Portable Positioning.
|
* fgetpwent: (libc)Scanning All Users.
|
* fgetpwent_r: (libc)Scanning All Users.
|
* fgets: (libc)Line Input.
|
* fgets_unlocked: (libc)Line Input.
|
* fgetwc: (libc)Character Input.
|
* fgetwc_unlocked: (libc)Character Input.
|
* fgetws: (libc)Line Input.
|
* fgetws_unlocked: (libc)Line Input.
|
* fileno: (libc)Descriptors and Streams.
|
* fileno_unlocked: (libc)Descriptors and Streams.
|
* finite: (libc)Floating Point Classes.
|
* finitef: (libc)Floating Point Classes.
|
* finitel: (libc)Floating Point Classes.
|
* flockfile: (libc)Streams and Threads.
|
* floor: (libc)Rounding Functions.
|
* floorf: (libc)Rounding Functions.
|
* floorfN: (libc)Rounding Functions.
|
* floorfNx: (libc)Rounding Functions.
|
* floorl: (libc)Rounding Functions.
|
* fma: (libc)Misc FP Arithmetic.
|
* fmaf: (libc)Misc FP Arithmetic.
|
* fmafN: (libc)Misc FP Arithmetic.
|
* fmafNx: (libc)Misc FP Arithmetic.
|
* fmal: (libc)Misc FP Arithmetic.
|
* fmax: (libc)Misc FP Arithmetic.
|
* fmaxf: (libc)Misc FP Arithmetic.
|
* fmaxfN: (libc)Misc FP Arithmetic.
|
* fmaxfNx: (libc)Misc FP Arithmetic.
|
* fmaxl: (libc)Misc FP Arithmetic.
|
* fmaxmag: (libc)Misc FP Arithmetic.
|
* fmaxmagf: (libc)Misc FP Arithmetic.
|
* fmaxmagfN: (libc)Misc FP Arithmetic.
|
* fmaxmagfNx: (libc)Misc FP Arithmetic.
|
* fmaxmagl: (libc)Misc FP Arithmetic.
|
* fmemopen: (libc)String Streams.
|
* fmin: (libc)Misc FP Arithmetic.
|
* fminf: (libc)Misc FP Arithmetic.
|
* fminfN: (libc)Misc FP Arithmetic.
|
* fminfNx: (libc)Misc FP Arithmetic.
|
* fminl: (libc)Misc FP Arithmetic.
|
* fminmag: (libc)Misc FP Arithmetic.
|
* fminmagf: (libc)Misc FP Arithmetic.
|
* fminmagfN: (libc)Misc FP Arithmetic.
|
* fminmagfNx: (libc)Misc FP Arithmetic.
|
* fminmagl: (libc)Misc FP Arithmetic.
|
* fmod: (libc)Remainder Functions.
|
* fmodf: (libc)Remainder Functions.
|
* fmodfN: (libc)Remainder Functions.
|
* fmodfNx: (libc)Remainder Functions.
|
* fmodl: (libc)Remainder Functions.
|
* fmtmsg: (libc)Printing Formatted Messages.
|
* fmul: (libc)Misc FP Arithmetic.
|
* fmull: (libc)Misc FP Arithmetic.
|
* fnmatch: (libc)Wildcard Matching.
|
* fopen64: (libc)Opening Streams.
|
* fopen: (libc)Opening Streams.
|
* fopencookie: (libc)Streams and Cookies.
|
* fork: (libc)Creating a Process.
|
* forkpty: (libc)Pseudo-Terminal Pairs.
|
* fpathconf: (libc)Pathconf.
|
* fpclassify: (libc)Floating Point Classes.
|
* fprintf: (libc)Formatted Output Functions.
|
* fputc: (libc)Simple Output.
|
* fputc_unlocked: (libc)Simple Output.
|
* fputs: (libc)Simple Output.
|
* fputs_unlocked: (libc)Simple Output.
|
* fputwc: (libc)Simple Output.
|
* fputwc_unlocked: (libc)Simple Output.
|
* fputws: (libc)Simple Output.
|
* fputws_unlocked: (libc)Simple Output.
|
* fread: (libc)Block Input/Output.
|
* fread_unlocked: (libc)Block Input/Output.
|
* free: (libc)Freeing after Malloc.
|
* freopen64: (libc)Opening Streams.
|
* freopen: (libc)Opening Streams.
|
* frexp: (libc)Normalization Functions.
|
* frexpf: (libc)Normalization Functions.
|
* frexpfN: (libc)Normalization Functions.
|
* frexpfNx: (libc)Normalization Functions.
|
* frexpl: (libc)Normalization Functions.
|
* fromfp: (libc)Rounding Functions.
|
* fromfpf: (libc)Rounding Functions.
|
* fromfpfN: (libc)Rounding Functions.
|
* fromfpfNx: (libc)Rounding Functions.
|
* fromfpl: (libc)Rounding Functions.
|
* fromfpx: (libc)Rounding Functions.
|
* fromfpxf: (libc)Rounding Functions.
|
* fromfpxfN: (libc)Rounding Functions.
|
* fromfpxfNx: (libc)Rounding Functions.
|
* fromfpxl: (libc)Rounding Functions.
|
* fscanf: (libc)Formatted Input Functions.
|
* fseek: (libc)File Positioning.
|
* fseeko64: (libc)File Positioning.
|
* fseeko: (libc)File Positioning.
|
* fsetpos64: (libc)Portable Positioning.
|
* fsetpos: (libc)Portable Positioning.
|
* fstat64: (libc)Reading Attributes.
|
* fstat: (libc)Reading Attributes.
|
* fsub: (libc)Misc FP Arithmetic.
|
* fsubl: (libc)Misc FP Arithmetic.
|
* fsync: (libc)Synchronizing I/O.
|
* ftell: (libc)File Positioning.
|
* ftello64: (libc)File Positioning.
|
* ftello: (libc)File Positioning.
|
* ftruncate64: (libc)File Size.
|
* ftruncate: (libc)File Size.
|
* ftrylockfile: (libc)Streams and Threads.
|
* ftw64: (libc)Working with Directory Trees.
|
* ftw: (libc)Working with Directory Trees.
|
* funlockfile: (libc)Streams and Threads.
|
* futimes: (libc)File Times.
|
* fwide: (libc)Streams and I18N.
|
* fwprintf: (libc)Formatted Output Functions.
|
* fwrite: (libc)Block Input/Output.
|
* fwrite_unlocked: (libc)Block Input/Output.
|
* fwscanf: (libc)Formatted Input Functions.
|
* gamma: (libc)Special Functions.
|
* gammaf: (libc)Special Functions.
|
* gammal: (libc)Special Functions.
|
* gcvt: (libc)System V Number Conversion.
|
* get_avphys_pages: (libc)Query Memory Parameters.
|
* get_current_dir_name: (libc)Working Directory.
|
* get_nprocs: (libc)Processor Resources.
|
* get_nprocs_conf: (libc)Processor Resources.
|
* get_phys_pages: (libc)Query Memory Parameters.
|
* getauxval: (libc)Auxiliary Vector.
|
* getc: (libc)Character Input.
|
* getc_unlocked: (libc)Character Input.
|
* getchar: (libc)Character Input.
|
* getchar_unlocked: (libc)Character Input.
|
* getcontext: (libc)System V contexts.
|
* getcpu: (libc)CPU Affinity.
|
* getcwd: (libc)Working Directory.
|
* getdate: (libc)General Time String Parsing.
|
* getdate_r: (libc)General Time String Parsing.
|
* getdelim: (libc)Line Input.
|
* getdents64: (libc)Low-level Directory Access.
|
* getdomainnname: (libc)Host Identification.
|
* getegid: (libc)Reading Persona.
|
* getentropy: (libc)Unpredictable Bytes.
|
* getenv: (libc)Environment Access.
|
* geteuid: (libc)Reading Persona.
|
* getfsent: (libc)fstab.
|
* getfsfile: (libc)fstab.
|
* getfsspec: (libc)fstab.
|
* getgid: (libc)Reading Persona.
|
* getgrent: (libc)Scanning All Groups.
|
* getgrent_r: (libc)Scanning All Groups.
|
* getgrgid: (libc)Lookup Group.
|
* getgrgid_r: (libc)Lookup Group.
|
* getgrnam: (libc)Lookup Group.
|
* getgrnam_r: (libc)Lookup Group.
|
* getgrouplist: (libc)Setting Groups.
|
* getgroups: (libc)Reading Persona.
|
* gethostbyaddr: (libc)Host Names.
|
* gethostbyaddr_r: (libc)Host Names.
|
* gethostbyname2: (libc)Host Names.
|
* gethostbyname2_r: (libc)Host Names.
|
* gethostbyname: (libc)Host Names.
|
* gethostbyname_r: (libc)Host Names.
|
* gethostent: (libc)Host Names.
|
* gethostid: (libc)Host Identification.
|
* gethostname: (libc)Host Identification.
|
* getitimer: (libc)Setting an Alarm.
|
* getline: (libc)Line Input.
|
* getloadavg: (libc)Processor Resources.
|
* getlogin: (libc)Who Logged In.
|
* getmntent: (libc)mtab.
|
* getmntent_r: (libc)mtab.
|
* getnetbyaddr: (libc)Networks Database.
|
* getnetbyname: (libc)Networks Database.
|
* getnetent: (libc)Networks Database.
|
* getnetgrent: (libc)Lookup Netgroup.
|
* getnetgrent_r: (libc)Lookup Netgroup.
|
* getopt: (libc)Using Getopt.
|
* getopt_long: (libc)Getopt Long Options.
|
* getopt_long_only: (libc)Getopt Long Options.
|
* getpagesize: (libc)Query Memory Parameters.
|
* getpass: (libc)getpass.
|
* getpayload: (libc)FP Bit Twiddling.
|
* getpayloadf: (libc)FP Bit Twiddling.
|
* getpayloadfN: (libc)FP Bit Twiddling.
|
* getpayloadfNx: (libc)FP Bit Twiddling.
|
* getpayloadl: (libc)FP Bit Twiddling.
|
* getpeername: (libc)Who is Connected.
|
* getpgid: (libc)Process Group Functions.
|
* getpgrp: (libc)Process Group Functions.
|
* getpid: (libc)Process Identification.
|
* getppid: (libc)Process Identification.
|
* getpriority: (libc)Traditional Scheduling Functions.
|
* getprotobyname: (libc)Protocols Database.
|
* getprotobynumber: (libc)Protocols Database.
|
* getprotoent: (libc)Protocols Database.
|
* getpt: (libc)Allocation.
|
* getpwent: (libc)Scanning All Users.
|
* getpwent_r: (libc)Scanning All Users.
|
* getpwnam: (libc)Lookup User.
|
* getpwnam_r: (libc)Lookup User.
|
* getpwuid: (libc)Lookup User.
|
* getpwuid_r: (libc)Lookup User.
|
* getrandom: (libc)Unpredictable Bytes.
|
* getrlimit64: (libc)Limits on Resources.
|
* getrlimit: (libc)Limits on Resources.
|
* getrusage: (libc)Resource Usage.
|
* gets: (libc)Line Input.
|
* getservbyname: (libc)Services Database.
|
* getservbyport: (libc)Services Database.
|
* getservent: (libc)Services Database.
|
* getsid: (libc)Process Group Functions.
|
* getsockname: (libc)Reading Address.
|
* getsockopt: (libc)Socket Option Functions.
|
* getsubopt: (libc)Suboptions.
|
* gettext: (libc)Translation with gettext.
|
* gettid: (libc)Process Identification.
|
* gettimeofday: (libc)Getting the Time.
|
* getuid: (libc)Reading Persona.
|
* getumask: (libc)Setting Permissions.
|
* getutent: (libc)Manipulating the Database.
|
* getutent_r: (libc)Manipulating the Database.
|
* getutid: (libc)Manipulating the Database.
|
* getutid_r: (libc)Manipulating the Database.
|
* getutline: (libc)Manipulating the Database.
|
* getutline_r: (libc)Manipulating the Database.
|
* getutmp: (libc)XPG Functions.
|
* getutmpx: (libc)XPG Functions.
|
* getutxent: (libc)XPG Functions.
|
* getutxid: (libc)XPG Functions.
|
* getutxline: (libc)XPG Functions.
|
* getw: (libc)Character Input.
|
* getwc: (libc)Character Input.
|
* getwc_unlocked: (libc)Character Input.
|
* getwchar: (libc)Character Input.
|
* getwchar_unlocked: (libc)Character Input.
|
* getwd: (libc)Working Directory.
|
* glob64: (libc)Calling Glob.
|
* glob: (libc)Calling Glob.
|
* globfree64: (libc)More Flags for Globbing.
|
* globfree: (libc)More Flags for Globbing.
|
* gmtime: (libc)Broken-down Time.
|
* gmtime_r: (libc)Broken-down Time.
|
* grantpt: (libc)Allocation.
|
* gsignal: (libc)Signaling Yourself.
|
* gtty: (libc)BSD Terminal Modes.
|
* hasmntopt: (libc)mtab.
|
* hcreate: (libc)Hash Search Function.
|
* hcreate_r: (libc)Hash Search Function.
|
* hdestroy: (libc)Hash Search Function.
|
* hdestroy_r: (libc)Hash Search Function.
|
* hsearch: (libc)Hash Search Function.
|
* hsearch_r: (libc)Hash Search Function.
|
* htonl: (libc)Byte Order.
|
* htons: (libc)Byte Order.
|
* hypot: (libc)Exponents and Logarithms.
|
* hypotf: (libc)Exponents and Logarithms.
|
* hypotfN: (libc)Exponents and Logarithms.
|
* hypotfNx: (libc)Exponents and Logarithms.
|
* hypotl: (libc)Exponents and Logarithms.
|
* iconv: (libc)Generic Conversion Interface.
|
* iconv_close: (libc)Generic Conversion Interface.
|
* iconv_open: (libc)Generic Conversion Interface.
|
* if_freenameindex: (libc)Interface Naming.
|
* if_indextoname: (libc)Interface Naming.
|
* if_nameindex: (libc)Interface Naming.
|
* if_nametoindex: (libc)Interface Naming.
|
* ilogb: (libc)Exponents and Logarithms.
|
* ilogbf: (libc)Exponents and Logarithms.
|
* ilogbfN: (libc)Exponents and Logarithms.
|
* ilogbfNx: (libc)Exponents and Logarithms.
|
* ilogbl: (libc)Exponents and Logarithms.
|
* imaxabs: (libc)Absolute Value.
|
* imaxdiv: (libc)Integer Division.
|
* in6addr_any: (libc)Host Address Data Type.
|
* in6addr_loopback: (libc)Host Address Data Type.
|
* index: (libc)Search Functions.
|
* inet_addr: (libc)Host Address Functions.
|
* inet_aton: (libc)Host Address Functions.
|
* inet_lnaof: (libc)Host Address Functions.
|
* inet_makeaddr: (libc)Host Address Functions.
|
* inet_netof: (libc)Host Address Functions.
|
* inet_network: (libc)Host Address Functions.
|
* inet_ntoa: (libc)Host Address Functions.
|
* inet_ntop: (libc)Host Address Functions.
|
* inet_pton: (libc)Host Address Functions.
|
* initgroups: (libc)Setting Groups.
|
* initstate: (libc)BSD Random.
|
* initstate_r: (libc)BSD Random.
|
* innetgr: (libc)Netgroup Membership.
|
* ioctl: (libc)IOCTLs.
|
* isalnum: (libc)Classification of Characters.
|
* isalpha: (libc)Classification of Characters.
|
* isascii: (libc)Classification of Characters.
|
* isatty: (libc)Is It a Terminal.
|
* isblank: (libc)Classification of Characters.
|
* iscanonical: (libc)Floating Point Classes.
|
* iscntrl: (libc)Classification of Characters.
|
* isdigit: (libc)Classification of Characters.
|
* iseqsig: (libc)FP Comparison Functions.
|
* isfinite: (libc)Floating Point Classes.
|
* isgraph: (libc)Classification of Characters.
|
* isgreater: (libc)FP Comparison Functions.
|
* isgreaterequal: (libc)FP Comparison Functions.
|
* isinf: (libc)Floating Point Classes.
|
* isinff: (libc)Floating Point Classes.
|
* isinfl: (libc)Floating Point Classes.
|
* isless: (libc)FP Comparison Functions.
|
* islessequal: (libc)FP Comparison Functions.
|
* islessgreater: (libc)FP Comparison Functions.
|
* islower: (libc)Classification of Characters.
|
* isnan: (libc)Floating Point Classes.
|
* isnan: (libc)Floating Point Classes.
|
* isnanf: (libc)Floating Point Classes.
|
* isnanl: (libc)Floating Point Classes.
|
* isnormal: (libc)Floating Point Classes.
|
* isprint: (libc)Classification of Characters.
|
* ispunct: (libc)Classification of Characters.
|
* issignaling: (libc)Floating Point Classes.
|
* isspace: (libc)Classification of Characters.
|
* issubnormal: (libc)Floating Point Classes.
|
* isunordered: (libc)FP Comparison Functions.
|
* isupper: (libc)Classification of Characters.
|
* iswalnum: (libc)Classification of Wide Characters.
|
* iswalpha: (libc)Classification of Wide Characters.
|
* iswblank: (libc)Classification of Wide Characters.
|
* iswcntrl: (libc)Classification of Wide Characters.
|
* iswctype: (libc)Classification of Wide Characters.
|
* iswdigit: (libc)Classification of Wide Characters.
|
* iswgraph: (libc)Classification of Wide Characters.
|
* iswlower: (libc)Classification of Wide Characters.
|
* iswprint: (libc)Classification of Wide Characters.
|
* iswpunct: (libc)Classification of Wide Characters.
|
* iswspace: (libc)Classification of Wide Characters.
|
* iswupper: (libc)Classification of Wide Characters.
|
* iswxdigit: (libc)Classification of Wide Characters.
|
* isxdigit: (libc)Classification of Characters.
|
* iszero: (libc)Floating Point Classes.
|
* j0: (libc)Special Functions.
|
* j0f: (libc)Special Functions.
|
* j0fN: (libc)Special Functions.
|
* j0fNx: (libc)Special Functions.
|
* j0l: (libc)Special Functions.
|
* j1: (libc)Special Functions.
|
* j1f: (libc)Special Functions.
|
* j1fN: (libc)Special Functions.
|
* j1fNx: (libc)Special Functions.
|
* j1l: (libc)Special Functions.
|
* jn: (libc)Special Functions.
|
* jnf: (libc)Special Functions.
|
* jnfN: (libc)Special Functions.
|
* jnfNx: (libc)Special Functions.
|
* jnl: (libc)Special Functions.
|
* jrand48: (libc)SVID Random.
|
* jrand48_r: (libc)SVID Random.
|
* kill: (libc)Signaling Another Process.
|
* killpg: (libc)Signaling Another Process.
|
* l64a: (libc)Encode Binary Data.
|
* labs: (libc)Absolute Value.
|
* lcong48: (libc)SVID Random.
|
* lcong48_r: (libc)SVID Random.
|
* ldexp: (libc)Normalization Functions.
|
* ldexpf: (libc)Normalization Functions.
|
* ldexpfN: (libc)Normalization Functions.
|
* ldexpfNx: (libc)Normalization Functions.
|
* ldexpl: (libc)Normalization Functions.
|
* ldiv: (libc)Integer Division.
|
* lfind: (libc)Array Search Function.
|
* lgamma: (libc)Special Functions.
|
* lgamma_r: (libc)Special Functions.
|
* lgammaf: (libc)Special Functions.
|
* lgammafN: (libc)Special Functions.
|
* lgammafN_r: (libc)Special Functions.
|
* lgammafNx: (libc)Special Functions.
|
* lgammafNx_r: (libc)Special Functions.
|
* lgammaf_r: (libc)Special Functions.
|
* lgammal: (libc)Special Functions.
|
* lgammal_r: (libc)Special Functions.
|
* link: (libc)Hard Links.
|
* linkat: (libc)Hard Links.
|
* lio_listio64: (libc)Asynchronous Reads/Writes.
|
* lio_listio: (libc)Asynchronous Reads/Writes.
|
* listen: (libc)Listening.
|
* llabs: (libc)Absolute Value.
|
* lldiv: (libc)Integer Division.
|
* llogb: (libc)Exponents and Logarithms.
|
* llogbf: (libc)Exponents and Logarithms.
|
* llogbfN: (libc)Exponents and Logarithms.
|
* llogbfNx: (libc)Exponents and Logarithms.
|
* llogbl: (libc)Exponents and Logarithms.
|
* llrint: (libc)Rounding Functions.
|
* llrintf: (libc)Rounding Functions.
|
* llrintfN: (libc)Rounding Functions.
|
* llrintfNx: (libc)Rounding Functions.
|
* llrintl: (libc)Rounding Functions.
|
* llround: (libc)Rounding Functions.
|
* llroundf: (libc)Rounding Functions.
|
* llroundfN: (libc)Rounding Functions.
|
* llroundfNx: (libc)Rounding Functions.
|
* llroundl: (libc)Rounding Functions.
|
* localeconv: (libc)The Lame Way to Locale Data.
|
* localtime: (libc)Broken-down Time.
|
* localtime_r: (libc)Broken-down Time.
|
* log10: (libc)Exponents and Logarithms.
|
* log10f: (libc)Exponents and Logarithms.
|
* log10fN: (libc)Exponents and Logarithms.
|
* log10fNx: (libc)Exponents and Logarithms.
|
* log10l: (libc)Exponents and Logarithms.
|
* log1p: (libc)Exponents and Logarithms.
|
* log1pf: (libc)Exponents and Logarithms.
|
* log1pfN: (libc)Exponents and Logarithms.
|
* log1pfNx: (libc)Exponents and Logarithms.
|
* log1pl: (libc)Exponents and Logarithms.
|
* log2: (libc)Exponents and Logarithms.
|
* log2f: (libc)Exponents and Logarithms.
|
* log2fN: (libc)Exponents and Logarithms.
|
* log2fNx: (libc)Exponents and Logarithms.
|
* log2l: (libc)Exponents and Logarithms.
|
* log: (libc)Exponents and Logarithms.
|
* logb: (libc)Exponents and Logarithms.
|
* logbf: (libc)Exponents and Logarithms.
|
* logbfN: (libc)Exponents and Logarithms.
|
* logbfNx: (libc)Exponents and Logarithms.
|
* logbl: (libc)Exponents and Logarithms.
|
* logf: (libc)Exponents and Logarithms.
|
* logfN: (libc)Exponents and Logarithms.
|
* logfNx: (libc)Exponents and Logarithms.
|
* login: (libc)Logging In and Out.
|
* login_tty: (libc)Logging In and Out.
|
* logl: (libc)Exponents and Logarithms.
|
* logout: (libc)Logging In and Out.
|
* logwtmp: (libc)Logging In and Out.
|
* longjmp: (libc)Non-Local Details.
|
* lrand48: (libc)SVID Random.
|
* lrand48_r: (libc)SVID Random.
|
* lrint: (libc)Rounding Functions.
|
* lrintf: (libc)Rounding Functions.
|
* lrintfN: (libc)Rounding Functions.
|
* lrintfNx: (libc)Rounding Functions.
|
* lrintl: (libc)Rounding Functions.
|
* lround: (libc)Rounding Functions.
|
* lroundf: (libc)Rounding Functions.
|
* lroundfN: (libc)Rounding Functions.
|
* lroundfNx: (libc)Rounding Functions.
|
* lroundl: (libc)Rounding Functions.
|
* lsearch: (libc)Array Search Function.
|
* lseek64: (libc)File Position Primitive.
|
* lseek: (libc)File Position Primitive.
|
* lstat64: (libc)Reading Attributes.
|
* lstat: (libc)Reading Attributes.
|
* lutimes: (libc)File Times.
|
* madvise: (libc)Memory-mapped I/O.
|
* makecontext: (libc)System V contexts.
|
* mallinfo2: (libc)Statistics of Malloc.
|
* malloc: (libc)Basic Allocation.
|
* mallopt: (libc)Malloc Tunable Parameters.
|
* mblen: (libc)Non-reentrant Character Conversion.
|
* mbrlen: (libc)Converting a Character.
|
* mbrtowc: (libc)Converting a Character.
|
* mbsinit: (libc)Keeping the state.
|
* mbsnrtowcs: (libc)Converting Strings.
|
* mbsrtowcs: (libc)Converting Strings.
|
* mbstowcs: (libc)Non-reentrant String Conversion.
|
* mbtowc: (libc)Non-reentrant Character Conversion.
|
* mcheck: (libc)Heap Consistency Checking.
|
* memalign: (libc)Aligned Memory Blocks.
|
* memccpy: (libc)Copying Strings and Arrays.
|
* memchr: (libc)Search Functions.
|
* memcmp: (libc)String/Array Comparison.
|
* memcpy: (libc)Copying Strings and Arrays.
|
* memfd_create: (libc)Memory-mapped I/O.
|
* memfrob: (libc)Obfuscating Data.
|
* memmem: (libc)Search Functions.
|
* memmove: (libc)Copying Strings and Arrays.
|
* mempcpy: (libc)Copying Strings and Arrays.
|
* memrchr: (libc)Search Functions.
|
* memset: (libc)Copying Strings and Arrays.
|
* mkdir: (libc)Creating Directories.
|
* mkdtemp: (libc)Temporary Files.
|
* mkfifo: (libc)FIFO Special Files.
|
* mknod: (libc)Making Special Files.
|
* mkstemp: (libc)Temporary Files.
|
* mktemp: (libc)Temporary Files.
|
* mktime: (libc)Broken-down Time.
|
* mlock2: (libc)Page Lock Functions.
|
* mlock: (libc)Page Lock Functions.
|
* mlockall: (libc)Page Lock Functions.
|
* mmap64: (libc)Memory-mapped I/O.
|
* mmap: (libc)Memory-mapped I/O.
|
* modf: (libc)Rounding Functions.
|
* modff: (libc)Rounding Functions.
|
* modffN: (libc)Rounding Functions.
|
* modffNx: (libc)Rounding Functions.
|
* modfl: (libc)Rounding Functions.
|
* mount: (libc)Mount-Unmount-Remount.
|
* mprobe: (libc)Heap Consistency Checking.
|
* mprotect: (libc)Memory Protection.
|
* mrand48: (libc)SVID Random.
|
* mrand48_r: (libc)SVID Random.
|
* mremap: (libc)Memory-mapped I/O.
|
* msync: (libc)Memory-mapped I/O.
|
* mtrace: (libc)Tracing malloc.
|
* mtx_destroy: (libc)ISO C Mutexes.
|
* mtx_init: (libc)ISO C Mutexes.
|
* mtx_lock: (libc)ISO C Mutexes.
|
* mtx_timedlock: (libc)ISO C Mutexes.
|
* mtx_trylock: (libc)ISO C Mutexes.
|
* mtx_unlock: (libc)ISO C Mutexes.
|
* munlock: (libc)Page Lock Functions.
|
* munlockall: (libc)Page Lock Functions.
|
* munmap: (libc)Memory-mapped I/O.
|
* muntrace: (libc)Tracing malloc.
|
* nan: (libc)FP Bit Twiddling.
|
* nanf: (libc)FP Bit Twiddling.
|
* nanfN: (libc)FP Bit Twiddling.
|
* nanfNx: (libc)FP Bit Twiddling.
|
* nanl: (libc)FP Bit Twiddling.
|
* nanosleep: (libc)Sleeping.
|
* nearbyint: (libc)Rounding Functions.
|
* nearbyintf: (libc)Rounding Functions.
|
* nearbyintfN: (libc)Rounding Functions.
|
* nearbyintfNx: (libc)Rounding Functions.
|
* nearbyintl: (libc)Rounding Functions.
|
* nextafter: (libc)FP Bit Twiddling.
|
* nextafterf: (libc)FP Bit Twiddling.
|
* nextafterfN: (libc)FP Bit Twiddling.
|
* nextafterfNx: (libc)FP Bit Twiddling.
|
* nextafterl: (libc)FP Bit Twiddling.
|
* nextdown: (libc)FP Bit Twiddling.
|
* nextdownf: (libc)FP Bit Twiddling.
|
* nextdownfN: (libc)FP Bit Twiddling.
|
* nextdownfNx: (libc)FP Bit Twiddling.
|
* nextdownl: (libc)FP Bit Twiddling.
|
* nexttoward: (libc)FP Bit Twiddling.
|
* nexttowardf: (libc)FP Bit Twiddling.
|
* nexttowardl: (libc)FP Bit Twiddling.
|
* nextup: (libc)FP Bit Twiddling.
|
* nextupf: (libc)FP Bit Twiddling.
|
* nextupfN: (libc)FP Bit Twiddling.
|
* nextupfNx: (libc)FP Bit Twiddling.
|
* nextupl: (libc)FP Bit Twiddling.
|
* nftw64: (libc)Working with Directory Trees.
|
* nftw: (libc)Working with Directory Trees.
|
* ngettext: (libc)Advanced gettext functions.
|
* nice: (libc)Traditional Scheduling Functions.
|
* nl_langinfo: (libc)The Elegant and Fast Way.
|
* nrand48: (libc)SVID Random.
|
* nrand48_r: (libc)SVID Random.
|
* ntohl: (libc)Byte Order.
|
* ntohs: (libc)Byte Order.
|
* ntp_adjtime: (libc)Setting and Adjusting the Time.
|
* ntp_gettime: (libc)Setting and Adjusting the Time.
|
* obstack_1grow: (libc)Growing Objects.
|
* obstack_1grow_fast: (libc)Extra Fast Growing.
|
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
|
* obstack_alloc: (libc)Allocation in an Obstack.
|
* obstack_base: (libc)Status of an Obstack.
|
* obstack_blank: (libc)Growing Objects.
|
* obstack_blank_fast: (libc)Extra Fast Growing.
|
* obstack_chunk_size: (libc)Obstack Chunks.
|
* obstack_copy0: (libc)Allocation in an Obstack.
|
* obstack_copy: (libc)Allocation in an Obstack.
|
* obstack_finish: (libc)Growing Objects.
|
* obstack_free: (libc)Freeing Obstack Objects.
|
* obstack_grow0: (libc)Growing Objects.
|
* obstack_grow: (libc)Growing Objects.
|
* obstack_init: (libc)Preparing for Obstacks.
|
* obstack_int_grow: (libc)Growing Objects.
|
* obstack_int_grow_fast: (libc)Extra Fast Growing.
|
* obstack_next_free: (libc)Status of an Obstack.
|
* obstack_object_size: (libc)Growing Objects.
|
* obstack_object_size: (libc)Status of an Obstack.
|
* obstack_printf: (libc)Dynamic Output.
|
* obstack_ptr_grow: (libc)Growing Objects.
|
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
|
* obstack_room: (libc)Extra Fast Growing.
|
* obstack_vprintf: (libc)Variable Arguments Output.
|
* offsetof: (libc)Structure Measurement.
|
* on_exit: (libc)Cleanups on Exit.
|
* open64: (libc)Opening and Closing Files.
|
* open: (libc)Opening and Closing Files.
|
* open_memstream: (libc)String Streams.
|
* opendir: (libc)Opening a Directory.
|
* openlog: (libc)openlog.
|
* openpty: (libc)Pseudo-Terminal Pairs.
|
* parse_printf_format: (libc)Parsing a Template String.
|
* pathconf: (libc)Pathconf.
|
* pause: (libc)Using Pause.
|
* pclose: (libc)Pipe to a Subprocess.
|
* perror: (libc)Error Messages.
|
* pipe: (libc)Creating a Pipe.
|
* pkey_alloc: (libc)Memory Protection.
|
* pkey_free: (libc)Memory Protection.
|
* pkey_get: (libc)Memory Protection.
|
* pkey_mprotect: (libc)Memory Protection.
|
* pkey_set: (libc)Memory Protection.
|
* popen: (libc)Pipe to a Subprocess.
|
* posix_fallocate64: (libc)Storage Allocation.
|
* posix_fallocate: (libc)Storage Allocation.
|
* posix_memalign: (libc)Aligned Memory Blocks.
|
* pow: (libc)Exponents and Logarithms.
|
* powf: (libc)Exponents and Logarithms.
|
* powfN: (libc)Exponents and Logarithms.
|
* powfNx: (libc)Exponents and Logarithms.
|
* powl: (libc)Exponents and Logarithms.
|
* pread64: (libc)I/O Primitives.
|
* pread: (libc)I/O Primitives.
|
* preadv2: (libc)Scatter-Gather.
|
* preadv64: (libc)Scatter-Gather.
|
* preadv64v2: (libc)Scatter-Gather.
|
* preadv: (libc)Scatter-Gather.
|
* printf: (libc)Formatted Output Functions.
|
* printf_size: (libc)Predefined Printf Handlers.
|
* printf_size_info: (libc)Predefined Printf Handlers.
|
* psignal: (libc)Signal Messages.
|
* pthread_attr_getsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_attr_setsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_clockjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_cond_clockwait: (libc)Waiting with Explicit Clocks.
|
* pthread_getattr_default_np: (libc)Default Thread Attributes.
|
* pthread_getspecific: (libc)Thread-specific Data.
|
* pthread_key_create: (libc)Thread-specific Data.
|
* pthread_key_delete: (libc)Thread-specific Data.
|
* pthread_rwlock_clockrdlock: (libc)Waiting with Explicit Clocks.
|
* pthread_rwlock_clockwrlock: (libc)Waiting with Explicit Clocks.
|
* pthread_setattr_default_np: (libc)Default Thread Attributes.
|
* pthread_setspecific: (libc)Thread-specific Data.
|
* pthread_timedjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_tryjoin_np: (libc)Waiting with Explicit Clocks.
|
* ptsname: (libc)Allocation.
|
* ptsname_r: (libc)Allocation.
|
* putc: (libc)Simple Output.
|
* putc_unlocked: (libc)Simple Output.
|
* putchar: (libc)Simple Output.
|
* putchar_unlocked: (libc)Simple Output.
|
* putenv: (libc)Environment Access.
|
* putpwent: (libc)Writing a User Entry.
|
* puts: (libc)Simple Output.
|
* pututline: (libc)Manipulating the Database.
|
* pututxline: (libc)XPG Functions.
|
* putw: (libc)Simple Output.
|
* putwc: (libc)Simple Output.
|
* putwc_unlocked: (libc)Simple Output.
|
* putwchar: (libc)Simple Output.
|
* putwchar_unlocked: (libc)Simple Output.
|
* pwrite64: (libc)I/O Primitives.
|
* pwrite: (libc)I/O Primitives.
|
* pwritev2: (libc)Scatter-Gather.
|
* pwritev64: (libc)Scatter-Gather.
|
* pwritev64v2: (libc)Scatter-Gather.
|
* pwritev: (libc)Scatter-Gather.
|
* qecvt: (libc)System V Number Conversion.
|
* qecvt_r: (libc)System V Number Conversion.
|
* qfcvt: (libc)System V Number Conversion.
|
* qfcvt_r: (libc)System V Number Conversion.
|
* qgcvt: (libc)System V Number Conversion.
|
* qsort: (libc)Array Sort Function.
|
* raise: (libc)Signaling Yourself.
|
* rand: (libc)ISO Random.
|
* rand_r: (libc)ISO Random.
|
* random: (libc)BSD Random.
|
* random_r: (libc)BSD Random.
|
* rawmemchr: (libc)Search Functions.
|
* read: (libc)I/O Primitives.
|
* readdir64: (libc)Reading/Closing Directory.
|
* readdir64_r: (libc)Reading/Closing Directory.
|
* readdir: (libc)Reading/Closing Directory.
|
* readdir_r: (libc)Reading/Closing Directory.
|
* readlink: (libc)Symbolic Links.
|
* readv: (libc)Scatter-Gather.
|
* realloc: (libc)Changing Block Size.
|
* reallocarray: (libc)Changing Block Size.
|
* realpath: (libc)Symbolic Links.
|
* recv: (libc)Receiving Data.
|
* recvfrom: (libc)Receiving Datagrams.
|
* recvmsg: (libc)Receiving Datagrams.
|
* regcomp: (libc)POSIX Regexp Compilation.
|
* regerror: (libc)Regexp Cleanup.
|
* regexec: (libc)Matching POSIX Regexps.
|
* regfree: (libc)Regexp Cleanup.
|
* register_printf_function: (libc)Registering New Conversions.
|
* remainder: (libc)Remainder Functions.
|
* remainderf: (libc)Remainder Functions.
|
* remainderfN: (libc)Remainder Functions.
|
* remainderfNx: (libc)Remainder Functions.
|
* remainderl: (libc)Remainder Functions.
|
* remove: (libc)Deleting Files.
|
* rename: (libc)Renaming Files.
|
* rewind: (libc)File Positioning.
|
* rewinddir: (libc)Random Access Directory.
|
* rindex: (libc)Search Functions.
|
* rint: (libc)Rounding Functions.
|
* rintf: (libc)Rounding Functions.
|
* rintfN: (libc)Rounding Functions.
|
* rintfNx: (libc)Rounding Functions.
|
* rintl: (libc)Rounding Functions.
|
* rmdir: (libc)Deleting Files.
|
* round: (libc)Rounding Functions.
|
* roundeven: (libc)Rounding Functions.
|
* roundevenf: (libc)Rounding Functions.
|
* roundevenfN: (libc)Rounding Functions.
|
* roundevenfNx: (libc)Rounding Functions.
|
* roundevenl: (libc)Rounding Functions.
|
* roundf: (libc)Rounding Functions.
|
* roundfN: (libc)Rounding Functions.
|
* roundfNx: (libc)Rounding Functions.
|
* roundl: (libc)Rounding Functions.
|
* rpmatch: (libc)Yes-or-No Questions.
|
* sbrk: (libc)Resizing the Data Segment.
|
* scalb: (libc)Normalization Functions.
|
* scalbf: (libc)Normalization Functions.
|
* scalbl: (libc)Normalization Functions.
|
* scalbln: (libc)Normalization Functions.
|
* scalblnf: (libc)Normalization Functions.
|
* scalblnfN: (libc)Normalization Functions.
|
* scalblnfNx: (libc)Normalization Functions.
|
* scalblnl: (libc)Normalization Functions.
|
* scalbn: (libc)Normalization Functions.
|
* scalbnf: (libc)Normalization Functions.
|
* scalbnfN: (libc)Normalization Functions.
|
* scalbnfNx: (libc)Normalization Functions.
|
* scalbnl: (libc)Normalization Functions.
|
* scandir64: (libc)Scanning Directory Content.
|
* scandir: (libc)Scanning Directory Content.
|
* scanf: (libc)Formatted Input Functions.
|
* sched_get_priority_max: (libc)Basic Scheduling Functions.
|
* sched_get_priority_min: (libc)Basic Scheduling Functions.
|
* sched_getaffinity: (libc)CPU Affinity.
|
* sched_getparam: (libc)Basic Scheduling Functions.
|
* sched_getscheduler: (libc)Basic Scheduling Functions.
|
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
|
* sched_setaffinity: (libc)CPU Affinity.
|
* sched_setparam: (libc)Basic Scheduling Functions.
|
* sched_setscheduler: (libc)Basic Scheduling Functions.
|
* sched_yield: (libc)Basic Scheduling Functions.
|
* secure_getenv: (libc)Environment Access.
|
* seed48: (libc)SVID Random.
|
* seed48_r: (libc)SVID Random.
|
* seekdir: (libc)Random Access Directory.
|
* select: (libc)Waiting for I/O.
|
* sem_clockwait: (libc)Waiting with Explicit Clocks.
|
* sem_close: (libc)Semaphores.
|
* sem_destroy: (libc)Semaphores.
|
* sem_getvalue: (libc)Semaphores.
|
* sem_init: (libc)Semaphores.
|
* sem_open: (libc)Semaphores.
|
* sem_post: (libc)Semaphores.
|
* sem_timedwait: (libc)Semaphores.
|
* sem_trywait: (libc)Semaphores.
|
* sem_unlink: (libc)Semaphores.
|
* sem_wait: (libc)Semaphores.
|
* semctl: (libc)Semaphores.
|
* semget: (libc)Semaphores.
|
* semop: (libc)Semaphores.
|
* semtimedop: (libc)Semaphores.
|
* send: (libc)Sending Data.
|
* sendmsg: (libc)Receiving Datagrams.
|
* sendto: (libc)Sending Datagrams.
|
* setbuf: (libc)Controlling Buffering.
|
* setbuffer: (libc)Controlling Buffering.
|
* setcontext: (libc)System V contexts.
|
* setdomainname: (libc)Host Identification.
|
* setegid: (libc)Setting Groups.
|
* setenv: (libc)Environment Access.
|
* seteuid: (libc)Setting User ID.
|
* setfsent: (libc)fstab.
|
* setgid: (libc)Setting Groups.
|
* setgrent: (libc)Scanning All Groups.
|
* setgroups: (libc)Setting Groups.
|
* sethostent: (libc)Host Names.
|
* sethostid: (libc)Host Identification.
|
* sethostname: (libc)Host Identification.
|
* setitimer: (libc)Setting an Alarm.
|
* setjmp: (libc)Non-Local Details.
|
* setlinebuf: (libc)Controlling Buffering.
|
* setlocale: (libc)Setting the Locale.
|
* setlogmask: (libc)setlogmask.
|
* setmntent: (libc)mtab.
|
* setnetent: (libc)Networks Database.
|
* setnetgrent: (libc)Lookup Netgroup.
|
* setpayload: (libc)FP Bit Twiddling.
|
* setpayloadf: (libc)FP Bit Twiddling.
|
* setpayloadfN: (libc)FP Bit Twiddling.
|
* setpayloadfNx: (libc)FP Bit Twiddling.
|
* setpayloadl: (libc)FP Bit Twiddling.
|
* setpayloadsig: (libc)FP Bit Twiddling.
|
* setpayloadsigf: (libc)FP Bit Twiddling.
|
* setpayloadsigfN: (libc)FP Bit Twiddling.
|
* setpayloadsigfNx: (libc)FP Bit Twiddling.
|
* setpayloadsigl: (libc)FP Bit Twiddling.
|
* setpgid: (libc)Process Group Functions.
|
* setpgrp: (libc)Process Group Functions.
|
* setpriority: (libc)Traditional Scheduling Functions.
|
* setprotoent: (libc)Protocols Database.
|
* setpwent: (libc)Scanning All Users.
|
* setregid: (libc)Setting Groups.
|
* setreuid: (libc)Setting User ID.
|
* setrlimit64: (libc)Limits on Resources.
|
* setrlimit: (libc)Limits on Resources.
|
* setservent: (libc)Services Database.
|
* setsid: (libc)Process Group Functions.
|
* setsockopt: (libc)Socket Option Functions.
|
* setstate: (libc)BSD Random.
|
* setstate_r: (libc)BSD Random.
|
* settimeofday: (libc)Setting and Adjusting the Time.
|
* setuid: (libc)Setting User ID.
|
* setutent: (libc)Manipulating the Database.
|
* setutxent: (libc)XPG Functions.
|
* setvbuf: (libc)Controlling Buffering.
|
* shm_open: (libc)Memory-mapped I/O.
|
* shm_unlink: (libc)Memory-mapped I/O.
|
* shutdown: (libc)Closing a Socket.
|
* sigabbrev_np: (libc)Signal Messages.
|
* sigaction: (libc)Advanced Signal Handling.
|
* sigaddset: (libc)Signal Sets.
|
* sigaltstack: (libc)Signal Stack.
|
* sigblock: (libc)BSD Signal Handling.
|
* sigdelset: (libc)Signal Sets.
|
* sigdescr_np: (libc)Signal Messages.
|
* sigemptyset: (libc)Signal Sets.
|
* sigfillset: (libc)Signal Sets.
|
* siginterrupt: (libc)BSD Signal Handling.
|
* sigismember: (libc)Signal Sets.
|
* siglongjmp: (libc)Non-Local Exits and Signals.
|
* sigmask: (libc)BSD Signal Handling.
|
* signal: (libc)Basic Signal Handling.
|
* signbit: (libc)FP Bit Twiddling.
|
* significand: (libc)Normalization Functions.
|
* significandf: (libc)Normalization Functions.
|
* significandl: (libc)Normalization Functions.
|
* sigpause: (libc)BSD Signal Handling.
|
* sigpending: (libc)Checking for Pending Signals.
|
* sigprocmask: (libc)Process Signal Mask.
|
* sigsetjmp: (libc)Non-Local Exits and Signals.
|
* sigsetmask: (libc)BSD Signal Handling.
|
* sigstack: (libc)Signal Stack.
|
* sigsuspend: (libc)Sigsuspend.
|
* sin: (libc)Trig Functions.
|
* sincos: (libc)Trig Functions.
|
* sincosf: (libc)Trig Functions.
|
* sincosfN: (libc)Trig Functions.
|
* sincosfNx: (libc)Trig Functions.
|
* sincosl: (libc)Trig Functions.
|
* sinf: (libc)Trig Functions.
|
* sinfN: (libc)Trig Functions.
|
* sinfNx: (libc)Trig Functions.
|
* sinh: (libc)Hyperbolic Functions.
|
* sinhf: (libc)Hyperbolic Functions.
|
* sinhfN: (libc)Hyperbolic Functions.
|
* sinhfNx: (libc)Hyperbolic Functions.
|
* sinhl: (libc)Hyperbolic Functions.
|
* sinl: (libc)Trig Functions.
|
* sleep: (libc)Sleeping.
|
* snprintf: (libc)Formatted Output Functions.
|
* socket: (libc)Creating a Socket.
|
* socketpair: (libc)Socket Pairs.
|
* sprintf: (libc)Formatted Output Functions.
|
* sqrt: (libc)Exponents and Logarithms.
|
* sqrtf: (libc)Exponents and Logarithms.
|
* sqrtfN: (libc)Exponents and Logarithms.
|
* sqrtfNx: (libc)Exponents and Logarithms.
|
* sqrtl: (libc)Exponents and Logarithms.
|
* srand48: (libc)SVID Random.
|
* srand48_r: (libc)SVID Random.
|
* srand: (libc)ISO Random.
|
* srandom: (libc)BSD Random.
|
* srandom_r: (libc)BSD Random.
|
* sscanf: (libc)Formatted Input Functions.
|
* ssignal: (libc)Basic Signal Handling.
|
* stat64: (libc)Reading Attributes.
|
* stat: (libc)Reading Attributes.
|
* stime: (libc)Setting and Adjusting the Time.
|
* stpcpy: (libc)Copying Strings and Arrays.
|
* stpncpy: (libc)Truncating Strings.
|
* strcasecmp: (libc)String/Array Comparison.
|
* strcasestr: (libc)Search Functions.
|
* strcat: (libc)Concatenating Strings.
|
* strchr: (libc)Search Functions.
|
* strchrnul: (libc)Search Functions.
|
* strcmp: (libc)String/Array Comparison.
|
* strcoll: (libc)Collation Functions.
|
* strcpy: (libc)Copying Strings and Arrays.
|
* strcspn: (libc)Search Functions.
|
* strdup: (libc)Copying Strings and Arrays.
|
* strdupa: (libc)Copying Strings and Arrays.
|
* strerror: (libc)Error Messages.
|
* strerror_r: (libc)Error Messages.
|
* strerrordesc_np: (libc)Error Messages.
|
* strerrorname_np: (libc)Error Messages.
|
* strfmon: (libc)Formatting Numbers.
|
* strfromd: (libc)Printing of Floats.
|
* strfromf: (libc)Printing of Floats.
|
* strfromfN: (libc)Printing of Floats.
|
* strfromfNx: (libc)Printing of Floats.
|
* strfroml: (libc)Printing of Floats.
|
* strfry: (libc)Shuffling Bytes.
|
* strftime: (libc)Formatting Calendar Time.
|
* strlen: (libc)String Length.
|
* strncasecmp: (libc)String/Array Comparison.
|
* strncat: (libc)Truncating Strings.
|
* strncmp: (libc)String/Array Comparison.
|
* strncpy: (libc)Truncating Strings.
|
* strndup: (libc)Truncating Strings.
|
* strndupa: (libc)Truncating Strings.
|
* strnlen: (libc)String Length.
|
* strpbrk: (libc)Search Functions.
|
* strptime: (libc)Low-Level Time String Parsing.
|
* strrchr: (libc)Search Functions.
|
* strsep: (libc)Finding Tokens in a String.
|
* strsignal: (libc)Signal Messages.
|
* strspn: (libc)Search Functions.
|
* strstr: (libc)Search Functions.
|
* strtod: (libc)Parsing of Floats.
|
* strtof: (libc)Parsing of Floats.
|
* strtofN: (libc)Parsing of Floats.
|
* strtofNx: (libc)Parsing of Floats.
|
* strtoimax: (libc)Parsing of Integers.
|
* strtok: (libc)Finding Tokens in a String.
|
* strtok_r: (libc)Finding Tokens in a String.
|
* strtol: (libc)Parsing of Integers.
|
* strtold: (libc)Parsing of Floats.
|
* strtoll: (libc)Parsing of Integers.
|
* strtoq: (libc)Parsing of Integers.
|
* strtoul: (libc)Parsing of Integers.
|
* strtoull: (libc)Parsing of Integers.
|
* strtoumax: (libc)Parsing of Integers.
|
* strtouq: (libc)Parsing of Integers.
|
* strverscmp: (libc)String/Array Comparison.
|
* strxfrm: (libc)Collation Functions.
|
* stty: (libc)BSD Terminal Modes.
|
* swapcontext: (libc)System V contexts.
|
* swprintf: (libc)Formatted Output Functions.
|
* swscanf: (libc)Formatted Input Functions.
|
* symlink: (libc)Symbolic Links.
|
* sync: (libc)Synchronizing I/O.
|
* syscall: (libc)System Calls.
|
* sysconf: (libc)Sysconf Definition.
|
* syslog: (libc)syslog; vsyslog.
|
* system: (libc)Running a Command.
|
* sysv_signal: (libc)Basic Signal Handling.
|
* tan: (libc)Trig Functions.
|
* tanf: (libc)Trig Functions.
|
* tanfN: (libc)Trig Functions.
|
* tanfNx: (libc)Trig Functions.
|
* tanh: (libc)Hyperbolic Functions.
|
* tanhf: (libc)Hyperbolic Functions.
|
* tanhfN: (libc)Hyperbolic Functions.
|
* tanhfNx: (libc)Hyperbolic Functions.
|
* tanhl: (libc)Hyperbolic Functions.
|
* tanl: (libc)Trig Functions.
|
* tcdrain: (libc)Line Control.
|
* tcflow: (libc)Line Control.
|
* tcflush: (libc)Line Control.
|
* tcgetattr: (libc)Mode Functions.
|
* tcgetpgrp: (libc)Terminal Access Functions.
|
* tcgetsid: (libc)Terminal Access Functions.
|
* tcsendbreak: (libc)Line Control.
|
* tcsetattr: (libc)Mode Functions.
|
* tcsetpgrp: (libc)Terminal Access Functions.
|
* tdelete: (libc)Tree Search Function.
|
* tdestroy: (libc)Tree Search Function.
|
* telldir: (libc)Random Access Directory.
|
* tempnam: (libc)Temporary Files.
|
* textdomain: (libc)Locating gettext catalog.
|
* tfind: (libc)Tree Search Function.
|
* tgamma: (libc)Special Functions.
|
* tgammaf: (libc)Special Functions.
|
* tgammafN: (libc)Special Functions.
|
* tgammafNx: (libc)Special Functions.
|
* tgammal: (libc)Special Functions.
|
* tgkill: (libc)Signaling Another Process.
|
* thrd_create: (libc)ISO C Thread Management.
|
* thrd_current: (libc)ISO C Thread Management.
|
* thrd_detach: (libc)ISO C Thread Management.
|
* thrd_equal: (libc)ISO C Thread Management.
|
* thrd_exit: (libc)ISO C Thread Management.
|
* thrd_join: (libc)ISO C Thread Management.
|
* thrd_sleep: (libc)ISO C Thread Management.
|
* thrd_yield: (libc)ISO C Thread Management.
|
* time: (libc)Getting the Time.
|
* timegm: (libc)Broken-down Time.
|
* timelocal: (libc)Broken-down Time.
|
* times: (libc)Processor Time.
|
* tmpfile64: (libc)Temporary Files.
|
* tmpfile: (libc)Temporary Files.
|
* tmpnam: (libc)Temporary Files.
|
* tmpnam_r: (libc)Temporary Files.
|
* toascii: (libc)Case Conversion.
|
* tolower: (libc)Case Conversion.
|
* totalorder: (libc)FP Comparison Functions.
|
* totalorderf: (libc)FP Comparison Functions.
|
* totalorderfN: (libc)FP Comparison Functions.
|
* totalorderfNx: (libc)FP Comparison Functions.
|
* totalorderl: (libc)FP Comparison Functions.
|
* totalordermag: (libc)FP Comparison Functions.
|
* totalordermagf: (libc)FP Comparison Functions.
|
* totalordermagfN: (libc)FP Comparison Functions.
|
* totalordermagfNx: (libc)FP Comparison Functions.
|
* totalordermagl: (libc)FP Comparison Functions.
|
* toupper: (libc)Case Conversion.
|
* towctrans: (libc)Wide Character Case Conversion.
|
* towlower: (libc)Wide Character Case Conversion.
|
* towupper: (libc)Wide Character Case Conversion.
|
* trunc: (libc)Rounding Functions.
|
* truncate64: (libc)File Size.
|
* truncate: (libc)File Size.
|
* truncf: (libc)Rounding Functions.
|
* truncfN: (libc)Rounding Functions.
|
* truncfNx: (libc)Rounding Functions.
|
* truncl: (libc)Rounding Functions.
|
* tsearch: (libc)Tree Search Function.
|
* tss_create: (libc)ISO C Thread-local Storage.
|
* tss_delete: (libc)ISO C Thread-local Storage.
|
* tss_get: (libc)ISO C Thread-local Storage.
|
* tss_set: (libc)ISO C Thread-local Storage.
|
* ttyname: (libc)Is It a Terminal.
|
* ttyname_r: (libc)Is It a Terminal.
|
* twalk: (libc)Tree Search Function.
|
* twalk_r: (libc)Tree Search Function.
|
* tzset: (libc)Time Zone Functions.
|
* ufromfp: (libc)Rounding Functions.
|
* ufromfpf: (libc)Rounding Functions.
|
* ufromfpfN: (libc)Rounding Functions.
|
* ufromfpfNx: (libc)Rounding Functions.
|
* ufromfpl: (libc)Rounding Functions.
|
* ufromfpx: (libc)Rounding Functions.
|
* ufromfpxf: (libc)Rounding Functions.
|
* ufromfpxfN: (libc)Rounding Functions.
|
* ufromfpxfNx: (libc)Rounding Functions.
|
* ufromfpxl: (libc)Rounding Functions.
|
* ulimit: (libc)Limits on Resources.
|
* umask: (libc)Setting Permissions.
|
* umount2: (libc)Mount-Unmount-Remount.
|
* umount: (libc)Mount-Unmount-Remount.
|
* uname: (libc)Platform Type.
|
* ungetc: (libc)How Unread.
|
* ungetwc: (libc)How Unread.
|
* unlink: (libc)Deleting Files.
|
* unlockpt: (libc)Allocation.
|
* unsetenv: (libc)Environment Access.
|
* updwtmp: (libc)Manipulating the Database.
|
* utime: (libc)File Times.
|
* utimes: (libc)File Times.
|
* utmpname: (libc)Manipulating the Database.
|
* utmpxname: (libc)XPG Functions.
|
* va_arg: (libc)Argument Macros.
|
* va_copy: (libc)Argument Macros.
|
* va_end: (libc)Argument Macros.
|
* va_start: (libc)Argument Macros.
|
* valloc: (libc)Aligned Memory Blocks.
|
* vasprintf: (libc)Variable Arguments Output.
|
* verr: (libc)Error Messages.
|
* verrx: (libc)Error Messages.
|
* versionsort64: (libc)Scanning Directory Content.
|
* versionsort: (libc)Scanning Directory Content.
|
* vfork: (libc)Creating a Process.
|
* vfprintf: (libc)Variable Arguments Output.
|
* vfscanf: (libc)Variable Arguments Input.
|
* vfwprintf: (libc)Variable Arguments Output.
|
* vfwscanf: (libc)Variable Arguments Input.
|
* vlimit: (libc)Limits on Resources.
|
* vprintf: (libc)Variable Arguments Output.
|
* vscanf: (libc)Variable Arguments Input.
|
* vsnprintf: (libc)Variable Arguments Output.
|
* vsprintf: (libc)Variable Arguments Output.
|
* vsscanf: (libc)Variable Arguments Input.
|
* vswprintf: (libc)Variable Arguments Output.
|
* vswscanf: (libc)Variable Arguments Input.
|
* vsyslog: (libc)syslog; vsyslog.
|
* vwarn: (libc)Error Messages.
|
* vwarnx: (libc)Error Messages.
|
* vwprintf: (libc)Variable Arguments Output.
|
* vwscanf: (libc)Variable Arguments Input.
|
* wait3: (libc)BSD Wait Functions.
|
* wait4: (libc)Process Completion.
|
* wait: (libc)Process Completion.
|
* waitpid: (libc)Process Completion.
|
* warn: (libc)Error Messages.
|
* warnx: (libc)Error Messages.
|
* wcpcpy: (libc)Copying Strings and Arrays.
|
* wcpncpy: (libc)Truncating Strings.
|
* wcrtomb: (libc)Converting a Character.
|
* wcscasecmp: (libc)String/Array Comparison.
|
* wcscat: (libc)Concatenating Strings.
|
* wcschr: (libc)Search Functions.
|
* wcschrnul: (libc)Search Functions.
|
* wcscmp: (libc)String/Array Comparison.
|
* wcscoll: (libc)Collation Functions.
|
* wcscpy: (libc)Copying Strings and Arrays.
|
* wcscspn: (libc)Search Functions.
|
* wcsdup: (libc)Copying Strings and Arrays.
|
* wcsftime: (libc)Formatting Calendar Time.
|
* wcslen: (libc)String Length.
|
* wcsncasecmp: (libc)String/Array Comparison.
|
* wcsncat: (libc)Truncating Strings.
|
* wcsncmp: (libc)String/Array Comparison.
|
* wcsncpy: (libc)Truncating Strings.
|
* wcsnlen: (libc)String Length.
|
* wcsnrtombs: (libc)Converting Strings.
|
* wcspbrk: (libc)Search Functions.
|
* wcsrchr: (libc)Search Functions.
|
* wcsrtombs: (libc)Converting Strings.
|
* wcsspn: (libc)Search Functions.
|
* wcsstr: (libc)Search Functions.
|
* wcstod: (libc)Parsing of Floats.
|
* wcstof: (libc)Parsing of Floats.
|
* wcstofN: (libc)Parsing of Floats.
|
* wcstofNx: (libc)Parsing of Floats.
|
* wcstoimax: (libc)Parsing of Integers.
|
* wcstok: (libc)Finding Tokens in a String.
|
* wcstol: (libc)Parsing of Integers.
|
* wcstold: (libc)Parsing of Floats.
|
* wcstoll: (libc)Parsing of Integers.
|
* wcstombs: (libc)Non-reentrant String Conversion.
|
* wcstoq: (libc)Parsing of Integers.
|
* wcstoul: (libc)Parsing of Integers.
|
* wcstoull: (libc)Parsing of Integers.
|
* wcstoumax: (libc)Parsing of Integers.
|
* wcstouq: (libc)Parsing of Integers.
|
* wcswcs: (libc)Search Functions.
|
* wcsxfrm: (libc)Collation Functions.
|
* wctob: (libc)Converting a Character.
|
* wctomb: (libc)Non-reentrant Character Conversion.
|
* wctrans: (libc)Wide Character Case Conversion.
|
* wctype: (libc)Classification of Wide Characters.
|
* wmemchr: (libc)Search Functions.
|
* wmemcmp: (libc)String/Array Comparison.
|
* wmemcpy: (libc)Copying Strings and Arrays.
|
* wmemmove: (libc)Copying Strings and Arrays.
|
* wmempcpy: (libc)Copying Strings and Arrays.
|
* wmemset: (libc)Copying Strings and Arrays.
|
* wordexp: (libc)Calling Wordexp.
|
* wordfree: (libc)Calling Wordexp.
|
* wprintf: (libc)Formatted Output Functions.
|
* write: (libc)I/O Primitives.
|
* writev: (libc)Scatter-Gather.
|
* wscanf: (libc)Formatted Input Functions.
|
* y0: (libc)Special Functions.
|
* y0f: (libc)Special Functions.
|
* y0fN: (libc)Special Functions.
|
* y0fNx: (libc)Special Functions.
|
* y0l: (libc)Special Functions.
|
* y1: (libc)Special Functions.
|
* y1f: (libc)Special Functions.
|
* y1fN: (libc)Special Functions.
|
* y1fNx: (libc)Special Functions.
|
* y1l: (libc)Special Functions.
|
* yn: (libc)Special Functions.
|
* ynf: (libc)Special Functions.
|
* ynfN: (libc)Special Functions.
|
* ynfNx: (libc)Special Functions.
|
* ynl: (libc)Special Functions.
|
END-INFO-DIR-ENTRY
|
|
|
File: libc.info, Node: Handler Returns, Next: Termination in Handler, Up: Defining Handlers
|
|
24.4.1 Signal Handlers that Return
|
----------------------------------
|
|
Handlers which return normally are usually used for signals such as
|
‘SIGALRM’ and the I/O and interprocess communication signals. But a
|
handler for ‘SIGINT’ might also return normally after setting a flag
|
that tells the program to exit at a convenient time.
|
|
It is not safe to return normally from the handler for a program
|
error signal, because the behavior of the program when the handler
|
function returns is not defined after a program error. *Note Program
|
Error Signals::.
|
|
Handlers that return normally must modify some global variable in
|
order to have any effect. Typically, the variable is one that is
|
examined periodically by the program during normal operation. Its data
|
type should be ‘sig_atomic_t’ for reasons described in *note Atomic Data
|
Access::.
|
|
Here is a simple example of such a program. It executes the body of
|
the loop until it has noticed that a ‘SIGALRM’ signal has arrived. This
|
technique is useful because it allows the iteration in progress when the
|
signal arrives to complete before the loop exits.
|
|
|
#include <signal.h>
|
#include <stdio.h>
|
#include <stdlib.h>
|
|
/* This flag controls termination of the main loop. */
|
volatile sig_atomic_t keep_going = 1;
|
|
/* The signal handler just clears the flag and re-enables itself. */
|
void
|
catch_alarm (int sig)
|
{
|
keep_going = 0;
|
signal (sig, catch_alarm);
|
}
|
|
void
|
do_stuff (void)
|
{
|
puts ("Doing stuff while waiting for alarm....");
|
}
|
|
int
|
main (void)
|
{
|
/* Establish a handler for SIGALRM signals. */
|
signal (SIGALRM, catch_alarm);
|
|
/* Set an alarm to go off in a little while. */
|
alarm (2);
|
|
/* Check the flag once in a while to see when to quit. */
|
while (keep_going)
|
do_stuff ();
|
|
return EXIT_SUCCESS;
|
}
|
|
|
File: libc.info, Node: Termination in Handler, Next: Longjmp in Handler, Prev: Handler Returns, Up: Defining Handlers
|
|
24.4.2 Handlers That Terminate the Process
|
------------------------------------------
|
|
Handler functions that terminate the program are typically used to cause
|
orderly cleanup or recovery from program error signals and interactive
|
interrupts.
|
|
The cleanest way for a handler to terminate the process is to raise
|
the same signal that ran the handler in the first place. Here is how to
|
do this:
|
|
volatile sig_atomic_t fatal_error_in_progress = 0;
|
|
void
|
fatal_error_signal (int sig)
|
{
|
/* Since this handler is established for more than one kind of signal,
|
it might still get invoked recursively by delivery of some other kind
|
of signal. Use a static variable to keep track of that. */
|
if (fatal_error_in_progress)
|
raise (sig);
|
fatal_error_in_progress = 1;
|
|
/* Now do the clean up actions:
|
- reset terminal modes
|
- kill child processes
|
- remove lock files */
|
…
|
|
/* Now reraise the signal. We reactivate the signal’s
|
default handling, which is to terminate the process.
|
We could just call ‘exit’ or ‘abort’,
|
but reraising the signal sets the return status
|
from the process correctly. */
|
signal (sig, SIG_DFL);
|
raise (sig);
|
}
|
|
|
File: libc.info, Node: Longjmp in Handler, Next: Signals in Handler, Prev: Termination in Handler, Up: Defining Handlers
|
|
24.4.3 Nonlocal Control Transfer in Handlers
|
--------------------------------------------
|
|
You can do a nonlocal transfer of control out of a signal handler using
|
the ‘setjmp’ and ‘longjmp’ facilities (*note Non-Local Exits::).
|
|
When the handler does a nonlocal control transfer, the part of the
|
program that was running will not continue. If this part of the program
|
was in the middle of updating an important data structure, the data
|
structure will remain inconsistent. Since the program does not
|
terminate, the inconsistency is likely to be noticed later on.
|
|
There are two ways to avoid this problem. One is to block the signal
|
for the parts of the program that update important data structures.
|
Blocking the signal delays its delivery until it is unblocked, once the
|
critical updating is finished. *Note Blocking Signals::.
|
|
The other way is to re-initialize the crucial data structures in the
|
signal handler, or to make their values consistent.
|
|
Here is a rather schematic example showing the reinitialization of
|
one global variable.
|
|
#include <signal.h>
|
#include <setjmp.h>
|
|
jmp_buf return_to_top_level;
|
|
volatile sig_atomic_t waiting_for_input;
|
|
void
|
handle_sigint (int signum)
|
{
|
/* We may have been waiting for input when the signal arrived,
|
but we are no longer waiting once we transfer control. */
|
waiting_for_input = 0;
|
longjmp (return_to_top_level, 1);
|
}
|
|
int
|
main (void)
|
{
|
…
|
signal (SIGINT, sigint_handler);
|
…
|
while (1) {
|
prepare_for_command ();
|
if (setjmp (return_to_top_level) == 0)
|
read_and_execute_command ();
|
}
|
}
|
|
/* Imagine this is a subroutine used by various commands. */
|
char *
|
read_data ()
|
{
|
if (input_from_terminal) {
|
waiting_for_input = 1;
|
…
|
waiting_for_input = 0;
|
} else {
|
…
|
}
|
}
|
|
|
File: libc.info, Node: Signals in Handler, Next: Merged Signals, Prev: Longjmp in Handler, Up: Defining Handlers
|
|
24.4.4 Signals Arriving While a Handler Runs
|
--------------------------------------------
|
|
What happens if another signal arrives while your signal handler
|
function is running?
|
|
When the handler for a particular signal is invoked, that signal is
|
automatically blocked until the handler returns. That means that if two
|
signals of the same kind arrive close together, the second one will be
|
held until the first has been handled. (The handler can explicitly
|
unblock the signal using ‘sigprocmask’, if you want to allow more
|
signals of this type to arrive; see *note Process Signal Mask::.)
|
|
However, your handler can still be interrupted by delivery of another
|
kind of signal. To avoid this, you can use the ‘sa_mask’ member of the
|
action structure passed to ‘sigaction’ to explicitly specify which
|
signals should be blocked while the signal handler runs. These signals
|
are in addition to the signal for which the handler was invoked, and any
|
other signals that are normally blocked by the process. *Note Blocking
|
for Handler::.
|
|
When the handler returns, the set of blocked signals is restored to
|
the value it had before the handler ran. So using ‘sigprocmask’ inside
|
the handler only affects what signals can arrive during the execution of
|
the handler itself, not what signals can arrive once the handler
|
returns.
|
|
*Portability Note:* Always use ‘sigaction’ to establish a handler for
|
a signal that you expect to receive asynchronously, if you want your
|
program to work properly on System V Unix. On this system, the handling
|
of a signal whose handler was established with ‘signal’ automatically
|
sets the signal’s action back to ‘SIG_DFL’, and the handler must
|
re-establish itself each time it runs. This practice, while
|
inconvenient, does work when signals cannot arrive in succession.
|
However, if another signal can arrive right away, it may arrive before
|
the handler can re-establish itself. Then the second signal would
|
receive the default handling, which could terminate the process.
|
|
|
File: libc.info, Node: Merged Signals, Next: Nonreentrancy, Prev: Signals in Handler, Up: Defining Handlers
|
|
24.4.5 Signals Close Together Merge into One
|
--------------------------------------------
|
|
If multiple signals of the same type are delivered to your process
|
before your signal handler has a chance to be invoked at all, the
|
handler may only be invoked once, as if only a single signal had
|
arrived. In effect, the signals merge into one. This situation can
|
arise when the signal is blocked, or in a multiprocessing environment
|
where the system is busy running some other processes while the signals
|
are delivered. This means, for example, that you cannot reliably use a
|
signal handler to count signals. The only distinction you can reliably
|
make is whether at least one signal has arrived since a given time in
|
the past.
|
|
Here is an example of a handler for ‘SIGCHLD’ that compensates for
|
the fact that the number of signals received may not equal the number of
|
child processes that generate them. It assumes that the program keeps
|
track of all the child processes with a chain of structures as follows:
|
|
struct process
|
{
|
struct process *next;
|
/* The process ID of this child. */
|
int pid;
|
/* The descriptor of the pipe or pseudo terminal
|
on which output comes from this child. */
|
int input_descriptor;
|
/* Nonzero if this process has stopped or terminated. */
|
sig_atomic_t have_status;
|
/* The status of this child; 0 if running,
|
otherwise a status value from ‘waitpid’. */
|
int status;
|
};
|
|
struct process *process_list;
|
|
This example also uses a flag to indicate whether signals have
|
arrived since some time in the past—whenever the program last cleared it
|
to zero.
|
|
/* Nonzero means some child’s status has changed
|
so look at ‘process_list’ for the details. */
|
int process_status_change;
|
|
Here is the handler itself:
|
|
void
|
sigchld_handler (int signo)
|
{
|
int old_errno = errno;
|
|
while (1) {
|
register int pid;
|
int w;
|
struct process *p;
|
|
/* Keep asking for a status until we get a definitive result. */
|
do
|
{
|
errno = 0;
|
pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED);
|
}
|
while (pid <= 0 && errno == EINTR);
|
|
if (pid <= 0) {
|
/* A real failure means there are no more
|
stopped or terminated child processes, so return. */
|
errno = old_errno;
|
return;
|
}
|
|
/* Find the process that signaled us, and record its status. */
|
|
for (p = process_list; p; p = p->next)
|
if (p->pid == pid) {
|
p->status = w;
|
/* Indicate that the ‘status’ field
|
has data to look at. We do this only after storing it. */
|
p->have_status = 1;
|
|
/* If process has terminated, stop waiting for its output. */
|
if (WIFSIGNALED (w) || WIFEXITED (w))
|
if (p->input_descriptor)
|
FD_CLR (p->input_descriptor, &input_wait_mask);
|
|
/* The program should check this flag from time to time
|
to see if there is any news in ‘process_list’. */
|
++process_status_change;
|
}
|
|
/* Loop around to handle all the processes
|
that have something to tell us. */
|
}
|
}
|
|
Here is the proper way to check the flag ‘process_status_change’:
|
|
if (process_status_change) {
|
struct process *p;
|
process_status_change = 0;
|
for (p = process_list; p; p = p->next)
|
if (p->have_status) {
|
… Examine ‘p->status’ …
|
}
|
}
|
|
It is vital to clear the flag before examining the list; otherwise, if a
|
signal were delivered just before the clearing of the flag, and after
|
the appropriate element of the process list had been checked, the status
|
change would go unnoticed until the next signal arrived to set the flag
|
again. You could, of course, avoid this problem by blocking the signal
|
while scanning the list, but it is much more elegant to guarantee
|
correctness by doing things in the right order.
|
|
The loop which checks process status avoids examining ‘p->status’
|
until it sees that status has been validly stored. This is to make sure
|
that the status cannot change in the middle of accessing it. Once
|
‘p->have_status’ is set, it means that the child process is stopped or
|
terminated, and in either case, it cannot stop or terminate again until
|
the program has taken notice. *Note Atomic Usage::, for more
|
information about coping with interruptions during accesses of a
|
variable.
|
|
Here is another way you can test whether the handler has run since
|
the last time you checked. This technique uses a counter which is never
|
changed outside the handler. Instead of clearing the count, the program
|
remembers the previous value and sees whether it has changed since the
|
previous check. The advantage of this method is that different parts of
|
the program can check independently, each part checking whether there
|
has been a signal since that part last checked.
|
|
sig_atomic_t process_status_change;
|
|
sig_atomic_t last_process_status_change;
|
|
…
|
{
|
sig_atomic_t prev = last_process_status_change;
|
last_process_status_change = process_status_change;
|
if (last_process_status_change != prev) {
|
struct process *p;
|
for (p = process_list; p; p = p->next)
|
if (p->have_status) {
|
… Examine ‘p->status’ …
|
}
|
}
|
}
|
|
|
File: libc.info, Node: Nonreentrancy, Next: Atomic Data Access, Prev: Merged Signals, Up: Defining Handlers
|
|
24.4.6 Signal Handling and Nonreentrant Functions
|
-------------------------------------------------
|
|
Handler functions usually don’t do very much. The best practice is to
|
write a handler that does nothing but set an external variable that the
|
program checks regularly, and leave all serious work to the program.
|
This is best because the handler can be called asynchronously, at
|
unpredictable times—perhaps in the middle of a primitive function, or
|
even between the beginning and the end of a C operator that requires
|
multiple instructions. The data structures being manipulated might
|
therefore be in an inconsistent state when the handler function is
|
invoked. Even copying one ‘int’ variable into another can take two
|
instructions on most machines.
|
|
This means you have to be very careful about what you do in a signal
|
handler.
|
|
• If your handler needs to access any global variables from your
|
program, declare those variables ‘volatile’. This tells the
|
compiler that the value of the variable might change
|
asynchronously, and inhibits certain optimizations that would be
|
invalidated by such modifications.
|
|
• If you call a function in the handler, make sure it is "reentrant"
|
with respect to signals, or else make sure that the signal cannot
|
interrupt a call to a related function.
|
|
A function can be non-reentrant if it uses memory that is not on the
|
stack.
|
|
• If a function uses a static variable or a global variable, or a
|
dynamically-allocated object that it finds for itself, then it is
|
non-reentrant and any two calls to the function can interfere.
|
|
For example, suppose that the signal handler uses ‘gethostbyname’.
|
This function returns its value in a static object, reusing the
|
same object each time. If the signal happens to arrive during a
|
call to ‘gethostbyname’, or even after one (while the program is
|
still using the value), it will clobber the value that the program
|
asked for.
|
|
However, if the program does not use ‘gethostbyname’ or any other
|
function that returns information in the same object, or if it
|
always blocks signals around each use, then you are safe.
|
|
There are a large number of library functions that return values in
|
a fixed object, always reusing the same object in this fashion, and
|
all of them cause the same problem. Function descriptions in this
|
manual always mention this behavior.
|
|
• If a function uses and modifies an object that you supply, then it
|
is potentially non-reentrant; two calls can interfere if they use
|
the same object.
|
|
This case arises when you do I/O using streams. Suppose that the
|
signal handler prints a message with ‘fprintf’. Suppose that the
|
program was in the middle of an ‘fprintf’ call using the same
|
stream when the signal was delivered. Both the signal handler’s
|
message and the program’s data could be corrupted, because both
|
calls operate on the same data structure—the stream itself.
|
|
However, if you know that the stream that the handler uses cannot
|
possibly be used by the program at a time when signals can arrive,
|
then you are safe. It is no problem if the program uses some other
|
stream.
|
|
• On most systems, ‘malloc’ and ‘free’ are not reentrant, because
|
they use a static data structure which records what memory blocks
|
are free. As a result, no library functions that allocate or free
|
memory are reentrant. This includes functions that allocate space
|
to store a result.
|
|
The best way to avoid the need to allocate memory in a handler is
|
to allocate in advance space for signal handlers to use.
|
|
The best way to avoid freeing memory in a handler is to flag or
|
record the objects to be freed, and have the program check from
|
time to time whether anything is waiting to be freed. But this
|
must be done with care, because placing an object on a chain is not
|
atomic, and if it is interrupted by another signal handler that
|
does the same thing, you could “lose” one of the objects.
|
|
• Any function that modifies ‘errno’ is non-reentrant, but you can
|
correct for this: in the handler, save the original value of
|
‘errno’ and restore it before returning normally. This prevents
|
errors that occur within the signal handler from being confused
|
with errors from system calls at the point the program is
|
interrupted to run the handler.
|
|
This technique is generally applicable; if you want to call in a
|
handler a function that modifies a particular object in memory, you
|
can make this safe by saving and restoring that object.
|
|
• Merely reading from a memory object is safe provided that you can
|
deal with any of the values that might appear in the object at a
|
time when the signal can be delivered. Keep in mind that
|
assignment to some data types requires more than one instruction,
|
which means that the handler could run “in the middle of” an
|
assignment to the variable if its type is not atomic. *Note Atomic
|
Data Access::.
|
|
• Merely writing into a memory object is safe as long as a sudden
|
change in the value, at any time when the handler might run, will
|
not disturb anything.
|
|
|
File: libc.info, Node: Atomic Data Access, Prev: Nonreentrancy, Up: Defining Handlers
|
|
24.4.7 Atomic Data Access and Signal Handling
|
---------------------------------------------
|
|
Whether the data in your application concerns atoms, or mere text, you
|
have to be careful about the fact that access to a single datum is not
|
necessarily "atomic". This means that it can take more than one
|
instruction to read or write a single object. In such cases, a signal
|
handler might be invoked in the middle of reading or writing the object.
|
|
There are three ways you can cope with this problem. You can use
|
data types that are always accessed atomically; you can carefully
|
arrange that nothing untoward happens if an access is interrupted, or
|
you can block all signals around any access that had better not be
|
interrupted (*note Blocking Signals::).
|
|
* Menu:
|
|
* Non-atomic Example:: A program illustrating interrupted access.
|
* Types: Atomic Types. Data types that guarantee no interruption.
|
* Usage: Atomic Usage. Proving that interruption is harmless.
|
|
|
File: libc.info, Node: Non-atomic Example, Next: Atomic Types, Up: Atomic Data Access
|
|
24.4.7.1 Problems with Non-Atomic Access
|
........................................
|
|
Here is an example which shows what can happen if a signal handler runs
|
in the middle of modifying a variable. (Interrupting the reading of a
|
variable can also lead to paradoxical results, but here we only show
|
writing.)
|
|
#include <signal.h>
|
#include <stdio.h>
|
|
volatile struct two_words { int a, b; } memory;
|
|
void
|
handler(int signum)
|
{
|
printf ("%d,%d\n", memory.a, memory.b);
|
alarm (1);
|
}
|
|
int
|
main (void)
|
{
|
static struct two_words zeros = { 0, 0 }, ones = { 1, 1 };
|
signal (SIGALRM, handler);
|
memory = zeros;
|
alarm (1);
|
while (1)
|
{
|
memory = zeros;
|
memory = ones;
|
}
|
}
|
|
This program fills ‘memory’ with zeros, ones, zeros, ones,
|
alternating forever; meanwhile, once per second, the alarm signal
|
handler prints the current contents. (Calling ‘printf’ in the handler
|
is safe in this program because it is certainly not being called outside
|
the handler when the signal happens.)
|
|
Clearly, this program can print a pair of zeros or a pair of ones.
|
But that’s not all it can do! On most machines, it takes several
|
instructions to store a new value in ‘memory’, and the value is stored
|
one word at a time. If the signal is delivered in between these
|
instructions, the handler might find that ‘memory.a’ is zero and
|
‘memory.b’ is one (or vice versa).
|
|
On some machines it may be possible to store a new value in ‘memory’
|
with just one instruction that cannot be interrupted. On these
|
machines, the handler will always print two zeros or two ones.
|
|
|
File: libc.info, Node: Atomic Types, Next: Atomic Usage, Prev: Non-atomic Example, Up: Atomic Data Access
|
|
24.4.7.2 Atomic Types
|
.....................
|
|
To avoid uncertainty about interrupting access to a variable, you can
|
use a particular data type for which access is always atomic:
|
‘sig_atomic_t’. Reading and writing this data type is guaranteed to
|
happen in a single instruction, so there’s no way for a handler to run
|
“in the middle” of an access.
|
|
The type ‘sig_atomic_t’ is always an integer data type, but which one
|
it is, and how many bits it contains, may vary from machine to machine.
|
|
-- Data Type: sig_atomic_t
|
|
This is an integer data type. Objects of this type are always
|
accessed atomically.
|
|
In practice, you can assume that ‘int’ is atomic. You can also
|
assume that pointer types are atomic; that is very convenient. Both of
|
these assumptions are true on all of the machines that the GNU C Library
|
supports and on all POSIX systems we know of.
|
|
|
File: libc.info, Node: Atomic Usage, Prev: Atomic Types, Up: Atomic Data Access
|
|
24.4.7.3 Atomic Usage Patterns
|
..............................
|
|
Certain patterns of access avoid any problem even if an access is
|
interrupted. For example, a flag which is set by the handler, and
|
tested and cleared by the main program from time to time, is always safe
|
even if access actually requires two instructions. To show that this is
|
so, we must consider each access that could be interrupted, and show
|
that there is no problem if it is interrupted.
|
|
An interrupt in the middle of testing the flag is safe because either
|
it’s recognized to be nonzero, in which case the precise value doesn’t
|
matter, or it will be seen to be nonzero the next time it’s tested.
|
|
An interrupt in the middle of clearing the flag is no problem because
|
either the value ends up zero, which is what happens if a signal comes
|
in just before the flag is cleared, or the value ends up nonzero, and
|
subsequent events occur as if the signal had come in just after the flag
|
was cleared. As long as the code handles both of these cases properly,
|
it can also handle a signal in the middle of clearing the flag. (This
|
is an example of the sort of reasoning you need to do to figure out
|
whether non-atomic usage is safe.)
|
|
Sometimes you can ensure uninterrupted access to one object by
|
protecting its use with another object, perhaps one whose type
|
guarantees atomicity. *Note Merged Signals::, for an example.
|
|
|
File: libc.info, Node: Interrupted Primitives, Next: Generating Signals, Prev: Defining Handlers, Up: Signal Handling
|
|
24.5 Primitives Interrupted by Signals
|
======================================
|
|
A signal can arrive and be handled while an I/O primitive such as ‘open’
|
or ‘read’ is waiting for an I/O device. If the signal handler returns,
|
the system faces the question: what should happen next?
|
|
POSIX specifies one approach: make the primitive fail right away.
|
The error code for this kind of failure is ‘EINTR’. This is flexible,
|
but usually inconvenient. Typically, POSIX applications that use signal
|
handlers must check for ‘EINTR’ after each library function that can
|
return it, in order to try the call again. Often programmers forget to
|
check, which is a common source of error.
|
|
The GNU C Library provides a convenient way to retry a call after a
|
temporary failure, with the macro ‘TEMP_FAILURE_RETRY’:
|
|
-- Macro: TEMP_FAILURE_RETRY (EXPRESSION)
|
|
This macro evaluates EXPRESSION once, and examines its value as
|
type ‘long int’. If the value equals ‘-1’, that indicates a
|
failure and ‘errno’ should be set to show what kind of failure. If
|
it fails and reports error code ‘EINTR’, ‘TEMP_FAILURE_RETRY’
|
evaluates it again, and over and over until the result is not a
|
temporary failure.
|
|
The value returned by ‘TEMP_FAILURE_RETRY’ is whatever value
|
EXPRESSION produced.
|
|
BSD avoids ‘EINTR’ entirely and provides a more convenient approach:
|
to restart the interrupted primitive, instead of making it fail. If you
|
choose this approach, you need not be concerned with ‘EINTR’.
|
|
You can choose either approach with the GNU C Library. If you use
|
‘sigaction’ to establish a signal handler, you can specify how that
|
handler should behave. If you specify the ‘SA_RESTART’ flag, return
|
from that handler will resume a primitive; otherwise, return from that
|
handler will cause ‘EINTR’. *Note Flags for Sigaction::.
|
|
Another way to specify the choice is with the ‘siginterrupt’
|
function. *Note BSD Signal Handling::.
|
|
When you don’t specify with ‘sigaction’ or ‘siginterrupt’ what a
|
particular handler should do, it uses a default choice. The default
|
choice in the GNU C Library is to make primitives fail with ‘EINTR’.
|
|
The description of each primitive affected by this issue lists
|
‘EINTR’ among the error codes it can return.
|
|
There is one situation where resumption never happens no matter which
|
choice you make: when a data-transfer function such as ‘read’ or ‘write’
|
is interrupted by a signal after transferring part of the data. In this
|
case, the function returns the number of bytes already transferred,
|
indicating partial success.
|
|
This might at first appear to cause unreliable behavior on
|
record-oriented devices (including datagram sockets; *note Datagrams::),
|
where splitting one ‘read’ or ‘write’ into two would read or write two
|
records. Actually, there is no problem, because interruption after a
|
partial transfer cannot happen on such devices; they always transfer an
|
entire record in one burst, with no waiting once data transfer has
|
started.
|
|
|
File: libc.info, Node: Generating Signals, Next: Blocking Signals, Prev: Interrupted Primitives, Up: Signal Handling
|
|
24.6 Generating Signals
|
=======================
|
|
Besides signals that are generated as a result of a hardware trap or
|
interrupt, your program can explicitly send signals to itself or to
|
another process.
|
|
* Menu:
|
|
* Signaling Yourself:: A process can send a signal to itself.
|
* Signaling Another Process:: Send a signal to another process.
|
* Permission for kill:: Permission for using ‘kill’.
|
* Kill Example:: Using ‘kill’ for Communication.
|
|
|
File: libc.info, Node: Signaling Yourself, Next: Signaling Another Process, Up: Generating Signals
|
|
24.6.1 Signaling Yourself
|
-------------------------
|
|
A process can send itself a signal with the ‘raise’ function. This
|
function is declared in ‘signal.h’.
|
|
-- Function: int raise (int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘raise’ function sends the signal SIGNUM to the calling
|
process. It returns zero if successful and a nonzero value if it
|
fails. About the only reason for failure would be if the value of
|
SIGNUM is invalid.
|
|
-- Function: int gsignal (int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘gsignal’ function does the same thing as ‘raise’; it is
|
provided only for compatibility with SVID.
|
|
One convenient use for ‘raise’ is to reproduce the default behavior
|
of a signal that you have trapped. For instance, suppose a user of your
|
program types the SUSP character (usually ‘C-z’; *note Special
|
Characters::) to send it an interactive stop signal (‘SIGTSTP’), and you
|
want to clean up some internal data buffers before stopping. You might
|
set this up like this:
|
|
#include <signal.h>
|
|
/* When a stop signal arrives, set the action back to the default
|
and then resend the signal after doing cleanup actions. */
|
|
void
|
tstp_handler (int sig)
|
{
|
signal (SIGTSTP, SIG_DFL);
|
/* Do cleanup actions here. */
|
…
|
raise (SIGTSTP);
|
}
|
|
/* When the process is continued again, restore the signal handler. */
|
|
void
|
cont_handler (int sig)
|
{
|
signal (SIGCONT, cont_handler);
|
signal (SIGTSTP, tstp_handler);
|
}
|
|
/* Enable both handlers during program initialization. */
|
|
int
|
main (void)
|
{
|
signal (SIGCONT, cont_handler);
|
signal (SIGTSTP, tstp_handler);
|
…
|
}
|
|
*Portability note:* ‘raise’ was invented by the ISO C committee.
|
Older systems may not support it, so using ‘kill’ may be more portable.
|
*Note Signaling Another Process::.
|
|
|
File: libc.info, Node: Signaling Another Process, Next: Permission for kill, Prev: Signaling Yourself, Up: Generating Signals
|
|
24.6.2 Signaling Another Process
|
--------------------------------
|
|
The ‘kill’ function can be used to send a signal to another process. In
|
spite of its name, it can be used for a lot of things other than causing
|
a process to terminate. Some examples of situations where you might
|
want to send signals between processes are:
|
|
• A parent process starts a child to perform a task—perhaps having
|
the child running an infinite loop—and then terminates the child
|
when the task is no longer needed.
|
|
• A process executes as part of a group, and needs to terminate or
|
notify the other processes in the group when an error or other
|
event occurs.
|
|
• Two processes need to synchronize while working together.
|
|
This section assumes that you know a little bit about how processes
|
work. For more information on this subject, see *note Processes::.
|
|
The ‘kill’ function is declared in ‘signal.h’.
|
|
-- Function: int kill (pid_t PID, int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘kill’ function sends the signal SIGNUM to the process or
|
process group specified by PID. Besides the signals listed in
|
*note Standard Signals::, SIGNUM can also have a value of zero to
|
check the validity of the PID.
|
|
The PID specifies the process or process group to receive the
|
signal:
|
|
‘PID > 0’
|
The process whose identifier is PID. (On Linux, the signal is
|
sent to the entire process even if PID is a thread ID distinct
|
from the process ID.)
|
|
‘PID == 0’
|
All processes in the same process group as the sender.
|
|
‘PID < -1’
|
The process group whose identifier is −PID.
|
|
‘PID == -1’
|
If the process is privileged, send the signal to all processes
|
except for some special system processes. Otherwise, send the
|
signal to all processes with the same effective user ID.
|
|
A process can send a signal to itself with a call like
|
‘kill (getpid(), SIGNUM)’. If ‘kill’ is used by a process to send
|
a signal to itself, and the signal is not blocked, then ‘kill’
|
delivers at least one signal (which might be some other pending
|
unblocked signal instead of the signal SIGNUM) to that process
|
before it returns.
|
|
The return value from ‘kill’ is zero if the signal can be sent
|
successfully. Otherwise, no signal is sent, and a value of ‘-1’ is
|
returned. If PID specifies sending a signal to several processes,
|
‘kill’ succeeds if it can send the signal to at least one of them.
|
There’s no way you can tell which of the processes got the signal
|
or whether all of them did.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EINVAL’
|
The SIGNUM argument is an invalid or unsupported number.
|
|
‘EPERM’
|
You do not have the privilege to send a signal to the process
|
or any of the processes in the process group named by PID.
|
|
‘ESRCH’
|
The PID argument does not refer to an existing process or
|
group.
|
|
-- Function: int tgkill (pid_t PID, pid_t TID, int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘tgkill’ function sends the signal SIGNUM to the thread or
|
process with ID TID, like the ‘kill’ function, but only if the
|
process ID of the thread TID is equal to PID. If the target thread
|
belongs to another process, the function fails with ‘ESRCH’.
|
|
The ‘tgkill’ function can be used to avoid sending a signal to a
|
thread in the wrong process if the caller ensures that the passed
|
PID value is not reused by the kernel (for example, if it is the
|
process ID of the current process, as returned by ‘getpid’).
|
|
-- Function: int killpg (int PGID, int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This is similar to ‘kill’, but sends signal SIGNUM to the process
|
group PGID. This function is provided for compatibility with BSD;
|
using ‘kill’ to do this is more portable.
|
|
As a simple example of ‘kill’, the call ‘kill (getpid (), SIG)’ has
|
the same effect as ‘raise (SIG)’.
|
|
|
File: libc.info, Node: Permission for kill, Next: Kill Example, Prev: Signaling Another Process, Up: Generating Signals
|
|
24.6.3 Permission for using ‘kill’
|
----------------------------------
|
|
There are restrictions that prevent you from using ‘kill’ to send
|
signals to any random process. These are intended to prevent antisocial
|
behavior such as arbitrarily killing off processes belonging to another
|
user. In typical use, ‘kill’ is used to pass signals between parent,
|
child, and sibling processes, and in these situations you normally do
|
have permission to send signals. The only common exception is when you
|
run a setuid program in a child process; if the program changes its real
|
UID as well as its effective UID, you may not have permission to send a
|
signal. The ‘su’ program does this.
|
|
Whether a process has permission to send a signal to another process
|
is determined by the user IDs of the two processes. This concept is
|
discussed in detail in *note Process Persona::.
|
|
Generally, for a process to be able to send a signal to another
|
process, either the sending process must belong to a privileged user
|
(like ‘root’), or the real or effective user ID of the sending process
|
must match the real or effective user ID of the receiving process. If
|
the receiving process has changed its effective user ID from the
|
set-user-ID mode bit on its process image file, then the owner of the
|
process image file is used in place of its current effective user ID. In
|
some implementations, a parent process might be able to send signals to
|
a child process even if the user ID’s don’t match, and other
|
implementations might enforce other restrictions.
|
|
The ‘SIGCONT’ signal is a special case. It can be sent if the sender
|
is part of the same session as the receiver, regardless of user IDs.
|
|
|
File: libc.info, Node: Kill Example, Prev: Permission for kill, Up: Generating Signals
|
|
24.6.4 Using ‘kill’ for Communication
|
-------------------------------------
|
|
Here is a longer example showing how signals can be used for
|
interprocess communication. This is what the ‘SIGUSR1’ and ‘SIGUSR2’
|
signals are provided for. Since these signals are fatal by default, the
|
process that is supposed to receive them must trap them through ‘signal’
|
or ‘sigaction’.
|
|
In this example, a parent process forks a child process and then
|
waits for the child to complete its initialization. The child process
|
tells the parent when it is ready by sending it a ‘SIGUSR1’ signal,
|
using the ‘kill’ function.
|
|
|
#include <signal.h>
|
#include <stdio.h>
|
#include <sys/types.h>
|
#include <unistd.h>
|
|
/* When a ‘SIGUSR1’ signal arrives, set this variable. */
|
volatile sig_atomic_t usr_interrupt = 0;
|
|
void
|
synch_signal (int sig)
|
{
|
usr_interrupt = 1;
|
}
|
|
/* The child process executes this function. */
|
void
|
child_function (void)
|
{
|
/* Perform initialization. */
|
printf ("I'm here!!! My pid is %d.\n", (int) getpid ());
|
|
/* Let parent know you’re done. */
|
kill (getppid (), SIGUSR1);
|
|
/* Continue with execution. */
|
puts ("Bye, now....");
|
exit (0);
|
}
|
|
int
|
main (void)
|
{
|
struct sigaction usr_action;
|
sigset_t block_mask;
|
pid_t child_id;
|
|
/* Establish the signal handler. */
|
sigfillset (&block_mask);
|
usr_action.sa_handler = synch_signal;
|
usr_action.sa_mask = block_mask;
|
usr_action.sa_flags = 0;
|
sigaction (SIGUSR1, &usr_action, NULL);
|
|
/* Create the child process. */
|
child_id = fork ();
|
if (child_id == 0)
|
child_function (); /* Does not return. */
|
|
/* Busy wait for the child to send a signal. */
|
while (!usr_interrupt)
|
;
|
|
/* Now continue execution. */
|
puts ("That's all, folks!");
|
|
return 0;
|
}
|
|
This example uses a busy wait, which is bad, because it wastes CPU
|
cycles that other programs could otherwise use. It is better to ask the
|
system to wait until the signal arrives. See the example in *note
|
Waiting for a Signal::.
|
|
|
File: libc.info, Node: Blocking Signals, Next: Waiting for a Signal, Prev: Generating Signals, Up: Signal Handling
|
|
24.7 Blocking Signals
|
=====================
|
|
Blocking a signal means telling the operating system to hold it and
|
deliver it later. Generally, a program does not block signals
|
indefinitely—it might as well ignore them by setting their actions to
|
‘SIG_IGN’. But it is useful to block signals briefly, to prevent them
|
from interrupting sensitive operations. For instance:
|
|
• You can use the ‘sigprocmask’ function to block signals while you
|
modify global variables that are also modified by the handlers for
|
these signals.
|
|
• You can set ‘sa_mask’ in your ‘sigaction’ call to block certain
|
signals while a particular signal handler runs. This way, the
|
signal handler can run without being interrupted itself by signals.
|
|
* Menu:
|
|
* Why Block:: The purpose of blocking signals.
|
* Signal Sets:: How to specify which signals to
|
block.
|
* Process Signal Mask:: Blocking delivery of signals to your
|
process during normal execution.
|
* Testing for Delivery:: Blocking to Test for Delivery of
|
a Signal.
|
* Blocking for Handler:: Blocking additional signals while a
|
handler is being run.
|
* Checking for Pending Signals:: Checking for Pending Signals
|
* Remembering a Signal:: How you can get almost the same
|
effect as blocking a signal, by
|
handling it and setting a flag
|
to be tested later.
|
|
|
File: libc.info, Node: Why Block, Next: Signal Sets, Up: Blocking Signals
|
|
24.7.1 Why Blocking Signals is Useful
|
-------------------------------------
|
|
Temporary blocking of signals with ‘sigprocmask’ gives you a way to
|
prevent interrupts during critical parts of your code. If signals
|
arrive in that part of the program, they are delivered later, after you
|
unblock them.
|
|
One example where this is useful is for sharing data between a signal
|
handler and the rest of the program. If the type of the data is not
|
‘sig_atomic_t’ (*note Atomic Data Access::), then the signal handler
|
could run when the rest of the program has only half finished reading or
|
writing the data. This would lead to confusing consequences.
|
|
To make the program reliable, you can prevent the signal handler from
|
running while the rest of the program is examining or modifying that
|
data—by blocking the appropriate signal around the parts of the program
|
that touch the data.
|
|
Blocking signals is also necessary when you want to perform a certain
|
action only if a signal has not arrived. Suppose that the handler for
|
the signal sets a flag of type ‘sig_atomic_t’; you would like to test
|
the flag and perform the action if the flag is not set. This is
|
unreliable. Suppose the signal is delivered immediately after you test
|
the flag, but before the consequent action: then the program will
|
perform the action even though the signal has arrived.
|
|
The only way to test reliably for whether a signal has yet arrived is
|
to test while the signal is blocked.
|
|
|
File: libc.info, Node: Signal Sets, Next: Process Signal Mask, Prev: Why Block, Up: Blocking Signals
|
|
24.7.2 Signal Sets
|
------------------
|
|
All of the signal blocking functions use a data structure called a
|
"signal set" to specify what signals are affected. Thus, every activity
|
involves two stages: creating the signal set, and then passing it as an
|
argument to a library function.
|
|
These facilities are declared in the header file ‘signal.h’.
|
|
-- Data Type: sigset_t
|
|
The ‘sigset_t’ data type is used to represent a signal set.
|
Internally, it may be implemented as either an integer or structure
|
type.
|
|
For portability, use only the functions described in this section
|
to initialize, change, and retrieve information from ‘sigset_t’
|
objects—don’t try to manipulate them directly.
|
|
There are two ways to initialize a signal set. You can initially
|
specify it to be empty with ‘sigemptyset’ and then add specified signals
|
individually. Or you can specify it to be full with ‘sigfillset’ and
|
then delete specified signals individually.
|
|
You must always initialize the signal set with one of these two
|
functions before using it in any other way. Don’t try to set all the
|
signals explicitly because the ‘sigset_t’ object might include some
|
other information (like a version field) that needs to be initialized as
|
well. (In addition, it’s not wise to put into your program an
|
assumption that the system has no signals aside from the ones you know
|
about.)
|
|
-- Function: int sigemptyset (sigset_t *SET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function initializes the signal set SET to exclude all of the
|
defined signals. It always returns ‘0’.
|
|
-- Function: int sigfillset (sigset_t *SET)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function initializes the signal set SET to include all of the
|
defined signals. Again, the return value is ‘0’.
|
|
-- Function: int sigaddset (sigset_t *SET, int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function adds the signal SIGNUM to the signal set SET. All
|
‘sigaddset’ does is modify SET; it does not block or unblock any
|
signals.
|
|
The return value is ‘0’ on success and ‘-1’ on failure. The
|
following ‘errno’ error condition is defined for this function:
|
|
‘EINVAL’
|
The SIGNUM argument doesn’t specify a valid signal.
|
|
-- Function: int sigdelset (sigset_t *SET, int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function removes the signal SIGNUM from the signal set SET.
|
All ‘sigdelset’ does is modify SET; it does not block or unblock
|
any signals. The return value and error conditions are the same as
|
for ‘sigaddset’.
|
|
Finally, there is a function to test what signals are in a signal
|
set:
|
|
-- Function: int sigismember (const sigset_t *SET, int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘sigismember’ function tests whether the signal SIGNUM is a
|
member of the signal set SET. It returns ‘1’ if the signal is in
|
the set, ‘0’ if not, and ‘-1’ if there is an error.
|
|
The following ‘errno’ error condition is defined for this function:
|
|
‘EINVAL’
|
The SIGNUM argument doesn’t specify a valid signal.
|
|
|
File: libc.info, Node: Process Signal Mask, Next: Testing for Delivery, Prev: Signal Sets, Up: Blocking Signals
|
|
24.7.3 Process Signal Mask
|
--------------------------
|
|
The collection of signals that are currently blocked is called the
|
"signal mask". Each process has its own signal mask. When you create a
|
new process (*note Creating a Process::), it inherits its parent’s mask.
|
You can block or unblock signals with total flexibility by modifying the
|
signal mask.
|
|
The prototype for the ‘sigprocmask’ function is in ‘signal.h’.
|
|
Note that you must not use ‘sigprocmask’ in multi-threaded processes,
|
because each thread has its own signal mask and there is no single
|
process signal mask. According to POSIX, the behavior of ‘sigprocmask’
|
in a multi-threaded process is “unspecified”. Instead, use
|
‘pthread_sigmask’.
|
|
-- Function: int sigprocmask (int HOW, const sigset_t *restrict SET,
|
sigset_t *restrict OLDSET)
|
|
Preliminary: | MT-Unsafe race:sigprocmask/bsd(SIG_UNBLOCK) |
|
AS-Unsafe lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘sigprocmask’ function is used to examine or change the calling
|
process’s signal mask. The HOW argument determines how the signal
|
mask is changed, and must be one of the following values:
|
|
‘SIG_BLOCK’
|
|
Block the signals in ‘set’—add them to the existing mask. In
|
other words, the new mask is the union of the existing mask
|
and SET.
|
|
‘SIG_UNBLOCK’
|
|
Unblock the signals in SET—remove them from the existing mask.
|
|
‘SIG_SETMASK’
|
|
Use SET for the mask; ignore the previous value of the mask.
|
|
The last argument, OLDSET, is used to return information about the
|
old process signal mask. If you just want to change the mask
|
without looking at it, pass a null pointer as the OLDSET argument.
|
Similarly, if you want to know what’s in the mask without changing
|
it, pass a null pointer for SET (in this case the HOW argument is
|
not significant). The OLDSET argument is often used to remember
|
the previous signal mask in order to restore it later. (Since the
|
signal mask is inherited over ‘fork’ and ‘exec’ calls, you can’t
|
predict what its contents are when your program starts running.)
|
|
If invoking ‘sigprocmask’ causes any pending signals to be
|
unblocked, at least one of those signals is delivered to the
|
process before ‘sigprocmask’ returns. The order in which pending
|
signals are delivered is not specified, but you can control the
|
order explicitly by making multiple ‘sigprocmask’ calls to unblock
|
various signals one at a time.
|
|
The ‘sigprocmask’ function returns ‘0’ if successful, and ‘-1’ to
|
indicate an error. The following ‘errno’ error conditions are
|
defined for this function:
|
|
‘EINVAL’
|
The HOW argument is invalid.
|
|
You can’t block the ‘SIGKILL’ and ‘SIGSTOP’ signals, but if the
|
signal set includes these, ‘sigprocmask’ just ignores them instead
|
of returning an error status.
|
|
Remember, too, that blocking program error signals such as ‘SIGFPE’
|
leads to undesirable results for signals generated by an actual
|
program error (as opposed to signals sent with ‘raise’ or ‘kill’).
|
This is because your program may be too broken to be able to
|
continue executing to a point where the signal is unblocked again.
|
*Note Program Error Signals::.
|
|
|
File: libc.info, Node: Testing for Delivery, Next: Blocking for Handler, Prev: Process Signal Mask, Up: Blocking Signals
|
|
24.7.4 Blocking to Test for Delivery of a Signal
|
------------------------------------------------
|
|
Now for a simple example. Suppose you establish a handler for ‘SIGALRM’
|
signals that sets a flag whenever a signal arrives, and your main
|
program checks this flag from time to time and then resets it. You can
|
prevent additional ‘SIGALRM’ signals from arriving in the meantime by
|
wrapping the critical part of the code with calls to ‘sigprocmask’, like
|
this:
|
|
/* This variable is set by the SIGALRM signal handler. */
|
volatile sig_atomic_t flag = 0;
|
|
int
|
main (void)
|
{
|
sigset_t block_alarm;
|
|
…
|
|
/* Initialize the signal mask. */
|
sigemptyset (&block_alarm);
|
sigaddset (&block_alarm, SIGALRM);
|
|
while (1)
|
{
|
/* Check if a signal has arrived; if so, reset the flag. */
|
sigprocmask (SIG_BLOCK, &block_alarm, NULL);
|
if (flag)
|
{
|
ACTIONS-IF-NOT-ARRIVED
|
flag = 0;
|
}
|
sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);
|
|
…
|
}
|
}
|
|
|
File: libc.info, Node: Blocking for Handler, Next: Checking for Pending Signals, Prev: Testing for Delivery, Up: Blocking Signals
|
|
24.7.5 Blocking Signals for a Handler
|
-------------------------------------
|
|
When a signal handler is invoked, you usually want it to be able to
|
finish without being interrupted by another signal. From the moment the
|
handler starts until the moment it finishes, you must block signals that
|
might confuse it or corrupt its data.
|
|
When a handler function is invoked on a signal, that signal is
|
automatically blocked (in addition to any other signals that are already
|
in the process’s signal mask) during the time the handler is running.
|
If you set up a handler for ‘SIGTSTP’, for instance, then the arrival of
|
that signal forces further ‘SIGTSTP’ signals to wait during the
|
execution of the handler.
|
|
However, by default, other kinds of signals are not blocked; they can
|
arrive during handler execution.
|
|
The reliable way to block other kinds of signals during the execution
|
of the handler is to use the ‘sa_mask’ member of the ‘sigaction’
|
structure.
|
|
Here is an example:
|
|
#include <signal.h>
|
#include <stddef.h>
|
|
void catch_stop ();
|
|
void
|
install_handler (void)
|
{
|
struct sigaction setup_action;
|
sigset_t block_mask;
|
|
sigemptyset (&block_mask);
|
/* Block other terminal-generated signals while handler runs. */
|
sigaddset (&block_mask, SIGINT);
|
sigaddset (&block_mask, SIGQUIT);
|
setup_action.sa_handler = catch_stop;
|
setup_action.sa_mask = block_mask;
|
setup_action.sa_flags = 0;
|
sigaction (SIGTSTP, &setup_action, NULL);
|
}
|
|
This is more reliable than blocking the other signals explicitly in
|
the code for the handler. If you block signals explicitly in the
|
handler, you can’t avoid at least a short interval at the beginning of
|
the handler where they are not yet blocked.
|
|
You cannot remove signals from the process’s current mask using this
|
mechanism. However, you can make calls to ‘sigprocmask’ within your
|
handler to block or unblock signals as you wish.
|
|
In any case, when the handler returns, the system restores the mask
|
that was in place before the handler was entered. If any signals that
|
become unblocked by this restoration are pending, the process will
|
receive those signals immediately, before returning to the code that was
|
interrupted.
|
|
|
File: libc.info, Node: Checking for Pending Signals, Next: Remembering a Signal, Prev: Blocking for Handler, Up: Blocking Signals
|
|
24.7.6 Checking for Pending Signals
|
-----------------------------------
|
|
You can find out which signals are pending at any time by calling
|
‘sigpending’. This function is declared in ‘signal.h’.
|
|
-- Function: int sigpending (sigset_t *SET)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
|
| *Note POSIX Safety Concepts::.
|
|
The ‘sigpending’ function stores information about pending signals
|
in SET. If there is a pending signal that is blocked from
|
delivery, then that signal is a member of the returned set. (You
|
can test whether a particular signal is a member of this set using
|
‘sigismember’; see *note Signal Sets::.)
|
|
The return value is ‘0’ if successful, and ‘-1’ on failure.
|
|
Testing whether a signal is pending is not often useful. Testing
|
when that signal is not blocked is almost certainly bad design.
|
|
Here is an example.
|
|
#include <signal.h>
|
#include <stddef.h>
|
|
sigset_t base_mask, waiting_mask;
|
|
sigemptyset (&base_mask);
|
sigaddset (&base_mask, SIGINT);
|
sigaddset (&base_mask, SIGTSTP);
|
|
/* Block user interrupts while doing other processing. */
|
sigprocmask (SIG_SETMASK, &base_mask, NULL);
|
…
|
|
/* After a while, check to see whether any signals are pending. */
|
sigpending (&waiting_mask);
|
if (sigismember (&waiting_mask, SIGINT)) {
|
/* User has tried to kill the process. */
|
}
|
else if (sigismember (&waiting_mask, SIGTSTP)) {
|
/* User has tried to stop the process. */
|
}
|
|
Remember that if there is a particular signal pending for your
|
process, additional signals of that same type that arrive in the
|
meantime might be discarded. For example, if a ‘SIGINT’ signal is
|
pending when another ‘SIGINT’ signal arrives, your program will probably
|
only see one of them when you unblock this signal.
|
|
*Portability Note:* The ‘sigpending’ function is new in POSIX.1.
|
Older systems have no equivalent facility.
|
|
|
File: libc.info, Node: Remembering a Signal, Prev: Checking for Pending Signals, Up: Blocking Signals
|
|
24.7.7 Remembering a Signal to Act On Later
|
-------------------------------------------
|
|
Instead of blocking a signal using the library facilities, you can get
|
almost the same results by making the handler set a flag to be tested
|
later, when you “unblock”. Here is an example:
|
|
/* If this flag is nonzero, don’t handle the signal right away. */
|
volatile sig_atomic_t signal_pending;
|
|
/* This is nonzero if a signal arrived and was not handled. */
|
volatile sig_atomic_t defer_signal;
|
|
void
|
handler (int signum)
|
{
|
if (defer_signal)
|
signal_pending = signum;
|
else
|
… /* “Really” handle the signal. */
|
}
|
|
…
|
|
void
|
update_mumble (int frob)
|
{
|
/* Prevent signals from having immediate effect. */
|
defer_signal++;
|
/* Now update ‘mumble’, without worrying about interruption. */
|
mumble.a = 1;
|
mumble.b = hack ();
|
mumble.c = frob;
|
/* We have updated ‘mumble’. Handle any signal that came in. */
|
defer_signal--;
|
if (defer_signal == 0 && signal_pending != 0)
|
raise (signal_pending);
|
}
|
|
Note how the particular signal that arrives is stored in
|
‘signal_pending’. That way, we can handle several types of inconvenient
|
signals with the same mechanism.
|
|
We increment and decrement ‘defer_signal’ so that nested critical
|
sections will work properly; thus, if ‘update_mumble’ were called with
|
‘signal_pending’ already nonzero, signals would be deferred not only
|
within ‘update_mumble’, but also within the caller. This is also why we
|
do not check ‘signal_pending’ if ‘defer_signal’ is still nonzero.
|
|
The incrementing and decrementing of ‘defer_signal’ each require more
|
than one instruction; it is possible for a signal to happen in the
|
middle. But that does not cause any problem. If the signal happens
|
early enough to see the value from before the increment or decrement,
|
that is equivalent to a signal which came before the beginning of the
|
increment or decrement, which is a case that works properly.
|
|
It is absolutely vital to decrement ‘defer_signal’ before testing
|
‘signal_pending’, because this avoids a subtle bug. If we did these
|
things in the other order, like this,
|
|
if (defer_signal == 1 && signal_pending != 0)
|
raise (signal_pending);
|
defer_signal--;
|
|
then a signal arriving in between the ‘if’ statement and the decrement
|
would be effectively “lost” for an indefinite amount of time. The
|
handler would merely set ‘defer_signal’, but the program having already
|
tested this variable, it would not test the variable again.
|
|
Bugs like these are called "timing errors". They are especially bad
|
because they happen only rarely and are nearly impossible to reproduce.
|
You can’t expect to find them with a debugger as you would find a
|
reproducible bug. So it is worth being especially careful to avoid
|
them.
|
|
(You would not be tempted to write the code in this order, given the
|
use of ‘defer_signal’ as a counter which must be tested along with
|
‘signal_pending’. After all, testing for zero is cleaner than testing
|
for one. But if you did not use ‘defer_signal’ as a counter, and gave
|
it values of zero and one only, then either order might seem equally
|
simple. This is a further advantage of using a counter for
|
‘defer_signal’: it will reduce the chance you will write the code in the
|
wrong order and create a subtle bug.)
|
|
|
File: libc.info, Node: Waiting for a Signal, Next: Signal Stack, Prev: Blocking Signals, Up: Signal Handling
|
|
24.8 Waiting for a Signal
|
=========================
|
|
If your program is driven by external events, or uses signals for
|
synchronization, then when it has nothing to do it should probably wait
|
until a signal arrives.
|
|
* Menu:
|
|
* Using Pause:: The simple way, using ‘pause’.
|
* Pause Problems:: Why the simple way is often not very good.
|
* Sigsuspend:: Reliably waiting for a specific signal.
|
|
|
File: libc.info, Node: Using Pause, Next: Pause Problems, Up: Waiting for a Signal
|
|
24.8.1 Using ‘pause’
|
--------------------
|
|
The simple way to wait until a signal arrives is to call ‘pause’.
|
Please read about its disadvantages, in the following section, before
|
you use it.
|
|
-- Function: int pause (void)
|
|
Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe
|
lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::.
|
|
The ‘pause’ function suspends program execution until a signal
|
arrives whose action is either to execute a handler function, or to
|
terminate the process.
|
|
If the signal causes a handler function to be executed, then
|
‘pause’ returns. This is considered an unsuccessful return (since
|
“successful” behavior would be to suspend the program forever), so
|
the return value is ‘-1’. Even if you specify that other
|
primitives should resume when a system handler returns (*note
|
Interrupted Primitives::), this has no effect on ‘pause’; it always
|
fails when a signal is handled.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EINTR’
|
The function was interrupted by delivery of a signal.
|
|
If the signal causes program termination, ‘pause’ doesn’t return
|
(obviously).
|
|
This function is a cancellation point in multithreaded programs.
|
This is a problem if the thread allocates some resources (like
|
memory, file descriptors, semaphores or whatever) at the time
|
‘pause’ is called. If the thread gets cancelled these resources
|
stay allocated until the program ends. To avoid this calls to
|
‘pause’ should be protected using cancellation handlers.
|
|
The ‘pause’ function is declared in ‘unistd.h’.
|
|
|
File: libc.info, Node: Pause Problems, Next: Sigsuspend, Prev: Using Pause, Up: Waiting for a Signal
|
|
24.8.2 Problems with ‘pause’
|
----------------------------
|
|
The simplicity of ‘pause’ can conceal serious timing errors that can
|
make a program hang mysteriously.
|
|
It is safe to use ‘pause’ if the real work of your program is done by
|
the signal handlers themselves, and the “main program” does nothing but
|
call ‘pause’. Each time a signal is delivered, the handler will do the
|
next batch of work that is to be done, and then return, so that the main
|
loop of the program can call ‘pause’ again.
|
|
You can’t safely use ‘pause’ to wait until one more signal arrives,
|
and then resume real work. Even if you arrange for the signal handler
|
to cooperate by setting a flag, you still can’t use ‘pause’ reliably.
|
Here is an example of this problem:
|
|
/* ‘usr_interrupt’ is set by the signal handler. */
|
if (!usr_interrupt)
|
pause ();
|
|
/* Do work once the signal arrives. */
|
…
|
|
This has a bug: the signal could arrive after the variable
|
‘usr_interrupt’ is checked, but before the call to ‘pause’. If no
|
further signals arrive, the process would never wake up again.
|
|
You can put an upper limit on the excess waiting by using ‘sleep’ in
|
a loop, instead of using ‘pause’. (*Note Sleeping::, for more about
|
‘sleep’.) Here is what this looks like:
|
|
/* ‘usr_interrupt’ is set by the signal handler.
|
while (!usr_interrupt)
|
sleep (1);
|
|
/* Do work once the signal arrives. */
|
…
|
|
For some purposes, that is good enough. But with a little more
|
complexity, you can wait reliably until a particular signal handler is
|
run, using ‘sigsuspend’. *Note Sigsuspend::.
|
|
|
File: libc.info, Node: Sigsuspend, Prev: Pause Problems, Up: Waiting for a Signal
|
|
24.8.3 Using ‘sigsuspend’
|
-------------------------
|
|
The clean and reliable way to wait for a signal to arrive is to block it
|
and then use ‘sigsuspend’. By using ‘sigsuspend’ in a loop, you can
|
wait for certain kinds of signals, while letting other kinds of signals
|
be handled by their handlers.
|
|
-- Function: int sigsuspend (const sigset_t *SET)
|
|
Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe
|
lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::.
|
|
This function replaces the process’s signal mask with SET and then
|
suspends the process until a signal is delivered whose action is
|
either to terminate the process or invoke a signal handling
|
function. In other words, the program is effectively suspended
|
until one of the signals that is not a member of SET arrives.
|
|
If the process is woken up by delivery of a signal that invokes a
|
handler function, and the handler function returns, then
|
‘sigsuspend’ also returns.
|
|
The mask remains SET only as long as ‘sigsuspend’ is waiting. The
|
function ‘sigsuspend’ always restores the previous signal mask when
|
it returns.
|
|
The return value and error conditions are the same as for ‘pause’.
|
|
With ‘sigsuspend’, you can replace the ‘pause’ or ‘sleep’ loop in the
|
previous section with something completely reliable:
|
|
sigset_t mask, oldmask;
|
|
…
|
|
/* Set up the mask of signals to temporarily block. */
|
sigemptyset (&mask);
|
sigaddset (&mask, SIGUSR1);
|
|
…
|
|
/* Wait for a signal to arrive. */
|
sigprocmask (SIG_BLOCK, &mask, &oldmask);
|
while (!usr_interrupt)
|
sigsuspend (&oldmask);
|
sigprocmask (SIG_UNBLOCK, &mask, NULL);
|
|
This last piece of code is a little tricky. The key point to
|
remember here is that when ‘sigsuspend’ returns, it resets the process’s
|
signal mask to the original value, the value from before the call to
|
‘sigsuspend’—in this case, the ‘SIGUSR1’ signal is once again blocked.
|
The second call to ‘sigprocmask’ is necessary to explicitly unblock this
|
signal.
|
|
One other point: you may be wondering why the ‘while’ loop is
|
necessary at all, since the program is apparently only waiting for one
|
‘SIGUSR1’ signal. The answer is that the mask passed to ‘sigsuspend’
|
permits the process to be woken up by the delivery of other kinds of
|
signals, as well—for example, job control signals. If the process is
|
woken up by a signal that doesn’t set ‘usr_interrupt’, it just suspends
|
itself again until the “right” kind of signal eventually arrives.
|
|
This technique takes a few more lines of preparation, but that is
|
needed just once for each kind of wait criterion you want to use. The
|
code that actually waits is just four lines.
|
|
|
File: libc.info, Node: Signal Stack, Next: BSD Signal Handling, Prev: Waiting for a Signal, Up: Signal Handling
|
|
24.9 Using a Separate Signal Stack
|
==================================
|
|
A signal stack is a special area of memory to be used as the execution
|
stack during signal handlers. It should be fairly large, to avoid any
|
danger that it will overflow in turn; the macro ‘SIGSTKSZ’ is defined to
|
a canonical size for signal stacks. You can use ‘malloc’ to allocate
|
the space for the stack. Then call ‘sigaltstack’ or ‘sigstack’ to tell
|
the system to use that space for the signal stack.
|
|
You don’t need to write signal handlers differently in order to use a
|
signal stack. Switching from one stack to the other happens
|
automatically. (Some non-GNU debuggers on some machines may get
|
confused if you examine a stack trace while a handler that uses the
|
signal stack is running.)
|
|
There are two interfaces for telling the system to use a separate
|
signal stack. ‘sigstack’ is the older interface, which comes from 4.2
|
BSD. ‘sigaltstack’ is the newer interface, and comes from 4.4 BSD. The
|
‘sigaltstack’ interface has the advantage that it does not require your
|
program to know which direction the stack grows, which depends on the
|
specific machine and operating system.
|
|
-- Data Type: stack_t
|
|
This structure describes a signal stack. It contains the following
|
members:
|
|
‘void *ss_sp’
|
This points to the base of the signal stack.
|
|
‘size_t ss_size’
|
This is the size (in bytes) of the signal stack which ‘ss_sp’
|
points to. You should set this to however much space you
|
allocated for the stack.
|
|
There are two macros defined in ‘signal.h’ that you should use
|
in calculating this size:
|
|
‘SIGSTKSZ’
|
This is the canonical size for a signal stack. It is
|
judged to be sufficient for normal uses.
|
|
‘MINSIGSTKSZ’
|
This is the amount of signal stack space the operating
|
system needs just to implement signal delivery. The size
|
of a signal stack *must* be greater than this.
|
|
For most cases, just using ‘SIGSTKSZ’ for ‘ss_size’ is
|
sufficient. But if you know how much stack space your
|
program’s signal handlers will need, you may want to use
|
a different size. In this case, you should allocate
|
‘MINSIGSTKSZ’ additional bytes for the signal stack and
|
increase ‘ss_size’ accordingly.
|
|
‘int ss_flags’
|
This field contains the bitwise OR of these flags:
|
|
‘SS_DISABLE’
|
This tells the system that it should not use the signal
|
stack.
|
|
‘SS_ONSTACK’
|
This is set by the system, and indicates that the signal
|
stack is currently in use. If this bit is not set, then
|
signals will be delivered on the normal user stack.
|
|
-- Function: int sigaltstack (const stack_t *restrict STACK, stack_t
|
*restrict OLDSTACK)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
|
| *Note POSIX Safety Concepts::.
|
|
The ‘sigaltstack’ function specifies an alternate stack for use
|
during signal handling. When a signal is received by the process
|
and its action indicates that the signal stack is used, the system
|
arranges a switch to the currently installed signal stack while the
|
handler for that signal is executed.
|
|
If OLDSTACK is not a null pointer, information about the currently
|
installed signal stack is returned in the location it points to.
|
If STACK is not a null pointer, then this is installed as the new
|
stack for use by signal handlers.
|
|
The return value is ‘0’ on success and ‘-1’ on failure. If
|
‘sigaltstack’ fails, it sets ‘errno’ to one of these values:
|
|
‘EINVAL’
|
You tried to disable a stack that was in fact currently in
|
use.
|
|
‘ENOMEM’
|
The size of the alternate stack was too small. It must be
|
greater than ‘MINSIGSTKSZ’.
|
|
Here is the older ‘sigstack’ interface. You should use ‘sigaltstack’
|
instead on systems that have it.
|
|
-- Data Type: struct sigstack
|
|
This structure describes a signal stack. It contains the following
|
members:
|
|
‘void *ss_sp’
|
This is the stack pointer. If the stack grows downwards on
|
your machine, this should point to the top of the area you
|
allocated. If the stack grows upwards, it should point to the
|
bottom.
|
|
‘int ss_onstack’
|
This field is true if the process is currently using this
|
stack.
|
|
-- Function: int sigstack (struct sigstack *STACK, struct sigstack
|
*OLDSTACK)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
|
| *Note POSIX Safety Concepts::.
|
|
The ‘sigstack’ function specifies an alternate stack for use during
|
signal handling. When a signal is received by the process and its
|
action indicates that the signal stack is used, the system arranges
|
a switch to the currently installed signal stack while the handler
|
for that signal is executed.
|
|
If OLDSTACK is not a null pointer, information about the currently
|
installed signal stack is returned in the location it points to.
|
If STACK is not a null pointer, then this is installed as the new
|
stack for use by signal handlers.
|
|
The return value is ‘0’ on success and ‘-1’ on failure.
|
|
|
File: libc.info, Node: BSD Signal Handling, Prev: Signal Stack, Up: Signal Handling
|
|
24.10 BSD Signal Handling
|
=========================
|
|
This section describes alternative signal handling functions derived
|
from BSD Unix. These facilities were an advance, in their time; today,
|
they are mostly obsolete, and supported mainly for compatibility with
|
BSD Unix.
|
|
There are many similarities between the BSD and POSIX signal handling
|
facilities, because the POSIX facilities were inspired by the BSD
|
facilities. Besides having different names for all the functions to
|
avoid conflicts, the main difference between the two is that BSD Unix
|
represents signal masks as an ‘int’ bit mask, rather than as a
|
‘sigset_t’ object.
|
|
The BSD facilities are declared in ‘signal.h’.
|
|
-- Function: int siginterrupt (int SIGNUM, int FAILFLAG)
|
|
Preliminary: | MT-Unsafe const:sigintr | AS-Unsafe | AC-Unsafe
|
corrupt | *Note POSIX Safety Concepts::.
|
|
This function specifies which approach to use when certain
|
primitives are interrupted by handling signal SIGNUM. If FAILFLAG
|
is false, signal SIGNUM restarts primitives. If FAILFLAG is true,
|
handling SIGNUM causes these primitives to fail with error code
|
‘EINTR’. *Note Interrupted Primitives::.
|
|
This function has been replaced by the ‘SA_RESTART’ flag of the
|
‘sigaction’ function. *Note Advanced Signal Handling::.
|
|
-- Macro: int sigmask (int SIGNUM)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns a signal mask that has the bit for signal SIGNUM
|
set. You can bitwise-OR the results of several calls to ‘sigmask’
|
together to specify more than one signal. For example,
|
|
(sigmask (SIGTSTP) | sigmask (SIGSTOP)
|
| sigmask (SIGTTIN) | sigmask (SIGTTOU))
|
|
specifies a mask that includes all the job-control stop signals.
|
|
This macro has been replaced by the ‘sigset_t’ type and the
|
associated signal set manipulation functions. *Note Signal Sets::.
|
|
-- Function: int sigblock (int MASK)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
|
| *Note POSIX Safety Concepts::.
|
|
This function is equivalent to ‘sigprocmask’ (*note Process Signal
|
Mask::) with a HOW argument of ‘SIG_BLOCK’: it adds the signals
|
specified by MASK to the calling process’s set of blocked signals.
|
The return value is the previous set of blocked signals.
|
|
-- Function: int sigsetmask (int MASK)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
|
| *Note POSIX Safety Concepts::.
|
|
This function is equivalent to ‘sigprocmask’ (*note Process Signal
|
Mask::) with a HOW argument of ‘SIG_SETMASK’: it sets the calling
|
process’s signal mask to MASK. The return value is the previous
|
set of blocked signals.
|
|
-- Function: int sigpause (int MASK)
|
|
Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe
|
lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::.
|
|
This function is the equivalent of ‘sigsuspend’ (*note Waiting for
|
a Signal::): it sets the calling process’s signal mask to MASK, and
|
waits for a signal to arrive. On return the previous set of
|
blocked signals is restored.
|
|
|
File: libc.info, Node: Program Basics, Next: Processes, Prev: Signal Handling, Up: Top
|
|
25 The Basic Program/System Interface
|
*************************************
|
|
"Processes" are the primitive units for allocation of system resources.
|
Each process has its own address space and (usually) one thread of
|
control. A process executes a program; you can have multiple processes
|
executing the same program, but each process has its own copy of the
|
program within its own address space and executes it independently of
|
the other copies. Though it may have multiple threads of control within
|
the same program and a program may be composed of multiple logically
|
separate modules, a process always executes exactly one program.
|
|
Note that we are using a specific definition of “program” for the
|
purposes of this manual, which corresponds to a common definition in the
|
context of Unix systems. In popular usage, “program” enjoys a much
|
broader definition; it can refer for example to a system’s kernel, an
|
editor macro, a complex package of software, or a discrete section of
|
code executing within a process.
|
|
Writing the program is what this manual is all about. This chapter
|
explains the most basic interface between your program and the system
|
that runs, or calls, it. This includes passing of parameters (arguments
|
and environment) from the system, requesting basic services from the
|
system, and telling the system the program is done.
|
|
A program starts another program with the ‘exec’ family of system
|
calls. This chapter looks at program startup from the execee’s point of
|
view. To see the event from the execor’s point of view, see *note
|
Executing a File::.
|
|
* Menu:
|
|
* Program Arguments:: Parsing your program’s command-line arguments
|
* Environment Variables:: Less direct parameters affecting your program
|
* Auxiliary Vector:: Least direct parameters affecting your program
|
* System Calls:: Requesting service from the system
|
* Program Termination:: Telling the system you’re done; return status
|
|
|
File: libc.info, Node: Program Arguments, Next: Environment Variables, Up: Program Basics
|
|
25.1 Program Arguments
|
======================
|
|
The system starts a C program by calling the function ‘main’. It is up
|
to you to write a function named ‘main’—otherwise, you won’t even be
|
able to link your program without errors.
|
|
In ISO C you can define ‘main’ either to take no arguments, or to
|
take two arguments that represent the command line arguments to the
|
program, like this:
|
|
int main (int ARGC, char *ARGV[])
|
|
The command line arguments are the whitespace-separated tokens given
|
in the shell command used to invoke the program; thus, in ‘cat foo bar’,
|
the arguments are ‘foo’ and ‘bar’. The only way a program can look at
|
its command line arguments is via the arguments of ‘main’. If ‘main’
|
doesn’t take arguments, then you cannot get at the command line.
|
|
The value of the ARGC argument is the number of command line
|
arguments. The ARGV argument is a vector of C strings; its elements are
|
the individual command line argument strings. The file name of the
|
program being run is also included in the vector as the first element;
|
the value of ARGC counts this element. A null pointer always follows
|
the last element: ‘ARGV[ARGC]’ is this null pointer.
|
|
For the command ‘cat foo bar’, ARGC is 3 and ARGV has three elements,
|
‘"cat"’, ‘"foo"’ and ‘"bar"’.
|
|
In Unix systems you can define ‘main’ a third way, using three
|
arguments:
|
|
int main (int ARGC, char *ARGV[], char *ENVP[])
|
|
The first two arguments are just the same. The third argument ENVP
|
gives the program’s environment; it is the same as the value of
|
‘environ’. *Note Environment Variables::. POSIX.1 does not allow this
|
three-argument form, so to be portable it is best to write ‘main’ to
|
take two arguments, and use the value of ‘environ’.
|
|
* Menu:
|
|
* Argument Syntax:: By convention, options start with a hyphen.
|
* Parsing Program Arguments:: Ways to parse program options and arguments.
|
|
|
File: libc.info, Node: Argument Syntax, Next: Parsing Program Arguments, Up: Program Arguments
|
|
25.1.1 Program Argument Syntax Conventions
|
------------------------------------------
|
|
POSIX recommends these conventions for command line arguments. ‘getopt’
|
(*note Getopt::) and ‘argp_parse’ (*note Argp::) make it easy to
|
implement them.
|
|
• Arguments are options if they begin with a hyphen delimiter (‘-’).
|
|
• Multiple options may follow a hyphen delimiter in a single token if
|
the options do not take arguments. Thus, ‘-abc’ is equivalent to
|
‘-a -b -c’.
|
|
• Option names are single alphanumeric characters (as for ‘isalnum’;
|
*note Classification of Characters::).
|
|
• Certain options require an argument. For example, the ‘-o’ option
|
of the ‘ld’ command requires an argument—an output file name.
|
|
• An option and its argument may or may not appear as separate
|
tokens. (In other words, the whitespace separating them is
|
optional.) Thus, ‘-o foo’ and ‘-ofoo’ are equivalent.
|
|
• Options typically precede other non-option arguments.
|
|
The implementations of ‘getopt’ and ‘argp_parse’ in the GNU C
|
Library normally make it appear as if all the option arguments were
|
specified before all the non-option arguments for the purposes of
|
parsing, even if the user of your program intermixed option and
|
non-option arguments. They do this by reordering the elements of
|
the ARGV array. This behavior is nonstandard; if you want to
|
suppress it, define the ‘_POSIX_OPTION_ORDER’ environment variable.
|
*Note Standard Environment::.
|
|
• The argument ‘--’ terminates all options; any following arguments
|
are treated as non-option arguments, even if they begin with a
|
hyphen.
|
|
• A token consisting of a single hyphen character is interpreted as
|
an ordinary non-option argument. By convention, it is used to
|
specify input from or output to the standard input and output
|
streams.
|
|
• Options may be supplied in any order, or appear multiple times.
|
The interpretation is left up to the particular application
|
program.
|
|
GNU adds "long options" to these conventions. Long options consist
|
of ‘--’ followed by a name made of alphanumeric characters and dashes.
|
Option names are typically one to three words long, with hyphens to
|
separate words. Users can abbreviate the option names as long as the
|
abbreviations are unique.
|
|
To specify an argument for a long option, write ‘--NAME=VALUE’. This
|
syntax enables a long option to accept an argument that is itself
|
optional.
|
|
Eventually, GNU systems will provide completion for long option names
|
in the shell.
|
|
|
File: libc.info, Node: Parsing Program Arguments, Prev: Argument Syntax, Up: Program Arguments
|
|
25.1.2 Parsing Program Arguments
|
--------------------------------
|
|
If the syntax for the command line arguments to your program is simple
|
enough, you can simply pick the arguments off from ARGV by hand. But
|
unless your program takes a fixed number of arguments, or all of the
|
arguments are interpreted in the same way (as file names, for example),
|
you are usually better off using ‘getopt’ (*note Getopt::) or
|
‘argp_parse’ (*note Argp::) to do the parsing.
|
|
‘getopt’ is more standard (the short-option only version of it is a
|
part of the POSIX standard), but using ‘argp_parse’ is often easier,
|
both for very simple and very complex option structures, because it does
|
more of the dirty work for you.
|
|
* Menu:
|
|
* Getopt:: Parsing program options using ‘getopt’.
|
* Argp:: Parsing program options using ‘argp_parse’.
|
* Suboptions:: Some programs need more detailed options.
|
* Suboptions Example:: This shows how it could be done for ‘mount’.
|
|
|
File: libc.info, Node: Getopt, Next: Argp, Up: Parsing Program Arguments
|
|
25.2 Parsing program options using ‘getopt’
|
===========================================
|
|
The ‘getopt’ and ‘getopt_long’ functions automate some of the chore
|
involved in parsing typical unix command line options.
|
|
* Menu:
|
|
* Using Getopt:: Using the ‘getopt’ function.
|
* Example of Getopt:: An example of parsing options with ‘getopt’.
|
* Getopt Long Options:: GNU suggests utilities accept long-named
|
options; here is one way to do.
|
* Getopt Long Option Example:: An example of using ‘getopt_long’.
|
|
|
File: libc.info, Node: Using Getopt, Next: Example of Getopt, Up: Getopt
|
|
25.2.1 Using the ‘getopt’ function
|
----------------------------------
|
|
Here are the details about how to call the ‘getopt’ function. To use
|
this facility, your program must include the header file ‘unistd.h’.
|
|
-- Variable: int opterr
|
|
If the value of this variable is nonzero, then ‘getopt’ prints an
|
error message to the standard error stream if it encounters an
|
unknown option character or an option with a missing required
|
argument. This is the default behavior. If you set this variable
|
to zero, ‘getopt’ does not print any messages, but it still returns
|
the character ‘?’ to indicate an error.
|
|
-- Variable: int optopt
|
|
When ‘getopt’ encounters an unknown option character or an option
|
with a missing required argument, it stores that option character
|
in this variable. You can use this for providing your own
|
diagnostic messages.
|
|
-- Variable: int optind
|
|
This variable is set by ‘getopt’ to the index of the next element
|
of the ARGV array to be processed. Once ‘getopt’ has found all of
|
the option arguments, you can use this variable to determine where
|
the remaining non-option arguments begin. The initial value of
|
this variable is ‘1’.
|
|
-- Variable: char * optarg
|
|
This variable is set by ‘getopt’ to point at the value of the
|
option argument, for those options that accept arguments.
|
|
-- Function: int getopt (int ARGC, char *const *ARGV, const char
|
*OPTIONS)
|
|
Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock
|
corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getopt’ function gets the next option argument from the
|
argument list specified by the ARGV and ARGC arguments. Normally
|
these values come directly from the arguments received by ‘main’.
|
|
The OPTIONS argument is a string that specifies the option
|
characters that are valid for this program. An option character in
|
this string can be followed by a colon (‘:’) to indicate that it
|
takes a required argument. If an option character is followed by
|
two colons (‘::’), its argument is optional; this is a GNU
|
extension.
|
|
‘getopt’ has three ways to deal with options that follow
|
non-options ARGV elements. The special argument ‘--’ forces in all
|
cases the end of option scanning.
|
|
• The default is to permute the contents of ARGV while scanning
|
it so that eventually all the non-options are at the end.
|
This allows options to be given in any order, even with
|
programs that were not written to expect this.
|
|
• If the OPTIONS argument string begins with a hyphen (‘-’),
|
this is treated specially. It permits arguments that are not
|
options to be returned as if they were associated with option
|
character ‘\1’.
|
|
• POSIX demands the following behavior: the first non-option
|
stops option processing. This mode is selected by either
|
setting the environment variable ‘POSIXLY_CORRECT’ or
|
beginning the OPTIONS argument string with a plus sign (‘+’).
|
|
The ‘getopt’ function returns the option character for the next
|
command line option. When no more option arguments are available,
|
it returns ‘-1’. There may still be more non-option arguments; you
|
must compare the external variable ‘optind’ against the ARGC
|
parameter to check this.
|
|
If the option has an argument, ‘getopt’ returns the argument by
|
storing it in the variable OPTARG. You don’t ordinarily need to
|
copy the ‘optarg’ string, since it is a pointer into the original
|
ARGV array, not into a static area that might be overwritten.
|
|
If ‘getopt’ finds an option character in ARGV that was not included
|
in OPTIONS, or a missing option argument, it returns ‘?’ and sets
|
the external variable ‘optopt’ to the actual option character. If
|
the first character of OPTIONS is a colon (‘:’), then ‘getopt’
|
returns ‘:’ instead of ‘?’ to indicate a missing option argument.
|
In addition, if the external variable ‘opterr’ is nonzero (which is
|
the default), ‘getopt’ prints an error message.
|
|
|
File: libc.info, Node: Example of Getopt, Next: Getopt Long Options, Prev: Using Getopt, Up: Getopt
|
|
25.2.2 Example of Parsing Arguments with ‘getopt’
|
-------------------------------------------------
|
|
Here is an example showing how ‘getopt’ is typically used. The key
|
points to notice are:
|
|
• Normally, ‘getopt’ is called in a loop. When ‘getopt’ returns
|
‘-1’, indicating no more options are present, the loop terminates.
|
|
• A ‘switch’ statement is used to dispatch on the return value from
|
‘getopt’. In typical use, each case just sets a variable that is
|
used later in the program.
|
|
• A second loop is used to process the remaining non-option
|
arguments.
|
|
|
#include <ctype.h>
|
#include <stdio.h>
|
#include <stdlib.h>
|
#include <unistd.h>
|
|
int
|
main (int argc, char **argv)
|
{
|
int aflag = 0;
|
int bflag = 0;
|
char *cvalue = NULL;
|
int index;
|
int c;
|
|
opterr = 0;
|
|
while ((c = getopt (argc, argv, "abc:")) != -1)
|
switch (c)
|
{
|
case 'a':
|
aflag = 1;
|
break;
|
case 'b':
|
bflag = 1;
|
break;
|
case 'c':
|
cvalue = optarg;
|
break;
|
case '?':
|
if (optopt == 'c')
|
fprintf (stderr, "Option -%c requires an argument.\n", optopt);
|
else if (isprint (optopt))
|
fprintf (stderr, "Unknown option `-%c'.\n", optopt);
|
else
|
fprintf (stderr,
|
"Unknown option character `\\x%x'.\n",
|
optopt);
|
return 1;
|
default:
|
abort ();
|
}
|
|
printf ("aflag = %d, bflag = %d, cvalue = %s\n",
|
aflag, bflag, cvalue);
|
|
for (index = optind; index < argc; index++)
|
printf ("Non-option argument %s\n", argv[index]);
|
return 0;
|
}
|
|
Here are some examples showing what this program prints with
|
different combinations of arguments:
|
|
% testopt
|
aflag = 0, bflag = 0, cvalue = (null)
|
|
% testopt -a -b
|
aflag = 1, bflag = 1, cvalue = (null)
|
|
% testopt -ab
|
aflag = 1, bflag = 1, cvalue = (null)
|
|
% testopt -c foo
|
aflag = 0, bflag = 0, cvalue = foo
|
|
% testopt -cfoo
|
aflag = 0, bflag = 0, cvalue = foo
|
|
% testopt arg1
|
aflag = 0, bflag = 0, cvalue = (null)
|
Non-option argument arg1
|
|
% testopt -a arg1
|
aflag = 1, bflag = 0, cvalue = (null)
|
Non-option argument arg1
|
|
% testopt -c foo arg1
|
aflag = 0, bflag = 0, cvalue = foo
|
Non-option argument arg1
|
|
% testopt -a -- -b
|
aflag = 1, bflag = 0, cvalue = (null)
|
Non-option argument -b
|
|
% testopt -a -
|
aflag = 1, bflag = 0, cvalue = (null)
|
Non-option argument -
|
|
|
File: libc.info, Node: Getopt Long Options, Next: Getopt Long Option Example, Prev: Example of Getopt, Up: Getopt
|
|
25.2.3 Parsing Long Options with ‘getopt_long’
|
----------------------------------------------
|
|
To accept GNU-style long options as well as single-character options,
|
use ‘getopt_long’ instead of ‘getopt’. This function is declared in
|
‘getopt.h’, not ‘unistd.h’. You should make every program accept long
|
options if it uses any options, for this takes little extra work and
|
helps beginners remember how to use the program.
|
|
-- Data Type: struct option
|
|
This structure describes a single long option name for the sake of
|
‘getopt_long’. The argument LONGOPTS must be an array of these
|
structures, one for each long option. Terminate the array with an
|
element containing all zeros.
|
|
The ‘struct option’ structure has these fields:
|
|
‘const char *name’
|
This field is the name of the option. It is a string.
|
|
‘int has_arg’
|
This field says whether the option takes an argument. It is
|
an integer, and there are three legitimate values:
|
‘no_argument’, ‘required_argument’ and ‘optional_argument’.
|
|
‘int *flag’
|
‘int val’
|
These fields control how to report or act on the option when
|
it occurs.
|
|
If ‘flag’ is a null pointer, then the ‘val’ is a value which
|
identifies this option. Often these values are chosen to
|
uniquely identify particular long options.
|
|
If ‘flag’ is not a null pointer, it should be the address of
|
an ‘int’ variable which is the flag for this option. The
|
value in ‘val’ is the value to store in the flag to indicate
|
that the option was seen.
|
|
-- Function: int getopt_long (int ARGC, char *const *ARGV, const char
|
*SHORTOPTS, const struct option *LONGOPTS, int *INDEXPTR)
|
|
Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock
|
corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety
|
Concepts::.
|
|
Decode options from the vector ARGV (whose length is ARGC). The
|
argument SHORTOPTS describes the short options to accept, just as
|
it does in ‘getopt’. The argument LONGOPTS describes the long
|
options to accept (see above).
|
|
When ‘getopt_long’ encounters a short option, it does the same
|
thing that ‘getopt’ would do: it returns the character code for the
|
option, and stores the option’s argument (if it has one) in
|
‘optarg’.
|
|
When ‘getopt_long’ encounters a long option, it takes actions based
|
on the ‘flag’ and ‘val’ fields of the definition of that option.
|
|
If ‘flag’ is a null pointer, then ‘getopt_long’ returns the
|
contents of ‘val’ to indicate which option it found. You should
|
arrange distinct values in the ‘val’ field for options with
|
different meanings, so you can decode these values after
|
‘getopt_long’ returns. If the long option is equivalent to a short
|
option, you can use the short option’s character code in ‘val’.
|
|
If ‘flag’ is not a null pointer, that means this option should just
|
set a flag in the program. The flag is a variable of type ‘int’
|
that you define. Put the address of the flag in the ‘flag’ field.
|
Put in the ‘val’ field the value you would like this option to
|
store in the flag. In this case, ‘getopt_long’ returns ‘0’.
|
|
For any long option, ‘getopt_long’ tells you the index in the array
|
LONGOPTS of the options definition, by storing it into ‘*INDEXPTR’.
|
You can get the name of the option with ‘LONGOPTS[*INDEXPTR].name’.
|
So you can distinguish among long options either by the values in
|
their ‘val’ fields or by their indices. You can also distinguish
|
in this way among long options that set flags.
|
|
When a long option has an argument, ‘getopt_long’ puts the argument
|
value in the variable ‘optarg’ before returning. When the option
|
has no argument, the value in ‘optarg’ is a null pointer. This is
|
how you can tell whether an optional argument was supplied.
|
|
When ‘getopt_long’ has no more options to handle, it returns ‘-1’,
|
and leaves in the variable ‘optind’ the index in ARGV of the next
|
remaining argument.
|
|
Since long option names were used before ‘getopt_long’ was invented
|
there are program interfaces which require programs to recognize options
|
like ‘-option value’ instead of ‘--option value’. To enable these
|
programs to use the GNU getopt functionality there is one more function
|
available.
|
|
-- Function: int getopt_long_only (int ARGC, char *const *ARGV, const
|
char *SHORTOPTS, const struct option *LONGOPTS, int *INDEXPTR)
|
|
Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock
|
corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getopt_long_only’ function is equivalent to the ‘getopt_long’
|
function but it allows the user of the application to pass long
|
options with only ‘-’ instead of ‘--’. The ‘--’ prefix is still
|
recognized but instead of looking through the short options if a
|
‘-’ is seen it is first tried whether this parameter names a long
|
option. If not, it is parsed as a short option.
|
|
Assuming ‘getopt_long_only’ is used starting an application with
|
|
app -foo
|
|
the ‘getopt_long_only’ will first look for a long option named
|
‘foo’. If this is not found, the short options ‘f’, ‘o’, and again
|
‘o’ are recognized.
|
|
|
File: libc.info, Node: Getopt Long Option Example, Prev: Getopt Long Options, Up: Getopt
|
|
25.2.4 Example of Parsing Long Options with ‘getopt_long’
|
---------------------------------------------------------
|
|
|
#include <stdio.h>
|
#include <stdlib.h>
|
#include <getopt.h>
|
|
/* Flag set by ‘--verbose’. */
|
static int verbose_flag;
|
|
int
|
main (int argc, char **argv)
|
{
|
int c;
|
|
while (1)
|
{
|
static struct option long_options[] =
|
{
|
/* These options set a flag. */
|
{"verbose", no_argument, &verbose_flag, 1},
|
{"brief", no_argument, &verbose_flag, 0},
|
/* These options don’t set a flag.
|
We distinguish them by their indices. */
|
{"add", no_argument, 0, 'a'},
|
{"append", no_argument, 0, 'b'},
|
{"delete", required_argument, 0, 'd'},
|
{"create", required_argument, 0, 'c'},
|
{"file", required_argument, 0, 'f'},
|
{0, 0, 0, 0}
|
};
|
/* ‘getopt_long’ stores the option index here. */
|
int option_index = 0;
|
|
c = getopt_long (argc, argv, "abc:d:f:",
|
long_options, &option_index);
|
|
/* Detect the end of the options. */
|
if (c == -1)
|
break;
|
|
switch (c)
|
{
|
case 0:
|
/* If this option set a flag, do nothing else now. */
|
if (long_options[option_index].flag != 0)
|
break;
|
printf ("option %s", long_options[option_index].name);
|
if (optarg)
|
printf (" with arg %s", optarg);
|
printf ("\n");
|
break;
|
|
case 'a':
|
puts ("option -a\n");
|
break;
|
|
case 'b':
|
puts ("option -b\n");
|
break;
|
|
case 'c':
|
printf ("option -c with value `%s'\n", optarg);
|
break;
|
|
case 'd':
|
printf ("option -d with value `%s'\n", optarg);
|
break;
|
|
case 'f':
|
printf ("option -f with value `%s'\n", optarg);
|
break;
|
|
case '?':
|
/* ‘getopt_long’ already printed an error message. */
|
break;
|
|
default:
|
abort ();
|
}
|
}
|
|
/* Instead of reporting ‘--verbose’
|
and ‘--brief’ as they are encountered,
|
we report the final status resulting from them. */
|
if (verbose_flag)
|
puts ("verbose flag is set");
|
|
/* Print any remaining command line arguments (not options). */
|
if (optind < argc)
|
{
|
printf ("non-option ARGV-elements: ");
|
while (optind < argc)
|
printf ("%s ", argv[optind++]);
|
putchar ('\n');
|
}
|
|
exit (0);
|
}
|
|
|
File: libc.info, Node: Argp, Next: Suboptions, Prev: Getopt, Up: Parsing Program Arguments
|
|
25.3 Parsing Program Options with Argp
|
======================================
|
|
"Argp" is an interface for parsing unix-style argument vectors. *Note
|
Program Arguments::.
|
|
Argp provides features unavailable in the more commonly used ‘getopt’
|
interface. These features include automatically producing output in
|
response to the ‘--help’ and ‘--version’ options, as described in the
|
GNU coding standards. Using argp makes it less likely that programmers
|
will neglect to implement these additional options or keep them up to
|
date.
|
|
Argp also provides the ability to merge several independently defined
|
option parsers into one, mediating conflicts between them and making the
|
result appear seamless. A library can export an argp option parser that
|
user programs might employ in conjunction with their own option parsers,
|
resulting in less work for the user programs. Some programs may use
|
only argument parsers exported by libraries, thereby achieving
|
consistent and efficient option-parsing for abstractions implemented by
|
the libraries.
|
|
The header file ‘<argp.h>’ should be included to use argp.
|
|
25.3.1 The ‘argp_parse’ Function
|
--------------------------------
|
|
The main interface to argp is the ‘argp_parse’ function. In many cases,
|
calling ‘argp_parse’ is the only argument-parsing code needed in ‘main’.
|
*Note Program Arguments::.
|
|
-- Function: error_t argp_parse (const struct argp *ARGP, int ARGC,
|
char **ARGV, unsigned FLAGS, int *ARG_INDEX, void *INPUT)
|
|
Preliminary: | MT-Unsafe race:argpbuf locale env | AS-Unsafe heap
|
i18n lock corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety
|
Concepts::.
|
|
The ‘argp_parse’ function parses the arguments in ARGV, of length
|
ARGC, using the argp parser ARGP. *Note Argp Parsers::. Passing a
|
null pointer for ARGP is the same as using a ‘struct argp’
|
containing all zeros.
|
|
FLAGS is a set of flag bits that modify the parsing behavior.
|
*Note Argp Flags::. INPUT is passed through to the argp parser
|
ARGP, and has meaning defined by ARGP. A typical usage is to pass
|
a pointer to a structure which is used for specifying parameters to
|
the parser and passing back the results.
|
|
Unless the ‘ARGP_NO_EXIT’ or ‘ARGP_NO_HELP’ flags are included in
|
FLAGS, calling ‘argp_parse’ may result in the program exiting.
|
This behavior is true if an error is detected, or when an unknown
|
option is encountered. *Note Program Termination::.
|
|
If ARG_INDEX is non-null, the index of the first unparsed option in
|
ARGV is returned as a value.
|
|
The return value is zero for successful parsing, or an error code
|
(*note Error Codes::) if an error is detected. Different argp
|
parsers may return arbitrary error codes, but the standard error
|
codes are: ‘ENOMEM’ if a memory allocation error occurred, or
|
‘EINVAL’ if an unknown option or option argument is encountered.
|
|
* Menu:
|
|
* Globals: Argp Global Variables. Global argp parameters.
|
* Parsers: Argp Parsers. Defining parsers for use with ‘argp_parse’.
|
* Flags: Argp Flags. Flags that modify the behavior of ‘argp_parse’.
|
* Help: Argp Help. Printing help messages when not parsing.
|
* Examples: Argp Examples. Simple examples of programs using argp.
|
* Customization: Argp User Customization.
|
Users may control the ‘--help’ output format.
|
|
|
File: libc.info, Node: Argp Global Variables, Next: Argp Parsers, Up: Argp
|
|
25.3.2 Argp Global Variables
|
----------------------------
|
|
These variables make it easy for user programs to implement the
|
‘--version’ option and provide a bug-reporting address in the ‘--help’
|
output. These are implemented in argp by default.
|
|
-- Variable: const char * argp_program_version
|
|
If defined or set by the user program to a non-zero value, then a
|
‘--version’ option is added when parsing with ‘argp_parse’, which
|
will print the ‘--version’ string followed by a newline and exit.
|
The exception to this is if the ‘ARGP_NO_EXIT’ flag is used.
|
|
-- Variable: const char * argp_program_bug_address
|
|
If defined or set by the user program to a non-zero value,
|
‘argp_program_bug_address’ should point to a string that will be
|
printed at the end of the standard output for the ‘--help’ option,
|
embedded in a sentence that says ‘Report bugs to ADDRESS.’.
|
|
-- Variable: argp_program_version_hook
|
|
If defined or set by the user program to a non-zero value, a
|
‘--version’ option is added when parsing with ‘arg_parse’, which
|
prints the program version and exits with a status of zero. This
|
is not the case if the ‘ARGP_NO_HELP’ flag is used. If the
|
‘ARGP_NO_EXIT’ flag is set, the exit behavior of the program is
|
suppressed or modified, as when the argp parser is going to be used
|
by other programs.
|
|
It should point to a function with this type of signature:
|
|
void PRINT-VERSION (FILE *STREAM, struct argp_state *STATE)
|
|
*Note Argp Parsing State::, for an explanation of STATE.
|
|
This variable takes precedence over ‘argp_program_version’, and is
|
useful if a program has version information not easily expressed in
|
a simple string.
|
|
-- Variable: error_t argp_err_exit_status
|
|
This is the exit status used when argp exits due to a parsing
|
error. If not defined or set by the user program, this defaults
|
to: ‘EX_USAGE’ from ‘<sysexits.h>’.
|
|
|
File: libc.info, Node: Argp Parsers, Next: Argp Flags, Prev: Argp Global Variables, Up: Argp
|
|
25.3.3 Specifying Argp Parsers
|
------------------------------
|
|
The first argument to the ‘argp_parse’ function is a pointer to a
|
‘struct argp’, which is known as an "argp parser":
|
|
-- Data Type: struct argp
|
|
This structure specifies how to parse a given set of options and
|
arguments, perhaps in conjunction with other argp parsers. It has
|
the following fields:
|
|
‘const struct argp_option *options’
|
A pointer to a vector of ‘argp_option’ structures specifying
|
which options this argp parser understands; it may be zero if
|
there are no options at all. *Note Argp Option Vectors::.
|
|
‘argp_parser_t parser’
|
A pointer to a function that defines actions for this parser;
|
it is called for each option parsed, and at other well-defined
|
points in the parsing process. A value of zero is the same as
|
a pointer to a function that always returns
|
‘ARGP_ERR_UNKNOWN’. *Note Argp Parser Functions::.
|
|
‘const char *args_doc’
|
If non-zero, a string describing what non-option arguments are
|
called by this parser. This is only used to print the
|
‘Usage:’ message. If it contains newlines, the strings
|
separated by them are considered alternative usage patterns
|
and printed on separate lines. Lines after the first are
|
prefixed by ‘ or: ’ instead of ‘Usage:’.
|
|
‘const char *doc’
|
If non-zero, a string containing extra text to be printed
|
before and after the options in a long help message, with the
|
two sections separated by a vertical tab (‘'\v'’, ‘'\013'’)
|
character. By convention, the documentation before the
|
options is just a short string explaining what the program
|
does. Documentation printed after the options describe
|
behavior in more detail.
|
|
‘const struct argp_child *children’
|
A pointer to a vector of ‘argp_child’ structures. This
|
pointer specifies which additional argp parsers should be
|
combined with this one. *Note Argp Children::.
|
|
‘char *(*help_filter)(int KEY, const char *TEXT, void *INPUT)’
|
If non-zero, a pointer to a function that filters the output
|
of help messages. *Note Argp Help Filtering::.
|
|
‘const char *argp_domain’
|
If non-zero, the strings used in the argp library are
|
translated using the domain described by this string. If
|
zero, the current default domain is used.
|
|
Of the above group, ‘options’, ‘parser’, ‘args_doc’, and the ‘doc’
|
fields are usually all that are needed. If an argp parser is defined as
|
an initialized C variable, only the fields used need be specified in the
|
initializer. The rest will default to zero due to the way C structure
|
initialization works. This design is exploited in most argp structures;
|
the most-used fields are grouped near the beginning, the unused fields
|
left unspecified.
|
|
* Menu:
|
|
* Options: Argp Option Vectors. Specifying options in an argp parser.
|
* Argp Parser Functions:: Defining actions for an argp parser.
|
* Children: Argp Children. Combining multiple argp parsers.
|
* Help Filtering: Argp Help Filtering. Customizing help output for an argp parser.
|
|
|
File: libc.info, Node: Argp Option Vectors, Next: Argp Parser Functions, Prev: Argp Parsers, Up: Argp Parsers
|
|
25.3.4 Specifying Options in an Argp Parser
|
-------------------------------------------
|
|
The ‘options’ field in a ‘struct argp’ points to a vector of ‘struct
|
argp_option’ structures, each of which specifies an option that the argp
|
parser supports. Multiple entries may be used for a single option
|
provided it has multiple names. This should be terminated by an entry
|
with zero in all fields. Note that when using an initialized C array
|
for options, writing ‘{ 0 }’ is enough to achieve this.
|
|
-- Data Type: struct argp_option
|
|
This structure specifies a single option that an argp parser
|
understands, as well as how to parse and document that option. It
|
has the following fields:
|
|
‘const char *name’
|
The long name for this option, corresponding to the long
|
option ‘--NAME’; this field may be zero if this option _only_
|
has a short name. To specify multiple names for an option,
|
additional entries may follow this one, with the
|
‘OPTION_ALIAS’ flag set. *Note Argp Option Flags::.
|
|
‘int key’
|
The integer key provided by the current option to the option
|
parser. If KEY has a value that is a printable ASCII
|
character (i.e., ‘isascii (KEY)’ is true), it _also_ specifies
|
a short option ‘-CHAR’, where CHAR is the ASCII character with
|
the code KEY.
|
|
‘const char *arg’
|
If non-zero, this is the name of an argument associated with
|
this option, which must be provided (e.g., with the
|
‘--NAME=VALUE’ or ‘-CHAR VALUE’ syntaxes), unless the
|
‘OPTION_ARG_OPTIONAL’ flag (*note Argp Option Flags::) is set,
|
in which case it _may_ be provided.
|
|
‘int flags’
|
Flags associated with this option, some of which are referred
|
to above. *Note Argp Option Flags::.
|
|
‘const char *doc’
|
A documentation string for this option, for printing in help
|
messages.
|
|
If both the ‘name’ and ‘key’ fields are zero, this string will
|
be printed tabbed left from the normal option column, making
|
it useful as a group header. This will be the first thing
|
printed in its group. In this usage, it’s conventional to end
|
the string with a ‘:’ character.
|
|
‘int group’
|
Group identity for this option.
|
|
In a long help message, options are sorted alphabetically
|
within each group, and the groups presented in the order 0, 1,
|
2, …, N, −M, …, −2, −1.
|
|
Every entry in an options array with this field 0 will inherit
|
the group number of the previous entry, or zero if it’s the
|
first one. If it’s a group header with ‘name’ and ‘key’
|
fields both zero, the previous entry + 1 is the default.
|
Automagic options such as ‘--help’ are put into group −1.
|
|
Note that because of C structure initialization rules, this
|
field often need not be specified, because 0 is the correct
|
value.
|
|
* Menu:
|
|
* Flags: Argp Option Flags. Flags for options.
|
|
|
File: libc.info, Node: Argp Option Flags, Up: Argp Option Vectors
|
|
25.3.4.1 Flags for Argp Options
|
...............................
|
|
The following flags may be or’d together in the ‘flags’ field of a
|
‘struct argp_option’. These flags control various aspects of how that
|
option is parsed or displayed in help messages:
|
|
‘OPTION_ARG_OPTIONAL’
|
|
The argument associated with this option is optional.
|
|
‘OPTION_HIDDEN’
|
|
This option isn’t displayed in any help messages.
|
|
‘OPTION_ALIAS’
|
|
This option is an alias for the closest previous non-alias option.
|
This means that it will be displayed in the same help entry, and
|
will inherit fields other than ‘name’ and ‘key’ from the option
|
being aliased.
|
|
‘OPTION_DOC’
|
|
This option isn’t actually an option and should be ignored by the
|
actual option parser. It is an arbitrary section of documentation
|
that should be displayed in much the same manner as the options.
|
This is known as a "documentation option".
|
|
If this flag is set, then the option ‘name’ field is displayed
|
unmodified (e.g., no ‘--’ prefix is added) at the left-margin where
|
a _short_ option would normally be displayed, and this
|
documentation string is left in its usual place. For purposes of
|
sorting, any leading whitespace and punctuation is ignored, unless
|
the first non-whitespace character is ‘-’. This entry is displayed
|
after all options, after ‘OPTION_DOC’ entries with a leading ‘-’,
|
in the same group.
|
|
‘OPTION_NO_USAGE’
|
|
This option shouldn’t be included in ‘long’ usage messages, but
|
should still be included in other help messages. This is intended
|
for options that are completely documented in an argp’s ‘args_doc’
|
field. *Note Argp Parsers::. Including this option in the generic
|
usage list would be redundant, and should be avoided.
|
|
For instance, if ‘args_doc’ is ‘"FOO BAR\n-x BLAH"’, and the ‘-x’
|
option’s purpose is to distinguish these two cases, ‘-x’ should
|
probably be marked ‘OPTION_NO_USAGE’.
|
|
|
File: libc.info, Node: Argp Parser Functions, Next: Argp Children, Prev: Argp Option Vectors, Up: Argp Parsers
|
|
25.3.5 Argp Parser Functions
|
----------------------------
|
|
The function pointed to by the ‘parser’ field in a ‘struct argp’ (*note
|
Argp Parsers::) defines what actions take place in response to each
|
option or argument parsed. It is also used as a hook, allowing a parser
|
to perform tasks at certain other points during parsing.
|
|
Argp parser functions have the following type signature:
|
|
error_t PARSER (int KEY, char *ARG, struct argp_state *STATE)
|
|
where the arguments are as follows:
|
|
KEY
|
For each option that is parsed, PARSER is called with a value of
|
KEY from that option’s ‘key’ field in the option vector. *Note
|
Argp Option Vectors::. PARSER is also called at other times with
|
special reserved keys, such as ‘ARGP_KEY_ARG’ for non-option
|
arguments. *Note Argp Special Keys::.
|
|
ARG
|
If KEY is an option, ARG is its given value. This defaults to zero
|
if no value is specified. Only options that have a non-zero ‘arg’
|
field can ever have a value. These must _always_ have a value
|
unless the ‘OPTION_ARG_OPTIONAL’ flag is specified. If the input
|
being parsed specifies a value for an option that doesn’t allow
|
one, an error results before PARSER ever gets called.
|
|
If KEY is ‘ARGP_KEY_ARG’, ARG is a non-option argument. Other
|
special keys always have a zero ARG.
|
|
STATE
|
STATE points to a ‘struct argp_state’, containing useful
|
information about the current parsing state for use by PARSER.
|
*Note Argp Parsing State::.
|
|
When PARSER is called, it should perform whatever action is
|
appropriate for KEY, and return ‘0’ for success, ‘ARGP_ERR_UNKNOWN’ if
|
the value of KEY is not handled by this parser function, or a unix error
|
code if a real error occurred. *Note Error Codes::.
|
|
-- Macro: int ARGP_ERR_UNKNOWN
|
|
Argp parser functions should return ‘ARGP_ERR_UNKNOWN’ for any KEY
|
value they do not recognize, or for non-option arguments (‘KEY ==
|
ARGP_KEY_ARG’) that they are not equipped to handle.
|
|
A typical parser function uses a switch statement on KEY:
|
|
error_t
|
parse_opt (int key, char *arg, struct argp_state *state)
|
{
|
switch (key)
|
{
|
case OPTION_KEY:
|
ACTION
|
break;
|
…
|
default:
|
return ARGP_ERR_UNKNOWN;
|
}
|
return 0;
|
}
|
|
* Menu:
|
|
* Keys: Argp Special Keys. Special values for the KEY argument.
|
* State: Argp Parsing State. What the STATE argument refers to.
|
* Functions: Argp Helper Functions. Functions to help during argp parsing.
|
|
|
File: libc.info, Node: Argp Special Keys, Next: Argp Parsing State, Up: Argp Parser Functions
|
|
25.3.5.1 Special Keys for Argp Parser Functions
|
...............................................
|
|
In addition to key values corresponding to user options, the KEY
|
argument to argp parser functions may have a number of other special
|
values. In the following example ARG and STATE refer to parser function
|
arguments. *Note Argp Parser Functions::.
|
|
‘ARGP_KEY_ARG’
|
|
This is not an option at all, but rather a command line argument,
|
whose value is pointed to by ARG.
|
|
When there are multiple parser functions in play due to argp
|
parsers being combined, it’s impossible to know which one will
|
handle a specific argument. Each is called until one returns 0 or
|
an error other than ‘ARGP_ERR_UNKNOWN’; if an argument is not
|
handled, ‘argp_parse’ immediately returns success, without parsing
|
any more arguments.
|
|
Once a parser function returns success for this key, that fact is
|
recorded, and the ‘ARGP_KEY_NO_ARGS’ case won’t be used.
|
_However_, if while processing the argument a parser function
|
decrements the ‘next’ field of its STATE argument, the option won’t
|
be considered processed; this is to allow you to actually modify
|
the argument, perhaps into an option, and have it processed again.
|
|
‘ARGP_KEY_ARGS’
|
|
If a parser function returns ‘ARGP_ERR_UNKNOWN’ for ‘ARGP_KEY_ARG’,
|
it is immediately called again with the key ‘ARGP_KEY_ARGS’, which
|
has a similar meaning, but is slightly more convenient for
|
consuming all remaining arguments. ARG is 0, and the tail of the
|
argument vector may be found at ‘STATE->argv + STATE->next’. If
|
success is returned for this key, and ‘STATE->next’ is unchanged,
|
all remaining arguments are considered to have been consumed.
|
Otherwise, the amount by which ‘STATE->next’ has been adjusted
|
indicates how many were used. Here’s an example that uses both,
|
for different args:
|
|
…
|
case ARGP_KEY_ARG:
|
if (STATE->arg_num == 0)
|
/* First argument */
|
first_arg = ARG;
|
else
|
/* Let the next case parse it. */
|
return ARGP_KEY_UNKNOWN;
|
break;
|
case ARGP_KEY_ARGS:
|
remaining_args = STATE->argv + STATE->next;
|
num_remaining_args = STATE->argc - STATE->next;
|
break;
|
|
‘ARGP_KEY_END’
|
|
This indicates that there are no more command line arguments.
|
Parser functions are called in a different order, children first.
|
This allows each parser to clean up its state for the parent.
|
|
‘ARGP_KEY_NO_ARGS’
|
|
Because it’s common to do some special processing if there aren’t
|
any non-option args, parser functions are called with this key if
|
they didn’t successfully process any non-option arguments. This is
|
called just before ‘ARGP_KEY_END’, where more general validity
|
checks on previously parsed arguments take place.
|
|
‘ARGP_KEY_INIT’
|
|
This is passed in before any parsing is done. Afterwards, the
|
values of each element of the ‘child_input’ field of STATE, if any,
|
are copied to each child’s state to be the initial value of the
|
‘input’ when _their_ parsers are called.
|
|
‘ARGP_KEY_SUCCESS’
|
|
Passed in when parsing has successfully been completed, even if
|
arguments remain.
|
|
‘ARGP_KEY_ERROR’
|
|
Passed in if an error has occurred and parsing is terminated. In
|
this case a call with a key of ‘ARGP_KEY_SUCCESS’ is never made.
|
|
‘ARGP_KEY_FINI’
|
|
The final key ever seen by any parser, even after
|
‘ARGP_KEY_SUCCESS’ and ‘ARGP_KEY_ERROR’. Any resources allocated
|
by ‘ARGP_KEY_INIT’ may be freed here. At times, certain resources
|
allocated are to be returned to the caller after a successful
|
parse. In that case, those particular resources can be freed in
|
the ‘ARGP_KEY_ERROR’ case.
|
|
In all cases, ‘ARGP_KEY_INIT’ is the first key seen by parser
|
functions, and ‘ARGP_KEY_FINI’ the last, unless an error was returned by
|
the parser for ‘ARGP_KEY_INIT’. Other keys can occur in one the
|
following orders. OPT refers to an arbitrary option key:
|
|
OPT… ‘ARGP_KEY_NO_ARGS’ ‘ARGP_KEY_END’ ‘ARGP_KEY_SUCCESS’
|
The arguments being parsed did not contain any non-option
|
arguments.
|
|
( OPT | ‘ARGP_KEY_ARG’ )… ‘ARGP_KEY_END’ ‘ARGP_KEY_SUCCESS’
|
All non-option arguments were successfully handled by a parser
|
function. There may be multiple parser functions if multiple argp
|
parsers were combined.
|
|
( OPT | ‘ARGP_KEY_ARG’ )… ‘ARGP_KEY_SUCCESS’
|
Some non-option argument went unrecognized.
|
|
This occurs when every parser function returns ‘ARGP_KEY_UNKNOWN’
|
for an argument, in which case parsing stops at that argument if
|
ARG_INDEX is a null pointer. Otherwise an error occurs.
|
|
In all cases, if a non-null value for ARG_INDEX gets passed to
|
‘argp_parse’, the index of the first unparsed command-line argument is
|
passed back in that value.
|
|
If an error occurs and is either detected by argp or because a parser
|
function returned an error value, each parser is called with
|
‘ARGP_KEY_ERROR’. No further calls are made, except the final call with
|
‘ARGP_KEY_FINI’.
|
|
|
File: libc.info, Node: Argp Parsing State, Next: Argp Helper Functions, Prev: Argp Special Keys, Up: Argp Parser Functions
|
|
25.3.5.2 Argp Parsing State
|
...........................
|
|
The third argument to argp parser functions (*note Argp Parser
|
Functions::) is a pointer to a ‘struct argp_state’, which contains
|
information about the state of the option parsing.
|
|
-- Data Type: struct argp_state
|
|
This structure has the following fields, which may be modified as
|
noted:
|
|
‘const struct argp *const root_argp’
|
The top level argp parser being parsed. Note that this is
|
often _not_ the same ‘struct argp’ passed into ‘argp_parse’ by
|
the invoking program. *Note Argp::. It is an internal argp
|
parser that contains options implemented by ‘argp_parse’
|
itself, such as ‘--help’.
|
|
‘int argc’
|
‘char **argv’
|
The argument vector being parsed. This may be modified.
|
|
‘int next’
|
The index in ‘argv’ of the next argument to be parsed. This
|
may be modified.
|
|
One way to consume all remaining arguments in the input is to
|
set ‘STATE->next = STATE->argc’, perhaps after recording the
|
value of the ‘next’ field to find the consumed arguments. The
|
current option can be re-parsed immediately by decrementing
|
this field, then modifying ‘STATE->argv[STATE->next]’ to
|
reflect the option that should be reexamined.
|
|
‘unsigned flags’
|
The flags supplied to ‘argp_parse’. These may be modified,
|
although some flags may only take effect when ‘argp_parse’ is
|
first invoked. *Note Argp Flags::.
|
|
‘unsigned arg_num’
|
While calling a parsing function with the KEY argument
|
‘ARGP_KEY_ARG’, this represents the number of the current arg,
|
starting at 0. It is incremented after each ‘ARGP_KEY_ARG’
|
call returns. At all other times, this is the number of
|
‘ARGP_KEY_ARG’ arguments that have been processed.
|
|
‘int quoted’
|
If non-zero, the index in ‘argv’ of the first argument
|
following a special ‘--’ argument. This prevents anything
|
that follows from being interpreted as an option. It is only
|
set after argument parsing has proceeded past this point.
|
|
‘void *input’
|
An arbitrary pointer passed in from the caller of
|
‘argp_parse’, in the INPUT argument.
|
|
‘void **child_inputs’
|
These are values that will be passed to child parsers. This
|
vector will be the same length as the number of children in
|
the current parser. Each child parser will be given the value
|
of ‘STATE->child_inputs[I]’ as _its_ ‘STATE->input’ field,
|
where I is the index of the child in the this parser’s
|
‘children’ field. *Note Argp Children::.
|
|
‘void *hook’
|
For the parser function’s use. Initialized to 0, but
|
otherwise ignored by argp.
|
|
‘char *name’
|
The name used when printing messages. This is initialized to
|
‘argv[0]’, or ‘program_invocation_name’ if ‘argv[0]’ is
|
unavailable.
|
|
‘FILE *err_stream’
|
‘FILE *out_stream’
|
The stdio streams used when argp prints. Error messages are
|
printed to ‘err_stream’, all other output, such as ‘--help’
|
output) to ‘out_stream’. These are initialized to ‘stderr’
|
and ‘stdout’ respectively. *Note Standard Streams::.
|
|
‘void *pstate’
|
Private, for use by the argp implementation.
|
|
|
File: libc.info, Node: Argp Helper Functions, Prev: Argp Parsing State, Up: Argp Parser Functions
|
|
25.3.5.3 Functions For Use in Argp Parsers
|
..........................................
|
|
Argp provides a number of functions available to the user of argp (*note
|
Argp Parser Functions::), mostly for producing error messages. These
|
take as their first argument the STATE argument to the parser function.
|
*Note Argp Parsing State::.
|
|
-- Function: void argp_usage (const struct argp_state *STATE)
|
|
Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap
|
i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety
|
Concepts::.
|
|
Outputs the standard usage message for the argp parser referred to
|
by STATE to ‘STATE->err_stream’ and terminates the program with
|
‘exit (argp_err_exit_status)’. *Note Argp Global Variables::.
|
|
-- Function: void argp_error (const struct argp_state *STATE, const
|
char *FMT, …)
|
|
Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap
|
i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety
|
Concepts::.
|
|
Prints the printf format string FMT and following args, preceded by
|
the program name and ‘:’, and followed by a ‘Try … --help’ message,
|
and terminates the program with an exit status of
|
‘argp_err_exit_status’. *Note Argp Global Variables::.
|
|
-- Function: void argp_failure (const struct argp_state *STATE, int
|
STATUS, int ERRNUM, const char *FMT, …)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock
|
corrupt mem | *Note POSIX Safety Concepts::.
|
|
Similar to the standard GNU error-reporting function ‘error’, this
|
prints the program name and ‘:’, the printf format string FMT, and
|
the appropriate following args. If it is non-zero, the standard
|
unix error text for ERRNUM is printed. If STATUS is non-zero, it
|
terminates the program with that value as its exit status.
|
|
The difference between ‘argp_failure’ and ‘argp_error’ is that
|
‘argp_error’ is for _parsing errors_, whereas ‘argp_failure’ is for
|
other problems that occur during parsing but don’t reflect a
|
syntactic problem with the input, such as illegal values for
|
options, bad phase of the moon, etc.
|
|
-- Function: void argp_state_help (const struct argp_state *STATE, FILE
|
*STREAM, unsigned FLAGS)
|
|
Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap
|
i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety
|
Concepts::.
|
|
Outputs a help message for the argp parser referred to by STATE, to
|
STREAM. The FLAGS argument determines what sort of help message is
|
produced. *Note Argp Help Flags::.
|
|
Error output is sent to ‘STATE->err_stream’, and the program name
|
printed is ‘STATE->name’.
|
|
The output or program termination behavior of these functions may be
|
suppressed if the ‘ARGP_NO_EXIT’ or ‘ARGP_NO_ERRS’ flags are passed to
|
‘argp_parse’. *Note Argp Flags::.
|
|
This behavior is useful if an argp parser is exported for use by
|
other programs (e.g., by a library), and may be used in a context where
|
it is not desirable to terminate the program in response to parsing
|
errors. In argp parsers intended for such general use, and for the case
|
where the program _doesn’t_ terminate, calls to any of these functions
|
should be followed by code that returns the appropriate error code:
|
|
if (BAD ARGUMENT SYNTAX)
|
{
|
argp_usage (STATE);
|
return EINVAL;
|
}
|
|
If a parser function will _only_ be used when ‘ARGP_NO_EXIT’ is not set,
|
the return may be omitted.
|
|
|
File: libc.info, Node: Argp Children, Next: Argp Help Filtering, Prev: Argp Parser Functions, Up: Argp Parsers
|
|
25.3.6 Combining Multiple Argp Parsers
|
--------------------------------------
|
|
The ‘children’ field in a ‘struct argp’ enables other argp parsers to be
|
combined with the referencing one for the parsing of a single set of
|
arguments. This field should point to a vector of ‘struct argp_child’,
|
which is terminated by an entry having a value of zero in the ‘argp’
|
field.
|
|
Where conflicts between combined parsers arise, as when two specify
|
an option with the same name, the parser conflicts are resolved in favor
|
of the parent argp parser(s), or the earlier of the argp parsers in the
|
list of children.
|
|
-- Data Type: struct argp_child
|
|
An entry in the list of subsidiary argp parsers pointed to by the
|
‘children’ field in a ‘struct argp’. The fields are as follows:
|
|
‘const struct argp *argp’
|
The child argp parser, or zero to end of the list.
|
|
‘int flags’
|
Flags for this child.
|
|
‘const char *header’
|
If non-zero, this is an optional header to be printed within
|
help output before the child options. As a side-effect, a
|
non-zero value forces the child options to be grouped
|
together. To achieve this effect without actually printing a
|
header string, use a value of ‘""’. As with header strings
|
specified in an option entry, the conventional value of the
|
last character is ‘:’. *Note Argp Option Vectors::.
|
|
‘int group’
|
This is where the child options are grouped relative to the
|
other ‘consolidated’ options in the parent argp parser. The
|
values are the same as the ‘group’ field in ‘struct
|
argp_option’. *Note Argp Option Vectors::. All
|
child-groupings follow parent options at a particular group
|
level. If both this field and ‘header’ are zero, then the
|
child’s options aren’t grouped together, they are merged with
|
parent options at the parent option group level.
|
|
|
File: libc.info, Node: Argp Flags, Next: Argp Help, Prev: Argp Parsers, Up: Argp
|
|
25.3.7 Flags for ‘argp_parse’
|
-----------------------------
|
|
The default behavior of ‘argp_parse’ is designed to be convenient for
|
the most common case of parsing program command line argument. To
|
modify these defaults, the following flags may be or’d together in the
|
FLAGS argument to ‘argp_parse’:
|
|
‘ARGP_PARSE_ARGV0’
|
|
Don’t ignore the first element of the ARGV argument to
|
‘argp_parse’. Unless ‘ARGP_NO_ERRS’ is set, the first element of
|
the argument vector is skipped for option parsing purposes, as it
|
corresponds to the program name in a command line.
|
|
‘ARGP_NO_ERRS’
|
|
Don’t print error messages for unknown options to ‘stderr’; unless
|
this flag is set, ‘ARGP_PARSE_ARGV0’ is ignored, as ‘argv[0]’ is
|
used as the program name in the error messages. This flag implies
|
‘ARGP_NO_EXIT’. This is based on the assumption that silent
|
exiting upon errors is bad behavior.
|
|
‘ARGP_NO_ARGS’
|
|
Don’t parse any non-option args. Normally these are parsed by
|
calling the parse functions with a key of ‘ARGP_KEY_ARG’, the
|
actual argument being the value. This flag needn’t normally be
|
set, as the default behavior is to stop parsing as soon as an
|
argument fails to be parsed. *Note Argp Parser Functions::.
|
|
‘ARGP_IN_ORDER’
|
|
Parse options and arguments in the same order they occur on the
|
command line. Normally they’re rearranged so that all options come
|
first.
|
|
‘ARGP_NO_HELP’
|
|
Don’t provide the standard long option ‘--help’, which ordinarily
|
causes usage and option help information to be output to ‘stdout’
|
and ‘exit (0)’.
|
|
‘ARGP_NO_EXIT’
|
|
Don’t exit on errors, although they may still result in error
|
messages.
|
|
‘ARGP_LONG_ONLY’
|
|
Use the GNU getopt ‘long-only’ rules for parsing arguments. This
|
allows long-options to be recognized with only a single ‘-’ (i.e.,
|
‘-help’). This results in a less useful interface, and its use is
|
discouraged as it conflicts with the way most GNU programs work as
|
well as the GNU coding standards.
|
|
‘ARGP_SILENT’
|
|
Turns off any message-printing/exiting options, specifically
|
‘ARGP_NO_EXIT’, ‘ARGP_NO_ERRS’, and ‘ARGP_NO_HELP’.
|
|
|
File: libc.info, Node: Argp Help Filtering, Prev: Argp Children, Up: Argp Parsers
|
|
25.3.8 Customizing Argp Help Output
|
-----------------------------------
|
|
The ‘help_filter’ field in a ‘struct argp’ is a pointer to a function
|
that filters the text of help messages before displaying them. They
|
have a function signature like:
|
|
char *HELP-FILTER (int KEY, const char *TEXT, void *INPUT)
|
|
Where KEY is either a key from an option, in which case TEXT is that
|
option’s help text. *Note Argp Option Vectors::. Alternately, one of
|
the special keys with names beginning with ‘ARGP_KEY_HELP_’ might be
|
used, describing which other help text TEXT will contain. *Note Argp
|
Help Filter Keys::.
|
|
The function should return either TEXT if it remains as-is, or a
|
replacement string allocated using ‘malloc’. This will be either be
|
freed by argp or zero, which prints nothing. The value of TEXT is
|
supplied _after_ any translation has been done, so if any of the
|
replacement text needs translation, it will be done by the filter
|
function. INPUT is either the input supplied to ‘argp_parse’ or it is
|
zero, if ‘argp_help’ was called directly by the user.
|
|
* Menu:
|
|
* Keys: Argp Help Filter Keys. Special KEY values for help filter functions.
|
|
|
File: libc.info, Node: Argp Help Filter Keys, Up: Argp Help Filtering
|
|
25.3.8.1 Special Keys for Argp Help Filter Functions
|
....................................................
|
|
The following special values may be passed to an argp help filter
|
function as the first argument in addition to key values for user
|
options. They specify which help text the TEXT argument contains:
|
|
‘ARGP_KEY_HELP_PRE_DOC’
|
|
The help text preceding options.
|
|
‘ARGP_KEY_HELP_POST_DOC’
|
|
The help text following options.
|
|
‘ARGP_KEY_HELP_HEADER’
|
|
The option header string.
|
|
‘ARGP_KEY_HELP_EXTRA’
|
|
This is used after all other documentation; TEXT is zero for this
|
key.
|
|
‘ARGP_KEY_HELP_DUP_ARGS_NOTE’
|
|
The explanatory note printed when duplicate option arguments have
|
been suppressed.
|
|
‘ARGP_KEY_HELP_ARGS_DOC’
|
|
The argument doc string; formally the ‘args_doc’ field from the
|
argp parser. *Note Argp Parsers::.
|
|
|
File: libc.info, Node: Argp Help, Next: Argp Examples, Prev: Argp Flags, Up: Argp
|
|
25.3.9 The ‘argp_help’ Function
|
-------------------------------
|
|
Normally programs using argp need not be written with particular
|
printing argument-usage-type help messages in mind as the standard
|
‘--help’ option is handled automatically by argp. Typical error cases
|
can be handled using ‘argp_usage’ and ‘argp_error’. *Note Argp Helper
|
Functions::. However, if it’s desirable to print a help message in some
|
context other than parsing the program options, argp offers the
|
‘argp_help’ interface.
|
|
-- Function: void argp_help (const struct argp *ARGP, FILE *STREAM,
|
unsigned FLAGS, char *NAME)
|
|
Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap
|
i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety
|
Concepts::.
|
|
This outputs a help message for the argp parser ARGP to STREAM.
|
The type of messages printed will be determined by FLAGS.
|
|
Any options such as ‘--help’ that are implemented automatically by
|
argp itself will _not_ be present in the help output; for this
|
reason it is best to use ‘argp_state_help’ if calling from within
|
an argp parser function. *Note Argp Helper Functions::.
|
|
* Menu:
|
|
* Flags: Argp Help Flags. Specifying what sort of help message to print.
|
|
|
File: libc.info, Node: Argp Help Flags, Up: Argp Help
|
|
25.3.10 Flags for the ‘argp_help’ Function
|
------------------------------------------
|
|
When calling ‘argp_help’ (*note Argp Help::) or ‘argp_state_help’ (*note
|
Argp Helper Functions::) the exact output is determined by the FLAGS
|
argument. This should consist of any of the following flags, or’d
|
together:
|
|
‘ARGP_HELP_USAGE’
|
|
A unix ‘Usage:’ message that explicitly lists all options.
|
|
‘ARGP_HELP_SHORT_USAGE’
|
|
A unix ‘Usage:’ message that displays an appropriate placeholder to
|
indicate where the options go; useful for showing the non-option
|
argument syntax.
|
|
‘ARGP_HELP_SEE’
|
|
A ‘Try … for more help’ message; ‘…’ contains the program name and
|
‘--help’.
|
|
‘ARGP_HELP_LONG’
|
|
A verbose option help message that gives each option available
|
along with its documentation string.
|
|
‘ARGP_HELP_PRE_DOC’
|
|
The part of the argp parser doc string preceding the verbose option
|
help.
|
|
‘ARGP_HELP_POST_DOC’
|
|
The part of the argp parser doc string that following the verbose
|
option help.
|
|
‘ARGP_HELP_DOC’
|
|
‘(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)’
|
|
‘ARGP_HELP_BUG_ADDR’
|
|
A message that prints where to report bugs for this program, if the
|
‘argp_program_bug_address’ variable contains this information.
|
|
‘ARGP_HELP_LONG_ONLY’
|
|
This will modify any output to reflect the ‘ARGP_LONG_ONLY’ mode.
|
|
The following flags are only understood when used with
|
‘argp_state_help’. They control whether the function returns after
|
printing its output, or terminates the program:
|
|
‘ARGP_HELP_EXIT_ERR’
|
|
This will terminate the program with ‘exit (argp_err_exit_status)’.
|
|
‘ARGP_HELP_EXIT_OK’
|
|
This will terminate the program with ‘exit (0)’.
|
|
The following flags are combinations of the basic flags for printing
|
standard messages:
|
|
‘ARGP_HELP_STD_ERR’
|
|
Assuming that an error message for a parsing error has printed,
|
this prints a message on how to get help, and terminates the
|
program with an error.
|
|
‘ARGP_HELP_STD_USAGE’
|
|
This prints a standard usage message and terminates the program
|
with an error. This is used when no other specific error messages
|
are appropriate or available.
|
|
‘ARGP_HELP_STD_HELP’
|
|
This prints the standard response for a ‘--help’ option, and
|
terminates the program successfully.
|
|
|
File: libc.info, Node: Argp Examples, Next: Argp User Customization, Prev: Argp Help, Up: Argp
|
|
25.3.11 Argp Examples
|
---------------------
|
|
These example programs demonstrate the basic usage of argp.
|
|
* Menu:
|
|
* 1: Argp Example 1. A minimal program using argp.
|
* 2: Argp Example 2. A program using only default options.
|
* 3: Argp Example 3. A simple program with user options.
|
* 4: Argp Example 4. Combining multiple argp parsers.
|
|
|
File: libc.info, Node: Argp Example 1, Next: Argp Example 2, Up: Argp Examples
|
|
25.3.11.1 A Minimal Program Using Argp
|
......................................
|
|
This is perhaps the smallest program possible that uses argp. It won’t
|
do much except give an error message and exit when there are any
|
arguments, and prints a rather pointless message for ‘--help’.
|
|
|
/* This is (probably) the smallest possible program that
|
uses argp. It won’t do much except give an error
|
messages and exit when there are any arguments, and print
|
a (rather pointless) messages for –help. */
|
|
#include <stdlib.h>
|
#include <argp.h>
|
|
int
|
main (int argc, char **argv)
|
{
|
argp_parse (0, argc, argv, 0, 0, 0);
|
exit (0);
|
}
|
|
|
File: libc.info, Node: Argp Example 2, Next: Argp Example 3, Prev: Argp Example 1, Up: Argp Examples
|
|
25.3.11.2 A Program Using Argp with Only Default Options
|
........................................................
|
|
This program doesn’t use any options or arguments, it uses argp to be
|
compliant with the GNU standard command line format.
|
|
In addition to giving no arguments and implementing a ‘--help’
|
option, this example has a ‘--version’ option, which will put the given
|
documentation string and bug address in the ‘--help’ output, as per GNU
|
standards.
|
|
The variable ‘argp’ contains the argument parser specification.
|
Adding fields to this structure is the way most parameters are passed to
|
‘argp_parse’. The first three fields are normally used, but they are
|
not in this small program. There are also two global variables that
|
argp can use defined here, ‘argp_program_version’ and
|
‘argp_program_bug_address’. They are considered global variables
|
because they will almost always be constant for a given program, even if
|
they use different argument parsers for various tasks.
|
|
|
/* This program doesn’t use any options or arguments, but uses
|
argp to be compliant with the GNU standard command line
|
format.
|
|
In addition to making sure no arguments are given, and
|
implementing a –help option, this example will have a
|
–version option, and will put the given documentation string
|
and bug address in the –help output, as per GNU standards.
|
|
The variable ARGP contains the argument parser specification;
|
adding fields to this structure is the way most parameters are
|
passed to argp_parse (the first three fields are usually used,
|
but not in this small program). There are also two global
|
variables that argp knows about defined here,
|
ARGP_PROGRAM_VERSION and ARGP_PROGRAM_BUG_ADDRESS (they are
|
global variables because they will almost always be constant
|
for a given program, even if it uses different argument
|
parsers for various tasks). */
|
|
#include <stdlib.h>
|
#include <argp.h>
|
|
const char *argp_program_version =
|
"argp-ex2 1.0";
|
const char *argp_program_bug_address =
|
"<bug-gnu-utils@gnu.org>";
|
|
/* Program documentation. */
|
static char doc[] =
|
"Argp example #2 -- a pretty minimal program using argp";
|
|
/* Our argument parser. The ‘options’, ‘parser’, and
|
‘args_doc’ fields are zero because we have neither options or
|
arguments; ‘doc’ and ‘argp_program_bug_address’ will be
|
used in the output for ‘--help’, and the ‘--version’
|
option will print out ‘argp_program_version’. */
|
static struct argp argp = { 0, 0, 0, doc };
|
|
int
|
main (int argc, char **argv)
|
{
|
argp_parse (&argp, argc, argv, 0, 0, 0);
|
exit (0);
|
}
|
|
|
File: libc.info, Node: Argp Example 3, Next: Argp Example 4, Prev: Argp Example 2, Up: Argp Examples
|
|
25.3.11.3 A Program Using Argp with User Options
|
................................................
|
|
This program uses the same features as example 2, adding user options
|
and arguments.
|
|
We now use the first four fields in ‘argp’ (*note Argp Parsers::) and
|
specify ‘parse_opt’ as the parser function. *Note Argp Parser
|
Functions::.
|
|
Note that in this example, ‘main’ uses a structure to communicate
|
with the ‘parse_opt’ function, a pointer to which it passes in the
|
‘input’ argument to ‘argp_parse’. *Note Argp::. It is retrieved by
|
‘parse_opt’ through the ‘input’ field in its ‘state’ argument. *Note
|
Argp Parsing State::. Of course, it’s also possible to use global
|
variables instead, but using a structure like this is somewhat more
|
flexible and clean.
|
|
|
/* This program uses the same features as example 2, and uses options and
|
arguments.
|
|
We now use the first four fields in ARGP, so here’s a description of them:
|
OPTIONS – A pointer to a vector of struct argp_option (see below)
|
PARSER – A function to parse a single option, called by argp
|
ARGS_DOC – A string describing how the non-option arguments should look
|
DOC – A descriptive string about this program; if it contains a
|
vertical tab character (\v), the part after it will be
|
printed *following* the options
|
|
The function PARSER takes the following arguments:
|
KEY – An integer specifying which option this is (taken
|
from the KEY field in each struct argp_option), or
|
a special key specifying something else; the only
|
special keys we use here are ARGP_KEY_ARG, meaning
|
a non-option argument, and ARGP_KEY_END, meaning
|
that all arguments have been parsed
|
ARG – For an option KEY, the string value of its
|
argument, or NULL if it has none
|
STATE– A pointer to a struct argp_state, containing
|
various useful information about the parsing state; used here
|
are the INPUT field, which reflects the INPUT argument to
|
argp_parse, and the ARG_NUM field, which is the number of the
|
current non-option argument being parsed
|
It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the
|
given KEY wasn’t recognized, or an errno value indicating some other
|
error.
|
|
Note that in this example, main uses a structure to communicate with the
|
parse_opt function, a pointer to which it passes in the INPUT argument to
|
argp_parse. Of course, it’s also possible to use global variables
|
instead, but this is somewhat more flexible.
|
|
The OPTIONS field contains a pointer to a vector of struct argp_option’s;
|
that structure has the following fields (if you assign your option
|
structures using array initialization like this example, unspecified
|
fields will be defaulted to 0, and need not be specified):
|
NAME – The name of this option’s long option (may be zero)
|
KEY – The KEY to pass to the PARSER function when parsing this option,
|
*and* the name of this option’s short option, if it is a
|
printable ascii character
|
ARG – The name of this option’s argument, if any
|
FLAGS – Flags describing this option; some of them are:
|
OPTION_ARG_OPTIONAL – The argument to this option is optional
|
OPTION_ALIAS – This option is an alias for the
|
previous option
|
OPTION_HIDDEN – Don’t show this option in –help output
|
DOC – A documentation string for this option, shown in –help output
|
|
An options vector should be terminated by an option with all fields zero. */
|
|
#include <stdlib.h>
|
#include <argp.h>
|
|
const char *argp_program_version =
|
"argp-ex3 1.0";
|
const char *argp_program_bug_address =
|
"<bug-gnu-utils@gnu.org>";
|
|
/* Program documentation. */
|
static char doc[] =
|
"Argp example #3 -- a program with options and arguments using argp";
|
|
/* A description of the arguments we accept. */
|
static char args_doc[] = "ARG1 ARG2";
|
|
/* The options we understand. */
|
static struct argp_option options[] = {
|
{"verbose", 'v', 0, 0, "Produce verbose output" },
|
{"quiet", 'q', 0, 0, "Don't produce any output" },
|
{"silent", 's', 0, OPTION_ALIAS },
|
{"output", 'o', "FILE", 0,
|
"Output to FILE instead of standard output" },
|
{ 0 }
|
};
|
|
/* Used by ‘main’ to communicate with ‘parse_opt’. */
|
struct arguments
|
{
|
char *args[2]; /* ARG1 & ARG2 */
|
int silent, verbose;
|
char *output_file;
|
};
|
|
/* Parse a single option. */
|
static error_t
|
parse_opt (int key, char *arg, struct argp_state *state)
|
{
|
/* Get the INPUT argument from ‘argp_parse’, which we
|
know is a pointer to our arguments structure. */
|
struct arguments *arguments = state->input;
|
|
switch (key)
|
{
|
case 'q': case 's':
|
arguments->silent = 1;
|
break;
|
case 'v':
|
arguments->verbose = 1;
|
break;
|
case 'o':
|
arguments->output_file = arg;
|
break;
|
|
case ARGP_KEY_ARG:
|
if (state->arg_num >= 2)
|
/* Too many arguments. */
|
argp_usage (state);
|
|
arguments->args[state->arg_num] = arg;
|
|
break;
|
|
case ARGP_KEY_END:
|
if (state->arg_num < 2)
|
/* Not enough arguments. */
|
argp_usage (state);
|
break;
|
|
default:
|
return ARGP_ERR_UNKNOWN;
|
}
|
return 0;
|
}
|
|
/* Our argp parser. */
|
static struct argp argp = { options, parse_opt, args_doc, doc };
|
|
int
|
main (int argc, char **argv)
|
{
|
struct arguments arguments;
|
|
/* Default values. */
|
arguments.silent = 0;
|
arguments.verbose = 0;
|
arguments.output_file = "-";
|
|
/* Parse our arguments; every option seen by ‘parse_opt’ will
|
be reflected in ‘arguments’. */
|
argp_parse (&argp, argc, argv, 0, 0, &arguments);
|
|
printf ("ARG1 = %s\nARG2 = %s\nOUTPUT_FILE = %s\n"
|
"VERBOSE = %s\nSILENT = %s\n",
|
arguments.args[0], arguments.args[1],
|
arguments.output_file,
|
arguments.verbose ? "yes" : "no",
|
arguments.silent ? "yes" : "no");
|
|
exit (0);
|
}
|
|
|
File: libc.info, Node: Argp Example 4, Prev: Argp Example 3, Up: Argp Examples
|
|
25.3.11.4 A Program Using Multiple Combined Argp Parsers
|
........................................................
|
|
This program uses the same features as example 3, but has more options,
|
and presents more structure in the ‘--help’ output. It also illustrates
|
how you can ‘steal’ the remainder of the input arguments past a certain
|
point for programs that accept a list of items. It also illustrates the
|
KEY value ‘ARGP_KEY_NO_ARGS’, which is only given if no non-option
|
arguments were supplied to the program. *Note Argp Special Keys::.
|
|
For structuring help output, two features are used: _headers_ and a
|
two part option string. The _headers_ are entries in the options
|
vector. *Note Argp Option Vectors::. The first four fields are zero.
|
The two part documentation string are in the variable ‘doc’, which
|
allows documentation both before and after the options. *Note Argp
|
Parsers::, the two parts of ‘doc’ are separated by a vertical-tab
|
character (‘'\v'’, or ‘'\013'’). By convention, the documentation
|
before the options is a short string stating what the program does, and
|
after any options it is longer, describing the behavior in more detail.
|
All documentation strings are automatically filled for output, although
|
newlines may be included to force a line break at a particular point.
|
In addition, documentation strings are passed to the ‘gettext’ function,
|
for possible translation into the current locale.
|
|
|
/* This program uses the same features as example 3, but has more
|
options, and somewhat more structure in the -help output. It
|
also shows how you can ‘steal’ the remainder of the input
|
arguments past a certain point, for programs that accept a
|
list of items. It also shows the special argp KEY value
|
ARGP_KEY_NO_ARGS, which is only given if no non-option
|
arguments were supplied to the program.
|
|
For structuring the help output, two features are used,
|
*headers* which are entries in the options vector with the
|
first four fields being zero, and a two part documentation
|
string (in the variable DOC), which allows documentation both
|
before and after the options; the two parts of DOC are
|
separated by a vertical-tab character (’\v’, or ’\013’). By
|
convention, the documentation before the options is just a
|
short string saying what the program does, and that afterwards
|
is longer, describing the behavior in more detail. All
|
documentation strings are automatically filled for output,
|
although newlines may be included to force a line break at a
|
particular point. All documentation strings are also passed to
|
the ‘gettext’ function, for possible translation into the
|
current locale. */
|
|
#include <stdlib.h>
|
#include <error.h>
|
#include <argp.h>
|
|
const char *argp_program_version =
|
"argp-ex4 1.0";
|
const char *argp_program_bug_address =
|
"<bug-gnu-utils@prep.ai.mit.edu>";
|
|
/* Program documentation. */
|
static char doc[] =
|
"Argp example #4 -- a program with somewhat more complicated\
|
options\
|
\vThis part of the documentation comes *after* the options;\
|
note that the text is automatically filled, but it's possible\
|
to force a line-break, e.g.\n<-- here.";
|
|
/* A description of the arguments we accept. */
|
static char args_doc[] = "ARG1 [STRING...]";
|
|
/* Keys for options without short-options. */
|
#define OPT_ABORT 1 /* –abort */
|
|
/* The options we understand. */
|
static struct argp_option options[] = {
|
{"verbose", 'v', 0, 0, "Produce verbose output" },
|
{"quiet", 'q', 0, 0, "Don't produce any output" },
|
{"silent", 's', 0, OPTION_ALIAS },
|
{"output", 'o', "FILE", 0,
|
"Output to FILE instead of standard output" },
|
|
{0,0,0,0, "The following options should be grouped together:" },
|
{"repeat", 'r', "COUNT", OPTION_ARG_OPTIONAL,
|
"Repeat the output COUNT (default 10) times"},
|
{"abort", OPT_ABORT, 0, 0, "Abort before showing any output"},
|
|
{ 0 }
|
};
|
|
/* Used by ‘main’ to communicate with ‘parse_opt’. */
|
struct arguments
|
{
|
char *arg1; /* ARG1 */
|
char **strings; /* [STRING…] */
|
int silent, verbose, abort; /* ‘-s’, ‘-v’, ‘--abort’ */
|
char *output_file; /* FILE arg to ‘--output’ */
|
int repeat_count; /* COUNT arg to ‘--repeat’ */
|
};
|
|
/* Parse a single option. */
|
static error_t
|
parse_opt (int key, char *arg, struct argp_state *state)
|
{
|
/* Get the ‘input’ argument from ‘argp_parse’, which we
|
know is a pointer to our arguments structure. */
|
struct arguments *arguments = state->input;
|
|
switch (key)
|
{
|
case 'q': case 's':
|
arguments->silent = 1;
|
break;
|
case 'v':
|
arguments->verbose = 1;
|
break;
|
case 'o':
|
arguments->output_file = arg;
|
break;
|
case 'r':
|
arguments->repeat_count = arg ? atoi (arg) : 10;
|
break;
|
case OPT_ABORT:
|
arguments->abort = 1;
|
break;
|
|
case ARGP_KEY_NO_ARGS:
|
argp_usage (state);
|
|
case ARGP_KEY_ARG:
|
/* Here we know that ‘state->arg_num == 0’, since we
|
force argument parsing to end before any more arguments can
|
get here. */
|
arguments->arg1 = arg;
|
|
/* Now we consume all the rest of the arguments.
|
‘state->next’ is the index in ‘state->argv’ of the
|
next argument to be parsed, which is the first STRING
|
we’re interested in, so we can just use
|
‘&state->argv[state->next]’ as the value for
|
arguments->strings.
|
|
_In addition_, by setting ‘state->next’ to the end
|
of the arguments, we can force argp to stop parsing here and
|
return. */
|
arguments->strings = &state->argv[state->next];
|
state->next = state->argc;
|
|
break;
|
|
default:
|
return ARGP_ERR_UNKNOWN;
|
}
|
return 0;
|
}
|
|
/* Our argp parser. */
|
static struct argp argp = { options, parse_opt, args_doc, doc };
|
|
int
|
main (int argc, char **argv)
|
{
|
int i, j;
|
struct arguments arguments;
|
|
/* Default values. */
|
arguments.silent = 0;
|
arguments.verbose = 0;
|
arguments.output_file = "-";
|
arguments.repeat_count = 1;
|
arguments.abort = 0;
|
|
/* Parse our arguments; every option seen by ‘parse_opt’ will be
|
reflected in ‘arguments’. */
|
argp_parse (&argp, argc, argv, 0, 0, &arguments);
|
|
if (arguments.abort)
|
error (10, 0, "ABORTED");
|
|
for (i = 0; i < arguments.repeat_count; i++)
|
{
|
printf ("ARG1 = %s\n", arguments.arg1);
|
printf ("STRINGS = ");
|
for (j = 0; arguments.strings[j]; j++)
|
printf (j == 0 ? "%s" : ", %s", arguments.strings[j]);
|
printf ("\n");
|
printf ("OUTPUT_FILE = %s\nVERBOSE = %s\nSILENT = %s\n",
|
arguments.output_file,
|
arguments.verbose ? "yes" : "no",
|
arguments.silent ? "yes" : "no");
|
}
|
|
exit (0);
|
}
|
|
|
File: libc.info, Node: Argp User Customization, Prev: Argp Examples, Up: Argp
|
|
25.3.12 Argp User Customization
|
-------------------------------
|
|
The formatting of argp ‘--help’ output may be controlled to some extent
|
by a program’s users, by setting the ‘ARGP_HELP_FMT’ environment
|
variable to a comma-separated list of tokens. Whitespace is ignored:
|
|
‘dup-args’
|
‘no-dup-args’
|
These turn "duplicate-argument-mode" on or off. In duplicate
|
argument mode, if an option that accepts an argument has multiple
|
names, the argument is shown for each name. Otherwise, it is only
|
shown for the first long option. A note is subsequently printed so
|
the user knows that it applies to other names as well. The default
|
is ‘no-dup-args’, which is less consistent, but prettier.
|
|
‘dup-args-note’
|
‘no-dup-args-note’
|
These will enable or disable the note informing the user of
|
suppressed option argument duplication. The default is
|
‘dup-args-note’.
|
|
‘short-opt-col=N’
|
This prints the first short option in column N. The default is 2.
|
|
‘long-opt-col=N’
|
This prints the first long option in column N. The default is 6.
|
|
‘doc-opt-col=N’
|
This prints ‘documentation options’ (*note Argp Option Flags::) in
|
column N. The default is 2.
|
|
‘opt-doc-col=N’
|
This prints the documentation for options starting in column N.
|
The default is 29.
|
|
‘header-col=N’
|
This will indent the group headers that document groups of options
|
to column N. The default is 1.
|
|
‘usage-indent=N’
|
This will indent continuation lines in ‘Usage:’ messages to column
|
N. The default is 12.
|
|
‘rmargin=N’
|
This will word wrap help output at or before column N. The default
|
is 79.
|
|
|
File: libc.info, Node: Suboptions, Next: Suboptions Example, Prev: Argp, Up: Parsing Program Arguments
|
|
25.3.12.1 Parsing of Suboptions
|
...............................
|
|
Having a single level of options is sometimes not enough. There might
|
be too many options which have to be available or a set of options is
|
closely related.
|
|
For this case some programs use suboptions. One of the most
|
prominent programs is certainly ‘mount’(8). The ‘-o’ option take one
|
argument which itself is a comma separated list of options. To ease the
|
programming of code like this the function ‘getsubopt’ is available.
|
|
-- Function: int getsubopt (char **OPTIONP, char *const *TOKENS, char
|
**VALUEP)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The OPTIONP parameter must be a pointer to a variable containing
|
the address of the string to process. When the function returns,
|
the reference is updated to point to the next suboption or to the
|
terminating ‘\0’ character if there are no more suboptions
|
available.
|
|
The TOKENS parameter references an array of strings containing the
|
known suboptions. All strings must be ‘\0’ terminated and to mark
|
the end a null pointer must be stored. When ‘getsubopt’ finds a
|
possible legal suboption it compares it with all strings available
|
in the TOKENS array and returns the index in the string as the
|
indicator.
|
|
In case the suboption has an associated value introduced by a ‘=’
|
character, a pointer to the value is returned in VALUEP. The
|
string is ‘\0’ terminated. If no argument is available VALUEP is
|
set to the null pointer. By doing this the caller can check
|
whether a necessary value is given or whether no unexpected value
|
is present.
|
|
In case the next suboption in the string is not mentioned in the
|
TOKENS array the starting address of the suboption including a
|
possible value is returned in VALUEP and the return value of the
|
function is ‘-1’.
|
|
|
File: libc.info, Node: Suboptions Example, Prev: Suboptions, Up: Parsing Program Arguments
|
|
25.3.13 Parsing of Suboptions Example
|
-------------------------------------
|
|
The code which might appear in the ‘mount’(8) program is a perfect
|
example of the use of ‘getsubopt’:
|
|
|
#include <stdio.h>
|
#include <stdlib.h>
|
#include <unistd.h>
|
|
int do_all;
|
const char *type;
|
int read_size;
|
int write_size;
|
int read_only;
|
|
enum
|
{
|
RO_OPTION = 0,
|
RW_OPTION,
|
READ_SIZE_OPTION,
|
WRITE_SIZE_OPTION,
|
THE_END
|
};
|
|
const char *mount_opts[] =
|
{
|
[RO_OPTION] = "ro",
|
[RW_OPTION] = "rw",
|
[READ_SIZE_OPTION] = "rsize",
|
[WRITE_SIZE_OPTION] = "wsize",
|
[THE_END] = NULL
|
};
|
|
int
|
main (int argc, char **argv)
|
{
|
char *subopts, *value;
|
int opt;
|
|
while ((opt = getopt (argc, argv, "at:o:")) != -1)
|
switch (opt)
|
{
|
case 'a':
|
do_all = 1;
|
break;
|
case 't':
|
type = optarg;
|
break;
|
case 'o':
|
subopts = optarg;
|
while (*subopts != '\0')
|
switch (getsubopt (&subopts, mount_opts, &value))
|
{
|
case RO_OPTION:
|
read_only = 1;
|
break;
|
case RW_OPTION:
|
read_only = 0;
|
break;
|
case READ_SIZE_OPTION:
|
if (value == NULL)
|
abort ();
|
read_size = atoi (value);
|
break;
|
case WRITE_SIZE_OPTION:
|
if (value == NULL)
|
abort ();
|
write_size = atoi (value);
|
break;
|
default:
|
/* Unknown suboption. */
|
printf ("Unknown suboption `%s'\n", value);
|
break;
|
}
|
break;
|
default:
|
abort ();
|
}
|
|
/* Do the real work. */
|
|
return 0;
|
}
|
|
|
File: libc.info, Node: Environment Variables, Next: Auxiliary Vector, Prev: Program Arguments, Up: Program Basics
|
|
25.4 Environment Variables
|
==========================
|
|
When a program is executed, it receives information about the context in
|
which it was invoked in two ways. The first mechanism uses the ARGV and
|
ARGC arguments to its ‘main’ function, and is discussed in *note Program
|
Arguments::. The second mechanism uses "environment variables" and is
|
discussed in this section.
|
|
The ARGV mechanism is typically used to pass command-line arguments
|
specific to the particular program being invoked. The environment, on
|
the other hand, keeps track of information that is shared by many
|
programs, changes infrequently, and that is less frequently used.
|
|
The environment variables discussed in this section are the same
|
environment variables that you set using assignments and the ‘export’
|
command in the shell. Programs executed from the shell inherit all of
|
the environment variables from the shell.
|
|
Standard environment variables are used for information about the
|
user’s home directory, terminal type, current locale, and so on; you can
|
define additional variables for other purposes. The set of all
|
environment variables that have values is collectively known as the
|
"environment".
|
|
Names of environment variables are case-sensitive and must not
|
contain the character ‘=’. System-defined environment variables are
|
invariably uppercase.
|
|
The values of environment variables can be anything that can be
|
represented as a string. A value must not contain an embedded null
|
character, since this is assumed to terminate the string.
|
|
* Menu:
|
|
* Environment Access:: How to get and set the values of
|
environment variables.
|
* Standard Environment:: These environment variables have
|
standard interpretations.
|
|
|
File: libc.info, Node: Environment Access, Next: Standard Environment, Up: Environment Variables
|
|
25.4.1 Environment Access
|
-------------------------
|
|
The value of an environment variable can be accessed with the ‘getenv’
|
function. This is declared in the header file ‘stdlib.h’.
|
|
Libraries should use ‘secure_getenv’ instead of ‘getenv’, so that
|
they do not accidentally use untrusted environment variables.
|
Modifications of environment variables are not allowed in multi-threaded
|
programs. The ‘getenv’ and ‘secure_getenv’ functions can be safely used
|
in multi-threaded programs.
|
|
-- Function: char * getenv (const char *NAME)
|
|
Preliminary: | MT-Safe env | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function returns a string that is the value of the environment
|
variable NAME. You must not modify this string. In some non-Unix
|
systems not using the GNU C Library, it might be overwritten by
|
subsequent calls to ‘getenv’ (but not by any other library
|
function). If the environment variable NAME is not defined, the
|
value is a null pointer.
|
|
-- Function: char * secure_getenv (const char *NAME)
|
|
Preliminary: | MT-Safe env | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to ‘getenv’, but it returns a null pointer
|
if the environment is untrusted. This happens when the program
|
file has SUID or SGID bits set. General-purpose libraries should
|
always prefer this function over ‘getenv’ to avoid vulnerabilities
|
if the library is referenced from a SUID/SGID program.
|
|
This function is a GNU extension.
|
|
-- Function: int putenv (char *STRING)
|
|
Preliminary: | MT-Unsafe const:env | AS-Unsafe heap lock |
|
AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
|
|
The ‘putenv’ function adds or removes definitions from the
|
environment. If the STRING is of the form ‘NAME=VALUE’, the
|
definition is added to the environment. Otherwise, the STRING is
|
interpreted as the name of an environment variable, and any
|
definition for this variable in the environment is removed.
|
|
If the function is successful it returns ‘0’. Otherwise the return
|
value is nonzero and ‘errno’ is set to indicate the error.
|
|
The difference to the ‘setenv’ function is that the exact string
|
given as the parameter STRING is put into the environment. If the
|
user should change the string after the ‘putenv’ call this will
|
reflect automatically in the environment. This also requires that
|
STRING not be an automatic variable whose scope is left before the
|
variable is removed from the environment. The same applies of
|
course to dynamically allocated variables which are freed later.
|
|
This function is part of the extended Unix interface. You should
|
define _XOPEN_SOURCE before including any header.
|
|
-- Function: int setenv (const char *NAME, const char *VALUE, int
|
REPLACE)
|
|
Preliminary: | MT-Unsafe const:env | AS-Unsafe heap lock |
|
AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
|
|
The ‘setenv’ function can be used to add a new definition to the
|
environment. The entry with the name NAME is replaced by the value
|
‘NAME=VALUE’. Please note that this is also true if VALUE is the
|
empty string. To do this a new string is created and the strings
|
NAME and VALUE are copied. A null pointer for the VALUE parameter
|
is illegal. If the environment already contains an entry with key
|
NAME the REPLACE parameter controls the action. If replace is
|
zero, nothing happens. Otherwise the old entry is replaced by the
|
new one.
|
|
Please note that you cannot remove an entry completely using this
|
function.
|
|
If the function is successful it returns ‘0’. Otherwise the
|
environment is unchanged and the return value is ‘-1’ and ‘errno’
|
is set.
|
|
This function was originally part of the BSD library but is now
|
part of the Unix standard.
|
|
-- Function: int unsetenv (const char *NAME)
|
|
Preliminary: | MT-Unsafe const:env | AS-Unsafe lock | AC-Unsafe
|
lock | *Note POSIX Safety Concepts::.
|
|
Using this function one can remove an entry completely from the
|
environment. If the environment contains an entry with the key
|
NAME this whole entry is removed. A call to this function is
|
equivalent to a call to ‘putenv’ when the VALUE part of the string
|
is empty.
|
|
The function returns ‘-1’ if NAME is a null pointer, points to an
|
empty string, or points to a string containing a ‘=’ character. It
|
returns ‘0’ if the call succeeded.
|
|
This function was originally part of the BSD library but is now
|
part of the Unix standard. The BSD version had no return value,
|
though.
|
|
There is one more function to modify the whole environment. This
|
function is said to be used in the POSIX.9 (POSIX bindings for Fortran
|
77) and so one should expect it did made it into POSIX.1. But this
|
never happened. But we still provide this function as a GNU extension
|
to enable writing standard compliant Fortran environments.
|
|
-- Function: int clearenv (void)
|
|
Preliminary: | MT-Unsafe const:env | AS-Unsafe heap lock |
|
AC-Unsafe lock mem | *Note POSIX Safety Concepts::.
|
|
The ‘clearenv’ function removes all entries from the environment.
|
Using ‘putenv’ and ‘setenv’ new entries can be added again later.
|
|
If the function is successful it returns ‘0’. Otherwise the return
|
value is nonzero.
|
|
You can deal directly with the underlying representation of
|
environment objects to add more variables to the environment (for
|
example, to communicate with another program you are about to execute;
|
*note Executing a File::).
|
|
-- Variable: char ** environ
|
|
The environment is represented as an array of strings. Each string
|
is of the format ‘NAME=VALUE’. The order in which strings appear
|
in the environment is not significant, but the same NAME must not
|
appear more than once. The last element of the array is a null
|
pointer.
|
|
This variable is declared in the header file ‘unistd.h’.
|
|
If you just want to get the value of an environment variable, use
|
‘getenv’.
|
|
Unix systems, and GNU systems, pass the initial value of ‘environ’ as
|
the third argument to ‘main’. *Note Program Arguments::.
|
|
|
File: libc.info, Node: Standard Environment, Prev: Environment Access, Up: Environment Variables
|
|
25.4.2 Standard Environment Variables
|
-------------------------------------
|
|
These environment variables have standard meanings. This doesn’t mean
|
that they are always present in the environment; but if these variables
|
_are_ present, they have these meanings. You shouldn’t try to use these
|
environment variable names for some other purpose.
|
|
‘HOME’
|
|
This is a string representing the user’s "home directory", or
|
initial default working directory.
|
|
The user can set ‘HOME’ to any value. If you need to make sure to
|
obtain the proper home directory for a particular user, you should
|
not use ‘HOME’; instead, look up the user’s name in the user
|
database (*note User Database::).
|
|
For most purposes, it is better to use ‘HOME’, precisely because
|
this lets the user specify the value.
|
|
‘LOGNAME’
|
|
This is the name that the user used to log in. Since the value in
|
the environment can be tweaked arbitrarily, this is not a reliable
|
way to identify the user who is running a program; a function like
|
‘getlogin’ (*note Who Logged In::) is better for that purpose.
|
|
For most purposes, it is better to use ‘LOGNAME’, precisely because
|
this lets the user specify the value.
|
|
‘PATH’
|
|
A "path" is a sequence of directory names which is used for
|
searching for a file. The variable ‘PATH’ holds a path used for
|
searching for programs to be run.
|
|
The ‘execlp’ and ‘execvp’ functions (*note Executing a File::) use
|
this environment variable, as do many shells and other utilities
|
which are implemented in terms of those functions.
|
|
The syntax of a path is a sequence of directory names separated by
|
colons. An empty string instead of a directory name stands for the
|
current directory (*note Working Directory::).
|
|
A typical value for this environment variable might be a string
|
like:
|
|
:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
|
|
This means that if the user tries to execute a program named ‘foo’,
|
the system will look for files named ‘foo’, ‘/bin/foo’, ‘/etc/foo’,
|
and so on. The first of these files that exists is the one that is
|
executed.
|
|
‘TERM’
|
|
This specifies the kind of terminal that is receiving program
|
output. Some programs can make use of this information to take
|
advantage of special escape sequences or terminal modes supported
|
by particular kinds of terminals. Many programs which use the
|
termcap library (*note Find: (termcap)Finding a Terminal
|
Description.) use the ‘TERM’ environment variable, for example.
|
|
‘TZ’
|
|
This specifies the time zone. *Note TZ Variable::, for information
|
about the format of this string and how it is used.
|
|
‘LANG’
|
|
This specifies the default locale to use for attribute categories
|
where neither ‘LC_ALL’ nor the specific environment variable for
|
that category is set. *Note Locales::, for more information about
|
locales.
|
|
‘LC_ALL’
|
|
If this environment variable is set it overrides the selection for
|
all the locales done using the other ‘LC_*’ environment variables.
|
The value of the other ‘LC_*’ environment variables is simply
|
ignored in this case.
|
|
‘LC_COLLATE’
|
|
This specifies what locale to use for string sorting.
|
|
‘LC_CTYPE’
|
|
This specifies what locale to use for character sets and character
|
classification.
|
|
‘LC_MESSAGES’
|
|
This specifies what locale to use for printing messages and to
|
parse responses.
|
|
‘LC_MONETARY’
|
|
This specifies what locale to use for formatting monetary values.
|
|
‘LC_NUMERIC’
|
|
This specifies what locale to use for formatting numbers.
|
|
‘LC_TIME’
|
|
This specifies what locale to use for formatting date/time values.
|
|
‘NLSPATH’
|
|
This specifies the directories in which the ‘catopen’ function
|
looks for message translation catalogs.
|
|
‘_POSIX_OPTION_ORDER’
|
|
If this environment variable is defined, it suppresses the usual
|
reordering of command line arguments by ‘getopt’ and ‘argp_parse’.
|
*Note Argument Syntax::.
|
|
|
File: libc.info, Node: Auxiliary Vector, Next: System Calls, Prev: Environment Variables, Up: Program Basics
|
|
25.5 Auxiliary Vector
|
=====================
|
|
When a program is executed, it receives information from the operating
|
system about the environment in which it is operating. The form of this
|
information is a table of key-value pairs, where the keys are from the
|
set of ‘AT_’ values in ‘elf.h’. Some of the data is provided by the
|
kernel for libc consumption, and may be obtained by ordinary interfaces,
|
such as ‘sysconf’. However, on a platform-by-platform basis there may
|
be information that is not available any other way.
|
|
25.5.1 Definition of ‘getauxval’
|
--------------------------------
|
|
-- Function: unsigned long int getauxval (unsigned long int TYPE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is used to inquire about the entries in the auxiliary
|
vector. The TYPE argument should be one of the ‘AT_’ symbols
|
defined in ‘elf.h’. If a matching entry is found, the value is
|
returned; if the entry is not found, zero is returned and ‘errno’
|
is set to ‘ENOENT’.
|
|
For some platforms, the key ‘AT_HWCAP’ is the easiest way to inquire
|
about any instruction set extensions available at runtime. In this
|
case, there will (of necessity) be a platform-specific set of ‘HWCAP_’
|
values masked together that describe the capabilities of the cpu on
|
which the program is being executed.
|
|
|
File: libc.info, Node: System Calls, Next: Program Termination, Prev: Auxiliary Vector, Up: Program Basics
|
|
25.6 System Calls
|
=================
|
|
A system call is a request for service that a program makes of the
|
kernel. The service is generally something that only the kernel has the
|
privilege to do, such as doing I/O. Programmers don’t normally need to
|
be concerned with system calls because there are functions in the GNU C
|
Library to do virtually everything that system calls do. These
|
functions work by making system calls themselves. For example, there is
|
a system call that changes the permissions of a file, but you don’t need
|
to know about it because you can just use the GNU C Library’s ‘chmod’
|
function.
|
|
System calls are sometimes called kernel calls.
|
|
However, there are times when you want to make a system call
|
explicitly, and for that, the GNU C Library provides the ‘syscall’
|
function. ‘syscall’ is harder to use and less portable than functions
|
like ‘chmod’, but easier and more portable than coding the system call
|
in assembler instructions.
|
|
‘syscall’ is most useful when you are working with a system call
|
which is special to your system or is newer than the GNU C Library you
|
are using. ‘syscall’ is implemented in an entirely generic way; the
|
function does not know anything about what a particular system call does
|
or even if it is valid.
|
|
The description of ‘syscall’ in this section assumes a certain
|
protocol for system calls on the various platforms on which the GNU C
|
Library runs. That protocol is not defined by any strong authority, but
|
we won’t describe it here either because anyone who is coding ‘syscall’
|
probably won’t accept anything less than kernel and C library source
|
code as a specification of the interface between them anyway.
|
|
‘syscall’ is declared in ‘unistd.h’.
|
|
-- Function: long int syscall (long int SYSNO, …)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘syscall’ performs a generic system call.
|
|
SYSNO is the system call number. Each kind of system call is
|
identified by a number. Macros for all the possible system call
|
numbers are defined in ‘sys/syscall.h’
|
|
The remaining arguments are the arguments for the system call, in
|
order, and their meanings depend on the kind of system call. Each
|
kind of system call has a definite number of arguments, from zero
|
to five. If you code more arguments than the system call takes,
|
the extra ones to the right are ignored.
|
|
The return value is the return value from the system call, unless
|
the system call failed. In that case, ‘syscall’ returns ‘-1’ and
|
sets ‘errno’ to an error code that the system call returned. Note
|
that system calls do not return ‘-1’ when they succeed.
|
|
If you specify an invalid SYSNO, ‘syscall’ returns ‘-1’ with
|
‘errno’ = ‘ENOSYS’.
|
|
Example:
|
|
|
#include <unistd.h>
|
#include <sys/syscall.h>
|
#include <errno.h>
|
|
…
|
|
int rc;
|
|
rc = syscall(SYS_chmod, "/etc/passwd", 0444);
|
|
if (rc == -1)
|
fprintf(stderr, "chmod failed, errno = %d\n", errno);
|
|
This, if all the compatibility stars are aligned, is equivalent to
|
the following preferable code:
|
|
|
#include <sys/types.h>
|
#include <sys/stat.h>
|
#include <errno.h>
|
|
…
|
|
int rc;
|
|
rc = chmod("/etc/passwd", 0444);
|
if (rc == -1)
|
fprintf(stderr, "chmod failed, errno = %d\n", errno);
|
|
|
File: libc.info, Node: Program Termination, Prev: System Calls, Up: Program Basics
|
|
25.7 Program Termination
|
========================
|
|
The usual way for a program to terminate is simply for its ‘main’
|
function to return. The "exit status value" returned from the ‘main’
|
function is used to report information back to the process’s parent
|
process or shell.
|
|
A program can also terminate normally by calling the ‘exit’ function.
|
|
In addition, programs can be terminated by signals; this is discussed
|
in more detail in *note Signal Handling::. The ‘abort’ function causes
|
a signal that kills the program.
|
|
* Menu:
|
|
* Normal Termination:: If a program calls ‘exit’, a
|
process terminates normally.
|
* Exit Status:: The ‘exit status’ provides information
|
about why the process terminated.
|
* Cleanups on Exit:: A process can run its own cleanup
|
functions upon normal termination.
|
* Aborting a Program:: The ‘abort’ function causes
|
abnormal program termination.
|
* Termination Internals:: What happens when a process terminates.
|
|
|
File: libc.info, Node: Normal Termination, Next: Exit Status, Up: Program Termination
|
|
25.7.1 Normal Termination
|
-------------------------
|
|
A process terminates normally when its program signals it is done by
|
calling ‘exit’. Returning from ‘main’ is equivalent to calling ‘exit’,
|
and the value that ‘main’ returns is used as the argument to ‘exit’.
|
|
-- Function: void exit (int STATUS)
|
|
Preliminary: | MT-Unsafe race:exit | AS-Unsafe corrupt | AC-Unsafe
|
corrupt lock | *Note POSIX Safety Concepts::.
|
|
The ‘exit’ function tells the system that the program is done,
|
which causes it to terminate the process.
|
|
STATUS is the program’s exit status, which becomes part of the
|
process’ termination status. This function does not return.
|
|
Normal termination causes the following actions:
|
|
1. Functions that were registered with the ‘atexit’ or ‘on_exit’
|
functions are called in the reverse order of their registration.
|
This mechanism allows your application to specify its own “cleanup”
|
actions to be performed at program termination. Typically, this is
|
used to do things like saving program state information in a file,
|
or unlocking locks in shared data bases.
|
|
2. All open streams are closed, writing out any buffered output data.
|
See *note Closing Streams::. In addition, temporary files opened
|
with the ‘tmpfile’ function are removed; see *note Temporary
|
Files::.
|
|
3. ‘_exit’ is called, terminating the program. *Note Termination
|
Internals::.
|
|
|
File: libc.info, Node: Exit Status, Next: Cleanups on Exit, Prev: Normal Termination, Up: Program Termination
|
|
25.7.2 Exit Status
|
------------------
|
|
When a program exits, it can return to the parent process a small amount
|
of information about the cause of termination, using the "exit status".
|
This is a value between 0 and 255 that the exiting process passes as an
|
argument to ‘exit’.
|
|
Normally you should use the exit status to report very broad
|
information about success or failure. You can’t provide a lot of detail
|
about the reasons for the failure, and most parent processes would not
|
want much detail anyway.
|
|
There are conventions for what sorts of status values certain
|
programs should return. The most common convention is simply 0 for
|
success and 1 for failure. Programs that perform comparison use a
|
different convention: they use status 1 to indicate a mismatch, and
|
status 2 to indicate an inability to compare. Your program should
|
follow an existing convention if an existing convention makes sense for
|
it.
|
|
A general convention reserves status values 128 and up for special
|
purposes. In particular, the value 128 is used to indicate failure to
|
execute another program in a subprocess. This convention is not
|
universally obeyed, but it is a good idea to follow it in your programs.
|
|
*Warning:* Don’t try to use the number of errors as the exit status.
|
This is actually not very useful; a parent process would generally not
|
care how many errors occurred. Worse than that, it does not work,
|
because the status value is truncated to eight bits. Thus, if the
|
program tried to report 256 errors, the parent would receive a report of
|
0 errors—that is, success.
|
|
For the same reason, it does not work to use the value of ‘errno’ as
|
the exit status—these can exceed 255.
|
|
*Portability note:* Some non-POSIX systems use different conventions
|
for exit status values. For greater portability, you can use the macros
|
‘EXIT_SUCCESS’ and ‘EXIT_FAILURE’ for the conventional status value for
|
success and failure, respectively. They are declared in the file
|
‘stdlib.h’.
|
|
-- Macro: int EXIT_SUCCESS
|
|
This macro can be used with the ‘exit’ function to indicate
|
successful program completion.
|
|
On POSIX systems, the value of this macro is ‘0’. On other
|
systems, the value might be some other (possibly non-constant)
|
integer expression.
|
|
-- Macro: int EXIT_FAILURE
|
|
This macro can be used with the ‘exit’ function to indicate
|
unsuccessful program completion in a general sense.
|
|
On POSIX systems, the value of this macro is ‘1’. On other
|
systems, the value might be some other (possibly non-constant)
|
integer expression. Other nonzero status values also indicate
|
failures. Certain programs use different nonzero status values to
|
indicate particular kinds of "non-success". For example, ‘diff’
|
uses status value ‘1’ to mean that the files are different, and ‘2’
|
or more to mean that there was difficulty in opening the files.
|
|
Don’t confuse a program’s exit status with a process’ termination
|
status. There are lots of ways a process can terminate besides having
|
its program finish. In the event that the process termination _is_
|
caused by program termination (i.e., ‘exit’), though, the program’s exit
|
status becomes part of the process’ termination status.
|
|
|
File: libc.info, Node: Cleanups on Exit, Next: Aborting a Program, Prev: Exit Status, Up: Program Termination
|
|
25.7.3 Cleanups on Exit
|
-----------------------
|
|
Your program can arrange to run its own cleanup functions if normal
|
termination happens. If you are writing a library for use in various
|
application programs, then it is unreliable to insist that all
|
applications call the library’s cleanup functions explicitly before
|
exiting. It is much more robust to make the cleanup invisible to the
|
application, by setting up a cleanup function in the library itself
|
using ‘atexit’ or ‘on_exit’.
|
|
-- Function: int atexit (void (*FUNCTION) (void))
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
The ‘atexit’ function registers the function FUNCTION to be called
|
at normal program termination. The FUNCTION is called with no
|
arguments.
|
|
The return value from ‘atexit’ is zero on success and nonzero if
|
the function cannot be registered.
|
|
-- Function: int on_exit (void (*FUNCTION)(int STATUS, void *ARG), void
|
*ARG)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
This function is a somewhat more powerful variant of ‘atexit’. It
|
accepts two arguments, a function FUNCTION and an arbitrary pointer
|
ARG. At normal program termination, the FUNCTION is called with
|
two arguments: the STATUS value passed to ‘exit’, and the ARG.
|
|
This function is included in the GNU C Library only for
|
compatibility for SunOS, and may not be supported by other
|
implementations.
|
|
Here’s a trivial program that illustrates the use of ‘exit’ and
|
‘atexit’:
|
|
|
#include <stdio.h>
|
#include <stdlib.h>
|
|
void
|
bye (void)
|
{
|
puts ("Goodbye, cruel world....");
|
}
|
|
int
|
main (void)
|
{
|
atexit (bye);
|
exit (EXIT_SUCCESS);
|
}
|
|
When this program is executed, it just prints the message and exits.
|
|
|
File: libc.info, Node: Aborting a Program, Next: Termination Internals, Prev: Cleanups on Exit, Up: Program Termination
|
|
25.7.4 Aborting a Program
|
-------------------------
|
|
You can abort your program using the ‘abort’ function. The prototype
|
for this function is in ‘stdlib.h’.
|
|
-- Function: void abort (void)
|
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
|
| *Note POSIX Safety Concepts::.
|
|
The ‘abort’ function causes abnormal program termination. This
|
does not execute cleanup functions registered with ‘atexit’ or
|
‘on_exit’.
|
|
This function actually terminates the process by raising a
|
‘SIGABRT’ signal, and your program can include a handler to
|
intercept this signal; see *note Signal Handling::.
|
|
|
File: libc.info, Node: Termination Internals, Prev: Aborting a Program, Up: Program Termination
|
|
25.7.5 Termination Internals
|
----------------------------
|
|
The ‘_exit’ function is the primitive used for process termination by
|
‘exit’. It is declared in the header file ‘unistd.h’.
|
|
-- Function: void _exit (int STATUS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘_exit’ function is the primitive for causing a process to
|
terminate with status STATUS. Calling this function does not
|
execute cleanup functions registered with ‘atexit’ or ‘on_exit’.
|
|
-- Function: void _Exit (int STATUS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘_Exit’ function is the ISO C equivalent to ‘_exit’. The ISO C
|
committee members were not sure whether the definitions of ‘_exit’
|
and ‘_Exit’ were compatible so they have not used the POSIX name.
|
|
This function was introduced in ISO C99 and is declared in
|
‘stdlib.h’.
|
|
When a process terminates for any reason—either because the program
|
terminates, or as a result of a signal—the following things happen:
|
|
• All open file descriptors in the process are closed. *Note
|
Low-Level I/O::. Note that streams are not flushed automatically
|
when the process terminates; see *note I/O on Streams::.
|
|
• A process exit status is saved to be reported back to the parent
|
process via ‘wait’ or ‘waitpid’; see *note Process Completion::.
|
If the program exited, this status includes as its low-order 8 bits
|
the program exit status.
|
|
• Any child processes of the process being terminated are assigned a
|
new parent process. (On most systems, including GNU, this is the
|
‘init’ process, with process ID 1.)
|
|
• A ‘SIGCHLD’ signal is sent to the parent process.
|
|
• If the process is a session leader that has a controlling terminal,
|
then a ‘SIGHUP’ signal is sent to each process in the foreground
|
job, and the controlling terminal is disassociated from that
|
session. *Note Job Control::.
|
|
• If termination of a process causes a process group to become
|
orphaned, and any member of that process group is stopped, then a
|
‘SIGHUP’ signal and a ‘SIGCONT’ signal are sent to each process in
|
the group. *Note Job Control::.
|
|
|
File: libc.info, Node: Processes, Next: Inter-Process Communication, Prev: Program Basics, Up: Top
|
|
26 Processes
|
************
|
|
"Processes" are the primitive units for allocation of system resources.
|
Each process has its own address space and (usually) one thread of
|
control. A process executes a program; you can have multiple processes
|
executing the same program, but each process has its own copy of the
|
program within its own address space and executes it independently of
|
the other copies.
|
|
Processes are organized hierarchically. Each process has a "parent
|
process" which explicitly arranged to create it. The processes created
|
by a given parent are called its "child processes". A child inherits
|
many of its attributes from the parent process.
|
|
This chapter describes how a program can create, terminate, and
|
control child processes. Actually, there are three distinct operations
|
involved: creating a new child process, causing the new process to
|
execute a program, and coordinating the completion of the child process
|
with the original program.
|
|
The ‘system’ function provides a simple, portable mechanism for
|
running another program; it does all three steps automatically. If you
|
need more control over the details of how this is done, you can use the
|
primitive functions to do each step individually instead.
|
|
* Menu:
|
|
* Running a Command:: The easy way to run another program.
|
* Process Creation Concepts:: An overview of the hard way to do it.
|
* Process Identification:: How to get the process ID of a process.
|
* Creating a Process:: How to fork a child process.
|
* Executing a File:: How to make a process execute another program.
|
* Process Completion:: How to tell when a child process has completed.
|
* Process Completion Status:: How to interpret the status value
|
returned from a child process.
|
* BSD Wait Functions:: More functions, for backward compatibility.
|
* Process Creation Example:: A complete example program.
|
|
|
File: libc.info, Node: Running a Command, Next: Process Creation Concepts, Up: Processes
|
|
26.1 Running a Command
|
======================
|
|
The easy way to run another program is to use the ‘system’ function.
|
This function does all the work of running a subprogram, but it doesn’t
|
give you much control over the details: you have to wait until the
|
subprogram terminates before you can do anything else.
|
|
-- Function: int system (const char *COMMAND)
|
|
Preliminary: | MT-Safe | AS-Unsafe plugin heap lock | AC-Unsafe
|
lock mem | *Note POSIX Safety Concepts::.
|
|
This function executes COMMAND as a shell command. In the GNU C
|
Library, it always uses the default shell ‘sh’ to run the command.
|
In particular, it searches the directories in ‘PATH’ to find
|
programs to execute. The return value is ‘-1’ if it wasn’t
|
possible to create the shell process, and otherwise is the status
|
of the shell process. *Note Process Completion::, for details on
|
how this status code can be interpreted.
|
|
If the COMMAND argument is a null pointer, a return value of zero
|
indicates that no command processor is available.
|
|
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
|
‘system’ is called. If the thread gets canceled these resources
|
stay allocated until the program ends. To avoid this calls to
|
‘system’ should be protected using cancellation handlers.
|
|
The ‘system’ function is declared in the header file ‘stdlib.h’.
|
|
*Portability Note:* Some C implementations may not have any notion of
|
a command processor that can execute other programs. You can determine
|
whether a command processor exists by executing ‘system (NULL)’; if the
|
return value is nonzero, a command processor is available.
|
|
The ‘popen’ and ‘pclose’ functions (*note Pipe to a Subprocess::) are
|
closely related to the ‘system’ function. They allow the parent process
|
to communicate with the standard input and output channels of the
|
command being executed.
|
|
|
File: libc.info, Node: Process Creation Concepts, Next: Process Identification, Prev: Running a Command, Up: Processes
|
|
26.2 Process Creation Concepts
|
==============================
|
|
This section gives an overview of processes and of the steps involved in
|
creating a process and making it run another program.
|
|
A new processes is created when one of the functions ‘posix_spawn’,
|
‘fork’, or ‘vfork’ is called. (The ‘system’ and ‘popen’ also create new
|
processes internally.) Due to the name of the ‘fork’ function, the act
|
of creating a new process is sometimes called "forking" a process. Each
|
new process (the "child process" or "subprocess") is allocated a process
|
ID, distinct from the process ID of the parent process. *Note Process
|
Identification::.
|
|
After forking a child process, both the parent and child processes
|
continue to execute normally. If you want your program to wait for a
|
child process to finish executing before continuing, you must do this
|
explicitly after the fork operation, by calling ‘wait’ or ‘waitpid’
|
(*note Process Completion::). These functions give you limited
|
information about why the child terminated—for example, its exit status
|
code.
|
|
A newly forked child process continues to execute the same program as
|
its parent process, at the point where the ‘fork’ call returns. You can
|
use the return value from ‘fork’ to tell whether the program is running
|
in the parent process or the child.
|
|
Having several processes run the same program is only occasionally
|
useful. But the child can execute another program using one of the
|
‘exec’ functions; see *note Executing a File::. The program that the
|
process is executing is called its "process image". Starting execution
|
of a new program causes the process to forget all about its previous
|
process image; when the new program exits, the process exits too,
|
instead of returning to the previous process image.
|
|
|
File: libc.info, Node: Process Identification, Next: Creating a Process, Prev: Process Creation Concepts, Up: Processes
|
|
26.3 Process Identification
|
===========================
|
|
Each process is named by a "process ID" number, a value of type ‘pid_t’.
|
A process ID is allocated to each process when it is created. Process
|
IDs are reused over time. The lifetime of a process ends when the
|
parent process of the corresponding process waits on the process ID
|
after the process has terminated. *Note Process Completion::. (The
|
parent process can arrange for such waiting to happen implicitly.) A
|
process ID uniquely identifies a process only during the lifetime of the
|
process. As a rule of thumb, this means that the process must still be
|
running.
|
|
Process IDs can also denote process groups and sessions. *Note Job
|
Control::.
|
|
On Linux, threads created by ‘pthread_create’ also receive a "thread
|
ID". The thread ID of the initial (main) thread is the same as the
|
process ID of the entire process. Thread IDs for subsequently created
|
threads are distinct. They are allocated from the same numbering space
|
as process IDs. Process IDs and thread IDs are sometimes also referred
|
to collectively as "task IDs". In contrast to processes, threads are
|
never waited for explicitly, so a thread ID becomes eligible for reuse
|
as soon as a thread exits or is canceled. This is true even for
|
joinable threads, not just detached threads. Threads are assigned to a
|
"thread group". In the GNU C Library implementation running on Linux,
|
the process ID is the thread group ID of all threads in the process.
|
|
You can get the process ID of a process by calling ‘getpid’. The
|
function ‘getppid’ returns the process ID of the parent of the current
|
process (this is also known as the "parent process ID"). Your program
|
should include the header files ‘unistd.h’ and ‘sys/types.h’ to use
|
these functions.
|
|
-- Data Type: pid_t
|
|
The ‘pid_t’ data type is a signed integer type which is capable of
|
representing a process ID. In the GNU C Library, this is an ‘int’.
|
|
-- Function: pid_t getpid (void)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getpid’ function returns the process ID of the current
|
process.
|
|
-- Function: pid_t getppid (void)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getppid’ function returns the process ID of the parent of the
|
current process.
|
|
-- Function: pid_t gettid (void)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘gettid’ function returns the thread ID of the current thread.
|
The returned value is obtained from the Linux kernel and is not
|
subject to caching. See the discussion of thread IDs above,
|
especially regarding reuse of the IDs of threads which have exited.
|
|
This function is specific to Linux.
|
|
|
File: libc.info, Node: Creating a Process, Next: Executing a File, Prev: Process Identification, Up: Processes
|
|
26.4 Creating a Process
|
=======================
|
|
The ‘fork’ function is the primitive for creating a process. It is
|
declared in the header file ‘unistd.h’.
|
|
-- Function: pid_t fork (void)
|
|
Preliminary: | MT-Safe | AS-Unsafe plugin | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
The ‘fork’ function creates a new process.
|
|
If the operation is successful, there are then both parent and
|
child processes and both see ‘fork’ return, but with different
|
values: it returns a value of ‘0’ in the child process and returns
|
the child’s process ID in the parent process.
|
|
If process creation failed, ‘fork’ returns a value of ‘-1’ in the
|
parent process. The following ‘errno’ error conditions are defined
|
for ‘fork’:
|
|
‘EAGAIN’
|
There aren’t enough system resources to create another
|
process, or the user already has too many processes running.
|
This means exceeding the ‘RLIMIT_NPROC’ resource limit, which
|
can usually be increased; *note Limits on Resources::.
|
|
‘ENOMEM’
|
The process requires more space than the system can supply.
|
|
The specific attributes of the child process that differ from the
|
parent process are:
|
|
• The child process has its own unique process ID.
|
|
• The parent process ID of the child process is the process ID of its
|
parent process.
|
|
• The child process gets its own copies of the parent process’s open
|
file descriptors. Subsequently changing attributes of the file
|
descriptors in the parent process won’t affect the file descriptors
|
in the child, and vice versa. *Note Control Operations::.
|
However, the file position associated with each descriptor is
|
shared by both processes; *note File Position::.
|
|
• The elapsed processor times for the child process are set to zero;
|
see *note Processor Time::.
|
|
• The child doesn’t inherit file locks set by the parent process.
|
*Note Control Operations::.
|
|
• The child doesn’t inherit alarms set by the parent process. *Note
|
Setting an Alarm::.
|
|
• The set of pending signals (*note Delivery of Signal::) for the
|
child process is cleared. (The child process inherits its mask of
|
blocked signals and signal actions from the parent process.)
|
|
-- Function: pid_t vfork (void)
|
|
Preliminary: | MT-Safe | AS-Unsafe plugin | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
The ‘vfork’ function is similar to ‘fork’ but on some systems it is
|
more efficient; however, there are restrictions you must follow to
|
use it safely.
|
|
While ‘fork’ makes a complete copy of the calling process’s address
|
space and allows both the parent and child to execute
|
independently, ‘vfork’ does not make this copy. Instead, the child
|
process created with ‘vfork’ shares its parent’s address space
|
until it calls ‘_exit’ or one of the ‘exec’ functions. In the
|
meantime, the parent process suspends execution.
|
|
You must be very careful not to allow the child process created
|
with ‘vfork’ to modify any global data or even local variables
|
shared with the parent. Furthermore, the child process cannot
|
return from (or do a long jump out of) the function that called
|
‘vfork’! This would leave the parent process’s control information
|
very confused. If in doubt, use ‘fork’ instead.
|
|
Some operating systems don’t really implement ‘vfork’. The GNU C
|
Library permits you to use ‘vfork’ on all systems, but actually
|
executes ‘fork’ if ‘vfork’ isn’t available. If you follow the
|
proper precautions for using ‘vfork’, your program will still work
|
even if the system uses ‘fork’ instead.
|
|
|
File: libc.info, Node: Executing a File, Next: Process Completion, Prev: Creating a Process, Up: Processes
|
|
26.5 Executing a File
|
=====================
|
|
This section describes the ‘exec’ family of functions, for executing a
|
file as a process image. You can use these functions to make a child
|
process execute a new program after it has been forked.
|
|
To see the effects of ‘exec’ from the point of view of the called
|
program, see *note Program Basics::.
|
|
The functions in this family differ in how you specify the arguments,
|
but otherwise they all do the same thing. They are declared in the
|
header file ‘unistd.h’.
|
|
-- Function: int execv (const char *FILENAME, char *const ARGV[])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘execv’ function executes the file named by FILENAME as a new
|
process image.
|
|
The ARGV argument is an array of null-terminated strings that is
|
used to provide a value for the ‘argv’ argument to the ‘main’
|
function of the program to be executed. The last element of this
|
array must be a null pointer. By convention, the first element of
|
this array is the file name of the program sans directory names.
|
*Note Program Arguments::, for full details on how programs can
|
access these arguments.
|
|
The environment for the new process image is taken from the
|
‘environ’ variable of the current process image; see *note
|
Environment Variables::, for information about environments.
|
|
-- Function: int execl (const char *FILENAME, const char *ARG0, …)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
This is similar to ‘execv’, but the ARGV strings are specified
|
individually instead of as an array. A null pointer must be passed
|
as the last such argument.
|
|
-- Function: int execve (const char *FILENAME, char *const ARGV[], char
|
*const ENV[])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This is similar to ‘execv’, but permits you to specify the
|
environment for the new program explicitly as the ENV argument.
|
This should be an array of strings in the same format as for the
|
‘environ’ variable; see *note Environment Access::.
|
|
-- Function: int fexecve (int FD, char *const ARGV[], char *const
|
ENV[])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This is similar to ‘execve’, but instead of identifying the program
|
executable by its pathname, the file descriptor FD is used. The
|
descriptor must have been opened with the ‘O_RDONLY’ flag or (on
|
Linux) the ‘O_PATH’ flag.
|
|
On Linux, ‘fexecve’ can fail with an error of ‘ENOSYS’ if ‘/proc’
|
has not been mounted and the kernel lacks support for the
|
underlying ‘execveat’ system call.
|
|
-- Function: int execle (const char *FILENAME, const char *ARG0, …,
|
char *const ENV[])
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
This is similar to ‘execl’, but permits you to specify the
|
environment for the new program explicitly. The environment
|
argument is passed following the null pointer that marks the last
|
ARGV argument, and should be an array of strings in the same format
|
as for the ‘environ’ variable.
|
|
-- Function: int execvp (const char *FILENAME, char *const ARGV[])
|
|
Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
The ‘execvp’ function is similar to ‘execv’, except that it
|
searches the directories listed in the ‘PATH’ environment variable
|
(*note Standard Environment::) to find the full file name of a file
|
from FILENAME if FILENAME does not contain a slash.
|
|
This function is useful for executing system utility programs,
|
because it looks for them in the places that the user has chosen.
|
Shells use it to run the commands that users type.
|
|
-- Function: int execlp (const char *FILENAME, const char *ARG0, …)
|
|
Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
This function is like ‘execl’, except that it performs the same
|
file name searching as the ‘execvp’ function.
|
|
The size of the argument list and environment list taken together
|
must not be greater than ‘ARG_MAX’ bytes. *Note General Limits::. On
|
GNU/Hurd systems, the size (which compares against ‘ARG_MAX’) includes,
|
for each string, the number of characters in the string, plus the size
|
of a ‘char *’, plus one, rounded up to a multiple of the size of a ‘char
|
*’. Other systems may have somewhat different rules for counting.
|
|
These functions normally don’t return, since execution of a new
|
program causes the currently executing program to go away completely. A
|
value of ‘-1’ is returned in the event of a failure. In addition to the
|
usual file name errors (*note File Name Errors::), the following ‘errno’
|
error conditions are defined for these functions:
|
|
‘E2BIG’
|
The combined size of the new program’s argument list and
|
environment list is larger than ‘ARG_MAX’ bytes. GNU/Hurd systems
|
have no specific limit on the argument list size, so this error
|
code cannot result, but you may get ‘ENOMEM’ instead if the
|
arguments are too big for available memory.
|
|
‘ENOEXEC’
|
The specified file can’t be executed because it isn’t in the right
|
format.
|
|
‘ENOMEM’
|
Executing the specified file requires more storage than is
|
available.
|
|
If execution of the new file succeeds, it updates the access time
|
field of the file as if the file had been read. *Note File Times::, for
|
more details about access times of files.
|
|
The point at which the file is closed again is not specified, but is
|
at some point before the process exits or before another process image
|
is executed.
|
|
Executing a new process image completely changes the contents of
|
memory, copying only the argument and environment strings to new
|
locations. But many other attributes of the process are unchanged:
|
|
• The process ID and the parent process ID. *Note Process Creation
|
Concepts::.
|
|
• Session and process group membership. *Note Concepts of Job
|
Control::.
|
|
• Real user ID and group ID, and supplementary group IDs. *Note
|
Process Persona::.
|
|
• Pending alarms. *Note Setting an Alarm::.
|
|
• Current working directory and root directory. *Note Working
|
Directory::. On GNU/Hurd systems, the root directory is not copied
|
when executing a setuid program; instead the system default root
|
directory is used for the new program.
|
|
• File mode creation mask. *Note Setting Permissions::.
|
|
• Process signal mask; see *note Process Signal Mask::.
|
|
• Pending signals; see *note Blocking Signals::.
|
|
• Elapsed processor time associated with the process; see *note
|
Processor Time::.
|
|
If the set-user-ID and set-group-ID mode bits of the process image
|
file are set, this affects the effective user ID and effective group ID
|
(respectively) of the process. These concepts are discussed in detail
|
in *note Process Persona::.
|
|
Signals that are set to be ignored in the existing process image are
|
also set to be ignored in the new process image. All other signals are
|
set to the default action in the new process image. For more
|
information about signals, see *note Signal Handling::.
|
|
File descriptors open in the existing process image remain open in
|
the new process image, unless they have the ‘FD_CLOEXEC’ (close-on-exec)
|
flag set. The files that remain open inherit all attributes of the open
|
file descriptors from the existing process image, including file locks.
|
File descriptors are discussed in *note Low-Level I/O::.
|
|
Streams, by contrast, cannot survive through ‘exec’ functions,
|
because they are located in the memory of the process itself. The new
|
process image has no streams except those it creates afresh. Each of
|
the streams in the pre-‘exec’ process image has a descriptor inside it,
|
and these descriptors do survive through ‘exec’ (provided that they do
|
not have ‘FD_CLOEXEC’ set). The new process image can reconnect these
|
to new streams using ‘fdopen’ (*note Descriptors and Streams::).
|
|
|
File: libc.info, Node: Process Completion, Next: Process Completion Status, Prev: Executing a File, Up: Processes
|
|
26.6 Process Completion
|
=======================
|
|
The functions described in this section are used to wait for a child
|
process to terminate or stop, and determine its status. These functions
|
are declared in the header file ‘sys/wait.h’.
|
|
-- Function: pid_t waitpid (pid_t PID, int *STATUS-PTR, int OPTIONS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘waitpid’ function is used to request status information from a
|
child process whose process ID is PID. Normally, the calling
|
process is suspended until the child process makes status
|
information available by terminating.
|
|
Other values for the PID argument have special interpretations. A
|
value of ‘-1’ or ‘WAIT_ANY’ requests status information for any
|
child process; a value of ‘0’ or ‘WAIT_MYPGRP’ requests information
|
for any child process in the same process group as the calling
|
process; and any other negative value − PGID requests information
|
for any child process whose process group ID is PGID.
|
|
If status information for a child process is available immediately,
|
this function returns immediately without waiting. If more than
|
one eligible child process has status information available, one of
|
them is chosen randomly, and its status is returned immediately.
|
To get the status from the other eligible child processes, you need
|
to call ‘waitpid’ again.
|
|
The OPTIONS argument is a bit mask. Its value should be the
|
bitwise OR (that is, the ‘|’ operator) of zero or more of the
|
‘WNOHANG’ and ‘WUNTRACED’ flags. You can use the ‘WNOHANG’ flag to
|
indicate that the parent process shouldn’t wait; and the
|
‘WUNTRACED’ flag to request status information from stopped
|
processes as well as processes that have terminated.
|
|
The status information from the child process is stored in the
|
object that STATUS-PTR points to, unless STATUS-PTR is a null
|
pointer.
|
|
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
|
‘waitpid’ is called. If the thread gets canceled these resources
|
stay allocated until the program ends. To avoid this calls to
|
‘waitpid’ should be protected using cancellation handlers.
|
|
The return value is normally the process ID of the child process
|
whose status is reported. If there are child processes but none of
|
them is waiting to be noticed, ‘waitpid’ will block until one is.
|
However, if the ‘WNOHANG’ option was specified, ‘waitpid’ will
|
return zero instead of blocking.
|
|
If a specific PID to wait for was given to ‘waitpid’, it will
|
ignore all other children (if any). Therefore if there are
|
children waiting to be noticed but the child whose PID was
|
specified is not one of them, ‘waitpid’ will block or return zero
|
as described above.
|
|
A value of ‘-1’ is returned in case of error. The following
|
‘errno’ error conditions are defined for this function:
|
|
‘EINTR’
|
The function was interrupted by delivery of a signal to the
|
calling process. *Note Interrupted Primitives::.
|
|
‘ECHILD’
|
There are no child processes to wait for, or the specified PID
|
is not a child of the calling process.
|
|
‘EINVAL’
|
An invalid value was provided for the OPTIONS argument.
|
|
These symbolic constants are defined as values for the PID argument
|
to the ‘waitpid’ function.
|
|
‘WAIT_ANY’
|
|
This constant macro (whose value is ‘-1’) specifies that ‘waitpid’
|
should return status information about any child process.
|
|
‘WAIT_MYPGRP’
|
This constant (with value ‘0’) specifies that ‘waitpid’ should
|
return status information about any child process in the same
|
process group as the calling process.
|
|
These symbolic constants are defined as flags for the OPTIONS
|
argument to the ‘waitpid’ function. You can bitwise-OR the flags
|
together to obtain a value to use as the argument.
|
|
‘WNOHANG’
|
|
This flag specifies that ‘waitpid’ should return immediately
|
instead of waiting, if there is no child process ready to be
|
noticed.
|
|
‘WUNTRACED’
|
|
This flag specifies that ‘waitpid’ should report the status of any
|
child processes that have been stopped as well as those that have
|
terminated.
|
|
-- Function: pid_t wait (int *STATUS-PTR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This is a simplified version of ‘waitpid’, and is used to wait
|
until any one child process terminates. The call:
|
|
wait (&status)
|
|
is exactly equivalent to:
|
|
waitpid (-1, &status, 0)
|
|
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
|
‘wait’ is called. If the thread gets canceled these resources stay
|
allocated until the program ends. To avoid this calls to ‘wait’
|
should be protected using cancellation handlers.
|
|
-- Function: pid_t wait4 (pid_t PID, int *STATUS-PTR, int OPTIONS,
|
struct rusage *USAGE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
If USAGE is a null pointer, ‘wait4’ is equivalent to ‘waitpid (PID,
|
STATUS-PTR, OPTIONS)’.
|
|
If USAGE is not null, ‘wait4’ stores usage figures for the child
|
process in ‘*RUSAGE’ (but only if the child has terminated, not if
|
it has stopped). *Note Resource Usage::.
|
|
This function is a BSD extension.
|
|
Here’s an example of how to use ‘waitpid’ to get the status from all
|
child processes that have terminated, without ever waiting. This
|
function is designed to be a handler for ‘SIGCHLD’, the signal that
|
indicates that at least one child process has terminated.
|
|
void
|
sigchld_handler (int signum)
|
{
|
int pid, status, serrno;
|
serrno = errno;
|
while (1)
|
{
|
pid = waitpid (WAIT_ANY, &status, WNOHANG);
|
if (pid < 0)
|
{
|
perror ("waitpid");
|
break;
|
}
|
if (pid == 0)
|
break;
|
notice_termination (pid, status);
|
}
|
errno = serrno;
|
}
|
