| This is |
| /tmp/dgboter/bbs/rhev-vm2--rhe6x86_64/buildbot/rhe6x86_64--aarch64-none-linux-gnu/build/build-aarch64-none-linux-gnu/obj/glibc/manual/libc.info, |
| produced by makeinfo version 4.13 from libc.texinfo. |
| |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHAR_BIT: (libc)Width of Type. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * FP_LLOGB0: (libc)Exponents and Logarithms. |
| * FP_LLOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OFD_GETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLK: (libc)Open File Description Locks. |
| * F_OFD_SETLKW: (libc)Open File Description Locks. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUGE_VAL_FN: (libc)Math Error Reporting. |
| * HUGE_VAL_FNx: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_DIRECTORY: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TMPFILE: (libc)Open-time Flags. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SNAN: (libc)Infinity and NaN. |
| * SNANF: (libc)Infinity and NaN. |
| * SNANFN: (libc)Infinity and NaN. |
| * SNANFNx: (libc)Infinity and NaN. |
| * SNANL: (libc)Infinity and NaN. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * S_IFMT: (libc)Testing File Type. |
| * S_ISBLK: (libc)Testing File Type. |
| * S_ISCHR: (libc)Testing File Type. |
| * S_ISDIR: (libc)Testing File Type. |
| * S_ISFIFO: (libc)Testing File Type. |
| * S_ISLNK: (libc)Testing File Type. |
| * S_ISREG: (libc)Testing File Type. |
| * S_ISSOCK: (libc)Testing File Type. |
| * S_TYPEISMQ: (libc)Testing File Type. |
| * S_TYPEISSEM: (libc)Testing File Type. |
| * S_TYPEISSHM: (libc)Testing File Type. |
| * TMP_MAX: (libc)Temporary Files. |
| * TOSTOP: (libc)Local Modes. |
| * TZNAME_MAX: (libc)General Limits. |
| * VDISCARD: (libc)Other Special. |
| * VDSUSP: (libc)Signal Characters. |
| * VEOF: (libc)Editing Characters. |
| * VEOL2: (libc)Editing Characters. |
| * VEOL: (libc)Editing Characters. |
| * VERASE: (libc)Editing Characters. |
| * VINTR: (libc)Signal Characters. |
| * VKILL: (libc)Editing Characters. |
| * VLNEXT: (libc)Other Special. |
| * VMIN: (libc)Noncanonical Input. |
| * VQUIT: (libc)Signal Characters. |
| * VREPRINT: (libc)Editing Characters. |
| * VSTART: (libc)Start/Stop Characters. |
| * VSTATUS: (libc)Other Special. |
| * VSTOP: (libc)Start/Stop Characters. |
| * VSUSP: (libc)Signal Characters. |
| * VTIME: (libc)Noncanonical Input. |
| * VWERASE: (libc)Editing Characters. |
| * WCHAR_MAX: (libc)Extended Char Intro. |
| * WCHAR_MIN: (libc)Extended Char Intro. |
| * WCOREDUMP: (libc)Process Completion Status. |
| * WEOF: (libc)EOF and Errors. |
| * WEOF: (libc)Extended Char Intro. |
| * WEXITSTATUS: (libc)Process Completion Status. |
| * WIFEXITED: (libc)Process Completion Status. |
| * WIFSIGNALED: (libc)Process Completion Status. |
| * WIFSTOPPED: (libc)Process Completion Status. |
| * WSTOPSIG: (libc)Process Completion Status. |
| * WTERMSIG: (libc)Process Completion Status. |
| * W_OK: (libc)Testing File Access. |
| * X_OK: (libc)Testing File Access. |
| * _Complex_I: (libc)Complex Numbers. |
| * _Exit: (libc)Termination Internals. |
| * _IOFBF: (libc)Controlling Buffering. |
| * _IOLBF: (libc)Controlling Buffering. |
| * _IONBF: (libc)Controlling Buffering. |
| * _Imaginary_I: (libc)Complex Numbers. |
| * _PATH_UTMP: (libc)Manipulating the Database. |
| * _PATH_WTMP: (libc)Manipulating the Database. |
| * _POSIX2_C_DEV: (libc)System Options. |
| * _POSIX2_C_VERSION: (libc)Version Supported. |
| * _POSIX2_FORT_DEV: (libc)System Options. |
| * _POSIX2_FORT_RUN: (libc)System Options. |
| * _POSIX2_LOCALEDEF: (libc)System Options. |
| * _POSIX2_SW_DEV: (libc)System Options. |
| * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files. |
| * _POSIX_JOB_CONTROL: (libc)System Options. |
| * _POSIX_NO_TRUNC: (libc)Options for Files. |
| * _POSIX_SAVED_IDS: (libc)System Options. |
| * _POSIX_VDISABLE: (libc)Options for Files. |
| * _POSIX_VERSION: (libc)Version Supported. |
| * __fbufsize: (libc)Controlling Buffering. |
| * __flbf: (libc)Controlling Buffering. |
| * __fpending: (libc)Controlling Buffering. |
| * __fpurge: (libc)Flushing Buffers. |
| * __freadable: (libc)Opening Streams. |
| * __freading: (libc)Opening Streams. |
| * __fsetlocking: (libc)Streams and Threads. |
| * __fwritable: (libc)Opening Streams. |
| * __fwriting: (libc)Opening Streams. |
| * __gconv_end_fct: (libc)glibc iconv Implementation. |
| * __gconv_fct: (libc)glibc iconv Implementation. |
| * __gconv_init_fct: (libc)glibc iconv Implementation. |
| * __ppc_get_timebase: (libc)PowerPC. |
| * __ppc_get_timebase_freq: (libc)PowerPC. |
| * __ppc_mdoio: (libc)PowerPC. |
| * __ppc_mdoom: (libc)PowerPC. |
| * __ppc_set_ppr_low: (libc)PowerPC. |
| * __ppc_set_ppr_med: (libc)PowerPC. |
| * __ppc_set_ppr_med_high: (libc)PowerPC. |
| * __ppc_set_ppr_med_low: (libc)PowerPC. |
| * __ppc_set_ppr_very_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __riscv_flush_icache: (libc)RISC-V. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosfN: (libc)Inverse Trig Functions. |
| * acosfNx: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshfN: (libc)Hyperbolic Functions. |
| * acoshfNx: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinfN: (libc)Inverse Trig Functions. |
| * asinfNx: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhfN: (libc)Hyperbolic Functions. |
| * asinhfNx: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2fN: (libc)Inverse Trig Functions. |
| * atan2fNx: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanfN: (libc)Inverse Trig Functions. |
| * atanfNx: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhfN: (libc)Hyperbolic Functions. |
| * atanhfNx: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying Strings and Arrays. |
| * bind: (libc)Setting Address. |
| * bind_textdomain_codeset: (libc)Charset conversion in gettext. |
| * bindtextdomain: (libc)Locating gettext catalog. |
| * brk: (libc)Resizing the Data Segment. |
| * bsearch: (libc)Array Search Function. |
| * btowc: (libc)Converting a Character. |
| * bzero: (libc)Copying Strings and Arrays. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsfN: (libc)Absolute Value. |
| * cabsfNx: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosfN: (libc)Inverse Trig Functions. |
| * cacosfNx: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshfN: (libc)Hyperbolic Functions. |
| * cacoshfNx: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * call_once: (libc)Call Once. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize: (libc)FP Bit Twiddling. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * canonicalizef: (libc)FP Bit Twiddling. |
| * canonicalizefN: (libc)FP Bit Twiddling. |
| * canonicalizefNx: (libc)FP Bit Twiddling. |
| * canonicalizel: (libc)FP Bit Twiddling. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargfN: (libc)Operations on Complex. |
| * cargfNx: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinfN: (libc)Inverse Trig Functions. |
| * casinfNx: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhfN: (libc)Hyperbolic Functions. |
| * casinhfNx: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanfN: (libc)Inverse Trig Functions. |
| * catanfNx: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhfN: (libc)Hyperbolic Functions. |
| * catanhfNx: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtfN: (libc)Exponents and Logarithms. |
| * cbrtfNx: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosfN: (libc)Trig Functions. |
| * ccosfNx: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshfN: (libc)Hyperbolic Functions. |
| * ccoshfNx: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceilfN: (libc)Rounding Functions. |
| * ceilfNx: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpfN: (libc)Exponents and Logarithms. |
| * cexpfNx: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagfN: (libc)Operations on Complex. |
| * cimagfNx: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10fN: (libc)Exponents and Logarithms. |
| * clog10fNx: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogfN: (libc)Exponents and Logarithms. |
| * clogfNx: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * cnd_broadcast: (libc)ISO C Condition Variables. |
| * cnd_destroy: (libc)ISO C Condition Variables. |
| * cnd_init: (libc)ISO C Condition Variables. |
| * cnd_signal: (libc)ISO C Condition Variables. |
| * cnd_timedwait: (libc)ISO C Condition Variables. |
| * cnd_wait: (libc)ISO C Condition Variables. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjfN: (libc)Operations on Complex. |
| * conjfNx: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copy_file_range: (libc)Copying File Data. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignfN: (libc)FP Bit Twiddling. |
| * copysignfNx: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosfN: (libc)Trig Functions. |
| * cosfNx: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshfN: (libc)Hyperbolic Functions. |
| * coshfNx: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowfN: (libc)Exponents and Logarithms. |
| * cpowfNx: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojfN: (libc)Operations on Complex. |
| * cprojfNx: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * crealfN: (libc)Operations on Complex. |
| * crealfNx: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)Passphrase Storage. |
| * crypt_r: (libc)Passphrase Storage. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinfN: (libc)Trig Functions. |
| * csinfNx: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhfN: (libc)Hyperbolic Functions. |
| * csinhfNx: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtfN: (libc)Exponents and Logarithms. |
| * csqrtfNx: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanfN: (libc)Trig Functions. |
| * ctanfNx: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhfN: (libc)Hyperbolic Functions. |
| * ctanhfNx: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * daddl: (libc)Misc FP Arithmetic. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * ddivl: (libc)Misc FP Arithmetic. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dmull: (libc)Misc FP Arithmetic. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dsubl: (libc)Misc FP Arithmetic. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_remove: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcfN: (libc)Special Functions. |
| * erfcfNx: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erffN: (libc)Special Functions. |
| * erffNx: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10fN: (libc)Exponents and Logarithms. |
| * exp10fNx: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2fN: (libc)Exponents and Logarithms. |
| * exp2fNx: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expfN: (libc)Exponents and Logarithms. |
| * expfNx: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * explicit_bzero: (libc)Erasing Sensitive Data. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1fN: (libc)Exponents and Logarithms. |
| * expm1fNx: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fMaddfN: (libc)Misc FP Arithmetic. |
| * fMaddfNx: (libc)Misc FP Arithmetic. |
| * fMdivfN: (libc)Misc FP Arithmetic. |
| * fMdivfNx: (libc)Misc FP Arithmetic. |
| * fMmulfN: (libc)Misc FP Arithmetic. |
| * fMmulfNx: (libc)Misc FP Arithmetic. |
| * fMsubfN: (libc)Misc FP Arithmetic. |
| * fMsubfNx: (libc)Misc FP Arithmetic. |
| * fMxaddfN: (libc)Misc FP Arithmetic. |
| * fMxaddfNx: (libc)Misc FP Arithmetic. |
| * fMxdivfN: (libc)Misc FP Arithmetic. |
| * fMxdivfNx: (libc)Misc FP Arithmetic. |
| * fMxmulfN: (libc)Misc FP Arithmetic. |
| * fMxmulfNx: (libc)Misc FP Arithmetic. |
| * fMxsubfN: (libc)Misc FP Arithmetic. |
| * fMxsubfNx: (libc)Misc FP Arithmetic. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsfN: (libc)Absolute Value. |
| * fabsfNx: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fadd: (libc)Misc FP Arithmetic. |
| * faddl: (libc)Misc FP Arithmetic. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdimfN: (libc)Misc FP Arithmetic. |
| * fdimfNx: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdiv: (libc)Misc FP Arithmetic. |
| * fdivl: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetmode: (libc)Control Functions. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexcept: (libc)Status bit operations. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetmode: (libc)Control Functions. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * fetestexceptflag: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorfN: (libc)Rounding Functions. |
| * floorfNx: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmafN: (libc)Misc FP Arithmetic. |
| * fmafNx: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxfN: (libc)Misc FP Arithmetic. |
| * fmaxfNx: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmaxmag: (libc)Misc FP Arithmetic. |
| * fmaxmagf: (libc)Misc FP Arithmetic. |
| * fmaxmagfN: (libc)Misc FP Arithmetic. |
| * fmaxmagfNx: (libc)Misc FP Arithmetic. |
| * fmaxmagl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminfN: (libc)Misc FP Arithmetic. |
| * fminfNx: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fminmag: (libc)Misc FP Arithmetic. |
| * fminmagf: (libc)Misc FP Arithmetic. |
| * fminmagfN: (libc)Misc FP Arithmetic. |
| * fminmagfNx: (libc)Misc FP Arithmetic. |
| * fminmagl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodfN: (libc)Remainder Functions. |
| * fmodfNx: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fmul: (libc)Misc FP Arithmetic. |
| * fmull: (libc)Misc FP Arithmetic. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpfN: (libc)Normalization Functions. |
| * frexpfNx: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fromfp: (libc)Rounding Functions. |
| * fromfpf: (libc)Rounding Functions. |
| * fromfpfN: (libc)Rounding Functions. |
| * fromfpfNx: (libc)Rounding Functions. |
| * fromfpl: (libc)Rounding Functions. |
| * fromfpx: (libc)Rounding Functions. |
| * fromfpxf: (libc)Rounding Functions. |
| * fromfpxfN: (libc)Rounding Functions. |
| * fromfpxfNx: (libc)Rounding Functions. |
| * fromfpxl: (libc)Rounding Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsub: (libc)Misc FP Arithmetic. |
| * fsubl: (libc)Misc FP Arithmetic. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcpu: (libc)CPU Affinity. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdents64: (libc)Low-level Directory Access. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getentropy: (libc)Unpredictable Bytes. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpayload: (libc)FP Bit Twiddling. |
| * getpayloadf: (libc)FP Bit Twiddling. |
| * getpayloadfN: (libc)FP Bit Twiddling. |
| * getpayloadfNx: (libc)FP Bit Twiddling. |
| * getpayloadl: (libc)FP Bit Twiddling. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrandom: (libc)Unpredictable Bytes. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettid: (libc)Process Identification. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotfN: (libc)Exponents and Logarithms. |
| * hypotfNx: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbfN: (libc)Exponents and Logarithms. |
| * ilogbfNx: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscanonical: (libc)Floating Point Classes. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * iseqsig: (libc)FP Comparison Functions. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * issubnormal: (libc)Floating Point Classes. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * iszero: (libc)Floating Point Classes. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0fN: (libc)Special Functions. |
| * j0fNx: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1fN: (libc)Special Functions. |
| * j1fNx: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnfN: (libc)Special Functions. |
| * jnfNx: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpfN: (libc)Normalization Functions. |
| * ldexpfNx: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammafN: (libc)Special Functions. |
| * lgammafN_r: (libc)Special Functions. |
| * lgammafNx: (libc)Special Functions. |
| * lgammafNx_r: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * linkat: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llogb: (libc)Exponents and Logarithms. |
| * llogbf: (libc)Exponents and Logarithms. |
| * llogbfN: (libc)Exponents and Logarithms. |
| * llogbfNx: (libc)Exponents and Logarithms. |
| * llogbl: (libc)Exponents and Logarithms. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintfN: (libc)Rounding Functions. |
| * llrintfNx: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundfN: (libc)Rounding Functions. |
| * llroundfNx: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10fN: (libc)Exponents and Logarithms. |
| * log10fNx: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pfN: (libc)Exponents and Logarithms. |
| * log1pfNx: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2fN: (libc)Exponents and Logarithms. |
| * log2fNx: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbfN: (libc)Exponents and Logarithms. |
| * logbfNx: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * logfN: (libc)Exponents and Logarithms. |
| * logfNx: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintfN: (libc)Rounding Functions. |
| * lrintfNx: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundfN: (libc)Rounding Functions. |
| * lroundfNx: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying Strings and Arrays. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying Strings and Arrays. |
| * memfd_create: (libc)Memory-mapped I/O. |
| * memfrob: (libc)Obfuscating Data. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying Strings and Arrays. |
| * mempcpy: (libc)Copying Strings and Arrays. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying Strings and Arrays. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock2: (libc)Page Lock Functions. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modffN: (libc)Rounding Functions. |
| * modffNx: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mprotect: (libc)Memory Protection. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * mtx_destroy: (libc)ISO C Mutexes. |
| * mtx_init: (libc)ISO C Mutexes. |
| * mtx_lock: (libc)ISO C Mutexes. |
| * mtx_timedlock: (libc)ISO C Mutexes. |
| * mtx_trylock: (libc)ISO C Mutexes. |
| * mtx_unlock: (libc)ISO C Mutexes. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanfN: (libc)FP Bit Twiddling. |
| * nanfNx: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintfN: (libc)Rounding Functions. |
| * nearbyintfNx: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterfN: (libc)FP Bit Twiddling. |
| * nextafterfNx: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nextdown: (libc)FP Bit Twiddling. |
| * nextdownf: (libc)FP Bit Twiddling. |
| * nextdownfN: (libc)FP Bit Twiddling. |
| * nextdownfNx: (libc)FP Bit Twiddling. |
| * nextdownl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nextup: (libc)FP Bit Twiddling. |
| * nextupf: (libc)FP Bit Twiddling. |
| * nextupfN: (libc)FP Bit Twiddling. |
| * nextupfNx: (libc)FP Bit Twiddling. |
| * nextupl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * pkey_alloc: (libc)Memory Protection. |
| * pkey_free: (libc)Memory Protection. |
| * pkey_get: (libc)Memory Protection. |
| * pkey_mprotect: (libc)Memory Protection. |
| * pkey_set: (libc)Memory Protection. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_fallocate64: (libc)Storage Allocation. |
| * posix_fallocate: (libc)Storage Allocation. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powfN: (libc)Exponents and Logarithms. |
| * powfNx: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * preadv2: (libc)Scatter-Gather. |
| * preadv64: (libc)Scatter-Gather. |
| * preadv64v2: (libc)Scatter-Gather. |
| * preadv: (libc)Scatter-Gather. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_cond_clockwait: (libc)Default Thread Attributes. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_rwlock_clockrdlock: (libc)Default Thread Attributes. |
| * pthread_rwlock_clockwrlock: (libc)Default Thread Attributes. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * pwritev2: (libc)Scatter-Gather. |
| * pwritev64: (libc)Scatter-Gather. |
| * pwritev64v2: (libc)Scatter-Gather. |
| * pwritev: (libc)Scatter-Gather. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * reallocarray: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderfN: (libc)Remainder Functions. |
| * remainderfNx: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintfN: (libc)Rounding Functions. |
| * rintfNx: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundeven: (libc)Rounding Functions. |
| * roundevenf: (libc)Rounding Functions. |
| * roundevenfN: (libc)Rounding Functions. |
| * roundevenfNx: (libc)Rounding Functions. |
| * roundevenl: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundfN: (libc)Rounding Functions. |
| * roundfNx: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnfN: (libc)Normalization Functions. |
| * scalblnfNx: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnfN: (libc)Normalization Functions. |
| * scalbnfNx: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * sem_clockwait: (libc)Default Thread Attributes. |
| * sem_close: (libc)Semaphores. |
| * sem_destroy: (libc)Semaphores. |
| * sem_getvalue: (libc)Semaphores. |
| * sem_init: (libc)Semaphores. |
| * sem_open: (libc)Semaphores. |
| * sem_post: (libc)Semaphores. |
| * sem_timedwait: (libc)Semaphores. |
| * sem_trywait: (libc)Semaphores. |
| * sem_unlink: (libc)Semaphores. |
| * sem_wait: (libc)Semaphores. |
| * semctl: (libc)Semaphores. |
| * semget: (libc)Semaphores. |
| * semop: (libc)Semaphores. |
| * semtimedop: (libc)Semaphores. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpayload: (libc)FP Bit Twiddling. |
| * setpayloadf: (libc)FP Bit Twiddling. |
| * setpayloadfN: (libc)FP Bit Twiddling. |
| * setpayloadfNx: (libc)FP Bit Twiddling. |
| * setpayloadl: (libc)FP Bit Twiddling. |
| * setpayloadsig: (libc)FP Bit Twiddling. |
| * setpayloadsigf: (libc)FP Bit Twiddling. |
| * setpayloadsigfN: (libc)FP Bit Twiddling. |
| * setpayloadsigfNx: (libc)FP Bit Twiddling. |
| * setpayloadsigl: (libc)FP Bit Twiddling. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)BSD Signal Handling. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Signal Handling. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)BSD Signal Handling. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)BSD Signal Handling. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)BSD Signal Handling. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosfN: (libc)Trig Functions. |
| * sincosfNx: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinfN: (libc)Trig Functions. |
| * sinfNx: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhfN: (libc)Hyperbolic Functions. |
| * sinhfNx: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtfN: (libc)Exponents and Logarithms. |
| * sqrtfNx: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying Strings and Arrays. |
| * stpncpy: (libc)Truncating Strings. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Concatenating Strings. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying Strings and Arrays. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying Strings and Arrays. |
| * strdupa: (libc)Copying Strings and Arrays. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfromd: (libc)Printing of Floats. |
| * strfromf: (libc)Printing of Floats. |
| * strfromfN: (libc)Printing of Floats. |
| * strfromfNx: (libc)Printing of Floats. |
| * strfroml: (libc)Printing of Floats. |
| * strfry: (libc)Shuffling Bytes. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Truncating Strings. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Truncating Strings. |
| * strndup: (libc)Truncating Strings. |
| * strndupa: (libc)Truncating Strings. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtofN: (libc)Parsing of Floats. |
| * strtofNx: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanfN: (libc)Trig Functions. |
| * tanfNx: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhfN: (libc)Hyperbolic Functions. |
| * tanhfNx: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammafN: (libc)Special Functions. |
| * tgammafNx: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * tgkill: (libc)Signaling Another Process. |
| * thrd_create: (libc)ISO C Thread Management. |
| * thrd_current: (libc)ISO C Thread Management. |
| * thrd_detach: (libc)ISO C Thread Management. |
| * thrd_equal: (libc)ISO C Thread Management. |
| * thrd_exit: (libc)ISO C Thread Management. |
| * thrd_join: (libc)ISO C Thread Management. |
| * thrd_sleep: (libc)ISO C Thread Management. |
| * thrd_yield: (libc)ISO C Thread Management. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * totalorder: (libc)FP Comparison Functions. |
| * totalorderf: (libc)FP Comparison Functions. |
| * totalorderfN: (libc)FP Comparison Functions. |
| * totalorderfNx: (libc)FP Comparison Functions. |
| * totalorderl: (libc)FP Comparison Functions. |
| * totalordermag: (libc)FP Comparison Functions. |
| * totalordermagf: (libc)FP Comparison Functions. |
| * totalordermagfN: (libc)FP Comparison Functions. |
| * totalordermagfNx: (libc)FP Comparison Functions. |
| * totalordermagl: (libc)FP Comparison Functions. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncfN: (libc)Rounding Functions. |
| * truncfNx: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * tss_create: (libc)ISO C Thread-local Storage. |
| * tss_delete: (libc)ISO C Thread-local Storage. |
| * tss_get: (libc)ISO C Thread-local Storage. |
| * tss_set: (libc)ISO C Thread-local Storage. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * twalk_r: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ufromfp: (libc)Rounding Functions. |
| * ufromfpf: (libc)Rounding Functions. |
| * ufromfpfN: (libc)Rounding Functions. |
| * ufromfpfNx: (libc)Rounding Functions. |
| * ufromfpl: (libc)Rounding Functions. |
| * ufromfpx: (libc)Rounding Functions. |
| * ufromfpxf: (libc)Rounding Functions. |
| * ufromfpxfN: (libc)Rounding Functions. |
| * ufromfpxfNx: (libc)Rounding Functions. |
| * ufromfpxl: (libc)Rounding Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying Strings and Arrays. |
| * wcpncpy: (libc)Truncating Strings. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Concatenating Strings. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying Strings and Arrays. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying Strings and Arrays. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Truncating Strings. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Truncating Strings. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstofN: (libc)Parsing of Floats. |
| * wcstofNx: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying Strings and Arrays. |
| * wmemmove: (libc)Copying Strings and Arrays. |
| * wmempcpy: (libc)Copying Strings and Arrays. |
| * wmemset: (libc)Copying Strings and Arrays. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0fN: (libc)Special Functions. |
| * y0fNx: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1fN: (libc)Special Functions. |
| * y1fNx: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynfN: (libc)Special Functions. |
| * ynfNx: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the GNU C Library. |
| |
| This is `The GNU C Library Reference Manual', for version 2.30 |
| (GNU Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10)). |
| |
| Copyright (C) 1993-2019 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version |
| 1.3 or any later version published by the Free Software Foundation; |
| with the Invariant Sections being "Free Software Needs Free |
| Documentation" and "GNU Lesser General Public License", the Front-Cover |
| texts being "A GNU Manual", and with the Back-Cover Texts as in (a) |
| below. A copy of the license is included in the section entitled "GNU |
| Free Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| |
| |
| File: libc.info, Node: Program Error Signals, Next: Termination Signals, Up: Standard Signals |
| |
| 24.2.1 Program Error Signals |
| ---------------------------- |
| |
| The following signals are generated when a serious program error is |
| detected by the operating system or the computer itself. In general, |
| all of these signals are indications that your program is seriously |
| broken in some way, and there's usually no way to continue the |
| computation which encountered the error. |
| |
| Some programs handle program error signals in order to tidy up before |
| terminating; for example, programs that turn off echoing of terminal |
| input should handle program error signals in order to turn echoing back |
| on. The handler should end by specifying the default action for the |
| signal that happened and then reraising it; this will cause the program |
| to terminate with that signal, as if it had not had a handler. (*Note |
| Termination in Handler::.) |
| |
| Termination is the sensible ultimate outcome from a program error in |
| most programs. However, programming systems such as Lisp that can load |
| compiled user programs might need to keep executing even if a user |
| program incurs an error. These programs have handlers which use |
| `longjmp' to return control to the command level. |
| |
| The default action for all of these signals is to cause the process |
| to terminate. If you block or ignore these signals or establish |
| handlers for them that return normally, your program will probably |
| break horribly when such signals happen, unless they are generated by |
| `raise' or `kill' instead of a real error. |
| |
| When one of these program error signals terminates a process, it also |
| writes a "core dump file" which records the state of the process at the |
| time of termination. The core dump file is named `core' and is written |
| in whichever directory is current in the process at the time. (On |
| GNU/Hurd systems, you can specify the file name for core dumps with the |
| environment variable `COREFILE'.) The purpose of core dump files is so |
| that you can examine them with a debugger to investigate what caused |
| the error. |
| |
| -- Macro: int SIGFPE |
| The `SIGFPE' signal reports a fatal arithmetic error. Although the |
| name is derived from "floating-point exception", this signal |
| actually covers all arithmetic errors, including division by zero |
| and overflow. If a program stores integer data in a location |
| which is then used in a floating-point operation, this often |
| causes an "invalid operation" exception, because the processor |
| cannot recognize the data as a floating-point number. |
| |
| Actual floating-point exceptions are a complicated subject because |
| there are many types of exceptions with subtly different meanings, |
| and the `SIGFPE' signal doesn't distinguish between them. The |
| `IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std |
| 754-1985 and ANSI/IEEE Std 854-1987)' defines various |
| floating-point exceptions and requires conforming computer systems |
| to report their occurrences. However, this standard does not |
| specify how the exceptions are reported, or what kinds of handling |
| and control the operating system can offer to the programmer. |
| |
| BSD systems provide the `SIGFPE' handler with an extra argument that |
| distinguishes various causes of the exception. In order to access this |
| argument, you must define the handler to accept two arguments, which |
| means you must cast it to a one-argument function type in order to |
| establish the handler. The GNU C Library does provide this extra |
| argument, but the value is meaningful only on operating systems that |
| provide the information (BSD systems and GNU systems). |
| |
| `FPE_INTOVF_TRAP' |
| Integer overflow (impossible in a C program unless you enable |
| overflow trapping in a hardware-specific fashion). |
| |
| `FPE_INTDIV_TRAP' |
| Integer division by zero. |
| |
| `FPE_SUBRNG_TRAP' |
| Subscript-range (something that C programs never check for). |
| |
| `FPE_FLTOVF_TRAP' |
| Floating overflow trap. |
| |
| `FPE_FLTDIV_TRAP' |
| Floating/decimal division by zero. |
| |
| `FPE_FLTUND_TRAP' |
| Floating underflow trap. (Trapping on floating underflow is not |
| normally enabled.) |
| |
| `FPE_DECOVF_TRAP' |
| Decimal overflow trap. (Only a few machines have decimal |
| arithmetic and C never uses it.) |
| |
| -- Macro: int SIGILL |
| The name of this signal is derived from "illegal instruction"; it |
| usually means your program is trying to execute garbage or a |
| privileged instruction. Since the C compiler generates only valid |
| instructions, `SIGILL' typically indicates that the executable |
| file is corrupted, or that you are trying to execute data. Some |
| common ways of getting into the latter situation are by passing an |
| invalid object where a pointer to a function was expected, or by |
| writing past the end of an automatic array (or similar problems |
| with pointers to automatic variables) and corrupting other data on |
| the stack such as the return address of a stack frame. |
| |
| `SIGILL' can also be generated when the stack overflows, or when |
| the system has trouble running the handler for a signal. |
| |
| -- Macro: int SIGSEGV |
| This signal is generated when a program tries to read or write |
| outside the memory that is allocated for it, or to write memory |
| that can only be read. (Actually, the signals only occur when the |
| program goes far enough outside to be detected by the system's |
| memory protection mechanism.) The name is an abbreviation for |
| "segmentation violation". |
| |
| Common ways of getting a `SIGSEGV' condition include dereferencing |
| a null or uninitialized pointer, or when you use a pointer to step |
| through an array, but fail to check for the end of the array. It |
| varies among systems whether dereferencing a null pointer generates |
| `SIGSEGV' or `SIGBUS'. |
| |
| -- Macro: int SIGBUS |
| This signal is generated when an invalid pointer is dereferenced. |
| Like `SIGSEGV', this signal is typically the result of |
| dereferencing an uninitialized pointer. The difference between |
| the two is that `SIGSEGV' indicates an invalid access to valid |
| memory, while `SIGBUS' indicates an access to an invalid address. |
| In particular, `SIGBUS' signals often result from dereferencing a |
| misaligned pointer, such as referring to a four-word integer at an |
| address not divisible by four. (Each kind of computer has its own |
| requirements for address alignment.) |
| |
| The name of this signal is an abbreviation for "bus error". |
| |
| -- Macro: int SIGABRT |
| This signal indicates an error detected by the program itself and |
| reported by calling `abort'. *Note Aborting a Program::. |
| |
| -- Macro: int SIGIOT |
| Generated by the PDP-11 "iot" instruction. On most machines, this |
| is just another name for `SIGABRT'. |
| |
| -- Macro: int SIGTRAP |
| Generated by the machine's breakpoint instruction, and possibly |
| other trap instructions. This signal is used by debuggers. Your |
| program will probably only see `SIGTRAP' if it is somehow |
| executing bad instructions. |
| |
| -- Macro: int SIGEMT |
| Emulator trap; this results from certain unimplemented instructions |
| which might be emulated in software, or the operating system's |
| failure to properly emulate them. |
| |
| -- Macro: int SIGSYS |
| Bad system call; that is to say, the instruction to trap to the |
| operating system was executed, but the code number for the system |
| call to perform was invalid. |
| |
| |
| File: libc.info, Node: Termination Signals, Next: Alarm Signals, Prev: Program Error Signals, Up: Standard Signals |
| |
| 24.2.2 Termination Signals |
| -------------------------- |
| |
| These signals are all used to tell a process to terminate, in one way |
| or another. They have different names because they're used for slightly |
| different purposes, and programs might want to handle them differently. |
| |
| The reason for handling these signals is usually so your program can |
| tidy up as appropriate before actually terminating. For example, you |
| might want to save state information, delete temporary files, or restore |
| the previous terminal modes. Such a handler should end by specifying |
| the default action for the signal that happened and then reraising it; |
| this will cause the program to terminate with that signal, as if it had |
| not had a handler. (*Note Termination in Handler::.) |
| |
| The (obvious) default action for all of these signals is to cause the |
| process to terminate. |
| |
| -- Macro: int SIGTERM |
| The `SIGTERM' signal is a generic signal used to cause program |
| termination. Unlike `SIGKILL', this signal can be blocked, |
| handled, and ignored. It is the normal way to politely ask a |
| program to terminate. |
| |
| The shell command `kill' generates `SIGTERM' by default. |
| |
| -- Macro: int SIGINT |
| The `SIGINT' ("program interrupt") signal is sent when the user |
| types the INTR character (normally `C-c'). *Note Special |
| Characters::, for information about terminal driver support for |
| `C-c'. |
| |
| -- Macro: int SIGQUIT |
| The `SIGQUIT' signal is similar to `SIGINT', except that it's |
| controlled by a different key--the QUIT character, usually |
| `C-\'--and produces a core dump when it terminates the process, |
| just like a program error signal. You can think of this as a |
| program error condition "detected" by the user. |
| |
| *Note Program Error Signals::, for information about core dumps. |
| *Note Special Characters::, for information about terminal driver |
| support. |
| |
| Certain kinds of cleanups are best omitted in handling `SIGQUIT'. |
| For example, if the program creates temporary files, it should |
| handle the other termination requests by deleting the temporary |
| files. But it is better for `SIGQUIT' not to delete them, so that |
| the user can examine them in conjunction with the core dump. |
| |
| -- Macro: int SIGKILL |
| The `SIGKILL' signal is used to cause immediate program |
| termination. It cannot be handled or ignored, and is therefore |
| always fatal. It is also not possible to block this signal. |
| |
| This signal is usually generated only by explicit request. Since |
| it cannot be handled, you should generate it only as a last |
| resort, after first trying a less drastic method such as `C-c' or |
| `SIGTERM'. If a process does not respond to any other termination |
| signals, sending it a `SIGKILL' signal will almost always cause it |
| to go away. |
| |
| In fact, if `SIGKILL' fails to terminate a process, that by itself |
| constitutes an operating system bug which you should report. |
| |
| The system will generate `SIGKILL' for a process itself under some |
| unusual conditions where the program cannot possibly continue to |
| run (even to run a signal handler). |
| |
| -- Macro: int SIGHUP |
| The `SIGHUP' ("hang-up") signal is used to report that the user's |
| terminal is disconnected, perhaps because a network or telephone |
| connection was broken. For more information about this, see *note |
| Control Modes::. |
| |
| This signal is also used to report the termination of the |
| controlling process on a terminal to jobs associated with that |
| session; this termination effectively disconnects all processes in |
| the session from the controlling terminal. For more information, |
| see *note Termination Internals::. |
| |
| |
| File: libc.info, Node: Alarm Signals, Next: Asynchronous I/O Signals, Prev: Termination Signals, Up: Standard Signals |
| |
| 24.2.3 Alarm Signals |
| -------------------- |
| |
| These signals are used to indicate the expiration of timers. *Note |
| Setting an Alarm::, for information about functions that cause these |
| signals to be sent. |
| |
| The default behavior for these signals is to cause program |
| termination. This default is rarely useful, but no other default would |
| be useful; most of the ways of using these signals would require |
| handler functions in any case. |
| |
| -- Macro: int SIGALRM |
| This signal typically indicates expiration of a timer that |
| measures real or clock time. It is used by the `alarm' function, |
| for example. |
| |
| -- Macro: int SIGVTALRM |
| This signal typically indicates expiration of a timer that |
| measures CPU time used by the current process. The name is an |
| abbreviation for "virtual time alarm". |
| |
| -- Macro: int SIGPROF |
| This signal typically indicates expiration of a timer that measures |
| both CPU time used by the current process, and CPU time expended on |
| behalf of the process by the system. Such a timer is used to |
| implement code profiling facilities, hence the name of this signal. |
| |
| |
| File: libc.info, Node: Asynchronous I/O Signals, Next: Job Control Signals, Prev: Alarm Signals, Up: Standard Signals |
| |
| 24.2.4 Asynchronous I/O Signals |
| ------------------------------- |
| |
| The signals listed in this section are used in conjunction with |
| asynchronous I/O facilities. You have to take explicit action by |
| calling `fcntl' to enable a particular file descriptor to generate |
| these signals (*note Interrupt Input::). The default action for these |
| signals is to ignore them. |
| |
| -- Macro: int SIGIO |
| This signal is sent when a file descriptor is ready to perform |
| input or output. |
| |
| On most operating systems, terminals and sockets are the only |
| kinds of files that can generate `SIGIO'; other kinds, including |
| ordinary files, never generate `SIGIO' even if you ask them to. |
| |
| On GNU systems `SIGIO' will always be generated properly if you |
| successfully set asynchronous mode with `fcntl'. |
| |
| -- Macro: int SIGURG |
| This signal is sent when "urgent" or out-of-band data arrives on a |
| socket. *Note Out-of-Band Data::. |
| |
| -- Macro: int SIGPOLL |
| This is a System V signal name, more or less similar to `SIGIO'. |
| It is defined only for compatibility. |
| |
| |
| File: libc.info, Node: Job Control Signals, Next: Operation Error Signals, Prev: Asynchronous I/O Signals, Up: Standard Signals |
| |
| 24.2.5 Job Control Signals |
| -------------------------- |
| |
| These signals are used to support job control. If your system doesn't |
| support job control, then these macros are defined but the signals |
| themselves can't be raised or handled. |
| |
| You should generally leave these signals alone unless you really |
| understand how job control works. *Note Job Control::. |
| |
| -- Macro: int SIGCHLD |
| This signal is sent to a parent process whenever one of its child |
| processes terminates or stops. |
| |
| The default action for this signal is to ignore it. If you |
| establish a handler for this signal while there are child |
| processes that have terminated but not reported their status via |
| `wait' or `waitpid' (*note Process Completion::), whether your new |
| handler applies to those processes or not depends on the |
| particular operating system. |
| |
| -- Macro: int SIGCLD |
| This is an obsolete name for `SIGCHLD'. |
| |
| -- Macro: int SIGCONT |
| You can send a `SIGCONT' signal to a process to make it continue. |
| This signal is special--it always makes the process continue if it |
| is stopped, before the signal is delivered. The default behavior |
| is to do nothing else. You cannot block this signal. You can set |
| a handler, but `SIGCONT' always makes the process continue |
| regardless. |
| |
| Most programs have no reason to handle `SIGCONT'; they simply |
| resume execution without realizing they were ever stopped. You |
| can use a handler for `SIGCONT' to make a program do something |
| special when it is stopped and continued--for example, to reprint |
| a prompt when it is suspended while waiting for input. |
| |
| -- Macro: int SIGSTOP |
| The `SIGSTOP' signal stops the process. It cannot be handled, |
| ignored, or blocked. |
| |
| -- Macro: int SIGTSTP |
| The `SIGTSTP' signal is an interactive stop signal. Unlike |
| `SIGSTOP', this signal can be handled and ignored. |
| |
| Your program should handle this signal if you have a special need |
| to leave files or system tables in a secure state when a process is |
| stopped. For example, programs that turn off echoing should handle |
| `SIGTSTP' so they can turn echoing back on before stopping. |
| |
| This signal is generated when the user types the SUSP character |
| (normally `C-z'). For more information about terminal driver |
| support, see *note Special Characters::. |
| |
| -- Macro: int SIGTTIN |
| A process cannot read from the user's terminal while it is running |
| as a background job. When any process in a background job tries to |
| read from the terminal, all of the processes in the job are sent a |
| `SIGTTIN' signal. The default action for this signal is to stop |
| the process. For more information about how this interacts with |
| the terminal driver, see *note Access to the Terminal::. |
| |
| -- Macro: int SIGTTOU |
| This is similar to `SIGTTIN', but is generated when a process in a |
| background job attempts to write to the terminal or set its modes. |
| Again, the default action is to stop the process. `SIGTTOU' is |
| only generated for an attempt to write to the terminal if the |
| `TOSTOP' output mode is set; *note Output Modes::. |
| |
| While a process is stopped, no more signals can be delivered to it |
| until it is continued, except `SIGKILL' signals and (obviously) |
| `SIGCONT' signals. The signals are marked as pending, but not |
| delivered until the process is continued. The `SIGKILL' signal always |
| causes termination of the process and can't be blocked, handled or |
| ignored. You can ignore `SIGCONT', but it always causes the process to |
| be continued anyway if it is stopped. Sending a `SIGCONT' signal to a |
| process causes any pending stop signals for that process to be |
| discarded. Likewise, any pending `SIGCONT' signals for a process are |
| discarded when it receives a stop signal. |
| |
| When a process in an orphaned process group (*note Orphaned Process |
| Groups::) receives a `SIGTSTP', `SIGTTIN', or `SIGTTOU' signal and does |
| not handle it, the process does not stop. Stopping the process would |
| probably not be very useful, since there is no shell program that will |
| notice it stop and allow the user to continue it. What happens instead |
| depends on the operating system you are using. Some systems may do |
| nothing; others may deliver another signal instead, such as `SIGKILL' |
| or `SIGHUP'. On GNU/Hurd systems, the process dies with `SIGKILL'; |
| this avoids the problem of many stopped, orphaned processes lying |
| around the system. |
| |
| |
| File: libc.info, Node: Operation Error Signals, Next: Miscellaneous Signals, Prev: Job Control Signals, Up: Standard Signals |
| |
| 24.2.6 Operation Error Signals |
| ------------------------------ |
| |
| These signals are used to report various errors generated by an |
| operation done by the program. They do not necessarily indicate a |
| programming error in the program, but an error that prevents an |
| operating system call from completing. The default action for all of |
| them is to cause the process to terminate. |
| |
| -- Macro: int SIGPIPE |
| Broken pipe. If you use pipes or FIFOs, you have to design your |
| application so that one process opens the pipe for reading before |
| another starts writing. If the reading process never starts, or |
| terminates unexpectedly, writing to the pipe or FIFO raises a |
| `SIGPIPE' signal. If `SIGPIPE' is blocked, handled or ignored, |
| the offending call fails with `EPIPE' instead. |
| |
| Pipes and FIFO special files are discussed in more detail in *note |
| Pipes and FIFOs::. |
| |
| Another cause of `SIGPIPE' is when you try to output to a socket |
| that isn't connected. *Note Sending Data::. |
| |
| -- Macro: int SIGLOST |
| Resource lost. This signal is generated when you have an advisory |
| lock on an NFS file, and the NFS server reboots and forgets about |
| your lock. |
| |
| On GNU/Hurd systems, `SIGLOST' is generated when any server program |
| dies unexpectedly. It is usually fine to ignore the signal; |
| whatever call was made to the server that died just returns an |
| error. |
| |
| -- Macro: int SIGXCPU |
| CPU time limit exceeded. This signal is generated when the process |
| exceeds its soft resource limit on CPU time. *Note Limits on |
| Resources::. |
| |
| -- Macro: int SIGXFSZ |
| File size limit exceeded. This signal is generated when the |
| process attempts to extend a file so it exceeds the process's soft |
| resource limit on file size. *Note Limits on Resources::. |
| |
| |
| File: libc.info, Node: Miscellaneous Signals, Next: Signal Messages, Prev: Operation Error Signals, Up: Standard Signals |
| |
| 24.2.7 Miscellaneous Signals |
| ---------------------------- |
| |
| These signals are used for various other purposes. In general, they |
| will not affect your program unless it explicitly uses them for |
| something. |
| |
| -- Macro: int SIGUSR1 |
| -- Macro: int SIGUSR2 |
| The `SIGUSR1' and `SIGUSR2' signals are set aside for you to use |
| any way you want. They're useful for simple interprocess |
| communication, if you write a signal handler for them in the |
| program that receives the signal. |
| |
| There is an example showing the use of `SIGUSR1' and `SIGUSR2' in |
| *note Signaling Another Process::. |
| |
| The default action is to terminate the process. |
| |
| -- Macro: int SIGWINCH |
| Window size change. This is generated on some systems (including |
| GNU) when the terminal driver's record of the number of rows and |
| columns on the screen is changed. The default action is to ignore |
| it. |
| |
| If a program does full-screen display, it should handle `SIGWINCH'. |
| When the signal arrives, it should fetch the new screen size and |
| reformat its display accordingly. |
| |
| -- Macro: int SIGINFO |
| Information request. On 4.4 BSD and GNU/Hurd systems, this signal |
| is sent to all the processes in the foreground process group of |
| the controlling terminal when the user types the STATUS character |
| in canonical mode; *note Signal Characters::. |
| |
| If the process is the leader of the process group, the default |
| action is to print some status information about the system and |
| what the process is doing. Otherwise the default is to do nothing. |
| |
| |
| File: libc.info, Node: Signal Messages, Prev: Miscellaneous Signals, Up: Standard Signals |
| |
| 24.2.8 Signal Messages |
| ---------------------- |
| |
| We mentioned above that the shell prints a message describing the signal |
| that terminated a child process. The clean way to print a message |
| describing a signal is to use the functions `strsignal' and `psignal'. |
| These functions use a signal number to specify which kind of signal to |
| describe. The signal number may come from the termination status of a |
| child process (*note Process Completion::) or it may come from a signal |
| handler in the same process. |
| |
| -- Function: char * strsignal (int SIGNUM) |
| Preliminary: | MT-Unsafe race:strsignal locale | AS-Unsafe init |
| i18n corrupt heap | AC-Unsafe init corrupt mem | *Note POSIX |
| Safety Concepts::. |
| |
| This function returns a pointer to a statically-allocated string |
| containing a message describing the signal SIGNUM. You should not |
| modify the contents of this string; and, since it can be rewritten |
| on subsequent calls, you should save a copy of it if you need to |
| reference it later. |
| |
| This function is a GNU extension, declared in the header file |
| `string.h'. |
| |
| -- Function: void psignal (int SIGNUM, const char *MESSAGE) |
| Preliminary: | MT-Safe locale | AS-Unsafe corrupt i18n heap | |
| AC-Unsafe lock corrupt mem | *Note POSIX Safety Concepts::. |
| |
| This function prints a message describing the signal SIGNUM to the |
| standard error output stream `stderr'; see *note Standard |
| Streams::. |
| |
| If you call `psignal' with a MESSAGE that is either a null pointer |
| or an empty string, `psignal' just prints the message |
| corresponding to SIGNUM, adding a trailing newline. |
| |
| If you supply a non-null MESSAGE argument, then `psignal' prefixes |
| its output with this string. It adds a colon and a space |
| character to separate the MESSAGE from the string corresponding to |
| SIGNUM. |
| |
| This function is a BSD feature, declared in the header file |
| `signal.h'. |
| |
| There is also an array `sys_siglist' which contains the messages for |
| the various signal codes. This array exists on BSD systems, unlike |
| `strsignal'. |
| |
| |
| File: libc.info, Node: Signal Actions, Next: Defining Handlers, Prev: Standard Signals, Up: Signal Handling |
| |
| 24.3 Specifying Signal Actions |
| ============================== |
| |
| The simplest way to change the action for a signal is to use the |
| `signal' function. You can specify a built-in action (such as to |
| ignore the signal), or you can "establish a handler". |
| |
| The GNU C Library also implements the more versatile `sigaction' |
| facility. This section describes both facilities and gives suggestions |
| on which to use when. |
| |
| * Menu: |
| |
| * Basic Signal Handling:: The simple `signal' function. |
| * Advanced Signal Handling:: The more powerful `sigaction' function. |
| * Signal and Sigaction:: How those two functions interact. |
| * Sigaction Function Example:: An example of using the sigaction function. |
| * Flags for Sigaction:: Specifying options for signal handling. |
| * Initial Signal Actions:: How programs inherit signal actions. |
| |
| |
| File: libc.info, Node: Basic Signal Handling, Next: Advanced Signal Handling, Up: Signal Actions |
| |
| 24.3.1 Basic Signal Handling |
| ---------------------------- |
| |
| The `signal' function provides a simple interface for establishing an |
| action for a particular signal. The function and associated macros are |
| declared in the header file `signal.h'. |
| |
| -- Data Type: sighandler_t |
| This is the type of signal handler functions. Signal handlers |
| take one integer argument specifying the signal number, and have |
| return type `void'. So, you should define handler functions like |
| this: |
| |
| void HANDLER (int `signum') { ... } |
| |
| The name `sighandler_t' for this data type is a GNU extension. |
| |
| -- Function: sighandler_t signal (int SIGNUM, sighandler_t ACTION) |
| Preliminary: | MT-Safe sigintr | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The `signal' function establishes ACTION as the action for the |
| signal SIGNUM. |
| |
| The first argument, SIGNUM, identifies the signal whose behavior |
| you want to control, and should be a signal number. The proper |
| way to specify a signal number is with one of the symbolic signal |
| names (*note Standard Signals::)--don't use an explicit number, |
| because the numerical code for a given kind of signal may vary |
| from operating system to operating system. |
| |
| The second argument, ACTION, specifies the action to use for the |
| signal SIGNUM. This can be one of the following: |
| |
| `SIG_DFL' |
| `SIG_DFL' specifies the default action for the particular |
| signal. The default actions for various kinds of signals are |
| stated in *note Standard Signals::. |
| |
| `SIG_IGN' |
| `SIG_IGN' specifies that the signal should be ignored. |
| |
| Your program generally should not ignore signals that |
| represent serious events or that are normally used to request |
| termination. You cannot ignore the `SIGKILL' or `SIGSTOP' |
| signals at all. You can ignore program error signals like |
| `SIGSEGV', but ignoring the error won't enable the program to |
| continue executing meaningfully. Ignoring user requests such |
| as `SIGINT', `SIGQUIT', and `SIGTSTP' is unfriendly. |
| |
| When you do not wish signals to be delivered during a certain |
| part of the program, the thing to do is to block them, not |
| ignore them. *Note Blocking Signals::. |
| |
| `HANDLER' |
| Supply the address of a handler function in your program, to |
| specify running this handler as the way to deliver the signal. |
| |
| For more information about defining signal handler functions, |
| see *note Defining Handlers::. |
| |
| If you set the action for a signal to `SIG_IGN', or if you set it |
| to `SIG_DFL' and the default action is to ignore that signal, then |
| any pending signals of that type are discarded (even if they are |
| blocked). Discarding the pending signals means that they will |
| never be delivered, not even if you subsequently specify another |
| action and unblock this kind of signal. |
| |
| The `signal' function returns the action that was previously in |
| effect for the specified SIGNUM. You can save this value and |
| restore it later by calling `signal' again. |
| |
| If `signal' can't honor the request, it returns `SIG_ERR' instead. |
| The following `errno' error conditions are defined for this |
| function: |
| |
| `EINVAL' |
| You specified an invalid SIGNUM; or you tried to ignore or |
| provide a handler for `SIGKILL' or `SIGSTOP'. |
| |
| *Compatibility Note:* A problem encountered when working with the |
| `signal' function is that it has different semantics on BSD and SVID |
| systems. The difference is that on SVID systems the signal handler is |
| deinstalled after signal delivery. On BSD systems the handler must be |
| explicitly deinstalled. In the GNU C Library we use the BSD version by |
| default. To use the SVID version you can either use the function |
| `sysv_signal' (see below) or use the `_XOPEN_SOURCE' feature select |
| macro (*note Feature Test Macros::). In general, use of these |
| functions should be avoided because of compatibility problems. It is |
| better to use `sigaction' if it is available since the results are much |
| more reliable. |
| |
| Here is a simple example of setting up a handler to delete temporary |
| files when certain fatal signals happen: |
| |
| #include <signal.h> |
| |
| void |
| termination_handler (int signum) |
| { |
| struct temp_file *p; |
| |
| for (p = temp_file_list; p; p = p->next) |
| unlink (p->name); |
| } |
| |
| int |
| main (void) |
| { |
| ... |
| if (signal (SIGINT, termination_handler) == SIG_IGN) |
| signal (SIGINT, SIG_IGN); |
| if (signal (SIGHUP, termination_handler) == SIG_IGN) |
| signal (SIGHUP, SIG_IGN); |
| if (signal (SIGTERM, termination_handler) == SIG_IGN) |
| signal (SIGTERM, SIG_IGN); |
| ... |
| } |
| |
| Note that if a given signal was previously set to be ignored, this code |
| avoids altering that setting. This is because non-job-control shells |
| often ignore certain signals when starting children, and it is important |
| for the children to respect this. |
| |
| We do not handle `SIGQUIT' or the program error signals in this |
| example because these are designed to provide information for debugging |
| (a core dump), and the temporary files may give useful information. |
| |
| -- Function: sighandler_t sysv_signal (int SIGNUM, sighandler_t ACTION) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The `sysv_signal' implements the behavior of the standard `signal' |
| function as found on SVID systems. The difference to BSD systems |
| is that the handler is deinstalled after a delivery of a signal. |
| |
| *Compatibility Note:* As said above for `signal', this function |
| should be avoided when possible. `sigaction' is the preferred |
| method. |
| |
| -- Function: sighandler_t ssignal (int SIGNUM, sighandler_t ACTION) |
| Preliminary: | MT-Safe sigintr | AS-Safe | AC-Safe | *Note POSIX |
| Safety Concepts::. |
| |
| The `ssignal' function does the same thing as `signal'; it is |
| provided only for compatibility with SVID. |
| |
| -- Macro: sighandler_t SIG_ERR |
| The value of this macro is used as the return value from `signal' |
| to indicate an error. |
| |
| |
| File: libc.info, Node: Advanced Signal Handling, Next: Signal and Sigaction, Prev: Basic Signal Handling, Up: Signal Actions |
| |
| 24.3.2 Advanced Signal Handling |
| ------------------------------- |
| |
| The `sigaction' function has the same basic effect as `signal': to |
| specify how a signal should be handled by the process. However, |
| `sigaction' offers more control, at the expense of more complexity. In |
| particular, `sigaction' allows you to specify additional flags to |
| control when the signal is generated and how the handler is invoked. |
| |
| The `sigaction' function is declared in `signal.h'. |
| |
| -- Data Type: struct sigaction |
| Structures of type `struct sigaction' are used in the `sigaction' |
| function to specify all the information about how to handle a |
| particular signal. This structure contains at least the following |
| members: |
| |
| `sighandler_t sa_handler' |
| This is used in the same way as the ACTION argument to the |
| `signal' function. The value can be `SIG_DFL', `SIG_IGN', or |
| a function pointer. *Note Basic Signal Handling::. |
| |
| `sigset_t sa_mask' |
| This specifies a set of signals to be blocked while the |
| handler runs. Blocking is explained in *note Blocking for |
| Handler::. Note that the signal that was delivered is |
| automatically blocked by default before its handler is |
| started; this is true regardless of the value in `sa_mask'. |
| If you want that signal not to be blocked within its handler, |
| you must write code in the handler to unblock it. |
| |
| `int sa_flags' |
| This specifies various flags which can affect the behavior of |
| the signal. These are described in more detail in *note |
| Flags for Sigaction::. |
| |
| -- Function: int sigaction (int SIGNUM, const struct sigaction |
| *restrict ACTION, struct sigaction *restrict OLD-ACTION) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The ACTION argument is used to set up a new action for the signal |
| SIGNUM, while the OLD-ACTION argument is used to return |
| information about the action previously associated with this |
| signal. (In other words, OLD-ACTION has the same purpose as the |
| `signal' function's return value--you can check to see what the |
| old action in effect for the signal was, and restore it later if |
| you want.) |
| |
| Either ACTION or OLD-ACTION can be a null pointer. If OLD-ACTION |
| is a null pointer, this simply suppresses the return of |
| information about the old action. If ACTION is a null pointer, |
| the action associated with the signal SIGNUM is unchanged; this |
| allows you to inquire about how a signal is being handled without |
| changing that handling. |
| |
| The return value from `sigaction' is zero if it succeeds, and `-1' |
| on failure. The following `errno' error conditions are defined |
| for this function: |
| |
| `EINVAL' |
| The SIGNUM argument is not valid, or you are trying to trap |
| or ignore `SIGKILL' or `SIGSTOP'. |
| |
| |
| File: libc.info, Node: Signal and Sigaction, Next: Sigaction Function Example, Prev: Advanced Signal Handling, Up: Signal Actions |
| |
| 24.3.3 Interaction of `signal' and `sigaction' |
| ---------------------------------------------- |
| |
| It's possible to use both the `signal' and `sigaction' functions within |
| a single program, but you have to be careful because they can interact |
| in slightly strange ways. |
| |
| The `sigaction' function specifies more information than the |
| `signal' function, so the return value from `signal' cannot express the |
| full range of `sigaction' possibilities. Therefore, if you use |
| `signal' to save and later reestablish an action, it may not be able to |
| reestablish properly a handler that was established with `sigaction'. |
| |
| To avoid having problems as a result, always use `sigaction' to save |
| and restore a handler if your program uses `sigaction' at all. Since |
| `sigaction' is more general, it can properly save and reestablish any |
| action, regardless of whether it was established originally with |
| `signal' or `sigaction'. |
| |
| On some systems if you establish an action with `signal' and then |
| examine it with `sigaction', the handler address that you get may not |
| be the same as what you specified with `signal'. It may not even be |
| suitable for use as an action argument with `signal'. But you can rely |
| on using it as an argument to `sigaction'. This problem never happens |
| on GNU systems. |
| |
| So, you're better off using one or the other of the mechanisms |
| consistently within a single program. |
| |
| *Portability Note:* The basic `signal' function is a feature of |
| ISO C, while `sigaction' is part of the POSIX.1 standard. If you are |
| concerned about portability to non-POSIX systems, then you should use |
| the `signal' function instead. |
| |
| |
| File: libc.info, Node: Sigaction Function Example, Next: Flags for Sigaction, Prev: Signal and Sigaction, Up: Signal Actions |
| |
| 24.3.4 `sigaction' Function Example |
| ----------------------------------- |
| |
| In *note Basic Signal Handling::, we gave an example of establishing a |
| simple handler for termination signals using `signal'. Here is an |
| equivalent example using `sigaction': |
| |
| #include <signal.h> |
| |
| void |
| termination_handler (int signum) |
| { |
| struct temp_file *p; |
| |
| for (p = temp_file_list; p; p = p->next) |
| unlink (p->name); |
| } |
| |
| int |
| main (void) |
| { |
| ... |
| struct sigaction new_action, old_action; |
| |
| /* Set up the structure to specify the new action. */ |
| new_action.sa_handler = termination_handler; |
| sigemptyset (&new_action.sa_mask); |
| new_action.sa_flags = 0; |
| |
| sigaction (SIGINT, NULL, &old_action); |
| if (old_action.sa_handler != SIG_IGN) |
| sigaction (SIGINT, &new_action, NULL); |
| sigaction (SIGHUP, NULL, &old_action); |
| if (old_action.sa_handler != SIG_IGN) |
| sigaction (SIGHUP, &new_action, NULL); |
| sigaction (SIGTERM, NULL, &old_action); |
| if (old_action.sa_handler != SIG_IGN) |
| sigaction (SIGTERM, &new_action, NULL); |
| ... |
| } |
| |
| The program just loads the `new_action' structure with the desired |
| parameters and passes it in the `sigaction' call. The usage of |
| `sigemptyset' is described later; see *note Blocking Signals::. |
| |
| As in the example using `signal', we avoid handling signals |
| previously set to be ignored. Here we can avoid altering the signal |
| handler even momentarily, by using the feature of `sigaction' that lets |
| us examine the current action without specifying a new one. |
| |
| Here is another example. It retrieves information about the current |
| action for `SIGINT' without changing that action. |
| |
| struct sigaction query_action; |
| |
| if (sigaction (SIGINT, NULL, &query_action) < 0) |
| /* `sigaction' returns -1 in case of error. */ |
| else if (query_action.sa_handler == SIG_DFL) |
| /* `SIGINT' is handled in the default, fatal manner. */ |
| else if (query_action.sa_handler == SIG_IGN) |
| /* `SIGINT' is ignored. */ |
| else |
| /* A programmer-defined signal handler is in effect. */ |
| |
| |
| File: libc.info, Node: Flags for Sigaction, Next: Initial Signal Actions, Prev: Sigaction Function Example, Up: Signal Actions |
| |
| 24.3.5 Flags for `sigaction' |
| ---------------------------- |
| |
| The `sa_flags' member of the `sigaction' structure is a catch-all for |
| special features. Most of the time, `SA_RESTART' is a good value to |
| use for this field. |
| |
| The value of `sa_flags' is interpreted as a bit mask. Thus, you |
| should choose the flags you want to set, OR those flags together, and |
| store the result in the `sa_flags' member of your `sigaction' structure. |
| |
| Each signal number has its own set of flags. Each call to |
| `sigaction' affects one particular signal number, and the flags that |
| you specify apply only to that particular signal. |
| |
| In the GNU C Library, establishing a handler with `signal' sets all |
| the flags to zero except for `SA_RESTART', whose value depends on the |
| settings you have made with `siginterrupt'. *Note Interrupted |
| Primitives::, to see what this is about. |
| |
| These macros are defined in the header file `signal.h'. |
| |
| -- Macro: int SA_NOCLDSTOP |
| This flag is meaningful only for the `SIGCHLD' signal. When the |
| flag is set, the system delivers the signal for a terminated child |
| process but not for one that is stopped. By default, `SIGCHLD' is |
| delivered for both terminated children and stopped children. |
| |
| Setting this flag for a signal other than `SIGCHLD' has no effect. |
| |
| -- Macro: int SA_ONSTACK |
| If this flag is set for a particular signal number, the system |
| uses the signal stack when delivering that kind of signal. *Note |
| Signal Stack::. If a signal with this flag arrives and you have |
| not set a signal stack, the system terminates the program with |
| `SIGILL'. |
| |
| -- Macro: int SA_RESTART |
| This flag controls what happens when a signal is delivered during |
| certain primitives (such as `open', `read' or `write'), and the |
| signal handler returns normally. There are two alternatives: the |
| library function can resume, or it can return failure with error |
| code `EINTR'. |
| |
| The choice is controlled by the `SA_RESTART' flag for the |
| particular kind of signal that was delivered. If the flag is set, |
| returning from a handler resumes the library function. If the |
| flag is clear, returning from a handler makes the function fail. |
| *Note Interrupted Primitives::. |
| |
| |
| File: libc.info, Node: Initial Signal Actions, Prev: Flags for Sigaction, Up: Signal Actions |
| |
| 24.3.6 Initial Signal Actions |
| ----------------------------- |
| |
| When a new process is created (*note Creating a Process::), it inherits |
| handling of signals from its parent process. However, when you load a |
| new process image using the `exec' function (*note Executing a File::), |
| any signals that you've defined your own handlers for revert to their |
| `SIG_DFL' handling. (If you think about it a little, this makes sense; |
| the handler functions from the old program are specific to that |
| program, and aren't even present in the address space of the new |
| program image.) Of course, the new program can establish its own |
| handlers. |
| |
| When a program is run by a shell, the shell normally sets the initial |
| actions for the child process to `SIG_DFL' or `SIG_IGN', as |
| appropriate. It's a good idea to check to make sure that the shell has |
| not set up an initial action of `SIG_IGN' before you establish your own |
| signal handlers. |
| |
| Here is an example of how to establish a handler for `SIGHUP', but |
| not if `SIGHUP' is currently ignored: |
| |
| ... |
| struct sigaction temp; |
| |
| sigaction (SIGHUP, NULL, &temp); |
| |
| if (temp.sa_handler != SIG_IGN) |
| { |
| temp.sa_handler = handle_sighup; |
| sigemptyset (&temp.sa_mask); |
| sigaction (SIGHUP, &temp, NULL); |
| } |
| |
| |
| File: libc.info, Node: Defining Handlers, Next: Interrupted Primitives, Prev: Signal Actions, Up: Signal Handling |
| |
| 24.4 Defining Signal Handlers |
| ============================= |
| |
| This section describes how to write a signal handler function that can |
| be established with the `signal' or `sigaction' functions. |
| |
| A signal handler is just a function that you compile together with |
| the rest of the program. Instead of directly invoking the function, |
| you use `signal' or `sigaction' to tell the operating system to call it |
| when a signal arrives. This is known as "establishing" the handler. |
| *Note Signal Actions::. |
| |
| There are two basic strategies you can use in signal handler |
| functions: |
| |
| * You can have the handler function note that the signal arrived by |
| tweaking some global data structures, and then return normally. |
| |
| * You can have the handler function terminate the program or transfer |
| control to a point where it can recover from the situation that |
| caused the signal. |
| |
| You need to take special care in writing handler functions because |
| they can be called asynchronously. That is, a handler might be called |
| at any point in the program, unpredictably. If two signals arrive |
| during a very short interval, one handler can run within another. This |
| section describes what your handler should do, and what you should |
| avoid. |
| |
| * Menu: |
| |
| * Handler Returns:: Handlers that return normally, and what |
| this means. |
| * Termination in Handler:: How handler functions terminate a program. |
| * Longjmp in Handler:: Nonlocal transfer of control out of a |
| signal handler. |
| * Signals in Handler:: What happens when signals arrive while |
| the handler is already occupied. |
| * Merged Signals:: When a second signal arrives before the |
| first is handled. |
| * Nonreentrancy:: Do not call any functions unless you know they |
| are reentrant with respect to signals. |
| * Atomic Data Access:: A single handler can run in the middle of |
| reading or writing a single object. |
| |
| |
| 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::. |
| |
| -- 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. |
| |
| -- 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' command |
| 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::. |
| |
| *Future Change Warning:* Proposed Federal censorship regulations may |
| prohibit us from giving you information about the possibility of |
| calling this function. We would be required to say that this is not an |
| acceptable way of terminating a program. |
| |
| |
| 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 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; |
| } |
| |
| |
| File: libc.info, Node: Process Completion Status, Next: BSD Wait Functions, Prev: Process Completion, Up: Processes |
| |
| 26.7 Process Completion Status |
| ============================== |
| |
| If the exit status value (*note Program Termination::) of the child |
| process is zero, then the status value reported by `waitpid' or `wait' |
| is also zero. You can test for other kinds of information encoded in |
| the returned status value using the following macros. These macros are |
| defined in the header file `sys/wait.h'. |
| |
| -- Macro: int WIFEXITED (int STATUS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value if the child process terminated |
| normally with `exit' or `_exit'. |
| |
| -- Macro: int WEXITSTATUS (int STATUS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If `WIFEXITED' is true of STATUS, this macro returns the low-order |
| 8 bits of the exit status value from the child process. *Note |
| Exit Status::. |
| |
| -- Macro: int WIFSIGNALED (int STATUS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value if the child process terminated |
| because it received a signal that was not handled. *Note Signal |
| Handling::. |
| |
| -- Macro: int WTERMSIG (int STATUS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If `WIFSIGNALED' is true of STATUS, this macro returns the signal |
| number of the signal that terminated the child process. |
| |
| -- Macro: int WCOREDUMP (int STATUS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value if the child process terminated |
| and produced a core dump. |
| |
| -- Macro: int WIFSTOPPED (int STATUS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This macro returns a nonzero value if the child process is stopped. |
| |
| -- Macro: int WSTOPSIG (int STATUS) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| If `WIFSTOPPED' is true of STATUS, this macro returns the signal |
| number of the signal that caused the child process to stop. |
| |
| |
| File: libc.info, Node: BSD Wait Functions, Next: Process Creation Example, Prev: Process Completion Status, Up: Processes |
| |
| 26.8 BSD Process Wait Function |
| ============================== |
| |
| The GNU C Library also provides the `wait3' function for compatibility |
| with BSD. This function is declared in `sys/wait.h'. It is the |
| predecessor to `wait4', which is more flexible. `wait3' is now |
| obsolete. |
| |
| -- Function: pid_t wait3 (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, `wait3' is equivalent to `waitpid (-1, |
| STATUS-PTR, OPTIONS)'. |
| |
| If USAGE is not null, `wait3' stores usage figures for the child |
| process in `*RUSAGE' (but only if the child has terminated, not if |
| it has stopped). *Note Resource Usage::. |
| |
| |
| File: libc.info, Node: Process Creation Example, Prev: BSD Wait Functions, Up: Processes |
| |
| 26.9 Process Creation Example |
| ============================= |
| |
| Here is an example program showing how you might write a function |
| similar to the built-in `system'. It executes its COMMAND argument |
| using the equivalent of `sh -c COMMAND'. |
| |
| #include <stddef.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| #include <sys/types.h> |
| #include <sys/wait.h> |
| |
| /* Execute the command using this shell program. */ |
| #define SHELL "/bin/sh" |
| |
| int |
| my_system (const char *command) |
| { |
| int status; |
| pid_t pid; |
| |
| pid = fork (); |
| if (pid == 0) |
| { |
| /* This is the child process. Execute the shell command. */ |
| execl (SHELL, SHELL, "-c", command, NULL); |
| _exit (EXIT_FAILURE); |
| } |
| else if (pid < 0) |
| /* The fork failed. Report failure. */ |
| status = -1; |
| else |
| /* This is the parent process. Wait for the child to complete. */ |
| if (waitpid (pid, &status, 0) != pid) |
| status = -1; |
| return status; |
| } |
| |
| There are a couple of things you should pay attention to in this |
| example. |
| |
| Remember that the first `argv' argument supplied to the program |
| represents the name of the program being executed. That is why, in the |
| call to `execl', `SHELL' is supplied once to name the program to |
| execute and a second time to supply a value for `argv[0]'. |
| |
| The `execl' call in the child process doesn't return if it is |
| successful. If it fails, you must do something to make the child |
| process terminate. Just returning a bad status code with `return' |
| would leave two processes running the original program. Instead, the |
| right behavior is for the child process to report failure to its parent |
| process. |
| |
| Call `_exit' to accomplish this. The reason for using `_exit' |
| instead of `exit' is to avoid flushing fully buffered streams such as |
| `stdout'. The buffers of these streams probably contain data that was |
| copied from the parent process by the `fork', data that will be output |
| eventually by the parent process. Calling `exit' in the child would |
| output the data twice. *Note Termination Internals::. |
| |
| |
| File: libc.info, Node: Inter-Process Communication, Next: Job Control, Prev: Processes, Up: Top |
| |
| 27 Inter-Process Communication |
| ****************************** |
| |
| This chapter describes the GNU C Library inter-process communication |
| primitives. |
| |
| * Menu: |
| |
| * Semaphores:: Support for creating and managing semaphores |
| |
| |
| File: libc.info, Node: Semaphores, Up: Inter-Process Communication |
| |
| 27.1 Semaphores |
| =============== |
| |
| The GNU C Library implements the semaphore APIs as defined in POSIX and |
| System V. Semaphores can be used by multiple processes to coordinate |
| shared resources. The following is a complete list of the semaphore |
| functions provided by the GNU C Library. |
| |
| 27.1.1 System V Semaphores |
| -------------------------- |
| |
| -- Function: int semctl (int SEMID, int SEMNUM, int CMD); |
| Preliminary: | MT-Safe | AS-Safe | AC-Unsafe corrupt/linux | *Note |
| POSIX Safety Concepts::. |
| |
| |
| -- Function: int semget (key_t KEY, int NSEMS, int SEMFLG); |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| |
| -- Function: int semop (int SEMID, struct sembuf *SOPS, size_t NSOPS); |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| |
| -- Function: int semtimedop (int SEMID, struct sembuf *SOPS, size_t |
| NSOPS, const struct timespec *TIMEOUT); |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| |
| 27.1.2 POSIX Semaphores |
| ----------------------- |
| |
| -- Function: int sem_init (sem_t *SEM, int PSHARED, unsigned int |
| VALUE); |
| Preliminary: | MT-Safe | AS-Safe | AC-Unsafe corrupt | *Note POSIX |
| Safety Concepts::. |
| |
| |
| -- Function: int sem_destroy (sem_t *SEM); |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| |
| -- Function: sem_t *sem_open (const char *NAME, int OFLAG, ...); |
| Preliminary: | MT-Safe | AS-Unsafe init | AC-Unsafe init | *Note |
| POSIX Safety Concepts::. |
| |
| |
| -- Function: int sem_close (sem_t *SEM); |
| Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note |
| POSIX Safety Concepts::. |
| |
| |
| -- Function: int sem_unlink (const char *NAME); |
| Preliminary: | MT-Safe | AS-Unsafe init | AC-Unsafe corrupt | |
| *Note POSIX Safety Concepts::. |
| |
| |
| -- Function: int sem_wait (sem_t *SEM); |
| Preliminary: | MT-Safe | AS-Safe | AC-Unsafe corrupt | *Note POSIX |
| Safety Concepts::. |
| |
| |
| -- Function: int sem_timedwait (sem_t *SEM, const struct timespec |
| *ABSTIME); |
| Preliminary: | MT-Safe | AS-Safe | AC-Unsafe corrupt | *Note POSIX |
| Safety Concepts::. |
| |
| |
| -- Function: int sem_trywait (sem_t *SEM); |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| |
| -- Function: int sem_post (sem_t *SEM); |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| |
| -- Function: int sem_getvalue (sem_t *SEM, int *SVAL); |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| |
| |
| File: libc.info, Node: Job Control, Next: Name Service Switch, Prev: Inter-Process Communication, Up: Top |
| |
| 28 Job Control |
| ************** |
| |
| "Job control" refers to the protocol for allowing a user to move |
| between multiple "process groups" (or "jobs") within a single "login |
| session". The job control facilities are set up so that appropriate |
| behavior for most programs happens automatically and they need not do |
| anything special about job control. So you can probably ignore the |
| material in this chapter unless you are writing a shell or login |
| program. |
| |
| You need to be familiar with concepts relating to process creation |
| (*note Process Creation Concepts::) and signal handling (*note Signal |
| Handling::) in order to understand this material presented in this |
| chapter. |
| |
| Some old systems do not support job control, but GNU systems always |
| have, and it is a required feature in the 2001 revision of POSIX.1 |
| (*note POSIX::). If you need to be portable to old systems, you can |
| use the `_POSIX_JOB_CONTROL' macro to test at compile-time whether the |
| system supports job control. *Note System Options::. |
| |
| * Menu: |
| |
| * Concepts of Job Control:: Jobs can be controlled by a shell. |
| * Controlling Terminal:: How a process gets its controlling terminal. |
| * Access to the Terminal:: How processes share the controlling terminal. |
| * Orphaned Process Groups:: Jobs left after the user logs out. |
| * Implementing a Shell:: What a shell must do to implement job control. |
| * Functions for Job Control:: Functions to control process groups. |
| |
| |
| File: libc.info, Node: Concepts of Job Control, Next: Controlling Terminal, Up: Job Control |
| |
| 28.1 Concepts of Job Control |
| ============================ |
| |
| The fundamental purpose of an interactive shell is to read commands |
| from the user's terminal and create processes to execute the programs |
| specified by those commands. It can do this using the `fork' (*note |
| Creating a Process::) and `exec' (*note Executing a File::) functions. |
| |
| A single command may run just one process--but often one command uses |
| several processes. If you use the `|' operator in a shell command, you |
| explicitly request several programs in their own processes. But even |
| if you run just one program, it can use multiple processes internally. |
| For example, a single compilation command such as `cc -c foo.c' |
| typically uses four processes (though normally only two at any given |
| time). If you run `make', its job is to run other programs in separate |
| processes. |
| |
| The processes belonging to a single command are called a "process |
| group" or "job". This is so that you can operate on all of them at |
| once. For example, typing `C-c' sends the signal `SIGINT' to terminate |
| all the processes in the foreground process group. |
| |
| A "session" is a larger group of processes. Normally all the |
| processes that stem from a single login belong to the same session. |
| |
| Every process belongs to a process group. When a process is |
| created, it becomes a member of the same process group and session as |
| its parent process. You can put it in another process group using the |
| `setpgid' function, provided the process group belongs to the same |
| session. |
| |
| The only way to put a process in a different session is to make it |
| the initial process of a new session, or a "session leader", using the |
| `setsid' function. This also puts the session leader into a new |
| process group, and you can't move it out of that process group again. |
| |
| Usually, new sessions are created by the system login program, and |
| the session leader is the process running the user's login shell. |
| |
| A shell that supports job control must arrange to control which job |
| can use the terminal at any time. Otherwise there might be multiple |
| jobs trying to read from the terminal at once, and confusion about which |
| process should receive the input typed by the user. To prevent this, |
| the shell must cooperate with the terminal driver using the protocol |
| described in this chapter. |
| |
| The shell can give unlimited access to the controlling terminal to |
| only one process group at a time. This is called the "foreground job" |
| on that controlling terminal. Other process groups managed by the shell |
| that are executing without such access to the terminal are called |
| "background jobs". |
| |
| If a background job needs to read from its controlling terminal, it |
| is "stopped" by the terminal driver; if the `TOSTOP' mode is set, |
| likewise for writing. The user can stop a foreground job by typing the |
| SUSP character (*note Special Characters::) and a program can stop any |
| job by sending it a `SIGSTOP' signal. It's the responsibility of the |
| shell to notice when jobs stop, to notify the user about them, and to |
| provide mechanisms for allowing the user to interactively continue |
| stopped jobs and switch jobs between foreground and background. |
| |
| *Note Access to the Terminal::, for more information about I/O to the |
| controlling terminal. |
| |
| |
| File: libc.info, Node: Controlling Terminal, Next: Access to the Terminal, Prev: Concepts of Job Control, Up: Job Control |
| |
| 28.2 Controlling Terminal of a Process |
| ====================================== |
| |
| One of the attributes of a process is its controlling terminal. Child |
| processes created with `fork' inherit the controlling terminal from |
| their parent process. In this way, all the processes in a session |
| inherit the controlling terminal from the session leader. A session |
| leader that has control of a terminal is called the "controlling |
| process" of that terminal. |
| |
| You generally do not need to worry about the exact mechanism used to |
| allocate a controlling terminal to a session, since it is done for you |
| by the system when you log in. |
| |
| An individual process disconnects from its controlling terminal when |
| it calls `setsid' to become the leader of a new session. *Note Process |
| Group Functions::. |
| |
| |
| File: libc.info, Node: Access to the Terminal, Next: Orphaned Process Groups, Prev: Controlling Terminal, Up: Job Control |
| |
| 28.3 Access to the Controlling Terminal |
| ======================================= |
| |
| Processes in the foreground job of a controlling terminal have |
| unrestricted access to that terminal; background processes do not. This |
| section describes in more detail what happens when a process in a |
| background job tries to access its controlling terminal. |
| |
| When a process in a background job tries to read from its controlling |
| terminal, the process group is usually sent a `SIGTTIN' signal. This |
| normally causes all of the processes in that group to stop (unless they |
| handle the signal and don't stop themselves). However, if the reading |
| process is ignoring or blocking this signal, then `read' fails with an |
| `EIO' error instead. |
| |
| Similarly, when a process in a background job tries to write to its |
| controlling terminal, the default behavior is to send a `SIGTTOU' |
| signal to the process group. However, the behavior is modified by the |
| `TOSTOP' bit of the local modes flags (*note Local Modes::). If this |
| bit is not set (which is the default), then writing to the controlling |
| terminal is always permitted without sending a signal. Writing is also |
| permitted if the `SIGTTOU' signal is being ignored or blocked by the |
| writing process. |
| |
| Most other terminal operations that a program can do are treated as |
| reading or as writing. (The description of each operation should say |
| which.) |
| |
| For more information about the primitive `read' and `write' |
| functions, see *note I/O Primitives::. |
| |
| |
| File: libc.info, Node: Orphaned Process Groups, Next: Implementing a Shell, Prev: Access to the Terminal, Up: Job Control |
| |
| 28.4 Orphaned Process Groups |
| ============================ |
| |
| When a controlling process terminates, its terminal becomes free and a |
| new session can be established on it. (In fact, another user could log |
| in on the terminal.) This could cause a problem if any processes from |
| the old session are still trying to use that terminal. |
| |
| To prevent problems, process groups that continue running even after |
| the session leader has terminated are marked as "orphaned process |
| groups". |
| |
| When a process group becomes an orphan, its processes are sent a |
| `SIGHUP' signal. Ordinarily, this causes the processes to terminate. |
| However, if a program ignores this signal or establishes a handler for |
| it (*note Signal Handling::), it can continue running as in the orphan |
| process group even after its controlling process terminates; but it |
| still cannot access the terminal any more. |
| |
| |
| File: libc.info, Node: Implementing a Shell, Next: Functions for Job Control, Prev: Orphaned Process Groups, Up: Job Control |
| |
| 28.5 Implementing a Job Control Shell |
| ===================================== |
| |
| This section describes what a shell must do to implement job control, by |
| presenting an extensive sample program to illustrate the concepts |
| involved. |
| |
| * Menu: |
| |
| * Data Structures:: Introduction to the sample shell. |
| * Initializing the Shell:: What the shell must do to take |
| responsibility for job control. |
| * Launching Jobs:: Creating jobs to execute commands. |
| * Foreground and Background:: Putting a job in foreground of background. |
| * Stopped and Terminated Jobs:: Reporting job status. |
| * Continuing Stopped Jobs:: How to continue a stopped job in |
| the foreground or background. |
| * Missing Pieces:: Other parts of the shell. |
| |
| |
| File: libc.info, Node: Data Structures, Next: Initializing the Shell, Up: Implementing a Shell |
| |
| 28.5.1 Data Structures for the Shell |
| ------------------------------------ |
| |
| All of the program examples included in this chapter are part of a |
| simple shell program. This section presents data structures and |
| utility functions which are used throughout the example. |
| |
| The sample shell deals mainly with two data structures. The `job' |
| type contains information about a job, which is a set of subprocesses |
| linked together with pipes. The `process' type holds information about |
| a single subprocess. Here are the relevant data structure declarations: |
| |
| /* A process is a single process. */ |
| typedef struct process |
| { |
| struct process *next; /* next process in pipeline */ |
| char **argv; /* for exec */ |
| pid_t pid; /* process ID */ |
| char completed; /* true if process has completed */ |
| char stopped; /* true if process has stopped */ |
| int status; /* reported status value */ |
| } process; |
| |
| /* A job is a pipeline of processes. */ |
| typedef struct job |
| { |
| struct job *next; /* next active job */ |
| char *command; /* command line, used for messages */ |
| process *first_process; /* list of processes in this job */ |
| pid_t pgid; /* process group ID */ |
| char notified; /* true if user told about stopped job */ |
| struct termios tmodes; /* saved terminal modes */ |
| int stdin, stdout, stderr; /* standard i/o channels */ |
| } job; |
| |
| /* The active jobs are linked into a list. This is its head. */ |
| job *first_job = NULL; |
| |
| Here are some utility functions that are used for operating on `job' |
| objects. |
| |
| /* Find the active job with the indicated PGID. */ |
| job * |
| find_job (pid_t pgid) |
| { |
| job *j; |
| |
| for (j = first_job; j; j = j->next) |
| if (j->pgid == pgid) |
| return j; |
| return NULL; |
| } |
| |
| /* Return true if all processes in the job have stopped or completed. */ |
| int |
| job_is_stopped (job *j) |
| { |
| process *p; |
| |
| for (p = j->first_process; p; p = p->next) |
| if (!p->completed && !p->stopped) |
| return 0; |
| return 1; |
| } |
| |
| /* Return true if all processes in the job have completed. */ |
| int |
| job_is_completed (job *j) |
| { |
| process *p; |
| |
| for (p = j->first_process; p; p = p->next) |
| if (!p->completed) |
| return 0; |
| return 1; |
| } |
| |
| |
| File: libc.info, Node: Initializing the Shell, Next: Launching Jobs, Prev: Data Structures, Up: Implementing a Shell |
| |
| 28.5.2 Initializing the Shell |
| ----------------------------- |
| |
| When a shell program that normally performs job control is started, it |
| has to be careful in case it has been invoked from another shell that is |
| already doing its own job control. |
| |
| A subshell that runs interactively has to ensure that it has been |
| placed in the foreground by its parent shell before it can enable job |
| control itself. It does this by getting its initial process group ID |
| with the `getpgrp' function, and comparing it to the process group ID |
| of the current foreground job associated with its controlling terminal |
| (which can be retrieved using the `tcgetpgrp' function). |
| |
| If the subshell is not running as a foreground job, it must stop |
| itself by sending a `SIGTTIN' signal to its own process group. It may |
| not arbitrarily put itself into the foreground; it must wait for the |
| user to tell the parent shell to do this. If the subshell is continued |
| again, it should repeat the check and stop itself again if it is still |
| not in the foreground. |
| |
| Once the subshell has been placed into the foreground by its parent |
| shell, it can enable its own job control. It does this by calling |
| `setpgid' to put itself into its own process group, and then calling |
| `tcsetpgrp' to place this process group into the foreground. |
| |
| When a shell enables job control, it should set itself to ignore all |
| the job control stop signals so that it doesn't accidentally stop |
| itself. You can do this by setting the action for all the stop signals |
| to `SIG_IGN'. |
| |
| A subshell that runs non-interactively cannot and should not support |
| job control. It must leave all processes it creates in the same process |
| group as the shell itself; this allows the non-interactive shell and its |
| child processes to be treated as a single job by the parent shell. This |
| is easy to do--just don't use any of the job control primitives--but |
| you must remember to make the shell do it. |
| |
| Here is the initialization code for the sample shell that shows how |
| to do all of this. |
| |
| /* Keep track of attributes of the shell. */ |
| |
| #include <sys/types.h> |
| #include <termios.h> |
| #include <unistd.h> |
| |
| pid_t shell_pgid; |
| struct termios shell_tmodes; |
| int shell_terminal; |
| int shell_is_interactive; |
| |
| |
| /* Make sure the shell is running interactively as the foreground job |
| before proceeding. */ |
| |
| void |
| init_shell () |
| { |
| |
| /* See if we are running interactively. */ |
| shell_terminal = STDIN_FILENO; |
| shell_is_interactive = isatty (shell_terminal); |
| |
| if (shell_is_interactive) |
| { |
| /* Loop until we are in the foreground. */ |
| while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ())) |
| kill (- shell_pgid, SIGTTIN); |
| |
| /* Ignore interactive and job-control signals. */ |
| signal (SIGINT, SIG_IGN); |
| signal (SIGQUIT, SIG_IGN); |
| signal (SIGTSTP, SIG_IGN); |
| signal (SIGTTIN, SIG_IGN); |
| signal (SIGTTOU, SIG_IGN); |
| signal (SIGCHLD, SIG_IGN); |
| |
| /* Put ourselves in our own process group. */ |
| shell_pgid = getpid (); |
| if (setpgid (shell_pgid, shell_pgid) < 0) |
| { |
| perror ("Couldn't put the shell in its own process group"); |
| exit (1); |
| } |
| |
| /* Grab control of the terminal. */ |
| tcsetpgrp (shell_terminal, shell_pgid); |
| |
| /* Save default terminal attributes for shell. */ |
| tcgetattr (shell_terminal, &shell_tmodes); |
| } |
| } |
| |
| |
| File: libc.info, Node: Launching Jobs, Next: Foreground and Background, Prev: Initializing the Shell, Up: Implementing a Shell |
| |
| 28.5.3 Launching Jobs |
| --------------------- |
| |
| Once the shell has taken responsibility for performing job control on |
| its controlling terminal, it can launch jobs in response to commands |
| typed by the user. |
| |
| To create the processes in a process group, you use the same `fork' |
| and `exec' functions described in *note Process Creation Concepts::. |
| Since there are multiple child processes involved, though, things are a |
| little more complicated and you must be careful to do things in the |
| right order. Otherwise, nasty race conditions can result. |
| |
| You have two choices for how to structure the tree of parent-child |
| relationships among the processes. You can either make all the |
| processes in the process group be children of the shell process, or you |
| can make one process in group be the ancestor of all the other processes |
| in that group. The sample shell program presented in this chapter uses |
| the first approach because it makes bookkeeping somewhat simpler. |
| |
| As each process is forked, it should put itself in the new process |
| group by calling `setpgid'; see *note Process Group Functions::. The |
| first process in the new group becomes its "process group leader", and |
| its process ID becomes the "process group ID" for the group. |
| |
| The shell should also call `setpgid' to put each of its child |
| processes into the new process group. This is because there is a |
| potential timing problem: each child process must be put in the process |
| group before it begins executing a new program, and the shell depends on |
| having all the child processes in the group before it continues |
| executing. If both the child processes and the shell call `setpgid', |
| this ensures that the right things happen no matter which process gets |
| to it first. |
| |
| If the job is being launched as a foreground job, the new process |
| group also needs to be put into the foreground on the controlling |
| terminal using `tcsetpgrp'. Again, this should be done by the shell as |
| well as by each of its child processes, to avoid race conditions. |
| |
| The next thing each child process should do is to reset its signal |
| actions. |
| |
| During initialization, the shell process set itself to ignore job |
| control signals; see *note Initializing the Shell::. As a result, any |
| child processes it creates also ignore these signals by inheritance. |
| This is definitely undesirable, so each child process should explicitly |
| set the actions for these signals back to `SIG_DFL' just after it is |
| forked. |
| |
| Since shells follow this convention, applications can assume that |
| they inherit the correct handling of these signals from the parent |
| process. But every application has a responsibility not to mess up the |
| handling of stop signals. Applications that disable the normal |
| interpretation of the SUSP character should provide some other |
| mechanism for the user to stop the job. When the user invokes this |
| mechanism, the program should send a `SIGTSTP' signal to the process |
| group of the process, not just to the process itself. *Note Signaling |
| Another Process::. |
| |
| Finally, each child process should call `exec' in the normal way. |
| This is also the point at which redirection of the standard input and |
| output channels should be handled. *Note Duplicating Descriptors::, |
| for an explanation of how to do this. |
| |
| Here is the function from the sample shell program that is |
| responsible for launching a program. The function is executed by each |
| child process immediately after it has been forked by the shell, and |
| never returns. |
| |
| void |
| launch_process (process *p, pid_t pgid, |
| int infile, int outfile, int errfile, |
| int foreground) |
| { |
| pid_t pid; |
| |
| if (shell_is_interactive) |
| { |
| /* Put the process into the process group and give the process group |
| the terminal, if appropriate. |
| This has to be done both by the shell and in the individual |
| child processes because of potential race conditions. */ |
| pid = getpid (); |
| if (pgid == 0) pgid = pid; |
| setpgid (pid, pgid); |
| if (foreground) |
| tcsetpgrp (shell_terminal, pgid); |
| |
| /* Set the handling for job control signals back to the default. */ |
| signal (SIGINT, SIG_DFL); |
| signal (SIGQUIT, SIG_DFL); |
| signal (SIGTSTP, SIG_DFL); |
| signal (SIGTTIN, SIG_DFL); |
| signal (SIGTTOU, SIG_DFL); |
| signal (SIGCHLD, SIG_DFL); |
| } |
| |
| /* Set the standard input/output channels of the new process. */ |
| if (infile != STDIN_FILENO) |
| { |
| dup2 (infile, STDIN_FILENO); |
| close (infile); |
| } |
| if (outfile != STDOUT_FILENO) |
| { |
| dup2 (outfile, STDOUT_FILENO); |
| close (outfile); |
| } |
| if (errfile != STDERR_FILENO) |
| { |
| dup2 (errfile, STDERR_FILENO); |
| close (errfile); |
| } |
| |
| /* Exec the new process. Make sure we exit. */ |
| execvp (p->argv[0], p->argv); |
| perror ("execvp"); |
| exit (1); |
| } |
| |
| If the shell is not running interactively, this function does not do |
| anything with process groups or signals. Remember that a shell not |
| performing job control must keep all of its subprocesses in the same |
| process group as the shell itself. |
| |
| Next, here is the function that actually launches a complete job. |
| After creating the child processes, this function calls some other |
| functions to put the newly created job into the foreground or |
| background; these are discussed in *note Foreground and Background::. |
| |
| void |
| launch_job (job *j, int foreground) |
| { |
| process *p; |
| pid_t pid; |
| int mypipe[2], infile, outfile; |
| |
| infile = j->stdin; |
| for (p = j->first_process; p; p = p->next) |
| { |
| /* Set up pipes, if necessary. */ |
| if (p->next) |
| { |
| if (pipe (mypipe) < 0) |
| { |
| perror ("pipe"); |
| exit (1); |
| } |
| outfile = mypipe[1]; |
| } |
| else |
| outfile = j->stdout; |
| |
| /* Fork the child processes. */ |
| pid = fork (); |
| if (pid == 0) |
| /* This is the child process. */ |
| launch_process (p, j->pgid, infile, |
| outfile, j->stderr, foreground); |
| else if (pid < 0) |
| { |
| /* The fork failed. */ |
| perror ("fork"); |
| exit (1); |
| } |
| else |
| { |
| /* This is the parent process. */ |
| p->pid = pid; |
| if (shell_is_interactive) |
| { |
| if (!j->pgid) |
| j->pgid = pid; |
| setpgid (pid, j->pgid); |
| } |
| } |
| |
| /* Clean up after pipes. */ |
| if (infile != j->stdin) |
| close (infile); |
| if (outfile != j->stdout) |
| close (outfile); |
| infile = mypipe[0]; |
| } |
| |
| format_job_info (j, "launched"); |
| |
| if (!shell_is_interactive) |
| wait_for_job (j); |
| else if (foreground) |
| put_job_in_foreground (j, 0); |
| else |
| put_job_in_background (j, 0); |
| } |
| |
| |
| File: libc.info, Node: Foreground and Background, Next: Stopped and Terminated Jobs, Prev: Launching Jobs, Up: Implementing a Shell |
| |
| 28.5.4 Foreground and Background |
| -------------------------------- |
| |
| Now let's consider what actions must be taken by the shell when it |
| launches a job into the foreground, and how this differs from what must |
| be done when a background job is launched. |
| |
| When a foreground job is launched, the shell must first give it |
| access to the controlling terminal by calling `tcsetpgrp'. Then, the |
| shell should wait for processes in that process group to terminate or |
| stop. This is discussed in more detail in *note Stopped and Terminated |
| Jobs::. |
| |
| When all of the processes in the group have either completed or |
| stopped, the shell should regain control of the terminal for its own |
| process group by calling `tcsetpgrp' again. Since stop signals caused |
| by I/O from a background process or a SUSP character typed by the user |
| are sent to the process group, normally all the processes in the job |
| stop together. |
| |
| The foreground job may have left the terminal in a strange state, so |
| the shell should restore its own saved terminal modes before |
| continuing. In case the job is merely stopped, the shell should first |
| save the current terminal modes so that it can restore them later if |
| the job is continued. The functions for dealing with terminal modes are |
| `tcgetattr' and `tcsetattr'; these are described in *note Terminal |
| Modes::. |
| |
| Here is the sample shell's function for doing all of this. |
| |
| /* Put job J in the foreground. If CONT is nonzero, |
| restore the saved terminal modes and send the process group a |
| `SIGCONT' signal to wake it up before we block. */ |
| |
| void |
| put_job_in_foreground (job *j, int cont) |
| { |
| /* Put the job into the foreground. */ |
| tcsetpgrp (shell_terminal, j->pgid); |
| |
| /* Send the job a continue signal, if necessary. */ |
| if (cont) |
| { |
| tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes); |
| if (kill (- j->pgid, SIGCONT) < 0) |
| perror ("kill (SIGCONT)"); |
| } |
| |
| /* Wait for it to report. */ |
| wait_for_job (j); |
| |
| /* Put the shell back in the foreground. */ |
| tcsetpgrp (shell_terminal, shell_pgid); |
| |
| /* Restore the shell's terminal modes. */ |
| tcgetattr (shell_terminal, &j->tmodes); |
| tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes); |
| } |
| |
| If the process group is launched as a background job, the shell |
| should remain in the foreground itself and continue to read commands |
| from the terminal. |
| |
| In the sample shell, there is not much that needs to be done to put |
| a job into the background. Here is the function it uses: |
| |
| /* Put a job in the background. If the cont argument is true, send |
| the process group a `SIGCONT' signal to wake it up. */ |
| |
| void |
| put_job_in_background (job *j, int cont) |
| { |
| /* Send the job a continue signal, if necessary. */ |
| if (cont) |
| if (kill (-j->pgid, SIGCONT) < 0) |
| perror ("kill (SIGCONT)"); |
| } |
| |
| |
| |
| Local Variables: |
| coding: utf-8 |
| End: |
