| This is libc.info, produced by makeinfo version 5.2 from libc.texinfo. |
| |
| This file documents the GNU C Library. |
| |
| This is 'The GNU C Library Reference Manual', for version 2.19 |
| (Buildroot). |
| |
| Copyright (C) 1993-2014 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software Needs Free Documentation" and |
| "GNU Lesser General Public License", the Front-Cover texts being "A GNU |
| Manual", and with the Back-Cover Texts as in (a) below. A copy of the |
| license is included in the section entitled "GNU Free Documentation |
| License". |
| |
| (a) The FSF's Back-Cover Text is: "You have the freedom to copy and |
| modify this GNU manual. Buying copies from the FSF supports it in |
| developing GNU and promoting software freedom." |
| INFO-DIR-SECTION Software libraries |
| START-INFO-DIR-ENTRY |
| * Libc: (libc). C library. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION GNU C library functions and macros |
| START-INFO-DIR-ENTRY |
| * ALTWERASE: (libc)Local Modes. |
| * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions. |
| * ARG_MAX: (libc)General Limits. |
| * BC_BASE_MAX: (libc)Utility Limits. |
| * BC_DIM_MAX: (libc)Utility Limits. |
| * BC_SCALE_MAX: (libc)Utility Limits. |
| * BC_STRING_MAX: (libc)Utility Limits. |
| * BRKINT: (libc)Input Modes. |
| * BUFSIZ: (libc)Controlling Buffering. |
| * CCTS_OFLOW: (libc)Control Modes. |
| * CHILD_MAX: (libc)General Limits. |
| * CIGNORE: (libc)Control Modes. |
| * CLK_TCK: (libc)Processor Time. |
| * CLOCAL: (libc)Control Modes. |
| * CLOCKS_PER_SEC: (libc)CPU Time. |
| * COLL_WEIGHTS_MAX: (libc)Utility Limits. |
| * CPU_CLR: (libc)CPU Affinity. |
| * CPU_ISSET: (libc)CPU Affinity. |
| * CPU_SET: (libc)CPU Affinity. |
| * CPU_SETSIZE: (libc)CPU Affinity. |
| * CPU_ZERO: (libc)CPU Affinity. |
| * CREAD: (libc)Control Modes. |
| * CRTS_IFLOW: (libc)Control Modes. |
| * CS5: (libc)Control Modes. |
| * CS6: (libc)Control Modes. |
| * CS7: (libc)Control Modes. |
| * CS8: (libc)Control Modes. |
| * CSIZE: (libc)Control Modes. |
| * CSTOPB: (libc)Control Modes. |
| * DES_FAILED: (libc)DES Encryption. |
| * DTTOIF: (libc)Directory Entries. |
| * E2BIG: (libc)Error Codes. |
| * EACCES: (libc)Error Codes. |
| * EADDRINUSE: (libc)Error Codes. |
| * EADDRNOTAVAIL: (libc)Error Codes. |
| * EADV: (libc)Error Codes. |
| * EAFNOSUPPORT: (libc)Error Codes. |
| * EAGAIN: (libc)Error Codes. |
| * EALREADY: (libc)Error Codes. |
| * EAUTH: (libc)Error Codes. |
| * EBACKGROUND: (libc)Error Codes. |
| * EBADE: (libc)Error Codes. |
| * EBADF: (libc)Error Codes. |
| * EBADFD: (libc)Error Codes. |
| * EBADMSG: (libc)Error Codes. |
| * EBADR: (libc)Error Codes. |
| * EBADRPC: (libc)Error Codes. |
| * EBADRQC: (libc)Error Codes. |
| * EBADSLT: (libc)Error Codes. |
| * EBFONT: (libc)Error Codes. |
| * EBUSY: (libc)Error Codes. |
| * ECANCELED: (libc)Error Codes. |
| * ECHILD: (libc)Error Codes. |
| * ECHO: (libc)Local Modes. |
| * ECHOCTL: (libc)Local Modes. |
| * ECHOE: (libc)Local Modes. |
| * ECHOK: (libc)Local Modes. |
| * ECHOKE: (libc)Local Modes. |
| * ECHONL: (libc)Local Modes. |
| * ECHOPRT: (libc)Local Modes. |
| * ECHRNG: (libc)Error Codes. |
| * ECOMM: (libc)Error Codes. |
| * ECONNABORTED: (libc)Error Codes. |
| * ECONNREFUSED: (libc)Error Codes. |
| * ECONNRESET: (libc)Error Codes. |
| * ED: (libc)Error Codes. |
| * EDEADLK: (libc)Error Codes. |
| * EDEADLOCK: (libc)Error Codes. |
| * EDESTADDRREQ: (libc)Error Codes. |
| * EDIED: (libc)Error Codes. |
| * EDOM: (libc)Error Codes. |
| * EDOTDOT: (libc)Error Codes. |
| * EDQUOT: (libc)Error Codes. |
| * EEXIST: (libc)Error Codes. |
| * EFAULT: (libc)Error Codes. |
| * EFBIG: (libc)Error Codes. |
| * EFTYPE: (libc)Error Codes. |
| * EGRATUITOUS: (libc)Error Codes. |
| * EGREGIOUS: (libc)Error Codes. |
| * EHOSTDOWN: (libc)Error Codes. |
| * EHOSTUNREACH: (libc)Error Codes. |
| * EHWPOISON: (libc)Error Codes. |
| * EIDRM: (libc)Error Codes. |
| * EIEIO: (libc)Error Codes. |
| * EILSEQ: (libc)Error Codes. |
| * EINPROGRESS: (libc)Error Codes. |
| * EINTR: (libc)Error Codes. |
| * EINVAL: (libc)Error Codes. |
| * EIO: (libc)Error Codes. |
| * EISCONN: (libc)Error Codes. |
| * EISDIR: (libc)Error Codes. |
| * EISNAM: (libc)Error Codes. |
| * EKEYEXPIRED: (libc)Error Codes. |
| * EKEYREJECTED: (libc)Error Codes. |
| * EKEYREVOKED: (libc)Error Codes. |
| * EL2HLT: (libc)Error Codes. |
| * EL2NSYNC: (libc)Error Codes. |
| * EL3HLT: (libc)Error Codes. |
| * EL3RST: (libc)Error Codes. |
| * ELIBACC: (libc)Error Codes. |
| * ELIBBAD: (libc)Error Codes. |
| * ELIBEXEC: (libc)Error Codes. |
| * ELIBMAX: (libc)Error Codes. |
| * ELIBSCN: (libc)Error Codes. |
| * ELNRNG: (libc)Error Codes. |
| * ELOOP: (libc)Error Codes. |
| * EMEDIUMTYPE: (libc)Error Codes. |
| * EMFILE: (libc)Error Codes. |
| * EMLINK: (libc)Error Codes. |
| * EMSGSIZE: (libc)Error Codes. |
| * EMULTIHOP: (libc)Error Codes. |
| * ENAMETOOLONG: (libc)Error Codes. |
| * ENAVAIL: (libc)Error Codes. |
| * ENEEDAUTH: (libc)Error Codes. |
| * ENETDOWN: (libc)Error Codes. |
| * ENETRESET: (libc)Error Codes. |
| * ENETUNREACH: (libc)Error Codes. |
| * ENFILE: (libc)Error Codes. |
| * ENOANO: (libc)Error Codes. |
| * ENOBUFS: (libc)Error Codes. |
| * ENOCSI: (libc)Error Codes. |
| * ENODATA: (libc)Error Codes. |
| * ENODEV: (libc)Error Codes. |
| * ENOENT: (libc)Error Codes. |
| * ENOEXEC: (libc)Error Codes. |
| * ENOKEY: (libc)Error Codes. |
| * ENOLCK: (libc)Error Codes. |
| * ENOLINK: (libc)Error Codes. |
| * ENOMEDIUM: (libc)Error Codes. |
| * ENOMEM: (libc)Error Codes. |
| * ENOMSG: (libc)Error Codes. |
| * ENONET: (libc)Error Codes. |
| * ENOPKG: (libc)Error Codes. |
| * ENOPROTOOPT: (libc)Error Codes. |
| * ENOSPC: (libc)Error Codes. |
| * ENOSR: (libc)Error Codes. |
| * ENOSTR: (libc)Error Codes. |
| * ENOSYS: (libc)Error Codes. |
| * ENOTBLK: (libc)Error Codes. |
| * ENOTCONN: (libc)Error Codes. |
| * ENOTDIR: (libc)Error Codes. |
| * ENOTEMPTY: (libc)Error Codes. |
| * ENOTNAM: (libc)Error Codes. |
| * ENOTRECOVERABLE: (libc)Error Codes. |
| * ENOTSOCK: (libc)Error Codes. |
| * ENOTSUP: (libc)Error Codes. |
| * ENOTTY: (libc)Error Codes. |
| * ENOTUNIQ: (libc)Error Codes. |
| * ENXIO: (libc)Error Codes. |
| * EOF: (libc)EOF and Errors. |
| * EOPNOTSUPP: (libc)Error Codes. |
| * EOVERFLOW: (libc)Error Codes. |
| * EOWNERDEAD: (libc)Error Codes. |
| * EPERM: (libc)Error Codes. |
| * EPFNOSUPPORT: (libc)Error Codes. |
| * EPIPE: (libc)Error Codes. |
| * EPROCLIM: (libc)Error Codes. |
| * EPROCUNAVAIL: (libc)Error Codes. |
| * EPROGMISMATCH: (libc)Error Codes. |
| * EPROGUNAVAIL: (libc)Error Codes. |
| * EPROTO: (libc)Error Codes. |
| * EPROTONOSUPPORT: (libc)Error Codes. |
| * EPROTOTYPE: (libc)Error Codes. |
| * EQUIV_CLASS_MAX: (libc)Utility Limits. |
| * ERANGE: (libc)Error Codes. |
| * EREMCHG: (libc)Error Codes. |
| * EREMOTE: (libc)Error Codes. |
| * EREMOTEIO: (libc)Error Codes. |
| * ERESTART: (libc)Error Codes. |
| * ERFKILL: (libc)Error Codes. |
| * EROFS: (libc)Error Codes. |
| * ERPCMISMATCH: (libc)Error Codes. |
| * ESHUTDOWN: (libc)Error Codes. |
| * ESOCKTNOSUPPORT: (libc)Error Codes. |
| * ESPIPE: (libc)Error Codes. |
| * ESRCH: (libc)Error Codes. |
| * ESRMNT: (libc)Error Codes. |
| * ESTALE: (libc)Error Codes. |
| * ESTRPIPE: (libc)Error Codes. |
| * ETIME: (libc)Error Codes. |
| * ETIMEDOUT: (libc)Error Codes. |
| * ETOOMANYREFS: (libc)Error Codes. |
| * ETXTBSY: (libc)Error Codes. |
| * EUCLEAN: (libc)Error Codes. |
| * EUNATCH: (libc)Error Codes. |
| * EUSERS: (libc)Error Codes. |
| * EWOULDBLOCK: (libc)Error Codes. |
| * EXDEV: (libc)Error Codes. |
| * EXFULL: (libc)Error Codes. |
| * EXIT_FAILURE: (libc)Exit Status. |
| * EXIT_SUCCESS: (libc)Exit Status. |
| * EXPR_NEST_MAX: (libc)Utility Limits. |
| * FD_CLOEXEC: (libc)Descriptor Flags. |
| * FD_CLR: (libc)Waiting for I/O. |
| * FD_ISSET: (libc)Waiting for I/O. |
| * FD_SET: (libc)Waiting for I/O. |
| * FD_SETSIZE: (libc)Waiting for I/O. |
| * FD_ZERO: (libc)Waiting for I/O. |
| * FILENAME_MAX: (libc)Limits for Files. |
| * FLUSHO: (libc)Local Modes. |
| * FOPEN_MAX: (libc)Opening Streams. |
| * FP_ILOGB0: (libc)Exponents and Logarithms. |
| * FP_ILOGBNAN: (libc)Exponents and Logarithms. |
| * F_DUPFD: (libc)Duplicating Descriptors. |
| * F_GETFD: (libc)Descriptor Flags. |
| * F_GETFL: (libc)Getting File Status Flags. |
| * F_GETLK: (libc)File Locks. |
| * F_GETOWN: (libc)Interrupt Input. |
| * F_OK: (libc)Testing File Access. |
| * F_SETFD: (libc)Descriptor Flags. |
| * F_SETFL: (libc)Getting File Status Flags. |
| * F_SETLK: (libc)File Locks. |
| * F_SETLKW: (libc)File Locks. |
| * F_SETOWN: (libc)Interrupt Input. |
| * HUGE_VAL: (libc)Math Error Reporting. |
| * HUGE_VALF: (libc)Math Error Reporting. |
| * HUGE_VALL: (libc)Math Error Reporting. |
| * HUPCL: (libc)Control Modes. |
| * I: (libc)Complex Numbers. |
| * ICANON: (libc)Local Modes. |
| * ICRNL: (libc)Input Modes. |
| * IEXTEN: (libc)Local Modes. |
| * IFNAMSIZ: (libc)Interface Naming. |
| * IFTODT: (libc)Directory Entries. |
| * IGNBRK: (libc)Input Modes. |
| * IGNCR: (libc)Input Modes. |
| * IGNPAR: (libc)Input Modes. |
| * IMAXBEL: (libc)Input Modes. |
| * INADDR_ANY: (libc)Host Address Data Type. |
| * INADDR_BROADCAST: (libc)Host Address Data Type. |
| * INADDR_LOOPBACK: (libc)Host Address Data Type. |
| * INADDR_NONE: (libc)Host Address Data Type. |
| * INFINITY: (libc)Infinity and NaN. |
| * INLCR: (libc)Input Modes. |
| * INPCK: (libc)Input Modes. |
| * IPPORT_RESERVED: (libc)Ports. |
| * IPPORT_USERRESERVED: (libc)Ports. |
| * ISIG: (libc)Local Modes. |
| * ISTRIP: (libc)Input Modes. |
| * IXANY: (libc)Input Modes. |
| * IXOFF: (libc)Input Modes. |
| * IXON: (libc)Input Modes. |
| * LINE_MAX: (libc)Utility Limits. |
| * LINK_MAX: (libc)Limits for Files. |
| * L_ctermid: (libc)Identifying the Terminal. |
| * L_cuserid: (libc)Who Logged In. |
| * L_tmpnam: (libc)Temporary Files. |
| * MAXNAMLEN: (libc)Limits for Files. |
| * MAXSYMLINKS: (libc)Symbolic Links. |
| * MAX_CANON: (libc)Limits for Files. |
| * MAX_INPUT: (libc)Limits for Files. |
| * MB_CUR_MAX: (libc)Selecting the Conversion. |
| * MB_LEN_MAX: (libc)Selecting the Conversion. |
| * MDMBUF: (libc)Control Modes. |
| * MSG_DONTROUTE: (libc)Socket Data Options. |
| * MSG_OOB: (libc)Socket Data Options. |
| * MSG_PEEK: (libc)Socket Data Options. |
| * NAME_MAX: (libc)Limits for Files. |
| * NAN: (libc)Infinity and NaN. |
| * NCCS: (libc)Mode Data Types. |
| * NGROUPS_MAX: (libc)General Limits. |
| * NOFLSH: (libc)Local Modes. |
| * NOKERNINFO: (libc)Local Modes. |
| * NSIG: (libc)Standard Signals. |
| * NULL: (libc)Null Pointer Constant. |
| * ONLCR: (libc)Output Modes. |
| * ONOEOT: (libc)Output Modes. |
| * OPEN_MAX: (libc)General Limits. |
| * OPOST: (libc)Output Modes. |
| * OXTABS: (libc)Output Modes. |
| * O_ACCMODE: (libc)Access Modes. |
| * O_APPEND: (libc)Operating Modes. |
| * O_ASYNC: (libc)Operating Modes. |
| * O_CREAT: (libc)Open-time Flags. |
| * O_EXCL: (libc)Open-time Flags. |
| * O_EXEC: (libc)Access Modes. |
| * O_EXLOCK: (libc)Open-time Flags. |
| * O_FSYNC: (libc)Operating Modes. |
| * O_IGNORE_CTTY: (libc)Open-time Flags. |
| * O_NDELAY: (libc)Operating Modes. |
| * O_NOATIME: (libc)Operating Modes. |
| * O_NOCTTY: (libc)Open-time Flags. |
| * O_NOLINK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Open-time Flags. |
| * O_NONBLOCK: (libc)Operating Modes. |
| * O_NOTRANS: (libc)Open-time Flags. |
| * O_RDONLY: (libc)Access Modes. |
| * O_RDWR: (libc)Access Modes. |
| * O_READ: (libc)Access Modes. |
| * O_SHLOCK: (libc)Open-time Flags. |
| * O_SYNC: (libc)Operating Modes. |
| * O_TRUNC: (libc)Open-time Flags. |
| * O_WRITE: (libc)Access Modes. |
| * O_WRONLY: (libc)Access Modes. |
| * PARENB: (libc)Control Modes. |
| * PARMRK: (libc)Input Modes. |
| * PARODD: (libc)Control Modes. |
| * PATH_MAX: (libc)Limits for Files. |
| * PA_FLAG_MASK: (libc)Parsing a Template String. |
| * PENDIN: (libc)Local Modes. |
| * PF_FILE: (libc)Local Namespace Details. |
| * PF_INET6: (libc)Internet Namespace. |
| * PF_INET: (libc)Internet Namespace. |
| * PF_LOCAL: (libc)Local Namespace Details. |
| * PF_UNIX: (libc)Local Namespace Details. |
| * PIPE_BUF: (libc)Limits for Files. |
| * P_tmpdir: (libc)Temporary Files. |
| * RAND_MAX: (libc)ISO Random. |
| * RE_DUP_MAX: (libc)General Limits. |
| * RLIM_INFINITY: (libc)Limits on Resources. |
| * R_OK: (libc)Testing File Access. |
| * SA_NOCLDSTOP: (libc)Flags for Sigaction. |
| * SA_ONSTACK: (libc)Flags for Sigaction. |
| * SA_RESTART: (libc)Flags for Sigaction. |
| * SEEK_CUR: (libc)File Positioning. |
| * SEEK_END: (libc)File Positioning. |
| * SEEK_SET: (libc)File Positioning. |
| * SIGABRT: (libc)Program Error Signals. |
| * SIGALRM: (libc)Alarm Signals. |
| * SIGBUS: (libc)Program Error Signals. |
| * SIGCHLD: (libc)Job Control Signals. |
| * SIGCLD: (libc)Job Control Signals. |
| * SIGCONT: (libc)Job Control Signals. |
| * SIGEMT: (libc)Program Error Signals. |
| * SIGFPE: (libc)Program Error Signals. |
| * SIGHUP: (libc)Termination Signals. |
| * SIGILL: (libc)Program Error Signals. |
| * SIGINFO: (libc)Miscellaneous Signals. |
| * SIGINT: (libc)Termination Signals. |
| * SIGIO: (libc)Asynchronous I/O Signals. |
| * SIGIOT: (libc)Program Error Signals. |
| * SIGKILL: (libc)Termination Signals. |
| * SIGLOST: (libc)Operation Error Signals. |
| * SIGPIPE: (libc)Operation Error Signals. |
| * SIGPOLL: (libc)Asynchronous I/O Signals. |
| * SIGPROF: (libc)Alarm Signals. |
| * SIGQUIT: (libc)Termination Signals. |
| * SIGSEGV: (libc)Program Error Signals. |
| * SIGSTOP: (libc)Job Control Signals. |
| * SIGSYS: (libc)Program Error Signals. |
| * SIGTERM: (libc)Termination Signals. |
| * SIGTRAP: (libc)Program Error Signals. |
| * SIGTSTP: (libc)Job Control Signals. |
| * SIGTTIN: (libc)Job Control Signals. |
| * SIGTTOU: (libc)Job Control Signals. |
| * SIGURG: (libc)Asynchronous I/O Signals. |
| * SIGUSR1: (libc)Miscellaneous Signals. |
| * SIGUSR2: (libc)Miscellaneous Signals. |
| * SIGVTALRM: (libc)Alarm Signals. |
| * SIGWINCH: (libc)Miscellaneous Signals. |
| * SIGXCPU: (libc)Operation Error Signals. |
| * SIGXFSZ: (libc)Operation Error Signals. |
| * SIG_ERR: (libc)Basic Signal Handling. |
| * SOCK_DGRAM: (libc)Communication Styles. |
| * SOCK_RAW: (libc)Communication Styles. |
| * SOCK_RDM: (libc)Communication Styles. |
| * SOCK_SEQPACKET: (libc)Communication Styles. |
| * SOCK_STREAM: (libc)Communication Styles. |
| * SOL_SOCKET: (libc)Socket-Level Options. |
| * SSIZE_MAX: (libc)General Limits. |
| * STREAM_MAX: (libc)General Limits. |
| * SUN_LEN: (libc)Local Namespace Details. |
| * SV_INTERRUPT: (libc)BSD Handler. |
| * SV_ONSTACK: (libc)BSD Handler. |
| * SV_RESETHAND: (libc)BSD Handler. |
| * 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_low: (libc)PowerPC. |
| * __ppc_yield: (libc)PowerPC. |
| * __va_copy: (libc)Argument Macros. |
| * _exit: (libc)Termination Internals. |
| * _flushlbf: (libc)Flushing Buffers. |
| * _tolower: (libc)Case Conversion. |
| * _toupper: (libc)Case Conversion. |
| * a64l: (libc)Encode Binary Data. |
| * abort: (libc)Aborting a Program. |
| * abs: (libc)Absolute Value. |
| * accept: (libc)Accepting Connections. |
| * access: (libc)Testing File Access. |
| * acos: (libc)Inverse Trig Functions. |
| * acosf: (libc)Inverse Trig Functions. |
| * acosh: (libc)Hyperbolic Functions. |
| * acoshf: (libc)Hyperbolic Functions. |
| * acoshl: (libc)Hyperbolic Functions. |
| * acosl: (libc)Inverse Trig Functions. |
| * addmntent: (libc)mtab. |
| * addseverity: (libc)Adding Severity Classes. |
| * adjtime: (libc)High-Resolution Calendar. |
| * adjtimex: (libc)High-Resolution Calendar. |
| * aio_cancel64: (libc)Cancel AIO Operations. |
| * aio_cancel: (libc)Cancel AIO Operations. |
| * aio_error64: (libc)Status of AIO Operations. |
| * aio_error: (libc)Status of AIO Operations. |
| * aio_fsync64: (libc)Synchronizing AIO Operations. |
| * aio_fsync: (libc)Synchronizing AIO Operations. |
| * aio_init: (libc)Configuration of AIO. |
| * aio_read64: (libc)Asynchronous Reads/Writes. |
| * aio_read: (libc)Asynchronous Reads/Writes. |
| * aio_return64: (libc)Status of AIO Operations. |
| * aio_return: (libc)Status of AIO Operations. |
| * aio_suspend64: (libc)Synchronizing AIO Operations. |
| * aio_suspend: (libc)Synchronizing AIO Operations. |
| * aio_write64: (libc)Asynchronous Reads/Writes. |
| * aio_write: (libc)Asynchronous Reads/Writes. |
| * alarm: (libc)Setting an Alarm. |
| * aligned_alloc: (libc)Aligned Memory Blocks. |
| * alloca: (libc)Variable Size Automatic. |
| * alphasort64: (libc)Scanning Directory Content. |
| * alphasort: (libc)Scanning Directory Content. |
| * argp_error: (libc)Argp Helper Functions. |
| * argp_failure: (libc)Argp Helper Functions. |
| * argp_help: (libc)Argp Help. |
| * argp_parse: (libc)Argp. |
| * argp_state_help: (libc)Argp Helper Functions. |
| * argp_usage: (libc)Argp Helper Functions. |
| * argz_add: (libc)Argz Functions. |
| * argz_add_sep: (libc)Argz Functions. |
| * argz_append: (libc)Argz Functions. |
| * argz_count: (libc)Argz Functions. |
| * argz_create: (libc)Argz Functions. |
| * argz_create_sep: (libc)Argz Functions. |
| * argz_delete: (libc)Argz Functions. |
| * argz_extract: (libc)Argz Functions. |
| * argz_insert: (libc)Argz Functions. |
| * argz_next: (libc)Argz Functions. |
| * argz_replace: (libc)Argz Functions. |
| * argz_stringify: (libc)Argz Functions. |
| * asctime: (libc)Formatting Calendar Time. |
| * asctime_r: (libc)Formatting Calendar Time. |
| * asin: (libc)Inverse Trig Functions. |
| * asinf: (libc)Inverse Trig Functions. |
| * asinh: (libc)Hyperbolic Functions. |
| * asinhf: (libc)Hyperbolic Functions. |
| * asinhl: (libc)Hyperbolic Functions. |
| * asinl: (libc)Inverse Trig Functions. |
| * asprintf: (libc)Dynamic Output. |
| * assert: (libc)Consistency Checking. |
| * assert_perror: (libc)Consistency Checking. |
| * atan2: (libc)Inverse Trig Functions. |
| * atan2f: (libc)Inverse Trig Functions. |
| * atan2l: (libc)Inverse Trig Functions. |
| * atan: (libc)Inverse Trig Functions. |
| * atanf: (libc)Inverse Trig Functions. |
| * atanh: (libc)Hyperbolic Functions. |
| * atanhf: (libc)Hyperbolic Functions. |
| * atanhl: (libc)Hyperbolic Functions. |
| * atanl: (libc)Inverse Trig Functions. |
| * atexit: (libc)Cleanups on Exit. |
| * atof: (libc)Parsing of Floats. |
| * atoi: (libc)Parsing of Integers. |
| * atol: (libc)Parsing of Integers. |
| * atoll: (libc)Parsing of Integers. |
| * backtrace: (libc)Backtraces. |
| * backtrace_symbols: (libc)Backtraces. |
| * backtrace_symbols_fd: (libc)Backtraces. |
| * basename: (libc)Finding Tokens in a String. |
| * basename: (libc)Finding Tokens in a String. |
| * bcmp: (libc)String/Array Comparison. |
| * bcopy: (libc)Copying and Concatenation. |
| * 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 and Concatenation. |
| * cabs: (libc)Absolute Value. |
| * cabsf: (libc)Absolute Value. |
| * cabsl: (libc)Absolute Value. |
| * cacos: (libc)Inverse Trig Functions. |
| * cacosf: (libc)Inverse Trig Functions. |
| * cacosh: (libc)Hyperbolic Functions. |
| * cacoshf: (libc)Hyperbolic Functions. |
| * cacoshl: (libc)Hyperbolic Functions. |
| * cacosl: (libc)Inverse Trig Functions. |
| * calloc: (libc)Allocating Cleared Space. |
| * canonicalize_file_name: (libc)Symbolic Links. |
| * carg: (libc)Operations on Complex. |
| * cargf: (libc)Operations on Complex. |
| * cargl: (libc)Operations on Complex. |
| * casin: (libc)Inverse Trig Functions. |
| * casinf: (libc)Inverse Trig Functions. |
| * casinh: (libc)Hyperbolic Functions. |
| * casinhf: (libc)Hyperbolic Functions. |
| * casinhl: (libc)Hyperbolic Functions. |
| * casinl: (libc)Inverse Trig Functions. |
| * catan: (libc)Inverse Trig Functions. |
| * catanf: (libc)Inverse Trig Functions. |
| * catanh: (libc)Hyperbolic Functions. |
| * catanhf: (libc)Hyperbolic Functions. |
| * catanhl: (libc)Hyperbolic Functions. |
| * catanl: (libc)Inverse Trig Functions. |
| * catclose: (libc)The catgets Functions. |
| * catgets: (libc)The catgets Functions. |
| * catopen: (libc)The catgets Functions. |
| * cbc_crypt: (libc)DES Encryption. |
| * cbrt: (libc)Exponents and Logarithms. |
| * cbrtf: (libc)Exponents and Logarithms. |
| * cbrtl: (libc)Exponents and Logarithms. |
| * ccos: (libc)Trig Functions. |
| * ccosf: (libc)Trig Functions. |
| * ccosh: (libc)Hyperbolic Functions. |
| * ccoshf: (libc)Hyperbolic Functions. |
| * ccoshl: (libc)Hyperbolic Functions. |
| * ccosl: (libc)Trig Functions. |
| * ceil: (libc)Rounding Functions. |
| * ceilf: (libc)Rounding Functions. |
| * ceill: (libc)Rounding Functions. |
| * cexp: (libc)Exponents and Logarithms. |
| * cexpf: (libc)Exponents and Logarithms. |
| * cexpl: (libc)Exponents and Logarithms. |
| * cfgetispeed: (libc)Line Speed. |
| * cfgetospeed: (libc)Line Speed. |
| * cfmakeraw: (libc)Noncanonical Input. |
| * cfree: (libc)Freeing after Malloc. |
| * cfsetispeed: (libc)Line Speed. |
| * cfsetospeed: (libc)Line Speed. |
| * cfsetspeed: (libc)Line Speed. |
| * chdir: (libc)Working Directory. |
| * chmod: (libc)Setting Permissions. |
| * chown: (libc)File Owner. |
| * cimag: (libc)Operations on Complex. |
| * cimagf: (libc)Operations on Complex. |
| * cimagl: (libc)Operations on Complex. |
| * clearenv: (libc)Environment Access. |
| * clearerr: (libc)Error Recovery. |
| * clearerr_unlocked: (libc)Error Recovery. |
| * clock: (libc)CPU Time. |
| * clog10: (libc)Exponents and Logarithms. |
| * clog10f: (libc)Exponents and Logarithms. |
| * clog10l: (libc)Exponents and Logarithms. |
| * clog: (libc)Exponents and Logarithms. |
| * clogf: (libc)Exponents and Logarithms. |
| * clogl: (libc)Exponents and Logarithms. |
| * close: (libc)Opening and Closing Files. |
| * closedir: (libc)Reading/Closing Directory. |
| * closelog: (libc)closelog. |
| * confstr: (libc)String Parameters. |
| * conj: (libc)Operations on Complex. |
| * conjf: (libc)Operations on Complex. |
| * conjl: (libc)Operations on Complex. |
| * connect: (libc)Connecting. |
| * copysign: (libc)FP Bit Twiddling. |
| * copysignf: (libc)FP Bit Twiddling. |
| * copysignl: (libc)FP Bit Twiddling. |
| * cos: (libc)Trig Functions. |
| * cosf: (libc)Trig Functions. |
| * cosh: (libc)Hyperbolic Functions. |
| * coshf: (libc)Hyperbolic Functions. |
| * coshl: (libc)Hyperbolic Functions. |
| * cosl: (libc)Trig Functions. |
| * cpow: (libc)Exponents and Logarithms. |
| * cpowf: (libc)Exponents and Logarithms. |
| * cpowl: (libc)Exponents and Logarithms. |
| * cproj: (libc)Operations on Complex. |
| * cprojf: (libc)Operations on Complex. |
| * cprojl: (libc)Operations on Complex. |
| * creal: (libc)Operations on Complex. |
| * crealf: (libc)Operations on Complex. |
| * creall: (libc)Operations on Complex. |
| * creat64: (libc)Opening and Closing Files. |
| * creat: (libc)Opening and Closing Files. |
| * crypt: (libc)crypt. |
| * crypt_r: (libc)crypt. |
| * csin: (libc)Trig Functions. |
| * csinf: (libc)Trig Functions. |
| * csinh: (libc)Hyperbolic Functions. |
| * csinhf: (libc)Hyperbolic Functions. |
| * csinhl: (libc)Hyperbolic Functions. |
| * csinl: (libc)Trig Functions. |
| * csqrt: (libc)Exponents and Logarithms. |
| * csqrtf: (libc)Exponents and Logarithms. |
| * csqrtl: (libc)Exponents and Logarithms. |
| * ctan: (libc)Trig Functions. |
| * ctanf: (libc)Trig Functions. |
| * ctanh: (libc)Hyperbolic Functions. |
| * ctanhf: (libc)Hyperbolic Functions. |
| * ctanhl: (libc)Hyperbolic Functions. |
| * ctanl: (libc)Trig Functions. |
| * ctermid: (libc)Identifying the Terminal. |
| * ctime: (libc)Formatting Calendar Time. |
| * ctime_r: (libc)Formatting Calendar Time. |
| * cuserid: (libc)Who Logged In. |
| * dcgettext: (libc)Translation with gettext. |
| * dcngettext: (libc)Advanced gettext functions. |
| * des_setparity: (libc)DES Encryption. |
| * dgettext: (libc)Translation with gettext. |
| * difftime: (libc)Elapsed Time. |
| * dirfd: (libc)Opening a Directory. |
| * dirname: (libc)Finding Tokens in a String. |
| * div: (libc)Integer Division. |
| * dngettext: (libc)Advanced gettext functions. |
| * drand48: (libc)SVID Random. |
| * drand48_r: (libc)SVID Random. |
| * drem: (libc)Remainder Functions. |
| * dremf: (libc)Remainder Functions. |
| * dreml: (libc)Remainder Functions. |
| * dup2: (libc)Duplicating Descriptors. |
| * dup: (libc)Duplicating Descriptors. |
| * ecb_crypt: (libc)DES Encryption. |
| * ecvt: (libc)System V Number Conversion. |
| * ecvt_r: (libc)System V Number Conversion. |
| * encrypt: (libc)DES Encryption. |
| * encrypt_r: (libc)DES Encryption. |
| * endfsent: (libc)fstab. |
| * endgrent: (libc)Scanning All Groups. |
| * endhostent: (libc)Host Names. |
| * endmntent: (libc)mtab. |
| * endnetent: (libc)Networks Database. |
| * endnetgrent: (libc)Lookup Netgroup. |
| * endprotoent: (libc)Protocols Database. |
| * endpwent: (libc)Scanning All Users. |
| * endservent: (libc)Services Database. |
| * endutent: (libc)Manipulating the Database. |
| * endutxent: (libc)XPG Functions. |
| * envz_add: (libc)Envz Functions. |
| * envz_entry: (libc)Envz Functions. |
| * envz_get: (libc)Envz Functions. |
| * envz_merge: (libc)Envz Functions. |
| * envz_strip: (libc)Envz Functions. |
| * erand48: (libc)SVID Random. |
| * erand48_r: (libc)SVID Random. |
| * erf: (libc)Special Functions. |
| * erfc: (libc)Special Functions. |
| * erfcf: (libc)Special Functions. |
| * erfcl: (libc)Special Functions. |
| * erff: (libc)Special Functions. |
| * erfl: (libc)Special Functions. |
| * err: (libc)Error Messages. |
| * errno: (libc)Checking for Errors. |
| * error: (libc)Error Messages. |
| * error_at_line: (libc)Error Messages. |
| * errx: (libc)Error Messages. |
| * execl: (libc)Executing a File. |
| * execle: (libc)Executing a File. |
| * execlp: (libc)Executing a File. |
| * execv: (libc)Executing a File. |
| * execve: (libc)Executing a File. |
| * execvp: (libc)Executing a File. |
| * exit: (libc)Normal Termination. |
| * exp10: (libc)Exponents and Logarithms. |
| * exp10f: (libc)Exponents and Logarithms. |
| * exp10l: (libc)Exponents and Logarithms. |
| * exp2: (libc)Exponents and Logarithms. |
| * exp2f: (libc)Exponents and Logarithms. |
| * exp2l: (libc)Exponents and Logarithms. |
| * exp: (libc)Exponents and Logarithms. |
| * expf: (libc)Exponents and Logarithms. |
| * expl: (libc)Exponents and Logarithms. |
| * expm1: (libc)Exponents and Logarithms. |
| * expm1f: (libc)Exponents and Logarithms. |
| * expm1l: (libc)Exponents and Logarithms. |
| * fabs: (libc)Absolute Value. |
| * fabsf: (libc)Absolute Value. |
| * fabsl: (libc)Absolute Value. |
| * fchdir: (libc)Working Directory. |
| * fchmod: (libc)Setting Permissions. |
| * fchown: (libc)File Owner. |
| * fclose: (libc)Closing Streams. |
| * fcloseall: (libc)Closing Streams. |
| * fcntl: (libc)Control Operations. |
| * fcvt: (libc)System V Number Conversion. |
| * fcvt_r: (libc)System V Number Conversion. |
| * fdatasync: (libc)Synchronizing I/O. |
| * fdim: (libc)Misc FP Arithmetic. |
| * fdimf: (libc)Misc FP Arithmetic. |
| * fdiml: (libc)Misc FP Arithmetic. |
| * fdopen: (libc)Descriptors and Streams. |
| * fdopendir: (libc)Opening a Directory. |
| * feclearexcept: (libc)Status bit operations. |
| * fedisableexcept: (libc)Control Functions. |
| * feenableexcept: (libc)Control Functions. |
| * fegetenv: (libc)Control Functions. |
| * fegetexcept: (libc)Control Functions. |
| * fegetexceptflag: (libc)Status bit operations. |
| * fegetround: (libc)Rounding. |
| * feholdexcept: (libc)Control Functions. |
| * feof: (libc)EOF and Errors. |
| * feof_unlocked: (libc)EOF and Errors. |
| * feraiseexcept: (libc)Status bit operations. |
| * ferror: (libc)EOF and Errors. |
| * ferror_unlocked: (libc)EOF and Errors. |
| * fesetenv: (libc)Control Functions. |
| * fesetexceptflag: (libc)Status bit operations. |
| * fesetround: (libc)Rounding. |
| * fetestexcept: (libc)Status bit operations. |
| * feupdateenv: (libc)Control Functions. |
| * fflush: (libc)Flushing Buffers. |
| * fflush_unlocked: (libc)Flushing Buffers. |
| * fgetc: (libc)Character Input. |
| * fgetc_unlocked: (libc)Character Input. |
| * fgetgrent: (libc)Scanning All Groups. |
| * fgetgrent_r: (libc)Scanning All Groups. |
| * fgetpos64: (libc)Portable Positioning. |
| * fgetpos: (libc)Portable Positioning. |
| * fgetpwent: (libc)Scanning All Users. |
| * fgetpwent_r: (libc)Scanning All Users. |
| * fgets: (libc)Line Input. |
| * fgets_unlocked: (libc)Line Input. |
| * fgetwc: (libc)Character Input. |
| * fgetwc_unlocked: (libc)Character Input. |
| * fgetws: (libc)Line Input. |
| * fgetws_unlocked: (libc)Line Input. |
| * fileno: (libc)Descriptors and Streams. |
| * fileno_unlocked: (libc)Descriptors and Streams. |
| * finite: (libc)Floating Point Classes. |
| * finitef: (libc)Floating Point Classes. |
| * finitel: (libc)Floating Point Classes. |
| * flockfile: (libc)Streams and Threads. |
| * floor: (libc)Rounding Functions. |
| * floorf: (libc)Rounding Functions. |
| * floorl: (libc)Rounding Functions. |
| * fma: (libc)Misc FP Arithmetic. |
| * fmaf: (libc)Misc FP Arithmetic. |
| * fmal: (libc)Misc FP Arithmetic. |
| * fmax: (libc)Misc FP Arithmetic. |
| * fmaxf: (libc)Misc FP Arithmetic. |
| * fmaxl: (libc)Misc FP Arithmetic. |
| * fmemopen: (libc)String Streams. |
| * fmin: (libc)Misc FP Arithmetic. |
| * fminf: (libc)Misc FP Arithmetic. |
| * fminl: (libc)Misc FP Arithmetic. |
| * fmod: (libc)Remainder Functions. |
| * fmodf: (libc)Remainder Functions. |
| * fmodl: (libc)Remainder Functions. |
| * fmtmsg: (libc)Printing Formatted Messages. |
| * fnmatch: (libc)Wildcard Matching. |
| * fopen64: (libc)Opening Streams. |
| * fopen: (libc)Opening Streams. |
| * fopencookie: (libc)Streams and Cookies. |
| * fork: (libc)Creating a Process. |
| * forkpty: (libc)Pseudo-Terminal Pairs. |
| * fpathconf: (libc)Pathconf. |
| * fpclassify: (libc)Floating Point Classes. |
| * fprintf: (libc)Formatted Output Functions. |
| * fputc: (libc)Simple Output. |
| * fputc_unlocked: (libc)Simple Output. |
| * fputs: (libc)Simple Output. |
| * fputs_unlocked: (libc)Simple Output. |
| * fputwc: (libc)Simple Output. |
| * fputwc_unlocked: (libc)Simple Output. |
| * fputws: (libc)Simple Output. |
| * fputws_unlocked: (libc)Simple Output. |
| * fread: (libc)Block Input/Output. |
| * fread_unlocked: (libc)Block Input/Output. |
| * free: (libc)Freeing after Malloc. |
| * freopen64: (libc)Opening Streams. |
| * freopen: (libc)Opening Streams. |
| * frexp: (libc)Normalization Functions. |
| * frexpf: (libc)Normalization Functions. |
| * frexpl: (libc)Normalization Functions. |
| * fscanf: (libc)Formatted Input Functions. |
| * fseek: (libc)File Positioning. |
| * fseeko64: (libc)File Positioning. |
| * fseeko: (libc)File Positioning. |
| * fsetpos64: (libc)Portable Positioning. |
| * fsetpos: (libc)Portable Positioning. |
| * fstat64: (libc)Reading Attributes. |
| * fstat: (libc)Reading Attributes. |
| * fsync: (libc)Synchronizing I/O. |
| * ftell: (libc)File Positioning. |
| * ftello64: (libc)File Positioning. |
| * ftello: (libc)File Positioning. |
| * ftruncate64: (libc)File Size. |
| * ftruncate: (libc)File Size. |
| * ftrylockfile: (libc)Streams and Threads. |
| * ftw64: (libc)Working with Directory Trees. |
| * ftw: (libc)Working with Directory Trees. |
| * funlockfile: (libc)Streams and Threads. |
| * futimes: (libc)File Times. |
| * fwide: (libc)Streams and I18N. |
| * fwprintf: (libc)Formatted Output Functions. |
| * fwrite: (libc)Block Input/Output. |
| * fwrite_unlocked: (libc)Block Input/Output. |
| * fwscanf: (libc)Formatted Input Functions. |
| * gamma: (libc)Special Functions. |
| * gammaf: (libc)Special Functions. |
| * gammal: (libc)Special Functions. |
| * gcvt: (libc)System V Number Conversion. |
| * get_avphys_pages: (libc)Query Memory Parameters. |
| * get_current_dir_name: (libc)Working Directory. |
| * get_nprocs: (libc)Processor Resources. |
| * get_nprocs_conf: (libc)Processor Resources. |
| * get_phys_pages: (libc)Query Memory Parameters. |
| * getauxval: (libc)Auxiliary Vector. |
| * getc: (libc)Character Input. |
| * getc_unlocked: (libc)Character Input. |
| * getchar: (libc)Character Input. |
| * getchar_unlocked: (libc)Character Input. |
| * getcontext: (libc)System V contexts. |
| * getcwd: (libc)Working Directory. |
| * getdate: (libc)General Time String Parsing. |
| * getdate_r: (libc)General Time String Parsing. |
| * getdelim: (libc)Line Input. |
| * getdomainnname: (libc)Host Identification. |
| * getegid: (libc)Reading Persona. |
| * getenv: (libc)Environment Access. |
| * geteuid: (libc)Reading Persona. |
| * getfsent: (libc)fstab. |
| * getfsfile: (libc)fstab. |
| * getfsspec: (libc)fstab. |
| * getgid: (libc)Reading Persona. |
| * getgrent: (libc)Scanning All Groups. |
| * getgrent_r: (libc)Scanning All Groups. |
| * getgrgid: (libc)Lookup Group. |
| * getgrgid_r: (libc)Lookup Group. |
| * getgrnam: (libc)Lookup Group. |
| * getgrnam_r: (libc)Lookup Group. |
| * getgrouplist: (libc)Setting Groups. |
| * getgroups: (libc)Reading Persona. |
| * gethostbyaddr: (libc)Host Names. |
| * gethostbyaddr_r: (libc)Host Names. |
| * gethostbyname2: (libc)Host Names. |
| * gethostbyname2_r: (libc)Host Names. |
| * gethostbyname: (libc)Host Names. |
| * gethostbyname_r: (libc)Host Names. |
| * gethostent: (libc)Host Names. |
| * gethostid: (libc)Host Identification. |
| * gethostname: (libc)Host Identification. |
| * getitimer: (libc)Setting an Alarm. |
| * getline: (libc)Line Input. |
| * getloadavg: (libc)Processor Resources. |
| * getlogin: (libc)Who Logged In. |
| * getmntent: (libc)mtab. |
| * getmntent_r: (libc)mtab. |
| * getnetbyaddr: (libc)Networks Database. |
| * getnetbyname: (libc)Networks Database. |
| * getnetent: (libc)Networks Database. |
| * getnetgrent: (libc)Lookup Netgroup. |
| * getnetgrent_r: (libc)Lookup Netgroup. |
| * getopt: (libc)Using Getopt. |
| * getopt_long: (libc)Getopt Long Options. |
| * getopt_long_only: (libc)Getopt Long Options. |
| * getpagesize: (libc)Query Memory Parameters. |
| * getpass: (libc)getpass. |
| * getpeername: (libc)Who is Connected. |
| * getpgid: (libc)Process Group Functions. |
| * getpgrp: (libc)Process Group Functions. |
| * getpid: (libc)Process Identification. |
| * getppid: (libc)Process Identification. |
| * getpriority: (libc)Traditional Scheduling Functions. |
| * getprotobyname: (libc)Protocols Database. |
| * getprotobynumber: (libc)Protocols Database. |
| * getprotoent: (libc)Protocols Database. |
| * getpt: (libc)Allocation. |
| * getpwent: (libc)Scanning All Users. |
| * getpwent_r: (libc)Scanning All Users. |
| * getpwnam: (libc)Lookup User. |
| * getpwnam_r: (libc)Lookup User. |
| * getpwuid: (libc)Lookup User. |
| * getpwuid_r: (libc)Lookup User. |
| * getrlimit64: (libc)Limits on Resources. |
| * getrlimit: (libc)Limits on Resources. |
| * getrusage: (libc)Resource Usage. |
| * gets: (libc)Line Input. |
| * getservbyname: (libc)Services Database. |
| * getservbyport: (libc)Services Database. |
| * getservent: (libc)Services Database. |
| * getsid: (libc)Process Group Functions. |
| * getsockname: (libc)Reading Address. |
| * getsockopt: (libc)Socket Option Functions. |
| * getsubopt: (libc)Suboptions. |
| * gettext: (libc)Translation with gettext. |
| * gettimeofday: (libc)High-Resolution Calendar. |
| * getuid: (libc)Reading Persona. |
| * getumask: (libc)Setting Permissions. |
| * getutent: (libc)Manipulating the Database. |
| * getutent_r: (libc)Manipulating the Database. |
| * getutid: (libc)Manipulating the Database. |
| * getutid_r: (libc)Manipulating the Database. |
| * getutline: (libc)Manipulating the Database. |
| * getutline_r: (libc)Manipulating the Database. |
| * getutmp: (libc)XPG Functions. |
| * getutmpx: (libc)XPG Functions. |
| * getutxent: (libc)XPG Functions. |
| * getutxid: (libc)XPG Functions. |
| * getutxline: (libc)XPG Functions. |
| * getw: (libc)Character Input. |
| * getwc: (libc)Character Input. |
| * getwc_unlocked: (libc)Character Input. |
| * getwchar: (libc)Character Input. |
| * getwchar_unlocked: (libc)Character Input. |
| * getwd: (libc)Working Directory. |
| * glob64: (libc)Calling Glob. |
| * glob: (libc)Calling Glob. |
| * globfree64: (libc)More Flags for Globbing. |
| * globfree: (libc)More Flags for Globbing. |
| * gmtime: (libc)Broken-down Time. |
| * gmtime_r: (libc)Broken-down Time. |
| * grantpt: (libc)Allocation. |
| * gsignal: (libc)Signaling Yourself. |
| * gtty: (libc)BSD Terminal Modes. |
| * hasmntopt: (libc)mtab. |
| * hcreate: (libc)Hash Search Function. |
| * hcreate_r: (libc)Hash Search Function. |
| * hdestroy: (libc)Hash Search Function. |
| * hdestroy_r: (libc)Hash Search Function. |
| * hsearch: (libc)Hash Search Function. |
| * hsearch_r: (libc)Hash Search Function. |
| * htonl: (libc)Byte Order. |
| * htons: (libc)Byte Order. |
| * hypot: (libc)Exponents and Logarithms. |
| * hypotf: (libc)Exponents and Logarithms. |
| * hypotl: (libc)Exponents and Logarithms. |
| * iconv: (libc)Generic Conversion Interface. |
| * iconv_close: (libc)Generic Conversion Interface. |
| * iconv_open: (libc)Generic Conversion Interface. |
| * if_freenameindex: (libc)Interface Naming. |
| * if_indextoname: (libc)Interface Naming. |
| * if_nameindex: (libc)Interface Naming. |
| * if_nametoindex: (libc)Interface Naming. |
| * ilogb: (libc)Exponents and Logarithms. |
| * ilogbf: (libc)Exponents and Logarithms. |
| * ilogbl: (libc)Exponents and Logarithms. |
| * imaxabs: (libc)Absolute Value. |
| * imaxdiv: (libc)Integer Division. |
| * in6addr_any: (libc)Host Address Data Type. |
| * in6addr_loopback: (libc)Host Address Data Type. |
| * index: (libc)Search Functions. |
| * inet_addr: (libc)Host Address Functions. |
| * inet_aton: (libc)Host Address Functions. |
| * inet_lnaof: (libc)Host Address Functions. |
| * inet_makeaddr: (libc)Host Address Functions. |
| * inet_netof: (libc)Host Address Functions. |
| * inet_network: (libc)Host Address Functions. |
| * inet_ntoa: (libc)Host Address Functions. |
| * inet_ntop: (libc)Host Address Functions. |
| * inet_pton: (libc)Host Address Functions. |
| * initgroups: (libc)Setting Groups. |
| * initstate: (libc)BSD Random. |
| * initstate_r: (libc)BSD Random. |
| * innetgr: (libc)Netgroup Membership. |
| * ioctl: (libc)IOCTLs. |
| * isalnum: (libc)Classification of Characters. |
| * isalpha: (libc)Classification of Characters. |
| * isascii: (libc)Classification of Characters. |
| * isatty: (libc)Is It a Terminal. |
| * isblank: (libc)Classification of Characters. |
| * iscntrl: (libc)Classification of Characters. |
| * isdigit: (libc)Classification of Characters. |
| * isfinite: (libc)Floating Point Classes. |
| * isgraph: (libc)Classification of Characters. |
| * isgreater: (libc)FP Comparison Functions. |
| * isgreaterequal: (libc)FP Comparison Functions. |
| * isinf: (libc)Floating Point Classes. |
| * isinff: (libc)Floating Point Classes. |
| * isinfl: (libc)Floating Point Classes. |
| * isless: (libc)FP Comparison Functions. |
| * islessequal: (libc)FP Comparison Functions. |
| * islessgreater: (libc)FP Comparison Functions. |
| * islower: (libc)Classification of Characters. |
| * isnan: (libc)Floating Point Classes. |
| * isnan: (libc)Floating Point Classes. |
| * isnanf: (libc)Floating Point Classes. |
| * isnanl: (libc)Floating Point Classes. |
| * isnormal: (libc)Floating Point Classes. |
| * isprint: (libc)Classification of Characters. |
| * ispunct: (libc)Classification of Characters. |
| * issignaling: (libc)Floating Point Classes. |
| * isspace: (libc)Classification of Characters. |
| * isunordered: (libc)FP Comparison Functions. |
| * isupper: (libc)Classification of Characters. |
| * iswalnum: (libc)Classification of Wide Characters. |
| * iswalpha: (libc)Classification of Wide Characters. |
| * iswblank: (libc)Classification of Wide Characters. |
| * iswcntrl: (libc)Classification of Wide Characters. |
| * iswctype: (libc)Classification of Wide Characters. |
| * iswdigit: (libc)Classification of Wide Characters. |
| * iswgraph: (libc)Classification of Wide Characters. |
| * iswlower: (libc)Classification of Wide Characters. |
| * iswprint: (libc)Classification of Wide Characters. |
| * iswpunct: (libc)Classification of Wide Characters. |
| * iswspace: (libc)Classification of Wide Characters. |
| * iswupper: (libc)Classification of Wide Characters. |
| * iswxdigit: (libc)Classification of Wide Characters. |
| * isxdigit: (libc)Classification of Characters. |
| * j0: (libc)Special Functions. |
| * j0f: (libc)Special Functions. |
| * j0l: (libc)Special Functions. |
| * j1: (libc)Special Functions. |
| * j1f: (libc)Special Functions. |
| * j1l: (libc)Special Functions. |
| * jn: (libc)Special Functions. |
| * jnf: (libc)Special Functions. |
| * jnl: (libc)Special Functions. |
| * jrand48: (libc)SVID Random. |
| * jrand48_r: (libc)SVID Random. |
| * kill: (libc)Signaling Another Process. |
| * killpg: (libc)Signaling Another Process. |
| * l64a: (libc)Encode Binary Data. |
| * labs: (libc)Absolute Value. |
| * lcong48: (libc)SVID Random. |
| * lcong48_r: (libc)SVID Random. |
| * ldexp: (libc)Normalization Functions. |
| * ldexpf: (libc)Normalization Functions. |
| * ldexpl: (libc)Normalization Functions. |
| * ldiv: (libc)Integer Division. |
| * lfind: (libc)Array Search Function. |
| * lgamma: (libc)Special Functions. |
| * lgamma_r: (libc)Special Functions. |
| * lgammaf: (libc)Special Functions. |
| * lgammaf_r: (libc)Special Functions. |
| * lgammal: (libc)Special Functions. |
| * lgammal_r: (libc)Special Functions. |
| * link: (libc)Hard Links. |
| * lio_listio64: (libc)Asynchronous Reads/Writes. |
| * lio_listio: (libc)Asynchronous Reads/Writes. |
| * listen: (libc)Listening. |
| * llabs: (libc)Absolute Value. |
| * lldiv: (libc)Integer Division. |
| * llrint: (libc)Rounding Functions. |
| * llrintf: (libc)Rounding Functions. |
| * llrintl: (libc)Rounding Functions. |
| * llround: (libc)Rounding Functions. |
| * llroundf: (libc)Rounding Functions. |
| * llroundl: (libc)Rounding Functions. |
| * localeconv: (libc)The Lame Way to Locale Data. |
| * localtime: (libc)Broken-down Time. |
| * localtime_r: (libc)Broken-down Time. |
| * log10: (libc)Exponents and Logarithms. |
| * log10f: (libc)Exponents and Logarithms. |
| * log10l: (libc)Exponents and Logarithms. |
| * log1p: (libc)Exponents and Logarithms. |
| * log1pf: (libc)Exponents and Logarithms. |
| * log1pl: (libc)Exponents and Logarithms. |
| * log2: (libc)Exponents and Logarithms. |
| * log2f: (libc)Exponents and Logarithms. |
| * log2l: (libc)Exponents and Logarithms. |
| * log: (libc)Exponents and Logarithms. |
| * logb: (libc)Exponents and Logarithms. |
| * logbf: (libc)Exponents and Logarithms. |
| * logbl: (libc)Exponents and Logarithms. |
| * logf: (libc)Exponents and Logarithms. |
| * login: (libc)Logging In and Out. |
| * login_tty: (libc)Logging In and Out. |
| * logl: (libc)Exponents and Logarithms. |
| * logout: (libc)Logging In and Out. |
| * logwtmp: (libc)Logging In and Out. |
| * longjmp: (libc)Non-Local Details. |
| * lrand48: (libc)SVID Random. |
| * lrand48_r: (libc)SVID Random. |
| * lrint: (libc)Rounding Functions. |
| * lrintf: (libc)Rounding Functions. |
| * lrintl: (libc)Rounding Functions. |
| * lround: (libc)Rounding Functions. |
| * lroundf: (libc)Rounding Functions. |
| * lroundl: (libc)Rounding Functions. |
| * lsearch: (libc)Array Search Function. |
| * lseek64: (libc)File Position Primitive. |
| * lseek: (libc)File Position Primitive. |
| * lstat64: (libc)Reading Attributes. |
| * lstat: (libc)Reading Attributes. |
| * lutimes: (libc)File Times. |
| * madvise: (libc)Memory-mapped I/O. |
| * makecontext: (libc)System V contexts. |
| * mallinfo: (libc)Statistics of Malloc. |
| * malloc: (libc)Basic Allocation. |
| * mallopt: (libc)Malloc Tunable Parameters. |
| * mblen: (libc)Non-reentrant Character Conversion. |
| * mbrlen: (libc)Converting a Character. |
| * mbrtowc: (libc)Converting a Character. |
| * mbsinit: (libc)Keeping the state. |
| * mbsnrtowcs: (libc)Converting Strings. |
| * mbsrtowcs: (libc)Converting Strings. |
| * mbstowcs: (libc)Non-reentrant String Conversion. |
| * mbtowc: (libc)Non-reentrant Character Conversion. |
| * mcheck: (libc)Heap Consistency Checking. |
| * memalign: (libc)Aligned Memory Blocks. |
| * memccpy: (libc)Copying and Concatenation. |
| * memchr: (libc)Search Functions. |
| * memcmp: (libc)String/Array Comparison. |
| * memcpy: (libc)Copying and Concatenation. |
| * memfrob: (libc)Trivial Encryption. |
| * memmem: (libc)Search Functions. |
| * memmove: (libc)Copying and Concatenation. |
| * mempcpy: (libc)Copying and Concatenation. |
| * memrchr: (libc)Search Functions. |
| * memset: (libc)Copying and Concatenation. |
| * mkdir: (libc)Creating Directories. |
| * mkdtemp: (libc)Temporary Files. |
| * mkfifo: (libc)FIFO Special Files. |
| * mknod: (libc)Making Special Files. |
| * mkstemp: (libc)Temporary Files. |
| * mktemp: (libc)Temporary Files. |
| * mktime: (libc)Broken-down Time. |
| * mlock: (libc)Page Lock Functions. |
| * mlockall: (libc)Page Lock Functions. |
| * mmap64: (libc)Memory-mapped I/O. |
| * mmap: (libc)Memory-mapped I/O. |
| * modf: (libc)Rounding Functions. |
| * modff: (libc)Rounding Functions. |
| * modfl: (libc)Rounding Functions. |
| * mount: (libc)Mount-Unmount-Remount. |
| * mprobe: (libc)Heap Consistency Checking. |
| * mrand48: (libc)SVID Random. |
| * mrand48_r: (libc)SVID Random. |
| * mremap: (libc)Memory-mapped I/O. |
| * msync: (libc)Memory-mapped I/O. |
| * mtrace: (libc)Tracing malloc. |
| * munlock: (libc)Page Lock Functions. |
| * munlockall: (libc)Page Lock Functions. |
| * munmap: (libc)Memory-mapped I/O. |
| * muntrace: (libc)Tracing malloc. |
| * nan: (libc)FP Bit Twiddling. |
| * nanf: (libc)FP Bit Twiddling. |
| * nanl: (libc)FP Bit Twiddling. |
| * nanosleep: (libc)Sleeping. |
| * nearbyint: (libc)Rounding Functions. |
| * nearbyintf: (libc)Rounding Functions. |
| * nearbyintl: (libc)Rounding Functions. |
| * nextafter: (libc)FP Bit Twiddling. |
| * nextafterf: (libc)FP Bit Twiddling. |
| * nextafterl: (libc)FP Bit Twiddling. |
| * nexttoward: (libc)FP Bit Twiddling. |
| * nexttowardf: (libc)FP Bit Twiddling. |
| * nexttowardl: (libc)FP Bit Twiddling. |
| * nftw64: (libc)Working with Directory Trees. |
| * nftw: (libc)Working with Directory Trees. |
| * ngettext: (libc)Advanced gettext functions. |
| * nice: (libc)Traditional Scheduling Functions. |
| * nl_langinfo: (libc)The Elegant and Fast Way. |
| * nrand48: (libc)SVID Random. |
| * nrand48_r: (libc)SVID Random. |
| * ntohl: (libc)Byte Order. |
| * ntohs: (libc)Byte Order. |
| * ntp_adjtime: (libc)High Accuracy Clock. |
| * ntp_gettime: (libc)High Accuracy Clock. |
| * obstack_1grow: (libc)Growing Objects. |
| * obstack_1grow_fast: (libc)Extra Fast Growing. |
| * obstack_alignment_mask: (libc)Obstacks Data Alignment. |
| * obstack_alloc: (libc)Allocation in an Obstack. |
| * obstack_base: (libc)Status of an Obstack. |
| * obstack_blank: (libc)Growing Objects. |
| * obstack_blank_fast: (libc)Extra Fast Growing. |
| * obstack_chunk_size: (libc)Obstack Chunks. |
| * obstack_copy0: (libc)Allocation in an Obstack. |
| * obstack_copy: (libc)Allocation in an Obstack. |
| * obstack_finish: (libc)Growing Objects. |
| * obstack_free: (libc)Freeing Obstack Objects. |
| * obstack_grow0: (libc)Growing Objects. |
| * obstack_grow: (libc)Growing Objects. |
| * obstack_init: (libc)Preparing for Obstacks. |
| * obstack_int_grow: (libc)Growing Objects. |
| * obstack_int_grow_fast: (libc)Extra Fast Growing. |
| * obstack_next_free: (libc)Status of an Obstack. |
| * obstack_object_size: (libc)Growing Objects. |
| * obstack_object_size: (libc)Status of an Obstack. |
| * obstack_printf: (libc)Dynamic Output. |
| * obstack_ptr_grow: (libc)Growing Objects. |
| * obstack_ptr_grow_fast: (libc)Extra Fast Growing. |
| * obstack_room: (libc)Extra Fast Growing. |
| * obstack_vprintf: (libc)Variable Arguments Output. |
| * offsetof: (libc)Structure Measurement. |
| * on_exit: (libc)Cleanups on Exit. |
| * open64: (libc)Opening and Closing Files. |
| * open: (libc)Opening and Closing Files. |
| * open_memstream: (libc)String Streams. |
| * opendir: (libc)Opening a Directory. |
| * openlog: (libc)openlog. |
| * openpty: (libc)Pseudo-Terminal Pairs. |
| * parse_printf_format: (libc)Parsing a Template String. |
| * pathconf: (libc)Pathconf. |
| * pause: (libc)Using Pause. |
| * pclose: (libc)Pipe to a Subprocess. |
| * perror: (libc)Error Messages. |
| * pipe: (libc)Creating a Pipe. |
| * popen: (libc)Pipe to a Subprocess. |
| * posix_memalign: (libc)Aligned Memory Blocks. |
| * pow10: (libc)Exponents and Logarithms. |
| * pow10f: (libc)Exponents and Logarithms. |
| * pow10l: (libc)Exponents and Logarithms. |
| * pow: (libc)Exponents and Logarithms. |
| * powf: (libc)Exponents and Logarithms. |
| * powl: (libc)Exponents and Logarithms. |
| * pread64: (libc)I/O Primitives. |
| * pread: (libc)I/O Primitives. |
| * printf: (libc)Formatted Output Functions. |
| * printf_size: (libc)Predefined Printf Handlers. |
| * printf_size_info: (libc)Predefined Printf Handlers. |
| * psignal: (libc)Signal Messages. |
| * pthread_getattr_default_np: (libc)Default Thread Attributes. |
| * pthread_getspecific: (libc)Thread-specific Data. |
| * pthread_key_create: (libc)Thread-specific Data. |
| * pthread_key_delete: (libc)Thread-specific Data. |
| * pthread_setattr_default_np: (libc)Default Thread Attributes. |
| * pthread_setspecific: (libc)Thread-specific Data. |
| * ptsname: (libc)Allocation. |
| * ptsname_r: (libc)Allocation. |
| * putc: (libc)Simple Output. |
| * putc_unlocked: (libc)Simple Output. |
| * putchar: (libc)Simple Output. |
| * putchar_unlocked: (libc)Simple Output. |
| * putenv: (libc)Environment Access. |
| * putpwent: (libc)Writing a User Entry. |
| * puts: (libc)Simple Output. |
| * pututline: (libc)Manipulating the Database. |
| * pututxline: (libc)XPG Functions. |
| * putw: (libc)Simple Output. |
| * putwc: (libc)Simple Output. |
| * putwc_unlocked: (libc)Simple Output. |
| * putwchar: (libc)Simple Output. |
| * putwchar_unlocked: (libc)Simple Output. |
| * pwrite64: (libc)I/O Primitives. |
| * pwrite: (libc)I/O Primitives. |
| * qecvt: (libc)System V Number Conversion. |
| * qecvt_r: (libc)System V Number Conversion. |
| * qfcvt: (libc)System V Number Conversion. |
| * qfcvt_r: (libc)System V Number Conversion. |
| * qgcvt: (libc)System V Number Conversion. |
| * qsort: (libc)Array Sort Function. |
| * raise: (libc)Signaling Yourself. |
| * rand: (libc)ISO Random. |
| * rand_r: (libc)ISO Random. |
| * random: (libc)BSD Random. |
| * random_r: (libc)BSD Random. |
| * rawmemchr: (libc)Search Functions. |
| * read: (libc)I/O Primitives. |
| * readdir64: (libc)Reading/Closing Directory. |
| * readdir64_r: (libc)Reading/Closing Directory. |
| * readdir: (libc)Reading/Closing Directory. |
| * readdir_r: (libc)Reading/Closing Directory. |
| * readlink: (libc)Symbolic Links. |
| * readv: (libc)Scatter-Gather. |
| * realloc: (libc)Changing Block Size. |
| * realpath: (libc)Symbolic Links. |
| * recv: (libc)Receiving Data. |
| * recvfrom: (libc)Receiving Datagrams. |
| * recvmsg: (libc)Receiving Datagrams. |
| * regcomp: (libc)POSIX Regexp Compilation. |
| * regerror: (libc)Regexp Cleanup. |
| * regexec: (libc)Matching POSIX Regexps. |
| * regfree: (libc)Regexp Cleanup. |
| * register_printf_function: (libc)Registering New Conversions. |
| * remainder: (libc)Remainder Functions. |
| * remainderf: (libc)Remainder Functions. |
| * remainderl: (libc)Remainder Functions. |
| * remove: (libc)Deleting Files. |
| * rename: (libc)Renaming Files. |
| * rewind: (libc)File Positioning. |
| * rewinddir: (libc)Random Access Directory. |
| * rindex: (libc)Search Functions. |
| * rint: (libc)Rounding Functions. |
| * rintf: (libc)Rounding Functions. |
| * rintl: (libc)Rounding Functions. |
| * rmdir: (libc)Deleting Files. |
| * round: (libc)Rounding Functions. |
| * roundf: (libc)Rounding Functions. |
| * roundl: (libc)Rounding Functions. |
| * rpmatch: (libc)Yes-or-No Questions. |
| * sbrk: (libc)Resizing the Data Segment. |
| * scalb: (libc)Normalization Functions. |
| * scalbf: (libc)Normalization Functions. |
| * scalbl: (libc)Normalization Functions. |
| * scalbln: (libc)Normalization Functions. |
| * scalblnf: (libc)Normalization Functions. |
| * scalblnl: (libc)Normalization Functions. |
| * scalbn: (libc)Normalization Functions. |
| * scalbnf: (libc)Normalization Functions. |
| * scalbnl: (libc)Normalization Functions. |
| * scandir64: (libc)Scanning Directory Content. |
| * scandir: (libc)Scanning Directory Content. |
| * scanf: (libc)Formatted Input Functions. |
| * sched_get_priority_max: (libc)Basic Scheduling Functions. |
| * sched_get_priority_min: (libc)Basic Scheduling Functions. |
| * sched_getaffinity: (libc)CPU Affinity. |
| * sched_getparam: (libc)Basic Scheduling Functions. |
| * sched_getscheduler: (libc)Basic Scheduling Functions. |
| * sched_rr_get_interval: (libc)Basic Scheduling Functions. |
| * sched_setaffinity: (libc)CPU Affinity. |
| * sched_setparam: (libc)Basic Scheduling Functions. |
| * sched_setscheduler: (libc)Basic Scheduling Functions. |
| * sched_yield: (libc)Basic Scheduling Functions. |
| * secure_getenv: (libc)Environment Access. |
| * seed48: (libc)SVID Random. |
| * seed48_r: (libc)SVID Random. |
| * seekdir: (libc)Random Access Directory. |
| * select: (libc)Waiting for I/O. |
| * send: (libc)Sending Data. |
| * sendmsg: (libc)Receiving Datagrams. |
| * sendto: (libc)Sending Datagrams. |
| * setbuf: (libc)Controlling Buffering. |
| * setbuffer: (libc)Controlling Buffering. |
| * setcontext: (libc)System V contexts. |
| * setdomainname: (libc)Host Identification. |
| * setegid: (libc)Setting Groups. |
| * setenv: (libc)Environment Access. |
| * seteuid: (libc)Setting User ID. |
| * setfsent: (libc)fstab. |
| * setgid: (libc)Setting Groups. |
| * setgrent: (libc)Scanning All Groups. |
| * setgroups: (libc)Setting Groups. |
| * sethostent: (libc)Host Names. |
| * sethostid: (libc)Host Identification. |
| * sethostname: (libc)Host Identification. |
| * setitimer: (libc)Setting an Alarm. |
| * setjmp: (libc)Non-Local Details. |
| * setkey: (libc)DES Encryption. |
| * setkey_r: (libc)DES Encryption. |
| * setlinebuf: (libc)Controlling Buffering. |
| * setlocale: (libc)Setting the Locale. |
| * setlogmask: (libc)setlogmask. |
| * setmntent: (libc)mtab. |
| * setnetent: (libc)Networks Database. |
| * setnetgrent: (libc)Lookup Netgroup. |
| * setpgid: (libc)Process Group Functions. |
| * setpgrp: (libc)Process Group Functions. |
| * setpriority: (libc)Traditional Scheduling Functions. |
| * setprotoent: (libc)Protocols Database. |
| * setpwent: (libc)Scanning All Users. |
| * setregid: (libc)Setting Groups. |
| * setreuid: (libc)Setting User ID. |
| * setrlimit64: (libc)Limits on Resources. |
| * setrlimit: (libc)Limits on Resources. |
| * setservent: (libc)Services Database. |
| * setsid: (libc)Process Group Functions. |
| * setsockopt: (libc)Socket Option Functions. |
| * setstate: (libc)BSD Random. |
| * setstate_r: (libc)BSD Random. |
| * settimeofday: (libc)High-Resolution Calendar. |
| * setuid: (libc)Setting User ID. |
| * setutent: (libc)Manipulating the Database. |
| * setutxent: (libc)XPG Functions. |
| * setvbuf: (libc)Controlling Buffering. |
| * shm_open: (libc)Memory-mapped I/O. |
| * shm_unlink: (libc)Memory-mapped I/O. |
| * shutdown: (libc)Closing a Socket. |
| * sigaction: (libc)Advanced Signal Handling. |
| * sigaddset: (libc)Signal Sets. |
| * sigaltstack: (libc)Signal Stack. |
| * sigblock: (libc)Blocking in BSD. |
| * sigdelset: (libc)Signal Sets. |
| * sigemptyset: (libc)Signal Sets. |
| * sigfillset: (libc)Signal Sets. |
| * siginterrupt: (libc)BSD Handler. |
| * sigismember: (libc)Signal Sets. |
| * siglongjmp: (libc)Non-Local Exits and Signals. |
| * sigmask: (libc)Blocking in BSD. |
| * signal: (libc)Basic Signal Handling. |
| * signbit: (libc)FP Bit Twiddling. |
| * significand: (libc)Normalization Functions. |
| * significandf: (libc)Normalization Functions. |
| * significandl: (libc)Normalization Functions. |
| * sigpause: (libc)Blocking in BSD. |
| * sigpending: (libc)Checking for Pending Signals. |
| * sigprocmask: (libc)Process Signal Mask. |
| * sigsetjmp: (libc)Non-Local Exits and Signals. |
| * sigsetmask: (libc)Blocking in BSD. |
| * sigstack: (libc)Signal Stack. |
| * sigsuspend: (libc)Sigsuspend. |
| * sigvec: (libc)BSD Handler. |
| * sin: (libc)Trig Functions. |
| * sincos: (libc)Trig Functions. |
| * sincosf: (libc)Trig Functions. |
| * sincosl: (libc)Trig Functions. |
| * sinf: (libc)Trig Functions. |
| * sinh: (libc)Hyperbolic Functions. |
| * sinhf: (libc)Hyperbolic Functions. |
| * sinhl: (libc)Hyperbolic Functions. |
| * sinl: (libc)Trig Functions. |
| * sleep: (libc)Sleeping. |
| * snprintf: (libc)Formatted Output Functions. |
| * socket: (libc)Creating a Socket. |
| * socketpair: (libc)Socket Pairs. |
| * sprintf: (libc)Formatted Output Functions. |
| * sqrt: (libc)Exponents and Logarithms. |
| * sqrtf: (libc)Exponents and Logarithms. |
| * sqrtl: (libc)Exponents and Logarithms. |
| * srand48: (libc)SVID Random. |
| * srand48_r: (libc)SVID Random. |
| * srand: (libc)ISO Random. |
| * srandom: (libc)BSD Random. |
| * srandom_r: (libc)BSD Random. |
| * sscanf: (libc)Formatted Input Functions. |
| * ssignal: (libc)Basic Signal Handling. |
| * stat64: (libc)Reading Attributes. |
| * stat: (libc)Reading Attributes. |
| * stime: (libc)Simple Calendar Time. |
| * stpcpy: (libc)Copying and Concatenation. |
| * stpncpy: (libc)Copying and Concatenation. |
| * strcasecmp: (libc)String/Array Comparison. |
| * strcasestr: (libc)Search Functions. |
| * strcat: (libc)Copying and Concatenation. |
| * strchr: (libc)Search Functions. |
| * strchrnul: (libc)Search Functions. |
| * strcmp: (libc)String/Array Comparison. |
| * strcoll: (libc)Collation Functions. |
| * strcpy: (libc)Copying and Concatenation. |
| * strcspn: (libc)Search Functions. |
| * strdup: (libc)Copying and Concatenation. |
| * strdupa: (libc)Copying and Concatenation. |
| * strerror: (libc)Error Messages. |
| * strerror_r: (libc)Error Messages. |
| * strfmon: (libc)Formatting Numbers. |
| * strfry: (libc)strfry. |
| * strftime: (libc)Formatting Calendar Time. |
| * strlen: (libc)String Length. |
| * strncasecmp: (libc)String/Array Comparison. |
| * strncat: (libc)Copying and Concatenation. |
| * strncmp: (libc)String/Array Comparison. |
| * strncpy: (libc)Copying and Concatenation. |
| * strndup: (libc)Copying and Concatenation. |
| * strndupa: (libc)Copying and Concatenation. |
| * strnlen: (libc)String Length. |
| * strpbrk: (libc)Search Functions. |
| * strptime: (libc)Low-Level Time String Parsing. |
| * strrchr: (libc)Search Functions. |
| * strsep: (libc)Finding Tokens in a String. |
| * strsignal: (libc)Signal Messages. |
| * strspn: (libc)Search Functions. |
| * strstr: (libc)Search Functions. |
| * strtod: (libc)Parsing of Floats. |
| * strtof: (libc)Parsing of Floats. |
| * strtoimax: (libc)Parsing of Integers. |
| * strtok: (libc)Finding Tokens in a String. |
| * strtok_r: (libc)Finding Tokens in a String. |
| * strtol: (libc)Parsing of Integers. |
| * strtold: (libc)Parsing of Floats. |
| * strtoll: (libc)Parsing of Integers. |
| * strtoq: (libc)Parsing of Integers. |
| * strtoul: (libc)Parsing of Integers. |
| * strtoull: (libc)Parsing of Integers. |
| * strtoumax: (libc)Parsing of Integers. |
| * strtouq: (libc)Parsing of Integers. |
| * strverscmp: (libc)String/Array Comparison. |
| * strxfrm: (libc)Collation Functions. |
| * stty: (libc)BSD Terminal Modes. |
| * swapcontext: (libc)System V contexts. |
| * swprintf: (libc)Formatted Output Functions. |
| * swscanf: (libc)Formatted Input Functions. |
| * symlink: (libc)Symbolic Links. |
| * sync: (libc)Synchronizing I/O. |
| * syscall: (libc)System Calls. |
| * sysconf: (libc)Sysconf Definition. |
| * sysctl: (libc)System Parameters. |
| * syslog: (libc)syslog; vsyslog. |
| * system: (libc)Running a Command. |
| * sysv_signal: (libc)Basic Signal Handling. |
| * tan: (libc)Trig Functions. |
| * tanf: (libc)Trig Functions. |
| * tanh: (libc)Hyperbolic Functions. |
| * tanhf: (libc)Hyperbolic Functions. |
| * tanhl: (libc)Hyperbolic Functions. |
| * tanl: (libc)Trig Functions. |
| * tcdrain: (libc)Line Control. |
| * tcflow: (libc)Line Control. |
| * tcflush: (libc)Line Control. |
| * tcgetattr: (libc)Mode Functions. |
| * tcgetpgrp: (libc)Terminal Access Functions. |
| * tcgetsid: (libc)Terminal Access Functions. |
| * tcsendbreak: (libc)Line Control. |
| * tcsetattr: (libc)Mode Functions. |
| * tcsetpgrp: (libc)Terminal Access Functions. |
| * tdelete: (libc)Tree Search Function. |
| * tdestroy: (libc)Tree Search Function. |
| * telldir: (libc)Random Access Directory. |
| * tempnam: (libc)Temporary Files. |
| * textdomain: (libc)Locating gettext catalog. |
| * tfind: (libc)Tree Search Function. |
| * tgamma: (libc)Special Functions. |
| * tgammaf: (libc)Special Functions. |
| * tgammal: (libc)Special Functions. |
| * time: (libc)Simple Calendar Time. |
| * timegm: (libc)Broken-down Time. |
| * timelocal: (libc)Broken-down Time. |
| * times: (libc)Processor Time. |
| * tmpfile64: (libc)Temporary Files. |
| * tmpfile: (libc)Temporary Files. |
| * tmpnam: (libc)Temporary Files. |
| * tmpnam_r: (libc)Temporary Files. |
| * toascii: (libc)Case Conversion. |
| * tolower: (libc)Case Conversion. |
| * toupper: (libc)Case Conversion. |
| * towctrans: (libc)Wide Character Case Conversion. |
| * towlower: (libc)Wide Character Case Conversion. |
| * towupper: (libc)Wide Character Case Conversion. |
| * trunc: (libc)Rounding Functions. |
| * truncate64: (libc)File Size. |
| * truncate: (libc)File Size. |
| * truncf: (libc)Rounding Functions. |
| * truncl: (libc)Rounding Functions. |
| * tsearch: (libc)Tree Search Function. |
| * ttyname: (libc)Is It a Terminal. |
| * ttyname_r: (libc)Is It a Terminal. |
| * twalk: (libc)Tree Search Function. |
| * tzset: (libc)Time Zone Functions. |
| * ulimit: (libc)Limits on Resources. |
| * umask: (libc)Setting Permissions. |
| * umount2: (libc)Mount-Unmount-Remount. |
| * umount: (libc)Mount-Unmount-Remount. |
| * uname: (libc)Platform Type. |
| * ungetc: (libc)How Unread. |
| * ungetwc: (libc)How Unread. |
| * unlink: (libc)Deleting Files. |
| * unlockpt: (libc)Allocation. |
| * unsetenv: (libc)Environment Access. |
| * updwtmp: (libc)Manipulating the Database. |
| * utime: (libc)File Times. |
| * utimes: (libc)File Times. |
| * utmpname: (libc)Manipulating the Database. |
| * utmpxname: (libc)XPG Functions. |
| * va_arg: (libc)Argument Macros. |
| * va_copy: (libc)Argument Macros. |
| * va_end: (libc)Argument Macros. |
| * va_start: (libc)Argument Macros. |
| * valloc: (libc)Aligned Memory Blocks. |
| * vasprintf: (libc)Variable Arguments Output. |
| * verr: (libc)Error Messages. |
| * verrx: (libc)Error Messages. |
| * versionsort64: (libc)Scanning Directory Content. |
| * versionsort: (libc)Scanning Directory Content. |
| * vfork: (libc)Creating a Process. |
| * vfprintf: (libc)Variable Arguments Output. |
| * vfscanf: (libc)Variable Arguments Input. |
| * vfwprintf: (libc)Variable Arguments Output. |
| * vfwscanf: (libc)Variable Arguments Input. |
| * vlimit: (libc)Limits on Resources. |
| * vprintf: (libc)Variable Arguments Output. |
| * vscanf: (libc)Variable Arguments Input. |
| * vsnprintf: (libc)Variable Arguments Output. |
| * vsprintf: (libc)Variable Arguments Output. |
| * vsscanf: (libc)Variable Arguments Input. |
| * vswprintf: (libc)Variable Arguments Output. |
| * vswscanf: (libc)Variable Arguments Input. |
| * vsyslog: (libc)syslog; vsyslog. |
| * vtimes: (libc)Resource Usage. |
| * vwarn: (libc)Error Messages. |
| * vwarnx: (libc)Error Messages. |
| * vwprintf: (libc)Variable Arguments Output. |
| * vwscanf: (libc)Variable Arguments Input. |
| * wait3: (libc)BSD Wait Functions. |
| * wait4: (libc)Process Completion. |
| * wait: (libc)Process Completion. |
| * waitpid: (libc)Process Completion. |
| * warn: (libc)Error Messages. |
| * warnx: (libc)Error Messages. |
| * wcpcpy: (libc)Copying and Concatenation. |
| * wcpncpy: (libc)Copying and Concatenation. |
| * wcrtomb: (libc)Converting a Character. |
| * wcscasecmp: (libc)String/Array Comparison. |
| * wcscat: (libc)Copying and Concatenation. |
| * wcschr: (libc)Search Functions. |
| * wcschrnul: (libc)Search Functions. |
| * wcscmp: (libc)String/Array Comparison. |
| * wcscoll: (libc)Collation Functions. |
| * wcscpy: (libc)Copying and Concatenation. |
| * wcscspn: (libc)Search Functions. |
| * wcsdup: (libc)Copying and Concatenation. |
| * wcsftime: (libc)Formatting Calendar Time. |
| * wcslen: (libc)String Length. |
| * wcsncasecmp: (libc)String/Array Comparison. |
| * wcsncat: (libc)Copying and Concatenation. |
| * wcsncmp: (libc)String/Array Comparison. |
| * wcsncpy: (libc)Copying and Concatenation. |
| * wcsnlen: (libc)String Length. |
| * wcsnrtombs: (libc)Converting Strings. |
| * wcspbrk: (libc)Search Functions. |
| * wcsrchr: (libc)Search Functions. |
| * wcsrtombs: (libc)Converting Strings. |
| * wcsspn: (libc)Search Functions. |
| * wcsstr: (libc)Search Functions. |
| * wcstod: (libc)Parsing of Floats. |
| * wcstof: (libc)Parsing of Floats. |
| * wcstoimax: (libc)Parsing of Integers. |
| * wcstok: (libc)Finding Tokens in a String. |
| * wcstol: (libc)Parsing of Integers. |
| * wcstold: (libc)Parsing of Floats. |
| * wcstoll: (libc)Parsing of Integers. |
| * wcstombs: (libc)Non-reentrant String Conversion. |
| * wcstoq: (libc)Parsing of Integers. |
| * wcstoul: (libc)Parsing of Integers. |
| * wcstoull: (libc)Parsing of Integers. |
| * wcstoumax: (libc)Parsing of Integers. |
| * wcstouq: (libc)Parsing of Integers. |
| * wcswcs: (libc)Search Functions. |
| * wcsxfrm: (libc)Collation Functions. |
| * wctob: (libc)Converting a Character. |
| * wctomb: (libc)Non-reentrant Character Conversion. |
| * wctrans: (libc)Wide Character Case Conversion. |
| * wctype: (libc)Classification of Wide Characters. |
| * wmemchr: (libc)Search Functions. |
| * wmemcmp: (libc)String/Array Comparison. |
| * wmemcpy: (libc)Copying and Concatenation. |
| * wmemmove: (libc)Copying and Concatenation. |
| * wmempcpy: (libc)Copying and Concatenation. |
| * wmemset: (libc)Copying and Concatenation. |
| * wordexp: (libc)Calling Wordexp. |
| * wordfree: (libc)Calling Wordexp. |
| * wprintf: (libc)Formatted Output Functions. |
| * write: (libc)I/O Primitives. |
| * writev: (libc)Scatter-Gather. |
| * wscanf: (libc)Formatted Input Functions. |
| * y0: (libc)Special Functions. |
| * y0f: (libc)Special Functions. |
| * y0l: (libc)Special Functions. |
| * y1: (libc)Special Functions. |
| * y1f: (libc)Special Functions. |
| * y1l: (libc)Special Functions. |
| * yn: (libc)Special Functions. |
| * ynf: (libc)Special Functions. |
| * ynl: (libc)Special Functions. |
| END-INFO-DIR-ENTRY |
| |
| |
| File: libc.info, Node: Hard Links, Next: Symbolic Links, Prev: Working with Directory Trees, Up: File System Interface |
| |
| 14.4 Hard Links |
| =============== |
| |
| In POSIX systems, one file can have many names at the same time. All of |
| the names are equally real, and no one of them is preferred to the |
| others. |
| |
| To add a name to a file, use the 'link' function. (The new name is |
| also called a "hard link" to the file.) Creating a new link to a file |
| does not copy the contents of the file; it simply makes a new name by |
| which the file can be known, in addition to the file's existing name or |
| names. |
| |
| One file can have names in several directories, so the organization |
| of the file system is not a strict hierarchy or tree. |
| |
| In most implementations, it is not possible to have hard links to the |
| same file in multiple file systems. 'link' reports an error if you try |
| to make a hard link to the file from another file system when this |
| cannot be done. |
| |
| The prototype for the 'link' function is declared in the header file |
| 'unistd.h'. |
| |
| -- Function: int link (const char *OLDNAME, const char *NEWNAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'link' function makes a new link to the existing file named by |
| OLDNAME, under the new name NEWNAME. |
| |
| This function returns a value of '0' if it is successful and '-1' |
| on failure. In addition to the usual file name errors (*note File |
| Name Errors::) for both OLDNAME and NEWNAME, the following 'errno' |
| error conditions are defined for this function: |
| |
| 'EACCES' |
| You are not allowed to write to the directory in which the new |
| link is to be written. |
| |
| 'EEXIST' |
| There is already a file named NEWNAME. If you want to replace |
| this link with a new link, you must remove the old link |
| explicitly first. |
| |
| 'EMLINK' |
| There are already too many links to the file named by OLDNAME. |
| (The maximum number of links to a file is 'LINK_MAX'; see |
| *note Limits for Files::.) |
| |
| 'ENOENT' |
| The file named by OLDNAME doesn't exist. You can't make a |
| link to a file that doesn't exist. |
| |
| 'ENOSPC' |
| The directory or file system that would contain the new link |
| is full and cannot be extended. |
| |
| 'EPERM' |
| On GNU/Linux and GNU/Hurd systems and some others, you cannot |
| make links to directories. Many systems allow only privileged |
| users to do so. This error is used to report the problem. |
| |
| 'EROFS' |
| The directory containing the new link can't be modified |
| because it's on a read-only file system. |
| |
| 'EXDEV' |
| The directory specified in NEWNAME is on a different file |
| system than the existing file. |
| |
| 'EIO' |
| A hardware error occurred while trying to read or write the to |
| filesystem. |
| |
| |
| File: libc.info, Node: Symbolic Links, Next: Deleting Files, Prev: Hard Links, Up: File System Interface |
| |
| 14.5 Symbolic Links |
| =================== |
| |
| GNU systems support "soft links" or "symbolic links". This is a kind of |
| "file" that is essentially a pointer to another file name. Unlike hard |
| links, symbolic links can be made to directories or across file systems |
| with no restrictions. You can also make a symbolic link to a name which |
| is not the name of any file. (Opening this link will fail until a file |
| by that name is created.) Likewise, if the symbolic link points to an |
| existing file which is later deleted, the symbolic link continues to |
| point to the same file name even though the name no longer names any |
| file. |
| |
| The reason symbolic links work the way they do is that special things |
| happen when you try to open the link. The 'open' function realizes you |
| have specified the name of a link, reads the file name contained in the |
| link, and opens that file name instead. The 'stat' function likewise |
| operates on the file that the symbolic link points to, instead of on the |
| link itself. |
| |
| By contrast, other operations such as deleting or renaming the file |
| operate on the link itself. The functions 'readlink' and 'lstat' also |
| refrain from following symbolic links, because their purpose is to |
| obtain information about the link. 'link', the function that makes a |
| hard link, does too. It makes a hard link to the symbolic link, which |
| one rarely wants. |
| |
| Some systems have for some functions operating on files have a limit |
| on how many symbolic links are followed when resolving a path name. The |
| limit if it exists is published in the 'sys/param.h' header file. |
| |
| -- Macro: int MAXSYMLINKS |
| |
| The macro 'MAXSYMLINKS' specifies how many symlinks some function |
| will follow before returning 'ELOOP'. Not all functions behave the |
| same and this value is not the same a that returned for |
| '_SC_SYMLOOP' by 'sysconf'. In fact, the 'sysconf' result can |
| indicate that there is no fixed limit although 'MAXSYMLINKS' exists |
| and has a finite value. |
| |
| Prototypes for most of the functions listed in this section are in |
| 'unistd.h'. |
| |
| -- Function: int symlink (const char *OLDNAME, const char *NEWNAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'symlink' function makes a symbolic link to OLDNAME named |
| NEWNAME. |
| |
| The normal return value from 'symlink' is '0'. A return value of |
| '-1' indicates an error. In addition to the usual file name syntax |
| errors (*note File Name Errors::), the following 'errno' error |
| conditions are defined for this function: |
| |
| 'EEXIST' |
| There is already an existing file named NEWNAME. |
| |
| 'EROFS' |
| The file NEWNAME would exist on a read-only file system. |
| |
| 'ENOSPC' |
| The directory or file system cannot be extended to make the |
| new link. |
| |
| 'EIO' |
| A hardware error occurred while reading or writing data on the |
| disk. |
| |
| -- Function: ssize_t readlink (const char *FILENAME, char *BUFFER, |
| size_t SIZE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'readlink' function gets the value of the symbolic link |
| FILENAME. The file name that the link points to is copied into |
| BUFFER. This file name string is _not_ null-terminated; 'readlink' |
| normally returns the number of characters copied. The SIZE |
| argument specifies the maximum number of characters to copy, |
| usually the allocation size of BUFFER. |
| |
| If the return value equals SIZE, you cannot tell whether or not |
| there was room to return the entire name. So make a bigger buffer |
| and call 'readlink' again. Here is an example: |
| |
| char * |
| readlink_malloc (const char *filename) |
| { |
| int size = 100; |
| char *buffer = NULL; |
| |
| while (1) |
| { |
| buffer = (char *) xrealloc (buffer, size); |
| int nchars = readlink (filename, buffer, size); |
| if (nchars < 0) |
| { |
| free (buffer); |
| return NULL; |
| } |
| if (nchars < size) |
| return buffer; |
| size *= 2; |
| } |
| } |
| |
| A value of '-1' is returned in case of error. In addition to the |
| usual file name errors (*note File Name Errors::), the following |
| 'errno' error conditions are defined for this function: |
| |
| 'EINVAL' |
| The named file is not a symbolic link. |
| |
| 'EIO' |
| A hardware error occurred while reading or writing data on the |
| disk. |
| |
| In some situations it is desirable to resolve all the symbolic links |
| to get the real name of a file where no prefix names a symbolic link |
| which is followed and no filename in the path is '.' or '..'. This is |
| for instance desirable if files have to be compare in which case |
| different names can refer to the same inode. |
| |
| -- Function: char * canonicalize_file_name (const char *NAME) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| The 'canonicalize_file_name' function returns the absolute name of |
| the file named by NAME which contains no '.', '..' components nor |
| any repeated path separators ('/') or symlinks. The result is |
| passed back as the return value of the function in a block of |
| memory allocated with 'malloc'. If the result is not used anymore |
| the memory should be freed with a call to 'free'. |
| |
| If any of the path components is missing the function returns a |
| NULL pointer. This is also what is returned if the length of the |
| path reaches or exceeds 'PATH_MAX' characters. In any case 'errno' |
| is set accordingly. |
| |
| 'ENAMETOOLONG' |
| The resulting path is too long. This error only occurs on |
| systems which have a limit on the file name length. |
| |
| 'EACCES' |
| At least one of the path components is not readable. |
| |
| 'ENOENT' |
| The input file name is empty. |
| |
| 'ENOENT' |
| At least one of the path components does not exist. |
| |
| 'ELOOP' |
| More than 'MAXSYMLINKS' many symlinks have been followed. |
| |
| This function is a GNU extension and is declared in 'stdlib.h'. |
| |
| The Unix standard includes a similar function which differs from |
| 'canonicalize_file_name' in that the user has to provide the buffer |
| where the result is placed in. |
| |
| -- Function: char * realpath (const char *restrict NAME, char *restrict |
| RESOLVED) |
| Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | *Note |
| POSIX Safety Concepts::. |
| |
| A call to 'realpath' where the RESOLVED parameter is 'NULL' behaves |
| exactly like 'canonicalize_file_name'. The function allocates a |
| buffer for the file name and returns a pointer to it. If RESOLVED |
| is not 'NULL' it points to a buffer into which the result is |
| copied. It is the callers responsibility to allocate a buffer |
| which is large enough. On systems which define 'PATH_MAX' this |
| means the buffer must be large enough for a pathname of this size. |
| For systems without limitations on the pathname length the |
| requirement cannot be met and programs should not call 'realpath' |
| with anything but 'NULL' for the second parameter. |
| |
| One other difference is that the buffer RESOLVED (if nonzero) will |
| contain the part of the path component which does not exist or is |
| not readable if the function returns 'NULL' and 'errno' is set to |
| 'EACCES' or 'ENOENT'. |
| |
| This function is declared in 'stdlib.h'. |
| |
| The advantage of using this function is that it is more widely |
| available. The drawback is that it reports failures for long path on |
| systems which have no limits on the file name length. |
| |
| |
| File: libc.info, Node: Deleting Files, Next: Renaming Files, Prev: Symbolic Links, Up: File System Interface |
| |
| 14.6 Deleting Files |
| =================== |
| |
| You can delete a file with 'unlink' or 'remove'. |
| |
| Deletion actually deletes a file name. If this is the file's only |
| name, then the file is deleted as well. If the file has other remaining |
| names (*note Hard Links::), it remains accessible under those names. |
| |
| -- Function: int unlink (const char *FILENAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'unlink' function deletes the file name FILENAME. If this is a |
| file's sole name, the file itself is also deleted. (Actually, if |
| any process has the file open when this happens, deletion is |
| postponed until all processes have closed the file.) |
| |
| The function 'unlink' is declared in the header file 'unistd.h'. |
| |
| This function returns '0' on successful completion, 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: |
| |
| 'EACCES' |
| Write permission is denied for the directory from which the |
| file is to be removed, or the directory has the sticky bit set |
| and you do not own the file. |
| |
| 'EBUSY' |
| This error indicates that the file is being used by the system |
| in such a way that it can't be unlinked. For example, you |
| might see this error if the file name specifies the root |
| directory or a mount point for a file system. |
| |
| 'ENOENT' |
| The file name to be deleted doesn't exist. |
| |
| 'EPERM' |
| On some systems 'unlink' cannot be used to delete the name of |
| a directory, or at least can only be used this way by a |
| privileged user. To avoid such problems, use 'rmdir' to |
| delete directories. (On GNU/Linux and GNU/Hurd systems |
| 'unlink' can never delete the name of a directory.) |
| |
| 'EROFS' |
| The directory containing the file name to be deleted is on a |
| read-only file system and can't be modified. |
| |
| -- Function: int rmdir (const char *FILENAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'rmdir' function deletes a directory. The directory must be |
| empty before it can be removed; in other words, it can only contain |
| entries for '.' and '..'. |
| |
| In most other respects, 'rmdir' behaves like 'unlink'. There are |
| two additional 'errno' error conditions defined for 'rmdir': |
| |
| 'ENOTEMPTY' |
| 'EEXIST' |
| The directory to be deleted is not empty. |
| |
| These two error codes are synonymous; some systems use one, and |
| some use the other. GNU/Linux and GNU/Hurd systems always use |
| 'ENOTEMPTY'. |
| |
| The prototype for this function is declared in the header file |
| 'unistd.h'. |
| |
| -- Function: int remove (const char *FILENAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| This is the ISO C function to remove a file. It works like |
| 'unlink' for files and like 'rmdir' for directories. 'remove' is |
| declared in 'stdio.h'. |
| |
| |
| File: libc.info, Node: Renaming Files, Next: Creating Directories, Prev: Deleting Files, Up: File System Interface |
| |
| 14.7 Renaming Files |
| =================== |
| |
| The 'rename' function is used to change a file's name. |
| |
| -- Function: int rename (const char *OLDNAME, const char *NEWNAME) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'rename' function renames the file OLDNAME to NEWNAME. The |
| file formerly accessible under the name OLDNAME is afterwards |
| accessible as NEWNAME instead. (If the file had any other names |
| aside from OLDNAME, it continues to have those names.) |
| |
| The directory containing the name NEWNAME must be on the same file |
| system as the directory containing the name OLDNAME. |
| |
| One special case for 'rename' is when OLDNAME and NEWNAME are two |
| names for the same file. The consistent way to handle this case is |
| to delete OLDNAME. However, in this case POSIX requires that |
| 'rename' do nothing and report success--which is inconsistent. We |
| don't know what your operating system will do. |
| |
| If OLDNAME is not a directory, then any existing file named NEWNAME |
| is removed during the renaming operation. However, if NEWNAME is |
| the name of a directory, 'rename' fails in this case. |
| |
| If OLDNAME is a directory, then either NEWNAME must not exist or it |
| must name a directory that is empty. In the latter case, the |
| existing directory named NEWNAME is deleted first. The name |
| NEWNAME must not specify a subdirectory of the directory 'oldname' |
| which is being renamed. |
| |
| One useful feature of 'rename' is that the meaning of NEWNAME |
| changes "atomically" from any previously existing file by that name |
| to its new meaning (i.e., the file that was called OLDNAME). There |
| is no instant at which NEWNAME is non-existent "in between" the old |
| meaning and the new meaning. If there is a system crash during the |
| operation, it is possible for both names to still exist; but |
| NEWNAME will always be intact if it exists at all. |
| |
| If 'rename' fails, it returns '-1'. In addition to the usual file |
| name errors (*note File Name Errors::), the following 'errno' error |
| conditions are defined for this function: |
| |
| 'EACCES' |
| One of the directories containing NEWNAME or OLDNAME refuses |
| write permission; or NEWNAME and OLDNAME are directories and |
| write permission is refused for one of them. |
| |
| 'EBUSY' |
| A directory named by OLDNAME or NEWNAME is being used by the |
| system in a way that prevents the renaming from working. This |
| includes directories that are mount points for filesystems, |
| and directories that are the current working directories of |
| processes. |
| |
| 'ENOTEMPTY' |
| 'EEXIST' |
| The directory NEWNAME isn't empty. GNU/Linux and GNU/Hurd |
| systems always return 'ENOTEMPTY' for this, but some other |
| systems return 'EEXIST'. |
| |
| 'EINVAL' |
| OLDNAME is a directory that contains NEWNAME. |
| |
| 'EISDIR' |
| NEWNAME is a directory but the OLDNAME isn't. |
| |
| 'EMLINK' |
| The parent directory of NEWNAME would have too many links |
| (entries). |
| |
| 'ENOENT' |
| The file OLDNAME doesn't exist. |
| |
| 'ENOSPC' |
| The directory that would contain NEWNAME has no room for |
| another entry, and there is no space left in the file system |
| to expand it. |
| |
| 'EROFS' |
| The operation would involve writing to a directory on a |
| read-only file system. |
| |
| 'EXDEV' |
| The two file names NEWNAME and OLDNAME are on different file |
| systems. |
| |
| |
| File: libc.info, Node: Creating Directories, Next: File Attributes, Prev: Renaming Files, Up: File System Interface |
| |
| 14.8 Creating Directories |
| ========================= |
| |
| Directories are created with the 'mkdir' function. (There is also a |
| shell command 'mkdir' which does the same thing.) |
| |
| -- Function: int mkdir (const char *FILENAME, mode_t MODE) |
| Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety |
| Concepts::. |
| |
| The 'mkdir' function creates a new, empty directory with name |
| FILENAME. |
| |
| The argument MODE specifies the file permissions for the new |
| directory file. *Note Permission Bits::, for more information |
| about this. |
| |
| A return value of '0' indicates successful completion, and '-1' |
| indicates failure. In addition to the usual file name syntax |
| errors (*note File Name Errors::), the following 'errno' error |
| conditions are defined for this function: |
| |
| 'EACCES' |
| Write permission is denied for the parent directory in which |
| the new directory is to be added. |
| |
| 'EEXIST' |
| A file named FILENAME already exists. |
| |
| 'EMLINK' |
| The parent directory has too many links (entries). |
| |
| Well-designed file systems never report this error, because |
| they permit more links than your disk could possibly hold. |
| However, you must still take account of the possibility of |
| this error, as it could result from network access to a file |
| system on another machine. |
| |
| 'ENOSPC' |
| The file system doesn't have enough room to create the new |
| directory. |
| |
| 'EROFS' |
| The parent directory of the directory being created is on a |
| read-only file system and cannot be modified. |
| |
| To use this function, your program should include the header file |
| 'sys/stat.h'. |
| |
| |
| 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. |
| |
| |
| 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 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'.) |
| |
| 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 object in the filesystem. These are message |
| queues, semaphores, and shared memory objects. To allow differentiating |
| these objects from other files the POSIX standard introduces three new |
| test macros. But unlike the other macros it does 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 implement 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 implement 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 implement 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 '_BSD_SOURCE' feature select |
| macro 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 beside 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_ 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 High-Resolution |
| Calendar::. |
| |
| 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, 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 the it is extended by a round 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: 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 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 password |
| 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::. |
| |
| The macro computes the length of 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. |
| *Note Socket Addresses::. |
| |
| 'struct in_addr sin_addr' |
| This is the Internet address of the host machine. *Note Host |
| Addresses::, and *note Host Names::, for how to get a value to |
| store here. |
| |
| 'unsigned short int sin_port' |
| This is the port number. *Note Ports::. |
| |
| 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::. |
| |
| '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. |
| |
| 'uint32_t sin6_flowinfo' |
| This is a currently unimplemented field. |
| |
| 'uint16_t sin6_port' |
| This is the port number. *Note Ports::. |
| |
| |
| 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 an 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 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 an |
| 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, files 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, files 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, files 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, files 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, files 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, files 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 password 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 a 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. |
| * 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. |
| |
| |
| File: libc.info, Node: I/O Queues, Next: Canonical or Not, Prev: Is It a Terminal, Up: Low-Level Terminal Interface |
| |
| 17.2 I/O Queues |
| =============== |
| |
| Many of the remaining functions in this section refer to the input and |
| output queues of a terminal device. These queues implement a form of |
| buffering _within the kernel_ independent of the buffering implemented |
| by I/O streams (*note I/O on Streams::). |
| |
| The "terminal input queue" is also sometimes referred to as its |
| "typeahead buffer". It holds the characters that have been received |
| from the terminal but not yet read by any process. |
| |
| The size of the input queue is described by the 'MAX_INPUT' and '_POSIX_MAX_INPUT' |
| parameters; see *note Limits for Files::. You are guaranteed a queue |
| size of at least 'MAX_INPUT', but the queue might be larger, and might |
| even dynamically change size. If input flow control is enabled by |
| setting the 'IXOFF' input mode bit (*note Input Modes::), the terminal |
| driver transmits STOP and START characters to the terminal when |
| necessary to prevent the queue from overflowing. Otherwise, input may |
| be lost if it comes in too fast from the terminal. In canonical mode, |
| all input stays in the queue until a newline character is received, so |
| the terminal input queue can fill up when you type a very long line. |
| *Note Canonical or Not::. |
| |
| The "terminal output queue" is like the input queue, but for output; |
| it contains characters that have been written by processes, but not yet |
| transmitted to the terminal. If output flow control is enabled by |
| setting the 'IXON' input mode bit (*note Input Modes::), the terminal |
| driver obeys START and STOP characters sent by the terminal to stop and |
| restart transmission of output. |
| |
| "Clearing" the terminal input queue means discarding any characters |
| that have been received but not yet read. Similarly, clearing the |
| terminal output queue means discarding any characters that have been |
| written but not yet transmitted. |
| |