This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
|
|
This file documents the GNU C Library.
|
|
This is ‘The GNU C Library Reference Manual’, for version 2.23.
|
|
Copyright © 1993–2016 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being “Free Software Needs Free Documentation” and
|
“GNU Lesser General Public License”, the Front-Cover texts being “A GNU
|
Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
|
license is included in the section entitled "GNU Free Documentation
|
License".
|
|
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
|
modify this GNU manual. Buying copies from the FSF supports it in
|
developing GNU and promoting software freedom.”
|
INFO-DIR-SECTION Software libraries
|
START-INFO-DIR-ENTRY
|
* Libc: (libc). C library.
|
END-INFO-DIR-ENTRY
|
|
INFO-DIR-SECTION GNU C library functions and macros
|
START-INFO-DIR-ENTRY
|
* ALTWERASE: (libc)Local Modes.
|
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
|
* ARG_MAX: (libc)General Limits.
|
* BC_BASE_MAX: (libc)Utility Limits.
|
* BC_DIM_MAX: (libc)Utility Limits.
|
* BC_SCALE_MAX: (libc)Utility Limits.
|
* BC_STRING_MAX: (libc)Utility Limits.
|
* BRKINT: (libc)Input Modes.
|
* BUFSIZ: (libc)Controlling Buffering.
|
* CCTS_OFLOW: (libc)Control Modes.
|
* CHILD_MAX: (libc)General Limits.
|
* CIGNORE: (libc)Control Modes.
|
* CLK_TCK: (libc)Processor Time.
|
* CLOCAL: (libc)Control Modes.
|
* CLOCKS_PER_SEC: (libc)CPU Time.
|
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
|
* CPU_CLR: (libc)CPU Affinity.
|
* CPU_ISSET: (libc)CPU Affinity.
|
* CPU_SET: (libc)CPU Affinity.
|
* CPU_SETSIZE: (libc)CPU Affinity.
|
* CPU_ZERO: (libc)CPU Affinity.
|
* CREAD: (libc)Control Modes.
|
* CRTS_IFLOW: (libc)Control Modes.
|
* CS5: (libc)Control Modes.
|
* CS6: (libc)Control Modes.
|
* CS7: (libc)Control Modes.
|
* CS8: (libc)Control Modes.
|
* CSIZE: (libc)Control Modes.
|
* CSTOPB: (libc)Control Modes.
|
* DES_FAILED: (libc)DES Encryption.
|
* DTTOIF: (libc)Directory Entries.
|
* E2BIG: (libc)Error Codes.
|
* EACCES: (libc)Error Codes.
|
* EADDRINUSE: (libc)Error Codes.
|
* EADDRNOTAVAIL: (libc)Error Codes.
|
* EADV: (libc)Error Codes.
|
* EAFNOSUPPORT: (libc)Error Codes.
|
* EAGAIN: (libc)Error Codes.
|
* EALREADY: (libc)Error Codes.
|
* EAUTH: (libc)Error Codes.
|
* EBACKGROUND: (libc)Error Codes.
|
* EBADE: (libc)Error Codes.
|
* EBADF: (libc)Error Codes.
|
* EBADFD: (libc)Error Codes.
|
* EBADMSG: (libc)Error Codes.
|
* EBADR: (libc)Error Codes.
|
* EBADRPC: (libc)Error Codes.
|
* EBADRQC: (libc)Error Codes.
|
* EBADSLT: (libc)Error Codes.
|
* EBFONT: (libc)Error Codes.
|
* EBUSY: (libc)Error Codes.
|
* ECANCELED: (libc)Error Codes.
|
* ECHILD: (libc)Error Codes.
|
* ECHO: (libc)Local Modes.
|
* ECHOCTL: (libc)Local Modes.
|
* ECHOE: (libc)Local Modes.
|
* ECHOK: (libc)Local Modes.
|
* ECHOKE: (libc)Local Modes.
|
* ECHONL: (libc)Local Modes.
|
* ECHOPRT: (libc)Local Modes.
|
* ECHRNG: (libc)Error Codes.
|
* ECOMM: (libc)Error Codes.
|
* ECONNABORTED: (libc)Error Codes.
|
* ECONNREFUSED: (libc)Error Codes.
|
* ECONNRESET: (libc)Error Codes.
|
* ED: (libc)Error Codes.
|
* EDEADLK: (libc)Error Codes.
|
* EDEADLOCK: (libc)Error Codes.
|
* EDESTADDRREQ: (libc)Error Codes.
|
* EDIED: (libc)Error Codes.
|
* EDOM: (libc)Error Codes.
|
* EDOTDOT: (libc)Error Codes.
|
* EDQUOT: (libc)Error Codes.
|
* EEXIST: (libc)Error Codes.
|
* EFAULT: (libc)Error Codes.
|
* EFBIG: (libc)Error Codes.
|
* EFTYPE: (libc)Error Codes.
|
* EGRATUITOUS: (libc)Error Codes.
|
* EGREGIOUS: (libc)Error Codes.
|
* EHOSTDOWN: (libc)Error Codes.
|
* EHOSTUNREACH: (libc)Error Codes.
|
* EHWPOISON: (libc)Error Codes.
|
* EIDRM: (libc)Error Codes.
|
* EIEIO: (libc)Error Codes.
|
* EILSEQ: (libc)Error Codes.
|
* EINPROGRESS: (libc)Error Codes.
|
* EINTR: (libc)Error Codes.
|
* EINVAL: (libc)Error Codes.
|
* EIO: (libc)Error Codes.
|
* EISCONN: (libc)Error Codes.
|
* EISDIR: (libc)Error Codes.
|
* EISNAM: (libc)Error Codes.
|
* EKEYEXPIRED: (libc)Error Codes.
|
* EKEYREJECTED: (libc)Error Codes.
|
* EKEYREVOKED: (libc)Error Codes.
|
* EL2HLT: (libc)Error Codes.
|
* EL2NSYNC: (libc)Error Codes.
|
* EL3HLT: (libc)Error Codes.
|
* EL3RST: (libc)Error Codes.
|
* ELIBACC: (libc)Error Codes.
|
* ELIBBAD: (libc)Error Codes.
|
* ELIBEXEC: (libc)Error Codes.
|
* ELIBMAX: (libc)Error Codes.
|
* ELIBSCN: (libc)Error Codes.
|
* ELNRNG: (libc)Error Codes.
|
* ELOOP: (libc)Error Codes.
|
* EMEDIUMTYPE: (libc)Error Codes.
|
* EMFILE: (libc)Error Codes.
|
* EMLINK: (libc)Error Codes.
|
* EMSGSIZE: (libc)Error Codes.
|
* EMULTIHOP: (libc)Error Codes.
|
* ENAMETOOLONG: (libc)Error Codes.
|
* ENAVAIL: (libc)Error Codes.
|
* ENEEDAUTH: (libc)Error Codes.
|
* ENETDOWN: (libc)Error Codes.
|
* ENETRESET: (libc)Error Codes.
|
* ENETUNREACH: (libc)Error Codes.
|
* ENFILE: (libc)Error Codes.
|
* ENOANO: (libc)Error Codes.
|
* ENOBUFS: (libc)Error Codes.
|
* ENOCSI: (libc)Error Codes.
|
* ENODATA: (libc)Error Codes.
|
* ENODEV: (libc)Error Codes.
|
* ENOENT: (libc)Error Codes.
|
* ENOEXEC: (libc)Error Codes.
|
* ENOKEY: (libc)Error Codes.
|
* ENOLCK: (libc)Error Codes.
|
* ENOLINK: (libc)Error Codes.
|
* ENOMEDIUM: (libc)Error Codes.
|
* ENOMEM: (libc)Error Codes.
|
* ENOMSG: (libc)Error Codes.
|
* ENONET: (libc)Error Codes.
|
* ENOPKG: (libc)Error Codes.
|
* ENOPROTOOPT: (libc)Error Codes.
|
* ENOSPC: (libc)Error Codes.
|
* ENOSR: (libc)Error Codes.
|
* ENOSTR: (libc)Error Codes.
|
* ENOSYS: (libc)Error Codes.
|
* ENOTBLK: (libc)Error Codes.
|
* ENOTCONN: (libc)Error Codes.
|
* ENOTDIR: (libc)Error Codes.
|
* ENOTEMPTY: (libc)Error Codes.
|
* ENOTNAM: (libc)Error Codes.
|
* ENOTRECOVERABLE: (libc)Error Codes.
|
* ENOTSOCK: (libc)Error Codes.
|
* ENOTSUP: (libc)Error Codes.
|
* ENOTTY: (libc)Error Codes.
|
* ENOTUNIQ: (libc)Error Codes.
|
* ENXIO: (libc)Error Codes.
|
* EOF: (libc)EOF and Errors.
|
* EOPNOTSUPP: (libc)Error Codes.
|
* EOVERFLOW: (libc)Error Codes.
|
* EOWNERDEAD: (libc)Error Codes.
|
* EPERM: (libc)Error Codes.
|
* EPFNOSUPPORT: (libc)Error Codes.
|
* EPIPE: (libc)Error Codes.
|
* EPROCLIM: (libc)Error Codes.
|
* EPROCUNAVAIL: (libc)Error Codes.
|
* EPROGMISMATCH: (libc)Error Codes.
|
* EPROGUNAVAIL: (libc)Error Codes.
|
* EPROTO: (libc)Error Codes.
|
* EPROTONOSUPPORT: (libc)Error Codes.
|
* EPROTOTYPE: (libc)Error Codes.
|
* EQUIV_CLASS_MAX: (libc)Utility Limits.
|
* ERANGE: (libc)Error Codes.
|
* EREMCHG: (libc)Error Codes.
|
* EREMOTE: (libc)Error Codes.
|
* EREMOTEIO: (libc)Error Codes.
|
* ERESTART: (libc)Error Codes.
|
* ERFKILL: (libc)Error Codes.
|
* EROFS: (libc)Error Codes.
|
* ERPCMISMATCH: (libc)Error Codes.
|
* ESHUTDOWN: (libc)Error Codes.
|
* ESOCKTNOSUPPORT: (libc)Error Codes.
|
* ESPIPE: (libc)Error Codes.
|
* ESRCH: (libc)Error Codes.
|
* ESRMNT: (libc)Error Codes.
|
* ESTALE: (libc)Error Codes.
|
* ESTRPIPE: (libc)Error Codes.
|
* ETIME: (libc)Error Codes.
|
* ETIMEDOUT: (libc)Error Codes.
|
* ETOOMANYREFS: (libc)Error Codes.
|
* ETXTBSY: (libc)Error Codes.
|
* EUCLEAN: (libc)Error Codes.
|
* EUNATCH: (libc)Error Codes.
|
* EUSERS: (libc)Error Codes.
|
* EWOULDBLOCK: (libc)Error Codes.
|
* EXDEV: (libc)Error Codes.
|
* EXFULL: (libc)Error Codes.
|
* EXIT_FAILURE: (libc)Exit Status.
|
* EXIT_SUCCESS: (libc)Exit Status.
|
* EXPR_NEST_MAX: (libc)Utility Limits.
|
* FD_CLOEXEC: (libc)Descriptor Flags.
|
* FD_CLR: (libc)Waiting for I/O.
|
* FD_ISSET: (libc)Waiting for I/O.
|
* FD_SET: (libc)Waiting for I/O.
|
* FD_SETSIZE: (libc)Waiting for I/O.
|
* FD_ZERO: (libc)Waiting for I/O.
|
* FILENAME_MAX: (libc)Limits for Files.
|
* FLUSHO: (libc)Local Modes.
|
* FOPEN_MAX: (libc)Opening Streams.
|
* FP_ILOGB0: (libc)Exponents and Logarithms.
|
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
|
* F_DUPFD: (libc)Duplicating Descriptors.
|
* F_GETFD: (libc)Descriptor Flags.
|
* F_GETFL: (libc)Getting File Status Flags.
|
* F_GETLK: (libc)File Locks.
|
* F_GETOWN: (libc)Interrupt Input.
|
* F_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.
|
* HUPCL: (libc)Control Modes.
|
* I: (libc)Complex Numbers.
|
* ICANON: (libc)Local Modes.
|
* ICRNL: (libc)Input Modes.
|
* IEXTEN: (libc)Local Modes.
|
* IFNAMSIZ: (libc)Interface Naming.
|
* IFTODT: (libc)Directory Entries.
|
* IGNBRK: (libc)Input Modes.
|
* IGNCR: (libc)Input Modes.
|
* IGNPAR: (libc)Input Modes.
|
* IMAXBEL: (libc)Input Modes.
|
* INADDR_ANY: (libc)Host Address Data Type.
|
* INADDR_BROADCAST: (libc)Host Address Data Type.
|
* INADDR_LOOPBACK: (libc)Host Address Data Type.
|
* INADDR_NONE: (libc)Host Address Data Type.
|
* INFINITY: (libc)Infinity and NaN.
|
* INLCR: (libc)Input Modes.
|
* INPCK: (libc)Input Modes.
|
* IPPORT_RESERVED: (libc)Ports.
|
* IPPORT_USERRESERVED: (libc)Ports.
|
* ISIG: (libc)Local Modes.
|
* ISTRIP: (libc)Input Modes.
|
* IXANY: (libc)Input Modes.
|
* IXOFF: (libc)Input Modes.
|
* IXON: (libc)Input Modes.
|
* LINE_MAX: (libc)Utility Limits.
|
* LINK_MAX: (libc)Limits for Files.
|
* L_ctermid: (libc)Identifying the Terminal.
|
* L_cuserid: (libc)Who Logged In.
|
* L_tmpnam: (libc)Temporary Files.
|
* MAXNAMLEN: (libc)Limits for Files.
|
* MAXSYMLINKS: (libc)Symbolic Links.
|
* MAX_CANON: (libc)Limits for Files.
|
* MAX_INPUT: (libc)Limits for Files.
|
* MB_CUR_MAX: (libc)Selecting the Conversion.
|
* MB_LEN_MAX: (libc)Selecting the Conversion.
|
* MDMBUF: (libc)Control Modes.
|
* MSG_DONTROUTE: (libc)Socket Data Options.
|
* MSG_OOB: (libc)Socket Data Options.
|
* MSG_PEEK: (libc)Socket Data Options.
|
* NAME_MAX: (libc)Limits for Files.
|
* NAN: (libc)Infinity and NaN.
|
* NCCS: (libc)Mode Data Types.
|
* NGROUPS_MAX: (libc)General Limits.
|
* NOFLSH: (libc)Local Modes.
|
* NOKERNINFO: (libc)Local Modes.
|
* NSIG: (libc)Standard Signals.
|
* NULL: (libc)Null Pointer Constant.
|
* ONLCR: (libc)Output Modes.
|
* ONOEOT: (libc)Output Modes.
|
* OPEN_MAX: (libc)General Limits.
|
* OPOST: (libc)Output Modes.
|
* OXTABS: (libc)Output Modes.
|
* O_ACCMODE: (libc)Access Modes.
|
* O_APPEND: (libc)Operating Modes.
|
* O_ASYNC: (libc)Operating Modes.
|
* O_CREAT: (libc)Open-time Flags.
|
* O_EXCL: (libc)Open-time Flags.
|
* O_EXEC: (libc)Access Modes.
|
* O_EXLOCK: (libc)Open-time Flags.
|
* O_FSYNC: (libc)Operating Modes.
|
* O_IGNORE_CTTY: (libc)Open-time Flags.
|
* O_NDELAY: (libc)Operating Modes.
|
* O_NOATIME: (libc)Operating Modes.
|
* O_NOCTTY: (libc)Open-time Flags.
|
* O_NOLINK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Operating Modes.
|
* O_NOTRANS: (libc)Open-time Flags.
|
* O_RDONLY: (libc)Access Modes.
|
* O_RDWR: (libc)Access Modes.
|
* O_READ: (libc)Access Modes.
|
* O_SHLOCK: (libc)Open-time Flags.
|
* O_SYNC: (libc)Operating Modes.
|
* O_TRUNC: (libc)Open-time Flags.
|
* O_WRITE: (libc)Access Modes.
|
* O_WRONLY: (libc)Access Modes.
|
* PARENB: (libc)Control Modes.
|
* PARMRK: (libc)Input Modes.
|
* PARODD: (libc)Control Modes.
|
* PATH_MAX: (libc)Limits for Files.
|
* PA_FLAG_MASK: (libc)Parsing a Template String.
|
* PENDIN: (libc)Local Modes.
|
* PF_FILE: (libc)Local Namespace Details.
|
* PF_INET6: (libc)Internet Namespace.
|
* PF_INET: (libc)Internet Namespace.
|
* PF_LOCAL: (libc)Local Namespace Details.
|
* PF_UNIX: (libc)Local Namespace Details.
|
* PIPE_BUF: (libc)Limits for Files.
|
* P_tmpdir: (libc)Temporary Files.
|
* RAND_MAX: (libc)ISO Random.
|
* RE_DUP_MAX: (libc)General Limits.
|
* RLIM_INFINITY: (libc)Limits on Resources.
|
* R_OK: (libc)Testing File Access.
|
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
|
* SA_ONSTACK: (libc)Flags for Sigaction.
|
* SA_RESTART: (libc)Flags for Sigaction.
|
* SEEK_CUR: (libc)File Positioning.
|
* SEEK_END: (libc)File Positioning.
|
* SEEK_SET: (libc)File Positioning.
|
* SIGABRT: (libc)Program Error Signals.
|
* SIGALRM: (libc)Alarm Signals.
|
* SIGBUS: (libc)Program Error Signals.
|
* SIGCHLD: (libc)Job Control Signals.
|
* SIGCLD: (libc)Job Control Signals.
|
* SIGCONT: (libc)Job Control Signals.
|
* SIGEMT: (libc)Program Error Signals.
|
* SIGFPE: (libc)Program Error Signals.
|
* SIGHUP: (libc)Termination Signals.
|
* SIGILL: (libc)Program Error Signals.
|
* SIGINFO: (libc)Miscellaneous Signals.
|
* SIGINT: (libc)Termination Signals.
|
* SIGIO: (libc)Asynchronous I/O Signals.
|
* SIGIOT: (libc)Program Error Signals.
|
* SIGKILL: (libc)Termination Signals.
|
* SIGLOST: (libc)Operation Error Signals.
|
* SIGPIPE: (libc)Operation Error Signals.
|
* SIGPOLL: (libc)Asynchronous I/O Signals.
|
* SIGPROF: (libc)Alarm Signals.
|
* SIGQUIT: (libc)Termination Signals.
|
* SIGSEGV: (libc)Program Error Signals.
|
* SIGSTOP: (libc)Job Control Signals.
|
* SIGSYS: (libc)Program Error Signals.
|
* SIGTERM: (libc)Termination Signals.
|
* SIGTRAP: (libc)Program Error Signals.
|
* SIGTSTP: (libc)Job Control Signals.
|
* SIGTTIN: (libc)Job Control Signals.
|
* SIGTTOU: (libc)Job Control Signals.
|
* SIGURG: (libc)Asynchronous I/O Signals.
|
* SIGUSR1: (libc)Miscellaneous Signals.
|
* SIGUSR2: (libc)Miscellaneous Signals.
|
* SIGVTALRM: (libc)Alarm Signals.
|
* SIGWINCH: (libc)Miscellaneous Signals.
|
* SIGXCPU: (libc)Operation Error Signals.
|
* SIGXFSZ: (libc)Operation Error Signals.
|
* SIG_ERR: (libc)Basic Signal Handling.
|
* SOCK_DGRAM: (libc)Communication Styles.
|
* SOCK_RAW: (libc)Communication Styles.
|
* SOCK_RDM: (libc)Communication Styles.
|
* SOCK_SEQPACKET: (libc)Communication Styles.
|
* SOCK_STREAM: (libc)Communication Styles.
|
* SOL_SOCKET: (libc)Socket-Level Options.
|
* SSIZE_MAX: (libc)General Limits.
|
* STREAM_MAX: (libc)General Limits.
|
* SUN_LEN: (libc)Local Namespace Details.
|
* 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.
|
* __va_copy: (libc)Argument Macros.
|
* _exit: (libc)Termination Internals.
|
* _flushlbf: (libc)Flushing Buffers.
|
* _tolower: (libc)Case Conversion.
|
* _toupper: (libc)Case Conversion.
|
* a64l: (libc)Encode Binary Data.
|
* abort: (libc)Aborting a Program.
|
* abs: (libc)Absolute Value.
|
* accept: (libc)Accepting Connections.
|
* access: (libc)Testing File Access.
|
* acos: (libc)Inverse Trig Functions.
|
* acosf: (libc)Inverse Trig Functions.
|
* acosh: (libc)Hyperbolic Functions.
|
* acoshf: (libc)Hyperbolic Functions.
|
* acoshl: (libc)Hyperbolic Functions.
|
* acosl: (libc)Inverse Trig Functions.
|
* addmntent: (libc)mtab.
|
* addseverity: (libc)Adding Severity Classes.
|
* adjtime: (libc)High-Resolution Calendar.
|
* adjtimex: (libc)High-Resolution Calendar.
|
* aio_cancel64: (libc)Cancel AIO Operations.
|
* aio_cancel: (libc)Cancel AIO Operations.
|
* aio_error64: (libc)Status of AIO Operations.
|
* aio_error: (libc)Status of AIO Operations.
|
* aio_fsync64: (libc)Synchronizing AIO Operations.
|
* aio_fsync: (libc)Synchronizing AIO Operations.
|
* aio_init: (libc)Configuration of AIO.
|
* aio_read64: (libc)Asynchronous Reads/Writes.
|
* aio_read: (libc)Asynchronous Reads/Writes.
|
* aio_return64: (libc)Status of AIO Operations.
|
* aio_return: (libc)Status of AIO Operations.
|
* aio_suspend64: (libc)Synchronizing AIO Operations.
|
* aio_suspend: (libc)Synchronizing AIO Operations.
|
* aio_write64: (libc)Asynchronous Reads/Writes.
|
* aio_write: (libc)Asynchronous Reads/Writes.
|
* alarm: (libc)Setting an Alarm.
|
* aligned_alloc: (libc)Aligned Memory Blocks.
|
* alloca: (libc)Variable Size Automatic.
|
* alphasort64: (libc)Scanning Directory Content.
|
* alphasort: (libc)Scanning Directory Content.
|
* argp_error: (libc)Argp Helper Functions.
|
* argp_failure: (libc)Argp Helper Functions.
|
* argp_help: (libc)Argp Help.
|
* argp_parse: (libc)Argp.
|
* argp_state_help: (libc)Argp Helper Functions.
|
* argp_usage: (libc)Argp Helper Functions.
|
* argz_add: (libc)Argz Functions.
|
* argz_add_sep: (libc)Argz Functions.
|
* argz_append: (libc)Argz Functions.
|
* argz_count: (libc)Argz Functions.
|
* argz_create: (libc)Argz Functions.
|
* argz_create_sep: (libc)Argz Functions.
|
* argz_delete: (libc)Argz Functions.
|
* argz_extract: (libc)Argz Functions.
|
* argz_insert: (libc)Argz Functions.
|
* argz_next: (libc)Argz Functions.
|
* argz_replace: (libc)Argz Functions.
|
* argz_stringify: (libc)Argz Functions.
|
* asctime: (libc)Formatting Calendar Time.
|
* asctime_r: (libc)Formatting Calendar Time.
|
* asin: (libc)Inverse Trig Functions.
|
* asinf: (libc)Inverse Trig Functions.
|
* asinh: (libc)Hyperbolic Functions.
|
* asinhf: (libc)Hyperbolic Functions.
|
* asinhl: (libc)Hyperbolic Functions.
|
* asinl: (libc)Inverse Trig Functions.
|
* asprintf: (libc)Dynamic Output.
|
* assert: (libc)Consistency Checking.
|
* assert_perror: (libc)Consistency Checking.
|
* atan2: (libc)Inverse Trig Functions.
|
* atan2f: (libc)Inverse Trig Functions.
|
* atan2l: (libc)Inverse Trig Functions.
|
* atan: (libc)Inverse Trig Functions.
|
* atanf: (libc)Inverse Trig Functions.
|
* atanh: (libc)Hyperbolic Functions.
|
* atanhf: (libc)Hyperbolic Functions.
|
* atanhl: (libc)Hyperbolic Functions.
|
* atanl: (libc)Inverse Trig Functions.
|
* atexit: (libc)Cleanups on Exit.
|
* atof: (libc)Parsing of Floats.
|
* atoi: (libc)Parsing of Integers.
|
* atol: (libc)Parsing of Integers.
|
* atoll: (libc)Parsing of Integers.
|
* backtrace: (libc)Backtraces.
|
* backtrace_symbols: (libc)Backtraces.
|
* backtrace_symbols_fd: (libc)Backtraces.
|
* basename: (libc)Finding Tokens in a String.
|
* basename: (libc)Finding Tokens in a String.
|
* bcmp: (libc)String/Array Comparison.
|
* bcopy: (libc)Copying 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.
|
* cabsl: (libc)Absolute Value.
|
* cacos: (libc)Inverse Trig Functions.
|
* cacosf: (libc)Inverse Trig Functions.
|
* cacosh: (libc)Hyperbolic Functions.
|
* cacoshf: (libc)Hyperbolic Functions.
|
* cacoshl: (libc)Hyperbolic Functions.
|
* cacosl: (libc)Inverse Trig Functions.
|
* calloc: (libc)Allocating Cleared Space.
|
* canonicalize_file_name: (libc)Symbolic Links.
|
* carg: (libc)Operations on Complex.
|
* cargf: (libc)Operations on Complex.
|
* cargl: (libc)Operations on Complex.
|
* casin: (libc)Inverse Trig Functions.
|
* casinf: (libc)Inverse Trig Functions.
|
* casinh: (libc)Hyperbolic Functions.
|
* casinhf: (libc)Hyperbolic Functions.
|
* casinhl: (libc)Hyperbolic Functions.
|
* casinl: (libc)Inverse Trig Functions.
|
* catan: (libc)Inverse Trig Functions.
|
* catanf: (libc)Inverse Trig Functions.
|
* catanh: (libc)Hyperbolic Functions.
|
* catanhf: (libc)Hyperbolic Functions.
|
* catanhl: (libc)Hyperbolic Functions.
|
* catanl: (libc)Inverse Trig Functions.
|
* catclose: (libc)The catgets Functions.
|
* catgets: (libc)The catgets Functions.
|
* catopen: (libc)The catgets Functions.
|
* cbc_crypt: (libc)DES Encryption.
|
* cbrt: (libc)Exponents and Logarithms.
|
* cbrtf: (libc)Exponents and Logarithms.
|
* cbrtl: (libc)Exponents and Logarithms.
|
* ccos: (libc)Trig Functions.
|
* ccosf: (libc)Trig Functions.
|
* ccosh: (libc)Hyperbolic Functions.
|
* ccoshf: (libc)Hyperbolic Functions.
|
* ccoshl: (libc)Hyperbolic Functions.
|
* ccosl: (libc)Trig Functions.
|
* ceil: (libc)Rounding Functions.
|
* ceilf: (libc)Rounding Functions.
|
* ceill: (libc)Rounding Functions.
|
* cexp: (libc)Exponents and Logarithms.
|
* cexpf: (libc)Exponents and Logarithms.
|
* cexpl: (libc)Exponents and Logarithms.
|
* cfgetispeed: (libc)Line Speed.
|
* cfgetospeed: (libc)Line Speed.
|
* cfmakeraw: (libc)Noncanonical Input.
|
* cfree: (libc)Freeing after Malloc.
|
* cfsetispeed: (libc)Line Speed.
|
* cfsetospeed: (libc)Line Speed.
|
* cfsetspeed: (libc)Line Speed.
|
* chdir: (libc)Working Directory.
|
* chmod: (libc)Setting Permissions.
|
* chown: (libc)File Owner.
|
* cimag: (libc)Operations on Complex.
|
* cimagf: (libc)Operations on Complex.
|
* cimagl: (libc)Operations on Complex.
|
* clearenv: (libc)Environment Access.
|
* clearerr: (libc)Error Recovery.
|
* clearerr_unlocked: (libc)Error Recovery.
|
* clock: (libc)CPU Time.
|
* clog10: (libc)Exponents and Logarithms.
|
* clog10f: (libc)Exponents and Logarithms.
|
* clog10l: (libc)Exponents and Logarithms.
|
* clog: (libc)Exponents and Logarithms.
|
* clogf: (libc)Exponents and Logarithms.
|
* clogl: (libc)Exponents and Logarithms.
|
* close: (libc)Opening and Closing Files.
|
* closedir: (libc)Reading/Closing Directory.
|
* closelog: (libc)closelog.
|
* confstr: (libc)String Parameters.
|
* conj: (libc)Operations on Complex.
|
* conjf: (libc)Operations on Complex.
|
* conjl: (libc)Operations on Complex.
|
* connect: (libc)Connecting.
|
* copysign: (libc)FP Bit Twiddling.
|
* copysignf: (libc)FP Bit Twiddling.
|
* copysignl: (libc)FP Bit Twiddling.
|
* cos: (libc)Trig Functions.
|
* cosf: (libc)Trig Functions.
|
* cosh: (libc)Hyperbolic Functions.
|
* coshf: (libc)Hyperbolic Functions.
|
* coshl: (libc)Hyperbolic Functions.
|
* cosl: (libc)Trig Functions.
|
* cpow: (libc)Exponents and Logarithms.
|
* cpowf: (libc)Exponents and Logarithms.
|
* cpowl: (libc)Exponents and Logarithms.
|
* cproj: (libc)Operations on Complex.
|
* cprojf: (libc)Operations on Complex.
|
* cprojl: (libc)Operations on Complex.
|
* creal: (libc)Operations on Complex.
|
* crealf: (libc)Operations on Complex.
|
* creall: (libc)Operations on Complex.
|
* creat64: (libc)Opening and Closing Files.
|
* creat: (libc)Opening and Closing Files.
|
* crypt: (libc)crypt.
|
* crypt_r: (libc)crypt.
|
* csin: (libc)Trig Functions.
|
* csinf: (libc)Trig Functions.
|
* csinh: (libc)Hyperbolic Functions.
|
* csinhf: (libc)Hyperbolic Functions.
|
* csinhl: (libc)Hyperbolic Functions.
|
* csinl: (libc)Trig Functions.
|
* csqrt: (libc)Exponents and Logarithms.
|
* csqrtf: (libc)Exponents and Logarithms.
|
* csqrtl: (libc)Exponents and Logarithms.
|
* ctan: (libc)Trig Functions.
|
* ctanf: (libc)Trig Functions.
|
* ctanh: (libc)Hyperbolic Functions.
|
* ctanhf: (libc)Hyperbolic Functions.
|
* ctanhl: (libc)Hyperbolic Functions.
|
* ctanl: (libc)Trig Functions.
|
* ctermid: (libc)Identifying the Terminal.
|
* ctime: (libc)Formatting Calendar Time.
|
* ctime_r: (libc)Formatting Calendar Time.
|
* cuserid: (libc)Who Logged In.
|
* dcgettext: (libc)Translation with gettext.
|
* dcngettext: (libc)Advanced gettext functions.
|
* des_setparity: (libc)DES Encryption.
|
* dgettext: (libc)Translation with gettext.
|
* difftime: (libc)Elapsed Time.
|
* dirfd: (libc)Opening a Directory.
|
* dirname: (libc)Finding Tokens in a String.
|
* div: (libc)Integer Division.
|
* dngettext: (libc)Advanced gettext functions.
|
* drand48: (libc)SVID Random.
|
* drand48_r: (libc)SVID Random.
|
* drem: (libc)Remainder Functions.
|
* dremf: (libc)Remainder Functions.
|
* dreml: (libc)Remainder Functions.
|
* dup2: (libc)Duplicating Descriptors.
|
* dup: (libc)Duplicating Descriptors.
|
* ecb_crypt: (libc)DES Encryption.
|
* ecvt: (libc)System V Number Conversion.
|
* ecvt_r: (libc)System V Number Conversion.
|
* encrypt: (libc)DES Encryption.
|
* encrypt_r: (libc)DES Encryption.
|
* endfsent: (libc)fstab.
|
* endgrent: (libc)Scanning All Groups.
|
* endhostent: (libc)Host Names.
|
* endmntent: (libc)mtab.
|
* endnetent: (libc)Networks Database.
|
* endnetgrent: (libc)Lookup Netgroup.
|
* endprotoent: (libc)Protocols Database.
|
* endpwent: (libc)Scanning All Users.
|
* endservent: (libc)Services Database.
|
* endutent: (libc)Manipulating the Database.
|
* endutxent: (libc)XPG Functions.
|
* envz_add: (libc)Envz Functions.
|
* envz_entry: (libc)Envz Functions.
|
* envz_get: (libc)Envz Functions.
|
* envz_merge: (libc)Envz Functions.
|
* envz_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.
|
* erfcl: (libc)Special Functions.
|
* erff: (libc)Special Functions.
|
* erfl: (libc)Special Functions.
|
* err: (libc)Error Messages.
|
* errno: (libc)Checking for Errors.
|
* error: (libc)Error Messages.
|
* error_at_line: (libc)Error Messages.
|
* errx: (libc)Error Messages.
|
* execl: (libc)Executing a File.
|
* execle: (libc)Executing a File.
|
* execlp: (libc)Executing a File.
|
* execv: (libc)Executing a File.
|
* execve: (libc)Executing a File.
|
* execvp: (libc)Executing a File.
|
* exit: (libc)Normal Termination.
|
* exp10: (libc)Exponents and Logarithms.
|
* exp10f: (libc)Exponents and Logarithms.
|
* exp10l: (libc)Exponents and Logarithms.
|
* exp2: (libc)Exponents and Logarithms.
|
* exp2f: (libc)Exponents and Logarithms.
|
* exp2l: (libc)Exponents and Logarithms.
|
* exp: (libc)Exponents and Logarithms.
|
* expf: (libc)Exponents and Logarithms.
|
* expl: (libc)Exponents and Logarithms.
|
* expm1: (libc)Exponents and Logarithms.
|
* expm1f: (libc)Exponents and Logarithms.
|
* expm1l: (libc)Exponents and Logarithms.
|
* fabs: (libc)Absolute Value.
|
* fabsf: (libc)Absolute Value.
|
* fabsl: (libc)Absolute Value.
|
* fchdir: (libc)Working Directory.
|
* fchmod: (libc)Setting Permissions.
|
* fchown: (libc)File Owner.
|
* fclose: (libc)Closing Streams.
|
* fcloseall: (libc)Closing Streams.
|
* fcntl: (libc)Control Operations.
|
* fcvt: (libc)System V Number Conversion.
|
* fcvt_r: (libc)System V Number Conversion.
|
* fdatasync: (libc)Synchronizing I/O.
|
* fdim: (libc)Misc FP Arithmetic.
|
* fdimf: (libc)Misc FP Arithmetic.
|
* fdiml: (libc)Misc FP Arithmetic.
|
* fdopen: (libc)Descriptors and Streams.
|
* fdopendir: (libc)Opening a Directory.
|
* feclearexcept: (libc)Status bit operations.
|
* fedisableexcept: (libc)Control Functions.
|
* feenableexcept: (libc)Control Functions.
|
* fegetenv: (libc)Control Functions.
|
* fegetexcept: (libc)Control Functions.
|
* fegetexceptflag: (libc)Status bit operations.
|
* fegetround: (libc)Rounding.
|
* feholdexcept: (libc)Control Functions.
|
* feof: (libc)EOF and Errors.
|
* feof_unlocked: (libc)EOF and Errors.
|
* feraiseexcept: (libc)Status bit operations.
|
* ferror: (libc)EOF and Errors.
|
* ferror_unlocked: (libc)EOF and Errors.
|
* fesetenv: (libc)Control Functions.
|
* fesetexceptflag: (libc)Status bit operations.
|
* fesetround: (libc)Rounding.
|
* fetestexcept: (libc)Status bit operations.
|
* feupdateenv: (libc)Control Functions.
|
* fflush: (libc)Flushing Buffers.
|
* fflush_unlocked: (libc)Flushing Buffers.
|
* fgetc: (libc)Character Input.
|
* fgetc_unlocked: (libc)Character Input.
|
* fgetgrent: (libc)Scanning All Groups.
|
* fgetgrent_r: (libc)Scanning All Groups.
|
* fgetpos64: (libc)Portable Positioning.
|
* fgetpos: (libc)Portable Positioning.
|
* fgetpwent: (libc)Scanning All Users.
|
* fgetpwent_r: (libc)Scanning All Users.
|
* fgets: (libc)Line Input.
|
* fgets_unlocked: (libc)Line Input.
|
* fgetwc: (libc)Character Input.
|
* fgetwc_unlocked: (libc)Character Input.
|
* fgetws: (libc)Line Input.
|
* fgetws_unlocked: (libc)Line Input.
|
* fileno: (libc)Descriptors and Streams.
|
* fileno_unlocked: (libc)Descriptors and Streams.
|
* finite: (libc)Floating Point Classes.
|
* finitef: (libc)Floating Point Classes.
|
* finitel: (libc)Floating Point Classes.
|
* flockfile: (libc)Streams and Threads.
|
* floor: (libc)Rounding Functions.
|
* floorf: (libc)Rounding Functions.
|
* floorl: (libc)Rounding Functions.
|
* fma: (libc)Misc FP Arithmetic.
|
* fmaf: (libc)Misc FP Arithmetic.
|
* fmal: (libc)Misc FP Arithmetic.
|
* fmax: (libc)Misc FP Arithmetic.
|
* fmaxf: (libc)Misc FP Arithmetic.
|
* fmaxl: (libc)Misc FP Arithmetic.
|
* fmemopen: (libc)String Streams.
|
* fmin: (libc)Misc FP Arithmetic.
|
* fminf: (libc)Misc FP Arithmetic.
|
* fminl: (libc)Misc FP Arithmetic.
|
* fmod: (libc)Remainder Functions.
|
* fmodf: (libc)Remainder Functions.
|
* fmodl: (libc)Remainder Functions.
|
* fmtmsg: (libc)Printing Formatted Messages.
|
* fnmatch: (libc)Wildcard Matching.
|
* fopen64: (libc)Opening Streams.
|
* fopen: (libc)Opening Streams.
|
* fopencookie: (libc)Streams and Cookies.
|
* fork: (libc)Creating a Process.
|
* forkpty: (libc)Pseudo-Terminal Pairs.
|
* fpathconf: (libc)Pathconf.
|
* fpclassify: (libc)Floating Point Classes.
|
* fprintf: (libc)Formatted Output Functions.
|
* fputc: (libc)Simple Output.
|
* fputc_unlocked: (libc)Simple Output.
|
* fputs: (libc)Simple Output.
|
* fputs_unlocked: (libc)Simple Output.
|
* fputwc: (libc)Simple Output.
|
* fputwc_unlocked: (libc)Simple Output.
|
* fputws: (libc)Simple Output.
|
* fputws_unlocked: (libc)Simple Output.
|
* fread: (libc)Block Input/Output.
|
* fread_unlocked: (libc)Block Input/Output.
|
* free: (libc)Freeing after Malloc.
|
* freopen64: (libc)Opening Streams.
|
* freopen: (libc)Opening Streams.
|
* frexp: (libc)Normalization Functions.
|
* frexpf: (libc)Normalization Functions.
|
* frexpl: (libc)Normalization Functions.
|
* fscanf: (libc)Formatted Input Functions.
|
* fseek: (libc)File Positioning.
|
* fseeko64: (libc)File Positioning.
|
* fseeko: (libc)File Positioning.
|
* fsetpos64: (libc)Portable Positioning.
|
* fsetpos: (libc)Portable Positioning.
|
* fstat64: (libc)Reading Attributes.
|
* fstat: (libc)Reading Attributes.
|
* fsync: (libc)Synchronizing I/O.
|
* ftell: (libc)File Positioning.
|
* ftello64: (libc)File Positioning.
|
* ftello: (libc)File Positioning.
|
* ftruncate64: (libc)File Size.
|
* ftruncate: (libc)File Size.
|
* ftrylockfile: (libc)Streams and Threads.
|
* ftw64: (libc)Working with Directory Trees.
|
* ftw: (libc)Working with Directory Trees.
|
* funlockfile: (libc)Streams and Threads.
|
* futimes: (libc)File Times.
|
* fwide: (libc)Streams and I18N.
|
* fwprintf: (libc)Formatted Output Functions.
|
* fwrite: (libc)Block Input/Output.
|
* fwrite_unlocked: (libc)Block Input/Output.
|
* fwscanf: (libc)Formatted Input Functions.
|
* gamma: (libc)Special Functions.
|
* gammaf: (libc)Special Functions.
|
* gammal: (libc)Special Functions.
|
* gcvt: (libc)System V Number Conversion.
|
* get_avphys_pages: (libc)Query Memory Parameters.
|
* get_current_dir_name: (libc)Working Directory.
|
* get_nprocs: (libc)Processor Resources.
|
* get_nprocs_conf: (libc)Processor Resources.
|
* get_phys_pages: (libc)Query Memory Parameters.
|
* getauxval: (libc)Auxiliary Vector.
|
* getc: (libc)Character Input.
|
* getc_unlocked: (libc)Character Input.
|
* getchar: (libc)Character Input.
|
* getchar_unlocked: (libc)Character Input.
|
* getcontext: (libc)System V contexts.
|
* getcwd: (libc)Working Directory.
|
* getdate: (libc)General Time String Parsing.
|
* getdate_r: (libc)General Time String Parsing.
|
* getdelim: (libc)Line Input.
|
* getdomainnname: (libc)Host Identification.
|
* getegid: (libc)Reading Persona.
|
* getenv: (libc)Environment Access.
|
* geteuid: (libc)Reading Persona.
|
* getfsent: (libc)fstab.
|
* getfsfile: (libc)fstab.
|
* getfsspec: (libc)fstab.
|
* getgid: (libc)Reading Persona.
|
* getgrent: (libc)Scanning All Groups.
|
* getgrent_r: (libc)Scanning All Groups.
|
* getgrgid: (libc)Lookup Group.
|
* getgrgid_r: (libc)Lookup Group.
|
* getgrnam: (libc)Lookup Group.
|
* getgrnam_r: (libc)Lookup Group.
|
* getgrouplist: (libc)Setting Groups.
|
* getgroups: (libc)Reading Persona.
|
* gethostbyaddr: (libc)Host Names.
|
* gethostbyaddr_r: (libc)Host Names.
|
* gethostbyname2: (libc)Host Names.
|
* gethostbyname2_r: (libc)Host Names.
|
* gethostbyname: (libc)Host Names.
|
* gethostbyname_r: (libc)Host Names.
|
* gethostent: (libc)Host Names.
|
* gethostid: (libc)Host Identification.
|
* gethostname: (libc)Host Identification.
|
* getitimer: (libc)Setting an Alarm.
|
* getline: (libc)Line Input.
|
* getloadavg: (libc)Processor Resources.
|
* getlogin: (libc)Who Logged In.
|
* getmntent: (libc)mtab.
|
* getmntent_r: (libc)mtab.
|
* getnetbyaddr: (libc)Networks Database.
|
* getnetbyname: (libc)Networks Database.
|
* getnetent: (libc)Networks Database.
|
* getnetgrent: (libc)Lookup Netgroup.
|
* getnetgrent_r: (libc)Lookup Netgroup.
|
* getopt: (libc)Using Getopt.
|
* getopt_long: (libc)Getopt Long Options.
|
* getopt_long_only: (libc)Getopt Long Options.
|
* getpagesize: (libc)Query Memory Parameters.
|
* getpass: (libc)getpass.
|
* getpeername: (libc)Who is Connected.
|
* getpgid: (libc)Process Group Functions.
|
* getpgrp: (libc)Process Group Functions.
|
* getpid: (libc)Process Identification.
|
* getppid: (libc)Process Identification.
|
* getpriority: (libc)Traditional Scheduling Functions.
|
* getprotobyname: (libc)Protocols Database.
|
* getprotobynumber: (libc)Protocols Database.
|
* getprotoent: (libc)Protocols Database.
|
* getpt: (libc)Allocation.
|
* getpwent: (libc)Scanning All Users.
|
* getpwent_r: (libc)Scanning All Users.
|
* getpwnam: (libc)Lookup User.
|
* getpwnam_r: (libc)Lookup User.
|
* getpwuid: (libc)Lookup User.
|
* getpwuid_r: (libc)Lookup User.
|
* getrlimit64: (libc)Limits on Resources.
|
* getrlimit: (libc)Limits on Resources.
|
* getrusage: (libc)Resource Usage.
|
* gets: (libc)Line Input.
|
* getservbyname: (libc)Services Database.
|
* getservbyport: (libc)Services Database.
|
* getservent: (libc)Services Database.
|
* getsid: (libc)Process Group Functions.
|
* getsockname: (libc)Reading Address.
|
* getsockopt: (libc)Socket Option Functions.
|
* getsubopt: (libc)Suboptions.
|
* gettext: (libc)Translation with gettext.
|
* gettimeofday: (libc)High-Resolution Calendar.
|
* getuid: (libc)Reading Persona.
|
* getumask: (libc)Setting Permissions.
|
* getutent: (libc)Manipulating the Database.
|
* getutent_r: (libc)Manipulating the Database.
|
* getutid: (libc)Manipulating the Database.
|
* getutid_r: (libc)Manipulating the Database.
|
* getutline: (libc)Manipulating the Database.
|
* getutline_r: (libc)Manipulating the Database.
|
* getutmp: (libc)XPG Functions.
|
* getutmpx: (libc)XPG Functions.
|
* getutxent: (libc)XPG Functions.
|
* getutxid: (libc)XPG Functions.
|
* getutxline: (libc)XPG Functions.
|
* getw: (libc)Character Input.
|
* getwc: (libc)Character Input.
|
* getwc_unlocked: (libc)Character Input.
|
* getwchar: (libc)Character Input.
|
* getwchar_unlocked: (libc)Character Input.
|
* getwd: (libc)Working Directory.
|
* glob64: (libc)Calling Glob.
|
* glob: (libc)Calling Glob.
|
* globfree64: (libc)More Flags for Globbing.
|
* globfree: (libc)More Flags for Globbing.
|
* gmtime: (libc)Broken-down Time.
|
* gmtime_r: (libc)Broken-down Time.
|
* grantpt: (libc)Allocation.
|
* gsignal: (libc)Signaling Yourself.
|
* gtty: (libc)BSD Terminal Modes.
|
* hasmntopt: (libc)mtab.
|
* hcreate: (libc)Hash Search Function.
|
* hcreate_r: (libc)Hash Search Function.
|
* hdestroy: (libc)Hash Search Function.
|
* hdestroy_r: (libc)Hash Search Function.
|
* hsearch: (libc)Hash Search Function.
|
* hsearch_r: (libc)Hash Search Function.
|
* htonl: (libc)Byte Order.
|
* htons: (libc)Byte Order.
|
* hypot: (libc)Exponents and Logarithms.
|
* hypotf: (libc)Exponents and Logarithms.
|
* hypotl: (libc)Exponents and Logarithms.
|
* iconv: (libc)Generic Conversion Interface.
|
* iconv_close: (libc)Generic Conversion Interface.
|
* iconv_open: (libc)Generic Conversion Interface.
|
* if_freenameindex: (libc)Interface Naming.
|
* if_indextoname: (libc)Interface Naming.
|
* if_nameindex: (libc)Interface Naming.
|
* if_nametoindex: (libc)Interface Naming.
|
* ilogb: (libc)Exponents and Logarithms.
|
* ilogbf: (libc)Exponents and Logarithms.
|
* ilogbl: (libc)Exponents and Logarithms.
|
* imaxabs: (libc)Absolute Value.
|
* imaxdiv: (libc)Integer Division.
|
* in6addr_any: (libc)Host Address Data Type.
|
* in6addr_loopback: (libc)Host Address Data Type.
|
* index: (libc)Search Functions.
|
* inet_addr: (libc)Host Address Functions.
|
* inet_aton: (libc)Host Address Functions.
|
* inet_lnaof: (libc)Host Address Functions.
|
* inet_makeaddr: (libc)Host Address Functions.
|
* inet_netof: (libc)Host Address Functions.
|
* inet_network: (libc)Host Address Functions.
|
* inet_ntoa: (libc)Host Address Functions.
|
* inet_ntop: (libc)Host Address Functions.
|
* inet_pton: (libc)Host Address Functions.
|
* initgroups: (libc)Setting Groups.
|
* initstate: (libc)BSD Random.
|
* initstate_r: (libc)BSD Random.
|
* innetgr: (libc)Netgroup Membership.
|
* ioctl: (libc)IOCTLs.
|
* isalnum: (libc)Classification of Characters.
|
* isalpha: (libc)Classification of Characters.
|
* isascii: (libc)Classification of Characters.
|
* isatty: (libc)Is It a Terminal.
|
* isblank: (libc)Classification of Characters.
|
* iscntrl: (libc)Classification of Characters.
|
* isdigit: (libc)Classification of Characters.
|
* isfinite: (libc)Floating Point Classes.
|
* isgraph: (libc)Classification of Characters.
|
* isgreater: (libc)FP Comparison Functions.
|
* isgreaterequal: (libc)FP Comparison Functions.
|
* isinf: (libc)Floating Point Classes.
|
* isinff: (libc)Floating Point Classes.
|
* isinfl: (libc)Floating Point Classes.
|
* isless: (libc)FP Comparison Functions.
|
* islessequal: (libc)FP Comparison Functions.
|
* islessgreater: (libc)FP Comparison Functions.
|
* islower: (libc)Classification of Characters.
|
* isnan: (libc)Floating Point Classes.
|
* isnan: (libc)Floating Point Classes.
|
* isnanf: (libc)Floating Point Classes.
|
* isnanl: (libc)Floating Point Classes.
|
* isnormal: (libc)Floating Point Classes.
|
* isprint: (libc)Classification of Characters.
|
* ispunct: (libc)Classification of Characters.
|
* issignaling: (libc)Floating Point Classes.
|
* isspace: (libc)Classification of Characters.
|
* isunordered: (libc)FP Comparison Functions.
|
* isupper: (libc)Classification of Characters.
|
* iswalnum: (libc)Classification of Wide Characters.
|
* iswalpha: (libc)Classification of Wide Characters.
|
* iswblank: (libc)Classification of Wide Characters.
|
* iswcntrl: (libc)Classification of Wide Characters.
|
* iswctype: (libc)Classification of Wide Characters.
|
* iswdigit: (libc)Classification of Wide Characters.
|
* iswgraph: (libc)Classification of Wide Characters.
|
* iswlower: (libc)Classification of Wide Characters.
|
* iswprint: (libc)Classification of Wide Characters.
|
* iswpunct: (libc)Classification of Wide Characters.
|
* iswspace: (libc)Classification of Wide Characters.
|
* iswupper: (libc)Classification of Wide Characters.
|
* iswxdigit: (libc)Classification of Wide Characters.
|
* isxdigit: (libc)Classification of Characters.
|
* j0: (libc)Special Functions.
|
* j0f: (libc)Special Functions.
|
* j0l: (libc)Special Functions.
|
* j1: (libc)Special Functions.
|
* j1f: (libc)Special Functions.
|
* j1l: (libc)Special Functions.
|
* jn: (libc)Special Functions.
|
* jnf: (libc)Special Functions.
|
* jnl: (libc)Special Functions.
|
* jrand48: (libc)SVID Random.
|
* jrand48_r: (libc)SVID Random.
|
* kill: (libc)Signaling Another Process.
|
* killpg: (libc)Signaling Another Process.
|
* l64a: (libc)Encode Binary Data.
|
* labs: (libc)Absolute Value.
|
* lcong48: (libc)SVID Random.
|
* lcong48_r: (libc)SVID Random.
|
* ldexp: (libc)Normalization Functions.
|
* ldexpf: (libc)Normalization Functions.
|
* ldexpl: (libc)Normalization Functions.
|
* ldiv: (libc)Integer Division.
|
* lfind: (libc)Array Search Function.
|
* lgamma: (libc)Special Functions.
|
* lgamma_r: (libc)Special Functions.
|
* lgammaf: (libc)Special Functions.
|
* lgammaf_r: (libc)Special Functions.
|
* lgammal: (libc)Special Functions.
|
* lgammal_r: (libc)Special Functions.
|
* link: (libc)Hard Links.
|
* lio_listio64: (libc)Asynchronous Reads/Writes.
|
* lio_listio: (libc)Asynchronous Reads/Writes.
|
* listen: (libc)Listening.
|
* llabs: (libc)Absolute Value.
|
* lldiv: (libc)Integer Division.
|
* llrint: (libc)Rounding Functions.
|
* llrintf: (libc)Rounding Functions.
|
* llrintl: (libc)Rounding Functions.
|
* llround: (libc)Rounding Functions.
|
* llroundf: (libc)Rounding Functions.
|
* llroundl: (libc)Rounding Functions.
|
* localeconv: (libc)The Lame Way to Locale Data.
|
* localtime: (libc)Broken-down Time.
|
* localtime_r: (libc)Broken-down Time.
|
* log10: (libc)Exponents and Logarithms.
|
* log10f: (libc)Exponents and Logarithms.
|
* log10l: (libc)Exponents and Logarithms.
|
* log1p: (libc)Exponents and Logarithms.
|
* log1pf: (libc)Exponents and Logarithms.
|
* log1pl: (libc)Exponents and Logarithms.
|
* log2: (libc)Exponents and Logarithms.
|
* log2f: (libc)Exponents and Logarithms.
|
* log2l: (libc)Exponents and Logarithms.
|
* log: (libc)Exponents and Logarithms.
|
* logb: (libc)Exponents and Logarithms.
|
* logbf: (libc)Exponents and Logarithms.
|
* logbl: (libc)Exponents and Logarithms.
|
* logf: (libc)Exponents and Logarithms.
|
* login: (libc)Logging In and Out.
|
* login_tty: (libc)Logging In and Out.
|
* logl: (libc)Exponents and Logarithms.
|
* logout: (libc)Logging In and Out.
|
* logwtmp: (libc)Logging In and Out.
|
* longjmp: (libc)Non-Local Details.
|
* lrand48: (libc)SVID Random.
|
* lrand48_r: (libc)SVID Random.
|
* lrint: (libc)Rounding Functions.
|
* lrintf: (libc)Rounding Functions.
|
* lrintl: (libc)Rounding Functions.
|
* lround: (libc)Rounding Functions.
|
* lroundf: (libc)Rounding Functions.
|
* lroundl: (libc)Rounding Functions.
|
* lsearch: (libc)Array Search Function.
|
* lseek64: (libc)File Position Primitive.
|
* lseek: (libc)File Position Primitive.
|
* lstat64: (libc)Reading Attributes.
|
* lstat: (libc)Reading Attributes.
|
* lutimes: (libc)File Times.
|
* madvise: (libc)Memory-mapped I/O.
|
* makecontext: (libc)System V contexts.
|
* mallinfo: (libc)Statistics of Malloc.
|
* malloc: (libc)Basic Allocation.
|
* mallopt: (libc)Malloc Tunable Parameters.
|
* mblen: (libc)Non-reentrant Character Conversion.
|
* mbrlen: (libc)Converting a Character.
|
* mbrtowc: (libc)Converting a Character.
|
* mbsinit: (libc)Keeping the state.
|
* mbsnrtowcs: (libc)Converting Strings.
|
* mbsrtowcs: (libc)Converting Strings.
|
* mbstowcs: (libc)Non-reentrant String Conversion.
|
* mbtowc: (libc)Non-reentrant Character Conversion.
|
* mcheck: (libc)Heap Consistency Checking.
|
* memalign: (libc)Aligned Memory Blocks.
|
* memccpy: (libc)Copying Strings and Arrays.
|
* memchr: (libc)Search Functions.
|
* memcmp: (libc)String/Array Comparison.
|
* memcpy: (libc)Copying Strings and Arrays.
|
* memfrob: (libc)Trivial Encryption.
|
* 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.
|
* mlock: (libc)Page Lock Functions.
|
* mlockall: (libc)Page Lock Functions.
|
* mmap64: (libc)Memory-mapped I/O.
|
* mmap: (libc)Memory-mapped I/O.
|
* modf: (libc)Rounding Functions.
|
* modff: (libc)Rounding Functions.
|
* modfl: (libc)Rounding Functions.
|
* mount: (libc)Mount-Unmount-Remount.
|
* mprobe: (libc)Heap Consistency Checking.
|
* mrand48: (libc)SVID Random.
|
* mrand48_r: (libc)SVID Random.
|
* mremap: (libc)Memory-mapped I/O.
|
* msync: (libc)Memory-mapped I/O.
|
* mtrace: (libc)Tracing malloc.
|
* munlock: (libc)Page Lock Functions.
|
* munlockall: (libc)Page Lock Functions.
|
* munmap: (libc)Memory-mapped I/O.
|
* muntrace: (libc)Tracing malloc.
|
* nan: (libc)FP Bit Twiddling.
|
* nanf: (libc)FP Bit Twiddling.
|
* nanl: (libc)FP Bit Twiddling.
|
* nanosleep: (libc)Sleeping.
|
* nearbyint: (libc)Rounding Functions.
|
* nearbyintf: (libc)Rounding Functions.
|
* nearbyintl: (libc)Rounding Functions.
|
* nextafter: (libc)FP Bit Twiddling.
|
* nextafterf: (libc)FP Bit Twiddling.
|
* nextafterl: (libc)FP Bit Twiddling.
|
* nexttoward: (libc)FP Bit Twiddling.
|
* nexttowardf: (libc)FP Bit Twiddling.
|
* nexttowardl: (libc)FP Bit Twiddling.
|
* nftw64: (libc)Working with Directory Trees.
|
* nftw: (libc)Working with Directory Trees.
|
* ngettext: (libc)Advanced gettext functions.
|
* nice: (libc)Traditional Scheduling Functions.
|
* nl_langinfo: (libc)The Elegant and Fast Way.
|
* nrand48: (libc)SVID Random.
|
* nrand48_r: (libc)SVID Random.
|
* ntohl: (libc)Byte Order.
|
* ntohs: (libc)Byte Order.
|
* ntp_adjtime: (libc)High Accuracy Clock.
|
* ntp_gettime: (libc)High Accuracy Clock.
|
* obstack_1grow: (libc)Growing Objects.
|
* obstack_1grow_fast: (libc)Extra Fast Growing.
|
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
|
* obstack_alloc: (libc)Allocation in an Obstack.
|
* obstack_base: (libc)Status of an Obstack.
|
* obstack_blank: (libc)Growing Objects.
|
* obstack_blank_fast: (libc)Extra Fast Growing.
|
* obstack_chunk_size: (libc)Obstack Chunks.
|
* obstack_copy0: (libc)Allocation in an Obstack.
|
* obstack_copy: (libc)Allocation in an Obstack.
|
* obstack_finish: (libc)Growing Objects.
|
* obstack_free: (libc)Freeing Obstack Objects.
|
* obstack_grow0: (libc)Growing Objects.
|
* obstack_grow: (libc)Growing Objects.
|
* obstack_init: (libc)Preparing for Obstacks.
|
* obstack_int_grow: (libc)Growing Objects.
|
* obstack_int_grow_fast: (libc)Extra Fast Growing.
|
* obstack_next_free: (libc)Status of an Obstack.
|
* obstack_object_size: (libc)Growing Objects.
|
* obstack_object_size: (libc)Status of an Obstack.
|
* obstack_printf: (libc)Dynamic Output.
|
* obstack_ptr_grow: (libc)Growing Objects.
|
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
|
* obstack_room: (libc)Extra Fast Growing.
|
* obstack_vprintf: (libc)Variable Arguments Output.
|
* offsetof: (libc)Structure Measurement.
|
* on_exit: (libc)Cleanups on Exit.
|
* open64: (libc)Opening and Closing Files.
|
* open: (libc)Opening and Closing Files.
|
* open_memstream: (libc)String Streams.
|
* opendir: (libc)Opening a Directory.
|
* openlog: (libc)openlog.
|
* openpty: (libc)Pseudo-Terminal Pairs.
|
* parse_printf_format: (libc)Parsing a Template String.
|
* pathconf: (libc)Pathconf.
|
* pause: (libc)Using Pause.
|
* pclose: (libc)Pipe to a Subprocess.
|
* perror: (libc)Error Messages.
|
* pipe: (libc)Creating a Pipe.
|
* popen: (libc)Pipe to a Subprocess.
|
* posix_fallocate64: (libc)Storage Allocation.
|
* posix_fallocate: (libc)Storage Allocation.
|
* posix_memalign: (libc)Aligned Memory Blocks.
|
* pow10: (libc)Exponents and Logarithms.
|
* pow10f: (libc)Exponents and Logarithms.
|
* pow10l: (libc)Exponents and Logarithms.
|
* pow: (libc)Exponents and Logarithms.
|
* powf: (libc)Exponents and Logarithms.
|
* powl: (libc)Exponents and Logarithms.
|
* pread64: (libc)I/O Primitives.
|
* pread: (libc)I/O Primitives.
|
* printf: (libc)Formatted Output Functions.
|
* printf_size: (libc)Predefined Printf Handlers.
|
* printf_size_info: (libc)Predefined Printf Handlers.
|
* psignal: (libc)Signal Messages.
|
* pthread_getattr_default_np: (libc)Default Thread Attributes.
|
* pthread_getspecific: (libc)Thread-specific Data.
|
* pthread_key_create: (libc)Thread-specific Data.
|
* pthread_key_delete: (libc)Thread-specific Data.
|
* pthread_setattr_default_np: (libc)Default Thread Attributes.
|
* pthread_setspecific: (libc)Thread-specific Data.
|
* ptsname: (libc)Allocation.
|
* ptsname_r: (libc)Allocation.
|
* putc: (libc)Simple Output.
|
* putc_unlocked: (libc)Simple Output.
|
* putchar: (libc)Simple Output.
|
* putchar_unlocked: (libc)Simple Output.
|
* putenv: (libc)Environment Access.
|
* putpwent: (libc)Writing a User Entry.
|
* puts: (libc)Simple Output.
|
* pututline: (libc)Manipulating the Database.
|
* pututxline: (libc)XPG Functions.
|
* putw: (libc)Simple Output.
|
* putwc: (libc)Simple Output.
|
* putwc_unlocked: (libc)Simple Output.
|
* putwchar: (libc)Simple Output.
|
* putwchar_unlocked: (libc)Simple Output.
|
* pwrite64: (libc)I/O Primitives.
|
* pwrite: (libc)I/O Primitives.
|
* qecvt: (libc)System V Number Conversion.
|
* qecvt_r: (libc)System V Number Conversion.
|
* qfcvt: (libc)System V Number Conversion.
|
* qfcvt_r: (libc)System V Number Conversion.
|
* qgcvt: (libc)System V Number Conversion.
|
* qsort: (libc)Array Sort Function.
|
* raise: (libc)Signaling Yourself.
|
* rand: (libc)ISO Random.
|
* rand_r: (libc)ISO Random.
|
* random: (libc)BSD Random.
|
* random_r: (libc)BSD Random.
|
* rawmemchr: (libc)Search Functions.
|
* read: (libc)I/O Primitives.
|
* readdir64: (libc)Reading/Closing Directory.
|
* readdir64_r: (libc)Reading/Closing Directory.
|
* readdir: (libc)Reading/Closing Directory.
|
* readdir_r: (libc)Reading/Closing Directory.
|
* readlink: (libc)Symbolic Links.
|
* readv: (libc)Scatter-Gather.
|
* realloc: (libc)Changing Block Size.
|
* realpath: (libc)Symbolic Links.
|
* recv: (libc)Receiving Data.
|
* recvfrom: (libc)Receiving Datagrams.
|
* recvmsg: (libc)Receiving Datagrams.
|
* regcomp: (libc)POSIX Regexp Compilation.
|
* regerror: (libc)Regexp Cleanup.
|
* regexec: (libc)Matching POSIX Regexps.
|
* regfree: (libc)Regexp Cleanup.
|
* register_printf_function: (libc)Registering New Conversions.
|
* remainder: (libc)Remainder Functions.
|
* remainderf: (libc)Remainder Functions.
|
* remainderl: (libc)Remainder Functions.
|
* remove: (libc)Deleting Files.
|
* rename: (libc)Renaming Files.
|
* rewind: (libc)File Positioning.
|
* rewinddir: (libc)Random Access Directory.
|
* rindex: (libc)Search Functions.
|
* rint: (libc)Rounding Functions.
|
* rintf: (libc)Rounding Functions.
|
* rintl: (libc)Rounding Functions.
|
* rmdir: (libc)Deleting Files.
|
* round: (libc)Rounding Functions.
|
* roundf: (libc)Rounding Functions.
|
* roundl: (libc)Rounding Functions.
|
* rpmatch: (libc)Yes-or-No Questions.
|
* sbrk: (libc)Resizing the Data Segment.
|
* scalb: (libc)Normalization Functions.
|
* scalbf: (libc)Normalization Functions.
|
* scalbl: (libc)Normalization Functions.
|
* scalbln: (libc)Normalization Functions.
|
* scalblnf: (libc)Normalization Functions.
|
* scalblnl: (libc)Normalization Functions.
|
* scalbn: (libc)Normalization Functions.
|
* scalbnf: (libc)Normalization Functions.
|
* scalbnl: (libc)Normalization Functions.
|
* scandir64: (libc)Scanning Directory Content.
|
* scandir: (libc)Scanning Directory Content.
|
* scanf: (libc)Formatted Input Functions.
|
* sched_get_priority_max: (libc)Basic Scheduling Functions.
|
* sched_get_priority_min: (libc)Basic Scheduling Functions.
|
* sched_getaffinity: (libc)CPU Affinity.
|
* sched_getparam: (libc)Basic Scheduling Functions.
|
* sched_getscheduler: (libc)Basic Scheduling Functions.
|
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
|
* sched_setaffinity: (libc)CPU Affinity.
|
* sched_setparam: (libc)Basic Scheduling Functions.
|
* sched_setscheduler: (libc)Basic Scheduling Functions.
|
* sched_yield: (libc)Basic Scheduling Functions.
|
* secure_getenv: (libc)Environment Access.
|
* seed48: (libc)SVID Random.
|
* seed48_r: (libc)SVID Random.
|
* seekdir: (libc)Random Access Directory.
|
* select: (libc)Waiting for I/O.
|
* 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.
|
* setkey: (libc)DES Encryption.
|
* setkey_r: (libc)DES Encryption.
|
* setlinebuf: (libc)Controlling Buffering.
|
* setlocale: (libc)Setting the Locale.
|
* setlogmask: (libc)setlogmask.
|
* setmntent: (libc)mtab.
|
* setnetent: (libc)Networks Database.
|
* setnetgrent: (libc)Lookup Netgroup.
|
* setpgid: (libc)Process Group Functions.
|
* setpgrp: (libc)Process Group Functions.
|
* setpriority: (libc)Traditional Scheduling Functions.
|
* setprotoent: (libc)Protocols Database.
|
* setpwent: (libc)Scanning All Users.
|
* setregid: (libc)Setting Groups.
|
* setreuid: (libc)Setting User ID.
|
* setrlimit64: (libc)Limits on Resources.
|
* setrlimit: (libc)Limits on Resources.
|
* setservent: (libc)Services Database.
|
* setsid: (libc)Process Group Functions.
|
* setsockopt: (libc)Socket Option Functions.
|
* setstate: (libc)BSD Random.
|
* setstate_r: (libc)BSD Random.
|
* settimeofday: (libc)High-Resolution Calendar.
|
* setuid: (libc)Setting User ID.
|
* setutent: (libc)Manipulating the Database.
|
* setutxent: (libc)XPG Functions.
|
* setvbuf: (libc)Controlling Buffering.
|
* shm_open: (libc)Memory-mapped I/O.
|
* shm_unlink: (libc)Memory-mapped I/O.
|
* shutdown: (libc)Closing a Socket.
|
* sigaction: (libc)Advanced Signal Handling.
|
* sigaddset: (libc)Signal Sets.
|
* sigaltstack: (libc)Signal Stack.
|
* sigblock: (libc)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.
|
* sincosl: (libc)Trig Functions.
|
* sinf: (libc)Trig Functions.
|
* sinh: (libc)Hyperbolic Functions.
|
* sinhf: (libc)Hyperbolic Functions.
|
* sinhl: (libc)Hyperbolic Functions.
|
* sinl: (libc)Trig Functions.
|
* sleep: (libc)Sleeping.
|
* snprintf: (libc)Formatted Output Functions.
|
* socket: (libc)Creating a Socket.
|
* socketpair: (libc)Socket Pairs.
|
* sprintf: (libc)Formatted Output Functions.
|
* sqrt: (libc)Exponents and Logarithms.
|
* sqrtf: (libc)Exponents and Logarithms.
|
* sqrtl: (libc)Exponents and Logarithms.
|
* srand48: (libc)SVID Random.
|
* srand48_r: (libc)SVID Random.
|
* srand: (libc)ISO Random.
|
* srandom: (libc)BSD Random.
|
* srandom_r: (libc)BSD Random.
|
* sscanf: (libc)Formatted Input Functions.
|
* ssignal: (libc)Basic Signal Handling.
|
* stat64: (libc)Reading Attributes.
|
* stat: (libc)Reading Attributes.
|
* stime: (libc)Simple Calendar Time.
|
* stpcpy: (libc)Copying 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.
|
* strfry: (libc)strfry.
|
* 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.
|
* strtoimax: (libc)Parsing of Integers.
|
* strtok: (libc)Finding Tokens in a String.
|
* strtok_r: (libc)Finding Tokens in a String.
|
* strtol: (libc)Parsing of Integers.
|
* strtold: (libc)Parsing of Floats.
|
* strtoll: (libc)Parsing of Integers.
|
* strtoq: (libc)Parsing of Integers.
|
* strtoul: (libc)Parsing of Integers.
|
* strtoull: (libc)Parsing of Integers.
|
* strtoumax: (libc)Parsing of Integers.
|
* strtouq: (libc)Parsing of Integers.
|
* strverscmp: (libc)String/Array Comparison.
|
* strxfrm: (libc)Collation Functions.
|
* stty: (libc)BSD Terminal Modes.
|
* swapcontext: (libc)System V contexts.
|
* swprintf: (libc)Formatted Output Functions.
|
* swscanf: (libc)Formatted Input Functions.
|
* symlink: (libc)Symbolic Links.
|
* sync: (libc)Synchronizing I/O.
|
* syscall: (libc)System Calls.
|
* sysconf: (libc)Sysconf Definition.
|
* sysctl: (libc)System Parameters.
|
* syslog: (libc)syslog; vsyslog.
|
* system: (libc)Running a Command.
|
* sysv_signal: (libc)Basic Signal Handling.
|
* tan: (libc)Trig Functions.
|
* tanf: (libc)Trig Functions.
|
* tanh: (libc)Hyperbolic Functions.
|
* tanhf: (libc)Hyperbolic Functions.
|
* tanhl: (libc)Hyperbolic Functions.
|
* tanl: (libc)Trig Functions.
|
* tcdrain: (libc)Line Control.
|
* tcflow: (libc)Line Control.
|
* tcflush: (libc)Line Control.
|
* tcgetattr: (libc)Mode Functions.
|
* tcgetpgrp: (libc)Terminal Access Functions.
|
* tcgetsid: (libc)Terminal Access Functions.
|
* tcsendbreak: (libc)Line Control.
|
* tcsetattr: (libc)Mode Functions.
|
* tcsetpgrp: (libc)Terminal Access Functions.
|
* tdelete: (libc)Tree Search Function.
|
* tdestroy: (libc)Tree Search Function.
|
* telldir: (libc)Random Access Directory.
|
* tempnam: (libc)Temporary Files.
|
* textdomain: (libc)Locating gettext catalog.
|
* tfind: (libc)Tree Search Function.
|
* tgamma: (libc)Special Functions.
|
* tgammaf: (libc)Special Functions.
|
* tgammal: (libc)Special Functions.
|
* time: (libc)Simple Calendar Time.
|
* timegm: (libc)Broken-down Time.
|
* timelocal: (libc)Broken-down Time.
|
* times: (libc)Processor Time.
|
* tmpfile64: (libc)Temporary Files.
|
* tmpfile: (libc)Temporary Files.
|
* tmpnam: (libc)Temporary Files.
|
* tmpnam_r: (libc)Temporary Files.
|
* toascii: (libc)Case Conversion.
|
* tolower: (libc)Case Conversion.
|
* toupper: (libc)Case Conversion.
|
* towctrans: (libc)Wide Character Case Conversion.
|
* towlower: (libc)Wide Character Case Conversion.
|
* towupper: (libc)Wide Character Case Conversion.
|
* trunc: (libc)Rounding Functions.
|
* truncate64: (libc)File Size.
|
* truncate: (libc)File Size.
|
* truncf: (libc)Rounding Functions.
|
* truncl: (libc)Rounding Functions.
|
* tsearch: (libc)Tree Search Function.
|
* ttyname: (libc)Is It a Terminal.
|
* ttyname_r: (libc)Is It a Terminal.
|
* twalk: (libc)Tree Search Function.
|
* tzset: (libc)Time Zone Functions.
|
* ulimit: (libc)Limits on Resources.
|
* umask: (libc)Setting Permissions.
|
* umount2: (libc)Mount-Unmount-Remount.
|
* umount: (libc)Mount-Unmount-Remount.
|
* uname: (libc)Platform Type.
|
* ungetc: (libc)How Unread.
|
* ungetwc: (libc)How Unread.
|
* unlink: (libc)Deleting Files.
|
* unlockpt: (libc)Allocation.
|
* unsetenv: (libc)Environment Access.
|
* updwtmp: (libc)Manipulating the Database.
|
* utime: (libc)File Times.
|
* utimes: (libc)File Times.
|
* utmpname: (libc)Manipulating the Database.
|
* utmpxname: (libc)XPG Functions.
|
* va_arg: (libc)Argument Macros.
|
* va_copy: (libc)Argument Macros.
|
* va_end: (libc)Argument Macros.
|
* va_start: (libc)Argument Macros.
|
* valloc: (libc)Aligned Memory Blocks.
|
* vasprintf: (libc)Variable Arguments Output.
|
* verr: (libc)Error Messages.
|
* verrx: (libc)Error Messages.
|
* versionsort64: (libc)Scanning Directory Content.
|
* versionsort: (libc)Scanning Directory Content.
|
* vfork: (libc)Creating a Process.
|
* vfprintf: (libc)Variable Arguments Output.
|
* vfscanf: (libc)Variable Arguments Input.
|
* vfwprintf: (libc)Variable Arguments Output.
|
* vfwscanf: (libc)Variable Arguments Input.
|
* vlimit: (libc)Limits on Resources.
|
* vprintf: (libc)Variable Arguments Output.
|
* vscanf: (libc)Variable Arguments Input.
|
* vsnprintf: (libc)Variable Arguments Output.
|
* vsprintf: (libc)Variable Arguments Output.
|
* vsscanf: (libc)Variable Arguments Input.
|
* vswprintf: (libc)Variable Arguments Output.
|
* vswscanf: (libc)Variable Arguments Input.
|
* vsyslog: (libc)syslog; vsyslog.
|
* vtimes: (libc)Resource Usage.
|
* vwarn: (libc)Error Messages.
|
* vwarnx: (libc)Error Messages.
|
* vwprintf: (libc)Variable Arguments Output.
|
* vwscanf: (libc)Variable Arguments Input.
|
* wait3: (libc)BSD Wait Functions.
|
* wait4: (libc)Process Completion.
|
* wait: (libc)Process Completion.
|
* waitpid: (libc)Process Completion.
|
* warn: (libc)Error Messages.
|
* warnx: (libc)Error Messages.
|
* wcpcpy: (libc)Copying 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.
|
* 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.
|
* y0l: (libc)Special Functions.
|
* y1: (libc)Special Functions.
|
* y1f: (libc)Special Functions.
|
* y1l: (libc)Special Functions.
|
* yn: (libc)Special Functions.
|
* ynf: (libc)Special Functions.
|
* ynl: (libc)Special Functions.
|
END-INFO-DIR-ENTRY
|
|
|
File: libc.info, Node: Extending NSS, Prev: NSS Module Internals, Up: Name Service Switch
|
|
29.4 Extending NSS
|
==================
|
|
One of the advantages of NSS mentioned above is that it can be extended
|
quite easily. There are two ways in which the extension can happen:
|
adding another database or adding another service. The former is
|
normally done only by the C library developers. It is here only
|
important to remember that adding another database is independent from
|
adding another service because a service need not support all databases
|
or lookup functions.
|
|
A designer/implementor of a new service is therefore free to choose
|
the databases s/he is interested in and leave the rest for later (or
|
completely aside).
|
|
* Menu:
|
|
* Adding another Service to NSS:: What is to do to add a new service.
|
* NSS Module Function Internals:: Guidelines for writing new NSS
|
service functions.
|
|
|
File: libc.info, Node: Adding another Service to NSS, Next: NSS Module Function Internals, Prev: Extending NSS, Up: Extending NSS
|
|
29.4.1 Adding another Service to NSS
|
------------------------------------
|
|
The sources for a new service need not (and should not) be part of the
|
GNU C Library itself. The developer retains complete control over the
|
sources and its development. The links between the C library and the
|
new service module consists solely of the interface functions.
|
|
Each module is designed following a specific interface specification.
|
For now the version is 2 (the interface in version 1 was not adequate)
|
and this manifests in the version number of the shared library object of
|
the NSS modules: they have the extension ‘.2’. If the interface changes
|
again in an incompatible way, this number will be increased. Modules
|
using the old interface will still be usable.
|
|
Developers of a new service will have to make sure that their module
|
is created using the correct interface number. This means the file
|
itself must have the correct name and on ELF systems the "soname"
|
(Shared Object Name) must also have this number. Building a module from
|
a bunch of object files on an ELF system using GNU CC could be done like
|
this:
|
|
gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS
|
|
*note Options for Linking: (gcc)Link Options, to learn more about this
|
command line.
|
|
To use the new module the library must be able to find it. This can
|
be achieved by using options for the dynamic linker so that it will
|
search the directory where the binary is placed. For an ELF system this
|
could be done by adding the wanted directory to the value of
|
‘LD_LIBRARY_PATH’.
|
|
But this is not always possible since some programs (those which run
|
under IDs which do not belong to the user) ignore this variable.
|
Therefore the stable version of the module should be placed into a
|
directory which is searched by the dynamic linker. Normally this should
|
be the directory ‘$prefix/lib’, where ‘$prefix’ corresponds to the value
|
given to configure using the ‘--prefix’ option. But be careful: this
|
should only be done if it is clear the module does not cause any harm.
|
System administrators should be careful.
|
|
|
File: libc.info, Node: NSS Module Function Internals, Prev: Adding another Service to NSS, Up: Extending NSS
|
|
29.4.2 Internals of the NSS Module Functions
|
--------------------------------------------
|
|
Until now we only provided the syntactic interface for the functions in
|
the NSS module. In fact there is not much more we can say since the
|
implementation obviously is different for each function. But a few
|
general rules must be followed by all functions.
|
|
In fact there are four kinds of different functions which may appear
|
in the interface. All derive from the traditional ones for system
|
databases. DB in the following table is normally an abbreviation for
|
the database (e.g., it is ‘pw’ for the password database).
|
|
‘enum nss_status _nss_DATABASE_setDBent (void)’
|
This function prepares the service for following operations. For a
|
simple file based lookup this means files could be opened, for
|
other services this function simply is a noop.
|
|
One special case for this function is that it takes an additional
|
argument for some DATABASEs (i.e., the interface is ‘int setDBent
|
(int)’). *note Host Names::, which describes the ‘sethostent’
|
function.
|
|
The return value should be NSS_STATUS_SUCCESS or according to the
|
table above in case of an error (*note NSS Modules Interface::).
|
|
‘enum nss_status _nss_DATABASE_endDBent (void)’
|
This function simply closes all files which are still open or
|
removes buffer caches. If there are no files or buffers to remove
|
this is again a simple noop.
|
|
There normally is no return value different to NSS_STATUS_SUCCESS.
|
|
‘enum nss_status _nss_DATABASE_getDBent_r (STRUCTURE *result, char *buffer, size_t buflen, int *errnop)’
|
Since this function will be called several times in a row to
|
retrieve one entry after the other it must keep some kind of state.
|
But this also means the functions are not really reentrant. They
|
are reentrant only in that simultaneous calls to this function will
|
not try to write the retrieved data in the same place (as it would
|
be the case for the non-reentrant functions); instead, it writes to
|
the structure pointed to by the RESULT parameter. But the calls
|
share a common state and in the case of a file access this means
|
they return neighboring entries in the file.
|
|
The buffer of length BUFLEN pointed to by BUFFER can be used for
|
storing some additional data for the result. It is _not_
|
guaranteed that the same buffer will be passed for the next call of
|
this function. Therefore one must not misuse this buffer to save
|
some state information from one call to another.
|
|
Before the function returns the implementation should store the
|
value of the local ERRNO variable in the variable pointed to be
|
ERRNOP. This is important to guarantee the module working in
|
statically linked programs.
|
|
As explained above this function could also have an additional last
|
argument. This depends on the database used; it happens only for
|
‘host’ and ‘networks’.
|
|
The function shall return ‘NSS_STATUS_SUCCESS’ as long as there are
|
more entries. When the last entry was read it should return
|
‘NSS_STATUS_NOTFOUND’. When the buffer given as an argument is too
|
small for the data to be returned ‘NSS_STATUS_TRYAGAIN’ should be
|
returned. When the service was not formerly initialized by a call
|
to ‘_nss_DATABASE_setDBent’ all return value allowed for this
|
function can also be returned here.
|
|
‘enum nss_status _nss_DATABASE_getDBbyXX_r (PARAMS, STRUCTURE *result, char *buffer, size_t buflen, int *errnop)’
|
This function shall return the entry from the database which is
|
addressed by the PARAMS. The type and number of these arguments
|
vary. It must be individually determined by looking to the
|
user-level interface functions. All arguments given to the
|
non-reentrant version are here described by PARAMS.
|
|
The result must be stored in the structure pointed to by RESULT.
|
If there is additional data to return (say strings, where the
|
RESULT structure only contains pointers) the function must use the
|
BUFFER or length BUFLEN. There must not be any references to
|
non-constant global data.
|
|
The implementation of this function should honor the STAYOPEN flag
|
set by the ‘setDBent’ function whenever this makes sense.
|
|
Before the function returns the implementation should store the
|
value of the local ERRNO variable in the variable pointed to be
|
ERRNOP. This is important to guarantee the module working in
|
statically linked programs.
|
|
Again, this function takes an additional last argument for the
|
‘host’ and ‘networks’ database.
|
|
The return value should as always follow the rules given above
|
(*note NSS Modules Interface::).
|
|
|
File: libc.info, Node: Users and Groups, Next: System Management, Prev: Name Service Switch, Up: Top
|
|
30 Users and Groups
|
*******************
|
|
Every user who can log in on the system is identified by a unique number
|
called the "user ID". Each process has an effective user ID which says
|
which user’s access permissions it has.
|
|
Users are classified into "groups" for access control purposes. Each
|
process has one or more "group ID values" which say which groups the
|
process can use for access to files.
|
|
The effective user and group IDs of a process collectively form its
|
"persona". This determines which files the process can access.
|
Normally, a process inherits its persona from the parent process, but
|
under special circumstances a process can change its persona and thus
|
change its access permissions.
|
|
Each file in the system also has a user ID and a group ID. Access
|
control works by comparing the user and group IDs of the file with those
|
of the running process.
|
|
The system keeps a database of all the registered users, and another
|
database of all the defined groups. There are library functions you can
|
use to examine these databases.
|
|
* Menu:
|
|
* User and Group IDs:: Each user has a unique numeric ID;
|
likewise for groups.
|
* Process Persona:: The user IDs and group IDs of a process.
|
* Why Change Persona:: Why a program might need to change
|
its user and/or group IDs.
|
* How Change Persona:: Changing the user and group IDs.
|
* Reading Persona:: How to examine the user and group IDs.
|
|
* Setting User ID:: Functions for setting the user ID.
|
* Setting Groups:: Functions for setting the group IDs.
|
|
* Enable/Disable Setuid:: Turning setuid access on and off.
|
* Setuid Program Example:: The pertinent parts of one sample program.
|
* Tips for Setuid:: How to avoid granting unlimited access.
|
|
* Who Logged In:: Getting the name of the user who logged in,
|
or of the real user ID of the current process.
|
|
* User Accounting Database:: Keeping information about users and various
|
actions in databases.
|
|
* User Database:: Functions and data structures for
|
accessing the user database.
|
* Group Database:: Functions and data structures for
|
accessing the group database.
|
* Database Example:: Example program showing the use of database
|
inquiry functions.
|
* Netgroup Database:: Functions for accessing the netgroup database.
|
|
|
File: libc.info, Node: User and Group IDs, Next: Process Persona, Up: Users and Groups
|
|
30.1 User and Group IDs
|
=======================
|
|
Each user account on a computer system is identified by a "user name"
|
(or "login name") and "user ID". Normally, each user name has a unique
|
user ID, but it is possible for several login names to have the same
|
user ID. The user names and corresponding user IDs are stored in a data
|
base which you can access as described in *note User Database::.
|
|
Users are classified in "groups". Each user name belongs to one
|
"default group" and may also belong to any number of "supplementary
|
groups". Users who are members of the same group can share resources
|
(such as files) that are not accessible to users who are not a member of
|
that group. Each group has a "group name" and "group ID". *Note Group
|
Database::, for how to find information about a group ID or group name.
|
|
|
File: libc.info, Node: Process Persona, Next: Why Change Persona, Prev: User and Group IDs, Up: Users and Groups
|
|
30.2 The Persona of a Process
|
=============================
|
|
At any time, each process has an "effective user ID", a "effective group
|
ID", and a set of "supplementary group IDs". These IDs determine the
|
privileges of the process. They are collectively called the "persona"
|
of the process, because they determine “who it is” for purposes of
|
access control.
|
|
Your login shell starts out with a persona which consists of your
|
user ID, your default group ID, and your supplementary group IDs (if you
|
are in more than one group). In normal circumstances, all your other
|
processes inherit these values.
|
|
A process also has a "real user ID" which identifies the user who
|
created the process, and a "real group ID" which identifies that user’s
|
default group. These values do not play a role in access control, so we
|
do not consider them part of the persona. But they are also important.
|
|
Both the real and effective user ID can be changed during the
|
lifetime of a process. *Note Why Change Persona::.
|
|
For details on how a process’s effective user ID and group IDs affect
|
its permission to access files, see *note Access Permission::.
|
|
The effective user ID of a process also controls permissions for
|
sending signals using the ‘kill’ function. *Note Signaling Another
|
Process::.
|
|
Finally, there are many operations which can only be performed by a
|
process whose effective user ID is zero. A process with this user ID is
|
a "privileged process". Commonly the user name ‘root’ is associated
|
with user ID 0, but there may be other user names with this ID.
|
|
|
File: libc.info, Node: Why Change Persona, Next: How Change Persona, Prev: Process Persona, Up: Users and Groups
|
|
30.3 Why Change the Persona of a Process?
|
=========================================
|
|
The most obvious situation where it is necessary for a process to change
|
its user and/or group IDs is the ‘login’ program. When ‘login’ starts
|
running, its user ID is ‘root’. Its job is to start a shell whose user
|
and group IDs are those of the user who is logging in. (To accomplish
|
this fully, ‘login’ must set the real user and group IDs as well as its
|
persona. But this is a special case.)
|
|
The more common case of changing persona is when an ordinary user
|
program needs access to a resource that wouldn’t ordinarily be
|
accessible to the user actually running it.
|
|
For example, you may have a file that is controlled by your program
|
but that shouldn’t be read or modified directly by other users, either
|
because it implements some kind of locking protocol, or because you want
|
to preserve the integrity or privacy of the information it contains.
|
This kind of restricted access can be implemented by having the program
|
change its effective user or group ID to match that of the resource.
|
|
Thus, imagine a game program that saves scores in a file. The game
|
program itself needs to be able to update this file no matter who is
|
running it, but if users can write the file without going through the
|
game, they can give themselves any scores they like. Some people
|
consider this undesirable, or even reprehensible. It can be prevented
|
by creating a new user ID and login name (say, ‘games’) to own the
|
scores file, and make the file writable only by this user. Then, when
|
the game program wants to update this file, it can change its effective
|
user ID to be that for ‘games’. In effect, the program must adopt the
|
persona of ‘games’ so it can write the scores file.
|
|
|
File: libc.info, Node: How Change Persona, Next: Reading Persona, Prev: Why Change Persona, Up: Users and Groups
|
|
30.4 How an Application Can Change Persona
|
==========================================
|
|
The ability to change the persona of a process can be a source of
|
unintentional privacy violations, or even intentional abuse. Because of
|
the potential for problems, changing persona is restricted to special
|
circumstances.
|
|
You can’t arbitrarily set your user ID or group ID to anything you
|
want; only privileged processes can do that. Instead, the normal way
|
for a program to change its persona is that it has been set up in
|
advance to change to a particular user or group. This is the function
|
of the setuid and setgid bits of a file’s access mode. *Note Permission
|
Bits::.
|
|
When the setuid bit of an executable file is on, executing that file
|
gives the process a third user ID: the "file user ID". This ID is set to
|
the owner ID of the file. The system then changes the effective user ID
|
to the file user ID. The real user ID remains as it was. Likewise, if
|
the setgid bit is on, the process is given a "file group ID" equal to
|
the group ID of the file, and its effective group ID is changed to the
|
file group ID.
|
|
If a process has a file ID (user or group), then it can at any time
|
change its effective ID to its real ID and back to its file ID. Programs
|
use this feature to relinquish their special privileges except when they
|
actually need them. This makes it less likely that they can be tricked
|
into doing something inappropriate with their privileges.
|
|
*Portability Note:* Older systems do not have file IDs. To determine
|
if a system has this feature, you can test the compiler define
|
‘_POSIX_SAVED_IDS’. (In the POSIX standard, file IDs are known as saved
|
IDs.)
|
|
*Note File Attributes::, for a more general discussion of file modes
|
and accessibility.
|
|
|
File: libc.info, Node: Reading Persona, Next: Setting User ID, Prev: How Change Persona, Up: Users and Groups
|
|
30.5 Reading the Persona of a Process
|
=====================================
|
|
Here are detailed descriptions of the functions for reading the user and
|
group IDs of a process, both real and effective. To use these
|
facilities, you must include the header files ‘sys/types.h’ and
|
‘unistd.h’.
|
|
-- Data Type: uid_t
|
This is an integer data type used to represent user IDs. In the
|
GNU C Library, this is an alias for ‘unsigned int’.
|
|
-- Data Type: gid_t
|
This is an integer data type used to represent group IDs. In the
|
GNU C Library, this is an alias for ‘unsigned int’.
|
|
-- Function: uid_t getuid (void)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getuid’ function returns the real user ID of the process.
|
|
-- Function: gid_t getgid (void)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getgid’ function returns the real group ID of the process.
|
|
-- Function: uid_t geteuid (void)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘geteuid’ function returns the effective user ID of the
|
process.
|
|
-- Function: gid_t getegid (void)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getegid’ function returns the effective group ID of the
|
process.
|
|
-- Function: int getgroups (int COUNT, gid_t *GROUPS)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getgroups’ function is used to inquire about the supplementary
|
group IDs of the process. Up to COUNT of these group IDs are
|
stored in the array GROUPS; the return value from the function is
|
the number of group IDs actually stored. If COUNT is smaller than
|
the total number of supplementary group IDs, then ‘getgroups’
|
returns a value of ‘-1’ and ‘errno’ is set to ‘EINVAL’.
|
|
If COUNT is zero, then ‘getgroups’ just returns the total number of
|
supplementary group IDs. On systems that do not support
|
supplementary groups, this will always be zero.
|
|
Here’s how to use ‘getgroups’ to read all the supplementary group
|
IDs:
|
|
gid_t *
|
read_all_groups (void)
|
{
|
int ngroups = getgroups (0, NULL);
|
gid_t *groups
|
= (gid_t *) xmalloc (ngroups * sizeof (gid_t));
|
int val = getgroups (ngroups, groups);
|
if (val < 0)
|
{
|
free (groups);
|
return NULL;
|
}
|
return groups;
|
}
|
|
|
File: libc.info, Node: Setting User ID, Next: Setting Groups, Prev: Reading Persona, Up: Users and Groups
|
|
30.6 Setting the User ID
|
========================
|
|
This section describes the functions for altering the user ID (real
|
and/or effective) of a process. To use these facilities, you must
|
include the header files ‘sys/types.h’ and ‘unistd.h’.
|
|
-- Function: int seteuid (uid_t NEWEUID)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function sets the effective user ID of a process to NEWEUID,
|
provided that the process is allowed to change its effective user
|
ID. A privileged process (effective user ID zero) can change its
|
effective user ID to any legal value. An unprivileged process with
|
a file user ID can change its effective user ID to its real user ID
|
or to its file user ID. Otherwise, a process may not change its
|
effective user ID at all.
|
|
The ‘seteuid’ function returns a value of ‘0’ to indicate
|
successful completion, and a value of ‘-1’ to indicate an error.
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EINVAL’
|
The value of the NEWEUID argument is invalid.
|
|
‘EPERM’
|
The process may not change to the specified ID.
|
|
Older systems (those without the ‘_POSIX_SAVED_IDS’ feature) do not
|
have this function.
|
|
-- Function: int setuid (uid_t NEWUID)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
If the calling process is privileged, this function sets both the
|
real and effective user ID of the process to NEWUID. It also
|
deletes the file user ID of the process, if any. NEWUID may be any
|
legal value. (Once this has been done, there is no way to recover
|
the old effective user ID.)
|
|
If the process is not privileged, and the system supports the
|
‘_POSIX_SAVED_IDS’ feature, then this function behaves like
|
‘seteuid’.
|
|
The return values and error conditions are the same as for
|
‘seteuid’.
|
|
-- Function: int setreuid (uid_t RUID, uid_t EUID)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function sets the real user ID of the process to RUID and the
|
effective user ID to EUID. If RUID is ‘-1’, it means not to change
|
the real user ID; likewise if EUID is ‘-1’, it means not to change
|
the effective user ID.
|
|
The ‘setreuid’ function exists for compatibility with 4.3 BSD Unix,
|
which does not support file IDs. You can use this function to swap
|
the effective and real user IDs of the process. (Privileged
|
processes are not limited to this particular usage.) If file IDs
|
are supported, you should use that feature instead of this
|
function. *Note Enable/Disable Setuid::.
|
|
The return value is ‘0’ on success and ‘-1’ on failure. The
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EPERM’
|
The process does not have the appropriate privileges; you do
|
not have permission to change to the specified ID.
|
|
|
File: libc.info, Node: Setting Groups, Next: Enable/Disable Setuid, Prev: Setting User ID, Up: Users and Groups
|
|
30.7 Setting the Group IDs
|
==========================
|
|
This section describes the functions for altering the group IDs (real
|
and effective) of a process. To use these facilities, you must include
|
the header files ‘sys/types.h’ and ‘unistd.h’.
|
|
-- Function: int setegid (gid_t NEWGID)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function sets the effective group ID of the process to NEWGID,
|
provided that the process is allowed to change its group ID. Just
|
as with ‘seteuid’, if the process is privileged it may change its
|
effective group ID to any value; if it isn’t, but it has a file
|
group ID, then it may change to its real group ID or file group ID;
|
otherwise it may not change its effective group ID.
|
|
Note that a process is only privileged if its effective _user_ ID
|
is zero. The effective group ID only affects access permissions.
|
|
The return values and error conditions for ‘setegid’ are the same
|
as those for ‘seteuid’.
|
|
This function is only present if ‘_POSIX_SAVED_IDS’ is defined.
|
|
-- Function: int setgid (gid_t NEWGID)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function sets both the real and effective group ID of the
|
process to NEWGID, provided that the process is privileged. It
|
also deletes the file group ID, if any.
|
|
If the process is not privileged, then ‘setgid’ behaves like
|
‘setegid’.
|
|
The return values and error conditions for ‘setgid’ are the same as
|
those for ‘seteuid’.
|
|
-- Function: int setregid (gid_t RGID, gid_t EGID)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function sets the real group ID of the process to RGID and the
|
effective group ID to EGID. If RGID is ‘-1’, it means not to
|
change the real group ID; likewise if EGID is ‘-1’, it means not to
|
change the effective group ID.
|
|
The ‘setregid’ function is provided for compatibility with 4.3 BSD
|
Unix, which does not support file IDs. You can use this function
|
to swap the effective and real group IDs of the process.
|
(Privileged processes are not limited to this usage.) If file IDs
|
are supported, you should use that feature instead of using this
|
function. *Note Enable/Disable Setuid::.
|
|
The return values and error conditions for ‘setregid’ are the same
|
as those for ‘setreuid’.
|
|
‘setuid’ and ‘setgid’ behave differently depending on whether the
|
effective user ID at the time is zero. If it is not zero, they behave
|
like ‘seteuid’ and ‘setegid’. If it is, they change both effective and
|
real IDs and delete the file ID. To avoid confusion, we recommend you
|
always use ‘seteuid’ and ‘setegid’ except when you know the effective
|
user ID is zero and your intent is to change the persona permanently.
|
This case is rare—most of the programs that need it, such as ‘login’ and
|
‘su’, have already been written.
|
|
Note that if your program is setuid to some user other than ‘root’,
|
there is no way to drop privileges permanently.
|
|
The system also lets privileged processes change their supplementary
|
group IDs. To use ‘setgroups’ or ‘initgroups’, your programs should
|
include the header file ‘grp.h’.
|
|
-- Function: int setgroups (size_t COUNT, const gid_t *GROUPS)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
This function sets the process’s supplementary group IDs. It can
|
only be called from privileged processes. The COUNT argument
|
specifies the number of group IDs in the array GROUPS.
|
|
This function returns ‘0’ if successful and ‘-1’ on error. The
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EPERM’
|
The calling process is not privileged.
|
|
-- Function: int initgroups (const char *USER, gid_t GROUP)
|
Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
|
AC-Unsafe corrupt mem fd lock | *Note POSIX Safety Concepts::.
|
|
The ‘initgroups’ function sets the process’s supplementary group
|
IDs to be the normal default for the user name USER. The group
|
GROUP is automatically included.
|
|
This function works by scanning the group database for all the
|
groups USER belongs to. It then calls ‘setgroups’ with the list it
|
has constructed.
|
|
The return values and error conditions are the same as for
|
‘setgroups’.
|
|
If you are interested in the groups a particular user belongs to, but
|
do not want to change the process’s supplementary group IDs, you can use
|
‘getgrouplist’. To use ‘getgrouplist’, your programs should include the
|
header file ‘grp.h’.
|
|
-- Function: int getgrouplist (const char *USER, gid_t GROUP, gid_t
|
*GROUPS, int *NGROUPS)
|
Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
|
AC-Unsafe corrupt mem fd lock | *Note POSIX Safety Concepts::.
|
|
The ‘getgrouplist’ function scans the group database for all the
|
groups USER belongs to. Up to *NGROUPS group IDs corresponding to
|
these groups are stored in the array GROUPS; the return value from
|
the function is the number of group IDs actually stored. If
|
*NGROUPS is smaller than the total number of groups found, then
|
‘getgrouplist’ returns a value of ‘-1’ and stores the actual number
|
of groups in *NGROUPS. The group GROUP is automatically included
|
in the list of groups returned by ‘getgrouplist’.
|
|
Here’s how to use ‘getgrouplist’ to read all supplementary groups
|
for USER:
|
|
gid_t *
|
supplementary_groups (char *user)
|
{
|
int ngroups = 16;
|
gid_t *groups
|
= (gid_t *) xmalloc (ngroups * sizeof (gid_t));
|
struct passwd *pw = getpwnam (user);
|
|
if (pw == NULL)
|
return NULL;
|
|
if (getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups) < 0)
|
{
|
groups = xrealloc (ngroups * sizeof (gid_t));
|
getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups);
|
}
|
return groups;
|
}
|
|
|
File: libc.info, Node: Enable/Disable Setuid, Next: Setuid Program Example, Prev: Setting Groups, Up: Users and Groups
|
|
30.8 Enabling and Disabling Setuid Access
|
=========================================
|
|
A typical setuid program does not need its special access all of the
|
time. It’s a good idea to turn off this access when it isn’t needed, so
|
it can’t possibly give unintended access.
|
|
If the system supports the ‘_POSIX_SAVED_IDS’ feature, you can
|
accomplish this with ‘seteuid’. When the game program starts, its real
|
user ID is ‘jdoe’, its effective user ID is ‘games’, and its saved user
|
ID is also ‘games’. The program should record both user ID values once
|
at the beginning, like this:
|
|
user_user_id = getuid ();
|
game_user_id = geteuid ();
|
|
Then it can turn off game file access with
|
|
seteuid (user_user_id);
|
|
and turn it on with
|
|
seteuid (game_user_id);
|
|
Throughout this process, the real user ID remains ‘jdoe’ and the file
|
user ID remains ‘games’, so the program can always set its effective
|
user ID to either one.
|
|
On other systems that don’t support file user IDs, you can turn
|
setuid access on and off by using ‘setreuid’ to swap the real and
|
effective user IDs of the process, as follows:
|
|
setreuid (geteuid (), getuid ());
|
|
This special case is always allowed—it cannot fail.
|
|
Why does this have the effect of toggling the setuid access? Suppose
|
a game program has just started, and its real user ID is ‘jdoe’ while
|
its effective user ID is ‘games’. In this state, the game can write the
|
scores file. If it swaps the two uids, the real becomes ‘games’ and the
|
effective becomes ‘jdoe’; now the program has only ‘jdoe’ access.
|
Another swap brings ‘games’ back to the effective user ID and restores
|
access to the scores file.
|
|
In order to handle both kinds of systems, test for the saved user ID
|
feature with a preprocessor conditional, like this:
|
|
#ifdef _POSIX_SAVED_IDS
|
seteuid (user_user_id);
|
#else
|
setreuid (geteuid (), getuid ());
|
#endif
|
|
|
File: libc.info, Node: Setuid Program Example, Next: Tips for Setuid, Prev: Enable/Disable Setuid, Up: Users and Groups
|
|
30.9 Setuid Program Example
|
===========================
|
|
Here’s an example showing how to set up a program that changes its
|
effective user ID.
|
|
This is part of a game program called ‘caber-toss’ that manipulates a
|
file ‘scores’ that should be writable only by the game program itself.
|
The program assumes that its executable file will be installed with the
|
setuid bit set and owned by the same user as the ‘scores’ file.
|
Typically, a system administrator will set up an account like ‘games’
|
for this purpose.
|
|
The executable file is given mode ‘4755’, so that doing an ‘ls -l’ on
|
it produces output like:
|
|
-rwsr-xr-x 1 games 184422 Jul 30 15:17 caber-toss
|
|
The setuid bit shows up in the file modes as the ‘s’.
|
|
The scores file is given mode ‘644’, and doing an ‘ls -l’ on it
|
shows:
|
|
-rw-r--r-- 1 games 0 Jul 31 15:33 scores
|
|
Here are the parts of the program that show how to set up the changed
|
user ID. This program is conditionalized so that it makes use of the
|
file IDs feature if it is supported, and otherwise uses ‘setreuid’ to
|
swap the effective and real user IDs.
|
|
#include <stdio.h>
|
#include <sys/types.h>
|
#include <unistd.h>
|
#include <stdlib.h>
|
|
|
/* Remember the effective and real UIDs. */
|
|
static uid_t euid, ruid;
|
|
|
/* Restore the effective UID to its original value. */
|
|
void
|
do_setuid (void)
|
{
|
int status;
|
|
#ifdef _POSIX_SAVED_IDS
|
status = seteuid (euid);
|
#else
|
status = setreuid (ruid, euid);
|
#endif
|
if (status < 0) {
|
fprintf (stderr, "Couldn't set uid.\n");
|
exit (status);
|
}
|
}
|
|
|
/* Set the effective UID to the real UID. */
|
|
void
|
undo_setuid (void)
|
{
|
int status;
|
|
#ifdef _POSIX_SAVED_IDS
|
status = seteuid (ruid);
|
#else
|
status = setreuid (euid, ruid);
|
#endif
|
if (status < 0) {
|
fprintf (stderr, "Couldn't set uid.\n");
|
exit (status);
|
}
|
}
|
|
/* Main program. */
|
|
int
|
main (void)
|
{
|
/* Remember the real and effective user IDs. */
|
ruid = getuid ();
|
euid = geteuid ();
|
undo_setuid ();
|
|
/* Do the game and record the score. */
|
…
|
}
|
|
Notice how the first thing the ‘main’ function does is to set the
|
effective user ID back to the real user ID. This is so that any other
|
file accesses that are performed while the user is playing the game use
|
the real user ID for determining permissions. Only when the program
|
needs to open the scores file does it switch back to the file user ID,
|
like this:
|
|
/* Record the score. */
|
|
int
|
record_score (int score)
|
{
|
FILE *stream;
|
char *myname;
|
|
/* Open the scores file. */
|
do_setuid ();
|
stream = fopen (SCORES_FILE, "a");
|
undo_setuid ();
|
|
/* Write the score to the file. */
|
if (stream)
|
{
|
myname = cuserid (NULL);
|
if (score < 0)
|
fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
|
else
|
fprintf (stream, "%10s: %d feet.\n", myname, score);
|
fclose (stream);
|
return 0;
|
}
|
else
|
return -1;
|
}
|
|
|
File: libc.info, Node: Tips for Setuid, Next: Who Logged In, Prev: Setuid Program Example, Up: Users and Groups
|
|
30.10 Tips for Writing Setuid Programs
|
======================================
|
|
It is easy for setuid programs to give the user access that isn’t
|
intended—in fact, if you want to avoid this, you need to be careful.
|
Here are some guidelines for preventing unintended access and minimizing
|
its consequences when it does occur:
|
|
• Don’t have ‘setuid’ programs with privileged user IDs such as
|
‘root’ unless it is absolutely necessary. If the resource is
|
specific to your particular program, it’s better to define a new,
|
nonprivileged user ID or group ID just to manage that resource.
|
It’s better if you can write your program to use a special group
|
than a special user.
|
|
• Be cautious about using the ‘exec’ functions in combination with
|
changing the effective user ID. Don’t let users of your program
|
execute arbitrary programs under a changed user ID. Executing a
|
shell is especially bad news. Less obviously, the ‘execlp’ and
|
‘execvp’ functions are a potential risk (since the program they
|
execute depends on the user’s ‘PATH’ environment variable).
|
|
If you must ‘exec’ another program under a changed ID, specify an
|
absolute file name (*note File Name Resolution::) for the
|
executable, and make sure that the protections on that executable
|
and _all_ containing directories are such that ordinary users
|
cannot replace it with some other program.
|
|
You should also check the arguments passed to the program to make
|
sure they do not have unexpected effects. Likewise, you should
|
examine the environment variables. Decide which arguments and
|
variables are safe, and reject all others.
|
|
You should never use ‘system’ in a privileged program, because it
|
invokes a shell.
|
|
• Only use the user ID controlling the resource in the part of the
|
program that actually uses that resource. When you’re finished
|
with it, restore the effective user ID back to the actual user’s
|
user ID. *Note Enable/Disable Setuid::.
|
|
• If the ‘setuid’ part of your program needs to access other files
|
besides the controlled resource, it should verify that the real
|
user would ordinarily have permission to access those files. You
|
can use the ‘access’ function (*note Access Permission::) to check
|
this; it uses the real user and group IDs, rather than the
|
effective IDs.
|
|
|
File: libc.info, Node: Who Logged In, Next: User Accounting Database, Prev: Tips for Setuid, Up: Users and Groups
|
|
30.11 Identifying Who Logged In
|
===============================
|
|
You can use the functions listed in this section to determine the login
|
name of the user who is running a process, and the name of the user who
|
logged in the current session. See also the function ‘getuid’ and
|
friends (*note Reading Persona::). How this information is collected by
|
the system and how to control/add/remove information from the background
|
storage is described in *note User Accounting Database::.
|
|
The ‘getlogin’ function is declared in ‘unistd.h’, while ‘cuserid’
|
and ‘L_cuserid’ are declared in ‘stdio.h’.
|
|
-- Function: char * getlogin (void)
|
Preliminary: | MT-Unsafe race:getlogin race:utent sig:ALRM timer
|
locale | AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock
|
fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘getlogin’ function returns a pointer to a string containing
|
the name of the user logged in on the controlling terminal of the
|
process, or a null pointer if this information cannot be
|
determined. The string is statically allocated and might be
|
overwritten on subsequent calls to this function or to ‘cuserid’.
|
|
-- Function: char * cuserid (char *STRING)
|
Preliminary: | MT-Unsafe race:cuserid/!string locale | AS-Unsafe
|
dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note
|
POSIX Safety Concepts::.
|
|
The ‘cuserid’ function returns a pointer to a string containing a
|
user name associated with the effective ID of the process. If
|
STRING is not a null pointer, it should be an array that can hold
|
at least ‘L_cuserid’ characters; the string is returned in this
|
array. Otherwise, a pointer to a string in a static area is
|
returned. This string is statically allocated and might be
|
overwritten on subsequent calls to this function or to ‘getlogin’.
|
|
The use of this function is deprecated since it is marked to be
|
withdrawn in XPG4.2 and has already been removed from newer
|
revisions of POSIX.1.
|
|
-- Macro: int L_cuserid
|
An integer constant that indicates how long an array you might need
|
to store a user name.
|
|
These functions let your program identify positively the user who is
|
running or the user who logged in this session. (These can differ when
|
setuid programs are involved; see *note Process Persona::.) The user
|
cannot do anything to fool these functions.
|
|
For most purposes, it is more useful to use the environment variable
|
‘LOGNAME’ to find out who the user is. This is more flexible precisely
|
because the user can set ‘LOGNAME’ arbitrarily. *Note Standard
|
Environment::.
|
|
|
File: libc.info, Node: User Accounting Database, Next: User Database, Prev: Who Logged In, Up: Users and Groups
|
|
30.12 The User Accounting Database
|
==================================
|
|
Most Unix-like operating systems keep track of logged in users by
|
maintaining a user accounting database. This user accounting database
|
stores for each terminal, who has logged on, at what time, the process
|
ID of the user’s login shell, etc., etc., but also stores information
|
about the run level of the system, the time of the last system reboot,
|
and possibly more.
|
|
The user accounting database typically lives in ‘/etc/utmp’,
|
‘/var/adm/utmp’ or ‘/var/run/utmp’. However, these files should *never*
|
be accessed directly. For reading information from and writing
|
information to the user accounting database, the functions described in
|
this section should be used.
|
|
* Menu:
|
|
* Manipulating the Database:: Scanning and modifying the user
|
accounting database.
|
* XPG Functions:: A standardized way for doing the same thing.
|
* Logging In and Out:: Functions from BSD that modify the user
|
accounting database.
|
|
|
File: libc.info, Node: Manipulating the Database, Next: XPG Functions, Up: User Accounting Database
|
|
30.12.1 Manipulating the User Accounting Database
|
-------------------------------------------------
|
|
These functions and the corresponding data structures are declared in
|
the header file ‘utmp.h’.
|
|
-- Data Type: struct exit_status
|
The ‘exit_status’ data structure is used to hold information about
|
the exit status of processes marked as ‘DEAD_PROCESS’ in the user
|
accounting database.
|
|
‘short int e_termination’
|
The exit status of the process.
|
|
‘short int e_exit’
|
The exit status of the process.
|
|
-- Data Type: struct utmp
|
The ‘utmp’ data structure is used to hold information about entries
|
in the user accounting database. On GNU systems it has the
|
following members:
|
|
‘short int ut_type’
|
Specifies the type of login; one of ‘EMPTY’, ‘RUN_LVL’,
|
‘BOOT_TIME’, ‘OLD_TIME’, ‘NEW_TIME’, ‘INIT_PROCESS’,
|
‘LOGIN_PROCESS’, ‘USER_PROCESS’, ‘DEAD_PROCESS’ or
|
‘ACCOUNTING’.
|
|
‘pid_t ut_pid’
|
The process ID number of the login process.
|
|
‘char ut_line[]’
|
The device name of the tty (without ‘/dev/’).
|
|
‘char ut_id[]’
|
The inittab ID of the process.
|
|
‘char ut_user[]’
|
The user’s login name.
|
|
‘char ut_host[]’
|
The name of the host from which the user logged in.
|
|
‘struct exit_status ut_exit’
|
The exit status of a process marked as ‘DEAD_PROCESS’.
|
|
‘long ut_session’
|
The Session ID, used for windowing.
|
|
‘struct timeval ut_tv’
|
Time the entry was made. For entries of type ‘OLD_TIME’ this
|
is the time when the system clock changed, and for entries of
|
type ‘NEW_TIME’ this is the time the system clock was set to.
|
|
‘int32_t ut_addr_v6[4]’
|
The Internet address of a remote host.
|
|
The ‘ut_type’, ‘ut_pid’, ‘ut_id’, ‘ut_tv’, and ‘ut_host’ fields are
|
not available on all systems. Portable applications therefore should be
|
prepared for these situations. To help doing this the ‘utmp.h’ header
|
provides macros ‘_HAVE_UT_TYPE’, ‘_HAVE_UT_PID’, ‘_HAVE_UT_ID’,
|
‘_HAVE_UT_TV’, and ‘_HAVE_UT_HOST’ if the respective field is available.
|
The programmer can handle the situations by using ‘#ifdef’ in the
|
program code.
|
|
The following macros are defined for use as values for the ‘ut_type’
|
member of the ‘utmp’ structure. The values are integer constants.
|
|
‘EMPTY’
|
This macro is used to indicate that the entry contains no valid
|
user accounting information.
|
|
‘RUN_LVL’
|
This macro is used to identify the systems runlevel.
|
|
‘BOOT_TIME’
|
This macro is used to identify the time of system boot.
|
|
‘OLD_TIME’
|
This macro is used to identify the time when the system clock
|
changed.
|
|
‘NEW_TIME’
|
This macro is used to identify the time after the system changed.
|
|
‘INIT_PROCESS’
|
This macro is used to identify a process spawned by the init
|
process.
|
|
‘LOGIN_PROCESS’
|
This macro is used to identify the session leader of a logged in
|
user.
|
|
‘USER_PROCESS’
|
This macro is used to identify a user process.
|
|
‘DEAD_PROCESS’
|
This macro is used to identify a terminated process.
|
|
‘ACCOUNTING’
|
???
|
|
The size of the ‘ut_line’, ‘ut_id’, ‘ut_user’ and ‘ut_host’ arrays
|
can be found using the ‘sizeof’ operator.
|
|
Many older systems have, instead of an ‘ut_tv’ member, an ‘ut_time’
|
member, usually of type ‘time_t’, for representing the time associated
|
with the entry. Therefore, for backwards compatibility only, ‘utmp.h’
|
defines ‘ut_time’ as an alias for ‘ut_tv.tv_sec’.
|
|
-- Function: void setutent (void)
|
Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock | AC-Unsafe
|
lock fd | *Note POSIX Safety Concepts::.
|
|
This function opens the user accounting database to begin scanning
|
it. You can then call ‘getutent’, ‘getutid’ or ‘getutline’ to read
|
entries and ‘pututline’ to write entries.
|
|
If the database is already open, it resets the input to the
|
beginning of the database.
|
|
-- Function: struct utmp * getutent (void)
|
Preliminary: | MT-Unsafe init race:utent race:utentbuf sig:ALRM
|
timer | AS-Unsafe heap lock | AC-Unsafe lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
The ‘getutent’ function reads the next entry from the user
|
accounting database. It returns a pointer to the entry, which is
|
statically allocated and may be overwritten by subsequent calls to
|
‘getutent’. You must copy the contents of the structure if you
|
wish to save the information or you can use the ‘getutent_r’
|
function which stores the data in a user-provided buffer.
|
|
A null pointer is returned in case no further entry is available.
|
|
-- Function: void endutent (void)
|
Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock | AC-Unsafe
|
lock fd | *Note POSIX Safety Concepts::.
|
|
This function closes the user accounting database.
|
|
-- Function: struct utmp * getutid (const struct utmp *ID)
|
Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | AS-Unsafe
|
lock heap | AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
|
|
This function searches forward from the current point in the
|
database for an entry that matches ID. If the ‘ut_type’ member of
|
the ID structure is one of ‘RUN_LVL’, ‘BOOT_TIME’, ‘OLD_TIME’ or
|
‘NEW_TIME’ the entries match if the ‘ut_type’ members are
|
identical. If the ‘ut_type’ member of the ID structure is
|
‘INIT_PROCESS’, ‘LOGIN_PROCESS’, ‘USER_PROCESS’ or ‘DEAD_PROCESS’,
|
the entries match if the ‘ut_type’ member of the entry read from
|
the database is one of these four, and the ‘ut_id’ members match.
|
However if the ‘ut_id’ member of either the ID structure or the
|
entry read from the database is empty it checks if the ‘ut_line’
|
members match instead. If a matching entry is found, ‘getutid’
|
returns a pointer to the entry, which is statically allocated, and
|
may be overwritten by a subsequent call to ‘getutent’, ‘getutid’ or
|
‘getutline’. You must copy the contents of the structure if you
|
wish to save the information.
|
|
A null pointer is returned in case the end of the database is
|
reached without a match.
|
|
The ‘getutid’ function may cache the last read entry. Therefore,
|
if you are using ‘getutid’ to search for multiple occurrences, it
|
is necessary to zero out the static data after each call.
|
Otherwise ‘getutid’ could just return a pointer to the same entry
|
over and over again.
|
|
-- Function: struct utmp * getutline (const struct utmp *LINE)
|
Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | AS-Unsafe
|
heap lock | AC-Unsafe lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function searches forward from the current point in the
|
database until it finds an entry whose ‘ut_type’ value is
|
‘LOGIN_PROCESS’ or ‘USER_PROCESS’, and whose ‘ut_line’ member
|
matches the ‘ut_line’ member of the LINE structure. If it finds
|
such an entry, it returns a pointer to the entry which is
|
statically allocated, and may be overwritten by a subsequent call
|
to ‘getutent’, ‘getutid’ or ‘getutline’. You must copy the
|
contents of the structure if you wish to save the information.
|
|
A null pointer is returned in case the end of the database is
|
reached without a match.
|
|
The ‘getutline’ function may cache the last read entry. Therefore
|
if you are using ‘getutline’ to search for multiple occurrences, it
|
is necessary to zero out the static data after each call.
|
Otherwise ‘getutline’ could just return a pointer to the same entry
|
over and over again.
|
|
-- Function: struct utmp * pututline (const struct utmp *UTMP)
|
Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock
|
| AC-Unsafe lock fd | *Note POSIX Safety Concepts::.
|
|
The ‘pututline’ function inserts the entry ‘*UTMP’ at the
|
appropriate place in the user accounting database. If it finds
|
that it is not already at the correct place in the database, it
|
uses ‘getutid’ to search for the position to insert the entry,
|
however this will not modify the static structure returned by
|
‘getutent’, ‘getutid’ and ‘getutline’. If this search fails, the
|
entry is appended to the database.
|
|
The ‘pututline’ function returns a pointer to a copy of the entry
|
inserted in the user accounting database, or a null pointer if the
|
entry could not be added. The following ‘errno’ error conditions
|
are defined for this function:
|
|
‘EPERM’
|
The process does not have the appropriate privileges; you
|
cannot modify the user accounting database.
|
|
All the ‘get*’ functions mentioned before store the information they
|
return in a static buffer. This can be a problem in multi-threaded
|
programs since the data returned for the request is overwritten by the
|
return value data in another thread. Therefore the GNU C Library
|
provides as extensions three more functions which return the data in a
|
user-provided buffer.
|
|
-- Function: int getutent_r (struct utmp *BUFFER, struct utmp **RESULT)
|
Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock
|
| AC-Unsafe lock fd | *Note POSIX Safety Concepts::.
|
|
The ‘getutent_r’ is equivalent to the ‘getutent’ function. It
|
returns the next entry from the database. But instead of storing
|
the information in a static buffer it stores it in the buffer
|
pointed to by the parameter BUFFER.
|
|
If the call was successful, the function returns ‘0’ and the
|
pointer variable pointed to by the parameter RESULT contains a
|
pointer to the buffer which contains the result (this is most
|
probably the same value as BUFFER). If something went wrong during
|
the execution of ‘getutent_r’ the function returns ‘-1’.
|
|
This function is a GNU extension.
|
|
-- Function: int getutid_r (const struct utmp *ID, struct utmp *BUFFER,
|
struct utmp **RESULT)
|
Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock
|
| AC-Unsafe lock fd | *Note POSIX Safety Concepts::.
|
|
This function retrieves just like ‘getutid’ the next entry matching
|
the information stored in ID. But the result is stored in the
|
buffer pointed to by the parameter BUFFER.
|
|
If successful the function returns ‘0’ and the pointer variable
|
pointed to by the parameter RESULT contains a pointer to the buffer
|
with the result (probably the same as RESULT. If not successful
|
the function return ‘-1’.
|
|
This function is a GNU extension.
|
|
-- Function: int getutline_r (const struct utmp *LINE, struct utmp
|
*BUFFER, struct utmp **RESULT)
|
Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock
|
| AC-Unsafe lock fd | *Note POSIX Safety Concepts::.
|
|
This function retrieves just like ‘getutline’ the next entry
|
matching the information stored in LINE. But the result is stored
|
in the buffer pointed to by the parameter BUFFER.
|
|
If successful the function returns ‘0’ and the pointer variable
|
pointed to by the parameter RESULT contains a pointer to the buffer
|
with the result (probably the same as RESULT. If not successful
|
the function return ‘-1’.
|
|
This function is a GNU extension.
|
|
In addition to the user accounting database, most systems keep a
|
number of similar databases. For example most systems keep a log file
|
with all previous logins (usually in ‘/etc/wtmp’ or ‘/var/log/wtmp’).
|
|
For specifying which database to examine, the following function
|
should be used.
|
|
-- Function: int utmpname (const char *FILE)
|
Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock heap |
|
AC-Unsafe lock mem | *Note POSIX Safety Concepts::.
|
|
The ‘utmpname’ function changes the name of the database to be
|
examined to FILE, and closes any previously opened database. By
|
default ‘getutent’, ‘getutid’, ‘getutline’ and ‘pututline’ read
|
from and write to the user accounting database.
|
|
The following macros are defined for use as the FILE argument:
|
|
-- Macro: char * _PATH_UTMP
|
This macro is used to specify the user accounting database.
|
|
-- Macro: char * _PATH_WTMP
|
This macro is used to specify the user accounting log file.
|
|
The ‘utmpname’ function returns a value of ‘0’ if the new name was
|
successfully stored, and a value of ‘-1’ to indicate an error.
|
Note that ‘utmpname’ does not try to open the database, and that
|
therefore the return value does not say anything about whether the
|
database can be successfully opened.
|
|
Specially for maintaining log-like databases the GNU C Library
|
provides the following function:
|
|
-- Function: void updwtmp (const char *WTMP_FILE, const struct utmp
|
*UTMP)
|
Preliminary: | MT-Unsafe sig:ALRM timer | AS-Unsafe | AC-Unsafe fd
|
| *Note POSIX Safety Concepts::.
|
|
The ‘updwtmp’ function appends the entry *UTMP to the database
|
specified by WTMP_FILE. For possible values for the WTMP_FILE
|
argument see the ‘utmpname’ function.
|
|
*Portability Note:* Although many operating systems provide a subset
|
of these functions, they are not standardized. There are often subtle
|
differences in the return types, and there are considerable differences
|
between the various definitions of ‘struct utmp’. When programming for
|
the GNU C Library, it is probably best to stick with the functions
|
described in this section. If however, you want your program to be
|
portable, consider using the XPG functions described in *note XPG
|
Functions::, or take a look at the BSD compatible functions in *note
|
Logging In and Out::.
|
|
|
File: libc.info, Node: XPG Functions, Next: Logging In and Out, Prev: Manipulating the Database, Up: User Accounting Database
|
|
30.12.2 XPG User Accounting Database Functions
|
----------------------------------------------
|
|
These functions, described in the X/Open Portability Guide, are declared
|
in the header file ‘utmpx.h’.
|
|
-- Data Type: struct utmpx
|
The ‘utmpx’ data structure contains at least the following members:
|
|
‘short int ut_type’
|
Specifies the type of login; one of ‘EMPTY’, ‘RUN_LVL’,
|
‘BOOT_TIME’, ‘OLD_TIME’, ‘NEW_TIME’, ‘INIT_PROCESS’,
|
‘LOGIN_PROCESS’, ‘USER_PROCESS’ or ‘DEAD_PROCESS’.
|
|
‘pid_t ut_pid’
|
The process ID number of the login process.
|
|
‘char ut_line[]’
|
The device name of the tty (without ‘/dev/’).
|
|
‘char ut_id[]’
|
The inittab ID of the process.
|
|
‘char ut_user[]’
|
The user’s login name.
|
|
‘struct timeval ut_tv’
|
Time the entry was made. For entries of type ‘OLD_TIME’ this
|
is the time when the system clock changed, and for entries of
|
type ‘NEW_TIME’ this is the time the system clock was set to.
|
In the GNU C Library, ‘struct utmpx’ is identical to ‘struct utmp’
|
except for the fact that including ‘utmpx.h’ does not make visible
|
the declaration of ‘struct exit_status’.
|
|
The following macros are defined for use as values for the ‘ut_type’
|
member of the ‘utmpx’ structure. The values are integer constants and
|
are, in the GNU C Library, identical to the definitions in ‘utmp.h’.
|
|
‘EMPTY’
|
This macro is used to indicate that the entry contains no valid
|
user accounting information.
|
|
‘RUN_LVL’
|
This macro is used to identify the systems runlevel.
|
|
‘BOOT_TIME’
|
This macro is used to identify the time of system boot.
|
|
‘OLD_TIME’
|
This macro is used to identify the time when the system clock
|
changed.
|
|
‘NEW_TIME’
|
This macro is used to identify the time after the system changed.
|
|
‘INIT_PROCESS’
|
This macro is used to identify a process spawned by the init
|
process.
|
|
‘LOGIN_PROCESS’
|
This macro is used to identify the session leader of a logged in
|
user.
|
|
‘USER_PROCESS’
|
This macro is used to identify a user process.
|
|
‘DEAD_PROCESS’
|
This macro is used to identify a terminated process.
|
|
The size of the ‘ut_line’, ‘ut_id’ and ‘ut_user’ arrays can be found
|
using the ‘sizeof’ operator.
|
|
-- Function: void setutxent (void)
|
Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock | AC-Unsafe
|
lock fd | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘setutent’. In the GNU C Library it is
|
simply an alias for ‘setutent’.
|
|
-- Function: struct utmpx * getutxent (void)
|
Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | AS-Unsafe
|
heap lock | AC-Unsafe lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘getutxent’ function is similar to ‘getutent’, but returns a
|
pointer to a ‘struct utmpx’ instead of ‘struct utmp’. In the GNU C
|
Library it simply is an alias for ‘getutent’.
|
|
-- Function: void endutxent (void)
|
Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock | AC-Unsafe
|
lock | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘endutent’. In the GNU C Library it is
|
simply an alias for ‘endutent’.
|
|
-- Function: struct utmpx * getutxid (const struct utmpx *ID)
|
Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | AS-Unsafe
|
lock heap | AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘getutid’, but uses ‘struct utmpx’
|
instead of ‘struct utmp’. In the GNU C Library it is simply an
|
alias for ‘getutid’.
|
|
-- Function: struct utmpx * getutxline (const struct utmpx *LINE)
|
Preliminary: | MT-Unsafe init race:utent sig:ALRM timer | AS-Unsafe
|
heap lock | AC-Unsafe lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘getutid’, but uses ‘struct utmpx’
|
instead of ‘struct utmp’. In the GNU C Library it is simply an
|
alias for ‘getutline’.
|
|
-- Function: struct utmpx * pututxline (const struct utmpx *UTMP)
|
Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock
|
| AC-Unsafe lock fd | *Note POSIX Safety Concepts::.
|
|
The ‘pututxline’ function is functionally identical to ‘pututline’,
|
but uses ‘struct utmpx’ instead of ‘struct utmp’. In the GNU C
|
Library, ‘pututxline’ is simply an alias for ‘pututline’.
|
|
-- Function: int utmpxname (const char *FILE)
|
Preliminary: | MT-Unsafe race:utent | AS-Unsafe lock heap |
|
AC-Unsafe lock mem | *Note POSIX Safety Concepts::.
|
|
The ‘utmpxname’ function is functionally identical to ‘utmpname’.
|
In the GNU C Library, ‘utmpxname’ is simply an alias for
|
‘utmpname’.
|
|
You can translate between a traditional ‘struct utmp’ and an XPG
|
‘struct utmpx’ with the following functions. In the GNU C Library,
|
these functions are merely copies, since the two structures are
|
identical.
|
|
-- Function: int getutmp (const struct utmpx *UTMPX, struct utmp *UTMP)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘getutmp’ copies the information, insofar as the structures are
|
compatible, from UTMPX to UTMP.
|
|
-- Function: int getutmpx (const struct utmp *UTMP, struct utmpx
|
*UTMPX)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘getutmpx’ copies the information, insofar as the structures are
|
compatible, from UTMP to UTMPX.
|
|
|
File: libc.info, Node: Logging In and Out, Prev: XPG Functions, Up: User Accounting Database
|
|
30.12.3 Logging In and Out
|
--------------------------
|
|
These functions, derived from BSD, are available in the separate
|
‘libutil’ library, and declared in ‘utmp.h’.
|
|
Note that the ‘ut_user’ member of ‘struct utmp’ is called ‘ut_name’
|
in BSD. Therefore, ‘ut_name’ is defined as an alias for ‘ut_user’ in
|
‘utmp.h’.
|
|
-- Function: int login_tty (int FILEDES)
|
Preliminary: | MT-Unsafe race:ttyname | AS-Unsafe heap lock |
|
AC-Unsafe lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function makes FILEDES the controlling terminal of the current
|
process, redirects standard input, standard output and standard
|
error output to this terminal, and closes FILEDES.
|
|
This function returns ‘0’ on successful completion, and ‘-1’ on
|
error.
|
|
-- Function: void login (const struct utmp *ENTRY)
|
Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock
|
heap | AC-Unsafe lock corrupt fd mem | *Note POSIX Safety
|
Concepts::.
|
|
The ‘login’ functions inserts an entry into the user accounting
|
database. The ‘ut_line’ member is set to the name of the terminal
|
on standard input. If standard input is not a terminal ‘login’
|
uses standard output or standard error output to determine the name
|
of the terminal. If ‘struct utmp’ has a ‘ut_type’ member, ‘login’
|
sets it to ‘USER_PROCESS’, and if there is an ‘ut_pid’ member, it
|
will be set to the process ID of the current process. The
|
remaining entries are copied from ENTRY.
|
|
A copy of the entry is written to the user accounting log file.
|
|
-- Function: int logout (const char *UT_LINE)
|
Preliminary: | MT-Unsafe race:utent sig:ALRM timer | AS-Unsafe lock
|
heap | AC-Unsafe lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function modifies the user accounting database to indicate
|
that the user on UT_LINE has logged out.
|
|
The ‘logout’ function returns ‘1’ if the entry was successfully
|
written to the database, or ‘0’ on error.
|
|
-- Function: void logwtmp (const char *UT_LINE, const char *UT_NAME,
|
const char *UT_HOST)
|
Preliminary: | MT-Unsafe sig:ALRM timer | AS-Unsafe | AC-Unsafe fd
|
| *Note POSIX Safety Concepts::.
|
|
The ‘logwtmp’ function appends an entry to the user accounting log
|
file, for the current time and the information provided in the
|
UT_LINE, UT_NAME and UT_HOST arguments.
|
|
*Portability Note:* The BSD ‘struct utmp’ only has the ‘ut_line’,
|
‘ut_name’, ‘ut_host’ and ‘ut_time’ members. Older systems do not even
|
have the ‘ut_host’ member.
|
|
|
File: libc.info, Node: User Database, Next: Group Database, Prev: User Accounting Database, Up: Users and Groups
|
|
30.13 User Database
|
===================
|
|
This section describes how to search and scan the database of registered
|
users. The database itself is kept in the file ‘/etc/passwd’ on most
|
systems, but on some systems a special network server gives access to
|
it.
|
|
* Menu:
|
|
* User Data Structure:: What each user record contains.
|
* Lookup User:: How to look for a particular user.
|
* Scanning All Users:: Scanning the list of all users, one by one.
|
* Writing a User Entry:: How a program can rewrite a user’s record.
|
|
|
File: libc.info, Node: User Data Structure, Next: Lookup User, Up: User Database
|
|
30.13.1 The Data Structure that Describes a User
|
------------------------------------------------
|
|
The functions and data structures for accessing the system user database
|
are declared in the header file ‘pwd.h’.
|
|
-- Data Type: struct passwd
|
The ‘passwd’ data structure is used to hold information about
|
entries in the system user data base. It has at least the
|
following members:
|
|
‘char *pw_name’
|
The user’s login name.
|
|
‘char *pw_passwd.’
|
The encrypted password string.
|
|
‘uid_t pw_uid’
|
The user ID number.
|
|
‘gid_t pw_gid’
|
The user’s default group ID number.
|
|
‘char *pw_gecos’
|
A string typically containing the user’s real name, and
|
possibly other information such as a phone number.
|
|
‘char *pw_dir’
|
The user’s home directory, or initial working directory. This
|
might be a null pointer, in which case the interpretation is
|
system-dependent.
|
|
‘char *pw_shell’
|
The user’s default shell, or the initial program run when the
|
user logs in. This might be a null pointer, indicating that
|
the system default should be used.
|
|
|
File: libc.info, Node: Lookup User, Next: Scanning All Users, Prev: User Data Structure, Up: User Database
|
|
30.13.2 Looking Up One User
|
---------------------------
|
|
You can search the system user database for information about a specific
|
user using ‘getpwuid’ or ‘getpwnam’. These functions are declared in
|
‘pwd.h’.
|
|
-- Function: struct passwd * getpwuid (uid_t UID)
|
Preliminary: | MT-Unsafe race:pwuid locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function returns a pointer to a statically-allocated structure
|
containing information about the user whose user ID is UID. This
|
structure may be overwritten on subsequent calls to ‘getpwuid’.
|
|
A null pointer value indicates there is no user in the data base
|
with user ID UID.
|
|
-- Function: int getpwuid_r (uid_t UID, struct passwd *RESULT_BUF, char
|
*BUFFER, size_t BUFLEN, struct passwd **RESULT)
|
Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘getpwuid’ in that it returns
|
information about the user whose user ID is UID. However, it fills
|
the user supplied structure pointed to by RESULT_BUF with the
|
information instead of using a static buffer. The first BUFLEN
|
bytes of the additional buffer pointed to by BUFFER are used to
|
contain additional information, normally strings which are pointed
|
to by the elements of the result structure.
|
|
If a user with ID UID is found, the pointer returned in RESULT
|
points to the record which contains the wanted data (i.e., RESULT
|
contains the value RESULT_BUF). If no user is found or if an error
|
occurred, the pointer returned in RESULT is a null pointer. The
|
function returns zero or an error code. If the buffer BUFFER is
|
too small to contain all the needed information, the error code
|
‘ERANGE’ is returned and ERRNO is set to ‘ERANGE’.
|
|
-- Function: struct passwd * getpwnam (const char *NAME)
|
Preliminary: | MT-Unsafe race:pwnam locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function returns a pointer to a statically-allocated structure
|
containing information about the user whose user name is NAME.
|
This structure may be overwritten on subsequent calls to
|
‘getpwnam’.
|
|
A null pointer return indicates there is no user named NAME.
|
|
-- Function: int getpwnam_r (const char *NAME, struct passwd
|
*RESULT_BUF, char *BUFFER, size_t BUFLEN, struct passwd
|
**RESULT)
|
Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘getpwnam’ in that is returns
|
information about the user whose user name is NAME. However, like
|
‘getpwuid_r’, it fills the user supplied buffers in RESULT_BUF and
|
BUFFER with the information instead of using a static buffer.
|
|
The return values are the same as for ‘getpwuid_r’.
|
|
|
File: libc.info, Node: Scanning All Users, Next: Writing a User Entry, Prev: Lookup User, Up: User Database
|
|
30.13.3 Scanning the List of All Users
|
--------------------------------------
|
|
This section explains how a program can read the list of all users in
|
the system, one user at a time. The functions described here are
|
declared in ‘pwd.h’.
|
|
You can use the ‘fgetpwent’ function to read user entries from a
|
particular file.
|
|
-- Function: struct passwd * fgetpwent (FILE *STREAM)
|
Preliminary: | MT-Unsafe race:fpwent | AS-Unsafe corrupt lock |
|
AC-Unsafe corrupt lock | *Note POSIX Safety Concepts::.
|
|
This function reads the next user entry from STREAM and returns a
|
pointer to the entry. The structure is statically allocated and is
|
rewritten on subsequent calls to ‘fgetpwent’. You must copy the
|
contents of the structure if you wish to save the information.
|
|
The stream must correspond to a file in the same format as the
|
standard password database file.
|
|
-- Function: int fgetpwent_r (FILE *STREAM, struct passwd *RESULT_BUF,
|
char *BUFFER, size_t BUFLEN, struct passwd **RESULT)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘fgetpwent’ in that it reads the next
|
user entry from STREAM. But the result is returned in the
|
structure pointed to by RESULT_BUF. The first BUFLEN bytes of the
|
additional buffer pointed to by BUFFER are used to contain
|
additional information, normally strings which are pointed to by
|
the elements of the result structure.
|
|
The stream must correspond to a file in the same format as the
|
standard password database file.
|
|
If the function returns zero RESULT points to the structure with
|
the wanted data (normally this is in RESULT_BUF). If errors
|
occurred the return value is nonzero and RESULT contains a null
|
pointer.
|
|
The way to scan all the entries in the user database is with
|
‘setpwent’, ‘getpwent’, and ‘endpwent’.
|
|
-- Function: void setpwent (void)
|
Preliminary: | MT-Unsafe race:pwent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function initializes a stream which ‘getpwent’ and
|
‘getpwent_r’ use to read the user database.
|
|
-- Function: struct passwd * getpwent (void)
|
Preliminary: | MT-Unsafe race:pwent race:pwentbuf locale |
|
AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
|
*Note POSIX Safety Concepts::.
|
|
The ‘getpwent’ function reads the next entry from the stream
|
initialized by ‘setpwent’. It returns a pointer to the entry. The
|
structure is statically allocated and is rewritten on subsequent
|
calls to ‘getpwent’. You must copy the contents of the structure
|
if you wish to save the information.
|
|
A null pointer is returned when no more entries are available.
|
|
-- Function: int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER,
|
size_t BUFLEN, struct passwd **RESULT)
|
Preliminary: | MT-Unsafe race:pwent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function is similar to ‘getpwent’ in that it returns the next
|
entry from the stream initialized by ‘setpwent’. Like
|
‘fgetpwent_r’, it uses the user-supplied buffers in RESULT_BUF and
|
BUFFER to return the information requested.
|
|
The return values are the same as for ‘fgetpwent_r’.
|
|
-- Function: void endpwent (void)
|
Preliminary: | MT-Unsafe race:pwent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function closes the internal stream used by ‘getpwent’ or
|
‘getpwent_r’.
|
|
|
File: libc.info, Node: Writing a User Entry, Prev: Scanning All Users, Up: User Database
|
|
30.13.4 Writing a User Entry
|
----------------------------
|
|
-- Function: int putpwent (const struct passwd *P, FILE *STREAM)
|
Preliminary: | MT-Safe locale | AS-Unsafe corrupt | AC-Unsafe lock
|
corrupt | *Note POSIX Safety Concepts::.
|
|
This function writes the user entry ‘*P’ to the stream STREAM, in
|
the format used for the standard user database file. The return
|
value is zero on success and nonzero on failure.
|
|
This function exists for compatibility with SVID. We recommend that
|
you avoid using it, because it makes sense only on the assumption
|
that the ‘struct passwd’ structure has no members except the
|
standard ones; on a system which merges the traditional Unix data
|
base with other extended information about users, adding an entry
|
using this function would inevitably leave out much of the
|
important information.
|
|
The group and user ID fields are left empty if the group or user
|
name starts with a - or +.
|
|
The function ‘putpwent’ is declared in ‘pwd.h’.
|
|
|
File: libc.info, Node: Group Database, Next: Database Example, Prev: User Database, Up: Users and Groups
|
|
30.14 Group Database
|
====================
|
|
This section describes how to search and scan the database of registered
|
groups. The database itself is kept in the file ‘/etc/group’ on most
|
systems, but on some systems a special network service provides access
|
to it.
|
|
* Menu:
|
|
* Group Data Structure:: What each group record contains.
|
* Lookup Group:: How to look for a particular group.
|
* Scanning All Groups:: Scanning the list of all groups.
|
|
|
File: libc.info, Node: Group Data Structure, Next: Lookup Group, Up: Group Database
|
|
30.14.1 The Data Structure for a Group
|
--------------------------------------
|
|
The functions and data structures for accessing the system group
|
database are declared in the header file ‘grp.h’.
|
|
-- Data Type: struct group
|
The ‘group’ structure is used to hold information about an entry in
|
the system group database. It has at least the following members:
|
|
‘char *gr_name’
|
The name of the group.
|
|
‘gid_t gr_gid’
|
The group ID of the group.
|
|
‘char **gr_mem’
|
A vector of pointers to the names of users in the group. Each
|
user name is a null-terminated string, and the vector itself
|
is terminated by a null pointer.
|
|
|
File: libc.info, Node: Lookup Group, Next: Scanning All Groups, Prev: Group Data Structure, Up: Group Database
|
|
30.14.2 Looking Up One Group
|
----------------------------
|
|
You can search the group database for information about a specific group
|
using ‘getgrgid’ or ‘getgrnam’. These functions are declared in
|
‘grp.h’.
|
|
-- Function: struct group * getgrgid (gid_t GID)
|
Preliminary: | MT-Unsafe race:grgid locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function returns a pointer to a statically-allocated structure
|
containing information about the group whose group ID is GID. This
|
structure may be overwritten by subsequent calls to ‘getgrgid’.
|
|
A null pointer indicates there is no group with ID GID.
|
|
-- Function: int getgrgid_r (gid_t GID, struct group *RESULT_BUF, char
|
*BUFFER, size_t BUFLEN, struct group **RESULT)
|
Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘getgrgid’ in that it returns
|
information about the group whose group ID is GID. However, it
|
fills the user supplied structure pointed to by RESULT_BUF with the
|
information instead of using a static buffer. The first BUFLEN
|
bytes of the additional buffer pointed to by BUFFER are used to
|
contain additional information, normally strings which are pointed
|
to by the elements of the result structure.
|
|
If a group with ID GID is found, the pointer returned in RESULT
|
points to the record which contains the wanted data (i.e., RESULT
|
contains the value RESULT_BUF). If no group is found or if an
|
error occurred, the pointer returned in RESULT is a null pointer.
|
The function returns zero or an error code. If the buffer BUFFER
|
is too small to contain all the needed information, the error code
|
‘ERANGE’ is returned and ERRNO is set to ‘ERANGE’.
|
|
-- Function: struct group * getgrnam (const char *NAME)
|
Preliminary: | MT-Unsafe race:grnam locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function returns a pointer to a statically-allocated structure
|
containing information about the group whose group name is NAME.
|
This structure may be overwritten by subsequent calls to
|
‘getgrnam’.
|
|
A null pointer indicates there is no group named NAME.
|
|
-- Function: int getgrnam_r (const char *NAME, struct group
|
*RESULT_BUF, char *BUFFER, size_t BUFLEN, struct group
|
**RESULT)
|
Preliminary: | MT-Safe locale | AS-Unsafe dlopen plugin heap lock |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘getgrnam’ in that is returns
|
information about the group whose group name is NAME. Like
|
‘getgrgid_r’, it uses the user supplied buffers in RESULT_BUF and
|
BUFFER, not a static buffer.
|
|
The return values are the same as for ‘getgrgid_r’ ‘ERANGE’.
|
|
|
File: libc.info, Node: Scanning All Groups, Prev: Lookup Group, Up: Group Database
|
|
30.14.3 Scanning the List of All Groups
|
---------------------------------------
|
|
This section explains how a program can read the list of all groups in
|
the system, one group at a time. The functions described here are
|
declared in ‘grp.h’.
|
|
You can use the ‘fgetgrent’ function to read group entries from a
|
particular file.
|
|
-- Function: struct group * fgetgrent (FILE *STREAM)
|
Preliminary: | MT-Unsafe race:fgrent | AS-Unsafe corrupt lock |
|
AC-Unsafe corrupt lock | *Note POSIX Safety Concepts::.
|
|
The ‘fgetgrent’ function reads the next entry from STREAM. It
|
returns a pointer to the entry. The structure is statically
|
allocated and is overwritten on subsequent calls to ‘fgetgrent’.
|
You must copy the contents of the structure if you wish to save the
|
information.
|
|
The stream must correspond to a file in the same format as the
|
standard group database file.
|
|
-- Function: int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF,
|
char *BUFFER, size_t BUFLEN, struct group **RESULT)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
|
| *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘fgetgrent’ in that it reads the next
|
user entry from STREAM. But the result is returned in the
|
structure pointed to by RESULT_BUF. The first BUFLEN bytes of the
|
additional buffer pointed to by BUFFER are used to contain
|
additional information, normally strings which are pointed to by
|
the elements of the result structure.
|
|
This stream must correspond to a file in the same format as the
|
standard group database file.
|
|
If the function returns zero RESULT points to the structure with
|
the wanted data (normally this is in RESULT_BUF). If errors
|
occurred the return value is non-zero and RESULT contains a null
|
pointer.
|
|
The way to scan all the entries in the group database is with
|
‘setgrent’, ‘getgrent’, and ‘endgrent’.
|
|
-- Function: void setgrent (void)
|
Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function initializes a stream for reading from the group data
|
base. You use this stream by calling ‘getgrent’ or ‘getgrent_r’.
|
|
-- Function: struct group * getgrent (void)
|
Preliminary: | MT-Unsafe race:grent race:grentbuf locale |
|
AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
|
*Note POSIX Safety Concepts::.
|
|
The ‘getgrent’ function reads the next entry from the stream
|
initialized by ‘setgrent’. It returns a pointer to the entry. The
|
structure is statically allocated and is overwritten on subsequent
|
calls to ‘getgrent’. You must copy the contents of the structure
|
if you wish to save the information.
|
|
-- Function: int getgrent_r (struct group *RESULT_BUF, char *BUFFER,
|
size_t BUFLEN, struct group **RESULT)
|
Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function is similar to ‘getgrent’ in that it returns the next
|
entry from the stream initialized by ‘setgrent’. Like
|
‘fgetgrent_r’, it places the result in user-supplied buffers
|
pointed to RESULT_BUF and BUFFER.
|
|
If the function returns zero RESULT contains a pointer to the data
|
(normally equal to RESULT_BUF). If errors occurred the return
|
value is non-zero and RESULT contains a null pointer.
|
|
-- Function: void endgrent (void)
|
Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function closes the internal stream used by ‘getgrent’ or
|
‘getgrent_r’.
|
|
|
File: libc.info, Node: Database Example, Next: Netgroup Database, Prev: Group Database, Up: Users and Groups
|
|
30.15 User and Group Database Example
|
=====================================
|
|
Here is an example program showing the use of the system database
|
inquiry functions. The program prints some information about the user
|
running the program.
|
|
|
#include <grp.h>
|
#include <pwd.h>
|
#include <sys/types.h>
|
#include <unistd.h>
|
#include <stdlib.h>
|
|
int
|
main (void)
|
{
|
uid_t me;
|
struct passwd *my_passwd;
|
struct group *my_group;
|
char **members;
|
|
/* Get information about the user ID. */
|
me = getuid ();
|
my_passwd = getpwuid (me);
|
if (!my_passwd)
|
{
|
printf ("Couldn't find out about user %d.\n", (int) me);
|
exit (EXIT_FAILURE);
|
}
|
|
/* Print the information. */
|
printf ("I am %s.\n", my_passwd->pw_gecos);
|
printf ("My login name is %s.\n", my_passwd->pw_name);
|
printf ("My uid is %d.\n", (int) (my_passwd->pw_uid));
|
printf ("My home directory is %s.\n", my_passwd->pw_dir);
|
printf ("My default shell is %s.\n", my_passwd->pw_shell);
|
|
/* Get information about the default group ID. */
|
my_group = getgrgid (my_passwd->pw_gid);
|
if (!my_group)
|
{
|
printf ("Couldn't find out about group %d.\n",
|
(int) my_passwd->pw_gid);
|
exit (EXIT_FAILURE);
|
}
|
|
/* Print the information. */
|
printf ("My default group is %s (%d).\n",
|
my_group->gr_name, (int) (my_passwd->pw_gid));
|
printf ("The members of this group are:\n");
|
members = my_group->gr_mem;
|
while (*members)
|
{
|
printf (" %s\n", *(members));
|
members++;
|
}
|
|
return EXIT_SUCCESS;
|
}
|
|
Here is some output from this program:
|
|
I am Throckmorton Snurd.
|
My login name is snurd.
|
My uid is 31093.
|
My home directory is /home/fsg/snurd.
|
My default shell is /bin/sh.
|
My default group is guest (12).
|
The members of this group are:
|
friedman
|
tami
|
|
|
File: libc.info, Node: Netgroup Database, Prev: Database Example, Up: Users and Groups
|
|
30.16 Netgroup Database
|
=======================
|
|
* Menu:
|
|
* Netgroup Data:: Data in the Netgroup database and where
|
it comes from.
|
* Lookup Netgroup:: How to look for a particular netgroup.
|
* Netgroup Membership:: How to test for netgroup membership.
|
|
|
File: libc.info, Node: Netgroup Data, Next: Lookup Netgroup, Up: Netgroup Database
|
|
30.16.1 Netgroup Data
|
---------------------
|
|
Sometimes it is useful to group users according to other criteria (*note
|
Group Database::). E.g., it is useful to associate a certain group of
|
users with a certain machine. On the other hand grouping of host names
|
is not supported so far.
|
|
In Sun Microsystems SunOS appeared a new kind of database, the
|
netgroup database. It allows grouping hosts, users, and domains freely,
|
giving them individual names. To be more concrete, a netgroup is a list
|
of triples consisting of a host name, a user name, and a domain name
|
where any of the entries can be a wildcard entry matching all inputs. A
|
last possibility is that names of other netgroups can also be given in
|
the list specifying a netgroup. So one can construct arbitrary
|
hierarchies without loops.
|
|
Sun’s implementation allows netgroups only for the ‘nis’ or ‘nisplus’
|
service, *note Services in the NSS configuration::. The implementation
|
in the GNU C Library has no such restriction. An entry in either of the
|
input services must have the following form:
|
|
GROUPNAME ( GROUPNAME | (HOSTNAME,USERNAME,domainname) )+
|
|
Any of the fields in the triple can be empty which means anything
|
matches. While describing the functions we will see that the opposite
|
case is useful as well. I.e., there may be entries which will not match
|
any input. For entries like this, a name consisting of the single
|
character ‘-’ shall be used.
|
|
|
File: libc.info, Node: Lookup Netgroup, Next: Netgroup Membership, Prev: Netgroup Data, Up: Netgroup Database
|
|
30.16.2 Looking up one Netgroup
|
-------------------------------
|
|
The lookup functions for netgroups are a bit different to all other
|
system database handling functions. Since a single netgroup can contain
|
many entries a two-step process is needed. First a single netgroup is
|
selected and then one can iterate over all entries in this netgroup.
|
These functions are declared in ‘netdb.h’.
|
|
-- Function: int setnetgrent (const char *NETGROUP)
|
Preliminary: | MT-Unsafe race:netgrent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
A call to this function initializes the internal state of the
|
library to allow following calls of the ‘getnetgrent’ to iterate
|
over all entries in the netgroup with name NETGROUP.
|
|
When the call is successful (i.e., when a netgroup with this name
|
exists) the return value is ‘1’. When the return value is ‘0’ no
|
netgroup of this name is known or some other error occurred.
|
|
It is important to remember that there is only one single state for
|
iterating the netgroups. Even if the programmer uses the
|
‘getnetgrent_r’ function the result is not really reentrant since always
|
only one single netgroup at a time can be processed. If the program
|
needs to process more than one netgroup simultaneously she must protect
|
this by using external locking. This problem was introduced in the
|
original netgroups implementation in SunOS and since we must stay
|
compatible it is not possible to change this.
|
|
Some other functions also use the netgroups state. Currently these
|
are the ‘innetgr’ function and parts of the implementation of the
|
‘compat’ service part of the NSS implementation.
|
|
-- Function: int getnetgrent (char **HOSTP, char **USERP, char
|
**DOMAINP)
|
Preliminary: | MT-Unsafe race:netgrent race:netgrentbuf locale |
|
AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
|
*Note POSIX Safety Concepts::.
|
|
This function returns the next unprocessed entry of the currently
|
selected netgroup. The string pointers, in which addresses are
|
passed in the arguments HOSTP, USERP, and DOMAINP, will contain
|
after a successful call pointers to appropriate strings. If the
|
string in the next entry is empty the pointer has the value ‘NULL’.
|
The returned string pointers are only valid if none of the netgroup
|
related functions are called.
|
|
The return value is ‘1’ if the next entry was successfully read. A
|
value of ‘0’ means no further entries exist or internal errors
|
occurred.
|
|
-- Function: int getnetgrent_r (char **HOSTP, char **USERP, char
|
**DOMAINP, char *BUFFER, size_t BUFLEN)
|
Preliminary: | MT-Unsafe race:netgrent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function is similar to ‘getnetgrent’ with only one exception:
|
the strings the three string pointers HOSTP, USERP, and DOMAINP
|
point to, are placed in the buffer of BUFLEN bytes starting at
|
BUFFER. This means the returned values are valid even after other
|
netgroup related functions are called.
|
|
The return value is ‘1’ if the next entry was successfully read and
|
the buffer contains enough room to place the strings in it. ‘0’ is
|
returned in case no more entries are found, the buffer is too
|
small, or internal errors occurred.
|
|
This function is a GNU extension. The original implementation in
|
the SunOS libc does not provide this function.
|
|
-- Function: void endnetgrent (void)
|
Preliminary: | MT-Unsafe race:netgrent | AS-Unsafe dlopen plugin
|
heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX Safety
|
Concepts::.
|
|
This function frees all buffers which were allocated to process the
|
last selected netgroup. As a result all string pointers returned
|
by calls to ‘getnetgrent’ are invalid afterwards.
|
|
|
File: libc.info, Node: Netgroup Membership, Prev: Lookup Netgroup, Up: Netgroup Database
|
|
30.16.3 Testing for Netgroup Membership
|
---------------------------------------
|
|
It is often not necessary to scan the whole netgroup since often the
|
only interesting question is whether a given entry is part of the
|
selected netgroup.
|
|
-- Function: int innetgr (const char *NETGROUP, const char *HOST, const
|
char *USER, const char *DOMAIN)
|
Preliminary: | MT-Unsafe race:netgrent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function tests whether the triple specified by the parameters
|
HOSTP, USERP, and DOMAINP is part of the netgroup NETGROUP. Using
|
this function has the advantage that
|
|
1. no other netgroup function can use the global netgroup state
|
since internal locking is used and
|
2. the function is implemented more efficiently than successive
|
calls to the other ‘set’/‘get’/‘endnetgrent’ functions.
|
|
Any of the pointers HOSTP, USERP, and DOMAINP can be ‘NULL’ which
|
means any value is accepted in this position. This is also true
|
for the name ‘-’ which should not match any other string otherwise.
|
|
The return value is ‘1’ if an entry matching the given triple is
|
found in the netgroup. The return value is ‘0’ if the netgroup
|
itself is not found, the netgroup does not contain the triple or
|
internal errors occurred.
|
|
|
File: libc.info, Node: System Management, Next: System Configuration, Prev: Users and Groups, Up: Top
|
|
31 System Management
|
********************
|
|
This chapter describes facilities for controlling the system that
|
underlies a process (including the operating system and hardware) and
|
for getting information about it. Anyone can generally use the
|
informational facilities, but usually only a properly privileged process
|
can make changes.
|
|
* Menu:
|
|
* Host Identification:: Determining the name of the machine.
|
* Platform Type:: Determining operating system and basic
|
machine type
|
* Filesystem Handling:: Controlling/querying mounts
|
* System Parameters:: Getting and setting various system parameters
|
|
To get information on parameters of the system that are built into
|
the system, such as the maximum length of a filename, *note System
|
Configuration::.
|
|
|
File: libc.info, Node: Host Identification, Next: Platform Type, Up: System Management
|
|
31.1 Host Identification
|
========================
|
|
This section explains how to identify the particular system on which
|
your program is running. First, let’s review the various ways computer
|
systems are named, which is a little complicated because of the history
|
of the development of the Internet.
|
|
Every Unix system (also known as a host) has a host name, whether
|
it’s connected to a network or not. In its simplest form, as used
|
before computer networks were an issue, it’s just a word like ‘chicken’.
|
|
But any system attached to the Internet or any network like it
|
conforms to a more rigorous naming convention as part of the Domain Name
|
System (DNS). In DNS, every host name is composed of two parts:
|
|
1. hostname
|
2. domain name
|
|
You will note that “hostname” looks a lot like “host name”, but is
|
not the same thing, and that people often incorrectly refer to entire
|
host names as “domain names.”
|
|
In DNS, the full host name is properly called the FQDN (Fully
|
Qualified Domain Name) and consists of the hostname, then a period, then
|
the domain name. The domain name itself usually has multiple components
|
separated by periods. So for example, a system’s hostname may be
|
‘chicken’ and its domain name might be ‘ai.mit.edu’, so its FQDN (which
|
is its host name) is ‘chicken.ai.mit.edu’.
|
|
Adding to the confusion, though, is that DNS is not the only name
|
space in which a computer needs to be known. Another name space is the
|
NIS (aka YP) name space. For NIS purposes, there is another domain
|
name, which is called the NIS domain name or the YP domain name. It
|
need not have anything to do with the DNS domain name.
|
|
Confusing things even more is the fact that in DNS, it is possible
|
for multiple FQDNs to refer to the same system. However, there is
|
always exactly one of them that is the true host name, and it is called
|
the canonical FQDN.
|
|
In some contexts, the host name is called a “node name.”
|
|
For more information on DNS host naming, see *note Host Names::.
|
|
Prototypes for these functions appear in ‘unistd.h’.
|
|
The programs ‘hostname’, ‘hostid’, and ‘domainname’ work by calling
|
these functions.
|
|
-- Function: int gethostname (char *NAME, size_t SIZE)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function returns the host name of the system on which it is
|
called, in the array NAME. The SIZE argument specifies the size of
|
this array, in bytes. Note that this is _not_ the DNS hostname.
|
If the system participates in DNS, this is the FQDN (see above).
|
|
The return value is ‘0’ on success and ‘-1’ on failure. In the GNU
|
C Library, ‘gethostname’ fails if SIZE is not large enough; then
|
you can try again with a larger array. The following ‘errno’ error
|
condition is defined for this function:
|
|
‘ENAMETOOLONG’
|
The SIZE argument is less than the size of the host name plus
|
one.
|
|
On some systems, there is a symbol for the maximum possible host
|
name length: ‘MAXHOSTNAMELEN’. It is defined in ‘sys/param.h’.
|
But you can’t count on this to exist, so it is cleaner to handle
|
failure and try again.
|
|
‘gethostname’ stores the beginning of the host name in NAME even if
|
the host name won’t entirely fit. For some purposes, a truncated
|
host name is good enough. If it is, you can ignore the error code.
|
|
-- Function: int sethostname (const char *NAME, size_t LENGTH)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘sethostname’ function sets the host name of the system that
|
calls it to NAME, a string with length LENGTH. Only privileged
|
processes are permitted to do this.
|
|
Usually ‘sethostname’ gets called just once, at system boot time.
|
Often, the program that calls it sets it to the value it finds in
|
the file ‘/etc/hostname’.
|
|
Be sure to set the host name to the full host name, not just the
|
DNS hostname (see above).
|
|
The return value is ‘0’ on success and ‘-1’ on failure. The
|
following ‘errno’ error condition is defined for this function:
|
|
‘EPERM’
|
This process cannot set the host name because it is not
|
privileged.
|
|
-- Function: int getdomainnname (char *NAME, size_t LENGTH)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘getdomainname’ returns the NIS (aka YP) domain name of the system
|
on which it is called. Note that this is not the more popular DNS
|
domain name. Get that with ‘gethostname’.
|
|
The specifics of this function are analogous to ‘gethostname’,
|
above.
|
|
-- Function: int setdomainname (const char *NAME, size_t LENGTH)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘getdomainname’ sets the NIS (aka YP) domain name of the system on
|
which it is called. Note that this is not the more popular DNS
|
domain name. Set that with ‘sethostname’.
|
|
The specifics of this function are analogous to ‘sethostname’,
|
above.
|
|
-- Function: long int gethostid (void)
|
Preliminary: | MT-Safe hostid env locale | AS-Unsafe dlopen plugin
|
corrupt heap lock | AC-Unsafe lock corrupt mem fd | *Note POSIX
|
Safety Concepts::.
|
|
This function returns the “host ID” of the machine the program is
|
running on. By convention, this is usually the primary Internet IP
|
address of that machine, converted to a ‘long int’. However, on
|
some systems it is a meaningless but unique number which is
|
hard-coded for each machine.
|
|
This is not widely used. It arose in BSD 4.2, but was dropped in
|
BSD 4.4. It is not required by POSIX.
|
|
The proper way to query the IP address is to use ‘gethostbyname’ on
|
the results of ‘gethostname’. For more information on IP
|
addresses, *Note Host Addresses::.
|
|
-- Function: int sethostid (long int ID)
|
Preliminary: | MT-Unsafe const:hostid | AS-Unsafe | AC-Unsafe
|
corrupt fd | *Note POSIX Safety Concepts::.
|
|
The ‘sethostid’ function sets the “host ID” of the host machine to
|
ID. Only privileged processes are permitted to do this. Usually
|
it happens just once, at system boot time.
|
|
The proper way to establish the primary IP address of a system is
|
to configure the IP address resolver to associate that IP address
|
with the system’s host name as returned by ‘gethostname’. For
|
example, put a record for the system in ‘/etc/hosts’.
|
|
See ‘gethostid’ above for more information on host ids.
|
|
The return value is ‘0’ on success and ‘-1’ on failure. The
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EPERM’
|
This process cannot set the host name because it is not
|
privileged.
|
|
‘ENOSYS’
|
The operating system does not support setting the host ID. On
|
some systems, the host ID is a meaningless but unique number
|
hard-coded for each machine.
|
|
|
File: libc.info, Node: Platform Type, Next: Filesystem Handling, Prev: Host Identification, Up: System Management
|
|
31.2 Platform Type Identification
|
=================================
|
|
You can use the ‘uname’ function to find out some information about the
|
type of computer your program is running on. This function and the
|
associated data type are declared in the header file ‘sys/utsname.h’.
|
|
As a bonus, ‘uname’ also gives some information identifying the
|
particular system your program is running on. This is the same
|
information which you can get with functions targeted to this purpose
|
described in *note Host Identification::.
|
|
-- Data Type: struct utsname
|
The ‘utsname’ structure is used to hold information returned by the
|
‘uname’ function. It has the following members:
|
|
‘char sysname[]’
|
This is the name of the operating system in use.
|
|
‘char release[]’
|
This is the current release level of the operating system
|
implementation.
|
|
‘char version[]’
|
This is the current version level within the release of the
|
operating system.
|
|
‘char machine[]’
|
This is a description of the type of hardware that is in use.
|
|
Some systems provide a mechanism to interrogate the kernel
|
directly for this information. On systems without such a
|
mechanism, the GNU C Library fills in this field based on the
|
configuration name that was specified when building and
|
installing the library.
|
|
GNU uses a three-part name to describe a system configuration;
|
the three parts are CPU, MANUFACTURER and SYSTEM-TYPE, and
|
they are separated with dashes. Any possible combination of
|
three names is potentially meaningful, but most such
|
combinations are meaningless in practice and even the
|
meaningful ones are not necessarily supported by any
|
particular GNU program.
|
|
Since the value in ‘machine’ is supposed to describe just the
|
hardware, it consists of the first two parts of the
|
configuration name: ‘CPU-MANUFACTURER’. For example, it might
|
be one of these:
|
|
‘"sparc-sun"’, ‘"i386-ANYTHING"’, ‘"m68k-hp"’,
|
‘"m68k-sony"’, ‘"m68k-sun"’, ‘"mips-dec"’
|
|
‘char nodename[]’
|
This is the host name of this particular computer. In the GNU
|
C Library, the value is the same as that returned by
|
‘gethostname’; see *note Host Identification::.
|
|
gethostname() is implemented with a call to uname().
|
|
‘char domainname[]’
|
This is the NIS or YP domain name. It is the same value
|
returned by ‘getdomainname’; see *note Host Identification::.
|
This element is a relatively recent invention and use of it is
|
not as portable as use of the rest of the structure.
|
|
-- Function: int uname (struct utsname *INFO)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘uname’ function fills in the structure pointed to by INFO with
|
information about the operating system and host machine. A
|
non-negative value indicates that the data was successfully stored.
|
|
‘-1’ as the value indicates an error. The only error possible is
|
‘EFAULT’, which we normally don’t mention as it is always a
|
possibility.
|
|
|
File: libc.info, Node: Filesystem Handling, Next: System Parameters, Prev: Platform Type, Up: System Management
|
|
31.3 Controlling and Querying Mounts
|
====================================
|
|
All files are in filesystems, and before you can access any file, its
|
filesystem must be mounted. Because of Unix’s concept of _Everything is
|
a file_, mounting of filesystems is central to doing almost anything.
|
This section explains how to find out what filesystems are currently
|
mounted and what filesystems are available for mounting, and how to
|
change what is mounted.
|
|
The classic filesystem is the contents of a disk drive. The concept
|
is considerably more abstract, though, and lots of things other than
|
disk drives can be mounted.
|
|
Some block devices don’t correspond to traditional devices like disk
|
drives. For example, a loop device is a block device whose driver uses
|
a regular file in another filesystem as its medium. So if that regular
|
file contains appropriate data for a filesystem, you can by mounting the
|
loop device essentially mount a regular file.
|
|
Some filesystems aren’t based on a device of any kind. The “proc”
|
filesystem, for example, contains files whose data is made up by the
|
filesystem driver on the fly whenever you ask for it. And when you
|
write to it, the data you write causes changes in the system. No data
|
gets stored.
|
|
* Menu:
|
|
* Mount Information:: What is or could be mounted?
|
* Mount-Unmount-Remount:: Controlling what is mounted and how
|
|
|
File: libc.info, Node: Mount Information, Next: Mount-Unmount-Remount, Up: Filesystem Handling
|
|
31.3.1 Mount Information
|
------------------------
|
|
For some programs it is desirable and necessary to access information
|
about whether a certain filesystem is mounted and, if it is, where, or
|
simply to get lists of all the available filesystems. The GNU C Library
|
provides some functions to retrieve this information portably.
|
|
Traditionally Unix systems have a file named ‘/etc/fstab’ which
|
describes all possibly mounted filesystems. The ‘mount’ program uses
|
this file to mount at startup time of the system all the necessary
|
filesystems. The information about all the filesystems actually mounted
|
is normally kept in a file named either ‘/var/run/mtab’ or ‘/etc/mtab’.
|
Both files share the same syntax and it is crucial that this syntax is
|
followed all the time. Therefore it is best to never directly write the
|
files. The functions described in this section can do this and they
|
also provide the functionality to convert the external textual
|
representation to the internal representation.
|
|
Note that the ‘fstab’ and ‘mtab’ files are maintained on a system by
|
_convention_. It is possible for the files not to exist or not to be
|
consistent with what is really mounted or available to mount, if the
|
system’s administration policy allows it. But programs that mount and
|
unmount filesystems typically maintain and use these files as described
|
herein.
|
|
The filenames given above should never be used directly. The
|
portable way to handle these file is to use the macro ‘_PATH_FSTAB’,
|
defined in ‘fstab.h’, or ‘_PATH_MNTTAB’, defined in ‘mntent.h’ and
|
‘paths.h’, for ‘fstab’; and the macro ‘_PATH_MOUNTED’, also defined in
|
‘mntent.h’ and ‘paths.h’, for ‘mtab’. There are also two alternate
|
macro names ‘FSTAB’, ‘MNTTAB’, and ‘MOUNTED’ defined but these names are
|
deprecated and kept only for backward compatibility. The names
|
‘_PATH_MNTTAB’ and ‘_PATH_MOUNTED’ should always be used.
|
|
* Menu:
|
|
* fstab:: The ‘fstab’ file
|
* mtab:: The ‘mtab’ file
|
* Other Mount Information:: Other (non-libc) sources of mount information
|
|
|
File: libc.info, Node: fstab, Next: mtab, Up: Mount Information
|
|
31.3.1.1 The ‘fstab’ file
|
.........................
|
|
The internal representation for entries of the file is ‘struct fstab’,
|
defined in ‘fstab.h’.
|
|
-- Data Type: struct fstab
|
This structure is used with the ‘getfsent’, ‘getfsspec’, and
|
‘getfsfile’ functions.
|
|
‘char *fs_spec’
|
This element describes the device from which the filesystem is
|
mounted. Normally this is the name of a special device, such
|
as a hard disk partition, but it could also be a more or less
|
generic string. For "NFS" it would be a hostname and
|
directory name combination.
|
|
Even though the element is not declared ‘const’ it shouldn’t
|
be modified. The missing ‘const’ has historic reasons, since
|
this function predates ISO C. The same is true for the other
|
string elements of this structure.
|
|
‘char *fs_file’
|
This describes the mount point on the local system. I.e.,
|
accessing any file in this filesystem has implicitly or
|
explicitly this string as a prefix.
|
|
‘char *fs_vfstype’
|
This is the type of the filesystem. Depending on what the
|
underlying kernel understands it can be any string.
|
|
‘char *fs_mntops’
|
This is a string containing options passed to the kernel with
|
the ‘mount’ call. Again, this can be almost anything. There
|
can be more than one option, separated from the others by a
|
comma. Each option consists of a name and an optional value
|
part, introduced by an ‘=’ character.
|
|
If the value of this element must be processed it should
|
ideally be done using the ‘getsubopt’ function; see *note
|
Suboptions::.
|
|
‘const char *fs_type’
|
This name is poorly chosen. This element points to a string
|
(possibly in the ‘fs_mntops’ string) which describes the modes
|
with which the filesystem is mounted. ‘fstab’ defines five
|
macros to describe the possible values:
|
|
‘FSTAB_RW’
|
The filesystems gets mounted with read and write enabled.
|
‘FSTAB_RQ’
|
The filesystems gets mounted with read and write enabled.
|
Write access is restricted by quotas.
|
‘FSTAB_RO’
|
The filesystem gets mounted read-only.
|
‘FSTAB_SW’
|
This is not a real filesystem, it is a swap device.
|
‘FSTAB_XX’
|
This entry from the ‘fstab’ file is totally ignored.
|
|
Testing for equality with these value must happen using
|
‘strcmp’ since these are all strings. Comparing the pointer
|
will probably always fail.
|
|
‘int fs_freq’
|
This element describes the dump frequency in days.
|
|
‘int fs_passno’
|
This element describes the pass number on parallel dumps. It
|
is closely related to the ‘dump’ utility used on Unix systems.
|
|
To read the entire content of the of the ‘fstab’ file the GNU C
|
Library contains a set of three functions which are designed in the
|
usual way.
|
|
-- Function: int setfsent (void)
|
Preliminary: | MT-Unsafe race:fsent | AS-Unsafe heap corrupt lock |
|
AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
|
|
This function makes sure that the internal read pointer for the
|
‘fstab’ file is at the beginning of the file. This is done by
|
either opening the file or resetting the read pointer.
|
|
Since the file handle is internal to the libc this function is not
|
thread-safe.
|
|
This function returns a non-zero value if the operation was
|
successful and the ‘getfs*’ functions can be used to read the
|
entries of the file.
|
|
-- Function: void endfsent (void)
|
Preliminary: | MT-Unsafe race:fsent | AS-Unsafe heap corrupt lock |
|
AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
|
|
This function makes sure that all resources acquired by a prior
|
call to ‘setfsent’ (explicitly or implicitly by calling ‘getfsent’)
|
are freed.
|
|
-- Function: struct fstab * getfsent (void)
|
Preliminary: | MT-Unsafe race:fsent locale | AS-Unsafe corrupt heap
|
lock | AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
|
|
This function returns the next entry of the ‘fstab’ file. If this
|
is the first call to any of the functions handling ‘fstab’ since
|
program start or the last call of ‘endfsent’, the file will be
|
opened.
|
|
The function returns a pointer to a variable of type ‘struct
|
fstab’. This variable is shared by all threads and therefore this
|
function is not thread-safe. If an error occurred ‘getfsent’
|
returns a ‘NULL’ pointer.
|
|
-- Function: struct fstab * getfsspec (const char *NAME)
|
Preliminary: | MT-Unsafe race:fsent locale | AS-Unsafe corrupt heap
|
lock | AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
|
|
This function returns the next entry of the ‘fstab’ file which has
|
a string equal to NAME pointed to by the ‘fs_spec’ element. Since
|
there is normally exactly one entry for each special device it
|
makes no sense to call this function more than once for the same
|
argument. If this is the first call to any of the functions
|
handling ‘fstab’ since program start or the last call of
|
‘endfsent’, the file will be opened.
|
|
The function returns a pointer to a variable of type ‘struct
|
fstab’. This variable is shared by all threads and therefore this
|
function is not thread-safe. If an error occurred ‘getfsent’
|
returns a ‘NULL’ pointer.
|
|
-- Function: struct fstab * getfsfile (const char *NAME)
|
Preliminary: | MT-Unsafe race:fsent locale | AS-Unsafe corrupt heap
|
lock | AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
|
|
This function returns the next entry of the ‘fstab’ file which has
|
a string equal to NAME pointed to by the ‘fs_file’ element. Since
|
there is normally exactly one entry for each mount point it makes
|
no sense to call this function more than once for the same
|
argument. If this is the first call to any of the functions
|
handling ‘fstab’ since program start or the last call of
|
‘endfsent’, the file will be opened.
|
|
The function returns a pointer to a variable of type ‘struct
|
fstab’. This variable is shared by all threads and therefore this
|
function is not thread-safe. If an error occurred ‘getfsent’
|
returns a ‘NULL’ pointer.
|
|
|
File: libc.info, Node: mtab, Next: Other Mount Information, Prev: fstab, Up: Mount Information
|
|
31.3.1.2 The ‘mtab’ file
|
........................
|
|
The following functions and data structure access the ‘mtab’ file.
|
|
-- Data Type: struct mntent
|
This structure is used with the ‘getmntent’, ‘getmntent_t’,
|
‘addmntent’, and ‘hasmntopt’ functions.
|
|
‘char *mnt_fsname’
|
This element contains a pointer to a string describing the
|
name of the special device from which the filesystem is
|
mounted. It corresponds to the ‘fs_spec’ element in ‘struct
|
fstab’.
|
|
‘char *mnt_dir’
|
This element points to a string describing the mount point of
|
the filesystem. It corresponds to the ‘fs_file’ element in
|
‘struct fstab’.
|
|
‘char *mnt_type’
|
‘mnt_type’ describes the filesystem type and is therefore
|
equivalent to ‘fs_vfstype’ in ‘struct fstab’. ‘mntent.h’
|
defines a few symbolic names for some of the values this
|
string can have. But since the kernel can support arbitrary
|
filesystems it does not make much sense to give them symbolic
|
names. If one knows the symbol name one also knows the
|
filesystem name. Nevertheless here follows the list of the
|
symbols provided in ‘mntent.h’.
|
|
‘MNTTYPE_IGNORE’
|
This symbol expands to ‘"ignore"’. The value is sometime
|
used in ‘fstab’ files to make sure entries are not used
|
without removing them.
|
‘MNTTYPE_NFS’
|
Expands to ‘"nfs"’. Using this macro sometimes could
|
make sense since it names the default NFS implementation,
|
in case both version 2 and 3 are supported.
|
‘MNTTYPE_SWAP’
|
This symbol expands to ‘"swap"’. It names the special
|
‘fstab’ entry which names one of the possibly multiple
|
swap partitions.
|
|
‘char *mnt_opts’
|
The element contains a string describing the options used
|
while mounting the filesystem. As for the equivalent element
|
‘fs_mntops’ of ‘struct fstab’ it is best to use the function
|
‘getsubopt’ (*note Suboptions::) to access the parts of this
|
string.
|
|
The ‘mntent.h’ file defines a number of macros with string
|
values which correspond to some of the options understood by
|
the kernel. There might be many more options which are
|
possible so it doesn’t make much sense to rely on these macros
|
but to be consistent here is the list:
|
|
‘MNTOPT_DEFAULTS’
|
Expands to ‘"defaults"’. This option should be used
|
alone since it indicates all values for the customizable
|
values are chosen to be the default.
|
‘MNTOPT_RO’
|
Expands to ‘"ro"’. See the ‘FSTAB_RO’ value, it means
|
the filesystem is mounted read-only.
|
‘MNTOPT_RW’
|
Expand to ‘"rw"’. See the ‘FSTAB_RW’ value, it means the
|
filesystem is mounted with read and write permissions.
|
‘MNTOPT_SUID’
|
Expands to ‘"suid"’. This means that the SUID bit (*note
|
How Change Persona::) is respected when a program from
|
the filesystem is started.
|
‘MNTOPT_NOSUID’
|
Expands to ‘"nosuid"’. This is the opposite of
|
‘MNTOPT_SUID’, the SUID bit for all files from the
|
filesystem is ignored.
|
‘MNTOPT_NOAUTO’
|
Expands to ‘"noauto"’. At startup time the ‘mount’
|
program will ignore this entry if it is started with the
|
‘-a’ option to mount all filesystems mentioned in the
|
‘fstab’ file.
|
|
As for the ‘FSTAB_*’ entries introduced above it is important
|
to use ‘strcmp’ to check for equality.
|
|
‘mnt_freq’
|
This elements corresponds to ‘fs_freq’ and also specifies the
|
frequency in days in which dumps are made.
|
|
‘mnt_passno’
|
This element is equivalent to ‘fs_passno’ with the same
|
meaning which is uninteresting for all programs beside ‘dump’.
|
|
For accessing the ‘mtab’ file there is again a set of three functions
|
to access all entries in a row. Unlike the functions to handle ‘fstab’
|
these functions do not access a fixed file and there is even a thread
|
safe variant of the get function. Beside this the GNU C Library
|
contains functions to alter the file and test for specific options.
|
|
-- Function: FILE * setmntent (const char *FILE, const char *MODE)
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
|
lock | *Note POSIX Safety Concepts::.
|
|
The ‘setmntent’ function prepares the file named FILE which must be
|
in the format of a ‘fstab’ and ‘mtab’ file for the upcoming
|
processing through the other functions of the family. The MODE
|
parameter can be chosen in the way the OPENTYPE parameter for
|
‘fopen’ (*note Opening Streams::) can be chosen. If the file is
|
opened for writing the file is also allowed to be empty.
|
|
If the file was successfully opened ‘setmntent’ returns a file
|
descriptor for future use. Otherwise the return value is ‘NULL’
|
and ‘errno’ is set accordingly.
|
|
-- Function: int endmntent (FILE *STREAM)
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem
|
fd | *Note POSIX Safety Concepts::.
|
|
This function takes for the STREAM parameter a file handle which
|
previously was returned from the ‘setmntent’ call. ‘endmntent’
|
closes the stream and frees all resources.
|
|
The return value is 1 unless an error occurred in which case it is
|
0.
|
|
-- Function: struct mntent * getmntent (FILE *STREAM)
|
Preliminary: | MT-Unsafe race:mntentbuf locale | AS-Unsafe corrupt
|
heap init | AC-Unsafe init corrupt lock mem | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getmntent’ function takes as the parameter a file handle
|
previously returned by successful call to ‘setmntent’. It returns
|
a pointer to a static variable of type ‘struct mntent’ which is
|
filled with the information from the next entry from the file
|
currently read.
|
|
The file format used prescribes the use of spaces or tab characters
|
to separate the fields. This makes it harder to use name
|
containing one of these characters (e.g., mount points using
|
spaces). Therefore these characters are encoded in the files and
|
the ‘getmntent’ function takes care of the decoding while reading
|
the entries back in. ‘'\040'’ is used to encode a space character,
|
‘'\011'’ to encode a tab character, ‘'\012'’ to encode a newline
|
character, and ‘'\\'’ to encode a backslash.
|
|
If there was an error or the end of the file is reached the return
|
value is ‘NULL’.
|
|
This function is not thread-safe since all calls to this function
|
return a pointer to the same static variable. ‘getmntent_r’ should
|
be used in situations where multiple threads access the file.
|
|
-- Function: struct mntent * getmntent_r (FILE *STREAM, struct mntent
|
*RESULT, char *BUFFER, int BUFSIZE)
|
Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
|
corrupt lock mem | *Note POSIX Safety Concepts::.
|
|
The ‘getmntent_r’ function is the reentrant variant of ‘getmntent’.
|
It also returns the next entry from the file and returns a pointer.
|
The actual variable the values are stored in is not static, though.
|
Instead the function stores the values in the variable pointed to
|
by the RESULT parameter. Additional information (e.g., the strings
|
pointed to by the elements of the result) are kept in the buffer of
|
size BUFSIZE pointed to by BUFFER.
|
|
Escaped characters (space, tab, backslash) are converted back in
|
the same way as it happens for ‘getmentent’.
|
|
The function returns a ‘NULL’ pointer in error cases. Errors could
|
be:
|
• error while reading the file,
|
• end of file reached,
|
• BUFSIZE is too small for reading a complete new entry.
|
|
-- Function: int addmntent (FILE *STREAM, const struct mntent *MNT)
|
Preliminary: | MT-Safe race:stream locale | AS-Unsafe corrupt |
|
AC-Unsafe corrupt | *Note POSIX Safety Concepts::.
|
|
The ‘addmntent’ function allows adding a new entry to the file
|
previously opened with ‘setmntent’. The new entries are always
|
appended. I.e., even if the position of the file descriptor is not
|
at the end of the file this function does not overwrite an existing
|
entry following the current position.
|
|
The implication of this is that to remove an entry from a file one
|
has to create a new file while leaving out the entry to be removed
|
and after closing the file remove the old one and rename the new
|
file to the chosen name.
|
|
This function takes care of spaces and tab characters in the names
|
to be written to the file. It converts them and the backslash
|
character into the format describe in the ‘getmntent’ description
|
above.
|
|
This function returns 0 in case the operation was successful.
|
Otherwise the return value is 1 and ‘errno’ is set appropriately.
|
|
-- Function: char * hasmntopt (const struct mntent *MNT, const char
|
*OPT)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function can be used to check whether the string pointed to by
|
the ‘mnt_opts’ element of the variable pointed to by MNT contains
|
the option OPT. If this is true a pointer to the beginning of the
|
option in the ‘mnt_opts’ element is returned. If no such option
|
exists the function returns ‘NULL’.
|
|
This function is useful to test whether a specific option is
|
present but when all options have to be processed one is better off
|
with using the ‘getsubopt’ function to iterate over all options in
|
the string.
|
|
|
File: libc.info, Node: Other Mount Information, Prev: mtab, Up: Mount Information
|
|
31.3.1.3 Other (Non-libc) Sources of Mount Information
|
......................................................
|
|
On a system with a Linux kernel and the ‘proc’ filesystem, you can get
|
information on currently mounted filesystems from the file ‘mounts’ in
|
the ‘proc’ filesystem. Its format is similar to that of the ‘mtab’
|
file, but represents what is truly mounted without relying on facilities
|
outside the kernel to keep ‘mtab’ up to date.
|
|
|
File: libc.info, Node: Mount-Unmount-Remount, Prev: Mount Information, Up: Filesystem Handling
|
|
31.3.2 Mount, Unmount, Remount
|
------------------------------
|
|
This section describes the functions for mounting, unmounting, and
|
remounting filesystems.
|
|
Only the superuser can mount, unmount, or remount a filesystem.
|
|
These functions do not access the ‘fstab’ and ‘mtab’ files. You
|
should maintain and use these separately. *Note Mount Information::.
|
|
The symbols in this section are declared in ‘sys/mount.h’.
|
|
-- Function: int mount (const char *SPECIAL_FILE, const char *DIR,
|
const char *FSTYPE, unsigned long int OPTIONS, const void
|
*DATA)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘mount’ mounts or remounts a filesystem. The two operations are
|
quite different and are merged rather unnaturally into this one
|
function. The ‘MS_REMOUNT’ option, explained below, determines
|
whether ‘mount’ mounts or remounts.
|
|
For a mount, the filesystem on the block device represented by the
|
device special file named SPECIAL_FILE gets mounted over the mount
|
point DIR. This means that the directory DIR (along with any files
|
in it) is no longer visible; in its place (and still with the name
|
DIR) is the root directory of the filesystem on the device.
|
|
As an exception, if the filesystem type (see below) is one which is
|
not based on a device (e.g. “proc”), ‘mount’ instantiates a
|
filesystem and mounts it over DIR and ignores SPECIAL_FILE.
|
|
For a remount, DIR specifies the mount point where the filesystem
|
to be remounted is (and remains) mounted and SPECIAL_FILE is
|
ignored. Remounting a filesystem means changing the options that
|
control operations on the filesystem while it is mounted. It does
|
not mean unmounting and mounting again.
|
|
For a mount, you must identify the type of the filesystem as
|
FSTYPE. This type tells the kernel how to access the filesystem
|
and can be thought of as the name of a filesystem driver. The
|
acceptable values are system dependent. On a system with a Linux
|
kernel and the ‘proc’ filesystem, the list of possible values is in
|
the file ‘filesystems’ in the ‘proc’ filesystem (e.g. type ‘cat
|
/proc/filesystems’ to see the list). With a Linux kernel, the
|
types of filesystems that ‘mount’ can mount, and their type names,
|
depends on what filesystem drivers are configured into the kernel
|
or loaded as loadable kernel modules. An example of a common value
|
for FSTYPE is ‘ext2’.
|
|
For a remount, ‘mount’ ignores FSTYPE.
|
|
OPTIONS specifies a variety of options that apply until the
|
filesystem is unmounted or remounted. The precise meaning of an
|
option depends on the filesystem and with some filesystems, an
|
option may have no effect at all. Furthermore, for some
|
filesystems, some of these options (but never ‘MS_RDONLY’) can be
|
overridden for individual file accesses via ‘ioctl’.
|
|
OPTIONS is a bit string with bit fields defined using the following
|
mask and masked value macros:
|
|
‘MS_MGC_MASK’
|
This multibit field contains a magic number. If it does not
|
have the value ‘MS_MGC_VAL’, ‘mount’ assumes all the following
|
bits are zero and the DATA argument is a null string,
|
regardless of their actual values.
|
|
‘MS_REMOUNT’
|
This bit on means to remount the filesystem. Off means to
|
mount it.
|
|
‘MS_RDONLY’
|
This bit on specifies that no writing to the filesystem shall
|
be allowed while it is mounted. This cannot be overridden by
|
‘ioctl’. This option is available on nearly all filesystems.
|
|
‘S_IMMUTABLE’
|
This bit on specifies that no writing to the files in the
|
filesystem shall be allowed while it is mounted. This can be
|
overridden for a particular file access by a properly
|
privileged call to ‘ioctl’. This option is a relatively new
|
invention and is not available on many filesystems.
|
|
‘S_APPEND’
|
This bit on specifies that the only file writing that shall be
|
allowed while the filesystem is mounted is appending. Some
|
filesystems allow this to be overridden for a particular
|
process by a properly privileged call to ‘ioctl’. This is a
|
relatively new invention and is not available on many
|
filesystems.
|
|
‘MS_NOSUID’
|
This bit on specifies that Setuid and Setgid permissions on
|
files in the filesystem shall be ignored while it is mounted.
|
|
‘MS_NOEXEC’
|
This bit on specifies that no files in the filesystem shall be
|
executed while the filesystem is mounted.
|
|
‘MS_NODEV’
|
This bit on specifies that no device special files in the
|
filesystem shall be accessible while the filesystem is
|
mounted.
|
|
‘MS_SYNCHRONOUS’
|
This bit on specifies that all writes to the filesystem while
|
it is mounted shall be synchronous; i.e., data shall be synced
|
before each write completes rather than held in the buffer
|
cache.
|
|
‘MS_MANDLOCK’
|
This bit on specifies that mandatory locks on files shall be
|
permitted while the filesystem is mounted.
|
|
‘MS_NOATIME’
|
This bit on specifies that access times of files shall not be
|
updated when the files are accessed while the filesystem is
|
mounted.
|
|
‘MS_NODIRATIME’
|
This bit on specifies that access times of directories shall
|
not be updated when the directories are accessed while the
|
filesystem in mounted.
|
|
Any bits not covered by the above masks should be set off;
|
otherwise, results are undefined.
|
|
The meaning of DATA depends on the filesystem type and is
|
controlled entirely by the filesystem driver in the kernel.
|
|
Example:
|
|
#include <sys/mount.h>
|
|
mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");
|
|
mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");
|
|
|
Appropriate arguments for ‘mount’ are conventionally recorded in
|
the ‘fstab’ table. *Note Mount Information::.
|
|
The return value is zero if the mount or remount is successful.
|
Otherwise, it is ‘-1’ and ‘errno’ is set appropriately. The values
|
of ‘errno’ are filesystem dependent, but here is a general list:
|
|
‘EPERM’
|
The process is not superuser.
|
‘ENODEV’
|
The file system type FSTYPE is not known to the kernel.
|
‘ENOTBLK’
|
The file DEV is not a block device special file.
|
‘EBUSY’
|
|
• The device is already mounted.
|
|
• The mount point is busy. (E.g. it is some process’
|
working directory or has a filesystem mounted on it
|
already).
|
|
• The request is to remount read-only, but there are files
|
open for write.
|
|
‘EINVAL’
|
|
• A remount was attempted, but there is no filesystem
|
mounted over the specified mount point.
|
|
• The supposed filesystem has an invalid superblock.
|
|
‘EACCES’
|
|
• The filesystem is inherently read-only (possibly due to a
|
switch on the device) and the process attempted to mount
|
it read/write (by setting the ‘MS_RDONLY’ bit off).
|
|
• SPECIAL_FILE or DIR is not accessible due to file
|
permissions.
|
|
• SPECIAL_FILE is not accessible because it is in a
|
filesystem that is mounted with the ‘MS_NODEV’ option.
|
|
‘EM_FILE’
|
The table of dummy devices is full. ‘mount’ needs to create a
|
dummy device (aka “unnamed” device) if the filesystem being
|
mounted is not one that uses a device.
|
|
-- Function: int umount2 (const char *FILE, int FLAGS)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘umount2’ unmounts a filesystem.
|
|
You can identify the filesystem to unmount either by the device
|
special file that contains the filesystem or by the mount point.
|
The effect is the same. Specify either as the string FILE.
|
|
FLAGS contains the one-bit field identified by the following mask
|
macro:
|
|
‘MNT_FORCE’
|
This bit on means to force the unmounting even if the
|
filesystem is busy, by making it unbusy first. If the bit is
|
off and the filesystem is busy, ‘umount2’ fails with ‘errno’ =
|
‘EBUSY’. Depending on the filesystem, this may override all,
|
some, or no busy conditions.
|
|
All other bits in FLAGS should be set to zero; otherwise, the
|
result is undefined.
|
|
Example:
|
|
#include <sys/mount.h>
|
|
umount2("/mnt", MNT_FORCE);
|
|
umount2("/dev/hdd1", 0);
|
|
|
After the filesystem is unmounted, the directory that was the mount
|
point is visible, as are any files in it.
|
|
As part of unmounting, ‘umount2’ syncs the filesystem.
|
|
If the unmounting is successful, the return value is zero.
|
Otherwise, it is ‘-1’ and ‘errno’ is set accordingly:
|
|
‘EPERM’
|
The process is not superuser.
|
‘EBUSY’
|
The filesystem cannot be unmounted because it is busy. E.g.
|
it contains a directory that is some process’s working
|
directory or a file that some process has open. With some
|
filesystems in some cases, you can avoid this failure with the
|
‘MNT_FORCE’ option.
|
|
‘EINVAL’
|
FILE validly refers to a file, but that file is neither a
|
mount point nor a device special file of a currently mounted
|
filesystem.
|
|
This function is not available on all systems.
|
|
-- Function: int umount (const char *FILE)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘umount’ does the same thing as ‘umount2’ with FLAGS set to zeroes.
|
It is more widely available than ‘umount2’ but since it lacks the
|
possibility to forcefully unmount a filesystem is deprecated when
|
‘umount2’ is also available.
|
|
|
File: libc.info, Node: System Parameters, Prev: Filesystem Handling, Up: System Management
|
|
31.4 System Parameters
|
======================
|
|
This section describes the ‘sysctl’ function, which gets and sets a
|
variety of system parameters.
|
|
The symbols used in this section are declared in the file
|
‘sys/sysctl.h’.
|
|
-- Function: int sysctl (int *NAMES, int NLEN, void *OLDVAL, size_t
|
*OLDLENP, void *NEWVAL, size_t NEWLEN)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
‘sysctl’ gets or sets a specified system parameter. There are so
|
many of these parameters that it is not practical to list them all
|
here, but here are some examples:
|
|
• network domain name
|
• paging parameters
|
• network Address Resolution Protocol timeout time
|
• maximum number of files that may be open
|
• root filesystem device
|
• when kernel was built
|
|
The set of available parameters depends on the kernel configuration
|
and can change while the system is running, particularly when you
|
load and unload loadable kernel modules.
|
|
The system parameters with which ‘syslog’ is concerned are arranged
|
in a hierarchical structure like a hierarchical filesystem. To
|
identify a particular parameter, you specify a path through the
|
structure in a way analogous to specifying the pathname of a file.
|
Each component of the path is specified by an integer and each of
|
these integers has a macro defined for it by ‘sys/sysctl.h’. NAMES
|
is the path, in the form of an array of integers. Each component
|
of the path is one element of the array, in order. NLEN is the
|
number of components in the path.
|
|
For example, the first component of the path for all the paging
|
parameters is the value ‘CTL_VM’. For the free page thresholds,
|
the second component of the path is ‘VM_FREEPG’. So to get the
|
free page threshold values, make NAMES an array containing the two
|
elements ‘CTL_VM’ and ‘VM_FREEPG’ and make NLEN = 2.
|
|
The format of the value of a parameter depends on the parameter.
|
Sometimes it is an integer; sometimes it is an ASCII string;
|
sometimes it is an elaborate structure. In the case of the free
|
page thresholds used in the example above, the parameter value is a
|
structure containing several integers.
|
|
In any case, you identify a place to return the parameter’s value
|
with OLDVAL and specify the amount of storage available at that
|
location as *OLDLENP. *OLDLENP does double duty because it is also
|
the output location that contains the actual length of the returned
|
value.
|
|
If you don’t want the parameter value returned, specify a null
|
pointer for OLDVAL.
|
|
To set the parameter, specify the address and length of the new
|
value as NEWVAL and NEWLEN. If you don’t want to set the
|
parameter, specify a null pointer as NEWVAL.
|
|
If you get and set a parameter in the same ‘sysctl’ call, the value
|
returned is the value of the parameter before it was set.
|
|
Each system parameter has a set of permissions similar to the
|
permissions for a file (including the permissions on directories in
|
its path) that determine whether you may get or set it. For the
|
purposes of these permissions, every parameter is considered to be
|
owned by the superuser and Group 0 so processes with that effective
|
uid or gid may have more access to system parameters. Unlike with
|
files, the superuser does not invariably have full permission to
|
all system parameters, because some of them are designed not to be
|
changed ever.
|
|
‘sysctl’ returns a zero return value if it succeeds. Otherwise, it
|
returns ‘-1’ and sets ‘errno’ appropriately. Besides the failures
|
that apply to all system calls, the following are the ‘errno’ codes
|
for all possible failures:
|
|
‘EPERM’
|
The process is not permitted to access one of the components
|
of the path of the system parameter or is not permitted to
|
access the system parameter itself in the way (read or write)
|
that it requested.
|
‘ENOTDIR’
|
There is no system parameter corresponding to NAME.
|
‘EFAULT’
|
OLDVAL is not null, which means the process wanted to read the
|
parameter, but *OLDLENP is zero, so there is no place to
|
return it.
|
‘EINVAL’
|
• The process attempted to set a system parameter to a
|
value that is not valid for that parameter.
|
• The space provided for the return of the system parameter
|
is not the right size for that parameter.
|
‘ENOMEM’
|
This value may be returned instead of the more correct
|
‘EINVAL’ in some cases where the space provided for the return
|
of the system parameter is too small.
|
|
If you have a Linux kernel with the ‘proc’ filesystem, you can get
|
and set most of the same parameters by reading and writing to files in
|
the ‘sys’ directory of the ‘proc’ filesystem. In the ‘sys’ directory,
|
the directory structure represents the hierarchical structure of the
|
parameters. E.g. you can display the free page thresholds with
|
cat /proc/sys/vm/freepages
|
|
Some more traditional and more widely available, though less general,
|
GNU C Library functions for getting and setting some of the same system
|
parameters are:
|
|
• ‘getdomainname’, ‘setdomainname’
|
• ‘gethostname’, ‘sethostname’ (*Note Host Identification::.)
|
• ‘uname’ (*Note Platform Type::.)
|
|
|
File: libc.info, Node: System Configuration, Next: Cryptographic Functions, Prev: System Management, Up: Top
|
|
32 System Configuration Parameters
|
**********************************
|
|
The functions and macros listed in this chapter give information about
|
configuration parameters of the operating system—for example, capacity
|
limits, presence of optional POSIX features, and the default path for
|
executable files (*note String Parameters::).
|
|
* Menu:
|
|
* General Limits:: Constants and functions that describe
|
various process-related limits that have
|
one uniform value for any given machine.
|
* System Options:: Optional POSIX features.
|
* Version Supported:: Version numbers of POSIX.1 and POSIX.2.
|
* Sysconf:: Getting specific configuration values
|
of general limits and system options.
|
* Minimums:: Minimum values for general limits.
|
|
* Limits for Files:: Size limitations that pertain to individual files.
|
These can vary between file systems
|
or even from file to file.
|
* Options for Files:: Optional features that some files may support.
|
* File Minimums:: Minimum values for file limits.
|
* Pathconf:: Getting the limit values for a particular file.
|
|
* Utility Limits:: Capacity limits of some POSIX.2 utility programs.
|
* Utility Minimums:: Minimum allowable values of those limits.
|
|
* String Parameters:: Getting the default search path.
|
|
|
File: libc.info, Node: General Limits, Next: System Options, Up: System Configuration
|
|
32.1 General Capacity Limits
|
============================
|
|
The POSIX.1 and POSIX.2 standards specify a number of parameters that
|
describe capacity limitations of the system. These limits can be fixed
|
constants for a given operating system, or they can vary from machine to
|
machine. For example, some limit values may be configurable by the
|
system administrator, either at run time or by rebuilding the kernel,
|
and this should not require recompiling application programs.
|
|
Each of the following limit parameters has a macro that is defined in
|
‘limits.h’ only if the system has a fixed, uniform limit for the
|
parameter in question. If the system allows different file systems or
|
files to have different limits, then the macro is undefined; use
|
‘sysconf’ to find out the limit that applies at a particular time on a
|
particular machine. *Note Sysconf::.
|
|
Each of these parameters also has another macro, with a name starting
|
with ‘_POSIX’, which gives the lowest value that the limit is allowed to
|
have on _any_ POSIX system. *Note Minimums::.
|
|
-- Macro: int ARG_MAX
|
If defined, the unvarying maximum combined length of the ARGV and
|
ENVIRON arguments that can be passed to the ‘exec’ functions.
|
|
-- Macro: int CHILD_MAX
|
If defined, the unvarying maximum number of processes that can
|
exist with the same real user ID at any one time. In BSD and GNU,
|
this is controlled by the ‘RLIMIT_NPROC’ resource limit; *note
|
Limits on Resources::.
|
|
-- Macro: int OPEN_MAX
|
If defined, the unvarying maximum number of files that a single
|
process can have open simultaneously. In BSD and GNU, this is
|
controlled by the ‘RLIMIT_NOFILE’ resource limit; *note Limits on
|
Resources::.
|
|
-- Macro: int STREAM_MAX
|
If defined, the unvarying maximum number of streams that a single
|
process can have open simultaneously. *Note Opening Streams::.
|
|
-- Macro: int TZNAME_MAX
|
If defined, the unvarying maximum length of a time zone name.
|
*Note Time Zone Functions::.
|
|
These limit macros are always defined in ‘limits.h’.
|
|
-- Macro: int NGROUPS_MAX
|
The maximum number of supplementary group IDs that one process can
|
have.
|
|
The value of this macro is actually a lower bound for the maximum.
|
That is, you can count on being able to have that many
|
supplementary group IDs, but a particular machine might let you
|
have even more. You can use ‘sysconf’ to see whether a particular
|
machine will let you have more (*note Sysconf::).
|
|
-- Macro: ssize_t SSIZE_MAX
|
The largest value that can fit in an object of type ‘ssize_t’.
|
Effectively, this is the limit on the number of bytes that can be
|
read or written in a single operation.
|
|
This macro is defined in all POSIX systems because this limit is
|
never configurable.
|
|
-- Macro: int RE_DUP_MAX
|
The largest number of repetitions you are guaranteed is allowed in
|
the construct ‘\{MIN,MAX\}’ in a regular expression.
|
|
The value of this macro is actually a lower bound for the maximum.
|
That is, you can count on being able to have that many repetitions,
|
but a particular machine might let you have even more. You can use
|
‘sysconf’ to see whether a particular machine will let you have
|
more (*note Sysconf::). And even the value that ‘sysconf’ tells
|
you is just a lower bound—larger values might work.
|
|
This macro is defined in all POSIX.2 systems, because POSIX.2 says
|
it should always be defined even if there is no specific imposed
|
limit.
|
|
|
File: libc.info, Node: System Options, Next: Version Supported, Prev: General Limits, Up: System Configuration
|
|
32.2 Overall System Options
|
===========================
|
|
POSIX defines certain system-specific options that not all POSIX systems
|
support. Since these options are provided in the kernel, not in the
|
library, simply using the GNU C Library does not guarantee any of these
|
features is supported; it depends on the system you are using.
|
|
You can test for the availability of a given option using the macros
|
in this section, together with the function ‘sysconf’. The macros are
|
defined only if you include ‘unistd.h’.
|
|
For the following macros, if the macro is defined in ‘unistd.h’, then
|
the option is supported. Otherwise, the option may or may not be
|
supported; use ‘sysconf’ to find out. *Note Sysconf::.
|
|
-- Macro: int _POSIX_JOB_CONTROL
|
If this symbol is defined, it indicates that the system supports
|
job control. Otherwise, the implementation behaves as if all
|
processes within a session belong to a single process group. *Note
|
Job Control::.
|
|
-- Macro: int _POSIX_SAVED_IDS
|
If this symbol is defined, it indicates that the system remembers
|
the effective user and group IDs of a process before it executes an
|
executable file with the set-user-ID or set-group-ID bits set, and
|
that explicitly changing the effective user or group IDs back to
|
these values is permitted. If this option is not defined, then if
|
a nonprivileged process changes its effective user or group ID to
|
the real user or group ID of the process, it can’t change it back
|
again. *Note Enable/Disable Setuid::.
|
|
For the following macros, if the macro is defined in ‘unistd.h’, then
|
its value indicates whether the option is supported. A value of ‘-1’
|
means no, and any other value means yes. If the macro is not defined,
|
then the option may or may not be supported; use ‘sysconf’ to find out.
|
*Note Sysconf::.
|
|
-- Macro: int _POSIX2_C_DEV
|
If this symbol is defined, it indicates that the system has the
|
POSIX.2 C compiler command, ‘c89’. The GNU C Library always
|
defines this as ‘1’, on the assumption that you would not have
|
installed it if you didn’t have a C compiler.
|
|
-- Macro: int _POSIX2_FORT_DEV
|
If this symbol is defined, it indicates that the system has the
|
POSIX.2 Fortran compiler command, ‘fort77’. The GNU C Library
|
never defines this, because we don’t know what the system has.
|
|
-- Macro: int _POSIX2_FORT_RUN
|
If this symbol is defined, it indicates that the system has the
|
POSIX.2 ‘asa’ command to interpret Fortran carriage control. The
|
GNU C Library never defines this, because we don’t know what the
|
system has.
|
|
-- Macro: int _POSIX2_LOCALEDEF
|
If this symbol is defined, it indicates that the system has the
|
POSIX.2 ‘localedef’ command. The GNU C Library never defines this,
|
because we don’t know what the system has.
|
|
-- Macro: int _POSIX2_SW_DEV
|
If this symbol is defined, it indicates that the system has the
|
POSIX.2 commands ‘ar’, ‘make’, and ‘strip’. The GNU C Library
|
always defines this as ‘1’, on the assumption that you had to have
|
‘ar’ and ‘make’ to install the library, and it’s unlikely that
|
‘strip’ would be absent when those are present.
|
|
|
File: libc.info, Node: Version Supported, Next: Sysconf, Prev: System Options, Up: System Configuration
|
|
32.3 Which Version of POSIX is Supported
|
========================================
|
|
-- Macro: long int _POSIX_VERSION
|
This constant represents the version of the POSIX.1 standard to
|
which the implementation conforms. For an implementation
|
conforming to the 1995 POSIX.1 standard, the value is the integer
|
‘199506L’.
|
|
‘_POSIX_VERSION’ is always defined (in ‘unistd.h’) in any POSIX
|
system.
|
|
*Usage Note:* Don’t try to test whether the system supports POSIX
|
by including ‘unistd.h’ and then checking whether ‘_POSIX_VERSION’
|
is defined. On a non-POSIX system, this will probably fail because
|
there is no ‘unistd.h’. We do not know of _any_ way you can
|
reliably test at compilation time whether your target system
|
supports POSIX or whether ‘unistd.h’ exists.
|
|
-- Macro: long int _POSIX2_C_VERSION
|
This constant represents the version of the POSIX.2 standard which
|
the library and system kernel support. We don’t know what value
|
this will be for the first version of the POSIX.2 standard, because
|
the value is based on the year and month in which the standard is
|
officially adopted.
|
|
The value of this symbol says nothing about the utilities installed
|
on the system.
|
|
*Usage Note:* You can use this macro to tell whether a POSIX.1
|
system library supports POSIX.2 as well. Any POSIX.1 system
|
contains ‘unistd.h’, so include that file and then test ‘defined
|
(_POSIX2_C_VERSION)’.
|
|
|
File: libc.info, Node: Sysconf, Next: Minimums, Prev: Version Supported, Up: System Configuration
|
|
32.4 Using ‘sysconf’
|
====================
|
|
When your system has configurable system limits, you can use the
|
‘sysconf’ function to find out the value that applies to any particular
|
machine. The function and the associated PARAMETER constants are
|
declared in the header file ‘unistd.h’.
|
|
* Menu:
|
|
* Sysconf Definition:: Detailed specifications of ‘sysconf’.
|
* Constants for Sysconf:: The list of parameters ‘sysconf’ can read.
|
* Examples of Sysconf:: How to use ‘sysconf’ and the parameter
|
macros properly together.
|
|
|
File: libc.info, Node: Sysconf Definition, Next: Constants for Sysconf, Up: Sysconf
|
|
32.4.1 Definition of ‘sysconf’
|
------------------------------
|
|
-- Function: long int sysconf (int PARAMETER)
|
Preliminary: | MT-Safe env | AS-Unsafe lock heap | AC-Unsafe lock
|
mem fd | *Note POSIX Safety Concepts::.
|
|
This function is used to inquire about runtime system parameters.
|
The PARAMETER argument should be one of the ‘_SC_’ symbols listed
|
below.
|
|
The normal return value from ‘sysconf’ is the value you requested.
|
A value of ‘-1’ is returned both if the implementation does not
|
impose a limit, and in case of an error.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EINVAL’
|
The value of the PARAMETER is invalid.
|
|
|
File: libc.info, Node: Constants for Sysconf, Next: Examples of Sysconf, Prev: Sysconf Definition, Up: Sysconf
|
|
32.4.2 Constants for ‘sysconf’ Parameters
|
-----------------------------------------
|
|
Here are the symbolic constants for use as the PARAMETER argument to
|
‘sysconf’. The values are all integer constants (more specifically,
|
enumeration type values).
|
|
‘_SC_ARG_MAX’
|
Inquire about the parameter corresponding to ‘ARG_MAX’.
|
|
‘_SC_CHILD_MAX’
|
Inquire about the parameter corresponding to ‘CHILD_MAX’.
|
|
‘_SC_OPEN_MAX’
|
Inquire about the parameter corresponding to ‘OPEN_MAX’.
|
|
‘_SC_STREAM_MAX’
|
Inquire about the parameter corresponding to ‘STREAM_MAX’.
|
|
‘_SC_TZNAME_MAX’
|
Inquire about the parameter corresponding to ‘TZNAME_MAX’.
|
|
‘_SC_NGROUPS_MAX’
|
Inquire about the parameter corresponding to ‘NGROUPS_MAX’.
|
|
‘_SC_JOB_CONTROL’
|
Inquire about the parameter corresponding to ‘_POSIX_JOB_CONTROL’.
|
|
‘_SC_SAVED_IDS’
|
Inquire about the parameter corresponding to ‘_POSIX_SAVED_IDS’.
|
|
‘_SC_VERSION’
|
Inquire about the parameter corresponding to ‘_POSIX_VERSION’.
|
|
‘_SC_CLK_TCK’
|
Inquire about the number of clock ticks per second; *note CPU
|
Time::. The corresponding parameter ‘CLK_TCK’ is obsolete.
|
|
‘_SC_CHARCLASS_NAME_MAX’
|
Inquire about the parameter corresponding to maximal length allowed
|
for a character class name in an extended locale specification.
|
These extensions are not yet standardized and so this option is not
|
standardized as well.
|
|
‘_SC_REALTIME_SIGNALS’
|
Inquire about the parameter corresponding to
|
‘_POSIX_REALTIME_SIGNALS’.
|
|
‘_SC_PRIORITY_SCHEDULING’
|
Inquire about the parameter corresponding to
|
‘_POSIX_PRIORITY_SCHEDULING’.
|
|
‘_SC_TIMERS’
|
Inquire about the parameter corresponding to ‘_POSIX_TIMERS’.
|
|
‘_SC_ASYNCHRONOUS_IO’
|
Inquire about the parameter corresponding to
|
‘_POSIX_ASYNCHRONOUS_IO’.
|
|
‘_SC_PRIORITIZED_IO’
|
Inquire about the parameter corresponding to
|
‘_POSIX_PRIORITIZED_IO’.
|
|
‘_SC_SYNCHRONIZED_IO’
|
Inquire about the parameter corresponding to
|
‘_POSIX_SYNCHRONIZED_IO’.
|
|
‘_SC_FSYNC’
|
Inquire about the parameter corresponding to ‘_POSIX_FSYNC’.
|
|
‘_SC_MAPPED_FILES’
|
Inquire about the parameter corresponding to ‘_POSIX_MAPPED_FILES’.
|
|
‘_SC_MEMLOCK’
|
Inquire about the parameter corresponding to ‘_POSIX_MEMLOCK’.
|
|
‘_SC_MEMLOCK_RANGE’
|
Inquire about the parameter corresponding to
|
‘_POSIX_MEMLOCK_RANGE’.
|
|
‘_SC_MEMORY_PROTECTION’
|
Inquire about the parameter corresponding to
|
‘_POSIX_MEMORY_PROTECTION’.
|
|
‘_SC_MESSAGE_PASSING’
|
Inquire about the parameter corresponding to
|
‘_POSIX_MESSAGE_PASSING’.
|
|
‘_SC_SEMAPHORES’
|
Inquire about the parameter corresponding to ‘_POSIX_SEMAPHORES’.
|
|
‘_SC_SHARED_MEMORY_OBJECTS’
|
Inquire about the parameter corresponding to
|
‘_POSIX_SHARED_MEMORY_OBJECTS’.
|
|
‘_SC_AIO_LISTIO_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_AIO_LISTIO_MAX’.
|
|
‘_SC_AIO_MAX’
|
Inquire about the parameter corresponding to ‘_POSIX_AIO_MAX’.
|
|
‘_SC_AIO_PRIO_DELTA_MAX’
|
Inquire the value by which a process can decrease its asynchronous
|
I/O priority level from its own scheduling priority. This
|
corresponds to the run-time invariant value ‘AIO_PRIO_DELTA_MAX’.
|
|
‘_SC_DELAYTIMER_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_DELAYTIMER_MAX’.
|
|
‘_SC_MQ_OPEN_MAX’
|
Inquire about the parameter corresponding to ‘_POSIX_MQ_OPEN_MAX’.
|
|
‘_SC_MQ_PRIO_MAX’
|
Inquire about the parameter corresponding to ‘_POSIX_MQ_PRIO_MAX’.
|
|
‘_SC_RTSIG_MAX’
|
Inquire about the parameter corresponding to ‘_POSIX_RTSIG_MAX’.
|
|
‘_SC_SEM_NSEMS_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_SEM_NSEMS_MAX’.
|
|
‘_SC_SEM_VALUE_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_SEM_VALUE_MAX’.
|
|
‘_SC_SIGQUEUE_MAX’
|
Inquire about the parameter corresponding to ‘_POSIX_SIGQUEUE_MAX’.
|
|
‘_SC_TIMER_MAX’
|
Inquire about the parameter corresponding to ‘_POSIX_TIMER_MAX’.
|
|
‘_SC_PII’
|
Inquire about the parameter corresponding to ‘_POSIX_PII’.
|
|
‘_SC_PII_XTI’
|
Inquire about the parameter corresponding to ‘_POSIX_PII_XTI’.
|
|
‘_SC_PII_SOCKET’
|
Inquire about the parameter corresponding to ‘_POSIX_PII_SOCKET’.
|
|
‘_SC_PII_INTERNET’
|
Inquire about the parameter corresponding to ‘_POSIX_PII_INTERNET’.
|
|
‘_SC_PII_OSI’
|
Inquire about the parameter corresponding to ‘_POSIX_PII_OSI’.
|
|
‘_SC_SELECT’
|
Inquire about the parameter corresponding to ‘_POSIX_SELECT’.
|
|
‘_SC_UIO_MAXIOV’
|
Inquire about the parameter corresponding to ‘_POSIX_UIO_MAXIOV’.
|
|
‘_SC_PII_INTERNET_STREAM’
|
Inquire about the parameter corresponding to
|
‘_POSIX_PII_INTERNET_STREAM’.
|
|
‘_SC_PII_INTERNET_DGRAM’
|
Inquire about the parameter corresponding to
|
‘_POSIX_PII_INTERNET_DGRAM’.
|
|
‘_SC_PII_OSI_COTS’
|
Inquire about the parameter corresponding to ‘_POSIX_PII_OSI_COTS’.
|
|
‘_SC_PII_OSI_CLTS’
|
Inquire about the parameter corresponding to ‘_POSIX_PII_OSI_CLTS’.
|
|
‘_SC_PII_OSI_M’
|
Inquire about the parameter corresponding to ‘_POSIX_PII_OSI_M’.
|
|
‘_SC_T_IOV_MAX’
|
Inquire the value of the value associated with the ‘T_IOV_MAX’
|
variable.
|
|
‘_SC_THREADS’
|
Inquire about the parameter corresponding to ‘_POSIX_THREADS’.
|
|
‘_SC_THREAD_SAFE_FUNCTIONS’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_SAFE_FUNCTIONS’.
|
|
‘_SC_GETGR_R_SIZE_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_GETGR_R_SIZE_MAX’.
|
|
‘_SC_GETPW_R_SIZE_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_GETPW_R_SIZE_MAX’.
|
|
‘_SC_LOGIN_NAME_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_LOGIN_NAME_MAX’.
|
|
‘_SC_TTY_NAME_MAX’
|
Inquire about the parameter corresponding to ‘_POSIX_TTY_NAME_MAX’.
|
|
‘_SC_THREAD_DESTRUCTOR_ITERATIONS’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_DESTRUCTOR_ITERATIONS’.
|
|
‘_SC_THREAD_KEYS_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_KEYS_MAX’.
|
|
‘_SC_THREAD_STACK_MIN’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_STACK_MIN’.
|
|
‘_SC_THREAD_THREADS_MAX’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_THREADS_MAX’.
|
|
‘_SC_THREAD_ATTR_STACKADDR’
|
Inquire about the parameter corresponding to
|
a ‘_POSIX_THREAD_ATTR_STACKADDR’.
|
|
‘_SC_THREAD_ATTR_STACKSIZE’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_ATTR_STACKSIZE’.
|
|
‘_SC_THREAD_PRIORITY_SCHEDULING’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_PRIORITY_SCHEDULING’.
|
|
‘_SC_THREAD_PRIO_INHERIT’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_PRIO_INHERIT’.
|
|
‘_SC_THREAD_PRIO_PROTECT’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_PRIO_PROTECT’.
|
|
‘_SC_THREAD_PROCESS_SHARED’
|
Inquire about the parameter corresponding to
|
‘_POSIX_THREAD_PROCESS_SHARED’.
|
|
‘_SC_2_C_DEV’
|
Inquire about whether the system has the POSIX.2 C compiler
|
command, ‘c89’.
|
|
‘_SC_2_FORT_DEV’
|
Inquire about whether the system has the POSIX.2 Fortran compiler
|
command, ‘fort77’.
|
|
‘_SC_2_FORT_RUN’
|
Inquire about whether the system has the POSIX.2 ‘asa’ command to
|
interpret Fortran carriage control.
|
|
‘_SC_2_LOCALEDEF’
|
Inquire about whether the system has the POSIX.2 ‘localedef’
|
command.
|
|
‘_SC_2_SW_DEV’
|
Inquire about whether the system has the POSIX.2 commands ‘ar’,
|
‘make’, and ‘strip’.
|
|
‘_SC_BC_BASE_MAX’
|
Inquire about the maximum value of ‘obase’ in the ‘bc’ utility.
|
|
‘_SC_BC_DIM_MAX’
|
Inquire about the maximum size of an array in the ‘bc’ utility.
|
|
‘_SC_BC_SCALE_MAX’
|
Inquire about the maximum value of ‘scale’ in the ‘bc’ utility.
|
|
‘_SC_BC_STRING_MAX’
|
Inquire about the maximum size of a string constant in the ‘bc’
|
utility.
|
|
‘_SC_COLL_WEIGHTS_MAX’
|
Inquire about the maximum number of weights that can necessarily be
|
used in defining the collating sequence for a locale.
|
|
‘_SC_EXPR_NEST_MAX’
|
Inquire about the maximum number of expressions nested within
|
parentheses when using the ‘expr’ utility.
|
|
‘_SC_LINE_MAX’
|
Inquire about the maximum size of a text line that the POSIX.2 text
|
utilities can handle.
|
|
‘_SC_EQUIV_CLASS_MAX’
|
Inquire about the maximum number of weights that can be assigned to
|
an entry of the ‘LC_COLLATE’ category ‘order’ keyword in a locale
|
definition. The GNU C Library does not presently support locale
|
definitions.
|
|
‘_SC_VERSION’
|
Inquire about the version number of POSIX.1 that the library and
|
kernel support.
|
|
‘_SC_2_VERSION’
|
Inquire about the version number of POSIX.2 that the system
|
utilities support.
|
|
‘_SC_PAGESIZE’
|
Inquire about the virtual memory page size of the machine.
|
‘getpagesize’ returns the same value (*note Query Memory
|
Parameters::).
|
|
‘_SC_NPROCESSORS_CONF’
|
Inquire about the number of configured processors.
|
|
‘_SC_NPROCESSORS_ONLN’
|
Inquire about the number of processors online.
|
|
‘_SC_PHYS_PAGES’
|
Inquire about the number of physical pages in the system.
|
|
‘_SC_AVPHYS_PAGES’
|
Inquire about the number of available physical pages in the system.
|
|
‘_SC_ATEXIT_MAX’
|
Inquire about the number of functions which can be registered as
|
termination functions for ‘atexit’; *note Cleanups on Exit::.
|
|
‘_SC_XOPEN_VERSION’
|
Inquire about the parameter corresponding to ‘_XOPEN_VERSION’.
|
|
‘_SC_XOPEN_XCU_VERSION’
|
Inquire about the parameter corresponding to ‘_XOPEN_XCU_VERSION’.
|
|
‘_SC_XOPEN_UNIX’
|
Inquire about the parameter corresponding to ‘_XOPEN_UNIX’.
|
|
‘_SC_XOPEN_REALTIME’
|
Inquire about the parameter corresponding to ‘_XOPEN_REALTIME’.
|
|
‘_SC_XOPEN_REALTIME_THREADS’
|
Inquire about the parameter corresponding to
|
‘_XOPEN_REALTIME_THREADS’.
|
|
‘_SC_XOPEN_LEGACY’
|
Inquire about the parameter corresponding to ‘_XOPEN_LEGACY’.
|
|
‘_SC_XOPEN_CRYPT’
|
Inquire about the parameter corresponding to ‘_XOPEN_CRYPT’.
|
|
‘_SC_XOPEN_ENH_I18N’
|
Inquire about the parameter corresponding to ‘_XOPEN_ENH_I18N’.
|
|
‘_SC_XOPEN_SHM’
|
Inquire about the parameter corresponding to ‘_XOPEN_SHM’.
|
|
‘_SC_XOPEN_XPG2’
|
Inquire about the parameter corresponding to ‘_XOPEN_XPG2’.
|
|
‘_SC_XOPEN_XPG3’
|
Inquire about the parameter corresponding to ‘_XOPEN_XPG3’.
|
|
‘_SC_XOPEN_XPG4’
|
Inquire about the parameter corresponding to ‘_XOPEN_XPG4’.
|
|
‘_SC_CHAR_BIT’
|
Inquire about the number of bits in a variable of type ‘char’.
|
|
‘_SC_CHAR_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘char’.
|
|
‘_SC_CHAR_MIN’
|
Inquire about the minimum value which can be stored in a variable
|
of type ‘char’.
|
|
‘_SC_INT_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘int’.
|
|
‘_SC_INT_MIN’
|
Inquire about the minimum value which can be stored in a variable
|
of type ‘int’.
|
|
‘_SC_LONG_BIT’
|
Inquire about the number of bits in a variable of type ‘long int’.
|
|
‘_SC_WORD_BIT’
|
Inquire about the number of bits in a variable of a register word.
|
|
‘_SC_MB_LEN_MAX’
|
Inquire the maximum length of a multi-byte representation of a wide
|
character value.
|
|
‘_SC_NZERO’
|
Inquire about the value used to internally represent the zero
|
priority level for the process execution.
|
|
‘SC_SSIZE_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘ssize_t’.
|
|
‘_SC_SCHAR_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘signed char’.
|
|
‘_SC_SCHAR_MIN’
|
Inquire about the minimum value which can be stored in a variable
|
of type ‘signed char’.
|
|
‘_SC_SHRT_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘short int’.
|
|
‘_SC_SHRT_MIN’
|
Inquire about the minimum value which can be stored in a variable
|
of type ‘short int’.
|
|
‘_SC_UCHAR_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘unsigned char’.
|
|
‘_SC_UINT_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘unsigned int’.
|
|
‘_SC_ULONG_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘unsigned long int’.
|
|
‘_SC_USHRT_MAX’
|
Inquire about the maximum value which can be stored in a variable
|
of type ‘unsigned short int’.
|
|
‘_SC_NL_ARGMAX’
|
Inquire about the parameter corresponding to ‘NL_ARGMAX’.
|
|
‘_SC_NL_LANGMAX’
|
Inquire about the parameter corresponding to ‘NL_LANGMAX’.
|
|
‘_SC_NL_MSGMAX’
|
Inquire about the parameter corresponding to ‘NL_MSGMAX’.
|
|
‘_SC_NL_NMAX’
|
Inquire about the parameter corresponding to ‘NL_NMAX’.
|
|
‘_SC_NL_SETMAX’
|
Inquire about the parameter corresponding to ‘NL_SETMAX’.
|
|
‘_SC_NL_TEXTMAX’
|
Inquire about the parameter corresponding to ‘NL_TEXTMAX’.
|
|
|
File: libc.info, Node: Examples of Sysconf, Prev: Constants for Sysconf, Up: Sysconf
|
|
32.4.3 Examples of ‘sysconf’
|
----------------------------
|
|
We recommend that you first test for a macro definition for the
|
parameter you are interested in, and call ‘sysconf’ only if the macro is
|
not defined. For example, here is how to test whether job control is
|
supported:
|
|
int
|
have_job_control (void)
|
{
|
#ifdef _POSIX_JOB_CONTROL
|
return 1;
|
#else
|
int value = sysconf (_SC_JOB_CONTROL);
|
if (value < 0)
|
/* If the system is that badly wedged,
|
there’s no use trying to go on. */
|
fatal (strerror (errno));
|
return value;
|
#endif
|
}
|
|
Here is how to get the value of a numeric limit:
|
|
int
|
get_child_max ()
|
{
|
#ifdef CHILD_MAX
|
return CHILD_MAX;
|
#else
|
int value = sysconf (_SC_CHILD_MAX);
|
if (value < 0)
|
fatal (strerror (errno));
|
return value;
|
#endif
|
}
|
|
|
File: libc.info, Node: Minimums, Next: Limits for Files, Prev: Sysconf, Up: System Configuration
|
|
32.5 Minimum Values for General Capacity Limits
|
===============================================
|
|
Here are the names for the POSIX minimum upper bounds for the system
|
limit parameters. The significance of these values is that you can
|
safely push to these limits without checking whether the particular
|
system you are using can go that far.
|
|
‘_POSIX_AIO_LISTIO_MAX’
|
The most restrictive limit permitted by POSIX for the maximum
|
number of I/O operations that can be specified in a list I/O call.
|
The value of this constant is ‘2’; thus you can add up to two new
|
entries of the list of outstanding operations.
|
|
‘_POSIX_AIO_MAX’
|
The most restrictive limit permitted by POSIX for the maximum
|
number of outstanding asynchronous I/O operations. The value of
|
this constant is ‘1’. So you cannot expect that you can issue more
|
than one operation and immediately continue with the normal work,
|
receiving the notifications asynchronously.
|
|
‘_POSIX_ARG_MAX’
|
The value of this macro is the most restrictive limit permitted by
|
POSIX for the maximum combined length of the ARGV and ENVIRON
|
arguments that can be passed to the ‘exec’ functions. Its value is
|
‘4096’.
|
|
‘_POSIX_CHILD_MAX’
|
The value of this macro is the most restrictive limit permitted by
|
POSIX for the maximum number of simultaneous processes per real
|
user ID. Its value is ‘6’.
|
|
‘_POSIX_NGROUPS_MAX’
|
The value of this macro is the most restrictive limit permitted by
|
POSIX for the maximum number of supplementary group IDs per
|
process. Its value is ‘0’.
|
|
‘_POSIX_OPEN_MAX’
|
The value of this macro is the most restrictive limit permitted by
|
POSIX for the maximum number of files that a single process can
|
have open simultaneously. Its value is ‘16’.
|
|
‘_POSIX_SSIZE_MAX’
|
The value of this macro is the most restrictive limit permitted by
|
POSIX for the maximum value that can be stored in an object of type
|
‘ssize_t’. Its value is ‘32767’.
|
|
‘_POSIX_STREAM_MAX’
|
The value of this macro is the most restrictive limit permitted by
|
POSIX for the maximum number of streams that a single process can
|
have open simultaneously. Its value is ‘8’.
|
|
‘_POSIX_TZNAME_MAX’
|
The value of this macro is the most restrictive limit permitted by
|
POSIX for the maximum length of a time zone name. Its value is
|
‘3’.
|
|
‘_POSIX2_RE_DUP_MAX’
|
The value of this macro is the most restrictive limit permitted by
|
POSIX for the numbers used in the ‘\{MIN,MAX\}’ construct in a
|
regular expression. Its value is ‘255’.
|
|
|
File: libc.info, Node: Limits for Files, Next: Options for Files, Prev: Minimums, Up: System Configuration
|
|
32.6 Limits on File System Capacity
|
===================================
|
|
The POSIX.1 standard specifies a number of parameters that describe the
|
limitations of the file system. It’s possible for the system to have a
|
fixed, uniform limit for a parameter, but this isn’t the usual case. On
|
most systems, it’s possible for different file systems (and, for some
|
parameters, even different files) to have different maximum limits. For
|
example, this is very likely if you use NFS to mount some of the file
|
systems from other machines.
|
|
Each of the following macros is defined in ‘limits.h’ only if the
|
system has a fixed, uniform limit for the parameter in question. If the
|
system allows different file systems or files to have different limits,
|
then the macro is undefined; use ‘pathconf’ or ‘fpathconf’ to find out
|
the limit that applies to a particular file. *Note Pathconf::.
|
|
Each parameter also has another macro, with a name starting with
|
‘_POSIX’, which gives the lowest value that the limit is allowed to have
|
on _any_ POSIX system. *Note File Minimums::.
|
|
-- Macro: int LINK_MAX
|
The uniform system limit (if any) for the number of names for a
|
given file. *Note Hard Links::.
|
|
-- Macro: int MAX_CANON
|
The uniform system limit (if any) for the amount of text in a line
|
of input when input editing is enabled. *Note Canonical or Not::.
|
|
-- Macro: int MAX_INPUT
|
The uniform system limit (if any) for the total number of
|
characters typed ahead as input. *Note I/O Queues::.
|
|
-- Macro: int NAME_MAX
|
The uniform system limit (if any) for the length of a file name
|
component, not including the terminating null character.
|
|
*Portability Note:* On some systems, the GNU C Library defines
|
‘NAME_MAX’, but does not actually enforce this limit.
|
|
-- Macro: int PATH_MAX
|
The uniform system limit (if any) for the length of an entire file
|
name (that is, the argument given to system calls such as ‘open’),
|
including the terminating null character.
|
|
*Portability Note:* The GNU C Library does not enforce this limit
|
even if ‘PATH_MAX’ is defined.
|
|
-- Macro: int PIPE_BUF
|
The uniform system limit (if any) for the number of bytes that can
|
be written atomically to a pipe. If multiple processes are writing
|
to the same pipe simultaneously, output from different processes
|
might be interleaved in chunks of this size. *Note Pipes and
|
FIFOs::.
|
|
These are alternative macro names for some of the same information.
|
|
-- Macro: int MAXNAMLEN
|
This is the BSD name for ‘NAME_MAX’. It is defined in ‘dirent.h’.
|
|
-- Macro: int FILENAME_MAX
|
The value of this macro is an integer constant expression that
|
represents the maximum length of a file name string. It is defined
|
in ‘stdio.h’.
|
|
Unlike ‘PATH_MAX’, this macro is defined even if there is no actual
|
limit imposed. In such a case, its value is typically a very large
|
number. *This is always the case on GNU/Hurd systems.*
|
|
*Usage Note:* Don’t use ‘FILENAME_MAX’ as the size of an array in
|
which to store a file name! You can’t possibly make an array that
|
big! Use dynamic allocation (*note Memory Allocation::) instead.
|
|
|
File: libc.info, Node: Options for Files, Next: File Minimums, Prev: Limits for Files, Up: System Configuration
|
|
32.7 Optional Features in File Support
|
======================================
|
|
POSIX defines certain system-specific options in the system calls for
|
operating on files. Some systems support these options and others do
|
not. Since these options are provided in the kernel, not in the
|
library, simply using the GNU C Library does not guarantee that any of
|
these features is supported; it depends on the system you are using.
|
They can also vary between file systems on a single machine.
|
|
This section describes the macros you can test to determine whether a
|
particular option is supported on your machine. If a given macro is
|
defined in ‘unistd.h’, then its value says whether the corresponding
|
feature is supported. (A value of ‘-1’ indicates no; any other value
|
indicates yes.) If the macro is undefined, it means particular files
|
may or may not support the feature.
|
|
Since all the machines that support the GNU C Library also support
|
NFS, one can never make a general statement about whether all file
|
systems support the ‘_POSIX_CHOWN_RESTRICTED’ and ‘_POSIX_NO_TRUNC’
|
features. So these names are never defined as macros in the GNU C
|
Library.
|
|
-- Macro: int _POSIX_CHOWN_RESTRICTED
|
If this option is in effect, the ‘chown’ function is restricted so
|
that the only changes permitted to nonprivileged processes is to
|
change the group owner of a file to either be the effective group
|
ID of the process, or one of its supplementary group IDs. *Note
|
File Owner::.
|
|
-- Macro: int _POSIX_NO_TRUNC
|
If this option is in effect, file name components longer than
|
‘NAME_MAX’ generate an ‘ENAMETOOLONG’ error. Otherwise, file name
|
components that are too long are silently truncated.
|
|
-- Macro: unsigned char _POSIX_VDISABLE
|
This option is only meaningful for files that are terminal devices.
|
If it is enabled, then handling for special control characters can
|
be disabled individually. *Note Special Characters::.
|
|
If one of these macros is undefined, that means that the option might
|
be in effect for some files and not for others. To inquire about a
|
particular file, call ‘pathconf’ or ‘fpathconf’. *Note Pathconf::.
|
|
|
File: libc.info, Node: File Minimums, Next: Pathconf, Prev: Options for Files, Up: System Configuration
|
|
32.8 Minimum Values for File System Limits
|
==========================================
|
|
Here are the names for the POSIX minimum upper bounds for some of the
|
above parameters. The significance of these values is that you can
|
safely push to these limits without checking whether the particular
|
system you are using can go that far. In most cases GNU systems do not
|
have these strict limitations. The actual limit should be requested if
|
necessary.
|
|
‘_POSIX_LINK_MAX’
|
The most restrictive limit permitted by POSIX for the maximum value
|
of a file’s link count. The value of this constant is ‘8’; thus,
|
you can always make up to eight names for a file without running
|
into a system limit.
|
|
‘_POSIX_MAX_CANON’
|
The most restrictive limit permitted by POSIX for the maximum
|
number of bytes in a canonical input line from a terminal device.
|
The value of this constant is ‘255’.
|
|
‘_POSIX_MAX_INPUT’
|
The most restrictive limit permitted by POSIX for the maximum
|
number of bytes in a terminal device input queue (or typeahead
|
buffer). *Note Input Modes::. The value of this constant is
|
‘255’.
|
|
‘_POSIX_NAME_MAX’
|
The most restrictive limit permitted by POSIX for the maximum
|
number of bytes in a file name component. The value of this
|
constant is ‘14’.
|
|
‘_POSIX_PATH_MAX’
|
The most restrictive limit permitted by POSIX for the maximum
|
number of bytes in a file name. The value of this constant is
|
‘256’.
|
|
‘_POSIX_PIPE_BUF’
|
The most restrictive limit permitted by POSIX for the maximum
|
number of bytes that can be written atomically to a pipe. The
|
value of this constant is ‘512’.
|
|
‘SYMLINK_MAX’
|
Maximum number of bytes in a symbolic link.
|
|
‘POSIX_REC_INCR_XFER_SIZE’
|
Recommended increment for file transfer sizes between the
|
‘POSIX_REC_MIN_XFER_SIZE’ and ‘POSIX_REC_MAX_XFER_SIZE’ values.
|
|
‘POSIX_REC_MAX_XFER_SIZE’
|
Maximum recommended file transfer size.
|
|
‘POSIX_REC_MIN_XFER_SIZE’
|
Minimum recommended file transfer size.
|
|
‘POSIX_REC_XFER_ALIGN’
|
Recommended file transfer buffer alignment.
|
|
|
File: libc.info, Node: Pathconf, Next: Utility Limits, Prev: File Minimums, Up: System Configuration
|
|
32.9 Using ‘pathconf’
|
=====================
|
|
When your machine allows different files to have different values for a
|
file system parameter, you can use the functions in this section to find
|
out the value that applies to any particular file.
|
|
These functions and the associated constants for the PARAMETER
|
argument are declared in the header file ‘unistd.h’.
|
|
-- Function: long int pathconf (const char *FILENAME, int PARAMETER)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock fd
|
mem | *Note POSIX Safety Concepts::.
|
|
This function is used to inquire about the limits that apply to the
|
file named FILENAME.
|
|
The PARAMETER argument should be one of the ‘_PC_’ constants listed
|
below.
|
|
The normal return value from ‘pathconf’ is the value you requested.
|
A value of ‘-1’ is returned both if the implementation does not
|
impose a limit, and in case of an error. In the former case,
|
‘errno’ is not set, while in the latter case, ‘errno’ is set to
|
indicate the cause of the problem. So the only way to use this
|
function robustly is to store ‘0’ into ‘errno’ just before calling
|
it.
|
|
Besides the usual file name errors (*note File Name Errors::), the
|
following error condition is defined for this function:
|
|
‘EINVAL’
|
The value of PARAMETER is invalid, or the implementation
|
doesn’t support the PARAMETER for the specific file.
|
|
-- Function: long int fpathconf (int FILEDES, int PARAMETER)
|
Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock fd
|
mem | *Note POSIX Safety Concepts::.
|
|
This is just like ‘pathconf’ except that an open file descriptor is
|
used to specify the file for which information is requested,
|
instead of a file name.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor.
|
|
‘EINVAL’
|
The value of PARAMETER is invalid, or the implementation
|
doesn’t support the PARAMETER for the specific file.
|
|
Here are the symbolic constants that you can use as the PARAMETER
|
argument to ‘pathconf’ and ‘fpathconf’. The values are all integer
|
constants.
|
|
‘_PC_LINK_MAX’
|
Inquire about the value of ‘LINK_MAX’.
|
|
‘_PC_MAX_CANON’
|
Inquire about the value of ‘MAX_CANON’.
|
|
‘_PC_MAX_INPUT’
|
Inquire about the value of ‘MAX_INPUT’.
|
|
‘_PC_NAME_MAX’
|
Inquire about the value of ‘NAME_MAX’.
|
|
‘_PC_PATH_MAX’
|
Inquire about the value of ‘PATH_MAX’.
|
|
‘_PC_PIPE_BUF’
|
Inquire about the value of ‘PIPE_BUF’.
|
|
‘_PC_CHOWN_RESTRICTED’
|
Inquire about the value of ‘_POSIX_CHOWN_RESTRICTED’.
|
|
‘_PC_NO_TRUNC’
|
Inquire about the value of ‘_POSIX_NO_TRUNC’.
|
|
‘_PC_VDISABLE’
|
Inquire about the value of ‘_POSIX_VDISABLE’.
|
|
‘_PC_SYNC_IO’
|
Inquire about the value of ‘_POSIX_SYNC_IO’.
|
|
‘_PC_ASYNC_IO’
|
Inquire about the value of ‘_POSIX_ASYNC_IO’.
|
|
‘_PC_PRIO_IO’
|
Inquire about the value of ‘_POSIX_PRIO_IO’.
|
|
‘_PC_FILESIZEBITS’
|
Inquire about the availability of large files on the filesystem.
|
|
‘_PC_REC_INCR_XFER_SIZE’
|
Inquire about the value of ‘POSIX_REC_INCR_XFER_SIZE’.
|
|
‘_PC_REC_MAX_XFER_SIZE’
|
Inquire about the value of ‘POSIX_REC_MAX_XFER_SIZE’.
|
|
‘_PC_REC_MIN_XFER_SIZE’
|
Inquire about the value of ‘POSIX_REC_MIN_XFER_SIZE’.
|
|
‘_PC_REC_XFER_ALIGN’
|
Inquire about the value of ‘POSIX_REC_XFER_ALIGN’.
|
|
*Portability Note:* On some systems, the GNU C Library does not
|
enforce ‘_PC_NAME_MAX’ or ‘_PC_PATH_MAX’ limits.
|
|
|
File: libc.info, Node: Utility Limits, Next: Utility Minimums, Prev: Pathconf, Up: System Configuration
|
|
32.10 Utility Program Capacity Limits
|
=====================================
|
|
The POSIX.2 standard specifies certain system limits that you can access
|
through ‘sysconf’ that apply to utility behavior rather than the
|
behavior of the library or the operating system.
|
|
The GNU C Library defines macros for these limits, and ‘sysconf’
|
returns values for them if you ask; but these values convey no
|
meaningful information. They are simply the smallest values that
|
POSIX.2 permits.
|
|
-- Macro: int BC_BASE_MAX
|
The largest value of ‘obase’ that the ‘bc’ utility is guaranteed to
|
support.
|
|
-- Macro: int BC_DIM_MAX
|
The largest number of elements in one array that the ‘bc’ utility
|
is guaranteed to support.
|
|
-- Macro: int BC_SCALE_MAX
|
The largest value of ‘scale’ that the ‘bc’ utility is guaranteed to
|
support.
|
|
-- Macro: int BC_STRING_MAX
|
The largest number of characters in one string constant that the
|
‘bc’ utility is guaranteed to support.
|
|
-- Macro: int COLL_WEIGHTS_MAX
|
The largest number of weights that can necessarily be used in
|
defining the collating sequence for a locale.
|
|
-- Macro: int EXPR_NEST_MAX
|
The maximum number of expressions that can be nested within
|
parenthesis by the ‘expr’ utility.
|
|
-- Macro: int LINE_MAX
|
The largest text line that the text-oriented POSIX.2 utilities can
|
support. (If you are using the GNU versions of these utilities,
|
then there is no actual limit except that imposed by the available
|
virtual memory, but there is no way that the library can tell you
|
this.)
|
|
-- Macro: int EQUIV_CLASS_MAX
|
The maximum number of weights that can be assigned to an entry of
|
the ‘LC_COLLATE’ category ‘order’ keyword in a locale definition.
|
The GNU C Library does not presently support locale definitions.
|
|
|
File: libc.info, Node: Utility Minimums, Next: String Parameters, Prev: Utility Limits, Up: System Configuration
|
|
32.11 Minimum Values for Utility Limits
|
=======================================
|
|
‘_POSIX2_BC_BASE_MAX’
|
The most restrictive limit permitted by POSIX.2 for the maximum
|
value of ‘obase’ in the ‘bc’ utility. Its value is ‘99’.
|
|
‘_POSIX2_BC_DIM_MAX’
|
The most restrictive limit permitted by POSIX.2 for the maximum
|
size of an array in the ‘bc’ utility. Its value is ‘2048’.
|
|
‘_POSIX2_BC_SCALE_MAX’
|
The most restrictive limit permitted by POSIX.2 for the maximum
|
value of ‘scale’ in the ‘bc’ utility. Its value is ‘99’.
|
|
‘_POSIX2_BC_STRING_MAX’
|
The most restrictive limit permitted by POSIX.2 for the maximum
|
size of a string constant in the ‘bc’ utility. Its value is
|
‘1000’.
|
|
‘_POSIX2_COLL_WEIGHTS_MAX’
|
The most restrictive limit permitted by POSIX.2 for the maximum
|
number of weights that can necessarily be used in defining the
|
collating sequence for a locale. Its value is ‘2’.
|
|
‘_POSIX2_EXPR_NEST_MAX’
|
The most restrictive limit permitted by POSIX.2 for the maximum
|
number of expressions nested within parenthesis when using the
|
‘expr’ utility. Its value is ‘32’.
|
|
‘_POSIX2_LINE_MAX’
|
The most restrictive limit permitted by POSIX.2 for the maximum
|
size of a text line that the text utilities can handle. Its value
|
is ‘2048’.
|
|
‘_POSIX2_EQUIV_CLASS_MAX’
|
The most restrictive limit permitted by POSIX.2 for the maximum
|
number of weights that can be assigned to an entry of the
|
‘LC_COLLATE’ category ‘order’ keyword in a locale definition. Its
|
value is ‘2’. The GNU C Library does not presently support locale
|
definitions.
|
|
|
File: libc.info, Node: String Parameters, Prev: Utility Minimums, Up: System Configuration
|
|
32.12 String-Valued Parameters
|
==============================
|
|
POSIX.2 defines a way to get string-valued parameters from the operating
|
system with the function ‘confstr’:
|
|
-- Function: size_t confstr (int PARAMETER, char *BUF, size_t LEN)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function reads the value of a string-valued system parameter,
|
storing the string into LEN bytes of memory space starting at BUF.
|
The PARAMETER argument should be one of the ‘_CS_’ symbols listed
|
below.
|
|
The normal return value from ‘confstr’ is the length of the string
|
value that you asked for. If you supply a null pointer for BUF,
|
then ‘confstr’ does not try to store the string; it just returns
|
its length. A value of ‘0’ indicates an error.
|
|
If the string you asked for is too long for the buffer (that is,
|
longer than ‘LEN - 1’), then ‘confstr’ stores just that much
|
(leaving room for the terminating null character). You can tell
|
that this has happened because ‘confstr’ returns a value greater
|
than or equal to LEN.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EINVAL’
|
The value of the PARAMETER is invalid.
|
|
Currently there is just one parameter you can read with ‘confstr’:
|
|
‘_CS_PATH’
|
This parameter’s value is the recommended default path for
|
searching for executable files. This is the path that a user has
|
by default just after logging in.
|
|
‘_CS_LFS_CFLAGS’
|
The returned string specifies which additional flags must be given
|
to the C compiler if a source is compiled using the
|
‘_LARGEFILE_SOURCE’ feature select macro; *note Feature Test
|
Macros::.
|
|
‘_CS_LFS_LDFLAGS’
|
The returned string specifies which additional flags must be given
|
to the linker if a source is compiled using the ‘_LARGEFILE_SOURCE’
|
feature select macro; *note Feature Test Macros::.
|
|
‘_CS_LFS_LIBS’
|
The returned string specifies which additional libraries must be
|
linked to the application if a source is compiled using the
|
‘_LARGEFILE_SOURCE’ feature select macro; *note Feature Test
|
Macros::.
|
|
‘_CS_LFS_LINTFLAGS’
|
The returned string specifies which additional flags must be given
|
to the lint tool if a source is compiled using the
|
‘_LARGEFILE_SOURCE’ feature select macro; *note Feature Test
|
Macros::.
|
|
‘_CS_LFS64_CFLAGS’
|
The returned string specifies which additional flags must be given
|
to the C compiler if a source is compiled using the
|
‘_LARGEFILE64_SOURCE’ feature select macro; *note Feature Test
|
Macros::.
|
|
‘_CS_LFS64_LDFLAGS’
|
The returned string specifies which additional flags must be given
|
to the linker if a source is compiled using the
|
‘_LARGEFILE64_SOURCE’ feature select macro; *note Feature Test
|
Macros::.
|
|
‘_CS_LFS64_LIBS’
|
The returned string specifies which additional libraries must be
|
linked to the application if a source is compiled using the
|
‘_LARGEFILE64_SOURCE’ feature select macro; *note Feature Test
|
Macros::.
|
|
‘_CS_LFS64_LINTFLAGS’
|
The returned string specifies which additional flags must be given
|
to the lint tool if a source is compiled using the
|
‘_LARGEFILE64_SOURCE’ feature select macro; *note Feature Test
|
Macros::.
|
|
The way to use ‘confstr’ without any arbitrary limit on string size
|
is to call it twice: first call it to get the length, allocate the
|
buffer accordingly, and then call ‘confstr’ again to fill the buffer,
|
like this:
|
|
char *
|
get_default_path (void)
|
{
|
size_t len = confstr (_CS_PATH, NULL, 0);
|
char *buffer = (char *) xmalloc (len);
|
|
if (confstr (_CS_PATH, buf, len + 1) == 0)
|
{
|
free (buffer);
|
return NULL;
|
}
|
|
return buffer;
|
}
|
|
|
File: libc.info, Node: Cryptographic Functions, Next: Debugging Support, Prev: System Configuration, Up: Top
|
|
33 DES Encryption and Password Handling
|
***************************************
|
|
On many systems, it is unnecessary to have any kind of user
|
authentication; for instance, a workstation which is not connected to a
|
network probably does not need any user authentication, because to use
|
the machine an intruder must have physical access.
|
|
Sometimes, however, it is necessary to be sure that a user is
|
authorized to use some service a machine provides—for instance, to log
|
in as a particular user id (*note Users and Groups::). One traditional
|
way of doing this is for each user to choose a secret "password"; then,
|
the system can ask someone claiming to be a user what the user’s
|
password is, and if the person gives the correct password then the
|
system can grant the appropriate privileges.
|
|
If all the passwords are just stored in a file somewhere, then this
|
file has to be very carefully protected. To avoid this, passwords are
|
run through a "one-way function", a function which makes it difficult to
|
work out what its input was by looking at its output, before storing in
|
the file.
|
|
The GNU C Library provides a one-way function that is compatible with
|
the behavior of the ‘crypt’ function introduced in FreeBSD 2.0. It
|
supports two one-way algorithms: one based on the MD5 message-digest
|
algorithm that is compatible with modern BSD systems, and the other
|
based on the Data Encryption Standard (DES) that is compatible with Unix
|
systems.
|
|
It also provides support for Secure RPC, and some library functions
|
that can be used to perform normal DES encryption. The ‘AUTH_DES’
|
authentication flavor in Secure RPC, as provided by the GNU C Library,
|
uses DES and does not comply with FIPS 140-2 nor does any other use of
|
DES within the GNU C Library. It is recommended that Secure RPC should
|
not be used for systems that need to comply with FIPS 140-2 since all
|
flavors of encrypted authentication use normal DES.
|
|
* Menu:
|
|
* Legal Problems:: This software can get you locked up, or worse.
|
* getpass:: Prompting the user for a password.
|
* crypt:: A one-way function for passwords.
|
* DES Encryption:: Routines for DES encryption.
|
|
|
File: libc.info, Node: Legal Problems, Next: getpass, Up: Cryptographic Functions
|
|
33.1 Legal Problems
|
===================
|
|
Because of the continuously changing state of the law, it’s not possible
|
to provide a definitive survey of the laws affecting cryptography.
|
Instead, this section warns you of some of the known trouble spots; this
|
may help you when you try to find out what the laws of your country are.
|
|
Some countries require that you have a licence to use, possess, or
|
import cryptography. These countries are believed to include
|
Byelorussia, Burma, India, Indonesia, Israel, Kazakhstan, Pakistan,
|
Russia, and Saudi Arabia.
|
|
Some countries restrict the transmission of encrypted messages by
|
radio; some telecommunications carriers restrict the transmission of
|
encrypted messages over their network.
|
|
Many countries have some form of export control for encryption
|
software. The Wassenaar Arrangement is a multilateral agreement between
|
33 countries (Argentina, Australia, Austria, Belgium, Bulgaria, Canada,
|
the Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary,
|
Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway,
|
Poland, Portugal, the Republic of Korea, Romania, the Russian
|
Federation, the Slovak Republic, Spain, Sweden, Switzerland, Turkey,
|
Ukraine, the United Kingdom and the United States) which restricts some
|
kinds of encryption exports. Different countries apply the arrangement
|
in different ways; some do not allow the exception for certain kinds of
|
“public domain” software (which would include this library), some only
|
restrict the export of software in tangible form, and others impose
|
significant additional restrictions.
|
|
The United States has additional rules. This software would
|
generally be exportable under 15 CFR 740.13(e), which permits exports of
|
“encryption source code” which is “publicly available” and which is “not
|
subject to an express agreement for the payment of a licensing fee or
|
royalty for commercial production or sale of any product developed with
|
the source code” to most countries.
|
|
The rules in this area are continuously changing. If you know of any
|
information in this manual that is out-of-date, please report it to the
|
bug database. *Note Reporting Bugs::.
|
|
|
File: libc.info, Node: getpass, Next: crypt, Prev: Legal Problems, Up: Cryptographic Functions
|
|
33.2 Reading Passwords
|
======================
|
|
When reading in a password, it is desirable to avoid displaying it on
|
the screen, to help keep it secret. The following function handles this
|
in a convenient way.
|
|
-- Function: char * getpass (const char *PROMPT)
|
Preliminary: | MT-Unsafe term | AS-Unsafe heap lock corrupt |
|
AC-Unsafe term lock corrupt | *Note POSIX Safety Concepts::.
|
|
‘getpass’ outputs PROMPT, then reads a string in from the terminal
|
without echoing it. It tries to connect to the real terminal,
|
‘/dev/tty’, if possible, to encourage users not to put plaintext
|
passwords in files; otherwise, it uses ‘stdin’ and ‘stderr’.
|
‘getpass’ also disables the INTR, QUIT, and SUSP characters on the
|
terminal using the ‘ISIG’ terminal attribute (*note Local Modes::).
|
The terminal is flushed before and after ‘getpass’, so that
|
characters of a mistyped password are not accidentally visible.
|
|
In other C libraries, ‘getpass’ may only return the first
|
‘PASS_MAX’ bytes of a password. The GNU C Library has no limit, so
|
‘PASS_MAX’ is undefined.
|
|
The prototype for this function is in ‘unistd.h’. ‘PASS_MAX’ would
|
be defined in ‘limits.h’.
|
|
This precise set of operations may not suit all possible situations.
|
In this case, it is recommended that users write their own ‘getpass’
|
substitute. For instance, a very simple substitute is as follows:
|
|
|
#include <termios.h>
|
#include <stdio.h>
|
|
ssize_t
|
my_getpass (char **lineptr, size_t *n, FILE *stream)
|
{
|
struct termios old, new;
|
int nread;
|
|
/* Turn echoing off and fail if we can’t. */
|
if (tcgetattr (fileno (stream), &old) != 0)
|
return -1;
|
new = old;
|
new.c_lflag &= ~ECHO;
|
if (tcsetattr (fileno (stream), TCSAFLUSH, &new) != 0)
|
return -1;
|
|
/* Read the password. */
|
nread = getline (lineptr, n, stream);
|
|
/* Restore terminal. */
|
(void) tcsetattr (fileno (stream), TCSAFLUSH, &old);
|
|
return nread;
|
}
|
|
The substitute takes the same parameters as ‘getline’ (*note Line
|
Input::); the user must print any prompt desired.
|
|
|
File: libc.info, Node: crypt, Next: DES Encryption, Prev: getpass, Up: Cryptographic Functions
|
|
33.3 Encrypting Passwords
|
=========================
|
|
-- Function: char * crypt (const char *KEY, const char *SALT)
|
Preliminary: | MT-Unsafe race:crypt | AS-Unsafe corrupt lock heap
|
dlopen | AC-Unsafe lock mem | *Note POSIX Safety Concepts::.
|
|
The ‘crypt’ function takes a password, KEY, as a string, and a SALT
|
character array which is described below, and returns a printable
|
ASCII string which starts with another salt. It is believed that,
|
given the output of the function, the best way to find a KEY that
|
will produce that output is to guess values of KEY until the
|
original value of KEY is found.
|
|
The SALT parameter does two things. Firstly, it selects which
|
algorithm is used, the MD5-based one or the DES-based one.
|
Secondly, it makes life harder for someone trying to guess
|
passwords against a file containing many passwords; without a SALT,
|
an intruder can make a guess, run ‘crypt’ on it once, and compare
|
the result with all the passwords. With a SALT, the intruder must
|
run ‘crypt’ once for each different salt.
|
|
For the MD5-based algorithm, the SALT should consist of the string
|
‘$1$’, followed by up to 8 characters, terminated by either another
|
‘$’ or the end of the string. The result of ‘crypt’ will be the
|
SALT, followed by a ‘$’ if the salt didn’t end with one, followed
|
by 22 characters from the alphabet ‘./0-9A-Za-z’, up to 34
|
characters total. Every character in the KEY is significant.
|
|
For the DES-based algorithm, the SALT should consist of two
|
characters from the alphabet ‘./0-9A-Za-z’, and the result of
|
‘crypt’ will be those two characters followed by 11 more from the
|
same alphabet, 13 in total. Only the first 8 characters in the KEY
|
are significant.
|
|
The MD5-based algorithm has no limit on the useful length of the
|
password used, and is slightly more secure. It is therefore
|
preferred over the DES-based algorithm.
|
|
When the user enters their password for the first time, the SALT
|
should be set to a new string which is reasonably random. To
|
verify a password against the result of a previous call to ‘crypt’,
|
pass the result of the previous call as the SALT.
|
|
The following short program is an example of how to use ‘crypt’ the
|
first time a password is entered. Note that the SALT generation is just
|
barely acceptable; in particular, it is not unique between machines, and
|
in many applications it would not be acceptable to let an attacker know
|
what time the user’s password was last set.
|
|
|
#include <stdio.h>
|
#include <time.h>
|
#include <unistd.h>
|
#include <crypt.h>
|
|
int
|
main(void)
|
{
|
unsigned long seed[2];
|
char salt[] = "$1$........";
|
const char *const seedchars =
|
"./0123456789ABCDEFGHIJKLMNOPQRST"
|
"UVWXYZabcdefghijklmnopqrstuvwxyz";
|
char *password;
|
int i;
|
|
/* Generate a (not very) random seed.
|
You should do it better than this... */
|
seed[0] = time(NULL);
|
seed[1] = getpid() ^ (seed[0] >> 14 & 0x30000);
|
|
/* Turn it into printable characters from ‘seedchars’. */
|
for (i = 0; i < 8; i++)
|
salt[3+i] = seedchars[(seed[i/5] >> (i%5)*6) & 0x3f];
|
|
/* Read in the user’s password and encrypt it. */
|
password = crypt(getpass("Password:"), salt);
|
|
/* Print the results. */
|
puts(password);
|
return 0;
|
}
|
|
The next program shows how to verify a password. It prompts the user
|
for a password and prints “Access granted.” if the user types ‘GNU libc
|
manual’.
|
|
|
#include <stdio.h>
|
#include <string.h>
|
#include <unistd.h>
|
#include <crypt.h>
|
|
int
|
main(void)
|
{
|
/* Hashed form of "GNU libc manual". */
|
const char *const pass = "$1$/iSaq7rB$EoUw5jJPPvAPECNaaWzMK/";
|
|
char *result;
|
int ok;
|
|
/* Read in the user’s password and encrypt it,
|
passing the expected password in as the salt. */
|
result = crypt(getpass("Password:"), pass);
|
|
/* Test the result. */
|
ok = strcmp (result, pass) == 0;
|
|
puts(ok ? "Access granted." : "Access denied.");
|
return ok ? 0 : 1;
|
}
|
|
-- Function: char * crypt_r (const char *KEY, const char *SALT, struct
|
crypt_data * DATA)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt lock heap dlopen |
|
AC-Unsafe lock mem | *Note POSIX Safety Concepts::.
|
|
The ‘crypt_r’ function does the same thing as ‘crypt’, but takes an
|
extra parameter which includes space for its result (among other
|
things), so it can be reentrant. ‘data->initialized’ must be
|
cleared to zero before the first time ‘crypt_r’ is called.
|
|
The ‘crypt_r’ function is a GNU extension.
|
|
The ‘crypt’ and ‘crypt_r’ functions are prototyped in the header
|
‘crypt.h’.
|
|
|
File: libc.info, Node: DES Encryption, Prev: crypt, Up: Cryptographic Functions
|
|
33.4 DES Encryption
|
===================
|
|
The Data Encryption Standard is described in the US Government Federal
|
Information Processing Standards (FIPS) 46-3 published by the National
|
Institute of Standards and Technology. The DES has been very thoroughly
|
analyzed since it was developed in the late 1970s, and no new
|
significant flaws have been found.
|
|
However, the DES uses only a 56-bit key (plus 8 parity bits), and a
|
machine has been built in 1998 which can search through all possible
|
keys in about 6 days, which cost about US$200000; faster searches would
|
be possible with more money. This makes simple DES insecure for most
|
purposes, and NIST no longer permits new US government systems to use
|
simple DES.
|
|
For serious encryption functionality, it is recommended that one of
|
the many free encryption libraries be used instead of these routines.
|
|
The DES is a reversible operation which takes a 64-bit block and a
|
64-bit key, and produces another 64-bit block. Usually the bits are
|
numbered so that the most-significant bit, the first bit, of each block
|
is numbered 1.
|
|
Under that numbering, every 8th bit of the key (the 8th, 16th, and so
|
on) is not used by the encryption algorithm itself. But the key must
|
have odd parity; that is, out of bits 1 through 8, and 9 through 16, and
|
so on, there must be an odd number of ‘1’ bits, and this completely
|
specifies the unused bits.
|
|
-- Function: void setkey (const char *KEY)
|
Preliminary: | MT-Unsafe race:crypt | AS-Unsafe corrupt lock |
|
AC-Unsafe lock | *Note POSIX Safety Concepts::.
|
|
The ‘setkey’ function sets an internal data structure to be an
|
expanded form of KEY. KEY is specified as an array of 64 bits each
|
stored in a ‘char’, the first bit is ‘key[0]’ and the 64th bit is
|
‘key[63]’. The KEY should have the correct parity.
|
|
-- Function: void encrypt (char *BLOCK, int EDFLAG)
|
Preliminary: | MT-Unsafe race:crypt | AS-Unsafe corrupt lock |
|
AC-Unsafe lock | *Note POSIX Safety Concepts::.
|
|
The ‘encrypt’ function encrypts BLOCK if EDFLAG is 0, otherwise it
|
decrypts BLOCK, using a key previously set by ‘setkey’. The result
|
is placed in BLOCK.
|
|
Like ‘setkey’, BLOCK is specified as an array of 64 bits each
|
stored in a ‘char’, but there are no parity bits in BLOCK.
|
|
-- Function: void setkey_r (const char *KEY, struct crypt_data * DATA)
|
-- Function: void encrypt_r (char *BLOCK, int EDFLAG, struct crypt_data
|
* DATA)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt lock | AC-Unsafe lock |
|
*Note POSIX Safety Concepts::.
|
|
These are reentrant versions of ‘setkey’ and ‘encrypt’. The only
|
difference is the extra parameter, which stores the expanded
|
version of KEY. Before calling ‘setkey_r’ the first time,
|
‘data->initialized’ must be cleared to zero.
|
|
The ‘setkey_r’ and ‘encrypt_r’ functions are GNU extensions.
|
‘setkey’, ‘encrypt’, ‘setkey_r’, and ‘encrypt_r’ are defined in
|
‘crypt.h’.
|
|
-- Function: int ecb_crypt (char *KEY, char *BLOCKS, unsigned LEN,
|
unsigned MODE)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The function ‘ecb_crypt’ encrypts or decrypts one or more blocks
|
using DES. Each block is encrypted independently.
|
|
The BLOCKS and the KEY are stored packed in 8-bit bytes, so that
|
the first bit of the key is the most-significant bit of ‘key[0]’
|
and the 63rd bit of the key is stored as the least-significant bit
|
of ‘key[7]’. The KEY should have the correct parity.
|
|
LEN is the number of bytes in BLOCKS. It should be a multiple of 8
|
(so that there is a whole number of blocks to encrypt). LEN is
|
limited to a maximum of ‘DES_MAXDATA’ bytes.
|
|
The result of the encryption replaces the input in BLOCKS.
|
|
The MODE parameter is the bitwise OR of two of the following:
|
|
‘DES_ENCRYPT’
|
This constant, used in the MODE parameter, specifies that
|
BLOCKS is to be encrypted.
|
|
‘DES_DECRYPT’
|
This constant, used in the MODE parameter, specifies that
|
BLOCKS is to be decrypted.
|
|
‘DES_HW’
|
This constant, used in the MODE parameter, asks to use a
|
hardware device. If no hardware device is available,
|
encryption happens anyway, but in software.
|
|
‘DES_SW’
|
This constant, used in the MODE parameter, specifies that no
|
hardware device is to be used.
|
|
The result of the function will be one of these values:
|
|
‘DESERR_NONE’
|
The encryption succeeded.
|
|
‘DESERR_NOHWDEVICE’
|
The encryption succeeded, but there was no hardware device
|
available.
|
|
‘DESERR_HWERROR’
|
The encryption failed because of a hardware problem.
|
|
‘DESERR_BADPARAM’
|
The encryption failed because of a bad parameter, for instance
|
LEN is not a multiple of 8 or LEN is larger than
|
‘DES_MAXDATA’.
|
|
-- Function: int DES_FAILED (int ERR)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns 1 if ERR is a ‘success’ result code from
|
‘ecb_crypt’ or ‘cbc_crypt’, and 0 otherwise.
|
|
-- Function: int cbc_crypt (char *KEY, char *BLOCKS, unsigned LEN,
|
unsigned MODE, char *IVEC)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The function ‘cbc_crypt’ encrypts or decrypts one or more blocks
|
using DES in Cipher Block Chaining mode.
|
|
For encryption in CBC mode, each block is exclusive-ored with IVEC
|
before being encrypted, then IVEC is replaced with the result of
|
the encryption, then the next block is processed. Decryption is
|
the reverse of this process.
|
|
This has the advantage that blocks which are the same before being
|
encrypted are very unlikely to be the same after being encrypted,
|
making it much harder to detect patterns in the data.
|
|
Usually, IVEC is set to 8 random bytes before encryption starts.
|
Then the 8 random bytes are transmitted along with the encrypted
|
data (without themselves being encrypted), and passed back in as
|
IVEC for decryption. Another possibility is to set IVEC to 8
|
zeroes initially, and have the first the block encrypted consist of
|
8 random bytes.
|
|
Otherwise, all the parameters are similar to those for ‘ecb_crypt’.
|
|
-- Function: void des_setparity (char *KEY)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The function ‘des_setparity’ changes the 64-bit KEY, stored packed
|
in 8-bit bytes, to have odd parity by altering the low bits of each
|
byte.
|
|
The ‘ecb_crypt’, ‘cbc_crypt’, and ‘des_setparity’ functions and their
|
accompanying macros are all defined in the header ‘rpc/des_crypt.h’.
|
|
|
File: libc.info, Node: Debugging Support, Next: POSIX Threads, Prev: Cryptographic Functions, Up: Top
|
|
34 Debugging support
|
********************
|
|
Applications are usually debugged using dedicated debugger programs.
|
But sometimes this is not possible and, in any case, it is useful to
|
provide the developer with as much information as possible at the time
|
the problems are experienced. For this reason a few functions are
|
provided which a program can use to help the developer more easily
|
locate the problem.
|
|
* Menu:
|
|
* Backtraces:: Obtaining and printing a back trace of the
|
current stack.
|
|
|
File: libc.info, Node: Backtraces, Up: Debugging Support
|
|
34.1 Backtraces
|
===============
|
|
A "backtrace" is a list of the function calls that are currently active
|
in a thread. The usual way to inspect a backtrace of a program is to
|
use an external debugger such as gdb. However, sometimes it is useful
|
to obtain a backtrace programmatically from within a program, e.g., for
|
the purposes of logging or diagnostics.
|
|
The header file ‘execinfo.h’ declares three functions that obtain and
|
manipulate backtraces of the current thread.
|
|
-- Function: int backtrace (void **BUFFER, int SIZE)
|
Preliminary: | MT-Safe | AS-Unsafe init heap dlopen plugin lock |
|
AC-Unsafe init mem lock fd | *Note POSIX Safety Concepts::.
|
|
The ‘backtrace’ function obtains a backtrace for the current
|
thread, as a list of pointers, and places the information into
|
BUFFER. The argument SIZE should be the number of ‘void *’
|
elements that will fit into BUFFER. The return value is the actual
|
number of entries of BUFFER that are obtained, and is at most SIZE.
|
|
The pointers placed in BUFFER are actually return addresses
|
obtained by inspecting the stack, one return address per stack
|
frame.
|
|
Note that certain compiler optimizations may interfere with
|
obtaining a valid backtrace. Function inlining causes the inlined
|
function to not have a stack frame; tail call optimization replaces
|
one stack frame with another; frame pointer elimination will stop
|
‘backtrace’ from interpreting the stack contents correctly.
|
|
-- Function: char ** backtrace_symbols (void *const *BUFFER, int SIZE)
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem lock |
|
*Note POSIX Safety Concepts::.
|
|
The ‘backtrace_symbols’ function translates the information
|
obtained from the ‘backtrace’ function into an array of strings.
|
The argument BUFFER should be a pointer to an array of addresses
|
obtained via the ‘backtrace’ function, and SIZE is the number of
|
entries in that array (the return value of ‘backtrace’).
|
|
The return value is a pointer to an array of strings, which has
|
SIZE entries just like the array BUFFER. Each string contains a
|
printable representation of the corresponding element of BUFFER.
|
It includes the function name (if this can be determined), an
|
offset into the function, and the actual return address (in
|
hexadecimal).
|
|
Currently, the function name and offset only be obtained on systems
|
that use the ELF binary format for programs and libraries. On
|
other systems, only the hexadecimal return address will be present.
|
Also, you may need to pass additional flags to the linker to make
|
the function names available to the program. (For example, on
|
systems using GNU ld, you must pass (‘-rdynamic’.)
|
|
The return value of ‘backtrace_symbols’ is a pointer obtained via
|
the ‘malloc’ function, and it is the responsibility of the caller
|
to ‘free’ that pointer. Note that only the return value need be
|
freed, not the individual strings.
|
|
The return value is ‘NULL’ if sufficient memory for the strings
|
cannot be obtained.
|
|
-- Function: void backtrace_symbols_fd (void *const *BUFFER, int SIZE,
|
int FD)
|
Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
|
Safety Concepts::.
|
|
The ‘backtrace_symbols_fd’ function performs the same translation
|
as the function ‘backtrace_symbols’ function. Instead of returning
|
the strings to the caller, it writes the strings to the file
|
descriptor FD, one per line. It does not use the ‘malloc’
|
function, and can therefore be used in situations where that
|
function might fail.
|
|
The following program illustrates the use of these functions. Note
|
that the array to contain the return addresses returned by ‘backtrace’
|
is allocated on the stack. Therefore code like this can be used in
|
situations where the memory handling via ‘malloc’ does not work anymore
|
(in which case the ‘backtrace_symbols’ has to be replaced by a
|
‘backtrace_symbols_fd’ call as well). The number of return addresses is
|
normally not very large. Even complicated programs rather seldom have a
|
nesting level of more than, say, 50 and with 200 possible entries
|
probably all programs should be covered.
|
|
|
#include <execinfo.h>
|
#include <stdio.h>
|
#include <stdlib.h>
|
|
/* Obtain a backtrace and print it to ‘stdout’. */
|
void
|
print_trace (void)
|
{
|
void *array[10];
|
size_t size;
|
char **strings;
|
size_t i;
|
|
size = backtrace (array, 10);
|
strings = backtrace_symbols (array, size);
|
|
printf ("Obtained %zd stack frames.\n", size);
|
|
for (i = 0; i < size; i++)
|
printf ("%s\n", strings[i]);
|
|
free (strings);
|
}
|
|
/* A dummy function to make the backtrace more interesting. */
|
void
|
dummy_function (void)
|
{
|
print_trace ();
|
}
|
|
int
|
main (void)
|
{
|
dummy_function ();
|
return 0;
|
}
|
|
|
File: libc.info, Node: POSIX Threads, Next: Internal Probes, Prev: Debugging Support, Up: Top
|
|
35 POSIX Threads
|
****************
|
|
This chapter describes the GNU C Library POSIX Thread implementation.
|
|
* Menu:
|
|
* Thread-specific Data:: Support for creating and
|
managing thread-specific data
|
* Non-POSIX Extensions:: Additional functions to extend
|
POSIX Thread functionality
|
|
|
File: libc.info, Node: Thread-specific Data, Next: Non-POSIX Extensions, Up: POSIX Threads
|
|
35.1 Thread-specific Data
|
=========================
|
|
The GNU C Library implements functions to allow users to create and
|
manage data specific to a thread. Such data may be destroyed at thread
|
exit, if a destructor is provided. The following functions are defined:
|
|
-- Function: int pthread_key_create (pthread_key_t *KEY, void
|
(*DESTRUCTOR)(void*))
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
Create a thread-specific data key for the calling thread,
|
referenced by KEY.
|
|
Objects declared with the C++11 ‘thread_local’ keyword are
|
destroyed before thread-specific data, so they should not be used
|
in thread-specific data destructors or even as members of the
|
thread-specific data, since the latter is passed as an argument to
|
the destructor function.
|
|
-- Function: int pthread_key_delete (pthread_key_t KEY)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
Destroy the thread-specific data KEY in the calling thread. The
|
destructor for the thread-specific data is not called during
|
destruction, nor is it called during thread exit.
|
|
-- Function: void *pthread_getspecific (pthread_key_t KEY)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
Return the thread-specific data associated with KEY in the calling
|
thread.
|
|
-- Function: int pthread_setspecific (pthread_key_t KEY, const void
|
*VALUE)
|
Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe corrupt
|
mem | *Note POSIX Safety Concepts::.
|
|
Associate the thread-specific VALUE with KEY in the calling thread.
|
|
|
File: libc.info, Node: Non-POSIX Extensions, Prev: Thread-specific Data, Up: POSIX Threads
|
|
35.2 Non-POSIX Extensions
|
=========================
|
|
In addition to implementing the POSIX API for threads, the GNU C Library
|
provides additional functions and interfaces to provide functionality
|
not specified in the standard.
|
|
* Menu:
|
|
* Default Thread Attributes:: Setting default attributes for
|
threads in a process.
|
|
|
File: libc.info, Node: Default Thread Attributes, Up: Non-POSIX Extensions
|
|
35.2.1 Setting Process-wide defaults for thread attributes
|
----------------------------------------------------------
|
|
The GNU C Library provides non-standard API functions to set and get the
|
default attributes used in the creation of threads in a process.
|
|
-- Function: int pthread_getattr_default_np (pthread_attr_t *ATTR)
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
|
POSIX Safety Concepts::.
|
|
Get the default attribute values and set ATTR to match. This
|
function returns 0 on success and a non-zero error code on failure.
|
|
-- Function: int pthread_setattr_default_np (pthread_attr_t *ATTR)
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
|
*Note POSIX Safety Concepts::.
|
|
Set the default attribute values to match the values in ATTR. The
|
function returns 0 on success and a non-zero error code on failure.
|
The following error codes are defined for this function:
|
|
‘EINVAL’
|
At least one of the values in ATTR does not qualify as valid
|
for the attributes or the stack address is set in the
|
attribute.
|
‘ENOMEM’
|
The system does not have sufficient memory.
|
|
|
File: libc.info, Node: Internal Probes, Next: Language Features, Prev: POSIX Threads, Up: Top
|
|
36 Internal probes
|
******************
|
|
In order to aid in debugging and monitoring internal behavior, the GNU C
|
Library exposes nearly-zero-overhead SystemTap probes marked with the
|
‘libc’ provider.
|
|
These probes are not part of the GNU C Library stable ABI, and they
|
are subject to change or removal across releases. Our only promise with
|
regard to them is that, if we find a need to remove or modify the
|
arguments of a probe, the modified probe will have a different name, so
|
that program monitors relying on the old probe will not get unexpected
|
arguments.
|
|
* Menu:
|
|
* Memory Allocation Probes:: Probes in the memory allocation subsystem
|
* Mathematical Function Probes:: Probes in mathematical functions
|
* Non-local Goto Probes:: Probes in setjmp and longjmp
|
|
|
File: libc.info, Node: Memory Allocation Probes, Next: Mathematical Function Probes, Up: Internal Probes
|
|
36.1 Memory Allocation Probes
|
=============================
|
|
These probes are designed to signal relatively unusual situations within
|
the virtual memory subsystem of the GNU C Library.
|
|
-- Probe: memory_sbrk_more (void *$ARG1, size_t $ARG2)
|
This probe is triggered after the main arena is extended by calling
|
‘sbrk’. Argument $ARG1 is the additional size requested to ‘sbrk’,
|
and $ARG2 is the pointer that marks the end of the ‘sbrk’ area,
|
returned in response to the request.
|
|
-- Probe: memory_sbrk_less (void *$ARG1, size_t $ARG2)
|
This probe is triggered after the size of the main arena is
|
decreased by calling ‘sbrk’. Argument $ARG1 is the size released
|
by ‘sbrk’ (the positive value, rather than the negative value
|
passed to ‘sbrk’), and $ARG2 is the pointer that marks the end of
|
the ‘sbrk’ area, returned in response to the request.
|
|
-- Probe: memory_heap_new (void *$ARG1, size_t $ARG2)
|
This probe is triggered after a new heap is ‘mmap’ed. Argument
|
$ARG1 is a pointer to the base of the memory area, where the
|
‘heap_info’ data structure is held, and $ARG2 is the size of the
|
heap.
|
|
-- Probe: memory_heap_free (void *$ARG1, size_t $ARG2)
|
This probe is triggered _before_ (unlike the other sbrk and heap
|
probes) a heap is completely removed via ‘munmap’. Argument $ARG1
|
is a pointer to the heap, and $ARG2 is the size of the heap.
|
|
-- Probe: memory_heap_more (void *$ARG1, size_t $ARG2)
|
This probe is triggered after a trailing portion of an ‘mmap’ed
|
heap is extended. Argument $ARG1 is a pointer to the heap, and
|
$ARG2 is the new size of the heap.
|
|
-- Probe: memory_heap_less (void *$ARG1, size_t $ARG2)
|
This probe is triggered after a trailing portion of an ‘mmap’ed
|
heap is released. Argument $ARG1 is a pointer to the heap, and
|
$ARG2 is the new size of the heap.
|
|
-- Probe: memory_malloc_retry (size_t $ARG1)
|
-- Probe: memory_realloc_retry (size_t $ARG1, void *$ARG2)
|
-- Probe: memory_memalign_retry (size_t $ARG1, size_t $ARG2)
|
-- Probe: memory_calloc_retry (size_t $ARG1)
|
These probes are triggered when the corresponding functions fail to
|
obtain the requested amount of memory from the arena in use, before
|
they call ‘arena_get_retry’ to select an alternate arena in which
|
to retry the allocation. Argument $ARG1 is the amount of memory
|
requested by the user; in the ‘calloc’ case, that is the total size
|
computed from both function arguments. In the ‘realloc’ case,
|
$ARG2 is the pointer to the memory area being resized. In the
|
‘memalign’ case, $ARG2 is the alignment to be used for the request,
|
which may be stricter than the value passed to the ‘memalign’
|
function. A ‘memalign’ probe is also used by functions
|
‘posix_memalign, valloc’ and ‘pvalloc’.
|
|
Note that the argument order does _not_ match that of the
|
corresponding two-argument functions, so that in all of these
|
probes the user-requested allocation size is in $ARG1.
|
|
-- Probe: memory_arena_retry (size_t $ARG1, void *$ARG2)
|
This probe is triggered within ‘arena_get_retry’ (the function
|
called to select the alternate arena in which to retry an
|
allocation that failed on the first attempt), before the selection
|
of an alternate arena. This probe is redundant, but much easier to
|
use when it’s not important to determine which of the various
|
memory allocation functions is failing to allocate on the first
|
try. Argument $ARG1 is the same as in the function-specific
|
probes, except for extra room for padding introduced by functions
|
that have to ensure stricter alignment. Argument $ARG2 is the
|
arena in which allocation failed.
|
|
-- Probe: memory_arena_new (void *$ARG1, size_t $ARG2)
|
This probe is triggered when ‘malloc’ allocates and initializes an
|
additional arena (not the main arena), but before the arena is
|
assigned to the running thread or inserted into the internal linked
|
list of arenas. The arena’s ‘malloc_state’ internal data structure
|
is located at $ARG1, within a newly-allocated heap big enough to
|
hold at least $ARG2 bytes.
|
|
-- Probe: memory_arena_reuse (void *$ARG1, void *$ARG2)
|
This probe is triggered when ‘malloc’ has just selected an existing
|
arena to reuse, and (temporarily) reserved it for exclusive use.
|
Argument $ARG1 is a pointer to the newly-selected arena, and $ARG2
|
is a pointer to the arena previously used by that thread.
|
|
This occurs within ‘reused_arena’, right after the mutex mentioned
|
in probe ‘memory_arena_reuse_wait’ is acquired; argument $ARG1 will
|
point to the same arena. In this configuration, this will usually
|
only occur once per thread. The exception is when a thread first
|
selected the main arena, but a subsequent allocation from it fails:
|
then, and only then, may we switch to another arena to retry that
|
allocations, and for further allocations within that thread.
|
|
-- Probe: memory_arena_reuse_wait (void *$ARG1, void *$ARG2, void
|
*$ARG3)
|
This probe is triggered when ‘malloc’ is about to wait for an arena
|
to become available for reuse. Argument $ARG1 holds a pointer to
|
the mutex the thread is going to wait on, $ARG2 is a pointer to a
|
newly-chosen arena to be reused, and $ARG3 is a pointer to the
|
arena previously used by that thread.
|
|
This occurs within ‘reused_arena’, when a thread first tries to
|
allocate memory or needs a retry after a failure to allocate from
|
the main arena, there isn’t any free arena, the maximum number of
|
arenas has been reached, and an existing arena was chosen for
|
reuse, but its mutex could not be immediately acquired. The mutex
|
in $ARG1 is the mutex of the selected arena.
|
|
-- Probe: memory_arena_reuse_free_list (void *$ARG1)
|
This probe is triggered when ‘malloc’ has chosen an arena that is
|
in the free list for use by a thread, within the ‘get_free_list’
|
function. The argument $ARG1 holds a pointer to the selected
|
arena.
|
|
-- Probe: memory_mallopt (int $ARG1, int $ARG2)
|
This probe is triggered when function ‘mallopt’ is called to change
|
‘malloc’ internal configuration parameters, before any change to
|
the parameters is made. The arguments $ARG1 and $ARG2 are the ones
|
passed to the ‘mallopt’ function.
|
|
-- Probe: memory_mallopt_mxfast (int $ARG1, int $ARG2)
|
This probe is triggered shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_MXFAST’, and the requested
|
value is in an acceptable range. Argument $ARG1 is the requested
|
value, and $ARG2 is the previous value of this ‘malloc’ parameter.
|
|
-- Probe: memory_mallopt_trim_threshold (int $ARG1, int $ARG2, int
|
$ARG3)
|
This probe is triggere shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_TRIM_THRESHOLD’. Argument
|
$ARG1 is the requested value, $ARG2 is the previous value of this
|
‘malloc’ parameter, and $ARG3 is nonzero if dynamic threshold
|
adjustment was already disabled.
|
|
-- Probe: memory_mallopt_top_pad (int $ARG1, int $ARG2, int $ARG3)
|
This probe is triggered shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_TOP_PAD’. Argument $ARG1 is
|
the requested value, $ARG2 is the previous value of this ‘malloc’
|
parameter, and $ARG3 is nonzero if dynamic threshold adjustment was
|
already disabled.
|
|
-- Probe: memory_mallopt_mmap_threshold (int $ARG1, int $ARG2, int
|
$ARG3)
|
This probe is triggered shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_MMAP_THRESHOLD’, and the
|
requested value is in an acceptable range. Argument $ARG1 is the
|
requested value, $ARG2 is the previous value of this ‘malloc’
|
parameter, and $ARG3 is nonzero if dynamic threshold adjustment was
|
already disabled.
|
|
-- Probe: memory_mallopt_mmap_max (int $ARG1, int $ARG2, int $ARG3)
|
This probe is triggered shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_MMAP_MAX’. Argument $ARG1
|
is the requested value, $ARG2 is the previous value of this
|
‘malloc’ parameter, and $ARG3 is nonzero if dynamic threshold
|
adjustment was already disabled.
|
|
-- Probe: memory_mallopt_check_action (int $ARG1, int $ARG2)
|
This probe is triggered shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_CHECK_ACTION’. Argument
|
$ARG1 is the requested value, and $ARG2 is the previous value of
|
this ‘malloc’ parameter.
|
|
-- Probe: memory_mallopt_perturb (int $ARG1, int $ARG2)
|
This probe is triggered shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_PERTURB’. Argument $ARG1 is
|
the requested value, and $ARG2 is the previous value of this
|
‘malloc’ parameter.
|
|
-- Probe: memory_mallopt_arena_test (int $ARG1, int $ARG2)
|
This probe is triggered shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_ARENA_TEST’, and the
|
requested value is in an acceptable range. Argument $ARG1 is the
|
requested value, and $ARG2 is the previous value of this ‘malloc’
|
parameter.
|
|
-- Probe: memory_mallopt_arena_max (int $ARG1, int $ARG2)
|
This probe is triggered shortly after the ‘memory_mallopt’ probe,
|
when the parameter to be changed is ‘M_ARENA_MAX’, and the
|
requested value is in an acceptable range. Argument $ARG1 is the
|
requested value, and $ARG2 is the previous value of this ‘malloc’
|
parameter.
|
|
-- Probe: memory_mallopt_free_dyn_thresholds (int $ARG1, int $ARG2)
|
This probe is triggered when function ‘free’ decides to adjust the
|
dynamic brk/mmap thresholds. Argument $ARG1 and $ARG2 are the
|
adjusted mmap and trim thresholds, respectively.
|
