# find /usr/share/man/man2 | grep 2 | xargs pr -t | mandoc >> bsd_man2_all KQUEUE(2) System Calls Manual KQUEUE(2) NNAAMMEE kkqquueeuuee, kkeevveenntt - kernel event notification mechanism SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t kkqquueeuuee(_v_o_i_d); _i_n_t kkeevveenntt(_i_n_t _k_q, _c_o_n_s_t _s_t_r_u_c_t _k_e_v_e_n_t _*_c_h_a_n_g_e_l_i_s_t, _i_n_t _n_c_h_a_n_g_e_s, _s_t_r_u_c_t _k_e_v_e_n_t _*_e_v_e_n_t_l_i_s_t, _i_n_t _n_e_v_e_n_t_s, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t); EEVV__SSEETT(_&_k_e_v, _i_d_e_n_t, _f_i_l_t_e_r, _f_l_a_g_s, _f_f_l_a_g_s, _d_a_t_a, _u_d_a_t_a); DDEESSCCRRIIPPTTIIOONN kkqquueeuuee() provides a generic method of notifying the user when an event happens or a condition holds, based on the results of small pieces of kernel code termed ``filters''. A kevent is identified by the (ident, filter) pair; there may only be one unique kevent per kqueue. The filter is executed upon the initial registration of a kevent in order to detect whether a preexisting condition is present, and is also executed whenever an event is passed to the filter for evaluation. If the filter determines that the condition should be reported, then the kevent is placed on the kqueue for the user to retrieve. The filter is also run when the user attempts to retrieve the kevent from the kqueue. If the filter indicates that the condition that triggered the event no longer holds, the kevent is removed from the kqueue and is not returned. Multiple events which trigger the filter do not result in multiple kevents being placed on the kqueue; instead, the filter will aggregate the events into a single struct kevent. Calling cclloossee() on a file descriptor will remove any kevents that reference the descriptor. kkqquueeuuee() creates a new kernel event queue and returns a descriptor. The queue is not inherited by a child created with fork(2). Similarly, kqueues cannot be passed across UNIX-domain sockets. kkeevveenntt() is used to register events with the queue, and return any pending events to the user. _c_h_a_n_g_e_l_i_s_t is a pointer to an array of _k_e_v_e_n_t structures, as defined in <_s_y_s_/_e_v_e_n_t_._h>. All changes contained in the _c_h_a_n_g_e_l_i_s_t are applied before any pending events are read from the queue. _n_c_h_a_n_g_e_s gives the size of _c_h_a_n_g_e_l_i_s_t. _e_v_e_n_t_l_i_s_t is a pointer to an array of kevent structures. _n_e_v_e_n_t_s determines the size of _e_v_e_n_t_l_i_s_t. When _n_e_v_e_n_t_s is zero, kkeevveenntt() will return immediately even if there is a _t_i_m_e_o_u_t specified unlike select(2). If _t_i_m_e_o_u_t is a non-null pointer, it specifies a maximum interval to wait for an event, which will be interpreted as a struct timespec. If _t_i_m_e_o_u_t is a null pointer, kkeevveenntt() waits indefinitely. To effect a poll, the _t_i_m_e_o_u_t argument should be non-null, pointing to a zero-valued _t_i_m_e_s_p_e_c structure. The same array may be used for the _c_h_a_n_g_e_l_i_s_t and _e_v_e_n_t_l_i_s_t. EEVV__SSEETT() is a macro which is provided for ease of initializing a kevent structure. The _k_e_v_e_n_t structure is defined as: struct kevent { uintptr_t ident; /* identifier for this event */ short filter; /* filter for event */ u_short flags; /* action flags for kqueue */ u_int fflags; /* filter flag value */ quad_t data; /* filter data value */ void *udata; /* opaque user data identifier */ }; The fields of struct kevent are: ident Value used to identify this event. The exact interpretation is determined by the attached filter, but often is a file descriptor. filter Identifies the kernel filter used to process this event. The pre-defined system filters are described below. flags Actions to perform on the event. fflags Filter-specific flags. data Filter-specific data value. udata Opaque user-defined value passed through the kernel unchanged. The _f_l_a_g_s field can contain the following values: EV_ADD Adds the event to the kqueue. Re-adding an existing event will modify the parameters of the original event, and not result in a duplicate entry. Adding an event automatically enables it, unless overridden by the EV_DISABLE flag. EV_ENABLE Permit kkeevveenntt() to return the event if it is triggered. EV_DISABLE Disable the event so kkeevveenntt() will not return it. The filter itself is not disabled. EV_DELETE Removes the event from the kqueue. Events which are attached to file descriptors are automatically deleted on the last close of the descriptor. EV_ONESHOT Causes the event to return only the first occurrence of the filter being triggered. After the user retrieves the event from the kqueue, it is deleted. EV_CLEAR After the event is retrieved by the user, its state is reset. This is useful for filters which report state transitions instead of the current state. Note that some filters may automatically set this flag internally. EV_EOF Filters may set this flag to indicate filter-specific EOF condition. EV_ERROR See _R_E_T_U_R_N _V_A_L_U_E_S below. The predefined system filters are listed below. Arguments may be passed to and from the filter via the _f_f_l_a_g_s and _d_a_t_a fields in the kevent structure. EVFILT_READ Takes a descriptor as the identifier, and returns whenever there is data available to read. The behavior of the filter is slightly different depending on the descriptor type. Sockets Sockets which have previously been passed to lliisstteenn() return when there is an incoming connection pending. _d_a_t_a contains the size of the listen backlog. Other socket descriptors return when there is data to be read, subject to the SO_RCVLOWAT value of the socket buffer. This may be overridden with a per- filter low water mark at the time the filter is added by setting the NOTE_LOWAT flag in _f_f_l_a_g_s, and specifying the new low water mark in _d_a_t_a. On return, _d_a_t_a contains the number of bytes in the socket buffer. If the read direction of the socket has shutdown, then the filter also sets EV_EOF in _f_l_a_g_s, and returns the socket error (if any) in _f_f_l_a_g_s. It is possible for EOF to be returned (indicating the connection is gone) while there is still data pending in the socket buffer. Vnodes Returns when the file pointer is not at the end of file. _d_a_t_a contains the offset from current position to end of file, and may be negative. If NOTE_EOF is set in _f_f_l_a_g_s, kkeevveenntt() will also return when the file pointer is at the end of file. The end of file condition is indicated by the presence of NOTE_EOF in _f_f_l_a_g_s on return. Fifos, Pipes Returns when there is data to read; _d_a_t_a contains the number of bytes available. When the last writer disconnects, the filter will set EV_EOF in _f_l_a_g_s. This may be cleared by passing in EV_CLEAR, at which point the filter will resume waiting for data to become available before returning. BPF devices Returns when the BPF buffer is full, the BPF timeout has expired, or when the BPF has ``immediate mode'' enabled and there is any data to read; _d_a_t_a contains the number of bytes available. EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever it is possible to write to the descriptor. For sockets, pipes, and FIFOs, _d_a_t_a will contain the amount of space remaining in the write buffer. The filter will set EV_EOF when the reader disconnects, and for the FIFO case, this may be cleared by use of EV_CLEAR. Note that this filter is not supported for vnodes or BPF devices. For sockets, the low water mark and socket error handling is identical to the EVFILT_READ case. EVFILT_VNODE Takes a file descriptor as the identifier and the events to watch for in _f_f_l_a_g_s, and returns when one or more of the requested events occurs on the descriptor. The events to monitor are: NOTE_DELETE uunnlliinnkk() was called on the file referenced by the descriptor. NOTE_WRITE A write occurred on the file referenced by the descriptor. NOTE_EXTEND The file referenced by the descriptor was extended. NOTE_TRUNCATE The file referenced by the descriptor was truncated. NOTE_ATTRIB The file referenced by the descriptor had its attributes changed. NOTE_LINK The link count on the file changed. NOTE_RENAME The file referenced by the descriptor was renamed. NOTE_REVOKE Access to the file was revoked via revoke(2) or the underlying file system was unmounted. On return, _f_f_l_a_g_s contains the events which triggered the filter. EVFILT_PROC Takes the process ID to monitor as the identifier and the events to watch for in _f_f_l_a_g_s, and returns when the process performs one or more of the requested events. If a process can normally see another process, it can attach an event to it. The events to monitor are: NOTE_EXIT The process has exited. The exit status will be stored in _d_a_t_a in the same format as the status set by wait(2). NOTE_FORK The process has called ffoorrkk(). NOTE_EXEC The process has executed a new process via execve(2) or similar call. NOTE_TRACK Follow a process across ffoorrkk() calls. The parent process will return with NOTE_FORK set in the _f_f_l_a_g_s field, while the child process will return with NOTE_CHILD set in _f_f_l_a_g_s and the parent PID in _d_a_t_a. NOTE_TRACKERR This flag is returned if the system was unable to attach an event to the child process, usually due to resource limitations. On return, _f_f_l_a_g_s contains the events which triggered the filter. EVFILT_SIGNAL Takes the signal number to monitor as the identifier and returns when the given signal is delivered to the process. This coexists with the ssiiggnnaall() and ssiiggaaccttiioonn() facilities, and has a lower precedence. The filter will record all attempts to deliver a signal to a process, even if the signal has been marked as SIG_IGN. Event notification happens after normal signal delivery processing. _d_a_t_a returns the number of times the signal has occurred since the last call to kkeevveenntt(). This filter automatically sets the EV_CLEAR flag internally. EVFILT_TIMER Establishes an arbitrary timer identified by _i_d_e_n_t. When adding a timer, _d_a_t_a specifies the timeout period in milliseconds. The timer will be periodic unless EV_ONESHOT is specified. On return, _d_a_t_a contains the number of times the timeout has expired since the last call to kkeevveenntt(). This filter automatically sets the EV_CLEAR flag internally. RREETTUURRNN VVAALLUUEESS kkqquueeuuee() creates a new kernel event queue and returns a file descriptor. If there was an error creating the kernel event queue, a value of -1 is returned and errno set. kkeevveenntt() returns the number of events placed in the _e_v_e_n_t_l_i_s_t, up to the value given by _n_e_v_e_n_t_s. If an error occurs while processing an element of the _c_h_a_n_g_e_l_i_s_t and there is enough room in the _e_v_e_n_t_l_i_s_t, then the event will be placed in the _e_v_e_n_t_l_i_s_t with EV_ERROR set in _f_l_a_g_s and the system error in _d_a_t_a. Otherwise, -1 will be returned, and errno will be set to indicate the error condition. If the time limit expires, then kkeevveenntt() returns 0. EERRRROORRSS The kkqquueeuuee() function fails if: [ENOMEM] The kernel failed to allocate enough memory for the kernel queue. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. The kkeevveenntt() function fails if: [EACCES] The process does not have permission to register a filter. [EFAULT] There was an error reading or writing the _k_e_v_e_n_t structure. [EBADF] The specified descriptor is invalid. [EINTR] A signal was delivered before the timeout expired and before any events were placed on the kqueue for return. [EINVAL] The specified time limit or filter is invalid. [ENOENT] The event could not be found to be modified or deleted. [ENOMEM] No memory was available to register the event. [ESRCH] The specified process to attach to does not exist. SSEEEE AALLSSOO poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) HHIISSTTOORRYY The kkqquueeuuee() and kkeevveenntt() functions first appeared in FreeBSD 4.1. AAUUTTHHOORRSS The kkqquueeuuee() system and this manual page were written by Jonathan Lemon <_j_l_e_m_o_n_@_F_r_e_e_B_S_D_._o_r_g>. BBUUGGSS It is currently not possible to watch FIFOs or AIO that reside on anything but a UFS file system. Watching a vnode is possible on UFS, NFS and MS-DOS file systems. The _t_i_m_e_o_u_t value is limited to 24 hours; longer timeouts will be silently reinterpreted as 24 hours. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE __eexxiitt, __EExxiitt - terminate the calling process SSYYNNOOPPSSIISS ##iinncclluuddee <> _v_o_i_d __eexxiitt(_i_n_t _s_t_a_t_u_s); ##iinncclluuddee <> _v_o_i_d __EExxiitt(_i_n_t _s_t_a_t_u_s); DDEESSCCRRIIPPTTIIOONN The __eexxiitt() and __EExxiitt() functions terminate a process with the following consequences: ++oo All threads in the process are terminated. ++oo All open file descriptors in the calling process are closed. This may entail delays; for example, waiting for output to drain. A process in this state may not be killed, as it is already dying. ++oo If the parent process of the calling process has an outstanding wait(2) call or catches the SIGCHLD signal, it is notified of the calling process's termination and _s_t_a_t_u_s is set as defined by wait(2). (Note that typically only the lower 8 bits of _s_t_a_t_u_s are passed on to the parent, thus negative values have less meaning.) ++oo The parent process ID of all of the calling process's existing child processes are set to 1; the initialization process (see the DEFINITIONS section of intro(2)) inherits each of these processes. ++oo If the termination of the process causes any process group to become orphaned (usually because the parents of all members of the group have now exited; see Orphaned Process Group in intro(2)), and if any member of the orphaned group is stopped, the SIGHUP and SIGCONT signals are sent to all members of the newly orphaned process group. ++oo If the process is a controlling process (see intro(2)), the SIGHUP signal is sent to the foreground process group of the controlling terminal, and all current access to the controlling terminal is revoked. Most C programs call the library routine exit(3), which flushes buffers, closes streams, unlinks temporary files, etc., and then calls __eexxiitt(). RREETTUURRNN VVAALLUUEESS __eexxiitt() and __EExxiitt() can never return. SSEEEE AALLSSOO fork(2), intro(2), sigaction(2), wait(2), exit(3), sysexits(3) SSTTAANNDDAARRDDSS The __eexxiitt() function conform to IEEE Std 1003.1-2008 (``POSIX.1''). The __EExxiitt() function conforms to ISO/IEC 9899:1999 (``ISO C99''). HHIISSTTOORRYY An eexxiitt() system call first appeared in Version 1 AT&T UNIX. It accepts the _s_t_a_t_u_s argument since Version 2 AT&T UNIX. An __eexxiitt() variant first appeared in Version 7 AT&T UNIX. The __EExxiitt() function appeared in OpenBSD 3.6. NNAAMMEE ____ggeett__ttccbb, ____sseett__ttccbb - get and set the address of the thread control block of the current thread SSYYNNOOPPSSIISS _v_o_i_d _* ____ggeett__ttccbb(_v_o_i_d); _v_o_i_d ____sseett__ttccbb(_v_o_i_d _*); DDEESSCCRRIIPPTTIIOONN The ____ggeett__ttccbb() and ____sseett__ttccbb() functions are for use by librthread and other parts of the system runtime to retrieve and set the address of the current thread's thread control block (TCB). This is used to locate per- thread data such as _e_r_r_n_o. Each kernel-level thread in a process has a separate value for this address, which can be obtained and changed via these system calls. New threads (including the first thread of a new process) created using fork(2), vfork(2), or __tfork(2), inherit the TCB address of the thread that created them. execve(2) resets it to zero. On some platforms, this address is also directly mapped to a CPU register which can be accessed from userspace. RREETTUURRNN VVAALLUUEESS ____ggeett__ttccbb() returns the address of the thread control block of the current thread. SSEEEE AALLSSOO __tfork(2) HHIISSTTOORRYY The ____ggeett__ttccbb() and ____sseett__ttccbb() system calls appeared in OpenBSD 5.1. NNAAMMEE ____ggeett__ttccbb, ____sseett__ttccbb - get and set the address of the thread control block of the current thread SSYYNNOOPPSSIISS _v_o_i_d _* ____ggeett__ttccbb(_v_o_i_d); _v_o_i_d ____sseett__ttccbb(_v_o_i_d _*); DDEESSCCRRIIPPTTIIOONN The ____ggeett__ttccbb() and ____sseett__ttccbb() functions are for use by librthread and other parts of the system runtime to retrieve and set the address of the current thread's thread control block (TCB). This is used to locate per- thread data such as _e_r_r_n_o. Each kernel-level thread in a process has a separate value for this address, which can be obtained and changed via these system calls. New threads (including the first thread of a new process) created using fork(2), vfork(2), or __tfork(2), inherit the TCB address of the thread that created them. execve(2) resets it to zero. On some platforms, this address is also directly mapped to a CPU register which can be accessed from userspace. RREETTUURRNN VVAALLUUEESS ____ggeett__ttccbb() returns the address of the thread control block of the current thread. SSEEEE AALLSSOO __tfork(2) HHIISSTTOORRYY The ____ggeett__ttccbb() and ____sseett__ttccbb() system calls appeared in OpenBSD 5.1. NNAAMMEE ssyyssccaallll, ____ssyyssccaallll - indirect system call SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ssyyssccaallll(_i_n_t _n_u_m_b_e_r, _._._.); ____ssyyssccaallll(_q_u_a_d___t _n_u_m_b_e_r, _._._.); DDEESSCCRRIIPPTTIIOONN ssyyssccaallll() performs the system call whose assembly language interface has the specified _n_u_m_b_e_r with the specified arguments. Symbolic constants for system calls can be found in the header file <_s_y_s_/_s_y_s_c_a_l_l_._h>. Since different system calls have different return types, a prototype of ____ssyyssccaallll specifying the correct return type should be declared locally. This is especially important for system calls returning larger-than-int results. The ____ssyyssccaallll form should be used when one or more of the parameters is a 64-bit argument to ensure that argument alignment is correct. This system call is useful for testing new system calls that do not have entries in the C library. RREETTUURRNN VVAALLUUEESS The return values are defined by the system call being invoked. In general, for system calls returning _i_n_t, a 0 return value indicates success. A -1 return value indicates an error, and an error code is stored in _e_r_r_n_o. HHIISSTTOORRYY The predecessor of these functions, the former iinnddiirr() system call, first appeared in Version 4 AT&T UNIX. The ssyyssccaallll() function first appeared in 3BSD. BBUUGGSS There is no way to simulate system calls that have multiple return values such as pipe(2). NNAAMMEE ____ttffoorrkk__tthhrreeaadd, ____ttffoorrkk - create a new kernel thread in the current process SSYYNNOOPPSSIISS ##iinncclluuddee <> struct __tfork { void *tf_tcb; /* TCB address for new thread */ pid_t *tf_tid; /* where to write child's thread ID */ void *tf_stack; /* stack address for new thread */ }; _p_i_d___t ____ttffoorrkk__tthhrreeaadd(_c_o_n_s_t _s_t_r_u_c_t _____t_f_o_r_k _*_p_a_r_a_m_s, _s_i_z_e___t _p_s_i_z_e, _v_o_i_d _(_*_s_t_a_r_t_f_u_n_c_)_(_v_o_i_d _*_), _v_o_i_d _*_s_t_a_r_t_a_r_g); _p_i_d___t ____ttffoorrkk(_c_o_n_s_t _s_t_r_u_c_t _____t_f_o_r_k _*_p_a_r_a_m_s, _s_i_z_e___t _p_s_i_z_e); DDEESSCCRRIIPPTTIIOONN The ____ttffoorrkk__tthhrreeaadd() function creates a new kernel thread in the current process. The new thread starts by calling _s_t_a_r_t_f_u_n_c, passing _s_t_a_r_t_a_r_g as the only argument. If _s_t_a_r_t_f_u_n_c returns, the thread will exit. The _p_a_r_a_m_s argument provides parameters used by the kernel during thread creation. The new thread's thread control block (TCB) address is set to _t_f___t_c_b. If _t_f___t_i_d is not NULL, the new thread's thread ID is returned to the user at that address, with the guarantee that this is done before returning to userspace in either the calling thread or the new thread. If _t_f___s_t_a_c_k is not NULL, the new thread's stack is initialized to start at that address. On hppa and hppa64, that is the lowest address used; on other architectures that is the address after the highest address used. The _p_s_i_z_e argument provides the size of the _s_t_r_u_c_t _____t_f_o_r_k passed via the _p_a_r_a_m_s argument. The underlying system call used to create the thread is ____ttffoorrkk(). Because the new thread returns without a stack frame, the syscall cannot be directly used from C and is therefore not provided as a function. However, the syscall may show up in the output of kdump(1). RREETTUURRNN VVAALLUUEESS Upon successful completion, ____ttffoorrkk__tthhrreeaadd() returns in the calling thread the thread ID of new thread. The ____ttffoorrkk() syscall itself, on success, returns a value of 0 in the new thread and returns the thread ID of the new thread to the calling thread. Otherwise, a value of -1 is returned, no thread is created, and the global variable _e_r_r_n_o is set to indicate an error. EERRRROORRSS ____ttffoorrkk__tthhrreeaadd() and ____ttffoorrkk() will fail and no thread will be created if: [ENOMEM] Cannot allocate memory. The new process image required more memory than was allowed by the hardware or by system-imposed memory management constraints. A lack of swap space is normally temporary; however, a lack of core is not. Soft limits may be increased to their corresponding hard limits. [EINVAL] Invalid argument. Some invalid argument was supplied. [EAGAIN] Resource temporarily unavailable. The system-imposed limit on the total number of threads under execution would be exceeded. This limit is configuration- dependent. [EAGAIN] Resource temporarily unavailable. The system-imposed limit MAXUPRC on the total number of threads under execution by a single user would be exceeded. MAXUPRC is currently defined in <_s_y_s_/_p_a_r_a_m_._h> as CHILD_MAX, which is currently defined as 80 in <_s_y_s_/_s_y_s_l_i_m_i_t_s_._h>. SSTTAANNDDAARRDDSS The ____ttffoorrkk__tthhrreeaadd() function and ____ttffoorrkk() syscall are specific to OpenBSD and should not be used in portable applications. HHIISSTTOORRYY The ____ttffoorrkk__tthhrreeaadd() function and ____ttffoorrkk() syscall appeared in OpenBSD 5.1. NNAAMMEE ____tthhrrssiiggddiivveerrtt - synchronously accept a signal SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ____tthhrrssiiggddiivveerrtt(_s_i_g_s_e_t___t _s_e_t, _s_i_g_i_n_f_o___t _*_i_n_f_o, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t); DDEESSCCRRIIPPTTIIOONN The ____tthhrrssiiggddiivveerrtt() function is used to implement ssiiggwwaaiitt(). It selects a signal pending for the calling thread or process from _s_e_t, atomically clears it from that set of pending signals, and returns that signal number. If prior to the call to ____tthhrrssiiggddiivveerrtt() there are multiple pending instances of a single signal number, it is undefined whether upon successful return there are any remaining pending signals for that signal number. If no signal in _s_e_t is pending at the time of the call, the thread shall be suspended until one or more becomes pending. The signals defined by _s_e_t should have been blocked in all threads in the process at the time of the call to ____tthhrrssiiggddiivveerrtt(); otherwise the signal may be delivered to some thread that does not have it blocked. If more than one thread is using ____tthhrrssiiggddiivveerrtt() to wait for the same signal, no more than one of these threads shall return from ____tthhrrssiiggddiivveerrtt() for any given signal that is sent. Which thread returns from ____tthhrrssiiggddiivveerrtt() if more than a single thread is waiting is unspecified. If the _i_n_f_o argument is not NULL, then a _s_i_g_i_n_f_o___t will be stored there which has the selected signal number in its _s_i___s_i_g_n_o member and the cause of the signal in its _s_i___c_o_d_e member. If the _t_i_m_e_o_u_t argument is not NULL and no selected signal is currently pending, then ____tthhrrssiiggddiivveerrtt() will wait no longer than the specified time period for a signal to arrive before failing. RREETTUURRNN VVAALLUUEESS If successful, the number of the signal that was accepted is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. EERRRROORRSS ____tthhrrssiiggddiivveerrtt() will succeed unless: [EWOULDBLOCK] The timeout was reached before a selected signal was received. SSEEEE AALLSSOO sigaction(2), sigprocmask(2), sigwait(3) SSTTAANNDDAARRDDSS The ____tthhrrssiiggddiivveerrtt() function is specific to OpenBSD and should not be used in portable applications. HHIISSTTOORRYY A tthhrrssiiggddiivveerrtt() syscall appeared in OpenBSD 3.9. The _i_n_f_o and _t_i_m_e_o_u_t arguments were added in OpenBSD 4.9. AAUUTTHHOORRSS The tthhrrssiiggddiivveerrtt() syscall was created by Ted Unangst <_t_e_d_u_@_O_p_e_n_B_S_D_._o_r_g>. This manual page was written by Philip Guenther <_g_u_e_n_t_h_e_r_@_O_p_e_n_B_S_D_._o_r_g>. NNAAMMEE ____tthhrrsslleeeepp, ____tthhrrwwaakkeeuupp - userspace thread sleep and wakeup SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ____tthhrrsslleeeepp(_c_o_n_s_t _v_o_l_a_t_i_l_e _v_o_i_d _*_i_d, _c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_a_b_s_t_i_m_e, _v_o_i_d _*_l_o_c_k, _c_o_n_s_t _i_n_t _*_a_b_o_r_t); _i_n_t ____tthhrrwwaakkeeuupp(_c_o_n_s_t _v_o_l_a_t_i_l_e _v_o_i_d _*_i_d, _i_n_t _c_o_u_n_t); DDEESSCCRRIIPPTTIIOONN The ____tthhrrsslleeeepp() and ____tthhrrwwaakkeeuupp() functions provide thread sleep and wakeup primitives with which synchronization primitives such as mutexes and condition variables can be implemented. ____tthhrrsslleeeepp() blocks the calling thread on the abstract ``wait channel'' identified by the _i_d argument until another thread calls ____tthhrrwwaakkeeuupp() with the same _i_d value. If the _a_b_s_t_i_m_e argument is not NULL, then it specifies an absolute time, measured against the _c_l_o_c_k___i_d clock, after which ____tthhrrsslleeeepp() should time out and return. If the specified time is in the past then ____tthhrrsslleeeepp() will return immediately without blocking. The _l_o_c_k argument, if not NULL, points to a locked spinlock that will be unlocked by ____tthhrrsslleeeepp() atomically with respect to calls to ____tthhrrwwaakkeeuupp(), such that if another thread locks the spinlock before calling ____tthhrrwwaakkeeuupp() with the same _i_d, then the thread that called ____tthhrrsslleeeepp() will be eligible for being woken up and unblocked. The _a_b_o_r_t argument, if not NULL, points to an _i_n_t that will be examined after unlocking the spinlock pointed to by _l_o_c_k and immediately before blocking. If that _i_n_t is non-zero then ____tthhrrsslleeeepp() will immediately return EINTR without blocking. This provides a mechanism for a signal handler to keep a call to ____tthhrrsslleeeepp() from blocking, even if the signal is delivered immediately before the call. The ____tthhrrwwaakkeeuupp() function unblocks one or more threads that are sleeping on the wait channel identified by _i_d. The number of threads unblocked is specified by the _c_o_u_n_t argument, except that if zero is specified then all threads sleeping on that _i_d are unblocked. RREETTUURRNN VVAALLUUEESS ____tthhrrsslleeeepp() will return zero if woken by a matching call to ____tthhrrwwaakkeeuupp(), otherwise an error number will be returned to indicate the error. ____tthhrrwwaakkeeuupp() will return zero if at least one matching call to ____tthhrrsslleeeepp() was unblocked, otherwise an error number will be returned to indicate the error. EERRRROORRSS ____tthhrrsslleeeepp() and ____tthhrrwwaakkeeuupp() will fail if: [EINVAL] The _i_d_e_n_t argument is NULL. In addition, ____tthhrrsslleeeepp() may return one of the following errors: [EWOULDBLOCK] The time specified by the _a_b_s_t_i_m_e and _c_l_o_c_k___i_d arguments was reached. [EINTR] A signal arrived or the _a_b_o_r_t argument pointed to a non-zero value. [EINVAL] The _c_l_o_c_k___i_d argument is neither CLOCK_REALTIME nor CLOCK_MONOTONIC. ____tthhrrwwaakkeeuupp() may return the following error: [ESRCH] No threads calling ____tthhrrsslleeeepp() with the same _i_d were found. SSEEEE AALLSSOO pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9) SSTTAANNDDAARRDDSS The ____tthhrrsslleeeepp() and ____tthhrrwwaakkeeuupp() functions are specific to OpenBSD and should not be used in portable applications. HHIISSTTOORRYY The tthhrrsslleeeepp() and tthhrrwwaakkeeuupp() syscalls appeared in OpenBSD 3.9. The _c_l_o_c_k___i_d and _a_b_s_t_i_m_e arguments were added in OpenBSD 4.9. The functions were renamed to ____tthhrrsslleeeepp() and ____tthhrrwwaakkeeuupp() and the _a_b_o_r_t argument was added in OpenBSD 5.1 AAUUTTHHOORRSS The tthhrrsslleeeepp() and tthhrrwwaakkeeuupp() syscalls were created by Ted Unangst <_t_e_d_u_@_O_p_e_n_B_S_D_._o_r_g>. This manual page was written by Philip Guenther <_g_u_e_n_t_h_e_r_@_O_p_e_n_B_S_D_._o_r_g>. NNAAMMEE ____tthhrrsslleeeepp, ____tthhrrwwaakkeeuupp - userspace thread sleep and wakeup SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ____tthhrrsslleeeepp(_c_o_n_s_t _v_o_l_a_t_i_l_e _v_o_i_d _*_i_d, _c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_a_b_s_t_i_m_e, _v_o_i_d _*_l_o_c_k, _c_o_n_s_t _i_n_t _*_a_b_o_r_t); _i_n_t ____tthhrrwwaakkeeuupp(_c_o_n_s_t _v_o_l_a_t_i_l_e _v_o_i_d _*_i_d, _i_n_t _c_o_u_n_t); DDEESSCCRRIIPPTTIIOONN The ____tthhrrsslleeeepp() and ____tthhrrwwaakkeeuupp() functions provide thread sleep and wakeup primitives with which synchronization primitives such as mutexes and condition variables can be implemented. ____tthhrrsslleeeepp() blocks the calling thread on the abstract ``wait channel'' identified by the _i_d argument until another thread calls ____tthhrrwwaakkeeuupp() with the same _i_d value. If the _a_b_s_t_i_m_e argument is not NULL, then it specifies an absolute time, measured against the _c_l_o_c_k___i_d clock, after which ____tthhrrsslleeeepp() should time out and return. If the specified time is in the past then ____tthhrrsslleeeepp() will return immediately without blocking. The _l_o_c_k argument, if not NULL, points to a locked spinlock that will be unlocked by ____tthhrrsslleeeepp() atomically with respect to calls to ____tthhrrwwaakkeeuupp(), such that if another thread locks the spinlock before calling ____tthhrrwwaakkeeuupp() with the same _i_d, then the thread that called ____tthhrrsslleeeepp() will be eligible for being woken up and unblocked. The _a_b_o_r_t argument, if not NULL, points to an _i_n_t that will be examined after unlocking the spinlock pointed to by _l_o_c_k and immediately before blocking. If that _i_n_t is non-zero then ____tthhrrsslleeeepp() will immediately return EINTR without blocking. This provides a mechanism for a signal handler to keep a call to ____tthhrrsslleeeepp() from blocking, even if the signal is delivered immediately before the call. The ____tthhrrwwaakkeeuupp() function unblocks one or more threads that are sleeping on the wait channel identified by _i_d. The number of threads unblocked is specified by the _c_o_u_n_t argument, except that if zero is specified then all threads sleeping on that _i_d are unblocked. RREETTUURRNN VVAALLUUEESS ____tthhrrsslleeeepp() will return zero if woken by a matching call to ____tthhrrwwaakkeeuupp(), otherwise an error number will be returned to indicate the error. ____tthhrrwwaakkeeuupp() will return zero if at least one matching call to ____tthhrrsslleeeepp() was unblocked, otherwise an error number will be returned to indicate the error. EERRRROORRSS ____tthhrrsslleeeepp() and ____tthhrrwwaakkeeuupp() will fail if: [EINVAL] The _i_d_e_n_t argument is NULL. In addition, ____tthhrrsslleeeepp() may return one of the following errors: [EWOULDBLOCK] The time specified by the _a_b_s_t_i_m_e and _c_l_o_c_k___i_d arguments was reached. [EINTR] A signal arrived or the _a_b_o_r_t argument pointed to a non-zero value. [EINVAL] The _c_l_o_c_k___i_d argument is neither CLOCK_REALTIME nor CLOCK_MONOTONIC. ____tthhrrwwaakkeeuupp() may return the following error: [ESRCH] No threads calling ____tthhrrsslleeeepp() with the same _i_d were found. SSEEEE AALLSSOO pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9) SSTTAANNDDAARRDDSS The ____tthhrrsslleeeepp() and ____tthhrrwwaakkeeuupp() functions are specific to OpenBSD and should not be used in portable applications. HHIISSTTOORRYY The tthhrrsslleeeepp() and tthhrrwwaakkeeuupp() syscalls appeared in OpenBSD 3.9. The _c_l_o_c_k___i_d and _a_b_s_t_i_m_e arguments were added in OpenBSD 4.9. The functions were renamed to ____tthhrrsslleeeepp() and ____tthhrrwwaakkeeuupp() and the _a_b_o_r_t argument was added in OpenBSD 5.1 AAUUTTHHOORRSS The tthhrrsslleeeepp() and tthhrrwwaakkeeuupp() syscalls were created by Ted Unangst <_t_e_d_u_@_O_p_e_n_B_S_D_._o_r_g>. This manual page was written by Philip Guenther <_g_u_e_n_t_h_e_r_@_O_p_e_n_B_S_D_._o_r_g>. NNAAMMEE __eexxiitt, __EExxiitt - terminate the calling process SSYYNNOOPPSSIISS ##iinncclluuddee <> _v_o_i_d __eexxiitt(_i_n_t _s_t_a_t_u_s); ##iinncclluuddee <> _v_o_i_d __EExxiitt(_i_n_t _s_t_a_t_u_s); DDEESSCCRRIIPPTTIIOONN The __eexxiitt() and __EExxiitt() functions terminate a process with the following consequences: ++oo All threads in the process are terminated. ++oo All open file descriptors in the calling process are closed. This may entail delays; for example, waiting for output to drain. A process in this state may not be killed, as it is already dying. ++oo If the parent process of the calling process has an outstanding wait(2) call or catches the SIGCHLD signal, it is notified of the calling process's termination and _s_t_a_t_u_s is set as defined by wait(2). (Note that typically only the lower 8 bits of _s_t_a_t_u_s are passed on to the parent, thus negative values have less meaning.) ++oo The parent process ID of all of the calling process's existing child processes are set to 1; the initialization process (see the DEFINITIONS section of intro(2)) inherits each of these processes. ++oo If the termination of the process causes any process group to become orphaned (usually because the parents of all members of the group have now exited; see Orphaned Process Group in intro(2)), and if any member of the orphaned group is stopped, the SIGHUP and SIGCONT signals are sent to all members of the newly orphaned process group. ++oo If the process is a controlling process (see intro(2)), the SIGHUP signal is sent to the foreground process group of the controlling terminal, and all current access to the controlling terminal is revoked. Most C programs call the library routine exit(3), which flushes buffers, closes streams, unlinks temporary files, etc., and then calls __eexxiitt(). RREETTUURRNN VVAALLUUEESS __eexxiitt() and __EExxiitt() can never return. SSEEEE AALLSSOO fork(2), intro(2), sigaction(2), wait(2), exit(3), sysexits(3) SSTTAANNDDAARRDDSS The __eexxiitt() function conform to IEEE Std 1003.1-2008 (``POSIX.1''). The __EExxiitt() function conforms to ISO/IEC 9899:1999 (``ISO C99''). HHIISSTTOORRYY An eexxiitt() system call first appeared in Version 1 AT&T UNIX. It accepts the _s_t_a_t_u_s argument since Version 2 AT&T UNIX. An __eexxiitt() variant first appeared in Version 7 AT&T UNIX. The __EExxiitt() function appeared in OpenBSD 3.6. NNAAMMEE aacccceepptt, aacccceepptt44 - accept a connection on a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aacccceepptt(_i_n_t _s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_a_d_d_r, _s_o_c_k_l_e_n___t _*_a_d_d_r_l_e_n); _i_n_t aacccceepptt44(_i_n_t _s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_a_d_d_r, _s_o_c_k_l_e_n___t _*_a_d_d_r_l_e_n, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The argument _s is a socket that has been created with socket(2), bound to an address with bind(2), and is listening for connections after a listen(2). The aacccceepptt() call extracts the first connection request on the queue of pending connections, creates a new socket with the same non- blocking I/O mode as _s, and allocates a new file descriptor for the socket with the close-on-exec flag clear. The aacccceepptt44() system call is similar, however the non-blocking I/O mode of the new socket is determined by the SOCK_NONBLOCK flag in the _f_l_a_g_s argument and the close-on-exec flag on the new file descriptor is determined by the SOCK_CLOEXEC flag in the _f_l_a_g_s argument. If no pending connections are present on the queue, and the socket is not marked as non-blocking, aacccceepptt() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, aacccceepptt() returns an error as described below. The accepted socket may not be used to accept more connections. The original socket _s remains open. The argument _a_d_d_r is a result parameter that is filled in with the address of the connecting entity as known to the communications layer. The exact format of the _a_d_d_r parameter is determined by the domain in which the communication is occurring. The structure sockaddr_storage exists for greater portability. It is large enough to hold any of the types that may be returned in the _a_d_d_r parameter. The _a_d_d_r_l_e_n is a value-result parameter; it should initially contain the amount of space pointed to by _a_d_d_r; on return it will contain the actual length (in bytes) of the address returned. If _a_d_d_r_l_e_n does not point to enough space to hold the entire socket address, the result will be truncated to the initial value of _a_d_d_r_l_e_n (in bytes). This call is used with connection-based socket types, currently with SOCK_STREAM. It is possible to select(2) or poll(2) a socket for the purposes of doing an aacccceepptt() by selecting it for read. RREETTUURRNN VVAALLUUEESS The call returns -1 on error. If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. EEXXAAMMPPLLEESS The following code uses struct sockaddr_storage to allocate enough space for the returned address: #include #include struct sockaddr_storage addr; socklen_t len = sizeof(addr); int retcode; retcode = accept(s, (struct sockaddr *)&addr, &len); if (retcode == -1) err(1, "accept"); EERRRROORRSS aacccceepptt() and aacccceepptt44() will fail if: [EBADF] The descriptor is invalid. [ENOTSOCK] The descriptor doesn't reference a socket. [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM. [EINTR] A signal was caught before a connection arrived. [EINVAL] The referenced socket is not listening for connections (that is, listen(2) has not yet been called). [EFAULT] The _a_d_d_r or _a_d_d_r_l_e_n parameter is not in a valid part of the process address space. [EWOULDBLOCK] The socket is marked non-blocking and no connections are present to be accepted. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [ECONNABORTED] A connection has been aborted. In addition, aacccceepptt44() will fail if [EINVAL] _f_l_a_g_s is invalid. SSEEEE AALLSSOO bind(2), connect(2), listen(2), poll(2), select(2), socket(2) SSTTAANNDDAARRDDSS The aacccceepptt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The aacccceepptt44() function is expected to conform to a future revision of that standard. HHIISSTTOORRYY The aacccceepptt() system call first appeared in 4.1cBSD and aacccceepptt44() in OpenBSD 5.7. CCAAVVEEAATTSS When EMFILE or ENFILE is returned, new connections are neither dequeued nor discarded. Thus considerable care is required in select(2) and poll(2) loops. NNAAMMEE aacccceepptt, aacccceepptt44 - accept a connection on a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aacccceepptt(_i_n_t _s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_a_d_d_r, _s_o_c_k_l_e_n___t _*_a_d_d_r_l_e_n); _i_n_t aacccceepptt44(_i_n_t _s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_a_d_d_r, _s_o_c_k_l_e_n___t _*_a_d_d_r_l_e_n, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The argument _s is a socket that has been created with socket(2), bound to an address with bind(2), and is listening for connections after a listen(2). The aacccceepptt() call extracts the first connection request on the queue of pending connections, creates a new socket with the same non- blocking I/O mode as _s, and allocates a new file descriptor for the socket with the close-on-exec flag clear. The aacccceepptt44() system call is similar, however the non-blocking I/O mode of the new socket is determined by the SOCK_NONBLOCK flag in the _f_l_a_g_s argument and the close-on-exec flag on the new file descriptor is determined by the SOCK_CLOEXEC flag in the _f_l_a_g_s argument. If no pending connections are present on the queue, and the socket is not marked as non-blocking, aacccceepptt() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, aacccceepptt() returns an error as described below. The accepted socket may not be used to accept more connections. The original socket _s remains open. The argument _a_d_d_r is a result parameter that is filled in with the address of the connecting entity as known to the communications layer. The exact format of the _a_d_d_r parameter is determined by the domain in which the communication is occurring. The structure sockaddr_storage exists for greater portability. It is large enough to hold any of the types that may be returned in the _a_d_d_r parameter. The _a_d_d_r_l_e_n is a value-result parameter; it should initially contain the amount of space pointed to by _a_d_d_r; on return it will contain the actual length (in bytes) of the address returned. If _a_d_d_r_l_e_n does not point to enough space to hold the entire socket address, the result will be truncated to the initial value of _a_d_d_r_l_e_n (in bytes). This call is used with connection-based socket types, currently with SOCK_STREAM. It is possible to select(2) or poll(2) a socket for the purposes of doing an aacccceepptt() by selecting it for read. RREETTUURRNN VVAALLUUEESS The call returns -1 on error. If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. EEXXAAMMPPLLEESS The following code uses struct sockaddr_storage to allocate enough space for the returned address: #include #include struct sockaddr_storage addr; socklen_t len = sizeof(addr); int retcode; retcode = accept(s, (struct sockaddr *)&addr, &len); if (retcode == -1) err(1, "accept"); EERRRROORRSS aacccceepptt() and aacccceepptt44() will fail if: [EBADF] The descriptor is invalid. [ENOTSOCK] The descriptor doesn't reference a socket. [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM. [EINTR] A signal was caught before a connection arrived. [EINVAL] The referenced socket is not listening for connections (that is, listen(2) has not yet been called). [EFAULT] The _a_d_d_r or _a_d_d_r_l_e_n parameter is not in a valid part of the process address space. [EWOULDBLOCK] The socket is marked non-blocking and no connections are present to be accepted. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [ECONNABORTED] A connection has been aborted. In addition, aacccceepptt44() will fail if [EINVAL] _f_l_a_g_s is invalid. SSEEEE AALLSSOO bind(2), connect(2), listen(2), poll(2), select(2), socket(2) SSTTAANNDDAARRDDSS The aacccceepptt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The aacccceepptt44() function is expected to conform to a future revision of that standard. HHIISSTTOORRYY The aacccceepptt() system call first appeared in 4.1cBSD and aacccceepptt44() in OpenBSD 5.7. CCAAVVEEAATTSS When EMFILE or ENFILE is returned, new connections are neither dequeued nor discarded. Thus considerable care is required in select(2) and poll(2) loops. NNAAMMEE aacccceessss, ffaacccceessssaatt - check access permissions of a file or pathname SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aacccceessss(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _a_m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffaacccceessssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _a_m_o_d_e, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The aacccceessss() function checks the accessibility of the file named by _p_a_t_h for the access permissions indicated by _a_m_o_d_e. The _a_m_o_d_e argument is either the bitwise OR of one or more of the access permissions to be checked (R_OK for read permission, W_OK for write permission, and X_OK for execute/search permission) or the existence test, F_OK. All components of the pathname _p_a_t_h are checked for access permissions (including F_OK). The real user ID is used in place of the effective user ID and the real group access list (including the real group ID) is used in place of the effective ID for verifying permission. If the invoking process has superuser privileges, aacccceessss() will always indicate success for R_OK and W_OK, regardless of the actual file permission bits. Likewise, for X_OK, if the file has any of the execute bits set and _p_a_t_h is not a directory, aacccceessss() will indicate success. The ffaacccceessssaatt() function is equivalent to aacccceessss() except that where _p_a_t_h specifies a relative path, the file whose accessibility is checked is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffaacccceessssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. If _f_l_a_g is also zero, the behavior is identical to a call to aacccceessss(). The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_EACCESS The checks for accessibility are performed using the effective user and group IDs instead of the real user and group IDs. RREETTUURRNN VVAALLUUEESS If _p_a_t_h cannot be found or if any of the desired access modes would not be granted, then a -1 value is returned; otherwise a 0 value is returned. EERRRROORRSS Access to the file is denied if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EROFS] Write access is requested for a file on a read-only file system. [ETXTBSY] Write access is requested for a pure procedure (shared text) file presently being executed. [EACCES] Permission bits of the file mode do not permit the requested access, or search permission is denied on a component of the path prefix. The owner of a file has permission checked with respect to the ``owner'' read, write, and execute mode bits, members of the file's group other than the owner have permission checked with respect to the ``group'' mode bits, and all others have permissions checked with respect to the ``other'' mode bits. [EPERM] Write access has been requested and the named file has its immutable flag set (see chflags(2)). [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. [EINVAL] An invalid value was specified for _a_m_o_d_e. Additionally, ffaacccceessssaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_EACCESS. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chmod(2), stat(2) SSTTAANNDDAARRDDSS The aacccceessss() and ffaacccceessssaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY aacccceessss() first appeared as an internal kernel function in Version 1 AT&T UNIX and was reimplemented in C before the release of Version 4 AT&T UNIX. It was first promoted to a system call in the Programmer's Workbench (PWB/UNIX), which was later ported to Version 7 AT&T UNIX and 2BSD. The ffaacccceessssaatt() function appeared in OpenBSD 5.0. AAUUTTHHOORRSS Ken Thompson first implemented the aacccceessss() kernel function in C. CCAAVVEEAATTSS aacccceessss() and ffaacccceessssaatt() should never be used for actual access control. Doing so can result in a time of check vs. time of use security hole. NNAAMMEE aacccctt - enable or disable process accounting SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aacccctt(_c_o_n_s_t _c_h_a_r _*_f_i_l_e); DDEESSCCRRIIPPTTIIOONN The aacccctt() call enables or disables the collection of system accounting records. If _f_i_l_e is NULL, accounting is disabled. If _f_i_l_e is an existing, NUL-terminated pathname, record collection is enabled and for every process initiated which terminates under normal conditions an accounting record is appended to _f_i_l_e. Abnormal conditions of termination are reboots or other fatal system problems. Records for processes which never terminate cannot be produced by aacccctt(). aacccctt() is only available on kernels compiled with the AACCCCOOUUNNTTIINNGG option. For more information on the record structure used by aacccctt(), see _/_u_s_r_/_i_n_c_l_u_d_e_/_s_y_s_/_a_c_c_t_._h and acct(5). This call is permitted only to the superuser. NNOOTTEESS Accounting is automatically disabled when the file system the accounting file resides on runs out of space; it is enabled when space once again becomes available. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS aacccctt() will fail if one of the following is true: [EPERM] The caller is not the superuser. [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix, or the path name is not a regular file. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EROFS] The named file resides on a read-only file system. [EFAULT] _f_i_l_e points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO acct(5), accton(8), sa(8) HHIISSTTOORRYY An aacccctt() function call appeared in Version 7 AT&T UNIX. NNAAMMEE aaddjjffrreeqq - correct the rate of the system clock SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t aaddjjffrreeqq(_c_o_n_s_t _i_n_t_6_4___t _*_f_r_e_q, _i_n_t_6_4___t _*_o_l_d_f_r_e_q); DDEESSCCRRIIPPTTIIOONN aaddjjffrreeqq() adjusts the rate in which time progresses if _f_r_e_q is non-null. The unit of the rate of adjustment is nanoseconds per second, shifted left 32 bits to allow for fractional values. If _o_l_d_f_r_e_q is non-null, the current value is returned. Only the superuser may adjust the frequency. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS aaddjjffrreeqq() will fail if: [EFAULT] Either of the arguments point outside the process's allocated address space. [EPERM] The _f_r_e_q argument is non-null and the process's effective user ID is not that of the superuser. SSEEEE AALLSSOO date(1), adjtime(2), gettimeofday(2), ntpd(8) HHIISSTTOORRYY The aaddjjffrreeqq() function call first appeared in OpenBSD 4.0. NNAAMMEE aaddjjttiimmee - correct the time to allow synchronization of the system clock SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aaddjjttiimmee(_c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_d_e_l_t_a, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_o_l_d_d_e_l_t_a); DDEESSCCRRIIPPTTIIOONN aaddjjttiimmee() makes small adjustments to the system time, as returned by gettimeofday(2), advancing or retarding it by the time specified by the timeval _d_e_l_t_a. If _d_e_l_t_a is negative, the clock is slowed down by incrementing it more slowly than normal until the correction is complete. If _d_e_l_t_a is positive, a larger increment than normal is used. The skew used to perform the correction is generally a fraction of one percent. Thus, the time is always a monotonically increasing function. A time correction from an earlier call to aaddjjttiimmee() may not be finished when aaddjjttiimmee() is called again. If _d_e_l_t_a is null, no adjustment is done. If _o_l_d_d_e_l_t_a is non-null, the structure pointed to will contain, upon return, the number of microseconds still to be corrected from the earlier call. Setting the time with settimeofday(2) will cancel any in-progress time adjustment. This call may be used by time servers that synchronize the clocks of computers in a local area network. Such time servers would slow down the clocks of some machines and speed up the clocks of others to bring them to the average network time. Only the superuser may adjust the time using the aaddjjttiimmee() function. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS aaddjjttiimmee() will fail if: [EFAULT] Either of the arguments point outside the process's allocated address space. [EPERM] The ddeellttaa() argument is non-null and the process's effective user ID is not that of the superuser. SSEEEE AALLSSOO date(1), adjfreq(2), gettimeofday(2), ntpd(8) HHIISSTTOORRYY The aaddjjttiimmee() function call appeared in 4.3BSD. CCAAVVEEAATTSS Other operating systems restrict calling kkqquueeuuee to the superuser and might not allow requesting the current correction without specifying a new value. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE ddeennssee__bbaassee, iinnbb, iinnll, iinnww, iiooppeerrmm, mmaapp__mmeemmoorryy, oouuttbb, oouuttll, oouuttww, rreeaaddbb, rreeaaddll, rreeaaddww, uunnmmaapp__mmeemmoorryy, wwrriitteebb, wwrriitteell, wwrriitteeww - Alpha devices I/O ports and memory access functions SSYYNNOOPPSSIISS _u___i_n_t_6_4___t ddeennssee__bbaassee(_v_o_i_d); _u___i_n_t_8___t iinnbb(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_3_2___t iinnll(_u___i_n_t_3_2___t _p_o_r_t); _u___i_n_t_1_6___t iinnww(_u___i_n_t_3_2___t _p_o_r_t); _i_n_t iiooppeerrmm(_u_n_s_i_g_n_e_d _l_o_n_g _f_r_o_m, _u_n_s_i_g_n_e_d _l_o_n_g _n_u_m, _i_n_t _o_n); _v_o_i_d _* mmaapp__mmeemmoorryy(_u___i_n_t_3_2___t _a_d_d_r_e_s_s, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d oouuttbb(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d oouuttll(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d oouuttww(_u___i_n_t_3_2___t _p_o_r_t, _u___i_n_t_1_6___t _v_a_l); _u___i_n_t_8___t rreeaaddbb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_3_2___t rreeaaddll(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _u___i_n_t_1_6___t rreeaaddww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t); _v_o_i_d uunnmmaapp__mmeemmoorryy(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _s_i_z_e); _v_o_i_d wwrriitteebb(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_8___t _v_a_l); _v_o_i_d wwrriitteell(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_3_2___t _v_a_l); _v_o_i_d wwrriitteeww(_v_o_i_d _*_h_a_n_d_l_e, _u___i_n_t_3_2___t _o_f_f_s_e_t, _u___i_n_t_1_6___t _v_a_l); DDEESSCCRRIIPPTTIIOONN The functions in libalpha give userland programs access to the I/O ports on the OpenBSD/alpha platform. The iinn**() functions return data read from the specified I/O port. The oouutt**() functions write data to the specified I/O port. iiooppeerrmm() enables access to the specified port numbers if _o_n is TRUE and disables access if _o_n is FALSE. The mmaapp__mmeemmoorryy() function allows a user program to map part of a device memory. The uunnmmaapp__mmeemmoorryy() function unmaps memory that was previously mapped by mmaapp__mmeemmoorryy(). The rreeaadd**() functions read data from device memory previously mapped by mmaapp__mmeemmoorryy(). The wwrriittee**() functions write data to the device memory previously mapped by mmaapp__mmeemmoorryy(). NNoottee: Code using these functions must be compiled using --llaallpphhaa. HHIISSTTOORRYY These functions originally appeared in FreeBSD. CCAAVVEEAATTSS Only BWX bus access method is supported for now. Machines requiring swiz type access are not supported. Root credentials are needed to use these functions. NNAAMMEE aammdd6644__ggeett__ffssbbaassee, aammdd6644__sseett__ffssbbaassee - manage amd64 per-thread %fs base address SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t aammdd6644__ggeett__ffssbbaassee(_v_o_i_d _*_*_b_a_s_e); _i_n_t aammdd6644__sseett__ffssbbaassee(_v_o_i_d _*_b_a_s_e); DDEESSCCRRIIPPTTIIOONN aammdd6644__ggeett__ffssbbaassee() copies the current base address of the %fs segment into the memory referenced by _b_a_s_e. aammdd6644__sseett__ffssbbaassee() sets the base address of the %fs segment to the address _b_a_s_e. The segment base address is local to each thread. The initial thread of a new process inherits its segment base address from the parent thread. __tfork(2) sets the initial segment base address for threads that it creates. NNoottee:: Code using the aammdd6644__ggeett__ffssbbaassee() and aammdd6644__sseett__ffssbbaassee() functions must be compiled using --llaammdd6644. RREETTUURRNN VVAALLUUEESS Upon successful completion, aammdd6644__ggeett__ffssbbaassee() and aammdd6644__sseett__ffssbbaassee() return 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS aammdd6644__ggeett__ffssbbaassee() will fail if: [EFAULT] _b_a_s_e points outside the process's allocated address space. SSEEEE AALLSSOO __tfork(2), fork(2) WWAARRNNIINNGG The ELF Thread-Local Storage ABI reserves %fs for its own use and requires that the dynamic linker and thread library set it to reference data-structures internal to and shared between them. Programs should use the __thread storage class keyword instead of using these calls. To be maximally portable, programs that require per-thread data should use the pptthhrreeaadd__kkeeyy__ccrreeaattee() interface. NNAAMMEE aammdd6644__iiooppll - change the amd64 I/O privilege level SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t aammdd6644__iiooppll(_i_n_t _i_o_p_l); DDEESSCCRRIIPPTTIIOONN aammdd6644__iiooppll() sets the amd64 I/O privilege level to the value specified by _i_o_p_l. This call may only be made by the superuser. Additionally, it is only permitted when the securelevel(7) is less than or equal to 0 or the _m_a_c_h_d_e_p_._a_l_l_o_w_a_p_e_r_t_u_r_e sysctl has been set to a non-zero value. NNoottee:: Code using the aammdd6644__iiooppll() function must be compiled using --llaammdd6644. RREETTUURRNN VVAALLUUEESS Upon successful completion, aammdd6644__iiooppll() returns 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS aammdd6644__iiooppll() will fail if: [EPERM] The caller was not the superuser, or the securelevel is greater than zero and _m_a_c_h_d_e_p_._a_l_l_o_w_a_p_e_r_t_u_r_e has not been set to a non- zero value. SSEEEE AALLSSOO securelevel(7) RREEFFEERREENNCCEESS Intel, _A_M_D_6_4 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. WWAARRNNIINNGG You can really hose your machine if you enable user-level I/O and write to hardware ports without care. NNAAMMEE aammdd6644__ggeett__ffssbbaassee, aammdd6644__sseett__ffssbbaassee - manage amd64 per-thread %fs base address SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t aammdd6644__ggeett__ffssbbaassee(_v_o_i_d _*_*_b_a_s_e); _i_n_t aammdd6644__sseett__ffssbbaassee(_v_o_i_d _*_b_a_s_e); DDEESSCCRRIIPPTTIIOONN aammdd6644__ggeett__ffssbbaassee() copies the current base address of the %fs segment into the memory referenced by _b_a_s_e. aammdd6644__sseett__ffssbbaassee() sets the base address of the %fs segment to the address _b_a_s_e. The segment base address is local to each thread. The initial thread of a new process inherits its segment base address from the parent thread. __tfork(2) sets the initial segment base address for threads that it creates. NNoottee:: Code using the aammdd6644__ggeett__ffssbbaassee() and aammdd6644__sseett__ffssbbaassee() functions must be compiled using --llaammdd6644. RREETTUURRNN VVAALLUUEESS Upon successful completion, aammdd6644__ggeett__ffssbbaassee() and aammdd6644__sseett__ffssbbaassee() return 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS aammdd6644__ggeett__ffssbbaassee() will fail if: [EFAULT] _b_a_s_e points outside the process's allocated address space. SSEEEE AALLSSOO __tfork(2), fork(2) WWAARRNNIINNGG The ELF Thread-Local Storage ABI reserves %fs for its own use and requires that the dynamic linker and thread library set it to reference data-structures internal to and shared between them. Programs should use the __thread storage class keyword instead of using these calls. To be maximally portable, programs that require per-thread data should use the pptthhrreeaadd__kkeeyy__ccrreeaattee() interface. NNAAMMEE aarrmm__ddrraaiinn__wwrriitteebbuuff - drains the CPU write buffer SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aarrmm__ddrraaiinn__wwrriitteebbuuff(); DDEESSCCRRIIPPTTIIOONN aarrmm__ddrraaiinn__wwrriitteebbuuff() will make sure that all the entries in the processor write buffer are written out to memory. Not all processors support this operation (currently only the SA110 does). Those processes that do not, treat this function as a null-op. EERRRROORRSS aarrmm__ddrraaiinn__wwrriitteebbuuff() will never fail so will always return 0. RREEFFEERREENNCCEESS StrongARM Data Sheet NNAAMMEE aarrmm__ssyynncc__iiccaacchhee - clean the CPU data cache and flush the CPU instruction cache SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aarrmm__ssyynncc__iiccaacchhee(_u___i_n_t _a_d_d_r, _i_n_t _l_e_n); DDEESSCCRRIIPPTTIIOONN aarrmm__ssyynncc__iiccaacchhee() will make sure that all the entries in the processor instruction cache are synchronized with main memory and that any data in a write back cache has been cleaned. Some ARM processors (e.g. SA110) have separate instruction and data caches, thus any dynamically generated or modified code needs to be written back from any data caches to main memory and the instruction cache needs to be synchronized with main memory. On such processors, aarrmm__ssyynncc__iiccaacchhee() will clean the data cache and invalidate the processor instruction cache to force reloading from main memory. On processors that have a shared instruction and data cache and have a write through cache (e.g. ARM6), no action needs to be taken. The routine takes a start address _a_d_d_r and a length _l_e_n to describe the area of memory that needs to be cleaned and synchronized. EERRRROORRSS aarrmm__ssyynncc__iiccaacchhee() will never fail so will always return 0. RREEFFEERREENNCCEESS StrongARM Data Sheet NNAAMMEE bbiinndd - bind a name to a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t bbiinndd(_i_n_t _s, _c_o_n_s_t _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_n_a_m_e, _s_o_c_k_l_e_n___t _n_a_m_e_l_e_n); DDEESSCCRRIIPPTTIIOONN bbiinndd() assigns a name to an unnamed socket. When a socket is created with socket(2) it exists in a name space (address family) but has no name assigned. bbiinndd() requests that _n_a_m_e be assigned to the socket. _n_a_m_e_l_e_n indicates the amount of space pointed to by _n_a_m_e, in bytes. NNOOTTEESS Binding a name in the UNIX-domain creates a socket in the file system that must be deleted by the caller when it is no longer needed (using unlink(2)). The rules used in name binding vary between communication domains. Consult the manual entries in section 4 for detailed information. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The bbiinndd() function will fail if: [EBADF] _s is not a valid descriptor. [ENOTSOCK] _s is not a socket. [EADDRNOTAVAIL] The specified address is not available from the local machine. [EADDRINUSE] The specified address is already in use. [EINVAL] The socket is already bound to an address, or _n_a_m_e_l_e_n is not a valid length for the supplied address. [EAFNOSUPPORT] The family of the socket and that requested in _n_a_m_e_-_>_s_a___f_a_m_i_l_y are not equivalent. [ENOBUFS] Insufficient buffer space is available. [EACCES] The requested address is protected, and the current user has inadequate permission to access it. [EFAULT] The _n_a_m_e parameter is not in a valid part of the user address space. The following errors are specific to binding names in the UNIX-domain. [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A prefix component of the path name does not exist. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [EROFS] The name would reside on a read-only file system. [EISDIR] An empty pathname was specified. SSEEEE AALLSSOO connect(2), getsockname(2), listen(2), socket(2) SSTTAANNDDAARRDDSS The bbiinndd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The bbiinndd() system call first appeared in 4.1cBSD. NNAAMMEE bbrrkk, ssbbrrkk - change data segment size SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t bbrrkk(_v_o_i_d _*_a_d_d_r); _v_o_i_d _* ssbbrrkk(_i_n_t _i_n_c_r); DDEESSCCRRIIPPTTIIOONN TThhee bbrrkk(()) aanndd ssbbrrkk(()) ffuunnccttiioonnss aarree hhiissttoorriiccaall ccuurriioossiittiieess lleefftt oovveerr ffrroomm eeaarrlliieerr ddaayyss bbeeffoorree tthhee aaddvveenntt ooff vviirrttuuaall mmeemmoorryy mmaannaaggeemmeenntt.. The bbrrkk() function sets the break or lowest address of a process's data segment (uninitialized data) to _a_d_d_r (immediately above bss). Data addressing is restricted between _a_d_d_r and the lowest stack pointer to the stack segment. Memory is allocated by bbrrkk() in page size pieces; if _a_d_d_r is not evenly divisible by the system page size, it is increased to the next page boundary. The current value of the program break is reliably returned by ``sbrk(0)'' (see also end(3)). The getrlimit(2) system call may be used to determine the maximum permissible size of the _d_a_t_a segment; it will not be possible to set the break beyond the _r_l_i_m___m_a_x value returned from a call to getrlimit(2), e.g., ``etext + rlp->rlim_max'' (see end(3) for the definition of _e_t_e_x_t). RREETTUURRNN VVAALLUUEESS The bbrrkk() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. The ssbbrrkk() function returns a pointer to the base of the new storage if successful; otherwise -1 with _e_r_r_n_o set to indicate why the allocation failed. EERRRROORRSS ssbbrrkk() will fail and no additional memory will be allocated if one of the following are true: [ENOMEM] The limit, as set by setrlimit(2), was exceeded. [ENOMEM] The maximum possible size of a data segment (compiled into the system) was exceeded. [ENOMEM] Insufficient space existed in the swap area to support the expansion. SSEEEE AALLSSOO execve(2), getrlimit(2), mmap(2), end(3), malloc(3) HHIISSTTOORRYY A bbrrkk() function call appeared in Version 7 AT&T UNIX. BBUUGGSS Setting the break may fail due to a temporary lack of swap space. It is not possible to distinguish this from a failure caused by exceeding the maximum size of the data segment without consulting getrlimit(2). NNAAMMEE cchhddiirr, ffcchhddiirr - change current working directory SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhddiirr(_c_o_n_s_t _c_h_a_r _*_p_a_t_h); _i_n_t ffcchhddiirr(_i_n_t _f_d); DDEESSCCRRIIPPTTIIOONN The _p_a_t_h argument points to the pathname of a directory. The cchhddiirr() function causes the named directory to become the current working directory, that is, the starting point for path searches of pathnames not beginning with a slash (`/'). The ffcchhddiirr() function causes the directory referenced by _f_d to become the current working directory, the starting point for path searches of pathnames not beginning with a slash (`/'). In order for a directory to become the current directory, a process must have execute (search) access to the directory. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhddiirr() will fail and the current working directory will be unchanged if one or more of the following are true: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named directory does not exist. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EACCES] Search permission is denied for any component of the pathname. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from the file system. ffcchhddiirr() will fail and the current working directory will be unchanged if one or more of the following are true: [EACCES] Search permission is denied for the directory referenced by the file descriptor. [ENOTDIR] The file descriptor does not reference a directory. [EBADF] The argument _f_d is not a valid file descriptor. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chroot(2) SSTTAANNDDAARRDDSS The cchhddiirr() and ffcchhddiirr() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhddiirr() system call first appeared in Version 1 AT&T UNIX, and ffcchhddiirr() in 4.3BSD-Reno. NNAAMMEE cchhffllaaggss, cchhffllaaggssaatt, ffcchhffllaaggss - set file flags SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhffllaaggss(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s); _i_n_t ffcchhffllaaggss(_i_n_t _f_d, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t cchhffllaaggssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s, _i_n_t _a_t_f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The file whose name is given by _p_a_t_h or referenced by the descriptor _f_d has its flags changed to _f_l_a_g_s. The flags are the bitwise OR of zero or more of the following values: UF_NODUMP Do not dump the file. UF_IMMUTABLE The file may not be changed. UF_APPEND The file may only be appended to. SF_ARCHIVED The file may be archived. SF_IMMUTABLE The file may not be changed. SF_APPEND The file may only be appended to. The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the owner of a file or the superuser. The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or unset by the superuser. They may be set at any time, but normally may only be unset when the system is in single-user mode. (See init(8) for details.) The cchhffllaaggssaatt() function is equivalent to cchhffllaaggss() except in the case where _p_a_t_h specifies a relative path. In this case the file to be changed is determined relative to the directory associated with the file descriptor _f_d instead of the current working directory. If cchhffllaaggssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. If _f_l_a_g is also zero, the behavior is identical to a call to cchhffllaaggss(). The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the flags of the symbolic link are changed. The ffcchhffllaaggss() function is equivalent to cchhffllaaggss() except that the file whose flags are changed is specified by the file descriptor _f_d. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhffllaaggss() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser, or the effective user ID is not the superuser and at least one of the super-user-only flags for the named file would be changed. [EOPNOTSUPP] The named file resides on a file system that does not support file flags. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. [EINVAL] The _f_l_a_g_s value is invalid. [EINVAL] The descriptor references a block or character device and the effective user ID is not the superuser. ffcchhffllaaggss() will fail if: [EBADF] The descriptor is not valid. [EINVAL] _f_d refers to a socket, not to a file. [EINVAL] The descriptor references a block or character device and the effective user ID is not the superuser. [EINVAL] The _f_l_a_g_s value is invalid. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser, or the effective user ID is not the superuser and at least one of the super-user-only flags for the named file would be changed. [EOPNOTSUPP] The named file resides on a file system that does not support file flags. [EROFS] The file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chflags(1), init(8) HHIISSTTOORRYY The cchhffllaaggss() and ffcchhffllaaggss() functions first appeared in 4.4BSD. The cchhffllaaggssaatt() function first appeared in FreeBSD 10.0. It was added to OpenBSD in OpenBSD 5.7. NNAAMMEE cchhffllaaggss, cchhffllaaggssaatt, ffcchhffllaaggss - set file flags SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhffllaaggss(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s); _i_n_t ffcchhffllaaggss(_i_n_t _f_d, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t cchhffllaaggssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s, _i_n_t _a_t_f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The file whose name is given by _p_a_t_h or referenced by the descriptor _f_d has its flags changed to _f_l_a_g_s. The flags are the bitwise OR of zero or more of the following values: UF_NODUMP Do not dump the file. UF_IMMUTABLE The file may not be changed. UF_APPEND The file may only be appended to. SF_ARCHIVED The file may be archived. SF_IMMUTABLE The file may not be changed. SF_APPEND The file may only be appended to. The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the owner of a file or the superuser. The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or unset by the superuser. They may be set at any time, but normally may only be unset when the system is in single-user mode. (See init(8) for details.) The cchhffllaaggssaatt() function is equivalent to cchhffllaaggss() except in the case where _p_a_t_h specifies a relative path. In this case the file to be changed is determined relative to the directory associated with the file descriptor _f_d instead of the current working directory. If cchhffllaaggssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. If _f_l_a_g is also zero, the behavior is identical to a call to cchhffllaaggss(). The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the flags of the symbolic link are changed. The ffcchhffllaaggss() function is equivalent to cchhffllaaggss() except that the file whose flags are changed is specified by the file descriptor _f_d. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhffllaaggss() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser, or the effective user ID is not the superuser and at least one of the super-user-only flags for the named file would be changed. [EOPNOTSUPP] The named file resides on a file system that does not support file flags. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. [EINVAL] The _f_l_a_g_s value is invalid. [EINVAL] The descriptor references a block or character device and the effective user ID is not the superuser. ffcchhffllaaggss() will fail if: [EBADF] The descriptor is not valid. [EINVAL] _f_d refers to a socket, not to a file. [EINVAL] The descriptor references a block or character device and the effective user ID is not the superuser. [EINVAL] The _f_l_a_g_s value is invalid. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser, or the effective user ID is not the superuser and at least one of the super-user-only flags for the named file would be changed. [EOPNOTSUPP] The named file resides on a file system that does not support file flags. [EROFS] The file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chflags(1), init(8) HHIISSTTOORRYY The cchhffllaaggss() and ffcchhffllaaggss() functions first appeared in 4.4BSD. The cchhffllaaggssaatt() function first appeared in FreeBSD 10.0. It was added to OpenBSD in OpenBSD 5.7. NNAAMMEE cchhmmoodd, ffcchhmmooddaatt, ffcchhmmoodd - change mode of file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhmmoodd(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); _i_n_t ffcchhmmoodd(_i_n_t _f_d, _m_o_d_e___t _m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffcchhmmooddaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The cchhmmoodd() function sets the file permission bits of the file specified by the pathname _p_a_t_h to _m_o_d_e. cchhmmoodd() verifies that the process owner (user) either owns the specified file or is the superuser. The _m_o_d_e argument is the bitwise OR of zero or more of the permission bit masks from the following list: #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ #define S_ISUID 0004000 /* set user id on execution */ #define S_ISGID 0002000 /* set group id on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ If mode ISVTX (the _s_t_i_c_k_y _b_i_t) is set on a file, it is ignored. If mode ISVTX (the _s_t_i_c_k_y _b_i_t) is set on a directory, an unprivileged user may not delete or rename files of other users in that directory. The sticky bit may be set by any user on a directory which the user owns or has appropriate permissions. For more details of the properties of the sticky bit, see sticky(8). Writing or changing the owner of a file turns off the set-user-ID and set-group-ID bits unless the user is the superuser. This makes the system somewhat more secure by protecting set-user-ID (set-group-ID) files from remaining set-user-ID (set-group-ID) if they are modified, at the expense of a degree of compatibility. The ffcchhmmooddaatt() function is equivalent to cchhmmoodd() except in the case where _p_a_t_h specifies a relative path. In this case the file to be changed is determined relative to the directory associated with the file descriptor _f_d instead of the current working directory. If ffcchhmmooddaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. If _f_l_a_g is also zero, the behavior is identical to a call to cchhmmoodd(). The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the mode of the symbolic link is changed. The ffcchhmmoodd() function is equivalent to cchhmmoodd() except that the file whose permissions are changed is specified by the file descriptor _f_d. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The cchhmmoodd() and ffcchhmmooddaatt() functions will fail and the file mode will be unchanged if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EINVAL] _m_o_d_e contains bits other than the file type and those described above. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, the ffcchhmmooddaatt() function will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EOPNOTSUPP] The _f_l_a_g argument specifies AT_SYMLINK_NOFOLLOW on a symbolic link and the file system does not support that operation. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffcchhmmoodd() will fail and the file mode will be unchanged if: [EBADF] The descriptor is not valid. [EINVAL] _f_d refers to a socket, not to a file. [EINVAL] _m_o_d_e contains bits other than the file type and those described above. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser. [EROFS] The file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chmod(1), chown(2), open(2), stat(2), sticky(8) SSTTAANNDDAARRDDSS The cchhmmoodd(), ffcchhmmoodd(), and ffcchhmmooddaatt() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhmmoodd() system call first appeared in Version 1 AT&T UNIX; ffcchhmmoodd() in 4.1cBSD; and ffcchhmmooddaatt() has been available since OpenBSD 5.0. NNAAMMEE cchhoowwnn, llcchhoowwnn, ffcchhoowwnnaatt, ffcchhoowwnn - change owner and group of a file or link SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhoowwnn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); _i_n_t llcchhoowwnn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); _i_n_t ffcchhoowwnn(_i_n_t _f_d, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffcchhoowwnnaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The owner ID and group ID of the file (or link) named by _p_a_t_h or referenced by _f_d is changed as specified by the arguments _o_w_n_e_r and _g_r_o_u_p. The owner of a file may change the _g_r_o_u_p to a group of which he or she is a member, but the change _o_w_n_e_r capability is restricted to the superuser. By default, cchhoowwnn() clears the set-user-ID and set-group-ID bits on the file to prevent accidental or mischievous creation of set-user-ID and set-group-ID programs. This behaviour can be overridden by setting the sysctl(8) variable _f_s_._p_o_s_i_x_._s_e_t_u_i_d to zero. llcchhoowwnn() operates similarly to how cchhoowwnn() operated on older systems, and does not follow symbolic links. It allows the owner and group of a symbolic link to be set. The ffcchhoowwnnaatt() function is equivalent to either the cchhoowwnn() or llcchhoowwnn() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose ownership is changed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffcchhoowwnnaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to cchhoowwnn() or llcchhoowwnn(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the ownership of the symbolic link is changed. ffcchhoowwnn() is particularly useful when used in conjunction with the file locking primitives (see flock(2)). One of the owner or group IDs may be left unchanged by specifying it as -1. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhoowwnn(), llcchhoowwnn(), and ffcchhoowwnnaatt() will fail and the file or link will be unchanged if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffcchhoowwnnaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffcchhoowwnn() will fail if: [EBADF] _f_d does not refer to a valid descriptor. [EINVAL] _f_d refers to a socket, not a file. [EPERM] The effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chgrp(1), chmod(2), flock(2), chown(8) SSTTAANNDDAARRDDSS The cchhoowwnn(), ffcchhoowwnn(), ffcchhoowwnnaatt(), and llcchhoowwnn() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhoowwnn() system call first appeared in Version 1 AT&T UNIX. Since Version 6 AT&T UNIX it supports changing the group as well, and in Version 7 AT&T UNIX _g_r_o_u_p was made a separate argument. The ffcchhoowwnn() system call first appeared in 4.1cBSD. The cchhoowwnn() and ffcchhoowwnn() system calls were changed to follow symbolic links in 4.4BSD; therefore, and for compatibility with AT&T System V Release 4 UNIX, the llcchhoowwnn() system call was added to OpenBSD 2.1. The ffcchhoowwnnaatt() system call has been available since OpenBSD 5.0. NNAAMMEE cchhrroooott - change root directory SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhrroooott(_c_o_n_s_t _c_h_a_r _*_d_i_r_n_a_m_e); DDEESSCCRRIIPPTTIIOONN _d_i_r_n_a_m_e is the address of the pathname of a directory, terminated by an ASCII NUL. cchhrroooott() causes _d_i_r_n_a_m_e to become the root directory, that is, the starting point for path searches of pathnames beginning with `/'. In order for a directory to become the root directory a process must have execute (search) access for that directory. If the program is not currently running with an altered root directory, it should be noted that cchhrroooott() has no effect on the process's current directory. If the program is already running with an altered root directory, the process's current directory is changed to the same new root directory. This prevents the current directory from being further up the directory tree than the altered root directory. This call is restricted to the superuser. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EEXXAAMMPPLLEESS The following example changes the root directory to _n_e_w_r_o_o_t, sets the current directory to the new root, and drops some setuid privileges. There may be other privileges which need to be dropped as well. #include #include if (chroot(newroot) != 0 || chdir("/") != 0) err(1, "%s", newroot); setresuid(getuid(), getuid(), getuid()); EERRRROORRSS cchhrroooott() will fail and the root directory will be unchanged if: [ENOTDIR] A component of the path name is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named directory does not exist. [EACCES] Search permission is denied for any component of the path name. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _d_i_r_n_a_m_e points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. [EPERM] The caller is not the superuser. SSEEEE AALLSSOO chdir(2) HHIISSTTOORRYY The cchhrroooott() system call first appeared in Version 7 AT&T UNIX. CCAAVVEEAATTSS There are ways for a root process to escape from the chroot jail. Changes to the directory hierarchy made from outside the chroot jail may allow a restricted process to escape, even if it is unprivileged. Passing directory file descriptors via recvmsg(2) from outside the chroot jail may also allow a process to escape. NNAAMMEE cclloocckk__ggeettttiimmee, cclloocckk__sseettttiimmee, cclloocckk__ggeettrreess - get/set/calibrate date and time SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cclloocckk__ggeettttiimmee(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); _i_n_t cclloocckk__sseettttiimmee(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); _i_n_t cclloocckk__ggeettrreess(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); DDEESSCCRRIIPPTTIIOONN The cclloocckk__ggeettttiimmee() and cclloocckk__sseettttiimmee() functions allow the calling process to retrieve or set the value used by a clock which is specified by _c_l_o_c_k___i_d. _c_l_o_c_k___i_d can be a value from clock_getcpuclockid(3) or pthread_getcpuclockid(3) or one of five predefined values: CLOCK_REALTIME time that increments as a wall clock should CLOCK_PROCESS_CPUTIME_ID time that increments when the CPU is running in user or kernel mode on behalf of the calling process CLOCK_THREAD_CPUTIME_ID time that increments when the CPU is running in user or kernel mode on behalf of the calling thread CLOCK_MONOTONIC time that increments as a wall clock should but whose absolute value is meaningless and cannot jump, providing accurate realtime interval measurement, even across suspend and resume CLOCK_UPTIME time whose absolute value is the time the system has been running and not suspended, providing accurate uptime measurement, both absolute and interval The structure pointed to by _t_p is defined in <_s_y_s_/_t_i_m_e_._h> as: struct timespec { time_t tv_sec; /* seconds */ long tv_nsec; /* and nanoseconds */ }; Only the CLOCK_REALTIME clock can be set, and only the superuser may do so. If the system securelevel is greater than 1 (see init(8)), the time may only be advanced. This limitation is imposed to prevent a malicious superuser from setting arbitrary time stamps on files. The system time can still be adjusted backwards using the adjtime(2) system call even when the system is secure. The resolution (granularity) of a clock is returned by the cclloocckk__ggeettrreess() call. This value is placed in a (non-null) _*_t_p. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cclloocckk__ggeettttiimmee(), cclloocckk__sseettttiimmee(), and cclloocckk__ggeettrreess() will fail if: [EINVAL] _c_l_o_c_k___i_d is not a valid value. [EFAULT] The _t_p argument address referenced invalid memory. In addition, cclloocckk__sseettttiimmee() may return the following errors: [EPERM] A user other than the superuser attempted to set the time. [EINVAL] _c_l_o_c_k___i_d specifies a clock that isn't settable, _t_p specifies a nanosecond value less than zero or greater than 1000 million, or a value outside the range of the specified clock. SSEEEE AALLSSOO date(1), adjtime(2), getitimer(2), gettimeofday(2), clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) SSTTAANNDDAARRDDSS The cclloocckk__ggeettrreess(), cclloocckk__ggeettttiimmee(), and cclloocckk__sseettttiimmee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The CLOCK_UPTIME clock is an extension to that. HHIISSTTOORRYY The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and was added to OpenBSD in OpenBSD 5.5. NNAAMMEE cclloocckk__ggeettttiimmee, cclloocckk__sseettttiimmee, cclloocckk__ggeettrreess - get/set/calibrate date and time SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cclloocckk__ggeettttiimmee(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); _i_n_t cclloocckk__sseettttiimmee(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); _i_n_t cclloocckk__ggeettrreess(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); DDEESSCCRRIIPPTTIIOONN The cclloocckk__ggeettttiimmee() and cclloocckk__sseettttiimmee() functions allow the calling process to retrieve or set the value used by a clock which is specified by _c_l_o_c_k___i_d. _c_l_o_c_k___i_d can be a value from clock_getcpuclockid(3) or pthread_getcpuclockid(3) or one of five predefined values: CLOCK_REALTIME time that increments as a wall clock should CLOCK_PROCESS_CPUTIME_ID time that increments when the CPU is running in user or kernel mode on behalf of the calling process CLOCK_THREAD_CPUTIME_ID time that increments when the CPU is running in user or kernel mode on behalf of the calling thread CLOCK_MONOTONIC time that increments as a wall clock should but whose absolute value is meaningless and cannot jump, providing accurate realtime interval measurement, even across suspend and resume CLOCK_UPTIME time whose absolute value is the time the system has been running and not suspended, providing accurate uptime measurement, both absolute and interval The structure pointed to by _t_p is defined in <_s_y_s_/_t_i_m_e_._h> as: struct timespec { time_t tv_sec; /* seconds */ long tv_nsec; /* and nanoseconds */ }; Only the CLOCK_REALTIME clock can be set, and only the superuser may do so. If the system securelevel is greater than 1 (see init(8)), the time may only be advanced. This limitation is imposed to prevent a malicious superuser from setting arbitrary time stamps on files. The system time can still be adjusted backwards using the adjtime(2) system call even when the system is secure. The resolution (granularity) of a clock is returned by the cclloocckk__ggeettrreess() call. This value is placed in a (non-null) _*_t_p. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cclloocckk__ggeettttiimmee(), cclloocckk__sseettttiimmee(), and cclloocckk__ggeettrreess() will fail if: [EINVAL] _c_l_o_c_k___i_d is not a valid value. [EFAULT] The _t_p argument address referenced invalid memory. In addition, cclloocckk__sseettttiimmee() may return the following errors: [EPERM] A user other than the superuser attempted to set the time. [EINVAL] _c_l_o_c_k___i_d specifies a clock that isn't settable, _t_p specifies a nanosecond value less than zero or greater than 1000 million, or a value outside the range of the specified clock. SSEEEE AALLSSOO date(1), adjtime(2), getitimer(2), gettimeofday(2), clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) SSTTAANNDDAARRDDSS The cclloocckk__ggeettrreess(), cclloocckk__ggeettttiimmee(), and cclloocckk__sseettttiimmee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The CLOCK_UPTIME clock is an extension to that. HHIISSTTOORRYY The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and was added to OpenBSD in OpenBSD 5.5. NNAAMMEE cclloocckk__ggeettttiimmee, cclloocckk__sseettttiimmee, cclloocckk__ggeettrreess - get/set/calibrate date and time SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cclloocckk__ggeettttiimmee(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); _i_n_t cclloocckk__sseettttiimmee(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); _i_n_t cclloocckk__ggeettrreess(_c_l_o_c_k_i_d___t _c_l_o_c_k___i_d, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_p); DDEESSCCRRIIPPTTIIOONN The cclloocckk__ggeettttiimmee() and cclloocckk__sseettttiimmee() functions allow the calling process to retrieve or set the value used by a clock which is specified by _c_l_o_c_k___i_d. _c_l_o_c_k___i_d can be a value from clock_getcpuclockid(3) or pthread_getcpuclockid(3) or one of five predefined values: CLOCK_REALTIME time that increments as a wall clock should CLOCK_PROCESS_CPUTIME_ID time that increments when the CPU is running in user or kernel mode on behalf of the calling process CLOCK_THREAD_CPUTIME_ID time that increments when the CPU is running in user or kernel mode on behalf of the calling thread CLOCK_MONOTONIC time that increments as a wall clock should but whose absolute value is meaningless and cannot jump, providing accurate realtime interval measurement, even across suspend and resume CLOCK_UPTIME time whose absolute value is the time the system has been running and not suspended, providing accurate uptime measurement, both absolute and interval The structure pointed to by _t_p is defined in <_s_y_s_/_t_i_m_e_._h> as: struct timespec { time_t tv_sec; /* seconds */ long tv_nsec; /* and nanoseconds */ }; Only the CLOCK_REALTIME clock can be set, and only the superuser may do so. If the system securelevel is greater than 1 (see init(8)), the time may only be advanced. This limitation is imposed to prevent a malicious superuser from setting arbitrary time stamps on files. The system time can still be adjusted backwards using the adjtime(2) system call even when the system is secure. The resolution (granularity) of a clock is returned by the cclloocckk__ggeettrreess() call. This value is placed in a (non-null) _*_t_p. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cclloocckk__ggeettttiimmee(), cclloocckk__sseettttiimmee(), and cclloocckk__ggeettrreess() will fail if: [EINVAL] _c_l_o_c_k___i_d is not a valid value. [EFAULT] The _t_p argument address referenced invalid memory. In addition, cclloocckk__sseettttiimmee() may return the following errors: [EPERM] A user other than the superuser attempted to set the time. [EINVAL] _c_l_o_c_k___i_d specifies a clock that isn't settable, _t_p specifies a nanosecond value less than zero or greater than 1000 million, or a value outside the range of the specified clock. SSEEEE AALLSSOO date(1), adjtime(2), getitimer(2), gettimeofday(2), clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) SSTTAANNDDAARRDDSS The cclloocckk__ggeettrreess(), cclloocckk__ggeettttiimmee(), and cclloocckk__sseettttiimmee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The CLOCK_UPTIME clock is an extension to that. HHIISSTTOORRYY The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and was added to OpenBSD in OpenBSD 5.5. NNAAMMEE cclloossee - delete a descriptor SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cclloossee(_i_n_t _d); DDEESSCCRRIIPPTTIIOONN The cclloossee() call deletes a descriptor _d from the per-process object reference table. If this is the last reference to the underlying object, the object will be deactivated. For example, on the last close of a file, the current _s_e_e_k pointer associated with the file is lost; on the last close of a socket(2), associated naming information and queued data are discarded; and on the last close of a file holding an advisory lock, the lock is released (see flock(2)). However, the semantics of System V and IEEE Std 1003.1-1988 (``POSIX.1'') dictate that all fcntl(2) advisory record locks associated with a file for a given process are removed when _a_n_y file descriptor for that file is closed by that process. When a process exits, all associated file descriptors are freed, but since there is a limit on active descriptors per process, the cclloossee() function call is useful when a large quantity of file descriptors are being handled. When a process forks (see fork(2)), all descriptors for the new child process reference the same objects as they did in the parent before the fork. If a new process image is to then be run using execve(2), the process would normally inherit these descriptors. Most of the descriptors can be rearranged with dup2(2) or deleted with cclloossee() before the execve(2) is attempted, but since some of these descriptors may still be needed should the execve(2) fail, it is necessary to arrange for them to be closed when the execve(2) succeeds. For this reason, the call ffccnnttll(_d, _F___S_E_T_F_D, _F_D___C_L_O_E_X_E_C) is provided, which arranges that a descriptor will be closed after a successful execve(2); the call ffccnnttll(_d, _F___S_E_T_F_D, _0) restores the default, which is to not close the descriptor. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cclloossee() will fail if: [EBADF] _d is not an active descriptor. [EINTR] An interrupt was received. [EIO] An I/O error occurred while writing to the file system. SSEEEE AALLSSOO accept(2), closefrom(2), dup2(2), execve(2), fcntl(2), flock(2), open(2), pipe(2), socket(2), socketpair(2) SSTTAANNDDAARRDDSS cclloossee() conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cclloossee() system call first appeared in Version 1 AT&T UNIX. NNAAMMEE cclloosseeffrroomm - delete many descriptors SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cclloosseeffrroomm(_i_n_t _f_d); DDEESSCCRRIIPPTTIIOONN The cclloosseeffrroomm() call deletes all descriptors numbered _f_d and higher from the per-process file descriptor table. It is effectively the same as calling close(2) on each descriptor. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cclloosseeffrroomm() will fail if: [EBADF] _f_d is greater than all open file descriptors. [EINTR] An interrupt was received. SSEEEE AALLSSOO close(2) NNAAMMEE ccoonnnneecctt - initiate a connection on a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ccoonnnneecctt(_i_n_t _s, _c_o_n_s_t _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_n_a_m_e, _s_o_c_k_l_e_n___t _n_a_m_e_l_e_n); DDEESSCCRRIIPPTTIIOONN The parameter _s is a socket. If it is of type SOCK_DGRAM, this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type SOCK_STREAM, this call attempts to make a connection to another socket. The other socket is specified by _n_a_m_e, which is an address in the communications space of the socket. _n_a_m_e_l_e_n indicates the amount of space pointed to by _n_a_m_e, in bytes. Each communications space interprets the _n_a_m_e parameter in its own way. Generally, stream sockets may use ccoonnnneecctt() only once; datagram sockets may use ccoonnnneecctt() multiple times to change their association. Datagram sockets may dissolve the association by connecting to an invalid address, such as a null address. RREETTUURRNN VVAALLUUEESS If the connection or binding succeeds, 0 is returned. Otherwise a -1 is returned, and a more specific error code is stored in _e_r_r_n_o. EERRRROORRSS The ccoonnnneecctt() call fails if: [EBADF] _s is not a valid descriptor. [ENOTSOCK] _s is not a socket. [EADDRNOTAVAIL] The specified address is not available on this machine. [EAFNOSUPPORT] Addresses in the specified address family cannot be used with this socket. [EISCONN] The socket is already connected. [ETIMEDOUT] Connection establishment timed out without establishing a connection. [EINVAL] A TCP connection with a local broadcast, the all-ones or a multicast address as the peer was attempted. [ECONNREFUSED] The attempt to connect was forcefully rejected. [EHOSTUNREACH] The destination address specified an unreachable host. [EINTR] A connect was interrupted before it succeeded by the delivery of a signal. [ENETUNREACH] The network isn't reachable from this host. [EADDRINUSE] The address is already in use. [EFAULT] The _n_a_m_e parameter specifies an area outside the process address space. [EINPROGRESS] The socket is non-blocking and the connection cannot be completed immediately. It is possible to select(2) or poll(2) for completion by selecting the socket for writing, and also use getsockopt(2) with SO_ERROR to check for error conditions. [EALREADY] The socket is non-blocking and a previous connection attempt has not yet been completed. The following errors are specific to connecting names in the UNIX-domain. These errors may not apply in future versions of the UNIX IPC domain. [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named socket does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] Write access to the named socket is denied. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPROTOTYPE] The file described by _n_a_m_e is of a different type than _s. E.g., _s may be of type SOCK_STREAM whereas _n_a_m_e may refer to a socket of type SOCK_DGRAM. SSEEEE AALLSSOO accept(2), getsockname(2), getsockopt(2), poll(2), select(2), socket(2) SSTTAANNDDAARRDDSS The ccoonnnneecctt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ccoonnnneecctt() system call first appeared in 4.1cBSD. NNAAMMEE dduupp, dduupp22, dduupp33 - duplicate an existing file descriptor SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t dduupp(_i_n_t _o_l_d_d); _i_n_t dduupp22(_i_n_t _o_l_d_d, _i_n_t _n_e_w_d); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t dduupp33(_i_n_t _o_l_d_d, _i_n_t _n_e_w_d, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN dduupp() duplicates an existing object descriptor and returns its value to the calling process (_n_e_w_d = dduupp(_o_l_d_d)). The argument _o_l_d_d is a small non-negative integer index in the per-process descriptor table. The value must be less than the size of the table, which is returned by getdtablesize(3). The new descriptor returned by the call is the lowest numbered descriptor currently not in use by the process. The object referenced by the descriptor does not distinguish between _o_l_d_d and _n_e_w_d in any way. Thus if _n_e_w_d and _o_l_d_d are duplicate references to an open file, read(2), write(2) and lseek(2) calls all move a single pointer into the file, and append mode, non-blocking I/O and asynchronous I/O options are shared between the references. If a separate pointer into the file is desired, a different object reference to the file must be obtained by issuing an additional open(2) call. The close-on-exec flag on the new file descriptor is unset. In dduupp22(), the value of the new descriptor _n_e_w_d is specified. If this descriptor is already in use, it is first deallocated as if a close(2) call had been done first. When _n_e_w_d equals _o_l_d_d, dduupp22() just returns without affecting the close-on-exec flag. In dduupp33(), both the value of the new descriptor and the close-on-exec flag on the new file descriptor are specified: _n_e_w_d specifies the value and the O_CLOEXEC bit in _f_l_a_g_s specifies the close-on-exec flag. Unlike dduupp22(), if _o_l_d_d and _n_e_w_d are equal then dduupp33() fails. Otherwise, if _f_l_a_g_s is zero then dduupp33() is identical to a call to dduupp22(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value of the new descriptor is returned. The value -1 is returned if an error occurs in either call. The external variable _e_r_r_n_o indicates the cause of the error. EERRRROORRSS dduupp() will fail if: [EBADF] _o_l_d_d is not a valid active descriptor. [EMFILE] Too many descriptors are active. dduupp22() and dduupp33() will fail if: [EBADF] _o_l_d_d is not a valid active descriptor or _n_e_w_d is negative or greater than or equal to the process's RLIMIT_NOFILE limit. [EINTR] An interrupt was received. [EIO] An I/O error occurred while writing to the file system. In addition, dduupp33() will return the following error: [EINVAL] _o_l_d_d is equal to _n_e_w_d or _f_l_a_g_s is invalid. SSEEEE AALLSSOO accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), socketpair(2), getdtablesize(3) SSTTAANNDDAARRDDSS dduupp() and dduupp22() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The dduupp33() function is expected to conform to a future revision of that standard. HHIISSTTOORRYY The dduupp() system call first appeared in Version 3 AT&T UNIX, dduupp22() in Version 7 AT&T UNIX, and dduupp33() in OpenBSD 5.7. NNAAMMEE dduupp, dduupp22, dduupp33 - duplicate an existing file descriptor SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t dduupp(_i_n_t _o_l_d_d); _i_n_t dduupp22(_i_n_t _o_l_d_d, _i_n_t _n_e_w_d); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t dduupp33(_i_n_t _o_l_d_d, _i_n_t _n_e_w_d, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN dduupp() duplicates an existing object descriptor and returns its value to the calling process (_n_e_w_d = dduupp(_o_l_d_d)). The argument _o_l_d_d is a small non-negative integer index in the per-process descriptor table. The value must be less than the size of the table, which is returned by getdtablesize(3). The new descriptor returned by the call is the lowest numbered descriptor currently not in use by the process. The object referenced by the descriptor does not distinguish between _o_l_d_d and _n_e_w_d in any way. Thus if _n_e_w_d and _o_l_d_d are duplicate references to an open file, read(2), write(2) and lseek(2) calls all move a single pointer into the file, and append mode, non-blocking I/O and asynchronous I/O options are shared between the references. If a separate pointer into the file is desired, a different object reference to the file must be obtained by issuing an additional open(2) call. The close-on-exec flag on the new file descriptor is unset. In dduupp22(), the value of the new descriptor _n_e_w_d is specified. If this descriptor is already in use, it is first deallocated as if a close(2) call had been done first. When _n_e_w_d equals _o_l_d_d, dduupp22() just returns without affecting the close-on-exec flag. In dduupp33(), both the value of the new descriptor and the close-on-exec flag on the new file descriptor are specified: _n_e_w_d specifies the value and the O_CLOEXEC bit in _f_l_a_g_s specifies the close-on-exec flag. Unlike dduupp22(), if _o_l_d_d and _n_e_w_d are equal then dduupp33() fails. Otherwise, if _f_l_a_g_s is zero then dduupp33() is identical to a call to dduupp22(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value of the new descriptor is returned. The value -1 is returned if an error occurs in either call. The external variable _e_r_r_n_o indicates the cause of the error. EERRRROORRSS dduupp() will fail if: [EBADF] _o_l_d_d is not a valid active descriptor. [EMFILE] Too many descriptors are active. dduupp22() and dduupp33() will fail if: [EBADF] _o_l_d_d is not a valid active descriptor or _n_e_w_d is negative or greater than or equal to the process's RLIMIT_NOFILE limit. [EINTR] An interrupt was received. [EIO] An I/O error occurred while writing to the file system. In addition, dduupp33() will return the following error: [EINVAL] _o_l_d_d is equal to _n_e_w_d or _f_l_a_g_s is invalid. SSEEEE AALLSSOO accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), socketpair(2), getdtablesize(3) SSTTAANNDDAARRDDSS dduupp() and dduupp22() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The dduupp33() function is expected to conform to a future revision of that standard. HHIISSTTOORRYY The dduupp() system call first appeared in Version 3 AT&T UNIX, dduupp22() in Version 7 AT&T UNIX, and dduupp33() in OpenBSD 5.7. NNAAMMEE dduupp, dduupp22, dduupp33 - duplicate an existing file descriptor SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t dduupp(_i_n_t _o_l_d_d); _i_n_t dduupp22(_i_n_t _o_l_d_d, _i_n_t _n_e_w_d); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t dduupp33(_i_n_t _o_l_d_d, _i_n_t _n_e_w_d, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN dduupp() duplicates an existing object descriptor and returns its value to the calling process (_n_e_w_d = dduupp(_o_l_d_d)). The argument _o_l_d_d is a small non-negative integer index in the per-process descriptor table. The value must be less than the size of the table, which is returned by getdtablesize(3). The new descriptor returned by the call is the lowest numbered descriptor currently not in use by the process. The object referenced by the descriptor does not distinguish between _o_l_d_d and _n_e_w_d in any way. Thus if _n_e_w_d and _o_l_d_d are duplicate references to an open file, read(2), write(2) and lseek(2) calls all move a single pointer into the file, and append mode, non-blocking I/O and asynchronous I/O options are shared between the references. If a separate pointer into the file is desired, a different object reference to the file must be obtained by issuing an additional open(2) call. The close-on-exec flag on the new file descriptor is unset. In dduupp22(), the value of the new descriptor _n_e_w_d is specified. If this descriptor is already in use, it is first deallocated as if a close(2) call had been done first. When _n_e_w_d equals _o_l_d_d, dduupp22() just returns without affecting the close-on-exec flag. In dduupp33(), both the value of the new descriptor and the close-on-exec flag on the new file descriptor are specified: _n_e_w_d specifies the value and the O_CLOEXEC bit in _f_l_a_g_s specifies the close-on-exec flag. Unlike dduupp22(), if _o_l_d_d and _n_e_w_d are equal then dduupp33() fails. Otherwise, if _f_l_a_g_s is zero then dduupp33() is identical to a call to dduupp22(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value of the new descriptor is returned. The value -1 is returned if an error occurs in either call. The external variable _e_r_r_n_o indicates the cause of the error. EERRRROORRSS dduupp() will fail if: [EBADF] _o_l_d_d is not a valid active descriptor. [EMFILE] Too many descriptors are active. dduupp22() and dduupp33() will fail if: [EBADF] _o_l_d_d is not a valid active descriptor or _n_e_w_d is negative or greater than or equal to the process's RLIMIT_NOFILE limit. [EINTR] An interrupt was received. [EIO] An I/O error occurred while writing to the file system. In addition, dduupp33() will return the following error: [EINVAL] _o_l_d_d is equal to _n_e_w_d or _f_l_a_g_s is invalid. SSEEEE AALLSSOO accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), socketpair(2), getdtablesize(3) SSTTAANNDDAARRDDSS dduupp() and dduupp22() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The dduupp33() function is expected to conform to a future revision of that standard. HHIISSTTOORRYY The dduupp() system call first appeared in Version 3 AT&T UNIX, dduupp22() in Version 7 AT&T UNIX, and dduupp33() in OpenBSD 5.7. NNAAMMEE iinnttrroo - introduction to system calls and error numbers SSYYNNOOPPSSIISS ##iinncclluuddee <> DDEESSCCRRIIPPTTIIOONN The manual pages in section 2 provide an overview of the system calls, their error returns, and other common definitions and concepts. DDIIAAGGNNOOSSTTIICCSS Nearly all of the system calls provide an error number via the identifier errno, which expands to an addressable location of type _i_n_t. The address of _e_r_r_n_o in each thread is guaranteed to be unique for the lifetime of the thread. Applications must use _e_r_r_n_o as defined in <_e_r_r_n_o_._h> and not attempt to use a custom definition. When a system call detects an error, it returns an integer value indicating failure (usually -1) and sets the variable _e_r_r_n_o accordingly. (This allows interpretation of the failure on receiving a -1 and to take action accordingly.) Successful calls never set _e_r_r_n_o; once set, it remains until another error occurs. It should only be examined after an error. Note that a number of system calls overload the meanings of these error numbers, and that the meanings must be interpreted according to the type and circumstances of the call. The following is a complete list of the errors and their names as given in <_s_y_s_/_e_r_r_n_o_._h>. 0 _U_n_d_e_f_i_n_e_d _e_r_r_o_r_: _0. Not used. 1 EPERM _O_p_e_r_a_t_i_o_n _n_o_t _p_e_r_m_i_t_t_e_d. An attempt was made to perform an operation limited to processes with appropriate privileges or to the owner of a file or other resources. 2 ENOENT _N_o _s_u_c_h _f_i_l_e _o_r _d_i_r_e_c_t_o_r_y. A component of a specified pathname did not exist, or the pathname was an empty string. 3 ESRCH _N_o _s_u_c_h _p_r_o_c_e_s_s. No process could be found which corresponds to the given process ID. 4 EINTR _I_n_t_e_r_r_u_p_t_e_d _s_y_s_t_e_m _c_a_l_l. An asynchronous signal (such as SIGINT or SIGQUIT) was caught by the thread during the execution of an interruptible function. If the signal handler performs a normal return, the interrupted function call will seem to have returned the error condition. 5 EIO _I_n_p_u_t_/_o_u_t_p_u_t _e_r_r_o_r. Some physical input or output error occurred. This error will not be reported until a subsequent operation on the same file descriptor and may be lost (overwritten) by any subsequent errors. 6 ENXIO _D_e_v_i_c_e _n_o_t _c_o_n_f_i_g_u_r_e_d. Input or output on a special file referred to a device that did not exist, or made a request beyond the limits of the device. This error may also occur when, for example, a tape drive is not online or no disk pack is loaded on a drive. 7 E2BIG _A_r_g_u_m_e_n_t _l_i_s_t _t_o_o _l_o_n_g. The number of bytes used for the argument and environment list of the new process exceeded the limit NCARGS (specified in <_s_y_s_/_p_a_r_a_m_._h>). 8 ENOEXEC _E_x_e_c _f_o_r_m_a_t _e_r_r_o_r. A request was made to execute a file that, although it has the appropriate permissions, was not in the format required for an executable file. 9 EBADF _B_a_d _f_i_l_e _d_e_s_c_r_i_p_t_o_r. A file descriptor argument was out of range, referred to no open file, or a read (write) request was made to a file that was only open for writing (reading). 10 ECHILD _N_o _c_h_i_l_d _p_r_o_c_e_s_s_e_s. A wait(2) or waitpid(2) function was executed by a process that had no existing or unwaited-for child processes. 11 EDEADLK _R_e_s_o_u_r_c_e _d_e_a_d_l_o_c_k _a_v_o_i_d_e_d. An attempt was made to lock a system resource that would have resulted in a deadlock situation. 12 ENOMEM _C_a_n_n_o_t _a_l_l_o_c_a_t_e _m_e_m_o_r_y. The new process image required more memory than was allowed by the hardware or by system-imposed memory management constraints. A lack of swap space is normally temporary; however, a lack of core is not. Soft limits may be increased to their corresponding hard limits. 13 EACCES _P_e_r_m_i_s_s_i_o_n _d_e_n_i_e_d. An attempt was made to access a file in a way forbidden by its file access permissions. 14 EFAULT _B_a_d _a_d_d_r_e_s_s. The system detected an invalid address in attempting to use an argument of a call. 15 ENOTBLK _B_l_o_c_k _d_e_v_i_c_e _r_e_q_u_i_r_e_d. A block device operation was attempted on a non-block device or file. 16 EBUSY _D_e_v_i_c_e _b_u_s_y. An attempt to use a system resource which was in use at the time in a manner which would have conflicted with the request. 17 EEXIST _F_i_l_e _e_x_i_s_t_s. An existing file was mentioned in an inappropriate context, for instance, as the new link name in a link(2) function. 18 EXDEV _C_r_o_s_s_-_d_e_v_i_c_e _l_i_n_k. A hard link to a file on another file system was attempted. 19 ENODEV _O_p_e_r_a_t_i_o_n _n_o_t _s_u_p_p_o_r_t_e_d _b_y _d_e_v_i_c_e. An attempt was made to apply an inappropriate function to a device, for example, trying to read a write-only device such as a printer. 20 ENOTDIR _N_o_t _a _d_i_r_e_c_t_o_r_y. A component of the specified pathname existed, but it was not a directory, when a directory was expected. 21 EISDIR _I_s _a _d_i_r_e_c_t_o_r_y. An attempt was made to open a directory with write mode specified. 22 EINVAL _I_n_v_a_l_i_d _a_r_g_u_m_e_n_t. Some invalid argument was supplied. (For example, specifying an undefined signal to a signal(3) or kill(2) function). 23 ENFILE _T_o_o _m_a_n_y _o_p_e_n _f_i_l_e_s _i_n _s_y_s_t_e_m. Maximum number of file descriptors allowable on the system has been reached and a request for an open cannot be satisfied until at least one has been closed. The sysctl(3) variable _k_e_r_n_._m_a_x_f_i_l_e_s contains the current limit. 24 EMFILE _T_o_o _m_a_n_y _o_p_e_n _f_i_l_e_s. The maximum number of file descriptors allowable for this process has been reached and a request for an open cannot be satisfied until at least one has been closed. getdtablesize(3) will obtain the current limit. 25 ENOTTY _I_n_a_p_p_r_o_p_r_i_a_t_e _i_o_c_t_l _f_o_r _d_e_v_i_c_e. A control function (see ioctl(2)) was attempted for a file or special device for which the operation was inappropriate. 26 ETXTBSY _T_e_x_t _f_i_l_e _b_u_s_y. An attempt was made either to execute a pure procedure (shared text) file which was open for writing by another process, or to open with write access a pure procedure file that is currently being executed. 27 EFBIG _F_i_l_e _t_o_o _l_a_r_g_e. The size of a file exceeded the maximum. (The system-wide maximum file size is 2**63 bytes. Each file system may impose a lower limit for files contained within it.) 28 ENOSPC _N_o _s_p_a_c_e _l_e_f_t _o_n _d_e_v_i_c_e. A write(2) to an ordinary file, the creation of a directory or symbolic link, or the creation of a directory entry failed because no more disk blocks were available on the file system, or the allocation of an inode for a newly created file failed because no more inodes were available on the file system. 29 ESPIPE _I_l_l_e_g_a_l _s_e_e_k. An lseek(2) function was issued on a socket, pipe or FIFO. 30 EROFS _R_e_a_d_-_o_n_l_y _f_i_l_e _s_y_s_t_e_m. An attempt was made to modify a file or create a directory on a file system that was read-only at the time. 31 EMLINK _T_o_o _m_a_n_y _l_i_n_k_s. The maximum allowable number of hard links to a single file has been exceeded (see pathconf(2) for how to obtain this value). 32 EPIPE _B_r_o_k_e_n _p_i_p_e. A write on a pipe, socket or FIFO for which there is no process to read the data. 33 EDOM _N_u_m_e_r_i_c_a_l _a_r_g_u_m_e_n_t _o_u_t _o_f _d_o_m_a_i_n. A numerical input argument was outside the defined domain of the mathematical function. 34 ERANGE _R_e_s_u_l_t _t_o_o _l_a_r_g_e. A result of the function was too large to fit in the available space (perhaps exceeded precision). 35 EAGAIN _R_e_s_o_u_r_c_e _t_e_m_p_o_r_a_r_i_l_y _u_n_a_v_a_i_l_a_b_l_e. This is a temporary condition and later calls to the same routine may complete normally. 36 EINPROGRESS _O_p_e_r_a_t_i_o_n _n_o_w _i_n _p_r_o_g_r_e_s_s. An operation that takes a long time to complete (such as a connect(2)) was attempted on a non- blocking object (see fcntl(2)). 37 EALREADY _O_p_e_r_a_t_i_o_n _a_l_r_e_a_d_y _i_n _p_r_o_g_r_e_s_s. An operation was attempted on a non-blocking object that already had an operation in progress. 38 ENOTSOCK _S_o_c_k_e_t _o_p_e_r_a_t_i_o_n _o_n _n_o_n_-_s_o_c_k_e_t. Self-explanatory. 39 EDESTADDRREQ _D_e_s_t_i_n_a_t_i_o_n _a_d_d_r_e_s_s _r_e_q_u_i_r_e_d. A required address was omitted from an operation on a socket. 40 EMSGSIZE _M_e_s_s_a_g_e _t_o_o _l_o_n_g. A message sent on a socket was larger than the internal message buffer or some other network limit. 41 EPROTOTYPE _P_r_o_t_o_c_o_l _w_r_o_n_g _t_y_p_e _f_o_r _s_o_c_k_e_t. A protocol was specified that does not support the semantics of the socket type requested. For example, you cannot use the Internet UDP protocol with type SOCK_STREAM. 42 ENOPROTOOPT _P_r_o_t_o_c_o_l _n_o_t _a_v_a_i_l_a_b_l_e. A bad option or level was specified in a getsockopt(2) or setsockopt(2) call. 43 EPROTONOSUPPORT _P_r_o_t_o_c_o_l _n_o_t _s_u_p_p_o_r_t_e_d. The protocol has not been configured into the system or no implementation for it exists. 44 ESOCKTNOSUPPORT _S_o_c_k_e_t _t_y_p_e _n_o_t _s_u_p_p_o_r_t_e_d. The support for the socket type has not been configured into the system or no implementation for it exists. 45 EOPNOTSUPP _O_p_e_r_a_t_i_o_n _n_o_t _s_u_p_p_o_r_t_e_d. The attempted operation is not supported for the type of object referenced. Usually this occurs when a file descriptor refers to a file or socket that cannot support this operation, for example, trying to _a_c_c_e_p_t a connection on a datagram socket. 46 EPFNOSUPPORT _P_r_o_t_o_c_o_l _f_a_m_i_l_y _n_o_t _s_u_p_p_o_r_t_e_d. The protocol family has not been configured into the system or no implementation for it exists. 47 EAFNOSUPPORT _A_d_d_r_e_s_s _f_a_m_i_l_y _n_o_t _s_u_p_p_o_r_t_e_d _b_y _p_r_o_t_o_c_o_l _f_a_m_i_l_y. An address incompatible with the requested protocol was used. For example, you shouldn't necessarily expect to be able to use NS addresses with Internet protocols. 48 EADDRINUSE _A_d_d_r_e_s_s _a_l_r_e_a_d_y _i_n _u_s_e. Only one usage of each address is normally permitted. 49 EADDRNOTAVAIL _C_a_n_'_t _a_s_s_i_g_n _r_e_q_u_e_s_t_e_d _a_d_d_r_e_s_s. Normally results from an attempt to create a socket with an address not on this machine. 50 ENETDOWN _N_e_t_w_o_r_k _i_s _d_o_w_n. A socket operation encountered a dead network. 51 ENETUNREACH _N_e_t_w_o_r_k _i_s _u_n_r_e_a_c_h_a_b_l_e. A socket operation was attempted to an unreachable network. 52 ENETRESET _N_e_t_w_o_r_k _d_r_o_p_p_e_d _c_o_n_n_e_c_t_i_o_n _o_n _r_e_s_e_t. The host you were connected to crashed and rebooted. 53 ECONNABORTED _S_o_f_t_w_a_r_e _c_a_u_s_e_d _c_o_n_n_e_c_t_i_o_n _a_b_o_r_t. A connection abort was caused internal to your host machine. 54 ECONNRESET _C_o_n_n_e_c_t_i_o_n _r_e_s_e_t _b_y _p_e_e_r. A connection was forcibly closed by a peer. This normally results from a loss of the connection on the remote socket due to a timeout or a reboot. 55 ENOBUFS _N_o _b_u_f_f_e_r _s_p_a_c_e _a_v_a_i_l_a_b_l_e. An operation on a socket or pipe was not performed because the system lacked sufficient buffer space or because a queue was full. 56 EISCONN _S_o_c_k_e_t _i_s _a_l_r_e_a_d_y _c_o_n_n_e_c_t_e_d. A connect(2) request was made on an already connected socket; or, a sendto(2) or sendmsg(2) request on a connected socket specified a destination when already connected. 57 ENOTCONN _S_o_c_k_e_t _i_s _n_o_t _c_o_n_n_e_c_t_e_d. A request to send or receive data was disallowed because the socket was not connected and (when sending on a datagram socket) no address was supplied. 58 ESHUTDOWN _C_a_n_'_t _s_e_n_d _a_f_t_e_r _s_o_c_k_e_t _s_h_u_t_d_o_w_n. A request to send data was disallowed because the socket had already been shut down with a previous shutdown(2) call. 59 ETOOMANYREFS _T_o_o _m_a_n_y _r_e_f_e_r_e_n_c_e_s_: _c_a_n_'_t _s_p_l_i_c_e. Not used in OpenBSD. 60 ETIMEDOUT _O_p_e_r_a_t_i_o_n _t_i_m_e_d _o_u_t. A connect(2) or send(2) request failed because the connected party did not properly respond after a period of time. (The timeout period is dependent on the communication protocol.) 61 ECONNREFUSED _C_o_n_n_e_c_t_i_o_n _r_e_f_u_s_e_d. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host. 62 ELOOP _T_o_o _m_a_n_y _l_e_v_e_l_s _o_f _s_y_m_b_o_l_i_c _l_i_n_k_s. A path name lookup involved more than 32 (SYMLOOP_MAX) symbolic links. 63 ENAMETOOLONG _F_i_l_e _n_a_m_e _t_o_o _l_o_n_g. A component of a pathname exceeded 255 (NAME_MAX) characters, or an entire pathname (including the terminating NUL) exceeded 1024 (PATH_MAX) bytes. 64 EHOSTDOWN _H_o_s_t _i_s _d_o_w_n. A socket operation failed because the destination host was down. 65 EHOSTUNREACH _N_o _r_o_u_t_e _t_o _h_o_s_t. A socket operation was attempted to an unreachable host. 66 ENOTEMPTY _D_i_r_e_c_t_o_r_y _n_o_t _e_m_p_t_y. A directory with entries other than `.' and `..' was supplied to a remove directory or rename call. 67 EPROCLIM _T_o_o _m_a_n_y _p_r_o_c_e_s_s_e_s. 68 EUSERS _T_o_o _m_a_n_y _u_s_e_r_s. The quota system ran out of table entries. 69 EDQUOT _D_i_s_c _q_u_o_t_a _e_x_c_e_e_d_e_d. A write(2) to an ordinary file, the creation of a directory or symbolic link, or the creation of a directory entry failed because the user's quota of disk blocks was exhausted, or the allocation of an inode for a newly created file failed because the user's quota of inodes was exhausted. 70 ESTALE _S_t_a_l_e _N_F_S _f_i_l_e _h_a_n_d_l_e. An attempt was made to access an open file on an NFS filesystem which is now unavailable as referenced by the file descriptor. This may indicate the file was deleted on the NFS server or some other catastrophic event occurred. 72 EBADRPC _R_P_C _s_t_r_u_c_t _i_s _b_a_d. Exchange of rpc(3) information was unsuccessful. 73 ERPCMISMATCH _R_P_C _v_e_r_s_i_o_n _w_r_o_n_g. The version of rpc(3) on the remote peer is not compatible with the local version. 74 EPROGUNAVAIL _R_P_C _p_r_o_g_. _n_o_t _a_v_a_i_l. The requested rpc(3) program is not registered on the remote host. 75 EPROGMISMATCH _P_r_o_g_r_a_m _v_e_r_s_i_o_n _w_r_o_n_g. The requested version of the rpc(3) program is not available on the remote host. 76 EPROCUNAVAIL _B_a_d _p_r_o_c_e_d_u_r_e _f_o_r _p_r_o_g_r_a_m. An rpc(3) call was attempted for a procedure which doesn't exist in the remote program. 77 ENOLCK _N_o _l_o_c_k_s _a_v_a_i_l_a_b_l_e. A system-imposed limit on the number of simultaneous file locks was reached. 78 ENOSYS _F_u_n_c_t_i_o_n _n_o_t _i_m_p_l_e_m_e_n_t_e_d. Attempted a system call that is not available on this system. 79 EFTYPE _I_n_a_p_p_r_o_p_r_i_a_t_e _f_i_l_e _t_y_p_e _o_r _f_o_r_m_a_t. The file contains invalid data or set to invalid modes. 80 EAUTH _A_u_t_h_e_n_t_i_c_a_t_i_o_n _e_r_r_o_r. Attempted to use an invalid authentication ticket to mount a NFS filesystem. 81 ENEEDAUTH _N_e_e_d _a_u_t_h_e_n_t_i_c_a_t_o_r. An authentication ticket must be obtained before the given NFS filesystem may be mounted. 82 EIPSEC _I_P_s_e_c _p_r_o_c_e_s_s_i_n_g _f_a_i_l_u_r_e. IPsec subsystem error. Not used in OpenBSD. 83 ENOATTR _A_t_t_r_i_b_u_t_e _n_o_t _f_o_u_n_d. A UFS Extended Attribute is not found for the specified pathname. 84 EILSEQ _I_l_l_e_g_a_l _b_y_t_e _s_e_q_u_e_n_c_e. An illegal sequence of bytes was used when using wide characters. 85 ENOMEDIUM _N_o _m_e_d_i_u_m _f_o_u_n_d. Attempted to use a removable media device with no medium present. 86 EMEDIUMTYPE _W_r_o_n_g _m_e_d_i_u_m _t_y_p_e. Attempted to use a removable media device with incorrect or incompatible medium. 87 EOVERFLOW _V_a_l_u_e _t_o_o _l_a_r_g_e _t_o _b_e _s_t_o_r_e_d _i_n _d_a_t_a _t_y_p_e. A numerical result of the function was too large to be stored in the caller provided space. 88 ECANCELED _O_p_e_r_a_t_i_o_n _c_a_n_c_e_l_e_d. The requested operation was canceled. 89 EIDRM _I_d_e_n_t_i_f_i_e_r _r_e_m_o_v_e_d. An IPC identifier was removed while the current thread was waiting on it. 90 ENOMSG _N_o _m_e_s_s_a_g_e _o_f _d_e_s_i_r_e_d _t_y_p_e. An IPC message queue does not contain a message of the desired type, or a message catalog does not contain the requested message. 91 ENOTSUP _N_o_t _s_u_p_p_o_r_t_e_d. The operation has requested an unsupported value. DDEEFFIINNIITTIIOONNSS Process A process is a collection of one or more threads, plus the resources shared by those threads such as process ID, address space, user IDs and group IDs, and root directory and current working directory. Process ID Each active process in the system is uniquely identified by a non-negative integer called a process ID. The range of this ID is from 1 to 32766. Parent Process ID A new process is created by a currently active process; (see fork(2)). The parent process ID of a process is initially the process ID of its creator. If the creating process exits, the parent process ID of each child is set to the ID of a system process, init(8). Process Group Each active process is a member of a process group that is identified by a non-negative integer called the process group ID. This is the process ID of the group leader. This grouping permits the signaling of related processes (see termios(4)) and the job control mechanisms of csh(1). Session A session is a set of one or more process groups. A session is created by a successful call to setsid(2), which causes the caller to become the only member of the only process group in the new session. Session Leader A process that has created a new session by a successful call to setsid(2), is known as a session leader. Only a session leader may acquire a terminal as its controlling terminal (see termios(4)). Controlling Process A session leader with a controlling terminal is a controlling process. Controlling Terminal A terminal that is associated with a session is known as the controlling terminal for that session and its members. Terminal Process Group ID A terminal may be acquired by a session leader as its controlling terminal. Once a terminal is associated with a session, any of the process groups within the session may be placed into the foreground by setting the terminal process group ID to the ID of the process group. This facility is used to arbitrate between multiple jobs contending for the same terminal; (see csh(1) and tty(4)). Orphaned Process Group A process group is considered to be _o_r_p_h_a_n_e_d if it is not under the control of a job control shell. More precisely, a process group is orphaned when none of its members has a parent process that is in the same session as the group, but is in a different process group. Note that when a process exits, the parent process for its children is changed to be init(8), which is in a separate session. Not all members of an orphaned process group are necessarily orphaned processes (those whose creating process has exited). The process group of a session leader is orphaned by definition. Thread A thread is a preemptively scheduled flow of control within a process, with its own set of register values, floating point environment, thread ID, signal mask, pending signal set, alternate signal stack, thread control block address, resource utilization, errno variable location, and values for thread- specific keys. A process initially has just one thread, a duplicate of the thread in the parent process that created this process. Real User ID and Real Group ID Each user on the system is identified by a positive integer termed the real user ID. Each user is also a member of one or more groups. One of these groups is distinguished from others and used in implementing accounting facilities. The positive integer corresponding to this distinguished group is termed the real group ID. All processes have a real user ID and real group ID. These are initialized from the equivalent attributes of the process that created it. Effective User ID, Effective Group ID, and Group Access List Access to system resources is governed by two values: the effective user ID, and the group access list. The first member of the group access list is also known as the effective group ID. (In POSIX.1, the group access list is known as the set of supplementary group IDs, and it is unspecified whether the effective group ID is a member of the list.) The effective user ID and effective group ID are initially the process's real user ID and real group ID respectively. Either may be modified through execution of a set-user-ID or set-group- ID file (possibly by one of its ancestors) (see execve(2)). By convention, the effective group ID (the first member of the group access list) is duplicated, so that the execution of a set-group- ID program does not result in the loss of the original (real) group ID. The group access list is a set of group IDs used only in determining resource accessibility. Access checks are performed as described below in ``File Access Permissions''. Saved Set User ID and Saved Set Group ID When a process executes a new file, the effective user ID is set to the owner of the file if the file is set-user-ID, and the effective group ID (first element of the group access list) is set to the group of the file if the file is set-group-ID. The effective user ID of the process is then recorded as the saved set-user-ID, and the effective group ID of the process is recorded as the saved set-group-ID. These values may be used to regain those values as the effective user or group ID after reverting to the real ID (see setuid(2)). (In POSIX.1, the saved set-user-ID and saved set-group-ID are optional, and are used in setuid and setgid, but this does not work as desired for the superuser.) Superuser A process is recognized as a _s_u_p_e_r_u_s_e_r process and is granted special privileges if its effective user ID is 0. Special Processes The processes with process IDs of 0 and 1 are special. Process 0 is the scheduler. Process 1 is the initialization process init(8), and is the ancestor of every other process in the system. It is used to control the process structure. Descriptor An integer assigned by the system when a file is referenced by open(2) or dup(2), or when a socket is created by pipe(2), socket(2) or socketpair(2), which uniquely identifies an access path to that file or socket from a given process or any of its children. File Name Names consisting of up to 255 (NAME_MAX) characters may be used to name an ordinary file, special file, or directory. These characters may be arbitrary eight-bit values, excluding 0 (NUL) and the ASCII code for `/' (slash). Note that it is generally unwise to use `*', `?', `[' or `]' as part of file names because of the special meaning attached to these characters by the shell. Note also that NAME_MAX is an upper limit fixed by the kernel, meant to be used for sizing buffers. Some filesystems may have additional restrictions. These can be queried using pathconf(2) and fpathconf(2). Path Name A path name is a NUL-terminated character string starting with an optional slash `/', followed by zero or more directory names separated by slashes, optionally followed by a file name. The total length of a path name must be less than 1024 (PATH_MAX) characters. Additional restrictions may apply, depending upon the filesystem, to be queried with pathconf(2) or fpathconf(2) if needed. If a path name begins with a slash, the path search begins at the _r_o_o_t directory. Otherwise, the search begins from the current working directory. A slash by itself names the root directory. An empty pathname is invalid. Directory A directory is a special type of file that contains entries that are references to other files. Directory entries are called links. By convention, a directory contains at least two links, `.' and `..', referred to as _d_o_t and _d_o_t_-_d_o_t respectively. Dot refers to the directory itself and dot-dot refers to its parent directory. Root Directory and Current Working Directory Each process has associated with it a concept of a root directory and a current working directory for the purpose of resolving path name searches. A process's root directory need not be the root directory of the root file system. File Access Permissions Every file in the file system has a set of access permissions. These permissions are used in determining whether a process may perform a requested operation on the file (such as opening a file for writing). Access permissions are established at the time a file is created. They may be changed at some later time through the chmod(2) call. File access is broken down according to whether a file may be: read, written, or executed. Directory files use the execute permission to control if the directory may be searched. File access permissions are interpreted by the system as they apply to three different classes of users: the owner of the file, those users in the file's group, anyone else. Every file has an independent set of access permissions for each of these classes. When an access check is made, the system decides if permission should be granted by checking the access information applicable to the caller. Read, write, and execute/search permissions on a file are granted to a process if: The process's effective user ID is that of the superuser. (Note: even the superuser cannot execute a non-executable file.) The process's effective user ID matches the user ID of the owner of the file and the owner permissions allow the access. The process's effective user ID does not match the user ID of the owner of the file, and either the process's effective group ID matches the group ID of the file, or the group ID of the file is in the process's group access list, and the group permissions allow the access. Neither the effective user ID nor effective group ID and group access list of the process match the corresponding user ID and group ID of the file, but the permissions for ``other users'' allow access. Otherwise, permission is denied. Sockets and Address Families A socket is an endpoint for communication between processes. Each socket has queues for sending and receiving data. Sockets are typed according to their communications properties. These properties include whether messages sent and received at a socket require the name of the partner, whether communication is reliable, the format used in naming message recipients, etc. Each instance of the system supports some collection of socket types; consult socket(2) for more information about the types available and their properties. Each instance of the system supports some number of sets of communications protocols. Each protocol set supports addresses of a certain format. An Address Family is the set of addresses for a specific group of protocols. Each socket has an address chosen from the address family in which the socket was created. SSEEEE AALLSSOO intro(3), perror(3) HHIISSTTOORRYY An kkqquueeuuee manual page appeared in Version 6 AT&T UNIX. NNAAMMEE eexxeeccvvee, eexxeecctt - execute a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t eexxeeccvvee(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_h_a_r _*_c_o_n_s_t _a_r_g_v_[_], _c_h_a_r _*_c_o_n_s_t _e_n_v_p_[_]); _i_n_t eexxeecctt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_h_a_r _*_c_o_n_s_t _a_r_g_v_[_], _c_h_a_r _*_c_o_n_s_t _e_n_v_p_[_]); DDEESSCCRRIIPPTTIIOONN eexxeeccvvee() transforms the calling process into a new process. The new process is constructed from an ordinary file, whose name is pointed to by _p_a_t_h, called the _n_e_w _p_r_o_c_e_s_s _f_i_l_e. This file is either an executable object file, or a file of data for an interpreter. An executable object file consists of an identifying header, followed by pages of data representing the initial program (text) and initialized data pages. Additional pages may be specified by the header to be initialized with zero data; see elf(5). An interpreter file begins with a line of the form: ##!! _i_n_t_e_r_p_r_e_t_e_r [_a_r_g] When an interpreter file is passed to eexxeeccvvee() the system instead calls eexxeeccvvee() with the specified _i_n_t_e_r_p_r_e_t_e_r. If the optional _a_r_g is specified, it becomes the first argument to the _i_n_t_e_r_p_r_e_t_e_r, and the original _p_a_t_h becomes the second argument; otherwise, _p_a_t_h becomes the first argument. The original arguments are shifted over to become the subsequent arguments. The zeroth argument, normally the name of the file being executed, is left unchanged. The argument _a_r_g_v is a pointer to a null-terminated array of character pointers to NUL-terminated character strings. These strings construct the argument list to be made available to the new process. At least one non-null argument must be present in the array; by custom, the first element should be the name of the executed program (for example, the last component of _p_a_t_h). The argument _e_n_v_p is also a pointer to a null-terminated array of character pointers to NUL-terminated strings. A pointer to this array is normally stored in the global variable _e_n_v_i_r_o_n. These strings pass information to the new process that is not directly an argument to the command (see environ(7)). File descriptors open in the calling process image remain open in the new process image, except for those for which the close-on-exec flag is set (see close(2) and fcntl(2)). Descriptors that remain open are unaffected by eexxeeccvvee(). In the case of a new setuid or setgid executable being executed, if file descriptors 0, 1, or 2 (representing stdin, stdout, and stderr) are currently unallocated, these descriptors will be opened to point to some system file like _/_d_e_v_/_n_u_l_l. The intent is to ensure these descriptors are not unallocated, since many libraries make assumptions about the use of these 3 file descriptors. Signals set to be ignored in the calling process are set to be ignored in the new process. Signals which are set to be caught in the calling process image are set to default action in the new process image. Blocked signals remain blocked regardless of changes to the signal action. The signal stack is reset to be undefined (see sigaction(2) for more information). If the set-user-ID mode bit of the new process image file is set (see chmod(2)), the effective user ID of the new process image is set to the owner ID of the new process image file. If the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file. (The effective group ID is the first element of the group list.) The real user ID, real group ID and other group IDs of the new process image remain the same as the calling process image. After any set-user-ID and set-group-ID processing, the effective user ID is recorded as the saved set-user-ID, and the effective group ID is recorded as the saved set- group-ID. These values may be used in changing the effective IDs later (see setuid(2)). The set-user-ID and set-group-ID bits have no effect if the new process image file is located on a file system mounted with the nosuid flag. The process will be started without the new permissions. The new process also inherits the following attributes from the calling process: process ID see getpid(2) parent process ID see getppid(2) process group ID see getpgrp(2) session ID see getsid(2) access groups see getgroups(2) working directory see chdir(2) root directory see chroot(2) control terminal see termios(4) resource usages see getrusage(2) interval timers see getitimer(2) (unless process image file is setuid or setgid, in which case all timers are disabled) resource limits see getrlimit(2) file mode mask see umask(2) signal mask see sigaction(2), sigsetmask(3) When a program is executed as a result of an eexxeeccvvee() call, it is entered as follows: main(int argc, char **argv, char **envp) where _a_r_g_c is the number of elements in _a_r_g_v (the ``arg count'') and _a_r_g_v points to the array of character pointers to the arguments themselves. The eexxeecctt() function is equivalent to eexxeeccvvee() with the additional property that it executes the file with the process tracing facilities enabled (see ptrace(2)). RREETTUURRNN VVAALLUUEESS As the eexxeeccvvee() function overlays the current process image with a new process image the successful call has no process to return to. If eexxeeccvvee() does return to the calling process an error has occurred; the return value will be -1 and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS eexxeeccvvee() will fail and return to the calling process if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The new process file does not exist. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] The new process file is not an ordinary file. [EACCES] The new process file mode denies execute permission. [EACCES] The new process file is on a filesystem mounted with execution disabled (MNT_NOEXEC in <_s_y_s_/_m_o_u_n_t_._h>). [ENOEXEC] The new process file has the appropriate access permission, but has an invalid magic number in its header. [ETXTBSY] The new process file is a pure procedure (shared text) file that is currently open for writing or reading by some process. [ENOMEM] The new process requires more virtual memory than is allowed by the imposed maximum (getrlimit(2)). [E2BIG] The number of bytes in the new process's argument list is larger than the system-imposed limit. The limit in the system as released is 262144 bytes (NCARGS in <_s_y_s_/_p_a_r_a_m_._h>). [EFAULT] The new process file is not as long as indicated by the size values in its header. [EFAULT] _p_a_t_h, _a_r_g_v, or _e_n_v_p point to an illegal address. [EINVAL] _a_r_g_v did not contain at least one element. [EIO] An I/O error occurred while reading from the file system. [ENFILE] During startup of an _i_n_t_e_r_p_r_e_t_e_r, the system file table was found to be full. SSEEEE AALLSSOO _exit(2), fork(2), execl(3), exit(3), elf(5), environ(7) SSTTAANNDDAARRDDSS The eexxeeccvvee() function is expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). The eexxeecctt() function should not be used in portable applications. HHIISSTTOORRYY The predecessor of these functions, the former eexxeecc() system call, first appeared in Version 1 AT&T UNIX. The eexxeeccvvee() function first appeared in Version 7 AT&T UNIX. CCAAVVEEAATTSS If a program is _s_e_t_u_i_d to a non-superuser, but is executed when the real _u_i_d is ``root'', then the process has some of the powers of a superuser as well. NNAAMMEE eexxeeccvvee, eexxeecctt - execute a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t eexxeeccvvee(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_h_a_r _*_c_o_n_s_t _a_r_g_v_[_], _c_h_a_r _*_c_o_n_s_t _e_n_v_p_[_]); _i_n_t eexxeecctt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_h_a_r _*_c_o_n_s_t _a_r_g_v_[_], _c_h_a_r _*_c_o_n_s_t _e_n_v_p_[_]); DDEESSCCRRIIPPTTIIOONN eexxeeccvvee() transforms the calling process into a new process. The new process is constructed from an ordinary file, whose name is pointed to by _p_a_t_h, called the _n_e_w _p_r_o_c_e_s_s _f_i_l_e. This file is either an executable object file, or a file of data for an interpreter. An executable object file consists of an identifying header, followed by pages of data representing the initial program (text) and initialized data pages. Additional pages may be specified by the header to be initialized with zero data; see elf(5). An interpreter file begins with a line of the form: ##!! _i_n_t_e_r_p_r_e_t_e_r [_a_r_g] When an interpreter file is passed to eexxeeccvvee() the system instead calls eexxeeccvvee() with the specified _i_n_t_e_r_p_r_e_t_e_r. If the optional _a_r_g is specified, it becomes the first argument to the _i_n_t_e_r_p_r_e_t_e_r, and the original _p_a_t_h becomes the second argument; otherwise, _p_a_t_h becomes the first argument. The original arguments are shifted over to become the subsequent arguments. The zeroth argument, normally the name of the file being executed, is left unchanged. The argument _a_r_g_v is a pointer to a null-terminated array of character pointers to NUL-terminated character strings. These strings construct the argument list to be made available to the new process. At least one non-null argument must be present in the array; by custom, the first element should be the name of the executed program (for example, the last component of _p_a_t_h). The argument _e_n_v_p is also a pointer to a null-terminated array of character pointers to NUL-terminated strings. A pointer to this array is normally stored in the global variable _e_n_v_i_r_o_n. These strings pass information to the new process that is not directly an argument to the command (see environ(7)). File descriptors open in the calling process image remain open in the new process image, except for those for which the close-on-exec flag is set (see close(2) and fcntl(2)). Descriptors that remain open are unaffected by eexxeeccvvee(). In the case of a new setuid or setgid executable being executed, if file descriptors 0, 1, or 2 (representing stdin, stdout, and stderr) are currently unallocated, these descriptors will be opened to point to some system file like _/_d_e_v_/_n_u_l_l. The intent is to ensure these descriptors are not unallocated, since many libraries make assumptions about the use of these 3 file descriptors. Signals set to be ignored in the calling process are set to be ignored in the new process. Signals which are set to be caught in the calling process image are set to default action in the new process image. Blocked signals remain blocked regardless of changes to the signal action. The signal stack is reset to be undefined (see sigaction(2) for more information). If the set-user-ID mode bit of the new process image file is set (see chmod(2)), the effective user ID of the new process image is set to the owner ID of the new process image file. If the set-group-ID mode bit of the new process image file is set, the effective group ID of the new process image is set to the group ID of the new process image file. (The effective group ID is the first element of the group list.) The real user ID, real group ID and other group IDs of the new process image remain the same as the calling process image. After any set-user-ID and set-group-ID processing, the effective user ID is recorded as the saved set-user-ID, and the effective group ID is recorded as the saved set- group-ID. These values may be used in changing the effective IDs later (see setuid(2)). The set-user-ID and set-group-ID bits have no effect if the new process image file is located on a file system mounted with the nosuid flag. The process will be started without the new permissions. The new process also inherits the following attributes from the calling process: process ID see getpid(2) parent process ID see getppid(2) process group ID see getpgrp(2) session ID see getsid(2) access groups see getgroups(2) working directory see chdir(2) root directory see chroot(2) control terminal see termios(4) resource usages see getrusage(2) interval timers see getitimer(2) (unless process image file is setuid or setgid, in which case all timers are disabled) resource limits see getrlimit(2) file mode mask see umask(2) signal mask see sigaction(2), sigsetmask(3) When a program is executed as a result of an eexxeeccvvee() call, it is entered as follows: main(int argc, char **argv, char **envp) where _a_r_g_c is the number of elements in _a_r_g_v (the ``arg count'') and _a_r_g_v points to the array of character pointers to the arguments themselves. The eexxeecctt() function is equivalent to eexxeeccvvee() with the additional property that it executes the file with the process tracing facilities enabled (see ptrace(2)). RREETTUURRNN VVAALLUUEESS As the eexxeeccvvee() function overlays the current process image with a new process image the successful call has no process to return to. If eexxeeccvvee() does return to the calling process an error has occurred; the return value will be -1 and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS eexxeeccvvee() will fail and return to the calling process if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The new process file does not exist. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] The new process file is not an ordinary file. [EACCES] The new process file mode denies execute permission. [EACCES] The new process file is on a filesystem mounted with execution disabled (MNT_NOEXEC in <_s_y_s_/_m_o_u_n_t_._h>). [ENOEXEC] The new process file has the appropriate access permission, but has an invalid magic number in its header. [ETXTBSY] The new process file is a pure procedure (shared text) file that is currently open for writing or reading by some process. [ENOMEM] The new process requires more virtual memory than is allowed by the imposed maximum (getrlimit(2)). [E2BIG] The number of bytes in the new process's argument list is larger than the system-imposed limit. The limit in the system as released is 262144 bytes (NCARGS in <_s_y_s_/_p_a_r_a_m_._h>). [EFAULT] The new process file is not as long as indicated by the size values in its header. [EFAULT] _p_a_t_h, _a_r_g_v, or _e_n_v_p point to an illegal address. [EINVAL] _a_r_g_v did not contain at least one element. [EIO] An I/O error occurred while reading from the file system. [ENFILE] During startup of an _i_n_t_e_r_p_r_e_t_e_r, the system file table was found to be full. SSEEEE AALLSSOO _exit(2), fork(2), execl(3), exit(3), elf(5), environ(7) SSTTAANNDDAARRDDSS The eexxeeccvvee() function is expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). The eexxeecctt() function should not be used in portable applications. HHIISSTTOORRYY The predecessor of these functions, the former eexxeecc() system call, first appeared in Version 1 AT&T UNIX. The eexxeeccvvee() function first appeared in Version 7 AT&T UNIX. CCAAVVEEAATTSS If a program is _s_e_t_u_i_d to a non-superuser, but is executed when the real _u_i_d is ``root'', then the process has some of the powers of a superuser as well. NNAAMMEE aacccceessss, ffaacccceessssaatt - check access permissions of a file or pathname SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aacccceessss(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _a_m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffaacccceessssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _a_m_o_d_e, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The aacccceessss() function checks the accessibility of the file named by _p_a_t_h for the access permissions indicated by _a_m_o_d_e. The _a_m_o_d_e argument is either the bitwise OR of one or more of the access permissions to be checked (R_OK for read permission, W_OK for write permission, and X_OK for execute/search permission) or the existence test, F_OK. All components of the pathname _p_a_t_h are checked for access permissions (including F_OK). The real user ID is used in place of the effective user ID and the real group access list (including the real group ID) is used in place of the effective ID for verifying permission. If the invoking process has superuser privileges, aacccceessss() will always indicate success for R_OK and W_OK, regardless of the actual file permission bits. Likewise, for X_OK, if the file has any of the execute bits set and _p_a_t_h is not a directory, aacccceessss() will indicate success. The ffaacccceessssaatt() function is equivalent to aacccceessss() except that where _p_a_t_h specifies a relative path, the file whose accessibility is checked is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffaacccceessssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. If _f_l_a_g is also zero, the behavior is identical to a call to aacccceessss(). The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_EACCESS The checks for accessibility are performed using the effective user and group IDs instead of the real user and group IDs. RREETTUURRNN VVAALLUUEESS If _p_a_t_h cannot be found or if any of the desired access modes would not be granted, then a -1 value is returned; otherwise a 0 value is returned. EERRRROORRSS Access to the file is denied if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EROFS] Write access is requested for a file on a read-only file system. [ETXTBSY] Write access is requested for a pure procedure (shared text) file presently being executed. [EACCES] Permission bits of the file mode do not permit the requested access, or search permission is denied on a component of the path prefix. The owner of a file has permission checked with respect to the ``owner'' read, write, and execute mode bits, members of the file's group other than the owner have permission checked with respect to the ``group'' mode bits, and all others have permissions checked with respect to the ``other'' mode bits. [EPERM] Write access has been requested and the named file has its immutable flag set (see chflags(2)). [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. [EINVAL] An invalid value was specified for _a_m_o_d_e. Additionally, ffaacccceessssaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_EACCESS. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chmod(2), stat(2) SSTTAANNDDAARRDDSS The aacccceessss() and ffaacccceessssaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY aacccceessss() first appeared as an internal kernel function in Version 1 AT&T UNIX and was reimplemented in C before the release of Version 4 AT&T UNIX. It was first promoted to a system call in the Programmer's Workbench (PWB/UNIX), which was later ported to Version 7 AT&T UNIX and 2BSD. The ffaacccceessssaatt() function appeared in OpenBSD 5.0. AAUUTTHHOORRSS Ken Thompson first implemented the aacccceessss() kernel function in C. CCAAVVEEAATTSS aacccceessss() and ffaacccceessssaatt() should never be used for actual access control. Doing so can result in a time of check vs. time of use security hole. NNAAMMEE cchhddiirr, ffcchhddiirr - change current working directory SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhddiirr(_c_o_n_s_t _c_h_a_r _*_p_a_t_h); _i_n_t ffcchhddiirr(_i_n_t _f_d); DDEESSCCRRIIPPTTIIOONN The _p_a_t_h argument points to the pathname of a directory. The cchhddiirr() function causes the named directory to become the current working directory, that is, the starting point for path searches of pathnames not beginning with a slash (`/'). The ffcchhddiirr() function causes the directory referenced by _f_d to become the current working directory, the starting point for path searches of pathnames not beginning with a slash (`/'). In order for a directory to become the current directory, a process must have execute (search) access to the directory. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhddiirr() will fail and the current working directory will be unchanged if one or more of the following are true: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named directory does not exist. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EACCES] Search permission is denied for any component of the pathname. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from the file system. ffcchhddiirr() will fail and the current working directory will be unchanged if one or more of the following are true: [EACCES] Search permission is denied for the directory referenced by the file descriptor. [ENOTDIR] The file descriptor does not reference a directory. [EBADF] The argument _f_d is not a valid file descriptor. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chroot(2) SSTTAANNDDAARRDDSS The cchhddiirr() and ffcchhddiirr() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhddiirr() system call first appeared in Version 1 AT&T UNIX, and ffcchhddiirr() in 4.3BSD-Reno. NNAAMMEE cchhffllaaggss, cchhffllaaggssaatt, ffcchhffllaaggss - set file flags SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhffllaaggss(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s); _i_n_t ffcchhffllaaggss(_i_n_t _f_d, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t cchhffllaaggssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_n_s_i_g_n_e_d _i_n_t _f_l_a_g_s, _i_n_t _a_t_f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The file whose name is given by _p_a_t_h or referenced by the descriptor _f_d has its flags changed to _f_l_a_g_s. The flags are the bitwise OR of zero or more of the following values: UF_NODUMP Do not dump the file. UF_IMMUTABLE The file may not be changed. UF_APPEND The file may only be appended to. SF_ARCHIVED The file may be archived. SF_IMMUTABLE The file may not be changed. SF_APPEND The file may only be appended to. The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the owner of a file or the superuser. The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or unset by the superuser. They may be set at any time, but normally may only be unset when the system is in single-user mode. (See init(8) for details.) The cchhffllaaggssaatt() function is equivalent to cchhffllaaggss() except in the case where _p_a_t_h specifies a relative path. In this case the file to be changed is determined relative to the directory associated with the file descriptor _f_d instead of the current working directory. If cchhffllaaggssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. If _f_l_a_g is also zero, the behavior is identical to a call to cchhffllaaggss(). The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the flags of the symbolic link are changed. The ffcchhffllaaggss() function is equivalent to cchhffllaaggss() except that the file whose flags are changed is specified by the file descriptor _f_d. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhffllaaggss() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser, or the effective user ID is not the superuser and at least one of the super-user-only flags for the named file would be changed. [EOPNOTSUPP] The named file resides on a file system that does not support file flags. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. [EINVAL] The _f_l_a_g_s value is invalid. [EINVAL] The descriptor references a block or character device and the effective user ID is not the superuser. ffcchhffllaaggss() will fail if: [EBADF] The descriptor is not valid. [EINVAL] _f_d refers to a socket, not to a file. [EINVAL] The descriptor references a block or character device and the effective user ID is not the superuser. [EINVAL] The _f_l_a_g_s value is invalid. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser, or the effective user ID is not the superuser and at least one of the super-user-only flags for the named file would be changed. [EOPNOTSUPP] The named file resides on a file system that does not support file flags. [EROFS] The file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chflags(1), init(8) HHIISSTTOORRYY The cchhffllaaggss() and ffcchhffllaaggss() functions first appeared in 4.4BSD. The cchhffllaaggssaatt() function first appeared in FreeBSD 10.0. It was added to OpenBSD in OpenBSD 5.7. NNAAMMEE cchhmmoodd, ffcchhmmooddaatt, ffcchhmmoodd - change mode of file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhmmoodd(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); _i_n_t ffcchhmmoodd(_i_n_t _f_d, _m_o_d_e___t _m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffcchhmmooddaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The cchhmmoodd() function sets the file permission bits of the file specified by the pathname _p_a_t_h to _m_o_d_e. cchhmmoodd() verifies that the process owner (user) either owns the specified file or is the superuser. The _m_o_d_e argument is the bitwise OR of zero or more of the permission bit masks from the following list: #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ #define S_ISUID 0004000 /* set user id on execution */ #define S_ISGID 0002000 /* set group id on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ If mode ISVTX (the _s_t_i_c_k_y _b_i_t) is set on a file, it is ignored. If mode ISVTX (the _s_t_i_c_k_y _b_i_t) is set on a directory, an unprivileged user may not delete or rename files of other users in that directory. The sticky bit may be set by any user on a directory which the user owns or has appropriate permissions. For more details of the properties of the sticky bit, see sticky(8). Writing or changing the owner of a file turns off the set-user-ID and set-group-ID bits unless the user is the superuser. This makes the system somewhat more secure by protecting set-user-ID (set-group-ID) files from remaining set-user-ID (set-group-ID) if they are modified, at the expense of a degree of compatibility. The ffcchhmmooddaatt() function is equivalent to cchhmmoodd() except in the case where _p_a_t_h specifies a relative path. In this case the file to be changed is determined relative to the directory associated with the file descriptor _f_d instead of the current working directory. If ffcchhmmooddaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. If _f_l_a_g is also zero, the behavior is identical to a call to cchhmmoodd(). The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the mode of the symbolic link is changed. The ffcchhmmoodd() function is equivalent to cchhmmoodd() except that the file whose permissions are changed is specified by the file descriptor _f_d. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The cchhmmoodd() and ffcchhmmooddaatt() functions will fail and the file mode will be unchanged if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EINVAL] _m_o_d_e contains bits other than the file type and those described above. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, the ffcchhmmooddaatt() function will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EOPNOTSUPP] The _f_l_a_g argument specifies AT_SYMLINK_NOFOLLOW on a symbolic link and the file system does not support that operation. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffcchhmmoodd() will fail and the file mode will be unchanged if: [EBADF] The descriptor is not valid. [EINVAL] _f_d refers to a socket, not to a file. [EINVAL] _m_o_d_e contains bits other than the file type and those described above. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser. [EROFS] The file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chmod(1), chown(2), open(2), stat(2), sticky(8) SSTTAANNDDAARRDDSS The cchhmmoodd(), ffcchhmmoodd(), and ffcchhmmooddaatt() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhmmoodd() system call first appeared in Version 1 AT&T UNIX; ffcchhmmoodd() in 4.1cBSD; and ffcchhmmooddaatt() has been available since OpenBSD 5.0. NNAAMMEE cchhmmoodd, ffcchhmmooddaatt, ffcchhmmoodd - change mode of file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhmmoodd(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); _i_n_t ffcchhmmoodd(_i_n_t _f_d, _m_o_d_e___t _m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffcchhmmooddaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The cchhmmoodd() function sets the file permission bits of the file specified by the pathname _p_a_t_h to _m_o_d_e. cchhmmoodd() verifies that the process owner (user) either owns the specified file or is the superuser. The _m_o_d_e argument is the bitwise OR of zero or more of the permission bit masks from the following list: #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ #define S_ISUID 0004000 /* set user id on execution */ #define S_ISGID 0002000 /* set group id on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ If mode ISVTX (the _s_t_i_c_k_y _b_i_t) is set on a file, it is ignored. If mode ISVTX (the _s_t_i_c_k_y _b_i_t) is set on a directory, an unprivileged user may not delete or rename files of other users in that directory. The sticky bit may be set by any user on a directory which the user owns or has appropriate permissions. For more details of the properties of the sticky bit, see sticky(8). Writing or changing the owner of a file turns off the set-user-ID and set-group-ID bits unless the user is the superuser. This makes the system somewhat more secure by protecting set-user-ID (set-group-ID) files from remaining set-user-ID (set-group-ID) if they are modified, at the expense of a degree of compatibility. The ffcchhmmooddaatt() function is equivalent to cchhmmoodd() except in the case where _p_a_t_h specifies a relative path. In this case the file to be changed is determined relative to the directory associated with the file descriptor _f_d instead of the current working directory. If ffcchhmmooddaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. If _f_l_a_g is also zero, the behavior is identical to a call to cchhmmoodd(). The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the mode of the symbolic link is changed. The ffcchhmmoodd() function is equivalent to cchhmmoodd() except that the file whose permissions are changed is specified by the file descriptor _f_d. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The cchhmmoodd() and ffcchhmmooddaatt() functions will fail and the file mode will be unchanged if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EINVAL] _m_o_d_e contains bits other than the file type and those described above. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, the ffcchhmmooddaatt() function will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EOPNOTSUPP] The _f_l_a_g argument specifies AT_SYMLINK_NOFOLLOW on a symbolic link and the file system does not support that operation. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffcchhmmoodd() will fail and the file mode will be unchanged if: [EBADF] The descriptor is not valid. [EINVAL] _f_d refers to a socket, not to a file. [EINVAL] _m_o_d_e contains bits other than the file type and those described above. [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not the superuser. [EROFS] The file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chmod(1), chown(2), open(2), stat(2), sticky(8) SSTTAANNDDAARRDDSS The cchhmmoodd(), ffcchhmmoodd(), and ffcchhmmooddaatt() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhmmoodd() system call first appeared in Version 1 AT&T UNIX; ffcchhmmoodd() in 4.1cBSD; and ffcchhmmooddaatt() has been available since OpenBSD 5.0. NNAAMMEE cchhoowwnn, llcchhoowwnn, ffcchhoowwnnaatt, ffcchhoowwnn - change owner and group of a file or link SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhoowwnn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); _i_n_t llcchhoowwnn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); _i_n_t ffcchhoowwnn(_i_n_t _f_d, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffcchhoowwnnaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The owner ID and group ID of the file (or link) named by _p_a_t_h or referenced by _f_d is changed as specified by the arguments _o_w_n_e_r and _g_r_o_u_p. The owner of a file may change the _g_r_o_u_p to a group of which he or she is a member, but the change _o_w_n_e_r capability is restricted to the superuser. By default, cchhoowwnn() clears the set-user-ID and set-group-ID bits on the file to prevent accidental or mischievous creation of set-user-ID and set-group-ID programs. This behaviour can be overridden by setting the sysctl(8) variable _f_s_._p_o_s_i_x_._s_e_t_u_i_d to zero. llcchhoowwnn() operates similarly to how cchhoowwnn() operated on older systems, and does not follow symbolic links. It allows the owner and group of a symbolic link to be set. The ffcchhoowwnnaatt() function is equivalent to either the cchhoowwnn() or llcchhoowwnn() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose ownership is changed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffcchhoowwnnaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to cchhoowwnn() or llcchhoowwnn(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the ownership of the symbolic link is changed. ffcchhoowwnn() is particularly useful when used in conjunction with the file locking primitives (see flock(2)). One of the owner or group IDs may be left unchanged by specifying it as -1. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhoowwnn(), llcchhoowwnn(), and ffcchhoowwnnaatt() will fail and the file or link will be unchanged if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffcchhoowwnnaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffcchhoowwnn() will fail if: [EBADF] _f_d does not refer to a valid descriptor. [EINVAL] _f_d refers to a socket, not a file. [EPERM] The effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chgrp(1), chmod(2), flock(2), chown(8) SSTTAANNDDAARRDDSS The cchhoowwnn(), ffcchhoowwnn(), ffcchhoowwnnaatt(), and llcchhoowwnn() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhoowwnn() system call first appeared in Version 1 AT&T UNIX. Since Version 6 AT&T UNIX it supports changing the group as well, and in Version 7 AT&T UNIX _g_r_o_u_p was made a separate argument. The ffcchhoowwnn() system call first appeared in 4.1cBSD. The cchhoowwnn() and ffcchhoowwnn() system calls were changed to follow symbolic links in 4.4BSD; therefore, and for compatibility with AT&T System V Release 4 UNIX, the llcchhoowwnn() system call was added to OpenBSD 2.1. The ffcchhoowwnnaatt() system call has been available since OpenBSD 5.0. NNAAMMEE cchhoowwnn, llcchhoowwnn, ffcchhoowwnnaatt, ffcchhoowwnn - change owner and group of a file or link SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhoowwnn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); _i_n_t llcchhoowwnn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); _i_n_t ffcchhoowwnn(_i_n_t _f_d, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffcchhoowwnnaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The owner ID and group ID of the file (or link) named by _p_a_t_h or referenced by _f_d is changed as specified by the arguments _o_w_n_e_r and _g_r_o_u_p. The owner of a file may change the _g_r_o_u_p to a group of which he or she is a member, but the change _o_w_n_e_r capability is restricted to the superuser. By default, cchhoowwnn() clears the set-user-ID and set-group-ID bits on the file to prevent accidental or mischievous creation of set-user-ID and set-group-ID programs. This behaviour can be overridden by setting the sysctl(8) variable _f_s_._p_o_s_i_x_._s_e_t_u_i_d to zero. llcchhoowwnn() operates similarly to how cchhoowwnn() operated on older systems, and does not follow symbolic links. It allows the owner and group of a symbolic link to be set. The ffcchhoowwnnaatt() function is equivalent to either the cchhoowwnn() or llcchhoowwnn() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose ownership is changed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffcchhoowwnnaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to cchhoowwnn() or llcchhoowwnn(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the ownership of the symbolic link is changed. ffcchhoowwnn() is particularly useful when used in conjunction with the file locking primitives (see flock(2)). One of the owner or group IDs may be left unchanged by specifying it as -1. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhoowwnn(), llcchhoowwnn(), and ffcchhoowwnnaatt() will fail and the file or link will be unchanged if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffcchhoowwnnaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffcchhoowwnn() will fail if: [EBADF] _f_d does not refer to a valid descriptor. [EINVAL] _f_d refers to a socket, not a file. [EPERM] The effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chgrp(1), chmod(2), flock(2), chown(8) SSTTAANNDDAARRDDSS The cchhoowwnn(), ffcchhoowwnn(), ffcchhoowwnnaatt(), and llcchhoowwnn() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhoowwnn() system call first appeared in Version 1 AT&T UNIX. Since Version 6 AT&T UNIX it supports changing the group as well, and in Version 7 AT&T UNIX _g_r_o_u_p was made a separate argument. The ffcchhoowwnn() system call first appeared in 4.1cBSD. The cchhoowwnn() and ffcchhoowwnn() system calls were changed to follow symbolic links in 4.4BSD; therefore, and for compatibility with AT&T System V Release 4 UNIX, the llcchhoowwnn() system call was added to OpenBSD 2.1. The ffcchhoowwnnaatt() system call has been available since OpenBSD 5.0. NNAAMMEE ffccnnttll - file control SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ffccnnttll(_i_n_t _f_d, _i_n_t _c_m_d, _._._.); DDEESSCCRRIIPPTTIIOONN The ffccnnttll() provides control over the properties of a file that is already open. The argument _f_d is a descriptor to be operated on by _c_m_d as described below. The third parameter is called _a_r_g and is technically a pointer to _v_o_i_d, but is interpreted as an int by some commands, a pointer to a struct flock by others (see below), and ignored by the rest. The commands are: F_DUPFD Return a new descriptor as follows: ++oo Lowest numbered available descriptor greater than or equal to _a_r_g (interpreted as an int). ++oo Same object references as the original descriptor. ++oo New descriptor shares the same file offset if the object was a file. ++oo Same access mode (read, write or read/write). ++oo Same file status flags (i.e., both file descriptors share the same file status flags). ++oo The close-on-exec flag associated with the new file descriptor is set to remain open across execve(2) calls. F_DUPFD_CLOEXEC Like F_DUPFD, but the FD_CLOEXEC flag associated with the new file descriptor is set, so the file descriptor is closed when execve(2) is called. F_GETFD Get the close-on-exec flag associated with the file descriptor _f_d as FD_CLOEXEC. If the returned value ANDed with FD_CLOEXEC is 0, the file will remain open across eexxeecc(), otherwise the file will be closed upon execution of eexxeecc() (_a_r_g is ignored). F_SETFD Set the close-on-exec flag associated with _f_d to _a_r_g, where _a_r_g (interpreted as an int) is either 0 or FD_CLOEXEC, as described above. F_GETFL Get file status flags associated with the file descriptor _f_d, as described below (_a_r_g is ignored). F_SETFL Set file status flags associated with the file descriptor _f_d to _a_r_g (interpreted as an int). F_GETOWN Get the process ID or process group currently receiving SIGIO and SIGURG signals; process groups are returned as negative values (_a_r_g is ignored). F_SETOWN Set the process or process group to receive SIGIO and SIGURG signals; process groups are specified by supplying _a_r_g (interpreted as an int) as negative, otherwise _a_r_g is taken as a process ID. The flags for the F_GETFL and F_SETFL commands are as follows: O_NONBLOCK Non-blocking I/O; if no data is available to a read(2) call, or if a write(2) operation would block, the read or write call returns -1 with the error EAGAIN. O_APPEND Force each write to append at the end of file; corresponds to the O_APPEND flag of open(2). O_ASYNC Enable the SIGIO signal to be sent to the process group when I/O is possible, e.g., upon availability of data to be read. O_SYNC Cause writes to be synchronous. Data will be written to the physical device instead of just being stored in the buffer cache; corresponds to the O_SYNC flag of open(2). Several commands are available for doing advisory file locking; they all operate on the following structure: struct flock { off_t l_start; /* starting offset */ off_t l_len; /* len = 0 means until end of file */ pid_t l_pid; /* lock owner */ short l_type; /* lock type: read/write, etc. */ short l_whence; /* type of l_start */ }; The commands available for advisory record locking are as follows: F_GETLK Get the first lock that blocks the lock description pointed to by the third argument, _a_r_g, taken as a pointer to a _s_t_r_u_c_t _f_l_o_c_k (see above). The information retrieved overwrites the information passed to ffccnnttll() in the _f_l_o_c_k structure. If no lock is found that would prevent this lock from being created, the structure is left unchanged by this function call except for the lock type which is set to F_UNLCK. F_SETLK Set or clear a file segment lock according to the lock description pointed to by the third argument, _a_r_g, taken as a pointer to a _s_t_r_u_c_t _f_l_o_c_k (see above). F_SETLK is used to establish shared (or read) locks (F_RDLCK) or exclusive (or write) locks (F_WRLCK), as well as remove either type of lock (F_UNLCK). If a shared or exclusive lock cannot be set, ffccnnttll() returns immediately with EAGAIN. F_SETLKW This command is the same as F_SETLK except that if a shared or exclusive lock is blocked by other locks, the process waits until the request can be satisfied. If a signal that is to be caught is received while ffccnnttll() is waiting for a region, the ffccnnttll() will be interrupted if the signal handler has not specified the SA_RESTART (see sigaction(2)). When a shared lock has been set on a segment of a file, other processes can set shared locks on that segment or a portion of it. A shared lock prevents any other process from setting an exclusive lock on any portion of the protected area. A request for a shared lock fails if the file descriptor was not opened with read access. An exclusive lock prevents any other process from setting a shared lock or an exclusive lock on any portion of the protected area. A request for an exclusive lock fails if the file was not opened with write access. The value of _l___w_h_e_n_c_e is SEEK_SET, SEEK_CUR, or SEEK_END to indicate that the relative offset, _l___s_t_a_r_t bytes, will be measured from the start of the file, current position, or end of the file, respectively. The value of _l___l_e_n is the number of consecutive bytes to be locked. If _l___l_e_n is negative, the result is undefined. The _l___p_i_d field is only used with F_GETLK to return the process ID of the process holding a blocking lock. After a successful F_GETLK request, the value of _l___w_h_e_n_c_e is SEEK_SET. Locks may start and extend beyond the current end of a file, but may not start or extend before the beginning of the file. A lock is set to extend to the largest possible value of the file offset for that file if _l___l_e_n is set to zero. If _l___w_h_e_n_c_e and _l___s_t_a_r_t point to the beginning of the file, and _l___l_e_n is zero, the entire file is locked. If an application wishes only to do entire file locking, the flock(2) system call is much more efficient. There is at most one type of lock set for each byte in the file. Before a successful return from an F_SETLK or an F_SETLKW request when the calling process has previously existing locks on bytes in the region specified by the request, the previous lock type for each byte in the specified region is replaced by the new lock type. As specified above under the descriptions of shared locks and exclusive locks, an F_SETLK or an F_SETLKW request fails or blocks respectively when another process has existing locks on bytes in the specified region and the type of any of those locks conflicts with the type specified in the request. This interface follows the completely stupid semantics of System V and IEEE Std 1003.1-1988 (``POSIX.1'') that require that all locks associated with a file for a given process are removed when _a_n_y file descriptor for that file is closed by that process. This semantic means that applications must be aware of any files that a subroutine library may access. For example if an application for updating the password file locks the password file database while making the update, and then calls getpwnam(3) to retrieve a record, the lock will be lost because getpwnam(3) opens, reads, and closes the password database. The database close will release all locks that the process has associated with the database, even if the library routine never requested a lock on the database. Another minor semantic problem with this interface is that locks are not inherited by a child process created using the fork(2) function. The flock(2) interface has much more rational last close semantics and allows locks to be inherited by child processes. flock(2) is recommended for applications that want to ensure the integrity of their locks when using library routines or wish to pass locks to their children. Note that flock(2) and ffccnnttll() locks may be safely used concurrently. All locks associated with a file for a given process are removed when the process terminates. A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock the locked region of another process. This implementation detects that sleeping until a locked region is unlocked would cause a deadlock and fails with an EDEADLK error. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value returned depends on _c_m_d as follows: F_DUPFD A new file descriptor. F_DUPFD_CLOEXEC A new file descriptor. F_GETFD Value of flag (only the low-order bit is defined). F_GETFL Value of flags. F_GETOWN Value of file descriptor owner. other Value other than -1. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS ffccnnttll() will fail if: [EAGAIN] The argument _c_m_d is F_SETLK, the type of lock (_l___t_y_p_e) is a shared lock (F_RDLCK) or exclusive lock (F_WRLCK), and the segment of a file to be locked is already exclusive-locked by another process; or the type is an exclusive lock and some portion of the segment of a file to be locked is already shared- locked or exclusive-locked by another process. [EBADF] _f_d is not a valid open file descriptor. The argument _c_m_d is F_SETLK or F_SETLKW, the type of lock (_l___t_y_p_e) is a shared lock (F_RDLCK), and _f_d is not a valid file descriptor open for reading. The argument _c_m_d is F_SETLK or F_SETLKW, the type of lock (_l___t_y_p_e) is an exclusive lock (F_WRLCK), and _f_d is not a valid file descriptor open for writing. [EDEADLK] The argument _c_m_d is F_SETLKW, and a deadlock condition was detected. [EINTR] The argument _c_m_d is invalid. The argument _c_m_d is F_SETLKW, and the function was interrupted by a signal. [EINVAL] _c_m_d is F_DUPFD and _a_r_g is negative or greater than the maximum allowable number (see getdtablesize(3)). The argument _c_m_d is F_GETLK, F_SETLK, or F_SETLKW and the data to which _a_r_g points is not valid, or _f_d refers to a file that does not support locking. [EMFILE] The argument _c_m_d is F_DUPFD and the maximum number of open file descriptors permitted for the process are already in use, or no file descriptors greater than or equal to _a_r_g are available. [ENOLCK] The argument _c_m_d is F_SETLK or F_SETLKW, and satisfying the lock or unlock request would result in the number of locked regions in the system exceeding a system-imposed limit. [ESRCH] _c_m_d is F_SETOWN and the process ID given in _a_r_g is not in use. SSEEEE AALLSSOO close(2), execve(2), flock(2), open(2), sigaction(2), getdtablesize(3) SSTTAANNDDAARRDDSS The ffccnnttll() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ffccnnttll() function call appeared in 4.2BSD. NNAAMMEE ffssyynncc, ffddaattaassyynncc - synchronize a file's in-core state with that on disk SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ffssyynncc(_i_n_t _f_d); _i_n_t ffddaattaassyynncc(_i_n_t _f_d); DDEESSCCRRIIPPTTIIOONN The ffssyynncc() function causes all modified data and attributes of _f_d to be moved to a permanent storage device. This normally results in all in- core modified copies of buffers for the associated file to be written to a disk. The ffddaattaassyynncc() function is similar to ffssyynncc() except that it only guarantees modified data (and metadata necessary to read that data) is committed to storage. Other file modifications may be left unsynchronized. ffssyynncc() and ffddaattaassyynncc() should be used by programs that require a file to be in a known state, for example, in building a simple transaction facility. RREETTUURRNN VVAALLUUEESS The ffssyynncc() and ffddaattaassyynncc() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The ffssyynncc() and ffddaattaassyynncc() functions fail if: [EBADF] _f_d is not a valid descriptor. [EINVAL] _f_d does not refer to a file which can be synchronized. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO sync(2), sync(8) SSTTAANNDDAARRDDSS The ffssyynncc() and ffddaattaassyynncc() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ffssyynncc() system call first appeared in 4.1cBSD, and the ffddaattaassyynncc() function has been available since OpenBSD 5.4. BBUUGGSS The ffddaattaassyynncc() function is currently a wrapper around ffssyynncc(), so it synchronizes more state than necessary. NNAAMMEE ffhhooppeenn, ffhhssttaatt, ffhhssttaattffss - access file via file handle SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffhhooppeenn(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _i_n_t _f_l_a_g_s); _i_n_t ffhhssttaatt(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffhhssttaattffss(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _s_t_r_u_c_t _s_t_a_t_f_s _*_b_u_f); DDEESSCCRRIIPPTTIIOONN These functions provide a means to access a file given the file handle _f_h_p. As this method bypasses directory access restrictions, these calls are restricted to the superuser. ffhhooppeenn() opens the file referenced by _f_h_p for reading and/or writing as specified by the argument _f_l_a_g_s and returns the file descriptor to the calling process. The _f_l_a_g_s are specified by _o_r'ing together the flags used for the open(2) call. All said flags are valid except for O_CREAT. ffhhssttaatt() and ffhhssttaattffss() provide the functionality of the fstat(2) and fstatfs(2) calls except that they return information for the file referred to by _f_h_p rather than an open file. RREETTUURRNN VVAALLUUEESS Upon successful completion, ffhhooppeenn() returns the file descriptor for the opened file, while ffhhssttaatt() and ffhhssttaattffss() return 0. Otherwise, -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS In addition to the errors returned by open(2), fstat(2), and fstatfs(2) respectively, ffhhooppeenn(), ffhhssttaatt(), and ffhhssttaattffss() will return [EINVAL] Calling ffhhooppeenn() with O_CREAT set. [ESTALE] The file handle _f_h_p is no longer valid. SSEEEE AALLSSOO fstat(2), fstatfs(2), getfh(2), open(2) HHIISSTTOORRYY The ffhhooppeenn(), ffhhssttaatt(), and ffhhssttaattffss() functions first appeared in NetBSD 1.5. NNAAMMEE ffhhooppeenn, ffhhssttaatt, ffhhssttaattffss - access file via file handle SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffhhooppeenn(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _i_n_t _f_l_a_g_s); _i_n_t ffhhssttaatt(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffhhssttaattffss(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _s_t_r_u_c_t _s_t_a_t_f_s _*_b_u_f); DDEESSCCRRIIPPTTIIOONN These functions provide a means to access a file given the file handle _f_h_p. As this method bypasses directory access restrictions, these calls are restricted to the superuser. ffhhooppeenn() opens the file referenced by _f_h_p for reading and/or writing as specified by the argument _f_l_a_g_s and returns the file descriptor to the calling process. The _f_l_a_g_s are specified by _o_r'ing together the flags used for the open(2) call. All said flags are valid except for O_CREAT. ffhhssttaatt() and ffhhssttaattffss() provide the functionality of the fstat(2) and fstatfs(2) calls except that they return information for the file referred to by _f_h_p rather than an open file. RREETTUURRNN VVAALLUUEESS Upon successful completion, ffhhooppeenn() returns the file descriptor for the opened file, while ffhhssttaatt() and ffhhssttaattffss() return 0. Otherwise, -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS In addition to the errors returned by open(2), fstat(2), and fstatfs(2) respectively, ffhhooppeenn(), ffhhssttaatt(), and ffhhssttaattffss() will return [EINVAL] Calling ffhhooppeenn() with O_CREAT set. [ESTALE] The file handle _f_h_p is no longer valid. SSEEEE AALLSSOO fstat(2), fstatfs(2), getfh(2), open(2) HHIISSTTOORRYY The ffhhooppeenn(), ffhhssttaatt(), and ffhhssttaattffss() functions first appeared in NetBSD 1.5. NNAAMMEE ffhhooppeenn, ffhhssttaatt, ffhhssttaattffss - access file via file handle SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffhhooppeenn(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _i_n_t _f_l_a_g_s); _i_n_t ffhhssttaatt(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffhhssttaattffss(_c_o_n_s_t _f_h_a_n_d_l_e___t _*_f_h_p, _s_t_r_u_c_t _s_t_a_t_f_s _*_b_u_f); DDEESSCCRRIIPPTTIIOONN These functions provide a means to access a file given the file handle _f_h_p. As this method bypasses directory access restrictions, these calls are restricted to the superuser. ffhhooppeenn() opens the file referenced by _f_h_p for reading and/or writing as specified by the argument _f_l_a_g_s and returns the file descriptor to the calling process. The _f_l_a_g_s are specified by _o_r'ing together the flags used for the open(2) call. All said flags are valid except for O_CREAT. ffhhssttaatt() and ffhhssttaattffss() provide the functionality of the fstat(2) and fstatfs(2) calls except that they return information for the file referred to by _f_h_p rather than an open file. RREETTUURRNN VVAALLUUEESS Upon successful completion, ffhhooppeenn() returns the file descriptor for the opened file, while ffhhssttaatt() and ffhhssttaattffss() return 0. Otherwise, -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS In addition to the errors returned by open(2), fstat(2), and fstatfs(2) respectively, ffhhooppeenn(), ffhhssttaatt(), and ffhhssttaattffss() will return [EINVAL] Calling ffhhooppeenn() with O_CREAT set. [ESTALE] The file handle _f_h_p is no longer valid. SSEEEE AALLSSOO fstat(2), fstatfs(2), getfh(2), open(2) HHIISSTTOORRYY The ffhhooppeenn(), ffhhssttaatt(), and ffhhssttaattffss() functions first appeared in NetBSD 1.5. NNAAMMEE fflloocckk - apply or remove an advisory lock on an open file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t fflloocckk(_i_n_t _f_d, _i_n_t _o_p_e_r_a_t_i_o_n); DDEESSCCRRIIPPTTIIOONN fflloocckk() applies or removes an _a_d_v_i_s_o_r_y lock on the file associated with the file descriptor _f_d. The _o_p_e_r_a_t_i_o_n argument is one of: LOCK_SH Apply a shared lock. LOCK_EX Apply an exclusive lock. LOCK_UN Remove an existing lock. LOCK_SH and LOCK_EX may be combined with the optional LOCK_NB for nonblocking mode. Advisory locks allow cooperating processes to perform consistent operations on files, but do not guarantee consistency (i.e., processes may still access files without using advisory locks possibly resulting in inconsistencies). The locking mechanism allows two types of locks: _s_h_a_r_e_d locks and _e_x_c_l_u_s_i_v_e locks. At any time multiple shared locks may be applied to a file, but at no time are multiple exclusive, or both shared and exclusive, locks allowed simultaneously on a file. A shared lock may be _u_p_g_r_a_d_e_d to an exclusive lock, and vice versa, simply by specifying the appropriate lock type; this results in the previous lock being released and the new lock applied (possibly after other processes have gained and released the lock). Requesting a lock on an object that is already locked normally causes the caller to be blocked until the lock may be acquired. If _o_p_e_r_a_t_i_o_n is the bitwise OR of LOCK_NB and LOCK_SH or LOCK_EX, then this will not happen; instead the call will fail and the error EWOULDBLOCK will be returned. NNOOTTEESS Locks are on files, not file descriptors. That is, file descriptors duplicated through dup(2) or fork(2) do not result in multiple instances of a lock, but rather multiple references to a single lock. If a process holding a lock on a file forks and the child explicitly unlocks the file, the parent will lose its lock. Processes blocked awaiting a lock may be awakened by signals. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The fflloocckk() call fails if: [EWOULDBLOCK] The file is locked and the LOCK_NB option was specified. [EBADF] The argument _f_d is an invalid descriptor. [EINVAL] The argument _o_p_e_r_a_t_i_o_n has an invalid value. [EOPNOTSUPP] The referenced descriptor is not of the correct type. SSEEEE AALLSSOO close(2), dup(2), execve(2), fcntl(2), fork(2), open(2) HHIISSTTOORRYY The fflloocckk() system call first appeared in 4.1cBSD. NNAAMMEE ffoorrkk - create a new process SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t ffoorrkk(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN ffoorrkk() causes creation of a new process. The new process (child process) is an exact copy of the calling process (parent process) except for the following: ++oo The child process has a unique process ID, which also does not match any existing process group ID. ++oo The child process has a different parent process ID (i.e., the process ID of the parent process). ++oo The child process has a single thread. ++oo The child process has its own copy of the parent's descriptors. These descriptors reference the same underlying objects, so that, for instance, file pointers in file objects are shared between the child and the parent, so that an lseek(2) on a descriptor in the child process can affect a subsequent read(2) or write(2) by the parent. This descriptor copying is also used by the shell to establish standard input and output for newly created processes as well as to set up pipes. ++oo The child process has no fcntl(2)-style file locks. ++oo The child process' resource utilizations are set to 0; see getrusage(2). ++oo All interval timers are cleared; see setitimer(2). ++oo The child process' semaphore undo values are set to 0; see semop(2). ++oo The child process' pending signals set is empty. ++oo The child process has no memory locks; see mlock(2) and mlockall(2). In general, the child process should call _exit(2) rather than exit(3). Otherwise, any stdio buffers that exist both in the parent and child will be flushed twice. Similarly, _exit(2) should be used to prevent atexit(3) routines from being called twice (once in the parent and once in the child). RREETTUURRNN VVAALLUUEESS Upon successful completion, ffoorrkk() returns a value of 0 to the child process and returns the process ID of the child process to the parent process. Otherwise, a value of -1 is returned to the parent process, no child process is created, and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ffoorrkk() will fail and no child process will be created if: [EAGAIN] The system-imposed limits on the total number of processes or total number of threads under execution would be exceeded. These limits are configuration dependent. [EAGAIN] The limit RLIMIT_NPROC on the total number of processes under execution by the user ID would be exceeded. [ENOMEM] There is insufficient swap space for the new process. SSEEEE AALLSSOO execve(2), getrusage(2), wait(2) SSTTAANNDDAARRDDSS The ffoorrkk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ffoorrkk() system call first appeared in Version 1 AT&T UNIX. NNAAMMEE ppaatthhccoonnff, ffppaatthhccoonnff - get configurable pathname variables SSYYNNOOPPSSIISS ##iinncclluuddee <> _l_o_n_g ppaatthhccoonnff(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _n_a_m_e); _l_o_n_g ffppaatthhccoonnff(_i_n_t _f_d, _i_n_t _n_a_m_e); DDEESSCCRRIIPPTTIIOONN The ppaatthhccoonnff() and ffppaatthhccoonnff() functions provide a method for applications to determine the current value of a configurable system limit or option variable associated with a pathname or file descriptor. For ppaatthhccoonnff, the _p_a_t_h argument is the name of a file or directory. For ffppaatthhccoonnff, the _f_d argument is an open file descriptor. The _n_a_m_e argument specifies the system variable to be queried. Symbolic constants for each name value are found in the include file <_u_n_i_s_t_d_._h>. The available values are as follows: _PC_LINK_MAX The maximum file link count. _PC_MAX_CANON The maximum number of bytes in a terminal canonical input line. _PC_MAX_INPUT The maximum number of bytes for which space is available in a terminal input queue. _PC_NAME_MAX The maximum number of bytes in a file name. _PC_PATH_MAX The maximum number of bytes in a pathname. _PC_PIPE_BUF The maximum number of bytes which will be written atomically to a pipe. _PC_CHOWN_RESTRICTED Returns 1 if appropriate privileges are required for the chown(2) system call, otherwise 0. IEEE Std 1003.1-2001 (``POSIX.1'') requires appropriate privilege in all cases, but this behavior was optional in prior editions of the standard. _PC_NO_TRUNC Returns 1 if attempts to use pathname components longer than {NAME_MAX} will result in an [ENAMETOOLONG] error; otherwise, such components will be truncated to {NAME_MAX}. IEEE Std 1003.1-2001 (``POSIX.1'') requires the error in all cases, but this behavior was optional in prior editions of the standard, and some non-POSIX-compliant file systems do not support this behavior. _PC_VDISABLE Returns the terminal character disabling value. _PC_2_SYMLINKS Returns 1 if the filesystem supports the creation of symbolic links within the specified directory; the meaning of _PC_2_SYMLINKS is unspecified for non-directory files. _PC_ALLOC_SIZE_MIN Minimum number of bytes of storage allocated for any portion of a file. _PC_ASYNC_IO Returns 1 if asynchronous I/O is supported, otherwise 0. _PC_FILESIZEBITS Number of bits needed to represent the maximum file size. _PC_PRIO_IO Returns 1 if prioritized I/O is supported, otherwise 0. _PC_REC_INCR_XFER_SIZE Recommended increment for file transfer sizes between _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE. _PC_REC_MAX_XFER_SIZE Maximum recommended file transfer size. _PC_REC_MIN_XFER_SIZE Minimum recommended file transfer size. _PC_REC_XFER_ALIGN Recommended file transfer buffer alignment. _PC_SYMLINK_MAX Maximum number of bytes in a symbolic link. _PC_SYNC_IO Returns 1 if synchronized I/O is supported, otherwise 0. _PC_TIMESTAMP_RESOLUTION The resolution in nanoseconds of file timestamps. RREETTUURRNN VVAALLUUEESS If the call to ppaatthhccoonnff or ffppaatthhccoonnff is not successful, -1 is returned and _e_r_r_n_o is set appropriately. Otherwise, if the variable is associated with functionality that does not have a limit in the system, -1 is returned and _e_r_r_n_o is not modified. Otherwise, the current variable value is returned. EERRRROORRSS If any of the following conditions occur, the ppaatthhccoonnff and ffppaatthhccoonnff functions shall return -1 and set _e_r_r_n_o to the corresponding value. [EINVAL] The value of the _n_a_m_e argument is invalid. [EINVAL] The implementation does not support an association of the variable name with the associated file. [EIO] An I/O error occurred while reading from the file system. ppaatthhccoonnff() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters (but see _PC_NO_TRUNC above), or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _p_a_t_h points outside the process's allocated address space. ffppaatthhccoonnff() will fail if: [EBADF] _f_d is not a valid open file descriptor. SSEEEE AALLSSOO sysconf(3), sysctl(3) SSTTAANNDDAARRDDSS The ppaatthhccoonnff and ffppaatthhccoonnff functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ppaatthhccoonnff and ffppaatthhccoonnff functions first appeared in 4.4BSD. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaattffss, ffssttaattffss - get file system statistics SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ssttaattffss(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t_f_s _*_b_u_f); _i_n_t ffssttaattffss(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t_f_s _*_b_u_f); DDEESSCCRRIIPPTTIIOONN ssttaattffss() returns information about a mounted file system. _p_a_t_h is the path name of any file within the mounted file system. _b_u_f is a pointer to a ssttaattffss structure defined as follows: typedef struct { int32_t val[2]; } fsid_t; #define MFSNAMELEN 16 /* length of fs type name, including nul */ #define MNAMELEN 90 /* length of buffer for returned name */ struct statfs { u_int32_t f_flags; /* copy of mount flags */ u_int32_t f_bsize; /* file system block size */ u_int32_t f_iosize; /* optimal transfer block size */ /* unit is f_bsize */ u_int64_t f_blocks; /* total data blocks in file system */ u_int64_t f_bfree; /* free blocks in fs */ int64_t f_bavail; /* free blocks avail to non-superuser */ u_int64_t f_files; /* total file nodes in file system */ u_int64_t f_ffree; /* free file nodes in fs */ int64_t f_favail; /* free file nodes avail to non-root */ u_int64_t f_syncwrites; /* count of sync writes since mount */ u_int64_t f_syncreads; /* count of sync reads since mount */ u_int64_t f_asyncwrites; /* count of async writes since mount */ u_int64_t f_asyncreads; /* count of async reads since mount */ fsid_t f_fsid; /* file system id */ u_int32_t f_namemax; /* maximum filename length */ uid_t f_owner; /* user that mounted the file system */ u_int64_t f_ctime; /* last mount [-u] time */ char f_fstypename[MFSNAMELEN]; /* fs type name */ char f_mntonname[MNAMELEN]; /* directory on which mounted */ char f_mntfromname[MNAMELEN]; /* mounted file system */ char f_mntfromspec[MNAMELEN]; /* special for mount request */ union mount_info mount_info; /* per-filesystem mount options */ }; ffssttaattffss() returns the same information about an open file referenced by descriptor _f_d. Note that _f___f_s_i_d will be empty unless the user is the superuser. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaattffss() fails if one or more of the following are true: [ENOTDIR] A component of the path prefix of _p_a_t_h is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The file referred to by _p_a_t_h does not exist. [EACCES] Search permission is denied for a component of the path prefix of _p_a_t_h. [ELOOP] Too many symbolic links were encountered in translating _p_a_t_h. [EFAULT] _b_u_f or _p_a_t_h points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. ffssttaattffss() fails if one or more of the following are true: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _b_u_f points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO df(1), getfsstat(2), mount(2), stat(2) HHIISSTTOORRYY The ssttaattffss() function first appeared in 4.4BSD. NNAAMMEE ffssyynncc, ffddaattaassyynncc - synchronize a file's in-core state with that on disk SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ffssyynncc(_i_n_t _f_d); _i_n_t ffddaattaassyynncc(_i_n_t _f_d); DDEESSCCRRIIPPTTIIOONN The ffssyynncc() function causes all modified data and attributes of _f_d to be moved to a permanent storage device. This normally results in all in- core modified copies of buffers for the associated file to be written to a disk. The ffddaattaassyynncc() function is similar to ffssyynncc() except that it only guarantees modified data (and metadata necessary to read that data) is committed to storage. Other file modifications may be left unsynchronized. ffssyynncc() and ffddaattaassyynncc() should be used by programs that require a file to be in a known state, for example, in building a simple transaction facility. RREETTUURRNN VVAALLUUEESS The ffssyynncc() and ffddaattaassyynncc() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The ffssyynncc() and ffddaattaassyynncc() functions fail if: [EBADF] _f_d is not a valid descriptor. [EINVAL] _f_d does not refer to a file which can be synchronized. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO sync(2), sync(8) SSTTAANNDDAARRDDSS The ffssyynncc() and ffddaattaassyynncc() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ffssyynncc() system call first appeared in 4.1cBSD, and the ffddaattaassyynncc() function has been available since OpenBSD 5.4. BBUUGGSS The ffddaattaassyynncc() function is currently a wrapper around ffssyynncc(), so it synchronizes more state than necessary. NNAAMMEE ttrruunnccaattee, ffttrruunnccaattee - truncate or extend a file to a specified length SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ttrruunnccaattee(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _o_f_f___t _l_e_n_g_t_h); _i_n_t ffttrruunnccaattee(_i_n_t _f_d, _o_f_f___t _l_e_n_g_t_h); DDEESSCCRRIIPPTTIIOONN ttrruunnccaattee() causes the file named by _p_a_t_h or referenced by _f_d to be truncated or extended to _l_e_n_g_t_h bytes in size. If the file was larger than this size, the extra data is lost. If the file was smaller than this size, it will be extended as if by writing bytes with the value zero. With ffttrruunnccaattee(), the file must be open for writing. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ttrruunnccaattee() and ffttrruunnccaattee() will succeed unless: [EINVAL] The _l_e_n_g_t_h is a negative value. [EIO] An I/O error occurred updating the inode. In addition, ttrruunnccaattee() may return the following errors: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] The named file is not writable by the user. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EISDIR] The named file is a directory. [EROFS] The named file resides on a read-only file system. [ETXTBSY] The file is a pure procedure (shared text) file that is being executed. [EFAULT] _p_a_t_h points outside the process's allocated address space. ffttrruunnccaattee() may return the following errors: [EBADF] The _f_d is not a valid descriptor. [EINVAL] The _f_d references a socket, not a file. [EINVAL] The _f_d is not open for writing. SSEEEE AALLSSOO open(2) SSTTAANNDDAARRDDSS The ttrruunnccaattee() and ffttrruunnccaattee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ttrruunnccaattee() and ffttrruunnccaattee() system calls first appeared in 4.1cBSD. BBUUGGSS These calls should be generalized to allow ranges of bytes in a file to be discarded. Use of ttrruunnccaattee() to extend a file is not portable. NNAAMMEE uuttiimmeess, ffuuttiimmeess, uuttiimmeennssaatt, ffuuttiimmeennss - set file access and modification times SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t uuttiimmeess(_c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_s); _i_n_t ffuuttiimmeess(_i_n_t _f_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_s); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t uuttiimmeennssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _t_i_m_e_s_[_2_], _i_n_t _f_l_a_g); _i_n_t ffuuttiimmeennss(_i_n_t _f_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _t_i_m_e_s_[_2_]); DDEESSCCRRIIPPTTIIOONN The access and modification times of the file named by _p_a_t_h or referenced by _f_d are changed as specified by the argument _t_i_m_e_s. If _t_i_m_e_s is NULL, the access and modification times are set to the current time. The caller must be the owner of the file, have permission to write the file, or be the superuser. If _t_i_m_e_s is non-null, it is assumed to point to an array of two timeval structures. The access time is set to the value of the first element, and the modification time is set to the value of the second element. The caller must be the owner of the file or be the superuser. In either case, the inode-change-time of the file is set to the current time. The uuttiimmeennssaatt() and ffuuttiimmeennss() are equivalent to uuttiimmeess() and ffuuttiimmeess(), respectively, with the following differences. Both uuttiimmeennssaatt() and ffuuttiimmeennss() take two timespec values instead of two timeval values. Further, either of the _t_v___n_s_e_c fields can be set to one of the following special values defined in <_s_y_s_/_s_t_a_t_._h>: UTIME_NOW Set the respective timestamp to the greatest value supported that is not greater than the current time. UTIME_OMIT Do not change the respective timestamp. Additionally, if the _p_a_t_h argument to uuttiimmeennssaatt() specifies a relative path, the file whose timestamps are changed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If uuttiimmeennssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the timestamps of the symbolic link are changed. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS uuttiimmeess() and uuttiimmeennssaatt() will fail if: [EACCES] Search permission is denied for a component of the path prefix; or the _t_i_m_e_s argument is NULL and the effective user ID of the process does not match the owner of the file, and is not the superuser, and write access is denied. [EFAULT] _f_i_l_e or _t_i_m_e_s points outside the process's allocated address space. [EIO] An I/O error occurred while reading or writing the affected inode. [ELOOP] Too many symbolic links were encountered in translating the pathname. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [ENOTDIR] A component of the path prefix is not a directory. [EPERM] The _t_i_m_e_s argument is not NULL and the calling process's effective user ID does not match the owner of the file and is not the superuser. [EROFS] The file system containing the file is mounted read- only. Additionally, uuttiimmeennssaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _f_i_l_e argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _f_i_l_e argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _f_i_l_e argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffuuttiimmeess() and ffuuttiimmeennss() will fail if: [EBADF] _f_d does not refer to a valid descriptor. [EACCES] The _t_i_m_e_s argument is NULL and the effective user ID of the process does not match the owner of the file, and is not the superuser, and write access is denied. [EFAULT] _t_i_m_e_s points outside the process's allocated address space. [EIO] An I/O error occurred while reading or writing the affected inode. [EPERM] The _t_i_m_e_s argument is not NULL and the calling process's effective user ID does not match the owner of the file and is not the superuser. [EROFS] The file system containing the file is mounted read- only. SSEEEE AALLSSOO clock_gettime(2), stat(2), utime(3) SSTTAANNDDAARRDDSS The uuttiimmeess(), uuttiimmeennssaatt(), and ffuuttiimmeennss() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The predecessors of uuttiimmeess() were ssmmddaattee() in Version 1 AT&T UNIX, mmddaattee() in Version 3 AT&T UNIX, and uuttiimmee() in Version 7 AT&T UNIX; the latter first supported the concept of an access time in addition to the modification time. The uuttiimmeess() function call appeared in 4.2BSD. The ffuuttiimmeess() function call appeared in NetBSD 1.2. The uuttiimmeennssaatt() and ffuuttiimmeennss() function calls appeared in OpenBSD 5.0. CCAAVVEEAATTSS IEEE Std 1003.1-2008 (``POSIX.1'') specifies that uuttiimmeennssaatt() and ffuuttiimmeennss() shall mark the last file status change timestamp (i.e. _s_t___c_t_i_m) for update upon successful completion. However, currently some filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the modification timestamp argument. NNAAMMEE uuttiimmeess, ffuuttiimmeess, uuttiimmeennssaatt, ffuuttiimmeennss - set file access and modification times SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t uuttiimmeess(_c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_s); _i_n_t ffuuttiimmeess(_i_n_t _f_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_s); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t uuttiimmeennssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _t_i_m_e_s_[_2_], _i_n_t _f_l_a_g); _i_n_t ffuuttiimmeennss(_i_n_t _f_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _t_i_m_e_s_[_2_]); DDEESSCCRRIIPPTTIIOONN The access and modification times of the file named by _p_a_t_h or referenced by _f_d are changed as specified by the argument _t_i_m_e_s. If _t_i_m_e_s is NULL, the access and modification times are set to the current time. The caller must be the owner of the file, have permission to write the file, or be the superuser. If _t_i_m_e_s is non-null, it is assumed to point to an array of two timeval structures. The access time is set to the value of the first element, and the modification time is set to the value of the second element. The caller must be the owner of the file or be the superuser. In either case, the inode-change-time of the file is set to the current time. The uuttiimmeennssaatt() and ffuuttiimmeennss() are equivalent to uuttiimmeess() and ffuuttiimmeess(), respectively, with the following differences. Both uuttiimmeennssaatt() and ffuuttiimmeennss() take two timespec values instead of two timeval values. Further, either of the _t_v___n_s_e_c fields can be set to one of the following special values defined in <_s_y_s_/_s_t_a_t_._h>: UTIME_NOW Set the respective timestamp to the greatest value supported that is not greater than the current time. UTIME_OMIT Do not change the respective timestamp. Additionally, if the _p_a_t_h argument to uuttiimmeennssaatt() specifies a relative path, the file whose timestamps are changed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If uuttiimmeennssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the timestamps of the symbolic link are changed. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS uuttiimmeess() and uuttiimmeennssaatt() will fail if: [EACCES] Search permission is denied for a component of the path prefix; or the _t_i_m_e_s argument is NULL and the effective user ID of the process does not match the owner of the file, and is not the superuser, and write access is denied. [EFAULT] _f_i_l_e or _t_i_m_e_s points outside the process's allocated address space. [EIO] An I/O error occurred while reading or writing the affected inode. [ELOOP] Too many symbolic links were encountered in translating the pathname. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [ENOTDIR] A component of the path prefix is not a directory. [EPERM] The _t_i_m_e_s argument is not NULL and the calling process's effective user ID does not match the owner of the file and is not the superuser. [EROFS] The file system containing the file is mounted read- only. Additionally, uuttiimmeennssaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _f_i_l_e argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _f_i_l_e argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _f_i_l_e argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffuuttiimmeess() and ffuuttiimmeennss() will fail if: [EBADF] _f_d does not refer to a valid descriptor. [EACCES] The _t_i_m_e_s argument is NULL and the effective user ID of the process does not match the owner of the file, and is not the superuser, and write access is denied. [EFAULT] _t_i_m_e_s points outside the process's allocated address space. [EIO] An I/O error occurred while reading or writing the affected inode. [EPERM] The _t_i_m_e_s argument is not NULL and the calling process's effective user ID does not match the owner of the file and is not the superuser. [EROFS] The file system containing the file is mounted read- only. SSEEEE AALLSSOO clock_gettime(2), stat(2), utime(3) SSTTAANNDDAARRDDSS The uuttiimmeess(), uuttiimmeennssaatt(), and ffuuttiimmeennss() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The predecessors of uuttiimmeess() were ssmmddaattee() in Version 1 AT&T UNIX, mmddaattee() in Version 3 AT&T UNIX, and uuttiimmee() in Version 7 AT&T UNIX; the latter first supported the concept of an access time in addition to the modification time. The uuttiimmeess() function call appeared in 4.2BSD. The ffuuttiimmeess() function call appeared in NetBSD 1.2. The uuttiimmeennssaatt() and ffuuttiimmeennss() function calls appeared in OpenBSD 5.0. CCAAVVEEAATTSS IEEE Std 1003.1-2008 (``POSIX.1'') specifies that uuttiimmeennssaatt() and ffuuttiimmeennss() shall mark the last file status change timestamp (i.e. _s_t___c_t_i_m) for update upon successful completion. However, currently some filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the modification timestamp argument. NNAAMMEE ggeettddeennttss - get directory entries in a filesystem independent format SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettddeennttss(_i_n_t _f_d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); DDEESSCCRRIIPPTTIIOONN ggeettddeennttss() reads directory entries from the directory referenced by the file descriptor _f_d into the buffer pointed to by _b_u_f, in a filesystem independent format. Up to _n_b_y_t_e_s of data will be transferred. _n_b_y_t_e_s must be greater than or equal to the block size associated with the file (see stat(2)). Some filesystems may not support ggeettddeennttss() with buffers smaller than this size. The data in the buffer is a series of _d_i_r_e_n_t structures each containing at least the following entries: ino_t d_fileno; off_t d_off; u_int16_t d_reclen; u_int8_t d_type; u_int8_t d_namlen; char d_name[MAXNAMLEN + 1]; /* see below */ The _d___f_i_l_e_n_o entry is a number which is unique for each distinct file in the filesystem. Files that are linked by hard links (see link(2)) have the same _d___f_i_l_e_n_o. The _d___o_f_f entry is the file offset of the next entry. The _d___r_e_c_l_e_n entry is the length, in bytes, of the directory record. The _d___t_y_p_e is the type of file, where the following are possible types: DT_UNKNOWN, DT_FIFO, DT_CHR, DT_DIR, DT_BLK, DT_REG, DT_LNK, and DT_SOCK. The _d___n_a_m_l_e_n entry specifies the length of the file name excluding the NUL byte. Thus the actual size of _d___n_a_m_e may vary from 1 to MAXNAMLEN + 1. The _d___n_a_m_e entry contains a NUL-terminated file name. Entries may be separated by extra space. The _d___r_e_c_l_e_n entry may be used as an offset from the start of a _d_i_r_e_n_t structure to the next structure, if any. Invalid entries with _d___f_i_l_e_n_o set to 0 may be returned among regular entries. The actual number of bytes transferred is returned. The current position pointer associated with _f_d is set to point to the next block of entries. The pointer may not advance by the number of bytes returned by ggeettddeennttss(). The current position pointer may be set and retrieved by lseek(2). The current position pointer should only be set to a value returned by lseek(2), the value of _d___o_f_f from an entry, or zero. RREETTUURRNN VVAALLUUEESS If successful, the number of bytes actually transferred is returned. A value of zero is returned when the end of the directory has been reached. Otherwise, -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettddeennttss() will fail if: [EBADF] _f_d is not a valid file descriptor open for reading. [EFAULT] Part of _b_u_f points outside the process's allocated address space. [EINVAL] The file referenced by _f_d is not a directory, or _n_b_y_t_e_s is too small for returning a directory entry or block of entries, or the current position pointer is invalid. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO lseek(2), open(2), opendir(3), dirent(5) SSTTAANNDDAARRDDSS The ggeettddeennttss() call is not a portable interface and should not be used directly by applications. Use readdir(3) instead. HHIISSTTOORRYY The ggeettddiirreennttrriieess() function first appeared in 4.4BSD. In OpenBSD 5.5 the _d___o_f_f entry was added to _s_t_r_u_c_t _d_i_r_e_n_t and ggeettddiirreennttrriieess() was replaced with ggeettddeennttss(). NNAAMMEE ggeettddttaabblleeccoouunntt - get descriptor table count SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettddttaabblleeccoouunntt(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN kkqquueeuuee returns the number of file descriptors the process currently has open. SSEEEE AALLSSOO getrlimit(2), getdtablesize(3) HHIISSTTOORRYY The kkqquueeuuee function appeared in OpenBSD 5.2. NNAAMMEE ggeettggiidd, ggeetteeggiidd - get group process identification SSYYNNOOPPSSIISS ##iinncclluuddee <> _g_i_d___t ggeettggiidd(_v_o_i_d); _g_i_d___t ggeetteeggiidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The ggeettggiidd() function returns the real group ID of the calling process and the ggeetteeggiidd() function returns the effective group ID of the calling process. The real group ID is specified at login time. The real group ID is the group of the user who invoked the program. As the effective group ID gives the process additional permissions during the execution of ``_s_e_t_-_g_r_o_u_p_-_I_D'' mode processes, ggeettggiidd() is used to determine the real group ID of the calling process. EERRRROORRSS The ggeettggiidd() and ggeetteeggiidd() functions are always successful, and no return value is reserved to indicate an error. SSEEEE AALLSSOO getgroups(2), getresgid(2), getuid(2), setgid(2), setregid(2) SSTTAANNDDAARRDDSS The ggeettggiidd() and ggeetteeggiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettggiidd() system call first appeared in Version 4 AT&T UNIX, and ggeetteeggiidd() in Version 7 AT&T UNIX. NNAAMMEE ggeetteennttrrooppyy - get entropy SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeetteennttrrooppyy(_v_o_i_d _*_b_u_f, _s_i_z_e___t _b_u_f_l_e_n); DDEESSCCRRIIPPTTIIOONN ggeetteennttrrooppyy() fills a buffer with high-quality entropy, which can be used as input for process-context pseudorandom generators like arc4random(3). The maximum buffer size permitted is 256 bytes. If _b_u_f_l_e_n exceeds this, an error of EIO will be indicated. ggeetteennttrrooppyy() is not intended for regular code; please use the arc4random(3) family of functions instead. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeetteennttrrooppyy() will succeed unless: [EFAULT] The _b_u_f parameter points to an invalid address. [EIO] Too many bytes requested, or some other fatal error occurred. SSEEEE AALLSSOO arc4random(3) HHIISSTTOORRYY The ggeetteennttrrooppyy() function appeared in OpenBSD 5.6. NNAAMMEE ggeettuuiidd, ggeetteeuuiidd - get user identification SSYYNNOOPPSSIISS ##iinncclluuddee <> _u_i_d___t ggeettuuiidd(_v_o_i_d); _u_i_d___t ggeetteeuuiidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The ggeettuuiidd() function returns the real user ID of the calling process. The ggeetteeuuiidd() function returns the effective user ID of the calling process. The real user ID is that of the user who has invoked the program. As the effective user ID gives the process additional permissions during execution of ``_s_e_t_-_u_s_e_r_-_I_D'' mode processes, ggeettuuiidd() is used to determine the real user ID of the calling process. EERRRROORRSS The ggeettuuiidd() and ggeetteeuuiidd() functions are always successful, and no return value is reserved to indicate an error. SSEEEE AALLSSOO getgid(2), getresuid(2), setreuid(2), setuid(2) SSTTAANNDDAARRDDSS The ggeettuuiidd() and ggeetteeuuiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettuuiidd() system call first appeared in Version 1 AT&T UNIX, and ggeetteeuuiidd() in Version 7 AT&T UNIX. NNAAMMEE ggeettffhh - get file handle SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ggeettffhh(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _f_h_a_n_d_l_e___t _*_f_h_p); DDEESSCCRRIIPPTTIIOONN ggeettffhh() returns a file handle for the specified file or directory _p_a_t_h in the file handle pointed to by _f_h_p. This system call is restricted to the superuser. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettffhh() fails if one or more of the following are true: [ENOTDIR] A component of the path prefix of _p_a_t_h is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The file referred to by _p_a_t_h does not exist. [EACCES] Search permission is denied for a component of the path prefix of _p_a_t_h. [ELOOP] Too many symbolic links were encountered in translating _p_a_t_h. [EPERM] The effective user ID is not the superuser. [EFAULT] _f_h_p or _p_a_t_h points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. [EINVAL] A portion of _p_a_t_h refers to a remote file system. [EOPNOTSUPP] A portion of _p_a_t_h refers to a remote file system. SSEEEE AALLSSOO fhstat(2) HHIISSTTOORRYY The ggeettffhh() function first appeared in 4.4BSD. NNAAMMEE ggeettffssssttaatt - get list of all mounted file systems SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ggeettffssssttaatt(_s_t_r_u_c_t _s_t_a_t_f_s _*_b_u_f, _s_i_z_e___t _b_u_f_s_i_z_e, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN ggeettffssssttaatt() returns information about all mounted file systems. _b_u_f is a pointer to an array of statfs(2) structures defined as follows: typedef struct { int32_t val[2]; } fsid_t; #define MFSNAMELEN 16 /* length of fs type name, including nul */ #define MNAMELEN 90 /* length of buffer for returned name */ struct statfs { u_int32_t f_flags; /* copy of mount flags */ u_int32_t f_bsize; /* file system block size */ u_int32_t f_iosize; /* optimal transfer block size */ /* unit is f_bsize */ u_int64_t f_blocks; /* total data blocks in file system */ u_int64_t f_bfree; /* free blocks in fs */ int64_t f_bavail; /* free blocks avail to non-superuser */ u_int64_t f_files; /* total file nodes in file system */ u_int64_t f_ffree; /* free file nodes in fs */ int64_t f_favail; /* free file nodes avail to non-root */ u_int64_t f_syncwrites; /* count of sync writes since mount */ u_int64_t f_syncreads; /* count of sync reads since mount */ u_int64_t f_asyncwrites; /* count of async writes since mount */ u_int64_t f_asyncreads; /* count of async reads since mount */ fsid_t f_fsid; /* file system id */ u_int32_t f_namemax; /* maximum filename length */ uid_t f_owner; /* user that mounted the file system */ u_int64_t f_ctime; /* last mount [-u] time */ char f_fstypename[MFSNAMELEN]; /* fs type name */ char f_mntonname[MNAMELEN]; /* directory on which mounted */ char f_mntfromname[MNAMELEN]; /* mounted file system */ char f_mntfromspec[MNAMELEN]; /* special for mount request */ union mount_info mount_info; /* per-filesystem mount options */ }; The buffer is filled with an array of _s_t_a_t_f_s structures, one for each mounted file system up to the size specified by _b_u_f_s_i_z_e. If _b_u_f is NULL, ggeettffssssttaatt() returns just the number of mounted file systems. Normally _f_l_a_g_s should be specified as MNT_WAIT. If _f_l_a_g_s is set to MNT_NOWAIT, ggeettffssssttaatt() will return the information it has available without requesting an update from each file system. Thus, some of the information will be out of date, but ggeettffssssttaatt() will not block waiting for information from a file system that is unable to respond. If no flags are provided, MNT_WAIT is assumed. Note that _f___f_s_i_d will be empty unless the user is the superuser. RREETTUURRNN VVAALLUUEESS Upon successful completion, the number of _s_t_a_t_f_s structures is returned. Otherwise, -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettffssssttaatt() fails if one or more of the following are true: [EFAULT] _b_u_f points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO statfs(2), fstab(5), mount(8) HHIISSTTOORRYY The ggeettffssssttaatt() function first appeared in 4.4BSD. NNAAMMEE ggeettggiidd, ggeetteeggiidd - get group process identification SSYYNNOOPPSSIISS ##iinncclluuddee <> _g_i_d___t ggeettggiidd(_v_o_i_d); _g_i_d___t ggeetteeggiidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The ggeettggiidd() function returns the real group ID of the calling process and the ggeetteeggiidd() function returns the effective group ID of the calling process. The real group ID is specified at login time. The real group ID is the group of the user who invoked the program. As the effective group ID gives the process additional permissions during the execution of ``_s_e_t_-_g_r_o_u_p_-_I_D'' mode processes, ggeettggiidd() is used to determine the real group ID of the calling process. EERRRROORRSS The ggeettggiidd() and ggeetteeggiidd() functions are always successful, and no return value is reserved to indicate an error. SSEEEE AALLSSOO getgroups(2), getresgid(2), getuid(2), setgid(2), setregid(2) SSTTAANNDDAARRDDSS The ggeettggiidd() and ggeetteeggiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettggiidd() system call first appeared in Version 4 AT&T UNIX, and ggeetteeggiidd() in Version 7 AT&T UNIX. NNAAMMEE ggeettggrroouuppss - get group access list SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettggrroouuppss(_i_n_t _g_i_d_s_e_t_l_e_n, _g_i_d___t _*_g_i_d_s_e_t); DDEESSCCRRIIPPTTIIOONN ggeettggrroouuppss() gets the current group access list of the current user process and stores it in the array _g_i_d_s_e_t. The parameter _g_i_d_s_e_t_l_e_n indicates the number of entries that may be placed in _g_i_d_s_e_t. ggeettggrroouuppss() returns the actual number of groups returned in _g_i_d_s_e_t. No more than {NGROUPS_MAX} will ever be returned. If _g_i_d_s_e_t_l_e_n is 0, ggeettggrroouuppss() returns the number of groups without modifying the _g_i_d_s_e_t array. RREETTUURRNN VVAALLUUEESS A successful call returns the number of groups in the group set. A value of -1 indicates that an error occurred, and the error code is stored in the global variable _e_r_r_n_o. EERRRROORRSS The possible errors for ggeettggrroouuppss() are: [EINVAL] The argument _g_i_d_s_e_t_l_e_n is smaller than the number of groups in the group set. [EFAULT] The argument _g_i_d_s_e_t specifies an invalid address. SSEEEE AALLSSOO getgid(2), setgid(2), setgroups(2), initgroups(3) SSTTAANNDDAARRDDSS The ggeettggrroouuppss() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettggrroouuppss() system call first appeared in 4.1cBSD. NNAAMMEE ggeettiittiimmeerr, sseettiittiimmeerr - get/set value of interval timer SSYYNNOOPPSSIISS ##iinncclluuddee <> ##ddeeffiinnee IITTIIMMEERR__RREEAALL 00 ##ddeeffiinnee IITTIIMMEERR__VVIIRRTTUUAALL 11 ##ddeeffiinnee IITTIIMMEERR__PPRROOFF 22 _i_n_t ggeettiittiimmeerr(_i_n_t _w_h_i_c_h, _s_t_r_u_c_t _i_t_i_m_e_r_v_a_l _*_v_a_l_u_e); _i_n_t sseettiittiimmeerr(_i_n_t _w_h_i_c_h, _c_o_n_s_t _s_t_r_u_c_t _i_t_i_m_e_r_v_a_l _*_v_a_l_u_e, _s_t_r_u_c_t _i_t_i_m_e_r_v_a_l _*_o_v_a_l_u_e); _v_o_i_d ttiimmeerrcclleeaarr(_s_t_r_u_c_t _t_i_m_e_v_a_l _*); _i_n_t ttiimmeerriisssseett(_s_t_r_u_c_t _t_i_m_e_v_a_l _*); _i_n_t ttiimmeerrccmmpp(_s_t_r_u_c_t _t_i_m_e_v_a_l _*_a, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_b, _C_M_P); _v_o_i_d ttiimmeerrssuubb(_s_t_r_u_c_t _t_i_m_e_v_a_l _*_a, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_b, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_r_e_s); _v_o_i_d ttiimmeerraadddd(_s_t_r_u_c_t _t_i_m_e_v_a_l _*_a, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_b, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_r_e_s); DDEESSCCRRIIPPTTIIOONN The system provides each process with three interval timers, defined in <_s_y_s_/_t_i_m_e_._h>. The ggeettiittiimmeerr() call returns the current value for the timer specified in _w_h_i_c_h in the structure at _v_a_l_u_e. The sseettiittiimmeerr() call sets a timer to the specified _v_a_l_u_e (returning the previous value of the timer if _o_v_a_l_u_e is non-null). A timer value is defined by the _i_t_i_m_e_r_v_a_l structure: struct itimerval { struct timeval it_interval; /* timer interval */ struct timeval it_value; /* current value */ }; If _i_t___v_a_l_u_e is non-zero, it indicates the time to the next timer expiration. If _i_t___i_n_t_e_r_v_a_l is non-zero, it specifies a value to be used in reloading _i_t___v_a_l_u_e when the timer expires. Setting _i_t___v_a_l_u_e to 0 disables a timer. Setting _i_t___i_n_t_e_r_v_a_l to 0 causes a timer to be disabled after its next expiration (assuming _i_t___v_a_l_u_e is non-zero). Time values smaller than the resolution of the system clock are rounded up to this resolution (typically 10 milliseconds). The ITIMER_REAL timer decrements in real time. A SIGALRM signal is delivered when this timer expires. The ITIMER_VIRTUAL timer decrements in process virtual time. It runs only when the process is executing. A SIGVTALRM signal is delivered when it expires. The ITIMER_PROF timer decrements both in process virtual time and when the system is running on behalf of the process. It is designed to be used by interpreters in statistically profiling the execution of interpreted programs. Each time the ITIMER_PROF timer expires, the SIGPROF signal is delivered. Because this signal may interrupt in- progress system calls, programs using this timer must be prepared to restart interrupted system calls. The remaining five functions are in fact macros for manipulating time values, defined in <_s_y_s_/_t_i_m_e_._h>. ttiimmeerrcclleeaarr(_a) sets the time value in _a to zero. ttiimmeerriisssseett(_a) tests if the time value in _a is non-zero. ttiimmeerrccmmpp(_a, _b, _C_M_P) compares two time values in the form _a CMP _b, where _C_M_P is <, <=, ==, !=, >=, or > . ttiimmeerrssuubb(_a, _b, _r_e_s) subtracts _a - _b and stores the result in _r_e_s. ttiimmeerraadddd(_a, _b, _r_e_s) adds two timers and stores the result in _r_e_s. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettiittiimmeerr() and sseettiittiimmeerr() will fail if: [EFAULT] The _v_a_l_u_e parameter specified a bad address. [EINVAL] An unrecognized value for _w_h_i_c_h was specified. In addition, sseettiittiimmeerr() may return the following error: [EINVAL] _v_a_l_u_e or _o_v_a_l_u_e specified a time that was too large to be handled. SSEEEE AALLSSOO clock_gettime(2), gettimeofday(2), poll(2), select(2), sigaction(2) SSTTAANNDDAARRDDSS The ggeettiittiimmeerr() and sseettiittiimmeerr() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettiittiimmeerr() and sseettiittiimmeerr() system calls first appeared in 4.1cBSD. NNAAMMEE ggeettllooggiinn, ggeettllooggiinn__rr, sseettllooggiinn - get/set login name SSYYNNOOPPSSIISS ##iinncclluuddee <> _c_h_a_r _* ggeettllooggiinn(_v_o_i_d); _i_n_t ggeettllooggiinn__rr(_c_h_a_r _*_n_a_m_e, _s_i_z_e___t _n_a_m_e_l_e_n); _i_n_t sseettllooggiinn(_c_o_n_s_t _c_h_a_r _*_n_a_m_e); DDEESSCCRRIIPPTTIIOONN The ggeettllooggiinn() routine returns the login name of the user associated with the current session, as previously set by sseettllooggiinn(). The name is normally associated with a login shell at the time a session is created, and is inherited by all processes descended from the login shell. (This is true even if some of those processes assume another user ID, for example when su(1) is used.) The ggeettllooggiinn__rr() routine is a reentrant version of ggeettllooggiinn(). It is functionally identical to ggeettllooggiinn() except that the caller must provide a buffer, _n_a_m_e, in which to store the user's login name and a corresponding length parameter, _n_a_m_e_l_e_n, that specifies the size of the buffer. The buffer should be large enough to store the login name and a trailing NUL (typically LOGIN_NAME_MAX bytes). sseettllooggiinn() sets the login name of the user associated with the current session to _n_a_m_e. This call is restricted to the superuser, and is normally used only when a new session is being created on behalf of the named user (for example, at login time, or when a remote shell is invoked). _N_O_T_E: There is only one login name per session. It is _C_R_I_T_I_C_A_L_L_Y important to ensure that sseettllooggiinn() is only ever called after the process has taken adequate steps to ensure that it is detached from its parent's session. The _O_N_L_Y way to do this is via the sseettssiidd() function. The ddaaeemmoonn() function calls sseettssiidd() which is an ideal way of detaching from a controlling terminal and forking into the background. In particular, neither iiooccttll(_t_t_y_f_d, _T_I_O_C_N_O_T_T_Y, _._._.) nor sseettppggrrpp(_._._.) is sufficient to create a new session. Once a parent process has called sseettssiidd(), it is acceptable for some child of that process to then call sseettllooggiinn(), even though it is not the session leader. Beware, however, that _A_L_L processes in the session will change their login name at the same time, even the parent. This is different from traditional UNIX privilege inheritance and as such can be counter-intuitive. Since the sseettllooggiinn() routine is restricted to the super-user, it is assumed that (like all other privileged programs) the programmer has taken adequate precautions to prevent security violations. RREETTUURRNN VVAALLUUEESS If a call to ggeettllooggiinn() succeeds, it returns a pointer to a NUL- terminated string in a static buffer. If the name has not been set, it returns NULL. If a call to ggeettllooggiinn__rr() succeeds, a value of 0 is returned, else the error number is returned. If a call to sseettllooggiinn() succeeds, a value of 0 is returned. If sseettllooggiinn() fails, a value of -1 is returned and an error code is placed in the global location _e_r_r_n_o. EERRRROORRSS ggeettllooggiinn__rr() and sseettllooggiinn() will succeed unless: [EFAULT] The _n_a_m_e parameter points to an invalid address. In addition, ggeettllooggiinn__rr() may return the following error: [ERANGE] The value of _n_a_m_e_l_e_n is not large enough to store the user's login name and a trailing NUL. sseettllooggiinn() may return the following errors: [EINVAL] The _n_a_m_e parameter pointed to a string that was too long. Login names are limited to LOGIN_NAME_MAX-1 characters, currently 31. [EPERM] The caller tried to set the login name and was not the superuser. SSEEEE AALLSSOO setsid(2) SSTTAANNDDAARRDDSS The ggeettllooggiinn() and ggeettllooggiinn__rr() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettllooggiinn() function first appeared in 4.2BSD. BBUUGGSS In earlier versions of the system, ggeettllooggiinn() failed unless the process was associated with a login terminal. The current implementation (using sseettllooggiinn()) allows getlogin to succeed even when the process has no controlling terminal. In earlier versions of the system, the value returned by ggeettllooggiinn() could not be trusted without checking the user ID. Portable programs should probably still make this check. NNAAMMEE ggeettllooggiinn, ggeettllooggiinn__rr, sseettllooggiinn - get/set login name SSYYNNOOPPSSIISS ##iinncclluuddee <> _c_h_a_r _* ggeettllooggiinn(_v_o_i_d); _i_n_t ggeettllooggiinn__rr(_c_h_a_r _*_n_a_m_e, _s_i_z_e___t _n_a_m_e_l_e_n); _i_n_t sseettllooggiinn(_c_o_n_s_t _c_h_a_r _*_n_a_m_e); DDEESSCCRRIIPPTTIIOONN The ggeettllooggiinn() routine returns the login name of the user associated with the current session, as previously set by sseettllooggiinn(). The name is normally associated with a login shell at the time a session is created, and is inherited by all processes descended from the login shell. (This is true even if some of those processes assume another user ID, for example when su(1) is used.) The ggeettllooggiinn__rr() routine is a reentrant version of ggeettllooggiinn(). It is functionally identical to ggeettllooggiinn() except that the caller must provide a buffer, _n_a_m_e, in which to store the user's login name and a corresponding length parameter, _n_a_m_e_l_e_n, that specifies the size of the buffer. The buffer should be large enough to store the login name and a trailing NUL (typically LOGIN_NAME_MAX bytes). sseettllooggiinn() sets the login name of the user associated with the current session to _n_a_m_e. This call is restricted to the superuser, and is normally used only when a new session is being created on behalf of the named user (for example, at login time, or when a remote shell is invoked). _N_O_T_E: There is only one login name per session. It is _C_R_I_T_I_C_A_L_L_Y important to ensure that sseettllooggiinn() is only ever called after the process has taken adequate steps to ensure that it is detached from its parent's session. The _O_N_L_Y way to do this is via the sseettssiidd() function. The ddaaeemmoonn() function calls sseettssiidd() which is an ideal way of detaching from a controlling terminal and forking into the background. In particular, neither iiooccttll(_t_t_y_f_d, _T_I_O_C_N_O_T_T_Y, _._._.) nor sseettppggrrpp(_._._.) is sufficient to create a new session. Once a parent process has called sseettssiidd(), it is acceptable for some child of that process to then call sseettllooggiinn(), even though it is not the session leader. Beware, however, that _A_L_L processes in the session will change their login name at the same time, even the parent. This is different from traditional UNIX privilege inheritance and as such can be counter-intuitive. Since the sseettllooggiinn() routine is restricted to the super-user, it is assumed that (like all other privileged programs) the programmer has taken adequate precautions to prevent security violations. RREETTUURRNN VVAALLUUEESS If a call to ggeettllooggiinn() succeeds, it returns a pointer to a NUL- terminated string in a static buffer. If the name has not been set, it returns NULL. If a call to ggeettllooggiinn__rr() succeeds, a value of 0 is returned, else the error number is returned. If a call to sseettllooggiinn() succeeds, a value of 0 is returned. If sseettllooggiinn() fails, a value of -1 is returned and an error code is placed in the global location _e_r_r_n_o. EERRRROORRSS ggeettllooggiinn__rr() and sseettllooggiinn() will succeed unless: [EFAULT] The _n_a_m_e parameter points to an invalid address. In addition, ggeettllooggiinn__rr() may return the following error: [ERANGE] The value of _n_a_m_e_l_e_n is not large enough to store the user's login name and a trailing NUL. sseettllooggiinn() may return the following errors: [EINVAL] The _n_a_m_e parameter pointed to a string that was too long. Login names are limited to LOGIN_NAME_MAX-1 characters, currently 31. [EPERM] The caller tried to set the login name and was not the superuser. SSEEEE AALLSSOO setsid(2) SSTTAANNDDAARRDDSS The ggeettllooggiinn() and ggeettllooggiinn__rr() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettllooggiinn() function first appeared in 4.2BSD. BBUUGGSS In earlier versions of the system, ggeettllooggiinn() failed unless the process was associated with a login terminal. The current implementation (using sseettllooggiinn()) allows getlogin to succeed even when the process has no controlling terminal. In earlier versions of the system, the value returned by ggeettllooggiinn() could not be trusted without checking the user ID. Portable programs should probably still make this check. NNAAMMEE ggeettppeeeerrnnaammee - get name of connected peer SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettppeeeerrnnaammee(_i_n_t _s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_n_a_m_e, _s_o_c_k_l_e_n___t _*_n_a_m_e_l_e_n); DDEESSCCRRIIPPTTIIOONN ggeettppeeeerrnnaammee() returns the address information of the peer connected to socket _s. One common use occurs when a process inherits an open socket, such as TCP servers forked from inetd(8). In this scenario, ggeettppeeeerrnnaammee() is used to determine the connecting client's IP address. ggeettppeeeerrnnaammee() takes three parameters: _s contains the file descriptor of the socket whose peer should be looked up. _n_a_m_e points to a sockaddr structure that will hold the address information for the connected peer. Normal use requires one to use a structure specific to the protocol family in use, such as sockaddr_in (IPv4) or sockaddr_in6 (IPv6), cast to a (struct sockaddr *). For greater portability, especially with the newer protocol families, the new struct sockaddr_storage should be used. sockaddr_storage is large enough to hold any of the other sockaddr_* variants. On return, it can be cast to the correct sockaddr type, based on the protocol family contained in its ss_family field. _n_a_m_e_l_e_n indicates the amount of space pointed to by _n_a_m_e, in bytes. If address information for the local end of the socket is required, the getsockname(2) function should be used instead. If _n_a_m_e does not point to enough space to hold the entire socket address, the result will be truncated to _n_a_m_e_l_e_n bytes. RREETTUURRNN VVAALLUUEESS If the call succeeds, a 0 is returned and _n_a_m_e_l_e_n is set to the actual size of the socket address returned in _n_a_m_e. Otherwise, _e_r_r_n_o is set and a value of -1 is returned. EERRRROORRSS On failure, _e_r_r_n_o is set to one of the following: [EBADF] The argument _s is not a valid descriptor. [ENOTSOCK] The argument _s is a file, not a socket. [ENOTCONN] The socket is not connected. [ENOBUFS] Insufficient resources were available in the system to perform the operation. [EFAULT] The _n_a_m_e or _n_a_m_e_l_e_n parameter points to memory not in a valid part of the process address space. SSEEEE AALLSSOO accept(2), bind(2), getsockname(2), socket(2), getpeereid(3) SSTTAANNDDAARRDDSS The ggeettppeeeerrnnaammee() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettppeeeerrnnaammee() function call appeared in 4.2BSD. NNAAMMEE ggeettppggrrpp, ggeettppggiidd - get process group SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t ggeettppggrrpp(_v_o_i_d); _p_i_d___t ggeettppggiidd(_p_i_d___t _p_i_d); DDEESSCCRRIIPPTTIIOONN The process group of the current process is returned by ggeettppggrrpp(). The process group of the _p_i_d process is returned by ggeettppggiidd(). If _p_i_d is zero, ggeettppggiidd() returns the process group of the current process. Process groups are used for distribution of signals, and by terminals to arbitrate requests for their input: processes that have the same process group as the terminal are foreground and may read, while others will block with a signal if they attempt to read. These calls are thus used by programs such as csh(1) to create process groups in implementing job control. The ttccggeettppggrrpp() and ttccsseettppggrrpp() calls are used to get/set the process group of the control terminal. EERRRROORRSS ggeettppggrrpp() always succeeds, however ggeettppggiidd() will succeed unless: [EPERM] The current process and the process _p_i_d are not in the same session. [ESRCH] There is no process with a process ID equal to _p_i_d. SSEEEE AALLSSOO setpgid(2), termios(4) SSTTAANNDDAARRDDSS The ggeettppggrrpp() and ggeettppggiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A ggeettppggrrpp() function call that took a _p_i_d___t _p_i_d argument appeared in 4.0BSD. This version, without an argument, is derived from its usage in System V Release 4, and first appeared in NetBSD 0.9. The ggeettppggiidd() function call is derived from its usage in System V Release 4, and first appeared in NetBSD 1.2a. NNAAMMEE ggeettppggrrpp, ggeettppggiidd - get process group SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t ggeettppggrrpp(_v_o_i_d); _p_i_d___t ggeettppggiidd(_p_i_d___t _p_i_d); DDEESSCCRRIIPPTTIIOONN The process group of the current process is returned by ggeettppggrrpp(). The process group of the _p_i_d process is returned by ggeettppggiidd(). If _p_i_d is zero, ggeettppggiidd() returns the process group of the current process. Process groups are used for distribution of signals, and by terminals to arbitrate requests for their input: processes that have the same process group as the terminal are foreground and may read, while others will block with a signal if they attempt to read. These calls are thus used by programs such as csh(1) to create process groups in implementing job control. The ttccggeettppggrrpp() and ttccsseettppggrrpp() calls are used to get/set the process group of the control terminal. EERRRROORRSS ggeettppggrrpp() always succeeds, however ggeettppggiidd() will succeed unless: [EPERM] The current process and the process _p_i_d are not in the same session. [ESRCH] There is no process with a process ID equal to _p_i_d. SSEEEE AALLSSOO setpgid(2), termios(4) SSTTAANNDDAARRDDSS The ggeettppggrrpp() and ggeettppggiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A ggeettppggrrpp() function call that took a _p_i_d___t _p_i_d argument appeared in 4.0BSD. This version, without an argument, is derived from its usage in System V Release 4, and first appeared in NetBSD 0.9. The ggeettppggiidd() function call is derived from its usage in System V Release 4, and first appeared in NetBSD 1.2a. NNAAMMEE ggeettppiidd, ggeettppppiidd - get parent or calling process identification SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t ggeettppiidd(_v_o_i_d); _p_i_d___t ggeettppppiidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN ggeettppiidd() returns the process ID of the calling process. Though the ID is guaranteed to be unique, it should _N_O_T be used for constructing temporary file names; see mkstemp(3) instead. ggeettppppiidd() returns the process ID of the parent of the calling process. RREETTUURRNN VVAALLUUEESS These functions are always successful, and no return value is reserved to indicate an error. SSEEEE AALLSSOO gethostid(3) SSTTAANNDDAARRDDSS ggeettppiidd() and ggeettppppiidd() conform to IEEE Std 1003.1-2008 (``POSIX.1''). NNAAMMEE ggeettppiidd, ggeettppppiidd - get parent or calling process identification SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t ggeettppiidd(_v_o_i_d); _p_i_d___t ggeettppppiidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN ggeettppiidd() returns the process ID of the calling process. Though the ID is guaranteed to be unique, it should _N_O_T be used for constructing temporary file names; see mkstemp(3) instead. ggeettppppiidd() returns the process ID of the parent of the calling process. RREETTUURRNN VVAALLUUEESS These functions are always successful, and no return value is reserved to indicate an error. SSEEEE AALLSSOO gethostid(3) SSTTAANNDDAARRDDSS ggeettppiidd() and ggeettppppiidd() conform to IEEE Std 1003.1-2008 (``POSIX.1''). NNAAMMEE ggeettpprriioorriittyy, sseettpprriioorriittyy - get/set process scheduling priority SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettpprriioorriittyy(_i_n_t _w_h_i_c_h, _i_d___t _w_h_o); _i_n_t sseettpprriioorriittyy(_i_n_t _w_h_i_c_h, _i_d___t _w_h_o, _i_n_t _p_r_i_o); DDEESSCCRRIIPPTTIIOONN The scheduling priority of the process, process group, or user, as indicated by _w_h_i_c_h and _w_h_o is obtained with the ggeettpprriioorriittyy() call and set with the sseettpprriioorriittyy() call. _w_h_i_c_h is one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, and _w_h_o is interpreted relative to _w_h_i_c_h (a process identifier for PRIO_PROCESS, process group identifier for PRIO_PGRP, and a user ID for PRIO_USER). A zero value of _w_h_o denotes the current process, process group, or user. _p_r_i_o is a value in the range -20 to 20. The default priority is 0; lower priorities cause more favorable scheduling. The ggeettpprriioorriittyy() call returns the highest priority (lowest numerical value) enjoyed by any of the specified processes. The sseettpprriioorriittyy() call sets the priorities of all of the specified processes to the specified value. Priority values outside the range -20 to 20 are truncated to the appropriate limit. Only the superuser may lower priorities. RREETTUURRNN VVAALLUUEESS Since ggeettpprriioorriittyy() can legitimately return the value -1, it is necessary to clear the external variable _e_r_r_n_o prior to the call, then check it afterward to determine if a -1 is an error or a legitimate value. The sseettpprriioorriittyy() call returns 0 if there is no error, or -1 if there is. EERRRROORRSS ggeettpprriioorriittyy() and sseettpprriioorriittyy() will fail if: [ESRCH] No process was located using the _w_h_i_c_h and _w_h_o values specified. [EINVAL] _w_h_i_c_h was not one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER. In addition, sseettpprriioorriittyy() will fail if: [EPERM] A process was located, but neither its effective nor real user ID matched the effective user ID of the caller. [EACCES] A non-superuser attempted to lower a process priority. SSEEEE AALLSSOO nice(1), fork(2), renice(8) SSTTAANNDDAARRDDSS The ggeettpprriioorriittyy() and sseettpprriioorriittyy() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The predecessor of these functions, the former nniiccee() system call, appeared in Version 3 AT&T UNIX and was removed in 4.3BSD-Reno. The ggeettpprriioorriittyy() and sseettpprriioorriittyy() system calls appeared in 4.1cBSD. NNAAMMEE ggeettrreessggiidd, ggeettrreessuuiidd, sseettrreessggiidd, sseettrreessuuiidd - get or set real, effective and saved user or group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ggeettrreessggiidd(_g_i_d___t _*_r_g_i_d, _g_i_d___t _*_e_g_i_d, _g_i_d___t _*_s_g_i_d); _i_n_t ggeettrreessuuiidd(_u_i_d___t _*_r_u_i_d, _u_i_d___t _*_e_u_i_d, _u_i_d___t _*_s_u_i_d); _i_n_t sseettrreessggiidd(_g_i_d___t _r_g_i_d, _g_i_d___t _e_g_i_d, _g_i_d___t _s_g_i_d); _i_n_t sseettrreessuuiidd(_u_i_d___t _r_u_i_d, _u_i_d___t _e_u_i_d, _u_i_d___t _s_u_i_d); DDEESSCCRRIIPPTTIIOONN The sseettrreessuuiidd() function sets the real, effective and saved user IDs of the current process. The analogous sseettrreessggiidd() sets the real, effective and saved group IDs. Privileged processes may set these IDs to arbitrary values. Unprivileged processes are restricted in that each of the new IDs must match one of the current IDs. Passing -1 as an argument causes the corresponding value to remain unchanged. The ggeettrreessggiidd() and ggeettrreessuuiidd() calls retrieve the real, effective, and saved group and user IDs of the current process, respectively. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [EPERM] The calling process was not privileged and tried to change one or more IDs to a value which was not the current real ID, the current effective ID nor the current saved ID. [EFAULT] An address passed to ggeettrreessggiidd() or ggeettrreessuuiidd() was invalid. SSEEEE AALLSSOO getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), setregid(2), setreuid(2), setuid(2) SSTTAANNDDAARRDDSS These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') specification. While they are not completely portable, they are the least ambiguous way to manage user and group IDs. HHIISSTTOORRYY These functions first appeared in HP-UX. NNAAMMEE ggeettrreessggiidd, ggeettrreessuuiidd, sseettrreessggiidd, sseettrreessuuiidd - get or set real, effective and saved user or group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ggeettrreessggiidd(_g_i_d___t _*_r_g_i_d, _g_i_d___t _*_e_g_i_d, _g_i_d___t _*_s_g_i_d); _i_n_t ggeettrreessuuiidd(_u_i_d___t _*_r_u_i_d, _u_i_d___t _*_e_u_i_d, _u_i_d___t _*_s_u_i_d); _i_n_t sseettrreessggiidd(_g_i_d___t _r_g_i_d, _g_i_d___t _e_g_i_d, _g_i_d___t _s_g_i_d); _i_n_t sseettrreessuuiidd(_u_i_d___t _r_u_i_d, _u_i_d___t _e_u_i_d, _u_i_d___t _s_u_i_d); DDEESSCCRRIIPPTTIIOONN The sseettrreessuuiidd() function sets the real, effective and saved user IDs of the current process. The analogous sseettrreessggiidd() sets the real, effective and saved group IDs. Privileged processes may set these IDs to arbitrary values. Unprivileged processes are restricted in that each of the new IDs must match one of the current IDs. Passing -1 as an argument causes the corresponding value to remain unchanged. The ggeettrreessggiidd() and ggeettrreessuuiidd() calls retrieve the real, effective, and saved group and user IDs of the current process, respectively. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [EPERM] The calling process was not privileged and tried to change one or more IDs to a value which was not the current real ID, the current effective ID nor the current saved ID. [EFAULT] An address passed to ggeettrreessggiidd() or ggeettrreessuuiidd() was invalid. SSEEEE AALLSSOO getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), setregid(2), setreuid(2), setuid(2) SSTTAANNDDAARRDDSS These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') specification. While they are not completely portable, they are the least ambiguous way to manage user and group IDs. HHIISSTTOORRYY These functions first appeared in HP-UX. NNAAMMEE ggeettrrlliimmiitt, sseettrrlliimmiitt - control maximum system resource consumption SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettrrlliimmiitt(_i_n_t _r_e_s_o_u_r_c_e, _s_t_r_u_c_t _r_l_i_m_i_t _*_r_l_p); _i_n_t sseettrrlliimmiitt(_i_n_t _r_e_s_o_u_r_c_e, _c_o_n_s_t _s_t_r_u_c_t _r_l_i_m_i_t _*_r_l_p); DDEESSCCRRIIPPTTIIOONN Limits on the consumption of system resources by the current process and each process it creates may be obtained with the ggeettrrlliimmiitt() call, and set with the sseettrrlliimmiitt() call. The _r_e_s_o_u_r_c_e parameter is one of the following: RLIMIT_CORE The largest size (in bytes) _c_o_r_e file that may be created. RLIMIT_CPU The maximum amount of CPU time (in seconds) to be used by each process. RLIMIT_DATA The maximum size (in bytes) of the data segment for a process; this includes memory allocated via malloc(3) and all other anonymous memory mapped via mmap(2). RLIMIT_FSIZE The largest size (in bytes) file that may be created. RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into memory using the mlock(2) function. RLIMIT_NOFILE The maximum number of open files for this process. RLIMIT_NPROC The maximum number of simultaneous processes for this user id. RLIMIT_RSS The maximum size (in bytes) to which a process's resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size. RLIMIT_STACK The maximum size (in bytes) of the stack segment for a process, which defines how far a process's stack segment may be extended. Stack extension is performed automatically by the system, and is only used by the main thread of a process. A resource limit is specified as a soft limit and a hard limit. When a soft limit is exceeded a process may receive a signal (for example, if the CPU time or file size is exceeded), but it will be allowed to continue execution until it reaches the hard limit (or modifies its resource limit). The _r_l_i_m_i_t structure is used to specify the hard and soft limits on a resource, struct rlimit { rlim_t rlim_cur; /* current (soft) limit */ rlim_t rlim_max; /* hard limit */ }; Only the superuser may raise the maximum limits. Other users may only alter _r_l_i_m___c_u_r within the range from 0 to _r_l_i_m___m_a_x or (irreversibly) lower _r_l_i_m___m_a_x. An ``infinite'' value for a limit is defined as RLIM_INFINITY. A value of RLIM_SAVED_CUR or RLIM_SAVED_MAX will be stored in _r_l_i_m___c_u_r or _r_l_i_m___m_a_x respectively by ggeettrrlliimmiitt() if the value for the current or maximum resource limit cannot be stored in an rlim_t. The values RLIM_SAVED_CUR and RLIM_SAVED_MAX should not be used in a call to sseettrrlliimmiitt() unless they were returned by a previous call to ggeettrrlliimmiitt(). Because this information is stored in the per-process information, this system call must be executed directly by the shell if it is to affect all future processes created by the shell; lliimmiitt is thus a built-in command to csh(1) and uulliimmiitt is the sh(1) equivalent. The system refuses to extend the data or stack space when the limits would be exceeded in the normal way: a brk(2) call fails if the data space limit is reached. When the stack limit is reached, the process receives a segmentation fault (SIGSEGV); if this signal is not caught by a handler using the signal stack, this signal will kill the process. A file I/O operation that would create a file larger than the process' soft limit will cause the write to fail and a signal SIGXFSZ to be generated; this normally terminates the process, but may be caught. When the soft CPU time limit is exceeded, a signal SIGXCPU is sent to the offending process. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettrrlliimmiitt() and sseettrrlliimmiitt() will fail if: [EFAULT] The address specified for _r_l_p is invalid. [EINVAL] An unrecognized value for _r_e_s_o_u_r_c_e was specified. In addition, sseettrrlliimmiitt() may return the following errors: [EINVAL] The new _r_l_i_m___c_u_r is greater than the new _r_l_i_m___m_a_x. [EPERM] The new _r_l_i_m___m_a_x is greater than the current maximum limit value, and the caller is not the superuser. SSEEEE AALLSSOO csh(1), sh(1), quotactl(2), sigaction(2), sigaltstack(2), sysctl(3) SSTTAANNDDAARRDDSS The ggeettrrlliimmiitt() and sseettrrlliimmiitt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS resources are non- standard extensions. HHIISSTTOORRYY The ggeettrrlliimmiitt() and sseettrrlliimmiitt() system calls first appeared in 4.1cBSD. BBUUGGSS The RLIMIT_AS resource is missing. NNAAMMEE ggeettrrttaabbllee, sseettrrttaabbllee - get and set the default routing table of the current process SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ggeettrrttaabbllee(_v_o_i_d); _i_n_t sseettrrttaabbllee(_i_n_t _r_t_a_b_l_e_i_d); DDEESSCCRRIIPPTTIIOONN ggeettrrttaabbllee() and sseettrrttaabbllee() manipulate the routing table and routing domain associated with the current process. Only the superuser is allowed to change the process routing table if it is already set to a non-zero value. RREETTUURRNN VVAALLUUEESS ggeettrrttaabbllee() returns the routing table of the current process. Upon successful completion, sseettrrttaabbllee() returns 0 if the call succeeds, -1 if it fails. EERRRROORRSS The call succeeds unless: [EINVAL] The value of the _r_t_a_b_l_e_i_d argument is not a valid routing table. [EPERM] The user is not the superuser and the routing table of the calling process is already set to a non-zero value. SSEEEE AALLSSOO getsockopt(2), route(8) HHIISSTTOORRYY The ggeettrrttaabbllee() and sseettrrttaabbllee() system calls appeared in OpenBSD 4.8. NNAAMMEE ggeettrruussaaggee - get information about resource utilization SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettrruussaaggee(_i_n_t _w_h_o, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN ggeettrruussaaggee() returns resource usage information for argument _w_h_o, which can be one of the following: RUSAGE_SELF Resources used by the current process. RUSAGE_CHILDREN Resources used by all the terminated children of the current process. RUSAGE_THREAD Resources used by the current thread. The buffer to which _r_u_s_a_g_e points will be filled in with the following structure: struct rusage { struct timeval ru_utime; /* user time used */ struct timeval ru_stime; /* system time used */ long ru_maxrss; /* max resident set size */ long ru_ixrss; /* integral shared text memory size */ long ru_idrss; /* integral unshared data size */ long ru_isrss; /* integral unshared stack size */ long ru_minflt; /* page reclaims */ long ru_majflt; /* page faults */ long ru_nswap; /* swaps */ long ru_inblock; /* block input operations */ long ru_oublock; /* block output operations */ long ru_msgsnd; /* messages sent */ long ru_msgrcv; /* messages received */ long ru_nsignals; /* signals received */ long ru_nvcsw; /* voluntary context switches */ long ru_nivcsw; /* involuntary context switches */ }; The fields are interpreted as follows: _r_u___u_t_i_m_e the total amount of time spent executing in user mode. _r_u___s_t_i_m_e the total amount of time spent in the system executing on behalf of the process(es). _r_u___m_a_x_r_s_s the maximum resident set size utilized (in kilobytes). _r_u___i_x_r_s_s an ``integral'' value indicating the amount of memory used by the text segment that was also shared among other processes. This value is expressed in units of kilobytes * ticks-of-execution. _r_u___i_d_r_s_s an integral value of the amount of unshared memory residing in the data segment of a process (expressed in units of kilobytes * ticks-of-execution). _r_u___i_s_r_s_s an integral value of the amount of unshared memory residing in the stack segment of a process (expressed in units of kilobytes * ticks-of-execution). _r_u___m_i_n_f_l_t the number of page faults serviced without any I/O activity; here I/O activity is avoided by ``reclaiming'' a page frame from the list of pages awaiting reallocation. _r_u___m_a_j_f_l_t the number of page faults serviced that required I/O activity. _r_u___n_s_w_a_p the number of times a process was ``swapped'' out of main memory. _r_u___i_n_b_l_o_c_k the number of times the file system had to perform input. _r_u___o_u_b_l_o_c_k the number of times the file system had to perform output. _r_u___m_s_g_s_n_d the number of IPC messages sent. _r_u___m_s_g_r_c_v the number of IPC messages received. _r_u___n_s_i_g_n_a_l_s the number of signals delivered. _r_u___n_v_c_s_w the number of times a context switch resulted due to a process voluntarily giving up the processor before its time slice was completed (usually to await availability of a resource). _r_u___n_i_v_c_s_w the number of times a context switch resulted due to a higher priority process becoming runnable or because the current process exceeded its time slice. NNOOTTEESS The numbers _r_u___i_n_b_l_o_c_k and _r_u___o_u_b_l_o_c_k account only for real I/O; data supplied by the caching mechanism is charged only to the first process to read or write the data. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettrruussaaggee() will fail if: [EINVAL] The _w_h_o parameter is not a valid value. [EFAULT] The address specified by the _r_u_s_a_g_e parameter is not in a valid part of the process address space. SSEEEE AALLSSOO clock_gettime(2), gettimeofday(2), wait(2) SSTTAANNDDAARRDDSS The ggeettrruussaaggee() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The RUSAGE_THREAD flag is an extension to that specification. HHIISSTTOORRYY A predecessor to ggeettrruussaaggee(), ttiimmeess(), first appeared in Version 3 AT&T UNIX. The ggeettrruussaaggee() system call first appeared in 4.1cBSD. The RUSAGE_THREAD flag has been available since OpenBSD 4.8. BBUUGGSS There is no way to obtain information about a child process that has not yet terminated. NNAAMMEE ggeettssiidd - get process session SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t ggeettssiidd(_p_i_d___t _p_i_d); DDEESSCCRRIIPPTTIIOONN The session ID of the process identified by _p_i_d is returned by ggeettssiidd(). If _p_i_d is zero, ggeettssiidd() returns the session ID of the current process. RREETTUURRNN VVAALLUUEESS Upon successful completion, the function ggeettssiidd() returns the session ID of the specified process; otherwise, it returns a value of -1 and sets _e_r_r_n_o to indicate an error. EERRRROORRSS ggeettssiidd() will succeed unless: [EPERM] The current process and the process _p_i_d are not in the same session. [ESRCH] There is no process with a process ID equal to _p_i_d. SSEEEE AALLSSOO getpgid(2), getpgrp(2), setpgid(2), setsid(2), termios(4) SSTTAANNDDAARRDDSS ggeettssiidd() conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettssiidd() function call is derived from its usage in AT&T System V UNIX, and is mandated by X/Open Portability Guide Issue 4 (``XPG4''). NNAAMMEE ggeettssoocckknnaammee - get socket name SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettssoocckknnaammee(_i_n_t _s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_n_a_m_e, _s_o_c_k_l_e_n___t _*_n_a_m_e_l_e_n); DDEESSCCRRIIPPTTIIOONN ggeettssoocckknnaammee() returns the locally bound address information for a specified socket. Common uses of this function are as follows: ++oo When bind(2) is called with a port number of 0 (indicating the kernel should pick an ephemeral port) ggeettssoocckknnaammee() is used to retrieve the kernel-assigned port number. ++oo When a process calls bind(2) on a wildcard IP address, ggeettssoocckknnaammee() is used to retrieve the local IP address for the connection. ++oo When a function wishes to know the address family of a socket, ggeettssoocckknnaammee() can be used. ggeettssoocckknnaammee() takes three parameters: _s contains the file descriptor for the socket to be looked up. _n_a_m_e points to a sockaddr structure which will hold the resulting address information. Normal use requires one to use a structure specific to the protocol family in use, such as sockaddr_in (IPv4) or sockaddr_in6 (IPv6), cast to a (struct sockaddr *). For greater portability (such as newer protocol families) the new structure sockaddr_storage exists. sockaddr_storage is large enough to hold any of the other sockaddr_* variants. On return, it should be cast to the correct sockaddr type, according to the current protocol family. _n_a_m_e_l_e_n indicates the amount of space pointed to by _n_a_m_e, in bytes. Upon return, _n_a_m_e_l_e_n is set to the actual size of the returned address information. If the address of the destination socket for a given socket connection is needed, the getpeername(2) function should be used instead. If _n_a_m_e does not point to enough space to hold the entire socket address, the result will be truncated to _n_a_m_e_l_e_n bytes. RREETTUURRNN VVAALLUUEESS On success, ggeettssoocckknnaammee() returns a 0, and _n_a_m_e_l_e_n is set to the actual size of the socket address returned in _n_a_m_e. Otherwise, _e_r_r_n_o is set, and a value of -1 is returned. EERRRROORRSS If ggeettssoocckknnaammee() fails, _e_r_r_n_o is set to one of the following: [EBADF] The argument _s is not a valid descriptor. [ENOTSOCK] The argument _s is a file, not a socket. [ENOBUFS] Insufficient resources were available in the system to perform the operation. [EFAULT] The _n_a_m_e or _n_a_m_e_l_e_n parameter points to memory not in a valid part of the process address space. SSEEEE AALLSSOO accept(2), bind(2), getpeername(2), socket(2), getpeereid(3) SSTTAANNDDAARRDDSS The ggeettssoocckknnaammee() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettssoocckknnaammee() function call appeared in 4.2BSD. NNAAMMEE ggeettssoocckkoopptt, sseettssoocckkoopptt - get and set options on sockets SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettssoocckkoopptt(_i_n_t _s, _i_n_t _l_e_v_e_l, _i_n_t _o_p_t_n_a_m_e, _v_o_i_d _*_o_p_t_v_a_l, _s_o_c_k_l_e_n___t _*_o_p_t_l_e_n); _i_n_t sseettssoocckkoopptt(_i_n_t _s, _i_n_t _l_e_v_e_l, _i_n_t _o_p_t_n_a_m_e, _c_o_n_s_t _v_o_i_d _*_o_p_t_v_a_l, _s_o_c_k_l_e_n___t _o_p_t_l_e_n); DDEESSCCRRIIPPTTIIOONN ggeettssoocckkoopptt() and sseettssoocckkoopptt() manipulate the _o_p_t_i_o_n_s associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost ``socket'' level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, _l_e_v_e_l is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, _l_e_v_e_l should be set to the protocol number of TCP; see getprotoent(3). The parameters _o_p_t_v_a_l and _o_p_t_l_e_n are used to access option values for sseettssoocckkoopptt(). For ggeettssoocckkoopptt() they identify a buffer in which the value for the requested option(s) are to be returned. For ggeettssoocckkoopptt(), _o_p_t_l_e_n is a value-result parameter, initially containing the size of the buffer pointed to by _o_p_t_v_a_l, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, _o_p_t_v_a_l may be NULL. _o_p_t_n_a_m_e and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file <_s_y_s_/_s_o_c_k_e_t_._h> contains definitions for socket level options, described below. Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. Most socket-level options utilize an int parameter for _o_p_t_v_a_l. For sseettssoocckkoopptt(), the parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. SO_LINGER uses a struct linger parameter, defined in <_s_y_s_/_s_o_c_k_e_t_._h>, which specifies the desired state of the option and the linger interval (see below). SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval parameter, defined in <_s_y_s_/_t_i_m_e_._h>. The following options are recognized at the socket level. Except as noted, each may be examined with ggeettssoocckkoopptt() and set with sseettssoocckkoopptt(). SO_DEBUG enables recording of debugging information SO_REUSEADDR enables local address reuse SO_REUSEPORT enables duplicate address and port bindings SO_KEEPALIVE enables keep connections alive SO_DONTROUTE enables routing bypass; not supported SO_LINGER linger on close if data present SO_BROADCAST enables permission to transmit broadcast messages SO_OOBINLINE enables reception of out-of-band data in band SO_BINDANY enables binding to any address SO_SNDBUF set buffer size for output SO_RCVBUF set buffer size for input SO_SNDLOWAT set minimum count for output SO_RCVLOWAT set minimum count for input SO_SNDTIMEO set timeout value for output SO_RCVTIMEO set timeout value for input SO_TIMESTAMP enables reception of a timestamp with datagrams SO_PEERCRED get the credentials from other side of connection SO_RTABLE set the routing table used for route lookups SO_SPLICE splice two sockets together or get data length SO_TYPE get the type of the socket (get only) SO_ERROR get and clear error on the socket (get only) SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a SIGPIPE signal when attempting to send data. SO_LINGER controls the action taken when unsent messages are queued on socket and a close(2) is performed. If the socket promises reliable delivery of data and SO_LINGER is set, the system will block the process on the close(2) attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period measured in seconds, termed the linger interval, is specified in the sseettssoocckkoopptt() call when SO_LINGER is requested). If SO_LINGER is disabled and a close(2) is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The option SO_BROADCAST requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv(2) or read(2) calls without the MSG_OOB flag. Some protocols always behave as if this option is set. SO_BINDANY allows the socket to be bound to addresses which are not local to the machine, so it can be used to make a transparent proxy. Note that this option is limited to the super-user. In order to receive packets for these addresses, SO_BINDANY needs to be combined with matching outgoing pf(4) rules with the _d_i_v_e_r_t_-_r_e_p_l_y parameter. For example, with the following rule the socket receives packets for 192.168.0.10 even if it is not a local address: pass out inet from 192.168.0.10 divert-reply SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. SO_SNDLOWAT is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A select(2) or poll(2) operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for SO_SNDLOWAT is set to a convenient size for network efficiency, often 1024. SO_RCVLOWAT is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with the smaller of the amount available or the amount requested. The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. SO_SNDTIMEO is an option to set a timeout value for output operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error EWOULDBLOCK if no data was sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error EWOULDBLOCK if no data were received. If the SO_TIMESTAMP option is enabled on a SOCK_DGRAM socket, the recvmsg(2) call will return a timestamp corresponding to when the datagram was received. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by a struct timeval. The cmsghdr fields have the following values: cmsg_len = CMSG_LEN(sizeof(struct timeval)) cmsg_level = SOL_SOCKET cmsg_type = SCM_TIMESTAMP SO_PEERCRED fetches the _s_t_r_u_c_t _s_o_c_k_p_e_e_r_c_r_e_d credentials from the other side of the connection (currently only possible on AF_UNIX sockets). These credentials are from the time that bind(2) or connect(2) were called. The SO_RTABLE option gets or sets the routing table which will be used by the socket for address lookups. If a protocol family of the socket doesn't support switching routing tables, the ENOPROTOOPT error is returned. Only the superuser is allowed to change the routing table if it is already set to a non-zero value. A socket's chosen routing table is initialized from the process's configuration, previously selected using setrtable(2). SO_SPLICE can splice together two TCP or UDP sockets for zero-copy data transfers. Both sockets must be of the same type. In the first form, sseettssoocckkoopptt() is called with the source socket _s and the drain socket's _i_n_t file descriptor as _o_p_t_v_a_l. In the second form, _o_p_t_v_a_l is a _s_t_r_u_c_t _s_p_l_i_c_e with the drain socket in _s_p___f_d, a positive maximum number of bytes or 0 in _s_p___m_a_x and an idle timeout _s_p___i_d_l_e in the form of a _s_t_r_u_c_t _t_i_m_e_v_a_l. If -1 is given as drain socket, the source socket _s gets unspliced. Otherwise the spliced data transfer continues within the kernel until the optional maximum is reached, one of the connections terminates, idle timeout expires or an error occurs. A successful select(2), poll(2), or kqueue(2) operation testing the ability to read from the source socket indicates that the splicing has terminated. The error status can be examined with SO_ERROR at the source socket. The ETIMEDOUT error is set if there was no data transferred between two sockets during the _s_p___i_d_l_e period of time. The EFBIG error is set after exactly _s_p___m_a_x bytes have been transferred. Note that if a maximum is given, it is only guaranteed that no more bytes are transferred. A short splice can happen, but then a second call to splice will transfer the remaining data immediately. The SO_SPLICE option with ggeettssoocckkoopptt() and an _o_f_f___t value as _o_p_t_v_a_l can be used to retrieve the number of bytes transferred so far from the source socket _s. A successful new splice resets this number. Finally, SO_TYPE and SO_ERROR are options used only with ggeettssoocckkoopptt(). SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful for servers that inherit sockets on startup. SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The call succeeds unless: [EBADF] The argument _s is not a valid descriptor. [ENOTSOCK] The argument _s is a file, not a socket. [ENOPROTOOPT] The option is unknown at the level indicated. [EOPNOTSUPP] The option is unsupported. [EFAULT] The address pointed to by _o_p_t_v_a_l is not in a valid part of the process address space. For ggeettssoocckkoopptt(), this error may also be returned if _o_p_t_l_e_n is not in a valid part of the process address space. SSEEEE AALLSSOO connect(2), getrtable(2), ioctl(2), poll(2), select(2), socket(2), getprotoent(3), divert(4), pf.conf(5), protocols(5), sosplice(9) SSTTAANNDDAARRDDSS The ggeettssoocckkoopptt() and sseettssoocckkoopptt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettssoocckkoopptt() system call appeared in 4.2BSD. BBUUGGSS Several of the socket options should be handled at lower levels of the system. NNAAMMEE ggeetttthhrriidd - get thread identifier SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t ggeetttthhrriidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN kkqquueeuuee returns the thread ID of the calling thread. This is used in the implementation of the thread library (--llpptthhrreeaadd) and can appear in the output of system utilities such as ps(1) and kdump(1). Thread IDs are not a stable interface and should not be used directly by applications except for correlation with system utility output. Applications should use the _p_t_h_r_e_a_d___t values from pthread_self(3) and pthread_create(3) to identify threads within the process itself. RREETTUURRNN VVAALLUUEESS This function is always successful, and no return value is reserved to indicate an error. SSEEEE AALLSSOO __tfork(2), getpid(2), pthread_create(3), pthread_self(3) SSTTAANNDDAARRDDSS The kkqquueeuuee syscall is specific to OpenBSD and should not be used in portable applications. HHIISSTTOORRYY The kkqquueeuuee syscall appeared in OpenBSD 3.9. NNAAMMEE ggeettttiimmeeooffddaayy, sseettttiimmeeooffddaayy - get/set date and time SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettttiimmeeooffddaayy(_s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_p, _s_t_r_u_c_t _t_i_m_e_z_o_n_e _*_t_z_p); _i_n_t sseettttiimmeeooffddaayy(_c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_p, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_z_o_n_e _*_t_z_p); DDEESSCCRRIIPPTTIIOONN NNoottee:: ttiimmeezzoonnee iiss nnoo lloonnggeerr uusseedd;; tthhiiss iinnffoorrmmaattiioonn iiss kkeepptt oouuttssiiddee tthhee kkeerrnneell.. The system's notion of the current Greenwich time and the current time zone is obtained with the ggeettttiimmeeooffddaayy() call, and set with the sseettttiimmeeooffddaayy() call. The time is expressed in seconds and microseconds since midnight (0 hour), January 1, 1970. The resolution of the system clock is hardware dependent, and the time may be updated continuously or in ``ticks''. If _t_p or _t_z_p is NULL, the associated time information will not be returned or set. The structures pointed to by _t_p and _t_z_p are defined in <_s_y_s_/_t_i_m_e_._h> as: struct timeval { time_t tv_sec; /* seconds since Jan. 1, 1970 */ suseconds_t tv_usec; /* and microseconds */ }; struct timezone { int tz_minuteswest; /* of Greenwich */ int tz_dsttime; /* type of dst correction to apply */ }; The _t_i_m_e_z_o_n_e structure indicates the local time zone (measured in minutes of time westward from Greenwich), and a flag that, if nonzero, indicates that Daylight Saving time applies locally during the appropriate part of the year. Only the superuser may set the time of day or time zone. If the system securelevel is greater than 1 (see init(8)), the time may only be advanced. This limitation is imposed to prevent a malicious superuser from setting arbitrary time stamps on files. The system time can still be adjusted backwards using the adjtime(2) system call even when the system is secure. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettttiimmeeooffddaayy() and sseettttiimmeeooffddaayy() will succeed unless: [EFAULT] An argument address referenced invalid memory. In addition, sseettttiimmeeooffddaayy() may return the following error: [EPERM] A user other than the superuser attempted to set the time. SSEEEE AALLSSOO date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3) SSTTAANNDDAARRDDSS The ggeettttiimmeeooffddaayy() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY As predecessors of these functions, former system calls ttiimmee() and ssttiimmee() first appeared in Version 1 AT&T UNIX, and ffttiimmee() first appeared in Version 7 AT&T UNIX. The ggeettttiimmeeooffddaayy() and sseettttiimmeeooffddaayy() system calls first appeared in 4.1cBSD. CCAAVVEEAATTSS Setting the time with sseettttiimmeeooffddaayy() is dangerous; if possible use adjtime(2) instead. Many daemon programming techniques utilize time- delta techniques using the results from ggeettttiimmeeooffddaayy() instead of from clock_gettime(2) on the CLOCK_MONOTONIC clock. Time jumps can cause these programs to malfunction in unexpected ways. If the time must be set, consider rebooting the machine for safety. NNAAMMEE ggeettuuiidd, ggeetteeuuiidd - get user identification SSYYNNOOPPSSIISS ##iinncclluuddee <> _u_i_d___t ggeettuuiidd(_v_o_i_d); _u_i_d___t ggeetteeuuiidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The ggeettuuiidd() function returns the real user ID of the calling process. The ggeetteeuuiidd() function returns the effective user ID of the calling process. The real user ID is that of the user who has invoked the program. As the effective user ID gives the process additional permissions during execution of ``_s_e_t_-_u_s_e_r_-_I_D'' mode processes, ggeettuuiidd() is used to determine the real user ID of the calling process. EERRRROORRSS The ggeettuuiidd() and ggeetteeuuiidd() functions are always successful, and no return value is reserved to indicate an error. SSEEEE AALLSSOO getgid(2), getresuid(2), setreuid(2), setuid(2) SSTTAANNDDAARRDDSS The ggeettuuiidd() and ggeetteeuuiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettuuiidd() system call first appeared in Version 1 AT&T UNIX, and ggeetteeuuiidd() in Version 7 AT&T UNIX. NNAAMMEE ii338866__ggeett__ffssbbaassee, ii338866__sseett__ffssbbaassee - manage i386 per-thread %fs base address SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__ggeett__ffssbbaassee(_v_o_i_d _*_*_b_a_s_e); _i_n_t ii338866__sseett__ffssbbaassee(_v_o_i_d _*_b_a_s_e); DDEESSCCRRIIPPTTIIOONN ii338866__ggeett__ffssbbaassee() copies the current base address of the segment that, by default, is referenced by the %fs selector into the memory referenced by _b_a_s_e. ii338866__sseett__ffssbbaassee() sets the base address of the segment that, by default, is referenced by %fs to the address _b_a_s_e. The segment base address is local to each thread. The initial thread of a new process inherits its segment base address from the parent thread. __tfork(2) sets the initial segment base address for threads that it creates. NNoottee:: Code using the ii338866__ggeett__ffssbbaassee() and ii338866__sseett__ffssbbaassee() functions must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__ggeett__ffssbbaassee() and ii338866__sseett__ffssbbaassee() return 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__ggeett__ffssbbaassee() will fail if: [EFAULT] _b_a_s_e points outside the process's allocated address space. SSEEEE AALLSSOO __tfork(2), fork(2) Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. NNAAMMEE ii338866__ggeett__ggssbbaassee, ii338866__sseett__ggssbbaassee - manage i386 per-thread %gs base address SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__ggeett__ggssbbaassee(_v_o_i_d _*_*_b_a_s_e); _i_n_t ii338866__sseett__ggssbbaassee(_v_o_i_d _*_b_a_s_e); DDEESSCCRRIIPPTTIIOONN ii338866__ggeett__ggssbbaassee() copies the current base address of the segment that, by default, is referenced by the %gs selector into the memory referenced by _b_a_s_e. ii338866__sseett__ggssbbaassee() sets the base address of the segment that, by default, is referenced by %gs to the address _b_a_s_e. The segment base address is local to each thread. The initial thread of a new process inherits its segment base address from the parent thread. __tfork(2) sets the initial segment base address for threads that it creates. NNoottee:: Code using the ii338866__ggeett__ggssbbaassee() and ii338866__sseett__ggssbbaassee() functions must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__ggeett__ggssbbaassee() and ii338866__sseett__ggssbbaassee() return 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__ggeett__ggssbbaassee() will fail if: [EFAULT] _b_a_s_e points outside the process's allocated address space. SSEEEE AALLSSOO __tfork(2), fork(2) Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. WWAARRNNIINNGG The ELF Thread-Local Storage ABI reserves %gs for its own use and requires that the dynamic linker and thread library set it to reference data-structures internal to and shared between them. Programs should use the __thread storage class keyword instead of using these calls. To be maximally portable, programs that require per-thread data should use the pptthhrreeaadd__kkeeyy__ccrreeaattee() interface. NNAAMMEE ii338866__ggeett__iiooppeerrmm, ii338866__sseett__iiooppeerrmm - manage i386 per-process I/O permission bitmap SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__ggeett__iiooppeerrmm(_u___l_o_n_g _*_i_o_m_a_p); _i_n_t ii338866__sseett__iiooppeerrmm(_u___l_o_n_g _*_i_o_m_a_p); DDEESSCCRRIIPPTTIIOONN ii338866__ggeett__iiooppeerrmm() copies the current I/O permission bitmap into the memory referenced by _i_o_m_a_p. ii338866__sseett__iiooppeerrmm() sets the I/O permission bitmap from the data pointed to by _i_o_m_a_p. This call may only be made by the superuser. Additionally, it is only permitted when the securelevel(7) is less than or equal to 0 or the _m_a_c_h_d_e_p_._a_l_l_o_w_a_p_e_r_t_u_r_e sysctl has been set to a non-zero value. The permission bitmap contains 1024 bits in 32 longwords. If bit _n is clear in the bitmap, then access is granted to I/O port _n. If bit _n is set in the bitmap, then an attempt to access I/O port _n results in delivery of a SIGBUS signal unless the process's I/O permission level would grant I/O access. NNoottee:: Code using the ii338866__ggeett__iiooppeerrmm() and ii338866__sseett__iiooppeerrmm() functions must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__ggeett__iiooppeerrmm() and ii338866__sseett__iiooppeerrmm() return 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__ggeett__iiooppeerrmm() and ii338866__sseett__iiooppeerrmm() will fail if: [EFAULT] _i_o_m_a_p points outside the process's allocated address space. Additionally ii338866__sseett__iiooppeerrmm() will fail if: [EPERM] The caller was not the superuser, or the securelevel is greater than zero and _m_a_c_h_d_e_p_._a_l_l_o_w_a_p_e_r_t_u_r_e has not been set to a non- zero value. SSEEEE AALLSSOO i386_iopl(2) Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. WWAARRNNIINNGG You can really hose your machine if you enable user-level I/O and write to hardware ports without care. BBUUGGSS The bitmap should really cover 65536 bits, but that's just too big for allocation in a kernel structure. If you need access to ports beyond 1024, use i386_iopl(2). NNAAMMEE ii338866__ggeett__llddtt, ii338866__sseett__llddtt - manage i386 per-process Local Descriptor Table entries SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__ggeett__llddtt(_i_n_t _s_t_a_r_t___s_e_l, _u_n_i_o_n _d_e_s_c_r_i_p_t_o_r _*_d_e_s_c_s, _i_n_t _n_u_m___s_e_l_s); _i_n_t ii338866__sseett__llddtt(_i_n_t _s_t_a_r_t___s_e_l, _u_n_i_o_n _d_e_s_c_r_i_p_t_o_r _*_d_e_s_c_s, _i_n_t _n_u_m___s_e_l_s); DDEESSCCRRIIPPTTIIOONN ii338866__ggeett__llddtt() returns a list of the i386 descriptors in the current process' LDT. ii338866__sseett__llddtt() sets a list of i386 descriptors in the current process' LDT. For both routines, _s_t_a_r_t___s_e_l specifies the index of the selector in the LDT at which to begin and _d_e_s_c_s points to an array of _n_u_m___s_e_l_s descriptors to be set or returned. Each entry in the _d_e_s_c_s array can be either a segment_descriptor or a gate_descriptor, as defined in <_i_3_8_6_/_s_e_g_m_e_n_t_s_._h>. These structures are defined by the architecture as disjoint bit-fields, so care must be taken in constructing them. Before this API can be used the functionality has to be enabled using the machdep.userldt sysctl(8) variable. NNoottee:: Code using the ii338866__ggeett__llddtt() and ii338866__sseett__llddtt() functions must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__ggeett__llddtt() returns the number of i386 descriptors copied into _d_e_s_c_s from the current process' LDT. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. Upon successful completion, ii338866__sseett__llddtt() returns the first selector set; if the kernel allocated a descriptor in the LDT, the allocated index is returned. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__ggeett__llddtt() and ii338866__sseett__llddtt() will fail if: [EINVAL] An inappropriate parameter was used for _s_t_a_r_t___s_e_l or _n_u_m___s_e_l_s. [EACCES] The caller attempted to use a descriptor that would circumvent protection or cause a failure. RREEFFEERREENNCCEESS Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. WWAARRNNIINNGG You can really hose your process using this. NNAAMMEE ii338866__iiooppll - change the i386 I/O privilege level SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__iiooppll(_i_n_t _i_o_p_l); DDEESSCCRRIIPPTTIIOONN ii338866__iiooppll() sets the i386 I/O privilege level to the value specified by _i_o_p_l. This call may only be made by the superuser. Additionally, it is only permitted when the securelevel(7) is less than or equal to 0 or the _m_a_c_h_d_e_p_._a_l_l_o_w_a_p_e_r_t_u_r_e sysctl has been set to a non-zero value. NNoottee:: Code using the ii338866__iiooppll() function must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__iiooppll() returns 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__iiooppll() will fail if: [EPERM] The caller was not the superuser, or the securelevel is greater than zero and _m_a_c_h_d_e_p_._a_l_l_o_w_a_p_e_r_t_u_r_e has not been set to a non- zero value. SSEEEE AALLSSOO i386_get_ioperm(2), securelevel(7) RREEFFEERREENNCCEESS Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. WWAARRNNIINNGG You can really hose your machine if you enable user-level I/O and write to hardware ports without care. NNAAMMEE ii338866__ggeett__ffssbbaassee, ii338866__sseett__ffssbbaassee - manage i386 per-thread %fs base address SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__ggeett__ffssbbaassee(_v_o_i_d _*_*_b_a_s_e); _i_n_t ii338866__sseett__ffssbbaassee(_v_o_i_d _*_b_a_s_e); DDEESSCCRRIIPPTTIIOONN ii338866__ggeett__ffssbbaassee() copies the current base address of the segment that, by default, is referenced by the %fs selector into the memory referenced by _b_a_s_e. ii338866__sseett__ffssbbaassee() sets the base address of the segment that, by default, is referenced by %fs to the address _b_a_s_e. The segment base address is local to each thread. The initial thread of a new process inherits its segment base address from the parent thread. __tfork(2) sets the initial segment base address for threads that it creates. NNoottee:: Code using the ii338866__ggeett__ffssbbaassee() and ii338866__sseett__ffssbbaassee() functions must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__ggeett__ffssbbaassee() and ii338866__sseett__ffssbbaassee() return 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__ggeett__ffssbbaassee() will fail if: [EFAULT] _b_a_s_e points outside the process's allocated address space. SSEEEE AALLSSOO __tfork(2), fork(2) Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. NNAAMMEE ii338866__ggeett__ggssbbaassee, ii338866__sseett__ggssbbaassee - manage i386 per-thread %gs base address SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__ggeett__ggssbbaassee(_v_o_i_d _*_*_b_a_s_e); _i_n_t ii338866__sseett__ggssbbaassee(_v_o_i_d _*_b_a_s_e); DDEESSCCRRIIPPTTIIOONN ii338866__ggeett__ggssbbaassee() copies the current base address of the segment that, by default, is referenced by the %gs selector into the memory referenced by _b_a_s_e. ii338866__sseett__ggssbbaassee() sets the base address of the segment that, by default, is referenced by %gs to the address _b_a_s_e. The segment base address is local to each thread. The initial thread of a new process inherits its segment base address from the parent thread. __tfork(2) sets the initial segment base address for threads that it creates. NNoottee:: Code using the ii338866__ggeett__ggssbbaassee() and ii338866__sseett__ggssbbaassee() functions must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__ggeett__ggssbbaassee() and ii338866__sseett__ggssbbaassee() return 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__ggeett__ggssbbaassee() will fail if: [EFAULT] _b_a_s_e points outside the process's allocated address space. SSEEEE AALLSSOO __tfork(2), fork(2) Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. WWAARRNNIINNGG The ELF Thread-Local Storage ABI reserves %gs for its own use and requires that the dynamic linker and thread library set it to reference data-structures internal to and shared between them. Programs should use the __thread storage class keyword instead of using these calls. To be maximally portable, programs that require per-thread data should use the pptthhrreeaadd__kkeeyy__ccrreeaattee() interface. NNAAMMEE ii338866__ggeett__iiooppeerrmm, ii338866__sseett__iiooppeerrmm - manage i386 per-process I/O permission bitmap SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__ggeett__iiooppeerrmm(_u___l_o_n_g _*_i_o_m_a_p); _i_n_t ii338866__sseett__iiooppeerrmm(_u___l_o_n_g _*_i_o_m_a_p); DDEESSCCRRIIPPTTIIOONN ii338866__ggeett__iiooppeerrmm() copies the current I/O permission bitmap into the memory referenced by _i_o_m_a_p. ii338866__sseett__iiooppeerrmm() sets the I/O permission bitmap from the data pointed to by _i_o_m_a_p. This call may only be made by the superuser. Additionally, it is only permitted when the securelevel(7) is less than or equal to 0 or the _m_a_c_h_d_e_p_._a_l_l_o_w_a_p_e_r_t_u_r_e sysctl has been set to a non-zero value. The permission bitmap contains 1024 bits in 32 longwords. If bit _n is clear in the bitmap, then access is granted to I/O port _n. If bit _n is set in the bitmap, then an attempt to access I/O port _n results in delivery of a SIGBUS signal unless the process's I/O permission level would grant I/O access. NNoottee:: Code using the ii338866__ggeett__iiooppeerrmm() and ii338866__sseett__iiooppeerrmm() functions must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__ggeett__iiooppeerrmm() and ii338866__sseett__iiooppeerrmm() return 0. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__ggeett__iiooppeerrmm() and ii338866__sseett__iiooppeerrmm() will fail if: [EFAULT] _i_o_m_a_p points outside the process's allocated address space. Additionally ii338866__sseett__iiooppeerrmm() will fail if: [EPERM] The caller was not the superuser, or the securelevel is greater than zero and _m_a_c_h_d_e_p_._a_l_l_o_w_a_p_e_r_t_u_r_e has not been set to a non- zero value. SSEEEE AALLSSOO i386_iopl(2) Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. WWAARRNNIINNGG You can really hose your machine if you enable user-level I/O and write to hardware ports without care. BBUUGGSS The bitmap should really cover 65536 bits, but that's just too big for allocation in a kernel structure. If you need access to ports beyond 1024, use i386_iopl(2). NNAAMMEE ii338866__ggeett__llddtt, ii338866__sseett__llddtt - manage i386 per-process Local Descriptor Table entries SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__ggeett__llddtt(_i_n_t _s_t_a_r_t___s_e_l, _u_n_i_o_n _d_e_s_c_r_i_p_t_o_r _*_d_e_s_c_s, _i_n_t _n_u_m___s_e_l_s); _i_n_t ii338866__sseett__llddtt(_i_n_t _s_t_a_r_t___s_e_l, _u_n_i_o_n _d_e_s_c_r_i_p_t_o_r _*_d_e_s_c_s, _i_n_t _n_u_m___s_e_l_s); DDEESSCCRRIIPPTTIIOONN ii338866__ggeett__llddtt() returns a list of the i386 descriptors in the current process' LDT. ii338866__sseett__llddtt() sets a list of i386 descriptors in the current process' LDT. For both routines, _s_t_a_r_t___s_e_l specifies the index of the selector in the LDT at which to begin and _d_e_s_c_s points to an array of _n_u_m___s_e_l_s descriptors to be set or returned. Each entry in the _d_e_s_c_s array can be either a segment_descriptor or a gate_descriptor, as defined in <_i_3_8_6_/_s_e_g_m_e_n_t_s_._h>. These structures are defined by the architecture as disjoint bit-fields, so care must be taken in constructing them. Before this API can be used the functionality has to be enabled using the machdep.userldt sysctl(8) variable. NNoottee:: Code using the ii338866__ggeett__llddtt() and ii338866__sseett__llddtt() functions must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS Upon successful completion, ii338866__ggeett__llddtt() returns the number of i386 descriptors copied into _d_e_s_c_s from the current process' LDT. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. Upon successful completion, ii338866__sseett__llddtt() returns the first selector set; if the kernel allocated a descriptor in the LDT, the allocated index is returned. Otherwise, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__ggeett__llddtt() and ii338866__sseett__llddtt() will fail if: [EINVAL] An inappropriate parameter was used for _s_t_a_r_t___s_e_l or _n_u_m___s_e_l_s. [EACCES] The caller attempted to use a descriptor that would circumvent protection or cause a failure. RREEFFEERREENNCCEESS Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. WWAARRNNIINNGG You can really hose your process using this. NNAAMMEE ii338866__vvmm8866 - set virtual 8086 processor registers and mode SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ii338866__vvmm8866(_s_t_r_u_c_t _v_m_8_6___s_t_r_u_c_t _*_v_m_c_p); DDEESSCCRRIIPPTTIIOONN ii338866__vvmm8866() will set the process into virtual 8086 mode using the registers and selectors specified by the context pointed to by _v_m_c_p. The processor registers are set from _v_m_c_p_-_>_s_u_b_s_t_r_._r_e_g_s, and the emulated processor type from _v_m_c_p_-_>_s_u_b_s_t_r_._s_s___c_p_u___t_y_p_e. The kernel keeps a pointer to the context, and uses the tables stored at _v_m_c_p_-_>_i_n_t___b_y_u_s_e_r and _v_m_c_p_-_>_i_n_t_2_1___b_y_u_s_e_r for fast virtual interrupt handling. If the _nth bit is clear in the first of these arrays, then the kernel may directly emulate the real-mode x86 INT _n instruction handling. If the _nth bit is set, then the process is delivered a signal when an INT instruction is executed. Since MS-DOS puts many DOS functions onto interrupt 21, it is handled specially: the _kth bit in the _v_m_c_p_-_>_i_n_t_2_1___b_y_u_s_e_r array is checked when INT _2_1 is requested and the _a_h register is _k. NNoottee:: Code using the ii338866__vvmm8866() function must be compiled using --llii338866. RREETTUURRNN VVAALLUUEESS This routine does not normally return: 32-bit mode will be restored by the delivery of a signal to the process. In case of an error in setting the VM86 mode, a value of -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ii338866__vvmm8866() will fail if: [EFAULT] The state at _v_m_c_p was not readable to the user process. RREEFFEERREENNCCEESS Intel, _i_3_8_6 _M_i_c_r_o_p_r_o_c_e_s_s_o_r _P_r_o_g_r_a_m_m_e_r_'_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. NNAAMMEE iinnttrroo - introduction to system calls and error numbers SSYYNNOOPPSSIISS ##iinncclluuddee <> DDEESSCCRRIIPPTTIIOONN The manual pages in section 2 provide an overview of the system calls, their error returns, and other common definitions and concepts. DDIIAAGGNNOOSSTTIICCSS Nearly all of the system calls provide an error number via the identifier errno, which expands to an addressable location of type _i_n_t. The address of _e_r_r_n_o in each thread is guaranteed to be unique for the lifetime of the thread. Applications must use _e_r_r_n_o as defined in <_e_r_r_n_o_._h> and not attempt to use a custom definition. When a system call detects an error, it returns an integer value indicating failure (usually -1) and sets the variable _e_r_r_n_o accordingly. (This allows interpretation of the failure on receiving a -1 and to take action accordingly.) Successful calls never set _e_r_r_n_o; once set, it remains until another error occurs. It should only be examined after an error. Note that a number of system calls overload the meanings of these error numbers, and that the meanings must be interpreted according to the type and circumstances of the call. The following is a complete list of the errors and their names as given in <_s_y_s_/_e_r_r_n_o_._h>. 0 _U_n_d_e_f_i_n_e_d _e_r_r_o_r_: _0. Not used. 1 EPERM _O_p_e_r_a_t_i_o_n _n_o_t _p_e_r_m_i_t_t_e_d. An attempt was made to perform an operation limited to processes with appropriate privileges or to the owner of a file or other resources. 2 ENOENT _N_o _s_u_c_h _f_i_l_e _o_r _d_i_r_e_c_t_o_r_y. A component of a specified pathname did not exist, or the pathname was an empty string. 3 ESRCH _N_o _s_u_c_h _p_r_o_c_e_s_s. No process could be found which corresponds to the given process ID. 4 EINTR _I_n_t_e_r_r_u_p_t_e_d _s_y_s_t_e_m _c_a_l_l. An asynchronous signal (such as SIGINT or SIGQUIT) was caught by the thread during the execution of an interruptible function. If the signal handler performs a normal return, the interrupted function call will seem to have returned the error condition. 5 EIO _I_n_p_u_t_/_o_u_t_p_u_t _e_r_r_o_r. Some physical input or output error occurred. This error will not be reported until a subsequent operation on the same file descriptor and may be lost (overwritten) by any subsequent errors. 6 ENXIO _D_e_v_i_c_e _n_o_t _c_o_n_f_i_g_u_r_e_d. Input or output on a special file referred to a device that did not exist, or made a request beyond the limits of the device. This error may also occur when, for example, a tape drive is not online or no disk pack is loaded on a drive. 7 E2BIG _A_r_g_u_m_e_n_t _l_i_s_t _t_o_o _l_o_n_g. The number of bytes used for the argument and environment list of the new process exceeded the limit NCARGS (specified in <_s_y_s_/_p_a_r_a_m_._h>). 8 ENOEXEC _E_x_e_c _f_o_r_m_a_t _e_r_r_o_r. A request was made to execute a file that, although it has the appropriate permissions, was not in the format required for an executable file. 9 EBADF _B_a_d _f_i_l_e _d_e_s_c_r_i_p_t_o_r. A file descriptor argument was out of range, referred to no open file, or a read (write) request was made to a file that was only open for writing (reading). 10 ECHILD _N_o _c_h_i_l_d _p_r_o_c_e_s_s_e_s. A wait(2) or waitpid(2) function was executed by a process that had no existing or unwaited-for child processes. 11 EDEADLK _R_e_s_o_u_r_c_e _d_e_a_d_l_o_c_k _a_v_o_i_d_e_d. An attempt was made to lock a system resource that would have resulted in a deadlock situation. 12 ENOMEM _C_a_n_n_o_t _a_l_l_o_c_a_t_e _m_e_m_o_r_y. The new process image required more memory than was allowed by the hardware or by system-imposed memory management constraints. A lack of swap space is normally temporary; however, a lack of core is not. Soft limits may be increased to their corresponding hard limits. 13 EACCES _P_e_r_m_i_s_s_i_o_n _d_e_n_i_e_d. An attempt was made to access a file in a way forbidden by its file access permissions. 14 EFAULT _B_a_d _a_d_d_r_e_s_s. The system detected an invalid address in attempting to use an argument of a call. 15 ENOTBLK _B_l_o_c_k _d_e_v_i_c_e _r_e_q_u_i_r_e_d. A block device operation was attempted on a non-block device or file. 16 EBUSY _D_e_v_i_c_e _b_u_s_y. An attempt to use a system resource which was in use at the time in a manner which would have conflicted with the request. 17 EEXIST _F_i_l_e _e_x_i_s_t_s. An existing file was mentioned in an inappropriate context, for instance, as the new link name in a link(2) function. 18 EXDEV _C_r_o_s_s_-_d_e_v_i_c_e _l_i_n_k. A hard link to a file on another file system was attempted. 19 ENODEV _O_p_e_r_a_t_i_o_n _n_o_t _s_u_p_p_o_r_t_e_d _b_y _d_e_v_i_c_e. An attempt was made to apply an inappropriate function to a device, for example, trying to read a write-only device such as a printer. 20 ENOTDIR _N_o_t _a _d_i_r_e_c_t_o_r_y. A component of the specified pathname existed, but it was not a directory, when a directory was expected. 21 EISDIR _I_s _a _d_i_r_e_c_t_o_r_y. An attempt was made to open a directory with write mode specified. 22 EINVAL _I_n_v_a_l_i_d _a_r_g_u_m_e_n_t. Some invalid argument was supplied. (For example, specifying an undefined signal to a signal(3) or kill(2) function). 23 ENFILE _T_o_o _m_a_n_y _o_p_e_n _f_i_l_e_s _i_n _s_y_s_t_e_m. Maximum number of file descriptors allowable on the system has been reached and a request for an open cannot be satisfied until at least one has been closed. The sysctl(3) variable _k_e_r_n_._m_a_x_f_i_l_e_s contains the current limit. 24 EMFILE _T_o_o _m_a_n_y _o_p_e_n _f_i_l_e_s. The maximum number of file descriptors allowable for this process has been reached and a request for an open cannot be satisfied until at least one has been closed. getdtablesize(3) will obtain the current limit. 25 ENOTTY _I_n_a_p_p_r_o_p_r_i_a_t_e _i_o_c_t_l _f_o_r _d_e_v_i_c_e. A control function (see ioctl(2)) was attempted for a file or special device for which the operation was inappropriate. 26 ETXTBSY _T_e_x_t _f_i_l_e _b_u_s_y. An attempt was made either to execute a pure procedure (shared text) file which was open for writing by another process, or to open with write access a pure procedure file that is currently being executed. 27 EFBIG _F_i_l_e _t_o_o _l_a_r_g_e. The size of a file exceeded the maximum. (The system-wide maximum file size is 2**63 bytes. Each file system may impose a lower limit for files contained within it.) 28 ENOSPC _N_o _s_p_a_c_e _l_e_f_t _o_n _d_e_v_i_c_e. A write(2) to an ordinary file, the creation of a directory or symbolic link, or the creation of a directory entry failed because no more disk blocks were available on the file system, or the allocation of an inode for a newly created file failed because no more inodes were available on the file system. 29 ESPIPE _I_l_l_e_g_a_l _s_e_e_k. An lseek(2) function was issued on a socket, pipe or FIFO. 30 EROFS _R_e_a_d_-_o_n_l_y _f_i_l_e _s_y_s_t_e_m. An attempt was made to modify a file or create a directory on a file system that was read-only at the time. 31 EMLINK _T_o_o _m_a_n_y _l_i_n_k_s. The maximum allowable number of hard links to a single file has been exceeded (see pathconf(2) for how to obtain this value). 32 EPIPE _B_r_o_k_e_n _p_i_p_e. A write on a pipe, socket or FIFO for which there is no process to read the data. 33 EDOM _N_u_m_e_r_i_c_a_l _a_r_g_u_m_e_n_t _o_u_t _o_f _d_o_m_a_i_n. A numerical input argument was outside the defined domain of the mathematical function. 34 ERANGE _R_e_s_u_l_t _t_o_o _l_a_r_g_e. A result of the function was too large to fit in the available space (perhaps exceeded precision). 35 EAGAIN _R_e_s_o_u_r_c_e _t_e_m_p_o_r_a_r_i_l_y _u_n_a_v_a_i_l_a_b_l_e. This is a temporary condition and later calls to the same routine may complete normally. 36 EINPROGRESS _O_p_e_r_a_t_i_o_n _n_o_w _i_n _p_r_o_g_r_e_s_s. An operation that takes a long time to complete (such as a connect(2)) was attempted on a non- blocking object (see fcntl(2)). 37 EALREADY _O_p_e_r_a_t_i_o_n _a_l_r_e_a_d_y _i_n _p_r_o_g_r_e_s_s. An operation was attempted on a non-blocking object that already had an operation in progress. 38 ENOTSOCK _S_o_c_k_e_t _o_p_e_r_a_t_i_o_n _o_n _n_o_n_-_s_o_c_k_e_t. Self-explanatory. 39 EDESTADDRREQ _D_e_s_t_i_n_a_t_i_o_n _a_d_d_r_e_s_s _r_e_q_u_i_r_e_d. A required address was omitted from an operation on a socket. 40 EMSGSIZE _M_e_s_s_a_g_e _t_o_o _l_o_n_g. A message sent on a socket was larger than the internal message buffer or some other network limit. 41 EPROTOTYPE _P_r_o_t_o_c_o_l _w_r_o_n_g _t_y_p_e _f_o_r _s_o_c_k_e_t. A protocol was specified that does not support the semantics of the socket type requested. For example, you cannot use the Internet UDP protocol with type SOCK_STREAM. 42 ENOPROTOOPT _P_r_o_t_o_c_o_l _n_o_t _a_v_a_i_l_a_b_l_e. A bad option or level was specified in a getsockopt(2) or setsockopt(2) call. 43 EPROTONOSUPPORT _P_r_o_t_o_c_o_l _n_o_t _s_u_p_p_o_r_t_e_d. The protocol has not been configured into the system or no implementation for it exists. 44 ESOCKTNOSUPPORT _S_o_c_k_e_t _t_y_p_e _n_o_t _s_u_p_p_o_r_t_e_d. The support for the socket type has not been configured into the system or no implementation for it exists. 45 EOPNOTSUPP _O_p_e_r_a_t_i_o_n _n_o_t _s_u_p_p_o_r_t_e_d. The attempted operation is not supported for the type of object referenced. Usually this occurs when a file descriptor refers to a file or socket that cannot support this operation, for example, trying to _a_c_c_e_p_t a connection on a datagram socket. 46 EPFNOSUPPORT _P_r_o_t_o_c_o_l _f_a_m_i_l_y _n_o_t _s_u_p_p_o_r_t_e_d. The protocol family has not been configured into the system or no implementation for it exists. 47 EAFNOSUPPORT _A_d_d_r_e_s_s _f_a_m_i_l_y _n_o_t _s_u_p_p_o_r_t_e_d _b_y _p_r_o_t_o_c_o_l _f_a_m_i_l_y. An address incompatible with the requested protocol was used. For example, you shouldn't necessarily expect to be able to use NS addresses with Internet protocols. 48 EADDRINUSE _A_d_d_r_e_s_s _a_l_r_e_a_d_y _i_n _u_s_e. Only one usage of each address is normally permitted. 49 EADDRNOTAVAIL _C_a_n_'_t _a_s_s_i_g_n _r_e_q_u_e_s_t_e_d _a_d_d_r_e_s_s. Normally results from an attempt to create a socket with an address not on this machine. 50 ENETDOWN _N_e_t_w_o_r_k _i_s _d_o_w_n. A socket operation encountered a dead network. 51 ENETUNREACH _N_e_t_w_o_r_k _i_s _u_n_r_e_a_c_h_a_b_l_e. A socket operation was attempted to an unreachable network. 52 ENETRESET _N_e_t_w_o_r_k _d_r_o_p_p_e_d _c_o_n_n_e_c_t_i_o_n _o_n _r_e_s_e_t. The host you were connected to crashed and rebooted. 53 ECONNABORTED _S_o_f_t_w_a_r_e _c_a_u_s_e_d _c_o_n_n_e_c_t_i_o_n _a_b_o_r_t. A connection abort was caused internal to your host machine. 54 ECONNRESET _C_o_n_n_e_c_t_i_o_n _r_e_s_e_t _b_y _p_e_e_r. A connection was forcibly closed by a peer. This normally results from a loss of the connection on the remote socket due to a timeout or a reboot. 55 ENOBUFS _N_o _b_u_f_f_e_r _s_p_a_c_e _a_v_a_i_l_a_b_l_e. An operation on a socket or pipe was not performed because the system lacked sufficient buffer space or because a queue was full. 56 EISCONN _S_o_c_k_e_t _i_s _a_l_r_e_a_d_y _c_o_n_n_e_c_t_e_d. A connect(2) request was made on an already connected socket; or, a sendto(2) or sendmsg(2) request on a connected socket specified a destination when already connected. 57 ENOTCONN _S_o_c_k_e_t _i_s _n_o_t _c_o_n_n_e_c_t_e_d. A request to send or receive data was disallowed because the socket was not connected and (when sending on a datagram socket) no address was supplied. 58 ESHUTDOWN _C_a_n_'_t _s_e_n_d _a_f_t_e_r _s_o_c_k_e_t _s_h_u_t_d_o_w_n. A request to send data was disallowed because the socket had already been shut down with a previous shutdown(2) call. 59 ETOOMANYREFS _T_o_o _m_a_n_y _r_e_f_e_r_e_n_c_e_s_: _c_a_n_'_t _s_p_l_i_c_e. Not used in OpenBSD. 60 ETIMEDOUT _O_p_e_r_a_t_i_o_n _t_i_m_e_d _o_u_t. A connect(2) or send(2) request failed because the connected party did not properly respond after a period of time. (The timeout period is dependent on the communication protocol.) 61 ECONNREFUSED _C_o_n_n_e_c_t_i_o_n _r_e_f_u_s_e_d. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host. 62 ELOOP _T_o_o _m_a_n_y _l_e_v_e_l_s _o_f _s_y_m_b_o_l_i_c _l_i_n_k_s. A path name lookup involved more than 32 (SYMLOOP_MAX) symbolic links. 63 ENAMETOOLONG _F_i_l_e _n_a_m_e _t_o_o _l_o_n_g. A component of a pathname exceeded 255 (NAME_MAX) characters, or an entire pathname (including the terminating NUL) exceeded 1024 (PATH_MAX) bytes. 64 EHOSTDOWN _H_o_s_t _i_s _d_o_w_n. A socket operation failed because the destination host was down. 65 EHOSTUNREACH _N_o _r_o_u_t_e _t_o _h_o_s_t. A socket operation was attempted to an unreachable host. 66 ENOTEMPTY _D_i_r_e_c_t_o_r_y _n_o_t _e_m_p_t_y. A directory with entries other than `.' and `..' was supplied to a remove directory or rename call. 67 EPROCLIM _T_o_o _m_a_n_y _p_r_o_c_e_s_s_e_s. 68 EUSERS _T_o_o _m_a_n_y _u_s_e_r_s. The quota system ran out of table entries. 69 EDQUOT _D_i_s_c _q_u_o_t_a _e_x_c_e_e_d_e_d. A write(2) to an ordinary file, the creation of a directory or symbolic link, or the creation of a directory entry failed because the user's quota of disk blocks was exhausted, or the allocation of an inode for a newly created file failed because the user's quota of inodes was exhausted. 70 ESTALE _S_t_a_l_e _N_F_S _f_i_l_e _h_a_n_d_l_e. An attempt was made to access an open file on an NFS filesystem which is now unavailable as referenced by the file descriptor. This may indicate the file was deleted on the NFS server or some other catastrophic event occurred. 72 EBADRPC _R_P_C _s_t_r_u_c_t _i_s _b_a_d. Exchange of rpc(3) information was unsuccessful. 73 ERPCMISMATCH _R_P_C _v_e_r_s_i_o_n _w_r_o_n_g. The version of rpc(3) on the remote peer is not compatible with the local version. 74 EPROGUNAVAIL _R_P_C _p_r_o_g_. _n_o_t _a_v_a_i_l. The requested rpc(3) program is not registered on the remote host. 75 EPROGMISMATCH _P_r_o_g_r_a_m _v_e_r_s_i_o_n _w_r_o_n_g. The requested version of the rpc(3) program is not available on the remote host. 76 EPROCUNAVAIL _B_a_d _p_r_o_c_e_d_u_r_e _f_o_r _p_r_o_g_r_a_m. An rpc(3) call was attempted for a procedure which doesn't exist in the remote program. 77 ENOLCK _N_o _l_o_c_k_s _a_v_a_i_l_a_b_l_e. A system-imposed limit on the number of simultaneous file locks was reached. 78 ENOSYS _F_u_n_c_t_i_o_n _n_o_t _i_m_p_l_e_m_e_n_t_e_d. Attempted a system call that is not available on this system. 79 EFTYPE _I_n_a_p_p_r_o_p_r_i_a_t_e _f_i_l_e _t_y_p_e _o_r _f_o_r_m_a_t. The file contains invalid data or set to invalid modes. 80 EAUTH _A_u_t_h_e_n_t_i_c_a_t_i_o_n _e_r_r_o_r. Attempted to use an invalid authentication ticket to mount a NFS filesystem. 81 ENEEDAUTH _N_e_e_d _a_u_t_h_e_n_t_i_c_a_t_o_r. An authentication ticket must be obtained before the given NFS filesystem may be mounted. 82 EIPSEC _I_P_s_e_c _p_r_o_c_e_s_s_i_n_g _f_a_i_l_u_r_e. IPsec subsystem error. Not used in OpenBSD. 83 ENOATTR _A_t_t_r_i_b_u_t_e _n_o_t _f_o_u_n_d. A UFS Extended Attribute is not found for the specified pathname. 84 EILSEQ _I_l_l_e_g_a_l _b_y_t_e _s_e_q_u_e_n_c_e. An illegal sequence of bytes was used when using wide characters. 85 ENOMEDIUM _N_o _m_e_d_i_u_m _f_o_u_n_d. Attempted to use a removable media device with no medium present. 86 EMEDIUMTYPE _W_r_o_n_g _m_e_d_i_u_m _t_y_p_e. Attempted to use a removable media device with incorrect or incompatible medium. 87 EOVERFLOW _V_a_l_u_e _t_o_o _l_a_r_g_e _t_o _b_e _s_t_o_r_e_d _i_n _d_a_t_a _t_y_p_e. A numerical result of the function was too large to be stored in the caller provided space. 88 ECANCELED _O_p_e_r_a_t_i_o_n _c_a_n_c_e_l_e_d. The requested operation was canceled. 89 EIDRM _I_d_e_n_t_i_f_i_e_r _r_e_m_o_v_e_d. An IPC identifier was removed while the current thread was waiting on it. 90 ENOMSG _N_o _m_e_s_s_a_g_e _o_f _d_e_s_i_r_e_d _t_y_p_e. An IPC message queue does not contain a message of the desired type, or a message catalog does not contain the requested message. 91 ENOTSUP _N_o_t _s_u_p_p_o_r_t_e_d. The operation has requested an unsupported value. DDEEFFIINNIITTIIOONNSS Process A process is a collection of one or more threads, plus the resources shared by those threads such as process ID, address space, user IDs and group IDs, and root directory and current working directory. Process ID Each active process in the system is uniquely identified by a non-negative integer called a process ID. The range of this ID is from 1 to 32766. Parent Process ID A new process is created by a currently active process; (see fork(2)). The parent process ID of a process is initially the process ID of its creator. If the creating process exits, the parent process ID of each child is set to the ID of a system process, init(8). Process Group Each active process is a member of a process group that is identified by a non-negative integer called the process group ID. This is the process ID of the group leader. This grouping permits the signaling of related processes (see termios(4)) and the job control mechanisms of csh(1). Session A session is a set of one or more process groups. A session is created by a successful call to setsid(2), which causes the caller to become the only member of the only process group in the new session. Session Leader A process that has created a new session by a successful call to setsid(2), is known as a session leader. Only a session leader may acquire a terminal as its controlling terminal (see termios(4)). Controlling Process A session leader with a controlling terminal is a controlling process. Controlling Terminal A terminal that is associated with a session is known as the controlling terminal for that session and its members. Terminal Process Group ID A terminal may be acquired by a session leader as its controlling terminal. Once a terminal is associated with a session, any of the process groups within the session may be placed into the foreground by setting the terminal process group ID to the ID of the process group. This facility is used to arbitrate between multiple jobs contending for the same terminal; (see csh(1) and tty(4)). Orphaned Process Group A process group is considered to be _o_r_p_h_a_n_e_d if it is not under the control of a job control shell. More precisely, a process group is orphaned when none of its members has a parent process that is in the same session as the group, but is in a different process group. Note that when a process exits, the parent process for its children is changed to be init(8), which is in a separate session. Not all members of an orphaned process group are necessarily orphaned processes (those whose creating process has exited). The process group of a session leader is orphaned by definition. Thread A thread is a preemptively scheduled flow of control within a process, with its own set of register values, floating point environment, thread ID, signal mask, pending signal set, alternate signal stack, thread control block address, resource utilization, errno variable location, and values for thread- specific keys. A process initially has just one thread, a duplicate of the thread in the parent process that created this process. Real User ID and Real Group ID Each user on the system is identified by a positive integer termed the real user ID. Each user is also a member of one or more groups. One of these groups is distinguished from others and used in implementing accounting facilities. The positive integer corresponding to this distinguished group is termed the real group ID. All processes have a real user ID and real group ID. These are initialized from the equivalent attributes of the process that created it. Effective User ID, Effective Group ID, and Group Access List Access to system resources is governed by two values: the effective user ID, and the group access list. The first member of the group access list is also known as the effective group ID. (In POSIX.1, the group access list is known as the set of supplementary group IDs, and it is unspecified whether the effective group ID is a member of the list.) The effective user ID and effective group ID are initially the process's real user ID and real group ID respectively. Either may be modified through execution of a set-user-ID or set-group- ID file (possibly by one of its ancestors) (see execve(2)). By convention, the effective group ID (the first member of the group access list) is duplicated, so that the execution of a set-group- ID program does not result in the loss of the original (real) group ID. The group access list is a set of group IDs used only in determining resource accessibility. Access checks are performed as described below in ``File Access Permissions''. Saved Set User ID and Saved Set Group ID When a process executes a new file, the effective user ID is set to the owner of the file if the file is set-user-ID, and the effective group ID (first element of the group access list) is set to the group of the file if the file is set-group-ID. The effective user ID of the process is then recorded as the saved set-user-ID, and the effective group ID of the process is recorded as the saved set-group-ID. These values may be used to regain those values as the effective user or group ID after reverting to the real ID (see setuid(2)). (In POSIX.1, the saved set-user-ID and saved set-group-ID are optional, and are used in setuid and setgid, but this does not work as desired for the superuser.) Superuser A process is recognized as a _s_u_p_e_r_u_s_e_r process and is granted special privileges if its effective user ID is 0. Special Processes The processes with process IDs of 0 and 1 are special. Process 0 is the scheduler. Process 1 is the initialization process init(8), and is the ancestor of every other process in the system. It is used to control the process structure. Descriptor An integer assigned by the system when a file is referenced by open(2) or dup(2), or when a socket is created by pipe(2), socket(2) or socketpair(2), which uniquely identifies an access path to that file or socket from a given process or any of its children. File Name Names consisting of up to 255 (NAME_MAX) characters may be used to name an ordinary file, special file, or directory. These characters may be arbitrary eight-bit values, excluding 0 (NUL) and the ASCII code for `/' (slash). Note that it is generally unwise to use `*', `?', `[' or `]' as part of file names because of the special meaning attached to these characters by the shell. Note also that NAME_MAX is an upper limit fixed by the kernel, meant to be used for sizing buffers. Some filesystems may have additional restrictions. These can be queried using pathconf(2) and fpathconf(2). Path Name A path name is a NUL-terminated character string starting with an optional slash `/', followed by zero or more directory names separated by slashes, optionally followed by a file name. The total length of a path name must be less than 1024 (PATH_MAX) characters. Additional restrictions may apply, depending upon the filesystem, to be queried with pathconf(2) or fpathconf(2) if needed. If a path name begins with a slash, the path search begins at the _r_o_o_t directory. Otherwise, the search begins from the current working directory. A slash by itself names the root directory. An empty pathname is invalid. Directory A directory is a special type of file that contains entries that are references to other files. Directory entries are called links. By convention, a directory contains at least two links, `.' and `..', referred to as _d_o_t and _d_o_t_-_d_o_t respectively. Dot refers to the directory itself and dot-dot refers to its parent directory. Root Directory and Current Working Directory Each process has associated with it a concept of a root directory and a current working directory for the purpose of resolving path name searches. A process's root directory need not be the root directory of the root file system. File Access Permissions Every file in the file system has a set of access permissions. These permissions are used in determining whether a process may perform a requested operation on the file (such as opening a file for writing). Access permissions are established at the time a file is created. They may be changed at some later time through the chmod(2) call. File access is broken down according to whether a file may be: read, written, or executed. Directory files use the execute permission to control if the directory may be searched. File access permissions are interpreted by the system as they apply to three different classes of users: the owner of the file, those users in the file's group, anyone else. Every file has an independent set of access permissions for each of these classes. When an access check is made, the system decides if permission should be granted by checking the access information applicable to the caller. Read, write, and execute/search permissions on a file are granted to a process if: The process's effective user ID is that of the superuser. (Note: even the superuser cannot execute a non-executable file.) The process's effective user ID matches the user ID of the owner of the file and the owner permissions allow the access. The process's effective user ID does not match the user ID of the owner of the file, and either the process's effective group ID matches the group ID of the file, or the group ID of the file is in the process's group access list, and the group permissions allow the access. Neither the effective user ID nor effective group ID and group access list of the process match the corresponding user ID and group ID of the file, but the permissions for ``other users'' allow access. Otherwise, permission is denied. Sockets and Address Families A socket is an endpoint for communication between processes. Each socket has queues for sending and receiving data. Sockets are typed according to their communications properties. These properties include whether messages sent and received at a socket require the name of the partner, whether communication is reliable, the format used in naming message recipients, etc. Each instance of the system supports some collection of socket types; consult socket(2) for more information about the types available and their properties. Each instance of the system supports some number of sets of communications protocols. Each protocol set supports addresses of a certain format. An Address Family is the set of addresses for a specific group of protocols. Each socket has an address chosen from the address family in which the socket was created. SSEEEE AALLSSOO intro(3), perror(3) HHIISSTTOORRYY An kkqquueeuuee manual page appeared in Version 6 AT&T UNIX. NNAAMMEE iiooccttll - control device SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t iiooccttll(_i_n_t _d, _u_n_s_i_g_n_e_d _l_o_n_g _r_e_q_u_e_s_t, _._._.); DDEESSCCRRIIPPTTIIOONN The iiooccttll() function manipulates the underlying device parameters of special files. In particular, many operating characteristics of character special files (e.g., terminals) may be controlled with iiooccttll() requests. The argument _d must be an open file descriptor. The third argument is called _a_r_g and contains additional information needed by this device to perform the requested function. _a_r_g is either an int or a pointer to a device-specific data structure, depending upon the given _r_e_q_u_e_s_t. An kkqquueeuuee _r_e_q_u_e_s_t has encoded in it whether the argument is an ``in'' parameter or ``out'' parameter, and the size of the third argument (_a_r_g) in bytes. Macros and defines used in specifying an ioctl _r_e_q_u_e_s_t are located in the file <_s_y_s_/_i_o_c_t_l_._h>. GGEENNEERRIICC IIOOCCTTLLSS Some ioctls are applicable to any file descriptor. These include: FIOCLEX Set close-on-exec flag. The file will be closed when exec(3) is invoked. FIONCLEX Clear close-on-exec flag. The file will remain open across exec(3). Some generic ioctls are not implemented for all types of file descriptors. These include: FIONREAD _i_n_t _* Get the number of bytes that are immediately available for reading. FIONBIO _i_n_t _* Set non-blocking I/O mode if the argument is non-zero. In non- blocking mode, read(2) or write(2) calls return -1 and set _e_r_r_n_o to EAGAIN immediately when no data is available. FIOASYNC _i_n_t _* Set asynchronous I/O mode if the argument is non-zero. In asynchronous mode, the process or process group specified by FIOSETOWN will start receiving SIGIO signals when data is available. The SIGIO signal will be delivered when data is available on the file descriptor. FIOSETOWN, FIOGETOWN _i_n_t _* Set/get the process or the process group (if negative) that should receive SIGIO signals when data is available. RREETTUURRNN VVAALLUUEESS If an error has occurred, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS iiooccttll() will fail if: [EBADF] _d is not a valid descriptor. [ENOTTY] _d is not associated with a character special device. [ENOTTY] The specified request does not apply to the kind of object that the descriptor _d references. [EINVAL] _r_e_q_u_e_s_t or _a_r_g is not valid. [EFAULT] _a_r_g points outside the process's allocated address space. SSEEEE AALLSSOO cdio(1), chio(1), mt(1), execve(2), fcntl(2), intro(4), tty(4) HHIISSTTOORRYY An iiooccttll() function call appeared in Version 7 AT&T UNIX. NNAAMMEE iisssseettuuggiidd - is current executable running setuid or setgid SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t iisssseettuuggiidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The iisssseettuuggiidd() function returns 1 if the process was made setuid or setgid as the result of the last or other previous eexxeeccvvee() system calls. Otherwise it returns 0. This system call exists so that library routines (inside libtermlib, libc, or other libraries) can guarantee safe behavior when used inside setuid or setgid programs. Some library routines may be passed insufficient information and hence not know whether the current program was started setuid or setgid because higher level calling code may have made changes to the uid, euid, gid, or egid. Hence these low-level library routines are unable to determine if they are being run with elevated or normal privileges. In particular, it is wise to use this call to determine if a pathname returned from a ggeetteennvv() call may safely be used to ooppeenn() the specified file. Quite often this is not wise because the status of the effective uid is not known. The iisssseettuuggiidd() system call's result is unaffected by calls to sseettuuiidd(), sseettggiidd(), or other such calls. In case of a ffoorrkk(), the child process inherits the same status. The status of iisssseettuuggiidd() is only affected by eexxeeccvvee(). If a child process executes a new executable file, a new issetugid status will be determined. This status is based on the existing process's uid, euid, gid, and egid permissions and on the modes of the executable file. If the new executable file modes are setuid or setgid, or if the existing process is executing the new image with uid != euid or gid != egid, the new process will be considered issetugid. EERRRROORRSS The iisssseettuuggiidd() function is always successful, and no return value is reserved to indicate an error. SSEEEE AALLSSOO execve(2), setegid(2), seteuid(2), setgid(2), setuid(2), getenv(3) HHIISSTTOORRYY The iisssseettuuggiidd() function call first appeared in OpenBSD 2.0. NNAAMMEE kkqquueeuuee, kkeevveenntt - kernel event notification mechanism SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t kkqquueeuuee(_v_o_i_d); _i_n_t kkeevveenntt(_i_n_t _k_q, _c_o_n_s_t _s_t_r_u_c_t _k_e_v_e_n_t _*_c_h_a_n_g_e_l_i_s_t, _i_n_t _n_c_h_a_n_g_e_s, _s_t_r_u_c_t _k_e_v_e_n_t _*_e_v_e_n_t_l_i_s_t, _i_n_t _n_e_v_e_n_t_s, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t); EEVV__SSEETT(_&_k_e_v, _i_d_e_n_t, _f_i_l_t_e_r, _f_l_a_g_s, _f_f_l_a_g_s, _d_a_t_a, _u_d_a_t_a); DDEESSCCRRIIPPTTIIOONN kkqquueeuuee() provides a generic method of notifying the user when an event happens or a condition holds, based on the results of small pieces of kernel code termed ``filters''. A kevent is identified by the (ident, filter) pair; there may only be one unique kevent per kqueue. The filter is executed upon the initial registration of a kevent in order to detect whether a preexisting condition is present, and is also executed whenever an event is passed to the filter for evaluation. If the filter determines that the condition should be reported, then the kevent is placed on the kqueue for the user to retrieve. The filter is also run when the user attempts to retrieve the kevent from the kqueue. If the filter indicates that the condition that triggered the event no longer holds, the kevent is removed from the kqueue and is not returned. Multiple events which trigger the filter do not result in multiple kevents being placed on the kqueue; instead, the filter will aggregate the events into a single struct kevent. Calling cclloossee() on a file descriptor will remove any kevents that reference the descriptor. kkqquueeuuee() creates a new kernel event queue and returns a descriptor. The queue is not inherited by a child created with fork(2). Similarly, kqueues cannot be passed across UNIX-domain sockets. kkeevveenntt() is used to register events with the queue, and return any pending events to the user. _c_h_a_n_g_e_l_i_s_t is a pointer to an array of _k_e_v_e_n_t structures, as defined in <_s_y_s_/_e_v_e_n_t_._h>. All changes contained in the _c_h_a_n_g_e_l_i_s_t are applied before any pending events are read from the queue. _n_c_h_a_n_g_e_s gives the size of _c_h_a_n_g_e_l_i_s_t. _e_v_e_n_t_l_i_s_t is a pointer to an array of kevent structures. _n_e_v_e_n_t_s determines the size of _e_v_e_n_t_l_i_s_t. When _n_e_v_e_n_t_s is zero, kkeevveenntt() will return immediately even if there is a _t_i_m_e_o_u_t specified unlike select(2). If _t_i_m_e_o_u_t is a non-null pointer, it specifies a maximum interval to wait for an event, which will be interpreted as a struct timespec. If _t_i_m_e_o_u_t is a null pointer, kkeevveenntt() waits indefinitely. To effect a poll, the _t_i_m_e_o_u_t argument should be non-null, pointing to a zero-valued _t_i_m_e_s_p_e_c structure. The same array may be used for the _c_h_a_n_g_e_l_i_s_t and _e_v_e_n_t_l_i_s_t. EEVV__SSEETT() is a macro which is provided for ease of initializing a kevent structure. The _k_e_v_e_n_t structure is defined as: struct kevent { uintptr_t ident; /* identifier for this event */ short filter; /* filter for event */ u_short flags; /* action flags for kqueue */ u_int fflags; /* filter flag value */ quad_t data; /* filter data value */ void *udata; /* opaque user data identifier */ }; The fields of struct kevent are: ident Value used to identify this event. The exact interpretation is determined by the attached filter, but often is a file descriptor. filter Identifies the kernel filter used to process this event. The pre-defined system filters are described below. flags Actions to perform on the event. fflags Filter-specific flags. data Filter-specific data value. udata Opaque user-defined value passed through the kernel unchanged. The _f_l_a_g_s field can contain the following values: EV_ADD Adds the event to the kqueue. Re-adding an existing event will modify the parameters of the original event, and not result in a duplicate entry. Adding an event automatically enables it, unless overridden by the EV_DISABLE flag. EV_ENABLE Permit kkeevveenntt() to return the event if it is triggered. EV_DISABLE Disable the event so kkeevveenntt() will not return it. The filter itself is not disabled. EV_DELETE Removes the event from the kqueue. Events which are attached to file descriptors are automatically deleted on the last close of the descriptor. EV_ONESHOT Causes the event to return only the first occurrence of the filter being triggered. After the user retrieves the event from the kqueue, it is deleted. EV_CLEAR After the event is retrieved by the user, its state is reset. This is useful for filters which report state transitions instead of the current state. Note that some filters may automatically set this flag internally. EV_EOF Filters may set this flag to indicate filter-specific EOF condition. EV_ERROR See _R_E_T_U_R_N _V_A_L_U_E_S below. The predefined system filters are listed below. Arguments may be passed to and from the filter via the _f_f_l_a_g_s and _d_a_t_a fields in the kevent structure. EVFILT_READ Takes a descriptor as the identifier, and returns whenever there is data available to read. The behavior of the filter is slightly different depending on the descriptor type. Sockets Sockets which have previously been passed to lliisstteenn() return when there is an incoming connection pending. _d_a_t_a contains the size of the listen backlog. Other socket descriptors return when there is data to be read, subject to the SO_RCVLOWAT value of the socket buffer. This may be overridden with a per- filter low water mark at the time the filter is added by setting the NOTE_LOWAT flag in _f_f_l_a_g_s, and specifying the new low water mark in _d_a_t_a. On return, _d_a_t_a contains the number of bytes in the socket buffer. If the read direction of the socket has shutdown, then the filter also sets EV_EOF in _f_l_a_g_s, and returns the socket error (if any) in _f_f_l_a_g_s. It is possible for EOF to be returned (indicating the connection is gone) while there is still data pending in the socket buffer. Vnodes Returns when the file pointer is not at the end of file. _d_a_t_a contains the offset from current position to end of file, and may be negative. If NOTE_EOF is set in _f_f_l_a_g_s, kkeevveenntt() will also return when the file pointer is at the end of file. The end of file condition is indicated by the presence of NOTE_EOF in _f_f_l_a_g_s on return. Fifos, Pipes Returns when there is data to read; _d_a_t_a contains the number of bytes available. When the last writer disconnects, the filter will set EV_EOF in _f_l_a_g_s. This may be cleared by passing in EV_CLEAR, at which point the filter will resume waiting for data to become available before returning. BPF devices Returns when the BPF buffer is full, the BPF timeout has expired, or when the BPF has ``immediate mode'' enabled and there is any data to read; _d_a_t_a contains the number of bytes available. EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever it is possible to write to the descriptor. For sockets, pipes, and FIFOs, _d_a_t_a will contain the amount of space remaining in the write buffer. The filter will set EV_EOF when the reader disconnects, and for the FIFO case, this may be cleared by use of EV_CLEAR. Note that this filter is not supported for vnodes or BPF devices. For sockets, the low water mark and socket error handling is identical to the EVFILT_READ case. EVFILT_VNODE Takes a file descriptor as the identifier and the events to watch for in _f_f_l_a_g_s, and returns when one or more of the requested events occurs on the descriptor. The events to monitor are: NOTE_DELETE uunnlliinnkk() was called on the file referenced by the descriptor. NOTE_WRITE A write occurred on the file referenced by the descriptor. NOTE_EXTEND The file referenced by the descriptor was extended. NOTE_TRUNCATE The file referenced by the descriptor was truncated. NOTE_ATTRIB The file referenced by the descriptor had its attributes changed. NOTE_LINK The link count on the file changed. NOTE_RENAME The file referenced by the descriptor was renamed. NOTE_REVOKE Access to the file was revoked via revoke(2) or the underlying file system was unmounted. On return, _f_f_l_a_g_s contains the events which triggered the filter. EVFILT_PROC Takes the process ID to monitor as the identifier and the events to watch for in _f_f_l_a_g_s, and returns when the process performs one or more of the requested events. If a process can normally see another process, it can attach an event to it. The events to monitor are: NOTE_EXIT The process has exited. The exit status will be stored in _d_a_t_a in the same format as the status set by wait(2). NOTE_FORK The process has called ffoorrkk(). NOTE_EXEC The process has executed a new process via execve(2) or similar call. NOTE_TRACK Follow a process across ffoorrkk() calls. The parent process will return with NOTE_FORK set in the _f_f_l_a_g_s field, while the child process will return with NOTE_CHILD set in _f_f_l_a_g_s and the parent PID in _d_a_t_a. NOTE_TRACKERR This flag is returned if the system was unable to attach an event to the child process, usually due to resource limitations. On return, _f_f_l_a_g_s contains the events which triggered the filter. EVFILT_SIGNAL Takes the signal number to monitor as the identifier and returns when the given signal is delivered to the process. This coexists with the ssiiggnnaall() and ssiiggaaccttiioonn() facilities, and has a lower precedence. The filter will record all attempts to deliver a signal to a process, even if the signal has been marked as SIG_IGN. Event notification happens after normal signal delivery processing. _d_a_t_a returns the number of times the signal has occurred since the last call to kkeevveenntt(). This filter automatically sets the EV_CLEAR flag internally. EVFILT_TIMER Establishes an arbitrary timer identified by _i_d_e_n_t. When adding a timer, _d_a_t_a specifies the timeout period in milliseconds. The timer will be periodic unless EV_ONESHOT is specified. On return, _d_a_t_a contains the number of times the timeout has expired since the last call to kkeevveenntt(). This filter automatically sets the EV_CLEAR flag internally. RREETTUURRNN VVAALLUUEESS kkqquueeuuee() creates a new kernel event queue and returns a file descriptor. If there was an error creating the kernel event queue, a value of -1 is returned and errno set. kkeevveenntt() returns the number of events placed in the _e_v_e_n_t_l_i_s_t, up to the value given by _n_e_v_e_n_t_s. If an error occurs while processing an element of the _c_h_a_n_g_e_l_i_s_t and there is enough room in the _e_v_e_n_t_l_i_s_t, then the event will be placed in the _e_v_e_n_t_l_i_s_t with EV_ERROR set in _f_l_a_g_s and the system error in _d_a_t_a. Otherwise, -1 will be returned, and errno will be set to indicate the error condition. If the time limit expires, then kkeevveenntt() returns 0. EERRRROORRSS The kkqquueeuuee() function fails if: [ENOMEM] The kernel failed to allocate enough memory for the kernel queue. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. The kkeevveenntt() function fails if: [EACCES] The process does not have permission to register a filter. [EFAULT] There was an error reading or writing the _k_e_v_e_n_t structure. [EBADF] The specified descriptor is invalid. [EINTR] A signal was delivered before the timeout expired and before any events were placed on the kqueue for return. [EINVAL] The specified time limit or filter is invalid. [ENOENT] The event could not be found to be modified or deleted. [ENOMEM] No memory was available to register the event. [ESRCH] The specified process to attach to does not exist. SSEEEE AALLSSOO poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) HHIISSTTOORRYY The kkqquueeuuee() and kkeevveenntt() functions first appeared in FreeBSD 4.1. AAUUTTHHOORRSS The kkqquueeuuee() system and this manual page were written by Jonathan Lemon <_j_l_e_m_o_n_@_F_r_e_e_B_S_D_._o_r_g>. BBUUGGSS It is currently not possible to watch FIFOs or AIO that reside on anything but a UFS file system. Watching a vnode is possible on UFS, NFS and MS-DOS file systems. The _t_i_m_e_o_u_t value is limited to 24 hours; longer timeouts will be silently reinterpreted as 24 hours. NNAAMMEE kkiillll - send signal to a process SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t kkiillll(_p_i_d___t _p_i_d, _i_n_t _s_i_g); DDEESSCCRRIIPPTTIIOONN The kkiillll() function sends the signal given by _s_i_g to _p_i_d, a process or a group of processes. _s_i_g may be one of the signals specified in sigaction(2) or it may be 0, in which case error checking is performed but no signal is actually sent. This can be used to check the validity of _p_i_d. For a process to have permission to send a signal to a process designated by _p_i_d, the real or effective user ID of the receiving process must match that of the sending process or the user must have appropriate privileges (such as given by a set-user-ID program or the user is the superuser). A single exception is the signal SIGCONT, which may always be sent to any process with the same session ID as the caller. If _p_i_d is greater than zero: _s_i_g is sent to the process whose ID is equal to _p_i_d. If _p_i_d is zero: _s_i_g is sent to all processes whose group ID is equal to the process group ID of the sender, and for which the process has permission; this is a variant of killpg(3). If _p_i_d is -1: If the user has superuser privileges, the signal is sent to all processes excluding system processes and the process sending the signal. If the user is not the superuser, the signal is sent to all processes with the same uid as the user excluding the process sending the signal. No error is returned if any process could be signaled. Setuid and setgid processes are dealt with slightly differently. For the non-root user, to prevent attacks against such processes, some signal deliveries are not permitted and return the error EPERM. The following signals are allowed through to this class of processes: SIGKILL, SIGINT, SIGTERM, SIGSTOP, SIGTTIN, SIGTTOU, SIGTSTP, SIGHUP, SIGUSR1, SIGUSR2. For compatibility with System V, if the process number is negative but not -1, the signal is sent to all processes whose process group ID is equal to the absolute value of the process number. This is a variant of killpg(3). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS kkiillll() will fail and no signal will be sent if: [EINVAL] _s_i_g is not a valid signal number. [ESRCH] No process can be found corresponding to that specified by _p_i_d. [EPERM] The sending process is not the superuser and its effective user ID does not match the effective user ID of the receiving process. When signaling a process group, this error is returned if none of the members of the group could be signaled. SSEEEE AALLSSOO getpgrp(2), getpid(2), sigaction(2), killpg(3), raise(3) SSTTAANNDDAARRDDSS The kkiillll() function is expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The kkiillll() system call first appeared in Version 3 AT&T UNIX. The _s_i_g argument was introduced in Version 4 AT&T UNIX. BBUUGGSS IEEE Std 1003.1-2008 (``POSIX.1'') specifies that kkiillll(_0, _s_i_g) should send signal _s_i_g to the calling process, but OpenBSD doesn't do so for historical reasons. NNAAMMEE kkqquueeuuee, kkeevveenntt - kernel event notification mechanism SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t kkqquueeuuee(_v_o_i_d); _i_n_t kkeevveenntt(_i_n_t _k_q, _c_o_n_s_t _s_t_r_u_c_t _k_e_v_e_n_t _*_c_h_a_n_g_e_l_i_s_t, _i_n_t _n_c_h_a_n_g_e_s, _s_t_r_u_c_t _k_e_v_e_n_t _*_e_v_e_n_t_l_i_s_t, _i_n_t _n_e_v_e_n_t_s, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t); EEVV__SSEETT(_&_k_e_v, _i_d_e_n_t, _f_i_l_t_e_r, _f_l_a_g_s, _f_f_l_a_g_s, _d_a_t_a, _u_d_a_t_a); DDEESSCCRRIIPPTTIIOONN kkqquueeuuee() provides a generic method of notifying the user when an event happens or a condition holds, based on the results of small pieces of kernel code termed ``filters''. A kevent is identified by the (ident, filter) pair; there may only be one unique kevent per kqueue. The filter is executed upon the initial registration of a kevent in order to detect whether a preexisting condition is present, and is also executed whenever an event is passed to the filter for evaluation. If the filter determines that the condition should be reported, then the kevent is placed on the kqueue for the user to retrieve. The filter is also run when the user attempts to retrieve the kevent from the kqueue. If the filter indicates that the condition that triggered the event no longer holds, the kevent is removed from the kqueue and is not returned. Multiple events which trigger the filter do not result in multiple kevents being placed on the kqueue; instead, the filter will aggregate the events into a single struct kevent. Calling cclloossee() on a file descriptor will remove any kevents that reference the descriptor. kkqquueeuuee() creates a new kernel event queue and returns a descriptor. The queue is not inherited by a child created with fork(2). Similarly, kqueues cannot be passed across UNIX-domain sockets. kkeevveenntt() is used to register events with the queue, and return any pending events to the user. _c_h_a_n_g_e_l_i_s_t is a pointer to an array of _k_e_v_e_n_t structures, as defined in <_s_y_s_/_e_v_e_n_t_._h>. All changes contained in the _c_h_a_n_g_e_l_i_s_t are applied before any pending events are read from the queue. _n_c_h_a_n_g_e_s gives the size of _c_h_a_n_g_e_l_i_s_t. _e_v_e_n_t_l_i_s_t is a pointer to an array of kevent structures. _n_e_v_e_n_t_s determines the size of _e_v_e_n_t_l_i_s_t. When _n_e_v_e_n_t_s is zero, kkeevveenntt() will return immediately even if there is a _t_i_m_e_o_u_t specified unlike select(2). If _t_i_m_e_o_u_t is a non-null pointer, it specifies a maximum interval to wait for an event, which will be interpreted as a struct timespec. If _t_i_m_e_o_u_t is a null pointer, kkeevveenntt() waits indefinitely. To effect a poll, the _t_i_m_e_o_u_t argument should be non-null, pointing to a zero-valued _t_i_m_e_s_p_e_c structure. The same array may be used for the _c_h_a_n_g_e_l_i_s_t and _e_v_e_n_t_l_i_s_t. EEVV__SSEETT() is a macro which is provided for ease of initializing a kevent structure. The _k_e_v_e_n_t structure is defined as: struct kevent { uintptr_t ident; /* identifier for this event */ short filter; /* filter for event */ u_short flags; /* action flags for kqueue */ u_int fflags; /* filter flag value */ quad_t data; /* filter data value */ void *udata; /* opaque user data identifier */ }; The fields of struct kevent are: ident Value used to identify this event. The exact interpretation is determined by the attached filter, but often is a file descriptor. filter Identifies the kernel filter used to process this event. The pre-defined system filters are described below. flags Actions to perform on the event. fflags Filter-specific flags. data Filter-specific data value. udata Opaque user-defined value passed through the kernel unchanged. The _f_l_a_g_s field can contain the following values: EV_ADD Adds the event to the kqueue. Re-adding an existing event will modify the parameters of the original event, and not result in a duplicate entry. Adding an event automatically enables it, unless overridden by the EV_DISABLE flag. EV_ENABLE Permit kkeevveenntt() to return the event if it is triggered. EV_DISABLE Disable the event so kkeevveenntt() will not return it. The filter itself is not disabled. EV_DELETE Removes the event from the kqueue. Events which are attached to file descriptors are automatically deleted on the last close of the descriptor. EV_ONESHOT Causes the event to return only the first occurrence of the filter being triggered. After the user retrieves the event from the kqueue, it is deleted. EV_CLEAR After the event is retrieved by the user, its state is reset. This is useful for filters which report state transitions instead of the current state. Note that some filters may automatically set this flag internally. EV_EOF Filters may set this flag to indicate filter-specific EOF condition. EV_ERROR See _R_E_T_U_R_N _V_A_L_U_E_S below. The predefined system filters are listed below. Arguments may be passed to and from the filter via the _f_f_l_a_g_s and _d_a_t_a fields in the kevent structure. EVFILT_READ Takes a descriptor as the identifier, and returns whenever there is data available to read. The behavior of the filter is slightly different depending on the descriptor type. Sockets Sockets which have previously been passed to lliisstteenn() return when there is an incoming connection pending. _d_a_t_a contains the size of the listen backlog. Other socket descriptors return when there is data to be read, subject to the SO_RCVLOWAT value of the socket buffer. This may be overridden with a per- filter low water mark at the time the filter is added by setting the NOTE_LOWAT flag in _f_f_l_a_g_s, and specifying the new low water mark in _d_a_t_a. On return, _d_a_t_a contains the number of bytes in the socket buffer. If the read direction of the socket has shutdown, then the filter also sets EV_EOF in _f_l_a_g_s, and returns the socket error (if any) in _f_f_l_a_g_s. It is possible for EOF to be returned (indicating the connection is gone) while there is still data pending in the socket buffer. Vnodes Returns when the file pointer is not at the end of file. _d_a_t_a contains the offset from current position to end of file, and may be negative. If NOTE_EOF is set in _f_f_l_a_g_s, kkeevveenntt() will also return when the file pointer is at the end of file. The end of file condition is indicated by the presence of NOTE_EOF in _f_f_l_a_g_s on return. Fifos, Pipes Returns when there is data to read; _d_a_t_a contains the number of bytes available. When the last writer disconnects, the filter will set EV_EOF in _f_l_a_g_s. This may be cleared by passing in EV_CLEAR, at which point the filter will resume waiting for data to become available before returning. BPF devices Returns when the BPF buffer is full, the BPF timeout has expired, or when the BPF has ``immediate mode'' enabled and there is any data to read; _d_a_t_a contains the number of bytes available. EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever it is possible to write to the descriptor. For sockets, pipes, and FIFOs, _d_a_t_a will contain the amount of space remaining in the write buffer. The filter will set EV_EOF when the reader disconnects, and for the FIFO case, this may be cleared by use of EV_CLEAR. Note that this filter is not supported for vnodes or BPF devices. For sockets, the low water mark and socket error handling is identical to the EVFILT_READ case. EVFILT_VNODE Takes a file descriptor as the identifier and the events to watch for in _f_f_l_a_g_s, and returns when one or more of the requested events occurs on the descriptor. The events to monitor are: NOTE_DELETE uunnlliinnkk() was called on the file referenced by the descriptor. NOTE_WRITE A write occurred on the file referenced by the descriptor. NOTE_EXTEND The file referenced by the descriptor was extended. NOTE_TRUNCATE The file referenced by the descriptor was truncated. NOTE_ATTRIB The file referenced by the descriptor had its attributes changed. NOTE_LINK The link count on the file changed. NOTE_RENAME The file referenced by the descriptor was renamed. NOTE_REVOKE Access to the file was revoked via revoke(2) or the underlying file system was unmounted. On return, _f_f_l_a_g_s contains the events which triggered the filter. EVFILT_PROC Takes the process ID to monitor as the identifier and the events to watch for in _f_f_l_a_g_s, and returns when the process performs one or more of the requested events. If a process can normally see another process, it can attach an event to it. The events to monitor are: NOTE_EXIT The process has exited. The exit status will be stored in _d_a_t_a in the same format as the status set by wait(2). NOTE_FORK The process has called ffoorrkk(). NOTE_EXEC The process has executed a new process via execve(2) or similar call. NOTE_TRACK Follow a process across ffoorrkk() calls. The parent process will return with NOTE_FORK set in the _f_f_l_a_g_s field, while the child process will return with NOTE_CHILD set in _f_f_l_a_g_s and the parent PID in _d_a_t_a. NOTE_TRACKERR This flag is returned if the system was unable to attach an event to the child process, usually due to resource limitations. On return, _f_f_l_a_g_s contains the events which triggered the filter. EVFILT_SIGNAL Takes the signal number to monitor as the identifier and returns when the given signal is delivered to the process. This coexists with the ssiiggnnaall() and ssiiggaaccttiioonn() facilities, and has a lower precedence. The filter will record all attempts to deliver a signal to a process, even if the signal has been marked as SIG_IGN. Event notification happens after normal signal delivery processing. _d_a_t_a returns the number of times the signal has occurred since the last call to kkeevveenntt(). This filter automatically sets the EV_CLEAR flag internally. EVFILT_TIMER Establishes an arbitrary timer identified by _i_d_e_n_t. When adding a timer, _d_a_t_a specifies the timeout period in milliseconds. The timer will be periodic unless EV_ONESHOT is specified. On return, _d_a_t_a contains the number of times the timeout has expired since the last call to kkeevveenntt(). This filter automatically sets the EV_CLEAR flag internally. RREETTUURRNN VVAALLUUEESS kkqquueeuuee() creates a new kernel event queue and returns a file descriptor. If there was an error creating the kernel event queue, a value of -1 is returned and errno set. kkeevveenntt() returns the number of events placed in the _e_v_e_n_t_l_i_s_t, up to the value given by _n_e_v_e_n_t_s. If an error occurs while processing an element of the _c_h_a_n_g_e_l_i_s_t and there is enough room in the _e_v_e_n_t_l_i_s_t, then the event will be placed in the _e_v_e_n_t_l_i_s_t with EV_ERROR set in _f_l_a_g_s and the system error in _d_a_t_a. Otherwise, -1 will be returned, and errno will be set to indicate the error condition. If the time limit expires, then kkeevveenntt() returns 0. EERRRROORRSS The kkqquueeuuee() function fails if: [ENOMEM] The kernel failed to allocate enough memory for the kernel queue. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. The kkeevveenntt() function fails if: [EACCES] The process does not have permission to register a filter. [EFAULT] There was an error reading or writing the _k_e_v_e_n_t structure. [EBADF] The specified descriptor is invalid. [EINTR] A signal was delivered before the timeout expired and before any events were placed on the kqueue for return. [EINVAL] The specified time limit or filter is invalid. [ENOENT] The event could not be found to be modified or deleted. [ENOMEM] No memory was available to register the event. [ESRCH] The specified process to attach to does not exist. SSEEEE AALLSSOO poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) HHIISSTTOORRYY The kkqquueeuuee() and kkeevveenntt() functions first appeared in FreeBSD 4.1. AAUUTTHHOORRSS The kkqquueeuuee() system and this manual page were written by Jonathan Lemon <_j_l_e_m_o_n_@_F_r_e_e_B_S_D_._o_r_g>. BBUUGGSS It is currently not possible to watch FIFOs or AIO that reside on anything but a UFS file system. Watching a vnode is possible on UFS, NFS and MS-DOS file systems. The _t_i_m_e_o_u_t value is limited to 24 hours; longer timeouts will be silently reinterpreted as 24 hours. NNAAMMEE kkttrraaccee - process tracing SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t kkttrraaccee(_c_o_n_s_t _c_h_a_r _*_t_r_a_c_e_f_i_l_e, _i_n_t _o_p_s, _i_n_t _t_r_p_o_i_n_t_s, _p_i_d___t _p_i_d); DDEESSCCRRIIPPTTIIOONN The kkttrraaccee() function enables or disables tracing of one or more processes. Users may only trace their own processes. Only the superuser can trace setuid or setgid programs. kkttrraaccee() is only available on kernels compiled with the KKTTRRAACCEE option. _t_r_a_c_e_f_i_l_e gives the pathname of the file to be used for tracing. The file must exist, be writable by the calling process, and not be a symbolic link. All trace records are always appended to the file, so the file must be truncated to zero length to discard previous trace data. If tracing points are being disabled (see KTROP_CLEAR below), _t_r_a_c_e_f_i_l_e may be NULL. The _o_p_s parameter specifies the requested ktrace operation. The defined operations are: KTROP_SET Enable trace points specified in _t_r_p_o_i_n_t_s. KTROP_CLEAR Disable trace points specified in _t_r_p_o_i_n_t_s. KTROP_CLEARFILE Stop all tracing. KTRFLAG_DESCEND The tracing change should apply to the specified process and all its current children. The _t_r_p_o_i_n_t_s parameter specifies the trace points of interest. The defined trace points are: KTRFAC_SYSCALL Trace system calls. KTRFAC_SYSRET Trace return values from system calls. KTRFAC_NAMEI Trace name lookup operations. KTRFAC_GENIO Trace all I/O (note that this option can generate much output). KTRFAC_PSIG Trace posted signals. KTRFAC_EMUL Trace emulation changes. KTRFAC_CSW Trace context switch points. KTRFAC_STRUCT Trace various structs KTRFAC_USER Trace user data coming from utrace(2) calls. KTRFAC_INHERIT Inherit tracing to future children. The _p_i_d parameter refers to a process ID. If it is negative, it refers to a process group ID. Each tracing event outputs a record composed of a generic header followed by a trace point specific structure. The generic header is: struct ktr_header { uint ktr_type; /* trace record type */ pid_t ktr_pid; /* process id */ pid_t ktr_tid; /* thread id */ struct timespec ktr_time; /* timestamp */ char ktr_comm[MAXCOMLEN+1]; /* command name */ size_t ktr_len; /* length of buf */ }; The _k_t_r___l_e_n field specifies the length of the _k_t_r___t_y_p_e data that follows this header. The _k_t_r___p_i_d, _k_t_r___t_i_d, and _k_t_r___c_o_m_m fields specify the process, thread, and command generating the record. The _k_t_r___t_i_m_e field gives the time (with nanosecond resolution) that the record was generated. The generic header is followed by _k_t_r___l_e_n bytes of a _k_t_r___t_y_p_e record. The type specific records are defined in the <_s_y_s_/_k_t_r_a_c_e_._h> include file. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS kkttrraaccee() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [EINVAL] No trace points were selected. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named tracefile does not exist. [EACCES] Search permission is denied for a component of the path prefix or the path refers to a symbolic link. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EIO] An I/O error occurred while reading from or writing to the file system. [ESRCH] No process can be found corresponding to that specified by _p_i_d. SSEEEE AALLSSOO kdump(1), ktrace(1), utrace(2) HHIISSTTOORRYY A kkttrraaccee() function call first appeared in 4.4BSD. NNAAMMEE cchhoowwnn, llcchhoowwnn, ffcchhoowwnnaatt, ffcchhoowwnn - change owner and group of a file or link SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t cchhoowwnn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); _i_n_t llcchhoowwnn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); _i_n_t ffcchhoowwnn(_i_n_t _f_d, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffcchhoowwnnaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _u_i_d___t _o_w_n_e_r, _g_i_d___t _g_r_o_u_p, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The owner ID and group ID of the file (or link) named by _p_a_t_h or referenced by _f_d is changed as specified by the arguments _o_w_n_e_r and _g_r_o_u_p. The owner of a file may change the _g_r_o_u_p to a group of which he or she is a member, but the change _o_w_n_e_r capability is restricted to the superuser. By default, cchhoowwnn() clears the set-user-ID and set-group-ID bits on the file to prevent accidental or mischievous creation of set-user-ID and set-group-ID programs. This behaviour can be overridden by setting the sysctl(8) variable _f_s_._p_o_s_i_x_._s_e_t_u_i_d to zero. llcchhoowwnn() operates similarly to how cchhoowwnn() operated on older systems, and does not follow symbolic links. It allows the owner and group of a symbolic link to be set. The ffcchhoowwnnaatt() function is equivalent to either the cchhoowwnn() or llcchhoowwnn() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose ownership is changed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffcchhoowwnnaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to cchhoowwnn() or llcchhoowwnn(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the ownership of the symbolic link is changed. ffcchhoowwnn() is particularly useful when used in conjunction with the file locking primitives (see flock(2)). One of the owner or group IDs may be left unchanged by specifying it as -1. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS cchhoowwnn(), llcchhoowwnn(), and ffcchhoowwnnaatt() will fail and the file or link will be unchanged if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffcchhoowwnnaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffcchhoowwnn() will fail if: [EBADF] _f_d does not refer to a valid descriptor. [EINVAL] _f_d refers to a socket, not a file. [EPERM] The effective user ID is not the superuser. [EROFS] The named file resides on a read-only file system. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO chgrp(1), chmod(2), flock(2), chown(8) SSTTAANNDDAARRDDSS The cchhoowwnn(), ffcchhoowwnn(), ffcchhoowwnnaatt(), and llcchhoowwnn() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The cchhoowwnn() system call first appeared in Version 1 AT&T UNIX. Since Version 6 AT&T UNIX it supports changing the group as well, and in Version 7 AT&T UNIX _g_r_o_u_p was made a separate argument. The ffcchhoowwnn() system call first appeared in 4.1cBSD. The cchhoowwnn() and ffcchhoowwnn() system calls were changed to follow symbolic links in 4.4BSD; therefore, and for compatibility with AT&T System V Release 4 UNIX, the llcchhoowwnn() system call was added to OpenBSD 2.1. The ffcchhoowwnnaatt() system call has been available since OpenBSD 5.0. NNAAMMEE lliinnkk, lliinnkkaatt - make hard link to a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t lliinnkk(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_1, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_2); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t lliinnkkaatt(_i_n_t _f_d_1, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_1, _i_n_t _f_d_2, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_2, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The lliinnkk() function atomically creates the specified directory entry (hard link) _n_a_m_e_2 with the attributes of the underlying object pointed at by _n_a_m_e_1. If the link is successful: the link count of the underlying object is incremented; _n_a_m_e_1 and _n_a_m_e_2 share equal access and rights to the underlying object. If _n_a_m_e_1 is removed, the file _n_a_m_e_2 is not deleted and the link count of the underlying object is decremented. _n_a_m_e_1 must exist for the hard link to succeed and both _n_a_m_e_1 and _n_a_m_e_2 must be in the same file system. As mandated by POSIX.1 _n_a_m_e_1 may not be a directory. The lliinnkkaatt() function is equivalent to lliinnkk() except that where _n_a_m_e_1 or _n_a_m_e_2 specifies a relative path, the directory entries linked are resolved relative to the directories associated with file descriptors _f_d_1 or _f_d_2 (respectively) instead of the current working directory. If lliinnkkaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d_1 or _f_d_2 parameter, the current working directory is used for resolving the respective _n_a_m_e_1 or _n_a_m_e_2 argument. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_FOLLOW If _n_a_m_e_1 names a symbolic link, a new link for the target of the symbolic link is created. If the AT_SYMLINK_FOLLOW flag is clear and _n_a_m_e_1 names a symbolic link, a new link is created for the symbolic link _n_a_m_e_1 and not its target. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS lliinnkk() and lliinnkkaatt() will fail and no link will be created if: [ENOTDIR] A component of either path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of either path prefix does not exist. [EOPNOTSUPP] The file system containing the file named by _n_a_m_e_1 does not support links. [EMLINK] The link count of the file named by _n_a_m_e_1 would exceed LINK_MAX. [EACCES] A component of either path prefix denies search permission. [EACCES] The requested link requires writing in a directory with a mode that denies write permission. [ELOOP] Too many symbolic links were encountered in translating one of the pathnames. [ENOENT] The file named by _n_a_m_e_1 does not exist. [EEXIST] The link named by _n_a_m_e_2 does exist. [EPERM] The file named by _n_a_m_e_1 is a directory and the effective user ID is not superuser, or the file system containing the file does not permit the use of lliinnkk() on a directory. [EPERM] The file named by _n_a_m_e_1 is flagged immutable or append-only. [EXDEV] The link named by _n_a_m_e_2 and the file named by _n_a_m_e_1 are on different file systems. [ENOSPC] The directory in which the entry for the new link is being placed cannot be extended because there is no space left on the file system containing the directory. [EDQUOT] The directory in which the entry for the new link is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EIO] An I/O error occurred while reading from or writing to the file system to make the directory entry. [EROFS] The requested link requires writing in a directory on a read-only file system. [EFAULT] One of the pathnames specified is outside the process's allocated address space. Additionally, lliinnkkaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_FOLLOW. [EBADF] The _n_a_m_e_1 or _n_a_m_e_2 argument specifies a relative path and the _f_d_1 or _f_d_2 argument, respectively, is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _n_a_m_e_1 or _n_a_m_e_2 argument specifies a relative path and the _f_d_1 or _f_d_2 argument, respectively, is a valid file descriptor but it does not reference a directory. [EACCES] The _n_a_m_e_1 or _n_a_m_e_2 argument specifies a relative path but search permission is denied for the directory which the _f_d_1 or _f_d_2 file descriptor, respectively, references. SSEEEE AALLSSOO ln(1), readlink(2), symlink(2), unlink(2) SSTTAANNDDAARRDDSS The lliinnkk() and lliinnkkaatt() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The lliinnkk() system call first appeared in Version 1 AT&T UNIX. The lliinnkkaatt() function appeared in OpenBSD 5.0. NNAAMMEE lliinnkk, lliinnkkaatt - make hard link to a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t lliinnkk(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_1, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_2); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t lliinnkkaatt(_i_n_t _f_d_1, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_1, _i_n_t _f_d_2, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_2, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The lliinnkk() function atomically creates the specified directory entry (hard link) _n_a_m_e_2 with the attributes of the underlying object pointed at by _n_a_m_e_1. If the link is successful: the link count of the underlying object is incremented; _n_a_m_e_1 and _n_a_m_e_2 share equal access and rights to the underlying object. If _n_a_m_e_1 is removed, the file _n_a_m_e_2 is not deleted and the link count of the underlying object is decremented. _n_a_m_e_1 must exist for the hard link to succeed and both _n_a_m_e_1 and _n_a_m_e_2 must be in the same file system. As mandated by POSIX.1 _n_a_m_e_1 may not be a directory. The lliinnkkaatt() function is equivalent to lliinnkk() except that where _n_a_m_e_1 or _n_a_m_e_2 specifies a relative path, the directory entries linked are resolved relative to the directories associated with file descriptors _f_d_1 or _f_d_2 (respectively) instead of the current working directory. If lliinnkkaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d_1 or _f_d_2 parameter, the current working directory is used for resolving the respective _n_a_m_e_1 or _n_a_m_e_2 argument. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_FOLLOW If _n_a_m_e_1 names a symbolic link, a new link for the target of the symbolic link is created. If the AT_SYMLINK_FOLLOW flag is clear and _n_a_m_e_1 names a symbolic link, a new link is created for the symbolic link _n_a_m_e_1 and not its target. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS lliinnkk() and lliinnkkaatt() will fail and no link will be created if: [ENOTDIR] A component of either path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of either path prefix does not exist. [EOPNOTSUPP] The file system containing the file named by _n_a_m_e_1 does not support links. [EMLINK] The link count of the file named by _n_a_m_e_1 would exceed LINK_MAX. [EACCES] A component of either path prefix denies search permission. [EACCES] The requested link requires writing in a directory with a mode that denies write permission. [ELOOP] Too many symbolic links were encountered in translating one of the pathnames. [ENOENT] The file named by _n_a_m_e_1 does not exist. [EEXIST] The link named by _n_a_m_e_2 does exist. [EPERM] The file named by _n_a_m_e_1 is a directory and the effective user ID is not superuser, or the file system containing the file does not permit the use of lliinnkk() on a directory. [EPERM] The file named by _n_a_m_e_1 is flagged immutable or append-only. [EXDEV] The link named by _n_a_m_e_2 and the file named by _n_a_m_e_1 are on different file systems. [ENOSPC] The directory in which the entry for the new link is being placed cannot be extended because there is no space left on the file system containing the directory. [EDQUOT] The directory in which the entry for the new link is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EIO] An I/O error occurred while reading from or writing to the file system to make the directory entry. [EROFS] The requested link requires writing in a directory on a read-only file system. [EFAULT] One of the pathnames specified is outside the process's allocated address space. Additionally, lliinnkkaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_FOLLOW. [EBADF] The _n_a_m_e_1 or _n_a_m_e_2 argument specifies a relative path and the _f_d_1 or _f_d_2 argument, respectively, is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _n_a_m_e_1 or _n_a_m_e_2 argument specifies a relative path and the _f_d_1 or _f_d_2 argument, respectively, is a valid file descriptor but it does not reference a directory. [EACCES] The _n_a_m_e_1 or _n_a_m_e_2 argument specifies a relative path but search permission is denied for the directory which the _f_d_1 or _f_d_2 file descriptor, respectively, references. SSEEEE AALLSSOO ln(1), readlink(2), symlink(2), unlink(2) SSTTAANNDDAARRDDSS The lliinnkk() and lliinnkkaatt() functions are expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The lliinnkk() system call first appeared in Version 1 AT&T UNIX. The lliinnkkaatt() function appeared in OpenBSD 5.0. NNAAMMEE lliisstteenn - listen for connections on a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t lliisstteenn(_i_n_t _s, _i_n_t _b_a_c_k_l_o_g); DDEESSCCRRIIPPTTIIOONN To accept connections, a socket is first created with socket(2), a willingness to accept incoming connections and a queue limit for incoming connections are specified with lliisstteenn(), and then the connections are accepted with accept(2). The lliisstteenn() call applies only to sockets of type SOCK_STREAM or SOCK_SEQPACKET. The _b_a_c_k_l_o_g parameter defines the maximum length the queue of pending connections may grow to. If a connection request arrives with the queue full the client may receive an error with an indication of ECONNREFUSED, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS lliisstteenn() will fail if: [EBADF] The argument _s is not a valid descriptor. [ENOTSOCK] The argument _s is not a socket. [EOPNOTSUPP] The socket is not of a type that supports the operation lliisstteenn(). [EINVAL] The socket is already connected. SSEEEE AALLSSOO accept(2), connect(2), socket(2), sysctl(8) SSTTAANNDDAARRDDSS The lliisstteenn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The lliisstteenn() system call first appeared in 4.1cBSD. BBUUGGSS The _b_a_c_k_l_o_g is currently limited (silently) to the value of the kern.somaxconn sysctl, which defaults to 128. NNAAMMEE llsseeeekk - reposition read/write file offset SSYYNNOOPPSSIISS ##iinncclluuddee <> _o_f_f___t llsseeeekk(_i_n_t _f_i_l_d_e_s, _o_f_f___t _o_f_f_s_e_t, _i_n_t _w_h_e_n_c_e); DDEESSCCRRIIPPTTIIOONN The llsseeeekk() function repositions the offset of the file descriptor _f_i_l_d_e_s to the argument _o_f_f_s_e_t according to the directive _w_h_e_n_c_e. The argument _f_i_l_d_e_s must be an open file descriptor. llsseeeekk() repositions the file pointer _f_i_l_d_e_s as follows: If _w_h_e_n_c_e is SEEK_SET, the offset is set to _o_f_f_s_e_t bytes. If _w_h_e_n_c_e is SEEK_CUR, the offset is set to its current location plus _o_f_f_s_e_t bytes. If _w_h_e_n_c_e is SEEK_END, the offset is set to the size of the file plus _o_f_f_s_e_t bytes. The llsseeeekk() function allows the file offset to be set beyond the end of the existing end-of-file of the file. If data is later written at this point, subsequent reads of the data in the gap return bytes of zeros (until data is actually written into the gap). Some devices are incapable of seeking. The value of the pointer associated with such a device is undefined. RREETTUURRNN VVAALLUUEESS Upon successful completion, llsseeeekk() returns the resulting offset location as measured in bytes from the beginning of the file. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS llsseeeekk() will fail and the file pointer will remain unchanged if: [EBADF] _f_i_l_d_e_s is not an open file descriptor. [ESPIPE] _f_i_l_d_e_s is associated with a pipe, socket, or FIFO. [EINVAL] _w_h_e_n_c_e is not a proper value or the resulting offset would be negative on a file system or special device that does not allow negative offsets to be used. SSEEEE AALLSSOO dup(2), open(2) SSTTAANNDDAARRDDSS The llsseeeekk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A sseeeekk() system call first appeared in Version 1 AT&T UNIX. In Version 7 AT&T UNIX it was renamed to llsseeeekk() for ``long seek'' due to a larger _o_f_f_s_e_t argument type. BBUUGGSS This document's use of _w_h_e_n_c_e is incorrect English, but is maintained for historical reasons. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE mmaaddvviissee, ppoossiixx__mmaaddvviissee - give advice about use of memory SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmaaddvviissee(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _b_e_h_a_v); _i_n_t ppoossiixx__mmaaddvviissee(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _b_e_h_a_v); DDEESSCCRRIIPPTTIIOONN The mmaaddvviissee() system call allows a process that has knowledge of its memory behavior to describe it to the system. The ppoossiixx__mmaaddvviissee() interface has the same effect, but returns the error value instead of only setting _e_r_r_n_o. The possible behaviors are: MADV_NORMAL No further special treatment needed. MADV_RANDOM Expect random page access patterns. MADV_SEQUENTIAL Expect sequential page references. MADV_WILLNEED The pages will be referenced soon. MADV_DONTNEED The pages will not be referenced soon. MADV_SPACEAVAIL Ensure that resources are reserved. MADV_FREE The pages don't contain any useful data and can be recycled. Portable programs that call the ppoossiixx__mmaaddvviissee() interface should use the aliases POSIX_MADV_NORMAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, POSIX_MADV_WILLNEED, and POSIX_MADV_DONTNEED rather than the flags described above. RREETTUURRNN VVAALLUUEESS The mmaaddvviissee() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. If successful, the ppoossiixx__mmaaddvviissee() function will return zero. Otherwise an error number will be returned to indicate the error. SSEEEE AALLSSOO mincore(2), minherit(2), mprotect(2), msync(2), munmap(2) SSTTAANNDDAARRDDSS The ppoossiixx__mmaaddvviissee() system call conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmaaddvviissee() function first appeared in 4.4BSD. The ppoossiixx__mmaaddvviissee() function first appeared in OpenBSD 4.8. BBUUGGSS The MADV_WILLNEED behavior is ignored. The MADV_SPACEAVAIL behavior is not implemented and will always fail. NNAAMMEE mmiinnccoorree - determine residency of memory pages SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmiinnccoorree(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _c_h_a_r _*_v_e_c); DDEESSCCRRIIPPTTIIOONN The mmiinnccoorree() system call allows a process to obtain information about whether pages are core resident. Here the current core residency of the pages is returned in the character array _v_e_c, with a value of 1 meaning that the page is in-core. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. SSEEEE AALLSSOO madvise(2), minherit(2), mlock(2), mprotect(2), msync(2), munmap(2) HHIISSTTOORRYY The mmiinnccoorree() function first appeared in 4.4BSD. NNAAMMEE mmiinnhheerriitt - control the inheritance of pages SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmiinnhheerriitt(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _i_n_h_e_r_i_t); DDEESSCCRRIIPPTTIIOONN The mmiinnhheerriitt() system call changes the specified pages to have the inheritance characteristic _i_n_h_e_r_i_t. A page's inheritance characteristic controls how it will be mapped in child processes as created by fork(2). The possible inheritance characteristics are: MAP_INHERIT_NONE Pages are not mapped in the child process. MAP_INHERIT_COPY Private copy of pages are mapped in the child process. MAP_INHERIT_SHARE Mapped pages are shared between the parent and child processes. MAP_INHERIT_ZERO New anonymous pages (initialized to all zero bytes) are mapped in the child process. Not all implementations will guarantee that the inheritance characteristic can be set on a page basis; the granularity of changes may be as large as an entire region. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The mmiinnhheerriitt() system call will fail if: [EINVAL] The virtual address range specified by the _a_d_d_r and _l_e_n arguments is not valid. [EINVAL] The _i_n_h_e_r_i_t argument is invalid. SSEEEE AALLSSOO madvise(2), mincore(2), mprotect(2), msync(2), munmap(2) HHIISSTTOORRYY The mmiinnhheerriitt() function first appeared in OpenBSD 2.0. NNAAMMEE mmkkddiirr, mmkkddiirraatt - make a directory file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmkkddiirr(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t mmkkddiirraatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); DDEESSCCRRIIPPTTIIOONN The directory _p_a_t_h is created with the access permissions specified by _m_o_d_e and restricted by the umask(2) of the calling process. The directory's owner ID is set to the process's effective user ID. The directory's group ID is set to that of the parent directory in which it is created. The mmkkddiirraatt() function is equivalent to mmkkddiirr() except that where _p_a_t_h specifies a relative path, the newly created directory is created relative to the directory associated with file descriptor _f_d instead of the current working directory. If mmkkddiirraatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to mmkkddiirr(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmkkddiirr() and mmkkddiirraatt() will fail and no directory will be created if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of the path prefix does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EROFS] The named file resides on a read-only file system. [EEXIST] The named file exists. [ENOSPC] The new directory cannot be created because there is no space left on the file system that will contain the directory. [ENOSPC] There are no free inodes on the file system on which the directory is being created. [EDQUOT] The new directory cannot be created because the user's quota of disk blocks on the file system that will contain the directory has been exhausted. [EDQUOT] The user's quota of inodes on the file system on which the directory is being created has been exhausted. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [EIO] An I/O error occurred while reading from or writing to the file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. Additionally, mmkkddiirraatt() will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chmod(2), stat(2), umask(2) SSTTAANNDDAARRDDSS The mmkkddiirr() and mmkkddiirraatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A mmkkddiirr() system call first appeared in Version 1 AT&T UNIX. It was renamed to mmaakkddiirr() in Version 2 AT&T UNIX. However, it did not exist from Version 4 AT&T UNIX to 4.1BSD; in those releases, mknod(2) had to be used. Since mmkkddiirr() reappeared in 4.1cBSD, it no longer requires superuser privileges and it automatically creates the `.' and `..' directory entries. The mmkkddiirraatt() system call has been available since OpenBSD 5.0. NNAAMMEE mmkkddiirr, mmkkddiirraatt - make a directory file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmkkddiirr(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t mmkkddiirraatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); DDEESSCCRRIIPPTTIIOONN The directory _p_a_t_h is created with the access permissions specified by _m_o_d_e and restricted by the umask(2) of the calling process. The directory's owner ID is set to the process's effective user ID. The directory's group ID is set to that of the parent directory in which it is created. The mmkkddiirraatt() function is equivalent to mmkkddiirr() except that where _p_a_t_h specifies a relative path, the newly created directory is created relative to the directory associated with file descriptor _f_d instead of the current working directory. If mmkkddiirraatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to mmkkddiirr(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmkkddiirr() and mmkkddiirraatt() will fail and no directory will be created if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of the path prefix does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EROFS] The named file resides on a read-only file system. [EEXIST] The named file exists. [ENOSPC] The new directory cannot be created because there is no space left on the file system that will contain the directory. [ENOSPC] There are no free inodes on the file system on which the directory is being created. [EDQUOT] The new directory cannot be created because the user's quota of disk blocks on the file system that will contain the directory has been exhausted. [EDQUOT] The user's quota of inodes on the file system on which the directory is being created has been exhausted. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [EIO] An I/O error occurred while reading from or writing to the file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. Additionally, mmkkddiirraatt() will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chmod(2), stat(2), umask(2) SSTTAANNDDAARRDDSS The mmkkddiirr() and mmkkddiirraatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A mmkkddiirr() system call first appeared in Version 1 AT&T UNIX. It was renamed to mmaakkddiirr() in Version 2 AT&T UNIX. However, it did not exist from Version 4 AT&T UNIX to 4.1BSD; in those releases, mknod(2) had to be used. Since mmkkddiirr() reappeared in 4.1cBSD, it no longer requires superuser privileges and it automatically creates the `.' and `..' directory entries. The mmkkddiirraatt() system call has been available since OpenBSD 5.0. NNAAMMEE mmkkffiiffoo, mmkkffiiffooaatt - make a FIFO file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmkkffiiffoo(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t mmkkffiiffooaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); DDEESSCCRRIIPPTTIIOONN mmkkffiiffoo() creates a new FIFO file with name _p_a_t_h. The access permissions are specified by _m_o_d_e and restricted by the umask(2) of the calling process. The FIFO's owner ID is set to the process's effective user ID. The FIFO's group ID is set to that of the parent directory in which it is created. The mmkkffiiffooaatt() function is equivalent to mmkkffiiffoo() except that where _p_a_t_h specifies a relative path, the newly created FIFO is created relative to the directory associated with file descriptor _f_d instead of the current working directory. If mmkkffiiffooaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to mmkkffiiffoo(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmkkffiiffoo() and mmkkffiiffooaatt() will fail and no FIFO will be created if: [EOPNOTSUPP] The kernel has not been configured to support FIFOs. [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of the path prefix does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EROFS] The named file resides on a read-only file system. [EEXIST] The named file exists. [ENOSPC] The directory in which the entry for the new FIFO is being placed cannot be extended because there is no space left on the file system containing the directory. [ENOSPC] There are no free inodes on the file system on which the FIFO is being created. [EDQUOT] The directory in which the entry for the new FIFO is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EDQUOT] The user's quota of inodes on the file system on which the FIFO is being created has been exhausted. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [EIO] An I/O error occurred while reading from or writing to the file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. Additionally, mmkkffiiffooaatt() will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chmod(2), stat(2), umask(2) SSTTAANNDDAARRDDSS The mmkkffiiffoo and mmkkffiiffooaatt functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmkkffiiffooaatt function appeared in OpenBSD 5.0. NNAAMMEE mmkkffiiffoo, mmkkffiiffooaatt - make a FIFO file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmkkffiiffoo(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t mmkkffiiffooaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e); DDEESSCCRRIIPPTTIIOONN mmkkffiiffoo() creates a new FIFO file with name _p_a_t_h. The access permissions are specified by _m_o_d_e and restricted by the umask(2) of the calling process. The FIFO's owner ID is set to the process's effective user ID. The FIFO's group ID is set to that of the parent directory in which it is created. The mmkkffiiffooaatt() function is equivalent to mmkkffiiffoo() except that where _p_a_t_h specifies a relative path, the newly created FIFO is created relative to the directory associated with file descriptor _f_d instead of the current working directory. If mmkkffiiffooaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to mmkkffiiffoo(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmkkffiiffoo() and mmkkffiiffooaatt() will fail and no FIFO will be created if: [EOPNOTSUPP] The kernel has not been configured to support FIFOs. [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of the path prefix does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EROFS] The named file resides on a read-only file system. [EEXIST] The named file exists. [ENOSPC] The directory in which the entry for the new FIFO is being placed cannot be extended because there is no space left on the file system containing the directory. [ENOSPC] There are no free inodes on the file system on which the FIFO is being created. [EDQUOT] The directory in which the entry for the new FIFO is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EDQUOT] The user's quota of inodes on the file system on which the FIFO is being created has been exhausted. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [EIO] An I/O error occurred while reading from or writing to the file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. Additionally, mmkkffiiffooaatt() will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chmod(2), stat(2), umask(2) SSTTAANNDDAARRDDSS The mmkkffiiffoo and mmkkffiiffooaatt functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmkkffiiffooaatt function appeared in OpenBSD 5.0. NNAAMMEE mmkknnoodd, mmkknnooddaatt - make a special file node SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmkknnoodd(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e, _d_e_v___t _d_e_v); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t mmkknnooddaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e, _d_e_v___t _d_e_v); DDEESSCCRRIIPPTTIIOONN The mmkknnoodd() function creates _p_a_t_h with a file type and mode of _m_o_d_e, as modified by umask(2). Only FIFO and device special files are supported by this implementation. If _m_o_d_e is the bitwise OR of S_IFIFO and zero or more file permissions, and _d_e_v is zero, then a FIFO is created. If _m_o_d_e is the bitwise OR of S_IFCHR or S_IFBLK and zero or more file permissions, then a character or block device special (respectively) is created with major and minor device numbers extracted from _d_e_v. The mmkknnooddaatt() function is equivalent to mmkknnoodd() except that where _p_a_t_h specifies a relative path, the newly created device special file is created relative to the directory associated with file descriptor _f_d instead of the current working directory. If mmkknnooddaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to mmkknnoodd(). Creating a device special file with mmkknnoodd() or mmkknnooddaatt() requires superuser privileges. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmkknnoodd() and mmkknnooddaatt() will fail and the file will be not created if: [EINVAL] _m_o_d_e is an invalid file type or _d_e_v is an invalid value for that file type. [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of the path prefix does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] _m_o_d_e is a device special and the process's effective user ID is not superuser. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [ENOSPC] The directory in which the entry for the new node is being placed cannot be extended because there is no space left on the file system containing the directory. [ENOSPC] There are no free inodes on the file system on which the node is being created. [EDQUOT] The directory in which the entry for the new node is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EDQUOT] The user's quota of inodes on the file system on which the node is being created has been exhausted. [EROFS] The named file resides on a read-only file system. [EEXIST] The named file exists. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EINVAL] The process is running within an alternate root directory, as created by chroot(2). Additionally, mmkknnooddaatt() will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chmod(2), chroot(2), mkfifo(2), stat(2), umask(2) SSTTAANNDDAARRDDSS The mmkknnoodd() and mmkknnooddaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmkknnoodd() system call first appeared in Version 4 AT&T UNIX, and mmkknnooddaatt() has been available since OpenBSD 5.0. NNAAMMEE mmkknnoodd, mmkknnooddaatt - make a special file node SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmkknnoodd(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e, _d_e_v___t _d_e_v); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t mmkknnooddaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _m_o_d_e___t _m_o_d_e, _d_e_v___t _d_e_v); DDEESSCCRRIIPPTTIIOONN The mmkknnoodd() function creates _p_a_t_h with a file type and mode of _m_o_d_e, as modified by umask(2). Only FIFO and device special files are supported by this implementation. If _m_o_d_e is the bitwise OR of S_IFIFO and zero or more file permissions, and _d_e_v is zero, then a FIFO is created. If _m_o_d_e is the bitwise OR of S_IFCHR or S_IFBLK and zero or more file permissions, then a character or block device special (respectively) is created with major and minor device numbers extracted from _d_e_v. The mmkknnooddaatt() function is equivalent to mmkknnoodd() except that where _p_a_t_h specifies a relative path, the newly created device special file is created relative to the directory associated with file descriptor _f_d instead of the current working directory. If mmkknnooddaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to mmkknnoodd(). Creating a device special file with mmkknnoodd() or mmkknnooddaatt() requires superuser privileges. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmkknnoodd() and mmkknnooddaatt() will fail and the file will be not created if: [EINVAL] _m_o_d_e is an invalid file type or _d_e_v is an invalid value for that file type. [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of the path prefix does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] _m_o_d_e is a device special and the process's effective user ID is not superuser. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [ENOSPC] The directory in which the entry for the new node is being placed cannot be extended because there is no space left on the file system containing the directory. [ENOSPC] There are no free inodes on the file system on which the node is being created. [EDQUOT] The directory in which the entry for the new node is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EDQUOT] The user's quota of inodes on the file system on which the node is being created has been exhausted. [EROFS] The named file resides on a read-only file system. [EEXIST] The named file exists. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EINVAL] The process is running within an alternate root directory, as created by chroot(2). Additionally, mmkknnooddaatt() will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chmod(2), chroot(2), mkfifo(2), stat(2), umask(2) SSTTAANNDDAARRDDSS The mmkknnoodd() and mmkknnooddaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmkknnoodd() system call first appeared in Version 4 AT&T UNIX, and mmkknnooddaatt() has been available since OpenBSD 5.0. NNAAMMEE mmlloocckk, mmuunnlloocckk - lock (unlock) physical pages in memory SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmlloocckk(_c_o_n_s_t _v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n); _i_n_t mmuunnlloocckk(_c_o_n_s_t _v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n); DDEESSCCRRIIPPTTIIOONN The mmlloocckk() system call locks into memory the physical pages associated with the virtual address range starting at _a_d_d_r for _l_e_n bytes. The mmuunnlloocckk() call unlocks pages previously locked by one or more mmlloocckk() calls. For both, the _a_d_d_r parameter should be aligned to a multiple of the page size. If the _l_e_n parameter is not a multiple of the page size, it will be rounded up to be so. The entire range must be allocated. After an mmlloocckk() call, the indicated pages will cause neither a non- resident page nor address-translation fault until they are unlocked. They may still cause protection-violation faults or TLB-miss faults on architectures with software-managed TLBs. The physical pages remain in memory until all locked mappings for the pages are removed. Multiple processes may have the same physical pages locked via their own virtual address mappings. A single process may likewise have pages multiply locked via different virtual mappings of the same pages or via nested mmlloocckk() calls on the same address range. Unlocking is performed explicitly by mmuunnlloocckk() or implicitly by a call to munmap(2) which deallocates the unmapped address range. Locked mappings are not inherited by the child process after a fork(2). Since physical memory is a potentially scarce resource, processes are limited in how much they can lock down. A single process can mmlloocckk() the minimum of a system-wide ``wired pages'' limit and the per-process RLIMIT_MEMLOCK resource limit. RREETTUURRNN VVAALLUUEESS The mmlloocckk() and mmuunnlloocckk() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmlloocckk() will fail if: [EINVAL] The address given is not page aligned or the length is negative. [EAGAIN] Locking the indicated range would exceed either the system or per-process limit for locked memory. [ENOMEM] Some portion of the indicated address range is not allocated. There was an error faulting/mapping a page. mmuunnlloocckk() will fail if: [EINVAL] The address given is not page aligned or _a_d_d_r and _s_i_z_e specify a region that would extend beyond the end of the address space. [ENOMEM] Some portion of the indicated address range is not allocated. Some portion of the indicated address range is not locked. SSEEEE AALLSSOO fork(2), mincore(2), minherit(2), mlockall(2), mmap(2), munmap(2), setrlimit(2), getpagesize(3) HHIISSTTOORRYY The mmlloocckk() and mmuunnlloocckk() functions first appeared in 4.4BSD. BBUUGGSS Unlike Sun's implementation, multiple mmlloocckk() calls on the same address range require the corresponding number of mmuunnlloocckk() calls to actually unlock the pages, i.e., mmlloocckk() nests. This should be considered a consequence of the implementation and not a feature. The per-process resource limit is a limit on the amount of virtual memory locked, while the system-wide limit is for the number of locked physical pages. Hence a process with two distinct locked mappings of the same physical page counts as 2 pages against the per-process limit and as only a single page in the system limit. NNAAMMEE mmlloocckkaallll, mmuunnlloocckkaallll - lock (unlock) the address space of a process SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmlloocckkaallll(_i_n_t _f_l_a_g_s); _i_n_t mmuunnlloocckkaallll(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The mmlloocckkaallll() system call locks into memory the physical pages associated with the address space of a process until the address space is unlocked, the process exits, or execs another program image. The following flags affect the behavior of mmlloocckkaallll(): MCL_CURRENT Lock all pages currently mapped into the process's address space. MCL_FUTURE Lock all pages mapped into the process's address space in the future, at the time the mapping is established. Note that this may cause future mappings to fail if those mappings cause resource limits to be exceeded. Since physical memory is a potentially scarce resource, processes are limited in how much they can lock down. A single process can lock the minimum of a system-wide ``wired pages'' limit and the per-process RLIMIT_MEMLOCK resource limit. The mmuunnlloocckkaallll() call unlocks any locked memory regions in the process address space. Any regions mapped after an mmuunnlloocckkaallll() call will not be locked. RREETTUURRNN VVAALLUUEESS The mmlloocckkaallll() and mmuunnlloocckkaallll() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmlloocckkaallll() will fail if: [EINVAL] The _f_l_a_g_s argument is zero or includes unimplemented flags. [ENOMEM] Locking all of the pages currently mapped would exceed either the system or per-process limit for locked memory. [EAGAIN] Some or all of the memory mapped into the process's address space could not be locked when the call was made. [EPERM] The calling process does not have the appropriate privileges to perform the requested operation. SSEEEE AALLSSOO mincore(2), mlock(2), mmap(2), munmap(2), setrlimit(2) SSTTAANNDDAARRDDSS The mmlloocckkaallll() and mmuunnlloocckkaallll() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmlloocckkaallll() and mmuunnlloocckkaallll() functions first appeared in OpenBSD 2.9. BBUUGGSS The per-process resource limit is a limit on the amount of virtual memory locked, while the system-wide limit is for the number of locked physical pages. Hence a process with two distinct locked mappings of the same physical page counts as 2 pages against the per-process limit and only as a single page in the system limit. NNAAMMEE mmmmaapp - map files or devices into memory SSYYNNOOPPSSIISS ##iinncclluuddee <> _v_o_i_d _* mmmmaapp(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _p_r_o_t, _i_n_t _f_l_a_g_s, _i_n_t _f_d, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN The mmmmaapp() function causes the contents of _f_d, starting at _o_f_f_s_e_t, to be mapped in memory at the given _a_d_d_r. The mapping will extend at least _l_e_n bytes, subject to page alignment restrictions. The _a_d_d_r argument describes the address where the system should place the mapping. If the MAP_FIXED flag is specified, the allocation will happen at the specified address, replacing any previously established mappings in its range. Otherwise, the mapping will be placed at the available spot at _a_d_d_r; failing that it will be placed "close by". If _a_d_d_r is NULL the system can pick any address. Except for MAP_FIXED mappings, the system will never replace existing mappings. The _l_e_n argument describes the minimum amount of bytes the mapping will span. Since mmmmaapp() maps pages into memory, _l_e_n may be rounded up to hit a page boundary. If _l_e_n is 0, the mapping will fail with EINVAL. If an _f_d and _o_f_f_s_e_t are specified, the resulting address may end up not on a page boundary, in order to align the page offset in the _a_d_d_r to the page offset in _o_f_f_s_e_t. The protections (region accessibility) are specified in the _p_r_o_t argument. It should either be PROT_NONE (no permissions) or the bitwise OR of one or more of the following values: PROT_EXEC Pages may be executed. PROT_READ Pages may be read. PROT_WRITE Pages may be written. The _f_l_a_g_s parameter specifies the type of the mapped object, mapping options, and whether modifications made to the mapped copy of the page are private to the process or are to be shared with other references. Sharing, mapping type, and options are specified in the _f_l_a_g_s argument by OR'ing the following values. Exactly one of the first two values must be specified: MAP_PRIVATE Modifications are private. MAP_SHARED Modifications are shared. Any combination of the following flags may additionally be used: MAP_ANON Map anonymous memory not associated with any specific file. The file descriptor used for creating MAP_ANON must currently be -1 indicating no name is associated with the region. MAP_ANONYMOUS Synonym for MAP_ANON. MAP_FIXED Demand that the mapping is placed at _a_d_d_r, rather than having the system select a location. _a_d_d_r, _l_e_n and _o_f_f_s_e_t (in the case of _f_d mappings) must be multiples of the page size. Existing mappings in the address range will be replaced. Use of this option is discouraged. Finally, the following flags are also provided for source compatibility with code written for other operating systems, but are not recommended for use in new OpenBSD code: MAP_COPY Modifications are private and, unlike MAP_PRIVATE, modifications made by others are not visible. On OpenBSD this behaves just like MAP_PRIVATE. MAP_FILE Mapped from a regular file, character special file, or block special file specified by file descriptor _f_d. On OpenBSD and all systems conforming to IEEE Std 1003.1-2008 (``POSIX.1'') this is the default mapping type and need not be specified. MAP_HASSEMAPHORE Notify the kernel that the region may contain semaphores and that special handling may be necessary. On OpenBSD this flag is ignored. MAP_INHERIT Permit regions to be inherited across exec(3) system calls. On OpenBSD this flag is ignored. MAP_TRYFIXED Attempt to use the hint provided by _a_d_d_r. On OpenBSD this is the default behavior. The close(2) function does not unmap pages; see munmap(2) for further information. RREETTUURRNN VVAALLUUEESS The mmmmaapp() function returns a pointer to the mapped region if successful; otherwise the value MAP_FAILED is returned and the global variable _e_r_r_n_o is set to indicate the error. A successful return from mmmmaapp() will never return the value MAP_FAILED. EERRRROORRSS mmmmaapp() will fail if: [EACCES] The flag PROT_READ was specified as part of the _p_r_o_t parameter and _f_d was not open for reading. The flags MAP_SHARED and PROT_WRITE were specified as part of the _f_l_a_g_s and _p_r_o_t parameters and _f_d was not open for writing. [EBADF] _f_d is not a valid open file descriptor. [EINVAL] MAP_PRIVATE and MAP_SHARED were both specified. [EINVAL] MAP_FIXED was specified and the _a_d_d_r parameter was not page aligned. [EINVAL] _a_d_d_r and _l_e_n specified a region that would extend beyond the end of the address space. [EINVAL] _f_d did not specify a regular, character special, or block special file. [EINVAL] The allocation _l_e_n was 0. [ENOMEM] MAP_FIXED was specified and the _a_d_d_r parameter wasn't available. MAP_ANON was specified and insufficient memory was available. SSEEEE AALLSSOO madvise(2), mincore(2), mlock(2), mprotect(2), mquery(2), msync(2), munmap(2), getpagesize(3) SSTTAANNDDAARRDDSS The mmmmaapp() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmmmaapp() system call first appeared in 4.1cBSD. CCAAVVEEAATTSS IEEE Std 1003.1-2008 (``POSIX.1'') specifies that references to pages beyond the end of a mapped object shall generate a SIGBUS signal; however, OpenBSD generates a SIGSEGV signal in this case instead. Additionally, IEEE Std 1003.1-2008 (``POSIX.1'') specifies that mmmmaapp() shall fail with EINVAL if neither MAP_PRIVATE nor MAP_SHARED is specified by _f_l_a_g_s; however, for compatibility with old programs, OpenBSD instead defaults to MAP_SHARED for mappings of character special files, and to MAP_PRIVATE for all other mappings. New programs should not rely on this behavior. BBUUGGSS Due to a limitation of the current vm system (see uvm(9)), mapping descriptors PROT_WRITE without also specifying PROT_READ is useless (results in a segmentation fault when first accessing the mapping). This means that such descriptors must be opened with O_RDWR, which requires both read and write permissions on the underlying object. NNAAMMEE mmoouunntt, uunnmmoouunntt - mount or dismount a filesystem SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t mmoouunntt(_c_o_n_s_t _c_h_a_r _*_t_y_p_e, _c_o_n_s_t _c_h_a_r _*_d_i_r, _i_n_t _f_l_a_g_s, _v_o_i_d _*_d_a_t_a); _i_n_t uunnmmoouunntt(_c_o_n_s_t _c_h_a_r _*_d_i_r, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The mmoouunntt() function grafts a filesystem object onto the system file tree at the point _d_i_r. The argument _d_a_t_a describes the filesystem object to be mounted. The argument _t_y_p_e tells the kernel how to interpret _d_a_t_a (see _t_y_p_e below). The contents of the filesystem become available through the new mount point _d_i_r. Any files in _d_i_r at the time of a successful mount are swept under the carpet, so to speak, and are unavailable until the filesystem is unmounted. The following _f_l_a_g_s may be specified to suppress default semantics which affect filesystem access. MNT_RDONLY The filesystem should be treated as read-only: even the superuser may not write to it. MNT_NOATIME Do not update the access time on files in the filesystem unless the modification or status change times are also being updated. MNT_NOEXEC Do not allow files to be executed from the filesystem. MNT_NOSUID Do not honor setuid or setgid bits on files when executing them. MNT_NODEV Do not interpret special files on the filesystem. MNT_SYNCHRONOUS All I/O to the filesystem should be done synchronously. MNT_ASYNC All I/O to the filesystem should be done asynchronously. MNT_SOFTDEP Use soft dependencies. Applies to FFS filesystems only (see 'softdep' in mount(8)). The flag MNT_UPDATE indicates that the mount command is being applied to an already mounted filesystem. This allows the mount flags to be changed without requiring that the filesystem be unmounted and remounted. Some filesystems may not allow all flags to be changed. For example, most filesystems will not allow a change from read-write to read-only. The _t_y_p_e argument defines the type of the filesystem. The types of filesystems known to the system are defined in <_s_y_s_/_m_o_u_n_t_._h>. _d_a_t_a is a pointer to a structure that contains the type specific arguments to mount. The currently supported types of filesystems and their type specific data are: MOUNT_CD9660 struct iso_args { char *fspec; /* block special device to mount */ struct export_args export_info; /* network export info */ int flags; /* mounting flags, see below */ }; #define ISOFSMNT_NORRIP 0x00000001 /* disable Rock Ridge Ext.*/ #define ISOFSMNT_GENS 0x00000002 /* enable generation numbers */ #define ISOFSMNT_EXTATT 0x00000004 /* enable extended attributes */ #define ISOFSMNT_NOJOLIET 0x00000008 /* disable Joliet Ext.*/ #define ISOFSMNT_SESS 0x00000010 /* use iso_args.sess */ MOUNT_FFS struct ufs_args { char *fspec; /* block special file to mount */ struct export_args export_info; /* network export information */ }; MOUNT_MFS struct mfs_args { char *fspec; /* name to export for statfs */ struct export_args export_info; /* if we can export an MFS */ caddr_t base; /* base of filesystem in mem */ u_long size; /* size of filesystem */ }; MOUNT_MSDOS struct msdosfs_args { char *fspec; /* blocks special holding fs to mount */ struct export_args export_info; /* network export information */ uid_t uid; /* uid that owns msdosfs files */ gid_t gid; /* gid that owns msdosfs files */ mode_t mask; /* mask to be applied for msdosfs perms */ int flags; /* see below */ }; /* * Msdosfs mount options: */ #define MSDOSFSMNT_SHORTNAME 1 /* Force old DOS short names only */ #define MSDOSFSMNT_LONGNAME 2 /* Force Win'95 long names */ #define MSDOSFSMNT_NOWIN95 4 /* Completely ignore Win95 entries */ MOUNT_NFS struct nfs_args { int version; /* args structure version */ struct sockaddr *addr; /* file server address */ int addrlen; /* length of address */ int sotype; /* Socket type */ int proto; /* and Protocol */ u_char *fh; /* File handle to be mounted */ int fhsize; /* Size, in bytes, of fh */ int flags; /* flags */ int wsize; /* write size in bytes */ int rsize; /* read size in bytes */ int readdirsize; /* readdir size in bytes */ int timeo; /* initial timeout in .1 secs */ int retrans; /* times to retry send */ int maxgrouplist; /* Max. size of group list */ int readahead; /* # of blocks to readahead */ int leaseterm; /* Term (sec) of lease */ int deadthresh; /* Retrans threshold */ char *hostname; /* server's name */ int acregmin; /* Attr cache file recently modified */ int acregmax; /* ac file not recently modified */ int acdirmin; /* ac for dir recently modified */ int acdirmax; /* ac for dir not recently modified */ }; MOUNT_NTFS struct ntfs_args { char *fspec; /* block special device to mount */ struct export_args export_info; /* network export information */ uid_t uid; /* uid that owns ntfs files */ gid_t gid; /* gid that owns ntfs files */ mode_t mode; /* mask to be applied for ntfs perms */ u_long flag; /* additional flags */ }; /* * ntfs mount options: */ #define NTFS_MFLAG_CASEINS 0x00000001 #define NTFS_MFLAG_ALLNAMES 0x00000002 MOUNT_UDF struct udf_args { char *fspec; /* block special device to mount */ }; The uunnmmoouunntt() function call disassociates the filesystem from the specified mount point _d_i_r. The _f_l_a_g_s argument may specify MNT_FORCE to specify that the filesystem should be forcibly unmounted even if files are still active. Active special devices continue to work, but any further accesses to any other active files result in errors even if the filesystem is later remounted. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmoouunntt() will fail when one of the following occurs: [EPERM] The caller is not the superuser. [ENAMETOOLONG] The path name exceeded {MNAMELEN} characters. [ELOOP] Too many symbolic links were encountered in translating a pathname. [ENOENT] A component of _d_i_r does not exist. [ENOTDIR] A component of _n_a_m_e is not a directory, or a path prefix of _s_p_e_c_i_a_l is not a directory. [EINVAL] An argument given was invalid. [EBUSY] Another process currently holds a reference to _d_i_r. [EFAULT] _d_i_r points outside the process's allocated address space. [EOPNOTSUPP] _t_y_p_e is not supported by the kernel. The following errors can occur for a ``ufs'' filesystem mount: [ENODEV] A component of ufs_args _f_s_p_e_c does not exist. [ENOTBLK] _f_s_p_e_c is not a block device. [ENXIO] The major device number of _f_s_p_e_c is out of range (this indicates no device driver exists for the associated hardware). [EBUSY] _f_s_p_e_c is already mounted. [EINVAL] The super block for the filesystem had a bad magic number, an out of range block size, or an invalid combination of flags. [ENOMEM] Not enough memory was available to read the cylinder group information for the filesystem. [EIO] An I/O error occurred while reading the super block or cylinder group information. [EFAULT] _f_s_p_e_c points outside the process's allocated address space. [EROFS] The filesystem was not unmounted cleanly and MNT_FORCE was not specified. [EROFS] An attempt was made to mount a 4.2BSD filesystem without the MNT_RDONLY flag. The following errors can occur for an _N_F_S filesystem mount: [ETIMEDOUT] _N_F_S timed out trying to contact the server. [EFAULT] Some part of the information described by nfs_args points outside the process's allocated address space. The following errors can occur for a _m_f_s filesystem mount: [EMFILE] No space remains in the mount table. [EINVAL] The super block for the filesystem had a bad magic number or an out of range block size. [ENOMEM] Not enough memory was available to read the cylinder group information for the filesystem. [EIO] A paging error occurred while reading the super block or cylinder group information. [EFAULT] _N_a_m_e points outside the process's allocated address space. uunnmmoouunntt() may fail with one of the following errors: [EPERM] The caller is not the superuser. [ENOTDIR] A component of the path is not a directory. [EINVAL] An argument given was invalid. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EINVAL] The requested directory is not in the mount table. [EBUSY] A process is holding a reference to a file located on the filesystem. [EIO] An I/O error occurred while writing cached filesystem information. [EFAULT] _d_i_r points outside the process's allocated address space. SSEEEE AALLSSOO statfs(2), mfs(8), mount(8), umount(8) HHIISSTTOORRYY The mmoouunntt() and uunnmmoouunntt() system calls first appeared in Version 1 AT&T UNIX. The _f_l_a_g_s argument is supported by mmoouunntt() since Version 5 AT&T UNIX and by uunnmmoouunntt() since 4.3BSD-Reno. The current calling convention involving _t_y_p_e and _d_a_t_a arguments was introduced by 4.3BSD-Reno as well. BBUUGGSS Some of the error codes need translation to more obvious messages. NNAAMMEE mmpprrootteecctt - control the protection of pages SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmpprrootteecctt(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _p_r_o_t); DDEESSCCRRIIPPTTIIOONN The mmpprrootteecctt() system call sets the access protections for the pages that contain the address range _a_d_d_r through _a_d_d_r + _l_e_n - 1 (inclusive). If _l_e_n is 0, no action is taken on the page that contains _a_d_d_r. The protections (region accessibility) are specified in the _p_r_o_t argument. It should either be PROT_NONE (no permissions) or the bitwise OR of one or more of the following values: PROT_EXEC Pages may be executed. PROT_READ Pages may be read. PROT_WRITE Pages may be written. Not all implementations will guarantee protection on a page basis; the granularity of protection changes may be as large as an entire region. Nor will all implementations guarantee to give exactly the requested permissions; more permissions may be granted than requested by _p_r_o_t. However, if PROT_WRITE was not specified then the page will not be writable. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmpprrootteecctt() will fail if: [EACCES] The process does not have sufficient access to the underlying memory object to provide the requested protection. [ENOMEM] The process has locked future pages with mmlloocckkaallll(_M_C_L___F_U_T_U_R_E), a page being protected is not currently accessible, and making it accessible and locked would exceed process or system limits. [EINVAL] The _p_r_o_t argument is invalid or the specified address range would wrap around. SSEEEE AALLSSOO madvise(2), mincore(2), msync(2), munmap(2) SSTTAANNDDAARRDDSS The mmpprrootteecctt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmpprrootteecctt() function first appeared in 4.4BSD. CCAAVVEEAATTSS The OpenBSD implementation of mmpprrootteecctt() does not require _a_d_d_r to be page-aligned, although other implementations may. NNAAMMEE mmqquueerryy - provide mapping hints to applications SSYYNNOOPPSSIISS ##iinncclluuddee <> _v_o_i_d _* mmqquueerryy(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _p_r_o_t, _i_n_t _f_l_a_g_s, _i_n_t _f_d, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN The mmqquueerryy() system call checks the existing memory mappings of a process and returns hints to the caller about where to put a memory mapping. This hint can be later used when performing memory mappings with the mmap(2) system call with MAP_FIXED in the flags. The _a_d_d_r argument should be a memory location that which the caller specifies the preferred address. The _s_i_z_e argument specifies the requested size of the memory area the caller is looking for. The _f_d and _o_f_f arguments specify the file that will be mapped and the offset in it, this is the same as the corresponding arguments to mmap(2). The behavior of the function depends on the _f_l_a_g_s argument. If set to MAP_FIXED the pointer _a_d_d_r is used as a fixed hint and mmqquueerryy() will return MAP_FAILED and set _e_r_r_n_o to ENOMEM if there is not _s_i_z_e bytes free after that address. Otherwise it will return the hint addr. If no flags are set mmqquueerryy() will use _a_d_d_r as a starting point in memory and will search forward to find a memory area with _s_i_z_e bytes free and that will be suitable for creating a mapping for the file and offset specified in the _f_d and _o_f_f arguments. When no such area can be found mmqquueerryy() will return and set _e_r_r_n_o to indicate the error. RREETTUURRNN VVAALLUUEESS When a memory range satisfying the request is found mmqquueerryy() returns the available address. Otherwise, MAP_FAILED is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmqquueerryy() will fail if: [EINVAL] MAP_FIXED was specified and the requested memory area is unavailable. [ENOMEM] There was not enough memory left after the hint specified. [EBADF] _f_d is not a valid open file descriptor. SSEEEE AALLSSOO mmap(2) SSTTAANNDDAARRDDSS The mmqquueerryy() function should not be used in portable applications. HHIISSTTOORRYY The mmqquueerryy() function first appeared in OpenBSD 3.4. NNAAMMEE mmssggccttll - message control operations SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmssggccttll(_i_n_t _m_s_q_i_d, _i_n_t _c_m_d, _s_t_r_u_c_t _m_s_q_i_d___d_s _*_b_u_f); DDEESSCCRRIIPPTTIIOONN The mmssggccttll() system call performs some control operations on the message queue specified by _m_s_q_i_d. Each message queue has a data structure associated with it, parts of which may be altered by mmssggccttll() and parts of which determine the actions of mmssggccttll(). The data structure is defined in <_s_y_s_/_m_s_g_._h> and contains (amongst others) the following members: struct msqid_ds { struct ipc_perm msg_perm; /* msg queue permission bits */ u_long msg_cbytes; /* # of bytes in use on the queue */ u_long msg_qnum; /* # of msgs in the queue */ u_long msg_qbytes; /* max # of bytes on the queue */ pid_t msg_lspid; /* pid of last msgsnd() */ pid_t msg_lrpid; /* pid of last msgrcv() */ time_t msg_stime; /* time of last msgsnd() */ time_t msg_rtime; /* time of last msgrcv() */ time_t msg_ctime; /* time of last msgctl() */ }; The _i_p_c___p_e_r_m structure used inside the _m_s_q_i_d___d_s structure is defined in <_s_y_s_/_i_p_c_._h> and looks like this: struct ipc_perm { uid_t cuid; /* creator user id */ gid_t cgid; /* creator group id */ uid_t uid; /* user id */ gid_t gid; /* group id */ mode_t mode; /* permission (9 bits, see chmod(2)) */ u_short seq; /* sequence # (to generate unique id) */ key_t key; /* user specified msg/sem/shm key */ }; The operation to be performed by mmssggccttll() is specified in _c_m_d and is one of: IPC_STAT Gather information about the message queue and place it in the structure pointed to by _b_u_f. IPC_SET Set the value of the _m_s_g___p_e_r_m_._u_i_d, _m_s_g___p_e_r_m_._g_i_d, _m_s_g___p_e_r_m_._m_o_d_e and _m_s_g___q_b_y_t_e_s fields in the structure associated with _m_s_q_i_d. The values are taken from the corresponding fields in the structure pointed to by _b_u_f. This operation can only be executed by the superuser, or a process that has an effective user ID equal to either _m_s_g___p_e_r_m_._c_u_i_d or _m_s_g___p_e_r_m_._u_i_d in the data structure associated with the message queue. The value of _m_s_g___q_b_y_t_e_s can only be increased by the superuser. Values for _m_s_g___q_b_y_t_e_s that exceed the system limit (MSGMNB from <_s_y_s_/_m_s_g_._h>) are silently truncated to that limit. IPC_RMID Remove the message queue specified by _m_s_q_i_d and destroy the data associated with it. Only the superuser or a process with an effective UID equal to the _m_s_g___p_e_r_m_._c_u_i_d or _m_s_g___p_e_r_m_._u_i_d values in the data structure associated with the queue can do this. The permission to read from or write to a message queue (see msgsnd(2) and msgrcv(2)) is determined by the _m_s_g___p_e_r_m_._m_o_d_e field in the same way as is done with files (see chmod(2)), but the effective UID can match either the _m_s_g___p_e_r_m_._c_u_i_d field or the _m_s_g___p_e_r_m_._u_i_d field, and the effective GID can match either _m_s_g___p_e_r_m_._c_g_i_d or _m_s_g___p_e_r_m_._g_i_d. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmssggccttll() will fail if: [EPERM] _c_m_d is equal to IPC_SET or IPC_RMID and the caller is not the superuser, nor does the effective UID match either the _m_s_g___p_e_r_m_._u_i_d or _m_s_g___p_e_r_m_._c_u_i_d fields of the data structure associated with the message queue. An attempt is made to increase the value of _m_s_g___q_b_y_t_e_s through IPC_SET but the caller is not the superuser. [EACCES] The command is IPC_STAT and the caller has no read permission for this message queue. [EINVAL] _m_s_q_i_d is not a valid message queue identifier. _c_m_d is not a valid command. [EFAULT] _b_u_f specifies an invalid address. SSEEEE AALLSSOO msgget(2), msgrcv(2), msgsnd(2) HHIISSTTOORRYY Message queues appeared in AT&T System V Release 1 UNIX. NNAAMMEE mmssggggeett - get message queue SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmssggggeett(_k_e_y___t _k_e_y, _i_n_t _m_s_g_f_l_g); DDEESSCCRRIIPPTTIIOONN mmssggggeett() returns the message queue identifier associated with _k_e_y. A message queue identifier is a unique integer greater than zero. A message queue is created if either _k_e_y is equal to IPC_PRIVATE, or _k_e_y does not have a message queue identifier associated with it, and the IPC_CREAT bit is set in _m_s_g_f_l_g. If a new message queue is created, the data structure associated with it (the _m_s_q_i_d___d_s structure, see msgctl(2)) is initialized as follows: ++oo _m_s_g___p_e_r_m_._c_u_i_d and _m_s_g___p_e_r_m_._u_i_d are set to the effective UID of the calling process. ++oo _m_s_g___p_e_r_m_._g_i_d and _m_s_g___p_e_r_m_._c_g_i_d are set to the effective GID of the calling process. ++oo _m_s_g___p_e_r_m_._m_o_d_e is set to the lower 9 bits of _m_s_g_f_l_g. ++oo _m_s_g___c_b_y_t_e_s, _m_s_g___q_n_u_m, _m_s_g___l_s_p_i_d, _m_s_g___l_r_p_i_d, _m_s_g___r_t_i_m_e, and _m_s_g___s_t_i_m_e are set to 0. ++oo _m_s_g___q_b_y_t_e_s is set to the system wide maximum value for the number of bytes in a queue (MSGMNB). ++oo _m_s_g___c_t_i_m_e is set to the current time. RREETTUURRNN VVAALLUUEESS Upon successful completion a positive message queue identifier is returned. Otherwise, -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [EACCES] A message queue is already associated with _k_e_y and the caller has no permission to access it. [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _m_s_g_f_l_g, and a message queue is already associated with _k_e_y. [ENOSPC] A new message queue could not be created because the system limit for the number of message queues has been reached. [ENOENT] IPC_CREAT was not set in _m_s_g_f_l_g and no message queue associated with _k_e_y was found. SSEEEE AALLSSOO msgctl(2), msgrcv(2), msgsnd(2), ftok(3) HHIISSTTOORRYY Message queues appeared in AT&T System V Release 1 UNIX. NNAAMMEE mmssggrrccvv - receive a message from a message queue SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmssggrrccvv(_i_n_t _m_s_q_i_d, _v_o_i_d _*_m_s_g_p, _s_i_z_e___t _m_s_g_s_z, _l_o_n_g _m_s_g_t_y_p, _i_n_t _m_s_g_f_l_g); DDEESSCCRRIIPPTTIIOONN The mmssggrrccvv() function receives a message from the message queue specified in _m_s_q_i_d, and places it into the structure pointed to by _m_s_g_p. This structure should consist of the following members: long mtype; /* message type */ char mtext[1]; /* body of message */ _m_t_y_p_e is an integer greater than 0 that can be used for selecting messages, _m_t_e_x_t is an array of bytes, with a size up to that of the system limit (MSGMAX). The value of _m_s_g_t_y_p has one of the following meanings: ++oo _m_s_g_t_y_p is greater than 0. The first message of type _m_s_g_t_y_p will be received. ++oo _m_s_g_t_y_p is equal to 0. The first message on the queue will be received. ++oo _m_s_g_t_y_p is less than 0. The first message of the lowest message type that is less than or equal to the absolute value of _m_s_g_t_y_p will be received. _m_s_g_s_z specifies the maximum length of the requested message. If the received message has a length greater than _m_s_g_s_z it will be silently truncated if the MSG_NOERROR flag is set in _m_s_g_f_l_g, otherwise an error will be returned. If no matching message is present on the message queue specified by _m_s_q_i_d, the behavior of mmssggrrccvv() depends on whether the IPC_NOWAIT flag is set in _m_s_g_f_l_g or not. If IPC_NOWAIT is set, mmssggrrccvv() will immediately return a value of -1, and set _e_r_r_n_o to EAGAIN. If IPC_NOWAIT is not set, the calling process will be blocked until: ++oo A message of the requested type becomes available on the message queue. ++oo The message queue is removed, in which case -1 will be returned, and _e_r_r_n_o set to EINVAL. ++oo A signal is received and caught. -1 is returned, and _e_r_r_n_o set to EINTR. If a message is successfully received, the data structure associated with _m_s_q_i_d is updated as follows: ++oo _m_s_g___c_b_y_t_e_s is decremented by the size of the message. ++oo _m_s_g___l_r_p_i_d is set to the pid of the caller. ++oo _m_s_g___l_r_t_i_m_e is set to the current time. ++oo _m_s_g___q_n_u_m is decremented by 1. RREETTUURRNN VVAALLUUEESS Upon successful completion, mmssggrrccvv() returns the number of bytes received into the _m_t_e_x_t field of the structure pointed to by _m_s_g_p. Otherwise, -1 is returned, and _e_r_r_n_o set to indicate the error. EERRRROORRSS mmssggrrccvv() will fail if: [EINVAL] _m_s_q_i_d is not a valid message queue identifier. _m_s_g_s_z is less than 0. [E2BIG] A matching message was received, but its size was greater than _m_s_g_s_z and the MSG_NOERROR flag was not set in _m_s_g_f_l_g. [EACCES] The calling process does not have read access to the message queue. [EFAULT] _m_s_g_p points to an invalid address. [EINTR] The system call was interrupted by the delivery of a signal. [ENOMSG] There is no message of the requested type available on the message queue, and IPC_NOWAIT is set in _m_s_g_f_l_g. [EIDRM] The message queue was removed while mmssggrrccvv() was waiting for a message of the requested type to become available on it. SSEEEE AALLSSOO msgctl(2), msgget(2), msgsnd(2) HHIISSTTOORRYY Message queues appeared in AT&T System V Release 1 UNIX. NNAAMMEE mmssggssnndd - send a message to a message queue SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmssggssnndd(_i_n_t _m_s_q_i_d, _c_o_n_s_t _v_o_i_d _*_m_s_g_p, _s_i_z_e___t _m_s_g_s_z, _i_n_t _m_s_g_f_l_g); DDEESSCCRRIIPPTTIIOONN The mmssggssnndd() function sends a message to the message queue specified by _m_s_q_i_d. _m_s_g_p points to a structure containing the message. This structure should consist of the following members: long mtype; /* message type */ char mtext[1]; /* body of message */ _m_t_y_p_e is an integer greater than 0 that can be used for selecting messages (see msgrcv(2)); _m_t_e_x_t is an array of _m_s_g_s_z bytes, with a size between 0 and that of the system limit (MSGMAX). If the number of bytes already on the message queue plus _m_s_g_s_z is bigger than the maximum number of bytes on the message queue (_m_s_g___q_b_y_t_e_s, see msgctl(2)), or the number of messages on all queues system-wide is already equal to the system limit, _m_s_g_f_l_g determines the action of mmssggssnndd(). If _m_s_g_f_l_g has IPC_NOWAIT mask set in it, the call will return immediately. If _m_s_g_f_l_g does not have IPC_NOWAIT set in it, the call will block until: ++oo The condition which caused the call to block does no longer exist. The message will be sent. ++oo The message queue is removed, in which case -1 will be returned, and _e_r_r_n_o is set to EINVAL. ++oo The caller catches a signal. The call returns with _e_r_r_n_o set to EINTR. After a successful call, the data structure associated with the message queue is updated in the following way: ++oo _m_s_g___c_b_y_t_e_s is incremented by the size of the message. ++oo _m_s_g___q_n_u_m is incremented by 1. ++oo _m_s_g___l_s_p_i_d is set to the pid of the calling process. ++oo _m_s_g___s_t_i_m_e is set to the current time. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmssggssnndd() will fail if: [EINVAL] _m_s_q_i_d is not a valid message queue identifier. _m_s_g_s_z is greater than _m_s_g___q_b_y_t_e_s. [EACCES] The calling process does not have write access to the message queue. [EAGAIN] There was no space for this message either on the queue, or in the whole system, and IPC_NOWAIT was set in _m_s_g_f_l_g. [EFAULT] _m_s_g_p points to an invalid address. [EINTR] The system call was interrupted by the delivery of a signal. [EIDRM] The message queue was removed while mmssggssnndd() was waiting for a resource to become available in order to deliver the message. SSEEEE AALLSSOO msgctl(2), msgget(2), msgrcv(2) HHIISSTTOORRYY Message queues appeared in AT&T System V Release 1 UNIX. NNAAMMEE mmssyynncc - synchronize a mapped region SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmssyynncc(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The mmssyynncc() system call writes all pages with shared modifications in the specified region of the process's address space back to permanent storage, and, if requested, invalidates cached data mapped in the region. If _l_e_n is 0, all modified pages within the region containing _a_d_d_r will be flushed; if _l_e_n is non-zero, only modified pages containing _a_d_d_r and _l_e_n_-_1 succeeding locations will be flushed. Any required synchronization of memory caches will also take place at this time. Filesystem operations on a file that is mapped for shared modifications are unpredictable except after an mmssyynncc(). The _f_l_a_g_s argument is the bitwise OR of zero or more of the following values: MS_ASYNC Perform asynchronous writes. MS_SYNC Perform synchronous writes. MS_INVALIDATE Invalidate cached data after writing. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The following errors may be reported: [EBUSY] The MS_INVALIDATE flag was specified and a portion of the specified region was locked with mlock(2). [EINVAL] The specified _f_l_a_g_s argument was invalid. [EINVAL] The _a_d_d_r parameter was not page aligned or _a_d_d_r and _s_i_z_e specify a region that would extend beyond the end of the address space. [ENOMEM] Addresses in the specified region are outside the range allowed for the address space of the process, or specify one or more pages which are unmapped. [EIO] An I/O error occurred while writing. SSEEEE AALLSSOO madvise(2), mincore(2), minherit(2), mprotect(2), munmap(2) HHIISSTTOORRYY The mmssyynncc() function first appeared in 4.4BSD. It was modified to conform to IEEE Std 1003.1b-1993 (``POSIX.1b'') BBUUGGSS Writes are currently done synchronously even if the MS_ASYNC flag is specified. NNAAMMEE mmlloocckk, mmuunnlloocckk - lock (unlock) physical pages in memory SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmlloocckk(_c_o_n_s_t _v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n); _i_n_t mmuunnlloocckk(_c_o_n_s_t _v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n); DDEESSCCRRIIPPTTIIOONN The mmlloocckk() system call locks into memory the physical pages associated with the virtual address range starting at _a_d_d_r for _l_e_n bytes. The mmuunnlloocckk() call unlocks pages previously locked by one or more mmlloocckk() calls. For both, the _a_d_d_r parameter should be aligned to a multiple of the page size. If the _l_e_n parameter is not a multiple of the page size, it will be rounded up to be so. The entire range must be allocated. After an mmlloocckk() call, the indicated pages will cause neither a non- resident page nor address-translation fault until they are unlocked. They may still cause protection-violation faults or TLB-miss faults on architectures with software-managed TLBs. The physical pages remain in memory until all locked mappings for the pages are removed. Multiple processes may have the same physical pages locked via their own virtual address mappings. A single process may likewise have pages multiply locked via different virtual mappings of the same pages or via nested mmlloocckk() calls on the same address range. Unlocking is performed explicitly by mmuunnlloocckk() or implicitly by a call to munmap(2) which deallocates the unmapped address range. Locked mappings are not inherited by the child process after a fork(2). Since physical memory is a potentially scarce resource, processes are limited in how much they can lock down. A single process can mmlloocckk() the minimum of a system-wide ``wired pages'' limit and the per-process RLIMIT_MEMLOCK resource limit. RREETTUURRNN VVAALLUUEESS The mmlloocckk() and mmuunnlloocckk() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmlloocckk() will fail if: [EINVAL] The address given is not page aligned or the length is negative. [EAGAIN] Locking the indicated range would exceed either the system or per-process limit for locked memory. [ENOMEM] Some portion of the indicated address range is not allocated. There was an error faulting/mapping a page. mmuunnlloocckk() will fail if: [EINVAL] The address given is not page aligned or _a_d_d_r and _s_i_z_e specify a region that would extend beyond the end of the address space. [ENOMEM] Some portion of the indicated address range is not allocated. Some portion of the indicated address range is not locked. SSEEEE AALLSSOO fork(2), mincore(2), minherit(2), mlockall(2), mmap(2), munmap(2), setrlimit(2), getpagesize(3) HHIISSTTOORRYY The mmlloocckk() and mmuunnlloocckk() functions first appeared in 4.4BSD. BBUUGGSS Unlike Sun's implementation, multiple mmlloocckk() calls on the same address range require the corresponding number of mmuunnlloocckk() calls to actually unlock the pages, i.e., mmlloocckk() nests. This should be considered a consequence of the implementation and not a feature. The per-process resource limit is a limit on the amount of virtual memory locked, while the system-wide limit is for the number of locked physical pages. Hence a process with two distinct locked mappings of the same physical page counts as 2 pages against the per-process limit and as only a single page in the system limit. NNAAMMEE mmlloocckkaallll, mmuunnlloocckkaallll - lock (unlock) the address space of a process SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmlloocckkaallll(_i_n_t _f_l_a_g_s); _i_n_t mmuunnlloocckkaallll(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The mmlloocckkaallll() system call locks into memory the physical pages associated with the address space of a process until the address space is unlocked, the process exits, or execs another program image. The following flags affect the behavior of mmlloocckkaallll(): MCL_CURRENT Lock all pages currently mapped into the process's address space. MCL_FUTURE Lock all pages mapped into the process's address space in the future, at the time the mapping is established. Note that this may cause future mappings to fail if those mappings cause resource limits to be exceeded. Since physical memory is a potentially scarce resource, processes are limited in how much they can lock down. A single process can lock the minimum of a system-wide ``wired pages'' limit and the per-process RLIMIT_MEMLOCK resource limit. The mmuunnlloocckkaallll() call unlocks any locked memory regions in the process address space. Any regions mapped after an mmuunnlloocckkaallll() call will not be locked. RREETTUURRNN VVAALLUUEESS The mmlloocckkaallll() and mmuunnlloocckkaallll() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmlloocckkaallll() will fail if: [EINVAL] The _f_l_a_g_s argument is zero or includes unimplemented flags. [ENOMEM] Locking all of the pages currently mapped would exceed either the system or per-process limit for locked memory. [EAGAIN] Some or all of the memory mapped into the process's address space could not be locked when the call was made. [EPERM] The calling process does not have the appropriate privileges to perform the requested operation. SSEEEE AALLSSOO mincore(2), mlock(2), mmap(2), munmap(2), setrlimit(2) SSTTAANNDDAARRDDSS The mmlloocckkaallll() and mmuunnlloocckkaallll() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmlloocckkaallll() and mmuunnlloocckkaallll() functions first appeared in OpenBSD 2.9. BBUUGGSS The per-process resource limit is a limit on the amount of virtual memory locked, while the system-wide limit is for the number of locked physical pages. Hence a process with two distinct locked mappings of the same physical page counts as 2 pages against the per-process limit and only as a single page in the system limit. NNAAMMEE mmuunnmmaapp - remove a mapping SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmuunnmmaapp(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n); DDEESSCCRRIIPPTTIIOONN The mmuunnmmaapp() system call deletes the mappings for the specified address range, and causes further references to addresses within the range to generate invalid memory references. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmuunnmmaapp() will fail if: [EINVAL] The _a_d_d_r parameter was not page aligned, _a_d_d_r and _l_e_n specify a region that would extend beyond the end of the address space, or some part of the region being unmapped is not part of the currently valid address space. SSEEEE AALLSSOO madvise(2), mincore(2), mlock(2), mlockall(2), mmap(2), mprotect(2), msync(2), getpagesize(3) HHIISSTTOORRYY The mmuunnmmaapp() system call first appeared in 4.1cBSD. NNAAMMEE nnaannoosslleeeepp - high resolution sleep SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t nnaannoosslleeeepp(_c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t, _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_r_e_m_a_i_n_d_e_r); DDEESSCCRRIIPPTTIIOONN nnaannoosslleeeepp() suspends execution of the calling process for the duration specified by _t_i_m_e_o_u_t. An unmasked signal will cause it to terminate the sleep early, regardless of the SA_RESTART value on the interrupting signal. RREETTUURRNN VVAALLUUEESS If the nnaannoosslleeeepp() function returns because the requested duration has elapsed, the value returned will be zero. If the nnaannoosslleeeepp() function returns due to the delivery of a signal, the value returned will be -1, and the global variable _e_r_r_n_o will be set to indicate the interruption. If _r_e_m_a_i_n_d_e_r is non-null, the timespec structure it references is updated to contain the unslept amount (the requested duration minus the duration actually slept). EERRRROORRSS If any of the following conditions occur, the nnaannoosslleeeepp() function shall return -1 and set _e_r_r_n_o to the corresponding value. [EINTR] kkqquueeuuee was interrupted by the delivery of a signal. [EINVAL] _t_i_m_e_o_u_t specified a nanosecond value less than zero or greater than 1000 million, or a second value less than zero or greater than 100 million. [EFAULT] Either _t_i_m_e_o_u_t or _r_e_m_a_i_n_d_e_r points to memory that is not a valid part of the process address space. SSEEEE AALLSSOO sleep(1), sleep(3) SSTTAANNDDAARRDDSS The nnaannoosslleeeepp() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The predecessor of this system call, sslleeeepp(), appeared in Version 3 AT&T UNIX, but was removed when alarm(3) was introduced into Version 7 AT&T UNIX. The nnaannoosslleeeepp() system call has been available since NetBSD 1.3 and was ported to OpenBSD 2.1 and FreeBSD 3.0. NNAAMMEE nnffssssvvcc - NFS services SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t nnffssssvvcc(_i_n_t _f_l_a_g_s, _v_o_i_d _*_a_r_g_s_t_r_u_c_t_p); DDEESSCCRRIIPPTTIIOONN The nnffssssvvcc() function is used by NFS daemons to pass information into the kernel and also to enter the kernel as a server daemon. The _f_l_a_g_s argument consists of several bits that show what action is to be taken once in the kernel and the _a_r_g_s_t_r_u_c_t_p points to one of two structures depending on which bits are set in flags. To enter an nfsd(8) daemon into the kernel, nnffssssvvcc() is called with the flag NFSSVC_NFSD and a pointer to a structure: struct nfsd_srvargs { struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ uid_t nsd_uid; /* Effective uid mapped to cred */ u_int32_t nsd_haddr; /* IP address of client */ struct xucred nsd_cr; /* Cred. uid maps to */ int nsd_authlen; /* Length of auth string (ret) */ u_char *nsd_authstr; /* Auth string (ret) */ int nsd_verflen; /* and the verifier */ u_char *nsd_verfstr; struct timeval nsd_timestamp; /* timestamp from verifier */ u_int32_t nsd_ttl; /* credential ttl (sec) */ }; To add further sockets for processing by the nfsd(8) server daemons the master nfsd(8) daemon calls nnffssssvvcc() with the flag NFSSVC_ADDSOCK and a pointer to a structure: struct nfsd_args { int sock; /* Socket to serve */ caddr_t name; /* Client address for connection based sockets */ int namelen; /* Length of name */ }; RREETTUURRNN VVAALLUUEESS Normally nnffssssvvcc does not return unless the server is terminated by a signal when a value of 0 is returned. Otherwise, -1 is returned and the global variable _e_r_r_n_o is set to specify the error. EERRRROORRSS [EPERM] The caller is not the superuser. [EINVAL] The flag argument consisted of incompatible or otherwise unsupported bits. SSEEEE AALLSSOO mount_nfs(8), nfsd(8), sysctl(8) HHIISSTTOORRYY The nnffssssvvcc function first appeared in 4.4BSD. BBUUGGSS The nnffssssvvcc system call is designed specifically for the NFS support daemons and as such is specific to their requirements. Several fields of the argument structures are assumed to be valid and sometimes to be unchanged from a previous call, such that nnffssssvvcc() must be used with extreme care. NNAAMMEE ooppeenn, ooppeennaatt - open or create a file for reading or writing SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ooppeenn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _f_l_a_g_s, _._._.); _i_n_t ooppeennaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _f_l_a_g_s, _._._.); DDEESSCCRRIIPPTTIIOONN The file name specified by _p_a_t_h is opened for reading and/or writing as specified by the argument _f_l_a_g_s and the file descriptor returned to the calling process. The _f_l_a_g_s argument may indicate the file is to be created if it does not exist (by specifying the O_CREAT flag), in which case the file is created with a mode specified by an additional argument of type _m_o_d_e___t as described in chmod(2) and modified by the process' umask value (see umask(2)). The _f_l_a_g_s specified are a bitwise OR of the following values. Exactly one of the first three values (file access modes) must be specified: O_RDONLY Open for reading only. O_WRONLY Open for writing only. O_RDWR Open for reading and writing. Any combination of the following flags may additionally be used: O_NONBLOCK Do not block on open or for data to become available. O_APPEND Append on each write. O_CREAT Create file if it does not exist. An additional argument of type _m_o_d_e___t must be supplied to the call. O_TRUNC Truncate size to 0. O_EXCL Error if O_CREAT is set and file exists. O_SYNC Perform synchronous I/O operations. O_SHLOCK Atomically obtain a shared lock. O_EXLOCK Atomically obtain an exclusive lock. O_NOFOLLOW If last path element is a symlink, don't follow it. O_CLOEXEC Set FD_CLOEXEC (the close-on-exec flag) on the new file descriptor. O_DIRECTORY Error if _p_a_t_h does not name a directory. Opening a file with O_APPEND set causes each write on the file to be appended to the end. If O_TRUNC and a writing mode are specified and the file exists, the file is truncated to zero length. If O_EXCL is set with O_CREAT and the file already exists, ooppeenn() returns an error. This may be used to implement a simple exclusive access locking mechanism. If either of O_EXCL or O_NOFOLLOW are set and the last component of the pathname is a symbolic link, ooppeenn() will fail even if the symbolic link points to a non-existent name. If the O_NONBLOCK flag is specified, do not wait for the device or file to be ready or available. If the ooppeenn() call would result in the process being blocked for some reason (e.g., waiting for carrier on a dialup line), ooppeenn() returns immediately. This flag also has the effect of making all subsequent I/O on the open file non-blocking. If the O_SYNC flag is set, all I/O operations on the file will be done synchronously. A FIFO should either be opened with O_RDONLY or with O_WRONLY. The behavior for opening a FIFO with O_RDWR is undefined. When opening a file, a lock with flock(2) semantics can be obtained by setting O_SHLOCK for a shared lock, or O_EXLOCK for an exclusive lock. If creating a file with O_CREAT, the request for the lock will never fail (provided that the underlying filesystem supports locking). If ooppeenn() is successful, the file pointer used to mark the current position within the file is set to the beginning of the file. When a new file is created it is given the group of the directory which contains it. The new descriptor is set to remain open across execve(2) system calls; see close(2) and fcntl(2). The system imposes a limit on the number of file descriptors open simultaneously by one process. getdtablesize(3) returns the current system limit. The ooppeennaatt() function is equivalent to ooppeenn() except that where _p_a_t_h specifies a relative path, the file to be opened is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ooppeennaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ooppeenn(). RREETTUURRNN VVAALLUUEESS If successful, ooppeenn() returns a non-negative integer, termed a file descriptor. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS The ooppeenn() and ooppeennaatt() functions will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENOTDIR] O_DIRECTORY is specified and _p_a_t_h does not name a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] O_CREAT is not set and the named file does not exist. [ENOENT] A component of the path name that must exist does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] The required permissions (for reading and/or writing) are denied for the given _f_l_a_g_s. [EACCES] O_CREAT is specified, the file does not exist, and the directory in which it is to be created does not permit writing. [ELOOP] Too many symbolic links were encountered in translating the pathname, or the O_NOFOLLOW flag was specified and the target is a symbolic link. [EISDIR] The named file is a directory, and the arguments specify it is to be opened for writing. [EINVAL] The _f_l_a_g_s specified for opening the file are not valid. [EROFS] The named file resides on a read-only file system, and the file is to be modified. [EMFILE] The process has already reached its limit for open file descriptors. [ENFILE] The system file table is full. [ENXIO] The named file is a character special or block special file, and the device associated with this special file does not exist. [ENXIO] The named file is a FIFO, the O_NONBLOCK and O_WRONLY flags are set, and no process has the file open for reading. [EINTR] The ooppeenn() operation was interrupted by a signal. [EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying filesystem does not support locking. [EWOULDBLOCK] O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is specified and the file is already locked. [ENOSPC] O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed cannot be extended because there is no space left on the file system containing the directory. [ENOSPC] O_CREAT is specified, the file does not exist, and there are no free inodes on the file system on which the file is being created. [EDQUOT] O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EDQUOT] O_CREAT is specified, the file does not exist, and the user's quota of inodes on the file system on which the file is being created has been exhausted. [EIO] An I/O error occurred while making the directory entry or allocating the inode for O_CREAT. [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and the ooppeenn() call requests write access. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EEXIST] O_CREAT and O_EXCL were specified and the file exists. [EPERM] The file named by _p_a_t_h is flagged append-only but O_APPEND was not specified in _f_l_a_g_s. [EOPNOTSUPP] An attempt was made to open a socket (not currently implemented). [EBUSY] An attempt was made to open a terminal device that requires exclusive access and the specified device has already be opened. Additionally, the ooppeennaatt() function will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chflags(2), chmod(2), close(2), dup(2), flock(2), lseek(2), read(2), umask(2), write(2), getdtablesize(3) SSTTAANNDDAARRDDSS The ooppeenn() and ooppeennaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). POSIX specifies three different flavors for synchronous I/O: O_SYNC, O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent. The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should not be used if portability is of concern. HHIISSTTOORRYY An ooppeenn() system call first appeared in Version 1 AT&T UNIX. The _f_l_a_g_s argument has been supported since 4.2BSD. Before that, a dedicated ccrreeaatt() system call had to be used to create new files; it appeared in Version 1 AT&T UNIX, was deprecated in 4.3BSD-Reno, and removed in OpenBSD 5.0. The ooppeennaatt() system call has been available since OpenBSD 5.0. CCAAVVEEAATTSS The O_TRUNC flag requires that one of O_RDWR or O_WRONLY also be specified, else EINVAL is returned. NNAAMMEE ooppeenn, ooppeennaatt - open or create a file for reading or writing SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ooppeenn(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _f_l_a_g_s, _._._.); _i_n_t ooppeennaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _f_l_a_g_s, _._._.); DDEESSCCRRIIPPTTIIOONN The file name specified by _p_a_t_h is opened for reading and/or writing as specified by the argument _f_l_a_g_s and the file descriptor returned to the calling process. The _f_l_a_g_s argument may indicate the file is to be created if it does not exist (by specifying the O_CREAT flag), in which case the file is created with a mode specified by an additional argument of type _m_o_d_e___t as described in chmod(2) and modified by the process' umask value (see umask(2)). The _f_l_a_g_s specified are a bitwise OR of the following values. Exactly one of the first three values (file access modes) must be specified: O_RDONLY Open for reading only. O_WRONLY Open for writing only. O_RDWR Open for reading and writing. Any combination of the following flags may additionally be used: O_NONBLOCK Do not block on open or for data to become available. O_APPEND Append on each write. O_CREAT Create file if it does not exist. An additional argument of type _m_o_d_e___t must be supplied to the call. O_TRUNC Truncate size to 0. O_EXCL Error if O_CREAT is set and file exists. O_SYNC Perform synchronous I/O operations. O_SHLOCK Atomically obtain a shared lock. O_EXLOCK Atomically obtain an exclusive lock. O_NOFOLLOW If last path element is a symlink, don't follow it. O_CLOEXEC Set FD_CLOEXEC (the close-on-exec flag) on the new file descriptor. O_DIRECTORY Error if _p_a_t_h does not name a directory. Opening a file with O_APPEND set causes each write on the file to be appended to the end. If O_TRUNC and a writing mode are specified and the file exists, the file is truncated to zero length. If O_EXCL is set with O_CREAT and the file already exists, ooppeenn() returns an error. This may be used to implement a simple exclusive access locking mechanism. If either of O_EXCL or O_NOFOLLOW are set and the last component of the pathname is a symbolic link, ooppeenn() will fail even if the symbolic link points to a non-existent name. If the O_NONBLOCK flag is specified, do not wait for the device or file to be ready or available. If the ooppeenn() call would result in the process being blocked for some reason (e.g., waiting for carrier on a dialup line), ooppeenn() returns immediately. This flag also has the effect of making all subsequent I/O on the open file non-blocking. If the O_SYNC flag is set, all I/O operations on the file will be done synchronously. A FIFO should either be opened with O_RDONLY or with O_WRONLY. The behavior for opening a FIFO with O_RDWR is undefined. When opening a file, a lock with flock(2) semantics can be obtained by setting O_SHLOCK for a shared lock, or O_EXLOCK for an exclusive lock. If creating a file with O_CREAT, the request for the lock will never fail (provided that the underlying filesystem supports locking). If ooppeenn() is successful, the file pointer used to mark the current position within the file is set to the beginning of the file. When a new file is created it is given the group of the directory which contains it. The new descriptor is set to remain open across execve(2) system calls; see close(2) and fcntl(2). The system imposes a limit on the number of file descriptors open simultaneously by one process. getdtablesize(3) returns the current system limit. The ooppeennaatt() function is equivalent to ooppeenn() except that where _p_a_t_h specifies a relative path, the file to be opened is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ooppeennaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ooppeenn(). RREETTUURRNN VVAALLUUEESS If successful, ooppeenn() returns a non-negative integer, termed a file descriptor. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS The ooppeenn() and ooppeennaatt() functions will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENOTDIR] O_DIRECTORY is specified and _p_a_t_h does not name a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] O_CREAT is not set and the named file does not exist. [ENOENT] A component of the path name that must exist does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] The required permissions (for reading and/or writing) are denied for the given _f_l_a_g_s. [EACCES] O_CREAT is specified, the file does not exist, and the directory in which it is to be created does not permit writing. [ELOOP] Too many symbolic links were encountered in translating the pathname, or the O_NOFOLLOW flag was specified and the target is a symbolic link. [EISDIR] The named file is a directory, and the arguments specify it is to be opened for writing. [EINVAL] The _f_l_a_g_s specified for opening the file are not valid. [EROFS] The named file resides on a read-only file system, and the file is to be modified. [EMFILE] The process has already reached its limit for open file descriptors. [ENFILE] The system file table is full. [ENXIO] The named file is a character special or block special file, and the device associated with this special file does not exist. [ENXIO] The named file is a FIFO, the O_NONBLOCK and O_WRONLY flags are set, and no process has the file open for reading. [EINTR] The ooppeenn() operation was interrupted by a signal. [EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying filesystem does not support locking. [EWOULDBLOCK] O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is specified and the file is already locked. [ENOSPC] O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed cannot be extended because there is no space left on the file system containing the directory. [ENOSPC] O_CREAT is specified, the file does not exist, and there are no free inodes on the file system on which the file is being created. [EDQUOT] O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EDQUOT] O_CREAT is specified, the file does not exist, and the user's quota of inodes on the file system on which the file is being created has been exhausted. [EIO] An I/O error occurred while making the directory entry or allocating the inode for O_CREAT. [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and the ooppeenn() call requests write access. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EEXIST] O_CREAT and O_EXCL were specified and the file exists. [EPERM] The file named by _p_a_t_h is flagged append-only but O_APPEND was not specified in _f_l_a_g_s. [EOPNOTSUPP] An attempt was made to open a socket (not currently implemented). [EBUSY] An attempt was made to open a terminal device that requires exclusive access and the specified device has already be opened. Additionally, the ooppeennaatt() function will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO chflags(2), chmod(2), close(2), dup(2), flock(2), lseek(2), read(2), umask(2), write(2), getdtablesize(3) SSTTAANNDDAARRDDSS The ooppeenn() and ooppeennaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). POSIX specifies three different flavors for synchronous I/O: O_SYNC, O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent. The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should not be used if portability is of concern. HHIISSTTOORRYY An ooppeenn() system call first appeared in Version 1 AT&T UNIX. The _f_l_a_g_s argument has been supported since 4.2BSD. Before that, a dedicated ccrreeaatt() system call had to be used to create new files; it appeared in Version 1 AT&T UNIX, was deprecated in 4.3BSD-Reno, and removed in OpenBSD 5.0. The ooppeennaatt() system call has been available since OpenBSD 5.0. CCAAVVEEAATTSS The O_TRUNC flag requires that one of O_RDWR or O_WRONLY also be specified, else EINVAL is returned. NNAAMMEE ppaatthhccoonnff, ffppaatthhccoonnff - get configurable pathname variables SSYYNNOOPPSSIISS ##iinncclluuddee <> _l_o_n_g ppaatthhccoonnff(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _n_a_m_e); _l_o_n_g ffppaatthhccoonnff(_i_n_t _f_d, _i_n_t _n_a_m_e); DDEESSCCRRIIPPTTIIOONN The ppaatthhccoonnff() and ffppaatthhccoonnff() functions provide a method for applications to determine the current value of a configurable system limit or option variable associated with a pathname or file descriptor. For ppaatthhccoonnff, the _p_a_t_h argument is the name of a file or directory. For ffppaatthhccoonnff, the _f_d argument is an open file descriptor. The _n_a_m_e argument specifies the system variable to be queried. Symbolic constants for each name value are found in the include file <_u_n_i_s_t_d_._h>. The available values are as follows: _PC_LINK_MAX The maximum file link count. _PC_MAX_CANON The maximum number of bytes in a terminal canonical input line. _PC_MAX_INPUT The maximum number of bytes for which space is available in a terminal input queue. _PC_NAME_MAX The maximum number of bytes in a file name. _PC_PATH_MAX The maximum number of bytes in a pathname. _PC_PIPE_BUF The maximum number of bytes which will be written atomically to a pipe. _PC_CHOWN_RESTRICTED Returns 1 if appropriate privileges are required for the chown(2) system call, otherwise 0. IEEE Std 1003.1-2001 (``POSIX.1'') requires appropriate privilege in all cases, but this behavior was optional in prior editions of the standard. _PC_NO_TRUNC Returns 1 if attempts to use pathname components longer than {NAME_MAX} will result in an [ENAMETOOLONG] error; otherwise, such components will be truncated to {NAME_MAX}. IEEE Std 1003.1-2001 (``POSIX.1'') requires the error in all cases, but this behavior was optional in prior editions of the standard, and some non-POSIX-compliant file systems do not support this behavior. _PC_VDISABLE Returns the terminal character disabling value. _PC_2_SYMLINKS Returns 1 if the filesystem supports the creation of symbolic links within the specified directory; the meaning of _PC_2_SYMLINKS is unspecified for non-directory files. _PC_ALLOC_SIZE_MIN Minimum number of bytes of storage allocated for any portion of a file. _PC_ASYNC_IO Returns 1 if asynchronous I/O is supported, otherwise 0. _PC_FILESIZEBITS Number of bits needed to represent the maximum file size. _PC_PRIO_IO Returns 1 if prioritized I/O is supported, otherwise 0. _PC_REC_INCR_XFER_SIZE Recommended increment for file transfer sizes between _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE. _PC_REC_MAX_XFER_SIZE Maximum recommended file transfer size. _PC_REC_MIN_XFER_SIZE Minimum recommended file transfer size. _PC_REC_XFER_ALIGN Recommended file transfer buffer alignment. _PC_SYMLINK_MAX Maximum number of bytes in a symbolic link. _PC_SYNC_IO Returns 1 if synchronized I/O is supported, otherwise 0. _PC_TIMESTAMP_RESOLUTION The resolution in nanoseconds of file timestamps. RREETTUURRNN VVAALLUUEESS If the call to ppaatthhccoonnff or ffppaatthhccoonnff is not successful, -1 is returned and _e_r_r_n_o is set appropriately. Otherwise, if the variable is associated with functionality that does not have a limit in the system, -1 is returned and _e_r_r_n_o is not modified. Otherwise, the current variable value is returned. EERRRROORRSS If any of the following conditions occur, the ppaatthhccoonnff and ffppaatthhccoonnff functions shall return -1 and set _e_r_r_n_o to the corresponding value. [EINVAL] The value of the _n_a_m_e argument is invalid. [EINVAL] The implementation does not support an association of the variable name with the associated file. [EIO] An I/O error occurred while reading from the file system. ppaatthhccoonnff() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters (but see _PC_NO_TRUNC above), or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _p_a_t_h points outside the process's allocated address space. ffppaatthhccoonnff() will fail if: [EBADF] _f_d is not a valid open file descriptor. SSEEEE AALLSSOO sysconf(3), sysctl(3) SSTTAANNDDAARRDDSS The ppaatthhccoonnff and ffppaatthhccoonnff functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ppaatthhccoonnff and ffppaatthhccoonnff functions first appeared in 4.4BSD. NNAAMMEE ppiippee, ppiippee22 - create descriptor pair for interprocess communication SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ppiippee(_i_n_t _f_i_l_d_e_s_[_2_]); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ppiippee22(_i_n_t _f_i_l_d_e_s_[_2_], _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The ppiippee() function creates a _p_i_p_e, which is an object allowing unidirectional data flow, and allocates a pair of file descriptors. The first descriptor connects to the _r_e_a_d _e_n_d of the pipe, and the second connects to the _w_r_i_t_e _e_n_d, so that data written to _f_i_l_d_e_s_[_1_] appears on (i.e., can be read from) _f_i_l_d_e_s_[_0_]. This allows the output of one program to be sent to another program: the source's standard output is set up to be the write end of the pipe, and the sink's standard input is set up to be the read end of the pipe. The pipe itself persists until all its associated descriptors are closed. A pipe whose read or write end has been closed is considered _w_i_d_o_w_e_d. Writing on such a pipe causes the writing process to receive a SIGPIPE signal. Widowing a pipe is the only way to deliver end-of-file to a reader: after the reader consumes any buffered data, reading a widowed pipe returns a zero count. The ppiippee22() function is identical to ppiippee() except that the non-blocking I/O mode on both ends of the pipe is determined by the O_NONBLOCK flag in the _f_l_a_g_s argument and the close-on-exec flag on both the new file descriptors is determined by the O_CLOEXEC flag in the _f_l_a_g_s argument. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ppiippee() and ppiippee22() will succeed unless: [EMFILE] Too many descriptors are active. [ENFILE] The system file table is full. [EFAULT] The _f_i_l_d_e_s buffer is in an invalid area of the process's address space. In addition, ppiippee22() may return the following error: [EINVAL] _f_l_a_g_s is invalid. SSEEEE AALLSSOO sh(1), fork(2), read(2), socketpair(2), write(2) SSTTAANNDDAARRDDSS The ppiippee() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The ppiippee22() function is expected to conform to a future revision of that standard. As an extension, the pipe provided is actually capable of moving data bidirectionally. This is compatible with SVR4. However, this is non- POSIX behaviour which should not be relied on, for reasons of portability. HHIISSTTOORRYY A ppiippee() function call appeared in Version 3 AT&T UNIX. Since Version 4 AT&T UNIX, it allocates two distinct file descriptors. The ppiippee22() function appeared in OpenBSD 5.7. NNAAMMEE ppiippee, ppiippee22 - create descriptor pair for interprocess communication SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ppiippee(_i_n_t _f_i_l_d_e_s_[_2_]); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ppiippee22(_i_n_t _f_i_l_d_e_s_[_2_], _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The ppiippee() function creates a _p_i_p_e, which is an object allowing unidirectional data flow, and allocates a pair of file descriptors. The first descriptor connects to the _r_e_a_d _e_n_d of the pipe, and the second connects to the _w_r_i_t_e _e_n_d, so that data written to _f_i_l_d_e_s_[_1_] appears on (i.e., can be read from) _f_i_l_d_e_s_[_0_]. This allows the output of one program to be sent to another program: the source's standard output is set up to be the write end of the pipe, and the sink's standard input is set up to be the read end of the pipe. The pipe itself persists until all its associated descriptors are closed. A pipe whose read or write end has been closed is considered _w_i_d_o_w_e_d. Writing on such a pipe causes the writing process to receive a SIGPIPE signal. Widowing a pipe is the only way to deliver end-of-file to a reader: after the reader consumes any buffered data, reading a widowed pipe returns a zero count. The ppiippee22() function is identical to ppiippee() except that the non-blocking I/O mode on both ends of the pipe is determined by the O_NONBLOCK flag in the _f_l_a_g_s argument and the close-on-exec flag on both the new file descriptors is determined by the O_CLOEXEC flag in the _f_l_a_g_s argument. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ppiippee() and ppiippee22() will succeed unless: [EMFILE] Too many descriptors are active. [ENFILE] The system file table is full. [EFAULT] The _f_i_l_d_e_s buffer is in an invalid area of the process's address space. In addition, ppiippee22() may return the following error: [EINVAL] _f_l_a_g_s is invalid. SSEEEE AALLSSOO sh(1), fork(2), read(2), socketpair(2), write(2) SSTTAANNDDAARRDDSS The ppiippee() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The ppiippee22() function is expected to conform to a future revision of that standard. As an extension, the pipe provided is actually capable of moving data bidirectionally. This is compatible with SVR4. However, this is non- POSIX behaviour which should not be relied on, for reasons of portability. HHIISSTTOORRYY A ppiippee() function call appeared in Version 3 AT&T UNIX. Since Version 4 AT&T UNIX, it allocates two distinct file descriptors. The ppiippee22() function appeared in OpenBSD 5.7. NNAAMMEE ppoollll, ppppoollll - synchronous I/O multiplexing SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ppoollll(_s_t_r_u_c_t _p_o_l_l_f_d _*_f_d_s, _n_f_d_s___t _n_f_d_s, _i_n_t _t_i_m_e_o_u_t); _i_n_t ppppoollll(_s_t_r_u_c_t _p_o_l_l_f_d _*_f_d_s, _n_f_d_s___t _n_f_d_s, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t, _c_o_n_s_t _s_i_g_s_e_t___t _*_m_a_s_k); DDEESSCCRRIIPPTTIIOONN ppoollll() provides a mechanism for multiplexing I/O across a set of file descriptors. It is similar in function to select(2). Unlike select(2), however, it is possible to only pass in data corresponding to the file descriptors for which events are wanted. This makes ppoollll() more efficient than select(2) in most cases. The arguments are as follows: _f_d_s Points to an array of _p_o_l_l_f_d structures, which are defined as: struct pollfd { int fd; short events; short revents; }; The _f_d member is an open file descriptor. If _f_d is -1, the _p_o_l_l_f_d structure is considered unused, and _r_e_v_e_n_t_s will be cleared. The _e_v_e_n_t_s and _r_e_v_e_n_t_s members are bitmasks of conditions to monitor and conditions found, respectively. _n_f_d_s An unsigned integer specifying the number of _p_o_l_l_f_d structures in the array. _t_i_m_e_o_u_t Maximum interval to wait for the poll to complete, in milliseconds. If this value is 0, ppoollll() will return immediately. If this value is INFTIM (-1), ppoollll() will block indefinitely until a condition is found. The calling process sets the _e_v_e_n_t_s bitmask and ppoollll() sets the _r_e_v_e_n_t_s bitmask. Each call to ppoollll() resets the _r_e_v_e_n_t_s bitmask for accuracy. The condition flags in the bitmasks are defined as: POLLIN Data other than high-priority data may be read without blocking. POLLRDNORM Normal data may be read without blocking. POLLRDBAND Priority data may be read without blocking. POLLNORM Same as POLLRDNORM. This flag is provided for source code compatibility with older programs and should not be used in new code. POLLPRI High-priority data may be read without blocking. POLLOUT Normal data may be written without blocking. POLLWRNORM Same as POLLOUT. POLLWRBAND Priority data may be written. POLLERR An error has occurred on the device or socket. This flag is only valid in the _r_e_v_e_n_t_s bitmask; it is ignored in the _e_v_e_n_t_s member. POLLHUP The device or socket has been disconnected. This event and POLLOUT are mutually-exclusive; a descriptor can never be writable if a hangup has occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually- exclusive. This flag is only valid in the _r_e_v_e_n_t_s bitmask; it is ignored in the _e_v_e_n_t_s member. POLLNVAL The corresponding file descriptor is invalid. This flag is only valid in the _r_e_v_e_n_t_s bitmask; it is ignored in the _e_v_e_n_t_s member. The significance and semantics of normal, priority, and high-priority data are device-specific. In addition to I/O multiplexing, ppoollll() can be used to generate simple timeouts. This functionality may be achieved by passing a null pointer for _f_d_s. The ppppoollll() function is similar to ppoollll() except that it specifies the timeout using a timespec structure, and a null pointer is used to specify an indefinite timeout instead of INFTIM. Also, if _m_a_s_k is a non-null pointer, ppppoollll() atomically sets the calling thread's signal mask to the signal set pointed to by _m_a_s_k for the duration of the function call. In this case, the original signal mask will be restored before ppppoollll() returns. RREETTUURRNN VVAALLUUEESS Upon error, ppoollll() and ppppoollll() return -1 and set the global variable _e_r_r_n_o to indicate the error. If the timeout interval was reached before any events occurred, they return 0. Otherwise, they return the number of _p_o_l_l_f_d structures for which _r_e_v_e_n_t_s is non-zero. IIDDIIOOMMSS Care must be taken when converting code from select(2) to ppoollll() as they have slightly different semantics. The first semantic difference is that, unlike select(2), ppoollll() has a way of indicating that one or more file descriptors is invalid by setting a flag in the _r_e_v_e_n_t_s field of corresponding entry of _f_d_s, whereas select(2) returns an error (-1) if any of the descriptors with bits set in the _f_d___s_e_t are invalid. The second difference is that on EOF there is no guarantee that POLLIN will be set in _r_e_v_e_n_t_s, the caller must also check for POLLHUP. This differs from select(2) where EOF is considered as a read event. Consider the following usage of select(2) that implements a read from the standard input with a 60 second time out: struct timeval timeout; fd_set readfds; char buf[BUFSIZ]; int nready; timeout.tv_sec = 60; timeout.tv_usec = 0; FD_ZERO(&readfds); FD_SET(STDIN_FILENO); nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); if (nready == -1) err(1, "select"); if (nready == 0) errx(1, "time out"); if (FD_ISSET(STDIN_FILENO, &readfds)) { if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) err(1, "read"); } This can be converted to ppoollll() as follows: struct pollfd pdf[1]; char buf[BUFSIZ]; int nready; pfd[0].fd = STDIN_FILENO; pfd[0].events = POLLIN; nready = poll(pfd, 1, 60 * 1000); if (nready == -1) err(1, "poll"); if (nready == 0) errx(1, "time out"); if ((pfd[0].revents & (POLLERR|POLLNVAL))) errx(1, "bad fd %d", pfd[0].fd); if ((pfd[0].revents & (POLLIN|POLLHUP))) if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) err(1, "read"); } EERRRROORRSS ppoollll() and ppppoollll() will fail if: [EFAULT] _f_d_s points outside the process's allocated address space. [EINTR] A signal was caught before any polled events occurred and before the timeout elapsed. [EINVAL] _n_f_d_s was greater than the number of available file descriptors. [EINVAL] The timeout passed was invalid. SSEEEE AALLSSOO clock_gettime(2), getrlimit(2), read(2), select(2), write(2) SSTTAANNDDAARRDDSS The ppoollll() function is compliant with the IEEE Std 1003.1-2008 (``POSIX.1'') specification. The ppppoollll() function is a Linux extension. HHIISSTTOORRYY A ppoollll() system call appeared in AT&T System V Release 3 UNIX. The ppppoollll() function appeared in OpenBSD 5.4. BBUUGGSS The POLLWRBAND flag is accepted but ignored by the kernel. Because OpenBSD does not implement STREAMS, there is no distinction between some of the fields in the _e_v_e_n_t_s and _r_e_v_e_n_t_s bitmasks. As a result, the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent. Internally to the kernel, ppoollll() and ppppoollll() work poorly if multiple processes wait on the same file descriptor. NNAAMMEE mmaaddvviissee, ppoossiixx__mmaaddvviissee - give advice about use of memory SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t mmaaddvviissee(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _b_e_h_a_v); _i_n_t ppoossiixx__mmaaddvviissee(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _b_e_h_a_v); DDEESSCCRRIIPPTTIIOONN The mmaaddvviissee() system call allows a process that has knowledge of its memory behavior to describe it to the system. The ppoossiixx__mmaaddvviissee() interface has the same effect, but returns the error value instead of only setting _e_r_r_n_o. The possible behaviors are: MADV_NORMAL No further special treatment needed. MADV_RANDOM Expect random page access patterns. MADV_SEQUENTIAL Expect sequential page references. MADV_WILLNEED The pages will be referenced soon. MADV_DONTNEED The pages will not be referenced soon. MADV_SPACEAVAIL Ensure that resources are reserved. MADV_FREE The pages don't contain any useful data and can be recycled. Portable programs that call the ppoossiixx__mmaaddvviissee() interface should use the aliases POSIX_MADV_NORMAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, POSIX_MADV_WILLNEED, and POSIX_MADV_DONTNEED rather than the flags described above. RREETTUURRNN VVAALLUUEESS The mmaaddvviissee() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. If successful, the ppoossiixx__mmaaddvviissee() function will return zero. Otherwise an error number will be returned to indicate the error. SSEEEE AALLSSOO mincore(2), minherit(2), mprotect(2), msync(2), munmap(2) SSTTAANNDDAARRDDSS The ppoossiixx__mmaaddvviissee() system call conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The mmaaddvviissee() function first appeared in 4.4BSD. The ppoossiixx__mmaaddvviissee() function first appeared in OpenBSD 4.8. BBUUGGSS The MADV_WILLNEED behavior is ignored. The MADV_SPACEAVAIL behavior is not implemented and will always fail. NNAAMMEE ppoollll, ppppoollll - synchronous I/O multiplexing SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ppoollll(_s_t_r_u_c_t _p_o_l_l_f_d _*_f_d_s, _n_f_d_s___t _n_f_d_s, _i_n_t _t_i_m_e_o_u_t); _i_n_t ppppoollll(_s_t_r_u_c_t _p_o_l_l_f_d _*_f_d_s, _n_f_d_s___t _n_f_d_s, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t, _c_o_n_s_t _s_i_g_s_e_t___t _*_m_a_s_k); DDEESSCCRRIIPPTTIIOONN ppoollll() provides a mechanism for multiplexing I/O across a set of file descriptors. It is similar in function to select(2). Unlike select(2), however, it is possible to only pass in data corresponding to the file descriptors for which events are wanted. This makes ppoollll() more efficient than select(2) in most cases. The arguments are as follows: _f_d_s Points to an array of _p_o_l_l_f_d structures, which are defined as: struct pollfd { int fd; short events; short revents; }; The _f_d member is an open file descriptor. If _f_d is -1, the _p_o_l_l_f_d structure is considered unused, and _r_e_v_e_n_t_s will be cleared. The _e_v_e_n_t_s and _r_e_v_e_n_t_s members are bitmasks of conditions to monitor and conditions found, respectively. _n_f_d_s An unsigned integer specifying the number of _p_o_l_l_f_d structures in the array. _t_i_m_e_o_u_t Maximum interval to wait for the poll to complete, in milliseconds. If this value is 0, ppoollll() will return immediately. If this value is INFTIM (-1), ppoollll() will block indefinitely until a condition is found. The calling process sets the _e_v_e_n_t_s bitmask and ppoollll() sets the _r_e_v_e_n_t_s bitmask. Each call to ppoollll() resets the _r_e_v_e_n_t_s bitmask for accuracy. The condition flags in the bitmasks are defined as: POLLIN Data other than high-priority data may be read without blocking. POLLRDNORM Normal data may be read without blocking. POLLRDBAND Priority data may be read without blocking. POLLNORM Same as POLLRDNORM. This flag is provided for source code compatibility with older programs and should not be used in new code. POLLPRI High-priority data may be read without blocking. POLLOUT Normal data may be written without blocking. POLLWRNORM Same as POLLOUT. POLLWRBAND Priority data may be written. POLLERR An error has occurred on the device or socket. This flag is only valid in the _r_e_v_e_n_t_s bitmask; it is ignored in the _e_v_e_n_t_s member. POLLHUP The device or socket has been disconnected. This event and POLLOUT are mutually-exclusive; a descriptor can never be writable if a hangup has occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually- exclusive. This flag is only valid in the _r_e_v_e_n_t_s bitmask; it is ignored in the _e_v_e_n_t_s member. POLLNVAL The corresponding file descriptor is invalid. This flag is only valid in the _r_e_v_e_n_t_s bitmask; it is ignored in the _e_v_e_n_t_s member. The significance and semantics of normal, priority, and high-priority data are device-specific. In addition to I/O multiplexing, ppoollll() can be used to generate simple timeouts. This functionality may be achieved by passing a null pointer for _f_d_s. The ppppoollll() function is similar to ppoollll() except that it specifies the timeout using a timespec structure, and a null pointer is used to specify an indefinite timeout instead of INFTIM. Also, if _m_a_s_k is a non-null pointer, ppppoollll() atomically sets the calling thread's signal mask to the signal set pointed to by _m_a_s_k for the duration of the function call. In this case, the original signal mask will be restored before ppppoollll() returns. RREETTUURRNN VVAALLUUEESS Upon error, ppoollll() and ppppoollll() return -1 and set the global variable _e_r_r_n_o to indicate the error. If the timeout interval was reached before any events occurred, they return 0. Otherwise, they return the number of _p_o_l_l_f_d structures for which _r_e_v_e_n_t_s is non-zero. IIDDIIOOMMSS Care must be taken when converting code from select(2) to ppoollll() as they have slightly different semantics. The first semantic difference is that, unlike select(2), ppoollll() has a way of indicating that one or more file descriptors is invalid by setting a flag in the _r_e_v_e_n_t_s field of corresponding entry of _f_d_s, whereas select(2) returns an error (-1) if any of the descriptors with bits set in the _f_d___s_e_t are invalid. The second difference is that on EOF there is no guarantee that POLLIN will be set in _r_e_v_e_n_t_s, the caller must also check for POLLHUP. This differs from select(2) where EOF is considered as a read event. Consider the following usage of select(2) that implements a read from the standard input with a 60 second time out: struct timeval timeout; fd_set readfds; char buf[BUFSIZ]; int nready; timeout.tv_sec = 60; timeout.tv_usec = 0; FD_ZERO(&readfds); FD_SET(STDIN_FILENO); nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); if (nready == -1) err(1, "select"); if (nready == 0) errx(1, "time out"); if (FD_ISSET(STDIN_FILENO, &readfds)) { if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) err(1, "read"); } This can be converted to ppoollll() as follows: struct pollfd pdf[1]; char buf[BUFSIZ]; int nready; pfd[0].fd = STDIN_FILENO; pfd[0].events = POLLIN; nready = poll(pfd, 1, 60 * 1000); if (nready == -1) err(1, "poll"); if (nready == 0) errx(1, "time out"); if ((pfd[0].revents & (POLLERR|POLLNVAL))) errx(1, "bad fd %d", pfd[0].fd); if ((pfd[0].revents & (POLLIN|POLLHUP))) if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) err(1, "read"); } EERRRROORRSS ppoollll() and ppppoollll() will fail if: [EFAULT] _f_d_s points outside the process's allocated address space. [EINTR] A signal was caught before any polled events occurred and before the timeout elapsed. [EINVAL] _n_f_d_s was greater than the number of available file descriptors. [EINVAL] The timeout passed was invalid. SSEEEE AALLSSOO clock_gettime(2), getrlimit(2), read(2), select(2), write(2) SSTTAANNDDAARRDDSS The ppoollll() function is compliant with the IEEE Std 1003.1-2008 (``POSIX.1'') specification. The ppppoollll() function is a Linux extension. HHIISSTTOORRYY A ppoollll() system call appeared in AT&T System V Release 3 UNIX. The ppppoollll() function appeared in OpenBSD 5.4. BBUUGGSS The POLLWRBAND flag is accepted but ignored by the kernel. Because OpenBSD does not implement STREAMS, there is no distinction between some of the fields in the _e_v_e_n_t_s and _r_e_v_e_n_t_s bitmasks. As a result, the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent. Internally to the kernel, ppoollll() and ppppoollll() work poorly if multiple processes wait on the same file descriptor. NNAAMMEE rreeaadd, rreeaaddvv, pprreeaadd, pprreeaaddvv - read input SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); _s_s_i_z_e___t pprreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s, _o_f_f___t _o_f_f_s_e_t); ##iinncclluuddee <> _s_s_i_z_e___t rreeaaddvv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t pprreeaaddvv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN rreeaadd() attempts to read _n_b_y_t_e_s of data from the object referenced by the descriptor _d into the buffer pointed to by _b_u_f. rreeaaddvv() performs the same action, but scatters the input data into the _i_o_v_c_n_t buffers specified by the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1]. pprreeaadd() and pprreeaaddvv() perform the same functions, but read from the specified position _o_f_f_s_e_t in the file without modifying the file pointer. For rreeaaddvv() and pprreeaaddvv(), the _i_o_v_e_c structure is defined as: struct iovec { void *iov_base; size_t iov_len; }; Each _i_o_v_e_c entry specifies the base address and length of an area in memory where data should be placed. rreeaaddvv() and pprreeaaddvv() will always fill an area completely before proceeding to the next. On objects capable of seeking, the rreeaadd() starts at a position given by the pointer associated with _d (see lseek(2)). Upon return from rreeaadd(), the pointer is incremented by the number of bytes actually read. Objects that are not capable of seeking always read from the current position. The value of the pointer associated with such an object is undefined. Upon successful completion, rreeaadd(), rreeaaddvv(), pprreeaadd(), and pprreeaaddvv() return the number of bytes actually read and placed in the buffer. The system guarantees to read the number of bytes requested if the descriptor references a normal file that has that many bytes left before the end-of- file, but in no other case. Note that rreeaaddvv() and pprreeaaddvv() will fail if the value of _i_o_v_c_n_t exceeds the constant IOV_MAX. RREETTUURRNN VVAALLUUEESS If successful, the number of bytes actually read is returned. Upon reading end-of-file, zero is returned. Otherwise, a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS rreeaadd(), rreeaaddvv(), pprreeaadd(), and pprreeaaddvv() will succeed unless: [EBADF] _d is not a valid file or socket descriptor open for reading. [EFAULT] Part of _b_u_f points outside the process's allocated address space. [EIO] An I/O error occurred while reading from the file system. [EINTR] A read from a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data arrived. In addition, rreeaadd() and rreeaaddvv() may return the following errors: [EAGAIN] The file was marked for non-blocking I/O, and no data were ready to be read. [ENOTCONN] The file is a socket associated with a connection- oriented protocol and has not been connected. [EIO] The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned. rreeaadd() and pprreeaadd() may return the following error: [EINVAL] _n_b_y_t_e_s was larger than SSIZE_MAX. pprreeaadd() and pprreeaaddvv() may return the following errors: [EINVAL] _o_f_f_s_e_t was negative. [ESPIPE] _d is associated with a pipe, socket, FIFO, or tty. rreeaaddvv() and pprreeaaddvv() may return one of the following errors: [EINVAL] _i_o_v_c_n_t was less than or equal to 0, or greater than IOV_MAX. [EINVAL] The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed an _s_s_i_z_e___t. [EFAULT] Part of _i_o_v points outside the process's allocated address space. SSEEEE AALLSSOO dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), socketpair(2) SSTTAANNDDAARRDDSS The rreeaadd(), rreeaaddvv(), and pprreeaadd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A rreeaadd() system call first appeared in Version 1 AT&T UNIX; rreeaaddvv() in 4.1cBSD; pprreeaadd() in AT&T System V Release 4 UNIX; and pprreeaaddvv() in OpenBSD 2.7. CCAAVVEEAATTSS Error checks should explicitly test for -1. Code such as while ((nr = read(fd, buf, sizeof(buf))) > 0) is not maximally portable, as some platforms allow for _n_b_y_t_e_s to range between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an error-free rreeaadd() may appear as a negative number distinct from -1. Proper loops should use while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) NNAAMMEE rreeaadd, rreeaaddvv, pprreeaadd, pprreeaaddvv - read input SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); _s_s_i_z_e___t pprreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s, _o_f_f___t _o_f_f_s_e_t); ##iinncclluuddee <> _s_s_i_z_e___t rreeaaddvv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t pprreeaaddvv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN rreeaadd() attempts to read _n_b_y_t_e_s of data from the object referenced by the descriptor _d into the buffer pointed to by _b_u_f. rreeaaddvv() performs the same action, but scatters the input data into the _i_o_v_c_n_t buffers specified by the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1]. pprreeaadd() and pprreeaaddvv() perform the same functions, but read from the specified position _o_f_f_s_e_t in the file without modifying the file pointer. For rreeaaddvv() and pprreeaaddvv(), the _i_o_v_e_c structure is defined as: struct iovec { void *iov_base; size_t iov_len; }; Each _i_o_v_e_c entry specifies the base address and length of an area in memory where data should be placed. rreeaaddvv() and pprreeaaddvv() will always fill an area completely before proceeding to the next. On objects capable of seeking, the rreeaadd() starts at a position given by the pointer associated with _d (see lseek(2)). Upon return from rreeaadd(), the pointer is incremented by the number of bytes actually read. Objects that are not capable of seeking always read from the current position. The value of the pointer associated with such an object is undefined. Upon successful completion, rreeaadd(), rreeaaddvv(), pprreeaadd(), and pprreeaaddvv() return the number of bytes actually read and placed in the buffer. The system guarantees to read the number of bytes requested if the descriptor references a normal file that has that many bytes left before the end-of- file, but in no other case. Note that rreeaaddvv() and pprreeaaddvv() will fail if the value of _i_o_v_c_n_t exceeds the constant IOV_MAX. RREETTUURRNN VVAALLUUEESS If successful, the number of bytes actually read is returned. Upon reading end-of-file, zero is returned. Otherwise, a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS rreeaadd(), rreeaaddvv(), pprreeaadd(), and pprreeaaddvv() will succeed unless: [EBADF] _d is not a valid file or socket descriptor open for reading. [EFAULT] Part of _b_u_f points outside the process's allocated address space. [EIO] An I/O error occurred while reading from the file system. [EINTR] A read from a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data arrived. In addition, rreeaadd() and rreeaaddvv() may return the following errors: [EAGAIN] The file was marked for non-blocking I/O, and no data were ready to be read. [ENOTCONN] The file is a socket associated with a connection- oriented protocol and has not been connected. [EIO] The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned. rreeaadd() and pprreeaadd() may return the following error: [EINVAL] _n_b_y_t_e_s was larger than SSIZE_MAX. pprreeaadd() and pprreeaaddvv() may return the following errors: [EINVAL] _o_f_f_s_e_t was negative. [ESPIPE] _d is associated with a pipe, socket, FIFO, or tty. rreeaaddvv() and pprreeaaddvv() may return one of the following errors: [EINVAL] _i_o_v_c_n_t was less than or equal to 0, or greater than IOV_MAX. [EINVAL] The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed an _s_s_i_z_e___t. [EFAULT] Part of _i_o_v points outside the process's allocated address space. SSEEEE AALLSSOO dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), socketpair(2) SSTTAANNDDAARRDDSS The rreeaadd(), rreeaaddvv(), and pprreeaadd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A rreeaadd() system call first appeared in Version 1 AT&T UNIX; rreeaaddvv() in 4.1cBSD; pprreeaadd() in AT&T System V Release 4 UNIX; and pprreeaaddvv() in OpenBSD 2.7. CCAAVVEEAATTSS Error checks should explicitly test for -1. Code such as while ((nr = read(fd, buf, sizeof(buf))) > 0) is not maximally portable, as some platforms allow for _n_b_y_t_e_s to range between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an error-free rreeaadd() may appear as a negative number distinct from -1. Proper loops should use while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) NNAAMMEE pprrooffiill - control process profiling SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t pprrooffiill(_c_h_a_r _*_s_a_m_p_l_e_s, _s_i_z_e___t _s_i_z_e, _u___l_o_n_g _o_f_f_s_e_t, _u___i_n_t _s_c_a_l_e); DDEESSCCRRIIPPTTIIOONN The pprrooffiill() function enables or disables program counter profiling of the current process. If profiling is enabled, then at every clock tick, the kernel updates an appropriate count in the _s_a_m_p_l_e_s buffer. The buffer _s_a_m_p_l_e_s contains _s_i_z_e bytes and is divided into a series of 16-bit bins. Each bin counts the number of times the program counter was in a particular address range in the process when a clock tick occurred while profiling was enabled. For a given program counter address, the number of the corresponding bin is given by the relation: [(pc - offset) / 2] * scale / 65536 The _o_f_f_s_e_t parameter is the lowest address at which the kernel takes program counter samples. The _s_c_a_l_e parameter ranges from 1 to 65536 and can be used to change the span of the bins. A scale of 65536 maps each bin to 2 bytes of address range; a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on. Intermediate values provide approximate intermediate ranges. A _s_c_a_l_e value of 0 disables profiling. RREETTUURRNN VVAALLUUEESS If the _s_c_a_l_e value is nonzero and the buffer _s_a_m_p_l_e_s contains an illegal address, pprrooffiill() returns -1, profiling is terminated, and _e_r_r_n_o is set appropriately. Otherwise, pprrooffiill() returns 0. FFIILLEESS _/_u_s_r_/_l_i_b_/_g_c_r_t_0_._o profiling C run-time startup file _g_m_o_n_._o_u_t conventional name for profiling output file EERRRROORRSS The following error may be reported: [EFAULT] The buffer _s_a_m_p_l_e_s contains an invalid address. SSEEEE AALLSSOO gprof(1) BBUUGGSS This routine should be named pprrooffiillee(). The _s_a_m_p_l_e_s argument should really be a vector of type _u_n_s_i_g_n_e_d _s_h_o_r_t. The format of the gmon.out file is undocumented. NNAAMMEE sseelleecctt, ppsseelleecctt - synchronous I/O multiplexing SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseelleecctt(_i_n_t _n_f_d_s, _f_d___s_e_t _*_r_e_a_d_f_d_s, _f_d___s_e_t _*_w_r_i_t_e_f_d_s, _f_d___s_e_t _*_e_x_c_e_p_t_f_d_s, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_o_u_t); _i_n_t ppsseelleecctt(_i_n_t _n_f_d_s, _f_d___s_e_t _*_r_e_a_d_f_d_s, _f_d___s_e_t _*_w_r_i_t_e_f_d_s, _f_d___s_e_t _*_e_x_c_e_p_t_f_d_s, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t, _c_o_n_s_t _s_i_g_s_e_t___t _*_m_a_s_k); FFDD__SSEETT(_f_d, _&_f_d_s_e_t); FFDD__CCLLRR(_f_d, _&_f_d_s_e_t); FFDD__IISSSSEETT(_f_d, _&_f_d_s_e_t); FFDD__ZZEERROO(_&_f_d_s_e_t); DDEESSCCRRIIPPTTIIOONN sseelleecctt() examines the I/O descriptor sets whose addresses are passed in _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and _e_x_c_e_p_t_f_d_s to see if some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. The first _n_f_d_s descriptors are checked in each set; i.e., the descriptors from 0 through _n_f_d_s-1 in the descriptor sets are examined. On return, sseelleecctt() replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. sseelleecctt() returns the total number of ready descriptors in all the sets. The descriptor sets are stored as bit fields in arrays of integers. The following macros are provided for manipulating such descriptor sets: FFDD__ZZEERROO(_&_f_d_s_e_t) initializes a descriptor set _f_d_s_e_t to the null set. FFDD__SSEETT(_f_d, _&_f_d_s_e_t) includes a particular descriptor _f_d in _f_d_s_e_t. FFDD__CCLLRR(_f_d, _&_f_d_s_e_t) removes _f_d from _f_d_s_e_t. FFDD__IISSSSEETT(_f_d, _&_f_d_s_e_t) is non- zero if _f_d is a member of _f_d_s_e_t, zero otherwise. The behavior of these macros is undefined if a descriptor value is less than zero or greater than or equal to FD_SETSIZE, which is normally at least equal to the maximum number of descriptors supported by the system. If _t_i_m_e_o_u_t is a non-null pointer, it specifies a maximum interval to wait for the selection to complete. If _t_i_m_e_o_u_t is a null pointer, the select blocks indefinitely. To effect a poll, the _t_i_m_e_o_u_t argument should be non-null, pointing to a zero-valued timeval structure. _t_i_m_e_o_u_t is not changed by sseelleecctt(), and may be reused on subsequent calls; however, it is good style to re-initialize it before each invocation of sseelleecctt(). Any of _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and _e_x_c_e_p_t_f_d_s may be given as null pointers if no descriptors are of interest. The ppsseelleecctt() function is similar to sseelleecctt() except that it specifies the timeout using a timespec structure. Also, if _m_a_s_k is a non-null pointer, ppsseelleecctt() atomically sets the calling thread's signal mask to the signal set pointed to by _m_a_s_k for the duration of the function call. In this case, the original signal mask will be restored before ppsseelleecctt() returns. RREETTUURRNN VVAALLUUEESS If successful, sseelleecctt() and ppsseelleecctt() return the number of ready descriptors that are contained in the descriptor sets. If a descriptor is included in multiple descriptor sets, each inclusion is counted separately. If the time limit expires before any descriptors become ready, they return 0. Otherwise, if sseelleecctt() or ppsseelleecctt() return with an error, including one due to an interrupted call, they return -1, and the descriptor sets will be unmodified. EERRRROORRSS An error return from sseelleecctt() or ppsseelleecctt() indicates: [EFAULT] One or more of _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, or _e_x_c_e_p_t_f_d_s points outside the process's allocated address space. [EBADF] One of the descriptor sets specified an invalid descriptor. [EINTR] A signal was delivered before the time limit expired and before any of the selected descriptors became ready. [EINVAL] The specified time limit is invalid. One of its components is negative or too large. SSEEEE AALLSSOO accept(2), clock_gettime(2), connect(2), gettimeofday(2), poll(2), read(2), recv(2), send(2), write(2), getdtablesize(3) HHIISSTTOORRYY The sseelleecctt() system call first appeared in 4.1cBSD. The ppsseelleecctt() system call has been available since OpenBSD 5.4. BBUUGGSS Although the provision of getdtablesize(3) was intended to allow user programs to be written independent of the kernel limit on the number of open files, the dimension of a sufficiently large bit field for select remains a problem. The default bit size of _f_d___s_e_t is based on the symbol FD_SETSIZE (currently 1024), but that is somewhat smaller than the current kernel limit to the number of open files. However, in order to accommodate programs which might potentially use a larger number of open files with select, it is possible to increase this size within a program by providing a larger definition of FD_SETSIZE before the inclusion of any headers. The kernel will cope, and the userland libraries provided with the system are also ready for large numbers of file descriptors. Alternatively, to be really safe, it is possible to allocate _f_d___s_e_t bit- arrays dynamically. The idea is to permit a program to work properly even if it is execve(2)'d with 4000 file descriptors pre-allocated. The following illustrates the technique which is used by userland libraries: fd_set *fdsr; int max = fd; fdsr = calloc(howmany(max+1, NFDBITS), sizeof(fd_mask)); if (fdsr == NULL) { ... return (-1); } FD_SET(fd, fdsr); n = select(max+1, fdsr, NULL, NULL, &tv); ... free(fdsr); Alternatively, it is possible to use the poll(2) interface. poll(2) is more efficient when the size of sseelleecctt()'s _f_d___s_e_t bit-arrays are very large, and for fixed numbers of file descriptors one need not size and dynamically allocate a memory object. sseelleecctt() should probably have been designed to return the time remaining from the original timeout, if any, by modifying the time value in place. Even though some systems stupidly act in this different way, it is unlikely this semantic will ever be commonly implemented, as the change causes massive source code compatibility problems. Furthermore, recent new standards have dictated the current behaviour. In general, due to the existence of those brain-damaged non-conforming systems, it is unwise to assume that the timeout value will be unmodified by the sseelleecctt() call, and the caller should reinitialize it on each invocation. Calculating the delta is easily done by calling gettimeofday(2) before and after the call to sseelleecctt(), and using ttiimmeerrssuubb() (as described in getitimer(2)). Internally to the kernel, sseelleecctt() and ppsseelleecctt() work poorly if multiple processes wait on the same file descriptor. Given that, it is rather surprising to see that many daemons are written that way. NNAAMMEE ppttrraaccee - process tracing and debugging SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ppttrraaccee(_i_n_t _r_e_q_u_e_s_t, _p_i_d___t _p_i_d, _c_a_d_d_r___t _a_d_d_r, _i_n_t _d_a_t_a); DDEESSCCRRIIPPTTIIOONN ppttrraaccee() provides tracing and debugging facilities. It allows one process (the _t_r_a_c_i_n_g process) to control another (the _t_r_a_c_e_d process). Most of the time, the traced process runs normally, but when it receives a signal (see sigaction(2)), it stops. The tracing process is expected to notice this via wait(2) or the delivery of a SIGCHLD signal, examine the state of the stopped process, and cause it to terminate or continue as appropriate. ppttrraaccee() is the mechanism by which all this happens. ppttrraaccee() is only available on kernels compiled with the PPTTRRAACCEE option. The _r_e_q_u_e_s_t argument specifies what operation is being performed; the meaning of the rest of the arguments depends on the operation, but except for one special case noted below, all ppttrraaccee() calls are made by the tracing process, and the _p_i_d argument specifies the process ID of the traced process. _r_e_q_u_e_s_t can be: PT_TRACE_ME This request is the only one used by the traced process; it declares that the process expects to be traced by its parent. All the other arguments are ignored. (If the parent process does not expect to trace the child, it will probably be rather confused by the results; once the traced process stops, it cannot be made to continue except via ppttrraaccee().) When a process has used this request and calls execve(2) or any of the routines built on it (such as execv(3)), it will stop before executing the first instruction of the new image. Also, any setuid or setgid bits on the executable being executed will be ignored. PT_READ_I, PT_READ_D These requests read a single int of data from the traced process' address space. Traditionally, ppttrraaccee() has allowed for machines with distinct address spaces for instruction and data, which is why there are two requests: conceptually, PT_READ_I reads from the instruction space and PT_READ_D reads from the data space. In the current OpenBSD implementation, these two requests are completely identical. The _a_d_d_r argument specifies the address (in the traced process' virtual address space) at which the read is to be done. This address does not have to meet any alignment constraints. The value read is returned as the return value from ppttrraaccee(). PT_WRITE_I, PT_WRITE_D These requests parallel PT_READ_I and PT_READ_D, except that they write rather than read. The _d_a_t_a argument supplies the value to be written. PT_CONTINUE The traced process continues execution. _a_d_d_r is an address specifying the place where execution is to be resumed (a new value for the program counter), or (caddr_t)1 to indicate that execution is to pick up where it left off. _d_a_t_a provides a signal number to be delivered to the traced process as it resumes execution, or 0 if no signal is to be sent. PT_KILL The traced process terminates, as if PT_CONTINUE had been used with SIGKILL given as the signal to be delivered. PT_ATTACH This request allows a process to gain control of an otherwise unrelated process and begin tracing it. It does not need any cooperation from the to-be-traced process. In this case, _p_i_d specifies the process ID of the to-be-traced process, and the other two arguments are ignored. This request requires that the target process must have the same real UID as the tracing process, and that it must not be executing a set-user-ID or set-group-ID executable. Additionally, if the kern.global_ptrace sysctl is 0, then the target process must be a descendent of the tracing process. (If the tracing process is running as root, these restrictions do not apply.) The tracing process will see the newly traced process stop and may then control it as if it had been traced all along. PT_DETACH This request is like PT_CONTINUE, except that it does not allow specifying an alternate place to continue execution, and after it succeeds, the traced process is no longer traced and continues execution normally. PT_IO This request is a more general interface that can be used instead of PT_READ_D, PT_WRITE_D, PT_READ_I and PT_WRITE_I. The I/O request is encoded in a ``struct ptrace_io_desc'' defined as: struct ptrace_io_desc { int piod_op; void *piod_offs; void *piod_addr; size_t piod_len; }; Where _p_i_o_d___o_f_f_s is the offset within the traced process where the I/O operation should be made, _p_i_o_d___a_d_d_r is the buffer in the parent and _p_i_o_d___l_e_n is the length of the I/O request. The _p_i_o_d___o_p member specifies what operation needs to be done. Possible values are: PIOD_READ_D PIOD_WRITE_D PIOD_READ_I PIOD_WRITE_I PIOD_READ_AUXV See also the description of PT_READ_I for the difference between D and I spaces. The PIOD_READ_AUXV operation can be used to read from the ELF auxiliary vector. A pointer to the descriptor is passed in _a_d_d_r. On return the _p_i_o_d___l_e_n field in the descriptor will be updated with the actual number of bytes transferred. If the requested I/O couldn't be successfully performed ppttrraaccee() will return -1 and set _e_r_r_n_o. PT_SET_EVENT_MASK This request can be used to specify which events in the traced process should be reported to the tracing process. These events are specified in a ``struct ptrace_event'' defined as: typedef struct ptrace_event { int pe_set_event; } ptrace_event_t; Where _p_e___s_e_t___e_v_e_n_t is the set of events to be reported. This set is formed by OR'ing together the following values: PTRACE_FORK Report fork(2). A pointer to this structure is passed in _a_d_d_r. The _d_a_t_a argument should be set to sizeof(struct ptrace_event). PT_GET_EVENT_MASK This request can be used to determine which events in the traced process will be reported. The information is read into the ``struct ptrace_event'' pointed to by _a_d_d_r. The _d_a_t_a argument should be set to sizeof(struct ptrace_event). PT_GET_PROCESS_STATE This request reads the state information associated with the event that stopped the traced process. The information is reported in a ``struct ptrace_state'' defined as: typedef struct ptrace_state { int pe_report_event; pid_t pe_other_pid; } ptrace_state_t; Where _p_e___r_e_p_o_r_t___e_v_e_n_t is the event being reported. If the event being reported is PTRACE_FORK, _p_e___o_t_h_e_r___p_i_d will be set to the process ID of the other end of the fork. A pointer to this structure is passed in _a_d_d_r. The _d_a_t_a argument should be set to sizeof(struct ptrace_state). Additionally, machine-specific requests can exist. Depending on the architecture, the following requests may be available under OpenBSD: PT_GETREGS (all platforms) This request reads the traced process' machine registers into the ``struct reg'' (defined in <_m_a_c_h_i_n_e_/_r_e_g_._h>) pointed to by _a_d_d_r. PT_SETREGS (all platforms) This request is the converse of PT_GETREGS; it loads the traced process' machine registers from the ``struct reg'' (defined in <_m_a_c_h_i_n_e_/_r_e_g_._h>) pointed to by _a_d_d_r. PT_STEP (not available on sparc and sparc64) The traced process continues execution, as in request PT_CONTINUE; however, execution stops as soon as possible after execution of at least one instruction (single-step). PT_GETFPREGS (not available on aviion, luna88k, sgi and vax) This request reads the traced process' floating-point registers into the ``struct fpreg'' (defined in <_m_a_c_h_i_n_e_/_r_e_g_._h>) pointed to by _a_d_d_r. PT_SETFPREGS (not available on aviion, luna88k, sgi and vax) This request is the converse of PT_GETFPREGS; it loads the traced process' floating-point registers from the ``struct fpreg'' (defined in <_m_a_c_h_i_n_e_/_r_e_g_._h>) pointed to by _a_d_d_r. PT_GETXMMREGS (i386 only) This request reads the traced process' XMM registers into the ``struct xmmregs'' (defined in <_m_a_c_h_i_n_e_/_r_e_g_._h>) pointed to by _a_d_d_r. PT_SETXMMREGS (i386 only) This request is the converse of PT_GETXMMREGS; it loads the traced process' XMM registers from the ``struct xmmregs'' (defined in <_m_a_c_h_i_n_e_/_r_e_g_._h>) pointed to by _a_d_d_r. PT_WCOOKIE (sparc and sparc64 only) This request reads the traced process' `window cookie' into the int pointed to by _a_d_d_r. The window cookie needs to be `XOR'ed' to stack-saved program counters. EERRRROORRSS Some requests can cause ppttrraaccee() to return -1 as a non-error value; to disambiguate, _e_r_r_n_o is set to zero and this should be checked. The possible errors are: [ESRCH] No process having the specified process ID exists. [EINVAL] ++oo A process attempted to use PT_ATTACH on itself. ++oo The _r_e_q_u_e_s_t was not one of the legal requests. ++oo The signal number (in _d_a_t_a) to PT_CONTINUE was neither 0 nor a legal signal number. ++oo PT_GETREGS, PT_SETREGS, PT_GETFPREGS, or PT_SETFPREGS was attempted on a process with no valid register set. (This is normally true only of system processes.) [EBUSY] ++oo PT_ATTACH was attempted on a process that was already being traced. ++oo A request attempted to manipulate a process that was being traced by some process other than the one making the request. ++oo A request (other than PT_ATTACH) specified a process that wasn't stopped. [EPERM] ++oo A request (other than PT_ATTACH) attempted to manipulate a process that wasn't being traced at all. ++oo An attempt was made to use PT_ATTACH on a process in violation of the requirements listed under PT_ATTACH above. ++oo An attempt was made to use PT_ATTACH on a system process. HHIISSTTOORRYY The ppttrraaccee() system call first appeared in Version 6 AT&T UNIX. BBUUGGSS On several RISC architectures (such as aviion, luna88k, sparc and sparc64), the PC is set to the provided PC value for PT_CONTINUE and similar calls, and the remainder of the execution pipeline registers are set to the following instructions, even if the instruction at PC is a branch instruction. Using PT_GETREGS and PT_SETREGS to modify the PC, passing (caddr_t)1 to ppttrraaccee(), should be able to sidestep this. NNAAMMEE wwrriittee, wwrriitteevv, ppwwrriittee, ppwwrriitteevv - write output SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t wwrriittee(_i_n_t _d, _c_o_n_s_t _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); _s_s_i_z_e___t ppwwrriittee(_i_n_t _d, _c_o_n_s_t _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s, _o_f_f___t _o_f_f_s_e_t); ##iinncclluuddee <> _s_s_i_z_e___t wwrriitteevv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t ppwwrriitteevv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN wwrriittee() attempts to write _n_b_y_t_e_s of data to the object referenced by the descriptor _d from the buffer pointed to by _b_u_f. wwrriitteevv() performs the same action, but gathers the output data from the _i_o_v_c_n_t buffers specified by the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1]. ppwwrriittee() and ppwwrriitteevv() perform the same functions, but write to the specified position _o_f_f_s_e_t in the file without modifying the file pointer. For wwrriitteevv() and ppwwrriitteevv(), the _i_o_v_e_c structure is defined as: struct iovec { void *iov_base; size_t iov_len; }; Each _i_o_v_e_c entry specifies the base address and length of an area in memory from which data should be written. wwrriitteevv() and ppwwrriitteevv() will always write a complete area before proceeding to the next. On objects capable of seeking, the wwrriittee() starts at a position given by the pointer associated with _d (see lseek(2)). Upon return from wwrriittee(), the pointer is incremented by the number of bytes which were written. If a file was opened with the O_APPEND flag (see open(2)), calls to wwrriittee() or wwrriitteevv() will automatically set the pointer to the end of the file before writing. Objects that are not capable of seeking always write from the current position. The value of the pointer associated with such an object is undefined. If the real user is not the superuser, then wwrriittee() clears the set-user- ID bit on a file. This prevents penetration of system security by a user who ``captures'' a writable set-user-ID file owned by the superuser. If wwrriittee() succeeds it will update the st_ctime and st_mtime fields of the file's meta-data (see stat(2)). When using non-blocking I/O on objects such as sockets that are subject to flow control, wwrriittee() and wwrriitteevv() may write fewer bytes than requested; the return value must be noted, and the remainder of the operation should be retried when possible. Note that wwrriitteevv() and ppwwrriitteevv() will fail if the value of _i_o_v_c_n_t exceeds the constant IOV_MAX. RREETTUURRNN VVAALLUUEESS Upon successful completion the number of bytes which were written is returned. Otherwise, a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwrriittee(), ppwwrriittee(), wwrriitteevv(), and ppwwrriitteevv() will fail and the file pointer will remain unchanged if: [EBADF] _d is not a valid descriptor open for writing. [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. [ENOSPC] There is no free space remaining on the file system containing the file. [EDQUOT] The user's quota of disk blocks on the file system containing the file has been exhausted. [EINTR] A write to a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data could be written. [EIO] An I/O error occurred while reading from or writing to the file system. [EFAULT] Part of _b_u_f points outside the process's allocated address space. In addition, wwrriittee() and wwrriitteevv() may return the following errors: [EPIPE] An attempt is made to write to a pipe that is not open for reading by any process. [EPIPE] An attempt is made to write to a socket of type SOCK_STREAM that is not connected to a peer socket. [EAGAIN] The file was marked for non-blocking I/O, and no data could be written immediately. [ENETDOWN] The destination address specified a network that is down. [EDESTADDRREQ] The destination is no longer available when writing to a UNIX-domain datagram socket on which connect(2) had been used to set a destination address. [EIO] The process is a member of a background process attempting to write to its controlling terminal, TOSTOP is set on the terminal, the process isn't ignoring the SIGTTOUT signal and the thread isn't blocking the SIGTTOUT signal, and either the process was created with vfork(2) and hasn't successfully executed one of the exec functions or the process group is orphaned. wwrriittee() and ppwwrriittee() may return the following error: [EINVAL] _n_b_y_t_e_s was larger than SSIZE_MAX. ppwwrriittee() and ppwwrriitteevv() may return the following error: [EINVAL] _o_f_f_s_e_t was negative. [ESPIPE] _d is associated with a pipe, socket, FIFO, or tty. wwrriitteevv() and ppwwrriitteevv() may return one of the following errors: [EINVAL] _i_o_v_c_n_t was less than or equal to 0, or greater than IOV_MAX. [EINVAL] The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed an _s_s_i_z_e___t. [EFAULT] Part of _i_o_v points outside the process's allocated address space. [ENOBUFS] The system lacked sufficient buffer space or a queue was full. SSEEEE AALLSSOO fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) SSTTAANNDDAARRDDSS The wwrriittee(), wwrriitteevv(), and ppwwrriittee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ppwwrriitteevv() function call appeared in OpenBSD 2.7. The ppwwrriittee() function call appeared in AT&T System V Release 4 UNIX. The wwrriitteevv() function call appeared in 4.2BSD. The wwrriittee() function call appeared in Version 2 AT&T UNIX. CCAAVVEEAATTSS Error checks should explicitly test for -1. Code such as while ((nr = write(fd, buf, sizeof(buf))) > 0) is not maximally portable, as some platforms allow for _n_b_y_t_e_s to range between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an error-free wwrriittee() may appear as a negative number distinct from -1. Proper loops should use while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) NNAAMMEE wwrriittee, wwrriitteevv, ppwwrriittee, ppwwrriitteevv - write output SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t wwrriittee(_i_n_t _d, _c_o_n_s_t _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); _s_s_i_z_e___t ppwwrriittee(_i_n_t _d, _c_o_n_s_t _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s, _o_f_f___t _o_f_f_s_e_t); ##iinncclluuddee <> _s_s_i_z_e___t wwrriitteevv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t ppwwrriitteevv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN wwrriittee() attempts to write _n_b_y_t_e_s of data to the object referenced by the descriptor _d from the buffer pointed to by _b_u_f. wwrriitteevv() performs the same action, but gathers the output data from the _i_o_v_c_n_t buffers specified by the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1]. ppwwrriittee() and ppwwrriitteevv() perform the same functions, but write to the specified position _o_f_f_s_e_t in the file without modifying the file pointer. For wwrriitteevv() and ppwwrriitteevv(), the _i_o_v_e_c structure is defined as: struct iovec { void *iov_base; size_t iov_len; }; Each _i_o_v_e_c entry specifies the base address and length of an area in memory from which data should be written. wwrriitteevv() and ppwwrriitteevv() will always write a complete area before proceeding to the next. On objects capable of seeking, the wwrriittee() starts at a position given by the pointer associated with _d (see lseek(2)). Upon return from wwrriittee(), the pointer is incremented by the number of bytes which were written. If a file was opened with the O_APPEND flag (see open(2)), calls to wwrriittee() or wwrriitteevv() will automatically set the pointer to the end of the file before writing. Objects that are not capable of seeking always write from the current position. The value of the pointer associated with such an object is undefined. If the real user is not the superuser, then wwrriittee() clears the set-user- ID bit on a file. This prevents penetration of system security by a user who ``captures'' a writable set-user-ID file owned by the superuser. If wwrriittee() succeeds it will update the st_ctime and st_mtime fields of the file's meta-data (see stat(2)). When using non-blocking I/O on objects such as sockets that are subject to flow control, wwrriittee() and wwrriitteevv() may write fewer bytes than requested; the return value must be noted, and the remainder of the operation should be retried when possible. Note that wwrriitteevv() and ppwwrriitteevv() will fail if the value of _i_o_v_c_n_t exceeds the constant IOV_MAX. RREETTUURRNN VVAALLUUEESS Upon successful completion the number of bytes which were written is returned. Otherwise, a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwrriittee(), ppwwrriittee(), wwrriitteevv(), and ppwwrriitteevv() will fail and the file pointer will remain unchanged if: [EBADF] _d is not a valid descriptor open for writing. [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. [ENOSPC] There is no free space remaining on the file system containing the file. [EDQUOT] The user's quota of disk blocks on the file system containing the file has been exhausted. [EINTR] A write to a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data could be written. [EIO] An I/O error occurred while reading from or writing to the file system. [EFAULT] Part of _b_u_f points outside the process's allocated address space. In addition, wwrriittee() and wwrriitteevv() may return the following errors: [EPIPE] An attempt is made to write to a pipe that is not open for reading by any process. [EPIPE] An attempt is made to write to a socket of type SOCK_STREAM that is not connected to a peer socket. [EAGAIN] The file was marked for non-blocking I/O, and no data could be written immediately. [ENETDOWN] The destination address specified a network that is down. [EDESTADDRREQ] The destination is no longer available when writing to a UNIX-domain datagram socket on which connect(2) had been used to set a destination address. [EIO] The process is a member of a background process attempting to write to its controlling terminal, TOSTOP is set on the terminal, the process isn't ignoring the SIGTTOUT signal and the thread isn't blocking the SIGTTOUT signal, and either the process was created with vfork(2) and hasn't successfully executed one of the exec functions or the process group is orphaned. wwrriittee() and ppwwrriittee() may return the following error: [EINVAL] _n_b_y_t_e_s was larger than SSIZE_MAX. ppwwrriittee() and ppwwrriitteevv() may return the following error: [EINVAL] _o_f_f_s_e_t was negative. [ESPIPE] _d is associated with a pipe, socket, FIFO, or tty. wwrriitteevv() and ppwwrriitteevv() may return one of the following errors: [EINVAL] _i_o_v_c_n_t was less than or equal to 0, or greater than IOV_MAX. [EINVAL] The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed an _s_s_i_z_e___t. [EFAULT] Part of _i_o_v points outside the process's allocated address space. [ENOBUFS] The system lacked sufficient buffer space or a queue was full. SSEEEE AALLSSOO fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) SSTTAANNDDAARRDDSS The wwrriittee(), wwrriitteevv(), and ppwwrriittee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ppwwrriitteevv() function call appeared in OpenBSD 2.7. The ppwwrriittee() function call appeared in AT&T System V Release 4 UNIX. The wwrriitteevv() function call appeared in 4.2BSD. The wwrriittee() function call appeared in Version 2 AT&T UNIX. CCAAVVEEAATTSS Error checks should explicitly test for -1. Code such as while ((nr = write(fd, buf, sizeof(buf))) > 0) is not maximally portable, as some platforms allow for _n_b_y_t_e_s to range between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an error-free wwrriittee() may appear as a negative number distinct from -1. Proper loops should use while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) NNAAMMEE qquuoottaaccttll - manipulate filesystem quotas SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t qquuoottaaccttll(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _c_m_d, _i_n_t _i_d, _c_h_a_r _*_a_d_d_r); DDEESSCCRRIIPPTTIIOONN The qquuoottaaccttll() call enables, disables and manipulates filesystem quotas. A quota control command given by _c_m_d operates on the given filename _p_a_t_h for the given user _i_d. The address of an optional command specific data structure, _a_d_d_r, may be given; its interpretation is discussed below with each command. Currently quotas are supported only for the ``ffs'' filesystem. For ``ffs'', a command is composed of a primary command (see below) and a command type used to interpret the _i_d. Types are supported for interpretation of user identifiers and group identifiers. The ``ffs'' specific commands are: Q_QUOTAON Enable disk quotas for the filesystem specified by _p_a_t_h. The command type specifies the type of the quotas being enabled. The _a_d_d_r argument specifies a file from which to take the quotas. The quota file must exist; it is normally created with the quotacheck(8) program. The _i_d argument is unused. Only the superuser may turn quotas on. Q_QUOTAOFF Disable disk quotas for the filesystem specified by _p_a_t_h. The command type specifies the type of the quotas being disabled. The _a_d_d_r and _i_d arguments are unused. Only the superuser may turn quotas off. Q_GETQUOTA Get disk quota limits and current usage for the user or group (as determined by the command type) with identifier _i_d. _a_d_d_r is a pointer to a struct dqblk structure. Q_SETQUOTA Set disk quota limits for the user or group (as determined by the command type) with identifier _i_d. _a_d_d_r is a pointer to a struct dqblk structure. The usage fields of struct dqblk structure are ignored. This call is restricted to the superuser. Q_SETUSE Set disk usage limits for the user or group (as determined by the command type) with identifier _i_d. _a_d_d_r is a pointer to a struct dqblk structure. Only the usage fields are used. This call is restricted to the superuser. Q_SYNC Update the on-disk copy of quota usages. The command type specifies which type of quotas are to be updated. The _i_d and _a_d_d_r parameters are ignored. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS A qquuoottaaccttll() call will fail if: [EOPNOTSUPP] The kernel has not been compiled with the QUOTA option. [EUSERS] The quota table cannot be expanded. [EINVAL] _c_m_d or the command type is invalid. [EACCES] In Q_QUOTAON, the quota file is not a plain file. [EACCES] Search permission is denied for a component of a path prefix. [ENOTDIR] A component of a path prefix was not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A filename does not exist. [ELOOP] Too many symbolic links were encountered in translating a pathname. [EROFS] In Q_QUOTAON, the quota file resides on a read-only filesystem. [EIO] An I/O error occurred while reading from or writing to a file containing quotas. [EFAULT] An invalid _a_d_d_r was supplied; the associated structure could not be copied in or out of the kernel. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EPERM] The call was privileged and the caller was not the superuser. SSEEEE AALLSSOO quota(1), fstab(5), edquota(8), quotacheck(8), quotaon(8), repquota(8) HHIISSTTOORRYY The qquuoottaaccttll() function call appeared in 4.3BSD-Reno. BBUUGGSS There should be some way to integrate this call with the resource limit interface provided by setrlimit(2) and getrlimit(2). NNAAMMEE rreeaadd, rreeaaddvv, pprreeaadd, pprreeaaddvv - read input SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); _s_s_i_z_e___t pprreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s, _o_f_f___t _o_f_f_s_e_t); ##iinncclluuddee <> _s_s_i_z_e___t rreeaaddvv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t pprreeaaddvv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN rreeaadd() attempts to read _n_b_y_t_e_s of data from the object referenced by the descriptor _d into the buffer pointed to by _b_u_f. rreeaaddvv() performs the same action, but scatters the input data into the _i_o_v_c_n_t buffers specified by the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1]. pprreeaadd() and pprreeaaddvv() perform the same functions, but read from the specified position _o_f_f_s_e_t in the file without modifying the file pointer. For rreeaaddvv() and pprreeaaddvv(), the _i_o_v_e_c structure is defined as: struct iovec { void *iov_base; size_t iov_len; }; Each _i_o_v_e_c entry specifies the base address and length of an area in memory where data should be placed. rreeaaddvv() and pprreeaaddvv() will always fill an area completely before proceeding to the next. On objects capable of seeking, the rreeaadd() starts at a position given by the pointer associated with _d (see lseek(2)). Upon return from rreeaadd(), the pointer is incremented by the number of bytes actually read. Objects that are not capable of seeking always read from the current position. The value of the pointer associated with such an object is undefined. Upon successful completion, rreeaadd(), rreeaaddvv(), pprreeaadd(), and pprreeaaddvv() return the number of bytes actually read and placed in the buffer. The system guarantees to read the number of bytes requested if the descriptor references a normal file that has that many bytes left before the end-of- file, but in no other case. Note that rreeaaddvv() and pprreeaaddvv() will fail if the value of _i_o_v_c_n_t exceeds the constant IOV_MAX. RREETTUURRNN VVAALLUUEESS If successful, the number of bytes actually read is returned. Upon reading end-of-file, zero is returned. Otherwise, a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS rreeaadd(), rreeaaddvv(), pprreeaadd(), and pprreeaaddvv() will succeed unless: [EBADF] _d is not a valid file or socket descriptor open for reading. [EFAULT] Part of _b_u_f points outside the process's allocated address space. [EIO] An I/O error occurred while reading from the file system. [EINTR] A read from a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data arrived. In addition, rreeaadd() and rreeaaddvv() may return the following errors: [EAGAIN] The file was marked for non-blocking I/O, and no data were ready to be read. [ENOTCONN] The file is a socket associated with a connection- oriented protocol and has not been connected. [EIO] The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned. rreeaadd() and pprreeaadd() may return the following error: [EINVAL] _n_b_y_t_e_s was larger than SSIZE_MAX. pprreeaadd() and pprreeaaddvv() may return the following errors: [EINVAL] _o_f_f_s_e_t was negative. [ESPIPE] _d is associated with a pipe, socket, FIFO, or tty. rreeaaddvv() and pprreeaaddvv() may return one of the following errors: [EINVAL] _i_o_v_c_n_t was less than or equal to 0, or greater than IOV_MAX. [EINVAL] The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed an _s_s_i_z_e___t. [EFAULT] Part of _i_o_v points outside the process's allocated address space. SSEEEE AALLSSOO dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), socketpair(2) SSTTAANNDDAARRDDSS The rreeaadd(), rreeaaddvv(), and pprreeaadd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A rreeaadd() system call first appeared in Version 1 AT&T UNIX; rreeaaddvv() in 4.1cBSD; pprreeaadd() in AT&T System V Release 4 UNIX; and pprreeaaddvv() in OpenBSD 2.7. CCAAVVEEAATTSS Error checks should explicitly test for -1. Code such as while ((nr = read(fd, buf, sizeof(buf))) > 0) is not maximally portable, as some platforms allow for _n_b_y_t_e_s to range between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an error-free rreeaadd() may appear as a negative number distinct from -1. Proper loops should use while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) NNAAMMEE rreeaaddlliinnkk, rreeaaddlliinnkkaatt - read value of a symbolic link SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeaaddlliinnkk(_c_o_n_s_t _c_h_a_r _*_r_e_s_t_r_i_c_t _p_a_t_h, _c_h_a_r _*_r_e_s_t_r_i_c_t _b_u_f, _s_i_z_e___t _b_u_f_s_i_z); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t rreeaaddlliinnkkaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_h_a_r _*_b_u_f, _s_i_z_e___t _b_u_f_s_i_z); DDEESSCCRRIIPPTTIIOONN The rreeaaddlliinnkk() function places the contents of the symbolic link _p_a_t_h in the buffer _b_u_f, which has size _b_u_f_s_i_z. rreeaaddlliinnkk does not append a NUL character to _b_u_f. The rreeaaddlliinnkkaatt() function is equivalent to rreeaaddlliinnkk() except that where _p_a_t_h specifies a relative path, the symbolic link whose contents are read is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If rreeaaddlliinnkkaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to rreeaaddlliinnkk(). RREETTUURRNN VVAALLUUEESS The call returns the count of characters placed in the buffer if it succeeds, or a -1 if an error occurs, placing the error code in the global variable _e_r_r_n_o. EERRRROORRSS rreeaaddlliinnkk() and rreeaaddlliinnkkaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EINVAL] The named file is not a symbolic link. [EIO] An I/O error occurred while reading from the file system. [EFAULT] _b_u_f or _p_a_t_h extends outside the process's allocated address space. Additionally, rreeaaddlliinnkkaatt() will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO lstat(2), stat(2), symlink(2), symlink(7) SSTTAANNDDAARRDDSS The rreeaaddlliinnkk() and rreeaaddlliinnkkaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The rreeaaddlliinnkk() system call first appeared in 4.1cBSD. The rreeaaddlliinnkkaatt() system call has been available since OpenBSD 5.0. NNAAMMEE rreeaaddlliinnkk, rreeaaddlliinnkkaatt - read value of a symbolic link SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeaaddlliinnkk(_c_o_n_s_t _c_h_a_r _*_r_e_s_t_r_i_c_t _p_a_t_h, _c_h_a_r _*_r_e_s_t_r_i_c_t _b_u_f, _s_i_z_e___t _b_u_f_s_i_z); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t rreeaaddlliinnkkaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_h_a_r _*_b_u_f, _s_i_z_e___t _b_u_f_s_i_z); DDEESSCCRRIIPPTTIIOONN The rreeaaddlliinnkk() function places the contents of the symbolic link _p_a_t_h in the buffer _b_u_f, which has size _b_u_f_s_i_z. rreeaaddlliinnkk does not append a NUL character to _b_u_f. The rreeaaddlliinnkkaatt() function is equivalent to rreeaaddlliinnkk() except that where _p_a_t_h specifies a relative path, the symbolic link whose contents are read is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If rreeaaddlliinnkkaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to rreeaaddlliinnkk(). RREETTUURRNN VVAALLUUEESS The call returns the count of characters placed in the buffer if it succeeds, or a -1 if an error occurs, placing the error code in the global variable _e_r_r_n_o. EERRRROORRSS rreeaaddlliinnkk() and rreeaaddlliinnkkaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EINVAL] The named file is not a symbolic link. [EIO] An I/O error occurred while reading from the file system. [EFAULT] _b_u_f or _p_a_t_h extends outside the process's allocated address space. Additionally, rreeaaddlliinnkkaatt() will fail if: [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO lstat(2), stat(2), symlink(2), symlink(7) SSTTAANNDDAARRDDSS The rreeaaddlliinnkk() and rreeaaddlliinnkkaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The rreeaaddlliinnkk() system call first appeared in 4.1cBSD. The rreeaaddlliinnkkaatt() system call has been available since OpenBSD 5.0. NNAAMMEE rreeaadd, rreeaaddvv, pprreeaadd, pprreeaaddvv - read input SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); _s_s_i_z_e___t pprreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s, _o_f_f___t _o_f_f_s_e_t); ##iinncclluuddee <> _s_s_i_z_e___t rreeaaddvv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t pprreeaaddvv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN rreeaadd() attempts to read _n_b_y_t_e_s of data from the object referenced by the descriptor _d into the buffer pointed to by _b_u_f. rreeaaddvv() performs the same action, but scatters the input data into the _i_o_v_c_n_t buffers specified by the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1]. pprreeaadd() and pprreeaaddvv() perform the same functions, but read from the specified position _o_f_f_s_e_t in the file without modifying the file pointer. For rreeaaddvv() and pprreeaaddvv(), the _i_o_v_e_c structure is defined as: struct iovec { void *iov_base; size_t iov_len; }; Each _i_o_v_e_c entry specifies the base address and length of an area in memory where data should be placed. rreeaaddvv() and pprreeaaddvv() will always fill an area completely before proceeding to the next. On objects capable of seeking, the rreeaadd() starts at a position given by the pointer associated with _d (see lseek(2)). Upon return from rreeaadd(), the pointer is incremented by the number of bytes actually read. Objects that are not capable of seeking always read from the current position. The value of the pointer associated with such an object is undefined. Upon successful completion, rreeaadd(), rreeaaddvv(), pprreeaadd(), and pprreeaaddvv() return the number of bytes actually read and placed in the buffer. The system guarantees to read the number of bytes requested if the descriptor references a normal file that has that many bytes left before the end-of- file, but in no other case. Note that rreeaaddvv() and pprreeaaddvv() will fail if the value of _i_o_v_c_n_t exceeds the constant IOV_MAX. RREETTUURRNN VVAALLUUEESS If successful, the number of bytes actually read is returned. Upon reading end-of-file, zero is returned. Otherwise, a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS rreeaadd(), rreeaaddvv(), pprreeaadd(), and pprreeaaddvv() will succeed unless: [EBADF] _d is not a valid file or socket descriptor open for reading. [EFAULT] Part of _b_u_f points outside the process's allocated address space. [EIO] An I/O error occurred while reading from the file system. [EINTR] A read from a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data arrived. In addition, rreeaadd() and rreeaaddvv() may return the following errors: [EAGAIN] The file was marked for non-blocking I/O, and no data were ready to be read. [ENOTCONN] The file is a socket associated with a connection- oriented protocol and has not been connected. [EIO] The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or blocking the SIGTTIN signal or the process group is orphaned. rreeaadd() and pprreeaadd() may return the following error: [EINVAL] _n_b_y_t_e_s was larger than SSIZE_MAX. pprreeaadd() and pprreeaaddvv() may return the following errors: [EINVAL] _o_f_f_s_e_t was negative. [ESPIPE] _d is associated with a pipe, socket, FIFO, or tty. rreeaaddvv() and pprreeaaddvv() may return one of the following errors: [EINVAL] _i_o_v_c_n_t was less than or equal to 0, or greater than IOV_MAX. [EINVAL] The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed an _s_s_i_z_e___t. [EFAULT] Part of _i_o_v points outside the process's allocated address space. SSEEEE AALLSSOO dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), socketpair(2) SSTTAANNDDAARRDDSS The rreeaadd(), rreeaaddvv(), and pprreeaadd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A rreeaadd() system call first appeared in Version 1 AT&T UNIX; rreeaaddvv() in 4.1cBSD; pprreeaadd() in AT&T System V Release 4 UNIX; and pprreeaaddvv() in OpenBSD 2.7. CCAAVVEEAATTSS Error checks should explicitly test for -1. Code such as while ((nr = read(fd, buf, sizeof(buf))) > 0) is not maximally portable, as some platforms allow for _n_b_y_t_e_s to range between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an error-free rreeaadd() may appear as a negative number distinct from -1. Proper loops should use while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) NNAAMMEE rreebboooott - reboot system or halt processor SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t rreebboooott(_i_n_t _h_o_w_t_o); DDEESSCCRRIIPPTTIIOONN rreebboooott() reboots the system. Only the superuser may reboot a machine on demand. However, a reboot is invoked automatically in the event of unrecoverable system failures. _h_o_w_t_o is a mask of options; the system call interface allows the following options, defined in the include file <_s_y_s_/_r_e_b_o_o_t_._h>, to be passed to the new kernel or the new bootstrap and init programs. RB_AUTOBOOT The default, causing the system to reboot in its usual fashion. RB_ASKNAME Interpreted by the bootstrap program itself, causing it to prompt on the console as to what file should be booted. Normally, the system is booted from the file ``_x_x(0,0)bsd'', where _x_x is the default disk name, without prompting for the file name. RB_DFLTROOT Use the compiled in root device. Normally, the system uses the device from which it was booted as the root device if possible. (The default behavior is dependent on the ability of the bootstrap program to determine the drive from which it was loaded, which is not possible on all systems.) RB_DUMP Dump kernel memory before rebooting; see savecore(8) for more information. RB_HALT The processor is simply halted; no reboot takes place. RB_POWERDOWN If used in conjunction with RB_HALT, and if the system hardware supports the function, the system will be powered off. RB_USERREQ By default, the system will halt if rreebboooott() is called during startup (before the system has finished autoconfiguration), even if RB_HALT is not specified. This is because panic(9)s during startup will probably just repeat on the next boot. Use of this option implies that the user has requested the action specified (for example, using the ddb(4) bboooott rreebboooott command), so the system will reboot if a halt is not explicitly requested. RB_INITNAME An option allowing the specification of an init program (see init(8)) other than _/_s_b_i_n_/_i_n_i_t to be run when the system reboots. This switch is not currently available. RB_KDB Load the symbol table and enable a built-in debugger in the system. This option will have no useful function if the kernel is not configured for debugging. Several other options have different meaning if combined with this option, although their use may not be possible via the rreebboooott() call. See ddb(4) for more information. RB_NOSYNC Normally, the disks are sync'd (see sync(8)) before the processor is halted or rebooted. This option may be useful if file system changes have been made manually or if the processor is on fire. RB_RDONLY Initially mount the root file system read-only. This is currently the default, and this option has been deprecated. RB_SINGLE Normally, the reboot procedure involves an automatic disk consistency check and then multi-user operations. RB_SINGLE prevents this, booting the system with a single- user shell on the console. RB_SINGLE is actually interpreted by the init(8) program in the newly booted system. When no options are given (i.e., RB_AUTOBOOT is used), the system is rebooted from file _/_b_s_d in the root file system of unit 0 of a disk chosen in a processor specific way. An automatic consistency check of the disks is normally performed (see fsck(8)). RREETTUURRNN VVAALLUUEESS If successful, this call never returns. Otherwise, a -1 is returned and an error is returned in the global variable _e_r_r_n_o. EERRRROORRSS [EPERM] The caller is not the superuser. SSEEEE AALLSSOO ddb(4), crash(8), halt(8), init(8), reboot(8), savecore(8), boot(9), panic(9) HHIISSTTOORRYY The rreebboooott() system call finally appeared in 4.0BSD. BBUUGGSS Not all platforms support all possible arguments. NNAAMMEE rreeccvv, rreeccvvffrroomm, rreeccvvmmssgg - receive a message from a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeccvv(_i_n_t _s, _v_o_i_d _*_b_u_f, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s); _s_s_i_z_e___t rreeccvvffrroomm(_i_n_t _s, _v_o_i_d _*_b_u_f, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_f_r_o_m, _s_o_c_k_l_e_n___t _*_f_r_o_m_l_e_n); _s_s_i_z_e___t rreeccvvmmssgg(_i_n_t _s, _s_t_r_u_c_t _m_s_g_h_d_r _*_m_s_g, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN rreeccvvffrroomm() and rreeccvvmmssgg() are used to receive messages from a socket, _s, and may be used to receive data on a socket whether or not it is connection-oriented. If _f_r_o_m is non-null and the socket is not connection-oriented, the source address of the message is filled in. _f_r_o_m_l_e_n is a value-result parameter, initialized to the size of the buffer associated with _f_r_o_m, and modified on return to indicate the actual size of the address stored there. The rreeccvv() call is normally used only on a _c_o_n_n_e_c_t_e_d socket (see connect(2)) and is identical to rreeccvvffrroomm() with a null _f_r_o_m parameter. As it is redundant, it may not be supported in future releases. On successful completion, all three routines return the number of message bytes read. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket(2)). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see fcntl(2)) in which case the value -1 is returned and the external variable _e_r_r_n_o set to EAGAIN. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested; this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). The select(2) or poll(2) system calls may be used to determine when more data arrive. The _f_l_a_g_s argument is the bitwise OR of zero or more of the following values: MSG_OOB process out-of-band data MSG_PEEK peek at incoming message MSG_WAITALL wait for full request or error MSG_DONTWAIT don't block MSG_CMSG_CLOEXEC set the close-on-exec flag on received file descriptors The MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. The MSG_WAITALL flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. The MSG_DONTWAIT flag requests the call to return when it would block otherwise. If no data is available, _e_r_r_n_o is set to EAGAIN. This flag is not available in strict ANSI or C99 compilation mode. The MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary data with rreeccvvmmssgg() (see below) have their close-on-exec flag set. The rreeccvvmmssgg() call uses a _m_s_g_h_d_r structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in <_s_y_s_/_s_o_c_k_e_t_._h>: struct msghdr { void *msg_name; /* optional address */ socklen_t msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter/gather array */ unsigned int msg_iovlen; /* # elements in msg_iov */ void *msg_control; /* ancillary data, see below */ socklen_t msg_controllen; /* ancillary data buffer len */ int msg_flags; /* flags on received message */ }; Here _m_s_g___n_a_m_e and _m_s_g___n_a_m_e_l_e_n specify the source address if the socket is unconnected; _m_s_g___n_a_m_e may be given as a null pointer if no names are desired or required. _m_s_g___i_o_v and _m_s_g___i_o_v_l_e_n describe scatter gather locations, as discussed in read(2). _m_s_g___c_o_n_t_r_o_l, which has length _m_s_g___c_o_n_t_r_o_l_l_e_n, points to a buffer for other protocol control related messages or other miscellaneous ancillary data. The messages are of the form: struct cmsghdr { socklen_t cmsg_len; /* data byte count, including hdr */ int cmsg_level; /* originating protocol */ int cmsg_type; /* protocol-specific type */ /* followed by u_char cmsg_data[]; */ }; See CMSG_DATA(3) for how these messages are constructed and decomposed. Open file descriptors are now passed as ancillary data for AF_UNIX domain and socketpair(2) sockets, with _c_m_s_g___l_e_v_e_l set to SOL_SOCKET and _c_m_s_g___t_y_p_e set to SCM_RIGHTS. The _m_s_g___f_l_a_g_s field is set on return according to the message received. It will contain zero or more of the following values: MSG_OOB Returned to indicate that expedited or out-of-band data was received. MSG_EOR Indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET). MSG_TRUNC Indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. MSG_CTRUNC Indicates that some control data were discarded due to lack of space in the buffer for ancillary data. MSG_BCAST Indicates that the packet was received as broadcast. MSG_MCAST Indicates that the packet was received as multicast. RREETTUURRNN VVAALLUUEESS These calls return the number of bytes received, or -1 if an error occurred. EERRRROORRSS rreeccvv(), rreeccvvffrroomm(), and rreeccvvmmssgg() fail if: [EBADF] The argument _s is an invalid descriptor. [ENOTCONN] The socket is associated with a connection-oriented protocol and has not been connected (see connect(2) and accept(2)). [ENOTSOCK] The argument _s does not refer to a socket. [EAGAIN] The socket is marked non-blocking, and the receive operation would block, or a receive timeout had been set, and the timeout expired before data were received. [EINTR] The receive was interrupted by delivery of a signal before any data were available. [EFAULT] The receive buffer pointer(s) point outside the process's address space. [EHOSTUNREACH] A socket operation was attempted to an unreachable host. [EHOSTDOWN] A socket operation failed because the destination host was down. [ENETDOWN] A socket operation encountered a dead network. [ECONNREFUSED] The socket is associated with a connection-oriented protocol and the connection was forcefully rejected (see connect(2)). In addition, rreeccvv() and rreeccvvffrroomm() may return the following error: [EINVAL] _l_e_n was larger than SSIZE_MAX. And rreeccvvmmssgg() may return one of the following errors: [EINVAL] The sum of the _i_o_v___l_e_n values in the _m_s_g___i_o_v array overflowed an _s_s_i_z_e___t. [EMSGSIZE] The _m_s_g___i_o_v_l_e_n member of _m_s_g was less than 0 or larger than IOV_MAX. [EMSGSIZE] The receiving program did not have sufficient free file descriptor slots. The descriptors are closed and any pending data can be returned by another call to rreeccvvmmssgg(). SSEEEE AALLSSOO connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) SSTTAANNDDAARRDDSS The rreeccvv(), rreeccvvffrroomm(), and rreeccvvmmssgg() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST flags are extensions to that specification. HHIISSTTOORRYY The rreeccvv() function call appeared in 4.2BSD. NNAAMMEE rreeccvv, rreeccvvffrroomm, rreeccvvmmssgg - receive a message from a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeccvv(_i_n_t _s, _v_o_i_d _*_b_u_f, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s); _s_s_i_z_e___t rreeccvvffrroomm(_i_n_t _s, _v_o_i_d _*_b_u_f, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_f_r_o_m, _s_o_c_k_l_e_n___t _*_f_r_o_m_l_e_n); _s_s_i_z_e___t rreeccvvmmssgg(_i_n_t _s, _s_t_r_u_c_t _m_s_g_h_d_r _*_m_s_g, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN rreeccvvffrroomm() and rreeccvvmmssgg() are used to receive messages from a socket, _s, and may be used to receive data on a socket whether or not it is connection-oriented. If _f_r_o_m is non-null and the socket is not connection-oriented, the source address of the message is filled in. _f_r_o_m_l_e_n is a value-result parameter, initialized to the size of the buffer associated with _f_r_o_m, and modified on return to indicate the actual size of the address stored there. The rreeccvv() call is normally used only on a _c_o_n_n_e_c_t_e_d socket (see connect(2)) and is identical to rreeccvvffrroomm() with a null _f_r_o_m parameter. As it is redundant, it may not be supported in future releases. On successful completion, all three routines return the number of message bytes read. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket(2)). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see fcntl(2)) in which case the value -1 is returned and the external variable _e_r_r_n_o set to EAGAIN. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested; this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). The select(2) or poll(2) system calls may be used to determine when more data arrive. The _f_l_a_g_s argument is the bitwise OR of zero or more of the following values: MSG_OOB process out-of-band data MSG_PEEK peek at incoming message MSG_WAITALL wait for full request or error MSG_DONTWAIT don't block MSG_CMSG_CLOEXEC set the close-on-exec flag on received file descriptors The MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. The MSG_WAITALL flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. The MSG_DONTWAIT flag requests the call to return when it would block otherwise. If no data is available, _e_r_r_n_o is set to EAGAIN. This flag is not available in strict ANSI or C99 compilation mode. The MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary data with rreeccvvmmssgg() (see below) have their close-on-exec flag set. The rreeccvvmmssgg() call uses a _m_s_g_h_d_r structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in <_s_y_s_/_s_o_c_k_e_t_._h>: struct msghdr { void *msg_name; /* optional address */ socklen_t msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter/gather array */ unsigned int msg_iovlen; /* # elements in msg_iov */ void *msg_control; /* ancillary data, see below */ socklen_t msg_controllen; /* ancillary data buffer len */ int msg_flags; /* flags on received message */ }; Here _m_s_g___n_a_m_e and _m_s_g___n_a_m_e_l_e_n specify the source address if the socket is unconnected; _m_s_g___n_a_m_e may be given as a null pointer if no names are desired or required. _m_s_g___i_o_v and _m_s_g___i_o_v_l_e_n describe scatter gather locations, as discussed in read(2). _m_s_g___c_o_n_t_r_o_l, which has length _m_s_g___c_o_n_t_r_o_l_l_e_n, points to a buffer for other protocol control related messages or other miscellaneous ancillary data. The messages are of the form: struct cmsghdr { socklen_t cmsg_len; /* data byte count, including hdr */ int cmsg_level; /* originating protocol */ int cmsg_type; /* protocol-specific type */ /* followed by u_char cmsg_data[]; */ }; See CMSG_DATA(3) for how these messages are constructed and decomposed. Open file descriptors are now passed as ancillary data for AF_UNIX domain and socketpair(2) sockets, with _c_m_s_g___l_e_v_e_l set to SOL_SOCKET and _c_m_s_g___t_y_p_e set to SCM_RIGHTS. The _m_s_g___f_l_a_g_s field is set on return according to the message received. It will contain zero or more of the following values: MSG_OOB Returned to indicate that expedited or out-of-band data was received. MSG_EOR Indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET). MSG_TRUNC Indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. MSG_CTRUNC Indicates that some control data were discarded due to lack of space in the buffer for ancillary data. MSG_BCAST Indicates that the packet was received as broadcast. MSG_MCAST Indicates that the packet was received as multicast. RREETTUURRNN VVAALLUUEESS These calls return the number of bytes received, or -1 if an error occurred. EERRRROORRSS rreeccvv(), rreeccvvffrroomm(), and rreeccvvmmssgg() fail if: [EBADF] The argument _s is an invalid descriptor. [ENOTCONN] The socket is associated with a connection-oriented protocol and has not been connected (see connect(2) and accept(2)). [ENOTSOCK] The argument _s does not refer to a socket. [EAGAIN] The socket is marked non-blocking, and the receive operation would block, or a receive timeout had been set, and the timeout expired before data were received. [EINTR] The receive was interrupted by delivery of a signal before any data were available. [EFAULT] The receive buffer pointer(s) point outside the process's address space. [EHOSTUNREACH] A socket operation was attempted to an unreachable host. [EHOSTDOWN] A socket operation failed because the destination host was down. [ENETDOWN] A socket operation encountered a dead network. [ECONNREFUSED] The socket is associated with a connection-oriented protocol and the connection was forcefully rejected (see connect(2)). In addition, rreeccvv() and rreeccvvffrroomm() may return the following error: [EINVAL] _l_e_n was larger than SSIZE_MAX. And rreeccvvmmssgg() may return one of the following errors: [EINVAL] The sum of the _i_o_v___l_e_n values in the _m_s_g___i_o_v array overflowed an _s_s_i_z_e___t. [EMSGSIZE] The _m_s_g___i_o_v_l_e_n member of _m_s_g was less than 0 or larger than IOV_MAX. [EMSGSIZE] The receiving program did not have sufficient free file descriptor slots. The descriptors are closed and any pending data can be returned by another call to rreeccvvmmssgg(). SSEEEE AALLSSOO connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) SSTTAANNDDAARRDDSS The rreeccvv(), rreeccvvffrroomm(), and rreeccvvmmssgg() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST flags are extensions to that specification. HHIISSTTOORRYY The rreeccvv() function call appeared in 4.2BSD. NNAAMMEE rreeccvv, rreeccvvffrroomm, rreeccvvmmssgg - receive a message from a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t rreeccvv(_i_n_t _s, _v_o_i_d _*_b_u_f, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s); _s_s_i_z_e___t rreeccvvffrroomm(_i_n_t _s, _v_o_i_d _*_b_u_f, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s, _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_f_r_o_m, _s_o_c_k_l_e_n___t _*_f_r_o_m_l_e_n); _s_s_i_z_e___t rreeccvvmmssgg(_i_n_t _s, _s_t_r_u_c_t _m_s_g_h_d_r _*_m_s_g, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN rreeccvvffrroomm() and rreeccvvmmssgg() are used to receive messages from a socket, _s, and may be used to receive data on a socket whether or not it is connection-oriented. If _f_r_o_m is non-null and the socket is not connection-oriented, the source address of the message is filled in. _f_r_o_m_l_e_n is a value-result parameter, initialized to the size of the buffer associated with _f_r_o_m, and modified on return to indicate the actual size of the address stored there. The rreeccvv() call is normally used only on a _c_o_n_n_e_c_t_e_d socket (see connect(2)) and is identical to rreeccvvffrroomm() with a null _f_r_o_m parameter. As it is redundant, it may not be supported in future releases. On successful completion, all three routines return the number of message bytes read. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket(2)). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see fcntl(2)) in which case the value -1 is returned and the external variable _e_r_r_n_o set to EAGAIN. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested; this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). The select(2) or poll(2) system calls may be used to determine when more data arrive. The _f_l_a_g_s argument is the bitwise OR of zero or more of the following values: MSG_OOB process out-of-band data MSG_PEEK peek at incoming message MSG_WAITALL wait for full request or error MSG_DONTWAIT don't block MSG_CMSG_CLOEXEC set the close-on-exec flag on received file descriptors The MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. The MSG_WAITALL flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. The MSG_DONTWAIT flag requests the call to return when it would block otherwise. If no data is available, _e_r_r_n_o is set to EAGAIN. This flag is not available in strict ANSI or C99 compilation mode. The MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary data with rreeccvvmmssgg() (see below) have their close-on-exec flag set. The rreeccvvmmssgg() call uses a _m_s_g_h_d_r structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in <_s_y_s_/_s_o_c_k_e_t_._h>: struct msghdr { void *msg_name; /* optional address */ socklen_t msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter/gather array */ unsigned int msg_iovlen; /* # elements in msg_iov */ void *msg_control; /* ancillary data, see below */ socklen_t msg_controllen; /* ancillary data buffer len */ int msg_flags; /* flags on received message */ }; Here _m_s_g___n_a_m_e and _m_s_g___n_a_m_e_l_e_n specify the source address if the socket is unconnected; _m_s_g___n_a_m_e may be given as a null pointer if no names are desired or required. _m_s_g___i_o_v and _m_s_g___i_o_v_l_e_n describe scatter gather locations, as discussed in read(2). _m_s_g___c_o_n_t_r_o_l, which has length _m_s_g___c_o_n_t_r_o_l_l_e_n, points to a buffer for other protocol control related messages or other miscellaneous ancillary data. The messages are of the form: struct cmsghdr { socklen_t cmsg_len; /* data byte count, including hdr */ int cmsg_level; /* originating protocol */ int cmsg_type; /* protocol-specific type */ /* followed by u_char cmsg_data[]; */ }; See CMSG_DATA(3) for how these messages are constructed and decomposed. Open file descriptors are now passed as ancillary data for AF_UNIX domain and socketpair(2) sockets, with _c_m_s_g___l_e_v_e_l set to SOL_SOCKET and _c_m_s_g___t_y_p_e set to SCM_RIGHTS. The _m_s_g___f_l_a_g_s field is set on return according to the message received. It will contain zero or more of the following values: MSG_OOB Returned to indicate that expedited or out-of-band data was received. MSG_EOR Indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET). MSG_TRUNC Indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. MSG_CTRUNC Indicates that some control data were discarded due to lack of space in the buffer for ancillary data. MSG_BCAST Indicates that the packet was received as broadcast. MSG_MCAST Indicates that the packet was received as multicast. RREETTUURRNN VVAALLUUEESS These calls return the number of bytes received, or -1 if an error occurred. EERRRROORRSS rreeccvv(), rreeccvvffrroomm(), and rreeccvvmmssgg() fail if: [EBADF] The argument _s is an invalid descriptor. [ENOTCONN] The socket is associated with a connection-oriented protocol and has not been connected (see connect(2) and accept(2)). [ENOTSOCK] The argument _s does not refer to a socket. [EAGAIN] The socket is marked non-blocking, and the receive operation would block, or a receive timeout had been set, and the timeout expired before data were received. [EINTR] The receive was interrupted by delivery of a signal before any data were available. [EFAULT] The receive buffer pointer(s) point outside the process's address space. [EHOSTUNREACH] A socket operation was attempted to an unreachable host. [EHOSTDOWN] A socket operation failed because the destination host was down. [ENETDOWN] A socket operation encountered a dead network. [ECONNREFUSED] The socket is associated with a connection-oriented protocol and the connection was forcefully rejected (see connect(2)). In addition, rreeccvv() and rreeccvvffrroomm() may return the following error: [EINVAL] _l_e_n was larger than SSIZE_MAX. And rreeccvvmmssgg() may return one of the following errors: [EINVAL] The sum of the _i_o_v___l_e_n values in the _m_s_g___i_o_v array overflowed an _s_s_i_z_e___t. [EMSGSIZE] The _m_s_g___i_o_v_l_e_n member of _m_s_g was less than 0 or larger than IOV_MAX. [EMSGSIZE] The receiving program did not have sufficient free file descriptor slots. The descriptors are closed and any pending data can be returned by another call to rreeccvvmmssgg(). SSEEEE AALLSSOO connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) SSTTAANNDDAARRDDSS The rreeccvv(), rreeccvvffrroomm(), and rreeccvvmmssgg() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST flags are extensions to that specification. HHIISSTTOORRYY The rreeccvv() function call appeared in 4.2BSD. NNAAMMEE rreennaammee, rreennaammeeaatt - change the name of a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t rreennaammee(_c_o_n_s_t _c_h_a_r _*_f_r_o_m, _c_o_n_s_t _c_h_a_r _*_t_o); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t rreennaammeeaatt(_i_n_t _f_r_o_m_f_d, _c_o_n_s_t _c_h_a_r _*_f_r_o_m, _i_n_t _t_o_f_d, _c_o_n_s_t _c_h_a_r _*_t_o); DDEESSCCRRIIPPTTIIOONN The rreennaammee() function causes the link named _f_r_o_m to be renamed as _t_o. If _t_o exists, it is first removed. Both _f_r_o_m and _t_o must be of the same type (that is, both directories or both non-directories), and must reside on the same file system. rreennaammee() guarantees that if _t_o already exists, an instance of _t_o will always exist, even if the system should crash in the middle of the operation. If the final component of _f_r_o_m is a symbolic link, the symbolic link is renamed, not the file or directory to which it points. The rreennaammeeaatt() function is equivalent to rreennaammee() except that where _f_r_o_m or _t_o specifies a relative path, the directory entry names used are resolved relative to the directories associated with file descriptors _f_r_o_m_f_d or _t_o_f_d (respectively) instead of the current working directory. If rreennaammeeaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_r_o_m_f_d or _t_o_f_d parameter, the current working directory is used for resolving the respective _f_r_o_m or _t_o argument. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS rreennaammee() and rreennaammeeaatt() will fail and neither of the argument files will be affected if: [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of the _f_r_o_m path does not exist, or a path prefix of _t_o does not exist. [EACCES] A component of either path prefix denies search permission. [EACCES] The requested change requires writing in a directory that denies write permission. [EACCES] The _f_r_o_m argument is a directory and denies write permission. [EPERM] The directory containing _f_r_o_m is marked sticky, and neither the containing directory nor _f_r_o_m are owned by the effective user ID. [EPERM] The _t_o file exists, the directory containing _t_o is marked sticky, and neither the containing directory nor _t_o are owned by the effective user ID. [ELOOP] Too many symbolic links were encountered in translating either pathname. [EMLINK] The link count on the source file or destination directory is at the maximum. A rename cannot be completed under these conditions. [ENOTDIR] A component of either path prefix is not a directory. [ENOTDIR] _f_r_o_m is a directory, but _t_o is not a directory. [EISDIR] _t_o is a directory, but _f_r_o_m is not a directory. [EXDEV] The link named by _t_o and the file named by _f_r_o_m are on different logical devices (file systems). Note that this error code will not be returned if the implementation permits cross-device links. [ENOSPC] The directory in which the entry for the new name is being placed cannot be extended because there is no space left on the file system containing the directory. [EDQUOT] The directory in which the entry for the new name is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EIO] An I/O error occurred while making or updating a directory entry. [EROFS] The requested link requires writing in a directory on a read-only file system. [EFAULT] _f_r_o_m or _t_o points outside the process's allocated address space. [EINVAL] _f_r_o_m is a parent directory of _t_o, or an attempt is made to rename `.' or `..'. [ENOTEMPTY] _t_o is a directory and is not empty. Additionally, rreennaammeeaatt() will fail if: [EBADF] The _f_r_o_m or _t_o argument specifies a relative path and the _f_r_o_m_f_d or _t_o_f_d argument, respectively, is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _f_r_o_m or _t_o argument specifies a relative path and the _f_r_o_m_f_d or _t_o_f_d argument, respectively, is a valid file descriptor but it does not reference a directory. [EACCES] The _f_r_o_m or _t_o argument specifies a relative path but search permission is denied for the directory which the _f_r_o_m_f_d or _t_o_f_d file descriptor, respectively, references. SSEEEE AALLSSOO mv(1), open(2), symlink(7) SSTTAANNDDAARRDDSS The rreennaammee() and rreennaammeeaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The rreennaammeeaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The system can deadlock if a loop in the file system graph is present. This loop takes the form of an entry in directory `_a', say `_a_/_f_o_o', being a hard link to directory `_b', and an entry in directory `_b', say `_b_/_b_a_r', being a hard link to directory `_a'. When such a loop exists and two separate processes attempt to perform `rename a/foo b/bar' and `rename b/bar a/foo', respectively, the system may deadlock attempting to lock both directories for modification. Hard links to directories should be replaced by symbolic links by the system administrator. NNAAMMEE rreennaammee, rreennaammeeaatt - change the name of a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t rreennaammee(_c_o_n_s_t _c_h_a_r _*_f_r_o_m, _c_o_n_s_t _c_h_a_r _*_t_o); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t rreennaammeeaatt(_i_n_t _f_r_o_m_f_d, _c_o_n_s_t _c_h_a_r _*_f_r_o_m, _i_n_t _t_o_f_d, _c_o_n_s_t _c_h_a_r _*_t_o); DDEESSCCRRIIPPTTIIOONN The rreennaammee() function causes the link named _f_r_o_m to be renamed as _t_o. If _t_o exists, it is first removed. Both _f_r_o_m and _t_o must be of the same type (that is, both directories or both non-directories), and must reside on the same file system. rreennaammee() guarantees that if _t_o already exists, an instance of _t_o will always exist, even if the system should crash in the middle of the operation. If the final component of _f_r_o_m is a symbolic link, the symbolic link is renamed, not the file or directory to which it points. The rreennaammeeaatt() function is equivalent to rreennaammee() except that where _f_r_o_m or _t_o specifies a relative path, the directory entry names used are resolved relative to the directories associated with file descriptors _f_r_o_m_f_d or _t_o_f_d (respectively) instead of the current working directory. If rreennaammeeaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_r_o_m_f_d or _t_o_f_d parameter, the current working directory is used for resolving the respective _f_r_o_m or _t_o argument. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS rreennaammee() and rreennaammeeaatt() will fail and neither of the argument files will be affected if: [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of the _f_r_o_m path does not exist, or a path prefix of _t_o does not exist. [EACCES] A component of either path prefix denies search permission. [EACCES] The requested change requires writing in a directory that denies write permission. [EACCES] The _f_r_o_m argument is a directory and denies write permission. [EPERM] The directory containing _f_r_o_m is marked sticky, and neither the containing directory nor _f_r_o_m are owned by the effective user ID. [EPERM] The _t_o file exists, the directory containing _t_o is marked sticky, and neither the containing directory nor _t_o are owned by the effective user ID. [ELOOP] Too many symbolic links were encountered in translating either pathname. [EMLINK] The link count on the source file or destination directory is at the maximum. A rename cannot be completed under these conditions. [ENOTDIR] A component of either path prefix is not a directory. [ENOTDIR] _f_r_o_m is a directory, but _t_o is not a directory. [EISDIR] _t_o is a directory, but _f_r_o_m is not a directory. [EXDEV] The link named by _t_o and the file named by _f_r_o_m are on different logical devices (file systems). Note that this error code will not be returned if the implementation permits cross-device links. [ENOSPC] The directory in which the entry for the new name is being placed cannot be extended because there is no space left on the file system containing the directory. [EDQUOT] The directory in which the entry for the new name is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EIO] An I/O error occurred while making or updating a directory entry. [EROFS] The requested link requires writing in a directory on a read-only file system. [EFAULT] _f_r_o_m or _t_o points outside the process's allocated address space. [EINVAL] _f_r_o_m is a parent directory of _t_o, or an attempt is made to rename `.' or `..'. [ENOTEMPTY] _t_o is a directory and is not empty. Additionally, rreennaammeeaatt() will fail if: [EBADF] The _f_r_o_m or _t_o argument specifies a relative path and the _f_r_o_m_f_d or _t_o_f_d argument, respectively, is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _f_r_o_m or _t_o argument specifies a relative path and the _f_r_o_m_f_d or _t_o_f_d argument, respectively, is a valid file descriptor but it does not reference a directory. [EACCES] The _f_r_o_m or _t_o argument specifies a relative path but search permission is denied for the directory which the _f_r_o_m_f_d or _t_o_f_d file descriptor, respectively, references. SSEEEE AALLSSOO mv(1), open(2), symlink(7) SSTTAANNDDAARRDDSS The rreennaammee() and rreennaammeeaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The rreennaammeeaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The system can deadlock if a loop in the file system graph is present. This loop takes the form of an entry in directory `_a', say `_a_/_f_o_o', being a hard link to directory `_b', and an entry in directory `_b', say `_b_/_b_a_r', being a hard link to directory `_a'. When such a loop exists and two separate processes attempt to perform `rename a/foo b/bar' and `rename b/bar a/foo', respectively, the system may deadlock attempting to lock both directories for modification. Hard links to directories should be replaced by symbolic links by the system administrator. NNAAMMEE rreevvookkee - revoke file access SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t rreevvookkee(_c_o_n_s_t _c_h_a_r _*_p_a_t_h); DDEESSCCRRIIPPTTIIOONN The rreevvookkee function invalidates all current open file descriptors in the system for the file named by _p_a_t_h. Subsequent operations on any such descriptors fail, with the exceptions that a rreeaadd() from a character device file which has been revoked returns a count of zero (end of file), and a cclloossee() call will succeed. If the file is a special file for a device which is open, the device close function is called as if all open references to the file had been closed. Access to a file may be revoked only by its owner or the superuser. The rreevvookkee function is normally used to prepare a terminal device for a new login session, preventing any access by a previous user of the terminal. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS Access to the named file is revoked unless one of the following: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file or a component of the path name does not exist. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _p_a_t_h points outside the process's allocated address space. [EPERM] The caller is neither the owner of the file nor the superuser. SSEEEE AALLSSOO close(2) HHIISSTTOORRYY The rreevvookkee function was introduced in 4.3BSD-Reno. NNAAMMEE rrmmddiirr - remove a directory file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t rrmmddiirr(_c_o_n_s_t _c_h_a_r _*_p_a_t_h); DDEESSCCRRIIPPTTIIOONN rrmmddiirr() removes a directory file whose name is given by _p_a_t_h. The directory must not have any entries other than `.' and `..'. There is no rrmmddiirraatt() function; to remove a directory with a path relative to the directory associated with a file descriptor use the unlinkat(2) function with the AT_REMOVEDIR flag. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The named file is removed unless: [ENOTDIR] A component of the path is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named directory does not exist. [ELOOP] Too many symbolic links were encountered in translating the pathname. [ENOTEMPTY] The named directory contains files other than `.' and `..' in it. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] Write permission is denied on the directory containing the directory to be removed. [EPERM] The directory containing the directory to be removed is marked sticky, and neither the containing directory nor the directory to be removed are owned by the effective user ID. [EPERM] The directory to be removed or the directory containing it has its immutable or append-only flag set (see chflags(2)). [EBUSY] The directory to be removed is the mount point for a mounted file system or the current directory. [EIO] An I/O error occurred while deleting the directory entry or deallocating the inode. [EROFS] The directory entry to be removed resides on a read- only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. SSEEEE AALLSSOO rmdir(1), chflags(2), mkdir(2), unlink(2) SSTTAANNDDAARRDDSS rrmmddiirr() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The rrmmddiirr() function call appeared in 4.2BSD. NNAAMMEE bbrrkk, ssbbrrkk - change data segment size SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t bbrrkk(_v_o_i_d _*_a_d_d_r); _v_o_i_d _* ssbbrrkk(_i_n_t _i_n_c_r); DDEESSCCRRIIPPTTIIOONN TThhee bbrrkk(()) aanndd ssbbrrkk(()) ffuunnccttiioonnss aarree hhiissttoorriiccaall ccuurriioossiittiieess lleefftt oovveerr ffrroomm eeaarrlliieerr ddaayyss bbeeffoorree tthhee aaddvveenntt ooff vviirrttuuaall mmeemmoorryy mmaannaaggeemmeenntt.. The bbrrkk() function sets the break or lowest address of a process's data segment (uninitialized data) to _a_d_d_r (immediately above bss). Data addressing is restricted between _a_d_d_r and the lowest stack pointer to the stack segment. Memory is allocated by bbrrkk() in page size pieces; if _a_d_d_r is not evenly divisible by the system page size, it is increased to the next page boundary. The current value of the program break is reliably returned by ``sbrk(0)'' (see also end(3)). The getrlimit(2) system call may be used to determine the maximum permissible size of the _d_a_t_a segment; it will not be possible to set the break beyond the _r_l_i_m___m_a_x value returned from a call to getrlimit(2), e.g., ``etext + rlp->rlim_max'' (see end(3) for the definition of _e_t_e_x_t). RREETTUURRNN VVAALLUUEESS The bbrrkk() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. The ssbbrrkk() function returns a pointer to the base of the new storage if successful; otherwise -1 with _e_r_r_n_o set to indicate why the allocation failed. EERRRROORRSS ssbbrrkk() will fail and no additional memory will be allocated if one of the following are true: [ENOMEM] The limit, as set by setrlimit(2), was exceeded. [ENOMEM] The maximum possible size of a data segment (compiled into the system) was exceeded. [ENOMEM] Insufficient space existed in the swap area to support the expansion. SSEEEE AALLSSOO execve(2), getrlimit(2), mmap(2), end(3), malloc(3) HHIISSTTOORRYY A bbrrkk() function call appeared in Version 7 AT&T UNIX. BBUUGGSS Setting the break may fail due to a temporary lack of swap space. It is not possible to distinguish this from a failure caused by exceeding the maximum size of the data segment without consulting getrlimit(2). NNAAMMEE sscchheedd__yyiieelldd - yield the processor SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sscchheedd__yyiieelldd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The sscchheedd__yyiieelldd() function makes the current thread yield the processor and be put at the end of its run queue without altering its priority. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. SSTTAANNDDAARRDDSS The sscchheedd__yyiieelldd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The sscchheedd__yyiieelldd() system call appeared in OpenBSD 4.2. CCAAVVEEAATTSS The effect of sscchheedd__yyiieelldd() is only precisely defined for real-time scheduling classes, none of which are currently supported by OpenBSD. NNAAMMEE sseelleecctt, ppsseelleecctt - synchronous I/O multiplexing SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseelleecctt(_i_n_t _n_f_d_s, _f_d___s_e_t _*_r_e_a_d_f_d_s, _f_d___s_e_t _*_w_r_i_t_e_f_d_s, _f_d___s_e_t _*_e_x_c_e_p_t_f_d_s, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_o_u_t); _i_n_t ppsseelleecctt(_i_n_t _n_f_d_s, _f_d___s_e_t _*_r_e_a_d_f_d_s, _f_d___s_e_t _*_w_r_i_t_e_f_d_s, _f_d___s_e_t _*_e_x_c_e_p_t_f_d_s, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _*_t_i_m_e_o_u_t, _c_o_n_s_t _s_i_g_s_e_t___t _*_m_a_s_k); FFDD__SSEETT(_f_d, _&_f_d_s_e_t); FFDD__CCLLRR(_f_d, _&_f_d_s_e_t); FFDD__IISSSSEETT(_f_d, _&_f_d_s_e_t); FFDD__ZZEERROO(_&_f_d_s_e_t); DDEESSCCRRIIPPTTIIOONN sseelleecctt() examines the I/O descriptor sets whose addresses are passed in _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and _e_x_c_e_p_t_f_d_s to see if some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. The first _n_f_d_s descriptors are checked in each set; i.e., the descriptors from 0 through _n_f_d_s-1 in the descriptor sets are examined. On return, sseelleecctt() replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. sseelleecctt() returns the total number of ready descriptors in all the sets. The descriptor sets are stored as bit fields in arrays of integers. The following macros are provided for manipulating such descriptor sets: FFDD__ZZEERROO(_&_f_d_s_e_t) initializes a descriptor set _f_d_s_e_t to the null set. FFDD__SSEETT(_f_d, _&_f_d_s_e_t) includes a particular descriptor _f_d in _f_d_s_e_t. FFDD__CCLLRR(_f_d, _&_f_d_s_e_t) removes _f_d from _f_d_s_e_t. FFDD__IISSSSEETT(_f_d, _&_f_d_s_e_t) is non- zero if _f_d is a member of _f_d_s_e_t, zero otherwise. The behavior of these macros is undefined if a descriptor value is less than zero or greater than or equal to FD_SETSIZE, which is normally at least equal to the maximum number of descriptors supported by the system. If _t_i_m_e_o_u_t is a non-null pointer, it specifies a maximum interval to wait for the selection to complete. If _t_i_m_e_o_u_t is a null pointer, the select blocks indefinitely. To effect a poll, the _t_i_m_e_o_u_t argument should be non-null, pointing to a zero-valued timeval structure. _t_i_m_e_o_u_t is not changed by sseelleecctt(), and may be reused on subsequent calls; however, it is good style to re-initialize it before each invocation of sseelleecctt(). Any of _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, and _e_x_c_e_p_t_f_d_s may be given as null pointers if no descriptors are of interest. The ppsseelleecctt() function is similar to sseelleecctt() except that it specifies the timeout using a timespec structure. Also, if _m_a_s_k is a non-null pointer, ppsseelleecctt() atomically sets the calling thread's signal mask to the signal set pointed to by _m_a_s_k for the duration of the function call. In this case, the original signal mask will be restored before ppsseelleecctt() returns. RREETTUURRNN VVAALLUUEESS If successful, sseelleecctt() and ppsseelleecctt() return the number of ready descriptors that are contained in the descriptor sets. If a descriptor is included in multiple descriptor sets, each inclusion is counted separately. If the time limit expires before any descriptors become ready, they return 0. Otherwise, if sseelleecctt() or ppsseelleecctt() return with an error, including one due to an interrupted call, they return -1, and the descriptor sets will be unmodified. EERRRROORRSS An error return from sseelleecctt() or ppsseelleecctt() indicates: [EFAULT] One or more of _r_e_a_d_f_d_s, _w_r_i_t_e_f_d_s, or _e_x_c_e_p_t_f_d_s points outside the process's allocated address space. [EBADF] One of the descriptor sets specified an invalid descriptor. [EINTR] A signal was delivered before the time limit expired and before any of the selected descriptors became ready. [EINVAL] The specified time limit is invalid. One of its components is negative or too large. SSEEEE AALLSSOO accept(2), clock_gettime(2), connect(2), gettimeofday(2), poll(2), read(2), recv(2), send(2), write(2), getdtablesize(3) HHIISSTTOORRYY The sseelleecctt() system call first appeared in 4.1cBSD. The ppsseelleecctt() system call has been available since OpenBSD 5.4. BBUUGGSS Although the provision of getdtablesize(3) was intended to allow user programs to be written independent of the kernel limit on the number of open files, the dimension of a sufficiently large bit field for select remains a problem. The default bit size of _f_d___s_e_t is based on the symbol FD_SETSIZE (currently 1024), but that is somewhat smaller than the current kernel limit to the number of open files. However, in order to accommodate programs which might potentially use a larger number of open files with select, it is possible to increase this size within a program by providing a larger definition of FD_SETSIZE before the inclusion of any headers. The kernel will cope, and the userland libraries provided with the system are also ready for large numbers of file descriptors. Alternatively, to be really safe, it is possible to allocate _f_d___s_e_t bit- arrays dynamically. The idea is to permit a program to work properly even if it is execve(2)'d with 4000 file descriptors pre-allocated. The following illustrates the technique which is used by userland libraries: fd_set *fdsr; int max = fd; fdsr = calloc(howmany(max+1, NFDBITS), sizeof(fd_mask)); if (fdsr == NULL) { ... return (-1); } FD_SET(fd, fdsr); n = select(max+1, fdsr, NULL, NULL, &tv); ... free(fdsr); Alternatively, it is possible to use the poll(2) interface. poll(2) is more efficient when the size of sseelleecctt()'s _f_d___s_e_t bit-arrays are very large, and for fixed numbers of file descriptors one need not size and dynamically allocate a memory object. sseelleecctt() should probably have been designed to return the time remaining from the original timeout, if any, by modifying the time value in place. Even though some systems stupidly act in this different way, it is unlikely this semantic will ever be commonly implemented, as the change causes massive source code compatibility problems. Furthermore, recent new standards have dictated the current behaviour. In general, due to the existence of those brain-damaged non-conforming systems, it is unwise to assume that the timeout value will be unmodified by the sseelleecctt() call, and the caller should reinitialize it on each invocation. Calculating the delta is easily done by calling gettimeofday(2) before and after the call to sseelleecctt(), and using ttiimmeerrssuubb() (as described in getitimer(2)). Internally to the kernel, sseelleecctt() and ppsseelleecctt() work poorly if multiple processes wait on the same file descriptor. Given that, it is rather surprising to see that many daemons are written that way. NNAAMMEE sseemmccttll - semaphore control operations SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseemmccttll(_i_n_t _s_e_m_i_d, _i_n_t _s_e_m_n_u_m, _i_n_t _c_m_d, _u_n_i_o_n _s_e_m_u_n _a_r_g); DDEESSCCRRIIPPTTIIOONN The sseemmccttll() system call provides a number of control operations on the semaphore specified by _s_e_m_n_u_m and _s_e_m_i_d. The operation to be performed is specified in _c_m_d (see below). _a_r_g is a union of the following fields: int val; /* value for SETVAL */ struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */ u_short *array; /* array for GETALL & SETALL */ The semid_ds structure used in the IPC_SET and IPC_STAT commands is defined as follows in <_s_y_s_/_s_e_m_._h>: struct semid_ds { struct ipc_perm sem_perm; /* operation permissions */ struct sem *sem_base; /* semaphore set */ u_short sem_nsems; /* number of sems in set */ time_t sem_otime; /* last operation time */ time_t sem_ctime; /* last change time */ }; The ipc_perm structure used inside the semid_ds structure is defined in <_s_y_s_/_i_p_c_._h> and looks like this: struct ipc_perm { uid_t cuid; /* creator user id */ gid_t cgid; /* creator group id */ uid_t uid; /* user id */ gid_t gid; /* group id */ mode_t mode; /* r/w permission (see chmod(2)) */ u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ key_t key; /* user specified msg/sem/shm key */ }; sseemmccttll() provides the following operations: GETVAL Return the value of the semaphore. SETVAL Set the value of the semaphore to _a_r_g_._v_a_l. GETPID Return the pid of the last process that did an operation on this semaphore. GETNCNT Return the number of processes waiting to acquire the semaphore. GETZCNT Return the number of processes waiting for the value of the semaphore to reach 0. GETALL Return the values for all the semaphores associated with _s_e_m_i_d. SETALL Set the values for all the semaphores that are associated with the semaphore identifier _s_e_m_i_d to the corresponding values in _a_r_g_._a_r_r_a_y. IPC_STAT Gather statistics about a semaphore and place the information in the semid_ds structure pointed to by _a_r_g_._b_u_f (see above). IPC_SET Set the value of the _s_e_m___p_e_r_m_._u_i_d, _s_e_m___p_e_r_m_._g_i_d and _s_e_m___p_e_r_m_._m_o_d_e fields in the structure associated with the semaphore. The values are taken from the corresponding fields in the structure pointed to by _a_r_g_._b_u_f. This operation can only be executed by the superuser, or a process that has an effective user ID equal to either _s_e_m___p_e_r_m_._c_u_i_d or _s_e_m___p_e_r_m_._u_i_d in the data structure associated with the message queue. IPC_RMID Remove the semaphores associated with _s_e_m_i_d from the system and destroy the data structures associated with it. Only the superuser or a process with an effective UID equal to the _s_e_m___p_e_r_m_._c_u_i_d or _s_e_m___p_e_r_m_._u_i_d values in the data structure associated with the semaphore can do this. The permission to read or change a message queue (see semop(2)) is determined by the _s_e_m___p_e_r_m_._m_o_d_e field in the same way as is done with files (see chmod(2)), but the effective UID can match either the _s_e_m___p_e_r_m_._c_u_i_d field or the _s_e_m___p_e_r_m_._u_i_d field, and the effective GID can match either _s_e_m___p_e_r_m_._c_g_i_d or _s_e_m___p_e_r_m_._g_i_d. RREETTUURRNN VVAALLUUEESS For the GETVAL, GETPID, GETNCNT, and GETZCNT operations, sseemmccttll() returns one of the values described above if successful. All other operations will make sseemmccttll() return 0 if no errors occur. Otherwise -1 is returned and _e_r_r_n_o set to reflect the error. EERRRROORRSS sseemmccttll() will fail if: [EPERM] _c_m_d is equal to IPC_SET or IPC_RMID and the caller is not the superuser, nor does the effective UID match either the _s_e_m___p_e_r_m_._u_i_d or _s_e_m___p_e_r_m_._c_u_i_d fields of the data structure associated with the message queue. [EACCES] The caller has no operation permission for this semaphore. [EINVAL] _s_e_m_i_d is not a valid message semaphore identifier. _c_m_d is not a valid command. [EFAULT] _a_r_g_._b_u_f or _a_r_g_._a_r_r_a_y specify an invalid address. [ERANGE] _c_m_d is equal to SETVAL or SETALL and _a_r_g_._v_a_l or the values in _a_r_g_._a_r_r_a_y are greater than the system- imposed limit. SSEEEE AALLSSOO semget(2), semop(2) NNAAMMEE sseemmggeett - get semaphore set SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseemmggeett(_k_e_y___t _k_e_y, _i_n_t _n_s_e_m_s, _i_n_t _s_e_m_f_l_g); DDEESSCCRRIIPPTTIIOONN The sseemmggeett() system call returns the semaphore identifier associated with _k_e_y. A new set containing _n_s_e_m_s semaphores is created if either _k_e_y is equal to IPC_PRIVATE, or _k_e_y does not have a semaphore set associated with it and the IPC_CREAT bit is set in _s_e_m_f_l_g. The access modes of the created semaphores is specified in _s_e_m_f_l_g as a bitwise OR of zero or more of the following values: SEM_A alter permission for owner SEM_R read permission for owner SEM_A >> 3 alter permission for group SEM_R >> 3 read permission for group SEM_A >> 6 alter permission for other SEM_R >> 6 read permission for other If a new set of semaphores is created, the data structure associated with it (the _s_e_m_i_d___d_s structure, see semctl(2)) is initialized as follows: ++oo _s_e_m___p_e_r_m_._c_u_i_d and _s_e_m___p_e_r_m_._u_i_d are set to the effective UID of the calling process. ++oo _s_e_m___p_e_r_m_._g_i_d and _s_e_m___p_e_r_m_._c_g_i_d are set to the effective GID of the calling process. ++oo _s_e_m___p_e_r_m_._m_o_d_e is set to the lower 9 bits of _s_e_m_f_l_g. ++oo _s_e_m___n_s_e_m_s is set to the value of _n_s_e_m_s. ++oo _s_e_m___c_t_i_m_e is set to the current time. ++oo _s_e_m___o_t_i_m_e is set to 0. RREETTUURRNN VVAALLUUEESS sseemmggeett() returns a non-negative semaphore identifier if successful. Otherwise, -1 is returned and _e_r_r_n_o is set to reflect the error. EERRRROORRSS [EACCES] The caller has no permission to access a semaphore set already associated with _k_e_y. [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _s_e_m_f_l_g, and a semaphore set is already associated with _k_e_y. [EINVAL] _n_s_e_m_s is less than or equal to 0 or greater than the system limit for the number in a semaphore set. A semaphore set associated with _k_e_y exists, but has fewer semaphores than the number specified in _n_s_e_m_s. [ENOSPC] A new set of semaphores could not be created because the system limit for the number of semaphores or the number of semaphore sets has been reached. [ENOENT] IPC_CREAT was not set in _s_e_m_f_l_g and no semaphore set associated with _k_e_y was found. SSEEEE AALLSSOO semctl(2), semop(2), ftok(3) NNAAMMEE sseemmoopp - semaphore operations SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseemmoopp(_i_n_t _s_e_m_i_d, _s_t_r_u_c_t _s_e_m_b_u_f _*_s_o_p_s, _s_i_z_e___t _n_s_o_p_s); DDEESSCCRRIIPPTTIIOONN sseemmoopp() provides a number of atomic operations on a set of semaphores. The semaphore set is specified by _s_e_m_i_d. _s_o_p_s is an array of semaphore operations, _n_s_o_p_s is the number of operations in this array. The _s_e_m_b_u_f structures in the array contain the following members: u_short sem_num; /* semaphore # */ short sem_op; /* semaphore operation */ short sem_flg; /* operation flags */ Each operation (specified in _s_e_m___o_p) is applied to semaphore number _s_e_m___n_u_m in the set of semaphores specified by _s_e_m_i_d. The value of _s_e_m___o_p determines the action taken in the following way: ++oo _s_e_m___o_p is less than 0. The current process is blocked until the value of the semaphore is greater than or equal to the absolute value of _s_e_m___o_p. The absolute value of _s_e_m___o_p is then subtracted from the value of the semaphore, and the calling process continues. Negative values of _s_e_m___o_p are thus used to enter critical regions. ++oo _s_e_m___o_p is greater than 0. Its value is added to the value of the specified semaphore. This is used to leave critical regions. ++oo _s_e_m___o_p is equal to 0. The calling process is blocked until the value of the specified semaphore reaches 0. The behavior of each operation is influenced by the flags set in _s_e_m___f_l_g in the following way: IPC_NOWAIT In the case where the calling process would normally block, waiting for a semaphore to reach a certain value, IPC_NOWAIT makes the call return immediately, returning a value of -1 and setting _e_r_r_n_o to EAGAIN. SEM_UNDO Keep track of the changes that this call makes to the value of a semaphore, so that they can be undone when the calling process terminates. This is useful to prevent other processes waiting on a semaphore to block forever, should the process that has the semaphore locked terminate in a critical section. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sseemmoopp() will fail if: [EINVAL] There is no semaphore associated with _s_e_m_i_d. [EIDRM] The semaphore set was removed while the process was waiting for one of its semaphores to reach a certain value. [EACCES] The calling process has no permission to access the specified semaphore set. [E2BIG] The value of _n_s_o_p_s is too big. The maximum is specified in MAX_SOPS in <_s_y_s_/_s_e_m_._h>. [EFBIG] _s_e_m___n_u_m in one of the sem_buf structures is less than 0, or greater than the actual number of semaphores in the set specified by _s_e_m_i_d. [ENOSPC] SEM_UNDO was requested, and there is not enough space left in the kernel to store the undo information. [EAGAIN] The requested operation can not immediately be performed, and IPC_NOWAIT was set in _s_e_m___f_l_g. [EFAULT] _s_o_p_s points to an illegal address. SSEEEE AALLSSOO semctl(2), semget(2) NNAAMMEE sseenndd, sseennddttoo, sseennddmmssgg - send a message from a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t sseenndd(_i_n_t _s, _c_o_n_s_t _v_o_i_d _*_m_s_g, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s); _s_s_i_z_e___t sseennddttoo(_i_n_t _s, _c_o_n_s_t _v_o_i_d _*_m_s_g, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s, _c_o_n_s_t _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_t_o, _s_o_c_k_l_e_n___t _t_o_l_e_n); _s_s_i_z_e___t sseennddmmssgg(_i_n_t _s, _c_o_n_s_t _s_t_r_u_c_t _m_s_g_h_d_r _*_m_s_g, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN sseenndd(), sseennddttoo(), and sseennddmmssgg() are used to transmit a message to another socket. sseenndd() may be used only when the socket is in a _c_o_n_n_e_c_t_e_d state, while sseennddttoo() and sseennddmmssgg() may be used at any time. The address of the target is given by _t_o with _t_o_l_e_n specifying its size. The length of the message is given by _l_e_n. If the message is too long to pass atomically through the underlying protocol, the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a sseenndd(). Locally detected errors are indicated by a return value of -1. If no messages space is available at the socket to hold the message to be transmitted, then sseenndd() normally blocks, unless the socket has been placed in non-blocking I/O mode. The select(2) or poll(2) system calls may be used to determine when it is possible to send more data. The _f_l_a_g_s parameter may include one or more of the following: MSG_DONTROUTE bypass routing tables, silently ignored MSG_DONTWAIT don't block MSG_EOR terminate the record (SOCK_SEQPACKET only) MSG_NOSIGNAL don't send SIGPIPE MSG_OOB process out-of-band data The flag MSG_OOB is used to send ``out-of-band'' data on sockets that support this notion (e.g., SOCK_STREAM); the underlying protocol must also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not to send the SIGPIPE signal if an attempt to send is made on a socket that is shut down for writing or no longer connected. See recv(2) for a description of the _m_s_g_h_d_r structure. RREETTUURRNN VVAALLUUEESS The call returns the number of characters sent, or -1 if an error occurred. EERRRROORRSS sseenndd(), sseennddttoo(), and sseennddmmssgg() fail if: [EBADF] An invalid descriptor was specified. [ENOTSOCK] The argument _s is not a socket. [EFAULT] An invalid user space address was specified for a parameter. [EMSGSIZE] The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT flag is set and the requested operation would block. [ENOBUFS] The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. [ENOBUFS] The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. [EACCES] The SO_BROADCAST option is not set on the socket, and a broadcast address was given as the destination. [EHOSTUNREACH] The destination address specified an unreachable host. [EINVAL] The _f_l_a_g_s parameter is invalid. [EHOSTDOWN] The destination address specified a host that is down. [ENETDOWN] The destination address specified a network that is down. [ECONNREFUSED] The destination host rejected the message (or a previous one). This error can only be returned by connected sockets. [ENOPROTOOPT] There was a problem sending the message. This error can only be returned by connected sockets. [EDESTADDRREQ] The socket is not connected, and no destination address was specified. [EPIPE] The socket is shut down for writing or not longer connected and the MSG_NOSIGNAL flag is set. In addition, sseenndd() and sseennddttoo() may return the following error: [EINVAL] _l_e_n was larger than SSIZE_MAX. sseennddttoo() and sseennddmmssgg() may return the following errors: [EAFNOSUPPORT] Addresses in the specified address family cannot be used with this socket. [EISCONN] The socket is already connected, and a destination address was specified. sseennddmmssgg() may return the following errors: [EINVAL] The sum of the _i_o_v___l_e_n values in the _m_s_g___i_o_v array overflowed an _s_s_i_z_e___t. [EMSGSIZE] The _m_s_g___i_o_v_l_e_n member of _m_s_g was less than 0 or larger than IOV_MAX. [EMFILE] The message contains control information utilizing CMSG_DATA(3) to pass file descriptors, but too many file descriptors are already in-flight. SSEEEE AALLSSOO fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), write(2), CMSG_DATA(3) SSTTAANNDDAARRDDSS The sseenndd(), sseennddttoo(), and sseennddmmssgg() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are extensions to that specification. HHIISSTTOORRYY The sseenndd() function call appeared in 4.2BSD. NNAAMMEE sseenndd, sseennddttoo, sseennddmmssgg - send a message from a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t sseenndd(_i_n_t _s, _c_o_n_s_t _v_o_i_d _*_m_s_g, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s); _s_s_i_z_e___t sseennddttoo(_i_n_t _s, _c_o_n_s_t _v_o_i_d _*_m_s_g, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s, _c_o_n_s_t _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_t_o, _s_o_c_k_l_e_n___t _t_o_l_e_n); _s_s_i_z_e___t sseennddmmssgg(_i_n_t _s, _c_o_n_s_t _s_t_r_u_c_t _m_s_g_h_d_r _*_m_s_g, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN sseenndd(), sseennddttoo(), and sseennddmmssgg() are used to transmit a message to another socket. sseenndd() may be used only when the socket is in a _c_o_n_n_e_c_t_e_d state, while sseennddttoo() and sseennddmmssgg() may be used at any time. The address of the target is given by _t_o with _t_o_l_e_n specifying its size. The length of the message is given by _l_e_n. If the message is too long to pass atomically through the underlying protocol, the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a sseenndd(). Locally detected errors are indicated by a return value of -1. If no messages space is available at the socket to hold the message to be transmitted, then sseenndd() normally blocks, unless the socket has been placed in non-blocking I/O mode. The select(2) or poll(2) system calls may be used to determine when it is possible to send more data. The _f_l_a_g_s parameter may include one or more of the following: MSG_DONTROUTE bypass routing tables, silently ignored MSG_DONTWAIT don't block MSG_EOR terminate the record (SOCK_SEQPACKET only) MSG_NOSIGNAL don't send SIGPIPE MSG_OOB process out-of-band data The flag MSG_OOB is used to send ``out-of-band'' data on sockets that support this notion (e.g., SOCK_STREAM); the underlying protocol must also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not to send the SIGPIPE signal if an attempt to send is made on a socket that is shut down for writing or no longer connected. See recv(2) for a description of the _m_s_g_h_d_r structure. RREETTUURRNN VVAALLUUEESS The call returns the number of characters sent, or -1 if an error occurred. EERRRROORRSS sseenndd(), sseennddttoo(), and sseennddmmssgg() fail if: [EBADF] An invalid descriptor was specified. [ENOTSOCK] The argument _s is not a socket. [EFAULT] An invalid user space address was specified for a parameter. [EMSGSIZE] The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT flag is set and the requested operation would block. [ENOBUFS] The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. [ENOBUFS] The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. [EACCES] The SO_BROADCAST option is not set on the socket, and a broadcast address was given as the destination. [EHOSTUNREACH] The destination address specified an unreachable host. [EINVAL] The _f_l_a_g_s parameter is invalid. [EHOSTDOWN] The destination address specified a host that is down. [ENETDOWN] The destination address specified a network that is down. [ECONNREFUSED] The destination host rejected the message (or a previous one). This error can only be returned by connected sockets. [ENOPROTOOPT] There was a problem sending the message. This error can only be returned by connected sockets. [EDESTADDRREQ] The socket is not connected, and no destination address was specified. [EPIPE] The socket is shut down for writing or not longer connected and the MSG_NOSIGNAL flag is set. In addition, sseenndd() and sseennddttoo() may return the following error: [EINVAL] _l_e_n was larger than SSIZE_MAX. sseennddttoo() and sseennddmmssgg() may return the following errors: [EAFNOSUPPORT] Addresses in the specified address family cannot be used with this socket. [EISCONN] The socket is already connected, and a destination address was specified. sseennddmmssgg() may return the following errors: [EINVAL] The sum of the _i_o_v___l_e_n values in the _m_s_g___i_o_v array overflowed an _s_s_i_z_e___t. [EMSGSIZE] The _m_s_g___i_o_v_l_e_n member of _m_s_g was less than 0 or larger than IOV_MAX. [EMFILE] The message contains control information utilizing CMSG_DATA(3) to pass file descriptors, but too many file descriptors are already in-flight. SSEEEE AALLSSOO fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), write(2), CMSG_DATA(3) SSTTAANNDDAARRDDSS The sseenndd(), sseennddttoo(), and sseennddmmssgg() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are extensions to that specification. HHIISSTTOORRYY The sseenndd() function call appeared in 4.2BSD. NNAAMMEE sseennddssyysslloogg - send a message to syslogd SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseennddssyysslloogg(_c_o_n_s_t _v_o_i_d _*_m_s_g, _s_i_z_e___t _l_e_n); DDEESSCCRRIIPPTTIIOONN sseennddssyysslloogg() is used to transmit a syslog(3) formatted message direct to syslogd(8) without requiring the allocation of a socket. This is used internally by syslog_r(3), so that messages can be sent during difficult situations. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sseennddssyysslloogg() can fail if: [ENOTCONN] The message cannot be sent, likely because syslogd(8) is not running. SSEEEE AALLSSOO syslog_r(3), syslogd(8) HHIISSTTOORRYY The sseennddssyysslloogg() function call appeared in OpenBSD 5.6. NNAAMMEE sseenndd, sseennddttoo, sseennddmmssgg - send a message from a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t sseenndd(_i_n_t _s, _c_o_n_s_t _v_o_i_d _*_m_s_g, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s); _s_s_i_z_e___t sseennddttoo(_i_n_t _s, _c_o_n_s_t _v_o_i_d _*_m_s_g, _s_i_z_e___t _l_e_n, _i_n_t _f_l_a_g_s, _c_o_n_s_t _s_t_r_u_c_t _s_o_c_k_a_d_d_r _*_t_o, _s_o_c_k_l_e_n___t _t_o_l_e_n); _s_s_i_z_e___t sseennddmmssgg(_i_n_t _s, _c_o_n_s_t _s_t_r_u_c_t _m_s_g_h_d_r _*_m_s_g, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN sseenndd(), sseennddttoo(), and sseennddmmssgg() are used to transmit a message to another socket. sseenndd() may be used only when the socket is in a _c_o_n_n_e_c_t_e_d state, while sseennddttoo() and sseennddmmssgg() may be used at any time. The address of the target is given by _t_o with _t_o_l_e_n specifying its size. The length of the message is given by _l_e_n. If the message is too long to pass atomically through the underlying protocol, the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a sseenndd(). Locally detected errors are indicated by a return value of -1. If no messages space is available at the socket to hold the message to be transmitted, then sseenndd() normally blocks, unless the socket has been placed in non-blocking I/O mode. The select(2) or poll(2) system calls may be used to determine when it is possible to send more data. The _f_l_a_g_s parameter may include one or more of the following: MSG_DONTROUTE bypass routing tables, silently ignored MSG_DONTWAIT don't block MSG_EOR terminate the record (SOCK_SEQPACKET only) MSG_NOSIGNAL don't send SIGPIPE MSG_OOB process out-of-band data The flag MSG_OOB is used to send ``out-of-band'' data on sockets that support this notion (e.g., SOCK_STREAM); the underlying protocol must also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not to send the SIGPIPE signal if an attempt to send is made on a socket that is shut down for writing or no longer connected. See recv(2) for a description of the _m_s_g_h_d_r structure. RREETTUURRNN VVAALLUUEESS The call returns the number of characters sent, or -1 if an error occurred. EERRRROORRSS sseenndd(), sseennddttoo(), and sseennddmmssgg() fail if: [EBADF] An invalid descriptor was specified. [ENOTSOCK] The argument _s is not a socket. [EFAULT] An invalid user space address was specified for a parameter. [EMSGSIZE] The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT flag is set and the requested operation would block. [ENOBUFS] The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. [ENOBUFS] The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. [EACCES] The SO_BROADCAST option is not set on the socket, and a broadcast address was given as the destination. [EHOSTUNREACH] The destination address specified an unreachable host. [EINVAL] The _f_l_a_g_s parameter is invalid. [EHOSTDOWN] The destination address specified a host that is down. [ENETDOWN] The destination address specified a network that is down. [ECONNREFUSED] The destination host rejected the message (or a previous one). This error can only be returned by connected sockets. [ENOPROTOOPT] There was a problem sending the message. This error can only be returned by connected sockets. [EDESTADDRREQ] The socket is not connected, and no destination address was specified. [EPIPE] The socket is shut down for writing or not longer connected and the MSG_NOSIGNAL flag is set. In addition, sseenndd() and sseennddttoo() may return the following error: [EINVAL] _l_e_n was larger than SSIZE_MAX. sseennddttoo() and sseennddmmssgg() may return the following errors: [EAFNOSUPPORT] Addresses in the specified address family cannot be used with this socket. [EISCONN] The socket is already connected, and a destination address was specified. sseennddmmssgg() may return the following errors: [EINVAL] The sum of the _i_o_v___l_e_n values in the _m_s_g___i_o_v array overflowed an _s_s_i_z_e___t. [EMSGSIZE] The _m_s_g___i_o_v_l_e_n member of _m_s_g was less than 0 or larger than IOV_MAX. [EMFILE] The message contains control information utilizing CMSG_DATA(3) to pass file descriptors, but too many file descriptors are already in-flight. SSEEEE AALLSSOO fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), write(2), CMSG_DATA(3) SSTTAANNDDAARRDDSS The sseenndd(), sseennddttoo(), and sseennddmmssgg() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are extensions to that specification. HHIISSTTOORRYY The sseenndd() function call appeared in 4.2BSD. NNAAMMEE sseettuuiidd, sseetteeuuiidd, sseettggiidd, sseetteeggiidd - set user and group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseettuuiidd(_u_i_d___t _u_i_d); _i_n_t sseetteeuuiidd(_u_i_d___t _e_u_i_d); _i_n_t sseettggiidd(_g_i_d___t _g_i_d); _i_n_t sseetteeggiidd(_g_i_d___t _e_g_i_d); DDEESSCCRRIIPPTTIIOONN The sseettuuiidd() function sets the real and effective user IDs and the saved set-user-ID of the current process to the specified value. The sseettuuiidd() function is permitted if the effective user ID is that of the superuser, or if the specified user ID is the same as the effective user ID. If not, but the specified user ID is the same as the real user ID, sseettuuiidd() will set the effective user ID to the real user ID. The sseettggiidd() function sets the real and effective group IDs and the saved set-group-ID of the current process to the specified value. The sseettggiidd() function is permitted if the effective user ID is that of the superuser, or if the specified group ID is the same as the effective group ID. If not, but the specified group ID is the same as the real group ID, sseettggiidd() will set the effective group ID to the real group ID. Supplementary group IDs remain unchanged. The sseetteeuuiidd() function (sseetteeggiidd()) sets the effective user ID (group ID) of the current process. The effective user ID may be set to the value of the real user ID or the saved set-user-ID (see intro(2) and execve(2)); in this way, the effective user ID of a set-user-ID executable may be toggled by switching to the real user ID, then re-enabled by reverting to the set-user-ID value. Similarly, the effective group ID may be set to the value of the real group ID or the saved set-group-ID. RREETTUURRNN VVAALLUUEESS The sseettuuiidd(), sseetteeuuiidd(), sseettggiidd(), and sseetteeggiidd() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sseettuuiidd() and sseetteeuuiidd() will succeed unless: [EPERM] The user is not the superuser and the requested _u_i_d or _e_u_i_d is not the process's real, effective, or saved UID. sseettggiidd() and sseetteeggiidd() will succeed unless: [EPERM] The user is not the superuser and the requested _g_i_d or _e_g_i_d is not the process's real, effective, or saved GID. SSEEEE AALLSSOO getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), setresgid(2), setresuid(2), setreuid(2) SSTTAANNDDAARRDDSS The sseettuuiidd(), sseetteeuuiidd(), sseettggiidd(), and sseetteeggiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The sseettuuiidd() system call first appeared in Version 1 AT&T UNIX; sseettggiidd() in Version 4 AT&T UNIX; and sseetteeuuiidd() and sseetteeggiidd() in 4.2BSD. NNAAMMEE sseettuuiidd, sseetteeuuiidd, sseettggiidd, sseetteeggiidd - set user and group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseettuuiidd(_u_i_d___t _u_i_d); _i_n_t sseetteeuuiidd(_u_i_d___t _e_u_i_d); _i_n_t sseettggiidd(_g_i_d___t _g_i_d); _i_n_t sseetteeggiidd(_g_i_d___t _e_g_i_d); DDEESSCCRRIIPPTTIIOONN The sseettuuiidd() function sets the real and effective user IDs and the saved set-user-ID of the current process to the specified value. The sseettuuiidd() function is permitted if the effective user ID is that of the superuser, or if the specified user ID is the same as the effective user ID. If not, but the specified user ID is the same as the real user ID, sseettuuiidd() will set the effective user ID to the real user ID. The sseettggiidd() function sets the real and effective group IDs and the saved set-group-ID of the current process to the specified value. The sseettggiidd() function is permitted if the effective user ID is that of the superuser, or if the specified group ID is the same as the effective group ID. If not, but the specified group ID is the same as the real group ID, sseettggiidd() will set the effective group ID to the real group ID. Supplementary group IDs remain unchanged. The sseetteeuuiidd() function (sseetteeggiidd()) sets the effective user ID (group ID) of the current process. The effective user ID may be set to the value of the real user ID or the saved set-user-ID (see intro(2) and execve(2)); in this way, the effective user ID of a set-user-ID executable may be toggled by switching to the real user ID, then re-enabled by reverting to the set-user-ID value. Similarly, the effective group ID may be set to the value of the real group ID or the saved set-group-ID. RREETTUURRNN VVAALLUUEESS The sseettuuiidd(), sseetteeuuiidd(), sseettggiidd(), and sseetteeggiidd() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sseettuuiidd() and sseetteeuuiidd() will succeed unless: [EPERM] The user is not the superuser and the requested _u_i_d or _e_u_i_d is not the process's real, effective, or saved UID. sseettggiidd() and sseetteeggiidd() will succeed unless: [EPERM] The user is not the superuser and the requested _g_i_d or _e_g_i_d is not the process's real, effective, or saved GID. SSEEEE AALLSSOO getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), setresgid(2), setresuid(2), setreuid(2) SSTTAANNDDAARRDDSS The sseettuuiidd(), sseetteeuuiidd(), sseettggiidd(), and sseetteeggiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The sseettuuiidd() system call first appeared in Version 1 AT&T UNIX; sseettggiidd() in Version 4 AT&T UNIX; and sseetteeuuiidd() and sseetteeggiidd() in 4.2BSD. NNAAMMEE sseettuuiidd, sseetteeuuiidd, sseettggiidd, sseetteeggiidd - set user and group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseettuuiidd(_u_i_d___t _u_i_d); _i_n_t sseetteeuuiidd(_u_i_d___t _e_u_i_d); _i_n_t sseettggiidd(_g_i_d___t _g_i_d); _i_n_t sseetteeggiidd(_g_i_d___t _e_g_i_d); DDEESSCCRRIIPPTTIIOONN The sseettuuiidd() function sets the real and effective user IDs and the saved set-user-ID of the current process to the specified value. The sseettuuiidd() function is permitted if the effective user ID is that of the superuser, or if the specified user ID is the same as the effective user ID. If not, but the specified user ID is the same as the real user ID, sseettuuiidd() will set the effective user ID to the real user ID. The sseettggiidd() function sets the real and effective group IDs and the saved set-group-ID of the current process to the specified value. The sseettggiidd() function is permitted if the effective user ID is that of the superuser, or if the specified group ID is the same as the effective group ID. If not, but the specified group ID is the same as the real group ID, sseettggiidd() will set the effective group ID to the real group ID. Supplementary group IDs remain unchanged. The sseetteeuuiidd() function (sseetteeggiidd()) sets the effective user ID (group ID) of the current process. The effective user ID may be set to the value of the real user ID or the saved set-user-ID (see intro(2) and execve(2)); in this way, the effective user ID of a set-user-ID executable may be toggled by switching to the real user ID, then re-enabled by reverting to the set-user-ID value. Similarly, the effective group ID may be set to the value of the real group ID or the saved set-group-ID. RREETTUURRNN VVAALLUUEESS The sseettuuiidd(), sseetteeuuiidd(), sseettggiidd(), and sseetteeggiidd() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sseettuuiidd() and sseetteeuuiidd() will succeed unless: [EPERM] The user is not the superuser and the requested _u_i_d or _e_u_i_d is not the process's real, effective, or saved UID. sseettggiidd() and sseetteeggiidd() will succeed unless: [EPERM] The user is not the superuser and the requested _g_i_d or _e_g_i_d is not the process's real, effective, or saved GID. SSEEEE AALLSSOO getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), setresgid(2), setresuid(2), setreuid(2) SSTTAANNDDAARRDDSS The sseettuuiidd(), sseetteeuuiidd(), sseettggiidd(), and sseetteeggiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The sseettuuiidd() system call first appeared in Version 1 AT&T UNIX; sseettggiidd() in Version 4 AT&T UNIX; and sseetteeuuiidd() and sseetteeggiidd() in 4.2BSD. NNAAMMEE sseettggrroouuppss - set group access list SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t sseettggrroouuppss(_i_n_t _n_g_r_o_u_p_s, _c_o_n_s_t _g_i_d___t _*_g_i_d_s_e_t); DDEESSCCRRIIPPTTIIOONN sseettggrroouuppss() sets the group access list of the current user process according to the array _g_i_d_s_e_t. The parameter _n_g_r_o_u_p_s indicates the number of entries in the array and must be no more than {NGROUPS_MAX}. Only the superuser may set new groups. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The sseettggrroouuppss() call will fail if: [EINVAL] The value of _n_g_r_o_u_p_s is greater than {NGROUPS_MAX}. [EPERM] The caller is not the superuser. [EFAULT] The address specified for _g_i_d_s_e_t is outside the process address space. SSEEEE AALLSSOO getgroups(2), setgid(2), setregid(2), initgroups(3) HHIISSTTOORRYY The sseettggrroouuppss() system call first appeared in 4.1cBSD. NNAAMMEE ggeettiittiimmeerr, sseettiittiimmeerr - get/set value of interval timer SSYYNNOOPPSSIISS ##iinncclluuddee <> ##ddeeffiinnee IITTIIMMEERR__RREEAALL 00 ##ddeeffiinnee IITTIIMMEERR__VVIIRRTTUUAALL 11 ##ddeeffiinnee IITTIIMMEERR__PPRROOFF 22 _i_n_t ggeettiittiimmeerr(_i_n_t _w_h_i_c_h, _s_t_r_u_c_t _i_t_i_m_e_r_v_a_l _*_v_a_l_u_e); _i_n_t sseettiittiimmeerr(_i_n_t _w_h_i_c_h, _c_o_n_s_t _s_t_r_u_c_t _i_t_i_m_e_r_v_a_l _*_v_a_l_u_e, _s_t_r_u_c_t _i_t_i_m_e_r_v_a_l _*_o_v_a_l_u_e); _v_o_i_d ttiimmeerrcclleeaarr(_s_t_r_u_c_t _t_i_m_e_v_a_l _*); _i_n_t ttiimmeerriisssseett(_s_t_r_u_c_t _t_i_m_e_v_a_l _*); _i_n_t ttiimmeerrccmmpp(_s_t_r_u_c_t _t_i_m_e_v_a_l _*_a, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_b, _C_M_P); _v_o_i_d ttiimmeerrssuubb(_s_t_r_u_c_t _t_i_m_e_v_a_l _*_a, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_b, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_r_e_s); _v_o_i_d ttiimmeerraadddd(_s_t_r_u_c_t _t_i_m_e_v_a_l _*_a, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_b, _s_t_r_u_c_t _t_i_m_e_v_a_l _*_r_e_s); DDEESSCCRRIIPPTTIIOONN The system provides each process with three interval timers, defined in <_s_y_s_/_t_i_m_e_._h>. The ggeettiittiimmeerr() call returns the current value for the timer specified in _w_h_i_c_h in the structure at _v_a_l_u_e. The sseettiittiimmeerr() call sets a timer to the specified _v_a_l_u_e (returning the previous value of the timer if _o_v_a_l_u_e is non-null). A timer value is defined by the _i_t_i_m_e_r_v_a_l structure: struct itimerval { struct timeval it_interval; /* timer interval */ struct timeval it_value; /* current value */ }; If _i_t___v_a_l_u_e is non-zero, it indicates the time to the next timer expiration. If _i_t___i_n_t_e_r_v_a_l is non-zero, it specifies a value to be used in reloading _i_t___v_a_l_u_e when the timer expires. Setting _i_t___v_a_l_u_e to 0 disables a timer. Setting _i_t___i_n_t_e_r_v_a_l to 0 causes a timer to be disabled after its next expiration (assuming _i_t___v_a_l_u_e is non-zero). Time values smaller than the resolution of the system clock are rounded up to this resolution (typically 10 milliseconds). The ITIMER_REAL timer decrements in real time. A SIGALRM signal is delivered when this timer expires. The ITIMER_VIRTUAL timer decrements in process virtual time. It runs only when the process is executing. A SIGVTALRM signal is delivered when it expires. The ITIMER_PROF timer decrements both in process virtual time and when the system is running on behalf of the process. It is designed to be used by interpreters in statistically profiling the execution of interpreted programs. Each time the ITIMER_PROF timer expires, the SIGPROF signal is delivered. Because this signal may interrupt in- progress system calls, programs using this timer must be prepared to restart interrupted system calls. The remaining five functions are in fact macros for manipulating time values, defined in <_s_y_s_/_t_i_m_e_._h>. ttiimmeerrcclleeaarr(_a) sets the time value in _a to zero. ttiimmeerriisssseett(_a) tests if the time value in _a is non-zero. ttiimmeerrccmmpp(_a, _b, _C_M_P) compares two time values in the form _a CMP _b, where _C_M_P is <, <=, ==, !=, >=, or > . ttiimmeerrssuubb(_a, _b, _r_e_s) subtracts _a - _b and stores the result in _r_e_s. ttiimmeerraadddd(_a, _b, _r_e_s) adds two timers and stores the result in _r_e_s. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettiittiimmeerr() and sseettiittiimmeerr() will fail if: [EFAULT] The _v_a_l_u_e parameter specified a bad address. [EINVAL] An unrecognized value for _w_h_i_c_h was specified. In addition, sseettiittiimmeerr() may return the following error: [EINVAL] _v_a_l_u_e or _o_v_a_l_u_e specified a time that was too large to be handled. SSEEEE AALLSSOO clock_gettime(2), gettimeofday(2), poll(2), select(2), sigaction(2) SSTTAANNDDAARRDDSS The ggeettiittiimmeerr() and sseettiittiimmeerr() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettiittiimmeerr() and sseettiittiimmeerr() system calls first appeared in 4.1cBSD. NNAAMMEE ggeettllooggiinn, ggeettllooggiinn__rr, sseettllooggiinn - get/set login name SSYYNNOOPPSSIISS ##iinncclluuddee <> _c_h_a_r _* ggeettllooggiinn(_v_o_i_d); _i_n_t ggeettllooggiinn__rr(_c_h_a_r _*_n_a_m_e, _s_i_z_e___t _n_a_m_e_l_e_n); _i_n_t sseettllooggiinn(_c_o_n_s_t _c_h_a_r _*_n_a_m_e); DDEESSCCRRIIPPTTIIOONN The ggeettllooggiinn() routine returns the login name of the user associated with the current session, as previously set by sseettllooggiinn(). The name is normally associated with a login shell at the time a session is created, and is inherited by all processes descended from the login shell. (This is true even if some of those processes assume another user ID, for example when su(1) is used.) The ggeettllooggiinn__rr() routine is a reentrant version of ggeettllooggiinn(). It is functionally identical to ggeettllooggiinn() except that the caller must provide a buffer, _n_a_m_e, in which to store the user's login name and a corresponding length parameter, _n_a_m_e_l_e_n, that specifies the size of the buffer. The buffer should be large enough to store the login name and a trailing NUL (typically LOGIN_NAME_MAX bytes). sseettllooggiinn() sets the login name of the user associated with the current session to _n_a_m_e. This call is restricted to the superuser, and is normally used only when a new session is being created on behalf of the named user (for example, at login time, or when a remote shell is invoked). _N_O_T_E: There is only one login name per session. It is _C_R_I_T_I_C_A_L_L_Y important to ensure that sseettllooggiinn() is only ever called after the process has taken adequate steps to ensure that it is detached from its parent's session. The _O_N_L_Y way to do this is via the sseettssiidd() function. The ddaaeemmoonn() function calls sseettssiidd() which is an ideal way of detaching from a controlling terminal and forking into the background. In particular, neither iiooccttll(_t_t_y_f_d, _T_I_O_C_N_O_T_T_Y, _._._.) nor sseettppggrrpp(_._._.) is sufficient to create a new session. Once a parent process has called sseettssiidd(), it is acceptable for some child of that process to then call sseettllooggiinn(), even though it is not the session leader. Beware, however, that _A_L_L processes in the session will change their login name at the same time, even the parent. This is different from traditional UNIX privilege inheritance and as such can be counter-intuitive. Since the sseettllooggiinn() routine is restricted to the super-user, it is assumed that (like all other privileged programs) the programmer has taken adequate precautions to prevent security violations. RREETTUURRNN VVAALLUUEESS If a call to ggeettllooggiinn() succeeds, it returns a pointer to a NUL- terminated string in a static buffer. If the name has not been set, it returns NULL. If a call to ggeettllooggiinn__rr() succeeds, a value of 0 is returned, else the error number is returned. If a call to sseettllooggiinn() succeeds, a value of 0 is returned. If sseettllooggiinn() fails, a value of -1 is returned and an error code is placed in the global location _e_r_r_n_o. EERRRROORRSS ggeettllooggiinn__rr() and sseettllooggiinn() will succeed unless: [EFAULT] The _n_a_m_e parameter points to an invalid address. In addition, ggeettllooggiinn__rr() may return the following error: [ERANGE] The value of _n_a_m_e_l_e_n is not large enough to store the user's login name and a trailing NUL. sseettllooggiinn() may return the following errors: [EINVAL] The _n_a_m_e parameter pointed to a string that was too long. Login names are limited to LOGIN_NAME_MAX-1 characters, currently 31. [EPERM] The caller tried to set the login name and was not the superuser. SSEEEE AALLSSOO setsid(2) SSTTAANNDDAARRDDSS The ggeettllooggiinn() and ggeettllooggiinn__rr() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettllooggiinn() function first appeared in 4.2BSD. BBUUGGSS In earlier versions of the system, ggeettllooggiinn() failed unless the process was associated with a login terminal. The current implementation (using sseettllooggiinn()) allows getlogin to succeed even when the process has no controlling terminal. In earlier versions of the system, the value returned by ggeettllooggiinn() could not be trusted without checking the user ID. Portable programs should probably still make this check. NNAAMMEE sseettppggiidd, sseettppggrrpp - set process group SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseettppggiidd(_p_i_d___t _p_i_d, _p_i_d___t _p_g_r_p); _i_n_t sseettppggrrpp(_p_i_d___t _p_i_d, _p_i_d___t _p_g_r_p); DDEESSCCRRIIPPTTIIOONN sseettppggiidd() sets the process group of the specified process _p_i_d to the specified _p_g_r_p. If _p_i_d is zero, then the call applies to the current process. If _p_g_r_p is zero, the process ID of the specified process is used. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sseettppggiidd() will fail and the process group will not be altered if: [EACCES] The value of the _p_i_d argument matches the process ID of a child process of the calling process, and the child process has successfully executed one of the exec functions. [EINVAL] The value of the _p_g_r_p argument is less than zero. [EPERM] The requested process is a descendant of the calling process, and is either a session leader or not in the same session as the calling process. [EPERM] The value of the _p_g_r_p argument is neither the PID of the process indicated by the _p_i_d argument nor the process group ID of an existing process group in the same session as the calling process. [ESRCH] The value of the _p_i_d argument does not match the process ID of the calling process or of a descendant of the calling process. SSEEEE AALLSSOO getpgrp(2), setsid(2) SSTTAANNDDAARRDDSS sseettppggrrpp() is identical to sseettppggiidd(), and is retained for calling convention compatibility with historical versions of BSD. The sseettppggiidd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). NNAAMMEE sseettppggiidd, sseettppggrrpp - set process group SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseettppggiidd(_p_i_d___t _p_i_d, _p_i_d___t _p_g_r_p); _i_n_t sseettppggrrpp(_p_i_d___t _p_i_d, _p_i_d___t _p_g_r_p); DDEESSCCRRIIPPTTIIOONN sseettppggiidd() sets the process group of the specified process _p_i_d to the specified _p_g_r_p. If _p_i_d is zero, then the call applies to the current process. If _p_g_r_p is zero, the process ID of the specified process is used. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sseettppggiidd() will fail and the process group will not be altered if: [EACCES] The value of the _p_i_d argument matches the process ID of a child process of the calling process, and the child process has successfully executed one of the exec functions. [EINVAL] The value of the _p_g_r_p argument is less than zero. [EPERM] The requested process is a descendant of the calling process, and is either a session leader or not in the same session as the calling process. [EPERM] The value of the _p_g_r_p argument is neither the PID of the process indicated by the _p_i_d argument nor the process group ID of an existing process group in the same session as the calling process. [ESRCH] The value of the _p_i_d argument does not match the process ID of the calling process or of a descendant of the calling process. SSEEEE AALLSSOO getpgrp(2), setsid(2) SSTTAANNDDAARRDDSS sseettppggrrpp() is identical to sseettppggiidd(), and is retained for calling convention compatibility with historical versions of BSD. The sseettppggiidd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). NNAAMMEE ggeettpprriioorriittyy, sseettpprriioorriittyy - get/set process scheduling priority SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettpprriioorriittyy(_i_n_t _w_h_i_c_h, _i_d___t _w_h_o); _i_n_t sseettpprriioorriittyy(_i_n_t _w_h_i_c_h, _i_d___t _w_h_o, _i_n_t _p_r_i_o); DDEESSCCRRIIPPTTIIOONN The scheduling priority of the process, process group, or user, as indicated by _w_h_i_c_h and _w_h_o is obtained with the ggeettpprriioorriittyy() call and set with the sseettpprriioorriittyy() call. _w_h_i_c_h is one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, and _w_h_o is interpreted relative to _w_h_i_c_h (a process identifier for PRIO_PROCESS, process group identifier for PRIO_PGRP, and a user ID for PRIO_USER). A zero value of _w_h_o denotes the current process, process group, or user. _p_r_i_o is a value in the range -20 to 20. The default priority is 0; lower priorities cause more favorable scheduling. The ggeettpprriioorriittyy() call returns the highest priority (lowest numerical value) enjoyed by any of the specified processes. The sseettpprriioorriittyy() call sets the priorities of all of the specified processes to the specified value. Priority values outside the range -20 to 20 are truncated to the appropriate limit. Only the superuser may lower priorities. RREETTUURRNN VVAALLUUEESS Since ggeettpprriioorriittyy() can legitimately return the value -1, it is necessary to clear the external variable _e_r_r_n_o prior to the call, then check it afterward to determine if a -1 is an error or a legitimate value. The sseettpprriioorriittyy() call returns 0 if there is no error, or -1 if there is. EERRRROORRSS ggeettpprriioorriittyy() and sseettpprriioorriittyy() will fail if: [ESRCH] No process was located using the _w_h_i_c_h and _w_h_o values specified. [EINVAL] _w_h_i_c_h was not one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER. In addition, sseettpprriioorriittyy() will fail if: [EPERM] A process was located, but neither its effective nor real user ID matched the effective user ID of the caller. [EACCES] A non-superuser attempted to lower a process priority. SSEEEE AALLSSOO nice(1), fork(2), renice(8) SSTTAANNDDAARRDDSS The ggeettpprriioorriittyy() and sseettpprriioorriittyy() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The predecessor of these functions, the former nniiccee() system call, appeared in Version 3 AT&T UNIX and was removed in 4.3BSD-Reno. The ggeettpprriioorriittyy() and sseettpprriioorriittyy() system calls appeared in 4.1cBSD. NNAAMMEE sseettrreeggiidd - set real and effective group IDs SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseettrreeggiidd(_g_i_d___t _r_g_i_d, _g_i_d___t _e_g_i_d); DDEESSCCRRIIPPTTIIOONN The real and effective group IDs of the current process are set according to the arguments. The saved group ID will be set to the new value of the real group ID if a real group ID is specified and either the new real group ID value is different from the current value or the new value of the effective group ID differs from the current saved group ID. Unprivileged users may change either group ID to the current value of the real, effective, or saved group ID. Only the superuser may make other changes. Supplying a value of -1 for either the real or effective group ID forces the system to substitute the current ID in place of the -1 parameter. The sseettrreeggiidd() function was intended to allow swapping the real and effective group IDs in set-group-ID programs to temporarily relinquish the set-group-ID value. This purpose is now better served by the use of the setegid(2) function. When setting the real and effective group IDs to the same value, the setgid(2) function is preferred. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [EPERM] The current process is not the superuser and a change other than changing the effective group ID to the real group ID was specified. SSEEEE AALLSSOO getgid(2), setegid(2), setgid(2), setresgid(2), setreuid(2) SSTTAANNDDAARRDDSS The sseettrreeggiidd() function conforms to the IEEE Std 1003.1-2008 (``POSIX.1'') specification, except that the conditions for changing the saved group ID differ and that, if it is changed, the saved group ID is set to the real group ID instead of the effective group ID. HHIISSTTOORRYY The sseettrreeggiidd() system call first appeared in 4.1cBSD, predating POSIX. A semantically different version appeared in 4.4BSD. The current version, with the original semantics restored, appeared in OpenBSD 3.3. NNAAMMEE ggeettrreessggiidd, ggeettrreessuuiidd, sseettrreessggiidd, sseettrreessuuiidd - get or set real, effective and saved user or group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ggeettrreessggiidd(_g_i_d___t _*_r_g_i_d, _g_i_d___t _*_e_g_i_d, _g_i_d___t _*_s_g_i_d); _i_n_t ggeettrreessuuiidd(_u_i_d___t _*_r_u_i_d, _u_i_d___t _*_e_u_i_d, _u_i_d___t _*_s_u_i_d); _i_n_t sseettrreessggiidd(_g_i_d___t _r_g_i_d, _g_i_d___t _e_g_i_d, _g_i_d___t _s_g_i_d); _i_n_t sseettrreessuuiidd(_u_i_d___t _r_u_i_d, _u_i_d___t _e_u_i_d, _u_i_d___t _s_u_i_d); DDEESSCCRRIIPPTTIIOONN The sseettrreessuuiidd() function sets the real, effective and saved user IDs of the current process. The analogous sseettrreessggiidd() sets the real, effective and saved group IDs. Privileged processes may set these IDs to arbitrary values. Unprivileged processes are restricted in that each of the new IDs must match one of the current IDs. Passing -1 as an argument causes the corresponding value to remain unchanged. The ggeettrreessggiidd() and ggeettrreessuuiidd() calls retrieve the real, effective, and saved group and user IDs of the current process, respectively. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [EPERM] The calling process was not privileged and tried to change one or more IDs to a value which was not the current real ID, the current effective ID nor the current saved ID. [EFAULT] An address passed to ggeettrreessggiidd() or ggeettrreessuuiidd() was invalid. SSEEEE AALLSSOO getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), setregid(2), setreuid(2), setuid(2) SSTTAANNDDAARRDDSS These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') specification. While they are not completely portable, they are the least ambiguous way to manage user and group IDs. HHIISSTTOORRYY These functions first appeared in HP-UX. NNAAMMEE ggeettrreessggiidd, ggeettrreessuuiidd, sseettrreessggiidd, sseettrreessuuiidd - get or set real, effective and saved user or group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ggeettrreessggiidd(_g_i_d___t _*_r_g_i_d, _g_i_d___t _*_e_g_i_d, _g_i_d___t _*_s_g_i_d); _i_n_t ggeettrreessuuiidd(_u_i_d___t _*_r_u_i_d, _u_i_d___t _*_e_u_i_d, _u_i_d___t _*_s_u_i_d); _i_n_t sseettrreessggiidd(_g_i_d___t _r_g_i_d, _g_i_d___t _e_g_i_d, _g_i_d___t _s_g_i_d); _i_n_t sseettrreessuuiidd(_u_i_d___t _r_u_i_d, _u_i_d___t _e_u_i_d, _u_i_d___t _s_u_i_d); DDEESSCCRRIIPPTTIIOONN The sseettrreessuuiidd() function sets the real, effective and saved user IDs of the current process. The analogous sseettrreessggiidd() sets the real, effective and saved group IDs. Privileged processes may set these IDs to arbitrary values. Unprivileged processes are restricted in that each of the new IDs must match one of the current IDs. Passing -1 as an argument causes the corresponding value to remain unchanged. The ggeettrreessggiidd() and ggeettrreessuuiidd() calls retrieve the real, effective, and saved group and user IDs of the current process, respectively. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [EPERM] The calling process was not privileged and tried to change one or more IDs to a value which was not the current real ID, the current effective ID nor the current saved ID. [EFAULT] An address passed to ggeettrreessggiidd() or ggeettrreessuuiidd() was invalid. SSEEEE AALLSSOO getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), setregid(2), setreuid(2), setuid(2) SSTTAANNDDAARRDDSS These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') specification. While they are not completely portable, they are the least ambiguous way to manage user and group IDs. HHIISSTTOORRYY These functions first appeared in HP-UX. NNAAMMEE sseettrreeuuiidd - set real and effective user IDs SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseettrreeuuiidd(_u_i_d___t _r_u_i_d, _u_i_d___t _e_u_i_d); DDEESSCCRRIIPPTTIIOONN The real and effective user IDs of the current process are set according to the arguments. The saved user ID will be set to the new value of the real user ID if a real user ID is specified and either the new real user ID value is different from the current value or the new value of the effective user ID differs from the current saved user ID. Unprivileged users may change either user ID to the current value of the real, effective, or saved user ID. Only the superuser may make other changes. Supplying a value of -1 for either the real or effective user ID forces the system to substitute the current ID in place of the -1 parameter. The sseettrreeuuiidd() function was intended to allow swapping the real and effective user IDs in set-user-ID programs to temporarily relinquish the set-user-ID value. This purpose is now better served by the use of the seteuid(2) function. When setting the real and effective user IDs to the same value, the setuid(2) function is preferred. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [EPERM] The current process is not the superuser and a change other than changing the effective user ID to the real user ID was specified. SSEEEE AALLSSOO getuid(2), seteuid(2), setregid(2), setresuid(2), setuid(2) SSTTAANNDDAARRDDSS The sseettrreeuuiidd() function conforms to the IEEE Std 1003.1-2008 (``POSIX.1'') specification, except that the conditions for changing the saved user ID differ and that, if it is changed, the saved user ID is set to the real user ID instead of the effective user ID. HHIISSTTOORRYY The sseettrreeuuiidd() system call first appeared in 4.1cBSD, predating POSIX. A semantically different version appeared in 4.4BSD. The current version, with the original semantics restored, appeared in OpenBSD 3.3. NNAAMMEE ggeettrrlliimmiitt, sseettrrlliimmiitt - control maximum system resource consumption SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettrrlliimmiitt(_i_n_t _r_e_s_o_u_r_c_e, _s_t_r_u_c_t _r_l_i_m_i_t _*_r_l_p); _i_n_t sseettrrlliimmiitt(_i_n_t _r_e_s_o_u_r_c_e, _c_o_n_s_t _s_t_r_u_c_t _r_l_i_m_i_t _*_r_l_p); DDEESSCCRRIIPPTTIIOONN Limits on the consumption of system resources by the current process and each process it creates may be obtained with the ggeettrrlliimmiitt() call, and set with the sseettrrlliimmiitt() call. The _r_e_s_o_u_r_c_e parameter is one of the following: RLIMIT_CORE The largest size (in bytes) _c_o_r_e file that may be created. RLIMIT_CPU The maximum amount of CPU time (in seconds) to be used by each process. RLIMIT_DATA The maximum size (in bytes) of the data segment for a process; this includes memory allocated via malloc(3) and all other anonymous memory mapped via mmap(2). RLIMIT_FSIZE The largest size (in bytes) file that may be created. RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into memory using the mlock(2) function. RLIMIT_NOFILE The maximum number of open files for this process. RLIMIT_NPROC The maximum number of simultaneous processes for this user id. RLIMIT_RSS The maximum size (in bytes) to which a process's resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size. RLIMIT_STACK The maximum size (in bytes) of the stack segment for a process, which defines how far a process's stack segment may be extended. Stack extension is performed automatically by the system, and is only used by the main thread of a process. A resource limit is specified as a soft limit and a hard limit. When a soft limit is exceeded a process may receive a signal (for example, if the CPU time or file size is exceeded), but it will be allowed to continue execution until it reaches the hard limit (or modifies its resource limit). The _r_l_i_m_i_t structure is used to specify the hard and soft limits on a resource, struct rlimit { rlim_t rlim_cur; /* current (soft) limit */ rlim_t rlim_max; /* hard limit */ }; Only the superuser may raise the maximum limits. Other users may only alter _r_l_i_m___c_u_r within the range from 0 to _r_l_i_m___m_a_x or (irreversibly) lower _r_l_i_m___m_a_x. An ``infinite'' value for a limit is defined as RLIM_INFINITY. A value of RLIM_SAVED_CUR or RLIM_SAVED_MAX will be stored in _r_l_i_m___c_u_r or _r_l_i_m___m_a_x respectively by ggeettrrlliimmiitt() if the value for the current or maximum resource limit cannot be stored in an rlim_t. The values RLIM_SAVED_CUR and RLIM_SAVED_MAX should not be used in a call to sseettrrlliimmiitt() unless they were returned by a previous call to ggeettrrlliimmiitt(). Because this information is stored in the per-process information, this system call must be executed directly by the shell if it is to affect all future processes created by the shell; lliimmiitt is thus a built-in command to csh(1) and uulliimmiitt is the sh(1) equivalent. The system refuses to extend the data or stack space when the limits would be exceeded in the normal way: a brk(2) call fails if the data space limit is reached. When the stack limit is reached, the process receives a segmentation fault (SIGSEGV); if this signal is not caught by a handler using the signal stack, this signal will kill the process. A file I/O operation that would create a file larger than the process' soft limit will cause the write to fail and a signal SIGXFSZ to be generated; this normally terminates the process, but may be caught. When the soft CPU time limit is exceeded, a signal SIGXCPU is sent to the offending process. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettrrlliimmiitt() and sseettrrlliimmiitt() will fail if: [EFAULT] The address specified for _r_l_p is invalid. [EINVAL] An unrecognized value for _r_e_s_o_u_r_c_e was specified. In addition, sseettrrlliimmiitt() may return the following errors: [EINVAL] The new _r_l_i_m___c_u_r is greater than the new _r_l_i_m___m_a_x. [EPERM] The new _r_l_i_m___m_a_x is greater than the current maximum limit value, and the caller is not the superuser. SSEEEE AALLSSOO csh(1), sh(1), quotactl(2), sigaction(2), sigaltstack(2), sysctl(3) SSTTAANNDDAARRDDSS The ggeettrrlliimmiitt() and sseettrrlliimmiitt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). The RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS resources are non- standard extensions. HHIISSTTOORRYY The ggeettrrlliimmiitt() and sseettrrlliimmiitt() system calls first appeared in 4.1cBSD. BBUUGGSS The RLIMIT_AS resource is missing. NNAAMMEE ggeettrrttaabbllee, sseettrrttaabbllee - get and set the default routing table of the current process SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ggeettrrttaabbllee(_v_o_i_d); _i_n_t sseettrrttaabbllee(_i_n_t _r_t_a_b_l_e_i_d); DDEESSCCRRIIPPTTIIOONN ggeettrrttaabbllee() and sseettrrttaabbllee() manipulate the routing table and routing domain associated with the current process. Only the superuser is allowed to change the process routing table if it is already set to a non-zero value. RREETTUURRNN VVAALLUUEESS ggeettrrttaabbllee() returns the routing table of the current process. Upon successful completion, sseettrrttaabbllee() returns 0 if the call succeeds, -1 if it fails. EERRRROORRSS The call succeeds unless: [EINVAL] The value of the _r_t_a_b_l_e_i_d argument is not a valid routing table. [EPERM] The user is not the superuser and the routing table of the calling process is already set to a non-zero value. SSEEEE AALLSSOO getsockopt(2), route(8) HHIISSTTOORRYY The ggeettrrttaabbllee() and sseettrrttaabbllee() system calls appeared in OpenBSD 4.8. NNAAMMEE sseettssiidd - create session and set process group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t sseettssiidd(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The sseettssiidd function creates a new session. The calling process is the session leader of the new session, is the process group leader of a new process group and has no controlling terminal. The calling process is the only process in either the session or the process group. Upon successful completion, the sseettssiidd function returns the value of the process group ID of the new process group, which is the same as the process ID of the calling process. EERRRROORRSS If an error occurs, sseettssiidd returns -1 and the global variable _e_r_r_n_o is set to indicate the error, as follows: [EPERM] The calling process is already a process group leader, or the process group ID of a process other than the calling process matches the process ID of the calling process. SSEEEE AALLSSOO getsid(2), setpgid(2), tcgetpgrp(3), tcsetpgrp(3) SSTTAANNDDAARRDDSS The sseettssiidd function is expected to be compliant with the IEEE Std 1003.1-2008 (``POSIX.1'') specification. NNAAMMEE ggeettssoocckkoopptt, sseettssoocckkoopptt - get and set options on sockets SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettssoocckkoopptt(_i_n_t _s, _i_n_t _l_e_v_e_l, _i_n_t _o_p_t_n_a_m_e, _v_o_i_d _*_o_p_t_v_a_l, _s_o_c_k_l_e_n___t _*_o_p_t_l_e_n); _i_n_t sseettssoocckkoopptt(_i_n_t _s, _i_n_t _l_e_v_e_l, _i_n_t _o_p_t_n_a_m_e, _c_o_n_s_t _v_o_i_d _*_o_p_t_v_a_l, _s_o_c_k_l_e_n___t _o_p_t_l_e_n); DDEESSCCRRIIPPTTIIOONN ggeettssoocckkoopptt() and sseettssoocckkoopptt() manipulate the _o_p_t_i_o_n_s associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost ``socket'' level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, _l_e_v_e_l is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, _l_e_v_e_l should be set to the protocol number of TCP; see getprotoent(3). The parameters _o_p_t_v_a_l and _o_p_t_l_e_n are used to access option values for sseettssoocckkoopptt(). For ggeettssoocckkoopptt() they identify a buffer in which the value for the requested option(s) are to be returned. For ggeettssoocckkoopptt(), _o_p_t_l_e_n is a value-result parameter, initially containing the size of the buffer pointed to by _o_p_t_v_a_l, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, _o_p_t_v_a_l may be NULL. _o_p_t_n_a_m_e and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file <_s_y_s_/_s_o_c_k_e_t_._h> contains definitions for socket level options, described below. Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. Most socket-level options utilize an int parameter for _o_p_t_v_a_l. For sseettssoocckkoopptt(), the parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. SO_LINGER uses a struct linger parameter, defined in <_s_y_s_/_s_o_c_k_e_t_._h>, which specifies the desired state of the option and the linger interval (see below). SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval parameter, defined in <_s_y_s_/_t_i_m_e_._h>. The following options are recognized at the socket level. Except as noted, each may be examined with ggeettssoocckkoopptt() and set with sseettssoocckkoopptt(). SO_DEBUG enables recording of debugging information SO_REUSEADDR enables local address reuse SO_REUSEPORT enables duplicate address and port bindings SO_KEEPALIVE enables keep connections alive SO_DONTROUTE enables routing bypass; not supported SO_LINGER linger on close if data present SO_BROADCAST enables permission to transmit broadcast messages SO_OOBINLINE enables reception of out-of-band data in band SO_BINDANY enables binding to any address SO_SNDBUF set buffer size for output SO_RCVBUF set buffer size for input SO_SNDLOWAT set minimum count for output SO_RCVLOWAT set minimum count for input SO_SNDTIMEO set timeout value for output SO_RCVTIMEO set timeout value for input SO_TIMESTAMP enables reception of a timestamp with datagrams SO_PEERCRED get the credentials from other side of connection SO_RTABLE set the routing table used for route lookups SO_SPLICE splice two sockets together or get data length SO_TYPE get the type of the socket (get only) SO_ERROR get and clear error on the socket (get only) SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a SIGPIPE signal when attempting to send data. SO_LINGER controls the action taken when unsent messages are queued on socket and a close(2) is performed. If the socket promises reliable delivery of data and SO_LINGER is set, the system will block the process on the close(2) attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period measured in seconds, termed the linger interval, is specified in the sseettssoocckkoopptt() call when SO_LINGER is requested). If SO_LINGER is disabled and a close(2) is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The option SO_BROADCAST requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv(2) or read(2) calls without the MSG_OOB flag. Some protocols always behave as if this option is set. SO_BINDANY allows the socket to be bound to addresses which are not local to the machine, so it can be used to make a transparent proxy. Note that this option is limited to the super-user. In order to receive packets for these addresses, SO_BINDANY needs to be combined with matching outgoing pf(4) rules with the _d_i_v_e_r_t_-_r_e_p_l_y parameter. For example, with the following rule the socket receives packets for 192.168.0.10 even if it is not a local address: pass out inet from 192.168.0.10 divert-reply SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. SO_SNDLOWAT is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A select(2) or poll(2) operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for SO_SNDLOWAT is set to a convenient size for network efficiency, often 1024. SO_RCVLOWAT is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with the smaller of the amount available or the amount requested. The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. SO_SNDTIMEO is an option to set a timeout value for output operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error EWOULDBLOCK if no data was sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error EWOULDBLOCK if no data were received. If the SO_TIMESTAMP option is enabled on a SOCK_DGRAM socket, the recvmsg(2) call will return a timestamp corresponding to when the datagram was received. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by a struct timeval. The cmsghdr fields have the following values: cmsg_len = CMSG_LEN(sizeof(struct timeval)) cmsg_level = SOL_SOCKET cmsg_type = SCM_TIMESTAMP SO_PEERCRED fetches the _s_t_r_u_c_t _s_o_c_k_p_e_e_r_c_r_e_d credentials from the other side of the connection (currently only possible on AF_UNIX sockets). These credentials are from the time that bind(2) or connect(2) were called. The SO_RTABLE option gets or sets the routing table which will be used by the socket for address lookups. If a protocol family of the socket doesn't support switching routing tables, the ENOPROTOOPT error is returned. Only the superuser is allowed to change the routing table if it is already set to a non-zero value. A socket's chosen routing table is initialized from the process's configuration, previously selected using setrtable(2). SO_SPLICE can splice together two TCP or UDP sockets for zero-copy data transfers. Both sockets must be of the same type. In the first form, sseettssoocckkoopptt() is called with the source socket _s and the drain socket's _i_n_t file descriptor as _o_p_t_v_a_l. In the second form, _o_p_t_v_a_l is a _s_t_r_u_c_t _s_p_l_i_c_e with the drain socket in _s_p___f_d, a positive maximum number of bytes or 0 in _s_p___m_a_x and an idle timeout _s_p___i_d_l_e in the form of a _s_t_r_u_c_t _t_i_m_e_v_a_l. If -1 is given as drain socket, the source socket _s gets unspliced. Otherwise the spliced data transfer continues within the kernel until the optional maximum is reached, one of the connections terminates, idle timeout expires or an error occurs. A successful select(2), poll(2), or kqueue(2) operation testing the ability to read from the source socket indicates that the splicing has terminated. The error status can be examined with SO_ERROR at the source socket. The ETIMEDOUT error is set if there was no data transferred between two sockets during the _s_p___i_d_l_e period of time. The EFBIG error is set after exactly _s_p___m_a_x bytes have been transferred. Note that if a maximum is given, it is only guaranteed that no more bytes are transferred. A short splice can happen, but then a second call to splice will transfer the remaining data immediately. The SO_SPLICE option with ggeettssoocckkoopptt() and an _o_f_f___t value as _o_p_t_v_a_l can be used to retrieve the number of bytes transferred so far from the source socket _s. A successful new splice resets this number. Finally, SO_TYPE and SO_ERROR are options used only with ggeettssoocckkoopptt(). SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful for servers that inherit sockets on startup. SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The call succeeds unless: [EBADF] The argument _s is not a valid descriptor. [ENOTSOCK] The argument _s is a file, not a socket. [ENOPROTOOPT] The option is unknown at the level indicated. [EOPNOTSUPP] The option is unsupported. [EFAULT] The address pointed to by _o_p_t_v_a_l is not in a valid part of the process address space. For ggeettssoocckkoopptt(), this error may also be returned if _o_p_t_l_e_n is not in a valid part of the process address space. SSEEEE AALLSSOO connect(2), getrtable(2), ioctl(2), poll(2), select(2), socket(2), getprotoent(3), divert(4), pf.conf(5), protocols(5), sosplice(9) SSTTAANNDDAARRDDSS The ggeettssoocckkoopptt() and sseettssoocckkoopptt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ggeettssoocckkoopptt() system call appeared in 4.2BSD. BBUUGGSS Several of the socket options should be handled at lower levels of the system. NNAAMMEE ggeettttiimmeeooffddaayy, sseettttiimmeeooffddaayy - get/set date and time SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ggeettttiimmeeooffddaayy(_s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_p, _s_t_r_u_c_t _t_i_m_e_z_o_n_e _*_t_z_p); _i_n_t sseettttiimmeeooffddaayy(_c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_p, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_z_o_n_e _*_t_z_p); DDEESSCCRRIIPPTTIIOONN NNoottee:: ttiimmeezzoonnee iiss nnoo lloonnggeerr uusseedd;; tthhiiss iinnffoorrmmaattiioonn iiss kkeepptt oouuttssiiddee tthhee kkeerrnneell.. The system's notion of the current Greenwich time and the current time zone is obtained with the ggeettttiimmeeooffddaayy() call, and set with the sseettttiimmeeooffddaayy() call. The time is expressed in seconds and microseconds since midnight (0 hour), January 1, 1970. The resolution of the system clock is hardware dependent, and the time may be updated continuously or in ``ticks''. If _t_p or _t_z_p is NULL, the associated time information will not be returned or set. The structures pointed to by _t_p and _t_z_p are defined in <_s_y_s_/_t_i_m_e_._h> as: struct timeval { time_t tv_sec; /* seconds since Jan. 1, 1970 */ suseconds_t tv_usec; /* and microseconds */ }; struct timezone { int tz_minuteswest; /* of Greenwich */ int tz_dsttime; /* type of dst correction to apply */ }; The _t_i_m_e_z_o_n_e structure indicates the local time zone (measured in minutes of time westward from Greenwich), and a flag that, if nonzero, indicates that Daylight Saving time applies locally during the appropriate part of the year. Only the superuser may set the time of day or time zone. If the system securelevel is greater than 1 (see init(8)), the time may only be advanced. This limitation is imposed to prevent a malicious superuser from setting arbitrary time stamps on files. The system time can still be adjusted backwards using the adjtime(2) system call even when the system is secure. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ggeettttiimmeeooffddaayy() and sseettttiimmeeooffddaayy() will succeed unless: [EFAULT] An argument address referenced invalid memory. In addition, sseettttiimmeeooffddaayy() may return the following error: [EPERM] A user other than the superuser attempted to set the time. SSEEEE AALLSSOO date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3) SSTTAANNDDAARRDDSS The ggeettttiimmeeooffddaayy() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY As predecessors of these functions, former system calls ttiimmee() and ssttiimmee() first appeared in Version 1 AT&T UNIX, and ffttiimmee() first appeared in Version 7 AT&T UNIX. The ggeettttiimmeeooffddaayy() and sseettttiimmeeooffddaayy() system calls first appeared in 4.1cBSD. CCAAVVEEAATTSS Setting the time with sseettttiimmeeooffddaayy() is dangerous; if possible use adjtime(2) instead. Many daemon programming techniques utilize time- delta techniques using the results from ggeettttiimmeeooffddaayy() instead of from clock_gettime(2) on the CLOCK_MONOTONIC clock. Time jumps can cause these programs to malfunction in unexpected ways. If the time must be set, consider rebooting the machine for safety. NNAAMMEE sseettuuiidd, sseetteeuuiidd, sseettggiidd, sseetteeggiidd - set user and group ID SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sseettuuiidd(_u_i_d___t _u_i_d); _i_n_t sseetteeuuiidd(_u_i_d___t _e_u_i_d); _i_n_t sseettggiidd(_g_i_d___t _g_i_d); _i_n_t sseetteeggiidd(_g_i_d___t _e_g_i_d); DDEESSCCRRIIPPTTIIOONN The sseettuuiidd() function sets the real and effective user IDs and the saved set-user-ID of the current process to the specified value. The sseettuuiidd() function is permitted if the effective user ID is that of the superuser, or if the specified user ID is the same as the effective user ID. If not, but the specified user ID is the same as the real user ID, sseettuuiidd() will set the effective user ID to the real user ID. The sseettggiidd() function sets the real and effective group IDs and the saved set-group-ID of the current process to the specified value. The sseettggiidd() function is permitted if the effective user ID is that of the superuser, or if the specified group ID is the same as the effective group ID. If not, but the specified group ID is the same as the real group ID, sseettggiidd() will set the effective group ID to the real group ID. Supplementary group IDs remain unchanged. The sseetteeuuiidd() function (sseetteeggiidd()) sets the effective user ID (group ID) of the current process. The effective user ID may be set to the value of the real user ID or the saved set-user-ID (see intro(2) and execve(2)); in this way, the effective user ID of a set-user-ID executable may be toggled by switching to the real user ID, then re-enabled by reverting to the set-user-ID value. Similarly, the effective group ID may be set to the value of the real group ID or the saved set-group-ID. RREETTUURRNN VVAALLUUEESS The sseettuuiidd(), sseetteeuuiidd(), sseettggiidd(), and sseetteeggiidd() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sseettuuiidd() and sseetteeuuiidd() will succeed unless: [EPERM] The user is not the superuser and the requested _u_i_d or _e_u_i_d is not the process's real, effective, or saved UID. sseettggiidd() and sseetteeggiidd() will succeed unless: [EPERM] The user is not the superuser and the requested _g_i_d or _e_g_i_d is not the process's real, effective, or saved GID. SSEEEE AALLSSOO getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), setresgid(2), setresuid(2), setreuid(2) SSTTAANNDDAARRDDSS The sseettuuiidd(), sseetteeuuiidd(), sseettggiidd(), and sseetteeggiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The sseettuuiidd() system call first appeared in Version 1 AT&T UNIX; sseettggiidd() in Version 4 AT&T UNIX; and sseetteeuuiidd() and sseetteeggiidd() in 4.2BSD. NNAAMMEE sshhmmaatt, sshhmmddtt - map/unmap shared memory SSYYNNOOPPSSIISS ##iinncclluuddee <> _v_o_i_d _* sshhmmaatt(_i_n_t _s_h_m_i_d, _c_o_n_s_t _v_o_i_d _*_s_h_m_a_d_d_r, _i_n_t _s_h_m_f_l_g); _i_n_t sshhmmddtt(_c_o_n_s_t _v_o_i_d _*_s_h_m_a_d_d_r); DDEESSCCRRIIPPTTIIOONN sshhmmaatt() maps the shared memory segment associated with the shared memory identifier _s_h_m_i_d into the address space of the calling process. The address at which the segment is mapped is determined by the _s_h_m_a_d_d_r parameter. If it is equal to 0, the system will pick an address itself. Otherwise, an attempt is made to map the shared memory segment at the address _s_h_m_a_d_d_r specifies. If SHM_RND is set in _s_h_m_f_l_g, the system will round the address down to a multiple of SHMLBA bytes (SHMLBA is defined in <_s_y_s_/_s_h_m_._h>). A shared memory segment can be mapped read-only by specifying the SHM_RDONLY flag in _s_h_m_f_l_g. sshhmmddtt() unmaps the shared memory segment that is currently mapped at _s_h_m_a_d_d_r from the calling process' address space. _s_h_m_a_d_d_r must be a value returned by a prior sshhmmaatt() call. A shared memory segment will remain existent until it is removed by a call to shmctl(2) with the IPC_RMID command. RREETTUURRNN VVAALLUUEESS sshhmmaatt() returns the address at which the shared memory segment has been mapped into the calling process' address space when successful, sshhmmddtt() returns 0 on successful completion. Otherwise, a value of -1 is returned, and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sshhmmaatt() will fail if: [EACCES] The calling process has no permission to access this shared memory segment. [ENOMEM] There is not enough available data space for the calling process to map the shared memory segment. [EINVAL] _s_h_m_i_d is not a valid shared memory identifier. _s_h_m_a_d_d_r specifies an illegal address. [EMFILE] The number of shared memory segments has reached the system-wide limit. sshhmmddtt() will fail if: [EINVAL] _s_h_m_a_d_d_r is not the start address of a mapped shared memory segment. SSEEEE AALLSSOO ipcrm(1), ipcs(1), mmap(2), shmctl(2), shmget(2) NNAAMMEE sshhmmccttll - shared memory control operations SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sshhmmccttll(_i_n_t _s_h_m_i_d, _i_n_t _c_m_d, _s_t_r_u_c_t _s_h_m_i_d___d_s _*_b_u_f); DDEESSCCRRIIPPTTIIOONN The sshhmmccttll() system call performs some control operations on the shared memory area specified by _s_h_m_i_d. Each shared memory segment has a data structure associated with it, parts of which may be altered by sshhmmccttll() and parts of which determine the actions of sshhmmccttll(). This structure is defined as follows in <_s_y_s_/_s_h_m_._h>: struct shmid_ds { struct ipc_perm shm_perm; /* operation permissions */ int shm_segsz; /* size of segment in bytes */ pid_t shm_lpid; /* pid of last shm op */ pid_t shm_cpid; /* pid of creator */ short shm_nattch; /* # of current attaches */ time_t shm_atime; /* last shmat() time*/ time_t shm_dtime; /* last shmdt() time */ time_t shm_ctime; /* last change by shmctl() */ void *shm_internal; /* sysv stupidity */ }; The ipc_perm structure used inside the shmid_ds structure is defined in <_s_y_s_/_i_p_c_._h> and looks like this: struct ipc_perm { uid_t cuid; /* creator user id */ gid_t cgid; /* creator group id */ uid_t uid; /* user id */ gid_t gid; /* group id */ mode_t mode; /* r/w permission (see chmod(2)) */ u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ key_t key; /* user specified msg/sem/shm key */ }; The operation to be performed by sshhmmccttll() is specified in _c_m_d and is one of: IPC_STAT Gather information about the shared memory segment and place it in the structure pointed to by _b_u_f. IPC_SET Set the value of the _s_h_m___p_e_r_m_._u_i_d, _s_h_m___p_e_r_m_._g_i_d and _s_h_m___p_e_r_m_._m_o_d_e fields in the structure associated with _s_h_m_i_d. The values are taken from the corresponding fields in the structure pointed to by _b_u_f. This operation can only be executed by the superuser, or a process that has an effective user ID equal to either _s_h_m___p_e_r_m_._c_u_i_d or _s_h_m___p_e_r_m_._u_i_d in the data structure associated with the shared memory segment. IPC_RMID Mark the shared memory segment specified by _s_h_m_i_d for removal when it is no longer in use by any process. When it is removed, all data associated with it will be destroyed too. Only the superuser or a process with an effective UID equal to the _s_h_m___p_e_r_m_._c_u_i_d or _s_h_m___p_e_r_m_._u_i_d values in the data structure associated with the queue can do this. The read and write permissions on a shared memory identifier are determined by the _s_h_m___p_e_r_m_._m_o_d_e field in the same way as is done with files (see chmod(2)), but the effective UID can match either the _s_h_m___p_e_r_m_._c_u_i_d field or the _s_h_m___p_e_r_m_._u_i_d field, and the effective GID can match either _s_h_m___p_e_r_m_._c_g_i_d or _s_h_m___p_e_r_m_._g_i_d. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sshhmmccttll() will fail if: [EPERM] _c_m_d is equal to IPC_SET or IPC_RMID and the caller is not the superuser, nor does the effective UID match either the _s_h_m___p_e_r_m_._u_i_d or _s_h_m___p_e_r_m_._c_u_i_d fields of the data structure associated with the shared memory segment. An attempt is made to increase the value of _s_h_m___q_b_y_t_e_s through IPC_SET but the caller is not the superuser. [EACCES] The command is IPC_STAT and the caller has no read permission for this shared memory segment. [EINVAL] _s_h_m_i_d is not a valid shared memory segment identifier. _c_m_d is not a valid command. [EFAULT] _b_u_f specifies an invalid address. SSEEEE AALLSSOO shmat(2), shmget(2) SSTTAANNDDAARRDDSS Segments which are marked for removal (but not yet removed since they are still in use) can be attached to by new callers using shmat(2). This is permitted as an extension beyond the standards. NNAAMMEE sshhmmaatt, sshhmmddtt - map/unmap shared memory SSYYNNOOPPSSIISS ##iinncclluuddee <> _v_o_i_d _* sshhmmaatt(_i_n_t _s_h_m_i_d, _c_o_n_s_t _v_o_i_d _*_s_h_m_a_d_d_r, _i_n_t _s_h_m_f_l_g); _i_n_t sshhmmddtt(_c_o_n_s_t _v_o_i_d _*_s_h_m_a_d_d_r); DDEESSCCRRIIPPTTIIOONN sshhmmaatt() maps the shared memory segment associated with the shared memory identifier _s_h_m_i_d into the address space of the calling process. The address at which the segment is mapped is determined by the _s_h_m_a_d_d_r parameter. If it is equal to 0, the system will pick an address itself. Otherwise, an attempt is made to map the shared memory segment at the address _s_h_m_a_d_d_r specifies. If SHM_RND is set in _s_h_m_f_l_g, the system will round the address down to a multiple of SHMLBA bytes (SHMLBA is defined in <_s_y_s_/_s_h_m_._h>). A shared memory segment can be mapped read-only by specifying the SHM_RDONLY flag in _s_h_m_f_l_g. sshhmmddtt() unmaps the shared memory segment that is currently mapped at _s_h_m_a_d_d_r from the calling process' address space. _s_h_m_a_d_d_r must be a value returned by a prior sshhmmaatt() call. A shared memory segment will remain existent until it is removed by a call to shmctl(2) with the IPC_RMID command. RREETTUURRNN VVAALLUUEESS sshhmmaatt() returns the address at which the shared memory segment has been mapped into the calling process' address space when successful, sshhmmddtt() returns 0 on successful completion. Otherwise, a value of -1 is returned, and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS sshhmmaatt() will fail if: [EACCES] The calling process has no permission to access this shared memory segment. [ENOMEM] There is not enough available data space for the calling process to map the shared memory segment. [EINVAL] _s_h_m_i_d is not a valid shared memory identifier. _s_h_m_a_d_d_r specifies an illegal address. [EMFILE] The number of shared memory segments has reached the system-wide limit. sshhmmddtt() will fail if: [EINVAL] _s_h_m_a_d_d_r is not the start address of a mapped shared memory segment. SSEEEE AALLSSOO ipcrm(1), ipcs(1), mmap(2), shmctl(2), shmget(2) NNAAMMEE sshhmmggeett - get shared memory area identifier SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sshhmmggeett(_k_e_y___t _k_e_y, _s_i_z_e___t _s_i_z_e, _i_n_t _s_h_m_f_l_g); DDEESSCCRRIIPPTTIIOONN sshhmmggeett() returns the shared memory identifier associated with the key _k_e_y. A shared memory segment is created if either _k_e_y is equal to IPC_PRIVATE, or _k_e_y does not have a shared memory segment identifier associated with it, and the IPC_CREAT bit is set in _s_h_m_f_l_g. If a new shared memory segment is created, the data structure associated with it (the _s_h_m_i_d___d_s structure, see shmctl(2)) is initialized as follows: ++oo _s_h_m___p_e_r_m_._c_u_i_d and _s_h_m___p_e_r_m_._u_i_d are set to the effective uid of the calling process. ++oo _s_h_m___p_e_r_m_._g_i_d and _s_h_m___p_e_r_m_._c_g_i_d are set to the effective gid of the calling process. ++oo _s_h_m___p_e_r_m_._m_o_d_e is set to the lower 9 bits of _s_h_m_f_l_g. ++oo _s_h_m___l_p_i_d, _s_h_m___n_a_t_t_c_h, _s_h_m___a_t_i_m_e, and _s_h_m___d_t_i_m_e are set to 0. ++oo _s_h_m___c_t_i_m_e is set to the current time. ++oo _s_h_m___s_e_g_s_z is set to the value of _s_i_z_e. RREETTUURRNN VVAALLUUEESS Upon successful completion a positive shared memory segment identifier is returned. Otherwise, -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [EACCES] A shared memory segment is already associated with _k_e_y and the caller has no permission to access it. [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _s_h_m_f_l_g, and a shared memory segment is already associated with _k_e_y. [EINVAL] A shared memory segment is already associated with _k_e_y and its _s_i_z_e is less than the requested size. [ENOSPC] A new shared memory identifier could not be created because the system limit for the number of shared memory identifiers has been reached. [ENOENT] IPC_CREAT was not set in _s_h_m_f_l_g and no shared memory segment associated with _k_e_y was found. [ENOMEM] There is not enough memory left to create a shared memory segment of the requested size. SSEEEE AALLSSOO ipcrm(1), ipcs(1), mmap(2), shmat(2), shmctl(2), ftok(3) NNAAMMEE sshhuuttddoowwnn - disable sends or receives on a socket SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t sshhuuttddoowwnn(_i_n_t _s, _i_n_t _h_o_w); DDEESSCCRRIIPPTTIIOONN The sshhuuttddoowwnn() system call disables sends or receives on a socket. If the file descriptor _s is associated with a SOCK_STREAM socket, all or part of the full-duplex connection will be shut down. The _h_o_w argument specifies the type of shutdown. Possible values are: SHUT_RD Further receives will be disallowed. SHUT_WR Further sends will be disallowed. This may cause actions specific to the protocol family of the socket _s to happen. SHUT_RDWR Further sends and receives will be disallowed. The following protocol specific actions apply to the use of SHUT_WR based on the properties of the socket associated with the file descriptor _s: DOMAIN TYPE PROTOCOL RETURN VALUE AND ACTION AF_INET SOCK_DGRAM IPPROTO_UDP Return 0. ICMP messages will _n_o_t be generated. AF_INET SOCK_STREAM IPPROTO_TCP Return 0. Send queued data, wait for ACK, then send FIN. AF_INET6 SOCK_DGRAM IPPROTO_UDP Return 0. ICMP messages will _n_o_t be generated. AF_INET6 SOCK_STREAM IPPROTO_TCP Return 0. Send queued data, wait for ACK, then send FIN. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The sshhuuttddoowwnn() system call fails if: [EBADF] The _s argument is not a valid file descriptor. [EINVAL] The _h_o_w argument is invalid. [ENOTCONN] The _s argument specifies a SOCK_STREAM socket which is not connected. [ENOTSOCK] The _s argument does not refer to a socket. [EOPNOTSUPP] The socket associated with the file descriptor _s does not support this operation. SSEEEE AALLSSOO connect(2), socket(2), inet(4), inet6(4) SSTTAANNDDAARRDDSS The sshhuuttddoowwnn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The sshhuuttddoowwnn() system call first appeared in 4.1cBSD. The SHUT_RD, SHUT_WR, and SHUT_RDWR constants appeared in IEEE Std 1003.1g-2000 (``POSIX.1g''). BBUUGGSS The ICMP ``port unreachable'' message should be generated in response to datagrams received on a local port to which _s is bound after sshhuuttddoowwnn() is called. NNAAMMEE ssiiggaaccttiioonn - software signal facilities SSYYNNOOPPSSIISS ##iinncclluuddee <> struct sigaction { union { /* signal handler */ void (*__sa_handler)(int); void (*__sa_sigaction)(int, siginfo_t *, void *); } __sigaction_u; sigset_t sa_mask; /* signal mask to apply */ int sa_flags; /* see signal options below */ }; ##ddeeffiinnee ssaa__hhaannddlleerr ____ssiiggaaccttiioonn__uu..____ssaa__hhaannddlleerr ##ddeeffiinnee ssaa__ssiiggaaccttiioonn ____ssiiggaaccttiioonn__uu..____ssaa__ssiiggaaccttiioonn _i_n_t ssiiggaaccttiioonn(_i_n_t _s_i_g, _c_o_n_s_t _s_t_r_u_c_t _s_i_g_a_c_t_i_o_n _*_a_c_t, _s_t_r_u_c_t _s_i_g_a_c_t_i_o_n _*_o_a_c_t); DDEESSCCRRIIPPTTIIOONN The system defines a set of signals that may be delivered to a process. Signal delivery resembles the occurrence of a hardware interrupt: the signal is normally blocked from further occurrence, the current process context is saved, and a new one is built. A process may specify a _h_a_n_d_l_e_r to which a signal is delivered, or specify that a signal is to be _i_g_n_o_r_e_d. A process may also specify that a default action is to be taken by the system when a signal occurs. A signal may also be _b_l_o_c_k_e_d, in which case its delivery is postponed until it is _u_n_b_l_o_c_k_e_d. The action to be taken on delivery is determined at the time of delivery. Normally, signal handlers execute on the current stack of the process. This may be changed, on a per-handler basis, so that signals are taken on a special _s_i_g_n_a_l _s_t_a_c_k. Signal routines normally execute with the signal that caused their invocation _b_l_o_c_k_e_d, but other signals may yet occur. A global _s_i_g_n_a_l _m_a_s_k defines the set of signals currently blocked from delivery to a process. The signal mask for a process is initialized from that of its parent (normally empty). It may be changed with a sigprocmask(2) call, or when a signal is delivered to the process. When a signal condition arises for a process, the signal is added to a set of signals pending for the process. If the signal is not currently _b_l_o_c_k_e_d by the process then it is delivered to the process. Signals may be delivered any time a process enters the operating system (e.g., during a system call, page fault or trap, or clock interrupt). If multiple signals are ready to be delivered at the same time, any signals that could be caused by traps are delivered first. Additional signals may be processed at the same time, with each appearing to interrupt the handlers for the previous signals before their first instructions. The set of pending signals is returned by the sigpending(2) function. When a caught signal is delivered, the current state of the process is saved, a new signal mask is calculated (as described below), and the signal handler is invoked. The call to the handler is arranged so that if the signal handling routine returns normally the process will resume execution in the context from before the signal's delivery. If the process wishes to resume in a different context, then it must arrange to restore the previous context itself. When a signal is delivered to a process a new signal mask is installed for the duration of the process' signal handler (or until a sigprocmask(2) call is made). This mask is formed by taking the union of the current signal mask set, the signal to be delivered, and the signal mask _s_a___m_a_s_k associated with the handler to be invoked, but always excluding SIGKILL and SIGSTOP. ssiiggaaccttiioonn() assigns an action for a signal specified by _s_i_g. If _a_c_t is non-zero, it specifies an action (SIG_DFL, SIG_IGN, or a handler routine) and mask to be used when delivering the specified signal. If _o_a_c_t is non-zero, the previous handling information for the signal is returned to the user. Once a signal handler is installed, it normally remains installed until another ssiiggaaccttiioonn() call is made, or an execve(2) is performed. The value of _s_a___h_a_n_d_l_e_r (or, if the SA_SIGINFO flag is set, the value of _s_a___s_i_g_a_c_t_i_o_n instead) indicates what action should be performed when a signal arrives. A signal-specific default action may be reset by setting _s_a___h_a_n_d_l_e_r to SIG_DFL. Alternately, if the SA_RESETHAND flag is set the default action will be reinstated when the signal is first posted. The defaults are process termination, possibly with core dump; no action; stopping the process; or continuing the process. See the signal list below for each signal's default action. If _s_a___h_a_n_d_l_e_r is SIG_DFL, the default action for the signal is to discard the signal, and if a signal is pending, the pending signal is discarded even if the signal is masked. If _s_a___h_a_n_d_l_e_r is set to SIG_IGN, current and pending instances of the signal are ignored and discarded. If _s_i_g is SIGCHLD and _s_a___h_a_n_d_l_e_r is set to SIG_IGN, the SA_NOCLDWAIT flag (described below) is implied. Options may be specified by setting _s_a___f_l_a_g_s. The meaning of the various bits is as follows: SA_NOCLDSTOP If this bit is set when installing a catching function for the SIGCHLD signal, the SIGCHLD signal will be generated only when a child process exits, not when a child process stops. SA_NOCLDWAIT If this bit is set when calling ssiiggaaccttiioonn() for the SIGCHLD signal, the system will not create zombie processes when children of the calling process exit, though existing zombies will remain. If the calling process subsequently issues a waitpid(2) (or equivalent) and there are no previously existing zombie child processes that match the waitpid(2) criteria, it blocks until all of the calling process's child processes that would match terminate, and then returns a value of -1 with _e_r_r_n_o set to ECHILD. SA_ONSTACK If this bit is set, the system will deliver the signal to the process on a _s_i_g_n_a_l _s_t_a_c_k, specified with sigaltstack(2). SA_NODEFER If this bit is set, further occurrences of the delivered signal are not masked during the execution of the handler. SA_RESETHAND If this bit is set, the handler is reset back to SIG_DFL at the moment the signal is delivered. SA_SIGINFO If this bit is set, the 2nd argument of the handler is set to be a pointer to a _s_i_g_i_n_f_o___t structure as described in <_s_y_s_/_s_i_g_i_n_f_o_._h>. It provides much more information about the causes and attributes of the signal that is being delivered. SA_RESTART If a signal is caught during the system calls listed below, the call may be forced to terminate with the error EINTR, the call may return with a data transfer shorter than requested, or the call may be restarted. Restarting of pending calls is requested by setting the SA_RESTART bit in _s_a___f_l_a_g_s. The affected system calls include read(2), write(2), sendto(2), recvfrom(2), sendmsg(2) and recvmsg(2) on a communications channel or a slow device (such as a terminal, but not a regular file) and during a wait(2) or ioctl(2). However, calls that have already committed are not restarted, but instead return a partial success (for example, a short read count). After a fork(2) or vfork(2), all signals, the signal mask, the signal stack, and the restart/interrupt flags are inherited by the child. execve(2) reinstates the default action for all signals which were caught and resets all signals to be caught on the user stack. Ignored signals remain ignored; the signal mask remains the same; signals that restart pending system calls continue to do so. The following is a list of all signals with names as in the include file <_s_i_g_n_a_l_._h>: NNaammee DDeeffaauulltt AAccttiioonn DDeessccrriippttiioonn SIGHUP terminate process terminal line hangup SIGINT terminate process interrupt program SIGQUIT create core image quit program SIGILL create core image illegal instruction SIGTRAP create core image trace trap SIGABRT create core image abort(3) call (formerly SIGIOT) SIGEMT create core image emulate instruction executed SIGFPE create core image floating-point exception SIGKILL terminate process kill program (cannot be caught or ignored) SIGBUS create core image bus error SIGSEGV create core image segmentation violation SIGSYS create core image system call given invalid argument SIGPIPE terminate process write on a pipe with no reader SIGALRM terminate process real-time timer expired SIGTERM terminate process software termination signal SIGURG discard signal urgent condition present on socket SIGSTOP stop process stop (cannot be caught or ignored) SIGTSTP stop process stop signal generated from keyboard SIGCONT discard signal continue after stop SIGCHLD discard signal child status has changed SIGTTIN stop process background read attempted from control terminal SIGTTOU stop process background write attempted to control terminal SIGIO discard signal I/O is possible on a descriptor (see fcntl(2)) SIGXCPU terminate process CPU time limit exceeded (see setrlimit(2)) SIGXFSZ terminate process file size limit exceeded (see setrlimit(2)) SIGVTALRM terminate process virtual time alarm (see setitimer(2)) SIGPROF terminate process profiling timer alarm (see setitimer(2)) SIGWINCH discard signal window size change SIGINFO discard signal status request from keyboard SIGUSR1 terminate process user defined signal 1 SIGUSR2 terminate process user defined signal 2 SIGTHR discard signal thread AST RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EEXXAAMMPPLLEESS The handler routine can be declared: void handler(int sig) If the SA_SIGINFO option is enabled, the canonical way to declare it is: void handler(int sig, siginfo_t *sip, struct sigcontext *scp) Here _s_i_g is the signal number, into which the hardware faults and traps are mapped. If the SA_SIGINFO option is set, _s_i_p is a pointer to a siginfo_t as described in <_s_y_s_/_s_i_g_i_n_f_o_._h>. If SA_SIGINFO is not set, this pointer will be NULL instead. The function specified in _s_a___s_i_g_a_c_t_i_o_n will be called instead of the function specified by _s_a___h_a_n_d_l_e_r (Note that in some implementations these are in fact the same). _s_c_p is a pointer to the _s_i_g_c_o_n_t_e_x_t structure (defined in <_s_i_g_n_a_l_._h>), used to restore the context from before the signal. EERRRROORRSS ssiiggaaccttiioonn() will fail and no new signal handler will be installed if one of the following occurs: [EFAULT] Either _a_c_t or _o_a_c_t points to memory that is not a valid part of the process address space. [EINVAL] _s_i_g is not a valid signal number. [EINVAL] An attempt is made to ignore or supply a handler for SIGKILL or SIGSTOP. SSEEEE AALLSSOO kill(1), kill(2), ptrace(2), sigaltstack(2), sigprocmask(2), sigsuspend(2), wait(2), setjmp(3), sigblock(3), sigpause(3), sigsetops(3), sigvec(3), tty(4) SSTTAANNDDAARRDDSS The ssiiggaaccttiioonn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The SA_ONSTACK flag and the SIGPROF, SIGSYS, SIGTRAP, SIGVTALRM, SIGXCPU, and SIGXFSZ signals conform to the X/Open System Interfaces option of that standard. The standard marks SIGPROF as obsolescent. The signals SIGEMT, SIGINFO, SIGIO, and SIGWINCH are Berkeley extensions. These signals are available on most BSD-derived systems. The SIGTHR signal is specific to OpenBSD and is part of the implementation of thread cancellation; _s_i_g_a_c_t_i_o_n and other signal interfaces may reject attempts to use or alter the handling of SIGTHR. The following functions are either reentrant or not interruptible by signals and are async-signal-safe. Therefore applications may invoke them, without restriction, from signal-catching functions: Standard Interfaces: __eexxiitt(), __EExxiitt(), aabboorrtt(), aacccceepptt(), aacccceessss(), aallaarrmm(), bbiinndd(), ccffggeettiissppeeeedd(), ccffggeettoossppeeeedd(), ccffsseettiissppeeeedd(), ccffsseettoossppeeeedd(), cchhddiirr(), cchhmmoodd(), cchhoowwnn(), cclloocckk__ggeettttiimmee(), cclloossee(), ccoonnnneecctt(), ccrreeaatt(), dduupp(), dduupp22(), eexxeeccll(), eexxeeccllee(), eexxeeccvv(), eexxeeccvvee(), ffaacccceessssaatt(), ffcchhddiirr(), ffcchhmmoodd(), ffcchhmmooddaatt(), ffcchhoowwnn(), ffcchhoowwnnaatt(), ffccnnttll(), ffddaattaassyynncc(), ffoorrkk(), ffppaatthhccoonnff(), ffssttaatt(), ffssttaattaatt(), ffssyynncc(), ffttrruunnccaattee(), ffuuttiimmeennss(), ffuuttiimmeess(), ggeetteeggiidd(), ggeetteeuuiidd(), ggeettggiidd(), ggeettggrroouuppss(), ggeettppeeeerrnnaammee(), ggeettppggrrpp(), ggeettppiidd(), ggeettppppiidd(), ggeettssoocckknnaammee(), ggeettssoocckkoopptt(), ggeettuuiidd(), kkiillll(), lliinnkk(), lliinnkkaatt(), lliisstteenn(), llsseeeekk(), llssttaatt(), mmkkddiirr(), mmkkddiirraatt(), mmkkffiiffoo(), mmkkffiiffooaatt(), mmkknnoodd(), mmkknnooddaatt(), ooppeenn(), ooppeennaatt(), ppaatthhccoonnff(), ppaauussee(), ppiippee(), ppoollll(), ppsseelleecctt(), pptthhrreeaadd__ssiiggmmaasskk(), rraaiissee(), rreeaadd(), rreeaaddlliinnkk(), rreeaaddlliinnkkaatt(), rreeccvv(), rreeccvvffrroomm(), rreeccvvmmssgg(), rreennaammee(), rreennaammeeaatt(), rrmmddiirr(), sseelleecctt(), sseenndd(), sseennddmmssgg(), sseennddttoo(), sseettggiidd(), sseettppggiidd(), sseettssiidd(), sseettssoocckkoopptt(), sseettuuiidd(), sshhuuttddoowwnn(), ssiiggaaccttiioonn(), ssiiggaaddddsseett(), ssiiggddeellsseett(), ssiiggeemmppttyysseett(), ssiiggffiillllsseett(), ssiiggiissmmeemmbbeerr(), ssiiggnnaall(), ssiiggppaauussee(), ssiiggppeennddiinngg(), ssiiggpprrooccmmaasskk(), ssiiggssuussppeenndd(), sslleeeepp(), ssoocckkaattmmaarrkk(), ssoocckkeett(), ssoocckkeettppaaiirr(), ssttaatt(), ssttrrccaatt(), ssttrrccppyy(), ssttrrnnccaatt(), ssttrrnnccppyy(), ssyymmlliinnkk(), ssyymmlliinnkkaatt(), ssyyssccoonnff(), ttccddrraaiinn(), ttccffllooww(), ttccfflluusshh(), ttccggeettaattttrr(), ttccggeettppggrrpp(), ttccsseennddbbrreeaakk(), ttccsseettaattttrr(), ttccsseettppggrrpp(), ttiimmee(), ttiimmeess(), uummaasskk(), uunnaammee(), uunnlliinnkk(), uunnlliinnkkaatt(), uuttiimmee(), uuttiimmeennssaatt(), uuttiimmeess(), wwaaiitt(), wwaaiittppiidd(), wwrriittee(), and perhaps some others. Extension Interfaces: aacccceepptt44(), cchhffllaaggss(), dduupp33(), ffcchhffllaaggss(), ggeetteennttrrooppyy(), ggeettrreessggiidd(), ggeettrreessuuiidd(), ppiippee22(), ppppoollll(), sseennddssyysslloogg(), sseettrreessggiidd(), sseettrreessuuiidd(), ssttrrllccaatt(), ssttrrllccppyy(), wwaaiitt33(), wwaaiitt44(). In addition, access and updates to _e_r_r_n_o are guaranteed to be safe. Most functions not in the above lists are considered to be unsafe with respect to signals. That is to say, the behaviour of such functions when called from a signal handler is undefined. In general though, signal handlers should do little more than set a flag, ideally of type volatile sig_atomic_t; most other actions are not safe. Additionally, it is advised that signal handlers guard against modification of the external symbol _e_r_r_n_o by the above functions, saving it at entry and restoring it on return, thus: void handler(int sig) { int save_errno = errno; ... errno = save_errno; } The functions below are async-signal-safe in OpenBSD except when used with floating-point arguments or directives, but are probably unsafe on other systems: ddpprriinnttff() Safe. vvddpprriinnttff() Safe. ssnnpprriinnttff() Safe. vvssnnpprriinnttff() Safe. ssyysslloogg__rr() Safe if the _s_y_s_l_o_g___d_a_t_a struct is initialized as a local variable. NNAAMMEE ssiiggaallttssttaacckk - set and/or get signal stack context SSYYNNOOPPSSIISS ##iinncclluuddee <> typedef struct sigaltstack { void *ss_sp; size_t ss_size; int ss_flags; } stack_t; _i_n_t ssiiggaallttssttaacckk(_c_o_n_s_t _s_t_a_c_k___t _*_s_s, _s_t_a_c_k___t _*_o_s_s); DDEESSCCRRIIPPTTIIOONN ssiiggaallttssttaacckk() allows users to define an alternate stack on which signals delivered to this thread are to be processed. If _s_s is non-zero and SS_DISABLE is set in _s_s___f_l_a_g_s, the signal stack will be disabled. A disabled stack will cause all signals to be taken on the regular user stack. Trying to disable an active stack will cause kkqquueeuuee to return -1 with _e_r_r_n_o set to EPERM. Otherwise, _s_s___s_p specifies a pointer to a space to be used as the signal stack and _s_s___s_i_z_e specifies the size of that space. When a signal's action indicates its handler should execute on the signal stack (specified with a sigaction(2) call), the system checks to see if the thread is currently executing on that stack. If the thread is not currently executing on the signal stack, the system arranges a switch to the signal stack for the duration of the signal handler's execution. If _o_s_s is non-zero, the current signal stack state is returned. The _s_s___f_l_a_g_s field will contain the value SS_ONSTACK if the thread is currently on a signal stack and SS_DISABLE if the signal stack is currently disabled. NNOOTTEESS The value SIGSTKSZ is defined to be the number of bytes/chars that would be used to cover the usual case when allocating an alternate stack area. The following code fragment is typically used to allocate an alternate stack. if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) /* error return */ sigstk.ss_size = SIGSTKSZ; sigstk.ss_flags = 0; if (sigaltstack(&sigstk, 0) == -1) perror("sigaltstack"); An alternative approach is provided for programs with signal handlers that require a specific amount of stack space other than the default size. The value MINSIGSTKSZ is defined to be the number of bytes/chars that is required by the operating system to implement the alternate stack feature. In computing an alternate stack size, programs should add MINSIGSTKSZ to their stack requirements to allow for the operating system overhead. Signal stacks are automatically adjusted for the direction of stack growth and alignment requirements. Signal stacks may or may not be protected by the hardware and are not ``grown'' automatically as is done for the normal stack. If the stack overflows and this space is not protected unpredictable results may occur. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssiiggaallttssttaacckk() will fail and the signal stack context will remain unchanged if one of the following occurs. [EFAULT] Either _s_s or _o_s_s points to memory that is not a valid part of the process address space. [EINVAL] The _s_s___f_l_a_g_s member pointed to by the _s_s argument contains flags other than SS_DISABLE. [ENOMEM] Size of alternate stack area is less than or equal to MINSIGSTKSZ. [EPERM] An attempt was made to disable an active stack. SSEEEE AALLSSOO sigaction(2), setjmp(3) SSTTAANNDDAARRDDSS The kkqquueeuuee function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The predecessor to ssiiggaallttssttaacckk, the ssiiggssttaacckk() system call, appeared in 4.2BSD. NNAAMMEE ssiiggppeennddiinngg - get pending signals SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssiiggppeennddiinngg(_s_i_g_s_e_t___t _*_s_e_t); DDEESSCCRRIIPPTTIIOONN The ssiiggppeennddiinngg function returns a mask of the signals pending for delivery to the calling process in the location indicated by _s_e_t. Signals may be pending because they are currently masked, or transiently before delivery (although the latter case is not normally detectable). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The ssiiggppeennddiinngg function does not currently detect any errors. SSEEEE AALLSSOO sigaction(2), sigprocmask(2), sigsetops(3) SSTTAANNDDAARRDDSS The ssiiggppeennddiinngg function is defined by IEEE Std 1003.1-2008 (``POSIX.1''). NNAAMMEE ssiiggpprrooccmmaasskk - manipulate current signal mask SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssiiggpprrooccmmaasskk(_i_n_t _h_o_w, _c_o_n_s_t _s_i_g_s_e_t___t _*_s_e_t, _s_i_g_s_e_t___t _*_o_s_e_t); DDEESSCCRRIIPPTTIIOONN The ssiiggpprrooccmmaasskk() function examines and/or changes the current signal mask (those signals that are blocked from delivery). Signals are blocked if they are members of the current signal mask set. If _s_e_t is not null, the action of ssiiggpprrooccmmaasskk() depends on the value of the parameter _h_o_w, which can be one of the following values: SIG_BLOCK The new mask is the union of the current mask and the specified _s_e_t. SIG_UNBLOCK The new mask is the intersection of the current mask and the complement of the specified _s_e_t. SIG_SETMASK The current mask is replaced by the specified _s_e_t. If _o_s_e_t is not null, it is set to the previous value of the signal mask. When _s_e_t is null, the value of _h_o_w is insignificant and the mask remains unchanged, providing a way to examine the signal mask without modification. The system quietly disallows SIGKILL or SIGSTOP to be blocked. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The ssiiggpprrooccmmaasskk() call will fail and the signal mask will be unchanged if one of the following occurs: [EINVAL] _h_o_w has a value other than those listed here. SSEEEE AALLSSOO kill(2), sigaction(2), sigsuspend(2), sigsetops(3) SSTTAANNDDAARRDDSS The ssiiggpprrooccmmaasskk() function call is expected to conform to IEEE Std 1003.1-2008 (``POSIX.1''). NNAAMMEE ssiiggrreettuurrnn - return from signal SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssiiggrreettuurrnn(_s_t_r_u_c_t _s_i_g_c_o_n_t_e_x_t _*_s_c_p); DDEESSCCRRIIPPTTIIOONN ssiiggrreettuurrnn() allows users to atomically unmask, switch stacks, and return from a signal context. The processes signal mask and stack status are restored from the context. The system call does not return; the users stack pointer, frame pointer, argument pointer, and processor status longword are restored from the context. Execution resumes at the specified pc. This system call is used by the trampoline code and longjmp(3) when returning from a signal to the previously executing program. Note that sigcontext contains machine dependent information. NNOOTTEESS This system call is not available in 4.2BSD hence it should not be used if backward compatibility is needed. RREETTUURRNN VVAALLUUEESS If successful, the system call does not return. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssiiggrreettuurrnn() will fail and the process context will remain unchanged if one of the following occurs. [EFAULT] _s_c_p points to memory that is not a valid part of the process address space. [EINVAL] The process status longword is invalid or would improperly raise the privilege level of the process. SSEEEE AALLSSOO sigaction(2), setjmp(3) HHIISSTTOORRYY The ssiiggrreettuurrnn() function call appeared in 4.3BSD. NNAAMMEE ssiiggssuussppeenndd - atomically change the signal mask and wait for interrupt SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssiiggssuussppeenndd(_c_o_n_s_t _s_i_g_s_e_t___t _*_s_i_g_m_a_s_k); DDEESSCCRRIIPPTTIIOONN ssiiggssuussppeenndd() temporarily changes the blocked signal mask to the set to which _s_i_g_m_a_s_k points, and then waits for a signal to arrive; on return the previous set of masked signals is restored. The signal mask set is usually empty to indicate that all signals are to be unblocked for the duration of the call. In normal usage, a signal is blocked using sigprocmask(2) to begin a critical section, variables modified on the occurrence of the signal are examined to determine that there is no work to be done, and the process pauses awaiting work by using ssiiggssuussppeenndd() with the previous mask returned by sigprocmask(2). RREETTUURRNN VVAALLUUEESS The ssiiggssuussppeenndd() function always terminates by being interrupted, returning -1 with _e_r_r_n_o set to EINTR. SSEEEE AALLSSOO sigaction(2), sigprocmask(2), sigsetops(3) SSTTAANNDDAARRDDSS The ssiiggssuussppeenndd function call conforms to IEEE Std 1003.1-2008 (``POSIX.1''). NNAAMMEE ssoocckkeett - create an endpoint for communication SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssoocckkeett(_i_n_t _d_o_m_a_i_n, _i_n_t _t_y_p_e, _i_n_t _p_r_o_t_o_c_o_l); DDEESSCCRRIIPPTTIIOONN ssoocckkeett() creates an endpoint for communication and returns a descriptor. The _d_o_m_a_i_n parameter specifies a communications domain within which communication will take place; this selects the protocol family which should be used. These families are defined in the include file <_s_y_s_/_s_o_c_k_e_t_._h>. The currently understood formats are: AF_UNIX UNIX internal protocols AF_INET ARPA Internet protocols AF_INET6 IPv6 (Internet Protocol version 6) protocols The socket has the indicated _t_y_p_e, which specifies the semantics of communication. Currently defined types are: SOCK_STREAM SOCK_DGRAM SOCK_RAW SOCK_SEQPACKET A SOCK_STREAM type provides sequenced, reliable, two-way connection based byte streams. An out-of-band data transmission mechanism may be supported. A SOCK_DGRAM socket supports datagrams (connectionless, unreliable messages of a fixed (typically small) maximum length). A SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer may be required to read an entire packet with each read system call. This facility is protocol specific, and presently implemented only for AF_UNIX. SOCK_RAW sockets provide access to internal network protocols and interfaces, and are available only to the superuser. Any combination of the following flags may additionally be used in the _t_y_p_e argument: SOCK_CLOEXEC Set close-on-exec flag on the new descriptor. SOCK_NONBLOCK Set non-blocking I/O mode on the new socket. The _p_r_o_t_o_c_o_l specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type within a given protocol family. However, it is possible that many protocols may exist, in which case a particular protocol must be specified in this manner. The protocol number to use is particular to the ``communication domain'' in which communication is to take place; see protocols(5). A value of 0 for _p_r_o_t_o_c_o_l will let the system select an appropriate protocol for the requested socket type. Sockets of type SOCK_STREAM are full-duplex byte streams. A stream socket must be in a _c_o_n_n_e_c_t_e_d state before any data may be sent or received on it. A connection to another socket is created with a connect(2) call. Once connected, data may be transferred using read(2) and write(2) calls or some variant of the send(2) and recv(2) calls. When a session has been completed a close(2) may be performed. Out-of- band data may also be transmitted as described in send(2) and received as described in recv(2). The communications protocols used to implement a SOCK_STREAM ensure that data is not lost or duplicated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered broken and calls will indicate an error with -1 returns and with ETIMEDOUT as the specific code in the global variable _e_r_r_n_o. The protocols optionally keep sockets ``warm'' by forcing transmissions roughly every minute in the absence of other activity. An error is then indicated if no response can be elicited on an otherwise idle connection for an extended period (e.g., 5 minutes). A SIGPIPE signal is raised if a process sends on a broken stream; this causes naive processes, which do not handle the signal, to exit. SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sockets. The only difference is that read(2) calls will return only the amount of data requested, and any remaining in the arriving packet will be discarded. SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspondents named in send(2) calls. Datagrams are generally received with recvfrom(2), which returns the next datagram with its return address. An fcntl(2) call can be used to specify a process group to receive a SIGURG signal when the out-of-band data arrives. It may also enable non- blocking I/O and asynchronous notification of I/O events via SIGIO. The operation of sockets is controlled by socket level _o_p_t_i_o_n_s. These options are defined in the file <_s_y_s_/_s_o_c_k_e_t_._h>. setsockopt(2) and getsockopt(2) are used to set and get options, respectively. RREETTUURRNN VVAALLUUEESS A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket. EERRRROORRSS The ssoocckkeett() call fails if: [EAFNOSUPPORT] The specified address family is not supported on this machine. [EPROTONOSUPPORT] The protocol type or the specified protocol is not supported within this domain. [EPROTOTYPE] The combination of the specified protocol and type is not supported. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [ENOBUFS] Insufficient resources were available in the system to perform the operation. [EACCES] Permission to create a socket of the specified type and/or protocol is denied. SSEEEE AALLSSOO accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), ioctl(2), listen(2), poll(2), read(2), recv(2), select(2), send(2), setsockopt(2), shutdown(2), socketpair(2), write(2), getprotoent(3), inet(4), inet6(4), netintro(4), unix(4) _A_n _I_n_t_r_o_d_u_c_t_o_r_y _4_._3 _B_S_D _I_n_t_e_r_p_r_o_c_e_s_s _C_o_m_m_u_n_i_c_a_t_i_o_n _T_u_t_o_r_i_a_l, reprinted in UNIX Programmer's Supplementary Documents Volume 1. _B_S_D _I_n_t_e_r_p_r_o_c_e_s_s _C_o_m_m_u_n_i_c_a_t_i_o_n _T_u_t_o_r_i_a_l, reprinted in UNIX Programmer's Supplementary Documents Volume 1. SSTTAANNDDAARRDDSS The ssoocckkeett() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssoocckkeett() system call first appeared in 4.1cBSD. NNAAMMEE ssoocckkeettppaaiirr - create a pair of connected sockets SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssoocckkeettppaaiirr(_i_n_t _d, _i_n_t _t_y_p_e, _i_n_t _p_r_o_t_o_c_o_l, _i_n_t _s_v_[_2_]); DDEESSCCRRIIPPTTIIOONN The ssoocckkeettppaaiirr() call creates an unnamed pair of connected sockets in the specified domain _d, of the specified _t_y_p_e, and using the optionally specified _p_r_o_t_o_c_o_l. The descriptors used in referencing the new sockets are returned in _s_v[0] and _s_v[1]. The two sockets are indistinguishable. Any combination of the following flags may additionally be used in the _t_y_p_e argument: SOCK_CLOEXEC Set close-on-exec flag on both the new descriptors. SOCK_NONBLOCK Set non-blocking I/O mode on both the new sockets. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The call succeeds unless: [EAFNOSUPPORT] The specified address family is not supported on this machine. [EPROTONOSUPPORT] The specified protocol is not supported on this machine. [EOPNOTSUPP] The specified protocol does not support creation of socket pairs. [EPROTOTYPE] The combination of the specified protocol and type is not supported. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [ENOBUFS] Insufficient resources were available in the system to perform the operation. [EFAULT] The address _s_v does not specify a valid part of the process address space. SSEEEE AALLSSOO pipe(2), read(2), socket(2), write(2) SSTTAANNDDAARRDDSS The ssoocckkeettppaaiirr() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssoocckkeettppaaiirr() function call appeared in 4.2BSD. BBUUGGSS This call is currently implemented only for the LOCAL domain. Many operating systems only accept a _p_r_o_t_o_c_o_l of PF_UNSPEC, so that should be used instead of PF_LOCAL for maximal portability. NNAAMMEE ssttaatt, llssttaatt, ffssttaattaatt, ffssttaatt - get file status SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t llssttaatt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b); _i_n_t ffssttaatt(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t _*_s_b); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ffssttaattaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t _*_s_b, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The ssttaatt() function obtains information about the file pointed to by _p_a_t_h. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. The llssttaatt() function is identical to ssttaatt() except when the named file is a symbolic link, in which case llssttaatt() returns information about the link itself, not the file the link references. The ffssttaattaatt() function is equivalent to either the ssttaatt() or llssttaatt() function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the file whose information is returned is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If ffssttaattaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssttaatt() or llssttaatt(), depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the status of the symbolic link is returned. The ffssttaatt() function obtains the same information about an open file known by the file descriptor _f_d. The _s_b argument is a pointer to a ssttaatt() structure as defined by <_s_y_s_/_s_t_a_t_._h> (shown below) and into which information is placed concerning the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ struct timespec st_atim; /* time of last access */ struct timespec st_mtim; /* time of last data modification */ struct timespec st_ctim; /* time of last file status change */ off_t st_size; /* file size, in bytes */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize;/* optimal blocksize for I/O */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are represented in struct timespec format, which has nanosecond precision. However, the actual precision is generally limited by the file system holding the file. The fields are as follows: _s_t___a_t_i_m Time when file data was last accessed. Set when the file system object was created and updated by the utimes(2) and read(2) system calls. _s_t___m_t_i_m Time when file data was last modified. Changed by the truncate(2), utimes(2), and write(2) system calls. For directories, changed by any system call that alters which files are in the directory, such as the unlink(2), rename(2), mkdir(2), and symlink(2) system calls. _s_t___c_t_i_m Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), rename(2), unlink(2), utimes(2), and write(2) system calls. In addition, all the time fields are set to the current time when a file system object is first created by the mkdir(2), mkfifo(2), mknod(2), open(2), and symlink(2) system calls. For compatibility with previous standards, _s_t___a_t_i_m_e, _s_t___m_t_i_m_e, and _s_t___c_t_i_m_e macros are provided that expand to the _t_v___s_e_c_s member of their respective struct timespec member. Deprecated macros are also provided for some transitional names: _s_t___a_t_i_m_e_n_s_e_c, _s_t___m_t_i_m_e_n_s_e_c, _s_t___c_t_i_m_e_n_s_e_c, _s_t___a_t_i_m_e_s_p_e_c, _s_t___m_t_i_m_e_s_p_e_c, and _s_t___c_t_i_m_e_s_p_e_c The size-related fields of the struct stat are as follows: _s_t___b_l_k_s_i_z_e The optimal I/O block size for the file. _s_t___b_l_o_c_k_s The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. The status information word _s_t___m_o_d_e has the following bits: #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_ISUID 0004000 /* set-user-ID on execution */ #define S_ISGID 0002000 /* set-group-ID on execution */ #define S_ISVTX 0001000 /* save swapped text even after use */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* R for owner */ #define S_IWUSR 0000200 /* W for owner */ #define S_IXUSR 0000100 /* X for owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* R for group */ #define S_IWGRP 0000020 /* W for group */ #define S_IXGRP 0000010 /* X for group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* R for other */ #define S_IWOTH 0000002 /* W for other */ #define S_IXOTH 0000001 /* X for other */ The following macros test a file's type. If the file is of that type, a non-zero value is returned; otherwise, 0 is returned. S_ISBLK(st_mode m) /* block special */ S_ISCHR(st_mode m) /* char special */ S_ISDIR(st_mode m) /* directory */ S_ISFIFO(st_mode m) /* fifo */ S_ISLNK(st_mode m) /* symbolic link */ S_ISREG(st_mode m) /* regular file */ S_ISSOCK(st_mode m) /* socket */ For a list of access modes, see <_s_y_s_/_s_t_a_t_._h>, access(2), and chmod(2). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaatt(), llssttaatt(), and ffssttaattaatt() will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] A component of _n_a_m_e does not exist or _n_a_m_e is the empty path. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EFAULT] _s_b or _n_a_m_e points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. Additionally, ffssttaattaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffssttaatt() will fail if: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _s_b points to an invalid address. [EIO] An I/O error occurred while reading from the file system. SSEEEE AALLSSOO chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) SSTTAANNDDAARRDDSS Previous versions of the system used different types for the _s_t___d_e_v, _s_t___u_i_d, _s_t___g_i_d, _s_t___r_d_e_v, _s_t___s_i_z_e, _s_t___b_l_k_s_i_z_e, and _s_t___b_l_o_c_k_s fields. The ffssttaatt(), ffssttaattaatt(), llssttaatt(), and ssttaatt() functions are intended to conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssttaatt() and ffssttaatt() system calls first appeared in Version 1 AT&T UNIX. The <_s_y_s_/_s_t_a_t_._h> header file and the _s_t_r_u_c_t _s_t_a_t were introduced in Version 7 AT&T UNIX. An llssttaatt() function call appeared in 4.2BSD. The ffssttaattaatt() function appeared in OpenBSD 5.0. CCAAVVEEAATTSS The file generation number, _s_t___g_e_n, is only available to the superuser. Certain programs written when the timestamps were just of type time_t assumed that the members were consecutive (and could therefore be treated as an array and have their address passed directly to utime(3)). The transition to timestamps of type struct timespec broke them irrevocably. BBUUGGSS Applying ffssttaatt() to a pipe or socket fails to fill in a unique device and inode number pair. Applying ffssttaatt() to a socket also fails to fill in the time fields. NNAAMMEE ssttaattffss, ffssttaattffss - get file system statistics SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ssttaattffss(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _s_t_r_u_c_t _s_t_a_t_f_s _*_b_u_f); _i_n_t ffssttaattffss(_i_n_t _f_d, _s_t_r_u_c_t _s_t_a_t_f_s _*_b_u_f); DDEESSCCRRIIPPTTIIOONN ssttaattffss() returns information about a mounted file system. _p_a_t_h is the path name of any file within the mounted file system. _b_u_f is a pointer to a ssttaattffss structure defined as follows: typedef struct { int32_t val[2]; } fsid_t; #define MFSNAMELEN 16 /* length of fs type name, including nul */ #define MNAMELEN 90 /* length of buffer for returned name */ struct statfs { u_int32_t f_flags; /* copy of mount flags */ u_int32_t f_bsize; /* file system block size */ u_int32_t f_iosize; /* optimal transfer block size */ /* unit is f_bsize */ u_int64_t f_blocks; /* total data blocks in file system */ u_int64_t f_bfree; /* free blocks in fs */ int64_t f_bavail; /* free blocks avail to non-superuser */ u_int64_t f_files; /* total file nodes in file system */ u_int64_t f_ffree; /* free file nodes in fs */ int64_t f_favail; /* free file nodes avail to non-root */ u_int64_t f_syncwrites; /* count of sync writes since mount */ u_int64_t f_syncreads; /* count of sync reads since mount */ u_int64_t f_asyncwrites; /* count of async writes since mount */ u_int64_t f_asyncreads; /* count of async reads since mount */ fsid_t f_fsid; /* file system id */ u_int32_t f_namemax; /* maximum filename length */ uid_t f_owner; /* user that mounted the file system */ u_int64_t f_ctime; /* last mount [-u] time */ char f_fstypename[MFSNAMELEN]; /* fs type name */ char f_mntonname[MNAMELEN]; /* directory on which mounted */ char f_mntfromname[MNAMELEN]; /* mounted file system */ char f_mntfromspec[MNAMELEN]; /* special for mount request */ union mount_info mount_info; /* per-filesystem mount options */ }; ffssttaattffss() returns the same information about an open file referenced by descriptor _f_d. Note that _f___f_s_i_d will be empty unless the user is the superuser. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ssttaattffss() fails if one or more of the following are true: [ENOTDIR] A component of the path prefix of _p_a_t_h is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The file referred to by _p_a_t_h does not exist. [EACCES] Search permission is denied for a component of the path prefix of _p_a_t_h. [ELOOP] Too many symbolic links were encountered in translating _p_a_t_h. [EFAULT] _b_u_f or _p_a_t_h points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. ffssttaattffss() fails if one or more of the following are true: [EBADF] _f_d is not a valid open file descriptor. [EFAULT] _b_u_f points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. SSEEEE AALLSSOO df(1), getfsstat(2), mount(2), stat(2) HHIISSTTOORRYY The ssttaattffss() function first appeared in 4.4BSD. NNAAMMEE sswwaappccttll - modify swap configuration SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t sswwaappccttll(_i_n_t _c_m_d, _c_o_n_s_t _v_o_i_d _*_a_r_g, _i_n_t _m_i_s_c); DDEESSCCRRIIPPTTIIOONN The sswwaappccttll() function is used to add and delete swap devices, and modify their configuration. The _c_m_d parameter specifies the operation to be performed. The _a_r_g and _m_i_s_c parameters have different meanings, depending on the _c_m_d parameter. If _c_m_d is SWAP_NSWAP, the current number of swap devices in the system is returned. The _a_r_g and _m_i_s_c parameters are ignored. If _c_m_d is SWAP_STATS, the current statistics for swap devices are returned in the _a_r_g parameter. No more than _m_i_s_c swap devices are returned. The _a_r_g parameter should point to an array of at least _m_i_s_c struct swapent structures: struct swapent { dev_t se_dev; /* device id */ int se_flags; /* entry flags */ int se_nblks; /* total blocks */ int se_inuse; /* blocks in use */ int se_priority; /* priority */ char se_path[PATH_MAX]; /* path to entry */ }; The flags are defined as SWF_INUSE in use: we have swapped here SWF_ENABLE enabled: we can swap here SWF_BUSY busy: I/O happening here SWF_FAKE fake: still being built All but SWAP_NSWAP and SWAP_STATS require superuser privileges. If _c_m_d is SWAP_ON, the _a_r_g parameter is used as a pathname of a file to enable swapping to. The _m_i_s_c parameter is used to set the priority of this swap device. If _c_m_d is SWAP_OFF, the _a_r_g parameter is used as the pathname of a file to disable swapping from. The _m_i_s_c parameter is ignored. If _c_m_d is SWAP_CTL, the _a_r_g and _m_i_s_c parameters have the same function as for the SWAP_ON case, except that they change the priority of a currently enabled swap device. When swapping is enabled on a block device, the first portion of the disk is left unused to prevent any disklabel present from being overwritten. This space is allocated from the swap device when the SWAP_ON command is used. RREETTUURRNN VVAALLUUEESS If the _c_m_d parameter is SWAP_NSWAP or SWAP_STATS, sswwaappccttll() returns the number of swap devices, if successful. The SWAP_NSWAP command is always successful. Otherwise it returns 0 on success and -1 on failure, setting the global variable _e_r_r_n_o to indicate the error. EERRRROORRSS sswwaappccttll() succeeds unless: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named device does not exist. For the SWAP_CTL command, the named device is not currently enabled for swapping. [EACCES] Search permission is denied for a component of the path prefix. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The caller is not the superuser. [EBUSY] The device specified by _a_r_g has already been made available for swapping. [EINVAL] The device configured by _a_r_g has no associated size, or the _c_m_d was unknown. [ENXIO] The major device number of _a_r_g is out of range (this indicates no device driver exists for the associated hardware). [EIO] An I/O error occurred while opening the swap device. [EFAULT] _a_r_g points outside the process' allocated address space. SSEEEE AALLSSOO config(8), swapctl(8) HHIISSTTOORRYY The sswwaappccttll() function call appeared in NetBSD 1.3. The _s_e___p_a_t_h member was added to _s_t_r_u_c_t _s_w_a_p_e_n_t in NetBSD 1.4, when the header file was also moved from <_v_m_/_v_m___s_w_a_p_._h>. AAUUTTHHOORRSS The current swap system was designed and implemented by Matthew Green <_m_r_g_@_e_t_e_r_n_a_._c_o_m_._a_u>, with help from Paul Kranenburg <_p_k_@_N_e_t_B_S_D_._O_R_G> and Leo Weppelman <_l_e_o_@_N_e_t_B_S_D_._O_R_G>, and insights from Jason R. Thorpe <_t_h_o_r_p_e_j_@_N_e_t_B_S_D_._O_R_G>. NNAAMMEE ssyymmlliinnkk, ssyymmlliinnkkaatt - make symbolic link to a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssyymmlliinnkk(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_1, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_2); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ssyymmlliinnkkaatt(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_1, _i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_2); DDEESSCCRRIIPPTTIIOONN A symbolic link _n_a_m_e_2 is created to _n_a_m_e_1 (_n_a_m_e_2 is the name of the file created, _n_a_m_e_1 is the string used in creating the symbolic link). Either name may be an arbitrary path name; the files need not be on the same file system, and the file specified by _n_a_m_e_1 need not exist at all. The ssyymmlliinnkkaatt() function is equivalent to ssyymmlliinnkk() except that where _n_a_m_e_2 specifies a relative path, the newly created symbolic link is created relative to the directory associated with file descriptor _f_d instead of the current working directory. If ssyymmlliinnkkaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssyymmlliinnkk(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The symbolic link succeeds unless: [ENOTDIR] A component of the _n_a_m_e_2 prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] A component of the _n_a_m_e_2 path prefix denies search permission. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EEXIST] _n_a_m_e_2 already exists. [EIO] An I/O error occurred while making the directory entry for _n_a_m_e_2, or allocating the inode for _n_a_m_e_2, or writing out the link contents of _n_a_m_e_2. [EROFS] The file _n_a_m_e_2 would reside on a read-only file system. [ENOSPC] The directory in which the entry for the new symbolic link is being placed cannot be extended because there is no space left on the file system containing the directory. [ENOSPC] The new symbolic link cannot be created because there is no space left on the file system that will contain the symbolic link. [ENOSPC] There are no free inodes on the file system on which the symbolic link is being created. [EDQUOT] The directory in which the entry for the new symbolic link is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EDQUOT] The new symbolic link cannot be created because the user's quota of disk blocks on the file system that will contain the symbolic link has been exhausted. [EDQUOT] The user's quota of inodes on the file system on which the symbolic link is being created has been exhausted. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [EFAULT] _n_a_m_e_1 or _n_a_m_e_2 points outside the process's allocated address space. Additionally, ssyymmlliinnkkaatt() will fail if: [EBADF] The _n_a_m_e_2 argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _n_a_m_e_2 argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _n_a_m_e_2 argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO ln(1), link(2), readlink(2), unlink(2), symlink(7) SSTTAANNDDAARRDDSS The ssyymmlliinnkk() and ssyymmlliinnkkaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssyymmlliinnkk() system call first appeared in 4.1cBSD. The ssyymmlliinnkkaatt() system call has been available since OpenBSD 5.0. NNAAMMEE ssyymmlliinnkk, ssyymmlliinnkkaatt - make symbolic link to a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssyymmlliinnkk(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_1, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_2); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ssyymmlliinnkkaatt(_c_o_n_s_t _c_h_a_r _*_n_a_m_e_1, _i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_n_a_m_e_2); DDEESSCCRRIIPPTTIIOONN A symbolic link _n_a_m_e_2 is created to _n_a_m_e_1 (_n_a_m_e_2 is the name of the file created, _n_a_m_e_1 is the string used in creating the symbolic link). Either name may be an arbitrary path name; the files need not be on the same file system, and the file specified by _n_a_m_e_1 need not exist at all. The ssyymmlliinnkkaatt() function is equivalent to ssyymmlliinnkk() except that where _n_a_m_e_2 specifies a relative path, the newly created symbolic link is created relative to the directory associated with file descriptor _f_d instead of the current working directory. If ssyymmlliinnkkaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to ssyymmlliinnkk(). RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The symbolic link succeeds unless: [ENOTDIR] A component of the _n_a_m_e_2 prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] A component of the _n_a_m_e_2 path prefix denies search permission. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EEXIST] _n_a_m_e_2 already exists. [EIO] An I/O error occurred while making the directory entry for _n_a_m_e_2, or allocating the inode for _n_a_m_e_2, or writing out the link contents of _n_a_m_e_2. [EROFS] The file _n_a_m_e_2 would reside on a read-only file system. [ENOSPC] The directory in which the entry for the new symbolic link is being placed cannot be extended because there is no space left on the file system containing the directory. [ENOSPC] The new symbolic link cannot be created because there is no space left on the file system that will contain the symbolic link. [ENOSPC] There are no free inodes on the file system on which the symbolic link is being created. [EDQUOT] The directory in which the entry for the new symbolic link is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. [EDQUOT] The new symbolic link cannot be created because the user's quota of disk blocks on the file system that will contain the symbolic link has been exhausted. [EDQUOT] The user's quota of inodes on the file system on which the symbolic link is being created has been exhausted. [EIO] An I/O error occurred while making the directory entry or allocating the inode. [EFAULT] _n_a_m_e_1 or _n_a_m_e_2 points outside the process's allocated address space. Additionally, ssyymmlliinnkkaatt() will fail if: [EBADF] The _n_a_m_e_2 argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _n_a_m_e_2 argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _n_a_m_e_2 argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO ln(1), link(2), readlink(2), unlink(2), symlink(7) SSTTAANNDDAARRDDSS The ssyymmlliinnkk() and ssyymmlliinnkkaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ssyymmlliinnkk() system call first appeared in 4.1cBSD. The ssyymmlliinnkkaatt() system call has been available since OpenBSD 5.0. NNAAMMEE ssyynncc - synchronize disk block in-core status with that on disk SSYYNNOOPPSSIISS ##iinncclluuddee <> _v_o_i_d ssyynncc(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN The ssyynncc() function forces a write of dirty (modified) buffers in the block buffer cache out to disk. The kernel keeps this information in core to reduce the number of disk I/O transfers required by the system. As information in the cache is lost after a system crash a ssyynncc() call is issued frequently by the in-kernel process update (about every 30 seconds). The function fsync(2) may be used to synchronize individual file descriptor attributes. SSEEEE AALLSSOO fsync(2), sync(8) SSTTAANNDDAARRDDSS The ssyynncc() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY A ssyynncc() function call appeared in Version 2 AT&T UNIX. BBUUGGSS ssyynncc() may return before the buffers are completely flushed. NNAAMMEE ssyyssaarrcchh - architecture-dependent system call SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ssyyssaarrcchh(_i_n_t _n_u_m_b_e_r, _v_o_i_d _*_a_r_g_s); DDEESSCCRRIIPPTTIIOONN ssyyssaarrcchh() performs the architecture-dependent function specified by _n_u_m_b_e_r with the arguments specified by the _a_r_g_s pointer. _a_r_g_s is a pointer to a structure defining the actual arguments of the function. Symbolic constants and argument structures for the architecture-dependent functions can be found in the header file <_m_a_c_h_i_n_e_/_s_y_s_a_r_c_h_._h>. The ssyyssaarrcchh() system call should never be called directly by user programs. Instead, they should access its functions using the architecture-dependent library. RREETTUURRNN VVAALLUUEESS See the manual pages for specific architecture-dependent function calls for information about their return values. HHIISSTTOORRYY The ssyyssaarrcchh() function call appeared in NetBSD 0.9a. NNAAMMEE ssyyssccaallll, ____ssyyssccaallll - indirect system call SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t ssyyssccaallll(_i_n_t _n_u_m_b_e_r, _._._.); ____ssyyssccaallll(_q_u_a_d___t _n_u_m_b_e_r, _._._.); DDEESSCCRRIIPPTTIIOONN ssyyssccaallll() performs the system call whose assembly language interface has the specified _n_u_m_b_e_r with the specified arguments. Symbolic constants for system calls can be found in the header file <_s_y_s_/_s_y_s_c_a_l_l_._h>. Since different system calls have different return types, a prototype of ____ssyyssccaallll specifying the correct return type should be declared locally. This is especially important for system calls returning larger-than-int results. The ____ssyyssccaallll form should be used when one or more of the parameters is a 64-bit argument to ensure that argument alignment is correct. This system call is useful for testing new system calls that do not have entries in the C library. RREETTUURRNN VVAALLUUEESS The return values are defined by the system call being invoked. In general, for system calls returning _i_n_t, a 0 return value indicates success. A -1 return value indicates an error, and an error code is stored in _e_r_r_n_o. HHIISSTTOORRYY The predecessor of these functions, the former iinnddiirr() system call, first appeared in Version 4 AT&T UNIX. The ssyyssccaallll() function first appeared in 3BSD. BBUUGGSS There is no way to simulate system calls that have multiple return values such as pipe(2). NNAAMMEE ttrruunnccaattee, ffttrruunnccaattee - truncate or extend a file to a specified length SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t ttrruunnccaattee(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _o_f_f___t _l_e_n_g_t_h); _i_n_t ffttrruunnccaattee(_i_n_t _f_d, _o_f_f___t _l_e_n_g_t_h); DDEESSCCRRIIPPTTIIOONN ttrruunnccaattee() causes the file named by _p_a_t_h or referenced by _f_d to be truncated or extended to _l_e_n_g_t_h bytes in size. If the file was larger than this size, the extra data is lost. If the file was smaller than this size, it will be extended as if by writing bytes with the value zero. With ffttrruunnccaattee(), the file must be open for writing. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS ttrruunnccaattee() and ffttrruunnccaattee() will succeed unless: [EINVAL] The _l_e_n_g_t_h is a negative value. [EIO] An I/O error occurred updating the inode. In addition, ttrruunnccaattee() may return the following errors: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] The named file is not writable by the user. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EISDIR] The named file is a directory. [EROFS] The named file resides on a read-only file system. [ETXTBSY] The file is a pure procedure (shared text) file that is being executed. [EFAULT] _p_a_t_h points outside the process's allocated address space. ffttrruunnccaattee() may return the following errors: [EBADF] The _f_d is not a valid descriptor. [EINVAL] The _f_d references a socket, not a file. [EINVAL] The _f_d is not open for writing. SSEEEE AALLSSOO open(2) SSTTAANNDDAARRDDSS The ttrruunnccaattee() and ffttrruunnccaattee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ttrruunnccaattee() and ffttrruunnccaattee() system calls first appeared in 4.1cBSD. BBUUGGSS These calls should be generalized to allow ranges of bytes in a file to be discarded. Use of ttrruunnccaattee() to extend a file is not portable. NNAAMMEE uummaasskk - set file creation mode mask SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _m_o_d_e___t uummaasskk(_m_o_d_e___t _n_u_m_a_s_k); DDEESSCCRRIIPPTTIIOONN The uummaasskk() routine sets the process's file mode creation mask to _n_u_m_a_s_k and returns the previous value of the mask. The 9 low-order access permission bits of _n_u_m_a_s_k are used by system calls, including open(2), mkdir(2), mkfifo(2) and mknod(2) to turn off corresponding bits requested in the file mode (see chmod(2)). This clearing allows each user to restrict the default access to his files. The default mask value is S_IWGRP|S_IWOTH (022, write access for the owner only). Child processes inherit the mask of the calling process. RREETTUURRNN VVAALLUUEESS The previous value of the file mode mask is returned by the call. EERRRROORRSS The uummaasskk() function is always successful. SSEEEE AALLSSOO chmod(2), mkdir(2), mkfifo(2), mknod(2), open(2) SSTTAANNDDAARRDDSS The uummaasskk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The uummaasskk() system call first appeared in Version 7 AT&T UNIX. NNAAMMEE uunnlliinnkk, uunnlliinnkkaatt - remove directory entry SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t uunnlliinnkk(_c_o_n_s_t _c_h_a_r _*_p_a_t_h); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t uunnlliinnkkaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The uunnlliinnkk() function removes the link named by _p_a_t_h from its directory and decrements the link count of the file which was referenced by the link. If that decrement reduces the link count of the file to zero, and no process has the file open, then all resources associated with the file are reclaimed. If one or more processes have the file open when the last link is removed, the link is removed, but the removal of the file is delayed until all references to it have been closed. The uunnlliinnkkaatt() function is equivalent to either the uunnlliinnkk() or rmdir(2) function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the directory entry to be removed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If uunnlliinnkkaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to uunnlliinnkk() or rmdir(2), depending on whether or not the AT_REMOVEDIR bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_REMOVEDIR Remove the directory entry specified by _p_a_t_h as a directory, not a normal file. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The uunnlliinnkk() and uunnlliinnkkaatt() functions will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] Write permission is denied on the directory containing the link to be removed. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The named file is a directory and the effective user ID of the process is not the superuser, or the file system containing the file does not permit the use of uunnlliinnkk() on a directory. [EPERM] The directory containing the file is marked sticky, and neither the containing directory nor the file to be removed are owned by the effective user ID. [EPERM] The named file or the directory containing it has its immutable or append-only flag set (see chflags(2)). [EBUSY] The entry to be unlinked is the mount point for a mounted file system. [EIO] An I/O error occurred while deleting the directory entry or deallocating the inode. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. Additionally, uunnlliinnkkaatt() will fail if: [ENOTDIR] The AT_REMOVEDIR flag bit is set and _p_a_t_h does not name a directory. [ENOTEMPTY] The AT_REMOVEDIR flag bit is set and the named directory contains files other than `.' and `..' in it. [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_REMOVEDIR. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO rm(1), chflags(2), close(2), link(2), rmdir(2), symlink(7) SSTTAANNDDAARRDDSS The uunnlliinnkk() and uunnlliinnkkaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The uunnlliinnkk() system call first appeared in Version 1 AT&T UNIX. The uunnlliinnkkaatt() function appeared in OpenBSD 5.0. NNAAMMEE uunnlliinnkk, uunnlliinnkkaatt - remove directory entry SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t uunnlliinnkk(_c_o_n_s_t _c_h_a_r _*_p_a_t_h); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t uunnlliinnkkaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_p_a_t_h, _i_n_t _f_l_a_g); DDEESSCCRRIIPPTTIIOONN The uunnlliinnkk() function removes the link named by _p_a_t_h from its directory and decrements the link count of the file which was referenced by the link. If that decrement reduces the link count of the file to zero, and no process has the file open, then all resources associated with the file are reclaimed. If one or more processes have the file open when the last link is removed, the link is removed, but the removal of the file is delayed until all references to it have been closed. The uunnlliinnkkaatt() function is equivalent to either the uunnlliinnkk() or rmdir(2) function depending on the value of _f_l_a_g (see below), except that where _p_a_t_h specifies a relative path, the directory entry to be removed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If uunnlliinnkkaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used and the behavior is identical to a call to uunnlliinnkk() or rmdir(2), depending on whether or not the AT_REMOVEDIR bit is set in _f_l_a_g. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_REMOVEDIR Remove the directory entry specified by _p_a_t_h as a directory, not a normal file. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS The uunnlliinnkk() and uunnlliinnkkaatt() functions will fail if: [ENOTDIR] A component of the path prefix is not a directory. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [EACCES] Search permission is denied for a component of the path prefix. [EACCES] Write permission is denied on the directory containing the link to be removed. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EPERM] The named file is a directory and the effective user ID of the process is not the superuser, or the file system containing the file does not permit the use of uunnlliinnkk() on a directory. [EPERM] The directory containing the file is marked sticky, and neither the containing directory nor the file to be removed are owned by the effective user ID. [EPERM] The named file or the directory containing it has its immutable or append-only flag set (see chflags(2)). [EBUSY] The entry to be unlinked is the mount point for a mounted file system. [EIO] An I/O error occurred while deleting the directory entry or deallocating the inode. [EROFS] The named file resides on a read-only file system. [EFAULT] _p_a_t_h points outside the process's allocated address space. Additionally, uunnlliinnkkaatt() will fail if: [ENOTDIR] The AT_REMOVEDIR flag bit is set and _p_a_t_h does not name a directory. [ENOTEMPTY] The AT_REMOVEDIR flag bit is set and the named directory contains files other than `.' and `..' in it. [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_REMOVEDIR. [EBADF] The _p_a_t_h argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _p_a_t_h argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _p_a_t_h argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. SSEEEE AALLSSOO rm(1), chflags(2), close(2), link(2), rmdir(2), symlink(7) SSTTAANNDDAARRDDSS The uunnlliinnkk() and uunnlliinnkkaatt() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The uunnlliinnkk() system call first appeared in Version 1 AT&T UNIX. The uunnlliinnkkaatt() function appeared in OpenBSD 5.0. NNAAMMEE mmoouunntt, uunnmmoouunntt - mount or dismount a filesystem SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t mmoouunntt(_c_o_n_s_t _c_h_a_r _*_t_y_p_e, _c_o_n_s_t _c_h_a_r _*_d_i_r, _i_n_t _f_l_a_g_s, _v_o_i_d _*_d_a_t_a); _i_n_t uunnmmoouunntt(_c_o_n_s_t _c_h_a_r _*_d_i_r, _i_n_t _f_l_a_g_s); DDEESSCCRRIIPPTTIIOONN The mmoouunntt() function grafts a filesystem object onto the system file tree at the point _d_i_r. The argument _d_a_t_a describes the filesystem object to be mounted. The argument _t_y_p_e tells the kernel how to interpret _d_a_t_a (see _t_y_p_e below). The contents of the filesystem become available through the new mount point _d_i_r. Any files in _d_i_r at the time of a successful mount are swept under the carpet, so to speak, and are unavailable until the filesystem is unmounted. The following _f_l_a_g_s may be specified to suppress default semantics which affect filesystem access. MNT_RDONLY The filesystem should be treated as read-only: even the superuser may not write to it. MNT_NOATIME Do not update the access time on files in the filesystem unless the modification or status change times are also being updated. MNT_NOEXEC Do not allow files to be executed from the filesystem. MNT_NOSUID Do not honor setuid or setgid bits on files when executing them. MNT_NODEV Do not interpret special files on the filesystem. MNT_SYNCHRONOUS All I/O to the filesystem should be done synchronously. MNT_ASYNC All I/O to the filesystem should be done asynchronously. MNT_SOFTDEP Use soft dependencies. Applies to FFS filesystems only (see 'softdep' in mount(8)). The flag MNT_UPDATE indicates that the mount command is being applied to an already mounted filesystem. This allows the mount flags to be changed without requiring that the filesystem be unmounted and remounted. Some filesystems may not allow all flags to be changed. For example, most filesystems will not allow a change from read-write to read-only. The _t_y_p_e argument defines the type of the filesystem. The types of filesystems known to the system are defined in <_s_y_s_/_m_o_u_n_t_._h>. _d_a_t_a is a pointer to a structure that contains the type specific arguments to mount. The currently supported types of filesystems and their type specific data are: MOUNT_CD9660 struct iso_args { char *fspec; /* block special device to mount */ struct export_args export_info; /* network export info */ int flags; /* mounting flags, see below */ }; #define ISOFSMNT_NORRIP 0x00000001 /* disable Rock Ridge Ext.*/ #define ISOFSMNT_GENS 0x00000002 /* enable generation numbers */ #define ISOFSMNT_EXTATT 0x00000004 /* enable extended attributes */ #define ISOFSMNT_NOJOLIET 0x00000008 /* disable Joliet Ext.*/ #define ISOFSMNT_SESS 0x00000010 /* use iso_args.sess */ MOUNT_FFS struct ufs_args { char *fspec; /* block special file to mount */ struct export_args export_info; /* network export information */ }; MOUNT_MFS struct mfs_args { char *fspec; /* name to export for statfs */ struct export_args export_info; /* if we can export an MFS */ caddr_t base; /* base of filesystem in mem */ u_long size; /* size of filesystem */ }; MOUNT_MSDOS struct msdosfs_args { char *fspec; /* blocks special holding fs to mount */ struct export_args export_info; /* network export information */ uid_t uid; /* uid that owns msdosfs files */ gid_t gid; /* gid that owns msdosfs files */ mode_t mask; /* mask to be applied for msdosfs perms */ int flags; /* see below */ }; /* * Msdosfs mount options: */ #define MSDOSFSMNT_SHORTNAME 1 /* Force old DOS short names only */ #define MSDOSFSMNT_LONGNAME 2 /* Force Win'95 long names */ #define MSDOSFSMNT_NOWIN95 4 /* Completely ignore Win95 entries */ MOUNT_NFS struct nfs_args { int version; /* args structure version */ struct sockaddr *addr; /* file server address */ int addrlen; /* length of address */ int sotype; /* Socket type */ int proto; /* and Protocol */ u_char *fh; /* File handle to be mounted */ int fhsize; /* Size, in bytes, of fh */ int flags; /* flags */ int wsize; /* write size in bytes */ int rsize; /* read size in bytes */ int readdirsize; /* readdir size in bytes */ int timeo; /* initial timeout in .1 secs */ int retrans; /* times to retry send */ int maxgrouplist; /* Max. size of group list */ int readahead; /* # of blocks to readahead */ int leaseterm; /* Term (sec) of lease */ int deadthresh; /* Retrans threshold */ char *hostname; /* server's name */ int acregmin; /* Attr cache file recently modified */ int acregmax; /* ac file not recently modified */ int acdirmin; /* ac for dir recently modified */ int acdirmax; /* ac for dir not recently modified */ }; MOUNT_NTFS struct ntfs_args { char *fspec; /* block special device to mount */ struct export_args export_info; /* network export information */ uid_t uid; /* uid that owns ntfs files */ gid_t gid; /* gid that owns ntfs files */ mode_t mode; /* mask to be applied for ntfs perms */ u_long flag; /* additional flags */ }; /* * ntfs mount options: */ #define NTFS_MFLAG_CASEINS 0x00000001 #define NTFS_MFLAG_ALLNAMES 0x00000002 MOUNT_UDF struct udf_args { char *fspec; /* block special device to mount */ }; The uunnmmoouunntt() function call disassociates the filesystem from the specified mount point _d_i_r. The _f_l_a_g_s argument may specify MNT_FORCE to specify that the filesystem should be forcibly unmounted even if files are still active. Active special devices continue to work, but any further accesses to any other active files result in errors even if the filesystem is later remounted. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS mmoouunntt() will fail when one of the following occurs: [EPERM] The caller is not the superuser. [ENAMETOOLONG] The path name exceeded {MNAMELEN} characters. [ELOOP] Too many symbolic links were encountered in translating a pathname. [ENOENT] A component of _d_i_r does not exist. [ENOTDIR] A component of _n_a_m_e is not a directory, or a path prefix of _s_p_e_c_i_a_l is not a directory. [EINVAL] An argument given was invalid. [EBUSY] Another process currently holds a reference to _d_i_r. [EFAULT] _d_i_r points outside the process's allocated address space. [EOPNOTSUPP] _t_y_p_e is not supported by the kernel. The following errors can occur for a ``ufs'' filesystem mount: [ENODEV] A component of ufs_args _f_s_p_e_c does not exist. [ENOTBLK] _f_s_p_e_c is not a block device. [ENXIO] The major device number of _f_s_p_e_c is out of range (this indicates no device driver exists for the associated hardware). [EBUSY] _f_s_p_e_c is already mounted. [EINVAL] The super block for the filesystem had a bad magic number, an out of range block size, or an invalid combination of flags. [ENOMEM] Not enough memory was available to read the cylinder group information for the filesystem. [EIO] An I/O error occurred while reading the super block or cylinder group information. [EFAULT] _f_s_p_e_c points outside the process's allocated address space. [EROFS] The filesystem was not unmounted cleanly and MNT_FORCE was not specified. [EROFS] An attempt was made to mount a 4.2BSD filesystem without the MNT_RDONLY flag. The following errors can occur for an _N_F_S filesystem mount: [ETIMEDOUT] _N_F_S timed out trying to contact the server. [EFAULT] Some part of the information described by nfs_args points outside the process's allocated address space. The following errors can occur for a _m_f_s filesystem mount: [EMFILE] No space remains in the mount table. [EINVAL] The super block for the filesystem had a bad magic number or an out of range block size. [ENOMEM] Not enough memory was available to read the cylinder group information for the filesystem. [EIO] A paging error occurred while reading the super block or cylinder group information. [EFAULT] _N_a_m_e points outside the process's allocated address space. uunnmmoouunntt() may fail with one of the following errors: [EPERM] The caller is not the superuser. [ENOTDIR] A component of the path is not a directory. [EINVAL] An argument given was invalid. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ELOOP] Too many symbolic links were encountered in translating the pathname. [EINVAL] The requested directory is not in the mount table. [EBUSY] A process is holding a reference to a file located on the filesystem. [EIO] An I/O error occurred while writing cached filesystem information. [EFAULT] _d_i_r points outside the process's allocated address space. SSEEEE AALLSSOO statfs(2), mfs(8), mount(8), umount(8) HHIISSTTOORRYY The mmoouunntt() and uunnmmoouunntt() system calls first appeared in Version 1 AT&T UNIX. The _f_l_a_g_s argument is supported by mmoouunntt() since Version 5 AT&T UNIX and by uunnmmoouunntt() since 4.3BSD-Reno. The current calling convention involving _t_y_p_e and _d_a_t_a arguments was introduced by 4.3BSD-Reno as well. BBUUGGSS Some of the error codes need translation to more obvious messages. NNAAMMEE uuttiimmeess, ffuuttiimmeess, uuttiimmeennssaatt, ffuuttiimmeennss - set file access and modification times SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t uuttiimmeess(_c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_s); _i_n_t ffuuttiimmeess(_i_n_t _f_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_s); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t uuttiimmeennssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _t_i_m_e_s_[_2_], _i_n_t _f_l_a_g); _i_n_t ffuuttiimmeennss(_i_n_t _f_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _t_i_m_e_s_[_2_]); DDEESSCCRRIIPPTTIIOONN The access and modification times of the file named by _p_a_t_h or referenced by _f_d are changed as specified by the argument _t_i_m_e_s. If _t_i_m_e_s is NULL, the access and modification times are set to the current time. The caller must be the owner of the file, have permission to write the file, or be the superuser. If _t_i_m_e_s is non-null, it is assumed to point to an array of two timeval structures. The access time is set to the value of the first element, and the modification time is set to the value of the second element. The caller must be the owner of the file or be the superuser. In either case, the inode-change-time of the file is set to the current time. The uuttiimmeennssaatt() and ffuuttiimmeennss() are equivalent to uuttiimmeess() and ffuuttiimmeess(), respectively, with the following differences. Both uuttiimmeennssaatt() and ffuuttiimmeennss() take two timespec values instead of two timeval values. Further, either of the _t_v___n_s_e_c fields can be set to one of the following special values defined in <_s_y_s_/_s_t_a_t_._h>: UTIME_NOW Set the respective timestamp to the greatest value supported that is not greater than the current time. UTIME_OMIT Do not change the respective timestamp. Additionally, if the _p_a_t_h argument to uuttiimmeennssaatt() specifies a relative path, the file whose timestamps are changed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If uuttiimmeennssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the timestamps of the symbolic link are changed. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS uuttiimmeess() and uuttiimmeennssaatt() will fail if: [EACCES] Search permission is denied for a component of the path prefix; or the _t_i_m_e_s argument is NULL and the effective user ID of the process does not match the owner of the file, and is not the superuser, and write access is denied. [EFAULT] _f_i_l_e or _t_i_m_e_s points outside the process's allocated address space. [EIO] An I/O error occurred while reading or writing the affected inode. [ELOOP] Too many symbolic links were encountered in translating the pathname. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [ENOTDIR] A component of the path prefix is not a directory. [EPERM] The _t_i_m_e_s argument is not NULL and the calling process's effective user ID does not match the owner of the file and is not the superuser. [EROFS] The file system containing the file is mounted read- only. Additionally, uuttiimmeennssaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _f_i_l_e argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _f_i_l_e argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _f_i_l_e argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffuuttiimmeess() and ffuuttiimmeennss() will fail if: [EBADF] _f_d does not refer to a valid descriptor. [EACCES] The _t_i_m_e_s argument is NULL and the effective user ID of the process does not match the owner of the file, and is not the superuser, and write access is denied. [EFAULT] _t_i_m_e_s points outside the process's allocated address space. [EIO] An I/O error occurred while reading or writing the affected inode. [EPERM] The _t_i_m_e_s argument is not NULL and the calling process's effective user ID does not match the owner of the file and is not the superuser. [EROFS] The file system containing the file is mounted read- only. SSEEEE AALLSSOO clock_gettime(2), stat(2), utime(3) SSTTAANNDDAARRDDSS The uuttiimmeess(), uuttiimmeennssaatt(), and ffuuttiimmeennss() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The predecessors of uuttiimmeess() were ssmmddaattee() in Version 1 AT&T UNIX, mmddaattee() in Version 3 AT&T UNIX, and uuttiimmee() in Version 7 AT&T UNIX; the latter first supported the concept of an access time in addition to the modification time. The uuttiimmeess() function call appeared in 4.2BSD. The ffuuttiimmeess() function call appeared in NetBSD 1.2. The uuttiimmeennssaatt() and ffuuttiimmeennss() function calls appeared in OpenBSD 5.0. CCAAVVEEAATTSS IEEE Std 1003.1-2008 (``POSIX.1'') specifies that uuttiimmeennssaatt() and ffuuttiimmeennss() shall mark the last file status change timestamp (i.e. _s_t___c_t_i_m) for update upon successful completion. However, currently some filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the modification timestamp argument. NNAAMMEE uuttiimmeess, ffuuttiimmeess, uuttiimmeennssaatt, ffuuttiimmeennss - set file access and modification times SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t uuttiimmeess(_c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_s); _i_n_t ffuuttiimmeess(_i_n_t _f_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_v_a_l _*_t_i_m_e_s); ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t uuttiimmeennssaatt(_i_n_t _f_d, _c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _t_i_m_e_s_[_2_], _i_n_t _f_l_a_g); _i_n_t ffuuttiimmeennss(_i_n_t _f_d, _c_o_n_s_t _s_t_r_u_c_t _t_i_m_e_s_p_e_c _t_i_m_e_s_[_2_]); DDEESSCCRRIIPPTTIIOONN The access and modification times of the file named by _p_a_t_h or referenced by _f_d are changed as specified by the argument _t_i_m_e_s. If _t_i_m_e_s is NULL, the access and modification times are set to the current time. The caller must be the owner of the file, have permission to write the file, or be the superuser. If _t_i_m_e_s is non-null, it is assumed to point to an array of two timeval structures. The access time is set to the value of the first element, and the modification time is set to the value of the second element. The caller must be the owner of the file or be the superuser. In either case, the inode-change-time of the file is set to the current time. The uuttiimmeennssaatt() and ffuuttiimmeennss() are equivalent to uuttiimmeess() and ffuuttiimmeess(), respectively, with the following differences. Both uuttiimmeennssaatt() and ffuuttiimmeennss() take two timespec values instead of two timeval values. Further, either of the _t_v___n_s_e_c fields can be set to one of the following special values defined in <_s_y_s_/_s_t_a_t_._h>: UTIME_NOW Set the respective timestamp to the greatest value supported that is not greater than the current time. UTIME_OMIT Do not change the respective timestamp. Additionally, if the _p_a_t_h argument to uuttiimmeennssaatt() specifies a relative path, the file whose timestamps are changed is determined relative to the directory associated with file descriptor _f_d instead of the current working directory. If uuttiimmeennssaatt() is passed the special value AT_FDCWD (defined in <_f_c_n_t_l_._h>) in the _f_d parameter, the current working directory is used. The _f_l_a_g argument is the bitwise OR of zero or more of the following values: AT_SYMLINK_NOFOLLOW If _p_a_t_h names a symbolic link, then the timestamps of the symbolic link are changed. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS uuttiimmeess() and uuttiimmeennssaatt() will fail if: [EACCES] Search permission is denied for a component of the path prefix; or the _t_i_m_e_s argument is NULL and the effective user ID of the process does not match the owner of the file, and is not the superuser, and write access is denied. [EFAULT] _f_i_l_e or _t_i_m_e_s points outside the process's allocated address space. [EIO] An I/O error occurred while reading or writing the affected inode. [ELOOP] Too many symbolic links were encountered in translating the pathname. [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, or an entire pathname (including the terminating NUL) exceeded PATH_MAX bytes. [ENOENT] The named file does not exist. [ENOTDIR] A component of the path prefix is not a directory. [EPERM] The _t_i_m_e_s argument is not NULL and the calling process's effective user ID does not match the owner of the file and is not the superuser. [EROFS] The file system containing the file is mounted read- only. Additionally, uuttiimmeennssaatt() will fail if: [EINVAL] The value of the _f_l_a_g argument was neither zero nor AT_SYMLINK_NOFOLLOW. [EBADF] The _f_i_l_e argument specifies a relative path and the _f_d argument is neither AT_FDCWD nor a valid file descriptor. [ENOTDIR] The _f_i_l_e argument specifies a relative path and the _f_d argument is a valid file descriptor but it does not reference a directory. [EACCES] The _f_i_l_e argument specifies a relative path but search permission is denied for the directory which the _f_d file descriptor references. ffuuttiimmeess() and ffuuttiimmeennss() will fail if: [EBADF] _f_d does not refer to a valid descriptor. [EACCES] The _t_i_m_e_s argument is NULL and the effective user ID of the process does not match the owner of the file, and is not the superuser, and write access is denied. [EFAULT] _t_i_m_e_s points outside the process's allocated address space. [EIO] An I/O error occurred while reading or writing the affected inode. [EPERM] The _t_i_m_e_s argument is not NULL and the calling process's effective user ID does not match the owner of the file and is not the superuser. [EROFS] The file system containing the file is mounted read- only. SSEEEE AALLSSOO clock_gettime(2), stat(2), utime(3) SSTTAANNDDAARRDDSS The uuttiimmeess(), uuttiimmeennssaatt(), and ffuuttiimmeennss() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The predecessors of uuttiimmeess() were ssmmddaattee() in Version 1 AT&T UNIX, mmddaattee() in Version 3 AT&T UNIX, and uuttiimmee() in Version 7 AT&T UNIX; the latter first supported the concept of an access time in addition to the modification time. The uuttiimmeess() function call appeared in 4.2BSD. The ffuuttiimmeess() function call appeared in NetBSD 1.2. The uuttiimmeennssaatt() and ffuuttiimmeennss() function calls appeared in OpenBSD 5.0. CCAAVVEEAATTSS IEEE Std 1003.1-2008 (``POSIX.1'') specifies that uuttiimmeennssaatt() and ffuuttiimmeennss() shall mark the last file status change timestamp (i.e. _s_t___c_t_i_m) for update upon successful completion. However, currently some filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the modification timestamp argument. NNAAMMEE uuttrraaccee - insert user record in ktrace log SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t uuttrraaccee(_c_o_n_s_t _c_h_a_r _*_l_a_b_e_l, _v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n); DDEESSCCRRIIPPTTIIOONN Adds a record to the process trace with information supplied by the user. The record is identified by _l_a_b_e_l and contains _l_e_n bytes from memory pointed to by _a_d_d_r. This call only has an effect if the calling process is being traced. RREETTUURRNN VVAALLUUEESS Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS [ENOSYS] The currently running kernel was compiled without ktrace(2) support (option KTRACE). [ENAMETOOLONG] The length of the _l_a_b_e_l string was longer than KTR_USER_MAXIDLEN-1. [EINVAL] The specified data length _l_e_n was bigger than KTR_USER_MAXLEN. SSEEEE AALLSSOO kdump(1), ktrace(1), ktrace(2), options(4) HHIISSTTOORRYY The uuttrraaccee() system call first appeared in FreeBSD 2.2. It was added to OpenBSD in OpenBSD 5.4. The _l_a_b_e_l argument is an extension. NNAAMMEE vvffoorrkk - spawn new process and block parent SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t vvffoorrkk(_v_o_i_d); DDEESSCCRRIIPPTTIIOONN vvffoorrkk() was originally used to create new processes without fully copying the address space of the old process, which is horrendously inefficient in a paged environment. It was useful when the purpose of fork(2) would have been to create a new system context for an execve(2). Since fork(2) is now efficient, even in the above case, the need for vvffoorrkk() has diminished. vvffoorrkk() differs from fork(2) in that the parent is suspended until the child makes a call to execve(2) or an exit (either by a call to _exit(2) or abnormally). In addition, fork handlers established using pthread_atfork(3) are not called when a multithreaded program calls vvffoorrkk(). vvffoorrkk() returns 0 in the child's context and (later) the PID of the child in the parent's context. RREETTUURRNN VVAALLUUEESS Same as for fork(2). SSEEEE AALLSSOO execve(2), fork(2), sigaction(2), wait(2) HHIISSTTOORRYY The vvffoorrkk() function call appeared in 2.9BSD with the additional semantics that the child process ran in the memory of the parent until it called execve(2) or exited. That sharing of memory was removed in 4.4BSD, leaving just the semantics of blocking the parent until the child calls execve(2) or exits. On many other systems the original behavior has been restored, making this interface particularly unportable. BBUUGGSS To avoid a possible deadlock situation, processes that are children in the middle of a vvffoorrkk() are never sent SIGTTOU or SIGTTIN signals; rather, output or ioctl(2) calls are allowed and input attempts result in an end-of-file indication. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwaaiitt, wwaaiittppiidd, wwaaiitt44, wwaaiitt33 - wait for process termination SSYYNNOOPPSSIISS ##iinncclluuddee <> _p_i_d___t wwaaiitt(_i_n_t _*_s_t_a_t_u_s); _p_i_d___t wwaaiittppiidd(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s); ##iinncclluuddee <> ##iinncclluuddee <> _p_i_d___t wwaaiitt33(_i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); _p_i_d___t wwaaiitt44(_p_i_d___t _w_p_i_d, _i_n_t _*_s_t_a_t_u_s, _i_n_t _o_p_t_i_o_n_s, _s_t_r_u_c_t _r_u_s_a_g_e _*_r_u_s_a_g_e); DDEESSCCRRIIPPTTIIOONN The wwaaiitt() function suspends execution of its calling process until _s_t_a_t_u_s information is available for a terminated child process, or a signal is received. On return from a successful wwaaiitt() call, the _s_t_a_t_u_s area, if non-zero, is filled in with termination information about the process that exited (see below). The wwaaiitt44() call provides a more general interface for programs that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. The other wait functions are implemented using wwaaiitt44(). The _w_p_i_d parameter specifies the set of child processes for which to wait. The following symbolic constants are currently defined in <_s_y_s_/_w_a_i_t_._h>: #define WAIT_ANY (-1) /* any process */ #define WAIT_MYPGRP 0 /* any process in my process group */ If _w_p_i_d is set to WAIT_ANY, the call waits for any child process. If _w_p_i_d is set to WAIT_MYPGRP, the call waits for any child process in the process group of the caller. If _w_p_i_d is greater than zero, the call waits for the process with process ID _w_p_i_d. If _w_p_i_d is less than -1, the call waits for any process whose process group ID equals the absolute value of _w_p_i_d. The _s_t_a_t_u_s parameter is defined below. The _o_p_t_i_o_n_s argument is the bitwise OR of zero or more of the following values: WCONTINUED Causes status to be reported for stopped child processes that have been continued by receipt of a SIGCONT signal. WNOHANG Indicates that the call should not block if there are no processes that wish to report status. WUNTRACED If set, children of the current process that are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have their status reported. If _r_u_s_a_g_e is non-zero, a summary of the resources used by the terminated process and all its children is returned (this information is currently not available for stopped processes). When the WNOHANG option is specified and no processes wish to report status, wwaaiitt44() returns a process ID of 0. The wwaaiittppiidd() call is identical to wwaaiitt44() with an _r_u_s_a_g_e value of zero. The older wwaaiitt33() call is the same as wwaaiitt44() with a _w_p_i_d value of -1. The following macros may be used to test the manner of exit of the process. One of the first three macros will evaluate to a non-zero (true) value: WWIIFFCCOONNTTIINNUUEEDD(_s_t_a_t_u_s) True if the process has not terminated, and has continued after a job control stop. This macro can be true only if the wait call specified the WCONTINUED option. WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) True if the process terminated normally by a call to _exit(2) or exit(3). WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) True if the process terminated due to receipt of a signal. WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the WUNTRACED option or if the child process is being traced (see ptrace(2)). Depending on the values of those macros, the following macros produce the remaining status information about the child process: WWEEXXIITTSSTTAATTUUSS(_s_t_a_t_u_s) If WWIIFFEEXXIITTEEDD(_s_t_a_t_u_s) is true, evaluates to the low-order 8 bits of the argument passed to _exit(2) or exit(3) by the child. WWTTEERRMMSSIIGG(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the termination of the process. WWCCOORREEDDUUMMPP(_s_t_a_t_u_s) If WWIIFFSSIIGGNNAALLEEDD(_s_t_a_t_u_s) is true, evaluates as true if the termination of the process was accompanied by the creation of a core file containing an image of the process when the signal was received. WWSSTTOOPPSSIIGG(_s_t_a_t_u_s) If WWIIFFSSTTOOPPPPEEDD(_s_t_a_t_u_s) is true, evaluates to the number of the signal that caused the process to stop. NNOOTTEESS See sigaction(2) for a list of termination signals. A status of 0 indicates normal termination. If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes are assigned the parent process 1 ID (the init process ID). If a signal is caught while any of the wwaaiitt() calls is pending, the call may be interrupted or restarted when the signal-catching routine returns, depending on the options in effect for the signal; for further information, see siginterrupt(3). RREETTUURRNN VVAALLUUEESS If wwaaiitt() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. If wwaaiitt44(), wwaaiitt33() or wwaaiittppiidd() returns due to a stopped or terminated child process, the process ID of the child is returned to the calling process. If there are no children not previously awaited, -1 is returned with _e_r_r_n_o set to [ECHILD]. Otherwise, if WNOHANG is specified and there are no stopped or exited children, 0 is returned. If an error is detected or a caught signal aborts the call, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwaaiitt() will fail and return immediately if: [ECHILD] The calling process has no existing unwaited-for child processes. [EFAULT] The _s_t_a_t_u_s or _r_u_s_a_g_e arguments point to an illegal address. (May not be detected before exit of a child process.) [EINTR] The call was interrupted by a caught signal, or the signal did not have the SA_RESTART flag set. [EINVAL] Invalid or undefined flags were passed in the _o_p_t_i_o_n_s argument. SSEEEE AALLSSOO _exit(2), sigaction(2), exit(3) SSTTAANNDDAARRDDSS The wwaaiitt() and wwaaiittppiidd() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). wwaaiitt44() and wwaaiitt33() are not specified by POSIX. The WWCCOORREEDDUUMMPP() macro and the ability to restart a pending wwaaiitt() call are extensions to that specification. HHIISSTTOORRYY A wwaaiitt() system call first appeared in Version 1 AT&T UNIX. The _s_t_a_t_u_s argument is accepted since Version 2 AT&T UNIX. A wwaaiitt33() system call first appeared in 4BSD, but the final calling convention was only established in 4.2BSD. The wwaaiitt44() and wwaaiittppiidd() function calls first appeared in 4.3BSD-Reno. NNAAMMEE wwrriittee, wwrriitteevv, ppwwrriittee, ppwwrriitteevv - write output SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t wwrriittee(_i_n_t _d, _c_o_n_s_t _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); _s_s_i_z_e___t ppwwrriittee(_i_n_t _d, _c_o_n_s_t _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s, _o_f_f___t _o_f_f_s_e_t); ##iinncclluuddee <> _s_s_i_z_e___t wwrriitteevv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t ppwwrriitteevv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN wwrriittee() attempts to write _n_b_y_t_e_s of data to the object referenced by the descriptor _d from the buffer pointed to by _b_u_f. wwrriitteevv() performs the same action, but gathers the output data from the _i_o_v_c_n_t buffers specified by the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1]. ppwwrriittee() and ppwwrriitteevv() perform the same functions, but write to the specified position _o_f_f_s_e_t in the file without modifying the file pointer. For wwrriitteevv() and ppwwrriitteevv(), the _i_o_v_e_c structure is defined as: struct iovec { void *iov_base; size_t iov_len; }; Each _i_o_v_e_c entry specifies the base address and length of an area in memory from which data should be written. wwrriitteevv() and ppwwrriitteevv() will always write a complete area before proceeding to the next. On objects capable of seeking, the wwrriittee() starts at a position given by the pointer associated with _d (see lseek(2)). Upon return from wwrriittee(), the pointer is incremented by the number of bytes which were written. If a file was opened with the O_APPEND flag (see open(2)), calls to wwrriittee() or wwrriitteevv() will automatically set the pointer to the end of the file before writing. Objects that are not capable of seeking always write from the current position. The value of the pointer associated with such an object is undefined. If the real user is not the superuser, then wwrriittee() clears the set-user- ID bit on a file. This prevents penetration of system security by a user who ``captures'' a writable set-user-ID file owned by the superuser. If wwrriittee() succeeds it will update the st_ctime and st_mtime fields of the file's meta-data (see stat(2)). When using non-blocking I/O on objects such as sockets that are subject to flow control, wwrriittee() and wwrriitteevv() may write fewer bytes than requested; the return value must be noted, and the remainder of the operation should be retried when possible. Note that wwrriitteevv() and ppwwrriitteevv() will fail if the value of _i_o_v_c_n_t exceeds the constant IOV_MAX. RREETTUURRNN VVAALLUUEESS Upon successful completion the number of bytes which were written is returned. Otherwise, a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwrriittee(), ppwwrriittee(), wwrriitteevv(), and ppwwrriitteevv() will fail and the file pointer will remain unchanged if: [EBADF] _d is not a valid descriptor open for writing. [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. [ENOSPC] There is no free space remaining on the file system containing the file. [EDQUOT] The user's quota of disk blocks on the file system containing the file has been exhausted. [EINTR] A write to a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data could be written. [EIO] An I/O error occurred while reading from or writing to the file system. [EFAULT] Part of _b_u_f points outside the process's allocated address space. In addition, wwrriittee() and wwrriitteevv() may return the following errors: [EPIPE] An attempt is made to write to a pipe that is not open for reading by any process. [EPIPE] An attempt is made to write to a socket of type SOCK_STREAM that is not connected to a peer socket. [EAGAIN] The file was marked for non-blocking I/O, and no data could be written immediately. [ENETDOWN] The destination address specified a network that is down. [EDESTADDRREQ] The destination is no longer available when writing to a UNIX-domain datagram socket on which connect(2) had been used to set a destination address. [EIO] The process is a member of a background process attempting to write to its controlling terminal, TOSTOP is set on the terminal, the process isn't ignoring the SIGTTOUT signal and the thread isn't blocking the SIGTTOUT signal, and either the process was created with vfork(2) and hasn't successfully executed one of the exec functions or the process group is orphaned. wwrriittee() and ppwwrriittee() may return the following error: [EINVAL] _n_b_y_t_e_s was larger than SSIZE_MAX. ppwwrriittee() and ppwwrriitteevv() may return the following error: [EINVAL] _o_f_f_s_e_t was negative. [ESPIPE] _d is associated with a pipe, socket, FIFO, or tty. wwrriitteevv() and ppwwrriitteevv() may return one of the following errors: [EINVAL] _i_o_v_c_n_t was less than or equal to 0, or greater than IOV_MAX. [EINVAL] The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed an _s_s_i_z_e___t. [EFAULT] Part of _i_o_v points outside the process's allocated address space. [ENOBUFS] The system lacked sufficient buffer space or a queue was full. SSEEEE AALLSSOO fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) SSTTAANNDDAARRDDSS The wwrriittee(), wwrriitteevv(), and ppwwrriittee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ppwwrriitteevv() function call appeared in OpenBSD 2.7. The ppwwrriittee() function call appeared in AT&T System V Release 4 UNIX. The wwrriitteevv() function call appeared in 4.2BSD. The wwrriittee() function call appeared in Version 2 AT&T UNIX. CCAAVVEEAATTSS Error checks should explicitly test for -1. Code such as while ((nr = write(fd, buf, sizeof(buf))) > 0) is not maximally portable, as some platforms allow for _n_b_y_t_e_s to range between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an error-free wwrriittee() may appear as a negative number distinct from -1. Proper loops should use while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) NNAAMMEE wwrriittee, wwrriitteevv, ppwwrriittee, ppwwrriitteevv - write output SSYYNNOOPPSSIISS ##iinncclluuddee <> _s_s_i_z_e___t wwrriittee(_i_n_t _d, _c_o_n_s_t _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s); _s_s_i_z_e___t ppwwrriittee(_i_n_t _d, _c_o_n_s_t _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s, _o_f_f___t _o_f_f_s_e_t); ##iinncclluuddee <> _s_s_i_z_e___t wwrriitteevv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t); ##iinncclluuddee <> ##iinncclluuddee <> _s_s_i_z_e___t ppwwrriitteevv(_i_n_t _d, _c_o_n_s_t _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN wwrriittee() attempts to write _n_b_y_t_e_s of data to the object referenced by the descriptor _d from the buffer pointed to by _b_u_f. wwrriitteevv() performs the same action, but gathers the output data from the _i_o_v_c_n_t buffers specified by the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1]. ppwwrriittee() and ppwwrriitteevv() perform the same functions, but write to the specified position _o_f_f_s_e_t in the file without modifying the file pointer. For wwrriitteevv() and ppwwrriitteevv(), the _i_o_v_e_c structure is defined as: struct iovec { void *iov_base; size_t iov_len; }; Each _i_o_v_e_c entry specifies the base address and length of an area in memory from which data should be written. wwrriitteevv() and ppwwrriitteevv() will always write a complete area before proceeding to the next. On objects capable of seeking, the wwrriittee() starts at a position given by the pointer associated with _d (see lseek(2)). Upon return from wwrriittee(), the pointer is incremented by the number of bytes which were written. If a file was opened with the O_APPEND flag (see open(2)), calls to wwrriittee() or wwrriitteevv() will automatically set the pointer to the end of the file before writing. Objects that are not capable of seeking always write from the current position. The value of the pointer associated with such an object is undefined. If the real user is not the superuser, then wwrriittee() clears the set-user- ID bit on a file. This prevents penetration of system security by a user who ``captures'' a writable set-user-ID file owned by the superuser. If wwrriittee() succeeds it will update the st_ctime and st_mtime fields of the file's meta-data (see stat(2)). When using non-blocking I/O on objects such as sockets that are subject to flow control, wwrriittee() and wwrriitteevv() may write fewer bytes than requested; the return value must be noted, and the remainder of the operation should be retried when possible. Note that wwrriitteevv() and ppwwrriitteevv() will fail if the value of _i_o_v_c_n_t exceeds the constant IOV_MAX. RREETTUURRNN VVAALLUUEESS Upon successful completion the number of bytes which were written is returned. Otherwise, a -1 is returned and the global variable _e_r_r_n_o is set to indicate the error. EERRRROORRSS wwrriittee(), ppwwrriittee(), wwrriitteevv(), and ppwwrriitteevv() will fail and the file pointer will remain unchanged if: [EBADF] _d is not a valid descriptor open for writing. [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. [ENOSPC] There is no free space remaining on the file system containing the file. [EDQUOT] The user's quota of disk blocks on the file system containing the file has been exhausted. [EINTR] A write to a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data could be written. [EIO] An I/O error occurred while reading from or writing to the file system. [EFAULT] Part of _b_u_f points outside the process's allocated address space. In addition, wwrriittee() and wwrriitteevv() may return the following errors: [EPIPE] An attempt is made to write to a pipe that is not open for reading by any process. [EPIPE] An attempt is made to write to a socket of type SOCK_STREAM that is not connected to a peer socket. [EAGAIN] The file was marked for non-blocking I/O, and no data could be written immediately. [ENETDOWN] The destination address specified a network that is down. [EDESTADDRREQ] The destination is no longer available when writing to a UNIX-domain datagram socket on which connect(2) had been used to set a destination address. [EIO] The process is a member of a background process attempting to write to its controlling terminal, TOSTOP is set on the terminal, the process isn't ignoring the SIGTTOUT signal and the thread isn't blocking the SIGTTOUT signal, and either the process was created with vfork(2) and hasn't successfully executed one of the exec functions or the process group is orphaned. wwrriittee() and ppwwrriittee() may return the following error: [EINVAL] _n_b_y_t_e_s was larger than SSIZE_MAX. ppwwrriittee() and ppwwrriitteevv() may return the following error: [EINVAL] _o_f_f_s_e_t was negative. [ESPIPE] _d is associated with a pipe, socket, FIFO, or tty. wwrriitteevv() and ppwwrriitteevv() may return one of the following errors: [EINVAL] _i_o_v_c_n_t was less than or equal to 0, or greater than IOV_MAX. [EINVAL] The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed an _s_s_i_z_e___t. [EFAULT] Part of _i_o_v points outside the process's allocated address space. [ENOBUFS] The system lacked sufficient buffer space or a queue was full. SSEEEE AALLSSOO fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) SSTTAANNDDAARRDDSS The wwrriittee(), wwrriitteevv(), and ppwwrriittee() functions conform to IEEE Std 1003.1-2008 (``POSIX.1''). HHIISSTTOORRYY The ppwwrriitteevv() function call appeared in OpenBSD 2.7. The ppwwrriittee() function call appeared in AT&T System V Release 4 UNIX. The wwrriitteevv() function call appeared in 4.2BSD. The wwrriittee() function call appeared in Version 2 AT&T UNIX. CCAAVVEEAATTSS Error checks should explicitly test for -1. Code such as while ((nr = write(fd, buf, sizeof(buf))) > 0) is not maximally portable, as some platforms allow for _n_b_y_t_e_s to range between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an error-free wwrriittee() may appear as a negative number distinct from -1. Proper loops should use while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) NNAAMMEE aarrmm__ddrraaiinn__wwrriitteebbuuff - drains the CPU write buffer SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aarrmm__ddrraaiinn__wwrriitteebbuuff(); DDEESSCCRRIIPPTTIIOONN aarrmm__ddrraaiinn__wwrriitteebbuuff() will make sure that all the entries in the processor write buffer are written out to memory. Not all processors support this operation (currently only the SA110 does). Those processes that do not, treat this function as a null-op. EERRRROORRSS aarrmm__ddrraaiinn__wwrriitteebbuuff() will never fail so will always return 0. RREEFFEERREENNCCEESS StrongARM Data Sheet NNAAMMEE aarrmm__ssyynncc__iiccaacchhee - clean the CPU data cache and flush the CPU instruction cache SSYYNNOOPPSSIISS ##iinncclluuddee <> _i_n_t aarrmm__ssyynncc__iiccaacchhee(_u___i_n_t _a_d_d_r, _i_n_t _l_e_n); DDEESSCCRRIIPPTTIIOONN aarrmm__ssyynncc__iiccaacchhee() will make sure that all the entries in the processor instruction cache are synchronized with main memory and that any data in a write back cache has been cleaned. Some ARM processors (e.g. SA110) have separate instruction and data caches, thus any dynamically generated or modified code needs to be written back from any data caches to main memory and the instruction cache needs to be synchronized with main memory. On such processors, aarrmm__ssyynncc__iiccaacchhee() will clean the data cache and invalidate the processor instruction cache to force reloading from main memory. On processors that have a shared instruction and data cache and have a write through cache (e.g. ARM6), no action needs to be taken. The routine takes a start address _a_d_d_r and a length _l_e_n to describe the area of memory that needs to be cleaned and synchronized. EERRRROORRSS aarrmm__ssyynncc__iiccaacchhee() will never fail so will always return 0. RREEFFEERREENNCCEESS StrongARM Data Sheet OpenBSD 5.7 August 14, 2013 OpenBSD 5.7