This is libc.info, produced by makeinfo version 5.1 from libc.texinfo.
|
|
This is ‘The GNU C Library Reference Manual’, for version 2.33 (GNU).
|
|
Copyright © 1993–2021 Free Software Foundation, Inc.
|
|
Permission is granted to copy, distribute and/or modify this document
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
any later version published by the Free Software Foundation; with the
|
Invariant Sections being “Free Software Needs Free Documentation” and
|
“GNU Lesser General Public License”, the Front-Cover texts being “A GNU
|
Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
|
license is included in the section entitled "GNU Free Documentation
|
License".
|
|
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
|
modify this GNU manual. Buying copies from the FSF supports it in
|
developing GNU and promoting software freedom.”
|
INFO-DIR-SECTION Software libraries
|
START-INFO-DIR-ENTRY
|
* Libc: (libc). C library.
|
END-INFO-DIR-ENTRY
|
|
INFO-DIR-SECTION GNU C library functions and macros
|
START-INFO-DIR-ENTRY
|
* ALTWERASE: (libc)Local Modes.
|
* ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
|
* ARG_MAX: (libc)General Limits.
|
* BC_BASE_MAX: (libc)Utility Limits.
|
* BC_DIM_MAX: (libc)Utility Limits.
|
* BC_SCALE_MAX: (libc)Utility Limits.
|
* BC_STRING_MAX: (libc)Utility Limits.
|
* BRKINT: (libc)Input Modes.
|
* BUFSIZ: (libc)Controlling Buffering.
|
* CCTS_OFLOW: (libc)Control Modes.
|
* CHAR_BIT: (libc)Width of Type.
|
* CHILD_MAX: (libc)General Limits.
|
* CIGNORE: (libc)Control Modes.
|
* CLK_TCK: (libc)Processor Time.
|
* CLOCAL: (libc)Control Modes.
|
* CLOCKS_PER_SEC: (libc)CPU Time.
|
* CLOCK_MONOTONIC: (libc)Getting the Time.
|
* CLOCK_REALTIME: (libc)Getting the Time.
|
* COLL_WEIGHTS_MAX: (libc)Utility Limits.
|
* CPU_CLR: (libc)CPU Affinity.
|
* CPU_FEATURE_USABLE: (libc)X86.
|
* CPU_ISSET: (libc)CPU Affinity.
|
* CPU_SET: (libc)CPU Affinity.
|
* CPU_SETSIZE: (libc)CPU Affinity.
|
* CPU_ZERO: (libc)CPU Affinity.
|
* CREAD: (libc)Control Modes.
|
* CRTS_IFLOW: (libc)Control Modes.
|
* CS5: (libc)Control Modes.
|
* CS6: (libc)Control Modes.
|
* CS7: (libc)Control Modes.
|
* CS8: (libc)Control Modes.
|
* CSIZE: (libc)Control Modes.
|
* CSTOPB: (libc)Control Modes.
|
* DTTOIF: (libc)Directory Entries.
|
* E2BIG: (libc)Error Codes.
|
* EACCES: (libc)Error Codes.
|
* EADDRINUSE: (libc)Error Codes.
|
* EADDRNOTAVAIL: (libc)Error Codes.
|
* EADV: (libc)Error Codes.
|
* EAFNOSUPPORT: (libc)Error Codes.
|
* EAGAIN: (libc)Error Codes.
|
* EALREADY: (libc)Error Codes.
|
* EAUTH: (libc)Error Codes.
|
* EBACKGROUND: (libc)Error Codes.
|
* EBADE: (libc)Error Codes.
|
* EBADF: (libc)Error Codes.
|
* EBADFD: (libc)Error Codes.
|
* EBADMSG: (libc)Error Codes.
|
* EBADR: (libc)Error Codes.
|
* EBADRPC: (libc)Error Codes.
|
* EBADRQC: (libc)Error Codes.
|
* EBADSLT: (libc)Error Codes.
|
* EBFONT: (libc)Error Codes.
|
* EBUSY: (libc)Error Codes.
|
* ECANCELED: (libc)Error Codes.
|
* ECHILD: (libc)Error Codes.
|
* ECHO: (libc)Local Modes.
|
* ECHOCTL: (libc)Local Modes.
|
* ECHOE: (libc)Local Modes.
|
* ECHOK: (libc)Local Modes.
|
* ECHOKE: (libc)Local Modes.
|
* ECHONL: (libc)Local Modes.
|
* ECHOPRT: (libc)Local Modes.
|
* ECHRNG: (libc)Error Codes.
|
* ECOMM: (libc)Error Codes.
|
* ECONNABORTED: (libc)Error Codes.
|
* ECONNREFUSED: (libc)Error Codes.
|
* ECONNRESET: (libc)Error Codes.
|
* ED: (libc)Error Codes.
|
* EDEADLK: (libc)Error Codes.
|
* EDEADLOCK: (libc)Error Codes.
|
* EDESTADDRREQ: (libc)Error Codes.
|
* EDIED: (libc)Error Codes.
|
* EDOM: (libc)Error Codes.
|
* EDOTDOT: (libc)Error Codes.
|
* EDQUOT: (libc)Error Codes.
|
* EEXIST: (libc)Error Codes.
|
* EFAULT: (libc)Error Codes.
|
* EFBIG: (libc)Error Codes.
|
* EFTYPE: (libc)Error Codes.
|
* EGRATUITOUS: (libc)Error Codes.
|
* EGREGIOUS: (libc)Error Codes.
|
* EHOSTDOWN: (libc)Error Codes.
|
* EHOSTUNREACH: (libc)Error Codes.
|
* EHWPOISON: (libc)Error Codes.
|
* EIDRM: (libc)Error Codes.
|
* EIEIO: (libc)Error Codes.
|
* EILSEQ: (libc)Error Codes.
|
* EINPROGRESS: (libc)Error Codes.
|
* EINTR: (libc)Error Codes.
|
* EINVAL: (libc)Error Codes.
|
* EIO: (libc)Error Codes.
|
* EISCONN: (libc)Error Codes.
|
* EISDIR: (libc)Error Codes.
|
* EISNAM: (libc)Error Codes.
|
* EKEYEXPIRED: (libc)Error Codes.
|
* EKEYREJECTED: (libc)Error Codes.
|
* EKEYREVOKED: (libc)Error Codes.
|
* EL2HLT: (libc)Error Codes.
|
* EL2NSYNC: (libc)Error Codes.
|
* EL3HLT: (libc)Error Codes.
|
* EL3RST: (libc)Error Codes.
|
* ELIBACC: (libc)Error Codes.
|
* ELIBBAD: (libc)Error Codes.
|
* ELIBEXEC: (libc)Error Codes.
|
* ELIBMAX: (libc)Error Codes.
|
* ELIBSCN: (libc)Error Codes.
|
* ELNRNG: (libc)Error Codes.
|
* ELOOP: (libc)Error Codes.
|
* EMEDIUMTYPE: (libc)Error Codes.
|
* EMFILE: (libc)Error Codes.
|
* EMLINK: (libc)Error Codes.
|
* EMSGSIZE: (libc)Error Codes.
|
* EMULTIHOP: (libc)Error Codes.
|
* ENAMETOOLONG: (libc)Error Codes.
|
* ENAVAIL: (libc)Error Codes.
|
* ENEEDAUTH: (libc)Error Codes.
|
* ENETDOWN: (libc)Error Codes.
|
* ENETRESET: (libc)Error Codes.
|
* ENETUNREACH: (libc)Error Codes.
|
* ENFILE: (libc)Error Codes.
|
* ENOANO: (libc)Error Codes.
|
* ENOBUFS: (libc)Error Codes.
|
* ENOCSI: (libc)Error Codes.
|
* ENODATA: (libc)Error Codes.
|
* ENODEV: (libc)Error Codes.
|
* ENOENT: (libc)Error Codes.
|
* ENOEXEC: (libc)Error Codes.
|
* ENOKEY: (libc)Error Codes.
|
* ENOLCK: (libc)Error Codes.
|
* ENOLINK: (libc)Error Codes.
|
* ENOMEDIUM: (libc)Error Codes.
|
* ENOMEM: (libc)Error Codes.
|
* ENOMSG: (libc)Error Codes.
|
* ENONET: (libc)Error Codes.
|
* ENOPKG: (libc)Error Codes.
|
* ENOPROTOOPT: (libc)Error Codes.
|
* ENOSPC: (libc)Error Codes.
|
* ENOSR: (libc)Error Codes.
|
* ENOSTR: (libc)Error Codes.
|
* ENOSYS: (libc)Error Codes.
|
* ENOTBLK: (libc)Error Codes.
|
* ENOTCONN: (libc)Error Codes.
|
* ENOTDIR: (libc)Error Codes.
|
* ENOTEMPTY: (libc)Error Codes.
|
* ENOTNAM: (libc)Error Codes.
|
* ENOTRECOVERABLE: (libc)Error Codes.
|
* ENOTSOCK: (libc)Error Codes.
|
* ENOTSUP: (libc)Error Codes.
|
* ENOTTY: (libc)Error Codes.
|
* ENOTUNIQ: (libc)Error Codes.
|
* ENXIO: (libc)Error Codes.
|
* EOF: (libc)EOF and Errors.
|
* EOPNOTSUPP: (libc)Error Codes.
|
* EOVERFLOW: (libc)Error Codes.
|
* EOWNERDEAD: (libc)Error Codes.
|
* EPERM: (libc)Error Codes.
|
* EPFNOSUPPORT: (libc)Error Codes.
|
* EPIPE: (libc)Error Codes.
|
* EPROCLIM: (libc)Error Codes.
|
* EPROCUNAVAIL: (libc)Error Codes.
|
* EPROGMISMATCH: (libc)Error Codes.
|
* EPROGUNAVAIL: (libc)Error Codes.
|
* EPROTO: (libc)Error Codes.
|
* EPROTONOSUPPORT: (libc)Error Codes.
|
* EPROTOTYPE: (libc)Error Codes.
|
* EQUIV_CLASS_MAX: (libc)Utility Limits.
|
* ERANGE: (libc)Error Codes.
|
* EREMCHG: (libc)Error Codes.
|
* EREMOTE: (libc)Error Codes.
|
* EREMOTEIO: (libc)Error Codes.
|
* ERESTART: (libc)Error Codes.
|
* ERFKILL: (libc)Error Codes.
|
* EROFS: (libc)Error Codes.
|
* ERPCMISMATCH: (libc)Error Codes.
|
* ESHUTDOWN: (libc)Error Codes.
|
* ESOCKTNOSUPPORT: (libc)Error Codes.
|
* ESPIPE: (libc)Error Codes.
|
* ESRCH: (libc)Error Codes.
|
* ESRMNT: (libc)Error Codes.
|
* ESTALE: (libc)Error Codes.
|
* ESTRPIPE: (libc)Error Codes.
|
* ETIME: (libc)Error Codes.
|
* ETIMEDOUT: (libc)Error Codes.
|
* ETOOMANYREFS: (libc)Error Codes.
|
* ETXTBSY: (libc)Error Codes.
|
* EUCLEAN: (libc)Error Codes.
|
* EUNATCH: (libc)Error Codes.
|
* EUSERS: (libc)Error Codes.
|
* EWOULDBLOCK: (libc)Error Codes.
|
* EXDEV: (libc)Error Codes.
|
* EXFULL: (libc)Error Codes.
|
* EXIT_FAILURE: (libc)Exit Status.
|
* EXIT_SUCCESS: (libc)Exit Status.
|
* EXPR_NEST_MAX: (libc)Utility Limits.
|
* FD_CLOEXEC: (libc)Descriptor Flags.
|
* FD_CLR: (libc)Waiting for I/O.
|
* FD_ISSET: (libc)Waiting for I/O.
|
* FD_SET: (libc)Waiting for I/O.
|
* FD_SETSIZE: (libc)Waiting for I/O.
|
* FD_ZERO: (libc)Waiting for I/O.
|
* FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
|
* FILENAME_MAX: (libc)Limits for Files.
|
* FLUSHO: (libc)Local Modes.
|
* FOPEN_MAX: (libc)Opening Streams.
|
* FP_ILOGB0: (libc)Exponents and Logarithms.
|
* FP_ILOGBNAN: (libc)Exponents and Logarithms.
|
* FP_LLOGB0: (libc)Exponents and Logarithms.
|
* FP_LLOGBNAN: (libc)Exponents and Logarithms.
|
* F_DUPFD: (libc)Duplicating Descriptors.
|
* F_GETFD: (libc)Descriptor Flags.
|
* F_GETFL: (libc)Getting File Status Flags.
|
* F_GETLK: (libc)File Locks.
|
* F_GETOWN: (libc)Interrupt Input.
|
* F_OFD_GETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLK: (libc)Open File Description Locks.
|
* F_OFD_SETLKW: (libc)Open File Description Locks.
|
* F_OK: (libc)Testing File Access.
|
* F_SETFD: (libc)Descriptor Flags.
|
* F_SETFL: (libc)Getting File Status Flags.
|
* F_SETLK: (libc)File Locks.
|
* F_SETLKW: (libc)File Locks.
|
* F_SETOWN: (libc)Interrupt Input.
|
* HAS_CPU_FEATURE: (libc)X86.
|
* HUGE_VAL: (libc)Math Error Reporting.
|
* HUGE_VALF: (libc)Math Error Reporting.
|
* HUGE_VALL: (libc)Math Error Reporting.
|
* HUGE_VAL_FN: (libc)Math Error Reporting.
|
* HUGE_VAL_FNx: (libc)Math Error Reporting.
|
* HUPCL: (libc)Control Modes.
|
* I: (libc)Complex Numbers.
|
* ICANON: (libc)Local Modes.
|
* ICRNL: (libc)Input Modes.
|
* IEXTEN: (libc)Local Modes.
|
* IFNAMSIZ: (libc)Interface Naming.
|
* IFTODT: (libc)Directory Entries.
|
* IGNBRK: (libc)Input Modes.
|
* IGNCR: (libc)Input Modes.
|
* IGNPAR: (libc)Input Modes.
|
* IMAXBEL: (libc)Input Modes.
|
* INADDR_ANY: (libc)Host Address Data Type.
|
* INADDR_BROADCAST: (libc)Host Address Data Type.
|
* INADDR_LOOPBACK: (libc)Host Address Data Type.
|
* INADDR_NONE: (libc)Host Address Data Type.
|
* INFINITY: (libc)Infinity and NaN.
|
* INLCR: (libc)Input Modes.
|
* INPCK: (libc)Input Modes.
|
* IPPORT_RESERVED: (libc)Ports.
|
* IPPORT_USERRESERVED: (libc)Ports.
|
* ISIG: (libc)Local Modes.
|
* ISTRIP: (libc)Input Modes.
|
* IXANY: (libc)Input Modes.
|
* IXOFF: (libc)Input Modes.
|
* IXON: (libc)Input Modes.
|
* LINE_MAX: (libc)Utility Limits.
|
* LINK_MAX: (libc)Limits for Files.
|
* L_ctermid: (libc)Identifying the Terminal.
|
* L_cuserid: (libc)Who Logged In.
|
* L_tmpnam: (libc)Temporary Files.
|
* MAXNAMLEN: (libc)Limits for Files.
|
* MAXSYMLINKS: (libc)Symbolic Links.
|
* MAX_CANON: (libc)Limits for Files.
|
* MAX_INPUT: (libc)Limits for Files.
|
* MB_CUR_MAX: (libc)Selecting the Conversion.
|
* MB_LEN_MAX: (libc)Selecting the Conversion.
|
* MDMBUF: (libc)Control Modes.
|
* MSG_DONTROUTE: (libc)Socket Data Options.
|
* MSG_OOB: (libc)Socket Data Options.
|
* MSG_PEEK: (libc)Socket Data Options.
|
* NAME_MAX: (libc)Limits for Files.
|
* NAN: (libc)Infinity and NaN.
|
* NCCS: (libc)Mode Data Types.
|
* NGROUPS_MAX: (libc)General Limits.
|
* NOFLSH: (libc)Local Modes.
|
* NOKERNINFO: (libc)Local Modes.
|
* NSIG: (libc)Standard Signals.
|
* NULL: (libc)Null Pointer Constant.
|
* ONLCR: (libc)Output Modes.
|
* ONOEOT: (libc)Output Modes.
|
* OPEN_MAX: (libc)General Limits.
|
* OPOST: (libc)Output Modes.
|
* OXTABS: (libc)Output Modes.
|
* O_ACCMODE: (libc)Access Modes.
|
* O_APPEND: (libc)Operating Modes.
|
* O_ASYNC: (libc)Operating Modes.
|
* O_CREAT: (libc)Open-time Flags.
|
* O_DIRECTORY: (libc)Open-time Flags.
|
* O_EXCL: (libc)Open-time Flags.
|
* O_EXEC: (libc)Access Modes.
|
* O_EXLOCK: (libc)Open-time Flags.
|
* O_FSYNC: (libc)Operating Modes.
|
* O_IGNORE_CTTY: (libc)Open-time Flags.
|
* O_NDELAY: (libc)Operating Modes.
|
* O_NOATIME: (libc)Operating Modes.
|
* O_NOCTTY: (libc)Open-time Flags.
|
* O_NOFOLLOW: (libc)Open-time Flags.
|
* O_NOLINK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Open-time Flags.
|
* O_NONBLOCK: (libc)Operating Modes.
|
* O_NOTRANS: (libc)Open-time Flags.
|
* O_PATH: (libc)Access Modes.
|
* O_RDONLY: (libc)Access Modes.
|
* O_RDWR: (libc)Access Modes.
|
* O_READ: (libc)Access Modes.
|
* O_SHLOCK: (libc)Open-time Flags.
|
* O_SYNC: (libc)Operating Modes.
|
* O_TMPFILE: (libc)Open-time Flags.
|
* O_TRUNC: (libc)Open-time Flags.
|
* O_WRITE: (libc)Access Modes.
|
* O_WRONLY: (libc)Access Modes.
|
* PARENB: (libc)Control Modes.
|
* PARMRK: (libc)Input Modes.
|
* PARODD: (libc)Control Modes.
|
* PATH_MAX: (libc)Limits for Files.
|
* PA_FLAG_MASK: (libc)Parsing a Template String.
|
* PENDIN: (libc)Local Modes.
|
* PF_FILE: (libc)Local Namespace Details.
|
* PF_INET6: (libc)Internet Namespace.
|
* PF_INET: (libc)Internet Namespace.
|
* PF_LOCAL: (libc)Local Namespace Details.
|
* PF_UNIX: (libc)Local Namespace Details.
|
* PIPE_BUF: (libc)Limits for Files.
|
* PTHREAD_ATTR_NO_SIGMASK_NP: (libc)Initial Thread Signal Mask.
|
* P_tmpdir: (libc)Temporary Files.
|
* RAND_MAX: (libc)ISO Random.
|
* RE_DUP_MAX: (libc)General Limits.
|
* RLIM_INFINITY: (libc)Limits on Resources.
|
* R_OK: (libc)Testing File Access.
|
* SA_NOCLDSTOP: (libc)Flags for Sigaction.
|
* SA_ONSTACK: (libc)Flags for Sigaction.
|
* SA_RESTART: (libc)Flags for Sigaction.
|
* SEEK_CUR: (libc)File Positioning.
|
* SEEK_END: (libc)File Positioning.
|
* SEEK_SET: (libc)File Positioning.
|
* SIGABRT: (libc)Program Error Signals.
|
* SIGALRM: (libc)Alarm Signals.
|
* SIGBUS: (libc)Program Error Signals.
|
* SIGCHLD: (libc)Job Control Signals.
|
* SIGCLD: (libc)Job Control Signals.
|
* SIGCONT: (libc)Job Control Signals.
|
* SIGEMT: (libc)Program Error Signals.
|
* SIGFPE: (libc)Program Error Signals.
|
* SIGHUP: (libc)Termination Signals.
|
* SIGILL: (libc)Program Error Signals.
|
* SIGINFO: (libc)Miscellaneous Signals.
|
* SIGINT: (libc)Termination Signals.
|
* SIGIO: (libc)Asynchronous I/O Signals.
|
* SIGIOT: (libc)Program Error Signals.
|
* SIGKILL: (libc)Termination Signals.
|
* SIGLOST: (libc)Operation Error Signals.
|
* SIGPIPE: (libc)Operation Error Signals.
|
* SIGPOLL: (libc)Asynchronous I/O Signals.
|
* SIGPROF: (libc)Alarm Signals.
|
* SIGQUIT: (libc)Termination Signals.
|
* SIGSEGV: (libc)Program Error Signals.
|
* SIGSTOP: (libc)Job Control Signals.
|
* SIGSYS: (libc)Program Error Signals.
|
* SIGTERM: (libc)Termination Signals.
|
* SIGTRAP: (libc)Program Error Signals.
|
* SIGTSTP: (libc)Job Control Signals.
|
* SIGTTIN: (libc)Job Control Signals.
|
* SIGTTOU: (libc)Job Control Signals.
|
* SIGURG: (libc)Asynchronous I/O Signals.
|
* SIGUSR1: (libc)Miscellaneous Signals.
|
* SIGUSR2: (libc)Miscellaneous Signals.
|
* SIGVTALRM: (libc)Alarm Signals.
|
* SIGWINCH: (libc)Miscellaneous Signals.
|
* SIGXCPU: (libc)Operation Error Signals.
|
* SIGXFSZ: (libc)Operation Error Signals.
|
* SIG_ERR: (libc)Basic Signal Handling.
|
* SNAN: (libc)Infinity and NaN.
|
* SNANF: (libc)Infinity and NaN.
|
* SNANFN: (libc)Infinity and NaN.
|
* SNANFNx: (libc)Infinity and NaN.
|
* SNANL: (libc)Infinity and NaN.
|
* SOCK_DGRAM: (libc)Communication Styles.
|
* SOCK_RAW: (libc)Communication Styles.
|
* SOCK_RDM: (libc)Communication Styles.
|
* SOCK_SEQPACKET: (libc)Communication Styles.
|
* SOCK_STREAM: (libc)Communication Styles.
|
* SOL_SOCKET: (libc)Socket-Level Options.
|
* SSIZE_MAX: (libc)General Limits.
|
* STREAM_MAX: (libc)General Limits.
|
* SUN_LEN: (libc)Local Namespace Details.
|
* S_IFMT: (libc)Testing File Type.
|
* S_ISBLK: (libc)Testing File Type.
|
* S_ISCHR: (libc)Testing File Type.
|
* S_ISDIR: (libc)Testing File Type.
|
* S_ISFIFO: (libc)Testing File Type.
|
* S_ISLNK: (libc)Testing File Type.
|
* S_ISREG: (libc)Testing File Type.
|
* S_ISSOCK: (libc)Testing File Type.
|
* S_TYPEISMQ: (libc)Testing File Type.
|
* S_TYPEISSEM: (libc)Testing File Type.
|
* S_TYPEISSHM: (libc)Testing File Type.
|
* TMP_MAX: (libc)Temporary Files.
|
* TOSTOP: (libc)Local Modes.
|
* TZNAME_MAX: (libc)General Limits.
|
* VDISCARD: (libc)Other Special.
|
* VDSUSP: (libc)Signal Characters.
|
* VEOF: (libc)Editing Characters.
|
* VEOL2: (libc)Editing Characters.
|
* VEOL: (libc)Editing Characters.
|
* VERASE: (libc)Editing Characters.
|
* VINTR: (libc)Signal Characters.
|
* VKILL: (libc)Editing Characters.
|
* VLNEXT: (libc)Other Special.
|
* VMIN: (libc)Noncanonical Input.
|
* VQUIT: (libc)Signal Characters.
|
* VREPRINT: (libc)Editing Characters.
|
* VSTART: (libc)Start/Stop Characters.
|
* VSTATUS: (libc)Other Special.
|
* VSTOP: (libc)Start/Stop Characters.
|
* VSUSP: (libc)Signal Characters.
|
* VTIME: (libc)Noncanonical Input.
|
* VWERASE: (libc)Editing Characters.
|
* WCHAR_MAX: (libc)Extended Char Intro.
|
* WCHAR_MIN: (libc)Extended Char Intro.
|
* WCOREDUMP: (libc)Process Completion Status.
|
* WEOF: (libc)EOF and Errors.
|
* WEOF: (libc)Extended Char Intro.
|
* WEXITSTATUS: (libc)Process Completion Status.
|
* WIFEXITED: (libc)Process Completion Status.
|
* WIFSIGNALED: (libc)Process Completion Status.
|
* WIFSTOPPED: (libc)Process Completion Status.
|
* WSTOPSIG: (libc)Process Completion Status.
|
* WTERMSIG: (libc)Process Completion Status.
|
* W_OK: (libc)Testing File Access.
|
* X_OK: (libc)Testing File Access.
|
* _Complex_I: (libc)Complex Numbers.
|
* _Exit: (libc)Termination Internals.
|
* _IOFBF: (libc)Controlling Buffering.
|
* _IOLBF: (libc)Controlling Buffering.
|
* _IONBF: (libc)Controlling Buffering.
|
* _Imaginary_I: (libc)Complex Numbers.
|
* _PATH_UTMP: (libc)Manipulating the Database.
|
* _PATH_WTMP: (libc)Manipulating the Database.
|
* _POSIX2_C_DEV: (libc)System Options.
|
* _POSIX2_C_VERSION: (libc)Version Supported.
|
* _POSIX2_FORT_DEV: (libc)System Options.
|
* _POSIX2_FORT_RUN: (libc)System Options.
|
* _POSIX2_LOCALEDEF: (libc)System Options.
|
* _POSIX2_SW_DEV: (libc)System Options.
|
* _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
|
* _POSIX_JOB_CONTROL: (libc)System Options.
|
* _POSIX_NO_TRUNC: (libc)Options for Files.
|
* _POSIX_SAVED_IDS: (libc)System Options.
|
* _POSIX_VDISABLE: (libc)Options for Files.
|
* _POSIX_VERSION: (libc)Version Supported.
|
* __fbufsize: (libc)Controlling Buffering.
|
* __flbf: (libc)Controlling Buffering.
|
* __fpending: (libc)Controlling Buffering.
|
* __fpurge: (libc)Flushing Buffers.
|
* __freadable: (libc)Opening Streams.
|
* __freading: (libc)Opening Streams.
|
* __fsetlocking: (libc)Streams and Threads.
|
* __fwritable: (libc)Opening Streams.
|
* __fwriting: (libc)Opening Streams.
|
* __gconv_end_fct: (libc)glibc iconv Implementation.
|
* __gconv_fct: (libc)glibc iconv Implementation.
|
* __gconv_init_fct: (libc)glibc iconv Implementation.
|
* __ppc_get_timebase: (libc)PowerPC.
|
* __ppc_get_timebase_freq: (libc)PowerPC.
|
* __ppc_mdoio: (libc)PowerPC.
|
* __ppc_mdoom: (libc)PowerPC.
|
* __ppc_set_ppr_low: (libc)PowerPC.
|
* __ppc_set_ppr_med: (libc)PowerPC.
|
* __ppc_set_ppr_med_high: (libc)PowerPC.
|
* __ppc_set_ppr_med_low: (libc)PowerPC.
|
* __ppc_set_ppr_very_low: (libc)PowerPC.
|
* __ppc_yield: (libc)PowerPC.
|
* __riscv_flush_icache: (libc)RISC-V.
|
* __va_copy: (libc)Argument Macros.
|
* __x86_get_cpuid_feature_leaf: (libc)X86.
|
* _exit: (libc)Termination Internals.
|
* _flushlbf: (libc)Flushing Buffers.
|
* _tolower: (libc)Case Conversion.
|
* _toupper: (libc)Case Conversion.
|
* a64l: (libc)Encode Binary Data.
|
* abort: (libc)Aborting a Program.
|
* abs: (libc)Absolute Value.
|
* accept: (libc)Accepting Connections.
|
* access: (libc)Testing File Access.
|
* acos: (libc)Inverse Trig Functions.
|
* acosf: (libc)Inverse Trig Functions.
|
* acosfN: (libc)Inverse Trig Functions.
|
* acosfNx: (libc)Inverse Trig Functions.
|
* acosh: (libc)Hyperbolic Functions.
|
* acoshf: (libc)Hyperbolic Functions.
|
* acoshfN: (libc)Hyperbolic Functions.
|
* acoshfNx: (libc)Hyperbolic Functions.
|
* acoshl: (libc)Hyperbolic Functions.
|
* acosl: (libc)Inverse Trig Functions.
|
* addmntent: (libc)mtab.
|
* addseverity: (libc)Adding Severity Classes.
|
* adjtime: (libc)Setting and Adjusting the Time.
|
* adjtimex: (libc)Setting and Adjusting the Time.
|
* aio_cancel64: (libc)Cancel AIO Operations.
|
* aio_cancel: (libc)Cancel AIO Operations.
|
* aio_error64: (libc)Status of AIO Operations.
|
* aio_error: (libc)Status of AIO Operations.
|
* aio_fsync64: (libc)Synchronizing AIO Operations.
|
* aio_fsync: (libc)Synchronizing AIO Operations.
|
* aio_init: (libc)Configuration of AIO.
|
* aio_read64: (libc)Asynchronous Reads/Writes.
|
* aio_read: (libc)Asynchronous Reads/Writes.
|
* aio_return64: (libc)Status of AIO Operations.
|
* aio_return: (libc)Status of AIO Operations.
|
* aio_suspend64: (libc)Synchronizing AIO Operations.
|
* aio_suspend: (libc)Synchronizing AIO Operations.
|
* aio_write64: (libc)Asynchronous Reads/Writes.
|
* aio_write: (libc)Asynchronous Reads/Writes.
|
* alarm: (libc)Setting an Alarm.
|
* aligned_alloc: (libc)Aligned Memory Blocks.
|
* alloca: (libc)Variable Size Automatic.
|
* alphasort64: (libc)Scanning Directory Content.
|
* alphasort: (libc)Scanning Directory Content.
|
* argp_error: (libc)Argp Helper Functions.
|
* argp_failure: (libc)Argp Helper Functions.
|
* argp_help: (libc)Argp Help.
|
* argp_parse: (libc)Argp.
|
* argp_state_help: (libc)Argp Helper Functions.
|
* argp_usage: (libc)Argp Helper Functions.
|
* argz_add: (libc)Argz Functions.
|
* argz_add_sep: (libc)Argz Functions.
|
* argz_append: (libc)Argz Functions.
|
* argz_count: (libc)Argz Functions.
|
* argz_create: (libc)Argz Functions.
|
* argz_create_sep: (libc)Argz Functions.
|
* argz_delete: (libc)Argz Functions.
|
* argz_extract: (libc)Argz Functions.
|
* argz_insert: (libc)Argz Functions.
|
* argz_next: (libc)Argz Functions.
|
* argz_replace: (libc)Argz Functions.
|
* argz_stringify: (libc)Argz Functions.
|
* asctime: (libc)Formatting Calendar Time.
|
* asctime_r: (libc)Formatting Calendar Time.
|
* asin: (libc)Inverse Trig Functions.
|
* asinf: (libc)Inverse Trig Functions.
|
* asinfN: (libc)Inverse Trig Functions.
|
* asinfNx: (libc)Inverse Trig Functions.
|
* asinh: (libc)Hyperbolic Functions.
|
* asinhf: (libc)Hyperbolic Functions.
|
* asinhfN: (libc)Hyperbolic Functions.
|
* asinhfNx: (libc)Hyperbolic Functions.
|
* asinhl: (libc)Hyperbolic Functions.
|
* asinl: (libc)Inverse Trig Functions.
|
* asprintf: (libc)Dynamic Output.
|
* assert: (libc)Consistency Checking.
|
* assert_perror: (libc)Consistency Checking.
|
* atan2: (libc)Inverse Trig Functions.
|
* atan2f: (libc)Inverse Trig Functions.
|
* atan2fN: (libc)Inverse Trig Functions.
|
* atan2fNx: (libc)Inverse Trig Functions.
|
* atan2l: (libc)Inverse Trig Functions.
|
* atan: (libc)Inverse Trig Functions.
|
* atanf: (libc)Inverse Trig Functions.
|
* atanfN: (libc)Inverse Trig Functions.
|
* atanfNx: (libc)Inverse Trig Functions.
|
* atanh: (libc)Hyperbolic Functions.
|
* atanhf: (libc)Hyperbolic Functions.
|
* atanhfN: (libc)Hyperbolic Functions.
|
* atanhfNx: (libc)Hyperbolic Functions.
|
* atanhl: (libc)Hyperbolic Functions.
|
* atanl: (libc)Inverse Trig Functions.
|
* atexit: (libc)Cleanups on Exit.
|
* atof: (libc)Parsing of Floats.
|
* atoi: (libc)Parsing of Integers.
|
* atol: (libc)Parsing of Integers.
|
* atoll: (libc)Parsing of Integers.
|
* backtrace: (libc)Backtraces.
|
* backtrace_symbols: (libc)Backtraces.
|
* backtrace_symbols_fd: (libc)Backtraces.
|
* basename: (libc)Finding Tokens in a String.
|
* basename: (libc)Finding Tokens in a String.
|
* bcmp: (libc)String/Array Comparison.
|
* bcopy: (libc)Copying Strings and Arrays.
|
* bind: (libc)Setting Address.
|
* bind_textdomain_codeset: (libc)Charset conversion in gettext.
|
* bindtextdomain: (libc)Locating gettext catalog.
|
* brk: (libc)Resizing the Data Segment.
|
* bsearch: (libc)Array Search Function.
|
* btowc: (libc)Converting a Character.
|
* bzero: (libc)Copying Strings and Arrays.
|
* cabs: (libc)Absolute Value.
|
* cabsf: (libc)Absolute Value.
|
* cabsfN: (libc)Absolute Value.
|
* cabsfNx: (libc)Absolute Value.
|
* cabsl: (libc)Absolute Value.
|
* cacos: (libc)Inverse Trig Functions.
|
* cacosf: (libc)Inverse Trig Functions.
|
* cacosfN: (libc)Inverse Trig Functions.
|
* cacosfNx: (libc)Inverse Trig Functions.
|
* cacosh: (libc)Hyperbolic Functions.
|
* cacoshf: (libc)Hyperbolic Functions.
|
* cacoshfN: (libc)Hyperbolic Functions.
|
* cacoshfNx: (libc)Hyperbolic Functions.
|
* cacoshl: (libc)Hyperbolic Functions.
|
* cacosl: (libc)Inverse Trig Functions.
|
* call_once: (libc)Call Once.
|
* calloc: (libc)Allocating Cleared Space.
|
* canonicalize: (libc)FP Bit Twiddling.
|
* canonicalize_file_name: (libc)Symbolic Links.
|
* canonicalizef: (libc)FP Bit Twiddling.
|
* canonicalizefN: (libc)FP Bit Twiddling.
|
* canonicalizefNx: (libc)FP Bit Twiddling.
|
* canonicalizel: (libc)FP Bit Twiddling.
|
* carg: (libc)Operations on Complex.
|
* cargf: (libc)Operations on Complex.
|
* cargfN: (libc)Operations on Complex.
|
* cargfNx: (libc)Operations on Complex.
|
* cargl: (libc)Operations on Complex.
|
* casin: (libc)Inverse Trig Functions.
|
* casinf: (libc)Inverse Trig Functions.
|
* casinfN: (libc)Inverse Trig Functions.
|
* casinfNx: (libc)Inverse Trig Functions.
|
* casinh: (libc)Hyperbolic Functions.
|
* casinhf: (libc)Hyperbolic Functions.
|
* casinhfN: (libc)Hyperbolic Functions.
|
* casinhfNx: (libc)Hyperbolic Functions.
|
* casinhl: (libc)Hyperbolic Functions.
|
* casinl: (libc)Inverse Trig Functions.
|
* catan: (libc)Inverse Trig Functions.
|
* catanf: (libc)Inverse Trig Functions.
|
* catanfN: (libc)Inverse Trig Functions.
|
* catanfNx: (libc)Inverse Trig Functions.
|
* catanh: (libc)Hyperbolic Functions.
|
* catanhf: (libc)Hyperbolic Functions.
|
* catanhfN: (libc)Hyperbolic Functions.
|
* catanhfNx: (libc)Hyperbolic Functions.
|
* catanhl: (libc)Hyperbolic Functions.
|
* catanl: (libc)Inverse Trig Functions.
|
* catclose: (libc)The catgets Functions.
|
* catgets: (libc)The catgets Functions.
|
* catopen: (libc)The catgets Functions.
|
* cbrt: (libc)Exponents and Logarithms.
|
* cbrtf: (libc)Exponents and Logarithms.
|
* cbrtfN: (libc)Exponents and Logarithms.
|
* cbrtfNx: (libc)Exponents and Logarithms.
|
* cbrtl: (libc)Exponents and Logarithms.
|
* ccos: (libc)Trig Functions.
|
* ccosf: (libc)Trig Functions.
|
* ccosfN: (libc)Trig Functions.
|
* ccosfNx: (libc)Trig Functions.
|
* ccosh: (libc)Hyperbolic Functions.
|
* ccoshf: (libc)Hyperbolic Functions.
|
* ccoshfN: (libc)Hyperbolic Functions.
|
* ccoshfNx: (libc)Hyperbolic Functions.
|
* ccoshl: (libc)Hyperbolic Functions.
|
* ccosl: (libc)Trig Functions.
|
* ceil: (libc)Rounding Functions.
|
* ceilf: (libc)Rounding Functions.
|
* ceilfN: (libc)Rounding Functions.
|
* ceilfNx: (libc)Rounding Functions.
|
* ceill: (libc)Rounding Functions.
|
* cexp: (libc)Exponents and Logarithms.
|
* cexpf: (libc)Exponents and Logarithms.
|
* cexpfN: (libc)Exponents and Logarithms.
|
* cexpfNx: (libc)Exponents and Logarithms.
|
* cexpl: (libc)Exponents and Logarithms.
|
* cfgetispeed: (libc)Line Speed.
|
* cfgetospeed: (libc)Line Speed.
|
* cfmakeraw: (libc)Noncanonical Input.
|
* cfsetispeed: (libc)Line Speed.
|
* cfsetospeed: (libc)Line Speed.
|
* cfsetspeed: (libc)Line Speed.
|
* chdir: (libc)Working Directory.
|
* chmod: (libc)Setting Permissions.
|
* chown: (libc)File Owner.
|
* cimag: (libc)Operations on Complex.
|
* cimagf: (libc)Operations on Complex.
|
* cimagfN: (libc)Operations on Complex.
|
* cimagfNx: (libc)Operations on Complex.
|
* cimagl: (libc)Operations on Complex.
|
* clearenv: (libc)Environment Access.
|
* clearerr: (libc)Error Recovery.
|
* clearerr_unlocked: (libc)Error Recovery.
|
* clock: (libc)CPU Time.
|
* clock_getres: (libc)Getting the Time.
|
* clock_gettime: (libc)Getting the Time.
|
* clock_settime: (libc)Setting and Adjusting the Time.
|
* clog10: (libc)Exponents and Logarithms.
|
* clog10f: (libc)Exponents and Logarithms.
|
* clog10fN: (libc)Exponents and Logarithms.
|
* clog10fNx: (libc)Exponents and Logarithms.
|
* clog10l: (libc)Exponents and Logarithms.
|
* clog: (libc)Exponents and Logarithms.
|
* clogf: (libc)Exponents and Logarithms.
|
* clogfN: (libc)Exponents and Logarithms.
|
* clogfNx: (libc)Exponents and Logarithms.
|
* clogl: (libc)Exponents and Logarithms.
|
* close: (libc)Opening and Closing Files.
|
* closedir: (libc)Reading/Closing Directory.
|
* closelog: (libc)closelog.
|
* cnd_broadcast: (libc)ISO C Condition Variables.
|
* cnd_destroy: (libc)ISO C Condition Variables.
|
* cnd_init: (libc)ISO C Condition Variables.
|
* cnd_signal: (libc)ISO C Condition Variables.
|
* cnd_timedwait: (libc)ISO C Condition Variables.
|
* cnd_wait: (libc)ISO C Condition Variables.
|
* confstr: (libc)String Parameters.
|
* conj: (libc)Operations on Complex.
|
* conjf: (libc)Operations on Complex.
|
* conjfN: (libc)Operations on Complex.
|
* conjfNx: (libc)Operations on Complex.
|
* conjl: (libc)Operations on Complex.
|
* connect: (libc)Connecting.
|
* copy_file_range: (libc)Copying File Data.
|
* copysign: (libc)FP Bit Twiddling.
|
* copysignf: (libc)FP Bit Twiddling.
|
* copysignfN: (libc)FP Bit Twiddling.
|
* copysignfNx: (libc)FP Bit Twiddling.
|
* copysignl: (libc)FP Bit Twiddling.
|
* cos: (libc)Trig Functions.
|
* cosf: (libc)Trig Functions.
|
* cosfN: (libc)Trig Functions.
|
* cosfNx: (libc)Trig Functions.
|
* cosh: (libc)Hyperbolic Functions.
|
* coshf: (libc)Hyperbolic Functions.
|
* coshfN: (libc)Hyperbolic Functions.
|
* coshfNx: (libc)Hyperbolic Functions.
|
* coshl: (libc)Hyperbolic Functions.
|
* cosl: (libc)Trig Functions.
|
* cpow: (libc)Exponents and Logarithms.
|
* cpowf: (libc)Exponents and Logarithms.
|
* cpowfN: (libc)Exponents and Logarithms.
|
* cpowfNx: (libc)Exponents and Logarithms.
|
* cpowl: (libc)Exponents and Logarithms.
|
* cproj: (libc)Operations on Complex.
|
* cprojf: (libc)Operations on Complex.
|
* cprojfN: (libc)Operations on Complex.
|
* cprojfNx: (libc)Operations on Complex.
|
* cprojl: (libc)Operations on Complex.
|
* creal: (libc)Operations on Complex.
|
* crealf: (libc)Operations on Complex.
|
* crealfN: (libc)Operations on Complex.
|
* crealfNx: (libc)Operations on Complex.
|
* creall: (libc)Operations on Complex.
|
* creat64: (libc)Opening and Closing Files.
|
* creat: (libc)Opening and Closing Files.
|
* crypt: (libc)Passphrase Storage.
|
* crypt_r: (libc)Passphrase Storage.
|
* csin: (libc)Trig Functions.
|
* csinf: (libc)Trig Functions.
|
* csinfN: (libc)Trig Functions.
|
* csinfNx: (libc)Trig Functions.
|
* csinh: (libc)Hyperbolic Functions.
|
* csinhf: (libc)Hyperbolic Functions.
|
* csinhfN: (libc)Hyperbolic Functions.
|
* csinhfNx: (libc)Hyperbolic Functions.
|
* csinhl: (libc)Hyperbolic Functions.
|
* csinl: (libc)Trig Functions.
|
* csqrt: (libc)Exponents and Logarithms.
|
* csqrtf: (libc)Exponents and Logarithms.
|
* csqrtfN: (libc)Exponents and Logarithms.
|
* csqrtfNx: (libc)Exponents and Logarithms.
|
* csqrtl: (libc)Exponents and Logarithms.
|
* ctan: (libc)Trig Functions.
|
* ctanf: (libc)Trig Functions.
|
* ctanfN: (libc)Trig Functions.
|
* ctanfNx: (libc)Trig Functions.
|
* ctanh: (libc)Hyperbolic Functions.
|
* ctanhf: (libc)Hyperbolic Functions.
|
* ctanhfN: (libc)Hyperbolic Functions.
|
* ctanhfNx: (libc)Hyperbolic Functions.
|
* ctanhl: (libc)Hyperbolic Functions.
|
* ctanl: (libc)Trig Functions.
|
* ctermid: (libc)Identifying the Terminal.
|
* ctime: (libc)Formatting Calendar Time.
|
* ctime_r: (libc)Formatting Calendar Time.
|
* cuserid: (libc)Who Logged In.
|
* daddl: (libc)Misc FP Arithmetic.
|
* dcgettext: (libc)Translation with gettext.
|
* dcngettext: (libc)Advanced gettext functions.
|
* ddivl: (libc)Misc FP Arithmetic.
|
* dgettext: (libc)Translation with gettext.
|
* difftime: (libc)Calculating Elapsed Time.
|
* dirfd: (libc)Opening a Directory.
|
* dirname: (libc)Finding Tokens in a String.
|
* div: (libc)Integer Division.
|
* dmull: (libc)Misc FP Arithmetic.
|
* dngettext: (libc)Advanced gettext functions.
|
* drand48: (libc)SVID Random.
|
* drand48_r: (libc)SVID Random.
|
* drem: (libc)Remainder Functions.
|
* dremf: (libc)Remainder Functions.
|
* dreml: (libc)Remainder Functions.
|
* dsubl: (libc)Misc FP Arithmetic.
|
* dup2: (libc)Duplicating Descriptors.
|
* dup: (libc)Duplicating Descriptors.
|
* ecvt: (libc)System V Number Conversion.
|
* ecvt_r: (libc)System V Number Conversion.
|
* endfsent: (libc)fstab.
|
* endgrent: (libc)Scanning All Groups.
|
* endhostent: (libc)Host Names.
|
* endmntent: (libc)mtab.
|
* endnetent: (libc)Networks Database.
|
* endnetgrent: (libc)Lookup Netgroup.
|
* endprotoent: (libc)Protocols Database.
|
* endpwent: (libc)Scanning All Users.
|
* endservent: (libc)Services Database.
|
* endutent: (libc)Manipulating the Database.
|
* endutxent: (libc)XPG Functions.
|
* envz_add: (libc)Envz Functions.
|
* envz_entry: (libc)Envz Functions.
|
* envz_get: (libc)Envz Functions.
|
* envz_merge: (libc)Envz Functions.
|
* envz_remove: (libc)Envz Functions.
|
* envz_strip: (libc)Envz Functions.
|
* erand48: (libc)SVID Random.
|
* erand48_r: (libc)SVID Random.
|
* erf: (libc)Special Functions.
|
* erfc: (libc)Special Functions.
|
* erfcf: (libc)Special Functions.
|
* erfcfN: (libc)Special Functions.
|
* erfcfNx: (libc)Special Functions.
|
* erfcl: (libc)Special Functions.
|
* erff: (libc)Special Functions.
|
* erffN: (libc)Special Functions.
|
* erffNx: (libc)Special Functions.
|
* erfl: (libc)Special Functions.
|
* err: (libc)Error Messages.
|
* errno: (libc)Checking for Errors.
|
* error: (libc)Error Messages.
|
* error_at_line: (libc)Error Messages.
|
* errx: (libc)Error Messages.
|
* execl: (libc)Executing a File.
|
* execle: (libc)Executing a File.
|
* execlp: (libc)Executing a File.
|
* execv: (libc)Executing a File.
|
* execve: (libc)Executing a File.
|
* execvp: (libc)Executing a File.
|
* exit: (libc)Normal Termination.
|
* exp10: (libc)Exponents and Logarithms.
|
* exp10f: (libc)Exponents and Logarithms.
|
* exp10fN: (libc)Exponents and Logarithms.
|
* exp10fNx: (libc)Exponents and Logarithms.
|
* exp10l: (libc)Exponents and Logarithms.
|
* exp2: (libc)Exponents and Logarithms.
|
* exp2f: (libc)Exponents and Logarithms.
|
* exp2fN: (libc)Exponents and Logarithms.
|
* exp2fNx: (libc)Exponents and Logarithms.
|
* exp2l: (libc)Exponents and Logarithms.
|
* exp: (libc)Exponents and Logarithms.
|
* expf: (libc)Exponents and Logarithms.
|
* expfN: (libc)Exponents and Logarithms.
|
* expfNx: (libc)Exponents and Logarithms.
|
* expl: (libc)Exponents and Logarithms.
|
* explicit_bzero: (libc)Erasing Sensitive Data.
|
* expm1: (libc)Exponents and Logarithms.
|
* expm1f: (libc)Exponents and Logarithms.
|
* expm1fN: (libc)Exponents and Logarithms.
|
* expm1fNx: (libc)Exponents and Logarithms.
|
* expm1l: (libc)Exponents and Logarithms.
|
* fMaddfN: (libc)Misc FP Arithmetic.
|
* fMaddfNx: (libc)Misc FP Arithmetic.
|
* fMdivfN: (libc)Misc FP Arithmetic.
|
* fMdivfNx: (libc)Misc FP Arithmetic.
|
* fMmulfN: (libc)Misc FP Arithmetic.
|
* fMmulfNx: (libc)Misc FP Arithmetic.
|
* fMsubfN: (libc)Misc FP Arithmetic.
|
* fMsubfNx: (libc)Misc FP Arithmetic.
|
* fMxaddfN: (libc)Misc FP Arithmetic.
|
* fMxaddfNx: (libc)Misc FP Arithmetic.
|
* fMxdivfN: (libc)Misc FP Arithmetic.
|
* fMxdivfNx: (libc)Misc FP Arithmetic.
|
* fMxmulfN: (libc)Misc FP Arithmetic.
|
* fMxmulfNx: (libc)Misc FP Arithmetic.
|
* fMxsubfN: (libc)Misc FP Arithmetic.
|
* fMxsubfNx: (libc)Misc FP Arithmetic.
|
* fabs: (libc)Absolute Value.
|
* fabsf: (libc)Absolute Value.
|
* fabsfN: (libc)Absolute Value.
|
* fabsfNx: (libc)Absolute Value.
|
* fabsl: (libc)Absolute Value.
|
* fadd: (libc)Misc FP Arithmetic.
|
* faddl: (libc)Misc FP Arithmetic.
|
* fchdir: (libc)Working Directory.
|
* fchmod: (libc)Setting Permissions.
|
* fchown: (libc)File Owner.
|
* fclose: (libc)Closing Streams.
|
* fcloseall: (libc)Closing Streams.
|
* fcntl: (libc)Control Operations.
|
* fcvt: (libc)System V Number Conversion.
|
* fcvt_r: (libc)System V Number Conversion.
|
* fdatasync: (libc)Synchronizing I/O.
|
* fdim: (libc)Misc FP Arithmetic.
|
* fdimf: (libc)Misc FP Arithmetic.
|
* fdimfN: (libc)Misc FP Arithmetic.
|
* fdimfNx: (libc)Misc FP Arithmetic.
|
* fdiml: (libc)Misc FP Arithmetic.
|
* fdiv: (libc)Misc FP Arithmetic.
|
* fdivl: (libc)Misc FP Arithmetic.
|
* fdopen: (libc)Descriptors and Streams.
|
* fdopendir: (libc)Opening a Directory.
|
* feclearexcept: (libc)Status bit operations.
|
* fedisableexcept: (libc)Control Functions.
|
* feenableexcept: (libc)Control Functions.
|
* fegetenv: (libc)Control Functions.
|
* fegetexcept: (libc)Control Functions.
|
* fegetexceptflag: (libc)Status bit operations.
|
* fegetmode: (libc)Control Functions.
|
* fegetround: (libc)Rounding.
|
* feholdexcept: (libc)Control Functions.
|
* feof: (libc)EOF and Errors.
|
* feof_unlocked: (libc)EOF and Errors.
|
* feraiseexcept: (libc)Status bit operations.
|
* ferror: (libc)EOF and Errors.
|
* ferror_unlocked: (libc)EOF and Errors.
|
* fesetenv: (libc)Control Functions.
|
* fesetexcept: (libc)Status bit operations.
|
* fesetexceptflag: (libc)Status bit operations.
|
* fesetmode: (libc)Control Functions.
|
* fesetround: (libc)Rounding.
|
* fetestexcept: (libc)Status bit operations.
|
* fetestexceptflag: (libc)Status bit operations.
|
* feupdateenv: (libc)Control Functions.
|
* fexecve: (libc)Executing a File.
|
* fflush: (libc)Flushing Buffers.
|
* fflush_unlocked: (libc)Flushing Buffers.
|
* fgetc: (libc)Character Input.
|
* fgetc_unlocked: (libc)Character Input.
|
* fgetgrent: (libc)Scanning All Groups.
|
* fgetgrent_r: (libc)Scanning All Groups.
|
* fgetpos64: (libc)Portable Positioning.
|
* fgetpos: (libc)Portable Positioning.
|
* fgetpwent: (libc)Scanning All Users.
|
* fgetpwent_r: (libc)Scanning All Users.
|
* fgets: (libc)Line Input.
|
* fgets_unlocked: (libc)Line Input.
|
* fgetwc: (libc)Character Input.
|
* fgetwc_unlocked: (libc)Character Input.
|
* fgetws: (libc)Line Input.
|
* fgetws_unlocked: (libc)Line Input.
|
* fileno: (libc)Descriptors and Streams.
|
* fileno_unlocked: (libc)Descriptors and Streams.
|
* finite: (libc)Floating Point Classes.
|
* finitef: (libc)Floating Point Classes.
|
* finitel: (libc)Floating Point Classes.
|
* flockfile: (libc)Streams and Threads.
|
* floor: (libc)Rounding Functions.
|
* floorf: (libc)Rounding Functions.
|
* floorfN: (libc)Rounding Functions.
|
* floorfNx: (libc)Rounding Functions.
|
* floorl: (libc)Rounding Functions.
|
* fma: (libc)Misc FP Arithmetic.
|
* fmaf: (libc)Misc FP Arithmetic.
|
* fmafN: (libc)Misc FP Arithmetic.
|
* fmafNx: (libc)Misc FP Arithmetic.
|
* fmal: (libc)Misc FP Arithmetic.
|
* fmax: (libc)Misc FP Arithmetic.
|
* fmaxf: (libc)Misc FP Arithmetic.
|
* fmaxfN: (libc)Misc FP Arithmetic.
|
* fmaxfNx: (libc)Misc FP Arithmetic.
|
* fmaxl: (libc)Misc FP Arithmetic.
|
* fmaxmag: (libc)Misc FP Arithmetic.
|
* fmaxmagf: (libc)Misc FP Arithmetic.
|
* fmaxmagfN: (libc)Misc FP Arithmetic.
|
* fmaxmagfNx: (libc)Misc FP Arithmetic.
|
* fmaxmagl: (libc)Misc FP Arithmetic.
|
* fmemopen: (libc)String Streams.
|
* fmin: (libc)Misc FP Arithmetic.
|
* fminf: (libc)Misc FP Arithmetic.
|
* fminfN: (libc)Misc FP Arithmetic.
|
* fminfNx: (libc)Misc FP Arithmetic.
|
* fminl: (libc)Misc FP Arithmetic.
|
* fminmag: (libc)Misc FP Arithmetic.
|
* fminmagf: (libc)Misc FP Arithmetic.
|
* fminmagfN: (libc)Misc FP Arithmetic.
|
* fminmagfNx: (libc)Misc FP Arithmetic.
|
* fminmagl: (libc)Misc FP Arithmetic.
|
* fmod: (libc)Remainder Functions.
|
* fmodf: (libc)Remainder Functions.
|
* fmodfN: (libc)Remainder Functions.
|
* fmodfNx: (libc)Remainder Functions.
|
* fmodl: (libc)Remainder Functions.
|
* fmtmsg: (libc)Printing Formatted Messages.
|
* fmul: (libc)Misc FP Arithmetic.
|
* fmull: (libc)Misc FP Arithmetic.
|
* fnmatch: (libc)Wildcard Matching.
|
* fopen64: (libc)Opening Streams.
|
* fopen: (libc)Opening Streams.
|
* fopencookie: (libc)Streams and Cookies.
|
* fork: (libc)Creating a Process.
|
* forkpty: (libc)Pseudo-Terminal Pairs.
|
* fpathconf: (libc)Pathconf.
|
* fpclassify: (libc)Floating Point Classes.
|
* fprintf: (libc)Formatted Output Functions.
|
* fputc: (libc)Simple Output.
|
* fputc_unlocked: (libc)Simple Output.
|
* fputs: (libc)Simple Output.
|
* fputs_unlocked: (libc)Simple Output.
|
* fputwc: (libc)Simple Output.
|
* fputwc_unlocked: (libc)Simple Output.
|
* fputws: (libc)Simple Output.
|
* fputws_unlocked: (libc)Simple Output.
|
* fread: (libc)Block Input/Output.
|
* fread_unlocked: (libc)Block Input/Output.
|
* free: (libc)Freeing after Malloc.
|
* freopen64: (libc)Opening Streams.
|
* freopen: (libc)Opening Streams.
|
* frexp: (libc)Normalization Functions.
|
* frexpf: (libc)Normalization Functions.
|
* frexpfN: (libc)Normalization Functions.
|
* frexpfNx: (libc)Normalization Functions.
|
* frexpl: (libc)Normalization Functions.
|
* fromfp: (libc)Rounding Functions.
|
* fromfpf: (libc)Rounding Functions.
|
* fromfpfN: (libc)Rounding Functions.
|
* fromfpfNx: (libc)Rounding Functions.
|
* fromfpl: (libc)Rounding Functions.
|
* fromfpx: (libc)Rounding Functions.
|
* fromfpxf: (libc)Rounding Functions.
|
* fromfpxfN: (libc)Rounding Functions.
|
* fromfpxfNx: (libc)Rounding Functions.
|
* fromfpxl: (libc)Rounding Functions.
|
* fscanf: (libc)Formatted Input Functions.
|
* fseek: (libc)File Positioning.
|
* fseeko64: (libc)File Positioning.
|
* fseeko: (libc)File Positioning.
|
* fsetpos64: (libc)Portable Positioning.
|
* fsetpos: (libc)Portable Positioning.
|
* fstat64: (libc)Reading Attributes.
|
* fstat: (libc)Reading Attributes.
|
* fsub: (libc)Misc FP Arithmetic.
|
* fsubl: (libc)Misc FP Arithmetic.
|
* fsync: (libc)Synchronizing I/O.
|
* ftell: (libc)File Positioning.
|
* ftello64: (libc)File Positioning.
|
* ftello: (libc)File Positioning.
|
* ftruncate64: (libc)File Size.
|
* ftruncate: (libc)File Size.
|
* ftrylockfile: (libc)Streams and Threads.
|
* ftw64: (libc)Working with Directory Trees.
|
* ftw: (libc)Working with Directory Trees.
|
* funlockfile: (libc)Streams and Threads.
|
* futimes: (libc)File Times.
|
* fwide: (libc)Streams and I18N.
|
* fwprintf: (libc)Formatted Output Functions.
|
* fwrite: (libc)Block Input/Output.
|
* fwrite_unlocked: (libc)Block Input/Output.
|
* fwscanf: (libc)Formatted Input Functions.
|
* gamma: (libc)Special Functions.
|
* gammaf: (libc)Special Functions.
|
* gammal: (libc)Special Functions.
|
* gcvt: (libc)System V Number Conversion.
|
* get_avphys_pages: (libc)Query Memory Parameters.
|
* get_current_dir_name: (libc)Working Directory.
|
* get_nprocs: (libc)Processor Resources.
|
* get_nprocs_conf: (libc)Processor Resources.
|
* get_phys_pages: (libc)Query Memory Parameters.
|
* getauxval: (libc)Auxiliary Vector.
|
* getc: (libc)Character Input.
|
* getc_unlocked: (libc)Character Input.
|
* getchar: (libc)Character Input.
|
* getchar_unlocked: (libc)Character Input.
|
* getcontext: (libc)System V contexts.
|
* getcpu: (libc)CPU Affinity.
|
* getcwd: (libc)Working Directory.
|
* getdate: (libc)General Time String Parsing.
|
* getdate_r: (libc)General Time String Parsing.
|
* getdelim: (libc)Line Input.
|
* getdents64: (libc)Low-level Directory Access.
|
* getdomainnname: (libc)Host Identification.
|
* getegid: (libc)Reading Persona.
|
* getentropy: (libc)Unpredictable Bytes.
|
* getenv: (libc)Environment Access.
|
* geteuid: (libc)Reading Persona.
|
* getfsent: (libc)fstab.
|
* getfsfile: (libc)fstab.
|
* getfsspec: (libc)fstab.
|
* getgid: (libc)Reading Persona.
|
* getgrent: (libc)Scanning All Groups.
|
* getgrent_r: (libc)Scanning All Groups.
|
* getgrgid: (libc)Lookup Group.
|
* getgrgid_r: (libc)Lookup Group.
|
* getgrnam: (libc)Lookup Group.
|
* getgrnam_r: (libc)Lookup Group.
|
* getgrouplist: (libc)Setting Groups.
|
* getgroups: (libc)Reading Persona.
|
* gethostbyaddr: (libc)Host Names.
|
* gethostbyaddr_r: (libc)Host Names.
|
* gethostbyname2: (libc)Host Names.
|
* gethostbyname2_r: (libc)Host Names.
|
* gethostbyname: (libc)Host Names.
|
* gethostbyname_r: (libc)Host Names.
|
* gethostent: (libc)Host Names.
|
* gethostid: (libc)Host Identification.
|
* gethostname: (libc)Host Identification.
|
* getitimer: (libc)Setting an Alarm.
|
* getline: (libc)Line Input.
|
* getloadavg: (libc)Processor Resources.
|
* getlogin: (libc)Who Logged In.
|
* getmntent: (libc)mtab.
|
* getmntent_r: (libc)mtab.
|
* getnetbyaddr: (libc)Networks Database.
|
* getnetbyname: (libc)Networks Database.
|
* getnetent: (libc)Networks Database.
|
* getnetgrent: (libc)Lookup Netgroup.
|
* getnetgrent_r: (libc)Lookup Netgroup.
|
* getopt: (libc)Using Getopt.
|
* getopt_long: (libc)Getopt Long Options.
|
* getopt_long_only: (libc)Getopt Long Options.
|
* getpagesize: (libc)Query Memory Parameters.
|
* getpass: (libc)getpass.
|
* getpayload: (libc)FP Bit Twiddling.
|
* getpayloadf: (libc)FP Bit Twiddling.
|
* getpayloadfN: (libc)FP Bit Twiddling.
|
* getpayloadfNx: (libc)FP Bit Twiddling.
|
* getpayloadl: (libc)FP Bit Twiddling.
|
* getpeername: (libc)Who is Connected.
|
* getpgid: (libc)Process Group Functions.
|
* getpgrp: (libc)Process Group Functions.
|
* getpid: (libc)Process Identification.
|
* getppid: (libc)Process Identification.
|
* getpriority: (libc)Traditional Scheduling Functions.
|
* getprotobyname: (libc)Protocols Database.
|
* getprotobynumber: (libc)Protocols Database.
|
* getprotoent: (libc)Protocols Database.
|
* getpt: (libc)Allocation.
|
* getpwent: (libc)Scanning All Users.
|
* getpwent_r: (libc)Scanning All Users.
|
* getpwnam: (libc)Lookup User.
|
* getpwnam_r: (libc)Lookup User.
|
* getpwuid: (libc)Lookup User.
|
* getpwuid_r: (libc)Lookup User.
|
* getrandom: (libc)Unpredictable Bytes.
|
* getrlimit64: (libc)Limits on Resources.
|
* getrlimit: (libc)Limits on Resources.
|
* getrusage: (libc)Resource Usage.
|
* gets: (libc)Line Input.
|
* getservbyname: (libc)Services Database.
|
* getservbyport: (libc)Services Database.
|
* getservent: (libc)Services Database.
|
* getsid: (libc)Process Group Functions.
|
* getsockname: (libc)Reading Address.
|
* getsockopt: (libc)Socket Option Functions.
|
* getsubopt: (libc)Suboptions.
|
* gettext: (libc)Translation with gettext.
|
* gettid: (libc)Process Identification.
|
* gettimeofday: (libc)Getting the Time.
|
* getuid: (libc)Reading Persona.
|
* getumask: (libc)Setting Permissions.
|
* getutent: (libc)Manipulating the Database.
|
* getutent_r: (libc)Manipulating the Database.
|
* getutid: (libc)Manipulating the Database.
|
* getutid_r: (libc)Manipulating the Database.
|
* getutline: (libc)Manipulating the Database.
|
* getutline_r: (libc)Manipulating the Database.
|
* getutmp: (libc)XPG Functions.
|
* getutmpx: (libc)XPG Functions.
|
* getutxent: (libc)XPG Functions.
|
* getutxid: (libc)XPG Functions.
|
* getutxline: (libc)XPG Functions.
|
* getw: (libc)Character Input.
|
* getwc: (libc)Character Input.
|
* getwc_unlocked: (libc)Character Input.
|
* getwchar: (libc)Character Input.
|
* getwchar_unlocked: (libc)Character Input.
|
* getwd: (libc)Working Directory.
|
* glob64: (libc)Calling Glob.
|
* glob: (libc)Calling Glob.
|
* globfree64: (libc)More Flags for Globbing.
|
* globfree: (libc)More Flags for Globbing.
|
* gmtime: (libc)Broken-down Time.
|
* gmtime_r: (libc)Broken-down Time.
|
* grantpt: (libc)Allocation.
|
* gsignal: (libc)Signaling Yourself.
|
* gtty: (libc)BSD Terminal Modes.
|
* hasmntopt: (libc)mtab.
|
* hcreate: (libc)Hash Search Function.
|
* hcreate_r: (libc)Hash Search Function.
|
* hdestroy: (libc)Hash Search Function.
|
* hdestroy_r: (libc)Hash Search Function.
|
* hsearch: (libc)Hash Search Function.
|
* hsearch_r: (libc)Hash Search Function.
|
* htonl: (libc)Byte Order.
|
* htons: (libc)Byte Order.
|
* hypot: (libc)Exponents and Logarithms.
|
* hypotf: (libc)Exponents and Logarithms.
|
* hypotfN: (libc)Exponents and Logarithms.
|
* hypotfNx: (libc)Exponents and Logarithms.
|
* hypotl: (libc)Exponents and Logarithms.
|
* iconv: (libc)Generic Conversion Interface.
|
* iconv_close: (libc)Generic Conversion Interface.
|
* iconv_open: (libc)Generic Conversion Interface.
|
* if_freenameindex: (libc)Interface Naming.
|
* if_indextoname: (libc)Interface Naming.
|
* if_nameindex: (libc)Interface Naming.
|
* if_nametoindex: (libc)Interface Naming.
|
* ilogb: (libc)Exponents and Logarithms.
|
* ilogbf: (libc)Exponents and Logarithms.
|
* ilogbfN: (libc)Exponents and Logarithms.
|
* ilogbfNx: (libc)Exponents and Logarithms.
|
* ilogbl: (libc)Exponents and Logarithms.
|
* imaxabs: (libc)Absolute Value.
|
* imaxdiv: (libc)Integer Division.
|
* in6addr_any: (libc)Host Address Data Type.
|
* in6addr_loopback: (libc)Host Address Data Type.
|
* index: (libc)Search Functions.
|
* inet_addr: (libc)Host Address Functions.
|
* inet_aton: (libc)Host Address Functions.
|
* inet_lnaof: (libc)Host Address Functions.
|
* inet_makeaddr: (libc)Host Address Functions.
|
* inet_netof: (libc)Host Address Functions.
|
* inet_network: (libc)Host Address Functions.
|
* inet_ntoa: (libc)Host Address Functions.
|
* inet_ntop: (libc)Host Address Functions.
|
* inet_pton: (libc)Host Address Functions.
|
* initgroups: (libc)Setting Groups.
|
* initstate: (libc)BSD Random.
|
* initstate_r: (libc)BSD Random.
|
* innetgr: (libc)Netgroup Membership.
|
* ioctl: (libc)IOCTLs.
|
* isalnum: (libc)Classification of Characters.
|
* isalpha: (libc)Classification of Characters.
|
* isascii: (libc)Classification of Characters.
|
* isatty: (libc)Is It a Terminal.
|
* isblank: (libc)Classification of Characters.
|
* iscanonical: (libc)Floating Point Classes.
|
* iscntrl: (libc)Classification of Characters.
|
* isdigit: (libc)Classification of Characters.
|
* iseqsig: (libc)FP Comparison Functions.
|
* isfinite: (libc)Floating Point Classes.
|
* isgraph: (libc)Classification of Characters.
|
* isgreater: (libc)FP Comparison Functions.
|
* isgreaterequal: (libc)FP Comparison Functions.
|
* isinf: (libc)Floating Point Classes.
|
* isinff: (libc)Floating Point Classes.
|
* isinfl: (libc)Floating Point Classes.
|
* isless: (libc)FP Comparison Functions.
|
* islessequal: (libc)FP Comparison Functions.
|
* islessgreater: (libc)FP Comparison Functions.
|
* islower: (libc)Classification of Characters.
|
* isnan: (libc)Floating Point Classes.
|
* isnan: (libc)Floating Point Classes.
|
* isnanf: (libc)Floating Point Classes.
|
* isnanl: (libc)Floating Point Classes.
|
* isnormal: (libc)Floating Point Classes.
|
* isprint: (libc)Classification of Characters.
|
* ispunct: (libc)Classification of Characters.
|
* issignaling: (libc)Floating Point Classes.
|
* isspace: (libc)Classification of Characters.
|
* issubnormal: (libc)Floating Point Classes.
|
* isunordered: (libc)FP Comparison Functions.
|
* isupper: (libc)Classification of Characters.
|
* iswalnum: (libc)Classification of Wide Characters.
|
* iswalpha: (libc)Classification of Wide Characters.
|
* iswblank: (libc)Classification of Wide Characters.
|
* iswcntrl: (libc)Classification of Wide Characters.
|
* iswctype: (libc)Classification of Wide Characters.
|
* iswdigit: (libc)Classification of Wide Characters.
|
* iswgraph: (libc)Classification of Wide Characters.
|
* iswlower: (libc)Classification of Wide Characters.
|
* iswprint: (libc)Classification of Wide Characters.
|
* iswpunct: (libc)Classification of Wide Characters.
|
* iswspace: (libc)Classification of Wide Characters.
|
* iswupper: (libc)Classification of Wide Characters.
|
* iswxdigit: (libc)Classification of Wide Characters.
|
* isxdigit: (libc)Classification of Characters.
|
* iszero: (libc)Floating Point Classes.
|
* j0: (libc)Special Functions.
|
* j0f: (libc)Special Functions.
|
* j0fN: (libc)Special Functions.
|
* j0fNx: (libc)Special Functions.
|
* j0l: (libc)Special Functions.
|
* j1: (libc)Special Functions.
|
* j1f: (libc)Special Functions.
|
* j1fN: (libc)Special Functions.
|
* j1fNx: (libc)Special Functions.
|
* j1l: (libc)Special Functions.
|
* jn: (libc)Special Functions.
|
* jnf: (libc)Special Functions.
|
* jnfN: (libc)Special Functions.
|
* jnfNx: (libc)Special Functions.
|
* jnl: (libc)Special Functions.
|
* jrand48: (libc)SVID Random.
|
* jrand48_r: (libc)SVID Random.
|
* kill: (libc)Signaling Another Process.
|
* killpg: (libc)Signaling Another Process.
|
* l64a: (libc)Encode Binary Data.
|
* labs: (libc)Absolute Value.
|
* lcong48: (libc)SVID Random.
|
* lcong48_r: (libc)SVID Random.
|
* ldexp: (libc)Normalization Functions.
|
* ldexpf: (libc)Normalization Functions.
|
* ldexpfN: (libc)Normalization Functions.
|
* ldexpfNx: (libc)Normalization Functions.
|
* ldexpl: (libc)Normalization Functions.
|
* ldiv: (libc)Integer Division.
|
* lfind: (libc)Array Search Function.
|
* lgamma: (libc)Special Functions.
|
* lgamma_r: (libc)Special Functions.
|
* lgammaf: (libc)Special Functions.
|
* lgammafN: (libc)Special Functions.
|
* lgammafN_r: (libc)Special Functions.
|
* lgammafNx: (libc)Special Functions.
|
* lgammafNx_r: (libc)Special Functions.
|
* lgammaf_r: (libc)Special Functions.
|
* lgammal: (libc)Special Functions.
|
* lgammal_r: (libc)Special Functions.
|
* link: (libc)Hard Links.
|
* linkat: (libc)Hard Links.
|
* lio_listio64: (libc)Asynchronous Reads/Writes.
|
* lio_listio: (libc)Asynchronous Reads/Writes.
|
* listen: (libc)Listening.
|
* llabs: (libc)Absolute Value.
|
* lldiv: (libc)Integer Division.
|
* llogb: (libc)Exponents and Logarithms.
|
* llogbf: (libc)Exponents and Logarithms.
|
* llogbfN: (libc)Exponents and Logarithms.
|
* llogbfNx: (libc)Exponents and Logarithms.
|
* llogbl: (libc)Exponents and Logarithms.
|
* llrint: (libc)Rounding Functions.
|
* llrintf: (libc)Rounding Functions.
|
* llrintfN: (libc)Rounding Functions.
|
* llrintfNx: (libc)Rounding Functions.
|
* llrintl: (libc)Rounding Functions.
|
* llround: (libc)Rounding Functions.
|
* llroundf: (libc)Rounding Functions.
|
* llroundfN: (libc)Rounding Functions.
|
* llroundfNx: (libc)Rounding Functions.
|
* llroundl: (libc)Rounding Functions.
|
* localeconv: (libc)The Lame Way to Locale Data.
|
* localtime: (libc)Broken-down Time.
|
* localtime_r: (libc)Broken-down Time.
|
* log10: (libc)Exponents and Logarithms.
|
* log10f: (libc)Exponents and Logarithms.
|
* log10fN: (libc)Exponents and Logarithms.
|
* log10fNx: (libc)Exponents and Logarithms.
|
* log10l: (libc)Exponents and Logarithms.
|
* log1p: (libc)Exponents and Logarithms.
|
* log1pf: (libc)Exponents and Logarithms.
|
* log1pfN: (libc)Exponents and Logarithms.
|
* log1pfNx: (libc)Exponents and Logarithms.
|
* log1pl: (libc)Exponents and Logarithms.
|
* log2: (libc)Exponents and Logarithms.
|
* log2f: (libc)Exponents and Logarithms.
|
* log2fN: (libc)Exponents and Logarithms.
|
* log2fNx: (libc)Exponents and Logarithms.
|
* log2l: (libc)Exponents and Logarithms.
|
* log: (libc)Exponents and Logarithms.
|
* logb: (libc)Exponents and Logarithms.
|
* logbf: (libc)Exponents and Logarithms.
|
* logbfN: (libc)Exponents and Logarithms.
|
* logbfNx: (libc)Exponents and Logarithms.
|
* logbl: (libc)Exponents and Logarithms.
|
* logf: (libc)Exponents and Logarithms.
|
* logfN: (libc)Exponents and Logarithms.
|
* logfNx: (libc)Exponents and Logarithms.
|
* login: (libc)Logging In and Out.
|
* login_tty: (libc)Logging In and Out.
|
* logl: (libc)Exponents and Logarithms.
|
* logout: (libc)Logging In and Out.
|
* logwtmp: (libc)Logging In and Out.
|
* longjmp: (libc)Non-Local Details.
|
* lrand48: (libc)SVID Random.
|
* lrand48_r: (libc)SVID Random.
|
* lrint: (libc)Rounding Functions.
|
* lrintf: (libc)Rounding Functions.
|
* lrintfN: (libc)Rounding Functions.
|
* lrintfNx: (libc)Rounding Functions.
|
* lrintl: (libc)Rounding Functions.
|
* lround: (libc)Rounding Functions.
|
* lroundf: (libc)Rounding Functions.
|
* lroundfN: (libc)Rounding Functions.
|
* lroundfNx: (libc)Rounding Functions.
|
* lroundl: (libc)Rounding Functions.
|
* lsearch: (libc)Array Search Function.
|
* lseek64: (libc)File Position Primitive.
|
* lseek: (libc)File Position Primitive.
|
* lstat64: (libc)Reading Attributes.
|
* lstat: (libc)Reading Attributes.
|
* lutimes: (libc)File Times.
|
* madvise: (libc)Memory-mapped I/O.
|
* makecontext: (libc)System V contexts.
|
* mallinfo2: (libc)Statistics of Malloc.
|
* malloc: (libc)Basic Allocation.
|
* mallopt: (libc)Malloc Tunable Parameters.
|
* mblen: (libc)Non-reentrant Character Conversion.
|
* mbrlen: (libc)Converting a Character.
|
* mbrtowc: (libc)Converting a Character.
|
* mbsinit: (libc)Keeping the state.
|
* mbsnrtowcs: (libc)Converting Strings.
|
* mbsrtowcs: (libc)Converting Strings.
|
* mbstowcs: (libc)Non-reentrant String Conversion.
|
* mbtowc: (libc)Non-reentrant Character Conversion.
|
* mcheck: (libc)Heap Consistency Checking.
|
* memalign: (libc)Aligned Memory Blocks.
|
* memccpy: (libc)Copying Strings and Arrays.
|
* memchr: (libc)Search Functions.
|
* memcmp: (libc)String/Array Comparison.
|
* memcpy: (libc)Copying Strings and Arrays.
|
* memfd_create: (libc)Memory-mapped I/O.
|
* memfrob: (libc)Obfuscating Data.
|
* memmem: (libc)Search Functions.
|
* memmove: (libc)Copying Strings and Arrays.
|
* mempcpy: (libc)Copying Strings and Arrays.
|
* memrchr: (libc)Search Functions.
|
* memset: (libc)Copying Strings and Arrays.
|
* mkdir: (libc)Creating Directories.
|
* mkdtemp: (libc)Temporary Files.
|
* mkfifo: (libc)FIFO Special Files.
|
* mknod: (libc)Making Special Files.
|
* mkstemp: (libc)Temporary Files.
|
* mktemp: (libc)Temporary Files.
|
* mktime: (libc)Broken-down Time.
|
* mlock2: (libc)Page Lock Functions.
|
* mlock: (libc)Page Lock Functions.
|
* mlockall: (libc)Page Lock Functions.
|
* mmap64: (libc)Memory-mapped I/O.
|
* mmap: (libc)Memory-mapped I/O.
|
* modf: (libc)Rounding Functions.
|
* modff: (libc)Rounding Functions.
|
* modffN: (libc)Rounding Functions.
|
* modffNx: (libc)Rounding Functions.
|
* modfl: (libc)Rounding Functions.
|
* mount: (libc)Mount-Unmount-Remount.
|
* mprobe: (libc)Heap Consistency Checking.
|
* mprotect: (libc)Memory Protection.
|
* mrand48: (libc)SVID Random.
|
* mrand48_r: (libc)SVID Random.
|
* mremap: (libc)Memory-mapped I/O.
|
* msync: (libc)Memory-mapped I/O.
|
* mtrace: (libc)Tracing malloc.
|
* mtx_destroy: (libc)ISO C Mutexes.
|
* mtx_init: (libc)ISO C Mutexes.
|
* mtx_lock: (libc)ISO C Mutexes.
|
* mtx_timedlock: (libc)ISO C Mutexes.
|
* mtx_trylock: (libc)ISO C Mutexes.
|
* mtx_unlock: (libc)ISO C Mutexes.
|
* munlock: (libc)Page Lock Functions.
|
* munlockall: (libc)Page Lock Functions.
|
* munmap: (libc)Memory-mapped I/O.
|
* muntrace: (libc)Tracing malloc.
|
* nan: (libc)FP Bit Twiddling.
|
* nanf: (libc)FP Bit Twiddling.
|
* nanfN: (libc)FP Bit Twiddling.
|
* nanfNx: (libc)FP Bit Twiddling.
|
* nanl: (libc)FP Bit Twiddling.
|
* nanosleep: (libc)Sleeping.
|
* nearbyint: (libc)Rounding Functions.
|
* nearbyintf: (libc)Rounding Functions.
|
* nearbyintfN: (libc)Rounding Functions.
|
* nearbyintfNx: (libc)Rounding Functions.
|
* nearbyintl: (libc)Rounding Functions.
|
* nextafter: (libc)FP Bit Twiddling.
|
* nextafterf: (libc)FP Bit Twiddling.
|
* nextafterfN: (libc)FP Bit Twiddling.
|
* nextafterfNx: (libc)FP Bit Twiddling.
|
* nextafterl: (libc)FP Bit Twiddling.
|
* nextdown: (libc)FP Bit Twiddling.
|
* nextdownf: (libc)FP Bit Twiddling.
|
* nextdownfN: (libc)FP Bit Twiddling.
|
* nextdownfNx: (libc)FP Bit Twiddling.
|
* nextdownl: (libc)FP Bit Twiddling.
|
* nexttoward: (libc)FP Bit Twiddling.
|
* nexttowardf: (libc)FP Bit Twiddling.
|
* nexttowardl: (libc)FP Bit Twiddling.
|
* nextup: (libc)FP Bit Twiddling.
|
* nextupf: (libc)FP Bit Twiddling.
|
* nextupfN: (libc)FP Bit Twiddling.
|
* nextupfNx: (libc)FP Bit Twiddling.
|
* nextupl: (libc)FP Bit Twiddling.
|
* nftw64: (libc)Working with Directory Trees.
|
* nftw: (libc)Working with Directory Trees.
|
* ngettext: (libc)Advanced gettext functions.
|
* nice: (libc)Traditional Scheduling Functions.
|
* nl_langinfo: (libc)The Elegant and Fast Way.
|
* nrand48: (libc)SVID Random.
|
* nrand48_r: (libc)SVID Random.
|
* ntohl: (libc)Byte Order.
|
* ntohs: (libc)Byte Order.
|
* ntp_adjtime: (libc)Setting and Adjusting the Time.
|
* ntp_gettime: (libc)Setting and Adjusting the Time.
|
* obstack_1grow: (libc)Growing Objects.
|
* obstack_1grow_fast: (libc)Extra Fast Growing.
|
* obstack_alignment_mask: (libc)Obstacks Data Alignment.
|
* obstack_alloc: (libc)Allocation in an Obstack.
|
* obstack_base: (libc)Status of an Obstack.
|
* obstack_blank: (libc)Growing Objects.
|
* obstack_blank_fast: (libc)Extra Fast Growing.
|
* obstack_chunk_size: (libc)Obstack Chunks.
|
* obstack_copy0: (libc)Allocation in an Obstack.
|
* obstack_copy: (libc)Allocation in an Obstack.
|
* obstack_finish: (libc)Growing Objects.
|
* obstack_free: (libc)Freeing Obstack Objects.
|
* obstack_grow0: (libc)Growing Objects.
|
* obstack_grow: (libc)Growing Objects.
|
* obstack_init: (libc)Preparing for Obstacks.
|
* obstack_int_grow: (libc)Growing Objects.
|
* obstack_int_grow_fast: (libc)Extra Fast Growing.
|
* obstack_next_free: (libc)Status of an Obstack.
|
* obstack_object_size: (libc)Growing Objects.
|
* obstack_object_size: (libc)Status of an Obstack.
|
* obstack_printf: (libc)Dynamic Output.
|
* obstack_ptr_grow: (libc)Growing Objects.
|
* obstack_ptr_grow_fast: (libc)Extra Fast Growing.
|
* obstack_room: (libc)Extra Fast Growing.
|
* obstack_vprintf: (libc)Variable Arguments Output.
|
* offsetof: (libc)Structure Measurement.
|
* on_exit: (libc)Cleanups on Exit.
|
* open64: (libc)Opening and Closing Files.
|
* open: (libc)Opening and Closing Files.
|
* open_memstream: (libc)String Streams.
|
* opendir: (libc)Opening a Directory.
|
* openlog: (libc)openlog.
|
* openpty: (libc)Pseudo-Terminal Pairs.
|
* parse_printf_format: (libc)Parsing a Template String.
|
* pathconf: (libc)Pathconf.
|
* pause: (libc)Using Pause.
|
* pclose: (libc)Pipe to a Subprocess.
|
* perror: (libc)Error Messages.
|
* pipe: (libc)Creating a Pipe.
|
* pkey_alloc: (libc)Memory Protection.
|
* pkey_free: (libc)Memory Protection.
|
* pkey_get: (libc)Memory Protection.
|
* pkey_mprotect: (libc)Memory Protection.
|
* pkey_set: (libc)Memory Protection.
|
* popen: (libc)Pipe to a Subprocess.
|
* posix_fallocate64: (libc)Storage Allocation.
|
* posix_fallocate: (libc)Storage Allocation.
|
* posix_memalign: (libc)Aligned Memory Blocks.
|
* pow: (libc)Exponents and Logarithms.
|
* powf: (libc)Exponents and Logarithms.
|
* powfN: (libc)Exponents and Logarithms.
|
* powfNx: (libc)Exponents and Logarithms.
|
* powl: (libc)Exponents and Logarithms.
|
* pread64: (libc)I/O Primitives.
|
* pread: (libc)I/O Primitives.
|
* preadv2: (libc)Scatter-Gather.
|
* preadv64: (libc)Scatter-Gather.
|
* preadv64v2: (libc)Scatter-Gather.
|
* preadv: (libc)Scatter-Gather.
|
* printf: (libc)Formatted Output Functions.
|
* printf_size: (libc)Predefined Printf Handlers.
|
* printf_size_info: (libc)Predefined Printf Handlers.
|
* psignal: (libc)Signal Messages.
|
* pthread_attr_getsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_attr_setsigmask_np: (libc)Initial Thread Signal Mask.
|
* pthread_clockjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_cond_clockwait: (libc)Waiting with Explicit Clocks.
|
* pthread_getattr_default_np: (libc)Default Thread Attributes.
|
* pthread_getspecific: (libc)Thread-specific Data.
|
* pthread_key_create: (libc)Thread-specific Data.
|
* pthread_key_delete: (libc)Thread-specific Data.
|
* pthread_rwlock_clockrdlock: (libc)Waiting with Explicit Clocks.
|
* pthread_rwlock_clockwrlock: (libc)Waiting with Explicit Clocks.
|
* pthread_setattr_default_np: (libc)Default Thread Attributes.
|
* pthread_setspecific: (libc)Thread-specific Data.
|
* pthread_timedjoin_np: (libc)Waiting with Explicit Clocks.
|
* pthread_tryjoin_np: (libc)Waiting with Explicit Clocks.
|
* ptsname: (libc)Allocation.
|
* ptsname_r: (libc)Allocation.
|
* putc: (libc)Simple Output.
|
* putc_unlocked: (libc)Simple Output.
|
* putchar: (libc)Simple Output.
|
* putchar_unlocked: (libc)Simple Output.
|
* putenv: (libc)Environment Access.
|
* putpwent: (libc)Writing a User Entry.
|
* puts: (libc)Simple Output.
|
* pututline: (libc)Manipulating the Database.
|
* pututxline: (libc)XPG Functions.
|
* putw: (libc)Simple Output.
|
* putwc: (libc)Simple Output.
|
* putwc_unlocked: (libc)Simple Output.
|
* putwchar: (libc)Simple Output.
|
* putwchar_unlocked: (libc)Simple Output.
|
* pwrite64: (libc)I/O Primitives.
|
* pwrite: (libc)I/O Primitives.
|
* pwritev2: (libc)Scatter-Gather.
|
* pwritev64: (libc)Scatter-Gather.
|
* pwritev64v2: (libc)Scatter-Gather.
|
* pwritev: (libc)Scatter-Gather.
|
* qecvt: (libc)System V Number Conversion.
|
* qecvt_r: (libc)System V Number Conversion.
|
* qfcvt: (libc)System V Number Conversion.
|
* qfcvt_r: (libc)System V Number Conversion.
|
* qgcvt: (libc)System V Number Conversion.
|
* qsort: (libc)Array Sort Function.
|
* raise: (libc)Signaling Yourself.
|
* rand: (libc)ISO Random.
|
* rand_r: (libc)ISO Random.
|
* random: (libc)BSD Random.
|
* random_r: (libc)BSD Random.
|
* rawmemchr: (libc)Search Functions.
|
* read: (libc)I/O Primitives.
|
* readdir64: (libc)Reading/Closing Directory.
|
* readdir64_r: (libc)Reading/Closing Directory.
|
* readdir: (libc)Reading/Closing Directory.
|
* readdir_r: (libc)Reading/Closing Directory.
|
* readlink: (libc)Symbolic Links.
|
* readv: (libc)Scatter-Gather.
|
* realloc: (libc)Changing Block Size.
|
* reallocarray: (libc)Changing Block Size.
|
* realpath: (libc)Symbolic Links.
|
* recv: (libc)Receiving Data.
|
* recvfrom: (libc)Receiving Datagrams.
|
* recvmsg: (libc)Receiving Datagrams.
|
* regcomp: (libc)POSIX Regexp Compilation.
|
* regerror: (libc)Regexp Cleanup.
|
* regexec: (libc)Matching POSIX Regexps.
|
* regfree: (libc)Regexp Cleanup.
|
* register_printf_function: (libc)Registering New Conversions.
|
* remainder: (libc)Remainder Functions.
|
* remainderf: (libc)Remainder Functions.
|
* remainderfN: (libc)Remainder Functions.
|
* remainderfNx: (libc)Remainder Functions.
|
* remainderl: (libc)Remainder Functions.
|
* remove: (libc)Deleting Files.
|
* rename: (libc)Renaming Files.
|
* rewind: (libc)File Positioning.
|
* rewinddir: (libc)Random Access Directory.
|
* rindex: (libc)Search Functions.
|
* rint: (libc)Rounding Functions.
|
* rintf: (libc)Rounding Functions.
|
* rintfN: (libc)Rounding Functions.
|
* rintfNx: (libc)Rounding Functions.
|
* rintl: (libc)Rounding Functions.
|
* rmdir: (libc)Deleting Files.
|
* round: (libc)Rounding Functions.
|
* roundeven: (libc)Rounding Functions.
|
* roundevenf: (libc)Rounding Functions.
|
* roundevenfN: (libc)Rounding Functions.
|
* roundevenfNx: (libc)Rounding Functions.
|
* roundevenl: (libc)Rounding Functions.
|
* roundf: (libc)Rounding Functions.
|
* roundfN: (libc)Rounding Functions.
|
* roundfNx: (libc)Rounding Functions.
|
* roundl: (libc)Rounding Functions.
|
* rpmatch: (libc)Yes-or-No Questions.
|
* sbrk: (libc)Resizing the Data Segment.
|
* scalb: (libc)Normalization Functions.
|
* scalbf: (libc)Normalization Functions.
|
* scalbl: (libc)Normalization Functions.
|
* scalbln: (libc)Normalization Functions.
|
* scalblnf: (libc)Normalization Functions.
|
* scalblnfN: (libc)Normalization Functions.
|
* scalblnfNx: (libc)Normalization Functions.
|
* scalblnl: (libc)Normalization Functions.
|
* scalbn: (libc)Normalization Functions.
|
* scalbnf: (libc)Normalization Functions.
|
* scalbnfN: (libc)Normalization Functions.
|
* scalbnfNx: (libc)Normalization Functions.
|
* scalbnl: (libc)Normalization Functions.
|
* scandir64: (libc)Scanning Directory Content.
|
* scandir: (libc)Scanning Directory Content.
|
* scanf: (libc)Formatted Input Functions.
|
* sched_get_priority_max: (libc)Basic Scheduling Functions.
|
* sched_get_priority_min: (libc)Basic Scheduling Functions.
|
* sched_getaffinity: (libc)CPU Affinity.
|
* sched_getparam: (libc)Basic Scheduling Functions.
|
* sched_getscheduler: (libc)Basic Scheduling Functions.
|
* sched_rr_get_interval: (libc)Basic Scheduling Functions.
|
* sched_setaffinity: (libc)CPU Affinity.
|
* sched_setparam: (libc)Basic Scheduling Functions.
|
* sched_setscheduler: (libc)Basic Scheduling Functions.
|
* sched_yield: (libc)Basic Scheduling Functions.
|
* secure_getenv: (libc)Environment Access.
|
* seed48: (libc)SVID Random.
|
* seed48_r: (libc)SVID Random.
|
* seekdir: (libc)Random Access Directory.
|
* select: (libc)Waiting for I/O.
|
* sem_clockwait: (libc)Waiting with Explicit Clocks.
|
* sem_close: (libc)Semaphores.
|
* sem_destroy: (libc)Semaphores.
|
* sem_getvalue: (libc)Semaphores.
|
* sem_init: (libc)Semaphores.
|
* sem_open: (libc)Semaphores.
|
* sem_post: (libc)Semaphores.
|
* sem_timedwait: (libc)Semaphores.
|
* sem_trywait: (libc)Semaphores.
|
* sem_unlink: (libc)Semaphores.
|
* sem_wait: (libc)Semaphores.
|
* semctl: (libc)Semaphores.
|
* semget: (libc)Semaphores.
|
* semop: (libc)Semaphores.
|
* semtimedop: (libc)Semaphores.
|
* send: (libc)Sending Data.
|
* sendmsg: (libc)Receiving Datagrams.
|
* sendto: (libc)Sending Datagrams.
|
* setbuf: (libc)Controlling Buffering.
|
* setbuffer: (libc)Controlling Buffering.
|
* setcontext: (libc)System V contexts.
|
* setdomainname: (libc)Host Identification.
|
* setegid: (libc)Setting Groups.
|
* setenv: (libc)Environment Access.
|
* seteuid: (libc)Setting User ID.
|
* setfsent: (libc)fstab.
|
* setgid: (libc)Setting Groups.
|
* setgrent: (libc)Scanning All Groups.
|
* setgroups: (libc)Setting Groups.
|
* sethostent: (libc)Host Names.
|
* sethostid: (libc)Host Identification.
|
* sethostname: (libc)Host Identification.
|
* setitimer: (libc)Setting an Alarm.
|
* setjmp: (libc)Non-Local Details.
|
* setlinebuf: (libc)Controlling Buffering.
|
* setlocale: (libc)Setting the Locale.
|
* setlogmask: (libc)setlogmask.
|
* setmntent: (libc)mtab.
|
* setnetent: (libc)Networks Database.
|
* setnetgrent: (libc)Lookup Netgroup.
|
* setpayload: (libc)FP Bit Twiddling.
|
* setpayloadf: (libc)FP Bit Twiddling.
|
* setpayloadfN: (libc)FP Bit Twiddling.
|
* setpayloadfNx: (libc)FP Bit Twiddling.
|
* setpayloadl: (libc)FP Bit Twiddling.
|
* setpayloadsig: (libc)FP Bit Twiddling.
|
* setpayloadsigf: (libc)FP Bit Twiddling.
|
* setpayloadsigfN: (libc)FP Bit Twiddling.
|
* setpayloadsigfNx: (libc)FP Bit Twiddling.
|
* setpayloadsigl: (libc)FP Bit Twiddling.
|
* setpgid: (libc)Process Group Functions.
|
* setpgrp: (libc)Process Group Functions.
|
* setpriority: (libc)Traditional Scheduling Functions.
|
* setprotoent: (libc)Protocols Database.
|
* setpwent: (libc)Scanning All Users.
|
* setregid: (libc)Setting Groups.
|
* setreuid: (libc)Setting User ID.
|
* setrlimit64: (libc)Limits on Resources.
|
* setrlimit: (libc)Limits on Resources.
|
* setservent: (libc)Services Database.
|
* setsid: (libc)Process Group Functions.
|
* setsockopt: (libc)Socket Option Functions.
|
* setstate: (libc)BSD Random.
|
* setstate_r: (libc)BSD Random.
|
* settimeofday: (libc)Setting and Adjusting the Time.
|
* setuid: (libc)Setting User ID.
|
* setutent: (libc)Manipulating the Database.
|
* setutxent: (libc)XPG Functions.
|
* setvbuf: (libc)Controlling Buffering.
|
* shm_open: (libc)Memory-mapped I/O.
|
* shm_unlink: (libc)Memory-mapped I/O.
|
* shutdown: (libc)Closing a Socket.
|
* sigabbrev_np: (libc)Signal Messages.
|
* sigaction: (libc)Advanced Signal Handling.
|
* sigaddset: (libc)Signal Sets.
|
* sigaltstack: (libc)Signal Stack.
|
* sigblock: (libc)BSD Signal Handling.
|
* sigdelset: (libc)Signal Sets.
|
* sigdescr_np: (libc)Signal Messages.
|
* sigemptyset: (libc)Signal Sets.
|
* sigfillset: (libc)Signal Sets.
|
* siginterrupt: (libc)BSD Signal Handling.
|
* sigismember: (libc)Signal Sets.
|
* siglongjmp: (libc)Non-Local Exits and Signals.
|
* sigmask: (libc)BSD Signal Handling.
|
* signal: (libc)Basic Signal Handling.
|
* signbit: (libc)FP Bit Twiddling.
|
* significand: (libc)Normalization Functions.
|
* significandf: (libc)Normalization Functions.
|
* significandl: (libc)Normalization Functions.
|
* sigpause: (libc)BSD Signal Handling.
|
* sigpending: (libc)Checking for Pending Signals.
|
* sigprocmask: (libc)Process Signal Mask.
|
* sigsetjmp: (libc)Non-Local Exits and Signals.
|
* sigsetmask: (libc)BSD Signal Handling.
|
* sigstack: (libc)Signal Stack.
|
* sigsuspend: (libc)Sigsuspend.
|
* sin: (libc)Trig Functions.
|
* sincos: (libc)Trig Functions.
|
* sincosf: (libc)Trig Functions.
|
* sincosfN: (libc)Trig Functions.
|
* sincosfNx: (libc)Trig Functions.
|
* sincosl: (libc)Trig Functions.
|
* sinf: (libc)Trig Functions.
|
* sinfN: (libc)Trig Functions.
|
* sinfNx: (libc)Trig Functions.
|
* sinh: (libc)Hyperbolic Functions.
|
* sinhf: (libc)Hyperbolic Functions.
|
* sinhfN: (libc)Hyperbolic Functions.
|
* sinhfNx: (libc)Hyperbolic Functions.
|
* sinhl: (libc)Hyperbolic Functions.
|
* sinl: (libc)Trig Functions.
|
* sleep: (libc)Sleeping.
|
* snprintf: (libc)Formatted Output Functions.
|
* socket: (libc)Creating a Socket.
|
* socketpair: (libc)Socket Pairs.
|
* sprintf: (libc)Formatted Output Functions.
|
* sqrt: (libc)Exponents and Logarithms.
|
* sqrtf: (libc)Exponents and Logarithms.
|
* sqrtfN: (libc)Exponents and Logarithms.
|
* sqrtfNx: (libc)Exponents and Logarithms.
|
* sqrtl: (libc)Exponents and Logarithms.
|
* srand48: (libc)SVID Random.
|
* srand48_r: (libc)SVID Random.
|
* srand: (libc)ISO Random.
|
* srandom: (libc)BSD Random.
|
* srandom_r: (libc)BSD Random.
|
* sscanf: (libc)Formatted Input Functions.
|
* ssignal: (libc)Basic Signal Handling.
|
* stat64: (libc)Reading Attributes.
|
* stat: (libc)Reading Attributes.
|
* stime: (libc)Setting and Adjusting the Time.
|
* stpcpy: (libc)Copying Strings and Arrays.
|
* stpncpy: (libc)Truncating Strings.
|
* strcasecmp: (libc)String/Array Comparison.
|
* strcasestr: (libc)Search Functions.
|
* strcat: (libc)Concatenating Strings.
|
* strchr: (libc)Search Functions.
|
* strchrnul: (libc)Search Functions.
|
* strcmp: (libc)String/Array Comparison.
|
* strcoll: (libc)Collation Functions.
|
* strcpy: (libc)Copying Strings and Arrays.
|
* strcspn: (libc)Search Functions.
|
* strdup: (libc)Copying Strings and Arrays.
|
* strdupa: (libc)Copying Strings and Arrays.
|
* strerror: (libc)Error Messages.
|
* strerror_r: (libc)Error Messages.
|
* strerrordesc_np: (libc)Error Messages.
|
* strerrorname_np: (libc)Error Messages.
|
* strfmon: (libc)Formatting Numbers.
|
* strfromd: (libc)Printing of Floats.
|
* strfromf: (libc)Printing of Floats.
|
* strfromfN: (libc)Printing of Floats.
|
* strfromfNx: (libc)Printing of Floats.
|
* strfroml: (libc)Printing of Floats.
|
* strfry: (libc)Shuffling Bytes.
|
* strftime: (libc)Formatting Calendar Time.
|
* strlen: (libc)String Length.
|
* strncasecmp: (libc)String/Array Comparison.
|
* strncat: (libc)Truncating Strings.
|
* strncmp: (libc)String/Array Comparison.
|
* strncpy: (libc)Truncating Strings.
|
* strndup: (libc)Truncating Strings.
|
* strndupa: (libc)Truncating Strings.
|
* strnlen: (libc)String Length.
|
* strpbrk: (libc)Search Functions.
|
* strptime: (libc)Low-Level Time String Parsing.
|
* strrchr: (libc)Search Functions.
|
* strsep: (libc)Finding Tokens in a String.
|
* strsignal: (libc)Signal Messages.
|
* strspn: (libc)Search Functions.
|
* strstr: (libc)Search Functions.
|
* strtod: (libc)Parsing of Floats.
|
* strtof: (libc)Parsing of Floats.
|
* strtofN: (libc)Parsing of Floats.
|
* strtofNx: (libc)Parsing of Floats.
|
* strtoimax: (libc)Parsing of Integers.
|
* strtok: (libc)Finding Tokens in a String.
|
* strtok_r: (libc)Finding Tokens in a String.
|
* strtol: (libc)Parsing of Integers.
|
* strtold: (libc)Parsing of Floats.
|
* strtoll: (libc)Parsing of Integers.
|
* strtoq: (libc)Parsing of Integers.
|
* strtoul: (libc)Parsing of Integers.
|
* strtoull: (libc)Parsing of Integers.
|
* strtoumax: (libc)Parsing of Integers.
|
* strtouq: (libc)Parsing of Integers.
|
* strverscmp: (libc)String/Array Comparison.
|
* strxfrm: (libc)Collation Functions.
|
* stty: (libc)BSD Terminal Modes.
|
* swapcontext: (libc)System V contexts.
|
* swprintf: (libc)Formatted Output Functions.
|
* swscanf: (libc)Formatted Input Functions.
|
* symlink: (libc)Symbolic Links.
|
* sync: (libc)Synchronizing I/O.
|
* syscall: (libc)System Calls.
|
* sysconf: (libc)Sysconf Definition.
|
* syslog: (libc)syslog; vsyslog.
|
* system: (libc)Running a Command.
|
* sysv_signal: (libc)Basic Signal Handling.
|
* tan: (libc)Trig Functions.
|
* tanf: (libc)Trig Functions.
|
* tanfN: (libc)Trig Functions.
|
* tanfNx: (libc)Trig Functions.
|
* tanh: (libc)Hyperbolic Functions.
|
* tanhf: (libc)Hyperbolic Functions.
|
* tanhfN: (libc)Hyperbolic Functions.
|
* tanhfNx: (libc)Hyperbolic Functions.
|
* tanhl: (libc)Hyperbolic Functions.
|
* tanl: (libc)Trig Functions.
|
* tcdrain: (libc)Line Control.
|
* tcflow: (libc)Line Control.
|
* tcflush: (libc)Line Control.
|
* tcgetattr: (libc)Mode Functions.
|
* tcgetpgrp: (libc)Terminal Access Functions.
|
* tcgetsid: (libc)Terminal Access Functions.
|
* tcsendbreak: (libc)Line Control.
|
* tcsetattr: (libc)Mode Functions.
|
* tcsetpgrp: (libc)Terminal Access Functions.
|
* tdelete: (libc)Tree Search Function.
|
* tdestroy: (libc)Tree Search Function.
|
* telldir: (libc)Random Access Directory.
|
* tempnam: (libc)Temporary Files.
|
* textdomain: (libc)Locating gettext catalog.
|
* tfind: (libc)Tree Search Function.
|
* tgamma: (libc)Special Functions.
|
* tgammaf: (libc)Special Functions.
|
* tgammafN: (libc)Special Functions.
|
* tgammafNx: (libc)Special Functions.
|
* tgammal: (libc)Special Functions.
|
* tgkill: (libc)Signaling Another Process.
|
* thrd_create: (libc)ISO C Thread Management.
|
* thrd_current: (libc)ISO C Thread Management.
|
* thrd_detach: (libc)ISO C Thread Management.
|
* thrd_equal: (libc)ISO C Thread Management.
|
* thrd_exit: (libc)ISO C Thread Management.
|
* thrd_join: (libc)ISO C Thread Management.
|
* thrd_sleep: (libc)ISO C Thread Management.
|
* thrd_yield: (libc)ISO C Thread Management.
|
* time: (libc)Getting the Time.
|
* timegm: (libc)Broken-down Time.
|
* timelocal: (libc)Broken-down Time.
|
* times: (libc)Processor Time.
|
* tmpfile64: (libc)Temporary Files.
|
* tmpfile: (libc)Temporary Files.
|
* tmpnam: (libc)Temporary Files.
|
* tmpnam_r: (libc)Temporary Files.
|
* toascii: (libc)Case Conversion.
|
* tolower: (libc)Case Conversion.
|
* totalorder: (libc)FP Comparison Functions.
|
* totalorderf: (libc)FP Comparison Functions.
|
* totalorderfN: (libc)FP Comparison Functions.
|
* totalorderfNx: (libc)FP Comparison Functions.
|
* totalorderl: (libc)FP Comparison Functions.
|
* totalordermag: (libc)FP Comparison Functions.
|
* totalordermagf: (libc)FP Comparison Functions.
|
* totalordermagfN: (libc)FP Comparison Functions.
|
* totalordermagfNx: (libc)FP Comparison Functions.
|
* totalordermagl: (libc)FP Comparison Functions.
|
* toupper: (libc)Case Conversion.
|
* towctrans: (libc)Wide Character Case Conversion.
|
* towlower: (libc)Wide Character Case Conversion.
|
* towupper: (libc)Wide Character Case Conversion.
|
* trunc: (libc)Rounding Functions.
|
* truncate64: (libc)File Size.
|
* truncate: (libc)File Size.
|
* truncf: (libc)Rounding Functions.
|
* truncfN: (libc)Rounding Functions.
|
* truncfNx: (libc)Rounding Functions.
|
* truncl: (libc)Rounding Functions.
|
* tsearch: (libc)Tree Search Function.
|
* tss_create: (libc)ISO C Thread-local Storage.
|
* tss_delete: (libc)ISO C Thread-local Storage.
|
* tss_get: (libc)ISO C Thread-local Storage.
|
* tss_set: (libc)ISO C Thread-local Storage.
|
* ttyname: (libc)Is It a Terminal.
|
* ttyname_r: (libc)Is It a Terminal.
|
* twalk: (libc)Tree Search Function.
|
* twalk_r: (libc)Tree Search Function.
|
* tzset: (libc)Time Zone Functions.
|
* ufromfp: (libc)Rounding Functions.
|
* ufromfpf: (libc)Rounding Functions.
|
* ufromfpfN: (libc)Rounding Functions.
|
* ufromfpfNx: (libc)Rounding Functions.
|
* ufromfpl: (libc)Rounding Functions.
|
* ufromfpx: (libc)Rounding Functions.
|
* ufromfpxf: (libc)Rounding Functions.
|
* ufromfpxfN: (libc)Rounding Functions.
|
* ufromfpxfNx: (libc)Rounding Functions.
|
* ufromfpxl: (libc)Rounding Functions.
|
* ulimit: (libc)Limits on Resources.
|
* umask: (libc)Setting Permissions.
|
* umount2: (libc)Mount-Unmount-Remount.
|
* umount: (libc)Mount-Unmount-Remount.
|
* uname: (libc)Platform Type.
|
* ungetc: (libc)How Unread.
|
* ungetwc: (libc)How Unread.
|
* unlink: (libc)Deleting Files.
|
* unlockpt: (libc)Allocation.
|
* unsetenv: (libc)Environment Access.
|
* updwtmp: (libc)Manipulating the Database.
|
* utime: (libc)File Times.
|
* utimes: (libc)File Times.
|
* utmpname: (libc)Manipulating the Database.
|
* utmpxname: (libc)XPG Functions.
|
* va_arg: (libc)Argument Macros.
|
* va_copy: (libc)Argument Macros.
|
* va_end: (libc)Argument Macros.
|
* va_start: (libc)Argument Macros.
|
* valloc: (libc)Aligned Memory Blocks.
|
* vasprintf: (libc)Variable Arguments Output.
|
* verr: (libc)Error Messages.
|
* verrx: (libc)Error Messages.
|
* versionsort64: (libc)Scanning Directory Content.
|
* versionsort: (libc)Scanning Directory Content.
|
* vfork: (libc)Creating a Process.
|
* vfprintf: (libc)Variable Arguments Output.
|
* vfscanf: (libc)Variable Arguments Input.
|
* vfwprintf: (libc)Variable Arguments Output.
|
* vfwscanf: (libc)Variable Arguments Input.
|
* vlimit: (libc)Limits on Resources.
|
* vprintf: (libc)Variable Arguments Output.
|
* vscanf: (libc)Variable Arguments Input.
|
* vsnprintf: (libc)Variable Arguments Output.
|
* vsprintf: (libc)Variable Arguments Output.
|
* vsscanf: (libc)Variable Arguments Input.
|
* vswprintf: (libc)Variable Arguments Output.
|
* vswscanf: (libc)Variable Arguments Input.
|
* vsyslog: (libc)syslog; vsyslog.
|
* vwarn: (libc)Error Messages.
|
* vwarnx: (libc)Error Messages.
|
* vwprintf: (libc)Variable Arguments Output.
|
* vwscanf: (libc)Variable Arguments Input.
|
* wait3: (libc)BSD Wait Functions.
|
* wait4: (libc)Process Completion.
|
* wait: (libc)Process Completion.
|
* waitpid: (libc)Process Completion.
|
* warn: (libc)Error Messages.
|
* warnx: (libc)Error Messages.
|
* wcpcpy: (libc)Copying Strings and Arrays.
|
* wcpncpy: (libc)Truncating Strings.
|
* wcrtomb: (libc)Converting a Character.
|
* wcscasecmp: (libc)String/Array Comparison.
|
* wcscat: (libc)Concatenating Strings.
|
* wcschr: (libc)Search Functions.
|
* wcschrnul: (libc)Search Functions.
|
* wcscmp: (libc)String/Array Comparison.
|
* wcscoll: (libc)Collation Functions.
|
* wcscpy: (libc)Copying Strings and Arrays.
|
* wcscspn: (libc)Search Functions.
|
* wcsdup: (libc)Copying Strings and Arrays.
|
* wcsftime: (libc)Formatting Calendar Time.
|
* wcslen: (libc)String Length.
|
* wcsncasecmp: (libc)String/Array Comparison.
|
* wcsncat: (libc)Truncating Strings.
|
* wcsncmp: (libc)String/Array Comparison.
|
* wcsncpy: (libc)Truncating Strings.
|
* wcsnlen: (libc)String Length.
|
* wcsnrtombs: (libc)Converting Strings.
|
* wcspbrk: (libc)Search Functions.
|
* wcsrchr: (libc)Search Functions.
|
* wcsrtombs: (libc)Converting Strings.
|
* wcsspn: (libc)Search Functions.
|
* wcsstr: (libc)Search Functions.
|
* wcstod: (libc)Parsing of Floats.
|
* wcstof: (libc)Parsing of Floats.
|
* wcstofN: (libc)Parsing of Floats.
|
* wcstofNx: (libc)Parsing of Floats.
|
* wcstoimax: (libc)Parsing of Integers.
|
* wcstok: (libc)Finding Tokens in a String.
|
* wcstol: (libc)Parsing of Integers.
|
* wcstold: (libc)Parsing of Floats.
|
* wcstoll: (libc)Parsing of Integers.
|
* wcstombs: (libc)Non-reentrant String Conversion.
|
* wcstoq: (libc)Parsing of Integers.
|
* wcstoul: (libc)Parsing of Integers.
|
* wcstoull: (libc)Parsing of Integers.
|
* wcstoumax: (libc)Parsing of Integers.
|
* wcstouq: (libc)Parsing of Integers.
|
* wcswcs: (libc)Search Functions.
|
* wcsxfrm: (libc)Collation Functions.
|
* wctob: (libc)Converting a Character.
|
* wctomb: (libc)Non-reentrant Character Conversion.
|
* wctrans: (libc)Wide Character Case Conversion.
|
* wctype: (libc)Classification of Wide Characters.
|
* wmemchr: (libc)Search Functions.
|
* wmemcmp: (libc)String/Array Comparison.
|
* wmemcpy: (libc)Copying Strings and Arrays.
|
* wmemmove: (libc)Copying Strings and Arrays.
|
* wmempcpy: (libc)Copying Strings and Arrays.
|
* wmemset: (libc)Copying Strings and Arrays.
|
* wordexp: (libc)Calling Wordexp.
|
* wordfree: (libc)Calling Wordexp.
|
* wprintf: (libc)Formatted Output Functions.
|
* write: (libc)I/O Primitives.
|
* writev: (libc)Scatter-Gather.
|
* wscanf: (libc)Formatted Input Functions.
|
* y0: (libc)Special Functions.
|
* y0f: (libc)Special Functions.
|
* y0fN: (libc)Special Functions.
|
* y0fNx: (libc)Special Functions.
|
* y0l: (libc)Special Functions.
|
* y1: (libc)Special Functions.
|
* y1f: (libc)Special Functions.
|
* y1fN: (libc)Special Functions.
|
* y1fNx: (libc)Special Functions.
|
* y1l: (libc)Special Functions.
|
* yn: (libc)Special Functions.
|
* ynf: (libc)Special Functions.
|
* ynfN: (libc)Special Functions.
|
* ynfNx: (libc)Special Functions.
|
* ynl: (libc)Special Functions.
|
END-INFO-DIR-ENTRY
|
|
|
File: libc.info, Node: File Attributes, Next: Making Special Files, Prev: Creating Directories, Up: File System Interface
|
|
14.9 File Attributes
|
====================
|
|
When you issue an ‘ls -l’ shell command on a file, it gives you
|
information about the size of the file, who owns it, when it was last
|
modified, etc. These are called the "file attributes", and are
|
associated with the file itself and not a particular one of its names.
|
|
This section contains information about how you can inquire about and
|
modify the attributes of a file.
|
|
* Menu:
|
|
* Attribute Meanings:: The names of the file attributes,
|
and what their values mean.
|
* Reading Attributes:: How to read the attributes of a file.
|
* Testing File Type:: Distinguishing ordinary files,
|
directories, links…
|
* File Owner:: How ownership for new files is determined,
|
and how to change it.
|
* Permission Bits:: How information about a file’s access
|
mode is stored.
|
* Access Permission:: How the system decides who can access a file.
|
* Setting Permissions:: How permissions for new files are assigned,
|
and how to change them.
|
* Testing File Access:: How to find out if your process can
|
access a file.
|
* File Times:: About the time attributes of a file.
|
* File Size:: Manually changing the size of a file.
|
* Storage Allocation:: Allocate backing storage for files.
|
|
|
File: libc.info, Node: Attribute Meanings, Next: Reading Attributes, Up: File Attributes
|
|
14.9.1 The meaning of the File Attributes
|
-----------------------------------------
|
|
When you read the attributes of a file, they come back in a structure
|
called ‘struct stat’. This section describes the names of the
|
attributes, their data types, and what they mean. For the functions to
|
read the attributes of a file, see *note Reading Attributes::.
|
|
The header file ‘sys/stat.h’ declares all the symbols defined in this
|
section.
|
|
-- Data Type: struct stat
|
|
The ‘stat’ structure type is used to return information about the
|
attributes of a file. It contains at least the following members:
|
|
‘mode_t st_mode’
|
Specifies the mode of the file. This includes file type
|
information (*note Testing File Type::) and the file
|
permission bits (*note Permission Bits::).
|
|
‘ino_t st_ino’
|
The file serial number, which distinguishes this file from all
|
other files on the same device.
|
|
‘dev_t st_dev’
|
Identifies the device containing the file. The ‘st_ino’ and
|
‘st_dev’, taken together, uniquely identify the file. The
|
‘st_dev’ value is not necessarily consistent across reboots or
|
system crashes, however.
|
|
‘nlink_t st_nlink’
|
The number of hard links to the file. This count keeps track
|
of how many directories have entries for this file. If the
|
count is ever decremented to zero, then the file itself is
|
discarded as soon as no process still holds it open. Symbolic
|
links are not counted in the total.
|
|
‘uid_t st_uid’
|
The user ID of the file’s owner. *Note File Owner::.
|
|
‘gid_t st_gid’
|
The group ID of the file. *Note File Owner::.
|
|
‘off_t st_size’
|
This specifies the size of a regular file in bytes. For files
|
that are really devices this field isn’t usually meaningful.
|
For symbolic links this specifies the length of the file name
|
the link refers to.
|
|
‘time_t st_atime’
|
This is the last access time for the file. *Note File
|
Times::.
|
|
‘unsigned long int st_atime_usec’
|
This is the fractional part of the last access time for the
|
file. *Note File Times::.
|
|
‘time_t st_mtime’
|
This is the time of the last modification to the contents of
|
the file. *Note File Times::.
|
|
‘unsigned long int st_mtime_usec’
|
This is the fractional part of the time of the last
|
modification to the contents of the file. *Note File Times::.
|
|
‘time_t st_ctime’
|
This is the time of the last modification to the attributes of
|
the file. *Note File Times::.
|
|
‘unsigned long int st_ctime_usec’
|
This is the fractional part of the time of the last
|
modification to the attributes of the file. *Note File
|
Times::.
|
|
‘blkcnt_t st_blocks’
|
This is the amount of disk space that the file occupies,
|
measured in units of 512-byte blocks.
|
|
The number of disk blocks is not strictly proportional to the
|
size of the file, for two reasons: the file system may use
|
some blocks for internal record keeping; and the file may be
|
sparse—it may have “holes” which contain zeros but do not
|
actually take up space on the disk.
|
|
You can tell (approximately) whether a file is sparse by
|
comparing this value with ‘st_size’, like this:
|
|
(st.st_blocks * 512 < st.st_size)
|
|
This test is not perfect because a file that is just slightly
|
sparse might not be detected as sparse at all. For practical
|
applications, this is not a problem.
|
|
‘unsigned int st_blksize’
|
The optimal block size for reading or writing this file, in
|
bytes. You might use this size for allocating the buffer
|
space for reading or writing the file. (This is unrelated to
|
‘st_blocks’.)
|
|
The extensions for the Large File Support (LFS) require, even on
|
32-bit machines, types which can handle file sizes up to 2^63.
|
Therefore a new definition of ‘struct stat’ is necessary.
|
|
-- Data Type: struct stat64
|
|
The members of this type are the same and have the same names as
|
those in ‘struct stat’. The only difference is that the members
|
‘st_ino’, ‘st_size’, and ‘st_blocks’ have a different type to
|
support larger values.
|
|
‘mode_t st_mode’
|
Specifies the mode of the file. This includes file type
|
information (*note Testing File Type::) and the file
|
permission bits (*note Permission Bits::).
|
|
‘ino64_t st_ino’
|
The file serial number, which distinguishes this file from all
|
other files on the same device.
|
|
‘dev_t st_dev’
|
Identifies the device containing the file. The ‘st_ino’ and
|
‘st_dev’, taken together, uniquely identify the file. The
|
‘st_dev’ value is not necessarily consistent across reboots or
|
system crashes, however.
|
|
‘nlink_t st_nlink’
|
The number of hard links to the file. This count keeps track
|
of how many directories have entries for this file. If the
|
count is ever decremented to zero, then the file itself is
|
discarded as soon as no process still holds it open. Symbolic
|
links are not counted in the total.
|
|
‘uid_t st_uid’
|
The user ID of the file’s owner. *Note File Owner::.
|
|
‘gid_t st_gid’
|
The group ID of the file. *Note File Owner::.
|
|
‘off64_t st_size’
|
This specifies the size of a regular file in bytes. For files
|
that are really devices this field isn’t usually meaningful.
|
For symbolic links this specifies the length of the file name
|
the link refers to.
|
|
‘time_t st_atime’
|
This is the last access time for the file. *Note File
|
Times::.
|
|
‘unsigned long int st_atime_usec’
|
This is the fractional part of the last access time for the
|
file. *Note File Times::.
|
|
‘time_t st_mtime’
|
This is the time of the last modification to the contents of
|
the file. *Note File Times::.
|
|
‘unsigned long int st_mtime_usec’
|
This is the fractional part of the time of the last
|
modification to the contents of the file. *Note File Times::.
|
|
‘time_t st_ctime’
|
This is the time of the last modification to the attributes of
|
the file. *Note File Times::.
|
|
‘unsigned long int st_ctime_usec’
|
This is the fractional part of the time of the last
|
modification to the attributes of the file. *Note File
|
Times::.
|
|
‘blkcnt64_t st_blocks’
|
This is the amount of disk space that the file occupies,
|
measured in units of 512-byte blocks.
|
|
‘unsigned int st_blksize’
|
The optimal block size for reading of writing this file, in
|
bytes. You might use this size for allocating the buffer
|
space for reading of writing the file. (This is unrelated to
|
‘st_blocks’.)
|
|
Some of the file attributes have special data type names which exist
|
specifically for those attributes. (They are all aliases for well-known
|
integer types that you know and love.) These typedef names are defined
|
in the header file ‘sys/types.h’ as well as in ‘sys/stat.h’. Here is a
|
list of them.
|
|
-- Data Type: mode_t
|
|
This is an integer data type used to represent file modes. In the
|
GNU C Library, this is an unsigned type no narrower than ‘unsigned
|
int’.
|
|
-- Data Type: ino_t
|
|
This is an unsigned integer type used to represent file serial
|
numbers. (In Unix jargon, these are sometimes called "inode
|
numbers".) In the GNU C Library, this type is no narrower than
|
‘unsigned int’.
|
|
If the source is compiled with ‘_FILE_OFFSET_BITS == 64’ this type
|
is transparently replaced by ‘ino64_t’.
|
|
-- Data Type: ino64_t
|
|
This is an unsigned integer type used to represent file serial
|
numbers for the use in LFS. In the GNU C Library, this type is no
|
narrower than ‘unsigned int’.
|
|
When compiling with ‘_FILE_OFFSET_BITS == 64’ this type is
|
available under the name ‘ino_t’.
|
|
-- Data Type: dev_t
|
|
This is an arithmetic data type used to represent file device
|
numbers. In the GNU C Library, this is an integer type no narrower
|
than ‘int’.
|
|
-- Data Type: nlink_t
|
|
This is an integer type used to represent file link counts.
|
|
-- Data Type: blkcnt_t
|
|
This is a signed integer type used to represent block counts. In
|
the GNU C Library, this type is no narrower than ‘int’.
|
|
If the source is compiled with ‘_FILE_OFFSET_BITS == 64’ this type
|
is transparently replaced by ‘blkcnt64_t’.
|
|
-- Data Type: blkcnt64_t
|
|
This is a signed integer type used to represent block counts for
|
the use in LFS. In the GNU C Library, this type is no narrower than
|
‘int’.
|
|
When compiling with ‘_FILE_OFFSET_BITS == 64’ this type is
|
available under the name ‘blkcnt_t’.
|
|
|
File: libc.info, Node: Reading Attributes, Next: Testing File Type, Prev: Attribute Meanings, Up: File Attributes
|
|
14.9.2 Reading the Attributes of a File
|
---------------------------------------
|
|
To examine the attributes of files, use the functions ‘stat’, ‘fstat’
|
and ‘lstat’. They return the attribute information in a ‘struct stat’
|
object. All three functions are declared in the header file
|
‘sys/stat.h’.
|
|
-- Function: int stat (const char *FILENAME, struct stat *BUF)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘stat’ function returns information about the attributes of the
|
file named by FILENAME in the structure pointed to by BUF.
|
|
If FILENAME is the name of a symbolic link, the attributes you get
|
describe the file that the link points to. If the link points to a
|
nonexistent file name, then ‘stat’ fails reporting a nonexistent
|
file.
|
|
The return value is ‘0’ if the operation is successful, or ‘-1’ on
|
failure. In addition to the usual file name errors (*note File
|
Name Errors::, the following ‘errno’ error conditions are defined
|
for this function:
|
|
‘ENOENT’
|
The file named by FILENAME doesn’t exist.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is in fact ‘stat64’ since the LFS interface transparently
|
replaces the normal implementation.
|
|
-- Function: int stat64 (const char *FILENAME, struct stat64 *BUF)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to ‘stat’ but it is also able to work on
|
files larger than 2^31 bytes on 32-bit systems. To be able to do
|
this the result is stored in a variable of type ‘struct stat64’ to
|
which BUF must point.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is available under the name ‘stat’ and so transparently
|
replaces the interface for small files on 32-bit machines.
|
|
-- Function: int fstat (int FILEDES, struct stat *BUF)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘fstat’ function is like ‘stat’, except that it takes an open
|
file descriptor as an argument instead of a file name. *Note
|
Low-Level I/O::.
|
|
Like ‘stat’, ‘fstat’ returns ‘0’ on success and ‘-1’ on failure.
|
The following ‘errno’ error conditions are defined for ‘fstat’:
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is in fact ‘fstat64’ since the LFS interface transparently
|
replaces the normal implementation.
|
|
-- Function: int fstat64 (int FILEDES, struct stat64 *BUF)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to ‘fstat’ but is able to work on large
|
files on 32-bit platforms. For large files the file descriptor
|
FILEDES should be obtained by ‘open64’ or ‘creat64’. The BUF
|
pointer points to a variable of type ‘struct stat64’ which is able
|
to represent the larger values.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is available under the name ‘fstat’ and so transparently
|
replaces the interface for small files on 32-bit machines.
|
|
-- Function: int lstat (const char *FILENAME, struct stat *BUF)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘lstat’ function is like ‘stat’, except that it does not follow
|
symbolic links. If FILENAME is the name of a symbolic link,
|
‘lstat’ returns information about the link itself; otherwise
|
‘lstat’ works like ‘stat’. *Note Symbolic Links::.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is in fact ‘lstat64’ since the LFS interface transparently
|
replaces the normal implementation.
|
|
-- Function: int lstat64 (const char *FILENAME, struct stat64 *BUF)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to ‘lstat’ but it is also able to work on
|
files larger than 2^31 bytes on 32-bit systems. To be able to do
|
this the result is stored in a variable of type ‘struct stat64’ to
|
which BUF must point.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
|
function is available under the name ‘lstat’ and so transparently
|
replaces the interface for small files on 32-bit machines.
|
|
|
File: libc.info, Node: Testing File Type, Next: File Owner, Prev: Reading Attributes, Up: File Attributes
|
|
14.9.3 Testing the Type of a File
|
---------------------------------
|
|
The "file mode", stored in the ‘st_mode’ field of the file attributes,
|
contains two kinds of information: the file type code, and the access
|
permission bits. This section discusses only the type code, which you
|
can use to tell whether the file is a directory, socket, symbolic link,
|
and so on. For details about access permissions see *note Permission
|
Bits::.
|
|
There are two ways you can access the file type information in a file
|
mode. Firstly, for each file type there is a "predicate macro" which
|
examines a given file mode and returns whether it is of that type or
|
not. Secondly, you can mask out the rest of the file mode to leave just
|
the file type code, and compare this against constants for each of the
|
supported file types.
|
|
All of the symbols listed in this section are defined in the header
|
file ‘sys/stat.h’.
|
|
The following predicate macros test the type of a file, given the
|
value M which is the ‘st_mode’ field returned by ‘stat’ on that file:
|
|
-- Macro: int S_ISDIR (mode_t M)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns non-zero if the file is a directory.
|
|
-- Macro: int S_ISCHR (mode_t M)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns non-zero if the file is a character special file
|
(a device like a terminal).
|
|
-- Macro: int S_ISBLK (mode_t M)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns non-zero if the file is a block special file (a
|
device like a disk).
|
|
-- Macro: int S_ISREG (mode_t M)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns non-zero if the file is a regular file.
|
|
-- Macro: int S_ISFIFO (mode_t M)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns non-zero if the file is a FIFO special file, or
|
a pipe. *Note Pipes and FIFOs::.
|
|
-- Macro: int S_ISLNK (mode_t M)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns non-zero if the file is a symbolic link. *Note
|
Symbolic Links::.
|
|
-- Macro: int S_ISSOCK (mode_t M)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro returns non-zero if the file is a socket. *Note
|
Sockets::.
|
|
An alternate non-POSIX method of testing the file type is supported
|
for compatibility with BSD. The mode can be bitwise AND-ed with ‘S_IFMT’
|
to extract the file type code, and compared to the appropriate constant.
|
For example,
|
|
S_ISCHR (MODE)
|
|
is equivalent to:
|
|
((MODE & S_IFMT) == S_IFCHR)
|
|
-- Macro: int S_IFMT
|
|
This is a bit mask used to extract the file type code from a mode
|
value.
|
|
These are the symbolic names for the different file type codes:
|
|
‘S_IFDIR’
|
|
This is the file type constant of a directory file.
|
|
‘S_IFCHR’
|
|
This is the file type constant of a character-oriented device file.
|
|
‘S_IFBLK’
|
|
This is the file type constant of a block-oriented device file.
|
|
‘S_IFREG’
|
|
This is the file type constant of a regular file.
|
|
‘S_IFLNK’
|
|
This is the file type constant of a symbolic link.
|
|
‘S_IFSOCK’
|
|
This is the file type constant of a socket.
|
|
‘S_IFIFO’
|
|
This is the file type constant of a FIFO or pipe.
|
|
The POSIX.1b standard introduced a few more objects which possibly
|
can be implemented as objects in the filesystem. These are message
|
queues, semaphores, and shared memory objects. To allow differentiating
|
these objects from other files the POSIX standard introduced three new
|
test macros. But unlike the other macros they do not take the value of
|
the ‘st_mode’ field as the parameter. Instead they expect a pointer to
|
the whole ‘struct stat’ structure.
|
|
-- Macro: int S_TYPEISMQ (struct stat *S)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
If the system implements POSIX message queues as distinct objects
|
and the file is a message queue object, this macro returns a
|
non-zero value. In all other cases the result is zero.
|
|
-- Macro: int S_TYPEISSEM (struct stat *S)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
If the system implements POSIX semaphores as distinct objects and
|
the file is a semaphore object, this macro returns a non-zero
|
value. In all other cases the result is zero.
|
|
-- Macro: int S_TYPEISSHM (struct stat *S)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
If the system implements POSIX shared memory objects as distinct
|
objects and the file is a shared memory object, this macro returns
|
a non-zero value. In all other cases the result is zero.
|
|
|
File: libc.info, Node: File Owner, Next: Permission Bits, Prev: Testing File Type, Up: File Attributes
|
|
14.9.4 File Owner
|
-----------------
|
|
Every file has an "owner" which is one of the registered user names
|
defined on the system. Each file also has a "group" which is one of the
|
defined groups. The file owner can often be useful for showing you who
|
edited the file (especially when you edit with GNU Emacs), but its main
|
purpose is for access control.
|
|
The file owner and group play a role in determining access because
|
the file has one set of access permission bits for the owner, another
|
set that applies to users who belong to the file’s group, and a third
|
set of bits that applies to everyone else. *Note Access Permission::,
|
for the details of how access is decided based on this data.
|
|
When a file is created, its owner is set to the effective user ID of
|
the process that creates it (*note Process Persona::). The file’s group
|
ID may be set to either the effective group ID of the process, or the
|
group ID of the directory that contains the file, depending on the
|
system where the file is stored. When you access a remote file system,
|
it behaves according to its own rules, not according to the system your
|
program is running on. Thus, your program must be prepared to encounter
|
either kind of behavior no matter what kind of system you run it on.
|
|
You can change the owner and/or group owner of an existing file using
|
the ‘chown’ function. This is the primitive for the ‘chown’ and ‘chgrp’
|
shell commands.
|
|
The prototype for this function is declared in ‘unistd.h’.
|
|
-- Function: int chown (const char *FILENAME, uid_t OWNER, gid_t GROUP)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘chown’ function changes the owner of the file FILENAME to
|
OWNER, and its group owner to GROUP.
|
|
Changing the owner of the file on certain systems clears the
|
set-user-ID and set-group-ID permission bits. (This is because
|
those bits may not be appropriate for the new owner.) Other file
|
permission bits are not changed.
|
|
The return value is ‘0’ on success and ‘-1’ on failure. In
|
addition to the usual file name errors (*note File Name Errors::),
|
the following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EPERM’
|
This process lacks permission to make the requested change.
|
|
Only privileged users or the file’s owner can change the
|
file’s group. On most file systems, only privileged users can
|
change the file owner; some file systems allow you to change
|
the owner if you are currently the owner. When you access a
|
remote file system, the behavior you encounter is determined
|
by the system that actually holds the file, not by the system
|
your program is running on.
|
|
*Note Options for Files::, for information about the
|
‘_POSIX_CHOWN_RESTRICTED’ macro.
|
|
‘EROFS’
|
The file is on a read-only file system.
|
|
-- Function: int fchown (int FILEDES, uid_t OWNER, gid_t GROUP)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This is like ‘chown’, except that it changes the owner of the open
|
file with descriptor FILEDES.
|
|
The return value from ‘fchown’ is ‘0’ on success and ‘-1’ on
|
failure. The following ‘errno’ error codes are defined for this
|
function:
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor.
|
|
‘EINVAL’
|
The FILEDES argument corresponds to a pipe or socket, not an
|
ordinary file.
|
|
‘EPERM’
|
This process lacks permission to make the requested change.
|
For details see ‘chmod’ above.
|
|
‘EROFS’
|
The file resides on a read-only file system.
|
|
|
File: libc.info, Node: Permission Bits, Next: Access Permission, Prev: File Owner, Up: File Attributes
|
|
14.9.5 The Mode Bits for Access Permission
|
------------------------------------------
|
|
The "file mode", stored in the ‘st_mode’ field of the file attributes,
|
contains two kinds of information: the file type code, and the access
|
permission bits. This section discusses only the access permission
|
bits, which control who can read or write the file. *Note Testing File
|
Type::, for information about the file type code.
|
|
All of the symbols listed in this section are defined in the header
|
file ‘sys/stat.h’.
|
|
These symbolic constants are defined for the file mode bits that
|
control access permission for the file:
|
|
‘S_IRUSR’
|
‘S_IREAD’
|
|
Read permission bit for the owner of the file. On many systems
|
this bit is 0400. ‘S_IREAD’ is an obsolete synonym provided for
|
BSD compatibility.
|
|
‘S_IWUSR’
|
‘S_IWRITE’
|
|
Write permission bit for the owner of the file. Usually 0200. ‘S_IWRITE’
|
is an obsolete synonym provided for BSD compatibility.
|
|
‘S_IXUSR’
|
‘S_IEXEC’
|
|
Execute (for ordinary files) or search (for directories) permission
|
bit for the owner of the file. Usually 0100. ‘S_IEXEC’ is an
|
obsolete synonym provided for BSD compatibility.
|
|
‘S_IRWXU’
|
|
This is equivalent to ‘(S_IRUSR | S_IWUSR | S_IXUSR)’.
|
|
‘S_IRGRP’
|
|
Read permission bit for the group owner of the file. Usually 040.
|
|
‘S_IWGRP’
|
|
Write permission bit for the group owner of the file. Usually 020.
|
|
‘S_IXGRP’
|
|
Execute or search permission bit for the group owner of the file.
|
Usually 010.
|
|
‘S_IRWXG’
|
|
This is equivalent to ‘(S_IRGRP | S_IWGRP | S_IXGRP)’.
|
|
‘S_IROTH’
|
|
Read permission bit for other users. Usually 04.
|
|
‘S_IWOTH’
|
|
Write permission bit for other users. Usually 02.
|
|
‘S_IXOTH’
|
|
Execute or search permission bit for other users. Usually 01.
|
|
‘S_IRWXO’
|
|
This is equivalent to ‘(S_IROTH | S_IWOTH | S_IXOTH)’.
|
|
‘S_ISUID’
|
|
This is the set-user-ID on execute bit, usually 04000. *Note How
|
Change Persona::.
|
|
‘S_ISGID’
|
|
This is the set-group-ID on execute bit, usually 02000. *Note How
|
Change Persona::.
|
|
‘S_ISVTX’
|
|
This is the "sticky" bit, usually 01000.
|
|
For a directory it gives permission to delete a file in that
|
directory only if you own that file. Ordinarily, a user can either
|
delete all the files in a directory or cannot delete any of them
|
(based on whether the user has write permission for the directory).
|
The same restriction applies—you must have both write permission
|
for the directory and own the file you want to delete. The one
|
exception is that the owner of the directory can delete any file in
|
the directory, no matter who owns it (provided the owner has given
|
himself write permission for the directory). This is commonly used
|
for the ‘/tmp’ directory, where anyone may create files but not
|
delete files created by other users.
|
|
Originally the sticky bit on an executable file modified the
|
swapping policies of the system. Normally, when a program
|
terminated, its pages in core were immediately freed and reused.
|
If the sticky bit was set on the executable file, the system kept
|
the pages in core for a while as if the program were still running.
|
This was advantageous for a program likely to be run many times in
|
succession. This usage is obsolete in modern systems. When a
|
program terminates, its pages always remain in core as long as
|
there is no shortage of memory in the system. When the program is
|
next run, its pages will still be in core if no shortage arose
|
since the last run.
|
|
On some modern systems where the sticky bit has no useful meaning
|
for an executable file, you cannot set the bit at all for a
|
non-directory. If you try, ‘chmod’ fails with ‘EFTYPE’; *note
|
Setting Permissions::.
|
|
Some systems (particularly SunOS) have yet another use for the
|
sticky bit. If the sticky bit is set on a file that is _not_
|
executable, it means the opposite: never cache the pages of this
|
file at all. The main use of this is for the files on an NFS
|
server machine which are used as the swap area of diskless client
|
machines. The idea is that the pages of the file will be cached in
|
the client’s memory, so it is a waste of the server’s memory to
|
cache them a second time. With this usage the sticky bit also
|
implies that the filesystem may fail to record the file’s
|
modification time onto disk reliably (the idea being that no-one
|
cares for a swap file).
|
|
This bit is only available on BSD systems (and those derived from
|
them). Therefore one has to use the ‘_GNU_SOURCE’ feature select
|
macro, or not define any feature test macros, to get the definition
|
(*note Feature Test Macros::).
|
|
The actual bit values of the symbols are listed in the table above so
|
you can decode file mode values when debugging your programs. These bit
|
values are correct for most systems, but they are not guaranteed.
|
|
*Warning:* Writing explicit numbers for file permissions is bad
|
practice. Not only is it not portable, it also requires everyone who
|
reads your program to remember what the bits mean. To make your program
|
clean use the symbolic names.
|
|
|
File: libc.info, Node: Access Permission, Next: Setting Permissions, Prev: Permission Bits, Up: File Attributes
|
|
14.9.6 How Your Access to a File is Decided
|
-------------------------------------------
|
|
Recall that the operating system normally decides access permission for
|
a file based on the effective user and group IDs of the process and its
|
supplementary group IDs, together with the file’s owner, group and
|
permission bits. These concepts are discussed in detail in *note
|
Process Persona::.
|
|
If the effective user ID of the process matches the owner user ID of
|
the file, then permissions for read, write, and execute/search are
|
controlled by the corresponding “user” (or “owner”) bits. Likewise, if
|
any of the effective group ID or supplementary group IDs of the process
|
matches the group owner ID of the file, then permissions are controlled
|
by the “group” bits. Otherwise, permissions are controlled by the
|
“other” bits.
|
|
Privileged users, like ‘root’, can access any file regardless of its
|
permission bits. As a special case, for a file to be executable even by
|
a privileged user, at least one of its execute bits must be set.
|
|
|
File: libc.info, Node: Setting Permissions, Next: Testing File Access, Prev: Access Permission, Up: File Attributes
|
|
14.9.7 Assigning File Permissions
|
---------------------------------
|
|
The primitive functions for creating files (for example, ‘open’ or
|
‘mkdir’) take a MODE argument, which specifies the file permissions to
|
give the newly created file. This mode is modified by the process’s
|
"file creation mask", or "umask", before it is used.
|
|
The bits that are set in the file creation mask identify permissions
|
that are always to be disabled for newly created files. For example, if
|
you set all the “other” access bits in the mask, then newly created
|
files are not accessible at all to processes in the “other” category,
|
even if the MODE argument passed to the create function would permit
|
such access. In other words, the file creation mask is the complement
|
of the ordinary access permissions you want to grant.
|
|
Programs that create files typically specify a MODE argument that
|
includes all the permissions that make sense for the particular file.
|
For an ordinary file, this is typically read and write permission for
|
all classes of users. These permissions are then restricted as
|
specified by the individual user’s own file creation mask.
|
|
To change the permission of an existing file given its name, call
|
‘chmod’. This function uses the specified permission bits and ignores
|
the file creation mask.
|
|
In normal use, the file creation mask is initialized by the user’s
|
login shell (using the ‘umask’ shell command), and inherited by all
|
subprocesses. Application programs normally don’t need to worry about
|
the file creation mask. It will automatically do what it is supposed to
|
do.
|
|
When your program needs to create a file and bypass the umask for its
|
access permissions, the easiest way to do this is to use ‘fchmod’ after
|
opening the file, rather than changing the umask. In fact, changing the
|
umask is usually done only by shells. They use the ‘umask’ function.
|
|
The functions in this section are declared in ‘sys/stat.h’.
|
|
-- Function: mode_t umask (mode_t MASK)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘umask’ function sets the file creation mask of the current
|
process to MASK, and returns the previous value of the file
|
creation mask.
|
|
Here is an example showing how to read the mask with ‘umask’
|
without changing it permanently:
|
|
mode_t
|
read_umask (void)
|
{
|
mode_t mask = umask (0);
|
umask (mask);
|
return mask;
|
}
|
|
However, on GNU/Hurd systems it is better to use ‘getumask’ if you
|
just want to read the mask value, because it is reentrant.
|
|
-- Function: mode_t getumask (void)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
Return the current value of the file creation mask for the current
|
process. This function is a GNU extension and is only available on
|
GNU/Hurd systems.
|
|
-- Function: int chmod (const char *FILENAME, mode_t MODE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘chmod’ function sets the access permission bits for the file
|
named by FILENAME to MODE.
|
|
If FILENAME is a symbolic link, ‘chmod’ changes the permissions of
|
the file pointed to by the link, not those of the link itself.
|
|
This function returns ‘0’ if successful and ‘-1’ if not. In
|
addition to the usual file name errors (*note File Name Errors::),
|
the following ‘errno’ error conditions are defined for this
|
function:
|
|
‘ENOENT’
|
The named file doesn’t exist.
|
|
‘EPERM’
|
This process does not have permission to change the access
|
permissions of this file. Only the file’s owner (as judged by
|
the effective user ID of the process) or a privileged user can
|
change them.
|
|
‘EROFS’
|
The file resides on a read-only file system.
|
|
‘EFTYPE’
|
MODE has the ‘S_ISVTX’ bit (the “sticky bit”) set, and the
|
named file is not a directory. Some systems do not allow
|
setting the sticky bit on non-directory files, and some do
|
(and only some of those assign a useful meaning to the bit for
|
non-directory files).
|
|
You only get ‘EFTYPE’ on systems where the sticky bit has no
|
useful meaning for non-directory files, so it is always safe
|
to just clear the bit in MODE and call ‘chmod’ again. *Note
|
Permission Bits::, for full details on the sticky bit.
|
|
-- Function: int fchmod (int FILEDES, mode_t MODE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This is like ‘chmod’, except that it changes the permissions of the
|
currently open file given by FILEDES.
|
|
The return value from ‘fchmod’ is ‘0’ on success and ‘-1’ on
|
failure. The following ‘errno’ error codes are defined for this
|
function:
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor.
|
|
‘EINVAL’
|
The FILEDES argument corresponds to a pipe or socket, or
|
something else that doesn’t really have access permissions.
|
|
‘EPERM’
|
This process does not have permission to change the access
|
permissions of this file. Only the file’s owner (as judged by
|
the effective user ID of the process) or a privileged user can
|
change them.
|
|
‘EROFS’
|
The file resides on a read-only file system.
|
|
|
File: libc.info, Node: Testing File Access, Next: File Times, Prev: Setting Permissions, Up: File Attributes
|
|
14.9.8 Testing Permission to Access a File
|
------------------------------------------
|
|
In some situations it is desirable to allow programs to access files or
|
devices even if this is not possible with the permissions granted to the
|
user. One possible solution is to set the setuid-bit of the program
|
file. If such a program is started the _effective_ user ID of the
|
process is changed to that of the owner of the program file. So to
|
allow write access to files like ‘/etc/passwd’, which normally can be
|
written only by the super-user, the modifying program will have to be
|
owned by ‘root’ and the setuid-bit must be set.
|
|
But besides the files the program is intended to change the user
|
should not be allowed to access any file to which s/he would not have
|
access anyway. The program therefore must explicitly check whether _the
|
user_ would have the necessary access to a file, before it reads or
|
writes the file.
|
|
To do this, use the function ‘access’, which checks for access
|
permission based on the process’s _real_ user ID rather than the
|
effective user ID. (The setuid feature does not alter the real user ID,
|
so it reflects the user who actually ran the program.)
|
|
There is another way you could check this access, which is easy to
|
describe, but very hard to use. This is to examine the file mode bits
|
and mimic the system’s own access computation. This method is
|
undesirable because many systems have additional access control
|
features; your program cannot portably mimic them, and you would not
|
want to try to keep track of the diverse features that different systems
|
have. Using ‘access’ is simple and automatically does whatever is
|
appropriate for the system you are using.
|
|
‘access’ is _only_ appropriate to use in setuid programs. A
|
non-setuid program will always use the effective ID rather than the real
|
ID.
|
|
The symbols in this section are declared in ‘unistd.h’.
|
|
-- Function: int access (const char *FILENAME, int HOW)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘access’ function checks to see whether the file named by
|
FILENAME can be accessed in the way specified by the HOW argument.
|
The HOW argument either can be the bitwise OR of the flags ‘R_OK’,
|
‘W_OK’, ‘X_OK’, or the existence test ‘F_OK’.
|
|
This function uses the _real_ user and group IDs of the calling
|
process, rather than the _effective_ IDs, to check for access
|
permission. As a result, if you use the function from a ‘setuid’
|
or ‘setgid’ program (*note How Change Persona::), it gives
|
information relative to the user who actually ran the program.
|
|
The return value is ‘0’ if the access is permitted, and ‘-1’
|
otherwise. (In other words, treated as a predicate function,
|
‘access’ returns true if the requested access is _denied_.)
|
|
In addition to the usual file name errors (*note File Name
|
Errors::), the following ‘errno’ error conditions are defined for
|
this function:
|
|
‘EACCES’
|
The access specified by HOW is denied.
|
|
‘ENOENT’
|
The file doesn’t exist.
|
|
‘EROFS’
|
Write permission was requested for a file on a read-only file
|
system.
|
|
These macros are defined in the header file ‘unistd.h’ for use as the
|
HOW argument to the ‘access’ function. The values are integer
|
constants.
|
|
-- Macro: int R_OK
|
|
Flag meaning test for read permission.
|
|
-- Macro: int W_OK
|
|
Flag meaning test for write permission.
|
|
-- Macro: int X_OK
|
|
Flag meaning test for execute/search permission.
|
|
-- Macro: int F_OK
|
|
Flag meaning test for existence of the file.
|
|
|
File: libc.info, Node: File Times, Next: File Size, Prev: Testing File Access, Up: File Attributes
|
|
14.9.9 File Times
|
-----------------
|
|
Each file has three time stamps associated with it: its access time, its
|
modification time, and its attribute modification time. These
|
correspond to the ‘st_atime’, ‘st_mtime’, and ‘st_ctime’ members of the
|
‘stat’ structure; see *note File Attributes::.
|
|
All of these times are represented in calendar time format, as
|
‘time_t’ objects. This data type is defined in ‘time.h’. For more
|
information about representation and manipulation of time values, see
|
*note Calendar Time::.
|
|
Reading from a file updates its access time attribute, and writing
|
updates its modification time. When a file is created, all three time
|
stamps for that file are set to the current time. In addition, the
|
attribute change time and modification time fields of the directory that
|
contains the new entry are updated.
|
|
Adding a new name for a file with the ‘link’ function updates the
|
attribute change time field of the file being linked, and both the
|
attribute change time and modification time fields of the directory
|
containing the new name. These same fields are affected if a file name
|
is deleted with ‘unlink’, ‘remove’ or ‘rmdir’. Renaming a file with
|
‘rename’ affects only the attribute change time and modification time
|
fields of the two parent directories involved, and not the times for the
|
file being renamed.
|
|
Changing the attributes of a file (for example, with ‘chmod’) updates
|
its attribute change time field.
|
|
You can also change some of the time stamps of a file explicitly
|
using the ‘utime’ function—all except the attribute change time. You
|
need to include the header file ‘utime.h’ to use this facility.
|
|
-- Data Type: struct utimbuf
|
|
The ‘utimbuf’ structure is used with the ‘utime’ function to
|
specify new access and modification times for a file. It contains
|
the following members:
|
|
‘time_t actime’
|
This is the access time for the file.
|
|
‘time_t modtime’
|
This is the modification time for the file.
|
|
-- Function: int utime (const char *FILENAME, const struct utimbuf
|
*TIMES)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is used to modify the file times associated with the
|
file named FILENAME.
|
|
If TIMES is a null pointer, then the access and modification times
|
of the file are set to the current time. Otherwise, they are set
|
to the values from the ‘actime’ and ‘modtime’ members
|
(respectively) of the ‘utimbuf’ structure pointed to by TIMES.
|
|
The attribute modification time for the file is set to the current
|
time in either case (since changing the time stamps is itself a
|
modification of the file attributes).
|
|
The ‘utime’ function returns ‘0’ if successful and ‘-1’ on failure.
|
In addition to the usual file name errors (*note File Name
|
Errors::), the following ‘errno’ error conditions are defined for
|
this function:
|
|
‘EACCES’
|
There is a permission problem in the case where a null pointer
|
was passed as the TIMES argument. In order to update the time
|
stamp on the file, you must either be the owner of the file,
|
have write permission for the file, or be a privileged user.
|
|
‘ENOENT’
|
The file doesn’t exist.
|
|
‘EPERM’
|
If the TIMES argument is not a null pointer, you must either
|
be the owner of the file or be a privileged user.
|
|
‘EROFS’
|
The file lives on a read-only file system.
|
|
Each of the three time stamps has a corresponding microsecond part,
|
which extends its resolution. These fields are called ‘st_atime_usec’,
|
‘st_mtime_usec’, and ‘st_ctime_usec’; each has a value between 0 and
|
999,999, which indicates the time in microseconds. They correspond to
|
the ‘tv_usec’ field of a ‘timeval’ structure; see *note Time Types::.
|
|
The ‘utimes’ function is like ‘utime’, but also lets you specify the
|
fractional part of the file times. The prototype for this function is
|
in the header file ‘sys/time.h’.
|
|
-- Function: int utimes (const char *FILENAME, const struct timeval
|
TVP[2])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function sets the file access and modification times of the
|
file FILENAME. The new file access time is specified by ‘TVP[0]’,
|
and the new modification time by ‘TVP[1]’. Similar to ‘utime’, if
|
TVP is a null pointer then the access and modification times of the
|
file are set to the current time. This function comes from BSD.
|
|
The return values and error conditions are the same as for the
|
‘utime’ function.
|
|
-- Function: int lutimes (const char *FILENAME, const struct timeval
|
TVP[2])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is like ‘utimes’, except that it does not follow
|
symbolic links. If FILENAME is the name of a symbolic link,
|
‘lutimes’ sets the file access and modification times of the
|
symbolic link special file itself (as seen by ‘lstat’; *note
|
Symbolic Links::) while ‘utimes’ sets the file access and
|
modification times of the file the symbolic link refers to. This
|
function comes from FreeBSD, and is not available on all platforms
|
(if not available, it will fail with ‘ENOSYS’).
|
|
The return values and error conditions are the same as for the
|
‘utime’ function.
|
|
-- Function: int futimes (int FD, const struct timeval TVP[2])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is like ‘utimes’, except that it takes an open file
|
descriptor as an argument instead of a file name. *Note Low-Level
|
I/O::. This function comes from FreeBSD, and is not available on
|
all platforms (if not available, it will fail with ‘ENOSYS’).
|
|
Like ‘utimes’, ‘futimes’ returns ‘0’ on success and ‘-1’ on
|
failure. The following ‘errno’ error conditions are defined for
|
‘futimes’:
|
|
‘EACCES’
|
There is a permission problem in the case where a null pointer
|
was passed as the TIMES argument. In order to update the time
|
stamp on the file, you must either be the owner of the file,
|
have write permission for the file, or be a privileged user.
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor.
|
|
‘EPERM’
|
If the TIMES argument is not a null pointer, you must either
|
be the owner of the file or be a privileged user.
|
|
‘EROFS’
|
The file lives on a read-only file system.
|
|
|
File: libc.info, Node: File Size, Next: Storage Allocation, Prev: File Times, Up: File Attributes
|
|
14.9.10 File Size
|
-----------------
|
|
Normally file sizes are maintained automatically. A file begins with a
|
size of 0 and is automatically extended when data is written past its
|
end. It is also possible to empty a file completely by an ‘open’ or
|
‘fopen’ call.
|
|
However, sometimes it is necessary to _reduce_ the size of a file.
|
This can be done with the ‘truncate’ and ‘ftruncate’ functions. They
|
were introduced in BSD Unix. ‘ftruncate’ was later added to POSIX.1.
|
|
Some systems allow you to extend a file (creating holes) with these
|
functions. This is useful when using memory-mapped I/O (*note
|
Memory-mapped I/O::), where files are not automatically extended.
|
However, it is not portable but must be implemented if ‘mmap’ allows
|
mapping of files (i.e., ‘_POSIX_MAPPED_FILES’ is defined).
|
|
Using these functions on anything other than a regular file gives
|
_undefined_ results. On many systems, such a call will appear to
|
succeed, without actually accomplishing anything.
|
|
-- Function: int truncate (const char *FILENAME, off_t LENGTH)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘truncate’ function changes the size of FILENAME to LENGTH. If
|
LENGTH is shorter than the previous length, data at the end will be
|
lost. The file must be writable by the user to perform this
|
operation.
|
|
If LENGTH is longer, holes will be added to the end. However, some
|
systems do not support this feature and will leave the file
|
unchanged.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
|
‘truncate’ function is in fact ‘truncate64’ and the type ‘off_t’
|
has 64 bits which makes it possible to handle files up to 2^63
|
bytes in length.
|
|
The return value is 0 for success, or -1 for an error. In addition
|
to the usual file name errors, the following errors may occur:
|
|
‘EACCES’
|
The file is a directory or not writable.
|
|
‘EINVAL’
|
LENGTH is negative.
|
|
‘EFBIG’
|
The operation would extend the file beyond the limits of the
|
operating system.
|
|
‘EIO’
|
A hardware I/O error occurred.
|
|
‘EPERM’
|
The file is "append-only" or "immutable".
|
|
‘EINTR’
|
The operation was interrupted by a signal.
|
|
-- Function: int truncate64 (const char *NAME, off64_t LENGTH)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘truncate’ function. The
|
difference is that the LENGTH argument is 64 bits wide even on 32
|
bits machines, which allows the handling of files with sizes up to
|
2^63 bytes.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ on
|
a 32 bits machine this function is actually available under the
|
name ‘truncate’ and so transparently replaces the 32 bits
|
interface.
|
|
-- Function: int ftruncate (int FD, off_t LENGTH)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This is like ‘truncate’, but it works on a file descriptor FD for
|
an opened file instead of a file name to identify the object. The
|
file must be opened for writing to successfully carry out the
|
operation.
|
|
The POSIX standard leaves it implementation defined what happens if
|
the specified new LENGTH of the file is bigger than the original
|
size. The ‘ftruncate’ function might simply leave the file alone
|
and do nothing or it can increase the size to the desired size. In
|
this later case the extended area should be zero-filled. So using
|
‘ftruncate’ is no reliable way to increase the file size but if it
|
is possible it is probably the fastest way. The function also
|
operates on POSIX shared memory segments if these are implemented
|
by the system.
|
|
‘ftruncate’ is especially useful in combination with ‘mmap’. Since
|
the mapped region must have a fixed size one cannot enlarge the
|
file by writing something beyond the last mapped page. Instead one
|
has to enlarge the file itself and then remap the file with the new
|
size. The example below shows how this works.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
|
‘ftruncate’ function is in fact ‘ftruncate64’ and the type ‘off_t’
|
has 64 bits which makes it possible to handle files up to 2^63
|
bytes in length.
|
|
The return value is 0 for success, or -1 for an error. The
|
following errors may occur:
|
|
‘EBADF’
|
FD does not correspond to an open file.
|
|
‘EACCES’
|
FD is a directory or not open for writing.
|
|
‘EINVAL’
|
LENGTH is negative.
|
|
‘EFBIG’
|
The operation would extend the file beyond the limits of the
|
operating system.
|
|
‘EIO’
|
A hardware I/O error occurred.
|
|
‘EPERM’
|
The file is "append-only" or "immutable".
|
|
‘EINTR’
|
The operation was interrupted by a signal.
|
|
-- Function: int ftruncate64 (int ID, off64_t LENGTH)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is similar to the ‘ftruncate’ function. The
|
difference is that the LENGTH argument is 64 bits wide even on 32
|
bits machines which allows the handling of files with sizes up to
|
2^63 bytes.
|
|
When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ on
|
a 32 bits machine this function is actually available under the
|
name ‘ftruncate’ and so transparently replaces the 32 bits
|
interface.
|
|
As announced here is a little example of how to use ‘ftruncate’ in
|
combination with ‘mmap’:
|
|
int fd;
|
void *start;
|
size_t len;
|
|
int
|
add (off_t at, void *block, size_t size)
|
{
|
if (at + size > len)
|
{
|
/* Resize the file and remap. */
|
size_t ps = sysconf (_SC_PAGESIZE);
|
size_t ns = (at + size + ps - 1) & ~(ps - 1);
|
void *np;
|
if (ftruncate (fd, ns) < 0)
|
return -1;
|
np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
|
if (np == MAP_FAILED)
|
return -1;
|
start = np;
|
len = ns;
|
}
|
memcpy ((char *) start + at, block, size);
|
return 0;
|
}
|
|
The function ‘add’ writes a block of memory at an arbitrary position
|
in the file. If the current size of the file is too small it is
|
extended. Note that it is extended by a whole number of pages. This is
|
a requirement of ‘mmap’. The program has to keep track of the real
|
size, and when it has finished a final ‘ftruncate’ call should set the
|
real size of the file.
|
|
|
File: libc.info, Node: Storage Allocation, Prev: File Size, Up: File Attributes
|
|
14.9.11 Storage Allocation
|
--------------------------
|
|
Most file systems support allocating large files in a non-contiguous
|
fashion: the file is split into _fragments_ which are allocated
|
sequentially, but the fragments themselves can be scattered across the
|
disk. File systems generally try to avoid such fragmentation because it
|
decreases performance, but if a file gradually increases in size, there
|
might be no other option than to fragment it. In addition, many file
|
systems support _sparse files_ with _holes_: regions of null bytes for
|
which no backing storage has been allocated by the file system. When
|
the holes are finally overwritten with data, fragmentation can occur as
|
well.
|
|
Explicit allocation of storage for yet-unwritten parts of the file
|
can help the system to avoid fragmentation. Additionally, if storage
|
pre-allocation fails, it is possible to report the out-of-disk error
|
early, often without filling up the entire disk. However, due to
|
deduplication, copy-on-write semantics, and file compression, such
|
pre-allocation may not reliably prevent the out-of-disk-space error from
|
occurring later. Checking for write errors is still required, and
|
writes to memory-mapped regions created with ‘mmap’ can still result in
|
‘SIGBUS’.
|
|
-- Function: int posix_fallocate (int FD, off_t OFFSET, off_t LENGTH)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
Allocate backing store for the region of LENGTH bytes starting at
|
byte OFFSET in the file for the descriptor FD. The file length is
|
increased to ‘LENGTH + OFFSET’ if necessary.
|
|
FD must be a regular file opened for writing, or ‘EBADF’ is
|
returned. If there is insufficient disk space to fulfill the
|
allocation request, ‘ENOSPC’ is returned.
|
|
*Note:* If ‘fallocate’ is not available (because the file system
|
does not support it), ‘posix_fallocate’ is emulated, which has the
|
following drawbacks:
|
|
• It is very inefficient because all file system blocks in the
|
requested range need to be examined (even if they have been
|
allocated before) and potentially rewritten. In contrast,
|
with proper ‘fallocate’ support (see below), the file system
|
can examine the internal file allocation data structures and
|
eliminate holes directly, maybe even using unwritten extents
|
(which are pre-allocated but uninitialized on disk).
|
|
• There is a race condition if another thread or process
|
modifies the underlying file in the to-be-allocated area.
|
Non-null bytes could be overwritten with null bytes.
|
|
• If FD has been opened with the ‘O_WRONLY’ flag, the function
|
will fail with an ‘errno’ value of ‘EBADF’.
|
|
• If FD has been opened with the ‘O_APPEND’ flag, the function
|
will fail with an ‘errno’ value of ‘EBADF’.
|
|
• If LENGTH is zero, ‘ftruncate’ is used to increase the file
|
size as requested, without allocating file system blocks.
|
There is a race condition which means that ‘ftruncate’ can
|
accidentally truncate the file if it has been extended
|
concurrently.
|
|
On Linux, if an application does not benefit from emulation or if
|
the emulation is harmful due to its inherent race conditions, the
|
application can use the Linux-specific ‘fallocate’ function, with a
|
zero flag argument. For the ‘fallocate’ function, the GNU C
|
Library does not perform allocation emulation if the file system
|
does not support allocation. Instead, an ‘EOPNOTSUPP’ is returned
|
to the caller.
|
|
-- Function: int posix_fallocate64 (int FD, off64_t OFFSET, off64_t
|
LENGTH)
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is a variant of ‘posix_fallocate64’ which accepts
|
64-bit file offsets on all platforms.
|
|
|
File: libc.info, Node: Making Special Files, Next: Temporary Files, Prev: File Attributes, Up: File System Interface
|
|
14.10 Making Special Files
|
==========================
|
|
The ‘mknod’ function is the primitive for making special files, such as
|
files that correspond to devices. The GNU C Library includes this
|
function for compatibility with BSD.
|
|
The prototype for ‘mknod’ is declared in ‘sys/stat.h’.
|
|
-- Function: int mknod (const char *FILENAME, mode_t MODE, dev_t DEV)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘mknod’ function makes a special file with name FILENAME. The
|
MODE specifies the mode of the file, and may include the various
|
special file bits, such as ‘S_IFCHR’ (for a character special file)
|
or ‘S_IFBLK’ (for a block special file). *Note Testing File
|
Type::.
|
|
The DEV argument specifies which device the special file refers to.
|
Its exact interpretation depends on the kind of special file being
|
created.
|
|
The return value is ‘0’ on success and ‘-1’ on error. In addition
|
to the usual file name errors (*note File Name Errors::), the
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EPERM’
|
The calling process is not privileged. Only the superuser can
|
create special files.
|
|
‘ENOSPC’
|
The directory or file system that would contain the new file
|
is full and cannot be extended.
|
|
‘EROFS’
|
The directory containing the new file can’t be modified
|
because it’s on a read-only file system.
|
|
‘EEXIST’
|
There is already a file named FILENAME. If you want to
|
replace this file, you must remove the old file explicitly
|
first.
|
|
|
File: libc.info, Node: Temporary Files, Prev: Making Special Files, Up: File System Interface
|
|
14.11 Temporary Files
|
=====================
|
|
If you need to use a temporary file in your program, you can use the
|
‘tmpfile’ function to open it. Or you can use the ‘tmpnam’ (better:
|
‘tmpnam_r’) function to provide a name for a temporary file and then you
|
can open it in the usual way with ‘fopen’.
|
|
The ‘tempnam’ function is like ‘tmpnam’ but lets you choose what
|
directory temporary files will go in, and something about what their
|
file names will look like. Important for multi-threaded programs is
|
that ‘tempnam’ is reentrant, while ‘tmpnam’ is not since it returns a
|
pointer to a static buffer.
|
|
These facilities are declared in the header file ‘stdio.h’.
|
|
-- Function: FILE * tmpfile (void)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
|
lock | *Note POSIX Safety Concepts::.
|
|
This function creates a temporary binary file for update mode, as
|
if by calling ‘fopen’ with mode ‘"wb+"’. The file is deleted
|
automatically when it is closed or when the program terminates.
|
(On some other ISO C systems the file may fail to be deleted if the
|
program terminates abnormally).
|
|
This function is reentrant.
|
|
When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
|
32-bit system this function is in fact ‘tmpfile64’, i.e., the LFS
|
interface transparently replaces the old interface.
|
|
-- Function: FILE * tmpfile64 (void)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
|
lock | *Note POSIX Safety Concepts::.
|
|
This function is similar to ‘tmpfile’, but the stream it returns a
|
pointer to was opened using ‘tmpfile64’. Therefore this stream can
|
be used for files larger than 2^31 bytes on 32-bit machines.
|
|
Please note that the return type is still ‘FILE *’. There is no
|
special ‘FILE’ type for the LFS interface.
|
|
If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
|
bits machine this function is available under the name ‘tmpfile’
|
and so transparently replaces the old interface.
|
|
-- Function: char * tmpnam (char *RESULT)
|
|
Preliminary: | MT-Unsafe race:tmpnam/!result | AS-Unsafe | AC-Safe
|
| *Note POSIX Safety Concepts::.
|
|
This function constructs and returns a valid file name that does
|
not refer to any existing file. If the RESULT argument is a null
|
pointer, the return value is a pointer to an internal static
|
string, which might be modified by subsequent calls and therefore
|
makes this function non-reentrant. Otherwise, the RESULT argument
|
should be a pointer to an array of at least ‘L_tmpnam’ characters,
|
and the result is written into that array.
|
|
It is possible for ‘tmpnam’ to fail if you call it too many times
|
without removing previously-created files. This is because the
|
limited length of the temporary file names gives room for only a
|
finite number of different names. If ‘tmpnam’ fails it returns a
|
null pointer.
|
|
*Warning:* Between the time the pathname is constructed and the
|
file is created another process might have created a file with the
|
same name using ‘tmpnam’, leading to a possible security hole. The
|
implementation generates names which can hardly be predicted, but
|
when opening the file you should use the ‘O_EXCL’ flag. Using
|
‘tmpfile’ or ‘mkstemp’ is a safe way to avoid this problem.
|
|
-- Function: char * tmpnam_r (char *RESULT)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is nearly identical to the ‘tmpnam’ function, except
|
that if RESULT is a null pointer it returns a null pointer.
|
|
This guarantees reentrancy because the non-reentrant situation of
|
‘tmpnam’ cannot happen here.
|
|
*Warning*: This function has the same security problems as
|
‘tmpnam’.
|
|
-- Macro: int L_tmpnam
|
|
The value of this macro is an integer constant expression that
|
represents the minimum size of a string large enough to hold a file
|
name generated by the ‘tmpnam’ function.
|
|
-- Macro: int TMP_MAX
|
|
The macro ‘TMP_MAX’ is a lower bound for how many temporary names
|
you can create with ‘tmpnam’. You can rely on being able to call
|
‘tmpnam’ at least this many times before it might fail saying you
|
have made too many temporary file names.
|
|
With the GNU C Library, you can create a very large number of
|
temporary file names. If you actually created the files, you would
|
probably run out of disk space before you ran out of names. Some
|
other systems have a fixed, small limit on the number of temporary
|
files. The limit is never less than ‘25’.
|
|
-- Function: char * tempnam (const char *DIR, const char *PREFIX)
|
|
Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
This function generates a unique temporary file name. If PREFIX is
|
not a null pointer, up to five characters of this string are used
|
as a prefix for the file name. The return value is a string newly
|
allocated with ‘malloc’, so you should release its storage with
|
‘free’ when it is no longer needed.
|
|
Because the string is dynamically allocated this function is
|
reentrant.
|
|
The directory prefix for the temporary file name is determined by
|
testing each of the following in sequence. The directory must
|
exist and be writable.
|
|
• The environment variable ‘TMPDIR’, if it is defined. For
|
security reasons this only happens if the program is not SUID
|
or SGID enabled.
|
|
• The DIR argument, if it is not a null pointer.
|
|
• The value of the ‘P_tmpdir’ macro.
|
|
• The directory ‘/tmp’.
|
|
This function is defined for SVID compatibility.
|
|
*Warning:* Between the time the pathname is constructed and the
|
file is created another process might have created a file with the
|
same name using ‘tempnam’, leading to a possible security hole.
|
The implementation generates names which can hardly be predicted,
|
but when opening the file you should use the ‘O_EXCL’ flag. Using
|
‘tmpfile’ or ‘mkstemp’ is a safe way to avoid this problem.
|
|
-- SVID Macro: char * P_tmpdir
|
|
This macro is the name of the default directory for temporary
|
files.
|
|
Older Unix systems did not have the functions just described.
|
Instead they used ‘mktemp’ and ‘mkstemp’. Both of these functions work
|
by modifying a file name template string you pass. The last six
|
characters of this string must be ‘XXXXXX’. These six ‘X’s are replaced
|
with six characters which make the whole string a unique file name.
|
Usually the template string is something like ‘/tmp/PREFIXXXXXXX’, and
|
each program uses a unique PREFIX.
|
|
*NB:* Because ‘mktemp’ and ‘mkstemp’ modify the template string, you
|
_must not_ pass string constants to them. String constants are normally
|
in read-only storage, so your program would crash when ‘mktemp’ or
|
‘mkstemp’ tried to modify the string. These functions are declared in
|
the header file ‘stdlib.h’.
|
|
-- Function: char * mktemp (char *TEMPLATE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘mktemp’ function generates a unique file name by modifying
|
TEMPLATE as described above. If successful, it returns TEMPLATE as
|
modified. If ‘mktemp’ cannot find a unique file name, it makes
|
TEMPLATE an empty string and returns that. If TEMPLATE does not
|
end with ‘XXXXXX’, ‘mktemp’ returns a null pointer.
|
|
*Warning:* Between the time the pathname is constructed and the
|
file is created another process might have created a file with the
|
same name using ‘mktemp’, leading to a possible security hole. The
|
implementation generates names which can hardly be predicted, but
|
when opening the file you should use the ‘O_EXCL’ flag. Using
|
‘mkstemp’ is a safe way to avoid this problem.
|
|
-- Function: int mkstemp (char *TEMPLATE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘mkstemp’ function generates a unique file name just as
|
‘mktemp’ does, but it also opens the file for you with ‘open’
|
(*note Opening and Closing Files::). If successful, it modifies
|
TEMPLATE in place and returns a file descriptor for that file open
|
for reading and writing. If ‘mkstemp’ cannot create a
|
uniquely-named file, it returns ‘-1’. If TEMPLATE does not end
|
with ‘XXXXXX’, ‘mkstemp’ returns ‘-1’ and does not modify TEMPLATE.
|
|
The file is opened using mode ‘0600’. If the file is meant to be
|
used by other users this mode must be changed explicitly.
|
|
Unlike ‘mktemp’, ‘mkstemp’ is actually guaranteed to create a unique
|
file that cannot possibly clash with any other program trying to create
|
a temporary file. This is because it works by calling ‘open’ with the
|
‘O_EXCL’ flag, which says you want to create a new file and get an error
|
if the file already exists.
|
|
-- Function: char * mkdtemp (char *TEMPLATE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘mkdtemp’ function creates a directory with a unique name. If
|
it succeeds, it overwrites TEMPLATE with the name of the directory,
|
and returns TEMPLATE. As with ‘mktemp’ and ‘mkstemp’, TEMPLATE
|
should be a string ending with ‘XXXXXX’.
|
|
If ‘mkdtemp’ cannot create an uniquely named directory, it returns
|
‘NULL’ and sets ‘errno’ appropriately. If TEMPLATE does not end
|
with ‘XXXXXX’, ‘mkdtemp’ returns ‘NULL’ and does not modify
|
TEMPLATE. ‘errno’ will be set to ‘EINVAL’ in this case.
|
|
The directory is created using mode ‘0700’.
|
|
The directory created by ‘mkdtemp’ cannot clash with temporary files
|
or directories created by other users. This is because directory
|
creation always works like ‘open’ with ‘O_EXCL’. *Note Creating
|
Directories::.
|
|
The ‘mkdtemp’ function comes from OpenBSD.
|
|
|
File: libc.info, Node: Pipes and FIFOs, Next: Sockets, Prev: File System Interface, Up: Top
|
|
15 Pipes and FIFOs
|
******************
|
|
A "pipe" is a mechanism for interprocess communication; data written to
|
the pipe by one process can be read by another process. The data is
|
handled in a first-in, first-out (FIFO) order. The pipe has no name; it
|
is created for one use and both ends must be inherited from the single
|
process which created the pipe.
|
|
A "FIFO special file" is similar to a pipe, but instead of being an
|
anonymous, temporary connection, a FIFO has a name or names like any
|
other file. Processes open the FIFO by name in order to communicate
|
through it.
|
|
A pipe or FIFO has to be open at both ends simultaneously. If you
|
read from a pipe or FIFO file that doesn’t have any processes writing to
|
it (perhaps because they have all closed the file, or exited), the read
|
returns end-of-file. Writing to a pipe or FIFO that doesn’t have a
|
reading process is treated as an error condition; it generates a
|
‘SIGPIPE’ signal, and fails with error code ‘EPIPE’ if the signal is
|
handled or blocked.
|
|
Neither pipes nor FIFO special files allow file positioning. Both
|
reading and writing operations happen sequentially; reading from the
|
beginning of the file and writing at the end.
|
|
* Menu:
|
|
* Creating a Pipe:: Making a pipe with the ‘pipe’ function.
|
* Pipe to a Subprocess:: Using a pipe to communicate with a
|
child process.
|
* FIFO Special Files:: Making a FIFO special file.
|
* Pipe Atomicity:: When pipe (or FIFO) I/O is atomic.
|
|
|
File: libc.info, Node: Creating a Pipe, Next: Pipe to a Subprocess, Up: Pipes and FIFOs
|
|
15.1 Creating a Pipe
|
====================
|
|
The primitive for creating a pipe is the ‘pipe’ function. This creates
|
both the reading and writing ends of the pipe. It is not very useful
|
for a single process to use a pipe to talk to itself. In typical use, a
|
process creates a pipe just before it forks one or more child processes
|
(*note Creating a Process::). The pipe is then used for communication
|
either between the parent or child processes, or between two sibling
|
processes.
|
|
The ‘pipe’ function is declared in the header file ‘unistd.h’.
|
|
-- Function: int pipe (int FILEDES[2])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘pipe’ function creates a pipe and puts the file descriptors
|
for the reading and writing ends of the pipe (respectively) into
|
‘FILEDES[0]’ and ‘FILEDES[1]’.
|
|
An easy way to remember that the input end comes first is that file
|
descriptor ‘0’ is standard input, and file descriptor ‘1’ is
|
standard output.
|
|
If successful, ‘pipe’ returns a value of ‘0’. On failure, ‘-1’ is
|
returned. The following ‘errno’ error conditions are defined for
|
this function:
|
|
‘EMFILE’
|
The process has too many files open.
|
|
‘ENFILE’
|
There are too many open files in the entire system. *Note
|
Error Codes::, for more information about ‘ENFILE’. This
|
error never occurs on GNU/Hurd systems.
|
|
Here is an example of a simple program that creates a pipe. This
|
program uses the ‘fork’ function (*note Creating a Process::) to create
|
a child process. The parent process writes data to the pipe, which is
|
read by the child process.
|
|
|
#include <sys/types.h>
|
#include <unistd.h>
|
#include <stdio.h>
|
#include <stdlib.h>
|
|
/* Read characters from the pipe and echo them to ‘stdout’. */
|
|
void
|
read_from_pipe (int file)
|
{
|
FILE *stream;
|
int c;
|
stream = fdopen (file, "r");
|
while ((c = fgetc (stream)) != EOF)
|
putchar (c);
|
fclose (stream);
|
}
|
|
/* Write some random text to the pipe. */
|
|
void
|
write_to_pipe (int file)
|
{
|
FILE *stream;
|
stream = fdopen (file, "w");
|
fprintf (stream, "hello, world!\n");
|
fprintf (stream, "goodbye, world!\n");
|
fclose (stream);
|
}
|
|
int
|
main (void)
|
{
|
pid_t pid;
|
int mypipe[2];
|
|
/* Create the pipe. */
|
if (pipe (mypipe))
|
{
|
fprintf (stderr, "Pipe failed.\n");
|
return EXIT_FAILURE;
|
}
|
|
/* Create the child process. */
|
pid = fork ();
|
if (pid == (pid_t) 0)
|
{
|
/* This is the child process.
|
Close other end first. */
|
close (mypipe[1]);
|
read_from_pipe (mypipe[0]);
|
return EXIT_SUCCESS;
|
}
|
else if (pid < (pid_t) 0)
|
{
|
/* The fork failed. */
|
fprintf (stderr, "Fork failed.\n");
|
return EXIT_FAILURE;
|
}
|
else
|
{
|
/* This is the parent process.
|
Close other end first. */
|
close (mypipe[0]);
|
write_to_pipe (mypipe[1]);
|
return EXIT_SUCCESS;
|
}
|
}
|
|
|
File: libc.info, Node: Pipe to a Subprocess, Next: FIFO Special Files, Prev: Creating a Pipe, Up: Pipes and FIFOs
|
|
15.2 Pipe to a Subprocess
|
=========================
|
|
A common use of pipes is to send data to or receive data from a program
|
being run as a subprocess. One way of doing this is by using a
|
combination of ‘pipe’ (to create the pipe), ‘fork’ (to create the
|
subprocess), ‘dup2’ (to force the subprocess to use the pipe as its
|
standard input or output channel), and ‘exec’ (to execute the new
|
program). Or, you can use ‘popen’ and ‘pclose’.
|
|
The advantage of using ‘popen’ and ‘pclose’ is that the interface is
|
much simpler and easier to use. But it doesn’t offer as much
|
flexibility as using the low-level functions directly.
|
|
-- Function: FILE * popen (const char *COMMAND, const char *MODE)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap corrupt | AC-Unsafe corrupt
|
lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘popen’ function is closely related to the ‘system’ function;
|
see *note Running a Command::. It executes the shell command
|
COMMAND as a subprocess. However, instead of waiting for the
|
command to complete, it creates a pipe to the subprocess and
|
returns a stream that corresponds to that pipe.
|
|
If you specify a MODE argument of ‘"r"’, you can read from the
|
stream to retrieve data from the standard output channel of the
|
subprocess. The subprocess inherits its standard input channel
|
from the parent process.
|
|
Similarly, if you specify a MODE argument of ‘"w"’, you can write
|
to the stream to send data to the standard input channel of the
|
subprocess. The subprocess inherits its standard output channel
|
from the parent process.
|
|
In the event of an error ‘popen’ returns a null pointer. This
|
might happen if the pipe or stream cannot be created, if the
|
subprocess cannot be forked, or if the program cannot be executed.
|
|
-- Function: int pclose (FILE *STREAM)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap plugin corrupt lock |
|
AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
|
|
The ‘pclose’ function is used to close a stream created by ‘popen’.
|
It waits for the child process to terminate and returns its status
|
value, as for the ‘system’ function.
|
|
Here is an example showing how to use ‘popen’ and ‘pclose’ to filter
|
output through another program, in this case the paging program ‘more’.
|
|
|
#include <stdio.h>
|
#include <stdlib.h>
|
|
void
|
write_data (FILE * stream)
|
{
|
int i;
|
for (i = 0; i < 100; i++)
|
fprintf (stream, "%d\n", i);
|
if (ferror (stream))
|
{
|
fprintf (stderr, "Output to stream failed.\n");
|
exit (EXIT_FAILURE);
|
}
|
}
|
|
int
|
main (void)
|
{
|
FILE *output;
|
|
output = popen ("more", "w");
|
if (!output)
|
{
|
fprintf (stderr,
|
"incorrect parameters or too many files.\n");
|
return EXIT_FAILURE;
|
}
|
write_data (output);
|
if (pclose (output) != 0)
|
{
|
fprintf (stderr,
|
"Could not run more or other error.\n");
|
}
|
return EXIT_SUCCESS;
|
}
|
|
|
File: libc.info, Node: FIFO Special Files, Next: Pipe Atomicity, Prev: Pipe to a Subprocess, Up: Pipes and FIFOs
|
|
15.3 FIFO Special Files
|
=======================
|
|
A FIFO special file is similar to a pipe, except that it is created in a
|
different way. Instead of being an anonymous communications channel, a
|
FIFO special file is entered into the file system by calling ‘mkfifo’.
|
|
Once you have created a FIFO special file in this way, any process
|
can open it for reading or writing, in the same way as an ordinary file.
|
However, it has to be open at both ends simultaneously before you can
|
proceed to do any input or output operations on it. Opening a FIFO for
|
reading normally blocks until some other process opens the same FIFO for
|
writing, and vice versa.
|
|
The ‘mkfifo’ function is declared in the header file ‘sys/stat.h’.
|
|
-- Function: int mkfifo (const char *FILENAME, mode_t MODE)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘mkfifo’ function makes a FIFO special file with name FILENAME.
|
The MODE argument is used to set the file’s permissions; see *note
|
Setting Permissions::.
|
|
The normal, successful return value from ‘mkfifo’ is ‘0’. In the
|
case of an error, ‘-1’ is returned. In addition to the usual file
|
name errors (*note File Name Errors::), the following ‘errno’ error
|
conditions are defined for this function:
|
|
‘EEXIST’
|
The named file already exists.
|
|
‘ENOSPC’
|
The directory or file system cannot be extended.
|
|
‘EROFS’
|
The directory that would contain the file resides on a
|
read-only file system.
|
|
|
File: libc.info, Node: Pipe Atomicity, Prev: FIFO Special Files, Up: Pipes and FIFOs
|
|
15.4 Atomicity of Pipe I/O
|
==========================
|
|
Reading or writing pipe data is "atomic" if the size of data written is
|
not greater than ‘PIPE_BUF’. This means that the data transfer seems to
|
be an instantaneous unit, in that nothing else in the system can observe
|
a state in which it is partially complete. Atomic I/O may not begin
|
right away (it may need to wait for buffer space or for data), but once
|
it does begin it finishes immediately.
|
|
Reading or writing a larger amount of data may not be atomic; for
|
example, output data from other processes sharing the descriptor may be
|
interspersed. Also, once ‘PIPE_BUF’ characters have been written,
|
further writes will block until some characters are read.
|
|
*Note Limits for Files::, for information about the ‘PIPE_BUF’
|
parameter.
|
|
|
File: libc.info, Node: Sockets, Next: Low-Level Terminal Interface, Prev: Pipes and FIFOs, Up: Top
|
|
16 Sockets
|
**********
|
|
This chapter describes the GNU facilities for interprocess communication
|
using sockets.
|
|
A "socket" is a generalized interprocess communication channel. Like
|
a pipe, a socket is represented as a file descriptor. Unlike pipes
|
sockets support communication between unrelated processes, and even
|
between processes running on different machines that communicate over a
|
network. Sockets are the primary means of communicating with other
|
machines; ‘telnet’, ‘rlogin’, ‘ftp’, ‘talk’ and the other familiar
|
network programs use sockets.
|
|
Not all operating systems support sockets. In the GNU C Library, the
|
header file ‘sys/socket.h’ exists regardless of the operating system,
|
and the socket functions always exist, but if the system does not really
|
support sockets these functions always fail.
|
|
*Incomplete:* We do not currently document the facilities for
|
broadcast messages or for configuring Internet interfaces. The
|
reentrant functions and some newer functions that are related to IPv6
|
aren’t documented either so far.
|
|
* Menu:
|
|
* Socket Concepts:: Basic concepts you need to know about.
|
* Communication Styles::Stream communication, datagrams and other styles.
|
* Socket Addresses:: How socket names (“addresses”) work.
|
* Interface Naming:: Identifying specific network interfaces.
|
* Local Namespace:: Details about the local namespace.
|
* Internet Namespace:: Details about the Internet namespace.
|
* Misc Namespaces:: Other namespaces not documented fully here.
|
* Open/Close Sockets:: Creating sockets and destroying them.
|
* Connections:: Operations on sockets with connection state.
|
* Datagrams:: Operations on datagram sockets.
|
* Inetd:: Inetd is a daemon that starts servers on request.
|
The most convenient way to write a server
|
is to make it work with Inetd.
|
* Socket Options:: Miscellaneous low-level socket options.
|
* Networks Database:: Accessing the database of network names.
|
|
|
File: libc.info, Node: Socket Concepts, Next: Communication Styles, Up: Sockets
|
|
16.1 Socket Concepts
|
====================
|
|
When you create a socket, you must specify the style of communication
|
you want to use and the type of protocol that should implement it. The
|
"communication style" of a socket defines the user-level semantics of
|
sending and receiving data on the socket. Choosing a communication
|
style specifies the answers to questions such as these:
|
|
• *What are the units of data transmission?* Some communication
|
styles regard the data as a sequence of bytes with no larger
|
structure; others group the bytes into records (which are known in
|
this context as "packets").
|
|
• *Can data be lost during normal operation?* Some communication
|
styles guarantee that all the data sent arrives in the order it was
|
sent (barring system or network crashes); other styles occasionally
|
lose data as a normal part of operation, and may sometimes deliver
|
packets more than once or in the wrong order.
|
|
Designing a program to use unreliable communication styles usually
|
involves taking precautions to detect lost or misordered packets
|
and to retransmit data as needed.
|
|
• *Is communication entirely with one partner?* Some communication
|
styles are like a telephone call—you make a "connection" with one
|
remote socket and then exchange data freely. Other styles are like
|
mailing letters—you specify a destination address for each message
|
you send.
|
|
You must also choose a "namespace" for naming the socket. A socket
|
name (“address”) is meaningful only in the context of a particular
|
namespace. In fact, even the data type to use for a socket name may
|
depend on the namespace. Namespaces are also called “domains”, but we
|
avoid that word as it can be confused with other usage of the same term.
|
Each namespace has a symbolic name that starts with ‘PF_’. A
|
corresponding symbolic name starting with ‘AF_’ designates the address
|
format for that namespace.
|
|
Finally you must choose the "protocol" to carry out the
|
communication. The protocol determines what low-level mechanism is used
|
to transmit and receive data. Each protocol is valid for a particular
|
namespace and communication style; a namespace is sometimes called a
|
"protocol family" because of this, which is why the namespace names
|
start with ‘PF_’.
|
|
The rules of a protocol apply to the data passing between two
|
programs, perhaps on different computers; most of these rules are
|
handled by the operating system and you need not know about them. What
|
you do need to know about protocols is this:
|
|
• In order to have communication between two sockets, they must
|
specify the _same_ protocol.
|
|
• Each protocol is meaningful with particular style/namespace
|
combinations and cannot be used with inappropriate combinations.
|
For example, the TCP protocol fits only the byte stream style of
|
communication and the Internet namespace.
|
|
• For each combination of style and namespace there is a "default
|
protocol", which you can request by specifying 0 as the protocol
|
number. And that’s what you should normally do—use the default.
|
|
Throughout the following description at various places
|
variables/parameters to denote sizes are required. And here the trouble
|
starts. In the first implementations the type of these variables was
|
simply ‘int’. On most machines at that time an ‘int’ was 32 bits wide,
|
which created a _de facto_ standard requiring 32-bit variables. This is
|
important since references to variables of this type are passed to the
|
kernel.
|
|
Then the POSIX people came and unified the interface with the words
|
"all size values are of type ‘size_t’". On 64-bit machines ‘size_t’ is
|
64 bits wide, so pointers to variables were no longer possible.
|
|
The Unix98 specification provides a solution by introducing a type
|
‘socklen_t’. This type is used in all of the cases that POSIX changed
|
to use ‘size_t’. The only requirement of this type is that it be an
|
unsigned type of at least 32 bits. Therefore, implementations which
|
require that references to 32-bit variables be passed can be as happy as
|
implementations which use 64-bit values.
|
|
|
File: libc.info, Node: Communication Styles, Next: Socket Addresses, Prev: Socket Concepts, Up: Sockets
|
|
16.2 Communication Styles
|
=========================
|
|
The GNU C Library includes support for several different kinds of
|
sockets, each with different characteristics. This section describes
|
the supported socket types. The symbolic constants listed here are
|
defined in ‘sys/socket.h’.
|
|
-- Macro: int SOCK_STREAM
|
|
The ‘SOCK_STREAM’ style is like a pipe (*note Pipes and FIFOs::).
|
It operates over a connection with a particular remote socket and
|
transmits data reliably as a stream of bytes.
|
|
Use of this style is covered in detail in *note Connections::.
|
|
-- Macro: int SOCK_DGRAM
|
|
The ‘SOCK_DGRAM’ style is used for sending individually-addressed
|
packets unreliably. It is the diametrical opposite of
|
‘SOCK_STREAM’.
|
|
Each time you write data to a socket of this kind, that data
|
becomes one packet. Since ‘SOCK_DGRAM’ sockets do not have
|
connections, you must specify the recipient address with each
|
packet.
|
|
The only guarantee that the system makes about your requests to
|
transmit data is that it will try its best to deliver each packet
|
you send. It may succeed with the sixth packet after failing with
|
the fourth and fifth packets; the seventh packet may arrive before
|
the sixth, and may arrive a second time after the sixth.
|
|
The typical use for ‘SOCK_DGRAM’ is in situations where it is
|
acceptable to simply re-send a packet if no response is seen in a
|
reasonable amount of time.
|
|
*Note Datagrams::, for detailed information about how to use
|
datagram sockets.
|
|
-- Macro: int SOCK_RAW
|
|
This style provides access to low-level network protocols and
|
interfaces. Ordinary user programs usually have no need to use
|
this style.
|
|
|
File: libc.info, Node: Socket Addresses, Next: Interface Naming, Prev: Communication Styles, Up: Sockets
|
|
16.3 Socket Addresses
|
=====================
|
|
The name of a socket is normally called an "address". The functions and
|
symbols for dealing with socket addresses were named inconsistently,
|
sometimes using the term “name” and sometimes using “address”. You can
|
regard these terms as synonymous where sockets are concerned.
|
|
A socket newly created with the ‘socket’ function has no address.
|
Other processes can find it for communication only if you give it an
|
address. We call this "binding" the address to the socket, and the way
|
to do it is with the ‘bind’ function.
|
|
You need only be concerned with the address of a socket if other
|
processes are to find it and start communicating with it. You can
|
specify an address for other sockets, but this is usually pointless; the
|
first time you send data from a socket, or use it to initiate a
|
connection, the system assigns an address automatically if you have not
|
specified one.
|
|
Occasionally a client needs to specify an address because the server
|
discriminates based on address; for example, the rsh and rlogin
|
protocols look at the client’s socket address and only bypass passphrase
|
checking if it is less than ‘IPPORT_RESERVED’ (*note Ports::).
|
|
The details of socket addresses vary depending on what namespace you
|
are using. *Note Local Namespace::, or *note Internet Namespace::, for
|
specific information.
|
|
Regardless of the namespace, you use the same functions ‘bind’ and
|
‘getsockname’ to set and examine a socket’s address. These functions
|
use a phony data type, ‘struct sockaddr *’, to accept the address. In
|
practice, the address lives in a structure of some other data type
|
appropriate to the address format you are using, but you cast its
|
address to ‘struct sockaddr *’ when you pass it to ‘bind’.
|
|
* Menu:
|
|
* Address Formats:: About ‘struct sockaddr’.
|
* Setting Address:: Binding an address to a socket.
|
* Reading Address:: Reading the address of a socket.
|
|
|
File: libc.info, Node: Address Formats, Next: Setting Address, Up: Socket Addresses
|
|
16.3.1 Address Formats
|
----------------------
|
|
The functions ‘bind’ and ‘getsockname’ use the generic data type ‘struct
|
sockaddr *’ to represent a pointer to a socket address. You can’t use
|
this data type effectively to interpret an address or construct one; for
|
that, you must use the proper data type for the socket’s namespace.
|
|
Thus, the usual practice is to construct an address of the proper
|
namespace-specific type, then cast a pointer to ‘struct sockaddr *’ when
|
you call ‘bind’ or ‘getsockname’.
|
|
The one piece of information that you can get from the ‘struct
|
sockaddr’ data type is the "address format designator". This tells you
|
which data type to use to understand the address fully.
|
|
The symbols in this section are defined in the header file
|
‘sys/socket.h’.
|
|
-- Data Type: struct sockaddr
|
|
The ‘struct sockaddr’ type itself has the following members:
|
|
‘short int sa_family’
|
This is the code for the address format of this address. It
|
identifies the format of the data which follows.
|
|
‘char sa_data[14]’
|
This is the actual socket address data, which is
|
format-dependent. Its length also depends on the format, and
|
may well be more than 14. The length 14 of ‘sa_data’ is
|
essentially arbitrary.
|
|
Each address format has a symbolic name which starts with ‘AF_’.
|
Each of them corresponds to a ‘PF_’ symbol which designates the
|
corresponding namespace. Here is a list of address format names:
|
|
‘AF_LOCAL’
|
|
This designates the address format that goes with the local
|
namespace. (‘PF_LOCAL’ is the name of that namespace.) *Note
|
Local Namespace Details::, for information about this address
|
format.
|
|
‘AF_UNIX’
|
|
This is a synonym for ‘AF_LOCAL’. Although ‘AF_LOCAL’ is mandated
|
by POSIX.1g, ‘AF_UNIX’ is portable to more systems. ‘AF_UNIX’ was
|
the traditional name stemming from BSD, so even most POSIX systems
|
support it. It is also the name of choice in the Unix98
|
specification. (The same is true for ‘PF_UNIX’ vs. ‘PF_LOCAL’).
|
|
‘AF_FILE’
|
|
This is another synonym for ‘AF_LOCAL’, for compatibility.
|
(‘PF_FILE’ is likewise a synonym for ‘PF_LOCAL’.)
|
|
‘AF_INET’
|
|
This designates the address format that goes with the Internet
|
namespace. (‘PF_INET’ is the name of that namespace.) *Note
|
Internet Address Formats::.
|
|
‘AF_INET6’
|
|
This is similar to ‘AF_INET’, but refers to the IPv6 protocol.
|
(‘PF_INET6’ is the name of the corresponding namespace.)
|
|
‘AF_UNSPEC’
|
|
This designates no particular address format. It is used only in
|
rare cases, such as to clear out the default destination address of
|
a “connected” datagram socket. *Note Sending Datagrams::.
|
|
The corresponding namespace designator symbol ‘PF_UNSPEC’ exists
|
for completeness, but there is no reason to use it in a program.
|
|
‘sys/socket.h’ defines symbols starting with ‘AF_’ for many different
|
kinds of networks, most or all of which are not actually implemented.
|
We will document those that really work as we receive information about
|
how to use them.
|
|
|
File: libc.info, Node: Setting Address, Next: Reading Address, Prev: Address Formats, Up: Socket Addresses
|
|
16.3.2 Setting the Address of a Socket
|
--------------------------------------
|
|
Use the ‘bind’ function to assign an address to a socket. The prototype
|
for ‘bind’ is in the header file ‘sys/socket.h’. For examples of use,
|
see *note Local Socket Example::, or see *note Inet Example::.
|
|
-- Function: int bind (int SOCKET, struct sockaddr *ADDR, socklen_t
|
LENGTH)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘bind’ function assigns an address to the socket SOCKET. The
|
ADDR and LENGTH arguments specify the address; the detailed format
|
of the address depends on the namespace. The first part of the
|
address is always the format designator, which specifies a
|
namespace, and says that the address is in the format of that
|
namespace.
|
|
The return value is ‘0’ on success and ‘-1’ on failure. The
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EBADF’
|
The SOCKET argument is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
The descriptor SOCKET is not a socket.
|
|
‘EADDRNOTAVAIL’
|
The specified address is not available on this machine.
|
|
‘EADDRINUSE’
|
Some other socket is already using the specified address.
|
|
‘EINVAL’
|
The socket SOCKET already has an address.
|
|
‘EACCES’
|
You do not have permission to access the requested address.
|
(In the Internet domain, only the super-user is allowed to
|
specify a port number in the range 0 through ‘IPPORT_RESERVED’
|
minus one; see *note Ports::.)
|
|
Additional conditions may be possible depending on the particular
|
namespace of the socket.
|
|
|
File: libc.info, Node: Reading Address, Prev: Setting Address, Up: Socket Addresses
|
|
16.3.3 Reading the Address of a Socket
|
--------------------------------------
|
|
Use the function ‘getsockname’ to examine the address of an Internet
|
socket. The prototype for this function is in the header file
|
‘sys/socket.h’.
|
|
-- Function: int getsockname (int SOCKET, struct sockaddr *ADDR,
|
socklen_t *LENGTH-PTR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe mem/hurd | *Note POSIX
|
Safety Concepts::.
|
|
The ‘getsockname’ function returns information about the address of
|
the socket SOCKET in the locations specified by the ADDR and
|
LENGTH-PTR arguments. Note that the LENGTH-PTR is a pointer; you
|
should initialize it to be the allocation size of ADDR, and on
|
return it contains the actual size of the address data.
|
|
The format of the address data depends on the socket namespace.
|
The length of the information is usually fixed for a given
|
namespace, so normally you can know exactly how much space is
|
needed and can provide that much. The usual practice is to
|
allocate a place for the value using the proper data type for the
|
socket’s namespace, then cast its address to ‘struct sockaddr *’ to
|
pass it to ‘getsockname’.
|
|
The return value is ‘0’ on success and ‘-1’ on error. The
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EBADF’
|
The SOCKET argument is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
The descriptor SOCKET is not a socket.
|
|
‘ENOBUFS’
|
There are not enough internal buffers available for the
|
operation.
|
|
You can’t read the address of a socket in the file namespace. This
|
is consistent with the rest of the system; in general, there’s no way to
|
find a file’s name from a descriptor for that file.
|
|
|
File: libc.info, Node: Interface Naming, Next: Local Namespace, Prev: Socket Addresses, Up: Sockets
|
|
16.4 Interface Naming
|
=====================
|
|
Each network interface has a name. This usually consists of a few
|
letters that relate to the type of interface, which may be followed by a
|
number if there is more than one interface of that type. Examples might
|
be ‘lo’ (the loopback interface) and ‘eth0’ (the first Ethernet
|
interface).
|
|
Although such names are convenient for humans, it would be clumsy to
|
have to use them whenever a program needs to refer to an interface. In
|
such situations an interface is referred to by its "index", which is an
|
arbitrarily-assigned small positive integer.
|
|
The following functions, constants and data types are declared in the
|
header file ‘net/if.h’.
|
|
-- Constant: size_t IFNAMSIZ
|
|
This constant defines the maximum buffer size needed to hold an
|
interface name, including its terminating zero byte.
|
|
-- Function: unsigned int if_nametoindex (const char *IFNAME)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd | *Note
|
POSIX Safety Concepts::.
|
|
This function yields the interface index corresponding to a
|
particular name. If no interface exists with the name given, it
|
returns 0.
|
|
-- Function: char * if_indextoname (unsigned int IFINDEX, char *IFNAME)
|
|
Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock fd | *Note
|
POSIX Safety Concepts::.
|
|
This function maps an interface index to its corresponding name.
|
The returned name is placed in the buffer pointed to by ‘ifname’,
|
which must be at least ‘IFNAMSIZ’ bytes in length. If the index
|
was invalid, the function’s return value is a null pointer,
|
otherwise it is ‘ifname’.
|
|
-- Data Type: struct if_nameindex
|
|
This data type is used to hold the information about a single
|
interface. It has the following members:
|
|
‘unsigned int if_index;’
|
This is the interface index.
|
|
‘char *if_name’
|
This is the null-terminated index name.
|
|
-- Function: struct if_nameindex * if_nameindex (void)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap lock/hurd | AC-Unsafe
|
lock/hurd fd mem | *Note POSIX Safety Concepts::.
|
|
This function returns an array of ‘if_nameindex’ structures, one
|
for every interface that is present. The end of the list is
|
indicated by a structure with an interface of 0 and a null name
|
pointer. If an error occurs, this function returns a null pointer.
|
|
The returned structure must be freed with ‘if_freenameindex’ after
|
use.
|
|
-- Function: void if_freenameindex (struct if_nameindex *PTR)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
|
POSIX Safety Concepts::.
|
|
This function frees the structure returned by an earlier call to
|
‘if_nameindex’.
|
|
|
File: libc.info, Node: Local Namespace, Next: Internet Namespace, Prev: Interface Naming, Up: Sockets
|
|
16.5 The Local Namespace
|
========================
|
|
This section describes the details of the local namespace, whose
|
symbolic name (required when you create a socket) is ‘PF_LOCAL’. The
|
local namespace is also known as “Unix domain sockets”. Another name is
|
file namespace since socket addresses are normally implemented as file
|
names.
|
|
* Menu:
|
|
* Concepts: Local Namespace Concepts. What you need to understand.
|
* Details: Local Namespace Details. Address format, symbolic names, etc.
|
* Example: Local Socket Example. Example of creating a socket.
|
|
|
File: libc.info, Node: Local Namespace Concepts, Next: Local Namespace Details, Up: Local Namespace
|
|
16.5.1 Local Namespace Concepts
|
-------------------------------
|
|
In the local namespace socket addresses are file names. You can specify
|
any file name you want as the address of the socket, but you must have
|
write permission on the directory containing it. It’s common to put
|
these files in the ‘/tmp’ directory.
|
|
One peculiarity of the local namespace is that the name is only used
|
when opening the connection; once open the address is not meaningful and
|
may not exist.
|
|
Another peculiarity is that you cannot connect to such a socket from
|
another machine–not even if the other machine shares the file system
|
which contains the name of the socket. You can see the socket in a
|
directory listing, but connecting to it never succeeds. Some programs
|
take advantage of this, such as by asking the client to send its own
|
process ID, and using the process IDs to distinguish between clients.
|
However, we recommend you not use this method in protocols you design,
|
as we might someday permit connections from other machines that mount
|
the same file systems. Instead, send each new client an identifying
|
number if you want it to have one.
|
|
After you close a socket in the local namespace, you should delete
|
the file name from the file system. Use ‘unlink’ or ‘remove’ to do
|
this; see *note Deleting Files::.
|
|
The local namespace supports just one protocol for any communication
|
style; it is protocol number ‘0’.
|
|
|
File: libc.info, Node: Local Namespace Details, Next: Local Socket Example, Prev: Local Namespace Concepts, Up: Local Namespace
|
|
16.5.2 Details of Local Namespace
|
---------------------------------
|
|
To create a socket in the local namespace, use the constant ‘PF_LOCAL’
|
as the NAMESPACE argument to ‘socket’ or ‘socketpair’. This constant is
|
defined in ‘sys/socket.h’.
|
|
-- Macro: int PF_LOCAL
|
|
This designates the local namespace, in which socket addresses are
|
local names, and its associated family of protocols. ‘PF_LOCAL’ is
|
the macro used by POSIX.1g.
|
|
-- Macro: int PF_UNIX
|
|
This is a synonym for ‘PF_LOCAL’, for compatibility’s sake.
|
|
-- Macro: int PF_FILE
|
|
This is a synonym for ‘PF_LOCAL’, for compatibility’s sake.
|
|
The structure for specifying socket names in the local namespace is
|
defined in the header file ‘sys/un.h’:
|
|
-- Data Type: struct sockaddr_un
|
|
This structure is used to specify local namespace socket addresses.
|
It has the following members:
|
|
‘short int sun_family’
|
This identifies the address family or format of the socket
|
address. You should store the value ‘AF_LOCAL’ to designate
|
the local namespace. *Note Socket Addresses::.
|
|
‘char sun_path[108]’
|
This is the file name to use.
|
|
*Incomplete:* Why is 108 a magic number? RMS suggests making
|
this a zero-length array and tweaking the following example to
|
use ‘alloca’ to allocate an appropriate amount of storage
|
based on the length of the filename.
|
|
You should compute the LENGTH parameter for a socket address in the
|
local namespace as the sum of the size of the ‘sun_family’ component and
|
the string length (_not_ the allocation size!) of the file name string.
|
This can be done using the macro ‘SUN_LEN’:
|
|
-- Macro: int SUN_LEN (_struct sockaddr_un *_ PTR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This macro computes the length of the socket address in the local
|
namespace.
|
|
|
File: libc.info, Node: Local Socket Example, Prev: Local Namespace Details, Up: Local Namespace
|
|
16.5.3 Example of Local-Namespace Sockets
|
-----------------------------------------
|
|
Here is an example showing how to create and name a socket in the local
|
namespace.
|
|
|
#include <stddef.h>
|
#include <stdio.h>
|
#include <errno.h>
|
#include <stdlib.h>
|
#include <string.h>
|
#include <sys/socket.h>
|
#include <sys/un.h>
|
|
int
|
make_named_socket (const char *filename)
|
{
|
struct sockaddr_un name;
|
int sock;
|
size_t size;
|
|
/* Create the socket. */
|
sock = socket (PF_LOCAL, SOCK_DGRAM, 0);
|
if (sock < 0)
|
{
|
perror ("socket");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Bind a name to the socket. */
|
name.sun_family = AF_LOCAL;
|
strncpy (name.sun_path, filename, sizeof (name.sun_path));
|
name.sun_path[sizeof (name.sun_path) - 1] = '\0';
|
|
/* The size of the address is
|
the offset of the start of the filename,
|
plus its length (not including the terminating null byte).
|
Alternatively you can just do:
|
size = SUN_LEN (&name);
|
*/
|
size = (offsetof (struct sockaddr_un, sun_path)
|
+ strlen (name.sun_path));
|
|
if (bind (sock, (struct sockaddr *) &name, size) < 0)
|
{
|
perror ("bind");
|
exit (EXIT_FAILURE);
|
}
|
|
return sock;
|
}
|
|
|
File: libc.info, Node: Internet Namespace, Next: Misc Namespaces, Prev: Local Namespace, Up: Sockets
|
|
16.6 The Internet Namespace
|
===========================
|
|
This section describes the details of the protocols and socket naming
|
conventions used in the Internet namespace.
|
|
Originally the Internet namespace used only IP version 4 (IPv4).
|
With the growing number of hosts on the Internet, a new protocol with a
|
larger address space was necessary: IP version 6 (IPv6). IPv6
|
introduces 128-bit addresses (IPv4 has 32-bit addresses) and other
|
features, and will eventually replace IPv4.
|
|
To create a socket in the IPv4 Internet namespace, use the symbolic
|
name ‘PF_INET’ of this namespace as the NAMESPACE argument to ‘socket’
|
or ‘socketpair’. For IPv6 addresses you need the macro ‘PF_INET6’.
|
These macros are defined in ‘sys/socket.h’.
|
|
-- Macro: int PF_INET
|
|
This designates the IPv4 Internet namespace and associated family
|
of protocols.
|
|
-- Macro: int PF_INET6
|
|
This designates the IPv6 Internet namespace and associated family
|
of protocols.
|
|
A socket address for the Internet namespace includes the following
|
components:
|
|
• The address of the machine you want to connect to. Internet
|
addresses can be specified in several ways; these are discussed in
|
*note Internet Address Formats::, *note Host Addresses:: and *note
|
Host Names::.
|
|
• A port number for that machine. *Note Ports::.
|
|
You must ensure that the address and port number are represented in a
|
canonical format called "network byte order". *Note Byte Order::, for
|
information about this.
|
|
* Menu:
|
|
* Internet Address Formats:: How socket addresses are specified in the
|
Internet namespace.
|
* Host Addresses:: All about host addresses of Internet host.
|
* Ports:: Internet port numbers.
|
* Services Database:: Ports may have symbolic names.
|
* Byte Order:: Different hosts may use different byte
|
ordering conventions; you need to
|
canonicalize host address and port number.
|
* Protocols Database:: Referring to protocols by name.
|
* Inet Example:: Putting it all together.
|
|
|
File: libc.info, Node: Internet Address Formats, Next: Host Addresses, Up: Internet Namespace
|
|
16.6.1 Internet Socket Address Formats
|
--------------------------------------
|
|
In the Internet namespace, for both IPv4 (‘AF_INET’) and IPv6
|
(‘AF_INET6’), a socket address consists of a host address and a port on
|
that host. In addition, the protocol you choose serves effectively as a
|
part of the address because local port numbers are meaningful only
|
within a particular protocol.
|
|
The data types for representing socket addresses in the Internet
|
namespace are defined in the header file ‘netinet/in.h’.
|
|
-- Data Type: struct sockaddr_in
|
|
This is the data type used to represent socket addresses in the
|
Internet namespace. It has the following members:
|
|
‘sa_family_t sin_family’
|
This identifies the address family or format of the socket
|
address. You should store the value ‘AF_INET’ in this member.
|
The address family is stored in host byte order. *Note Socket
|
Addresses::.
|
|
‘struct in_addr sin_addr’
|
This is the IPv4 address. *Note Host Addresses::, and *note
|
Host Names::, for how to get a value to store here. The IPv4
|
address is stored in network byte order.
|
|
‘unsigned short int sin_port’
|
This is the port number. *Note Ports::. The port number is
|
stored in network byte order.
|
|
When you call ‘bind’ or ‘getsockname’, you should specify ‘sizeof
|
(struct sockaddr_in)’ as the LENGTH parameter if you are using an IPv4
|
Internet namespace socket address.
|
|
-- Data Type: struct sockaddr_in6
|
This is the data type used to represent socket addresses in the
|
IPv6 namespace. It has the following members:
|
|
‘sa_family_t sin6_family’
|
This identifies the address family or format of the socket
|
address. You should store the value of ‘AF_INET6’ in this
|
member. *Note Socket Addresses::. The address family is
|
stored in host byte order.
|
|
‘struct in6_addr sin6_addr’
|
This is the IPv6 address of the host machine. *Note Host
|
Addresses::, and *note Host Names::, for how to get a value to
|
store here. The address is stored in network byte order.
|
|
‘uint32_t sin6_flowinfo’
|
This combines the IPv6 traffic class and flow label values, as
|
found in the IPv6 header. This field is stored in network
|
byte order. Only the 28 lower bits (of the number in network
|
byte order) are used; the remainig bits must be zero. The
|
lower 20 bits are the flow label, and bits 20 to 27 are the
|
the traffic class. Typically, this field is zero.
|
|
‘uint32_t sin6_scope_id’
|
For link-local addresses, this identifies the interface on
|
which this address is valid. The scope ID is stored in host
|
byte order. Typically, this field is zero.
|
|
‘uint16_t sin6_port’
|
This is the port number. *Note Ports::. The port number is
|
stored in network byte order.
|
|
|
File: libc.info, Node: Host Addresses, Next: Ports, Prev: Internet Address Formats, Up: Internet Namespace
|
|
16.6.2 Host Addresses
|
---------------------
|
|
Each computer on the Internet has one or more "Internet addresses",
|
numbers which identify that computer among all those on the Internet.
|
Users typically write IPv4 numeric host addresses as sequences of four
|
numbers, separated by periods, as in ‘128.52.46.32’, and IPv6 numeric
|
host addresses as sequences of up to eight numbers separated by colons,
|
as in ‘5f03:1200:836f:c100::1’.
|
|
Each computer also has one or more "host names", which are strings of
|
words separated by periods, as in ‘www.gnu.org’.
|
|
Programs that let the user specify a host typically accept both
|
numeric addresses and host names. To open a connection a program needs
|
a numeric address, and so must convert a host name to the numeric
|
address it stands for.
|
|
* Menu:
|
|
* Abstract Host Addresses:: What a host number consists of.
|
* Data type: Host Address Data Type. Data type for a host number.
|
* Functions: Host Address Functions. Functions to operate on them.
|
* Names: Host Names. Translating host names to host numbers.
|
|
|
File: libc.info, Node: Abstract Host Addresses, Next: Host Address Data Type, Up: Host Addresses
|
|
16.6.2.1 Internet Host Addresses
|
................................
|
|
Each computer on the Internet has one or more Internet addresses,
|
numbers which identify that computer among all those on the Internet.
|
|
An IPv4 Internet host address is a number containing four bytes of
|
data. Historically these are divided into two parts, a "network number"
|
and a "local network address number" within that network. In the
|
mid-1990s classless addresses were introduced which changed this
|
behavior. Since some functions implicitly expect the old definitions,
|
we first describe the class-based network and will then describe
|
classless addresses. IPv6 uses only classless addresses and therefore
|
the following paragraphs don’t apply.
|
|
The class-based IPv4 network number consists of the first one, two or
|
three bytes; the rest of the bytes are the local address.
|
|
IPv4 network numbers are registered with the Network Information
|
Center (NIC), and are divided into three classes—A, B and C. The local
|
network address numbers of individual machines are registered with the
|
administrator of the particular network.
|
|
Class A networks have single-byte numbers in the range 0 to 127.
|
There are only a small number of Class A networks, but they can each
|
support a very large number of hosts. Medium-sized Class B networks
|
have two-byte network numbers, with the first byte in the range 128 to
|
191. Class C networks are the smallest; they have three-byte network
|
numbers, with the first byte in the range 192-255. Thus, the first 1,
|
2, or 3 bytes of an Internet address specify a network. The remaining
|
bytes of the Internet address specify the address within that network.
|
|
The Class A network 0 is reserved for broadcast to all networks. In
|
addition, the host number 0 within each network is reserved for
|
broadcast to all hosts in that network. These uses are obsolete now but
|
for compatibility reasons you shouldn’t use network 0 and host number 0.
|
|
The Class A network 127 is reserved for loopback; you can always use
|
the Internet address ‘127.0.0.1’ to refer to the host machine.
|
|
Since a single machine can be a member of multiple networks, it can
|
have multiple Internet host addresses. However, there is never supposed
|
to be more than one machine with the same host address.
|
|
There are four forms of the "standard numbers-and-dots notation" for
|
Internet addresses:
|
|
‘A.B.C.D’
|
This specifies all four bytes of the address individually and is
|
the commonly used representation.
|
|
‘A.B.C’
|
The last part of the address, C, is interpreted as a 2-byte
|
quantity. This is useful for specifying host addresses in a Class
|
B network with network address number ‘A.B’.
|
|
‘A.B’
|
The last part of the address, B, is interpreted as a 3-byte
|
quantity. This is useful for specifying host addresses in a Class
|
A network with network address number A.
|
|
‘A’
|
If only one part is given, this corresponds directly to the host
|
address number.
|
|
Within each part of the address, the usual C conventions for
|
specifying the radix apply. In other words, a leading ‘0x’ or ‘0X’
|
implies hexadecimal radix; a leading ‘0’ implies octal; and otherwise
|
decimal radix is assumed.
|
|
Classless Addresses
|
...................
|
|
IPv4 addresses (and IPv6 addresses also) are now considered classless;
|
the distinction between classes A, B and C can be ignored. Instead an
|
IPv4 host address consists of a 32-bit address and a 32-bit mask. The
|
mask contains set bits for the network part and cleared bits for the
|
host part. The network part is contiguous from the left, with the
|
remaining bits representing the host. As a consequence, the netmask can
|
simply be specified as the number of set bits. Classes A, B and C are
|
just special cases of this general rule. For example, class A addresses
|
have a netmask of ‘255.0.0.0’ or a prefix length of 8.
|
|
Classless IPv4 network addresses are written in numbers-and-dots
|
notation with the prefix length appended and a slash as separator. For
|
example the class A network 10 is written as ‘10.0.0.0/8’.
|
|
IPv6 Addresses
|
..............
|
|
IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host
|
address is usually written as eight 16-bit hexadecimal numbers that are
|
separated by colons. Two colons are used to abbreviate strings of
|
consecutive zeros. For example, the IPv6 loopback address
|
‘0:0:0:0:0:0:0:1’ can just be written as ‘::1’.
|
|
|
File: libc.info, Node: Host Address Data Type, Next: Host Address Functions, Prev: Abstract Host Addresses, Up: Host Addresses
|
|
16.6.2.2 Host Address Data Type
|
...............................
|
|
IPv4 Internet host addresses are represented in some contexts as
|
integers (type ‘uint32_t’). In other contexts, the integer is packaged
|
inside a structure of type ‘struct in_addr’. It would be better if the
|
usage were made consistent, but it is not hard to extract the integer
|
from the structure or put the integer into a structure.
|
|
You will find older code that uses ‘unsigned long int’ for IPv4
|
Internet host addresses instead of ‘uint32_t’ or ‘struct in_addr’.
|
Historically ‘unsigned long int’ was a 32-bit number but with 64-bit
|
machines this has changed. Using ‘unsigned long int’ might break the
|
code if it is used on machines where this type doesn’t have 32 bits.
|
‘uint32_t’ is specified by Unix98 and guaranteed to have 32 bits.
|
|
IPv6 Internet host addresses have 128 bits and are packaged inside a
|
structure of type ‘struct in6_addr’.
|
|
The following basic definitions for Internet addresses are declared
|
in the header file ‘netinet/in.h’:
|
|
-- Data Type: struct in_addr
|
|
This data type is used in certain contexts to contain an IPv4
|
Internet host address. It has just one field, named ‘s_addr’,
|
which records the host address number as an ‘uint32_t’.
|
|
-- Macro: uint32_t INADDR_LOOPBACK
|
|
You can use this constant to stand for “the address of this
|
machine,” instead of finding its actual address. It is the IPv4
|
Internet address ‘127.0.0.1’, which is usually called ‘localhost’.
|
This special constant saves you the trouble of looking up the
|
address of your own machine. Also, the system usually implements
|
‘INADDR_LOOPBACK’ specially, avoiding any network traffic for the
|
case of one machine talking to itself.
|
|
-- Macro: uint32_t INADDR_ANY
|
|
You can use this constant to stand for “any incoming address” when
|
binding to an address. *Note Setting Address::. This is the usual
|
address to give in the ‘sin_addr’ member of ‘struct sockaddr_in’
|
when you want to accept Internet connections.
|
|
-- Macro: uint32_t INADDR_BROADCAST
|
|
This constant is the address you use to send a broadcast message.
|
|
-- Macro: uint32_t INADDR_NONE
|
|
This constant is returned by some functions to indicate an error.
|
|
-- Data Type: struct in6_addr
|
|
This data type is used to store an IPv6 address. It stores 128
|
bits of data, which can be accessed (via a union) in a variety of
|
ways.
|
|
-- Constant: struct in6_addr in6addr_loopback
|
|
This constant is the IPv6 address ‘::1’, the loopback address. See
|
above for a description of what this means. The macro
|
‘IN6ADDR_LOOPBACK_INIT’ is provided to allow you to initialize your
|
own variables to this value.
|
|
-- Constant: struct in6_addr in6addr_any
|
|
This constant is the IPv6 address ‘::’, the unspecified address.
|
See above for a description of what this means. The macro
|
‘IN6ADDR_ANY_INIT’ is provided to allow you to initialize your own
|
variables to this value.
|
|
|
File: libc.info, Node: Host Address Functions, Next: Host Names, Prev: Host Address Data Type, Up: Host Addresses
|
|
16.6.2.3 Host Address Functions
|
...............................
|
|
These additional functions for manipulating Internet addresses are
|
declared in the header file ‘arpa/inet.h’. They represent Internet
|
addresses in network byte order, and network numbers and
|
local-address-within-network numbers in host byte order. *Note Byte
|
Order::, for an explanation of network and host byte order.
|
|
-- Function: int inet_aton (const char *NAME, struct in_addr *ADDR)
|
|
Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This function converts the IPv4 Internet host address NAME from the
|
standard numbers-and-dots notation into binary data and stores it
|
in the ‘struct in_addr’ that ADDR points to. ‘inet_aton’ returns
|
nonzero if the address is valid, zero if not.
|
|
-- Function: uint32_t inet_addr (const char *NAME)
|
|
Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This function converts the IPv4 Internet host address NAME from the
|
standard numbers-and-dots notation into binary data. If the input
|
is not valid, ‘inet_addr’ returns ‘INADDR_NONE’. This is an
|
obsolete interface to ‘inet_aton’, described immediately above. It
|
is obsolete because ‘INADDR_NONE’ is a valid address
|
(255.255.255.255), and ‘inet_aton’ provides a cleaner way to
|
indicate error return.
|
|
-- Function: uint32_t inet_network (const char *NAME)
|
|
Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This function extracts the network number from the address NAME,
|
given in the standard numbers-and-dots notation. The returned
|
address is in host order. If the input is not valid,
|
‘inet_network’ returns ‘-1’.
|
|
The function works only with traditional IPv4 class A, B and C
|
network types. It doesn’t work with classless addresses and
|
shouldn’t be used anymore.
|
|
-- Function: char * inet_ntoa (struct in_addr ADDR)
|
|
Preliminary: | MT-Safe locale | AS-Unsafe race | AC-Safe | *Note
|
POSIX Safety Concepts::.
|
|
This function converts the IPv4 Internet host address ADDR to a
|
string in the standard numbers-and-dots notation. The return value
|
is a pointer into a statically-allocated buffer. Subsequent calls
|
will overwrite the same buffer, so you should copy the string if
|
you need to save it.
|
|
In multi-threaded programs each thread has its own
|
statically-allocated buffer. But still subsequent calls of
|
‘inet_ntoa’ in the same thread will overwrite the result of the
|
last call.
|
|
Instead of ‘inet_ntoa’ the newer function ‘inet_ntop’ which is
|
described below should be used since it handles both IPv4 and IPv6
|
addresses.
|
|
-- Function: struct in_addr inet_makeaddr (uint32_t NET, uint32_t
|
LOCAL)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function makes an IPv4 Internet host address by combining the
|
network number NET with the local-address-within-network number
|
LOCAL.
|
|
-- Function: uint32_t inet_lnaof (struct in_addr ADDR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function returns the local-address-within-network part of the
|
Internet host address ADDR.
|
|
The function works only with traditional IPv4 class A, B and C
|
network types. It doesn’t work with classless addresses and
|
shouldn’t be used anymore.
|
|
-- Function: uint32_t inet_netof (struct in_addr ADDR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function returns the network number part of the Internet host
|
address ADDR.
|
|
The function works only with traditional IPv4 class A, B and C
|
network types. It doesn’t work with classless addresses and
|
shouldn’t be used anymore.
|
|
-- Function: int inet_pton (int AF, const char *CP, void *BUF)
|
|
Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This function converts an Internet address (either IPv4 or IPv6)
|
from presentation (textual) to network (binary) format. AF should
|
be either ‘AF_INET’ or ‘AF_INET6’, as appropriate for the type of
|
address being converted. CP is a pointer to the input string, and
|
BUF is a pointer to a buffer for the result. It is the caller’s
|
responsibility to make sure the buffer is large enough.
|
|
-- Function: const char * inet_ntop (int AF, const void *CP, char *BUF,
|
socklen_t LEN)
|
|
Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
|
Safety Concepts::.
|
|
This function converts an Internet address (either IPv4 or IPv6)
|
from network (binary) to presentation (textual) form. AF should be
|
either ‘AF_INET’ or ‘AF_INET6’, as appropriate. CP is a pointer to
|
the address to be converted. BUF should be a pointer to a buffer
|
to hold the result, and LEN is the length of this buffer. The
|
return value from the function will be this buffer address.
|
|
|
File: libc.info, Node: Host Names, Prev: Host Address Functions, Up: Host Addresses
|
|
16.6.2.4 Host Names
|
...................
|
|
Besides the standard numbers-and-dots notation for Internet addresses,
|
you can also refer to a host by a symbolic name. The advantage of a
|
symbolic name is that it is usually easier to remember. For example,
|
the machine with Internet address ‘158.121.106.19’ is also known as
|
‘alpha.gnu.org’; and other machines in the ‘gnu.org’ domain can refer to
|
it simply as ‘alpha’.
|
|
Internally, the system uses a database to keep track of the mapping
|
between host names and host numbers. This database is usually either
|
the file ‘/etc/hosts’ or an equivalent provided by a name server. The
|
functions and other symbols for accessing this database are declared in
|
‘netdb.h’. They are BSD features, defined unconditionally if you
|
include ‘netdb.h’.
|
|
-- Data Type: struct hostent
|
|
This data type is used to represent an entry in the hosts database.
|
It has the following members:
|
|
‘char *h_name’
|
This is the “official” name of the host.
|
|
‘char **h_aliases’
|
These are alternative names for the host, represented as a
|
null-terminated vector of strings.
|
|
‘int h_addrtype’
|
This is the host address type; in practice, its value is
|
always either ‘AF_INET’ or ‘AF_INET6’, with the latter being
|
used for IPv6 hosts. In principle other kinds of addresses
|
could be represented in the database as well as Internet
|
addresses; if this were done, you might find a value in this
|
field other than ‘AF_INET’ or ‘AF_INET6’. *Note Socket
|
Addresses::.
|
|
‘int h_length’
|
This is the length, in bytes, of each address.
|
|
‘char **h_addr_list’
|
This is the vector of addresses for the host. (Recall that
|
the host might be connected to multiple networks and have
|
different addresses on each one.) The vector is terminated by
|
a null pointer.
|
|
‘char *h_addr’
|
This is a synonym for ‘h_addr_list[0]’; in other words, it is
|
the first host address.
|
|
As far as the host database is concerned, each address is just a
|
block of memory ‘h_length’ bytes long. But in other contexts there is
|
an implicit assumption that you can convert IPv4 addresses to a ‘struct
|
in_addr’ or an ‘uint32_t’. Host addresses in a ‘struct hostent’
|
structure are always given in network byte order; see *note Byte
|
Order::.
|
|
You can use ‘gethostbyname’, ‘gethostbyname2’ or ‘gethostbyaddr’ to
|
search the hosts database for information about a particular host. The
|
information is returned in a statically-allocated structure; you must
|
copy the information if you need to save it across calls. You can also
|
use ‘getaddrinfo’ and ‘getnameinfo’ to obtain this information.
|
|
-- Function: struct hostent * gethostbyname (const char *NAME)
|
|
Preliminary: | MT-Unsafe race:hostbyname env locale | AS-Unsafe
|
dlopen plugin corrupt heap lock | AC-Unsafe lock corrupt mem fd |
|
*Note POSIX Safety Concepts::.
|
|
The ‘gethostbyname’ function returns information about the host
|
named NAME. If the lookup fails, it returns a null pointer.
|
|
-- Function: struct hostent * gethostbyname2 (const char *NAME, int AF)
|
|
Preliminary: | MT-Unsafe race:hostbyname2 env locale | AS-Unsafe
|
dlopen plugin corrupt heap lock | AC-Unsafe lock corrupt mem fd |
|
*Note POSIX Safety Concepts::.
|
|
The ‘gethostbyname2’ function is like ‘gethostbyname’, but allows
|
the caller to specify the desired address family (e.g. ‘AF_INET’ or
|
‘AF_INET6’) of the result.
|
|
-- Function: struct hostent * gethostbyaddr (const void *ADDR,
|
socklen_t LENGTH, int FORMAT)
|
|
Preliminary: | MT-Unsafe race:hostbyaddr env locale | AS-Unsafe
|
dlopen plugin corrupt heap lock | AC-Unsafe lock corrupt mem fd |
|
*Note POSIX Safety Concepts::.
|
|
The ‘gethostbyaddr’ function returns information about the host
|
with Internet address ADDR. The parameter ADDR is not really a
|
pointer to char - it can be a pointer to an IPv4 or an IPv6
|
address. The LENGTH argument is the size (in bytes) of the address
|
at ADDR. FORMAT specifies the address format; for an IPv4 Internet
|
address, specify a value of ‘AF_INET’; for an IPv6 Internet
|
address, use ‘AF_INET6’.
|
|
If the lookup fails, ‘gethostbyaddr’ returns a null pointer.
|
|
If the name lookup by ‘gethostbyname’ or ‘gethostbyaddr’ fails, you
|
can find out the reason by looking at the value of the variable
|
‘h_errno’. (It would be cleaner design for these functions to set
|
‘errno’, but use of ‘h_errno’ is compatible with other systems.)
|
|
Here are the error codes that you may find in ‘h_errno’:
|
|
‘HOST_NOT_FOUND’
|
|
No such host is known in the database.
|
|
‘TRY_AGAIN’
|
|
This condition happens when the name server could not be contacted.
|
If you try again later, you may succeed then.
|
|
‘NO_RECOVERY’
|
|
A non-recoverable error occurred.
|
|
‘NO_ADDRESS’
|
|
The host database contains an entry for the name, but it doesn’t
|
have an associated Internet address.
|
|
The lookup functions above all have one thing in common: they are not
|
reentrant and therefore unusable in multi-threaded applications.
|
Therefore provides the GNU C Library a new set of functions which can be
|
used in this context.
|
|
-- Function: int gethostbyname_r (const char *restrict NAME, struct
|
hostent *restrict RESULT_BUF, char *restrict BUF, size_t
|
BUFLEN, struct hostent **restrict RESULT, int *restrict
|
H_ERRNOP)
|
|
Preliminary: | MT-Safe env locale | AS-Unsafe dlopen plugin corrupt
|
heap lock | AC-Unsafe lock corrupt mem fd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘gethostbyname_r’ function returns information about the host
|
named NAME. The caller must pass a pointer to an object of type
|
‘struct hostent’ in the RESULT_BUF parameter. In addition the
|
function may need extra buffer space and the caller must pass a
|
pointer and the size of the buffer in the BUF and BUFLEN
|
parameters.
|
|
A pointer to the buffer, in which the result is stored, is
|
available in ‘*RESULT’ after the function call successfully
|
returned. The buffer passed as the BUF parameter can be freed only
|
once the caller has finished with the result hostent struct, or has
|
copied it including all the other memory that it points to. If an
|
error occurs or if no entry is found, the pointer ‘*RESULT’ is a
|
null pointer. Success is signalled by a zero return value. If the
|
function failed the return value is an error number. In addition
|
to the errors defined for ‘gethostbyname’ it can also be ‘ERANGE’.
|
In this case the call should be repeated with a larger buffer.
|
Additional error information is not stored in the global variable
|
‘h_errno’ but instead in the object pointed to by H_ERRNOP.
|
|
Here’s a small example:
|
struct hostent *
|
gethostname (char *host)
|
{
|
struct hostent *hostbuf, *hp;
|
size_t hstbuflen;
|
char *tmphstbuf;
|
int res;
|
int herr;
|
|
hostbuf = malloc (sizeof (struct hostent));
|
hstbuflen = 1024;
|
tmphstbuf = malloc (hstbuflen);
|
|
while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen,
|
&hp, &herr)) == ERANGE)
|
{
|
/* Enlarge the buffer. */
|
hstbuflen *= 2;
|
tmphstbuf = realloc (tmphstbuf, hstbuflen);
|
}
|
|
free (tmphstbuf);
|
/* Check for errors. */
|
if (res || hp == NULL)
|
return NULL;
|
return hp;
|
}
|
|
-- Function: int gethostbyname2_r (const char *NAME, int AF, struct
|
hostent *restrict RESULT_BUF, char *restrict BUF, size_t
|
BUFLEN, struct hostent **restrict RESULT, int *restrict
|
H_ERRNOP)
|
|
Preliminary: | MT-Safe env locale | AS-Unsafe dlopen plugin corrupt
|
heap lock | AC-Unsafe lock corrupt mem fd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘gethostbyname2_r’ function is like ‘gethostbyname_r’, but
|
allows the caller to specify the desired address family (e.g.
|
‘AF_INET’ or ‘AF_INET6’) for the result.
|
|
-- Function: int gethostbyaddr_r (const void *ADDR, socklen_t LENGTH,
|
int FORMAT, struct hostent *restrict RESULT_BUF, char
|
*restrict BUF, size_t BUFLEN, struct hostent **restrict
|
RESULT, int *restrict H_ERRNOP)
|
|
Preliminary: | MT-Safe env locale | AS-Unsafe dlopen plugin corrupt
|
heap lock | AC-Unsafe lock corrupt mem fd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘gethostbyaddr_r’ function returns information about the host
|
with Internet address ADDR. The parameter ADDR is not really a
|
pointer to char - it can be a pointer to an IPv4 or an IPv6
|
address. The LENGTH argument is the size (in bytes) of the address
|
at ADDR. FORMAT specifies the address format; for an IPv4 Internet
|
address, specify a value of ‘AF_INET’; for an IPv6 Internet
|
address, use ‘AF_INET6’.
|
|
Similar to the ‘gethostbyname_r’ function, the caller must provide
|
buffers for the result and memory used internally. In case of
|
success the function returns zero. Otherwise the value is an error
|
number where ‘ERANGE’ has the special meaning that the
|
caller-provided buffer is too small.
|
|
You can also scan the entire hosts database one entry at a time using
|
‘sethostent’, ‘gethostent’ and ‘endhostent’. Be careful when using
|
these functions because they are not reentrant.
|
|
-- Function: void sethostent (int STAYOPEN)
|
|
Preliminary: | MT-Unsafe race:hostent env locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function opens the hosts database to begin scanning it. You
|
can then call ‘gethostent’ to read the entries.
|
|
If the STAYOPEN argument is nonzero, this sets a flag so that
|
subsequent calls to ‘gethostbyname’ or ‘gethostbyaddr’ will not
|
close the database (as they usually would). This makes for more
|
efficiency if you call those functions several times, by avoiding
|
reopening the database for each call.
|
|
-- Function: struct hostent * gethostent (void)
|
|
Preliminary: | MT-Unsafe race:hostent race:hostentbuf env locale |
|
AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
|
*Note POSIX Safety Concepts::.
|
|
This function returns the next entry in the hosts database. It
|
returns a null pointer if there are no more entries.
|
|
-- Function: void endhostent (void)
|
|
Preliminary: | MT-Unsafe race:hostent env locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function closes the hosts database.
|
|
|
File: libc.info, Node: Ports, Next: Services Database, Prev: Host Addresses, Up: Internet Namespace
|
|
16.6.3 Internet Ports
|
---------------------
|
|
A socket address in the Internet namespace consists of a machine’s
|
Internet address plus a "port number" which distinguishes the sockets on
|
a given machine (for a given protocol). Port numbers range from 0 to
|
65,535.
|
|
Port numbers less than ‘IPPORT_RESERVED’ are reserved for standard
|
servers, such as ‘finger’ and ‘telnet’. There is a database that keeps
|
track of these, and you can use the ‘getservbyname’ function to map a
|
service name onto a port number; see *note Services Database::.
|
|
If you write a server that is not one of the standard ones defined in
|
the database, you must choose a port number for it. Use a number
|
greater than ‘IPPORT_USERRESERVED’; such numbers are reserved for
|
servers and won’t ever be generated automatically by the system.
|
Avoiding conflicts with servers being run by other users is up to you.
|
|
When you use a socket without specifying its address, the system
|
generates a port number for it. This number is between
|
‘IPPORT_RESERVED’ and ‘IPPORT_USERRESERVED’.
|
|
On the Internet, it is actually legitimate to have two different
|
sockets with the same port number, as long as they never both try to
|
communicate with the same socket address (host address plus port
|
number). You shouldn’t duplicate a port number except in special
|
circumstances where a higher-level protocol requires it. Normally, the
|
system won’t let you do it; ‘bind’ normally insists on distinct port
|
numbers. To reuse a port number, you must set the socket option
|
‘SO_REUSEADDR’. *Note Socket-Level Options::.
|
|
These macros are defined in the header file ‘netinet/in.h’.
|
|
-- Macro: int IPPORT_RESERVED
|
|
Port numbers less than ‘IPPORT_RESERVED’ are reserved for superuser
|
use.
|
|
-- Macro: int IPPORT_USERRESERVED
|
|
Port numbers greater than or equal to ‘IPPORT_USERRESERVED’ are
|
reserved for explicit use; they will never be allocated
|
automatically.
|
|
|
File: libc.info, Node: Services Database, Next: Byte Order, Prev: Ports, Up: Internet Namespace
|
|
16.6.4 The Services Database
|
----------------------------
|
|
The database that keeps track of “well-known” services is usually either
|
the file ‘/etc/services’ or an equivalent from a name server. You can
|
use these utilities, declared in ‘netdb.h’, to access the services
|
database.
|
|
-- Data Type: struct servent
|
|
This data type holds information about entries from the services
|
database. It has the following members:
|
|
‘char *s_name’
|
This is the “official” name of the service.
|
|
‘char **s_aliases’
|
These are alternate names for the service, represented as an
|
array of strings. A null pointer terminates the array.
|
|
‘int s_port’
|
This is the port number for the service. Port numbers are
|
given in network byte order; see *note Byte Order::.
|
|
‘char *s_proto’
|
This is the name of the protocol to use with this service.
|
*Note Protocols Database::.
|
|
To get information about a particular service, use the
|
‘getservbyname’ or ‘getservbyport’ functions. The information is
|
returned in a statically-allocated structure; you must copy the
|
information if you need to save it across calls.
|
|
-- Function: struct servent * getservbyname (const char *NAME, const
|
char *PROTO)
|
|
Preliminary: | MT-Unsafe race:servbyname locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
The ‘getservbyname’ function returns information about the service
|
named NAME using protocol PROTO. If it can’t find such a service,
|
it returns a null pointer.
|
|
This function is useful for servers as well as for clients; servers
|
use it to determine which port they should listen on (*note
|
Listening::).
|
|
-- Function: struct servent * getservbyport (int PORT, const char
|
*PROTO)
|
|
Preliminary: | MT-Unsafe race:servbyport locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
The ‘getservbyport’ function returns information about the service
|
at port PORT using protocol PROTO. If it can’t find such a
|
service, it returns a null pointer.
|
|
You can also scan the services database using ‘setservent’, ‘getservent’
|
and ‘endservent’. Be careful when using these functions because they
|
are not reentrant.
|
|
-- Function: void setservent (int STAYOPEN)
|
|
Preliminary: | MT-Unsafe race:servent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function opens the services database to begin scanning it.
|
|
If the STAYOPEN argument is nonzero, this sets a flag so that
|
subsequent calls to ‘getservbyname’ or ‘getservbyport’ will not
|
close the database (as they usually would). This makes for more
|
efficiency if you call those functions several times, by avoiding
|
reopening the database for each call.
|
|
-- Function: struct servent * getservent (void)
|
|
Preliminary: | MT-Unsafe race:servent race:serventbuf locale |
|
AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
|
*Note POSIX Safety Concepts::.
|
|
This function returns the next entry in the services database. If
|
there are no more entries, it returns a null pointer.
|
|
-- Function: void endservent (void)
|
|
Preliminary: | MT-Unsafe race:servent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function closes the services database.
|
|
|
File: libc.info, Node: Byte Order, Next: Protocols Database, Prev: Services Database, Up: Internet Namespace
|
|
16.6.5 Byte Order Conversion
|
----------------------------
|
|
Different kinds of computers use different conventions for the ordering
|
of bytes within a word. Some computers put the most significant byte
|
within a word first (this is called “big-endian” order), and others put
|
it last (“little-endian” order).
|
|
So that machines with different byte order conventions can
|
communicate, the Internet protocols specify a canonical byte order
|
convention for data transmitted over the network. This is known as
|
"network byte order".
|
|
When establishing an Internet socket connection, you must make sure
|
that the data in the ‘sin_port’ and ‘sin_addr’ members of the
|
‘sockaddr_in’ structure are represented in network byte order. If you
|
are encoding integer data in the messages sent through the socket, you
|
should convert this to network byte order too. If you don’t do this,
|
your program may fail when running on or talking to other kinds of
|
machines.
|
|
If you use ‘getservbyname’ and ‘gethostbyname’ or ‘inet_addr’ to get
|
the port number and host address, the values are already in network byte
|
order, and you can copy them directly into the ‘sockaddr_in’ structure.
|
|
Otherwise, you have to convert the values explicitly. Use ‘htons’
|
and ‘ntohs’ to convert values for the ‘sin_port’ member. Use ‘htonl’
|
and ‘ntohl’ to convert IPv4 addresses for the ‘sin_addr’ member.
|
(Remember, ‘struct in_addr’ is equivalent to ‘uint32_t’.) These
|
functions are declared in ‘netinet/in.h’.
|
|
-- Function: uint16_t htons (uint16_t HOSTSHORT)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function converts the ‘uint16_t’ integer HOSTSHORT from host
|
byte order to network byte order.
|
|
-- Function: uint16_t ntohs (uint16_t NETSHORT)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function converts the ‘uint16_t’ integer NETSHORT from network
|
byte order to host byte order.
|
|
-- Function: uint32_t htonl (uint32_t HOSTLONG)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function converts the ‘uint32_t’ integer HOSTLONG from host
|
byte order to network byte order.
|
|
This is used for IPv4 Internet addresses.
|
|
-- Function: uint32_t ntohl (uint32_t NETLONG)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function converts the ‘uint32_t’ integer NETLONG from network
|
byte order to host byte order.
|
|
This is used for IPv4 Internet addresses.
|
|
|
File: libc.info, Node: Protocols Database, Next: Inet Example, Prev: Byte Order, Up: Internet Namespace
|
|
16.6.6 Protocols Database
|
-------------------------
|
|
The communications protocol used with a socket controls low-level
|
details of how data are exchanged. For example, the protocol implements
|
things like checksums to detect errors in transmissions, and routing
|
instructions for messages. Normal user programs have little reason to
|
mess with these details directly.
|
|
The default communications protocol for the Internet namespace
|
depends on the communication style. For stream communication, the
|
default is TCP (“transmission control protocol”). For datagram
|
communication, the default is UDP (“user datagram protocol”). For
|
reliable datagram communication, the default is RDP (“reliable datagram
|
protocol”). You should nearly always use the default.
|
|
Internet protocols are generally specified by a name instead of a
|
number. The network protocols that a host knows about are stored in a
|
database. This is usually either derived from the file
|
‘/etc/protocols’, or it may be an equivalent provided by a name server.
|
You look up the protocol number associated with a named protocol in the
|
database using the ‘getprotobyname’ function.
|
|
Here are detailed descriptions of the utilities for accessing the
|
protocols database. These are declared in ‘netdb.h’.
|
|
-- Data Type: struct protoent
|
|
This data type is used to represent entries in the network
|
protocols database. It has the following members:
|
|
‘char *p_name’
|
This is the official name of the protocol.
|
|
‘char **p_aliases’
|
These are alternate names for the protocol, specified as an
|
array of strings. The last element of the array is a null
|
pointer.
|
|
‘int p_proto’
|
This is the protocol number (in host byte order); use this
|
member as the PROTOCOL argument to ‘socket’.
|
|
You can use ‘getprotobyname’ and ‘getprotobynumber’ to search the
|
protocols database for a specific protocol. The information is returned
|
in a statically-allocated structure; you must copy the information if
|
you need to save it across calls.
|
|
-- Function: struct protoent * getprotobyname (const char *NAME)
|
|
Preliminary: | MT-Unsafe race:protobyname locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
The ‘getprotobyname’ function returns information about the network
|
protocol named NAME. If there is no such protocol, it returns a
|
null pointer.
|
|
-- Function: struct protoent * getprotobynumber (int PROTOCOL)
|
|
Preliminary: | MT-Unsafe race:protobynumber locale | AS-Unsafe
|
dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note
|
POSIX Safety Concepts::.
|
|
The ‘getprotobynumber’ function returns information about the
|
network protocol with number PROTOCOL. If there is no such
|
protocol, it returns a null pointer.
|
|
You can also scan the whole protocols database one protocol at a time
|
by using ‘setprotoent’, ‘getprotoent’ and ‘endprotoent’. Be careful
|
when using these functions because they are not reentrant.
|
|
-- Function: void setprotoent (int STAYOPEN)
|
|
Preliminary: | MT-Unsafe race:protoent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function opens the protocols database to begin scanning it.
|
|
If the STAYOPEN argument is nonzero, this sets a flag so that
|
subsequent calls to ‘getprotobyname’ or ‘getprotobynumber’ will not
|
close the database (as they usually would). This makes for more
|
efficiency if you call those functions several times, by avoiding
|
reopening the database for each call.
|
|
-- Function: struct protoent * getprotoent (void)
|
|
Preliminary: | MT-Unsafe race:protoent race:protoentbuf locale |
|
AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
|
*Note POSIX Safety Concepts::.
|
|
This function returns the next entry in the protocols database. It
|
returns a null pointer if there are no more entries.
|
|
-- Function: void endprotoent (void)
|
|
Preliminary: | MT-Unsafe race:protoent locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function closes the protocols database.
|
|
|
File: libc.info, Node: Inet Example, Prev: Protocols Database, Up: Internet Namespace
|
|
16.6.7 Internet Socket Example
|
------------------------------
|
|
Here is an example showing how to create and name a socket in the
|
Internet namespace. The newly created socket exists on the machine that
|
the program is running on. Rather than finding and using the machine’s
|
Internet address, this example specifies ‘INADDR_ANY’ as the host
|
address; the system replaces that with the machine’s actual address.
|
|
|
#include <stdio.h>
|
#include <stdlib.h>
|
#include <sys/socket.h>
|
#include <netinet/in.h>
|
|
int
|
make_socket (uint16_t port)
|
{
|
int sock;
|
struct sockaddr_in name;
|
|
/* Create the socket. */
|
sock = socket (PF_INET, SOCK_STREAM, 0);
|
if (sock < 0)
|
{
|
perror ("socket");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Give the socket a name. */
|
name.sin_family = AF_INET;
|
name.sin_port = htons (port);
|
name.sin_addr.s_addr = htonl (INADDR_ANY);
|
if (bind (sock, (struct sockaddr *) &name, sizeof (name)) < 0)
|
{
|
perror ("bind");
|
exit (EXIT_FAILURE);
|
}
|
|
return sock;
|
}
|
|
Here is another example, showing how you can fill in a ‘sockaddr_in’
|
structure, given a host name string and a port number:
|
|
|
#include <stdio.h>
|
#include <stdlib.h>
|
#include <sys/socket.h>
|
#include <netinet/in.h>
|
#include <netdb.h>
|
|
void
|
init_sockaddr (struct sockaddr_in *name,
|
const char *hostname,
|
uint16_t port)
|
{
|
struct hostent *hostinfo;
|
|
name->sin_family = AF_INET;
|
name->sin_port = htons (port);
|
hostinfo = gethostbyname (hostname);
|
if (hostinfo == NULL)
|
{
|
fprintf (stderr, "Unknown host %s.\n", hostname);
|
exit (EXIT_FAILURE);
|
}
|
name->sin_addr = *(struct in_addr *) hostinfo->h_addr;
|
}
|
|
|
File: libc.info, Node: Misc Namespaces, Next: Open/Close Sockets, Prev: Internet Namespace, Up: Sockets
|
|
16.7 Other Namespaces
|
=====================
|
|
Certain other namespaces and associated protocol families are supported
|
but not documented yet because they are not often used. ‘PF_NS’ refers
|
to the Xerox Network Software protocols. ‘PF_ISO’ stands for Open
|
Systems Interconnect. ‘PF_CCITT’ refers to protocols from CCITT.
|
‘socket.h’ defines these symbols and others naming protocols not
|
actually implemented.
|
|
‘PF_IMPLINK’ is used for communicating between hosts and Internet
|
Message Processors. For information on this and ‘PF_ROUTE’, an
|
occasionally-used local area routing protocol, see the GNU Hurd Manual
|
(to appear in the future).
|
|
|
File: libc.info, Node: Open/Close Sockets, Next: Connections, Prev: Misc Namespaces, Up: Sockets
|
|
16.8 Opening and Closing Sockets
|
================================
|
|
This section describes the actual library functions for opening and
|
closing sockets. The same functions work for all namespaces and
|
connection styles.
|
|
* Menu:
|
|
* Creating a Socket:: How to open a socket.
|
* Closing a Socket:: How to close a socket.
|
* Socket Pairs:: These are created like pipes.
|
|
|
File: libc.info, Node: Creating a Socket, Next: Closing a Socket, Up: Open/Close Sockets
|
|
16.8.1 Creating a Socket
|
------------------------
|
|
The primitive for creating a socket is the ‘socket’ function, declared
|
in ‘sys/socket.h’.
|
|
-- Function: int socket (int NAMESPACE, int STYLE, int PROTOCOL)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
This function creates a socket and specifies communication style
|
STYLE, which should be one of the socket styles listed in *note
|
Communication Styles::. The NAMESPACE argument specifies the
|
namespace; it must be ‘PF_LOCAL’ (*note Local Namespace::) or
|
‘PF_INET’ (*note Internet Namespace::). PROTOCOL designates the
|
specific protocol (*note Socket Concepts::); zero is usually right
|
for PROTOCOL.
|
|
The return value from ‘socket’ is the file descriptor for the new
|
socket, or ‘-1’ in case of error. The following ‘errno’ error
|
conditions are defined for this function:
|
|
‘EPROTONOSUPPORT’
|
The PROTOCOL or STYLE is not supported by the NAMESPACE
|
specified.
|
|
‘EMFILE’
|
The process already has too many file descriptors open.
|
|
‘ENFILE’
|
The system already has too many file descriptors open.
|
|
‘EACCES’
|
The process does not have the privilege to create a socket of
|
the specified STYLE or PROTOCOL.
|
|
‘ENOBUFS’
|
The system ran out of internal buffer space.
|
|
The file descriptor returned by the ‘socket’ function supports both
|
read and write operations. However, like pipes, sockets do not
|
support file positioning operations.
|
|
For examples of how to call the ‘socket’ function, see *note Local
|
Socket Example::, or *note Inet Example::.
|
|
|
File: libc.info, Node: Closing a Socket, Next: Socket Pairs, Prev: Creating a Socket, Up: Open/Close Sockets
|
|
16.8.2 Closing a Socket
|
-----------------------
|
|
When you have finished using a socket, you can simply close its file
|
descriptor with ‘close’; see *note Opening and Closing Files::. If
|
there is still data waiting to be transmitted over the connection,
|
normally ‘close’ tries to complete this transmission. You can control
|
this behavior using the ‘SO_LINGER’ socket option to specify a timeout
|
period; see *note Socket Options::.
|
|
You can also shut down only reception or transmission on a connection
|
by calling ‘shutdown’, which is declared in ‘sys/socket.h’.
|
|
-- Function: int shutdown (int SOCKET, int HOW)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘shutdown’ function shuts down the connection of socket SOCKET.
|
The argument HOW specifies what action to perform:
|
|
‘0’
|
Stop receiving data for this socket. If further data arrives,
|
reject it.
|
|
‘1’
|
Stop trying to transmit data from this socket. Discard any
|
data waiting to be sent. Stop looking for acknowledgement of
|
data already sent; don’t retransmit it if it is lost.
|
|
‘2’
|
Stop both reception and transmission.
|
|
The return value is ‘0’ on success and ‘-1’ on failure. The
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EBADF’
|
SOCKET is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
SOCKET is not a socket.
|
|
‘ENOTCONN’
|
SOCKET is not connected.
|
|
|
File: libc.info, Node: Socket Pairs, Prev: Closing a Socket, Up: Open/Close Sockets
|
|
16.8.3 Socket Pairs
|
-------------------
|
|
A "socket pair" consists of a pair of connected (but unnamed) sockets.
|
It is very similar to a pipe and is used in much the same way. Socket
|
pairs are created with the ‘socketpair’ function, declared in
|
‘sys/socket.h’. A socket pair is much like a pipe; the main difference
|
is that the socket pair is bidirectional, whereas the pipe has one
|
input-only end and one output-only end (*note Pipes and FIFOs::).
|
|
-- Function: int socketpair (int NAMESPACE, int STYLE, int PROTOCOL,
|
int FILEDES[2])
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
This function creates a socket pair, returning the file descriptors
|
in ‘FILEDES[0]’ and ‘FILEDES[1]’. The socket pair is a full-duplex
|
communications channel, so that both reading and writing may be
|
performed at either end.
|
|
The NAMESPACE, STYLE and PROTOCOL arguments are interpreted as for
|
the ‘socket’ function. STYLE should be one of the communication
|
styles listed in *note Communication Styles::. The NAMESPACE
|
argument specifies the namespace, which must be ‘AF_LOCAL’ (*note
|
Local Namespace::); PROTOCOL specifies the communications protocol,
|
but zero is the only meaningful value.
|
|
If STYLE specifies a connectionless communication style, then the
|
two sockets you get are not _connected_, strictly speaking, but
|
each of them knows the other as the default destination address, so
|
they can send packets to each other.
|
|
The ‘socketpair’ function returns ‘0’ on success and ‘-1’ on
|
failure. The following ‘errno’ error conditions are defined for
|
this function:
|
|
‘EMFILE’
|
The process has too many file descriptors open.
|
|
‘EAFNOSUPPORT’
|
The specified namespace is not supported.
|
|
‘EPROTONOSUPPORT’
|
The specified protocol is not supported.
|
|
‘EOPNOTSUPP’
|
The specified protocol does not support the creation of socket
|
pairs.
|
|
|
File: libc.info, Node: Connections, Next: Datagrams, Prev: Open/Close Sockets, Up: Sockets
|
|
16.9 Using Sockets with Connections
|
===================================
|
|
The most common communication styles involve making a connection to a
|
particular other socket, and then exchanging data with that socket over
|
and over. Making a connection is asymmetric; one side (the "client")
|
acts to request a connection, while the other side (the "server") makes
|
a socket and waits for the connection request.
|
|
* Menu:
|
|
* Connecting:: What the client program must do.
|
* Listening:: How a server program waits for requests.
|
* Accepting Connections:: What the server does when it gets a request.
|
* Who is Connected:: Getting the address of the
|
other side of a connection.
|
* Transferring Data:: How to send and receive data.
|
* Byte Stream Example:: An example program: a client for communicating
|
over a byte stream socket in the Internet namespace.
|
* Server Example:: A corresponding server program.
|
* Out-of-Band Data:: This is an advanced feature.
|
|
|
File: libc.info, Node: Connecting, Next: Listening, Up: Connections
|
|
16.9.1 Making a Connection
|
--------------------------
|
|
In making a connection, the client makes a connection while the server
|
waits for and accepts the connection. Here we discuss what the client
|
program must do with the ‘connect’ function, which is declared in
|
‘sys/socket.h’.
|
|
-- Function: int connect (int SOCKET, struct sockaddr *ADDR, socklen_t
|
LENGTH)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘connect’ function initiates a connection from the socket with
|
file descriptor SOCKET to the socket whose address is specified by
|
the ADDR and LENGTH arguments. (This socket is typically on
|
another machine, and it must be already set up as a server.) *Note
|
Socket Addresses::, for information about how these arguments are
|
interpreted.
|
|
Normally, ‘connect’ waits until the server responds to the request
|
before it returns. You can set nonblocking mode on the socket
|
SOCKET to make ‘connect’ return immediately without waiting for the
|
response. *Note File Status Flags::, for information about
|
nonblocking mode.
|
|
The normal return value from ‘connect’ is ‘0’. If an error occurs,
|
‘connect’ returns ‘-1’. The following ‘errno’ error conditions are
|
defined for this function:
|
|
‘EBADF’
|
The socket SOCKET is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
File descriptor SOCKET is not a socket.
|
|
‘EADDRNOTAVAIL’
|
The specified address is not available on the remote machine.
|
|
‘EAFNOSUPPORT’
|
The namespace of the ADDR is not supported by this socket.
|
|
‘EISCONN’
|
The socket SOCKET is already connected.
|
|
‘ETIMEDOUT’
|
The attempt to establish the connection timed out.
|
|
‘ECONNREFUSED’
|
The server has actively refused to establish the connection.
|
|
‘ENETUNREACH’
|
The network of the given ADDR isn’t reachable from this host.
|
|
‘EADDRINUSE’
|
The socket address of the given ADDR is already in use.
|
|
‘EINPROGRESS’
|
The socket SOCKET is non-blocking and the connection could not
|
be established immediately. You can determine when the
|
connection is completely established with ‘select’; *note
|
Waiting for I/O::. Another ‘connect’ call on the same socket,
|
before the connection is completely established, will fail
|
with ‘EALREADY’.
|
|
‘EALREADY’
|
The socket SOCKET is non-blocking and already has a pending
|
connection in progress (see ‘EINPROGRESS’ above).
|
|
This function is defined as a cancellation point in multi-threaded
|
programs, so one has to be prepared for this and make sure that
|
allocated resources (like memory, file descriptors, semaphores or
|
whatever) are freed even if the thread is canceled.
|
|
|
File: libc.info, Node: Listening, Next: Accepting Connections, Prev: Connecting, Up: Connections
|
|
16.9.2 Listening for Connections
|
--------------------------------
|
|
Now let us consider what the server process must do to accept
|
connections on a socket. First it must use the ‘listen’ function to
|
enable connection requests on the socket, and then accept each incoming
|
connection with a call to ‘accept’ (*note Accepting Connections::).
|
Once connection requests are enabled on a server socket, the ‘select’
|
function reports when the socket has a connection ready to be accepted
|
(*note Waiting for I/O::).
|
|
The ‘listen’ function is not allowed for sockets using connectionless
|
communication styles.
|
|
You can write a network server that does not even start running until
|
a connection to it is requested. *Note Inetd Servers::.
|
|
In the Internet namespace, there are no special protection mechanisms
|
for controlling access to a port; any process on any machine can make a
|
connection to your server. If you want to restrict access to your
|
server, make it examine the addresses associated with connection
|
requests or implement some other handshaking or identification protocol.
|
|
In the local namespace, the ordinary file protection bits control who
|
has access to connect to the socket.
|
|
-- Function: int listen (int SOCKET, int N)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
The ‘listen’ function enables the socket SOCKET to accept
|
connections, thus making it a server socket.
|
|
The argument N specifies the length of the queue for pending
|
connections. When the queue fills, new clients attempting to
|
connect fail with ‘ECONNREFUSED’ until the server calls ‘accept’ to
|
accept a connection from the queue.
|
|
The ‘listen’ function returns ‘0’ on success and ‘-1’ on failure.
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EBADF’
|
The argument SOCKET is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
The argument SOCKET is not a socket.
|
|
‘EOPNOTSUPP’
|
The socket SOCKET does not support this operation.
|
|
|
File: libc.info, Node: Accepting Connections, Next: Who is Connected, Prev: Listening, Up: Connections
|
|
16.9.3 Accepting Connections
|
----------------------------
|
|
When a server receives a connection request, it can complete the
|
connection by accepting the request. Use the function ‘accept’ to do
|
this.
|
|
A socket that has been established as a server can accept connection
|
requests from multiple clients. The server’s original socket _does not
|
become part of the connection_; instead, ‘accept’ makes a new socket
|
which participates in the connection. ‘accept’ returns the descriptor
|
for this socket. The server’s original socket remains available for
|
listening for further connection requests.
|
|
The number of pending connection requests on a server socket is
|
finite. If connection requests arrive from clients faster than the
|
server can act upon them, the queue can fill up and additional requests
|
are refused with an ‘ECONNREFUSED’ error. You can specify the maximum
|
length of this queue as an argument to the ‘listen’ function, although
|
the system may also impose its own internal limit on the length of this
|
queue.
|
|
-- Function: int accept (int SOCKET, struct sockaddr *ADDR, socklen_t
|
*LENGTH_PTR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
|
Concepts::.
|
|
This function is used to accept a connection request on the server
|
socket SOCKET.
|
|
The ‘accept’ function waits if there are no connections pending,
|
unless the socket SOCKET has nonblocking mode set. (You can use
|
‘select’ to wait for a pending connection, with a nonblocking
|
socket.) *Note File Status Flags::, for information about
|
nonblocking mode.
|
|
The ADDR and LENGTH-PTR arguments are used to return information
|
about the name of the client socket that initiated the connection.
|
*Note Socket Addresses::, for information about the format of the
|
information.
|
|
Accepting a connection does not make SOCKET part of the connection.
|
Instead, it creates a new socket which becomes connected. The
|
normal return value of ‘accept’ is the file descriptor for the new
|
socket.
|
|
After ‘accept’, the original socket SOCKET remains open and
|
unconnected, and continues listening until you close it. You can
|
accept further connections with SOCKET by calling ‘accept’ again.
|
|
If an error occurs, ‘accept’ returns ‘-1’. The following ‘errno’
|
error conditions are defined for this function:
|
|
‘EBADF’
|
The SOCKET argument is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
The descriptor SOCKET argument is not a socket.
|
|
‘EOPNOTSUPP’
|
The descriptor SOCKET does not support this operation.
|
|
‘EWOULDBLOCK’
|
SOCKET has nonblocking mode set, and there are no pending
|
connections immediately available.
|
|
This function is defined as a cancellation point in multi-threaded
|
programs, so one has to be prepared for this and make sure that
|
allocated resources (like memory, file descriptors, semaphores or
|
whatever) are freed even if the thread is canceled.
|
|
The ‘accept’ function is not allowed for sockets using connectionless
|
communication styles.
|
|
|
File: libc.info, Node: Who is Connected, Next: Transferring Data, Prev: Accepting Connections, Up: Connections
|
|
16.9.4 Who is Connected to Me?
|
------------------------------
|
|
-- Function: int getpeername (int SOCKET, struct sockaddr *ADDR,
|
socklen_t *LENGTH-PTR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getpeername’ function returns the address of the socket that
|
SOCKET is connected to; it stores the address in the memory space
|
specified by ADDR and LENGTH-PTR. It stores the length of the
|
address in ‘*LENGTH-PTR’.
|
|
*Note Socket Addresses::, for information about the format of the
|
address. In some operating systems, ‘getpeername’ works only for
|
sockets in the Internet domain.
|
|
The return value is ‘0’ on success and ‘-1’ on error. The
|
following ‘errno’ error conditions are defined for this function:
|
|
‘EBADF’
|
The argument SOCKET is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
The descriptor SOCKET is not a socket.
|
|
‘ENOTCONN’
|
The socket SOCKET is not connected.
|
|
‘ENOBUFS’
|
There are not enough internal buffers available.
|
|
|
File: libc.info, Node: Transferring Data, Next: Byte Stream Example, Prev: Who is Connected, Up: Connections
|
|
16.9.5 Transferring Data
|
------------------------
|
|
Once a socket has been connected to a peer, you can use the ordinary
|
‘read’ and ‘write’ operations (*note I/O Primitives::) to transfer data.
|
A socket is a two-way communications channel, so read and write
|
operations can be performed at either end.
|
|
There are also some I/O modes that are specific to socket operations.
|
In order to specify these modes, you must use the ‘recv’ and ‘send’
|
functions instead of the more generic ‘read’ and ‘write’ functions. The
|
‘recv’ and ‘send’ functions take an additional argument which you can
|
use to specify various flags to control special I/O modes. For example,
|
you can specify the ‘MSG_OOB’ flag to read or write out-of-band data,
|
the ‘MSG_PEEK’ flag to peek at input, or the ‘MSG_DONTROUTE’ flag to
|
control inclusion of routing information on output.
|
|
* Menu:
|
|
* Sending Data:: Sending data with ‘send’.
|
* Receiving Data:: Reading data with ‘recv’.
|
* Socket Data Options:: Using ‘send’ and ‘recv’.
|
|
|
File: libc.info, Node: Sending Data, Next: Receiving Data, Up: Transferring Data
|
|
16.9.5.1 Sending Data
|
.....................
|
|
The ‘send’ function is declared in the header file ‘sys/socket.h’. If
|
your FLAGS argument is zero, you can just as well use ‘write’ instead of
|
‘send’; see *note I/O Primitives::. If the socket was connected but the
|
connection has broken, you get a ‘SIGPIPE’ signal for any use of ‘send’
|
or ‘write’ (*note Miscellaneous Signals::).
|
|
-- Function: ssize_t send (int SOCKET, const void *BUFFER, size_t SIZE,
|
int FLAGS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘send’ function is like ‘write’, but with the additional flags
|
FLAGS. The possible values of FLAGS are described in *note Socket
|
Data Options::.
|
|
This function returns the number of bytes transmitted, or ‘-1’ on
|
failure. If the socket is nonblocking, then ‘send’ (like ‘write’)
|
can return after sending just part of the data. *Note File Status
|
Flags::, for information about nonblocking mode.
|
|
Note, however, that a successful return value merely indicates that
|
the message has been sent without error, not necessarily that it
|
has been received without error.
|
|
The following ‘errno’ error conditions are defined for this
|
function:
|
|
‘EBADF’
|
The SOCKET argument is not a valid file descriptor.
|
|
‘EINTR’
|
The operation was interrupted by a signal before any data was
|
sent. *Note Interrupted Primitives::.
|
|
‘ENOTSOCK’
|
The descriptor SOCKET is not a socket.
|
|
‘EMSGSIZE’
|
The socket type requires that the message be sent atomically,
|
but the message is too large for this to be possible.
|
|
‘EWOULDBLOCK’
|
Nonblocking mode has been set on the socket, and the write
|
operation would block. (Normally ‘send’ blocks until the
|
operation can be completed.)
|
|
‘ENOBUFS’
|
There is not enough internal buffer space available.
|
|
‘ENOTCONN’
|
You never connected this socket.
|
|
‘EPIPE’
|
This socket was connected but the connection is now broken.
|
In this case, ‘send’ generates a ‘SIGPIPE’ signal first; if
|
that signal is ignored or blocked, or if its handler returns,
|
then ‘send’ fails with ‘EPIPE’.
|
|
This function is defined as a cancellation point in multi-threaded
|
programs, so one has to be prepared for this and make sure that
|
allocated resources (like memory, file descriptors, semaphores or
|
whatever) are freed even if the thread is canceled.
|
|
|
File: libc.info, Node: Receiving Data, Next: Socket Data Options, Prev: Sending Data, Up: Transferring Data
|
|
16.9.5.2 Receiving Data
|
.......................
|
|
The ‘recv’ function is declared in the header file ‘sys/socket.h’. If
|
your FLAGS argument is zero, you can just as well use ‘read’ instead of
|
‘recv’; see *note I/O Primitives::.
|
|
-- Function: ssize_t recv (int SOCKET, void *BUFFER, size_t SIZE, int
|
FLAGS)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘recv’ function is like ‘read’, but with the additional flags
|
FLAGS. The possible values of FLAGS are described in *note Socket
|
Data Options::.
|
|
If nonblocking mode is set for SOCKET, and no data are available to
|
be read, ‘recv’ fails immediately rather than waiting. *Note File
|
Status Flags::, for information about nonblocking mode.
|
|
This function returns the number of bytes received, or ‘-1’ on
|
failure. The following ‘errno’ error conditions are defined for
|
this function:
|
|
‘EBADF’
|
The SOCKET argument is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
The descriptor SOCKET is not a socket.
|
|
‘EWOULDBLOCK’
|
Nonblocking mode has been set on the socket, and the read
|
operation would block. (Normally, ‘recv’ blocks until there
|
is input available to be read.)
|
|
‘EINTR’
|
The operation was interrupted by a signal before any data was
|
read. *Note Interrupted Primitives::.
|
|
‘ENOTCONN’
|
You never connected this socket.
|
|
This function is defined as a cancellation point in multi-threaded
|
programs, so one has to be prepared for this and make sure that
|
allocated resources (like memory, file descriptors, semaphores or
|
whatever) are freed even if the thread is canceled.
|
|
|
File: libc.info, Node: Socket Data Options, Prev: Receiving Data, Up: Transferring Data
|
|
16.9.5.3 Socket Data Options
|
............................
|
|
The FLAGS argument to ‘send’ and ‘recv’ is a bit mask. You can
|
bitwise-OR the values of the following macros together to obtain a value
|
for this argument. All are defined in the header file ‘sys/socket.h’.
|
|
-- Macro: int MSG_OOB
|
|
Send or receive out-of-band data. *Note Out-of-Band Data::.
|
|
-- Macro: int MSG_PEEK
|
|
Look at the data but don’t remove it from the input queue. This is
|
only meaningful with input functions such as ‘recv’, not with
|
‘send’.
|
|
-- Macro: int MSG_DONTROUTE
|
|
Don’t include routing information in the message. This is only
|
meaningful with output operations, and is usually only of interest
|
for diagnostic or routing programs. We don’t try to explain it
|
here.
|
|
|
File: libc.info, Node: Byte Stream Example, Next: Server Example, Prev: Transferring Data, Up: Connections
|
|
16.9.6 Byte Stream Socket Example
|
---------------------------------
|
|
Here is an example client program that makes a connection for a byte
|
stream socket in the Internet namespace. It doesn’t do anything
|
particularly interesting once it has connected to the server; it just
|
sends a text string to the server and exits.
|
|
This program uses ‘init_sockaddr’ to set up the socket address; see
|
*note Inet Example::.
|
|
|
#include <stdio.h>
|
#include <errno.h>
|
#include <stdlib.h>
|
#include <unistd.h>
|
#include <sys/types.h>
|
#include <sys/socket.h>
|
#include <netinet/in.h>
|
#include <netdb.h>
|
|
#define PORT 5555
|
#define MESSAGE "Yow!!! Are we having fun yet?!?"
|
#define SERVERHOST "www.gnu.org"
|
|
void
|
write_to_server (int filedes)
|
{
|
int nbytes;
|
|
nbytes = write (filedes, MESSAGE, strlen (MESSAGE) + 1);
|
if (nbytes < 0)
|
{
|
perror ("write");
|
exit (EXIT_FAILURE);
|
}
|
}
|
|
|
int
|
main (void)
|
{
|
extern void init_sockaddr (struct sockaddr_in *name,
|
const char *hostname,
|
uint16_t port);
|
int sock;
|
struct sockaddr_in servername;
|
|
/* Create the socket. */
|
sock = socket (PF_INET, SOCK_STREAM, 0);
|
if (sock < 0)
|
{
|
perror ("socket (client)");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Connect to the server. */
|
init_sockaddr (&servername, SERVERHOST, PORT);
|
if (0 > connect (sock,
|
(struct sockaddr *) &servername,
|
sizeof (servername)))
|
{
|
perror ("connect (client)");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Send data to the server. */
|
write_to_server (sock);
|
close (sock);
|
exit (EXIT_SUCCESS);
|
}
|
|
|
File: libc.info, Node: Server Example, Next: Out-of-Band Data, Prev: Byte Stream Example, Up: Connections
|
|
16.9.7 Byte Stream Connection Server Example
|
--------------------------------------------
|
|
The server end is much more complicated. Since we want to allow
|
multiple clients to be connected to the server at the same time, it
|
would be incorrect to wait for input from a single client by simply
|
calling ‘read’ or ‘recv’. Instead, the right thing to do is to use
|
‘select’ (*note Waiting for I/O::) to wait for input on all of the open
|
sockets. This also allows the server to deal with additional connection
|
requests.
|
|
This particular server doesn’t do anything interesting once it has
|
gotten a message from a client. It does close the socket for that
|
client when it detects an end-of-file condition (resulting from the
|
client shutting down its end of the connection).
|
|
This program uses ‘make_socket’ to set up the socket address; see
|
*note Inet Example::.
|
|
|
#include <stdio.h>
|
#include <errno.h>
|
#include <stdlib.h>
|
#include <unistd.h>
|
#include <sys/types.h>
|
#include <sys/socket.h>
|
#include <netinet/in.h>
|
#include <netdb.h>
|
|
#define PORT 5555
|
#define MAXMSG 512
|
|
int
|
read_from_client (int filedes)
|
{
|
char buffer[MAXMSG];
|
int nbytes;
|
|
nbytes = read (filedes, buffer, MAXMSG);
|
if (nbytes < 0)
|
{
|
/* Read error. */
|
perror ("read");
|
exit (EXIT_FAILURE);
|
}
|
else if (nbytes == 0)
|
/* End-of-file. */
|
return -1;
|
else
|
{
|
/* Data read. */
|
fprintf (stderr, "Server: got message: `%s'\n", buffer);
|
return 0;
|
}
|
}
|
|
int
|
main (void)
|
{
|
extern int make_socket (uint16_t port);
|
int sock;
|
fd_set active_fd_set, read_fd_set;
|
int i;
|
struct sockaddr_in clientname;
|
size_t size;
|
|
/* Create the socket and set it up to accept connections. */
|
sock = make_socket (PORT);
|
if (listen (sock, 1) < 0)
|
{
|
perror ("listen");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Initialize the set of active sockets. */
|
FD_ZERO (&active_fd_set);
|
FD_SET (sock, &active_fd_set);
|
|
while (1)
|
{
|
/* Block until input arrives on one or more active sockets. */
|
read_fd_set = active_fd_set;
|
if (select (FD_SETSIZE, &read_fd_set, NULL, NULL, NULL) < 0)
|
{
|
perror ("select");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Service all the sockets with input pending. */
|
for (i = 0; i < FD_SETSIZE; ++i)
|
if (FD_ISSET (i, &read_fd_set))
|
{
|
if (i == sock)
|
{
|
/* Connection request on original socket. */
|
int new;
|
size = sizeof (clientname);
|
new = accept (sock,
|
(struct sockaddr *) &clientname,
|
&size);
|
if (new < 0)
|
{
|
perror ("accept");
|
exit (EXIT_FAILURE);
|
}
|
fprintf (stderr,
|
"Server: connect from host %s, port %hd.\n",
|
inet_ntoa (clientname.sin_addr),
|
ntohs (clientname.sin_port));
|
FD_SET (new, &active_fd_set);
|
}
|
else
|
{
|
/* Data arriving on an already-connected socket. */
|
if (read_from_client (i) < 0)
|
{
|
close (i);
|
FD_CLR (i, &active_fd_set);
|
}
|
}
|
}
|
}
|
}
|
|
|
File: libc.info, Node: Out-of-Band Data, Prev: Server Example, Up: Connections
|
|
16.9.8 Out-of-Band Data
|
-----------------------
|
|
Streams with connections permit "out-of-band" data that is delivered
|
with higher priority than ordinary data. Typically the reason for
|
sending out-of-band data is to send notice of an exceptional condition.
|
To send out-of-band data use ‘send’, specifying the flag ‘MSG_OOB’
|
(*note Sending Data::).
|
|
Out-of-band data are received with higher priority because the
|
receiving process need not read it in sequence; to read the next
|
available out-of-band data, use ‘recv’ with the ‘MSG_OOB’ flag (*note
|
Receiving Data::). Ordinary read operations do not read out-of-band
|
data; they read only ordinary data.
|
|
When a socket finds that out-of-band data are on their way, it sends
|
a ‘SIGURG’ signal to the owner process or process group of the socket.
|
You can specify the owner using the ‘F_SETOWN’ command to the ‘fcntl’
|
function; see *note Interrupt Input::. You must also establish a
|
handler for this signal, as described in *note Signal Handling::, in
|
order to take appropriate action such as reading the out-of-band data.
|
|
Alternatively, you can test for pending out-of-band data, or wait
|
until there is out-of-band data, using the ‘select’ function; it can
|
wait for an exceptional condition on the socket. *Note Waiting for
|
I/O::, for more information about ‘select’.
|
|
Notification of out-of-band data (whether with ‘SIGURG’ or with
|
‘select’) indicates that out-of-band data are on the way; the data may
|
not actually arrive until later. If you try to read the out-of-band
|
data before it arrives, ‘recv’ fails with an ‘EWOULDBLOCK’ error.
|
|
Sending out-of-band data automatically places a “mark” in the stream
|
of ordinary data, showing where in the sequence the out-of-band data
|
“would have been”. This is useful when the meaning of out-of-band data
|
is “cancel everything sent so far”. Here is how you can test, in the
|
receiving process, whether any ordinary data was sent before the mark:
|
|
success = ioctl (socket, SIOCATMARK, &atmark);
|
|
The ‘integer’ variable ATMARK is set to a nonzero value if the
|
socket’s read pointer has reached the “mark”.
|
|
Here’s a function to discard any ordinary data preceding the
|
out-of-band mark:
|
|
int
|
discard_until_mark (int socket)
|
{
|
while (1)
|
{
|
/* This is not an arbitrary limit; any size will do. */
|
char buffer[1024];
|
int atmark, success;
|
|
/* If we have reached the mark, return. */
|
success = ioctl (socket, SIOCATMARK, &atmark);
|
if (success < 0)
|
perror ("ioctl");
|
if (result)
|
return;
|
|
/* Otherwise, read a bunch of ordinary data and discard it.
|
This is guaranteed not to read past the mark
|
if it starts before the mark. */
|
success = read (socket, buffer, sizeof buffer);
|
if (success < 0)
|
perror ("read");
|
}
|
}
|
|
If you don’t want to discard the ordinary data preceding the mark,
|
you may need to read some of it anyway, to make room in internal system
|
buffers for the out-of-band data. If you try to read out-of-band data
|
and get an ‘EWOULDBLOCK’ error, try reading some ordinary data (saving
|
it so that you can use it when you want it) and see if that makes room.
|
Here is an example:
|
|
struct buffer
|
{
|
char *buf;
|
int size;
|
struct buffer *next;
|
};
|
|
/* Read the out-of-band data from SOCKET and return it
|
as a ‘struct buffer’, which records the address of the data
|
and its size.
|
|
It may be necessary to read some ordinary data
|
in order to make room for the out-of-band data.
|
If so, the ordinary data are saved as a chain of buffers
|
found in the ‘next’ field of the value. */
|
|
struct buffer *
|
read_oob (int socket)
|
{
|
struct buffer *tail = 0;
|
struct buffer *list = 0;
|
|
while (1)
|
{
|
/* This is an arbitrary limit.
|
Does anyone know how to do this without a limit? */
|
#define BUF_SZ 1024
|
char *buf = (char *) xmalloc (BUF_SZ);
|
int success;
|
int atmark;
|
|
/* Try again to read the out-of-band data. */
|
success = recv (socket, buf, BUF_SZ, MSG_OOB);
|
if (success >= 0)
|
{
|
/* We got it, so return it. */
|
struct buffer *link
|
= (struct buffer *) xmalloc (sizeof (struct buffer));
|
link->buf = buf;
|
link->size = success;
|
link->next = list;
|
return link;
|
}
|
|
/* If we fail, see if we are at the mark. */
|
success = ioctl (socket, SIOCATMARK, &atmark);
|
if (success < 0)
|
perror ("ioctl");
|
if (atmark)
|
{
|
/* At the mark; skipping past more ordinary data cannot help.
|
So just wait a while. */
|
sleep (1);
|
continue;
|
}
|
|
/* Otherwise, read a bunch of ordinary data and save it.
|
This is guaranteed not to read past the mark
|
if it starts before the mark. */
|
success = read (socket, buf, BUF_SZ);
|
if (success < 0)
|
perror ("read");
|
|
/* Save this data in the buffer list. */
|
{
|
struct buffer *link
|
= (struct buffer *) xmalloc (sizeof (struct buffer));
|
link->buf = buf;
|
link->size = success;
|
|
/* Add the new link to the end of the list. */
|
if (tail)
|
tail->next = link;
|
else
|
list = link;
|
tail = link;
|
}
|
}
|
}
|
|
|
File: libc.info, Node: Datagrams, Next: Inetd, Prev: Connections, Up: Sockets
|
|
16.10 Datagram Socket Operations
|
================================
|
|
This section describes how to use communication styles that don’t use
|
connections (styles ‘SOCK_DGRAM’ and ‘SOCK_RDM’). Using these styles,
|
you group data into packets and each packet is an independent
|
communication. You specify the destination for each packet
|
individually.
|
|
Datagram packets are like letters: you send each one independently
|
with its own destination address, and they may arrive in the wrong order
|
or not at all.
|
|
The ‘listen’ and ‘accept’ functions are not allowed for sockets using
|
connectionless communication styles.
|
|
* Menu:
|
|
* Sending Datagrams:: Sending packets on a datagram socket.
|
* Receiving Datagrams:: Receiving packets on a datagram socket.
|
* Datagram Example:: An example program: packets sent over a
|
datagram socket in the local namespace.
|
* Example Receiver:: Another program, that receives those packets.
|
|
|
File: libc.info, Node: Sending Datagrams, Next: Receiving Datagrams, Up: Datagrams
|
|
16.10.1 Sending Datagrams
|
-------------------------
|
|
The normal way of sending data on a datagram socket is by using the
|
‘sendto’ function, declared in ‘sys/socket.h’.
|
|
You can call ‘connect’ on a datagram socket, but this only specifies
|
a default destination for further data transmission on the socket. When
|
a socket has a default destination you can use ‘send’ (*note Sending
|
Data::) or even ‘write’ (*note I/O Primitives::) to send a packet there.
|
You can cancel the default destination by calling ‘connect’ using an
|
address format of ‘AF_UNSPEC’ in the ADDR argument. *Note Connecting::,
|
for more information about the ‘connect’ function.
|
|
-- Function: ssize_t sendto (int SOCKET, const void *BUFFER, size_t
|
SIZE, int FLAGS, struct sockaddr *ADDR, socklen_t LENGTH)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘sendto’ function transmits the data in the BUFFER through the
|
socket SOCKET to the destination address specified by the ADDR and
|
LENGTH arguments. The SIZE argument specifies the number of bytes
|
to be transmitted.
|
|
The FLAGS are interpreted the same way as for ‘send’; see *note
|
Socket Data Options::.
|
|
The return value and error conditions are also the same as for
|
‘send’, but you cannot rely on the system to detect errors and
|
report them; the most common error is that the packet is lost or
|
there is no-one at the specified address to receive it, and the
|
operating system on your machine usually does not know this.
|
|
It is also possible for one call to ‘sendto’ to report an error
|
owing to a problem related to a previous call.
|
|
This function is defined as a cancellation point in multi-threaded
|
programs, so one has to be prepared for this and make sure that
|
allocated resources (like memory, file descriptors, semaphores or
|
whatever) are freed even if the thread is canceled.
|
|
|
File: libc.info, Node: Receiving Datagrams, Next: Datagram Example, Prev: Sending Datagrams, Up: Datagrams
|
|
16.10.2 Receiving Datagrams
|
---------------------------
|
|
The ‘recvfrom’ function reads a packet from a datagram socket and also
|
tells you where it was sent from. This function is declared in
|
‘sys/socket.h’.
|
|
-- Function: ssize_t recvfrom (int SOCKET, void *BUFFER, size_t SIZE,
|
int FLAGS, struct sockaddr *ADDR, socklen_t *LENGTH-PTR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘recvfrom’ function reads one packet from the socket SOCKET
|
into the buffer BUFFER. The SIZE argument specifies the maximum
|
number of bytes to be read.
|
|
If the packet is longer than SIZE bytes, then you get the first
|
SIZE bytes of the packet and the rest of the packet is lost.
|
There’s no way to read the rest of the packet. Thus, when you use
|
a packet protocol, you must always know how long a packet to
|
expect.
|
|
The ADDR and LENGTH-PTR arguments are used to return the address
|
where the packet came from. *Note Socket Addresses::. For a
|
socket in the local domain the address information won’t be
|
meaningful, since you can’t read the address of such a socket
|
(*note Local Namespace::). You can specify a null pointer as the
|
ADDR argument if you are not interested in this information.
|
|
The FLAGS are interpreted the same way as for ‘recv’ (*note Socket
|
Data Options::). The return value and error conditions are also
|
the same as for ‘recv’.
|
|
This function is defined as a cancellation point in multi-threaded
|
programs, so one has to be prepared for this and make sure that
|
allocated resources (like memory, file descriptors, semaphores or
|
whatever) are freed even if the thread is canceled.
|
|
You can use plain ‘recv’ (*note Receiving Data::) instead of
|
‘recvfrom’ if you don’t need to find out who sent the packet (either
|
because you know where it should come from or because you treat all
|
possible senders alike). Even ‘read’ can be used if you don’t want to
|
specify FLAGS (*note I/O Primitives::).
|
|
|
File: libc.info, Node: Datagram Example, Next: Example Receiver, Prev: Receiving Datagrams, Up: Datagrams
|
|
16.10.3 Datagram Socket Example
|
-------------------------------
|
|
Here is a set of example programs that send messages over a datagram
|
stream in the local namespace. Both the client and server programs use
|
the ‘make_named_socket’ function that was presented in *note Local
|
Socket Example::, to create and name their sockets.
|
|
First, here is the server program. It sits in a loop waiting for
|
messages to arrive, bouncing each message back to the sender. Obviously
|
this isn’t a particularly useful program, but it does show the general
|
ideas involved.
|
|
|
#include <stdio.h>
|
#include <errno.h>
|
#include <stdlib.h>
|
#include <sys/socket.h>
|
#include <sys/un.h>
|
|
#define SERVER "/tmp/serversocket"
|
#define MAXMSG 512
|
|
int
|
main (void)
|
{
|
int sock;
|
char message[MAXMSG];
|
struct sockaddr_un name;
|
size_t size;
|
int nbytes;
|
|
/* Remove the filename first, it’s ok if the call fails */
|
unlink (SERVER);
|
|
/* Make the socket, then loop endlessly. */
|
sock = make_named_socket (SERVER);
|
while (1)
|
{
|
/* Wait for a datagram. */
|
size = sizeof (name);
|
nbytes = recvfrom (sock, message, MAXMSG, 0,
|
(struct sockaddr *) & name, &size);
|
if (nbytes < 0)
|
{
|
perror ("recfrom (server)");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Give a diagnostic message. */
|
fprintf (stderr, "Server: got message: %s\n", message);
|
|
/* Bounce the message back to the sender. */
|
nbytes = sendto (sock, message, nbytes, 0,
|
(struct sockaddr *) & name, size);
|
if (nbytes < 0)
|
{
|
perror ("sendto (server)");
|
exit (EXIT_FAILURE);
|
}
|
}
|
}
|
|
|
File: libc.info, Node: Example Receiver, Prev: Datagram Example, Up: Datagrams
|
|
16.10.4 Example of Reading Datagrams
|
------------------------------------
|
|
Here is the client program corresponding to the server above.
|
|
It sends a datagram to the server and then waits for a reply. Notice
|
that the socket for the client (as well as for the server) in this
|
example has to be given a name. This is so that the server can direct a
|
message back to the client. Since the socket has no associated
|
connection state, the only way the server can do this is by referencing
|
the name of the client.
|
|
|
#include <stdio.h>
|
#include <errno.h>
|
#include <unistd.h>
|
#include <stdlib.h>
|
#include <sys/socket.h>
|
#include <sys/un.h>
|
|
#define SERVER "/tmp/serversocket"
|
#define CLIENT "/tmp/mysocket"
|
#define MAXMSG 512
|
#define MESSAGE "Yow!!! Are we having fun yet?!?"
|
|
int
|
main (void)
|
{
|
extern int make_named_socket (const char *name);
|
int sock;
|
char message[MAXMSG];
|
struct sockaddr_un name;
|
size_t size;
|
int nbytes;
|
|
/* Make the socket. */
|
sock = make_named_socket (CLIENT);
|
|
/* Initialize the server socket address. */
|
name.sun_family = AF_LOCAL;
|
strcpy (name.sun_path, SERVER);
|
size = strlen (name.sun_path) + sizeof (name.sun_family);
|
|
/* Send the datagram. */
|
nbytes = sendto (sock, MESSAGE, strlen (MESSAGE) + 1, 0,
|
(struct sockaddr *) & name, size);
|
if (nbytes < 0)
|
{
|
perror ("sendto (client)");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Wait for a reply. */
|
nbytes = recvfrom (sock, message, MAXMSG, 0, NULL, 0);
|
if (nbytes < 0)
|
{
|
perror ("recfrom (client)");
|
exit (EXIT_FAILURE);
|
}
|
|
/* Print a diagnostic message. */
|
fprintf (stderr, "Client: got message: %s\n", message);
|
|
/* Clean up. */
|
remove (CLIENT);
|
close (sock);
|
}
|
|
Keep in mind that datagram socket communications are unreliable. In
|
this example, the client program waits indefinitely if the message never
|
reaches the server or if the server’s response never comes back. It’s
|
up to the user running the program to kill and restart it if desired. A
|
more automatic solution could be to use ‘select’ (*note Waiting for
|
I/O::) to establish a timeout period for the reply, and in case of
|
timeout either re-send the message or shut down the socket and exit.
|
|
|
File: libc.info, Node: Inetd, Next: Socket Options, Prev: Datagrams, Up: Sockets
|
|
16.11 The ‘inetd’ Daemon
|
========================
|
|
We’ve explained above how to write a server program that does its own
|
listening. Such a server must already be running in order for anyone to
|
connect to it.
|
|
Another way to provide a service on an Internet port is to let the
|
daemon program ‘inetd’ do the listening. ‘inetd’ is a program that runs
|
all the time and waits (using ‘select’) for messages on a specified set
|
of ports. When it receives a message, it accepts the connection (if the
|
socket style calls for connections) and then forks a child process to
|
run the corresponding server program. You specify the ports and their
|
programs in the file ‘/etc/inetd.conf’.
|
|
* Menu:
|
|
* Inetd Servers::
|
* Configuring Inetd::
|
|
|
File: libc.info, Node: Inetd Servers, Next: Configuring Inetd, Up: Inetd
|
|
16.11.1 ‘inetd’ Servers
|
-----------------------
|
|
Writing a server program to be run by ‘inetd’ is very simple. Each time
|
someone requests a connection to the appropriate port, a new server
|
process starts. The connection already exists at this time; the socket
|
is available as the standard input descriptor and as the standard output
|
descriptor (descriptors 0 and 1) in the server process. Thus the server
|
program can begin reading and writing data right away. Often the
|
program needs only the ordinary I/O facilities; in fact, a
|
general-purpose filter program that knows nothing about sockets can work
|
as a byte stream server run by ‘inetd’.
|
|
You can also use ‘inetd’ for servers that use connectionless
|
communication styles. For these servers, ‘inetd’ does not try to accept
|
a connection since no connection is possible. It just starts the server
|
program, which can read the incoming datagram packet from descriptor 0.
|
The server program can handle one request and then exit, or you can
|
choose to write it to keep reading more requests until no more arrive,
|
and then exit. You must specify which of these two techniques the
|
server uses when you configure ‘inetd’.
|
|
|
File: libc.info, Node: Configuring Inetd, Prev: Inetd Servers, Up: Inetd
|
|
16.11.2 Configuring ‘inetd’
|
---------------------------
|
|
The file ‘/etc/inetd.conf’ tells ‘inetd’ which ports to listen to and
|
what server programs to run for them. Normally each entry in the file
|
is one line, but you can split it onto multiple lines provided all but
|
the first line of the entry start with whitespace. Lines that start
|
with ‘#’ are comments.
|
|
Here are two standard entries in ‘/etc/inetd.conf’:
|
|
ftp stream tcp nowait root /libexec/ftpd ftpd
|
talk dgram udp wait root /libexec/talkd talkd
|
|
An entry has this format:
|
|
SERVICE STYLE PROTOCOL WAIT USERNAME PROGRAM ARGUMENTS
|
|
The SERVICE field says which service this program provides. It
|
should be the name of a service defined in ‘/etc/services’. ‘inetd’
|
uses SERVICE to decide which port to listen on for this entry.
|
|
The fields STYLE and PROTOCOL specify the communication style and the
|
protocol to use for the listening socket. The style should be the name
|
of a communication style, converted to lower case and with ‘SOCK_’
|
deleted—for example, ‘stream’ or ‘dgram’. PROTOCOL should be one of the
|
protocols listed in ‘/etc/protocols’. The typical protocol names are
|
‘tcp’ for byte stream connections and ‘udp’ for unreliable datagrams.
|
|
The WAIT field should be either ‘wait’ or ‘nowait’. Use ‘wait’ if
|
STYLE is a connectionless style and the server, once started, handles
|
multiple requests as they come in. Use ‘nowait’ if ‘inetd’ should start
|
a new process for each message or request that comes in. If STYLE uses
|
connections, then WAIT *must* be ‘nowait’.
|
|
USER is the user name that the server should run as. ‘inetd’ runs as
|
root, so it can set the user ID of its children arbitrarily. It’s best
|
to avoid using ‘root’ for USER if you can; but some servers, such as
|
Telnet and FTP, read a username and passphrase themselves. These
|
servers need to be root initially so they can log in as commanded by the
|
data coming over the network.
|
|
PROGRAM together with ARGUMENTS specifies the command to run to start
|
the server. PROGRAM should be an absolute file name specifying the
|
executable file to run. ARGUMENTS consists of any number of
|
whitespace-separated words, which become the command-line arguments of
|
PROGRAM. The first word in ARGUMENTS is argument zero, which should by
|
convention be the program name itself (sans directories).
|
|
If you edit ‘/etc/inetd.conf’, you can tell ‘inetd’ to reread the
|
file and obey its new contents by sending the ‘inetd’ process the
|
‘SIGHUP’ signal. You’ll have to use ‘ps’ to determine the process ID of
|
the ‘inetd’ process as it is not fixed.
|
|
|
File: libc.info, Node: Socket Options, Next: Networks Database, Prev: Inetd, Up: Sockets
|
|
16.12 Socket Options
|
====================
|
|
This section describes how to read or set various options that modify
|
the behavior of sockets and their underlying communications protocols.
|
|
When you are manipulating a socket option, you must specify which
|
"level" the option pertains to. This describes whether the option
|
applies to the socket interface, or to a lower-level communications
|
protocol interface.
|
|
* Menu:
|
|
* Socket Option Functions:: The basic functions for setting and getting
|
socket options.
|
* Socket-Level Options:: Details of the options at the socket level.
|
|
|
File: libc.info, Node: Socket Option Functions, Next: Socket-Level Options, Up: Socket Options
|
|
16.12.1 Socket Option Functions
|
-------------------------------
|
|
Here are the functions for examining and modifying socket options. They
|
are declared in ‘sys/socket.h’.
|
|
-- Function: int getsockopt (int SOCKET, int LEVEL, int OPTNAME, void
|
*OPTVAL, socklen_t *OPTLEN-PTR)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
The ‘getsockopt’ function gets information about the value of
|
option OPTNAME at level LEVEL for socket SOCKET.
|
|
The option value is stored in the buffer that OPTVAL points to.
|
Before the call, you should supply in ‘*OPTLEN-PTR’ the size of
|
this buffer; on return, it contains the number of bytes of
|
information actually stored in the buffer.
|
|
Most options interpret the OPTVAL buffer as a single ‘int’ value.
|
|
The actual return value of ‘getsockopt’ is ‘0’ on success and ‘-1’
|
on failure. The following ‘errno’ error conditions are defined:
|
|
‘EBADF’
|
The SOCKET argument is not a valid file descriptor.
|
|
‘ENOTSOCK’
|
The descriptor SOCKET is not a socket.
|
|
‘ENOPROTOOPT’
|
The OPTNAME doesn’t make sense for the given LEVEL.
|
|
-- Function: int setsockopt (int SOCKET, int LEVEL, int OPTNAME, const
|
void *OPTVAL, socklen_t OPTLEN)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function is used to set the socket option OPTNAME at level
|
LEVEL for socket SOCKET. The value of the option is passed in the
|
buffer OPTVAL of size OPTLEN.
|
|
The return value and error codes for ‘setsockopt’ are the same as
|
for ‘getsockopt’.
|
|
|
File: libc.info, Node: Socket-Level Options, Prev: Socket Option Functions, Up: Socket Options
|
|
16.12.2 Socket-Level Options
|
----------------------------
|
|
-- Constant: int SOL_SOCKET
|
|
Use this constant as the LEVEL argument to ‘getsockopt’ or
|
‘setsockopt’ to manipulate the socket-level options described in
|
this section.
|
|
Here is a table of socket-level option names; all are defined in the
|
header file ‘sys/socket.h’.
|
|
‘SO_DEBUG’
|
|
This option toggles recording of debugging information in the
|
underlying protocol modules. The value has type ‘int’; a nonzero
|
value means “yes”.
|
|
‘SO_REUSEADDR’
|
|
This option controls whether ‘bind’ (*note Setting Address::)
|
should permit reuse of local addresses for this socket. If you
|
enable this option, you can actually have two sockets with the same
|
Internet port number; but the system won’t allow you to use the two
|
identically-named sockets in a way that would confuse the Internet.
|
The reason for this option is that some higher-level Internet
|
protocols, including FTP, require you to keep reusing the same port
|
number.
|
|
The value has type ‘int’; a nonzero value means “yes”.
|
|
‘SO_KEEPALIVE’
|
|
This option controls whether the underlying protocol should
|
periodically transmit messages on a connected socket. If the peer
|
fails to respond to these messages, the connection is considered
|
broken. The value has type ‘int’; a nonzero value means “yes”.
|
|
‘SO_DONTROUTE’
|
|
This option controls whether outgoing messages bypass the normal
|
message routing facilities. If set, messages are sent directly to
|
the network interface instead. The value has type ‘int’; a nonzero
|
value means “yes”.
|
|
‘SO_LINGER’
|
|
This option specifies what should happen when the socket of a type
|
that promises reliable delivery still has untransmitted messages
|
when it is closed; see *note Closing a Socket::. The value has
|
type ‘struct linger’.
|
|
-- Data Type: struct linger
|
|
This structure type has the following members:
|
|
‘int l_onoff’
|
This field is interpreted as a boolean. If nonzero,
|
‘close’ blocks until the data are transmitted or the
|
timeout period has expired.
|
|
‘int l_linger’
|
This specifies the timeout period, in seconds.
|
|
‘SO_BROADCAST’
|
|
This option controls whether datagrams may be broadcast from the
|
socket. The value has type ‘int’; a nonzero value means “yes”.
|
|
‘SO_OOBINLINE’
|
|
If this option is set, out-of-band data received on the socket is
|
placed in the normal input queue. This permits it to be read using
|
‘read’ or ‘recv’ without specifying the ‘MSG_OOB’ flag. *Note
|
Out-of-Band Data::. The value has type ‘int’; a nonzero value
|
means “yes”.
|
|
‘SO_SNDBUF’
|
|
This option gets or sets the size of the output buffer. The value
|
is a ‘size_t’, which is the size in bytes.
|
|
‘SO_RCVBUF’
|
|
This option gets or sets the size of the input buffer. The value
|
is a ‘size_t’, which is the size in bytes.
|
|
‘SO_STYLE’
|
‘SO_TYPE’
|
|
This option can be used with ‘getsockopt’ only. It is used to get
|
the socket’s communication style. ‘SO_TYPE’ is the historical
|
name, and ‘SO_STYLE’ is the preferred name in GNU. The value has
|
type ‘int’ and its value designates a communication style; see
|
*note Communication Styles::.
|
|
‘SO_ERROR’
|
|
This option can be used with ‘getsockopt’ only. It is used to
|
reset the error status of the socket. The value is an ‘int’, which
|
represents the previous error status.
|
|
|
File: libc.info, Node: Networks Database, Prev: Socket Options, Up: Sockets
|
|
16.13 Networks Database
|
=======================
|
|
Many systems come with a database that records a list of networks known
|
to the system developer. This is usually kept either in the file
|
‘/etc/networks’ or in an equivalent from a name server. This data base
|
is useful for routing programs such as ‘route’, but it is not useful for
|
programs that simply communicate over the network. We provide functions
|
to access this database, which are declared in ‘netdb.h’.
|
|
-- Data Type: struct netent
|
|
This data type is used to represent information about entries in
|
the networks database. It has the following members:
|
|
‘char *n_name’
|
This is the “official” name of the network.
|
|
‘char **n_aliases’
|
These are alternative names for the network, represented as a
|
vector of strings. A null pointer terminates the array.
|
|
‘int n_addrtype’
|
This is the type of the network number; this is always equal
|
to ‘AF_INET’ for Internet networks.
|
|
‘unsigned long int n_net’
|
This is the network number. Network numbers are returned in
|
host byte order; see *note Byte Order::.
|
|
Use the ‘getnetbyname’ or ‘getnetbyaddr’ functions to search the
|
networks database for information about a specific network. The
|
information is returned in a statically-allocated structure; you must
|
copy the information if you need to save it.
|
|
-- Function: struct netent * getnetbyname (const char *NAME)
|
|
Preliminary: | MT-Unsafe race:netbyname env locale | AS-Unsafe
|
dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note
|
POSIX Safety Concepts::.
|
|
The ‘getnetbyname’ function returns information about the network
|
named NAME. It returns a null pointer if there is no such network.
|
|
-- Function: struct netent * getnetbyaddr (uint32_t NET, int TYPE)
|
|
Preliminary: | MT-Unsafe race:netbyaddr locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
The ‘getnetbyaddr’ function returns information about the network
|
of type TYPE with number NET. You should specify a value of
|
‘AF_INET’ for the TYPE argument for Internet networks.
|
|
‘getnetbyaddr’ returns a null pointer if there is no such network.
|
|
You can also scan the networks database using ‘setnetent’,
|
‘getnetent’ and ‘endnetent’. Be careful when using these functions
|
because they are not reentrant.
|
|
-- Function: void setnetent (int STAYOPEN)
|
|
Preliminary: | MT-Unsafe race:netent env locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function opens and rewinds the networks database.
|
|
If the STAYOPEN argument is nonzero, this sets a flag so that
|
subsequent calls to ‘getnetbyname’ or ‘getnetbyaddr’ will not close
|
the database (as they usually would). This makes for more
|
efficiency if you call those functions several times, by avoiding
|
reopening the database for each call.
|
|
-- Function: struct netent * getnetent (void)
|
|
Preliminary: | MT-Unsafe race:netent race:netentbuf env locale |
|
AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem |
|
*Note POSIX Safety Concepts::.
|
|
This function returns the next entry in the networks database. It
|
returns a null pointer if there are no more entries.
|
|
-- Function: void endnetent (void)
|
|
Preliminary: | MT-Unsafe race:netent env locale | AS-Unsafe dlopen
|
plugin heap lock | AC-Unsafe corrupt lock fd mem | *Note POSIX
|
Safety Concepts::.
|
|
This function closes the networks database.
|
|
|
File: libc.info, Node: Low-Level Terminal Interface, Next: Syslog, Prev: Sockets, Up: Top
|
|
17 Low-Level Terminal Interface
|
*******************************
|
|
This chapter describes functions that are specific to terminal devices.
|
You can use these functions to do things like turn off input echoing;
|
set serial line characteristics such as line speed and flow control; and
|
change which characters are used for end-of-file, command-line editing,
|
sending signals, and similar control functions.
|
|
Most of the functions in this chapter operate on file descriptors.
|
*Note Low-Level I/O::, for more information about what a file descriptor
|
is and how to open a file descriptor for a terminal device.
|
|
* Menu:
|
|
* Is It a Terminal:: How to determine if a file is a terminal
|
device, and what its name is.
|
* I/O Queues:: About flow control and typeahead.
|
* Canonical or Not:: Two basic styles of input processing.
|
* Terminal Modes:: How to examine and modify flags controlling
|
details of terminal I/O: echoing,
|
signals, editing. Posix.
|
* BSD Terminal Modes:: BSD compatible terminal mode setting
|
* Line Control:: Sending break sequences, clearing
|
terminal buffers …
|
* Noncanon Example:: How to read single characters without echo.
|
* getpass:: Prompting the user for a passphrase.
|
* Pseudo-Terminals:: How to open a pseudo-terminal.
|
|
|
File: libc.info, Node: Is It a Terminal, Next: I/O Queues, Up: Low-Level Terminal Interface
|
|
17.1 Identifying Terminals
|
==========================
|
|
The functions described in this chapter only work on files that
|
correspond to terminal devices. You can find out whether a file
|
descriptor is associated with a terminal by using the ‘isatty’ function.
|
|
Prototypes for the functions in this section are declared in the
|
header file ‘unistd.h’.
|
|
-- Function: int isatty (int FILEDES)
|
|
Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
|
Concepts::.
|
|
This function returns ‘1’ if FILEDES is a file descriptor
|
associated with an open terminal device, and 0 otherwise.
|
|
If a file descriptor is associated with a terminal, you can get its
|
associated file name using the ‘ttyname’ function. See also the
|
‘ctermid’ function, described in *note Identifying the Terminal::.
|
|
-- Function: char * ttyname (int FILEDES)
|
|
Preliminary: | MT-Unsafe race:ttyname | AS-Unsafe heap lock |
|
AC-Unsafe lock fd mem | *Note POSIX Safety Concepts::.
|
|
If the file descriptor FILEDES is associated with a terminal
|
device, the ‘ttyname’ function returns a pointer to a
|
statically-allocated, null-terminated string containing the file
|
name of the terminal file. The value is a null pointer if the file
|
descriptor isn’t associated with a terminal, or the file name
|
cannot be determined.
|
|
-- Function: int ttyname_r (int FILEDES, char *BUF, size_t LEN)
|
|
Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note
|
POSIX Safety Concepts::.
|
|
The ‘ttyname_r’ function is similar to the ‘ttyname’ function
|
except that it places its result into the user-specified buffer
|
starting at BUF with length LEN.
|
|
The normal return value from ‘ttyname_r’ is 0. Otherwise an error
|
number is returned to indicate the error. The following ‘errno’
|
error conditions are defined for this function:
|
|
‘EBADF’
|
The FILEDES argument is not a valid file descriptor.
|
|
‘ENOTTY’
|
The FILEDES is not associated with a terminal.
|
|
‘ERANGE’
|
The buffer length LEN is too small to store the string to be
|
returned.
|
|
‘ENODEV’
|
The FILEDES is associated with a terminal device that is a
|
slave pseudo-terminal, but the file name associated with that
|
device could not be determined. This is a GNU extension.
|
