From: kremlin Date: Fri, 13 Feb 2015 09:44:50 +0000 (-0500) Subject: initial, add openbsd man pages X-Git-Url: https://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=openbsd_emul.git;a=commitdiff_plain;h=6a039e1a62a1c2f8b7538529d1313721f0b22a57 initial, add openbsd man pages --- 6a039e1a62a1c2f8b7538529d1313721f0b22a57 diff --git a/bsd_man2_all b/bsd_man2_all new file mode 100644 index 0000000..f72ccd9 --- /dev/null +++ b/bsd_man2_all @@ -0,0 +1,29046 @@ +# 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