| 1 | # find /usr/share/man/man2 | grep 2 | xargs pr -t | mandoc >> bsd_man2_all |
| 2 | |
| 3 | KQUEUE(2) System Calls Manual KQUEUE(2) |
| 4 | |
| 5 | N\bNA\bAM\bME\bE |
| 6 | k\bkq\bqu\bue\beu\bue\be, k\bke\bev\bve\ben\bnt\bt - kernel event notification mechanism |
| 7 | |
| 8 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 10 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/e\bev\bve\ben\bnt\bt.\b.h\bh>\b> |
| 11 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 12 | |
| 13 | _\bi_\bn_\bt |
| 14 | k\bkq\bqu\bue\beu\bue\be(_\bv_\bo_\bi_\bd); |
| 15 | |
| 16 | _\bi_\bn_\bt |
| 17 | k\bke\bev\bve\ben\bnt\bt(_\bi_\bn_\bt _\bk_\bq, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs, |
| 18 | _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\be_\bv_\be_\bn_\bt_\bs, |
| 19 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
| 20 | |
| 21 | E\bEV\bV_\b_S\bSE\bET\bT(_\b&_\bk_\be_\bv, _\bi_\bd_\be_\bn_\bt, _\bf_\bi_\bl_\bt_\be_\br, _\bf_\bl_\ba_\bg_\bs, _\bf_\bf_\bl_\ba_\bg_\bs, _\bd_\ba_\bt_\ba, _\bu_\bd_\ba_\bt_\ba); |
| 22 | |
| 23 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24 | k\bkq\bqu\bue\beu\bue\be() provides a generic method of notifying the user when an event |
| 25 | happens or a condition holds, based on the results of small pieces of |
| 26 | kernel code termed ``filters''. A kevent is identified by the (ident, |
| 27 | filter) pair; there may only be one unique kevent per kqueue. |
| 28 | |
| 29 | The filter is executed upon the initial registration of a kevent in order |
| 30 | to detect whether a preexisting condition is present, and is also |
| 31 | executed whenever an event is passed to the filter for evaluation. If |
| 32 | the filter determines that the condition should be reported, then the |
| 33 | kevent is placed on the kqueue for the user to retrieve. |
| 34 | |
| 35 | The filter is also run when the user attempts to retrieve the kevent from |
| 36 | the kqueue. If the filter indicates that the condition that triggered |
| 37 | the event no longer holds, the kevent is removed from the kqueue and is |
| 38 | not returned. |
| 39 | |
| 40 | Multiple events which trigger the filter do not result in multiple |
| 41 | kevents being placed on the kqueue; instead, the filter will aggregate |
| 42 | the events into a single struct kevent. Calling c\bcl\blo\bos\bse\be() on a file |
| 43 | descriptor will remove any kevents that reference the descriptor. |
| 44 | |
| 45 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a descriptor. The |
| 46 | queue is not inherited by a child created with fork(2). Similarly, |
| 47 | kqueues cannot be passed across UNIX-domain sockets. |
| 48 | |
| 49 | k\bke\bev\bve\ben\bnt\bt() is used to register events with the queue, and return any |
| 50 | pending events to the user. _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt is a pointer to an array of |
| 51 | _\bk_\be_\bv_\be_\bn_\bt structures, as defined in <_\bs_\by_\bs_\b/_\be_\bv_\be_\bn_\bt_\b._\bh>. All changes contained in |
| 52 | the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt are applied before any pending events are read from the |
| 53 | queue. _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs gives the size of _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt. _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt is a pointer to |
| 54 | an array of kevent structures. _\bn_\be_\bv_\be_\bn_\bt_\bs determines the size of _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
| 55 | When _\bn_\be_\bv_\be_\bn_\bt_\bs is zero, k\bke\bev\bve\ben\bnt\bt() will return immediately even if there is a |
| 56 | _\bt_\bi_\bm_\be_\bo_\bu_\bt specified unlike select(2). If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it |
| 57 | specifies a maximum interval to wait for an event, which will be |
| 58 | interpreted as a struct timespec. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, k\bke\bev\bve\ben\bnt\bt() |
| 59 | waits indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
| 60 | non-null, pointing to a zero-valued _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc structure. The same array |
| 61 | may be used for the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
| 62 | |
| 63 | E\bEV\bV_\b_S\bSE\bET\bT() is a macro which is provided for ease of initializing a kevent |
| 64 | structure. |
| 65 | |
| 66 | The _\bk_\be_\bv_\be_\bn_\bt structure is defined as: |
| 67 | |
| 68 | struct kevent { |
| 69 | uintptr_t ident; /* identifier for this event */ |
| 70 | short filter; /* filter for event */ |
| 71 | u_short flags; /* action flags for kqueue */ |
| 72 | u_int fflags; /* filter flag value */ |
| 73 | quad_t data; /* filter data value */ |
| 74 | void *udata; /* opaque user data identifier */ |
| 75 | }; |
| 76 | |
| 77 | The fields of struct kevent are: |
| 78 | |
| 79 | ident Value used to identify this event. The exact interpretation |
| 80 | is determined by the attached filter, but often is a file |
| 81 | descriptor. |
| 82 | |
| 83 | filter Identifies the kernel filter used to process this event. The |
| 84 | pre-defined system filters are described below. |
| 85 | |
| 86 | flags Actions to perform on the event. |
| 87 | |
| 88 | fflags Filter-specific flags. |
| 89 | |
| 90 | data Filter-specific data value. |
| 91 | |
| 92 | udata Opaque user-defined value passed through the kernel unchanged. |
| 93 | |
| 94 | The _\bf_\bl_\ba_\bg_\bs field can contain the following values: |
| 95 | |
| 96 | EV_ADD Adds the event to the kqueue. Re-adding an existing event |
| 97 | will modify the parameters of the original event, and not |
| 98 | result in a duplicate entry. Adding an event |
| 99 | automatically enables it, unless overridden by the |
| 100 | EV_DISABLE flag. |
| 101 | |
| 102 | EV_ENABLE Permit k\bke\bev\bve\ben\bnt\bt() to return the event if it is triggered. |
| 103 | |
| 104 | EV_DISABLE Disable the event so k\bke\bev\bve\ben\bnt\bt() will not return it. The |
| 105 | filter itself is not disabled. |
| 106 | |
| 107 | EV_DELETE Removes the event from the kqueue. Events which are |
| 108 | attached to file descriptors are automatically deleted on |
| 109 | the last close of the descriptor. |
| 110 | |
| 111 | EV_ONESHOT Causes the event to return only the first occurrence of |
| 112 | the filter being triggered. After the user retrieves the |
| 113 | event from the kqueue, it is deleted. |
| 114 | |
| 115 | EV_CLEAR After the event is retrieved by the user, its state is |
| 116 | reset. This is useful for filters which report state |
| 117 | transitions instead of the current state. Note that some |
| 118 | filters may automatically set this flag internally. |
| 119 | |
| 120 | EV_EOF Filters may set this flag to indicate filter-specific EOF |
| 121 | condition. |
| 122 | |
| 123 | EV_ERROR See _\bR_\bE_\bT_\bU_\bR_\bN _\bV_\bA_\bL_\bU_\bE_\bS below. |
| 124 | |
| 125 | The predefined system filters are listed below. Arguments may be passed |
| 126 | to and from the filter via the _\bf_\bf_\bl_\ba_\bg_\bs and _\bd_\ba_\bt_\ba fields in the kevent |
| 127 | structure. |
| 128 | |
| 129 | EVFILT_READ Takes a descriptor as the identifier, and returns whenever |
| 130 | there is data available to read. The behavior of the |
| 131 | filter is slightly different depending on the descriptor |
| 132 | type. |
| 133 | |
| 134 | Sockets |
| 135 | Sockets which have previously been passed to l\bli\bis\bst\bte\ben\bn() |
| 136 | return when there is an incoming connection pending. |
| 137 | _\bd_\ba_\bt_\ba contains the size of the listen backlog. |
| 138 | |
| 139 | Other socket descriptors return when there is data to |
| 140 | be read, subject to the SO_RCVLOWAT value of the |
| 141 | socket buffer. This may be overridden with a per- |
| 142 | filter low water mark at the time the filter is added |
| 143 | by setting the NOTE_LOWAT flag in _\bf_\bf_\bl_\ba_\bg_\bs, and |
| 144 | specifying the new low water mark in _\bd_\ba_\bt_\ba. On return, |
| 145 | _\bd_\ba_\bt_\ba contains the number of bytes in the socket |
| 146 | buffer. |
| 147 | |
| 148 | If the read direction of the socket has shutdown, then |
| 149 | the filter also sets EV_EOF in _\bf_\bl_\ba_\bg_\bs, and returns the |
| 150 | socket error (if any) in _\bf_\bf_\bl_\ba_\bg_\bs. It is possible for |
| 151 | EOF to be returned (indicating the connection is gone) |
| 152 | while there is still data pending in the socket |
| 153 | buffer. |
| 154 | |
| 155 | Vnodes |
| 156 | Returns when the file pointer is not at the end of |
| 157 | file. _\bd_\ba_\bt_\ba contains the offset from current position |
| 158 | to end of file, and may be negative. If NOTE_EOF is |
| 159 | set in _\bf_\bf_\bl_\ba_\bg_\bs, k\bke\bev\bve\ben\bnt\bt() will also return when the file |
| 160 | pointer is at the end of file. The end of file |
| 161 | condition is indicated by the presence of NOTE_EOF in |
| 162 | _\bf_\bf_\bl_\ba_\bg_\bs on return. |
| 163 | |
| 164 | Fifos, Pipes |
| 165 | Returns when there is data to read; _\bd_\ba_\bt_\ba contains the |
| 166 | number of bytes available. |
| 167 | |
| 168 | When the last writer disconnects, the filter will set |
| 169 | EV_EOF in _\bf_\bl_\ba_\bg_\bs. This may be cleared by passing in |
| 170 | EV_CLEAR, at which point the filter will resume |
| 171 | waiting for data to become available before returning. |
| 172 | |
| 173 | BPF devices |
| 174 | Returns when the BPF buffer is full, the BPF timeout |
| 175 | has expired, or when the BPF has ``immediate mode'' |
| 176 | enabled and there is any data to read; _\bd_\ba_\bt_\ba contains |
| 177 | the number of bytes available. |
| 178 | |
| 179 | EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever |
| 180 | it is possible to write to the descriptor. For sockets, |
| 181 | pipes, and FIFOs, _\bd_\ba_\bt_\ba will contain the amount of space |
| 182 | remaining in the write buffer. The filter will set EV_EOF |
| 183 | when the reader disconnects, and for the FIFO case, this |
| 184 | may be cleared by use of EV_CLEAR. Note that this filter |
| 185 | is not supported for vnodes or BPF devices. |
| 186 | |
| 187 | For sockets, the low water mark and socket error handling |
| 188 | is identical to the EVFILT_READ case. |
| 189 | |
| 190 | EVFILT_VNODE Takes a file descriptor as the identifier and the events |
| 191 | to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when one or more of |
| 192 | the requested events occurs on the descriptor. The events |
| 193 | to monitor are: |
| 194 | |
| 195 | NOTE_DELETE u\bun\bnl\bli\bin\bnk\bk() was called on the file referenced |
| 196 | by the descriptor. |
| 197 | |
| 198 | NOTE_WRITE A write occurred on the file referenced by |
| 199 | the descriptor. |
| 200 | |
| 201 | NOTE_EXTEND The file referenced by the descriptor was |
| 202 | extended. |
| 203 | |
| 204 | NOTE_TRUNCATE The file referenced by the descriptor was |
| 205 | truncated. |
| 206 | |
| 207 | NOTE_ATTRIB The file referenced by the descriptor had |
| 208 | its attributes changed. |
| 209 | |
| 210 | NOTE_LINK The link count on the file changed. |
| 211 | |
| 212 | NOTE_RENAME The file referenced by the descriptor was |
| 213 | renamed. |
| 214 | |
| 215 | NOTE_REVOKE Access to the file was revoked via |
| 216 | revoke(2) or the underlying file system was |
| 217 | unmounted. |
| 218 | |
| 219 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
| 220 | filter. |
| 221 | |
| 222 | EVFILT_PROC Takes the process ID to monitor as the identifier and the |
| 223 | events to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when the |
| 224 | process performs one or more of the requested events. If |
| 225 | a process can normally see another process, it can attach |
| 226 | an event to it. The events to monitor are: |
| 227 | |
| 228 | NOTE_EXIT The process has exited. The exit status |
| 229 | will be stored in _\bd_\ba_\bt_\ba in the same format |
| 230 | as the status set by wait(2). |
| 231 | |
| 232 | NOTE_FORK The process has called f\bfo\bor\brk\bk(). |
| 233 | |
| 234 | NOTE_EXEC The process has executed a new process |
| 235 | via execve(2) or similar call. |
| 236 | |
| 237 | NOTE_TRACK Follow a process across f\bfo\bor\brk\bk() calls. |
| 238 | The parent process will return with |
| 239 | NOTE_FORK set in the _\bf_\bf_\bl_\ba_\bg_\bs field, while |
| 240 | the child process will return with |
| 241 | NOTE_CHILD set in _\bf_\bf_\bl_\ba_\bg_\bs and the parent |
| 242 | PID in _\bd_\ba_\bt_\ba. |
| 243 | |
| 244 | NOTE_TRACKERR This flag is returned if the system was |
| 245 | unable to attach an event to the child |
| 246 | process, usually due to resource |
| 247 | limitations. |
| 248 | |
| 249 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
| 250 | filter. |
| 251 | |
| 252 | EVFILT_SIGNAL Takes the signal number to monitor as the identifier and |
| 253 | returns when the given signal is delivered to the process. |
| 254 | This coexists with the s\bsi\big\bgn\bna\bal\bl() and s\bsi\big\bga\bac\bct\bti\bio\bon\bn() |
| 255 | facilities, and has a lower precedence. The filter will |
| 256 | record all attempts to deliver a signal to a process, even |
| 257 | if the signal has been marked as SIG_IGN. Event |
| 258 | notification happens after normal signal delivery |
| 259 | processing. _\bd_\ba_\bt_\ba returns the number of times the signal |
| 260 | has occurred since the last call to k\bke\bev\bve\ben\bnt\bt(). This filter |
| 261 | automatically sets the EV_CLEAR flag internally. |
| 262 | |
| 263 | EVFILT_TIMER Establishes an arbitrary timer identified by _\bi_\bd_\be_\bn_\bt. When |
| 264 | adding a timer, _\bd_\ba_\bt_\ba specifies the timeout period in |
| 265 | milliseconds. The timer will be periodic unless |
| 266 | EV_ONESHOT is specified. On return, _\bd_\ba_\bt_\ba contains the |
| 267 | number of times the timeout has expired since the last |
| 268 | call to k\bke\bev\bve\ben\bnt\bt(). This filter automatically sets the |
| 269 | EV_CLEAR flag internally. |
| 270 | |
| 271 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 272 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a file descriptor. |
| 273 | If there was an error creating the kernel event queue, a value of -1 is |
| 274 | returned and errno set. |
| 275 | |
| 276 | k\bke\bev\bve\ben\bnt\bt() returns the number of events placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, up to the |
| 277 | value given by _\bn_\be_\bv_\be_\bn_\bt_\bs. If an error occurs while processing an element |
| 278 | of the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and there is enough room in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, then the |
| 279 | event will be placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt with EV_ERROR set in _\bf_\bl_\ba_\bg_\bs and the |
| 280 | system error in _\bd_\ba_\bt_\ba. Otherwise, -1 will be returned, and errno will be |
| 281 | set to indicate the error condition. If the time limit expires, then |
| 282 | k\bke\bev\bve\ben\bnt\bt() returns 0. |
| 283 | |
| 284 | E\bER\bRR\bRO\bOR\bRS\bS |
| 285 | The k\bkq\bqu\bue\beu\bue\be() function fails if: |
| 286 | |
| 287 | [ENOMEM] The kernel failed to allocate enough memory for the |
| 288 | kernel queue. |
| 289 | |
| 290 | [EMFILE] The per-process descriptor table is full. |
| 291 | |
| 292 | [ENFILE] The system file table is full. |
| 293 | |
| 294 | The k\bke\bev\bve\ben\bnt\bt() function fails if: |
| 295 | |
| 296 | [EACCES] The process does not have permission to register a |
| 297 | filter. |
| 298 | |
| 299 | [EFAULT] There was an error reading or writing the _\bk_\be_\bv_\be_\bn_\bt |
| 300 | structure. |
| 301 | |
| 302 | [EBADF] The specified descriptor is invalid. |
| 303 | |
| 304 | [EINTR] A signal was delivered before the timeout expired and |
| 305 | before any events were placed on the kqueue for |
| 306 | return. |
| 307 | |
| 308 | [EINVAL] The specified time limit or filter is invalid. |
| 309 | |
| 310 | [ENOENT] The event could not be found to be modified or |
| 311 | deleted. |
| 312 | |
| 313 | [ENOMEM] No memory was available to register the event. |
| 314 | |
| 315 | [ESRCH] The specified process to attach to does not exist. |
| 316 | |
| 317 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 318 | poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) |
| 319 | |
| 320 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 321 | The k\bkq\bqu\bue\beu\bue\be() and k\bke\bev\bve\ben\bnt\bt() functions first appeared in FreeBSD 4.1. |
| 322 | |
| 323 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 324 | The k\bkq\bqu\bue\beu\bue\be() system and this manual page were written by Jonathan Lemon |
| 325 | <_\bj_\bl_\be_\bm_\bo_\bn_\b@_\bF_\br_\be_\be_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
| 326 | |
| 327 | B\bBU\bUG\bGS\bS |
| 328 | It is currently not possible to watch FIFOs or AIO that reside on |
| 329 | anything but a UFS file system. Watching a vnode is possible on UFS, NFS |
| 330 | and MS-DOS file systems. |
| 331 | |
| 332 | The _\bt_\bi_\bm_\be_\bo_\bu_\bt value is limited to 24 hours; longer timeouts will be |
| 333 | silently reinterpreted as 24 hours. |
| 334 | |
| 335 | N\bNA\bAM\bME\bE |
| 336 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 337 | |
| 338 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 339 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 340 | |
| 341 | _\bi_\bn_\bt |
| 342 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 343 | |
| 344 | _\bi_\bn_\bt |
| 345 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 346 | |
| 347 | _\bi_\bn_\bt |
| 348 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 349 | |
| 350 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 351 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 352 | |
| 353 | _\bi_\bn_\bt |
| 354 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 355 | |
| 356 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 357 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 358 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 359 | required, but all directories listed in the path name leading to the file |
| 360 | must be searchable. |
| 361 | |
| 362 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 363 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 364 | itself, not the file the link references. |
| 365 | |
| 366 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 367 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 368 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 369 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 370 | instead of the current working directory. |
| 371 | |
| 372 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 373 | in the _\bf_\bd parameter, the current working directory is used and the |
| 374 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 375 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 376 | |
| 377 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 378 | values: |
| 379 | |
| 380 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 381 | of the symbolic link is returned. |
| 382 | |
| 383 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 384 | known by the file descriptor _\bf_\bd. |
| 385 | |
| 386 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 387 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 388 | concerning the file. |
| 389 | |
| 390 | struct stat { |
| 391 | dev_t st_dev; /* inode's device */ |
| 392 | ino_t st_ino; /* inode's number */ |
| 393 | mode_t st_mode; /* inode protection mode */ |
| 394 | nlink_t st_nlink; /* number of hard links */ |
| 395 | uid_t st_uid; /* user ID of the file's owner */ |
| 396 | gid_t st_gid; /* group ID of the file's group */ |
| 397 | dev_t st_rdev; /* device type */ |
| 398 | struct timespec st_atim; /* time of last access */ |
| 399 | struct timespec st_mtim; /* time of last data modification */ |
| 400 | struct timespec st_ctim; /* time of last file status change */ |
| 401 | off_t st_size; /* file size, in bytes */ |
| 402 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 403 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 404 | u_int32_t st_flags; /* user defined flags for file */ |
| 405 | u_int32_t st_gen; /* file generation number */ |
| 406 | }; |
| 407 | |
| 408 | The time-related fields of struct stat are represented in struct timespec |
| 409 | format, which has nanosecond precision. However, the actual precision is |
| 410 | generally limited by the file system holding the file. The fields are as |
| 411 | follows: |
| 412 | |
| 413 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 414 | system object was created and updated by the utimes(2) and |
| 415 | read(2) system calls. |
| 416 | |
| 417 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 418 | truncate(2), utimes(2), and write(2) system calls. For |
| 419 | directories, changed by any system call that alters which |
| 420 | files are in the directory, such as the unlink(2), rename(2), |
| 421 | mkdir(2), and symlink(2) system calls. |
| 422 | |
| 423 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 424 | modification). Changed by the chmod(2), chown(2), link(2), |
| 425 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 426 | |
| 427 | In addition, all the time fields are set to the current time when a file |
| 428 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 429 | open(2), and symlink(2) system calls. |
| 430 | |
| 431 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 432 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 433 | respective struct timespec member. Deprecated macros are also provided |
| 434 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 435 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 436 | |
| 437 | The size-related fields of the struct stat are as follows: |
| 438 | |
| 439 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 440 | |
| 441 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 442 | 512-byte units. As short symbolic links are stored in the |
| 443 | inode, this number may be zero. |
| 444 | |
| 445 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 446 | |
| 447 | #define S_IFMT 0170000 /* type of file mask */ |
| 448 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 449 | #define S_IFCHR 0020000 /* character special */ |
| 450 | #define S_IFDIR 0040000 /* directory */ |
| 451 | #define S_IFBLK 0060000 /* block special */ |
| 452 | #define S_IFREG 0100000 /* regular */ |
| 453 | #define S_IFLNK 0120000 /* symbolic link */ |
| 454 | #define S_IFSOCK 0140000 /* socket */ |
| 455 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 456 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 457 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 458 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 459 | #define S_IRUSR 0000400 /* R for owner */ |
| 460 | #define S_IWUSR 0000200 /* W for owner */ |
| 461 | #define S_IXUSR 0000100 /* X for owner */ |
| 462 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 463 | #define S_IRGRP 0000040 /* R for group */ |
| 464 | #define S_IWGRP 0000020 /* W for group */ |
| 465 | #define S_IXGRP 0000010 /* X for group */ |
| 466 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 467 | #define S_IROTH 0000004 /* R for other */ |
| 468 | #define S_IWOTH 0000002 /* W for other */ |
| 469 | #define S_IXOTH 0000001 /* X for other */ |
| 470 | |
| 471 | The following macros test a file's type. If the file is of that type, a |
| 472 | non-zero value is returned; otherwise, 0 is returned. |
| 473 | |
| 474 | S_ISBLK(st_mode m) /* block special */ |
| 475 | S_ISCHR(st_mode m) /* char special */ |
| 476 | S_ISDIR(st_mode m) /* directory */ |
| 477 | S_ISFIFO(st_mode m) /* fifo */ |
| 478 | S_ISLNK(st_mode m) /* symbolic link */ |
| 479 | S_ISREG(st_mode m) /* regular file */ |
| 480 | S_ISSOCK(st_mode m) /* socket */ |
| 481 | |
| 482 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 483 | |
| 484 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 485 | Upon successful completion, the value 0 is returned; otherwise the |
| 486 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 487 | error. |
| 488 | |
| 489 | E\bER\bRR\bRO\bOR\bRS\bS |
| 490 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 491 | |
| 492 | [ENOTDIR] A component of the path prefix is not a directory. |
| 493 | |
| 494 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 495 | characters, or an entire pathname (including the |
| 496 | terminating NUL) exceeded PATH_MAX bytes. |
| 497 | |
| 498 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 499 | empty path. |
| 500 | |
| 501 | [EACCES] Search permission is denied for a component of the |
| 502 | path prefix. |
| 503 | |
| 504 | [ELOOP] Too many symbolic links were encountered in |
| 505 | translating the pathname. |
| 506 | |
| 507 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 508 | |
| 509 | [EIO] An I/O error occurred while reading from or writing to |
| 510 | the file system. |
| 511 | |
| 512 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 513 | |
| 514 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 515 | AT_SYMLINK_NOFOLLOW. |
| 516 | |
| 517 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 518 | argument is neither AT_FDCWD nor a valid file |
| 519 | descriptor. |
| 520 | |
| 521 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 522 | argument is a valid file descriptor but it does not |
| 523 | reference a directory. |
| 524 | |
| 525 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 526 | permission is denied for the directory which the _\bf_\bd |
| 527 | file descriptor references. |
| 528 | |
| 529 | f\bfs\bst\bta\bat\bt() will fail if: |
| 530 | |
| 531 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 532 | |
| 533 | [EFAULT] _\bs_\bb points to an invalid address. |
| 534 | |
| 535 | [EIO] An I/O error occurred while reading from the file |
| 536 | system. |
| 537 | |
| 538 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 539 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 540 | |
| 541 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 542 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 543 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 544 | |
| 545 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 546 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 547 | |
| 548 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 549 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 550 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 551 | in Version 7 AT&T UNIX. |
| 552 | |
| 553 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 554 | appeared in OpenBSD 5.0. |
| 555 | |
| 556 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 557 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 558 | |
| 559 | Certain programs written when the timestamps were just of type time_t |
| 560 | assumed that the members were consecutive (and could therefore be treated |
| 561 | as an array and have their address passed directly to utime(3)). The |
| 562 | transition to timestamps of type struct timespec broke them irrevocably. |
| 563 | |
| 564 | B\bBU\bUG\bGS\bS |
| 565 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 566 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 567 | the time fields. |
| 568 | |
| 569 | N\bNA\bAM\bME\bE |
| 570 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 571 | |
| 572 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 573 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 574 | |
| 575 | _\bi_\bn_\bt |
| 576 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 577 | |
| 578 | _\bi_\bn_\bt |
| 579 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 580 | |
| 581 | _\bi_\bn_\bt |
| 582 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 583 | |
| 584 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 585 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 586 | |
| 587 | _\bi_\bn_\bt |
| 588 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 589 | |
| 590 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 591 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 592 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 593 | required, but all directories listed in the path name leading to the file |
| 594 | must be searchable. |
| 595 | |
| 596 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 597 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 598 | itself, not the file the link references. |
| 599 | |
| 600 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 601 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 602 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 603 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 604 | instead of the current working directory. |
| 605 | |
| 606 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 607 | in the _\bf_\bd parameter, the current working directory is used and the |
| 608 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 609 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 610 | |
| 611 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 612 | values: |
| 613 | |
| 614 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 615 | of the symbolic link is returned. |
| 616 | |
| 617 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 618 | known by the file descriptor _\bf_\bd. |
| 619 | |
| 620 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 621 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 622 | concerning the file. |
| 623 | |
| 624 | struct stat { |
| 625 | dev_t st_dev; /* inode's device */ |
| 626 | ino_t st_ino; /* inode's number */ |
| 627 | mode_t st_mode; /* inode protection mode */ |
| 628 | nlink_t st_nlink; /* number of hard links */ |
| 629 | uid_t st_uid; /* user ID of the file's owner */ |
| 630 | gid_t st_gid; /* group ID of the file's group */ |
| 631 | dev_t st_rdev; /* device type */ |
| 632 | struct timespec st_atim; /* time of last access */ |
| 633 | struct timespec st_mtim; /* time of last data modification */ |
| 634 | struct timespec st_ctim; /* time of last file status change */ |
| 635 | off_t st_size; /* file size, in bytes */ |
| 636 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 637 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 638 | u_int32_t st_flags; /* user defined flags for file */ |
| 639 | u_int32_t st_gen; /* file generation number */ |
| 640 | }; |
| 641 | |
| 642 | The time-related fields of struct stat are represented in struct timespec |
| 643 | format, which has nanosecond precision. However, the actual precision is |
| 644 | generally limited by the file system holding the file. The fields are as |
| 645 | follows: |
| 646 | |
| 647 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 648 | system object was created and updated by the utimes(2) and |
| 649 | read(2) system calls. |
| 650 | |
| 651 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 652 | truncate(2), utimes(2), and write(2) system calls. For |
| 653 | directories, changed by any system call that alters which |
| 654 | files are in the directory, such as the unlink(2), rename(2), |
| 655 | mkdir(2), and symlink(2) system calls. |
| 656 | |
| 657 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 658 | modification). Changed by the chmod(2), chown(2), link(2), |
| 659 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 660 | |
| 661 | In addition, all the time fields are set to the current time when a file |
| 662 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 663 | open(2), and symlink(2) system calls. |
| 664 | |
| 665 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 666 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 667 | respective struct timespec member. Deprecated macros are also provided |
| 668 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 669 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 670 | |
| 671 | The size-related fields of the struct stat are as follows: |
| 672 | |
| 673 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 674 | |
| 675 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 676 | 512-byte units. As short symbolic links are stored in the |
| 677 | inode, this number may be zero. |
| 678 | |
| 679 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 680 | |
| 681 | #define S_IFMT 0170000 /* type of file mask */ |
| 682 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 683 | #define S_IFCHR 0020000 /* character special */ |
| 684 | #define S_IFDIR 0040000 /* directory */ |
| 685 | #define S_IFBLK 0060000 /* block special */ |
| 686 | #define S_IFREG 0100000 /* regular */ |
| 687 | #define S_IFLNK 0120000 /* symbolic link */ |
| 688 | #define S_IFSOCK 0140000 /* socket */ |
| 689 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 690 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 691 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 692 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 693 | #define S_IRUSR 0000400 /* R for owner */ |
| 694 | #define S_IWUSR 0000200 /* W for owner */ |
| 695 | #define S_IXUSR 0000100 /* X for owner */ |
| 696 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 697 | #define S_IRGRP 0000040 /* R for group */ |
| 698 | #define S_IWGRP 0000020 /* W for group */ |
| 699 | #define S_IXGRP 0000010 /* X for group */ |
| 700 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 701 | #define S_IROTH 0000004 /* R for other */ |
| 702 | #define S_IWOTH 0000002 /* W for other */ |
| 703 | #define S_IXOTH 0000001 /* X for other */ |
| 704 | |
| 705 | The following macros test a file's type. If the file is of that type, a |
| 706 | non-zero value is returned; otherwise, 0 is returned. |
| 707 | |
| 708 | S_ISBLK(st_mode m) /* block special */ |
| 709 | S_ISCHR(st_mode m) /* char special */ |
| 710 | S_ISDIR(st_mode m) /* directory */ |
| 711 | S_ISFIFO(st_mode m) /* fifo */ |
| 712 | S_ISLNK(st_mode m) /* symbolic link */ |
| 713 | S_ISREG(st_mode m) /* regular file */ |
| 714 | S_ISSOCK(st_mode m) /* socket */ |
| 715 | |
| 716 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 717 | |
| 718 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 719 | Upon successful completion, the value 0 is returned; otherwise the |
| 720 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 721 | error. |
| 722 | |
| 723 | E\bER\bRR\bRO\bOR\bRS\bS |
| 724 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 725 | |
| 726 | [ENOTDIR] A component of the path prefix is not a directory. |
| 727 | |
| 728 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 729 | characters, or an entire pathname (including the |
| 730 | terminating NUL) exceeded PATH_MAX bytes. |
| 731 | |
| 732 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 733 | empty path. |
| 734 | |
| 735 | [EACCES] Search permission is denied for a component of the |
| 736 | path prefix. |
| 737 | |
| 738 | [ELOOP] Too many symbolic links were encountered in |
| 739 | translating the pathname. |
| 740 | |
| 741 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 742 | |
| 743 | [EIO] An I/O error occurred while reading from or writing to |
| 744 | the file system. |
| 745 | |
| 746 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 747 | |
| 748 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 749 | AT_SYMLINK_NOFOLLOW. |
| 750 | |
| 751 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 752 | argument is neither AT_FDCWD nor a valid file |
| 753 | descriptor. |
| 754 | |
| 755 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 756 | argument is a valid file descriptor but it does not |
| 757 | reference a directory. |
| 758 | |
| 759 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 760 | permission is denied for the directory which the _\bf_\bd |
| 761 | file descriptor references. |
| 762 | |
| 763 | f\bfs\bst\bta\bat\bt() will fail if: |
| 764 | |
| 765 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 766 | |
| 767 | [EFAULT] _\bs_\bb points to an invalid address. |
| 768 | |
| 769 | [EIO] An I/O error occurred while reading from the file |
| 770 | system. |
| 771 | |
| 772 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 773 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 774 | |
| 775 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 776 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 777 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 778 | |
| 779 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 780 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 781 | |
| 782 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 783 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 784 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 785 | in Version 7 AT&T UNIX. |
| 786 | |
| 787 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 788 | appeared in OpenBSD 5.0. |
| 789 | |
| 790 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 791 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 792 | |
| 793 | Certain programs written when the timestamps were just of type time_t |
| 794 | assumed that the members were consecutive (and could therefore be treated |
| 795 | as an array and have their address passed directly to utime(3)). The |
| 796 | transition to timestamps of type struct timespec broke them irrevocably. |
| 797 | |
| 798 | B\bBU\bUG\bGS\bS |
| 799 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 800 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 801 | the time fields. |
| 802 | |
| 803 | N\bNA\bAM\bME\bE |
| 804 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 805 | |
| 806 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 807 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 808 | |
| 809 | _\bi_\bn_\bt |
| 810 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 811 | |
| 812 | _\bi_\bn_\bt |
| 813 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 814 | |
| 815 | _\bi_\bn_\bt |
| 816 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 817 | |
| 818 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 819 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 820 | |
| 821 | _\bi_\bn_\bt |
| 822 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 823 | |
| 824 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 825 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 826 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 827 | required, but all directories listed in the path name leading to the file |
| 828 | must be searchable. |
| 829 | |
| 830 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 831 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 832 | itself, not the file the link references. |
| 833 | |
| 834 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 835 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 836 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 837 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 838 | instead of the current working directory. |
| 839 | |
| 840 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 841 | in the _\bf_\bd parameter, the current working directory is used and the |
| 842 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 843 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 844 | |
| 845 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 846 | values: |
| 847 | |
| 848 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 849 | of the symbolic link is returned. |
| 850 | |
| 851 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 852 | known by the file descriptor _\bf_\bd. |
| 853 | |
| 854 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 855 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 856 | concerning the file. |
| 857 | |
| 858 | struct stat { |
| 859 | dev_t st_dev; /* inode's device */ |
| 860 | ino_t st_ino; /* inode's number */ |
| 861 | mode_t st_mode; /* inode protection mode */ |
| 862 | nlink_t st_nlink; /* number of hard links */ |
| 863 | uid_t st_uid; /* user ID of the file's owner */ |
| 864 | gid_t st_gid; /* group ID of the file's group */ |
| 865 | dev_t st_rdev; /* device type */ |
| 866 | struct timespec st_atim; /* time of last access */ |
| 867 | struct timespec st_mtim; /* time of last data modification */ |
| 868 | struct timespec st_ctim; /* time of last file status change */ |
| 869 | off_t st_size; /* file size, in bytes */ |
| 870 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 871 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 872 | u_int32_t st_flags; /* user defined flags for file */ |
| 873 | u_int32_t st_gen; /* file generation number */ |
| 874 | }; |
| 875 | |
| 876 | The time-related fields of struct stat are represented in struct timespec |
| 877 | format, which has nanosecond precision. However, the actual precision is |
| 878 | generally limited by the file system holding the file. The fields are as |
| 879 | follows: |
| 880 | |
| 881 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 882 | system object was created and updated by the utimes(2) and |
| 883 | read(2) system calls. |
| 884 | |
| 885 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 886 | truncate(2), utimes(2), and write(2) system calls. For |
| 887 | directories, changed by any system call that alters which |
| 888 | files are in the directory, such as the unlink(2), rename(2), |
| 889 | mkdir(2), and symlink(2) system calls. |
| 890 | |
| 891 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 892 | modification). Changed by the chmod(2), chown(2), link(2), |
| 893 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 894 | |
| 895 | In addition, all the time fields are set to the current time when a file |
| 896 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 897 | open(2), and symlink(2) system calls. |
| 898 | |
| 899 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 900 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 901 | respective struct timespec member. Deprecated macros are also provided |
| 902 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 903 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 904 | |
| 905 | The size-related fields of the struct stat are as follows: |
| 906 | |
| 907 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 908 | |
| 909 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 910 | 512-byte units. As short symbolic links are stored in the |
| 911 | inode, this number may be zero. |
| 912 | |
| 913 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 914 | |
| 915 | #define S_IFMT 0170000 /* type of file mask */ |
| 916 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 917 | #define S_IFCHR 0020000 /* character special */ |
| 918 | #define S_IFDIR 0040000 /* directory */ |
| 919 | #define S_IFBLK 0060000 /* block special */ |
| 920 | #define S_IFREG 0100000 /* regular */ |
| 921 | #define S_IFLNK 0120000 /* symbolic link */ |
| 922 | #define S_IFSOCK 0140000 /* socket */ |
| 923 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 924 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 925 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 926 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 927 | #define S_IRUSR 0000400 /* R for owner */ |
| 928 | #define S_IWUSR 0000200 /* W for owner */ |
| 929 | #define S_IXUSR 0000100 /* X for owner */ |
| 930 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 931 | #define S_IRGRP 0000040 /* R for group */ |
| 932 | #define S_IWGRP 0000020 /* W for group */ |
| 933 | #define S_IXGRP 0000010 /* X for group */ |
| 934 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 935 | #define S_IROTH 0000004 /* R for other */ |
| 936 | #define S_IWOTH 0000002 /* W for other */ |
| 937 | #define S_IXOTH 0000001 /* X for other */ |
| 938 | |
| 939 | The following macros test a file's type. If the file is of that type, a |
| 940 | non-zero value is returned; otherwise, 0 is returned. |
| 941 | |
| 942 | S_ISBLK(st_mode m) /* block special */ |
| 943 | S_ISCHR(st_mode m) /* char special */ |
| 944 | S_ISDIR(st_mode m) /* directory */ |
| 945 | S_ISFIFO(st_mode m) /* fifo */ |
| 946 | S_ISLNK(st_mode m) /* symbolic link */ |
| 947 | S_ISREG(st_mode m) /* regular file */ |
| 948 | S_ISSOCK(st_mode m) /* socket */ |
| 949 | |
| 950 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 951 | |
| 952 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 953 | Upon successful completion, the value 0 is returned; otherwise the |
| 954 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 955 | error. |
| 956 | |
| 957 | E\bER\bRR\bRO\bOR\bRS\bS |
| 958 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 959 | |
| 960 | [ENOTDIR] A component of the path prefix is not a directory. |
| 961 | |
| 962 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 963 | characters, or an entire pathname (including the |
| 964 | terminating NUL) exceeded PATH_MAX bytes. |
| 965 | |
| 966 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 967 | empty path. |
| 968 | |
| 969 | [EACCES] Search permission is denied for a component of the |
| 970 | path prefix. |
| 971 | |
| 972 | [ELOOP] Too many symbolic links were encountered in |
| 973 | translating the pathname. |
| 974 | |
| 975 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 976 | |
| 977 | [EIO] An I/O error occurred while reading from or writing to |
| 978 | the file system. |
| 979 | |
| 980 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 981 | |
| 982 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 983 | AT_SYMLINK_NOFOLLOW. |
| 984 | |
| 985 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 986 | argument is neither AT_FDCWD nor a valid file |
| 987 | descriptor. |
| 988 | |
| 989 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 990 | argument is a valid file descriptor but it does not |
| 991 | reference a directory. |
| 992 | |
| 993 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 994 | permission is denied for the directory which the _\bf_\bd |
| 995 | file descriptor references. |
| 996 | |
| 997 | f\bfs\bst\bta\bat\bt() will fail if: |
| 998 | |
| 999 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 1000 | |
| 1001 | [EFAULT] _\bs_\bb points to an invalid address. |
| 1002 | |
| 1003 | [EIO] An I/O error occurred while reading from the file |
| 1004 | system. |
| 1005 | |
| 1006 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 1007 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 1008 | |
| 1009 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 1010 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 1011 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 1012 | |
| 1013 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 1014 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 1015 | |
| 1016 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 1017 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 1018 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 1019 | in Version 7 AT&T UNIX. |
| 1020 | |
| 1021 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 1022 | appeared in OpenBSD 5.0. |
| 1023 | |
| 1024 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 1025 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 1026 | |
| 1027 | Certain programs written when the timestamps were just of type time_t |
| 1028 | assumed that the members were consecutive (and could therefore be treated |
| 1029 | as an array and have their address passed directly to utime(3)). The |
| 1030 | transition to timestamps of type struct timespec broke them irrevocably. |
| 1031 | |
| 1032 | B\bBU\bUG\bGS\bS |
| 1033 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 1034 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 1035 | the time fields. |
| 1036 | |
| 1037 | N\bNA\bAM\bME\bE |
| 1038 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 1039 | |
| 1040 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 1041 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 1042 | |
| 1043 | _\bi_\bn_\bt |
| 1044 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1045 | |
| 1046 | _\bi_\bn_\bt |
| 1047 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1048 | |
| 1049 | _\bi_\bn_\bt |
| 1050 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1051 | |
| 1052 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 1053 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 1054 | |
| 1055 | _\bi_\bn_\bt |
| 1056 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 1057 | |
| 1058 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 1059 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 1060 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 1061 | required, but all directories listed in the path name leading to the file |
| 1062 | must be searchable. |
| 1063 | |
| 1064 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 1065 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 1066 | itself, not the file the link references. |
| 1067 | |
| 1068 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 1069 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 1070 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 1071 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 1072 | instead of the current working directory. |
| 1073 | |
| 1074 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 1075 | in the _\bf_\bd parameter, the current working directory is used and the |
| 1076 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 1077 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 1078 | |
| 1079 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 1080 | values: |
| 1081 | |
| 1082 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 1083 | of the symbolic link is returned. |
| 1084 | |
| 1085 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 1086 | known by the file descriptor _\bf_\bd. |
| 1087 | |
| 1088 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 1089 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 1090 | concerning the file. |
| 1091 | |
| 1092 | struct stat { |
| 1093 | dev_t st_dev; /* inode's device */ |
| 1094 | ino_t st_ino; /* inode's number */ |
| 1095 | mode_t st_mode; /* inode protection mode */ |
| 1096 | nlink_t st_nlink; /* number of hard links */ |
| 1097 | uid_t st_uid; /* user ID of the file's owner */ |
| 1098 | gid_t st_gid; /* group ID of the file's group */ |
| 1099 | dev_t st_rdev; /* device type */ |
| 1100 | struct timespec st_atim; /* time of last access */ |
| 1101 | struct timespec st_mtim; /* time of last data modification */ |
| 1102 | struct timespec st_ctim; /* time of last file status change */ |
| 1103 | off_t st_size; /* file size, in bytes */ |
| 1104 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 1105 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 1106 | u_int32_t st_flags; /* user defined flags for file */ |
| 1107 | u_int32_t st_gen; /* file generation number */ |
| 1108 | }; |
| 1109 | |
| 1110 | The time-related fields of struct stat are represented in struct timespec |
| 1111 | format, which has nanosecond precision. However, the actual precision is |
| 1112 | generally limited by the file system holding the file. The fields are as |
| 1113 | follows: |
| 1114 | |
| 1115 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 1116 | system object was created and updated by the utimes(2) and |
| 1117 | read(2) system calls. |
| 1118 | |
| 1119 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 1120 | truncate(2), utimes(2), and write(2) system calls. For |
| 1121 | directories, changed by any system call that alters which |
| 1122 | files are in the directory, such as the unlink(2), rename(2), |
| 1123 | mkdir(2), and symlink(2) system calls. |
| 1124 | |
| 1125 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 1126 | modification). Changed by the chmod(2), chown(2), link(2), |
| 1127 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 1128 | |
| 1129 | In addition, all the time fields are set to the current time when a file |
| 1130 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 1131 | open(2), and symlink(2) system calls. |
| 1132 | |
| 1133 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 1134 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 1135 | respective struct timespec member. Deprecated macros are also provided |
| 1136 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 1137 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 1138 | |
| 1139 | The size-related fields of the struct stat are as follows: |
| 1140 | |
| 1141 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 1142 | |
| 1143 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 1144 | 512-byte units. As short symbolic links are stored in the |
| 1145 | inode, this number may be zero. |
| 1146 | |
| 1147 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 1148 | |
| 1149 | #define S_IFMT 0170000 /* type of file mask */ |
| 1150 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 1151 | #define S_IFCHR 0020000 /* character special */ |
| 1152 | #define S_IFDIR 0040000 /* directory */ |
| 1153 | #define S_IFBLK 0060000 /* block special */ |
| 1154 | #define S_IFREG 0100000 /* regular */ |
| 1155 | #define S_IFLNK 0120000 /* symbolic link */ |
| 1156 | #define S_IFSOCK 0140000 /* socket */ |
| 1157 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 1158 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 1159 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 1160 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 1161 | #define S_IRUSR 0000400 /* R for owner */ |
| 1162 | #define S_IWUSR 0000200 /* W for owner */ |
| 1163 | #define S_IXUSR 0000100 /* X for owner */ |
| 1164 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 1165 | #define S_IRGRP 0000040 /* R for group */ |
| 1166 | #define S_IWGRP 0000020 /* W for group */ |
| 1167 | #define S_IXGRP 0000010 /* X for group */ |
| 1168 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 1169 | #define S_IROTH 0000004 /* R for other */ |
| 1170 | #define S_IWOTH 0000002 /* W for other */ |
| 1171 | #define S_IXOTH 0000001 /* X for other */ |
| 1172 | |
| 1173 | The following macros test a file's type. If the file is of that type, a |
| 1174 | non-zero value is returned; otherwise, 0 is returned. |
| 1175 | |
| 1176 | S_ISBLK(st_mode m) /* block special */ |
| 1177 | S_ISCHR(st_mode m) /* char special */ |
| 1178 | S_ISDIR(st_mode m) /* directory */ |
| 1179 | S_ISFIFO(st_mode m) /* fifo */ |
| 1180 | S_ISLNK(st_mode m) /* symbolic link */ |
| 1181 | S_ISREG(st_mode m) /* regular file */ |
| 1182 | S_ISSOCK(st_mode m) /* socket */ |
| 1183 | |
| 1184 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 1185 | |
| 1186 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 1187 | Upon successful completion, the value 0 is returned; otherwise the |
| 1188 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 1189 | error. |
| 1190 | |
| 1191 | E\bER\bRR\bRO\bOR\bRS\bS |
| 1192 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 1193 | |
| 1194 | [ENOTDIR] A component of the path prefix is not a directory. |
| 1195 | |
| 1196 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 1197 | characters, or an entire pathname (including the |
| 1198 | terminating NUL) exceeded PATH_MAX bytes. |
| 1199 | |
| 1200 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 1201 | empty path. |
| 1202 | |
| 1203 | [EACCES] Search permission is denied for a component of the |
| 1204 | path prefix. |
| 1205 | |
| 1206 | [ELOOP] Too many symbolic links were encountered in |
| 1207 | translating the pathname. |
| 1208 | |
| 1209 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 1210 | |
| 1211 | [EIO] An I/O error occurred while reading from or writing to |
| 1212 | the file system. |
| 1213 | |
| 1214 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 1215 | |
| 1216 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 1217 | AT_SYMLINK_NOFOLLOW. |
| 1218 | |
| 1219 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 1220 | argument is neither AT_FDCWD nor a valid file |
| 1221 | descriptor. |
| 1222 | |
| 1223 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 1224 | argument is a valid file descriptor but it does not |
| 1225 | reference a directory. |
| 1226 | |
| 1227 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 1228 | permission is denied for the directory which the _\bf_\bd |
| 1229 | file descriptor references. |
| 1230 | |
| 1231 | f\bfs\bst\bta\bat\bt() will fail if: |
| 1232 | |
| 1233 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 1234 | |
| 1235 | [EFAULT] _\bs_\bb points to an invalid address. |
| 1236 | |
| 1237 | [EIO] An I/O error occurred while reading from the file |
| 1238 | system. |
| 1239 | |
| 1240 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 1241 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 1242 | |
| 1243 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 1244 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 1245 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 1246 | |
| 1247 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 1248 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 1249 | |
| 1250 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 1251 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 1252 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 1253 | in Version 7 AT&T UNIX. |
| 1254 | |
| 1255 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 1256 | appeared in OpenBSD 5.0. |
| 1257 | |
| 1258 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 1259 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 1260 | |
| 1261 | Certain programs written when the timestamps were just of type time_t |
| 1262 | assumed that the members were consecutive (and could therefore be treated |
| 1263 | as an array and have their address passed directly to utime(3)). The |
| 1264 | transition to timestamps of type struct timespec broke them irrevocably. |
| 1265 | |
| 1266 | B\bBU\bUG\bGS\bS |
| 1267 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 1268 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 1269 | the time fields. |
| 1270 | |
| 1271 | N\bNA\bAM\bME\bE |
| 1272 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 1273 | |
| 1274 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 1275 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 1276 | |
| 1277 | _\bi_\bn_\bt |
| 1278 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1279 | |
| 1280 | _\bi_\bn_\bt |
| 1281 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1282 | |
| 1283 | _\bi_\bn_\bt |
| 1284 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1285 | |
| 1286 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 1287 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 1288 | |
| 1289 | _\bi_\bn_\bt |
| 1290 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 1291 | |
| 1292 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 1293 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 1294 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 1295 | required, but all directories listed in the path name leading to the file |
| 1296 | must be searchable. |
| 1297 | |
| 1298 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 1299 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 1300 | itself, not the file the link references. |
| 1301 | |
| 1302 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 1303 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 1304 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 1305 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 1306 | instead of the current working directory. |
| 1307 | |
| 1308 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 1309 | in the _\bf_\bd parameter, the current working directory is used and the |
| 1310 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 1311 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 1312 | |
| 1313 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 1314 | values: |
| 1315 | |
| 1316 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 1317 | of the symbolic link is returned. |
| 1318 | |
| 1319 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 1320 | known by the file descriptor _\bf_\bd. |
| 1321 | |
| 1322 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 1323 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 1324 | concerning the file. |
| 1325 | |
| 1326 | struct stat { |
| 1327 | dev_t st_dev; /* inode's device */ |
| 1328 | ino_t st_ino; /* inode's number */ |
| 1329 | mode_t st_mode; /* inode protection mode */ |
| 1330 | nlink_t st_nlink; /* number of hard links */ |
| 1331 | uid_t st_uid; /* user ID of the file's owner */ |
| 1332 | gid_t st_gid; /* group ID of the file's group */ |
| 1333 | dev_t st_rdev; /* device type */ |
| 1334 | struct timespec st_atim; /* time of last access */ |
| 1335 | struct timespec st_mtim; /* time of last data modification */ |
| 1336 | struct timespec st_ctim; /* time of last file status change */ |
| 1337 | off_t st_size; /* file size, in bytes */ |
| 1338 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 1339 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 1340 | u_int32_t st_flags; /* user defined flags for file */ |
| 1341 | u_int32_t st_gen; /* file generation number */ |
| 1342 | }; |
| 1343 | |
| 1344 | The time-related fields of struct stat are represented in struct timespec |
| 1345 | format, which has nanosecond precision. However, the actual precision is |
| 1346 | generally limited by the file system holding the file. The fields are as |
| 1347 | follows: |
| 1348 | |
| 1349 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 1350 | system object was created and updated by the utimes(2) and |
| 1351 | read(2) system calls. |
| 1352 | |
| 1353 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 1354 | truncate(2), utimes(2), and write(2) system calls. For |
| 1355 | directories, changed by any system call that alters which |
| 1356 | files are in the directory, such as the unlink(2), rename(2), |
| 1357 | mkdir(2), and symlink(2) system calls. |
| 1358 | |
| 1359 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 1360 | modification). Changed by the chmod(2), chown(2), link(2), |
| 1361 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 1362 | |
| 1363 | In addition, all the time fields are set to the current time when a file |
| 1364 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 1365 | open(2), and symlink(2) system calls. |
| 1366 | |
| 1367 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 1368 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 1369 | respective struct timespec member. Deprecated macros are also provided |
| 1370 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 1371 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 1372 | |
| 1373 | The size-related fields of the struct stat are as follows: |
| 1374 | |
| 1375 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 1376 | |
| 1377 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 1378 | 512-byte units. As short symbolic links are stored in the |
| 1379 | inode, this number may be zero. |
| 1380 | |
| 1381 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 1382 | |
| 1383 | #define S_IFMT 0170000 /* type of file mask */ |
| 1384 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 1385 | #define S_IFCHR 0020000 /* character special */ |
| 1386 | #define S_IFDIR 0040000 /* directory */ |
| 1387 | #define S_IFBLK 0060000 /* block special */ |
| 1388 | #define S_IFREG 0100000 /* regular */ |
| 1389 | #define S_IFLNK 0120000 /* symbolic link */ |
| 1390 | #define S_IFSOCK 0140000 /* socket */ |
| 1391 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 1392 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 1393 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 1394 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 1395 | #define S_IRUSR 0000400 /* R for owner */ |
| 1396 | #define S_IWUSR 0000200 /* W for owner */ |
| 1397 | #define S_IXUSR 0000100 /* X for owner */ |
| 1398 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 1399 | #define S_IRGRP 0000040 /* R for group */ |
| 1400 | #define S_IWGRP 0000020 /* W for group */ |
| 1401 | #define S_IXGRP 0000010 /* X for group */ |
| 1402 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 1403 | #define S_IROTH 0000004 /* R for other */ |
| 1404 | #define S_IWOTH 0000002 /* W for other */ |
| 1405 | #define S_IXOTH 0000001 /* X for other */ |
| 1406 | |
| 1407 | The following macros test a file's type. If the file is of that type, a |
| 1408 | non-zero value is returned; otherwise, 0 is returned. |
| 1409 | |
| 1410 | S_ISBLK(st_mode m) /* block special */ |
| 1411 | S_ISCHR(st_mode m) /* char special */ |
| 1412 | S_ISDIR(st_mode m) /* directory */ |
| 1413 | S_ISFIFO(st_mode m) /* fifo */ |
| 1414 | S_ISLNK(st_mode m) /* symbolic link */ |
| 1415 | S_ISREG(st_mode m) /* regular file */ |
| 1416 | S_ISSOCK(st_mode m) /* socket */ |
| 1417 | |
| 1418 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 1419 | |
| 1420 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 1421 | Upon successful completion, the value 0 is returned; otherwise the |
| 1422 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 1423 | error. |
| 1424 | |
| 1425 | E\bER\bRR\bRO\bOR\bRS\bS |
| 1426 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 1427 | |
| 1428 | [ENOTDIR] A component of the path prefix is not a directory. |
| 1429 | |
| 1430 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 1431 | characters, or an entire pathname (including the |
| 1432 | terminating NUL) exceeded PATH_MAX bytes. |
| 1433 | |
| 1434 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 1435 | empty path. |
| 1436 | |
| 1437 | [EACCES] Search permission is denied for a component of the |
| 1438 | path prefix. |
| 1439 | |
| 1440 | [ELOOP] Too many symbolic links were encountered in |
| 1441 | translating the pathname. |
| 1442 | |
| 1443 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 1444 | |
| 1445 | [EIO] An I/O error occurred while reading from or writing to |
| 1446 | the file system. |
| 1447 | |
| 1448 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 1449 | |
| 1450 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 1451 | AT_SYMLINK_NOFOLLOW. |
| 1452 | |
| 1453 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 1454 | argument is neither AT_FDCWD nor a valid file |
| 1455 | descriptor. |
| 1456 | |
| 1457 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 1458 | argument is a valid file descriptor but it does not |
| 1459 | reference a directory. |
| 1460 | |
| 1461 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 1462 | permission is denied for the directory which the _\bf_\bd |
| 1463 | file descriptor references. |
| 1464 | |
| 1465 | f\bfs\bst\bta\bat\bt() will fail if: |
| 1466 | |
| 1467 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 1468 | |
| 1469 | [EFAULT] _\bs_\bb points to an invalid address. |
| 1470 | |
| 1471 | [EIO] An I/O error occurred while reading from the file |
| 1472 | system. |
| 1473 | |
| 1474 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 1475 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 1476 | |
| 1477 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 1478 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 1479 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 1480 | |
| 1481 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 1482 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 1483 | |
| 1484 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 1485 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 1486 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 1487 | in Version 7 AT&T UNIX. |
| 1488 | |
| 1489 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 1490 | appeared in OpenBSD 5.0. |
| 1491 | |
| 1492 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 1493 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 1494 | |
| 1495 | Certain programs written when the timestamps were just of type time_t |
| 1496 | assumed that the members were consecutive (and could therefore be treated |
| 1497 | as an array and have their address passed directly to utime(3)). The |
| 1498 | transition to timestamps of type struct timespec broke them irrevocably. |
| 1499 | |
| 1500 | B\bBU\bUG\bGS\bS |
| 1501 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 1502 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 1503 | the time fields. |
| 1504 | |
| 1505 | N\bNA\bAM\bME\bE |
| 1506 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 1507 | |
| 1508 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 1509 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 1510 | |
| 1511 | _\bi_\bn_\bt |
| 1512 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1513 | |
| 1514 | _\bi_\bn_\bt |
| 1515 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1516 | |
| 1517 | _\bi_\bn_\bt |
| 1518 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1519 | |
| 1520 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 1521 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 1522 | |
| 1523 | _\bi_\bn_\bt |
| 1524 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 1525 | |
| 1526 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 1527 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 1528 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 1529 | required, but all directories listed in the path name leading to the file |
| 1530 | must be searchable. |
| 1531 | |
| 1532 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 1533 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 1534 | itself, not the file the link references. |
| 1535 | |
| 1536 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 1537 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 1538 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 1539 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 1540 | instead of the current working directory. |
| 1541 | |
| 1542 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 1543 | in the _\bf_\bd parameter, the current working directory is used and the |
| 1544 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 1545 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 1546 | |
| 1547 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 1548 | values: |
| 1549 | |
| 1550 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 1551 | of the symbolic link is returned. |
| 1552 | |
| 1553 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 1554 | known by the file descriptor _\bf_\bd. |
| 1555 | |
| 1556 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 1557 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 1558 | concerning the file. |
| 1559 | |
| 1560 | struct stat { |
| 1561 | dev_t st_dev; /* inode's device */ |
| 1562 | ino_t st_ino; /* inode's number */ |
| 1563 | mode_t st_mode; /* inode protection mode */ |
| 1564 | nlink_t st_nlink; /* number of hard links */ |
| 1565 | uid_t st_uid; /* user ID of the file's owner */ |
| 1566 | gid_t st_gid; /* group ID of the file's group */ |
| 1567 | dev_t st_rdev; /* device type */ |
| 1568 | struct timespec st_atim; /* time of last access */ |
| 1569 | struct timespec st_mtim; /* time of last data modification */ |
| 1570 | struct timespec st_ctim; /* time of last file status change */ |
| 1571 | off_t st_size; /* file size, in bytes */ |
| 1572 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 1573 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 1574 | u_int32_t st_flags; /* user defined flags for file */ |
| 1575 | u_int32_t st_gen; /* file generation number */ |
| 1576 | }; |
| 1577 | |
| 1578 | The time-related fields of struct stat are represented in struct timespec |
| 1579 | format, which has nanosecond precision. However, the actual precision is |
| 1580 | generally limited by the file system holding the file. The fields are as |
| 1581 | follows: |
| 1582 | |
| 1583 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 1584 | system object was created and updated by the utimes(2) and |
| 1585 | read(2) system calls. |
| 1586 | |
| 1587 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 1588 | truncate(2), utimes(2), and write(2) system calls. For |
| 1589 | directories, changed by any system call that alters which |
| 1590 | files are in the directory, such as the unlink(2), rename(2), |
| 1591 | mkdir(2), and symlink(2) system calls. |
| 1592 | |
| 1593 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 1594 | modification). Changed by the chmod(2), chown(2), link(2), |
| 1595 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 1596 | |
| 1597 | In addition, all the time fields are set to the current time when a file |
| 1598 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 1599 | open(2), and symlink(2) system calls. |
| 1600 | |
| 1601 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 1602 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 1603 | respective struct timespec member. Deprecated macros are also provided |
| 1604 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 1605 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 1606 | |
| 1607 | The size-related fields of the struct stat are as follows: |
| 1608 | |
| 1609 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 1610 | |
| 1611 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 1612 | 512-byte units. As short symbolic links are stored in the |
| 1613 | inode, this number may be zero. |
| 1614 | |
| 1615 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 1616 | |
| 1617 | #define S_IFMT 0170000 /* type of file mask */ |
| 1618 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 1619 | #define S_IFCHR 0020000 /* character special */ |
| 1620 | #define S_IFDIR 0040000 /* directory */ |
| 1621 | #define S_IFBLK 0060000 /* block special */ |
| 1622 | #define S_IFREG 0100000 /* regular */ |
| 1623 | #define S_IFLNK 0120000 /* symbolic link */ |
| 1624 | #define S_IFSOCK 0140000 /* socket */ |
| 1625 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 1626 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 1627 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 1628 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 1629 | #define S_IRUSR 0000400 /* R for owner */ |
| 1630 | #define S_IWUSR 0000200 /* W for owner */ |
| 1631 | #define S_IXUSR 0000100 /* X for owner */ |
| 1632 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 1633 | #define S_IRGRP 0000040 /* R for group */ |
| 1634 | #define S_IWGRP 0000020 /* W for group */ |
| 1635 | #define S_IXGRP 0000010 /* X for group */ |
| 1636 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 1637 | #define S_IROTH 0000004 /* R for other */ |
| 1638 | #define S_IWOTH 0000002 /* W for other */ |
| 1639 | #define S_IXOTH 0000001 /* X for other */ |
| 1640 | |
| 1641 | The following macros test a file's type. If the file is of that type, a |
| 1642 | non-zero value is returned; otherwise, 0 is returned. |
| 1643 | |
| 1644 | S_ISBLK(st_mode m) /* block special */ |
| 1645 | S_ISCHR(st_mode m) /* char special */ |
| 1646 | S_ISDIR(st_mode m) /* directory */ |
| 1647 | S_ISFIFO(st_mode m) /* fifo */ |
| 1648 | S_ISLNK(st_mode m) /* symbolic link */ |
| 1649 | S_ISREG(st_mode m) /* regular file */ |
| 1650 | S_ISSOCK(st_mode m) /* socket */ |
| 1651 | |
| 1652 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 1653 | |
| 1654 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 1655 | Upon successful completion, the value 0 is returned; otherwise the |
| 1656 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 1657 | error. |
| 1658 | |
| 1659 | E\bER\bRR\bRO\bOR\bRS\bS |
| 1660 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 1661 | |
| 1662 | [ENOTDIR] A component of the path prefix is not a directory. |
| 1663 | |
| 1664 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 1665 | characters, or an entire pathname (including the |
| 1666 | terminating NUL) exceeded PATH_MAX bytes. |
| 1667 | |
| 1668 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 1669 | empty path. |
| 1670 | |
| 1671 | [EACCES] Search permission is denied for a component of the |
| 1672 | path prefix. |
| 1673 | |
| 1674 | [ELOOP] Too many symbolic links were encountered in |
| 1675 | translating the pathname. |
| 1676 | |
| 1677 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 1678 | |
| 1679 | [EIO] An I/O error occurred while reading from or writing to |
| 1680 | the file system. |
| 1681 | |
| 1682 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 1683 | |
| 1684 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 1685 | AT_SYMLINK_NOFOLLOW. |
| 1686 | |
| 1687 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 1688 | argument is neither AT_FDCWD nor a valid file |
| 1689 | descriptor. |
| 1690 | |
| 1691 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 1692 | argument is a valid file descriptor but it does not |
| 1693 | reference a directory. |
| 1694 | |
| 1695 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 1696 | permission is denied for the directory which the _\bf_\bd |
| 1697 | file descriptor references. |
| 1698 | |
| 1699 | f\bfs\bst\bta\bat\bt() will fail if: |
| 1700 | |
| 1701 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 1702 | |
| 1703 | [EFAULT] _\bs_\bb points to an invalid address. |
| 1704 | |
| 1705 | [EIO] An I/O error occurred while reading from the file |
| 1706 | system. |
| 1707 | |
| 1708 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 1709 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 1710 | |
| 1711 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 1712 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 1713 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 1714 | |
| 1715 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 1716 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 1717 | |
| 1718 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 1719 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 1720 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 1721 | in Version 7 AT&T UNIX. |
| 1722 | |
| 1723 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 1724 | appeared in OpenBSD 5.0. |
| 1725 | |
| 1726 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 1727 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 1728 | |
| 1729 | Certain programs written when the timestamps were just of type time_t |
| 1730 | assumed that the members were consecutive (and could therefore be treated |
| 1731 | as an array and have their address passed directly to utime(3)). The |
| 1732 | transition to timestamps of type struct timespec broke them irrevocably. |
| 1733 | |
| 1734 | B\bBU\bUG\bGS\bS |
| 1735 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 1736 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 1737 | the time fields. |
| 1738 | |
| 1739 | N\bNA\bAM\bME\bE |
| 1740 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 1741 | |
| 1742 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 1743 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 1744 | |
| 1745 | _\bi_\bn_\bt |
| 1746 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1747 | |
| 1748 | _\bi_\bn_\bt |
| 1749 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1750 | |
| 1751 | _\bi_\bn_\bt |
| 1752 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 1753 | |
| 1754 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 1755 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 1756 | |
| 1757 | _\bi_\bn_\bt |
| 1758 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 1759 | |
| 1760 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 1761 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 1762 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 1763 | required, but all directories listed in the path name leading to the file |
| 1764 | must be searchable. |
| 1765 | |
| 1766 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 1767 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 1768 | itself, not the file the link references. |
| 1769 | |
| 1770 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 1771 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 1772 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 1773 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 1774 | instead of the current working directory. |
| 1775 | |
| 1776 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 1777 | in the _\bf_\bd parameter, the current working directory is used and the |
| 1778 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 1779 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 1780 | |
| 1781 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 1782 | values: |
| 1783 | |
| 1784 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 1785 | of the symbolic link is returned. |
| 1786 | |
| 1787 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 1788 | known by the file descriptor _\bf_\bd. |
| 1789 | |
| 1790 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 1791 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 1792 | concerning the file. |
| 1793 | |
| 1794 | struct stat { |
| 1795 | dev_t st_dev; /* inode's device */ |
| 1796 | ino_t st_ino; /* inode's number */ |
| 1797 | mode_t st_mode; /* inode protection mode */ |
| 1798 | nlink_t st_nlink; /* number of hard links */ |
| 1799 | uid_t st_uid; /* user ID of the file's owner */ |
| 1800 | gid_t st_gid; /* group ID of the file's group */ |
| 1801 | dev_t st_rdev; /* device type */ |
| 1802 | struct timespec st_atim; /* time of last access */ |
| 1803 | struct timespec st_mtim; /* time of last data modification */ |
| 1804 | struct timespec st_ctim; /* time of last file status change */ |
| 1805 | off_t st_size; /* file size, in bytes */ |
| 1806 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 1807 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 1808 | u_int32_t st_flags; /* user defined flags for file */ |
| 1809 | u_int32_t st_gen; /* file generation number */ |
| 1810 | }; |
| 1811 | |
| 1812 | The time-related fields of struct stat are represented in struct timespec |
| 1813 | format, which has nanosecond precision. However, the actual precision is |
| 1814 | generally limited by the file system holding the file. The fields are as |
| 1815 | follows: |
| 1816 | |
| 1817 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 1818 | system object was created and updated by the utimes(2) and |
| 1819 | read(2) system calls. |
| 1820 | |
| 1821 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 1822 | truncate(2), utimes(2), and write(2) system calls. For |
| 1823 | directories, changed by any system call that alters which |
| 1824 | files are in the directory, such as the unlink(2), rename(2), |
| 1825 | mkdir(2), and symlink(2) system calls. |
| 1826 | |
| 1827 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 1828 | modification). Changed by the chmod(2), chown(2), link(2), |
| 1829 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 1830 | |
| 1831 | In addition, all the time fields are set to the current time when a file |
| 1832 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 1833 | open(2), and symlink(2) system calls. |
| 1834 | |
| 1835 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 1836 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 1837 | respective struct timespec member. Deprecated macros are also provided |
| 1838 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 1839 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 1840 | |
| 1841 | The size-related fields of the struct stat are as follows: |
| 1842 | |
| 1843 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 1844 | |
| 1845 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 1846 | 512-byte units. As short symbolic links are stored in the |
| 1847 | inode, this number may be zero. |
| 1848 | |
| 1849 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 1850 | |
| 1851 | #define S_IFMT 0170000 /* type of file mask */ |
| 1852 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 1853 | #define S_IFCHR 0020000 /* character special */ |
| 1854 | #define S_IFDIR 0040000 /* directory */ |
| 1855 | #define S_IFBLK 0060000 /* block special */ |
| 1856 | #define S_IFREG 0100000 /* regular */ |
| 1857 | #define S_IFLNK 0120000 /* symbolic link */ |
| 1858 | #define S_IFSOCK 0140000 /* socket */ |
| 1859 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 1860 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 1861 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 1862 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 1863 | #define S_IRUSR 0000400 /* R for owner */ |
| 1864 | #define S_IWUSR 0000200 /* W for owner */ |
| 1865 | #define S_IXUSR 0000100 /* X for owner */ |
| 1866 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 1867 | #define S_IRGRP 0000040 /* R for group */ |
| 1868 | #define S_IWGRP 0000020 /* W for group */ |
| 1869 | #define S_IXGRP 0000010 /* X for group */ |
| 1870 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 1871 | #define S_IROTH 0000004 /* R for other */ |
| 1872 | #define S_IWOTH 0000002 /* W for other */ |
| 1873 | #define S_IXOTH 0000001 /* X for other */ |
| 1874 | |
| 1875 | The following macros test a file's type. If the file is of that type, a |
| 1876 | non-zero value is returned; otherwise, 0 is returned. |
| 1877 | |
| 1878 | S_ISBLK(st_mode m) /* block special */ |
| 1879 | S_ISCHR(st_mode m) /* char special */ |
| 1880 | S_ISDIR(st_mode m) /* directory */ |
| 1881 | S_ISFIFO(st_mode m) /* fifo */ |
| 1882 | S_ISLNK(st_mode m) /* symbolic link */ |
| 1883 | S_ISREG(st_mode m) /* regular file */ |
| 1884 | S_ISSOCK(st_mode m) /* socket */ |
| 1885 | |
| 1886 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 1887 | |
| 1888 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 1889 | Upon successful completion, the value 0 is returned; otherwise the |
| 1890 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 1891 | error. |
| 1892 | |
| 1893 | E\bER\bRR\bRO\bOR\bRS\bS |
| 1894 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 1895 | |
| 1896 | [ENOTDIR] A component of the path prefix is not a directory. |
| 1897 | |
| 1898 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 1899 | characters, or an entire pathname (including the |
| 1900 | terminating NUL) exceeded PATH_MAX bytes. |
| 1901 | |
| 1902 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 1903 | empty path. |
| 1904 | |
| 1905 | [EACCES] Search permission is denied for a component of the |
| 1906 | path prefix. |
| 1907 | |
| 1908 | [ELOOP] Too many symbolic links were encountered in |
| 1909 | translating the pathname. |
| 1910 | |
| 1911 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 1912 | |
| 1913 | [EIO] An I/O error occurred while reading from or writing to |
| 1914 | the file system. |
| 1915 | |
| 1916 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 1917 | |
| 1918 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 1919 | AT_SYMLINK_NOFOLLOW. |
| 1920 | |
| 1921 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 1922 | argument is neither AT_FDCWD nor a valid file |
| 1923 | descriptor. |
| 1924 | |
| 1925 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 1926 | argument is a valid file descriptor but it does not |
| 1927 | reference a directory. |
| 1928 | |
| 1929 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 1930 | permission is denied for the directory which the _\bf_\bd |
| 1931 | file descriptor references. |
| 1932 | |
| 1933 | f\bfs\bst\bta\bat\bt() will fail if: |
| 1934 | |
| 1935 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 1936 | |
| 1937 | [EFAULT] _\bs_\bb points to an invalid address. |
| 1938 | |
| 1939 | [EIO] An I/O error occurred while reading from the file |
| 1940 | system. |
| 1941 | |
| 1942 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 1943 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 1944 | |
| 1945 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 1946 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 1947 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 1948 | |
| 1949 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 1950 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 1951 | |
| 1952 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 1953 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 1954 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 1955 | in Version 7 AT&T UNIX. |
| 1956 | |
| 1957 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 1958 | appeared in OpenBSD 5.0. |
| 1959 | |
| 1960 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 1961 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 1962 | |
| 1963 | Certain programs written when the timestamps were just of type time_t |
| 1964 | assumed that the members were consecutive (and could therefore be treated |
| 1965 | as an array and have their address passed directly to utime(3)). The |
| 1966 | transition to timestamps of type struct timespec broke them irrevocably. |
| 1967 | |
| 1968 | B\bBU\bUG\bGS\bS |
| 1969 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 1970 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 1971 | the time fields. |
| 1972 | |
| 1973 | N\bNA\bAM\bME\bE |
| 1974 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 1975 | |
| 1976 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 1977 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 1978 | |
| 1979 | _\bp_\bi_\bd_\b__\bt |
| 1980 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 1981 | |
| 1982 | _\bp_\bi_\bd_\b__\bt |
| 1983 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 1984 | |
| 1985 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 1986 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 1987 | |
| 1988 | _\bp_\bi_\bd_\b__\bt |
| 1989 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 1990 | |
| 1991 | _\bp_\bi_\bd_\b__\bt |
| 1992 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 1993 | |
| 1994 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 1995 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 1996 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 1997 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 1998 | area, if non-zero, is filled in with termination information about the |
| 1999 | process that exited (see below). |
| 2000 | |
| 2001 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 2002 | to wait for certain child processes, that need resource utilization |
| 2003 | statistics accumulated by child processes, or that require options. The |
| 2004 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 2005 | |
| 2006 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 2007 | wait. The following symbolic constants are currently defined in |
| 2008 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 2009 | |
| 2010 | #define WAIT_ANY (-1) /* any process */ |
| 2011 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 2012 | |
| 2013 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 2014 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 2015 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 2016 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 2017 | call waits for any process whose process group ID equals the absolute |
| 2018 | value of _\bw_\bp_\bi_\bd. |
| 2019 | |
| 2020 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 2021 | bitwise OR of zero or more of the following values: |
| 2022 | |
| 2023 | WCONTINUED Causes status to be reported for stopped child processes that |
| 2024 | have been continued by receipt of a SIGCONT signal. |
| 2025 | |
| 2026 | WNOHANG Indicates that the call should not block if there are no |
| 2027 | processes that wish to report status. |
| 2028 | |
| 2029 | WUNTRACED If set, children of the current process that are stopped due |
| 2030 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 2031 | their status reported. |
| 2032 | |
| 2033 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 2034 | process and all its children is returned (this information is currently |
| 2035 | not available for stopped processes). |
| 2036 | |
| 2037 | When the WNOHANG option is specified and no processes wish to report |
| 2038 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 2039 | |
| 2040 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 2041 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 2042 | |
| 2043 | The following macros may be used to test the manner of exit of the |
| 2044 | process. One of the first three macros will evaluate to a non-zero |
| 2045 | (true) value: |
| 2046 | |
| 2047 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2048 | True if the process has not terminated, and has continued after a |
| 2049 | job control stop. This macro can be true only if the wait call |
| 2050 | specified the WCONTINUED option. |
| 2051 | |
| 2052 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2053 | True if the process terminated normally by a call to _exit(2) or |
| 2054 | exit(3). |
| 2055 | |
| 2056 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2057 | True if the process terminated due to receipt of a signal. |
| 2058 | |
| 2059 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2060 | True if the process has not terminated, but has stopped and can |
| 2061 | be restarted. This macro can be true only if the wait call |
| 2062 | specified the WUNTRACED option or if the child process is being |
| 2063 | traced (see ptrace(2)). |
| 2064 | |
| 2065 | Depending on the values of those macros, the following macros produce the |
| 2066 | remaining status information about the child process: |
| 2067 | |
| 2068 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2069 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 2070 | of the argument passed to _exit(2) or exit(3) by the child. |
| 2071 | |
| 2072 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2073 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2074 | signal that caused the termination of the process. |
| 2075 | |
| 2076 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2077 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 2078 | termination of the process was accompanied by the creation of a |
| 2079 | core file containing an image of the process when the signal was |
| 2080 | received. |
| 2081 | |
| 2082 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2083 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2084 | signal that caused the process to stop. |
| 2085 | |
| 2086 | N\bNO\bOT\bTE\bES\bS |
| 2087 | See sigaction(2) for a list of termination signals. A status of 0 |
| 2088 | indicates normal termination. |
| 2089 | |
| 2090 | If a parent process terminates without waiting for all of its child |
| 2091 | processes to terminate, the remaining child processes are assigned the |
| 2092 | parent process 1 ID (the init process ID). |
| 2093 | |
| 2094 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 2095 | may be interrupted or restarted when the signal-catching routine returns, |
| 2096 | depending on the options in effect for the signal; for further |
| 2097 | information, see siginterrupt(3). |
| 2098 | |
| 2099 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 2100 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 2101 | process ID of the child is returned to the calling process. Otherwise, a |
| 2102 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2103 | |
| 2104 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 2105 | child process, the process ID of the child is returned to the calling |
| 2106 | process. If there are no children not previously awaited, -1 is returned |
| 2107 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 2108 | are no stopped or exited children, 0 is returned. If an error is |
| 2109 | detected or a caught signal aborts the call, a value of -1 is returned |
| 2110 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2111 | |
| 2112 | E\bER\bRR\bRO\bOR\bRS\bS |
| 2113 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 2114 | |
| 2115 | [ECHILD] The calling process has no existing unwaited-for child |
| 2116 | processes. |
| 2117 | |
| 2118 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 2119 | address. (May not be detected before exit of a child |
| 2120 | process.) |
| 2121 | |
| 2122 | [EINTR] The call was interrupted by a caught signal, or the |
| 2123 | signal did not have the SA_RESTART flag set. |
| 2124 | |
| 2125 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 2126 | argument. |
| 2127 | |
| 2128 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 2129 | _exit(2), sigaction(2), exit(3) |
| 2130 | |
| 2131 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 2132 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 2133 | (``POSIX.1''). |
| 2134 | |
| 2135 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 2136 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 2137 | specification. |
| 2138 | |
| 2139 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 2140 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 2141 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 2142 | first appeared in 4BSD, but the final calling convention was only |
| 2143 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 2144 | appeared in 4.3BSD-Reno. |
| 2145 | |
| 2146 | N\bNA\bAM\bME\bE |
| 2147 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 2148 | |
| 2149 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 2150 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2151 | |
| 2152 | _\bp_\bi_\bd_\b__\bt |
| 2153 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 2154 | |
| 2155 | _\bp_\bi_\bd_\b__\bt |
| 2156 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 2157 | |
| 2158 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 2159 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2160 | |
| 2161 | _\bp_\bi_\bd_\b__\bt |
| 2162 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2163 | |
| 2164 | _\bp_\bi_\bd_\b__\bt |
| 2165 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2166 | |
| 2167 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 2168 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 2169 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 2170 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 2171 | area, if non-zero, is filled in with termination information about the |
| 2172 | process that exited (see below). |
| 2173 | |
| 2174 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 2175 | to wait for certain child processes, that need resource utilization |
| 2176 | statistics accumulated by child processes, or that require options. The |
| 2177 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 2178 | |
| 2179 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 2180 | wait. The following symbolic constants are currently defined in |
| 2181 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 2182 | |
| 2183 | #define WAIT_ANY (-1) /* any process */ |
| 2184 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 2185 | |
| 2186 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 2187 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 2188 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 2189 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 2190 | call waits for any process whose process group ID equals the absolute |
| 2191 | value of _\bw_\bp_\bi_\bd. |
| 2192 | |
| 2193 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 2194 | bitwise OR of zero or more of the following values: |
| 2195 | |
| 2196 | WCONTINUED Causes status to be reported for stopped child processes that |
| 2197 | have been continued by receipt of a SIGCONT signal. |
| 2198 | |
| 2199 | WNOHANG Indicates that the call should not block if there are no |
| 2200 | processes that wish to report status. |
| 2201 | |
| 2202 | WUNTRACED If set, children of the current process that are stopped due |
| 2203 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 2204 | their status reported. |
| 2205 | |
| 2206 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 2207 | process and all its children is returned (this information is currently |
| 2208 | not available for stopped processes). |
| 2209 | |
| 2210 | When the WNOHANG option is specified and no processes wish to report |
| 2211 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 2212 | |
| 2213 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 2214 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 2215 | |
| 2216 | The following macros may be used to test the manner of exit of the |
| 2217 | process. One of the first three macros will evaluate to a non-zero |
| 2218 | (true) value: |
| 2219 | |
| 2220 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2221 | True if the process has not terminated, and has continued after a |
| 2222 | job control stop. This macro can be true only if the wait call |
| 2223 | specified the WCONTINUED option. |
| 2224 | |
| 2225 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2226 | True if the process terminated normally by a call to _exit(2) or |
| 2227 | exit(3). |
| 2228 | |
| 2229 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2230 | True if the process terminated due to receipt of a signal. |
| 2231 | |
| 2232 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2233 | True if the process has not terminated, but has stopped and can |
| 2234 | be restarted. This macro can be true only if the wait call |
| 2235 | specified the WUNTRACED option or if the child process is being |
| 2236 | traced (see ptrace(2)). |
| 2237 | |
| 2238 | Depending on the values of those macros, the following macros produce the |
| 2239 | remaining status information about the child process: |
| 2240 | |
| 2241 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2242 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 2243 | of the argument passed to _exit(2) or exit(3) by the child. |
| 2244 | |
| 2245 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2246 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2247 | signal that caused the termination of the process. |
| 2248 | |
| 2249 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2250 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 2251 | termination of the process was accompanied by the creation of a |
| 2252 | core file containing an image of the process when the signal was |
| 2253 | received. |
| 2254 | |
| 2255 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2256 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2257 | signal that caused the process to stop. |
| 2258 | |
| 2259 | N\bNO\bOT\bTE\bES\bS |
| 2260 | See sigaction(2) for a list of termination signals. A status of 0 |
| 2261 | indicates normal termination. |
| 2262 | |
| 2263 | If a parent process terminates without waiting for all of its child |
| 2264 | processes to terminate, the remaining child processes are assigned the |
| 2265 | parent process 1 ID (the init process ID). |
| 2266 | |
| 2267 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 2268 | may be interrupted or restarted when the signal-catching routine returns, |
| 2269 | depending on the options in effect for the signal; for further |
| 2270 | information, see siginterrupt(3). |
| 2271 | |
| 2272 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 2273 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 2274 | process ID of the child is returned to the calling process. Otherwise, a |
| 2275 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2276 | |
| 2277 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 2278 | child process, the process ID of the child is returned to the calling |
| 2279 | process. If there are no children not previously awaited, -1 is returned |
| 2280 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 2281 | are no stopped or exited children, 0 is returned. If an error is |
| 2282 | detected or a caught signal aborts the call, a value of -1 is returned |
| 2283 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2284 | |
| 2285 | E\bER\bRR\bRO\bOR\bRS\bS |
| 2286 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 2287 | |
| 2288 | [ECHILD] The calling process has no existing unwaited-for child |
| 2289 | processes. |
| 2290 | |
| 2291 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 2292 | address. (May not be detected before exit of a child |
| 2293 | process.) |
| 2294 | |
| 2295 | [EINTR] The call was interrupted by a caught signal, or the |
| 2296 | signal did not have the SA_RESTART flag set. |
| 2297 | |
| 2298 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 2299 | argument. |
| 2300 | |
| 2301 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 2302 | _exit(2), sigaction(2), exit(3) |
| 2303 | |
| 2304 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 2305 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 2306 | (``POSIX.1''). |
| 2307 | |
| 2308 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 2309 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 2310 | specification. |
| 2311 | |
| 2312 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 2313 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 2314 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 2315 | first appeared in 4BSD, but the final calling convention was only |
| 2316 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 2317 | appeared in 4.3BSD-Reno. |
| 2318 | |
| 2319 | N\bNA\bAM\bME\bE |
| 2320 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 2321 | |
| 2322 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 2323 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2324 | |
| 2325 | _\bp_\bi_\bd_\b__\bt |
| 2326 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 2327 | |
| 2328 | _\bp_\bi_\bd_\b__\bt |
| 2329 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 2330 | |
| 2331 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 2332 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2333 | |
| 2334 | _\bp_\bi_\bd_\b__\bt |
| 2335 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2336 | |
| 2337 | _\bp_\bi_\bd_\b__\bt |
| 2338 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2339 | |
| 2340 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 2341 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 2342 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 2343 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 2344 | area, if non-zero, is filled in with termination information about the |
| 2345 | process that exited (see below). |
| 2346 | |
| 2347 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 2348 | to wait for certain child processes, that need resource utilization |
| 2349 | statistics accumulated by child processes, or that require options. The |
| 2350 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 2351 | |
| 2352 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 2353 | wait. The following symbolic constants are currently defined in |
| 2354 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 2355 | |
| 2356 | #define WAIT_ANY (-1) /* any process */ |
| 2357 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 2358 | |
| 2359 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 2360 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 2361 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 2362 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 2363 | call waits for any process whose process group ID equals the absolute |
| 2364 | value of _\bw_\bp_\bi_\bd. |
| 2365 | |
| 2366 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 2367 | bitwise OR of zero or more of the following values: |
| 2368 | |
| 2369 | WCONTINUED Causes status to be reported for stopped child processes that |
| 2370 | have been continued by receipt of a SIGCONT signal. |
| 2371 | |
| 2372 | WNOHANG Indicates that the call should not block if there are no |
| 2373 | processes that wish to report status. |
| 2374 | |
| 2375 | WUNTRACED If set, children of the current process that are stopped due |
| 2376 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 2377 | their status reported. |
| 2378 | |
| 2379 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 2380 | process and all its children is returned (this information is currently |
| 2381 | not available for stopped processes). |
| 2382 | |
| 2383 | When the WNOHANG option is specified and no processes wish to report |
| 2384 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 2385 | |
| 2386 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 2387 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 2388 | |
| 2389 | The following macros may be used to test the manner of exit of the |
| 2390 | process. One of the first three macros will evaluate to a non-zero |
| 2391 | (true) value: |
| 2392 | |
| 2393 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2394 | True if the process has not terminated, and has continued after a |
| 2395 | job control stop. This macro can be true only if the wait call |
| 2396 | specified the WCONTINUED option. |
| 2397 | |
| 2398 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2399 | True if the process terminated normally by a call to _exit(2) or |
| 2400 | exit(3). |
| 2401 | |
| 2402 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2403 | True if the process terminated due to receipt of a signal. |
| 2404 | |
| 2405 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2406 | True if the process has not terminated, but has stopped and can |
| 2407 | be restarted. This macro can be true only if the wait call |
| 2408 | specified the WUNTRACED option or if the child process is being |
| 2409 | traced (see ptrace(2)). |
| 2410 | |
| 2411 | Depending on the values of those macros, the following macros produce the |
| 2412 | remaining status information about the child process: |
| 2413 | |
| 2414 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2415 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 2416 | of the argument passed to _exit(2) or exit(3) by the child. |
| 2417 | |
| 2418 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2419 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2420 | signal that caused the termination of the process. |
| 2421 | |
| 2422 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2423 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 2424 | termination of the process was accompanied by the creation of a |
| 2425 | core file containing an image of the process when the signal was |
| 2426 | received. |
| 2427 | |
| 2428 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2429 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2430 | signal that caused the process to stop. |
| 2431 | |
| 2432 | N\bNO\bOT\bTE\bES\bS |
| 2433 | See sigaction(2) for a list of termination signals. A status of 0 |
| 2434 | indicates normal termination. |
| 2435 | |
| 2436 | If a parent process terminates without waiting for all of its child |
| 2437 | processes to terminate, the remaining child processes are assigned the |
| 2438 | parent process 1 ID (the init process ID). |
| 2439 | |
| 2440 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 2441 | may be interrupted or restarted when the signal-catching routine returns, |
| 2442 | depending on the options in effect for the signal; for further |
| 2443 | information, see siginterrupt(3). |
| 2444 | |
| 2445 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 2446 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 2447 | process ID of the child is returned to the calling process. Otherwise, a |
| 2448 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2449 | |
| 2450 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 2451 | child process, the process ID of the child is returned to the calling |
| 2452 | process. If there are no children not previously awaited, -1 is returned |
| 2453 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 2454 | are no stopped or exited children, 0 is returned. If an error is |
| 2455 | detected or a caught signal aborts the call, a value of -1 is returned |
| 2456 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2457 | |
| 2458 | E\bER\bRR\bRO\bOR\bRS\bS |
| 2459 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 2460 | |
| 2461 | [ECHILD] The calling process has no existing unwaited-for child |
| 2462 | processes. |
| 2463 | |
| 2464 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 2465 | address. (May not be detected before exit of a child |
| 2466 | process.) |
| 2467 | |
| 2468 | [EINTR] The call was interrupted by a caught signal, or the |
| 2469 | signal did not have the SA_RESTART flag set. |
| 2470 | |
| 2471 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 2472 | argument. |
| 2473 | |
| 2474 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 2475 | _exit(2), sigaction(2), exit(3) |
| 2476 | |
| 2477 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 2478 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 2479 | (``POSIX.1''). |
| 2480 | |
| 2481 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 2482 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 2483 | specification. |
| 2484 | |
| 2485 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 2486 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 2487 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 2488 | first appeared in 4BSD, but the final calling convention was only |
| 2489 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 2490 | appeared in 4.3BSD-Reno. |
| 2491 | |
| 2492 | N\bNA\bAM\bME\bE |
| 2493 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 2494 | |
| 2495 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 2496 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2497 | |
| 2498 | _\bp_\bi_\bd_\b__\bt |
| 2499 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 2500 | |
| 2501 | _\bp_\bi_\bd_\b__\bt |
| 2502 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 2503 | |
| 2504 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 2505 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2506 | |
| 2507 | _\bp_\bi_\bd_\b__\bt |
| 2508 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2509 | |
| 2510 | _\bp_\bi_\bd_\b__\bt |
| 2511 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2512 | |
| 2513 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 2514 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 2515 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 2516 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 2517 | area, if non-zero, is filled in with termination information about the |
| 2518 | process that exited (see below). |
| 2519 | |
| 2520 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 2521 | to wait for certain child processes, that need resource utilization |
| 2522 | statistics accumulated by child processes, or that require options. The |
| 2523 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 2524 | |
| 2525 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 2526 | wait. The following symbolic constants are currently defined in |
| 2527 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 2528 | |
| 2529 | #define WAIT_ANY (-1) /* any process */ |
| 2530 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 2531 | |
| 2532 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 2533 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 2534 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 2535 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 2536 | call waits for any process whose process group ID equals the absolute |
| 2537 | value of _\bw_\bp_\bi_\bd. |
| 2538 | |
| 2539 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 2540 | bitwise OR of zero or more of the following values: |
| 2541 | |
| 2542 | WCONTINUED Causes status to be reported for stopped child processes that |
| 2543 | have been continued by receipt of a SIGCONT signal. |
| 2544 | |
| 2545 | WNOHANG Indicates that the call should not block if there are no |
| 2546 | processes that wish to report status. |
| 2547 | |
| 2548 | WUNTRACED If set, children of the current process that are stopped due |
| 2549 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 2550 | their status reported. |
| 2551 | |
| 2552 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 2553 | process and all its children is returned (this information is currently |
| 2554 | not available for stopped processes). |
| 2555 | |
| 2556 | When the WNOHANG option is specified and no processes wish to report |
| 2557 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 2558 | |
| 2559 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 2560 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 2561 | |
| 2562 | The following macros may be used to test the manner of exit of the |
| 2563 | process. One of the first three macros will evaluate to a non-zero |
| 2564 | (true) value: |
| 2565 | |
| 2566 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2567 | True if the process has not terminated, and has continued after a |
| 2568 | job control stop. This macro can be true only if the wait call |
| 2569 | specified the WCONTINUED option. |
| 2570 | |
| 2571 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2572 | True if the process terminated normally by a call to _exit(2) or |
| 2573 | exit(3). |
| 2574 | |
| 2575 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2576 | True if the process terminated due to receipt of a signal. |
| 2577 | |
| 2578 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2579 | True if the process has not terminated, but has stopped and can |
| 2580 | be restarted. This macro can be true only if the wait call |
| 2581 | specified the WUNTRACED option or if the child process is being |
| 2582 | traced (see ptrace(2)). |
| 2583 | |
| 2584 | Depending on the values of those macros, the following macros produce the |
| 2585 | remaining status information about the child process: |
| 2586 | |
| 2587 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2588 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 2589 | of the argument passed to _exit(2) or exit(3) by the child. |
| 2590 | |
| 2591 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2592 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2593 | signal that caused the termination of the process. |
| 2594 | |
| 2595 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2596 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 2597 | termination of the process was accompanied by the creation of a |
| 2598 | core file containing an image of the process when the signal was |
| 2599 | received. |
| 2600 | |
| 2601 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2602 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2603 | signal that caused the process to stop. |
| 2604 | |
| 2605 | N\bNO\bOT\bTE\bES\bS |
| 2606 | See sigaction(2) for a list of termination signals. A status of 0 |
| 2607 | indicates normal termination. |
| 2608 | |
| 2609 | If a parent process terminates without waiting for all of its child |
| 2610 | processes to terminate, the remaining child processes are assigned the |
| 2611 | parent process 1 ID (the init process ID). |
| 2612 | |
| 2613 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 2614 | may be interrupted or restarted when the signal-catching routine returns, |
| 2615 | depending on the options in effect for the signal; for further |
| 2616 | information, see siginterrupt(3). |
| 2617 | |
| 2618 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 2619 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 2620 | process ID of the child is returned to the calling process. Otherwise, a |
| 2621 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2622 | |
| 2623 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 2624 | child process, the process ID of the child is returned to the calling |
| 2625 | process. If there are no children not previously awaited, -1 is returned |
| 2626 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 2627 | are no stopped or exited children, 0 is returned. If an error is |
| 2628 | detected or a caught signal aborts the call, a value of -1 is returned |
| 2629 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2630 | |
| 2631 | E\bER\bRR\bRO\bOR\bRS\bS |
| 2632 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 2633 | |
| 2634 | [ECHILD] The calling process has no existing unwaited-for child |
| 2635 | processes. |
| 2636 | |
| 2637 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 2638 | address. (May not be detected before exit of a child |
| 2639 | process.) |
| 2640 | |
| 2641 | [EINTR] The call was interrupted by a caught signal, or the |
| 2642 | signal did not have the SA_RESTART flag set. |
| 2643 | |
| 2644 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 2645 | argument. |
| 2646 | |
| 2647 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 2648 | _exit(2), sigaction(2), exit(3) |
| 2649 | |
| 2650 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 2651 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 2652 | (``POSIX.1''). |
| 2653 | |
| 2654 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 2655 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 2656 | specification. |
| 2657 | |
| 2658 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 2659 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 2660 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 2661 | first appeared in 4BSD, but the final calling convention was only |
| 2662 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 2663 | appeared in 4.3BSD-Reno. |
| 2664 | |
| 2665 | N\bNA\bAM\bME\bE |
| 2666 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 2667 | |
| 2668 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 2669 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2670 | |
| 2671 | _\bp_\bi_\bd_\b__\bt |
| 2672 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 2673 | |
| 2674 | _\bp_\bi_\bd_\b__\bt |
| 2675 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 2676 | |
| 2677 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 2678 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2679 | |
| 2680 | _\bp_\bi_\bd_\b__\bt |
| 2681 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2682 | |
| 2683 | _\bp_\bi_\bd_\b__\bt |
| 2684 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2685 | |
| 2686 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 2687 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 2688 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 2689 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 2690 | area, if non-zero, is filled in with termination information about the |
| 2691 | process that exited (see below). |
| 2692 | |
| 2693 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 2694 | to wait for certain child processes, that need resource utilization |
| 2695 | statistics accumulated by child processes, or that require options. The |
| 2696 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 2697 | |
| 2698 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 2699 | wait. The following symbolic constants are currently defined in |
| 2700 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 2701 | |
| 2702 | #define WAIT_ANY (-1) /* any process */ |
| 2703 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 2704 | |
| 2705 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 2706 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 2707 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 2708 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 2709 | call waits for any process whose process group ID equals the absolute |
| 2710 | value of _\bw_\bp_\bi_\bd. |
| 2711 | |
| 2712 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 2713 | bitwise OR of zero or more of the following values: |
| 2714 | |
| 2715 | WCONTINUED Causes status to be reported for stopped child processes that |
| 2716 | have been continued by receipt of a SIGCONT signal. |
| 2717 | |
| 2718 | WNOHANG Indicates that the call should not block if there are no |
| 2719 | processes that wish to report status. |
| 2720 | |
| 2721 | WUNTRACED If set, children of the current process that are stopped due |
| 2722 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 2723 | their status reported. |
| 2724 | |
| 2725 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 2726 | process and all its children is returned (this information is currently |
| 2727 | not available for stopped processes). |
| 2728 | |
| 2729 | When the WNOHANG option is specified and no processes wish to report |
| 2730 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 2731 | |
| 2732 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 2733 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 2734 | |
| 2735 | The following macros may be used to test the manner of exit of the |
| 2736 | process. One of the first three macros will evaluate to a non-zero |
| 2737 | (true) value: |
| 2738 | |
| 2739 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2740 | True if the process has not terminated, and has continued after a |
| 2741 | job control stop. This macro can be true only if the wait call |
| 2742 | specified the WCONTINUED option. |
| 2743 | |
| 2744 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2745 | True if the process terminated normally by a call to _exit(2) or |
| 2746 | exit(3). |
| 2747 | |
| 2748 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2749 | True if the process terminated due to receipt of a signal. |
| 2750 | |
| 2751 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2752 | True if the process has not terminated, but has stopped and can |
| 2753 | be restarted. This macro can be true only if the wait call |
| 2754 | specified the WUNTRACED option or if the child process is being |
| 2755 | traced (see ptrace(2)). |
| 2756 | |
| 2757 | Depending on the values of those macros, the following macros produce the |
| 2758 | remaining status information about the child process: |
| 2759 | |
| 2760 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2761 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 2762 | of the argument passed to _exit(2) or exit(3) by the child. |
| 2763 | |
| 2764 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2765 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2766 | signal that caused the termination of the process. |
| 2767 | |
| 2768 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2769 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 2770 | termination of the process was accompanied by the creation of a |
| 2771 | core file containing an image of the process when the signal was |
| 2772 | received. |
| 2773 | |
| 2774 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2775 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2776 | signal that caused the process to stop. |
| 2777 | |
| 2778 | N\bNO\bOT\bTE\bES\bS |
| 2779 | See sigaction(2) for a list of termination signals. A status of 0 |
| 2780 | indicates normal termination. |
| 2781 | |
| 2782 | If a parent process terminates without waiting for all of its child |
| 2783 | processes to terminate, the remaining child processes are assigned the |
| 2784 | parent process 1 ID (the init process ID). |
| 2785 | |
| 2786 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 2787 | may be interrupted or restarted when the signal-catching routine returns, |
| 2788 | depending on the options in effect for the signal; for further |
| 2789 | information, see siginterrupt(3). |
| 2790 | |
| 2791 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 2792 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 2793 | process ID of the child is returned to the calling process. Otherwise, a |
| 2794 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2795 | |
| 2796 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 2797 | child process, the process ID of the child is returned to the calling |
| 2798 | process. If there are no children not previously awaited, -1 is returned |
| 2799 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 2800 | are no stopped or exited children, 0 is returned. If an error is |
| 2801 | detected or a caught signal aborts the call, a value of -1 is returned |
| 2802 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2803 | |
| 2804 | E\bER\bRR\bRO\bOR\bRS\bS |
| 2805 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 2806 | |
| 2807 | [ECHILD] The calling process has no existing unwaited-for child |
| 2808 | processes. |
| 2809 | |
| 2810 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 2811 | address. (May not be detected before exit of a child |
| 2812 | process.) |
| 2813 | |
| 2814 | [EINTR] The call was interrupted by a caught signal, or the |
| 2815 | signal did not have the SA_RESTART flag set. |
| 2816 | |
| 2817 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 2818 | argument. |
| 2819 | |
| 2820 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 2821 | _exit(2), sigaction(2), exit(3) |
| 2822 | |
| 2823 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 2824 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 2825 | (``POSIX.1''). |
| 2826 | |
| 2827 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 2828 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 2829 | specification. |
| 2830 | |
| 2831 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 2832 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 2833 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 2834 | first appeared in 4BSD, but the final calling convention was only |
| 2835 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 2836 | appeared in 4.3BSD-Reno. |
| 2837 | |
| 2838 | N\bNA\bAM\bME\bE |
| 2839 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 2840 | |
| 2841 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 2842 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2843 | |
| 2844 | _\bp_\bi_\bd_\b__\bt |
| 2845 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 2846 | |
| 2847 | _\bp_\bi_\bd_\b__\bt |
| 2848 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 2849 | |
| 2850 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 2851 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 2852 | |
| 2853 | _\bp_\bi_\bd_\b__\bt |
| 2854 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2855 | |
| 2856 | _\bp_\bi_\bd_\b__\bt |
| 2857 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 2858 | |
| 2859 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 2860 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 2861 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 2862 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 2863 | area, if non-zero, is filled in with termination information about the |
| 2864 | process that exited (see below). |
| 2865 | |
| 2866 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 2867 | to wait for certain child processes, that need resource utilization |
| 2868 | statistics accumulated by child processes, or that require options. The |
| 2869 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 2870 | |
| 2871 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 2872 | wait. The following symbolic constants are currently defined in |
| 2873 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 2874 | |
| 2875 | #define WAIT_ANY (-1) /* any process */ |
| 2876 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 2877 | |
| 2878 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 2879 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 2880 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 2881 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 2882 | call waits for any process whose process group ID equals the absolute |
| 2883 | value of _\bw_\bp_\bi_\bd. |
| 2884 | |
| 2885 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 2886 | bitwise OR of zero or more of the following values: |
| 2887 | |
| 2888 | WCONTINUED Causes status to be reported for stopped child processes that |
| 2889 | have been continued by receipt of a SIGCONT signal. |
| 2890 | |
| 2891 | WNOHANG Indicates that the call should not block if there are no |
| 2892 | processes that wish to report status. |
| 2893 | |
| 2894 | WUNTRACED If set, children of the current process that are stopped due |
| 2895 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 2896 | their status reported. |
| 2897 | |
| 2898 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 2899 | process and all its children is returned (this information is currently |
| 2900 | not available for stopped processes). |
| 2901 | |
| 2902 | When the WNOHANG option is specified and no processes wish to report |
| 2903 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 2904 | |
| 2905 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 2906 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 2907 | |
| 2908 | The following macros may be used to test the manner of exit of the |
| 2909 | process. One of the first three macros will evaluate to a non-zero |
| 2910 | (true) value: |
| 2911 | |
| 2912 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2913 | True if the process has not terminated, and has continued after a |
| 2914 | job control stop. This macro can be true only if the wait call |
| 2915 | specified the WCONTINUED option. |
| 2916 | |
| 2917 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2918 | True if the process terminated normally by a call to _exit(2) or |
| 2919 | exit(3). |
| 2920 | |
| 2921 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2922 | True if the process terminated due to receipt of a signal. |
| 2923 | |
| 2924 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2925 | True if the process has not terminated, but has stopped and can |
| 2926 | be restarted. This macro can be true only if the wait call |
| 2927 | specified the WUNTRACED option or if the child process is being |
| 2928 | traced (see ptrace(2)). |
| 2929 | |
| 2930 | Depending on the values of those macros, the following macros produce the |
| 2931 | remaining status information about the child process: |
| 2932 | |
| 2933 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2934 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 2935 | of the argument passed to _exit(2) or exit(3) by the child. |
| 2936 | |
| 2937 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2938 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2939 | signal that caused the termination of the process. |
| 2940 | |
| 2941 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2942 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 2943 | termination of the process was accompanied by the creation of a |
| 2944 | core file containing an image of the process when the signal was |
| 2945 | received. |
| 2946 | |
| 2947 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 2948 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 2949 | signal that caused the process to stop. |
| 2950 | |
| 2951 | N\bNO\bOT\bTE\bES\bS |
| 2952 | See sigaction(2) for a list of termination signals. A status of 0 |
| 2953 | indicates normal termination. |
| 2954 | |
| 2955 | If a parent process terminates without waiting for all of its child |
| 2956 | processes to terminate, the remaining child processes are assigned the |
| 2957 | parent process 1 ID (the init process ID). |
| 2958 | |
| 2959 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 2960 | may be interrupted or restarted when the signal-catching routine returns, |
| 2961 | depending on the options in effect for the signal; for further |
| 2962 | information, see siginterrupt(3). |
| 2963 | |
| 2964 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 2965 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 2966 | process ID of the child is returned to the calling process. Otherwise, a |
| 2967 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2968 | |
| 2969 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 2970 | child process, the process ID of the child is returned to the calling |
| 2971 | process. If there are no children not previously awaited, -1 is returned |
| 2972 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 2973 | are no stopped or exited children, 0 is returned. If an error is |
| 2974 | detected or a caught signal aborts the call, a value of -1 is returned |
| 2975 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 2976 | |
| 2977 | E\bER\bRR\bRO\bOR\bRS\bS |
| 2978 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 2979 | |
| 2980 | [ECHILD] The calling process has no existing unwaited-for child |
| 2981 | processes. |
| 2982 | |
| 2983 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 2984 | address. (May not be detected before exit of a child |
| 2985 | process.) |
| 2986 | |
| 2987 | [EINTR] The call was interrupted by a caught signal, or the |
| 2988 | signal did not have the SA_RESTART flag set. |
| 2989 | |
| 2990 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 2991 | argument. |
| 2992 | |
| 2993 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 2994 | _exit(2), sigaction(2), exit(3) |
| 2995 | |
| 2996 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 2997 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 2998 | (``POSIX.1''). |
| 2999 | |
| 3000 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 3001 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 3002 | specification. |
| 3003 | |
| 3004 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3005 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 3006 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 3007 | first appeared in 4BSD, but the final calling convention was only |
| 3008 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 3009 | appeared in 4.3BSD-Reno. |
| 3010 | |
| 3011 | N\bNA\bAM\bME\bE |
| 3012 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 3013 | |
| 3014 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3015 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 3016 | |
| 3017 | _\bp_\bi_\bd_\b__\bt |
| 3018 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 3019 | |
| 3020 | _\bp_\bi_\bd_\b__\bt |
| 3021 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 3022 | |
| 3023 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 3024 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 3025 | |
| 3026 | _\bp_\bi_\bd_\b__\bt |
| 3027 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 3028 | |
| 3029 | _\bp_\bi_\bd_\b__\bt |
| 3030 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 3031 | |
| 3032 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3033 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 3034 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 3035 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 3036 | area, if non-zero, is filled in with termination information about the |
| 3037 | process that exited (see below). |
| 3038 | |
| 3039 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 3040 | to wait for certain child processes, that need resource utilization |
| 3041 | statistics accumulated by child processes, or that require options. The |
| 3042 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 3043 | |
| 3044 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 3045 | wait. The following symbolic constants are currently defined in |
| 3046 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 3047 | |
| 3048 | #define WAIT_ANY (-1) /* any process */ |
| 3049 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 3050 | |
| 3051 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 3052 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 3053 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 3054 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 3055 | call waits for any process whose process group ID equals the absolute |
| 3056 | value of _\bw_\bp_\bi_\bd. |
| 3057 | |
| 3058 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 3059 | bitwise OR of zero or more of the following values: |
| 3060 | |
| 3061 | WCONTINUED Causes status to be reported for stopped child processes that |
| 3062 | have been continued by receipt of a SIGCONT signal. |
| 3063 | |
| 3064 | WNOHANG Indicates that the call should not block if there are no |
| 3065 | processes that wish to report status. |
| 3066 | |
| 3067 | WUNTRACED If set, children of the current process that are stopped due |
| 3068 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 3069 | their status reported. |
| 3070 | |
| 3071 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 3072 | process and all its children is returned (this information is currently |
| 3073 | not available for stopped processes). |
| 3074 | |
| 3075 | When the WNOHANG option is specified and no processes wish to report |
| 3076 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 3077 | |
| 3078 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 3079 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 3080 | |
| 3081 | The following macros may be used to test the manner of exit of the |
| 3082 | process. One of the first three macros will evaluate to a non-zero |
| 3083 | (true) value: |
| 3084 | |
| 3085 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3086 | True if the process has not terminated, and has continued after a |
| 3087 | job control stop. This macro can be true only if the wait call |
| 3088 | specified the WCONTINUED option. |
| 3089 | |
| 3090 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3091 | True if the process terminated normally by a call to _exit(2) or |
| 3092 | exit(3). |
| 3093 | |
| 3094 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3095 | True if the process terminated due to receipt of a signal. |
| 3096 | |
| 3097 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3098 | True if the process has not terminated, but has stopped and can |
| 3099 | be restarted. This macro can be true only if the wait call |
| 3100 | specified the WUNTRACED option or if the child process is being |
| 3101 | traced (see ptrace(2)). |
| 3102 | |
| 3103 | Depending on the values of those macros, the following macros produce the |
| 3104 | remaining status information about the child process: |
| 3105 | |
| 3106 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3107 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 3108 | of the argument passed to _exit(2) or exit(3) by the child. |
| 3109 | |
| 3110 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3111 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 3112 | signal that caused the termination of the process. |
| 3113 | |
| 3114 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3115 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 3116 | termination of the process was accompanied by the creation of a |
| 3117 | core file containing an image of the process when the signal was |
| 3118 | received. |
| 3119 | |
| 3120 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3121 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 3122 | signal that caused the process to stop. |
| 3123 | |
| 3124 | N\bNO\bOT\bTE\bES\bS |
| 3125 | See sigaction(2) for a list of termination signals. A status of 0 |
| 3126 | indicates normal termination. |
| 3127 | |
| 3128 | If a parent process terminates without waiting for all of its child |
| 3129 | processes to terminate, the remaining child processes are assigned the |
| 3130 | parent process 1 ID (the init process ID). |
| 3131 | |
| 3132 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 3133 | may be interrupted or restarted when the signal-catching routine returns, |
| 3134 | depending on the options in effect for the signal; for further |
| 3135 | information, see siginterrupt(3). |
| 3136 | |
| 3137 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3138 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 3139 | process ID of the child is returned to the calling process. Otherwise, a |
| 3140 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 3141 | |
| 3142 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 3143 | child process, the process ID of the child is returned to the calling |
| 3144 | process. If there are no children not previously awaited, -1 is returned |
| 3145 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 3146 | are no stopped or exited children, 0 is returned. If an error is |
| 3147 | detected or a caught signal aborts the call, a value of -1 is returned |
| 3148 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 3149 | |
| 3150 | E\bER\bRR\bRO\bOR\bRS\bS |
| 3151 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 3152 | |
| 3153 | [ECHILD] The calling process has no existing unwaited-for child |
| 3154 | processes. |
| 3155 | |
| 3156 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 3157 | address. (May not be detected before exit of a child |
| 3158 | process.) |
| 3159 | |
| 3160 | [EINTR] The call was interrupted by a caught signal, or the |
| 3161 | signal did not have the SA_RESTART flag set. |
| 3162 | |
| 3163 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 3164 | argument. |
| 3165 | |
| 3166 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3167 | _exit(2), sigaction(2), exit(3) |
| 3168 | |
| 3169 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 3170 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 3171 | (``POSIX.1''). |
| 3172 | |
| 3173 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 3174 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 3175 | specification. |
| 3176 | |
| 3177 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3178 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 3179 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 3180 | first appeared in 4BSD, but the final calling convention was only |
| 3181 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 3182 | appeared in 4.3BSD-Reno. |
| 3183 | |
| 3184 | N\bNA\bAM\bME\bE |
| 3185 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 3186 | |
| 3187 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3188 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 3189 | |
| 3190 | _\bp_\bi_\bd_\b__\bt |
| 3191 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 3192 | |
| 3193 | _\bp_\bi_\bd_\b__\bt |
| 3194 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 3195 | |
| 3196 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 3197 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 3198 | |
| 3199 | _\bp_\bi_\bd_\b__\bt |
| 3200 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 3201 | |
| 3202 | _\bp_\bi_\bd_\b__\bt |
| 3203 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 3204 | |
| 3205 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3206 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 3207 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 3208 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 3209 | area, if non-zero, is filled in with termination information about the |
| 3210 | process that exited (see below). |
| 3211 | |
| 3212 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 3213 | to wait for certain child processes, that need resource utilization |
| 3214 | statistics accumulated by child processes, or that require options. The |
| 3215 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 3216 | |
| 3217 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 3218 | wait. The following symbolic constants are currently defined in |
| 3219 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 3220 | |
| 3221 | #define WAIT_ANY (-1) /* any process */ |
| 3222 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 3223 | |
| 3224 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 3225 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 3226 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 3227 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 3228 | call waits for any process whose process group ID equals the absolute |
| 3229 | value of _\bw_\bp_\bi_\bd. |
| 3230 | |
| 3231 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 3232 | bitwise OR of zero or more of the following values: |
| 3233 | |
| 3234 | WCONTINUED Causes status to be reported for stopped child processes that |
| 3235 | have been continued by receipt of a SIGCONT signal. |
| 3236 | |
| 3237 | WNOHANG Indicates that the call should not block if there are no |
| 3238 | processes that wish to report status. |
| 3239 | |
| 3240 | WUNTRACED If set, children of the current process that are stopped due |
| 3241 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 3242 | their status reported. |
| 3243 | |
| 3244 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 3245 | process and all its children is returned (this information is currently |
| 3246 | not available for stopped processes). |
| 3247 | |
| 3248 | When the WNOHANG option is specified and no processes wish to report |
| 3249 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 3250 | |
| 3251 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 3252 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 3253 | |
| 3254 | The following macros may be used to test the manner of exit of the |
| 3255 | process. One of the first three macros will evaluate to a non-zero |
| 3256 | (true) value: |
| 3257 | |
| 3258 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3259 | True if the process has not terminated, and has continued after a |
| 3260 | job control stop. This macro can be true only if the wait call |
| 3261 | specified the WCONTINUED option. |
| 3262 | |
| 3263 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3264 | True if the process terminated normally by a call to _exit(2) or |
| 3265 | exit(3). |
| 3266 | |
| 3267 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3268 | True if the process terminated due to receipt of a signal. |
| 3269 | |
| 3270 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3271 | True if the process has not terminated, but has stopped and can |
| 3272 | be restarted. This macro can be true only if the wait call |
| 3273 | specified the WUNTRACED option or if the child process is being |
| 3274 | traced (see ptrace(2)). |
| 3275 | |
| 3276 | Depending on the values of those macros, the following macros produce the |
| 3277 | remaining status information about the child process: |
| 3278 | |
| 3279 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3280 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 3281 | of the argument passed to _exit(2) or exit(3) by the child. |
| 3282 | |
| 3283 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3284 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 3285 | signal that caused the termination of the process. |
| 3286 | |
| 3287 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3288 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 3289 | termination of the process was accompanied by the creation of a |
| 3290 | core file containing an image of the process when the signal was |
| 3291 | received. |
| 3292 | |
| 3293 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 3294 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 3295 | signal that caused the process to stop. |
| 3296 | |
| 3297 | N\bNO\bOT\bTE\bES\bS |
| 3298 | See sigaction(2) for a list of termination signals. A status of 0 |
| 3299 | indicates normal termination. |
| 3300 | |
| 3301 | If a parent process terminates without waiting for all of its child |
| 3302 | processes to terminate, the remaining child processes are assigned the |
| 3303 | parent process 1 ID (the init process ID). |
| 3304 | |
| 3305 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 3306 | may be interrupted or restarted when the signal-catching routine returns, |
| 3307 | depending on the options in effect for the signal; for further |
| 3308 | information, see siginterrupt(3). |
| 3309 | |
| 3310 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3311 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 3312 | process ID of the child is returned to the calling process. Otherwise, a |
| 3313 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 3314 | |
| 3315 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 3316 | child process, the process ID of the child is returned to the calling |
| 3317 | process. If there are no children not previously awaited, -1 is returned |
| 3318 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 3319 | are no stopped or exited children, 0 is returned. If an error is |
| 3320 | detected or a caught signal aborts the call, a value of -1 is returned |
| 3321 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 3322 | |
| 3323 | E\bER\bRR\bRO\bOR\bRS\bS |
| 3324 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 3325 | |
| 3326 | [ECHILD] The calling process has no existing unwaited-for child |
| 3327 | processes. |
| 3328 | |
| 3329 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 3330 | address. (May not be detected before exit of a child |
| 3331 | process.) |
| 3332 | |
| 3333 | [EINTR] The call was interrupted by a caught signal, or the |
| 3334 | signal did not have the SA_RESTART flag set. |
| 3335 | |
| 3336 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 3337 | argument. |
| 3338 | |
| 3339 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3340 | _exit(2), sigaction(2), exit(3) |
| 3341 | |
| 3342 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 3343 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 3344 | (``POSIX.1''). |
| 3345 | |
| 3346 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 3347 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 3348 | specification. |
| 3349 | |
| 3350 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3351 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 3352 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 3353 | first appeared in 4BSD, but the final calling convention was only |
| 3354 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 3355 | appeared in 4.3BSD-Reno. |
| 3356 | |
| 3357 | N\bNA\bAM\bME\bE |
| 3358 | _\b_e\bex\bxi\bit\bt, _\b_E\bEx\bxi\bit\bt - terminate the calling process |
| 3359 | |
| 3360 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3361 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 3362 | |
| 3363 | _\bv_\bo_\bi_\bd |
| 3364 | _\b_e\bex\bxi\bit\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\bt_\bu_\bs); |
| 3365 | |
| 3366 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdl\bli\bib\bb.\b.h\bh>\b> |
| 3367 | |
| 3368 | _\bv_\bo_\bi_\bd |
| 3369 | _\b_E\bEx\bxi\bit\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\bt_\bu_\bs); |
| 3370 | |
| 3371 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3372 | The _\b_e\bex\bxi\bit\bt() and _\b_E\bEx\bxi\bit\bt() functions terminate a process with the following |
| 3373 | consequences: |
| 3374 | |
| 3375 | +\b+\bo\bo All threads in the process are terminated. |
| 3376 | |
| 3377 | +\b+\bo\bo All open file descriptors in the calling process are closed. This |
| 3378 | may entail delays; for example, waiting for output to drain. A |
| 3379 | process in this state may not be killed, as it is already dying. |
| 3380 | |
| 3381 | +\b+\bo\bo If the parent process of the calling process has an outstanding |
| 3382 | wait(2) call or catches the SIGCHLD signal, it is notified of the |
| 3383 | calling process's termination and _\bs_\bt_\ba_\bt_\bu_\bs is set as defined by |
| 3384 | wait(2). (Note that typically only the lower 8 bits of _\bs_\bt_\ba_\bt_\bu_\bs are |
| 3385 | passed on to the parent, thus negative values have less meaning.) |
| 3386 | |
| 3387 | +\b+\bo\bo The parent process ID of all of the calling process's existing child |
| 3388 | processes are set to 1; the initialization process (see the |
| 3389 | DEFINITIONS section of intro(2)) inherits each of these processes. |
| 3390 | |
| 3391 | +\b+\bo\bo If the termination of the process causes any process group to become |
| 3392 | orphaned (usually because the parents of all members of the group |
| 3393 | have now exited; see Orphaned Process Group in intro(2)), and if any |
| 3394 | member of the orphaned group is stopped, the SIGHUP and SIGCONT |
| 3395 | signals are sent to all members of the newly orphaned process group. |
| 3396 | |
| 3397 | +\b+\bo\bo If the process is a controlling process (see intro(2)), the SIGHUP |
| 3398 | signal is sent to the foreground process group of the controlling |
| 3399 | terminal, and all current access to the controlling terminal is |
| 3400 | revoked. |
| 3401 | |
| 3402 | Most C programs call the library routine exit(3), which flushes buffers, |
| 3403 | closes streams, unlinks temporary files, etc., and then calls _\b_e\bex\bxi\bit\bt(). |
| 3404 | |
| 3405 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3406 | _\b_e\bex\bxi\bit\bt() and _\b_E\bEx\bxi\bit\bt() can never return. |
| 3407 | |
| 3408 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3409 | fork(2), intro(2), sigaction(2), wait(2), exit(3), sysexits(3) |
| 3410 | |
| 3411 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 3412 | The _\b_e\bex\bxi\bit\bt() function conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
| 3413 | _\b_E\bEx\bxi\bit\bt() function conforms to ISO/IEC 9899:1999 (``ISO C99''). |
| 3414 | |
| 3415 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3416 | An e\bex\bxi\bit\bt() system call first appeared in Version 1 AT&T UNIX. It accepts |
| 3417 | the _\bs_\bt_\ba_\bt_\bu_\bs argument since Version 2 AT&T UNIX. An _\b_e\bex\bxi\bit\bt() variant first |
| 3418 | appeared in Version 7 AT&T UNIX. The _\b_E\bEx\bxi\bit\bt() function appeared in |
| 3419 | OpenBSD 3.6. |
| 3420 | |
| 3421 | N\bNA\bAM\bME\bE |
| 3422 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb, _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb - get and set the address of the thread control |
| 3423 | block of the current thread |
| 3424 | |
| 3425 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3426 | _\bv_\bo_\bi_\bd _\b* |
| 3427 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb(_\bv_\bo_\bi_\bd); |
| 3428 | |
| 3429 | _\bv_\bo_\bi_\bd |
| 3430 | _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb(_\bv_\bo_\bi_\bd _\b*); |
| 3431 | |
| 3432 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3433 | The _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() and _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb() functions are for use by librthread and |
| 3434 | other parts of the system runtime to retrieve and set the address of the |
| 3435 | current thread's thread control block (TCB). This is used to locate per- |
| 3436 | thread data such as _\be_\br_\br_\bn_\bo. Each kernel-level thread in a process has a |
| 3437 | separate value for this address, which can be obtained and changed via |
| 3438 | these system calls. New threads (including the first thread of a new |
| 3439 | process) created using fork(2), vfork(2), or __tfork(2), inherit the TCB |
| 3440 | address of the thread that created them. execve(2) resets it to zero. |
| 3441 | |
| 3442 | On some platforms, this address is also directly mapped to a CPU register |
| 3443 | which can be accessed from userspace. |
| 3444 | |
| 3445 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3446 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() returns the address of the thread control block of the |
| 3447 | current thread. |
| 3448 | |
| 3449 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3450 | __tfork(2) |
| 3451 | |
| 3452 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3453 | The _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() and _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb() system calls appeared in OpenBSD 5.1. |
| 3454 | |
| 3455 | N\bNA\bAM\bME\bE |
| 3456 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb, _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb - get and set the address of the thread control |
| 3457 | block of the current thread |
| 3458 | |
| 3459 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3460 | _\bv_\bo_\bi_\bd _\b* |
| 3461 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb(_\bv_\bo_\bi_\bd); |
| 3462 | |
| 3463 | _\bv_\bo_\bi_\bd |
| 3464 | _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb(_\bv_\bo_\bi_\bd _\b*); |
| 3465 | |
| 3466 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3467 | The _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() and _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb() functions are for use by librthread and |
| 3468 | other parts of the system runtime to retrieve and set the address of the |
| 3469 | current thread's thread control block (TCB). This is used to locate per- |
| 3470 | thread data such as _\be_\br_\br_\bn_\bo. Each kernel-level thread in a process has a |
| 3471 | separate value for this address, which can be obtained and changed via |
| 3472 | these system calls. New threads (including the first thread of a new |
| 3473 | process) created using fork(2), vfork(2), or __tfork(2), inherit the TCB |
| 3474 | address of the thread that created them. execve(2) resets it to zero. |
| 3475 | |
| 3476 | On some platforms, this address is also directly mapped to a CPU register |
| 3477 | which can be accessed from userspace. |
| 3478 | |
| 3479 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3480 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() returns the address of the thread control block of the |
| 3481 | current thread. |
| 3482 | |
| 3483 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3484 | __tfork(2) |
| 3485 | |
| 3486 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3487 | The _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() and _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb() system calls appeared in OpenBSD 5.1. |
| 3488 | |
| 3489 | N\bNA\bAM\bME\bE |
| 3490 | s\bsy\bys\bsc\bca\bal\bll\bl, _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl - indirect system call |
| 3491 | |
| 3492 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3493 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsy\bys\bsc\bca\bal\bll\bl.\b.h\bh>\b> |
| 3494 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 3495 | |
| 3496 | _\bi_\bn_\bt |
| 3497 | s\bsy\bys\bsc\bca\bal\bll\bl(_\bi_\bn_\bt _\bn_\bu_\bm_\bb_\be_\br, _\b._\b._\b.); |
| 3498 | |
| 3499 | _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl(_\bq_\bu_\ba_\bd_\b__\bt _\bn_\bu_\bm_\bb_\be_\br, _\b._\b._\b.); |
| 3500 | |
| 3501 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3502 | s\bsy\bys\bsc\bca\bal\bll\bl() performs the system call whose assembly language interface has |
| 3503 | the specified _\bn_\bu_\bm_\bb_\be_\br with the specified arguments. Symbolic constants |
| 3504 | for system calls can be found in the header file <_\bs_\by_\bs_\b/_\bs_\by_\bs_\bc_\ba_\bl_\bl_\b._\bh>. |
| 3505 | |
| 3506 | Since different system calls have different return types, a prototype of |
| 3507 | _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl specifying the correct return type should be declared locally. |
| 3508 | This is especially important for system calls returning larger-than-int |
| 3509 | results. |
| 3510 | |
| 3511 | The _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl form should be used when one or more of the parameters is a |
| 3512 | 64-bit argument to ensure that argument alignment is correct. This |
| 3513 | system call is useful for testing new system calls that do not have |
| 3514 | entries in the C library. |
| 3515 | |
| 3516 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3517 | The return values are defined by the system call being invoked. In |
| 3518 | general, for system calls returning _\bi_\bn_\bt, a 0 return value indicates |
| 3519 | success. A -1 return value indicates an error, and an error code is |
| 3520 | stored in _\be_\br_\br_\bn_\bo. |
| 3521 | |
| 3522 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3523 | The predecessor of these functions, the former i\bin\bnd\bdi\bir\br() system call, first |
| 3524 | appeared in Version 4 AT&T UNIX. The s\bsy\bys\bsc\bca\bal\bll\bl() function first appeared |
| 3525 | in 3BSD. |
| 3526 | |
| 3527 | B\bBU\bUG\bGS\bS |
| 3528 | There is no way to simulate system calls that have multiple return values |
| 3529 | such as pipe(2). |
| 3530 | |
| 3531 | N\bNA\bAM\bME\bE |
| 3532 | _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd, _\b__\b_t\btf\bfo\bor\brk\bk - create a new kernel thread in the current |
| 3533 | process |
| 3534 | |
| 3535 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3536 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 3537 | |
| 3538 | struct __tfork { |
| 3539 | void *tf_tcb; /* TCB address for new thread */ |
| 3540 | pid_t *tf_tid; /* where to write child's thread ID */ |
| 3541 | void *tf_stack; /* stack address for new thread */ |
| 3542 | }; |
| 3543 | |
| 3544 | _\bp_\bi_\bd_\b__\bt |
| 3545 | _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\b__\b__\bt_\bf_\bo_\br_\bk _\b*_\bp_\ba_\br_\ba_\bm_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bp_\bs_\bi_\bz_\be, |
| 3546 | _\bv_\bo_\bi_\bd _\b(_\b*_\bs_\bt_\ba_\br_\bt_\bf_\bu_\bn_\bc_\b)_\b(_\bv_\bo_\bi_\bd _\b*_\b), _\bv_\bo_\bi_\bd _\b*_\bs_\bt_\ba_\br_\bt_\ba_\br_\bg); |
| 3547 | |
| 3548 | _\bp_\bi_\bd_\b__\bt |
| 3549 | _\b__\b_t\btf\bfo\bor\brk\bk(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\b__\b__\bt_\bf_\bo_\br_\bk _\b*_\bp_\ba_\br_\ba_\bm_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bp_\bs_\bi_\bz_\be); |
| 3550 | |
| 3551 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3552 | The _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() function creates a new kernel thread in the current |
| 3553 | process. The new thread starts by calling _\bs_\bt_\ba_\br_\bt_\bf_\bu_\bn_\bc, passing _\bs_\bt_\ba_\br_\bt_\ba_\br_\bg as |
| 3554 | the only argument. If _\bs_\bt_\ba_\br_\bt_\bf_\bu_\bn_\bc returns, the thread will exit. |
| 3555 | |
| 3556 | The _\bp_\ba_\br_\ba_\bm_\bs argument provides parameters used by the kernel during thread |
| 3557 | creation. The new thread's thread control block (TCB) address is set to |
| 3558 | _\bt_\bf_\b__\bt_\bc_\bb. If _\bt_\bf_\b__\bt_\bi_\bd is not NULL, the new thread's thread ID is returned to |
| 3559 | the user at that address, with the guarantee that this is done before |
| 3560 | returning to userspace in either the calling thread or the new thread. |
| 3561 | If _\bt_\bf_\b__\bs_\bt_\ba_\bc_\bk is not NULL, the new thread's stack is initialized to start |
| 3562 | at that address. On hppa and hppa64, that is the lowest address used; on |
| 3563 | other architectures that is the address after the highest address used. |
| 3564 | |
| 3565 | The _\bp_\bs_\bi_\bz_\be argument provides the size of the _\bs_\bt_\br_\bu_\bc_\bt _\b__\b__\bt_\bf_\bo_\br_\bk passed via the |
| 3566 | _\bp_\ba_\br_\ba_\bm_\bs argument. |
| 3567 | |
| 3568 | The underlying system call used to create the thread is _\b__\b_t\btf\bfo\bor\brk\bk(). |
| 3569 | Because the new thread returns without a stack frame, the syscall cannot |
| 3570 | be directly used from C and is therefore not provided as a function. |
| 3571 | However, the syscall may show up in the output of kdump(1). |
| 3572 | |
| 3573 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3574 | Upon successful completion, _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() returns in the calling |
| 3575 | thread the thread ID of new thread. The _\b__\b_t\btf\bfo\bor\brk\bk() syscall itself, on |
| 3576 | success, returns a value of 0 in the new thread and returns the thread ID |
| 3577 | of the new thread to the calling thread. Otherwise, a value of -1 is |
| 3578 | returned, no thread is created, and the global variable _\be_\br_\br_\bn_\bo is set to |
| 3579 | indicate an error. |
| 3580 | |
| 3581 | E\bER\bRR\bRO\bOR\bRS\bS |
| 3582 | _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() and _\b__\b_t\btf\bfo\bor\brk\bk() will fail and no thread will be created |
| 3583 | if: |
| 3584 | |
| 3585 | [ENOMEM] Cannot allocate memory. The new process image |
| 3586 | required more memory than was allowed by the hardware |
| 3587 | or by system-imposed memory management constraints. A |
| 3588 | lack of swap space is normally temporary; however, a |
| 3589 | lack of core is not. Soft limits may be increased to |
| 3590 | their corresponding hard limits. |
| 3591 | |
| 3592 | [EINVAL] Invalid argument. Some invalid argument was supplied. |
| 3593 | |
| 3594 | [EAGAIN] Resource temporarily unavailable. The system-imposed |
| 3595 | limit on the total number of threads under execution |
| 3596 | would be exceeded. This limit is configuration- |
| 3597 | dependent. |
| 3598 | |
| 3599 | [EAGAIN] Resource temporarily unavailable. The system-imposed |
| 3600 | limit MAXUPRC on the total number of threads under |
| 3601 | execution by a single user would be exceeded. MAXUPRC |
| 3602 | is currently defined in <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh> as CHILD_MAX, |
| 3603 | which is currently defined as 80 in <_\bs_\by_\bs_\b/_\bs_\by_\bs_\bl_\bi_\bm_\bi_\bt_\bs_\b._\bh>. |
| 3604 | |
| 3605 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 3606 | The _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() function and _\b__\b_t\btf\bfo\bor\brk\bk() syscall are specific to |
| 3607 | OpenBSD and should not be used in portable applications. |
| 3608 | |
| 3609 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3610 | The _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() function and _\b__\b_t\btf\bfo\bor\brk\bk() syscall appeared in |
| 3611 | OpenBSD 5.1. |
| 3612 | |
| 3613 | N\bNA\bAM\bME\bE |
| 3614 | _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt - synchronously accept a signal |
| 3615 | |
| 3616 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3617 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 3618 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 3619 | |
| 3620 | _\bi_\bn_\bt |
| 3621 | _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt(_\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\bs_\be_\bt, _\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b__\bt _\b*_\bi_\bn_\bf_\bo, |
| 3622 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
| 3623 | |
| 3624 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3625 | The _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() function is used to implement s\bsi\big\bgw\bwa\bai\bit\bt(). It selects |
| 3626 | a signal pending for the calling thread or process from _\bs_\be_\bt, atomically |
| 3627 | clears it from that set of pending signals, and returns that signal |
| 3628 | number. If prior to the call to _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() there are multiple |
| 3629 | pending instances of a single signal number, it is undefined whether upon |
| 3630 | successful return there are any remaining pending signals for that signal |
| 3631 | number. If no signal in _\bs_\be_\bt is pending at the time of the call, the |
| 3632 | thread shall be suspended until one or more becomes pending. The signals |
| 3633 | defined by _\bs_\be_\bt should have been blocked in all threads in the process at |
| 3634 | the time of the call to _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt(); otherwise the signal may be |
| 3635 | delivered to some thread that does not have it blocked. |
| 3636 | |
| 3637 | If more than one thread is using _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() to wait for the same |
| 3638 | signal, no more than one of these threads shall return from |
| 3639 | _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() for any given signal that is sent. Which thread returns |
| 3640 | from _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() if more than a single thread is waiting is |
| 3641 | unspecified. |
| 3642 | |
| 3643 | If the _\bi_\bn_\bf_\bo argument is not NULL, then a _\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b__\bt will be stored there |
| 3644 | which has the selected signal number in its _\bs_\bi_\b__\bs_\bi_\bg_\bn_\bo member and the cause |
| 3645 | of the signal in its _\bs_\bi_\b__\bc_\bo_\bd_\be member. |
| 3646 | |
| 3647 | If the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument is not NULL and no selected signal is currently |
| 3648 | pending, then _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() will wait no longer than the specified |
| 3649 | time period for a signal to arrive before failing. |
| 3650 | |
| 3651 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3652 | If successful, the number of the signal that was accepted is returned. |
| 3653 | Otherwise, a value of -1 is returned and errno is set to indicate the |
| 3654 | error. |
| 3655 | |
| 3656 | E\bER\bRR\bRO\bOR\bRS\bS |
| 3657 | _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() will succeed unless: |
| 3658 | |
| 3659 | [EWOULDBLOCK] The timeout was reached before a selected signal was |
| 3660 | received. |
| 3661 | |
| 3662 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3663 | sigaction(2), sigprocmask(2), sigwait(3) |
| 3664 | |
| 3665 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 3666 | The _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() function is specific to OpenBSD and should not be |
| 3667 | used in portable applications. |
| 3668 | |
| 3669 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3670 | A t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() syscall appeared in OpenBSD 3.9. The _\bi_\bn_\bf_\bo and _\bt_\bi_\bm_\be_\bo_\bu_\bt |
| 3671 | arguments were added in OpenBSD 4.9. |
| 3672 | |
| 3673 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 3674 | The t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() syscall was created by Ted Unangst <_\bt_\be_\bd_\bu_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
| 3675 | This manual page was written by Philip Guenther <_\bg_\bu_\be_\bn_\bt_\bh_\be_\br_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
| 3676 | |
| 3677 | N\bNA\bAM\bME\bE |
| 3678 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp, _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp - userspace thread sleep and wakeup |
| 3679 | |
| 3680 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3681 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 3682 | |
| 3683 | _\bi_\bn_\bt |
| 3684 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bl_\ba_\bt_\bi_\bl_\be _\bv_\bo_\bi_\bd _\b*_\bi_\bd, _\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, |
| 3685 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\ba_\bb_\bs_\bt_\bi_\bm_\be, _\bv_\bo_\bi_\bd _\b*_\bl_\bo_\bc_\bk, _\bc_\bo_\bn_\bs_\bt _\bi_\bn_\bt _\b*_\ba_\bb_\bo_\br_\bt); |
| 3686 | |
| 3687 | _\bi_\bn_\bt |
| 3688 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bl_\ba_\bt_\bi_\bl_\be _\bv_\bo_\bi_\bd _\b*_\bi_\bd, _\bi_\bn_\bt _\bc_\bo_\bu_\bn_\bt); |
| 3689 | |
| 3690 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3691 | The _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() functions provide thread sleep and |
| 3692 | wakeup primitives with which synchronization primitives such as mutexes |
| 3693 | and condition variables can be implemented. _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() blocks the |
| 3694 | calling thread on the abstract ``wait channel'' identified by the _\bi_\bd |
| 3695 | argument until another thread calls _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() with the same _\bi_\bd value. |
| 3696 | If the _\ba_\bb_\bs_\bt_\bi_\bm_\be argument is not NULL, then it specifies an absolute time, |
| 3697 | measured against the _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd clock, after which _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() should time |
| 3698 | out and return. If the specified time is in the past then _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() |
| 3699 | will return immediately without blocking. |
| 3700 | |
| 3701 | The _\bl_\bo_\bc_\bk argument, if not NULL, points to a locked spinlock that will be |
| 3702 | unlocked by _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() atomically with respect to calls to |
| 3703 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(), such that if another thread locks the spinlock before |
| 3704 | calling _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() with the same _\bi_\bd, then the thread that called |
| 3705 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will be eligible for being woken up and unblocked. |
| 3706 | |
| 3707 | The _\ba_\bb_\bo_\br_\bt argument, if not NULL, points to an _\bi_\bn_\bt that will be examined |
| 3708 | after unlocking the spinlock pointed to by _\bl_\bo_\bc_\bk and immediately before |
| 3709 | blocking. If that _\bi_\bn_\bt is non-zero then _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will immediately |
| 3710 | return EINTR without blocking. This provides a mechanism for a signal |
| 3711 | handler to keep a call to _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() from blocking, even if the signal |
| 3712 | is delivered immediately before the call. |
| 3713 | |
| 3714 | The _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() function unblocks one or more threads that are sleeping |
| 3715 | on the wait channel identified by _\bi_\bd. The number of threads unblocked is |
| 3716 | specified by the _\bc_\bo_\bu_\bn_\bt argument, except that if zero is specified then |
| 3717 | all threads sleeping on that _\bi_\bd are unblocked. |
| 3718 | |
| 3719 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3720 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will return zero if woken by a matching call to |
| 3721 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(), otherwise an error number will be returned to indicate the |
| 3722 | error. |
| 3723 | |
| 3724 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() will return zero if at least one matching call to |
| 3725 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() was unblocked, otherwise an error number will be returned to |
| 3726 | indicate the error. |
| 3727 | |
| 3728 | E\bER\bRR\bRO\bOR\bRS\bS |
| 3729 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() will fail if: |
| 3730 | |
| 3731 | [EINVAL] The _\bi_\bd_\be_\bn_\bt argument is NULL. |
| 3732 | |
| 3733 | In addition, _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() may return one of the following errors: |
| 3734 | |
| 3735 | [EWOULDBLOCK] The time specified by the _\ba_\bb_\bs_\bt_\bi_\bm_\be and _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd |
| 3736 | arguments was reached. |
| 3737 | |
| 3738 | [EINTR] A signal arrived or the _\ba_\bb_\bo_\br_\bt argument pointed to a |
| 3739 | non-zero value. |
| 3740 | |
| 3741 | [EINVAL] The _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd argument is neither CLOCK_REALTIME nor |
| 3742 | CLOCK_MONOTONIC. |
| 3743 | |
| 3744 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() may return the following error: |
| 3745 | |
| 3746 | [ESRCH] No threads calling _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() with the same _\bi_\bd were |
| 3747 | found. |
| 3748 | |
| 3749 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3750 | pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9) |
| 3751 | |
| 3752 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 3753 | The _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() functions are specific to OpenBSD and |
| 3754 | should not be used in portable applications. |
| 3755 | |
| 3756 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3757 | The t\bth\bhr\brs\bsl\ble\bee\bep\bp() and t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() syscalls appeared in OpenBSD 3.9. The |
| 3758 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd and _\ba_\bb_\bs_\bt_\bi_\bm_\be arguments were added in OpenBSD 4.9. The functions |
| 3759 | were renamed to _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() and the _\ba_\bb_\bo_\br_\bt argument was |
| 3760 | added in OpenBSD 5.1 |
| 3761 | |
| 3762 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 3763 | The t\bth\bhr\brs\bsl\ble\bee\bep\bp() and t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() syscalls were created by Ted Unangst |
| 3764 | <_\bt_\be_\bd_\bu_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. This manual page was written by Philip Guenther |
| 3765 | <_\bg_\bu_\be_\bn_\bt_\bh_\be_\br_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
| 3766 | |
| 3767 | N\bNA\bAM\bME\bE |
| 3768 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp, _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp - userspace thread sleep and wakeup |
| 3769 | |
| 3770 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3771 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 3772 | |
| 3773 | _\bi_\bn_\bt |
| 3774 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bl_\ba_\bt_\bi_\bl_\be _\bv_\bo_\bi_\bd _\b*_\bi_\bd, _\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, |
| 3775 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\ba_\bb_\bs_\bt_\bi_\bm_\be, _\bv_\bo_\bi_\bd _\b*_\bl_\bo_\bc_\bk, _\bc_\bo_\bn_\bs_\bt _\bi_\bn_\bt _\b*_\ba_\bb_\bo_\br_\bt); |
| 3776 | |
| 3777 | _\bi_\bn_\bt |
| 3778 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bl_\ba_\bt_\bi_\bl_\be _\bv_\bo_\bi_\bd _\b*_\bi_\bd, _\bi_\bn_\bt _\bc_\bo_\bu_\bn_\bt); |
| 3779 | |
| 3780 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3781 | The _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() functions provide thread sleep and |
| 3782 | wakeup primitives with which synchronization primitives such as mutexes |
| 3783 | and condition variables can be implemented. _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() blocks the |
| 3784 | calling thread on the abstract ``wait channel'' identified by the _\bi_\bd |
| 3785 | argument until another thread calls _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() with the same _\bi_\bd value. |
| 3786 | If the _\ba_\bb_\bs_\bt_\bi_\bm_\be argument is not NULL, then it specifies an absolute time, |
| 3787 | measured against the _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd clock, after which _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() should time |
| 3788 | out and return. If the specified time is in the past then _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() |
| 3789 | will return immediately without blocking. |
| 3790 | |
| 3791 | The _\bl_\bo_\bc_\bk argument, if not NULL, points to a locked spinlock that will be |
| 3792 | unlocked by _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() atomically with respect to calls to |
| 3793 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(), such that if another thread locks the spinlock before |
| 3794 | calling _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() with the same _\bi_\bd, then the thread that called |
| 3795 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will be eligible for being woken up and unblocked. |
| 3796 | |
| 3797 | The _\ba_\bb_\bo_\br_\bt argument, if not NULL, points to an _\bi_\bn_\bt that will be examined |
| 3798 | after unlocking the spinlock pointed to by _\bl_\bo_\bc_\bk and immediately before |
| 3799 | blocking. If that _\bi_\bn_\bt is non-zero then _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will immediately |
| 3800 | return EINTR without blocking. This provides a mechanism for a signal |
| 3801 | handler to keep a call to _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() from blocking, even if the signal |
| 3802 | is delivered immediately before the call. |
| 3803 | |
| 3804 | The _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() function unblocks one or more threads that are sleeping |
| 3805 | on the wait channel identified by _\bi_\bd. The number of threads unblocked is |
| 3806 | specified by the _\bc_\bo_\bu_\bn_\bt argument, except that if zero is specified then |
| 3807 | all threads sleeping on that _\bi_\bd are unblocked. |
| 3808 | |
| 3809 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3810 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will return zero if woken by a matching call to |
| 3811 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(), otherwise an error number will be returned to indicate the |
| 3812 | error. |
| 3813 | |
| 3814 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() will return zero if at least one matching call to |
| 3815 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() was unblocked, otherwise an error number will be returned to |
| 3816 | indicate the error. |
| 3817 | |
| 3818 | E\bER\bRR\bRO\bOR\bRS\bS |
| 3819 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() will fail if: |
| 3820 | |
| 3821 | [EINVAL] The _\bi_\bd_\be_\bn_\bt argument is NULL. |
| 3822 | |
| 3823 | In addition, _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() may return one of the following errors: |
| 3824 | |
| 3825 | [EWOULDBLOCK] The time specified by the _\ba_\bb_\bs_\bt_\bi_\bm_\be and _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd |
| 3826 | arguments was reached. |
| 3827 | |
| 3828 | [EINTR] A signal arrived or the _\ba_\bb_\bo_\br_\bt argument pointed to a |
| 3829 | non-zero value. |
| 3830 | |
| 3831 | [EINVAL] The _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd argument is neither CLOCK_REALTIME nor |
| 3832 | CLOCK_MONOTONIC. |
| 3833 | |
| 3834 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() may return the following error: |
| 3835 | |
| 3836 | [ESRCH] No threads calling _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() with the same _\bi_\bd were |
| 3837 | found. |
| 3838 | |
| 3839 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3840 | pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9) |
| 3841 | |
| 3842 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 3843 | The _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() functions are specific to OpenBSD and |
| 3844 | should not be used in portable applications. |
| 3845 | |
| 3846 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3847 | The t\bth\bhr\brs\bsl\ble\bee\bep\bp() and t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() syscalls appeared in OpenBSD 3.9. The |
| 3848 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd and _\ba_\bb_\bs_\bt_\bi_\bm_\be arguments were added in OpenBSD 4.9. The functions |
| 3849 | were renamed to _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() and the _\ba_\bb_\bo_\br_\bt argument was |
| 3850 | added in OpenBSD 5.1 |
| 3851 | |
| 3852 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 3853 | The t\bth\bhr\brs\bsl\ble\bee\bep\bp() and t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() syscalls were created by Ted Unangst |
| 3854 | <_\bt_\be_\bd_\bu_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. This manual page was written by Philip Guenther |
| 3855 | <_\bg_\bu_\be_\bn_\bt_\bh_\be_\br_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
| 3856 | |
| 3857 | N\bNA\bAM\bME\bE |
| 3858 | _\b_e\bex\bxi\bit\bt, _\b_E\bEx\bxi\bit\bt - terminate the calling process |
| 3859 | |
| 3860 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3861 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 3862 | |
| 3863 | _\bv_\bo_\bi_\bd |
| 3864 | _\b_e\bex\bxi\bit\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\bt_\bu_\bs); |
| 3865 | |
| 3866 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdl\bli\bib\bb.\b.h\bh>\b> |
| 3867 | |
| 3868 | _\bv_\bo_\bi_\bd |
| 3869 | _\b_E\bEx\bxi\bit\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\bt_\bu_\bs); |
| 3870 | |
| 3871 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3872 | The _\b_e\bex\bxi\bit\bt() and _\b_E\bEx\bxi\bit\bt() functions terminate a process with the following |
| 3873 | consequences: |
| 3874 | |
| 3875 | +\b+\bo\bo All threads in the process are terminated. |
| 3876 | |
| 3877 | +\b+\bo\bo All open file descriptors in the calling process are closed. This |
| 3878 | may entail delays; for example, waiting for output to drain. A |
| 3879 | process in this state may not be killed, as it is already dying. |
| 3880 | |
| 3881 | +\b+\bo\bo If the parent process of the calling process has an outstanding |
| 3882 | wait(2) call or catches the SIGCHLD signal, it is notified of the |
| 3883 | calling process's termination and _\bs_\bt_\ba_\bt_\bu_\bs is set as defined by |
| 3884 | wait(2). (Note that typically only the lower 8 bits of _\bs_\bt_\ba_\bt_\bu_\bs are |
| 3885 | passed on to the parent, thus negative values have less meaning.) |
| 3886 | |
| 3887 | +\b+\bo\bo The parent process ID of all of the calling process's existing child |
| 3888 | processes are set to 1; the initialization process (see the |
| 3889 | DEFINITIONS section of intro(2)) inherits each of these processes. |
| 3890 | |
| 3891 | +\b+\bo\bo If the termination of the process causes any process group to become |
| 3892 | orphaned (usually because the parents of all members of the group |
| 3893 | have now exited; see Orphaned Process Group in intro(2)), and if any |
| 3894 | member of the orphaned group is stopped, the SIGHUP and SIGCONT |
| 3895 | signals are sent to all members of the newly orphaned process group. |
| 3896 | |
| 3897 | +\b+\bo\bo If the process is a controlling process (see intro(2)), the SIGHUP |
| 3898 | signal is sent to the foreground process group of the controlling |
| 3899 | terminal, and all current access to the controlling terminal is |
| 3900 | revoked. |
| 3901 | |
| 3902 | Most C programs call the library routine exit(3), which flushes buffers, |
| 3903 | closes streams, unlinks temporary files, etc., and then calls _\b_e\bex\bxi\bit\bt(). |
| 3904 | |
| 3905 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3906 | _\b_e\bex\bxi\bit\bt() and _\b_E\bEx\bxi\bit\bt() can never return. |
| 3907 | |
| 3908 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 3909 | fork(2), intro(2), sigaction(2), wait(2), exit(3), sysexits(3) |
| 3910 | |
| 3911 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 3912 | The _\b_e\bex\bxi\bit\bt() function conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
| 3913 | _\b_E\bEx\bxi\bit\bt() function conforms to ISO/IEC 9899:1999 (``ISO C99''). |
| 3914 | |
| 3915 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 3916 | An e\bex\bxi\bit\bt() system call first appeared in Version 1 AT&T UNIX. It accepts |
| 3917 | the _\bs_\bt_\ba_\bt_\bu_\bs argument since Version 2 AT&T UNIX. An _\b_e\bex\bxi\bit\bt() variant first |
| 3918 | appeared in Version 7 AT&T UNIX. The _\b_E\bEx\bxi\bit\bt() function appeared in |
| 3919 | OpenBSD 3.6. |
| 3920 | |
| 3921 | N\bNA\bAM\bME\bE |
| 3922 | a\bac\bcc\bce\bep\bpt\bt, a\bac\bcc\bce\bep\bpt\bt4\b4 - accept a connection on a socket |
| 3923 | |
| 3924 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 3925 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 3926 | |
| 3927 | _\bi_\bn_\bt |
| 3928 | a\bac\bcc\bce\bep\bpt\bt(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\ba_\bd_\bd_\br, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\ba_\bd_\bd_\br_\bl_\be_\bn); |
| 3929 | |
| 3930 | _\bi_\bn_\bt |
| 3931 | a\bac\bcc\bce\bep\bpt\bt4\b4(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\ba_\bd_\bd_\br, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\ba_\bd_\bd_\br_\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 3932 | |
| 3933 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 3934 | The argument _\bs is a socket that has been created with socket(2), bound to |
| 3935 | an address with bind(2), and is listening for connections after a |
| 3936 | listen(2). The a\bac\bcc\bce\bep\bpt\bt() call extracts the first connection request on |
| 3937 | the queue of pending connections, creates a new socket with the same non- |
| 3938 | blocking I/O mode as _\bs, and allocates a new file descriptor for the |
| 3939 | socket with the close-on-exec flag clear. |
| 3940 | |
| 3941 | The a\bac\bcc\bce\bep\bpt\bt4\b4() system call is similar, however the non-blocking I/O mode |
| 3942 | of the new socket is determined by the SOCK_NONBLOCK flag in the _\bf_\bl_\ba_\bg_\bs |
| 3943 | argument and the close-on-exec flag on the new file descriptor is |
| 3944 | determined by the SOCK_CLOEXEC flag in the _\bf_\bl_\ba_\bg_\bs argument. |
| 3945 | |
| 3946 | If no pending connections are present on the queue, and the socket is not |
| 3947 | marked as non-blocking, a\bac\bcc\bce\bep\bpt\bt() blocks the caller until a connection is |
| 3948 | present. If the socket is marked non-blocking and no pending connections |
| 3949 | are present on the queue, a\bac\bcc\bce\bep\bpt\bt() returns an error as described below. |
| 3950 | The accepted socket may not be used to accept more connections. The |
| 3951 | original socket _\bs remains open. |
| 3952 | |
| 3953 | The argument _\ba_\bd_\bd_\br is a result parameter that is filled in with the |
| 3954 | address of the connecting entity as known to the communications layer. |
| 3955 | The exact format of the _\ba_\bd_\bd_\br parameter is determined by the domain in |
| 3956 | which the communication is occurring. The structure sockaddr_storage |
| 3957 | exists for greater portability. It is large enough to hold any of the |
| 3958 | types that may be returned in the _\ba_\bd_\bd_\br parameter. |
| 3959 | |
| 3960 | The _\ba_\bd_\bd_\br_\bl_\be_\bn is a value-result parameter; it should initially contain the |
| 3961 | amount of space pointed to by _\ba_\bd_\bd_\br; on return it will contain the actual |
| 3962 | length (in bytes) of the address returned. If _\ba_\bd_\bd_\br_\bl_\be_\bn does not point to |
| 3963 | enough space to hold the entire socket address, the result will be |
| 3964 | truncated to the initial value of _\ba_\bd_\bd_\br_\bl_\be_\bn (in bytes). This call is used |
| 3965 | with connection-based socket types, currently with SOCK_STREAM. |
| 3966 | |
| 3967 | It is possible to select(2) or poll(2) a socket for the purposes of doing |
| 3968 | an a\bac\bcc\bce\bep\bpt\bt() by selecting it for read. |
| 3969 | |
| 3970 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 3971 | The call returns -1 on error. If it succeeds, it returns a non-negative |
| 3972 | integer that is a descriptor for the accepted socket. |
| 3973 | |
| 3974 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS |
| 3975 | The following code uses struct sockaddr_storage to allocate enough space |
| 3976 | for the returned address: |
| 3977 | |
| 3978 | #include <sys/types.h> |
| 3979 | #include <sys/socket.h> |
| 3980 | |
| 3981 | struct sockaddr_storage addr; |
| 3982 | socklen_t len = sizeof(addr); |
| 3983 | int retcode; |
| 3984 | |
| 3985 | retcode = accept(s, (struct sockaddr *)&addr, &len); |
| 3986 | if (retcode == -1) |
| 3987 | err(1, "accept"); |
| 3988 | |
| 3989 | E\bER\bRR\bRO\bOR\bRS\bS |
| 3990 | a\bac\bcc\bce\bep\bpt\bt() and a\bac\bcc\bce\bep\bpt\bt4\b4() will fail if: |
| 3991 | |
| 3992 | [EBADF] The descriptor is invalid. |
| 3993 | |
| 3994 | [ENOTSOCK] The descriptor doesn't reference a socket. |
| 3995 | |
| 3996 | [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM. |
| 3997 | |
| 3998 | [EINTR] A signal was caught before a connection arrived. |
| 3999 | |
| 4000 | [EINVAL] The referenced socket is not listening for connections |
| 4001 | (that is, listen(2) has not yet been called). |
| 4002 | |
| 4003 | [EFAULT] The _\ba_\bd_\bd_\br or _\ba_\bd_\bd_\br_\bl_\be_\bn parameter is not in a valid part |
| 4004 | of the process address space. |
| 4005 | |
| 4006 | [EWOULDBLOCK] The socket is marked non-blocking and no connections |
| 4007 | are present to be accepted. |
| 4008 | |
| 4009 | [EMFILE] The per-process descriptor table is full. |
| 4010 | |
| 4011 | [ENFILE] The system file table is full. |
| 4012 | |
| 4013 | [ECONNABORTED] A connection has been aborted. |
| 4014 | |
| 4015 | In addition, a\bac\bcc\bce\bep\bpt\bt4\b4() will fail if |
| 4016 | |
| 4017 | [EINVAL] _\bf_\bl_\ba_\bg_\bs is invalid. |
| 4018 | |
| 4019 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 4020 | bind(2), connect(2), listen(2), poll(2), select(2), socket(2) |
| 4021 | |
| 4022 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 4023 | The a\bac\bcc\bce\bep\bpt\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 4024 | The a\bac\bcc\bce\bep\bpt\bt4\b4() function is expected to conform to a future revision of |
| 4025 | that standard. |
| 4026 | |
| 4027 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4028 | The a\bac\bcc\bce\bep\bpt\bt() system call first appeared in 4.1cBSD and a\bac\bcc\bce\bep\bpt\bt4\b4() in |
| 4029 | OpenBSD 5.7. |
| 4030 | |
| 4031 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4032 | When EMFILE or ENFILE is returned, new connections are neither dequeued |
| 4033 | nor discarded. Thus considerable care is required in select(2) and |
| 4034 | poll(2) loops. |
| 4035 | |
| 4036 | N\bNA\bAM\bME\bE |
| 4037 | a\bac\bcc\bce\bep\bpt\bt, a\bac\bcc\bce\bep\bpt\bt4\b4 - accept a connection on a socket |
| 4038 | |
| 4039 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4040 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 4041 | |
| 4042 | _\bi_\bn_\bt |
| 4043 | a\bac\bcc\bce\bep\bpt\bt(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\ba_\bd_\bd_\br, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\ba_\bd_\bd_\br_\bl_\be_\bn); |
| 4044 | |
| 4045 | _\bi_\bn_\bt |
| 4046 | a\bac\bcc\bce\bep\bpt\bt4\b4(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\ba_\bd_\bd_\br, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\ba_\bd_\bd_\br_\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 4047 | |
| 4048 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4049 | The argument _\bs is a socket that has been created with socket(2), bound to |
| 4050 | an address with bind(2), and is listening for connections after a |
| 4051 | listen(2). The a\bac\bcc\bce\bep\bpt\bt() call extracts the first connection request on |
| 4052 | the queue of pending connections, creates a new socket with the same non- |
| 4053 | blocking I/O mode as _\bs, and allocates a new file descriptor for the |
| 4054 | socket with the close-on-exec flag clear. |
| 4055 | |
| 4056 | The a\bac\bcc\bce\bep\bpt\bt4\b4() system call is similar, however the non-blocking I/O mode |
| 4057 | of the new socket is determined by the SOCK_NONBLOCK flag in the _\bf_\bl_\ba_\bg_\bs |
| 4058 | argument and the close-on-exec flag on the new file descriptor is |
| 4059 | determined by the SOCK_CLOEXEC flag in the _\bf_\bl_\ba_\bg_\bs argument. |
| 4060 | |
| 4061 | If no pending connections are present on the queue, and the socket is not |
| 4062 | marked as non-blocking, a\bac\bcc\bce\bep\bpt\bt() blocks the caller until a connection is |
| 4063 | present. If the socket is marked non-blocking and no pending connections |
| 4064 | are present on the queue, a\bac\bcc\bce\bep\bpt\bt() returns an error as described below. |
| 4065 | The accepted socket may not be used to accept more connections. The |
| 4066 | original socket _\bs remains open. |
| 4067 | |
| 4068 | The argument _\ba_\bd_\bd_\br is a result parameter that is filled in with the |
| 4069 | address of the connecting entity as known to the communications layer. |
| 4070 | The exact format of the _\ba_\bd_\bd_\br parameter is determined by the domain in |
| 4071 | which the communication is occurring. The structure sockaddr_storage |
| 4072 | exists for greater portability. It is large enough to hold any of the |
| 4073 | types that may be returned in the _\ba_\bd_\bd_\br parameter. |
| 4074 | |
| 4075 | The _\ba_\bd_\bd_\br_\bl_\be_\bn is a value-result parameter; it should initially contain the |
| 4076 | amount of space pointed to by _\ba_\bd_\bd_\br; on return it will contain the actual |
| 4077 | length (in bytes) of the address returned. If _\ba_\bd_\bd_\br_\bl_\be_\bn does not point to |
| 4078 | enough space to hold the entire socket address, the result will be |
| 4079 | truncated to the initial value of _\ba_\bd_\bd_\br_\bl_\be_\bn (in bytes). This call is used |
| 4080 | with connection-based socket types, currently with SOCK_STREAM. |
| 4081 | |
| 4082 | It is possible to select(2) or poll(2) a socket for the purposes of doing |
| 4083 | an a\bac\bcc\bce\bep\bpt\bt() by selecting it for read. |
| 4084 | |
| 4085 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 4086 | The call returns -1 on error. If it succeeds, it returns a non-negative |
| 4087 | integer that is a descriptor for the accepted socket. |
| 4088 | |
| 4089 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS |
| 4090 | The following code uses struct sockaddr_storage to allocate enough space |
| 4091 | for the returned address: |
| 4092 | |
| 4093 | #include <sys/types.h> |
| 4094 | #include <sys/socket.h> |
| 4095 | |
| 4096 | struct sockaddr_storage addr; |
| 4097 | socklen_t len = sizeof(addr); |
| 4098 | int retcode; |
| 4099 | |
| 4100 | retcode = accept(s, (struct sockaddr *)&addr, &len); |
| 4101 | if (retcode == -1) |
| 4102 | err(1, "accept"); |
| 4103 | |
| 4104 | E\bER\bRR\bRO\bOR\bRS\bS |
| 4105 | a\bac\bcc\bce\bep\bpt\bt() and a\bac\bcc\bce\bep\bpt\bt4\b4() will fail if: |
| 4106 | |
| 4107 | [EBADF] The descriptor is invalid. |
| 4108 | |
| 4109 | [ENOTSOCK] The descriptor doesn't reference a socket. |
| 4110 | |
| 4111 | [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM. |
| 4112 | |
| 4113 | [EINTR] A signal was caught before a connection arrived. |
| 4114 | |
| 4115 | [EINVAL] The referenced socket is not listening for connections |
| 4116 | (that is, listen(2) has not yet been called). |
| 4117 | |
| 4118 | [EFAULT] The _\ba_\bd_\bd_\br or _\ba_\bd_\bd_\br_\bl_\be_\bn parameter is not in a valid part |
| 4119 | of the process address space. |
| 4120 | |
| 4121 | [EWOULDBLOCK] The socket is marked non-blocking and no connections |
| 4122 | are present to be accepted. |
| 4123 | |
| 4124 | [EMFILE] The per-process descriptor table is full. |
| 4125 | |
| 4126 | [ENFILE] The system file table is full. |
| 4127 | |
| 4128 | [ECONNABORTED] A connection has been aborted. |
| 4129 | |
| 4130 | In addition, a\bac\bcc\bce\bep\bpt\bt4\b4() will fail if |
| 4131 | |
| 4132 | [EINVAL] _\bf_\bl_\ba_\bg_\bs is invalid. |
| 4133 | |
| 4134 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 4135 | bind(2), connect(2), listen(2), poll(2), select(2), socket(2) |
| 4136 | |
| 4137 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 4138 | The a\bac\bcc\bce\bep\bpt\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 4139 | The a\bac\bcc\bce\bep\bpt\bt4\b4() function is expected to conform to a future revision of |
| 4140 | that standard. |
| 4141 | |
| 4142 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4143 | The a\bac\bcc\bce\bep\bpt\bt() system call first appeared in 4.1cBSD and a\bac\bcc\bce\bep\bpt\bt4\b4() in |
| 4144 | OpenBSD 5.7. |
| 4145 | |
| 4146 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4147 | When EMFILE or ENFILE is returned, new connections are neither dequeued |
| 4148 | nor discarded. Thus considerable care is required in select(2) and |
| 4149 | poll(2) loops. |
| 4150 | |
| 4151 | N\bNA\bAM\bME\bE |
| 4152 | a\bac\bcc\bce\bes\bss\bs, f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt - check access permissions of a file or pathname |
| 4153 | |
| 4154 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4155 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 4156 | |
| 4157 | _\bi_\bn_\bt |
| 4158 | a\bac\bcc\bce\bes\bss\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\ba_\bm_\bo_\bd_\be); |
| 4159 | |
| 4160 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 4161 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 4162 | |
| 4163 | _\bi_\bn_\bt |
| 4164 | f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\ba_\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 4165 | |
| 4166 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4167 | The a\bac\bcc\bce\bes\bss\bs() function checks the accessibility of the file named by _\bp_\ba_\bt_\bh |
| 4168 | for the access permissions indicated by _\ba_\bm_\bo_\bd_\be. The _\ba_\bm_\bo_\bd_\be argument is |
| 4169 | either the bitwise OR of one or more of the access permissions to be |
| 4170 | checked (R_OK for read permission, W_OK for write permission, and X_OK |
| 4171 | for execute/search permission) or the existence test, F_OK. All |
| 4172 | components of the pathname _\bp_\ba_\bt_\bh are checked for access permissions |
| 4173 | (including F_OK). |
| 4174 | |
| 4175 | The real user ID is used in place of the effective user ID and the real |
| 4176 | group access list (including the real group ID) is used in place of the |
| 4177 | effective ID for verifying permission. |
| 4178 | |
| 4179 | If the invoking process has superuser privileges, a\bac\bcc\bce\bes\bss\bs() will always |
| 4180 | indicate success for R_OK and W_OK, regardless of the actual file |
| 4181 | permission bits. Likewise, for X_OK, if the file has any of the execute |
| 4182 | bits set and _\bp_\ba_\bt_\bh is not a directory, a\bac\bcc\bce\bes\bss\bs() will indicate success. |
| 4183 | |
| 4184 | The f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() function is equivalent to a\bac\bcc\bce\bes\bss\bs() except that where _\bp_\ba_\bt_\bh |
| 4185 | specifies a relative path, the file whose accessibility is checked is |
| 4186 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 4187 | instead of the current working directory. |
| 4188 | |
| 4189 | If f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 4190 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 4191 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to a\bac\bcc\bce\bes\bss\bs(). |
| 4192 | |
| 4193 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 4194 | values: |
| 4195 | |
| 4196 | AT_EACCESS The checks for accessibility are performed using the |
| 4197 | effective user and group IDs instead of the real user |
| 4198 | and group IDs. |
| 4199 | |
| 4200 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 4201 | If _\bp_\ba_\bt_\bh cannot be found or if any of the desired access modes would not |
| 4202 | be granted, then a -1 value is returned; otherwise a 0 value is returned. |
| 4203 | |
| 4204 | E\bER\bRR\bRO\bOR\bRS\bS |
| 4205 | Access to the file is denied if: |
| 4206 | |
| 4207 | [ENOTDIR] A component of the path prefix is not a directory. |
| 4208 | |
| 4209 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 4210 | characters, or an entire pathname (including the |
| 4211 | terminating NUL) exceeded PATH_MAX bytes. |
| 4212 | |
| 4213 | [ENOENT] The named file does not exist. |
| 4214 | |
| 4215 | [ELOOP] Too many symbolic links were encountered in |
| 4216 | translating the pathname. |
| 4217 | |
| 4218 | [EROFS] Write access is requested for a file on a read-only |
| 4219 | file system. |
| 4220 | |
| 4221 | [ETXTBSY] Write access is requested for a pure procedure (shared |
| 4222 | text) file presently being executed. |
| 4223 | |
| 4224 | [EACCES] Permission bits of the file mode do not permit the |
| 4225 | requested access, or search permission is denied on a |
| 4226 | component of the path prefix. The owner of a file has |
| 4227 | permission checked with respect to the ``owner'' read, |
| 4228 | write, and execute mode bits, members of the file's |
| 4229 | group other than the owner have permission checked |
| 4230 | with respect to the ``group'' mode bits, and all |
| 4231 | others have permissions checked with respect to the |
| 4232 | ``other'' mode bits. |
| 4233 | |
| 4234 | [EPERM] Write access has been requested and the named file has |
| 4235 | its immutable flag set (see chflags(2)). |
| 4236 | |
| 4237 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 4238 | space. |
| 4239 | |
| 4240 | [EIO] An I/O error occurred while reading from or writing to |
| 4241 | the file system. |
| 4242 | |
| 4243 | [EINVAL] An invalid value was specified for _\ba_\bm_\bo_\bd_\be. |
| 4244 | |
| 4245 | Additionally, f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() will fail if: |
| 4246 | |
| 4247 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 4248 | AT_EACCESS. |
| 4249 | |
| 4250 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 4251 | argument is neither AT_FDCWD nor a valid file |
| 4252 | descriptor. |
| 4253 | |
| 4254 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 4255 | argument is a valid file descriptor but it does not |
| 4256 | reference a directory. |
| 4257 | |
| 4258 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 4259 | permission is denied for the directory which the _\bf_\bd |
| 4260 | file descriptor references. |
| 4261 | |
| 4262 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 4263 | chmod(2), stat(2) |
| 4264 | |
| 4265 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 4266 | The a\bac\bcc\bce\bes\bss\bs() and f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 4267 | (``POSIX.1''). |
| 4268 | |
| 4269 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4270 | a\bac\bcc\bce\bes\bss\bs() first appeared as an internal kernel function in Version 1 AT&T |
| 4271 | UNIX and was reimplemented in C before the release of Version 4 AT&T |
| 4272 | UNIX. It was first promoted to a system call in the Programmer's |
| 4273 | Workbench (PWB/UNIX), which was later ported to Version 7 AT&T UNIX and |
| 4274 | 2BSD. |
| 4275 | |
| 4276 | The f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() function appeared in OpenBSD 5.0. |
| 4277 | |
| 4278 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 4279 | Ken Thompson first implemented the a\bac\bcc\bce\bes\bss\bs() kernel function in C. |
| 4280 | |
| 4281 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4282 | a\bac\bcc\bce\bes\bss\bs() and f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() should never be used for actual access control. |
| 4283 | Doing so can result in a time of check vs. time of use security hole. |
| 4284 | |
| 4285 | N\bNA\bAM\bME\bE |
| 4286 | a\bac\bcc\bct\bt - enable or disable process accounting |
| 4287 | |
| 4288 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4289 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 4290 | |
| 4291 | _\bi_\bn_\bt |
| 4292 | a\bac\bcc\bct\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be); |
| 4293 | |
| 4294 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4295 | The a\bac\bcc\bct\bt() call enables or disables the collection of system accounting |
| 4296 | records. If _\bf_\bi_\bl_\be is NULL, accounting is disabled. If _\bf_\bi_\bl_\be is an |
| 4297 | existing, NUL-terminated pathname, record collection is enabled and for |
| 4298 | every process initiated which terminates under normal conditions an |
| 4299 | accounting record is appended to _\bf_\bi_\bl_\be. Abnormal conditions of |
| 4300 | termination are reboots or other fatal system problems. Records for |
| 4301 | processes which never terminate cannot be produced by a\bac\bcc\bct\bt(). a\bac\bcc\bct\bt() is |
| 4302 | only available on kernels compiled with the A\bAC\bCC\bCO\bOU\bUN\bNT\bTI\bIN\bNG\bG option. |
| 4303 | |
| 4304 | For more information on the record structure used by a\bac\bcc\bct\bt(), see |
| 4305 | _\b/_\bu_\bs_\br_\b/_\bi_\bn_\bc_\bl_\bu_\bd_\be_\b/_\bs_\by_\bs_\b/_\ba_\bc_\bc_\bt_\b._\bh and acct(5). |
| 4306 | |
| 4307 | This call is permitted only to the superuser. |
| 4308 | |
| 4309 | N\bNO\bOT\bTE\bES\bS |
| 4310 | Accounting is automatically disabled when the file system the accounting |
| 4311 | file resides on runs out of space; it is enabled when space once again |
| 4312 | becomes available. |
| 4313 | |
| 4314 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 4315 | Upon successful completion, the value 0 is returned; otherwise the |
| 4316 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 4317 | error. |
| 4318 | |
| 4319 | E\bER\bRR\bRO\bOR\bRS\bS |
| 4320 | a\bac\bcc\bct\bt() will fail if one of the following is true: |
| 4321 | |
| 4322 | [EPERM] The caller is not the superuser. |
| 4323 | |
| 4324 | [ENOTDIR] A component of the path prefix is not a directory. |
| 4325 | |
| 4326 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 4327 | characters, or an entire pathname (including the |
| 4328 | terminating NUL) exceeded PATH_MAX bytes. |
| 4329 | |
| 4330 | [ENOENT] The named file does not exist. |
| 4331 | |
| 4332 | [EACCES] Search permission is denied for a component of the |
| 4333 | path prefix, or the path name is not a regular file. |
| 4334 | |
| 4335 | [ELOOP] Too many symbolic links were encountered in |
| 4336 | translating the pathname. |
| 4337 | |
| 4338 | [EROFS] The named file resides on a read-only file system. |
| 4339 | |
| 4340 | [EFAULT] _\bf_\bi_\bl_\be points outside the process's allocated address |
| 4341 | space. |
| 4342 | |
| 4343 | [EIO] An I/O error occurred while reading from or writing to |
| 4344 | the file system. |
| 4345 | |
| 4346 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 4347 | acct(5), accton(8), sa(8) |
| 4348 | |
| 4349 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4350 | An a\bac\bcc\bct\bt() function call appeared in Version 7 AT&T UNIX. |
| 4351 | |
| 4352 | N\bNA\bAM\bME\bE |
| 4353 | a\bad\bdj\bjf\bfr\bre\beq\bq - correct the rate of the system clock |
| 4354 | |
| 4355 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4356 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 4357 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 4358 | |
| 4359 | _\bi_\bn_\bt |
| 4360 | a\bad\bdj\bjf\bfr\bre\beq\bq(_\bc_\bo_\bn_\bs_\bt _\bi_\bn_\bt_\b6_\b4_\b__\bt _\b*_\bf_\br_\be_\bq, _\bi_\bn_\bt_\b6_\b4_\b__\bt _\b*_\bo_\bl_\bd_\bf_\br_\be_\bq); |
| 4361 | |
| 4362 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4363 | a\bad\bdj\bjf\bfr\bre\beq\bq() adjusts the rate in which time progresses if _\bf_\br_\be_\bq is non-null. |
| 4364 | The unit of the rate of adjustment is nanoseconds per second, shifted |
| 4365 | left 32 bits to allow for fractional values. |
| 4366 | |
| 4367 | If _\bo_\bl_\bd_\bf_\br_\be_\bq is non-null, the current value is returned. |
| 4368 | |
| 4369 | Only the superuser may adjust the frequency. |
| 4370 | |
| 4371 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 4372 | Upon successful completion, the value 0 is returned; otherwise the |
| 4373 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 4374 | error. |
| 4375 | |
| 4376 | E\bER\bRR\bRO\bOR\bRS\bS |
| 4377 | a\bad\bdj\bjf\bfr\bre\beq\bq() will fail if: |
| 4378 | |
| 4379 | [EFAULT] Either of the arguments point outside the process's |
| 4380 | allocated address space. |
| 4381 | |
| 4382 | [EPERM] The _\bf_\br_\be_\bq argument is non-null and the process's |
| 4383 | effective user ID is not that of the superuser. |
| 4384 | |
| 4385 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 4386 | date(1), adjtime(2), gettimeofday(2), ntpd(8) |
| 4387 | |
| 4388 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4389 | The a\bad\bdj\bjf\bfr\bre\beq\bq() function call first appeared in OpenBSD 4.0. |
| 4390 | |
| 4391 | N\bNA\bAM\bME\bE |
| 4392 | a\bad\bdj\bjt\bti\bim\bme\be - correct the time to allow synchronization of the system clock |
| 4393 | |
| 4394 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4395 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 4396 | |
| 4397 | _\bi_\bn_\bt |
| 4398 | a\bad\bdj\bjt\bti\bim\bme\be(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bd_\be_\bl_\bt_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bo_\bl_\bd_\bd_\be_\bl_\bt_\ba); |
| 4399 | |
| 4400 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4401 | a\bad\bdj\bjt\bti\bim\bme\be() makes small adjustments to the system time, as returned by |
| 4402 | gettimeofday(2), advancing or retarding it by the time specified by the |
| 4403 | timeval _\bd_\be_\bl_\bt_\ba. If _\bd_\be_\bl_\bt_\ba is negative, the clock is slowed down by |
| 4404 | incrementing it more slowly than normal until the correction is complete. |
| 4405 | If _\bd_\be_\bl_\bt_\ba is positive, a larger increment than normal is used. The skew |
| 4406 | used to perform the correction is generally a fraction of one percent. |
| 4407 | Thus, the time is always a monotonically increasing function. A time |
| 4408 | correction from an earlier call to a\bad\bdj\bjt\bti\bim\bme\be() may not be finished when |
| 4409 | a\bad\bdj\bjt\bti\bim\bme\be() is called again. If _\bd_\be_\bl_\bt_\ba is null, no adjustment is done. If |
| 4410 | _\bo_\bl_\bd_\bd_\be_\bl_\bt_\ba is non-null, the structure pointed to will contain, upon return, |
| 4411 | the number of microseconds still to be corrected from the earlier call. |
| 4412 | Setting the time with settimeofday(2) will cancel any in-progress time |
| 4413 | adjustment. |
| 4414 | |
| 4415 | This call may be used by time servers that synchronize the clocks of |
| 4416 | computers in a local area network. Such time servers would slow down the |
| 4417 | clocks of some machines and speed up the clocks of others to bring them |
| 4418 | to the average network time. |
| 4419 | |
| 4420 | Only the superuser may adjust the time using the a\bad\bdj\bjt\bti\bim\bme\be() function. |
| 4421 | |
| 4422 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 4423 | Upon successful completion, the value 0 is returned; otherwise the |
| 4424 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 4425 | error. |
| 4426 | |
| 4427 | E\bER\bRR\bRO\bOR\bRS\bS |
| 4428 | a\bad\bdj\bjt\bti\bim\bme\be() will fail if: |
| 4429 | |
| 4430 | [EFAULT] Either of the arguments point outside the process's |
| 4431 | allocated address space. |
| 4432 | |
| 4433 | [EPERM] The d\bde\bel\blt\bta\ba() argument is non-null and the process's |
| 4434 | effective user ID is not that of the superuser. |
| 4435 | |
| 4436 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 4437 | date(1), adjfreq(2), gettimeofday(2), ntpd(8) |
| 4438 | |
| 4439 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4440 | The a\bad\bdj\bjt\bti\bim\bme\be() function call appeared in 4.3BSD. |
| 4441 | |
| 4442 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4443 | Other operating systems restrict calling k\bkq\bqu\bue\beu\bue\be to the superuser and |
| 4444 | might not allow requesting the current correction without specifying a |
| 4445 | new value. |
| 4446 | |
| 4447 | N\bNA\bAM\bME\bE |
| 4448 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 4449 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 4450 | ports and memory access functions |
| 4451 | |
| 4452 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4453 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 4454 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 4455 | |
| 4456 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4457 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4458 | |
| 4459 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4460 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4461 | |
| 4462 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4463 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4464 | |
| 4465 | _\bi_\bn_\bt |
| 4466 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 4467 | |
| 4468 | _\bv_\bo_\bi_\bd _\b* |
| 4469 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4470 | |
| 4471 | _\bv_\bo_\bi_\bd |
| 4472 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4473 | |
| 4474 | _\bv_\bo_\bi_\bd |
| 4475 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4476 | |
| 4477 | _\bv_\bo_\bi_\bd |
| 4478 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4479 | |
| 4480 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4481 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4482 | |
| 4483 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4484 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4485 | |
| 4486 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4487 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4488 | |
| 4489 | _\bv_\bo_\bi_\bd |
| 4490 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4491 | |
| 4492 | _\bv_\bo_\bi_\bd |
| 4493 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4494 | |
| 4495 | _\bv_\bo_\bi_\bd |
| 4496 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4497 | |
| 4498 | _\bv_\bo_\bi_\bd |
| 4499 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4500 | |
| 4501 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4502 | The functions in libalpha give userland programs access to the I/O ports |
| 4503 | on the OpenBSD/alpha platform. |
| 4504 | |
| 4505 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 4506 | |
| 4507 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 4508 | |
| 4509 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 4510 | disables access if _\bo_\bn is FALSE. |
| 4511 | |
| 4512 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 4513 | memory. |
| 4514 | |
| 4515 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 4516 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4517 | |
| 4518 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 4519 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4520 | |
| 4521 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 4522 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4523 | |
| 4524 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 4525 | |
| 4526 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4527 | These functions originally appeared in FreeBSD. |
| 4528 | |
| 4529 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4530 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 4531 | type access are not supported. |
| 4532 | |
| 4533 | Root credentials are needed to use these functions. |
| 4534 | |
| 4535 | N\bNA\bAM\bME\bE |
| 4536 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 4537 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 4538 | ports and memory access functions |
| 4539 | |
| 4540 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4541 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 4542 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 4543 | |
| 4544 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4545 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4546 | |
| 4547 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4548 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4549 | |
| 4550 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4551 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4552 | |
| 4553 | _\bi_\bn_\bt |
| 4554 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 4555 | |
| 4556 | _\bv_\bo_\bi_\bd _\b* |
| 4557 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4558 | |
| 4559 | _\bv_\bo_\bi_\bd |
| 4560 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4561 | |
| 4562 | _\bv_\bo_\bi_\bd |
| 4563 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4564 | |
| 4565 | _\bv_\bo_\bi_\bd |
| 4566 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4567 | |
| 4568 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4569 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4570 | |
| 4571 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4572 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4573 | |
| 4574 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4575 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4576 | |
| 4577 | _\bv_\bo_\bi_\bd |
| 4578 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4579 | |
| 4580 | _\bv_\bo_\bi_\bd |
| 4581 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4582 | |
| 4583 | _\bv_\bo_\bi_\bd |
| 4584 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4585 | |
| 4586 | _\bv_\bo_\bi_\bd |
| 4587 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4588 | |
| 4589 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4590 | The functions in libalpha give userland programs access to the I/O ports |
| 4591 | on the OpenBSD/alpha platform. |
| 4592 | |
| 4593 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 4594 | |
| 4595 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 4596 | |
| 4597 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 4598 | disables access if _\bo_\bn is FALSE. |
| 4599 | |
| 4600 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 4601 | memory. |
| 4602 | |
| 4603 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 4604 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4605 | |
| 4606 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 4607 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4608 | |
| 4609 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 4610 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4611 | |
| 4612 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 4613 | |
| 4614 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4615 | These functions originally appeared in FreeBSD. |
| 4616 | |
| 4617 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4618 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 4619 | type access are not supported. |
| 4620 | |
| 4621 | Root credentials are needed to use these functions. |
| 4622 | |
| 4623 | N\bNA\bAM\bME\bE |
| 4624 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 4625 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 4626 | ports and memory access functions |
| 4627 | |
| 4628 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4629 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 4630 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 4631 | |
| 4632 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4633 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4634 | |
| 4635 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4636 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4637 | |
| 4638 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4639 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4640 | |
| 4641 | _\bi_\bn_\bt |
| 4642 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 4643 | |
| 4644 | _\bv_\bo_\bi_\bd _\b* |
| 4645 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4646 | |
| 4647 | _\bv_\bo_\bi_\bd |
| 4648 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4649 | |
| 4650 | _\bv_\bo_\bi_\bd |
| 4651 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4652 | |
| 4653 | _\bv_\bo_\bi_\bd |
| 4654 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4655 | |
| 4656 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4657 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4658 | |
| 4659 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4660 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4661 | |
| 4662 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4663 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4664 | |
| 4665 | _\bv_\bo_\bi_\bd |
| 4666 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4667 | |
| 4668 | _\bv_\bo_\bi_\bd |
| 4669 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4670 | |
| 4671 | _\bv_\bo_\bi_\bd |
| 4672 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4673 | |
| 4674 | _\bv_\bo_\bi_\bd |
| 4675 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4676 | |
| 4677 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4678 | The functions in libalpha give userland programs access to the I/O ports |
| 4679 | on the OpenBSD/alpha platform. |
| 4680 | |
| 4681 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 4682 | |
| 4683 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 4684 | |
| 4685 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 4686 | disables access if _\bo_\bn is FALSE. |
| 4687 | |
| 4688 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 4689 | memory. |
| 4690 | |
| 4691 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 4692 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4693 | |
| 4694 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 4695 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4696 | |
| 4697 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 4698 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4699 | |
| 4700 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 4701 | |
| 4702 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4703 | These functions originally appeared in FreeBSD. |
| 4704 | |
| 4705 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4706 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 4707 | type access are not supported. |
| 4708 | |
| 4709 | Root credentials are needed to use these functions. |
| 4710 | |
| 4711 | N\bNA\bAM\bME\bE |
| 4712 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 4713 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 4714 | ports and memory access functions |
| 4715 | |
| 4716 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4717 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 4718 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 4719 | |
| 4720 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4721 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4722 | |
| 4723 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4724 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4725 | |
| 4726 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4727 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4728 | |
| 4729 | _\bi_\bn_\bt |
| 4730 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 4731 | |
| 4732 | _\bv_\bo_\bi_\bd _\b* |
| 4733 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4734 | |
| 4735 | _\bv_\bo_\bi_\bd |
| 4736 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4737 | |
| 4738 | _\bv_\bo_\bi_\bd |
| 4739 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4740 | |
| 4741 | _\bv_\bo_\bi_\bd |
| 4742 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4743 | |
| 4744 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4745 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4746 | |
| 4747 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4748 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4749 | |
| 4750 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4751 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4752 | |
| 4753 | _\bv_\bo_\bi_\bd |
| 4754 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4755 | |
| 4756 | _\bv_\bo_\bi_\bd |
| 4757 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4758 | |
| 4759 | _\bv_\bo_\bi_\bd |
| 4760 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4761 | |
| 4762 | _\bv_\bo_\bi_\bd |
| 4763 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4764 | |
| 4765 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4766 | The functions in libalpha give userland programs access to the I/O ports |
| 4767 | on the OpenBSD/alpha platform. |
| 4768 | |
| 4769 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 4770 | |
| 4771 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 4772 | |
| 4773 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 4774 | disables access if _\bo_\bn is FALSE. |
| 4775 | |
| 4776 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 4777 | memory. |
| 4778 | |
| 4779 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 4780 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4781 | |
| 4782 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 4783 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4784 | |
| 4785 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 4786 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4787 | |
| 4788 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 4789 | |
| 4790 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4791 | These functions originally appeared in FreeBSD. |
| 4792 | |
| 4793 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4794 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 4795 | type access are not supported. |
| 4796 | |
| 4797 | Root credentials are needed to use these functions. |
| 4798 | |
| 4799 | N\bNA\bAM\bME\bE |
| 4800 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 4801 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 4802 | ports and memory access functions |
| 4803 | |
| 4804 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4805 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 4806 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 4807 | |
| 4808 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4809 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4810 | |
| 4811 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4812 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4813 | |
| 4814 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4815 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4816 | |
| 4817 | _\bi_\bn_\bt |
| 4818 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 4819 | |
| 4820 | _\bv_\bo_\bi_\bd _\b* |
| 4821 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4822 | |
| 4823 | _\bv_\bo_\bi_\bd |
| 4824 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4825 | |
| 4826 | _\bv_\bo_\bi_\bd |
| 4827 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4828 | |
| 4829 | _\bv_\bo_\bi_\bd |
| 4830 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4831 | |
| 4832 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4833 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4834 | |
| 4835 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4836 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4837 | |
| 4838 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4839 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4840 | |
| 4841 | _\bv_\bo_\bi_\bd |
| 4842 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4843 | |
| 4844 | _\bv_\bo_\bi_\bd |
| 4845 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4846 | |
| 4847 | _\bv_\bo_\bi_\bd |
| 4848 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4849 | |
| 4850 | _\bv_\bo_\bi_\bd |
| 4851 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4852 | |
| 4853 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4854 | The functions in libalpha give userland programs access to the I/O ports |
| 4855 | on the OpenBSD/alpha platform. |
| 4856 | |
| 4857 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 4858 | |
| 4859 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 4860 | |
| 4861 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 4862 | disables access if _\bo_\bn is FALSE. |
| 4863 | |
| 4864 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 4865 | memory. |
| 4866 | |
| 4867 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 4868 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4869 | |
| 4870 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 4871 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4872 | |
| 4873 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 4874 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4875 | |
| 4876 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 4877 | |
| 4878 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4879 | These functions originally appeared in FreeBSD. |
| 4880 | |
| 4881 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4882 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 4883 | type access are not supported. |
| 4884 | |
| 4885 | Root credentials are needed to use these functions. |
| 4886 | |
| 4887 | N\bNA\bAM\bME\bE |
| 4888 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 4889 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 4890 | ports and memory access functions |
| 4891 | |
| 4892 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4893 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 4894 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 4895 | |
| 4896 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4897 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4898 | |
| 4899 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4900 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4901 | |
| 4902 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4903 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4904 | |
| 4905 | _\bi_\bn_\bt |
| 4906 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 4907 | |
| 4908 | _\bv_\bo_\bi_\bd _\b* |
| 4909 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4910 | |
| 4911 | _\bv_\bo_\bi_\bd |
| 4912 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4913 | |
| 4914 | _\bv_\bo_\bi_\bd |
| 4915 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4916 | |
| 4917 | _\bv_\bo_\bi_\bd |
| 4918 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4919 | |
| 4920 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4921 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4922 | |
| 4923 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4924 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4925 | |
| 4926 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4927 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 4928 | |
| 4929 | _\bv_\bo_\bi_\bd |
| 4930 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4931 | |
| 4932 | _\bv_\bo_\bi_\bd |
| 4933 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 4934 | |
| 4935 | _\bv_\bo_\bi_\bd |
| 4936 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 4937 | |
| 4938 | _\bv_\bo_\bi_\bd |
| 4939 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 4940 | |
| 4941 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 4942 | The functions in libalpha give userland programs access to the I/O ports |
| 4943 | on the OpenBSD/alpha platform. |
| 4944 | |
| 4945 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 4946 | |
| 4947 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 4948 | |
| 4949 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 4950 | disables access if _\bo_\bn is FALSE. |
| 4951 | |
| 4952 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 4953 | memory. |
| 4954 | |
| 4955 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 4956 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4957 | |
| 4958 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 4959 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4960 | |
| 4961 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 4962 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 4963 | |
| 4964 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 4965 | |
| 4966 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 4967 | These functions originally appeared in FreeBSD. |
| 4968 | |
| 4969 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 4970 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 4971 | type access are not supported. |
| 4972 | |
| 4973 | Root credentials are needed to use these functions. |
| 4974 | |
| 4975 | N\bNA\bAM\bME\bE |
| 4976 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 4977 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 4978 | ports and memory access functions |
| 4979 | |
| 4980 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 4981 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 4982 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 4983 | |
| 4984 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 4985 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4986 | |
| 4987 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 4988 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4989 | |
| 4990 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 4991 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 4992 | |
| 4993 | _\bi_\bn_\bt |
| 4994 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 4995 | |
| 4996 | _\bv_\bo_\bi_\bd _\b* |
| 4997 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 4998 | |
| 4999 | _\bv_\bo_\bi_\bd |
| 5000 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5001 | |
| 5002 | _\bv_\bo_\bi_\bd |
| 5003 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5004 | |
| 5005 | _\bv_\bo_\bi_\bd |
| 5006 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5007 | |
| 5008 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5009 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5010 | |
| 5011 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5012 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5013 | |
| 5014 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5015 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5016 | |
| 5017 | _\bv_\bo_\bi_\bd |
| 5018 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5019 | |
| 5020 | _\bv_\bo_\bi_\bd |
| 5021 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5022 | |
| 5023 | _\bv_\bo_\bi_\bd |
| 5024 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5025 | |
| 5026 | _\bv_\bo_\bi_\bd |
| 5027 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5028 | |
| 5029 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5030 | The functions in libalpha give userland programs access to the I/O ports |
| 5031 | on the OpenBSD/alpha platform. |
| 5032 | |
| 5033 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5034 | |
| 5035 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5036 | |
| 5037 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5038 | disables access if _\bo_\bn is FALSE. |
| 5039 | |
| 5040 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5041 | memory. |
| 5042 | |
| 5043 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5044 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5045 | |
| 5046 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5047 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5048 | |
| 5049 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5050 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5051 | |
| 5052 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5053 | |
| 5054 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5055 | These functions originally appeared in FreeBSD. |
| 5056 | |
| 5057 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5058 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5059 | type access are not supported. |
| 5060 | |
| 5061 | Root credentials are needed to use these functions. |
| 5062 | |
| 5063 | N\bNA\bAM\bME\bE |
| 5064 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5065 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5066 | ports and memory access functions |
| 5067 | |
| 5068 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5069 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5070 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5071 | |
| 5072 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5073 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5074 | |
| 5075 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5076 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5077 | |
| 5078 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5079 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5080 | |
| 5081 | _\bi_\bn_\bt |
| 5082 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5083 | |
| 5084 | _\bv_\bo_\bi_\bd _\b* |
| 5085 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5086 | |
| 5087 | _\bv_\bo_\bi_\bd |
| 5088 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5089 | |
| 5090 | _\bv_\bo_\bi_\bd |
| 5091 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5092 | |
| 5093 | _\bv_\bo_\bi_\bd |
| 5094 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5095 | |
| 5096 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5097 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5098 | |
| 5099 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5100 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5101 | |
| 5102 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5103 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5104 | |
| 5105 | _\bv_\bo_\bi_\bd |
| 5106 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5107 | |
| 5108 | _\bv_\bo_\bi_\bd |
| 5109 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5110 | |
| 5111 | _\bv_\bo_\bi_\bd |
| 5112 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5113 | |
| 5114 | _\bv_\bo_\bi_\bd |
| 5115 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5116 | |
| 5117 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5118 | The functions in libalpha give userland programs access to the I/O ports |
| 5119 | on the OpenBSD/alpha platform. |
| 5120 | |
| 5121 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5122 | |
| 5123 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5124 | |
| 5125 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5126 | disables access if _\bo_\bn is FALSE. |
| 5127 | |
| 5128 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5129 | memory. |
| 5130 | |
| 5131 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5132 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5133 | |
| 5134 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5135 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5136 | |
| 5137 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5138 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5139 | |
| 5140 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5141 | |
| 5142 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5143 | These functions originally appeared in FreeBSD. |
| 5144 | |
| 5145 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5146 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5147 | type access are not supported. |
| 5148 | |
| 5149 | Root credentials are needed to use these functions. |
| 5150 | |
| 5151 | N\bNA\bAM\bME\bE |
| 5152 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5153 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5154 | ports and memory access functions |
| 5155 | |
| 5156 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5157 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5158 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5159 | |
| 5160 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5161 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5162 | |
| 5163 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5164 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5165 | |
| 5166 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5167 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5168 | |
| 5169 | _\bi_\bn_\bt |
| 5170 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5171 | |
| 5172 | _\bv_\bo_\bi_\bd _\b* |
| 5173 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5174 | |
| 5175 | _\bv_\bo_\bi_\bd |
| 5176 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5177 | |
| 5178 | _\bv_\bo_\bi_\bd |
| 5179 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5180 | |
| 5181 | _\bv_\bo_\bi_\bd |
| 5182 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5183 | |
| 5184 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5185 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5186 | |
| 5187 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5188 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5189 | |
| 5190 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5191 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5192 | |
| 5193 | _\bv_\bo_\bi_\bd |
| 5194 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5195 | |
| 5196 | _\bv_\bo_\bi_\bd |
| 5197 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5198 | |
| 5199 | _\bv_\bo_\bi_\bd |
| 5200 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5201 | |
| 5202 | _\bv_\bo_\bi_\bd |
| 5203 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5204 | |
| 5205 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5206 | The functions in libalpha give userland programs access to the I/O ports |
| 5207 | on the OpenBSD/alpha platform. |
| 5208 | |
| 5209 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5210 | |
| 5211 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5212 | |
| 5213 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5214 | disables access if _\bo_\bn is FALSE. |
| 5215 | |
| 5216 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5217 | memory. |
| 5218 | |
| 5219 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5220 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5221 | |
| 5222 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5223 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5224 | |
| 5225 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5226 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5227 | |
| 5228 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5229 | |
| 5230 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5231 | These functions originally appeared in FreeBSD. |
| 5232 | |
| 5233 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5234 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5235 | type access are not supported. |
| 5236 | |
| 5237 | Root credentials are needed to use these functions. |
| 5238 | |
| 5239 | N\bNA\bAM\bME\bE |
| 5240 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5241 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5242 | ports and memory access functions |
| 5243 | |
| 5244 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5245 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5246 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5247 | |
| 5248 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5249 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5250 | |
| 5251 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5252 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5253 | |
| 5254 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5255 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5256 | |
| 5257 | _\bi_\bn_\bt |
| 5258 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5259 | |
| 5260 | _\bv_\bo_\bi_\bd _\b* |
| 5261 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5262 | |
| 5263 | _\bv_\bo_\bi_\bd |
| 5264 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5265 | |
| 5266 | _\bv_\bo_\bi_\bd |
| 5267 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5268 | |
| 5269 | _\bv_\bo_\bi_\bd |
| 5270 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5271 | |
| 5272 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5273 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5274 | |
| 5275 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5276 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5277 | |
| 5278 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5279 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5280 | |
| 5281 | _\bv_\bo_\bi_\bd |
| 5282 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5283 | |
| 5284 | _\bv_\bo_\bi_\bd |
| 5285 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5286 | |
| 5287 | _\bv_\bo_\bi_\bd |
| 5288 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5289 | |
| 5290 | _\bv_\bo_\bi_\bd |
| 5291 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5292 | |
| 5293 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5294 | The functions in libalpha give userland programs access to the I/O ports |
| 5295 | on the OpenBSD/alpha platform. |
| 5296 | |
| 5297 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5298 | |
| 5299 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5300 | |
| 5301 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5302 | disables access if _\bo_\bn is FALSE. |
| 5303 | |
| 5304 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5305 | memory. |
| 5306 | |
| 5307 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5308 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5309 | |
| 5310 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5311 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5312 | |
| 5313 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5314 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5315 | |
| 5316 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5317 | |
| 5318 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5319 | These functions originally appeared in FreeBSD. |
| 5320 | |
| 5321 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5322 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5323 | type access are not supported. |
| 5324 | |
| 5325 | Root credentials are needed to use these functions. |
| 5326 | |
| 5327 | N\bNA\bAM\bME\bE |
| 5328 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5329 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5330 | ports and memory access functions |
| 5331 | |
| 5332 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5333 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5334 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5335 | |
| 5336 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5337 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5338 | |
| 5339 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5340 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5341 | |
| 5342 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5343 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5344 | |
| 5345 | _\bi_\bn_\bt |
| 5346 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5347 | |
| 5348 | _\bv_\bo_\bi_\bd _\b* |
| 5349 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5350 | |
| 5351 | _\bv_\bo_\bi_\bd |
| 5352 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5353 | |
| 5354 | _\bv_\bo_\bi_\bd |
| 5355 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5356 | |
| 5357 | _\bv_\bo_\bi_\bd |
| 5358 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5359 | |
| 5360 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5361 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5362 | |
| 5363 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5364 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5365 | |
| 5366 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5367 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5368 | |
| 5369 | _\bv_\bo_\bi_\bd |
| 5370 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5371 | |
| 5372 | _\bv_\bo_\bi_\bd |
| 5373 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5374 | |
| 5375 | _\bv_\bo_\bi_\bd |
| 5376 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5377 | |
| 5378 | _\bv_\bo_\bi_\bd |
| 5379 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5380 | |
| 5381 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5382 | The functions in libalpha give userland programs access to the I/O ports |
| 5383 | on the OpenBSD/alpha platform. |
| 5384 | |
| 5385 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5386 | |
| 5387 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5388 | |
| 5389 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5390 | disables access if _\bo_\bn is FALSE. |
| 5391 | |
| 5392 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5393 | memory. |
| 5394 | |
| 5395 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5396 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5397 | |
| 5398 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5399 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5400 | |
| 5401 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5402 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5403 | |
| 5404 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5405 | |
| 5406 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5407 | These functions originally appeared in FreeBSD. |
| 5408 | |
| 5409 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5410 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5411 | type access are not supported. |
| 5412 | |
| 5413 | Root credentials are needed to use these functions. |
| 5414 | |
| 5415 | N\bNA\bAM\bME\bE |
| 5416 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5417 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5418 | ports and memory access functions |
| 5419 | |
| 5420 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5421 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5422 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5423 | |
| 5424 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5425 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5426 | |
| 5427 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5428 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5429 | |
| 5430 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5431 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5432 | |
| 5433 | _\bi_\bn_\bt |
| 5434 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5435 | |
| 5436 | _\bv_\bo_\bi_\bd _\b* |
| 5437 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5438 | |
| 5439 | _\bv_\bo_\bi_\bd |
| 5440 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5441 | |
| 5442 | _\bv_\bo_\bi_\bd |
| 5443 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5444 | |
| 5445 | _\bv_\bo_\bi_\bd |
| 5446 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5447 | |
| 5448 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5449 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5450 | |
| 5451 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5452 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5453 | |
| 5454 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5455 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5456 | |
| 5457 | _\bv_\bo_\bi_\bd |
| 5458 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5459 | |
| 5460 | _\bv_\bo_\bi_\bd |
| 5461 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5462 | |
| 5463 | _\bv_\bo_\bi_\bd |
| 5464 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5465 | |
| 5466 | _\bv_\bo_\bi_\bd |
| 5467 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5468 | |
| 5469 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5470 | The functions in libalpha give userland programs access to the I/O ports |
| 5471 | on the OpenBSD/alpha platform. |
| 5472 | |
| 5473 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5474 | |
| 5475 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5476 | |
| 5477 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5478 | disables access if _\bo_\bn is FALSE. |
| 5479 | |
| 5480 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5481 | memory. |
| 5482 | |
| 5483 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5484 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5485 | |
| 5486 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5487 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5488 | |
| 5489 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5490 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5491 | |
| 5492 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5493 | |
| 5494 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5495 | These functions originally appeared in FreeBSD. |
| 5496 | |
| 5497 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5498 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5499 | type access are not supported. |
| 5500 | |
| 5501 | Root credentials are needed to use these functions. |
| 5502 | |
| 5503 | N\bNA\bAM\bME\bE |
| 5504 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5505 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5506 | ports and memory access functions |
| 5507 | |
| 5508 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5509 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5510 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5511 | |
| 5512 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5513 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5514 | |
| 5515 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5516 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5517 | |
| 5518 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5519 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5520 | |
| 5521 | _\bi_\bn_\bt |
| 5522 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5523 | |
| 5524 | _\bv_\bo_\bi_\bd _\b* |
| 5525 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5526 | |
| 5527 | _\bv_\bo_\bi_\bd |
| 5528 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5529 | |
| 5530 | _\bv_\bo_\bi_\bd |
| 5531 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5532 | |
| 5533 | _\bv_\bo_\bi_\bd |
| 5534 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5535 | |
| 5536 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5537 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5538 | |
| 5539 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5540 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5541 | |
| 5542 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5543 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5544 | |
| 5545 | _\bv_\bo_\bi_\bd |
| 5546 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5547 | |
| 5548 | _\bv_\bo_\bi_\bd |
| 5549 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5550 | |
| 5551 | _\bv_\bo_\bi_\bd |
| 5552 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5553 | |
| 5554 | _\bv_\bo_\bi_\bd |
| 5555 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5556 | |
| 5557 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5558 | The functions in libalpha give userland programs access to the I/O ports |
| 5559 | on the OpenBSD/alpha platform. |
| 5560 | |
| 5561 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5562 | |
| 5563 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5564 | |
| 5565 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5566 | disables access if _\bo_\bn is FALSE. |
| 5567 | |
| 5568 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5569 | memory. |
| 5570 | |
| 5571 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5572 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5573 | |
| 5574 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5575 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5576 | |
| 5577 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5578 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5579 | |
| 5580 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5581 | |
| 5582 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5583 | These functions originally appeared in FreeBSD. |
| 5584 | |
| 5585 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5586 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5587 | type access are not supported. |
| 5588 | |
| 5589 | Root credentials are needed to use these functions. |
| 5590 | |
| 5591 | N\bNA\bAM\bME\bE |
| 5592 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5593 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5594 | ports and memory access functions |
| 5595 | |
| 5596 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5597 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5598 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5599 | |
| 5600 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5601 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5602 | |
| 5603 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5604 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5605 | |
| 5606 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5607 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5608 | |
| 5609 | _\bi_\bn_\bt |
| 5610 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5611 | |
| 5612 | _\bv_\bo_\bi_\bd _\b* |
| 5613 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5614 | |
| 5615 | _\bv_\bo_\bi_\bd |
| 5616 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5617 | |
| 5618 | _\bv_\bo_\bi_\bd |
| 5619 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5620 | |
| 5621 | _\bv_\bo_\bi_\bd |
| 5622 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5623 | |
| 5624 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5625 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5626 | |
| 5627 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5628 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5629 | |
| 5630 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5631 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5632 | |
| 5633 | _\bv_\bo_\bi_\bd |
| 5634 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5635 | |
| 5636 | _\bv_\bo_\bi_\bd |
| 5637 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5638 | |
| 5639 | _\bv_\bo_\bi_\bd |
| 5640 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5641 | |
| 5642 | _\bv_\bo_\bi_\bd |
| 5643 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5644 | |
| 5645 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5646 | The functions in libalpha give userland programs access to the I/O ports |
| 5647 | on the OpenBSD/alpha platform. |
| 5648 | |
| 5649 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5650 | |
| 5651 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5652 | |
| 5653 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5654 | disables access if _\bo_\bn is FALSE. |
| 5655 | |
| 5656 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5657 | memory. |
| 5658 | |
| 5659 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5660 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5661 | |
| 5662 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5663 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5664 | |
| 5665 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5666 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5667 | |
| 5668 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5669 | |
| 5670 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5671 | These functions originally appeared in FreeBSD. |
| 5672 | |
| 5673 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5674 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5675 | type access are not supported. |
| 5676 | |
| 5677 | Root credentials are needed to use these functions. |
| 5678 | |
| 5679 | N\bNA\bAM\bME\bE |
| 5680 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5681 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5682 | ports and memory access functions |
| 5683 | |
| 5684 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5685 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5686 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5687 | |
| 5688 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5689 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5690 | |
| 5691 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5692 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5693 | |
| 5694 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5695 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5696 | |
| 5697 | _\bi_\bn_\bt |
| 5698 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5699 | |
| 5700 | _\bv_\bo_\bi_\bd _\b* |
| 5701 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5702 | |
| 5703 | _\bv_\bo_\bi_\bd |
| 5704 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5705 | |
| 5706 | _\bv_\bo_\bi_\bd |
| 5707 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5708 | |
| 5709 | _\bv_\bo_\bi_\bd |
| 5710 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5711 | |
| 5712 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5713 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5714 | |
| 5715 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5716 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5717 | |
| 5718 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5719 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5720 | |
| 5721 | _\bv_\bo_\bi_\bd |
| 5722 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5723 | |
| 5724 | _\bv_\bo_\bi_\bd |
| 5725 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5726 | |
| 5727 | _\bv_\bo_\bi_\bd |
| 5728 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5729 | |
| 5730 | _\bv_\bo_\bi_\bd |
| 5731 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5732 | |
| 5733 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5734 | The functions in libalpha give userland programs access to the I/O ports |
| 5735 | on the OpenBSD/alpha platform. |
| 5736 | |
| 5737 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5738 | |
| 5739 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5740 | |
| 5741 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5742 | disables access if _\bo_\bn is FALSE. |
| 5743 | |
| 5744 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5745 | memory. |
| 5746 | |
| 5747 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5748 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5749 | |
| 5750 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5751 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5752 | |
| 5753 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5754 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5755 | |
| 5756 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5757 | |
| 5758 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5759 | These functions originally appeared in FreeBSD. |
| 5760 | |
| 5761 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5762 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5763 | type access are not supported. |
| 5764 | |
| 5765 | Root credentials are needed to use these functions. |
| 5766 | |
| 5767 | N\bNA\bAM\bME\bE |
| 5768 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
| 5769 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
| 5770 | ports and memory access functions |
| 5771 | |
| 5772 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5773 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
| 5774 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
| 5775 | |
| 5776 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5777 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5778 | |
| 5779 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5780 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5781 | |
| 5782 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5783 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
| 5784 | |
| 5785 | _\bi_\bn_\bt |
| 5786 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
| 5787 | |
| 5788 | _\bv_\bo_\bi_\bd _\b* |
| 5789 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5790 | |
| 5791 | _\bv_\bo_\bi_\bd |
| 5792 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5793 | |
| 5794 | _\bv_\bo_\bi_\bd |
| 5795 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5796 | |
| 5797 | _\bv_\bo_\bi_\bd |
| 5798 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5799 | |
| 5800 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
| 5801 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5802 | |
| 5803 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
| 5804 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5805 | |
| 5806 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
| 5807 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 5808 | |
| 5809 | _\bv_\bo_\bi_\bd |
| 5810 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
| 5811 | |
| 5812 | _\bv_\bo_\bi_\bd |
| 5813 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
| 5814 | |
| 5815 | _\bv_\bo_\bi_\bd |
| 5816 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
| 5817 | |
| 5818 | _\bv_\bo_\bi_\bd |
| 5819 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
| 5820 | |
| 5821 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5822 | The functions in libalpha give userland programs access to the I/O ports |
| 5823 | on the OpenBSD/alpha platform. |
| 5824 | |
| 5825 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
| 5826 | |
| 5827 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
| 5828 | |
| 5829 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
| 5830 | disables access if _\bo_\bn is FALSE. |
| 5831 | |
| 5832 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
| 5833 | memory. |
| 5834 | |
| 5835 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
| 5836 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5837 | |
| 5838 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
| 5839 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5840 | |
| 5841 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
| 5842 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
| 5843 | |
| 5844 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
| 5845 | |
| 5846 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 5847 | These functions originally appeared in FreeBSD. |
| 5848 | |
| 5849 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 5850 | Only BWX bus access method is supported for now. Machines requiring swiz |
| 5851 | type access are not supported. |
| 5852 | |
| 5853 | Root credentials are needed to use these functions. |
| 5854 | |
| 5855 | N\bNA\bAM\bME\bE |
| 5856 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be, a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be - manage amd64 per-thread %fs base |
| 5857 | address |
| 5858 | |
| 5859 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5860 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 5861 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 5862 | |
| 5863 | _\bi_\bn_\bt |
| 5864 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
| 5865 | |
| 5866 | _\bi_\bn_\bt |
| 5867 | a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
| 5868 | |
| 5869 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5870 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() copies the current base address of the %fs segment |
| 5871 | into the memory referenced by _\bb_\ba_\bs_\be. |
| 5872 | |
| 5873 | a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() sets the base address of the %fs segment to the |
| 5874 | address _\bb_\ba_\bs_\be. |
| 5875 | |
| 5876 | The segment base address is local to each thread. The initial thread of |
| 5877 | a new process inherits its segment base address from the parent thread. |
| 5878 | __tfork(2) sets the initial segment base address for threads that it |
| 5879 | creates. |
| 5880 | |
| 5881 | N\bNo\bot\bte\be:\b: Code using the a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() functions |
| 5882 | must be compiled using -\b-l\bla\bam\bmd\bd6\b64\b4. |
| 5883 | |
| 5884 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 5885 | Upon successful completion, a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() |
| 5886 | return 0. Otherwise, a value of -1 is returned and the global variable |
| 5887 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 5888 | |
| 5889 | E\bER\bRR\bRO\bOR\bRS\bS |
| 5890 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() will fail if: |
| 5891 | |
| 5892 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
| 5893 | |
| 5894 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 5895 | __tfork(2), fork(2) |
| 5896 | |
| 5897 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 5898 | The ELF Thread-Local Storage ABI reserves %fs for its own use and |
| 5899 | requires that the dynamic linker and thread library set it to reference |
| 5900 | data-structures internal to and shared between them. Programs should use |
| 5901 | the __thread storage class keyword instead of using these calls. To be |
| 5902 | maximally portable, programs that require per-thread data should use the |
| 5903 | p\bpt\bth\bhr\bre\bea\bad\bd_\b_k\bke\bey\by_\b_c\bcr\bre\bea\bat\bte\be() interface. |
| 5904 | |
| 5905 | N\bNA\bAM\bME\bE |
| 5906 | a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl - change the amd64 I/O privilege level |
| 5907 | |
| 5908 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5909 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 5910 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 5911 | |
| 5912 | _\bi_\bn_\bt |
| 5913 | a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl(_\bi_\bn_\bt _\bi_\bo_\bp_\bl); |
| 5914 | |
| 5915 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5916 | a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl() sets the amd64 I/O privilege level to the value specified by |
| 5917 | _\bi_\bo_\bp_\bl. |
| 5918 | |
| 5919 | This call may only be made by the superuser. Additionally, it is only |
| 5920 | permitted when the securelevel(7) is less than or equal to 0 or the |
| 5921 | _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be sysctl has been set to a non-zero value. |
| 5922 | |
| 5923 | N\bNo\bot\bte\be:\b: Code using the a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl() function must be compiled using |
| 5924 | -\b-l\bla\bam\bmd\bd6\b64\b4. |
| 5925 | |
| 5926 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 5927 | Upon successful completion, a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl() returns 0. Otherwise, a value |
| 5928 | of -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 5929 | error. |
| 5930 | |
| 5931 | E\bER\bRR\bRO\bOR\bRS\bS |
| 5932 | a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl() will fail if: |
| 5933 | |
| 5934 | [EPERM] The caller was not the superuser, or the securelevel is greater |
| 5935 | than zero and _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be has not been set to a non- |
| 5936 | zero value. |
| 5937 | |
| 5938 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 5939 | securelevel(7) |
| 5940 | |
| 5941 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 5942 | Intel, _\bA_\bM_\bD_\b6_\b4 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 5943 | |
| 5944 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 5945 | You can really hose your machine if you enable user-level I/O and write |
| 5946 | to hardware ports without care. |
| 5947 | |
| 5948 | N\bNA\bAM\bME\bE |
| 5949 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be, a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be - manage amd64 per-thread %fs base |
| 5950 | address |
| 5951 | |
| 5952 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 5953 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 5954 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 5955 | |
| 5956 | _\bi_\bn_\bt |
| 5957 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
| 5958 | |
| 5959 | _\bi_\bn_\bt |
| 5960 | a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
| 5961 | |
| 5962 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 5963 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() copies the current base address of the %fs segment |
| 5964 | into the memory referenced by _\bb_\ba_\bs_\be. |
| 5965 | |
| 5966 | a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() sets the base address of the %fs segment to the |
| 5967 | address _\bb_\ba_\bs_\be. |
| 5968 | |
| 5969 | The segment base address is local to each thread. The initial thread of |
| 5970 | a new process inherits its segment base address from the parent thread. |
| 5971 | __tfork(2) sets the initial segment base address for threads that it |
| 5972 | creates. |
| 5973 | |
| 5974 | N\bNo\bot\bte\be:\b: Code using the a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() functions |
| 5975 | must be compiled using -\b-l\bla\bam\bmd\bd6\b64\b4. |
| 5976 | |
| 5977 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 5978 | Upon successful completion, a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() |
| 5979 | return 0. Otherwise, a value of -1 is returned and the global variable |
| 5980 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 5981 | |
| 5982 | E\bER\bRR\bRO\bOR\bRS\bS |
| 5983 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() will fail if: |
| 5984 | |
| 5985 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
| 5986 | |
| 5987 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 5988 | __tfork(2), fork(2) |
| 5989 | |
| 5990 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 5991 | The ELF Thread-Local Storage ABI reserves %fs for its own use and |
| 5992 | requires that the dynamic linker and thread library set it to reference |
| 5993 | data-structures internal to and shared between them. Programs should use |
| 5994 | the __thread storage class keyword instead of using these calls. To be |
| 5995 | maximally portable, programs that require per-thread data should use the |
| 5996 | p\bpt\bth\bhr\bre\bea\bad\bd_\b_k\bke\bey\by_\b_c\bcr\bre\bea\bat\bte\be() interface. |
| 5997 | |
| 5998 | N\bNA\bAM\bME\bE |
| 5999 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf - drains the CPU write buffer |
| 6000 | |
| 6001 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6002 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 6003 | |
| 6004 | _\bi_\bn_\bt |
| 6005 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf(); |
| 6006 | |
| 6007 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6008 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf() will make sure that all the entries in the processor |
| 6009 | write buffer are written out to memory. |
| 6010 | |
| 6011 | Not all processors support this operation (currently only the SA110 |
| 6012 | does). Those processes that do not, treat this function as a null-op. |
| 6013 | |
| 6014 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6015 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf() will never fail so will always return 0. |
| 6016 | |
| 6017 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 6018 | StrongARM Data Sheet |
| 6019 | |
| 6020 | N\bNA\bAM\bME\bE |
| 6021 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be - clean the CPU data cache and flush the CPU instruction |
| 6022 | cache |
| 6023 | |
| 6024 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6025 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 6026 | |
| 6027 | _\bi_\bn_\bt |
| 6028 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be(_\bu_\b__\bi_\bn_\bt _\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bl_\be_\bn); |
| 6029 | |
| 6030 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6031 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will make sure that all the entries in the processor |
| 6032 | instruction cache are synchronized with main memory and that any data in |
| 6033 | a write back cache has been cleaned. Some ARM processors (e.g. SA110) |
| 6034 | have separate instruction and data caches, thus any dynamically generated |
| 6035 | or modified code needs to be written back from any data caches to main |
| 6036 | memory and the instruction cache needs to be synchronized with main |
| 6037 | memory. |
| 6038 | |
| 6039 | On such processors, a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will clean the data cache and |
| 6040 | invalidate the processor instruction cache to force reloading from main |
| 6041 | memory. On processors that have a shared instruction and data cache and |
| 6042 | have a write through cache (e.g. ARM6), no action needs to be taken. |
| 6043 | |
| 6044 | The routine takes a start address _\ba_\bd_\bd_\br and a length _\bl_\be_\bn to describe the |
| 6045 | area of memory that needs to be cleaned and synchronized. |
| 6046 | |
| 6047 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6048 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will never fail so will always return 0. |
| 6049 | |
| 6050 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 6051 | StrongARM Data Sheet |
| 6052 | |
| 6053 | N\bNA\bAM\bME\bE |
| 6054 | b\bbi\bin\bnd\bd - bind a name to a socket |
| 6055 | |
| 6056 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6057 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 6058 | |
| 6059 | _\bi_\bn_\bt |
| 6060 | b\bbi\bin\bnd\bd(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
| 6061 | |
| 6062 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6063 | b\bbi\bin\bnd\bd() assigns a name to an unnamed socket. When a socket is created |
| 6064 | with socket(2) it exists in a name space (address family) but has no name |
| 6065 | assigned. b\bbi\bin\bnd\bd() requests that _\bn_\ba_\bm_\be be assigned to the socket. _\bn_\ba_\bm_\be_\bl_\be_\bn |
| 6066 | indicates the amount of space pointed to by _\bn_\ba_\bm_\be, in bytes. |
| 6067 | |
| 6068 | N\bNO\bOT\bTE\bES\bS |
| 6069 | Binding a name in the UNIX-domain creates a socket in the file system |
| 6070 | that must be deleted by the caller when it is no longer needed (using |
| 6071 | unlink(2)). |
| 6072 | |
| 6073 | The rules used in name binding vary between communication domains. |
| 6074 | Consult the manual entries in section 4 for detailed information. |
| 6075 | |
| 6076 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6077 | Upon successful completion, the value 0 is returned; otherwise the |
| 6078 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6079 | error. |
| 6080 | |
| 6081 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6082 | The b\bbi\bin\bnd\bd() function will fail if: |
| 6083 | |
| 6084 | [EBADF] _\bs is not a valid descriptor. |
| 6085 | |
| 6086 | [ENOTSOCK] _\bs is not a socket. |
| 6087 | |
| 6088 | [EADDRNOTAVAIL] The specified address is not available from the local |
| 6089 | machine. |
| 6090 | |
| 6091 | [EADDRINUSE] The specified address is already in use. |
| 6092 | |
| 6093 | [EINVAL] The socket is already bound to an address, or _\bn_\ba_\bm_\be_\bl_\be_\bn |
| 6094 | is not a valid length for the supplied address. |
| 6095 | |
| 6096 | [EAFNOSUPPORT] The family of the socket and that requested in |
| 6097 | _\bn_\ba_\bm_\be_\b-_\b>_\bs_\ba_\b__\bf_\ba_\bm_\bi_\bl_\by are not equivalent. |
| 6098 | |
| 6099 | [ENOBUFS] Insufficient buffer space is available. |
| 6100 | |
| 6101 | [EACCES] The requested address is protected, and the current |
| 6102 | user has inadequate permission to access it. |
| 6103 | |
| 6104 | [EFAULT] The _\bn_\ba_\bm_\be parameter is not in a valid part of the user |
| 6105 | address space. |
| 6106 | |
| 6107 | The following errors are specific to binding names in the UNIX-domain. |
| 6108 | |
| 6109 | [ENOTDIR] A component of the path prefix is not a directory. |
| 6110 | |
| 6111 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 6112 | characters, or an entire pathname (including the |
| 6113 | terminating NUL) exceeded PATH_MAX bytes. |
| 6114 | |
| 6115 | [ENOENT] A prefix component of the path name does not exist. |
| 6116 | |
| 6117 | [ELOOP] Too many symbolic links were encountered in |
| 6118 | translating the pathname. |
| 6119 | |
| 6120 | [EIO] An I/O error occurred while making the directory entry |
| 6121 | or allocating the inode. |
| 6122 | |
| 6123 | [EROFS] The name would reside on a read-only file system. |
| 6124 | |
| 6125 | [EISDIR] An empty pathname was specified. |
| 6126 | |
| 6127 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 6128 | connect(2), getsockname(2), listen(2), socket(2) |
| 6129 | |
| 6130 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 6131 | The b\bbi\bin\bnd\bd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 6132 | |
| 6133 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 6134 | The b\bbi\bin\bnd\bd() system call first appeared in 4.1cBSD. |
| 6135 | |
| 6136 | N\bNA\bAM\bME\bE |
| 6137 | b\bbr\brk\bk, s\bsb\bbr\brk\bk - change data segment size |
| 6138 | |
| 6139 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6140 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 6141 | |
| 6142 | _\bi_\bn_\bt |
| 6143 | b\bbr\brk\bk(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br); |
| 6144 | |
| 6145 | _\bv_\bo_\bi_\bd _\b* |
| 6146 | s\bsb\bbr\brk\bk(_\bi_\bn_\bt _\bi_\bn_\bc_\br); |
| 6147 | |
| 6148 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6149 | T\bTh\bhe\be b\bbr\brk\bk(\b()\b) a\ban\bnd\bd s\bsb\bbr\brk\bk(\b()\b) f\bfu\bun\bnc\bct\bti\bio\bon\bns\bs a\bar\bre\be h\bhi\bis\bst\bto\bor\bri\bic\bca\bal\bl c\bcu\bur\bri\bio\bos\bsi\bit\bti\bie\bes\bs l\ble\bef\bft\bt o\bov\bve\ber\br f\bfr\bro\bom\bm |
| 6150 | e\bea\bar\brl\bli\bie\ber\br d\bda\bay\bys\bs b\bbe\bef\bfo\bor\bre\be t\bth\bhe\be a\bad\bdv\bve\ben\bnt\bt o\bof\bf v\bvi\bir\brt\btu\bua\bal\bl m\bme\bem\bmo\bor\bry\by m\bma\ban\bna\bag\bge\bem\bme\ben\bnt\bt.\b. The b\bbr\brk\bk() |
| 6151 | function sets the break or lowest address of a process's data segment |
| 6152 | (uninitialized data) to _\ba_\bd_\bd_\br (immediately above bss). Data addressing is |
| 6153 | restricted between _\ba_\bd_\bd_\br and the lowest stack pointer to the stack |
| 6154 | segment. Memory is allocated by b\bbr\brk\bk() in page size pieces; if _\ba_\bd_\bd_\br is |
| 6155 | not evenly divisible by the system page size, it is increased to the next |
| 6156 | page boundary. |
| 6157 | |
| 6158 | The current value of the program break is reliably returned by |
| 6159 | ``sbrk(0)'' (see also end(3)). The getrlimit(2) system call may be used |
| 6160 | to determine the maximum permissible size of the _\bd_\ba_\bt_\ba segment; it will |
| 6161 | not be possible to set the break beyond the _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx value returned from |
| 6162 | a call to getrlimit(2), e.g., ``etext + rlp->rlim_max'' (see end(3) for |
| 6163 | the definition of _\be_\bt_\be_\bx_\bt). |
| 6164 | |
| 6165 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6166 | The b\bbr\brk\bk() function returns the value 0 if successful; otherwise the |
| 6167 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6168 | error. |
| 6169 | |
| 6170 | The s\bsb\bbr\brk\bk() function returns a pointer to the base of the new storage if |
| 6171 | successful; otherwise -1 with _\be_\br_\br_\bn_\bo set to indicate why the allocation |
| 6172 | failed. |
| 6173 | |
| 6174 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6175 | s\bsb\bbr\brk\bk() will fail and no additional memory will be allocated if one of the |
| 6176 | following are true: |
| 6177 | |
| 6178 | [ENOMEM] The limit, as set by setrlimit(2), was exceeded. |
| 6179 | |
| 6180 | [ENOMEM] The maximum possible size of a data segment (compiled |
| 6181 | into the system) was exceeded. |
| 6182 | |
| 6183 | [ENOMEM] Insufficient space existed in the swap area to support |
| 6184 | the expansion. |
| 6185 | |
| 6186 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 6187 | execve(2), getrlimit(2), mmap(2), end(3), malloc(3) |
| 6188 | |
| 6189 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 6190 | A b\bbr\brk\bk() function call appeared in Version 7 AT&T UNIX. |
| 6191 | |
| 6192 | B\bBU\bUG\bGS\bS |
| 6193 | Setting the break may fail due to a temporary lack of swap space. It is |
| 6194 | not possible to distinguish this from a failure caused by exceeding the |
| 6195 | maximum size of the data segment without consulting getrlimit(2). |
| 6196 | |
| 6197 | N\bNA\bAM\bME\bE |
| 6198 | c\bch\bhd\bdi\bir\br, f\bfc\bch\bhd\bdi\bir\br - change current working directory |
| 6199 | |
| 6200 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6201 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 6202 | |
| 6203 | _\bi_\bn_\bt |
| 6204 | c\bch\bhd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
| 6205 | |
| 6206 | _\bi_\bn_\bt |
| 6207 | f\bfc\bch\bhd\bdi\bir\br(_\bi_\bn_\bt _\bf_\bd); |
| 6208 | |
| 6209 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6210 | The _\bp_\ba_\bt_\bh argument points to the pathname of a directory. The c\bch\bhd\bdi\bir\br() |
| 6211 | function causes the named directory to become the current working |
| 6212 | directory, that is, the starting point for path searches of pathnames not |
| 6213 | beginning with a slash (`/'). |
| 6214 | |
| 6215 | The f\bfc\bch\bhd\bdi\bir\br() function causes the directory referenced by _\bf_\bd to become the |
| 6216 | current working directory, the starting point for path searches of |
| 6217 | pathnames not beginning with a slash (`/'). |
| 6218 | |
| 6219 | In order for a directory to become the current directory, a process must |
| 6220 | have execute (search) access to the directory. |
| 6221 | |
| 6222 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6223 | Upon successful completion, the value 0 is returned; otherwise the |
| 6224 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6225 | error. |
| 6226 | |
| 6227 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6228 | c\bch\bhd\bdi\bir\br() will fail and the current working directory will be unchanged if |
| 6229 | one or more of the following are true: |
| 6230 | |
| 6231 | [ENOTDIR] A component of the path prefix is not a directory. |
| 6232 | |
| 6233 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 6234 | characters, or an entire pathname (including the |
| 6235 | terminating NUL) exceeded PATH_MAX bytes. |
| 6236 | |
| 6237 | [ENOENT] The named directory does not exist. |
| 6238 | |
| 6239 | [ELOOP] Too many symbolic links were encountered in |
| 6240 | translating the pathname. |
| 6241 | |
| 6242 | [EACCES] Search permission is denied for any component of the |
| 6243 | pathname. |
| 6244 | |
| 6245 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 6246 | space. |
| 6247 | |
| 6248 | [EIO] An I/O error occurred while reading from the file |
| 6249 | system. |
| 6250 | |
| 6251 | f\bfc\bch\bhd\bdi\bir\br() will fail and the current working directory will be unchanged if |
| 6252 | one or more of the following are true: |
| 6253 | |
| 6254 | [EACCES] Search permission is denied for the directory |
| 6255 | referenced by the file descriptor. |
| 6256 | |
| 6257 | [ENOTDIR] The file descriptor does not reference a directory. |
| 6258 | |
| 6259 | [EBADF] The argument _\bf_\bd is not a valid file descriptor. |
| 6260 | |
| 6261 | [EIO] An I/O error occurred while reading from the file |
| 6262 | system. |
| 6263 | |
| 6264 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 6265 | chroot(2) |
| 6266 | |
| 6267 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 6268 | The c\bch\bhd\bdi\bir\br() and f\bfc\bch\bhd\bdi\bir\br() functions are expected to conform to IEEE Std |
| 6269 | 1003.1-2008 (``POSIX.1''). |
| 6270 | |
| 6271 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 6272 | The c\bch\bhd\bdi\bir\br() system call first appeared in Version 1 AT&T UNIX, and |
| 6273 | f\bfc\bch\bhd\bdi\bir\br() in 4.3BSD-Reno. |
| 6274 | |
| 6275 | N\bNA\bAM\bME\bE |
| 6276 | c\bch\bhf\bfl\bla\bag\bgs\bs, c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt, f\bfc\bch\bhf\bfl\bla\bag\bgs\bs - set file flags |
| 6277 | |
| 6278 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6279 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 6280 | |
| 6281 | _\bi_\bn_\bt |
| 6282 | c\bch\bhf\bfl\bla\bag\bgs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 6283 | |
| 6284 | _\bi_\bn_\bt |
| 6285 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs(_\bi_\bn_\bt _\bf_\bd, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 6286 | |
| 6287 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 6288 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 6289 | |
| 6290 | _\bi_\bn_\bt |
| 6291 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\ba_\bt_\bf_\bl_\ba_\bg_\bs); |
| 6292 | |
| 6293 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6294 | The file whose name is given by _\bp_\ba_\bt_\bh or referenced by the descriptor _\bf_\bd |
| 6295 | has its flags changed to _\bf_\bl_\ba_\bg_\bs. |
| 6296 | |
| 6297 | The flags are the bitwise OR of zero or more of the following values: |
| 6298 | |
| 6299 | UF_NODUMP Do not dump the file. |
| 6300 | UF_IMMUTABLE The file may not be changed. |
| 6301 | UF_APPEND The file may only be appended to. |
| 6302 | SF_ARCHIVED The file may be archived. |
| 6303 | SF_IMMUTABLE The file may not be changed. |
| 6304 | SF_APPEND The file may only be appended to. |
| 6305 | |
| 6306 | The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the |
| 6307 | owner of a file or the superuser. |
| 6308 | |
| 6309 | The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or |
| 6310 | unset by the superuser. They may be set at any time, but normally may |
| 6311 | only be unset when the system is in single-user mode. (See init(8) for |
| 6312 | details.) |
| 6313 | |
| 6314 | The c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except in the case |
| 6315 | where _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be |
| 6316 | changed is determined relative to the directory associated with the file |
| 6317 | descriptor _\bf_\bd instead of the current working directory. |
| 6318 | |
| 6319 | If c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 6320 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 6321 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to c\bch\bhf\bfl\bla\bag\bgs\bs(). |
| 6322 | |
| 6323 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 6324 | values: |
| 6325 | |
| 6326 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the flags |
| 6327 | of the symbolic link are changed. |
| 6328 | |
| 6329 | The f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except that the file |
| 6330 | whose flags are changed is specified by the file descriptor _\bf_\bd. |
| 6331 | |
| 6332 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6333 | Upon successful completion, the value 0 is returned; otherwise the |
| 6334 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6335 | error. |
| 6336 | |
| 6337 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6338 | c\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
| 6339 | |
| 6340 | [ENOTDIR] A component of the path prefix is not a directory. |
| 6341 | |
| 6342 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 6343 | characters, or an entire pathname (including the |
| 6344 | terminating NUL) exceeded PATH_MAX bytes. |
| 6345 | |
| 6346 | [ENOENT] The named file does not exist. |
| 6347 | |
| 6348 | [EACCES] Search permission is denied for a component of the |
| 6349 | path prefix. |
| 6350 | |
| 6351 | [ELOOP] Too many symbolic links were encountered in |
| 6352 | translating the pathname. |
| 6353 | |
| 6354 | [EPERM] The effective user ID does not match the owner of the |
| 6355 | file and the effective user ID is not the superuser, |
| 6356 | or the effective user ID is not the superuser and at |
| 6357 | least one of the super-user-only flags for the named |
| 6358 | file would be changed. |
| 6359 | |
| 6360 | [EOPNOTSUPP] The named file resides on a file system that does not |
| 6361 | support file flags. |
| 6362 | |
| 6363 | [EROFS] The named file resides on a read-only file system. |
| 6364 | |
| 6365 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 6366 | space. |
| 6367 | |
| 6368 | [EIO] An I/O error occurred while reading from or writing to |
| 6369 | the file system. |
| 6370 | |
| 6371 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
| 6372 | |
| 6373 | [EINVAL] The descriptor references a block or character device |
| 6374 | and the effective user ID is not the superuser. |
| 6375 | |
| 6376 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
| 6377 | |
| 6378 | [EBADF] The descriptor is not valid. |
| 6379 | |
| 6380 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
| 6381 | |
| 6382 | [EINVAL] The descriptor references a block or character device |
| 6383 | and the effective user ID is not the superuser. |
| 6384 | |
| 6385 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
| 6386 | |
| 6387 | [EPERM] The effective user ID does not match the owner of the |
| 6388 | file and the effective user ID is not the superuser, |
| 6389 | or the effective user ID is not the superuser and at |
| 6390 | least one of the super-user-only flags for the named |
| 6391 | file would be changed. |
| 6392 | |
| 6393 | [EOPNOTSUPP] The named file resides on a file system that does not |
| 6394 | support file flags. |
| 6395 | |
| 6396 | [EROFS] The file resides on a read-only file system. |
| 6397 | |
| 6398 | [EIO] An I/O error occurred while reading from or writing to |
| 6399 | the file system. |
| 6400 | |
| 6401 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 6402 | chflags(1), init(8) |
| 6403 | |
| 6404 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 6405 | The c\bch\bhf\bfl\bla\bag\bgs\bs() and f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() functions first appeared in 4.4BSD. The |
| 6406 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function first appeared in FreeBSD 10.0. It was added to |
| 6407 | OpenBSD in OpenBSD 5.7. |
| 6408 | |
| 6409 | N\bNA\bAM\bME\bE |
| 6410 | c\bch\bhf\bfl\bla\bag\bgs\bs, c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt, f\bfc\bch\bhf\bfl\bla\bag\bgs\bs - set file flags |
| 6411 | |
| 6412 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6413 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 6414 | |
| 6415 | _\bi_\bn_\bt |
| 6416 | c\bch\bhf\bfl\bla\bag\bgs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 6417 | |
| 6418 | _\bi_\bn_\bt |
| 6419 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs(_\bi_\bn_\bt _\bf_\bd, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 6420 | |
| 6421 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 6422 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 6423 | |
| 6424 | _\bi_\bn_\bt |
| 6425 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\ba_\bt_\bf_\bl_\ba_\bg_\bs); |
| 6426 | |
| 6427 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6428 | The file whose name is given by _\bp_\ba_\bt_\bh or referenced by the descriptor _\bf_\bd |
| 6429 | has its flags changed to _\bf_\bl_\ba_\bg_\bs. |
| 6430 | |
| 6431 | The flags are the bitwise OR of zero or more of the following values: |
| 6432 | |
| 6433 | UF_NODUMP Do not dump the file. |
| 6434 | UF_IMMUTABLE The file may not be changed. |
| 6435 | UF_APPEND The file may only be appended to. |
| 6436 | SF_ARCHIVED The file may be archived. |
| 6437 | SF_IMMUTABLE The file may not be changed. |
| 6438 | SF_APPEND The file may only be appended to. |
| 6439 | |
| 6440 | The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the |
| 6441 | owner of a file or the superuser. |
| 6442 | |
| 6443 | The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or |
| 6444 | unset by the superuser. They may be set at any time, but normally may |
| 6445 | only be unset when the system is in single-user mode. (See init(8) for |
| 6446 | details.) |
| 6447 | |
| 6448 | The c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except in the case |
| 6449 | where _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be |
| 6450 | changed is determined relative to the directory associated with the file |
| 6451 | descriptor _\bf_\bd instead of the current working directory. |
| 6452 | |
| 6453 | If c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 6454 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 6455 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to c\bch\bhf\bfl\bla\bag\bgs\bs(). |
| 6456 | |
| 6457 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 6458 | values: |
| 6459 | |
| 6460 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the flags |
| 6461 | of the symbolic link are changed. |
| 6462 | |
| 6463 | The f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except that the file |
| 6464 | whose flags are changed is specified by the file descriptor _\bf_\bd. |
| 6465 | |
| 6466 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6467 | Upon successful completion, the value 0 is returned; otherwise the |
| 6468 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6469 | error. |
| 6470 | |
| 6471 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6472 | c\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
| 6473 | |
| 6474 | [ENOTDIR] A component of the path prefix is not a directory. |
| 6475 | |
| 6476 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 6477 | characters, or an entire pathname (including the |
| 6478 | terminating NUL) exceeded PATH_MAX bytes. |
| 6479 | |
| 6480 | [ENOENT] The named file does not exist. |
| 6481 | |
| 6482 | [EACCES] Search permission is denied for a component of the |
| 6483 | path prefix. |
| 6484 | |
| 6485 | [ELOOP] Too many symbolic links were encountered in |
| 6486 | translating the pathname. |
| 6487 | |
| 6488 | [EPERM] The effective user ID does not match the owner of the |
| 6489 | file and the effective user ID is not the superuser, |
| 6490 | or the effective user ID is not the superuser and at |
| 6491 | least one of the super-user-only flags for the named |
| 6492 | file would be changed. |
| 6493 | |
| 6494 | [EOPNOTSUPP] The named file resides on a file system that does not |
| 6495 | support file flags. |
| 6496 | |
| 6497 | [EROFS] The named file resides on a read-only file system. |
| 6498 | |
| 6499 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 6500 | space. |
| 6501 | |
| 6502 | [EIO] An I/O error occurred while reading from or writing to |
| 6503 | the file system. |
| 6504 | |
| 6505 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
| 6506 | |
| 6507 | [EINVAL] The descriptor references a block or character device |
| 6508 | and the effective user ID is not the superuser. |
| 6509 | |
| 6510 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
| 6511 | |
| 6512 | [EBADF] The descriptor is not valid. |
| 6513 | |
| 6514 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
| 6515 | |
| 6516 | [EINVAL] The descriptor references a block or character device |
| 6517 | and the effective user ID is not the superuser. |
| 6518 | |
| 6519 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
| 6520 | |
| 6521 | [EPERM] The effective user ID does not match the owner of the |
| 6522 | file and the effective user ID is not the superuser, |
| 6523 | or the effective user ID is not the superuser and at |
| 6524 | least one of the super-user-only flags for the named |
| 6525 | file would be changed. |
| 6526 | |
| 6527 | [EOPNOTSUPP] The named file resides on a file system that does not |
| 6528 | support file flags. |
| 6529 | |
| 6530 | [EROFS] The file resides on a read-only file system. |
| 6531 | |
| 6532 | [EIO] An I/O error occurred while reading from or writing to |
| 6533 | the file system. |
| 6534 | |
| 6535 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 6536 | chflags(1), init(8) |
| 6537 | |
| 6538 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 6539 | The c\bch\bhf\bfl\bla\bag\bgs\bs() and f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() functions first appeared in 4.4BSD. The |
| 6540 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function first appeared in FreeBSD 10.0. It was added to |
| 6541 | OpenBSD in OpenBSD 5.7. |
| 6542 | |
| 6543 | N\bNA\bAM\bME\bE |
| 6544 | c\bch\bhm\bmo\bod\bd, f\bfc\bch\bhm\bmo\bod\bda\bat\bt, f\bfc\bch\bhm\bmo\bod\bd - change mode of file |
| 6545 | |
| 6546 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6547 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 6548 | |
| 6549 | _\bi_\bn_\bt |
| 6550 | c\bch\bhm\bmo\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 6551 | |
| 6552 | _\bi_\bn_\bt |
| 6553 | f\bfc\bch\bhm\bmo\bod\bd(_\bi_\bn_\bt _\bf_\bd, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 6554 | |
| 6555 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 6556 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 6557 | |
| 6558 | _\bi_\bn_\bt |
| 6559 | f\bfc\bch\bhm\bmo\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 6560 | |
| 6561 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6562 | The c\bch\bhm\bmo\bod\bd() function sets the file permission bits of the file specified |
| 6563 | by the pathname _\bp_\ba_\bt_\bh to _\bm_\bo_\bd_\be. c\bch\bhm\bmo\bod\bd() verifies that the process owner |
| 6564 | (user) either owns the specified file or is the superuser. |
| 6565 | |
| 6566 | The _\bm_\bo_\bd_\be argument is the bitwise OR of zero or more of the permission bit |
| 6567 | masks from the following list: |
| 6568 | |
| 6569 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 6570 | #define S_IRUSR 0000400 /* R for owner */ |
| 6571 | #define S_IWUSR 0000200 /* W for owner */ |
| 6572 | #define S_IXUSR 0000100 /* X for owner */ |
| 6573 | |
| 6574 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 6575 | #define S_IRGRP 0000040 /* R for group */ |
| 6576 | #define S_IWGRP 0000020 /* W for group */ |
| 6577 | #define S_IXGRP 0000010 /* X for group */ |
| 6578 | |
| 6579 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 6580 | #define S_IROTH 0000004 /* R for other */ |
| 6581 | #define S_IWOTH 0000002 /* W for other */ |
| 6582 | #define S_IXOTH 0000001 /* X for other */ |
| 6583 | |
| 6584 | #define S_ISUID 0004000 /* set user id on execution */ |
| 6585 | #define S_ISGID 0002000 /* set group id on execution */ |
| 6586 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 6587 | |
| 6588 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a file, it is ignored. |
| 6589 | |
| 6590 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a directory, an unprivileged |
| 6591 | user may not delete or rename files of other users in that directory. |
| 6592 | The sticky bit may be set by any user on a directory which the user owns |
| 6593 | or has appropriate permissions. For more details of the properties of |
| 6594 | the sticky bit, see sticky(8). |
| 6595 | |
| 6596 | Writing or changing the owner of a file turns off the set-user-ID and |
| 6597 | set-group-ID bits unless the user is the superuser. This makes the |
| 6598 | system somewhat more secure by protecting set-user-ID (set-group-ID) |
| 6599 | files from remaining set-user-ID (set-group-ID) if they are modified, at |
| 6600 | the expense of a degree of compatibility. |
| 6601 | |
| 6602 | The f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function is equivalent to c\bch\bhm\bmo\bod\bd() except in the case where |
| 6603 | _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be changed is |
| 6604 | determined relative to the directory associated with the file descriptor |
| 6605 | _\bf_\bd instead of the current working directory. |
| 6606 | |
| 6607 | If f\bfc\bch\bhm\bmo\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 6608 | in the _\bf_\bd parameter, the current working directory is used. If _\bf_\bl_\ba_\bg is |
| 6609 | also zero, the behavior is identical to a call to c\bch\bhm\bmo\bod\bd(). |
| 6610 | |
| 6611 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 6612 | values: |
| 6613 | |
| 6614 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the mode |
| 6615 | of the symbolic link is changed. |
| 6616 | |
| 6617 | The f\bfc\bch\bhm\bmo\bod\bd() function is equivalent to c\bch\bhm\bmo\bod\bd() except that the file whose |
| 6618 | permissions are changed is specified by the file descriptor _\bf_\bd. |
| 6619 | |
| 6620 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6621 | Upon successful completion, the value 0 is returned; otherwise the |
| 6622 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6623 | error. |
| 6624 | |
| 6625 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6626 | The c\bch\bhm\bmo\bod\bd() and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions will fail and the file mode will be |
| 6627 | unchanged if: |
| 6628 | |
| 6629 | [ENOTDIR] A component of the path prefix is not a directory. |
| 6630 | |
| 6631 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 6632 | characters, or an entire pathname (including the |
| 6633 | terminating NUL) exceeded PATH_MAX bytes. |
| 6634 | |
| 6635 | [ENOENT] The named file does not exist. |
| 6636 | |
| 6637 | [EACCES] Search permission is denied for a component of the |
| 6638 | path prefix. |
| 6639 | |
| 6640 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
| 6641 | described above. |
| 6642 | |
| 6643 | [ELOOP] Too many symbolic links were encountered in |
| 6644 | translating the pathname. |
| 6645 | |
| 6646 | [EPERM] The effective user ID does not match the owner of the |
| 6647 | file and the effective user ID is not the superuser. |
| 6648 | |
| 6649 | [EROFS] The named file resides on a read-only file system. |
| 6650 | |
| 6651 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 6652 | space. |
| 6653 | |
| 6654 | [EIO] An I/O error occurred while reading from or writing to |
| 6655 | the file system. |
| 6656 | |
| 6657 | Additionally, the f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function will fail if: |
| 6658 | |
| 6659 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 6660 | AT_SYMLINK_NOFOLLOW. |
| 6661 | |
| 6662 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 6663 | argument is neither AT_FDCWD nor a valid file |
| 6664 | descriptor. |
| 6665 | |
| 6666 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 6667 | argument is a valid file descriptor but it does not |
| 6668 | reference a directory. |
| 6669 | |
| 6670 | [EOPNOTSUPP] The _\bf_\bl_\ba_\bg argument specifies AT_SYMLINK_NOFOLLOW on a |
| 6671 | symbolic link and the file system does not support |
| 6672 | that operation. |
| 6673 | |
| 6674 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 6675 | permission is denied for the directory which the _\bf_\bd |
| 6676 | file descriptor references. |
| 6677 | |
| 6678 | f\bfc\bch\bhm\bmo\bod\bd() will fail and the file mode will be unchanged if: |
| 6679 | |
| 6680 | [EBADF] The descriptor is not valid. |
| 6681 | |
| 6682 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
| 6683 | |
| 6684 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
| 6685 | described above. |
| 6686 | |
| 6687 | [EPERM] The effective user ID does not match the owner of the |
| 6688 | file and the effective user ID is not the superuser. |
| 6689 | |
| 6690 | [EROFS] The file resides on a read-only file system. |
| 6691 | |
| 6692 | [EIO] An I/O error occurred while reading from or writing to |
| 6693 | the file system. |
| 6694 | |
| 6695 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 6696 | chmod(1), chown(2), open(2), stat(2), sticky(8) |
| 6697 | |
| 6698 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 6699 | The c\bch\bhm\bmo\bod\bd(), f\bfc\bch\bhm\bmo\bod\bd(), and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions are expected to conform |
| 6700 | to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 6701 | |
| 6702 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 6703 | The c\bch\bhm\bmo\bod\bd() system call first appeared in Version 1 AT&T UNIX; f\bfc\bch\bhm\bmo\bod\bd() |
| 6704 | in 4.1cBSD; and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
| 6705 | |
| 6706 | N\bNA\bAM\bME\bE |
| 6707 | c\bch\bho\bow\bwn\bn, l\blc\bch\bho\bow\bwn\bn, f\bfc\bch\bho\bow\bwn\bna\bat\bt, f\bfc\bch\bho\bow\bwn\bn - change owner and group of a file or |
| 6708 | link |
| 6709 | |
| 6710 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6711 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 6712 | |
| 6713 | _\bi_\bn_\bt |
| 6714 | c\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 6715 | |
| 6716 | _\bi_\bn_\bt |
| 6717 | l\blc\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 6718 | |
| 6719 | _\bi_\bn_\bt |
| 6720 | f\bfc\bch\bho\bow\bwn\bn(_\bi_\bn_\bt _\bf_\bd, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 6721 | |
| 6722 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 6723 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 6724 | |
| 6725 | _\bi_\bn_\bt |
| 6726 | f\bfc\bch\bho\bow\bwn\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 6727 | |
| 6728 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6729 | The owner ID and group ID of the file (or link) named by _\bp_\ba_\bt_\bh or |
| 6730 | referenced by _\bf_\bd is changed as specified by the arguments _\bo_\bw_\bn_\be_\br and |
| 6731 | _\bg_\br_\bo_\bu_\bp. The owner of a file may change the _\bg_\br_\bo_\bu_\bp to a group of which he |
| 6732 | or she is a member, but the change _\bo_\bw_\bn_\be_\br capability is restricted to the |
| 6733 | superuser. |
| 6734 | |
| 6735 | By default, c\bch\bho\bow\bwn\bn() clears the set-user-ID and set-group-ID bits on the |
| 6736 | file to prevent accidental or mischievous creation of set-user-ID and |
| 6737 | set-group-ID programs. This behaviour can be overridden by setting the |
| 6738 | sysctl(8) variable _\bf_\bs_\b._\bp_\bo_\bs_\bi_\bx_\b._\bs_\be_\bt_\bu_\bi_\bd to zero. |
| 6739 | |
| 6740 | l\blc\bch\bho\bow\bwn\bn() operates similarly to how c\bch\bho\bow\bwn\bn() operated on older systems, and |
| 6741 | does not follow symbolic links. It allows the owner and group of a |
| 6742 | symbolic link to be set. |
| 6743 | |
| 6744 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() function is equivalent to either the c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn() |
| 6745 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 6746 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose ownership is changed is |
| 6747 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 6748 | instead of the current working directory. |
| 6749 | |
| 6750 | If f\bfc\bch\bho\bow\bwn\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 6751 | in the _\bf_\bd parameter, the current working directory is used and the |
| 6752 | behavior is identical to a call to c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn(), depending on |
| 6753 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 6754 | |
| 6755 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 6756 | values: |
| 6757 | |
| 6758 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
| 6759 | ownership of the symbolic link is changed. |
| 6760 | |
| 6761 | f\bfc\bch\bho\bow\bwn\bn() is particularly useful when used in conjunction with the file |
| 6762 | locking primitives (see flock(2)). |
| 6763 | |
| 6764 | One of the owner or group IDs may be left unchanged by specifying it as |
| 6765 | -1. |
| 6766 | |
| 6767 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6768 | Upon successful completion, the value 0 is returned; otherwise the |
| 6769 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6770 | error. |
| 6771 | |
| 6772 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6773 | c\bch\bho\bow\bwn\bn(), l\blc\bch\bho\bow\bwn\bn(), and f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail and the file or link will be |
| 6774 | unchanged if: |
| 6775 | |
| 6776 | [ENOTDIR] A component of the path prefix is not a directory. |
| 6777 | |
| 6778 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 6779 | characters, or an entire pathname (including the |
| 6780 | terminating NUL) exceeded PATH_MAX bytes. |
| 6781 | |
| 6782 | [ENOENT] The named file does not exist. |
| 6783 | |
| 6784 | [EACCES] Search permission is denied for a component of the |
| 6785 | path prefix. |
| 6786 | |
| 6787 | [ELOOP] Too many symbolic links were encountered in |
| 6788 | translating the pathname. |
| 6789 | |
| 6790 | [EPERM] The effective user ID is not the superuser. |
| 6791 | |
| 6792 | [EROFS] The named file resides on a read-only file system. |
| 6793 | |
| 6794 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 6795 | space. |
| 6796 | |
| 6797 | [EIO] An I/O error occurred while reading from or writing to |
| 6798 | the file system. |
| 6799 | |
| 6800 | Additionally, f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail if: |
| 6801 | |
| 6802 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 6803 | AT_SYMLINK_NOFOLLOW. |
| 6804 | |
| 6805 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 6806 | argument is neither AT_FDCWD nor a valid file |
| 6807 | descriptor. |
| 6808 | |
| 6809 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 6810 | argument is a valid file descriptor but it does not |
| 6811 | reference a directory. |
| 6812 | |
| 6813 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 6814 | permission is denied for the directory which the _\bf_\bd |
| 6815 | file descriptor references. |
| 6816 | |
| 6817 | f\bfc\bch\bho\bow\bwn\bn() will fail if: |
| 6818 | |
| 6819 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
| 6820 | |
| 6821 | [EINVAL] _\bf_\bd refers to a socket, not a file. |
| 6822 | |
| 6823 | [EPERM] The effective user ID is not the superuser. |
| 6824 | |
| 6825 | [EROFS] The named file resides on a read-only file system. |
| 6826 | |
| 6827 | [EIO] An I/O error occurred while reading from or writing to |
| 6828 | the file system. |
| 6829 | |
| 6830 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 6831 | chgrp(1), chmod(2), flock(2), chown(8) |
| 6832 | |
| 6833 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 6834 | The c\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), and l\blc\bch\bho\bow\bwn\bn() functions are expected to |
| 6835 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 6836 | |
| 6837 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 6838 | The c\bch\bho\bow\bwn\bn() system call first appeared in Version 1 AT&T UNIX. Since |
| 6839 | Version 6 AT&T UNIX it supports changing the group as well, and in |
| 6840 | Version 7 AT&T UNIX _\bg_\br_\bo_\bu_\bp was made a separate argument. |
| 6841 | |
| 6842 | The f\bfc\bch\bho\bow\bwn\bn() system call first appeared in 4.1cBSD. |
| 6843 | |
| 6844 | The c\bch\bho\bow\bwn\bn() and f\bfc\bch\bho\bow\bwn\bn() system calls were changed to follow symbolic |
| 6845 | links in 4.4BSD; therefore, and for compatibility with AT&T System V |
| 6846 | Release 4 UNIX, the l\blc\bch\bho\bow\bwn\bn() system call was added to OpenBSD 2.1. |
| 6847 | |
| 6848 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() system call has been available since OpenBSD 5.0. |
| 6849 | |
| 6850 | N\bNA\bAM\bME\bE |
| 6851 | c\bch\bhr\bro\boo\bot\bt - change root directory |
| 6852 | |
| 6853 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6854 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 6855 | |
| 6856 | _\bi_\bn_\bt |
| 6857 | c\bch\bhr\bro\boo\bot\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br_\bn_\ba_\bm_\be); |
| 6858 | |
| 6859 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6860 | _\bd_\bi_\br_\bn_\ba_\bm_\be is the address of the pathname of a directory, terminated by an |
| 6861 | ASCII NUL. c\bch\bhr\bro\boo\bot\bt() causes _\bd_\bi_\br_\bn_\ba_\bm_\be to become the root directory, that |
| 6862 | is, the starting point for path searches of pathnames beginning with `/'. |
| 6863 | |
| 6864 | In order for a directory to become the root directory a process must have |
| 6865 | execute (search) access for that directory. |
| 6866 | |
| 6867 | If the program is not currently running with an altered root directory, |
| 6868 | it should be noted that c\bch\bhr\bro\boo\bot\bt() has no effect on the process's current |
| 6869 | directory. |
| 6870 | |
| 6871 | If the program is already running with an altered root directory, the |
| 6872 | process's current directory is changed to the same new root directory. |
| 6873 | This prevents the current directory from being further up the directory |
| 6874 | tree than the altered root directory. |
| 6875 | |
| 6876 | This call is restricted to the superuser. |
| 6877 | |
| 6878 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6879 | Upon successful completion, the value 0 is returned; otherwise the |
| 6880 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6881 | error. |
| 6882 | |
| 6883 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS |
| 6884 | The following example changes the root directory to _\bn_\be_\bw_\br_\bo_\bo_\bt, sets the |
| 6885 | current directory to the new root, and drops some setuid privileges. |
| 6886 | There may be other privileges which need to be dropped as well. |
| 6887 | |
| 6888 | #include <err.h> |
| 6889 | #include <unistd.h> |
| 6890 | |
| 6891 | if (chroot(newroot) != 0 || chdir("/") != 0) |
| 6892 | err(1, "%s", newroot); |
| 6893 | setresuid(getuid(), getuid(), getuid()); |
| 6894 | |
| 6895 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6896 | c\bch\bhr\bro\boo\bot\bt() will fail and the root directory will be unchanged if: |
| 6897 | |
| 6898 | [ENOTDIR] A component of the path name is not a directory. |
| 6899 | |
| 6900 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 6901 | characters, or an entire pathname (including the |
| 6902 | terminating NUL) exceeded PATH_MAX bytes. |
| 6903 | |
| 6904 | [ENOENT] The named directory does not exist. |
| 6905 | |
| 6906 | [EACCES] Search permission is denied for any component of the |
| 6907 | path name. |
| 6908 | |
| 6909 | [ELOOP] Too many symbolic links were encountered in |
| 6910 | translating the pathname. |
| 6911 | |
| 6912 | [EFAULT] _\bd_\bi_\br_\bn_\ba_\bm_\be points outside the process's allocated address |
| 6913 | space. |
| 6914 | |
| 6915 | [EIO] An I/O error occurred while reading from or writing to |
| 6916 | the file system. |
| 6917 | |
| 6918 | [EPERM] The caller is not the superuser. |
| 6919 | |
| 6920 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 6921 | chdir(2) |
| 6922 | |
| 6923 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 6924 | The c\bch\bhr\bro\boo\bot\bt() system call first appeared in Version 7 AT&T UNIX. |
| 6925 | |
| 6926 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 6927 | There are ways for a root process to escape from the chroot jail. |
| 6928 | Changes to the directory hierarchy made from outside the chroot jail may |
| 6929 | allow a restricted process to escape, even if it is unprivileged. |
| 6930 | Passing directory file descriptors via recvmsg(2) from outside the chroot |
| 6931 | jail may also allow a process to escape. |
| 6932 | |
| 6933 | N\bNA\bAM\bME\bE |
| 6934 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs - get/set/calibrate date and |
| 6935 | time |
| 6936 | |
| 6937 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 6938 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<t\bti\bim\bme\be.\b.h\bh>\b> |
| 6939 | |
| 6940 | _\bi_\bn_\bt |
| 6941 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 6942 | |
| 6943 | _\bi_\bn_\bt |
| 6944 | c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 6945 | |
| 6946 | _\bi_\bn_\bt |
| 6947 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 6948 | |
| 6949 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 6950 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be() and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions allow the calling |
| 6951 | process to retrieve or set the value used by a clock which is specified |
| 6952 | by _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd. |
| 6953 | |
| 6954 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd can be a value from clock_getcpuclockid(3) or |
| 6955 | pthread_getcpuclockid(3) or one of five predefined values: |
| 6956 | |
| 6957 | CLOCK_REALTIME time that increments as a wall clock should |
| 6958 | |
| 6959 | CLOCK_PROCESS_CPUTIME_ID |
| 6960 | time that increments when the CPU is running in user or |
| 6961 | kernel mode on behalf of the calling process |
| 6962 | |
| 6963 | CLOCK_THREAD_CPUTIME_ID |
| 6964 | time that increments when the CPU is running in user or |
| 6965 | kernel mode on behalf of the calling thread |
| 6966 | |
| 6967 | CLOCK_MONOTONIC time that increments as a wall clock should but whose |
| 6968 | absolute value is meaningless and cannot jump, providing |
| 6969 | accurate realtime interval measurement, even across |
| 6970 | suspend and resume |
| 6971 | |
| 6972 | CLOCK_UPTIME time whose absolute value is the time the system has |
| 6973 | been running and not suspended, providing accurate |
| 6974 | uptime measurement, both absolute and interval |
| 6975 | |
| 6976 | The structure pointed to by _\bt_\bp is defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
| 6977 | |
| 6978 | struct timespec { |
| 6979 | time_t tv_sec; /* seconds */ |
| 6980 | long tv_nsec; /* and nanoseconds */ |
| 6981 | }; |
| 6982 | |
| 6983 | Only the CLOCK_REALTIME clock can be set, and only the superuser may do |
| 6984 | so. If the system securelevel is greater than 1 (see init(8)), the time |
| 6985 | may only be advanced. This limitation is imposed to prevent a malicious |
| 6986 | superuser from setting arbitrary time stamps on files. The system time |
| 6987 | can still be adjusted backwards using the adjtime(2) system call even |
| 6988 | when the system is secure. |
| 6989 | |
| 6990 | The resolution (granularity) of a clock is returned by the c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() |
| 6991 | call. This value is placed in a (non-null) _\b*_\bt_\bp. |
| 6992 | |
| 6993 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 6994 | Upon successful completion, the value 0 is returned; otherwise the |
| 6995 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 6996 | error. |
| 6997 | |
| 6998 | E\bER\bRR\bRO\bOR\bRS\bS |
| 6999 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() will fail if: |
| 7000 | |
| 7001 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd is not a valid value. |
| 7002 | |
| 7003 | [EFAULT] The _\bt_\bp argument address referenced invalid memory. |
| 7004 | |
| 7005 | In addition, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() may return the following errors: |
| 7006 | |
| 7007 | [EPERM] A user other than the superuser attempted to set the |
| 7008 | time. |
| 7009 | |
| 7010 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd specifies a clock that isn't settable, _\bt_\bp |
| 7011 | specifies a nanosecond value less than zero or greater |
| 7012 | than 1000 million, or a value outside the range of the |
| 7013 | specified clock. |
| 7014 | |
| 7015 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7016 | date(1), adjtime(2), getitimer(2), gettimeofday(2), |
| 7017 | clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) |
| 7018 | |
| 7019 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 7020 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(), c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions |
| 7021 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 7022 | |
| 7023 | The CLOCK_UPTIME clock is an extension to that. |
| 7024 | |
| 7025 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 7026 | The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared |
| 7027 | in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and |
| 7028 | was added to OpenBSD in OpenBSD 5.5. |
| 7029 | |
| 7030 | N\bNA\bAM\bME\bE |
| 7031 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs - get/set/calibrate date and |
| 7032 | time |
| 7033 | |
| 7034 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7035 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<t\bti\bim\bme\be.\b.h\bh>\b> |
| 7036 | |
| 7037 | _\bi_\bn_\bt |
| 7038 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 7039 | |
| 7040 | _\bi_\bn_\bt |
| 7041 | c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 7042 | |
| 7043 | _\bi_\bn_\bt |
| 7044 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 7045 | |
| 7046 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7047 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be() and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions allow the calling |
| 7048 | process to retrieve or set the value used by a clock which is specified |
| 7049 | by _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd. |
| 7050 | |
| 7051 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd can be a value from clock_getcpuclockid(3) or |
| 7052 | pthread_getcpuclockid(3) or one of five predefined values: |
| 7053 | |
| 7054 | CLOCK_REALTIME time that increments as a wall clock should |
| 7055 | |
| 7056 | CLOCK_PROCESS_CPUTIME_ID |
| 7057 | time that increments when the CPU is running in user or |
| 7058 | kernel mode on behalf of the calling process |
| 7059 | |
| 7060 | CLOCK_THREAD_CPUTIME_ID |
| 7061 | time that increments when the CPU is running in user or |
| 7062 | kernel mode on behalf of the calling thread |
| 7063 | |
| 7064 | CLOCK_MONOTONIC time that increments as a wall clock should but whose |
| 7065 | absolute value is meaningless and cannot jump, providing |
| 7066 | accurate realtime interval measurement, even across |
| 7067 | suspend and resume |
| 7068 | |
| 7069 | CLOCK_UPTIME time whose absolute value is the time the system has |
| 7070 | been running and not suspended, providing accurate |
| 7071 | uptime measurement, both absolute and interval |
| 7072 | |
| 7073 | The structure pointed to by _\bt_\bp is defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
| 7074 | |
| 7075 | struct timespec { |
| 7076 | time_t tv_sec; /* seconds */ |
| 7077 | long tv_nsec; /* and nanoseconds */ |
| 7078 | }; |
| 7079 | |
| 7080 | Only the CLOCK_REALTIME clock can be set, and only the superuser may do |
| 7081 | so. If the system securelevel is greater than 1 (see init(8)), the time |
| 7082 | may only be advanced. This limitation is imposed to prevent a malicious |
| 7083 | superuser from setting arbitrary time stamps on files. The system time |
| 7084 | can still be adjusted backwards using the adjtime(2) system call even |
| 7085 | when the system is secure. |
| 7086 | |
| 7087 | The resolution (granularity) of a clock is returned by the c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() |
| 7088 | call. This value is placed in a (non-null) _\b*_\bt_\bp. |
| 7089 | |
| 7090 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 7091 | Upon successful completion, the value 0 is returned; otherwise the |
| 7092 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 7093 | error. |
| 7094 | |
| 7095 | E\bER\bRR\bRO\bOR\bRS\bS |
| 7096 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() will fail if: |
| 7097 | |
| 7098 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd is not a valid value. |
| 7099 | |
| 7100 | [EFAULT] The _\bt_\bp argument address referenced invalid memory. |
| 7101 | |
| 7102 | In addition, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() may return the following errors: |
| 7103 | |
| 7104 | [EPERM] A user other than the superuser attempted to set the |
| 7105 | time. |
| 7106 | |
| 7107 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd specifies a clock that isn't settable, _\bt_\bp |
| 7108 | specifies a nanosecond value less than zero or greater |
| 7109 | than 1000 million, or a value outside the range of the |
| 7110 | specified clock. |
| 7111 | |
| 7112 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7113 | date(1), adjtime(2), getitimer(2), gettimeofday(2), |
| 7114 | clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) |
| 7115 | |
| 7116 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 7117 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(), c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions |
| 7118 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 7119 | |
| 7120 | The CLOCK_UPTIME clock is an extension to that. |
| 7121 | |
| 7122 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 7123 | The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared |
| 7124 | in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and |
| 7125 | was added to OpenBSD in OpenBSD 5.5. |
| 7126 | |
| 7127 | N\bNA\bAM\bME\bE |
| 7128 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs - get/set/calibrate date and |
| 7129 | time |
| 7130 | |
| 7131 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7132 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<t\bti\bim\bme\be.\b.h\bh>\b> |
| 7133 | |
| 7134 | _\bi_\bn_\bt |
| 7135 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 7136 | |
| 7137 | _\bi_\bn_\bt |
| 7138 | c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 7139 | |
| 7140 | _\bi_\bn_\bt |
| 7141 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
| 7142 | |
| 7143 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7144 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be() and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions allow the calling |
| 7145 | process to retrieve or set the value used by a clock which is specified |
| 7146 | by _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd. |
| 7147 | |
| 7148 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd can be a value from clock_getcpuclockid(3) or |
| 7149 | pthread_getcpuclockid(3) or one of five predefined values: |
| 7150 | |
| 7151 | CLOCK_REALTIME time that increments as a wall clock should |
| 7152 | |
| 7153 | CLOCK_PROCESS_CPUTIME_ID |
| 7154 | time that increments when the CPU is running in user or |
| 7155 | kernel mode on behalf of the calling process |
| 7156 | |
| 7157 | CLOCK_THREAD_CPUTIME_ID |
| 7158 | time that increments when the CPU is running in user or |
| 7159 | kernel mode on behalf of the calling thread |
| 7160 | |
| 7161 | CLOCK_MONOTONIC time that increments as a wall clock should but whose |
| 7162 | absolute value is meaningless and cannot jump, providing |
| 7163 | accurate realtime interval measurement, even across |
| 7164 | suspend and resume |
| 7165 | |
| 7166 | CLOCK_UPTIME time whose absolute value is the time the system has |
| 7167 | been running and not suspended, providing accurate |
| 7168 | uptime measurement, both absolute and interval |
| 7169 | |
| 7170 | The structure pointed to by _\bt_\bp is defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
| 7171 | |
| 7172 | struct timespec { |
| 7173 | time_t tv_sec; /* seconds */ |
| 7174 | long tv_nsec; /* and nanoseconds */ |
| 7175 | }; |
| 7176 | |
| 7177 | Only the CLOCK_REALTIME clock can be set, and only the superuser may do |
| 7178 | so. If the system securelevel is greater than 1 (see init(8)), the time |
| 7179 | may only be advanced. This limitation is imposed to prevent a malicious |
| 7180 | superuser from setting arbitrary time stamps on files. The system time |
| 7181 | can still be adjusted backwards using the adjtime(2) system call even |
| 7182 | when the system is secure. |
| 7183 | |
| 7184 | The resolution (granularity) of a clock is returned by the c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() |
| 7185 | call. This value is placed in a (non-null) _\b*_\bt_\bp. |
| 7186 | |
| 7187 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 7188 | Upon successful completion, the value 0 is returned; otherwise the |
| 7189 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 7190 | error. |
| 7191 | |
| 7192 | E\bER\bRR\bRO\bOR\bRS\bS |
| 7193 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() will fail if: |
| 7194 | |
| 7195 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd is not a valid value. |
| 7196 | |
| 7197 | [EFAULT] The _\bt_\bp argument address referenced invalid memory. |
| 7198 | |
| 7199 | In addition, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() may return the following errors: |
| 7200 | |
| 7201 | [EPERM] A user other than the superuser attempted to set the |
| 7202 | time. |
| 7203 | |
| 7204 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd specifies a clock that isn't settable, _\bt_\bp |
| 7205 | specifies a nanosecond value less than zero or greater |
| 7206 | than 1000 million, or a value outside the range of the |
| 7207 | specified clock. |
| 7208 | |
| 7209 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7210 | date(1), adjtime(2), getitimer(2), gettimeofday(2), |
| 7211 | clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) |
| 7212 | |
| 7213 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 7214 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(), c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions |
| 7215 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 7216 | |
| 7217 | The CLOCK_UPTIME clock is an extension to that. |
| 7218 | |
| 7219 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 7220 | The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared |
| 7221 | in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and |
| 7222 | was added to OpenBSD in OpenBSD 5.5. |
| 7223 | |
| 7224 | N\bNA\bAM\bME\bE |
| 7225 | c\bcl\blo\bos\bse\be - delete a descriptor |
| 7226 | |
| 7227 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7228 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 7229 | |
| 7230 | _\bi_\bn_\bt |
| 7231 | c\bcl\blo\bos\bse\be(_\bi_\bn_\bt _\bd); |
| 7232 | |
| 7233 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7234 | The c\bcl\blo\bos\bse\be() call deletes a descriptor _\bd from the per-process object |
| 7235 | reference table. If this is the last reference to the underlying object, |
| 7236 | the object will be deactivated. For example, on the last close of a |
| 7237 | file, the current _\bs_\be_\be_\bk pointer associated with the file is lost; on the |
| 7238 | last close of a socket(2), associated naming information and queued data |
| 7239 | are discarded; and on the last close of a file holding an advisory lock, |
| 7240 | the lock is released (see flock(2)). However, the semantics of System V |
| 7241 | and IEEE Std 1003.1-1988 (``POSIX.1'') dictate that all fcntl(2) advisory |
| 7242 | record locks associated with a file for a given process are removed when |
| 7243 | _\ba_\bn_\by file descriptor for that file is closed by that process. |
| 7244 | |
| 7245 | When a process exits, all associated file descriptors are freed, but |
| 7246 | since there is a limit on active descriptors per process, the c\bcl\blo\bos\bse\be() |
| 7247 | function call is useful when a large quantity of file descriptors are |
| 7248 | being handled. |
| 7249 | |
| 7250 | When a process forks (see fork(2)), all descriptors for the new child |
| 7251 | process reference the same objects as they did in the parent before the |
| 7252 | fork. If a new process image is to then be run using execve(2), the |
| 7253 | process would normally inherit these descriptors. Most of the |
| 7254 | descriptors can be rearranged with dup2(2) or deleted with c\bcl\blo\bos\bse\be() before |
| 7255 | the execve(2) is attempted, but since some of these descriptors may still |
| 7256 | be needed should the execve(2) fail, it is necessary to arrange for them |
| 7257 | to be closed when the execve(2) succeeds. For this reason, the call |
| 7258 | f\bfc\bcn\bnt\btl\bl(_\bd, _\bF_\b__\bS_\bE_\bT_\bF_\bD, _\bF_\bD_\b__\bC_\bL_\bO_\bE_\bX_\bE_\bC) is provided, which arranges that a |
| 7259 | descriptor will be closed after a successful execve(2); the call f\bfc\bcn\bnt\btl\bl(_\bd, |
| 7260 | _\bF_\b__\bS_\bE_\bT_\bF_\bD, _\b0) restores the default, which is to not close the descriptor. |
| 7261 | |
| 7262 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 7263 | Upon successful completion, the value 0 is returned; otherwise the |
| 7264 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 7265 | error. |
| 7266 | |
| 7267 | E\bER\bRR\bRO\bOR\bRS\bS |
| 7268 | c\bcl\blo\bos\bse\be() will fail if: |
| 7269 | |
| 7270 | [EBADF] _\bd is not an active descriptor. |
| 7271 | |
| 7272 | [EINTR] An interrupt was received. |
| 7273 | |
| 7274 | [EIO] An I/O error occurred while writing to the file |
| 7275 | system. |
| 7276 | |
| 7277 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7278 | accept(2), closefrom(2), dup2(2), execve(2), fcntl(2), flock(2), open(2), |
| 7279 | pipe(2), socket(2), socketpair(2) |
| 7280 | |
| 7281 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 7282 | c\bcl\blo\bos\bse\be() conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 7283 | |
| 7284 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 7285 | The c\bcl\blo\bos\bse\be() system call first appeared in Version 1 AT&T UNIX. |
| 7286 | |
| 7287 | N\bNA\bAM\bME\bE |
| 7288 | c\bcl\blo\bos\bse\bef\bfr\bro\bom\bm - delete many descriptors |
| 7289 | |
| 7290 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7291 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 7292 | |
| 7293 | _\bi_\bn_\bt |
| 7294 | c\bcl\blo\bos\bse\bef\bfr\bro\bom\bm(_\bi_\bn_\bt _\bf_\bd); |
| 7295 | |
| 7296 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7297 | The c\bcl\blo\bos\bse\bef\bfr\bro\bom\bm() call deletes all descriptors numbered _\bf_\bd and higher from |
| 7298 | the per-process file descriptor table. It is effectively the same as |
| 7299 | calling close(2) on each descriptor. |
| 7300 | |
| 7301 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 7302 | Upon successful completion, the value 0 is returned; otherwise the |
| 7303 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 7304 | error. |
| 7305 | |
| 7306 | E\bER\bRR\bRO\bOR\bRS\bS |
| 7307 | c\bcl\blo\bos\bse\bef\bfr\bro\bom\bm() will fail if: |
| 7308 | |
| 7309 | [EBADF] _\bf_\bd is greater than all open file descriptors. |
| 7310 | |
| 7311 | [EINTR] An interrupt was received. |
| 7312 | |
| 7313 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7314 | close(2) |
| 7315 | |
| 7316 | N\bNA\bAM\bME\bE |
| 7317 | c\bco\bon\bnn\bne\bec\bct\bt - initiate a connection on a socket |
| 7318 | |
| 7319 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7320 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 7321 | |
| 7322 | _\bi_\bn_\bt |
| 7323 | c\bco\bon\bnn\bne\bec\bct\bt(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
| 7324 | |
| 7325 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7326 | The parameter _\bs is a socket. If it is of type SOCK_DGRAM, this call |
| 7327 | specifies the peer with which the socket is to be associated; this |
| 7328 | address is that to which datagrams are to be sent, and the only address |
| 7329 | from which datagrams are to be received. If the socket is of type |
| 7330 | SOCK_STREAM, this call attempts to make a connection to another socket. |
| 7331 | The other socket is specified by _\bn_\ba_\bm_\be, which is an address in the |
| 7332 | communications space of the socket. _\bn_\ba_\bm_\be_\bl_\be_\bn indicates the amount of |
| 7333 | space pointed to by _\bn_\ba_\bm_\be, in bytes. Each communications space interprets |
| 7334 | the _\bn_\ba_\bm_\be parameter in its own way. Generally, stream sockets may use |
| 7335 | c\bco\bon\bnn\bne\bec\bct\bt() only once; datagram sockets may use c\bco\bon\bnn\bne\bec\bct\bt() multiple times to |
| 7336 | change their association. Datagram sockets may dissolve the association |
| 7337 | by connecting to an invalid address, such as a null address. |
| 7338 | |
| 7339 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 7340 | If the connection or binding succeeds, 0 is returned. Otherwise a -1 is |
| 7341 | returned, and a more specific error code is stored in _\be_\br_\br_\bn_\bo. |
| 7342 | |
| 7343 | E\bER\bRR\bRO\bOR\bRS\bS |
| 7344 | The c\bco\bon\bnn\bne\bec\bct\bt() call fails if: |
| 7345 | |
| 7346 | [EBADF] _\bs is not a valid descriptor. |
| 7347 | |
| 7348 | [ENOTSOCK] _\bs is not a socket. |
| 7349 | |
| 7350 | [EADDRNOTAVAIL] The specified address is not available on this |
| 7351 | machine. |
| 7352 | |
| 7353 | [EAFNOSUPPORT] Addresses in the specified address family cannot be |
| 7354 | used with this socket. |
| 7355 | |
| 7356 | [EISCONN] The socket is already connected. |
| 7357 | |
| 7358 | [ETIMEDOUT] Connection establishment timed out without |
| 7359 | establishing a connection. |
| 7360 | |
| 7361 | [EINVAL] A TCP connection with a local broadcast, the all-ones |
| 7362 | or a multicast address as the peer was attempted. |
| 7363 | |
| 7364 | [ECONNREFUSED] The attempt to connect was forcefully rejected. |
| 7365 | |
| 7366 | [EHOSTUNREACH] The destination address specified an unreachable host. |
| 7367 | |
| 7368 | [EINTR] A connect was interrupted before it succeeded by the |
| 7369 | delivery of a signal. |
| 7370 | |
| 7371 | [ENETUNREACH] The network isn't reachable from this host. |
| 7372 | |
| 7373 | [EADDRINUSE] The address is already in use. |
| 7374 | |
| 7375 | [EFAULT] The _\bn_\ba_\bm_\be parameter specifies an area outside the |
| 7376 | process address space. |
| 7377 | |
| 7378 | [EINPROGRESS] The socket is non-blocking and the connection cannot |
| 7379 | be completed immediately. It is possible to select(2) |
| 7380 | or poll(2) for completion by selecting the socket for |
| 7381 | writing, and also use getsockopt(2) with SO_ERROR to |
| 7382 | check for error conditions. |
| 7383 | |
| 7384 | [EALREADY] The socket is non-blocking and a previous connection |
| 7385 | attempt has not yet been completed. |
| 7386 | |
| 7387 | The following errors are specific to connecting names in the UNIX-domain. |
| 7388 | These errors may not apply in future versions of the UNIX IPC domain. |
| 7389 | |
| 7390 | [ENOTDIR] A component of the path prefix is not a directory. |
| 7391 | |
| 7392 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 7393 | characters, or an entire pathname (including the |
| 7394 | terminating NUL) exceeded PATH_MAX bytes. |
| 7395 | |
| 7396 | [ENOENT] The named socket does not exist. |
| 7397 | |
| 7398 | [EACCES] Search permission is denied for a component of the |
| 7399 | path prefix. |
| 7400 | |
| 7401 | [EACCES] Write access to the named socket is denied. |
| 7402 | |
| 7403 | [ELOOP] Too many symbolic links were encountered in |
| 7404 | translating the pathname. |
| 7405 | |
| 7406 | [EPROTOTYPE] The file described by _\bn_\ba_\bm_\be is of a different type than |
| 7407 | _\bs. E.g., _\bs may be of type SOCK_STREAM whereas _\bn_\ba_\bm_\be |
| 7408 | may refer to a socket of type SOCK_DGRAM. |
| 7409 | |
| 7410 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7411 | accept(2), getsockname(2), getsockopt(2), poll(2), select(2), socket(2) |
| 7412 | |
| 7413 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 7414 | The c\bco\bon\bnn\bne\bec\bct\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 7415 | |
| 7416 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 7417 | The c\bco\bon\bnn\bne\bec\bct\bt() system call first appeared in 4.1cBSD. |
| 7418 | |
| 7419 | N\bNA\bAM\bME\bE |
| 7420 | d\bdu\bup\bp, d\bdu\bup\bp2\b2, d\bdu\bup\bp3\b3 - duplicate an existing file descriptor |
| 7421 | |
| 7422 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7423 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 7424 | |
| 7425 | _\bi_\bn_\bt |
| 7426 | d\bdu\bup\bp(_\bi_\bn_\bt _\bo_\bl_\bd_\bd); |
| 7427 | |
| 7428 | _\bi_\bn_\bt |
| 7429 | d\bdu\bup\bp2\b2(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd); |
| 7430 | |
| 7431 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 7432 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 7433 | |
| 7434 | _\bi_\bn_\bt |
| 7435 | d\bdu\bup\bp3\b3(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 7436 | |
| 7437 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7438 | d\bdu\bup\bp() duplicates an existing object descriptor and returns its value to |
| 7439 | the calling process (_\bn_\be_\bw_\bd = d\bdu\bup\bp(_\bo_\bl_\bd_\bd)). The argument _\bo_\bl_\bd_\bd is a small |
| 7440 | non-negative integer index in the per-process descriptor table. The |
| 7441 | value must be less than the size of the table, which is returned by |
| 7442 | getdtablesize(3). The new descriptor returned by the call is the lowest |
| 7443 | numbered descriptor currently not in use by the process. |
| 7444 | |
| 7445 | The object referenced by the descriptor does not distinguish between _\bo_\bl_\bd_\bd |
| 7446 | and _\bn_\be_\bw_\bd in any way. Thus if _\bn_\be_\bw_\bd and _\bo_\bl_\bd_\bd are duplicate references to |
| 7447 | an open file, read(2), write(2) and lseek(2) calls all move a single |
| 7448 | pointer into the file, and append mode, non-blocking I/O and asynchronous |
| 7449 | I/O options are shared between the references. If a separate pointer |
| 7450 | into the file is desired, a different object reference to the file must |
| 7451 | be obtained by issuing an additional open(2) call. The close-on-exec |
| 7452 | flag on the new file descriptor is unset. |
| 7453 | |
| 7454 | In d\bdu\bup\bp2\b2(), the value of the new descriptor _\bn_\be_\bw_\bd is specified. If this |
| 7455 | descriptor is already in use, it is first deallocated as if a close(2) |
| 7456 | call had been done first. When _\bn_\be_\bw_\bd equals _\bo_\bl_\bd_\bd, d\bdu\bup\bp2\b2() just returns |
| 7457 | without affecting the close-on-exec flag. |
| 7458 | |
| 7459 | In d\bdu\bup\bp3\b3(), both the value of the new descriptor and the close-on-exec |
| 7460 | flag on the new file descriptor are specified: _\bn_\be_\bw_\bd specifies the value |
| 7461 | and the O_CLOEXEC bit in _\bf_\bl_\ba_\bg_\bs specifies the close-on-exec flag. Unlike |
| 7462 | d\bdu\bup\bp2\b2(), if _\bo_\bl_\bd_\bd and _\bn_\be_\bw_\bd are equal then d\bdu\bup\bp3\b3() fails. Otherwise, if |
| 7463 | _\bf_\bl_\ba_\bg_\bs is zero then d\bdu\bup\bp3\b3() is identical to a call to d\bdu\bup\bp2\b2(). |
| 7464 | |
| 7465 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 7466 | Upon successful completion, the value of the new descriptor is returned. |
| 7467 | The value -1 is returned if an error occurs in either call. The external |
| 7468 | variable _\be_\br_\br_\bn_\bo indicates the cause of the error. |
| 7469 | |
| 7470 | E\bER\bRR\bRO\bOR\bRS\bS |
| 7471 | d\bdu\bup\bp() will fail if: |
| 7472 | |
| 7473 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor. |
| 7474 | |
| 7475 | [EMFILE] Too many descriptors are active. |
| 7476 | |
| 7477 | d\bdu\bup\bp2\b2() and d\bdu\bup\bp3\b3() will fail if: |
| 7478 | |
| 7479 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor or _\bn_\be_\bw_\bd is |
| 7480 | negative or greater than or equal to the process's |
| 7481 | RLIMIT_NOFILE limit. |
| 7482 | |
| 7483 | [EINTR] An interrupt was received. |
| 7484 | |
| 7485 | [EIO] An I/O error occurred while writing to the file |
| 7486 | system. |
| 7487 | |
| 7488 | In addition, d\bdu\bup\bp3\b3() will return the following error: |
| 7489 | |
| 7490 | [EINVAL] _\bo_\bl_\bd_\bd is equal to _\bn_\be_\bw_\bd or _\bf_\bl_\ba_\bg_\bs is invalid. |
| 7491 | |
| 7492 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7493 | accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), |
| 7494 | socketpair(2), getdtablesize(3) |
| 7495 | |
| 7496 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 7497 | d\bdu\bup\bp() and d\bdu\bup\bp2\b2() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
| 7498 | d\bdu\bup\bp3\b3() function is expected to conform to a future revision of that |
| 7499 | standard. |
| 7500 | |
| 7501 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 7502 | The d\bdu\bup\bp() system call first appeared in Version 3 AT&T UNIX, d\bdu\bup\bp2\b2() in |
| 7503 | Version 7 AT&T UNIX, and d\bdu\bup\bp3\b3() in OpenBSD 5.7. |
| 7504 | |
| 7505 | N\bNA\bAM\bME\bE |
| 7506 | d\bdu\bup\bp, d\bdu\bup\bp2\b2, d\bdu\bup\bp3\b3 - duplicate an existing file descriptor |
| 7507 | |
| 7508 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7509 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 7510 | |
| 7511 | _\bi_\bn_\bt |
| 7512 | d\bdu\bup\bp(_\bi_\bn_\bt _\bo_\bl_\bd_\bd); |
| 7513 | |
| 7514 | _\bi_\bn_\bt |
| 7515 | d\bdu\bup\bp2\b2(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd); |
| 7516 | |
| 7517 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 7518 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 7519 | |
| 7520 | _\bi_\bn_\bt |
| 7521 | d\bdu\bup\bp3\b3(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 7522 | |
| 7523 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7524 | d\bdu\bup\bp() duplicates an existing object descriptor and returns its value to |
| 7525 | the calling process (_\bn_\be_\bw_\bd = d\bdu\bup\bp(_\bo_\bl_\bd_\bd)). The argument _\bo_\bl_\bd_\bd is a small |
| 7526 | non-negative integer index in the per-process descriptor table. The |
| 7527 | value must be less than the size of the table, which is returned by |
| 7528 | getdtablesize(3). The new descriptor returned by the call is the lowest |
| 7529 | numbered descriptor currently not in use by the process. |
| 7530 | |
| 7531 | The object referenced by the descriptor does not distinguish between _\bo_\bl_\bd_\bd |
| 7532 | and _\bn_\be_\bw_\bd in any way. Thus if _\bn_\be_\bw_\bd and _\bo_\bl_\bd_\bd are duplicate references to |
| 7533 | an open file, read(2), write(2) and lseek(2) calls all move a single |
| 7534 | pointer into the file, and append mode, non-blocking I/O and asynchronous |
| 7535 | I/O options are shared between the references. If a separate pointer |
| 7536 | into the file is desired, a different object reference to the file must |
| 7537 | be obtained by issuing an additional open(2) call. The close-on-exec |
| 7538 | flag on the new file descriptor is unset. |
| 7539 | |
| 7540 | In d\bdu\bup\bp2\b2(), the value of the new descriptor _\bn_\be_\bw_\bd is specified. If this |
| 7541 | descriptor is already in use, it is first deallocated as if a close(2) |
| 7542 | call had been done first. When _\bn_\be_\bw_\bd equals _\bo_\bl_\bd_\bd, d\bdu\bup\bp2\b2() just returns |
| 7543 | without affecting the close-on-exec flag. |
| 7544 | |
| 7545 | In d\bdu\bup\bp3\b3(), both the value of the new descriptor and the close-on-exec |
| 7546 | flag on the new file descriptor are specified: _\bn_\be_\bw_\bd specifies the value |
| 7547 | and the O_CLOEXEC bit in _\bf_\bl_\ba_\bg_\bs specifies the close-on-exec flag. Unlike |
| 7548 | d\bdu\bup\bp2\b2(), if _\bo_\bl_\bd_\bd and _\bn_\be_\bw_\bd are equal then d\bdu\bup\bp3\b3() fails. Otherwise, if |
| 7549 | _\bf_\bl_\ba_\bg_\bs is zero then d\bdu\bup\bp3\b3() is identical to a call to d\bdu\bup\bp2\b2(). |
| 7550 | |
| 7551 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 7552 | Upon successful completion, the value of the new descriptor is returned. |
| 7553 | The value -1 is returned if an error occurs in either call. The external |
| 7554 | variable _\be_\br_\br_\bn_\bo indicates the cause of the error. |
| 7555 | |
| 7556 | E\bER\bRR\bRO\bOR\bRS\bS |
| 7557 | d\bdu\bup\bp() will fail if: |
| 7558 | |
| 7559 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor. |
| 7560 | |
| 7561 | [EMFILE] Too many descriptors are active. |
| 7562 | |
| 7563 | d\bdu\bup\bp2\b2() and d\bdu\bup\bp3\b3() will fail if: |
| 7564 | |
| 7565 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor or _\bn_\be_\bw_\bd is |
| 7566 | negative or greater than or equal to the process's |
| 7567 | RLIMIT_NOFILE limit. |
| 7568 | |
| 7569 | [EINTR] An interrupt was received. |
| 7570 | |
| 7571 | [EIO] An I/O error occurred while writing to the file |
| 7572 | system. |
| 7573 | |
| 7574 | In addition, d\bdu\bup\bp3\b3() will return the following error: |
| 7575 | |
| 7576 | [EINVAL] _\bo_\bl_\bd_\bd is equal to _\bn_\be_\bw_\bd or _\bf_\bl_\ba_\bg_\bs is invalid. |
| 7577 | |
| 7578 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7579 | accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), |
| 7580 | socketpair(2), getdtablesize(3) |
| 7581 | |
| 7582 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 7583 | d\bdu\bup\bp() and d\bdu\bup\bp2\b2() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
| 7584 | d\bdu\bup\bp3\b3() function is expected to conform to a future revision of that |
| 7585 | standard. |
| 7586 | |
| 7587 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 7588 | The d\bdu\bup\bp() system call first appeared in Version 3 AT&T UNIX, d\bdu\bup\bp2\b2() in |
| 7589 | Version 7 AT&T UNIX, and d\bdu\bup\bp3\b3() in OpenBSD 5.7. |
| 7590 | |
| 7591 | N\bNA\bAM\bME\bE |
| 7592 | d\bdu\bup\bp, d\bdu\bup\bp2\b2, d\bdu\bup\bp3\b3 - duplicate an existing file descriptor |
| 7593 | |
| 7594 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7595 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 7596 | |
| 7597 | _\bi_\bn_\bt |
| 7598 | d\bdu\bup\bp(_\bi_\bn_\bt _\bo_\bl_\bd_\bd); |
| 7599 | |
| 7600 | _\bi_\bn_\bt |
| 7601 | d\bdu\bup\bp2\b2(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd); |
| 7602 | |
| 7603 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 7604 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 7605 | |
| 7606 | _\bi_\bn_\bt |
| 7607 | d\bdu\bup\bp3\b3(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 7608 | |
| 7609 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7610 | d\bdu\bup\bp() duplicates an existing object descriptor and returns its value to |
| 7611 | the calling process (_\bn_\be_\bw_\bd = d\bdu\bup\bp(_\bo_\bl_\bd_\bd)). The argument _\bo_\bl_\bd_\bd is a small |
| 7612 | non-negative integer index in the per-process descriptor table. The |
| 7613 | value must be less than the size of the table, which is returned by |
| 7614 | getdtablesize(3). The new descriptor returned by the call is the lowest |
| 7615 | numbered descriptor currently not in use by the process. |
| 7616 | |
| 7617 | The object referenced by the descriptor does not distinguish between _\bo_\bl_\bd_\bd |
| 7618 | and _\bn_\be_\bw_\bd in any way. Thus if _\bn_\be_\bw_\bd and _\bo_\bl_\bd_\bd are duplicate references to |
| 7619 | an open file, read(2), write(2) and lseek(2) calls all move a single |
| 7620 | pointer into the file, and append mode, non-blocking I/O and asynchronous |
| 7621 | I/O options are shared between the references. If a separate pointer |
| 7622 | into the file is desired, a different object reference to the file must |
| 7623 | be obtained by issuing an additional open(2) call. The close-on-exec |
| 7624 | flag on the new file descriptor is unset. |
| 7625 | |
| 7626 | In d\bdu\bup\bp2\b2(), the value of the new descriptor _\bn_\be_\bw_\bd is specified. If this |
| 7627 | descriptor is already in use, it is first deallocated as if a close(2) |
| 7628 | call had been done first. When _\bn_\be_\bw_\bd equals _\bo_\bl_\bd_\bd, d\bdu\bup\bp2\b2() just returns |
| 7629 | without affecting the close-on-exec flag. |
| 7630 | |
| 7631 | In d\bdu\bup\bp3\b3(), both the value of the new descriptor and the close-on-exec |
| 7632 | flag on the new file descriptor are specified: _\bn_\be_\bw_\bd specifies the value |
| 7633 | and the O_CLOEXEC bit in _\bf_\bl_\ba_\bg_\bs specifies the close-on-exec flag. Unlike |
| 7634 | d\bdu\bup\bp2\b2(), if _\bo_\bl_\bd_\bd and _\bn_\be_\bw_\bd are equal then d\bdu\bup\bp3\b3() fails. Otherwise, if |
| 7635 | _\bf_\bl_\ba_\bg_\bs is zero then d\bdu\bup\bp3\b3() is identical to a call to d\bdu\bup\bp2\b2(). |
| 7636 | |
| 7637 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 7638 | Upon successful completion, the value of the new descriptor is returned. |
| 7639 | The value -1 is returned if an error occurs in either call. The external |
| 7640 | variable _\be_\br_\br_\bn_\bo indicates the cause of the error. |
| 7641 | |
| 7642 | E\bER\bRR\bRO\bOR\bRS\bS |
| 7643 | d\bdu\bup\bp() will fail if: |
| 7644 | |
| 7645 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor. |
| 7646 | |
| 7647 | [EMFILE] Too many descriptors are active. |
| 7648 | |
| 7649 | d\bdu\bup\bp2\b2() and d\bdu\bup\bp3\b3() will fail if: |
| 7650 | |
| 7651 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor or _\bn_\be_\bw_\bd is |
| 7652 | negative or greater than or equal to the process's |
| 7653 | RLIMIT_NOFILE limit. |
| 7654 | |
| 7655 | [EINTR] An interrupt was received. |
| 7656 | |
| 7657 | [EIO] An I/O error occurred while writing to the file |
| 7658 | system. |
| 7659 | |
| 7660 | In addition, d\bdu\bup\bp3\b3() will return the following error: |
| 7661 | |
| 7662 | [EINVAL] _\bo_\bl_\bd_\bd is equal to _\bn_\be_\bw_\bd or _\bf_\bl_\ba_\bg_\bs is invalid. |
| 7663 | |
| 7664 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 7665 | accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), |
| 7666 | socketpair(2), getdtablesize(3) |
| 7667 | |
| 7668 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 7669 | d\bdu\bup\bp() and d\bdu\bup\bp2\b2() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
| 7670 | d\bdu\bup\bp3\b3() function is expected to conform to a future revision of that |
| 7671 | standard. |
| 7672 | |
| 7673 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 7674 | The d\bdu\bup\bp() system call first appeared in Version 3 AT&T UNIX, d\bdu\bup\bp2\b2() in |
| 7675 | Version 7 AT&T UNIX, and d\bdu\bup\bp3\b3() in OpenBSD 5.7. |
| 7676 | |
| 7677 | N\bNA\bAM\bME\bE |
| 7678 | i\bin\bnt\btr\bro\bo - introduction to system calls and error numbers |
| 7679 | |
| 7680 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7681 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<e\ber\brr\brn\bno\bo.\b.h\bh>\b> |
| 7682 | |
| 7683 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 7684 | The manual pages in section 2 provide an overview of the system calls, |
| 7685 | their error returns, and other common definitions and concepts. |
| 7686 | |
| 7687 | D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS |
| 7688 | Nearly all of the system calls provide an error number via the identifier |
| 7689 | errno, which expands to an addressable location of type _\bi_\bn_\bt. The address |
| 7690 | of _\be_\br_\br_\bn_\bo in each thread is guaranteed to be unique for the lifetime of |
| 7691 | the thread. Applications must use _\be_\br_\br_\bn_\bo as defined in <_\be_\br_\br_\bn_\bo_\b._\bh> and not |
| 7692 | attempt to use a custom definition. |
| 7693 | |
| 7694 | When a system call detects an error, it returns an integer value |
| 7695 | indicating failure (usually -1) and sets the variable _\be_\br_\br_\bn_\bo accordingly. |
| 7696 | (This allows interpretation of the failure on receiving a -1 and to take |
| 7697 | action accordingly.) Successful calls never set _\be_\br_\br_\bn_\bo; once set, it |
| 7698 | remains until another error occurs. It should only be examined after an |
| 7699 | error. Note that a number of system calls overload the meanings of these |
| 7700 | error numbers, and that the meanings must be interpreted according to the |
| 7701 | type and circumstances of the call. |
| 7702 | |
| 7703 | The following is a complete list of the errors and their names as given |
| 7704 | in <_\bs_\by_\bs_\b/_\be_\br_\br_\bn_\bo_\b._\bh>. |
| 7705 | |
| 7706 | 0 _\bU_\bn_\bd_\be_\bf_\bi_\bn_\be_\bd _\be_\br_\br_\bo_\br_\b: _\b0. Not used. |
| 7707 | |
| 7708 | 1 EPERM _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bp_\be_\br_\bm_\bi_\bt_\bt_\be_\bd. An attempt was made to perform an |
| 7709 | operation limited to processes with appropriate privileges or to |
| 7710 | the owner of a file or other resources. |
| 7711 | |
| 7712 | 2 ENOENT _\bN_\bo _\bs_\bu_\bc_\bh _\bf_\bi_\bl_\be _\bo_\br _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. A component of a specified pathname |
| 7713 | did not exist, or the pathname was an empty string. |
| 7714 | |
| 7715 | 3 ESRCH _\bN_\bo _\bs_\bu_\bc_\bh _\bp_\br_\bo_\bc_\be_\bs_\bs. No process could be found which corresponds to |
| 7716 | the given process ID. |
| 7717 | |
| 7718 | 4 EINTR _\bI_\bn_\bt_\be_\br_\br_\bu_\bp_\bt_\be_\bd _\bs_\by_\bs_\bt_\be_\bm _\bc_\ba_\bl_\bl. An asynchronous signal (such as SIGINT |
| 7719 | or SIGQUIT) was caught by the thread during the execution of an |
| 7720 | interruptible function. If the signal handler performs a normal |
| 7721 | return, the interrupted function call will seem to have returned |
| 7722 | the error condition. |
| 7723 | |
| 7724 | 5 EIO _\bI_\bn_\bp_\bu_\bt_\b/_\bo_\bu_\bt_\bp_\bu_\bt _\be_\br_\br_\bo_\br. Some physical input or output error occurred. |
| 7725 | This error will not be reported until a subsequent operation on |
| 7726 | the same file descriptor and may be lost (overwritten) by any |
| 7727 | subsequent errors. |
| 7728 | |
| 7729 | 6 ENXIO _\bD_\be_\bv_\bi_\bc_\be _\bn_\bo_\bt _\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\bd. Input or output on a special file referred |
| 7730 | to a device that did not exist, or made a request beyond the |
| 7731 | limits of the device. This error may also occur when, for |
| 7732 | example, a tape drive is not online or no disk pack is loaded on |
| 7733 | a drive. |
| 7734 | |
| 7735 | 7 E2BIG _\bA_\br_\bg_\bu_\bm_\be_\bn_\bt _\bl_\bi_\bs_\bt _\bt_\bo_\bo _\bl_\bo_\bn_\bg. The number of bytes used for the argument |
| 7736 | and environment list of the new process exceeded the limit NCARGS |
| 7737 | (specified in <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh>). |
| 7738 | |
| 7739 | 8 ENOEXEC _\bE_\bx_\be_\bc _\bf_\bo_\br_\bm_\ba_\bt _\be_\br_\br_\bo_\br. A request was made to execute a file that, |
| 7740 | although it has the appropriate permissions, was not in the |
| 7741 | format required for an executable file. |
| 7742 | |
| 7743 | 9 EBADF _\bB_\ba_\bd _\bf_\bi_\bl_\be _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br. A file descriptor argument was out of range, |
| 7744 | referred to no open file, or a read (write) request was made to a |
| 7745 | file that was only open for writing (reading). |
| 7746 | |
| 7747 | 10 ECHILD _\bN_\bo _\bc_\bh_\bi_\bl_\bd _\bp_\br_\bo_\bc_\be_\bs_\bs_\be_\bs. A wait(2) or waitpid(2) function was |
| 7748 | executed by a process that had no existing or unwaited-for child |
| 7749 | processes. |
| 7750 | |
| 7751 | 11 EDEADLK _\bR_\be_\bs_\bo_\bu_\br_\bc_\be _\bd_\be_\ba_\bd_\bl_\bo_\bc_\bk _\ba_\bv_\bo_\bi_\bd_\be_\bd. An attempt was made to lock a |
| 7752 | system resource that would have resulted in a deadlock situation. |
| 7753 | |
| 7754 | 12 ENOMEM _\bC_\ba_\bn_\bn_\bo_\bt _\ba_\bl_\bl_\bo_\bc_\ba_\bt_\be _\bm_\be_\bm_\bo_\br_\by. The new process image required more |
| 7755 | memory than was allowed by the hardware or by system-imposed |
| 7756 | memory management constraints. A lack of swap space is normally |
| 7757 | temporary; however, a lack of core is not. Soft limits may be |
| 7758 | increased to their corresponding hard limits. |
| 7759 | |
| 7760 | 13 EACCES _\bP_\be_\br_\bm_\bi_\bs_\bs_\bi_\bo_\bn _\bd_\be_\bn_\bi_\be_\bd. An attempt was made to access a file in a |
| 7761 | way forbidden by its file access permissions. |
| 7762 | |
| 7763 | 14 EFAULT _\bB_\ba_\bd _\ba_\bd_\bd_\br_\be_\bs_\bs. The system detected an invalid address in |
| 7764 | attempting to use an argument of a call. |
| 7765 | |
| 7766 | 15 ENOTBLK _\bB_\bl_\bo_\bc_\bk _\bd_\be_\bv_\bi_\bc_\be _\br_\be_\bq_\bu_\bi_\br_\be_\bd. A block device operation was attempted |
| 7767 | on a non-block device or file. |
| 7768 | |
| 7769 | 16 EBUSY _\bD_\be_\bv_\bi_\bc_\be _\bb_\bu_\bs_\by. An attempt to use a system resource which was in |
| 7770 | use at the time in a manner which would have conflicted with the |
| 7771 | request. |
| 7772 | |
| 7773 | 17 EEXIST _\bF_\bi_\bl_\be _\be_\bx_\bi_\bs_\bt_\bs. An existing file was mentioned in an inappropriate |
| 7774 | context, for instance, as the new link name in a link(2) |
| 7775 | function. |
| 7776 | |
| 7777 | 18 EXDEV _\bC_\br_\bo_\bs_\bs_\b-_\bd_\be_\bv_\bi_\bc_\be _\bl_\bi_\bn_\bk. A hard link to a file on another file system |
| 7778 | was attempted. |
| 7779 | |
| 7780 | 19 ENODEV _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd _\bb_\by _\bd_\be_\bv_\bi_\bc_\be. An attempt was made to apply |
| 7781 | an inappropriate function to a device, for example, trying to |
| 7782 | read a write-only device such as a printer. |
| 7783 | |
| 7784 | 20 ENOTDIR _\bN_\bo_\bt _\ba _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. A component of the specified pathname |
| 7785 | existed, but it was not a directory, when a directory was |
| 7786 | expected. |
| 7787 | |
| 7788 | 21 EISDIR _\bI_\bs _\ba _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. An attempt was made to open a directory with |
| 7789 | write mode specified. |
| 7790 | |
| 7791 | 22 EINVAL _\bI_\bn_\bv_\ba_\bl_\bi_\bd _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt. Some invalid argument was supplied. (For |
| 7792 | example, specifying an undefined signal to a signal(3) or kill(2) |
| 7793 | function). |
| 7794 | |
| 7795 | 23 ENFILE _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bo_\bp_\be_\bn _\bf_\bi_\bl_\be_\bs _\bi_\bn _\bs_\by_\bs_\bt_\be_\bm. Maximum number of file |
| 7796 | descriptors allowable on the system has been reached and a |
| 7797 | request for an open cannot be satisfied until at least one has |
| 7798 | been closed. The sysctl(3) variable _\bk_\be_\br_\bn_\b._\bm_\ba_\bx_\bf_\bi_\bl_\be_\bs contains the |
| 7799 | current limit. |
| 7800 | |
| 7801 | 24 EMFILE _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bo_\bp_\be_\bn _\bf_\bi_\bl_\be_\bs. The maximum number of file descriptors |
| 7802 | allowable for this process has been reached and a request for an |
| 7803 | open cannot be satisfied until at least one has been closed. |
| 7804 | getdtablesize(3) will obtain the current limit. |
| 7805 | |
| 7806 | 25 ENOTTY _\bI_\bn_\ba_\bp_\bp_\br_\bo_\bp_\br_\bi_\ba_\bt_\be _\bi_\bo_\bc_\bt_\bl _\bf_\bo_\br _\bd_\be_\bv_\bi_\bc_\be. A control function (see |
| 7807 | ioctl(2)) was attempted for a file or special device for which |
| 7808 | the operation was inappropriate. |
| 7809 | |
| 7810 | 26 ETXTBSY _\bT_\be_\bx_\bt _\bf_\bi_\bl_\be _\bb_\bu_\bs_\by. An attempt was made either to execute a pure |
| 7811 | procedure (shared text) file which was open for writing by |
| 7812 | another process, or to open with write access a pure procedure |
| 7813 | file that is currently being executed. |
| 7814 | |
| 7815 | 27 EFBIG _\bF_\bi_\bl_\be _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be. The size of a file exceeded the maximum. (The |
| 7816 | system-wide maximum file size is 2**63 bytes. Each file system |
| 7817 | may impose a lower limit for files contained within it.) |
| 7818 | |
| 7819 | 28 ENOSPC _\bN_\bo _\bs_\bp_\ba_\bc_\be _\bl_\be_\bf_\bt _\bo_\bn _\bd_\be_\bv_\bi_\bc_\be. A write(2) to an ordinary file, the |
| 7820 | creation of a directory or symbolic link, or the creation of a |
| 7821 | directory entry failed because no more disk blocks were available |
| 7822 | on the file system, or the allocation of an inode for a newly |
| 7823 | created file failed because no more inodes were available on the |
| 7824 | file system. |
| 7825 | |
| 7826 | 29 ESPIPE _\bI_\bl_\bl_\be_\bg_\ba_\bl _\bs_\be_\be_\bk. An lseek(2) function was issued on a socket, pipe |
| 7827 | or FIFO. |
| 7828 | |
| 7829 | 30 EROFS _\bR_\be_\ba_\bd_\b-_\bo_\bn_\bl_\by _\bf_\bi_\bl_\be _\bs_\by_\bs_\bt_\be_\bm. An attempt was made to modify a file or |
| 7830 | create a directory on a file system that was read-only at the |
| 7831 | time. |
| 7832 | |
| 7833 | 31 EMLINK _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bl_\bi_\bn_\bk_\bs. The maximum allowable number of hard links to a |
| 7834 | single file has been exceeded (see pathconf(2) for how to obtain |
| 7835 | this value). |
| 7836 | |
| 7837 | 32 EPIPE _\bB_\br_\bo_\bk_\be_\bn _\bp_\bi_\bp_\be. A write on a pipe, socket or FIFO for which there |
| 7838 | is no process to read the data. |
| 7839 | |
| 7840 | 33 EDOM _\bN_\bu_\bm_\be_\br_\bi_\bc_\ba_\bl _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt _\bo_\bu_\bt _\bo_\bf _\bd_\bo_\bm_\ba_\bi_\bn. A numerical input argument was |
| 7841 | outside the defined domain of the mathematical function. |
| 7842 | |
| 7843 | 34 ERANGE _\bR_\be_\bs_\bu_\bl_\bt _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be. A result of the function was too large to fit |
| 7844 | in the available space (perhaps exceeded precision). |
| 7845 | |
| 7846 | 35 EAGAIN _\bR_\be_\bs_\bo_\bu_\br_\bc_\be _\bt_\be_\bm_\bp_\bo_\br_\ba_\br_\bi_\bl_\by _\bu_\bn_\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. This is a temporary condition |
| 7847 | and later calls to the same routine may complete normally. |
| 7848 | |
| 7849 | 36 EINPROGRESS _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bw _\bi_\bn _\bp_\br_\bo_\bg_\br_\be_\bs_\bs. An operation that takes a long |
| 7850 | time to complete (such as a connect(2)) was attempted on a non- |
| 7851 | blocking object (see fcntl(2)). |
| 7852 | |
| 7853 | 37 EALREADY _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\ba_\bl_\br_\be_\ba_\bd_\by _\bi_\bn _\bp_\br_\bo_\bg_\br_\be_\bs_\bs. An operation was attempted on |
| 7854 | a non-blocking object that already had an operation in progress. |
| 7855 | |
| 7856 | 38 ENOTSOCK _\bS_\bo_\bc_\bk_\be_\bt _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bo_\bn _\bn_\bo_\bn_\b-_\bs_\bo_\bc_\bk_\be_\bt. Self-explanatory. |
| 7857 | |
| 7858 | 39 EDESTADDRREQ _\bD_\be_\bs_\bt_\bi_\bn_\ba_\bt_\bi_\bo_\bn _\ba_\bd_\bd_\br_\be_\bs_\bs _\br_\be_\bq_\bu_\bi_\br_\be_\bd. A required address was |
| 7859 | omitted from an operation on a socket. |
| 7860 | |
| 7861 | 40 EMSGSIZE _\bM_\be_\bs_\bs_\ba_\bg_\be _\bt_\bo_\bo _\bl_\bo_\bn_\bg. A message sent on a socket was larger than |
| 7862 | the internal message buffer or some other network limit. |
| 7863 | |
| 7864 | 41 EPROTOTYPE _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bw_\br_\bo_\bn_\bg _\bt_\by_\bp_\be _\bf_\bo_\br _\bs_\bo_\bc_\bk_\be_\bt. A protocol was specified |
| 7865 | that does not support the semantics of the socket type requested. |
| 7866 | For example, you cannot use the Internet UDP protocol with type |
| 7867 | SOCK_STREAM. |
| 7868 | |
| 7869 | 42 ENOPROTOOPT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bn_\bo_\bt _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. A bad option or level was |
| 7870 | specified in a getsockopt(2) or setsockopt(2) call. |
| 7871 | |
| 7872 | 43 EPROTONOSUPPORT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The protocol has not been |
| 7873 | configured into the system or no implementation for it exists. |
| 7874 | |
| 7875 | 44 ESOCKTNOSUPPORT _\bS_\bo_\bc_\bk_\be_\bt _\bt_\by_\bp_\be _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The support for the socket |
| 7876 | type has not been configured into the system or no implementation |
| 7877 | for it exists. |
| 7878 | |
| 7879 | 45 EOPNOTSUPP _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The attempted operation is not |
| 7880 | supported for the type of object referenced. Usually this occurs |
| 7881 | when a file descriptor refers to a file or socket that cannot |
| 7882 | support this operation, for example, trying to _\ba_\bc_\bc_\be_\bp_\bt a |
| 7883 | connection on a datagram socket. |
| 7884 | |
| 7885 | 46 EPFNOSUPPORT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bf_\ba_\bm_\bi_\bl_\by _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The protocol family has |
| 7886 | not been configured into the system or no implementation for it |
| 7887 | exists. |
| 7888 | |
| 7889 | 47 EAFNOSUPPORT _\bA_\bd_\bd_\br_\be_\bs_\bs _\bf_\ba_\bm_\bi_\bl_\by _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd _\bb_\by _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bf_\ba_\bm_\bi_\bl_\by. An |
| 7890 | address incompatible with the requested protocol was used. For |
| 7891 | example, you shouldn't necessarily expect to be able to use NS |
| 7892 | addresses with Internet protocols. |
| 7893 | |
| 7894 | 48 EADDRINUSE _\bA_\bd_\bd_\br_\be_\bs_\bs _\ba_\bl_\br_\be_\ba_\bd_\by _\bi_\bn _\bu_\bs_\be. Only one usage of each address is |
| 7895 | normally permitted. |
| 7896 | |
| 7897 | 49 EADDRNOTAVAIL _\bC_\ba_\bn_\b'_\bt _\ba_\bs_\bs_\bi_\bg_\bn _\br_\be_\bq_\bu_\be_\bs_\bt_\be_\bd _\ba_\bd_\bd_\br_\be_\bs_\bs. Normally results from an |
| 7898 | attempt to create a socket with an address not on this machine. |
| 7899 | |
| 7900 | 50 ENETDOWN _\bN_\be_\bt_\bw_\bo_\br_\bk _\bi_\bs _\bd_\bo_\bw_\bn. A socket operation encountered a dead |
| 7901 | network. |
| 7902 | |
| 7903 | 51 ENETUNREACH _\bN_\be_\bt_\bw_\bo_\br_\bk _\bi_\bs _\bu_\bn_\br_\be_\ba_\bc_\bh_\ba_\bb_\bl_\be. A socket operation was attempted |
| 7904 | to an unreachable network. |
| 7905 | |
| 7906 | 52 ENETRESET _\bN_\be_\bt_\bw_\bo_\br_\bk _\bd_\br_\bo_\bp_\bp_\be_\bd _\bc_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\bo_\bn _\br_\be_\bs_\be_\bt. The host you were |
| 7907 | connected to crashed and rebooted. |
| 7908 | |
| 7909 | 53 ECONNABORTED _\bS_\bo_\bf_\bt_\bw_\ba_\br_\be _\bc_\ba_\bu_\bs_\be_\bd _\bc_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\ba_\bb_\bo_\br_\bt. A connection abort was |
| 7910 | caused internal to your host machine. |
| 7911 | |
| 7912 | 54 ECONNRESET _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\br_\be_\bs_\be_\bt _\bb_\by _\bp_\be_\be_\br. A connection was forcibly closed |
| 7913 | by a peer. This normally results from a loss of the connection |
| 7914 | on the remote socket due to a timeout or a reboot. |
| 7915 | |
| 7916 | 55 ENOBUFS _\bN_\bo _\bb_\bu_\bf_\bf_\be_\br _\bs_\bp_\ba_\bc_\be _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. An operation on a socket or pipe |
| 7917 | was not performed because the system lacked sufficient buffer |
| 7918 | space or because a queue was full. |
| 7919 | |
| 7920 | 56 EISCONN _\bS_\bo_\bc_\bk_\be_\bt _\bi_\bs _\ba_\bl_\br_\be_\ba_\bd_\by _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd. A connect(2) request was made on |
| 7921 | an already connected socket; or, a sendto(2) or sendmsg(2) |
| 7922 | request on a connected socket specified a destination when |
| 7923 | already connected. |
| 7924 | |
| 7925 | 57 ENOTCONN _\bS_\bo_\bc_\bk_\be_\bt _\bi_\bs _\bn_\bo_\bt _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd. A request to send or receive data |
| 7926 | was disallowed because the socket was not connected and (when |
| 7927 | sending on a datagram socket) no address was supplied. |
| 7928 | |
| 7929 | 58 ESHUTDOWN _\bC_\ba_\bn_\b'_\bt _\bs_\be_\bn_\bd _\ba_\bf_\bt_\be_\br _\bs_\bo_\bc_\bk_\be_\bt _\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn. A request to send data was |
| 7930 | disallowed because the socket had already been shut down with a |
| 7931 | previous shutdown(2) call. |
| 7932 | |
| 7933 | 59 ETOOMANYREFS _\bT_\bo_\bo _\bm_\ba_\bn_\by _\br_\be_\bf_\be_\br_\be_\bn_\bc_\be_\bs_\b: _\bc_\ba_\bn_\b'_\bt _\bs_\bp_\bl_\bi_\bc_\be. Not used in OpenBSD. |
| 7934 | |
| 7935 | 60 ETIMEDOUT _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bt_\bi_\bm_\be_\bd _\bo_\bu_\bt. A connect(2) or send(2) request failed |
| 7936 | because the connected party did not properly respond after a |
| 7937 | period of time. (The timeout period is dependent on the |
| 7938 | communication protocol.) |
| 7939 | |
| 7940 | 61 ECONNREFUSED _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\br_\be_\bf_\bu_\bs_\be_\bd. No connection could be made because |
| 7941 | the target machine actively refused it. This usually results |
| 7942 | from trying to connect to a service that is inactive on the |
| 7943 | foreign host. |
| 7944 | |
| 7945 | 62 ELOOP _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bl_\be_\bv_\be_\bl_\bs _\bo_\bf _\bs_\by_\bm_\bb_\bo_\bl_\bi_\bc _\bl_\bi_\bn_\bk_\bs. A path name lookup involved |
| 7946 | more than 32 (SYMLOOP_MAX) symbolic links. |
| 7947 | |
| 7948 | 63 ENAMETOOLONG _\bF_\bi_\bl_\be _\bn_\ba_\bm_\be _\bt_\bo_\bo _\bl_\bo_\bn_\bg. A component of a pathname exceeded |
| 7949 | 255 (NAME_MAX) characters, or an entire pathname (including the |
| 7950 | terminating NUL) exceeded 1024 (PATH_MAX) bytes. |
| 7951 | |
| 7952 | 64 EHOSTDOWN _\bH_\bo_\bs_\bt _\bi_\bs _\bd_\bo_\bw_\bn. A socket operation failed because the |
| 7953 | destination host was down. |
| 7954 | |
| 7955 | 65 EHOSTUNREACH _\bN_\bo _\br_\bo_\bu_\bt_\be _\bt_\bo _\bh_\bo_\bs_\bt. A socket operation was attempted to an |
| 7956 | unreachable host. |
| 7957 | |
| 7958 | 66 ENOTEMPTY _\bD_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bn_\bo_\bt _\be_\bm_\bp_\bt_\by. A directory with entries other than `.' |
| 7959 | and `..' was supplied to a remove directory or rename call. |
| 7960 | |
| 7961 | 67 EPROCLIM _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bp_\br_\bo_\bc_\be_\bs_\bs_\be_\bs. |
| 7962 | |
| 7963 | 68 EUSERS _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bu_\bs_\be_\br_\bs. The quota system ran out of table entries. |
| 7964 | |
| 7965 | 69 EDQUOT _\bD_\bi_\bs_\bc _\bq_\bu_\bo_\bt_\ba _\be_\bx_\bc_\be_\be_\bd_\be_\bd. A write(2) to an ordinary file, the |
| 7966 | creation of a directory or symbolic link, or the creation of a |
| 7967 | directory entry failed because the user's quota of disk blocks |
| 7968 | was exhausted, or the allocation of an inode for a newly created |
| 7969 | file failed because the user's quota of inodes was exhausted. |
| 7970 | |
| 7971 | 70 ESTALE _\bS_\bt_\ba_\bl_\be _\bN_\bF_\bS _\bf_\bi_\bl_\be _\bh_\ba_\bn_\bd_\bl_\be. An attempt was made to access an open |
| 7972 | file on an NFS filesystem which is now unavailable as referenced |
| 7973 | by the file descriptor. This may indicate the file was deleted |
| 7974 | on the NFS server or some other catastrophic event occurred. |
| 7975 | |
| 7976 | 72 EBADRPC _\bR_\bP_\bC _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bs _\bb_\ba_\bd. Exchange of rpc(3) information was |
| 7977 | unsuccessful. |
| 7978 | |
| 7979 | 73 ERPCMISMATCH _\bR_\bP_\bC _\bv_\be_\br_\bs_\bi_\bo_\bn _\bw_\br_\bo_\bn_\bg. The version of rpc(3) on the remote |
| 7980 | peer is not compatible with the local version. |
| 7981 | |
| 7982 | 74 EPROGUNAVAIL _\bR_\bP_\bC _\bp_\br_\bo_\bg_\b. _\bn_\bo_\bt _\ba_\bv_\ba_\bi_\bl. The requested rpc(3) program is not |
| 7983 | registered on the remote host. |
| 7984 | |
| 7985 | 75 EPROGMISMATCH _\bP_\br_\bo_\bg_\br_\ba_\bm _\bv_\be_\br_\bs_\bi_\bo_\bn _\bw_\br_\bo_\bn_\bg. The requested version of the |
| 7986 | rpc(3) program is not available on the remote host. |
| 7987 | |
| 7988 | 76 EPROCUNAVAIL _\bB_\ba_\bd _\bp_\br_\bo_\bc_\be_\bd_\bu_\br_\be _\bf_\bo_\br _\bp_\br_\bo_\bg_\br_\ba_\bm. An rpc(3) call was attempted |
| 7989 | for a procedure which doesn't exist in the remote program. |
| 7990 | |
| 7991 | 77 ENOLCK _\bN_\bo _\bl_\bo_\bc_\bk_\bs _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. A system-imposed limit on the number of |
| 7992 | simultaneous file locks was reached. |
| 7993 | |
| 7994 | 78 ENOSYS _\bF_\bu_\bn_\bc_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd. Attempted a system call that is not |
| 7995 | available on this system. |
| 7996 | |
| 7997 | 79 EFTYPE _\bI_\bn_\ba_\bp_\bp_\br_\bo_\bp_\br_\bi_\ba_\bt_\be _\bf_\bi_\bl_\be _\bt_\by_\bp_\be _\bo_\br _\bf_\bo_\br_\bm_\ba_\bt. The file contains invalid |
| 7998 | data or set to invalid modes. |
| 7999 | |
| 8000 | 80 EAUTH _\bA_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\be_\br_\br_\bo_\br. Attempted to use an invalid authentication |
| 8001 | ticket to mount a NFS filesystem. |
| 8002 | |
| 8003 | 81 ENEEDAUTH _\bN_\be_\be_\bd _\ba_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\bo_\br. An authentication ticket must be |
| 8004 | obtained before the given NFS filesystem may be mounted. |
| 8005 | |
| 8006 | 82 EIPSEC _\bI_\bP_\bs_\be_\bc _\bp_\br_\bo_\bc_\be_\bs_\bs_\bi_\bn_\bg _\bf_\ba_\bi_\bl_\bu_\br_\be. IPsec subsystem error. Not used in |
| 8007 | OpenBSD. |
| 8008 | |
| 8009 | 83 ENOATTR _\bA_\bt_\bt_\br_\bi_\bb_\bu_\bt_\be _\bn_\bo_\bt _\bf_\bo_\bu_\bn_\bd. A UFS Extended Attribute is not found for |
| 8010 | the specified pathname. |
| 8011 | |
| 8012 | 84 EILSEQ _\bI_\bl_\bl_\be_\bg_\ba_\bl _\bb_\by_\bt_\be _\bs_\be_\bq_\bu_\be_\bn_\bc_\be. An illegal sequence of bytes was used |
| 8013 | when using wide characters. |
| 8014 | |
| 8015 | 85 ENOMEDIUM _\bN_\bo _\bm_\be_\bd_\bi_\bu_\bm _\bf_\bo_\bu_\bn_\bd. Attempted to use a removable media device |
| 8016 | with no medium present. |
| 8017 | |
| 8018 | 86 EMEDIUMTYPE _\bW_\br_\bo_\bn_\bg _\bm_\be_\bd_\bi_\bu_\bm _\bt_\by_\bp_\be. Attempted to use a removable media |
| 8019 | device with incorrect or incompatible medium. |
| 8020 | |
| 8021 | 87 EOVERFLOW _\bV_\ba_\bl_\bu_\be _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be _\bt_\bo _\bb_\be _\bs_\bt_\bo_\br_\be_\bd _\bi_\bn _\bd_\ba_\bt_\ba _\bt_\by_\bp_\be. A numerical |
| 8022 | result of the function was too large to be stored in the caller |
| 8023 | provided space. |
| 8024 | |
| 8025 | 88 ECANCELED _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bc_\ba_\bn_\bc_\be_\bl_\be_\bd. The requested operation was canceled. |
| 8026 | |
| 8027 | 89 EIDRM _\bI_\bd_\be_\bn_\bt_\bi_\bf_\bi_\be_\br _\br_\be_\bm_\bo_\bv_\be_\bd. An IPC identifier was removed while the |
| 8028 | current thread was waiting on it. |
| 8029 | |
| 8030 | 90 ENOMSG _\bN_\bo _\bm_\be_\bs_\bs_\ba_\bg_\be _\bo_\bf _\bd_\be_\bs_\bi_\br_\be_\bd _\bt_\by_\bp_\be. An IPC message queue does not |
| 8031 | contain a message of the desired type, or a message catalog does |
| 8032 | not contain the requested message. |
| 8033 | |
| 8034 | 91 ENOTSUP _\bN_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The operation has requested an unsupported |
| 8035 | value. |
| 8036 | |
| 8037 | D\bDE\bEF\bFI\bIN\bNI\bIT\bTI\bIO\bON\bNS\bS |
| 8038 | Process |
| 8039 | A process is a collection of one or more threads, plus the |
| 8040 | resources shared by those threads such as process ID, address |
| 8041 | space, user IDs and group IDs, and root directory and current |
| 8042 | working directory. |
| 8043 | |
| 8044 | Process ID |
| 8045 | Each active process in the system is uniquely identified by a |
| 8046 | non-negative integer called a process ID. The range of this ID |
| 8047 | is from 1 to 32766. |
| 8048 | |
| 8049 | Parent Process ID |
| 8050 | A new process is created by a currently active process; (see |
| 8051 | fork(2)). The parent process ID of a process is initially the |
| 8052 | process ID of its creator. If the creating process exits, the |
| 8053 | parent process ID of each child is set to the ID of a system |
| 8054 | process, init(8). |
| 8055 | |
| 8056 | Process Group |
| 8057 | Each active process is a member of a process group that is |
| 8058 | identified by a non-negative integer called the process group ID. |
| 8059 | This is the process ID of the group leader. This grouping |
| 8060 | permits the signaling of related processes (see termios(4)) and |
| 8061 | the job control mechanisms of csh(1). |
| 8062 | |
| 8063 | Session |
| 8064 | A session is a set of one or more process groups. A session is |
| 8065 | created by a successful call to setsid(2), which causes the |
| 8066 | caller to become the only member of the only process group in the |
| 8067 | new session. |
| 8068 | |
| 8069 | Session Leader |
| 8070 | A process that has created a new session by a successful call to |
| 8071 | setsid(2), is known as a session leader. Only a session leader |
| 8072 | may acquire a terminal as its controlling terminal (see |
| 8073 | termios(4)). |
| 8074 | |
| 8075 | Controlling Process |
| 8076 | A session leader with a controlling terminal is a controlling |
| 8077 | process. |
| 8078 | |
| 8079 | Controlling Terminal |
| 8080 | A terminal that is associated with a session is known as the |
| 8081 | controlling terminal for that session and its members. |
| 8082 | |
| 8083 | Terminal Process Group ID |
| 8084 | A terminal may be acquired by a session leader as its controlling |
| 8085 | terminal. Once a terminal is associated with a session, any of |
| 8086 | the process groups within the session may be placed into the |
| 8087 | foreground by setting the terminal process group ID to the ID of |
| 8088 | the process group. This facility is used to arbitrate between |
| 8089 | multiple jobs contending for the same terminal; (see csh(1) and |
| 8090 | tty(4)). |
| 8091 | |
| 8092 | Orphaned Process Group |
| 8093 | A process group is considered to be _\bo_\br_\bp_\bh_\ba_\bn_\be_\bd if it is not under |
| 8094 | the control of a job control shell. More precisely, a process |
| 8095 | group is orphaned when none of its members has a parent process |
| 8096 | that is in the same session as the group, but is in a different |
| 8097 | process group. Note that when a process exits, the parent |
| 8098 | process for its children is changed to be init(8), which is in a |
| 8099 | separate session. Not all members of an orphaned process group |
| 8100 | are necessarily orphaned processes (those whose creating process |
| 8101 | has exited). The process group of a session leader is orphaned |
| 8102 | by definition. |
| 8103 | |
| 8104 | Thread A thread is a preemptively scheduled flow of control within a |
| 8105 | process, with its own set of register values, floating point |
| 8106 | environment, thread ID, signal mask, pending signal set, |
| 8107 | alternate signal stack, thread control block address, resource |
| 8108 | utilization, errno variable location, and values for thread- |
| 8109 | specific keys. A process initially has just one thread, a |
| 8110 | duplicate of the thread in the parent process that created this |
| 8111 | process. |
| 8112 | |
| 8113 | Real User ID and Real Group ID |
| 8114 | Each user on the system is identified by a positive integer |
| 8115 | termed the real user ID. |
| 8116 | |
| 8117 | Each user is also a member of one or more groups. One of these |
| 8118 | groups is distinguished from others and used in implementing |
| 8119 | accounting facilities. The positive integer corresponding to |
| 8120 | this distinguished group is termed the real group ID. |
| 8121 | |
| 8122 | All processes have a real user ID and real group ID. These are |
| 8123 | initialized from the equivalent attributes of the process that |
| 8124 | created it. |
| 8125 | |
| 8126 | Effective User ID, Effective Group ID, and Group Access List |
| 8127 | Access to system resources is governed by two values: the |
| 8128 | effective user ID, and the group access list. The first member |
| 8129 | of the group access list is also known as the effective group ID. |
| 8130 | (In POSIX.1, the group access list is known as the set of |
| 8131 | supplementary group IDs, and it is unspecified whether the |
| 8132 | effective group ID is a member of the list.) |
| 8133 | |
| 8134 | The effective user ID and effective group ID are initially the |
| 8135 | process's real user ID and real group ID respectively. Either |
| 8136 | may be modified through execution of a set-user-ID or set-group- |
| 8137 | ID file (possibly by one of its ancestors) (see execve(2)). By |
| 8138 | convention, the effective group ID (the first member of the group |
| 8139 | access list) is duplicated, so that the execution of a set-group- |
| 8140 | ID program does not result in the loss of the original (real) |
| 8141 | group ID. |
| 8142 | |
| 8143 | The group access list is a set of group IDs used only in |
| 8144 | determining resource accessibility. Access checks are performed |
| 8145 | as described below in ``File Access Permissions''. |
| 8146 | |
| 8147 | Saved Set User ID and Saved Set Group ID |
| 8148 | When a process executes a new file, the effective user ID is set |
| 8149 | to the owner of the file if the file is set-user-ID, and the |
| 8150 | effective group ID (first element of the group access list) is |
| 8151 | set to the group of the file if the file is set-group-ID. The |
| 8152 | effective user ID of the process is then recorded as the saved |
| 8153 | set-user-ID, and the effective group ID of the process is |
| 8154 | recorded as the saved set-group-ID. These values may be used to |
| 8155 | regain those values as the effective user or group ID after |
| 8156 | reverting to the real ID (see setuid(2)). (In POSIX.1, the saved |
| 8157 | set-user-ID and saved set-group-ID are optional, and are used in |
| 8158 | setuid and setgid, but this does not work as desired for the |
| 8159 | superuser.) |
| 8160 | |
| 8161 | Superuser |
| 8162 | A process is recognized as a _\bs_\bu_\bp_\be_\br_\bu_\bs_\be_\br process and is granted |
| 8163 | special privileges if its effective user ID is 0. |
| 8164 | |
| 8165 | Special Processes |
| 8166 | The processes with process IDs of 0 and 1 are special. Process 0 |
| 8167 | is the scheduler. Process 1 is the initialization process |
| 8168 | init(8), and is the ancestor of every other process in the |
| 8169 | system. It is used to control the process structure. |
| 8170 | |
| 8171 | Descriptor |
| 8172 | An integer assigned by the system when a file is referenced by |
| 8173 | open(2) or dup(2), or when a socket is created by pipe(2), |
| 8174 | socket(2) or socketpair(2), which uniquely identifies an access |
| 8175 | path to that file or socket from a given process or any of its |
| 8176 | children. |
| 8177 | |
| 8178 | File Name |
| 8179 | Names consisting of up to 255 (NAME_MAX) characters may be used |
| 8180 | to name an ordinary file, special file, or directory. |
| 8181 | |
| 8182 | These characters may be arbitrary eight-bit values, excluding 0 |
| 8183 | (NUL) and the ASCII code for `/' (slash). |
| 8184 | |
| 8185 | Note that it is generally unwise to use `*', `?', `[' or `]' as |
| 8186 | part of file names because of the special meaning attached to |
| 8187 | these characters by the shell. |
| 8188 | |
| 8189 | Note also that NAME_MAX is an upper limit fixed by the kernel, |
| 8190 | meant to be used for sizing buffers. Some filesystems may have |
| 8191 | additional restrictions. These can be queried using pathconf(2) |
| 8192 | and fpathconf(2). |
| 8193 | |
| 8194 | Path Name |
| 8195 | A path name is a NUL-terminated character string starting with an |
| 8196 | optional slash `/', followed by zero or more directory names |
| 8197 | separated by slashes, optionally followed by a file name. The |
| 8198 | total length of a path name must be less than 1024 (PATH_MAX) |
| 8199 | characters. Additional restrictions may apply, depending upon |
| 8200 | the filesystem, to be queried with pathconf(2) or fpathconf(2) if |
| 8201 | needed. |
| 8202 | |
| 8203 | If a path name begins with a slash, the path search begins at the |
| 8204 | _\br_\bo_\bo_\bt directory. Otherwise, the search begins from the current |
| 8205 | working directory. A slash by itself names the root directory. |
| 8206 | An empty pathname is invalid. |
| 8207 | |
| 8208 | Directory |
| 8209 | A directory is a special type of file that contains entries that |
| 8210 | are references to other files. Directory entries are called |
| 8211 | links. By convention, a directory contains at least two links, |
| 8212 | `.' and `..', referred to as _\bd_\bo_\bt and _\bd_\bo_\bt_\b-_\bd_\bo_\bt respectively. Dot |
| 8213 | refers to the directory itself and dot-dot refers to its parent |
| 8214 | directory. |
| 8215 | |
| 8216 | Root Directory and Current Working Directory |
| 8217 | Each process has associated with it a concept of a root directory |
| 8218 | and a current working directory for the purpose of resolving path |
| 8219 | name searches. A process's root directory need not be the root |
| 8220 | directory of the root file system. |
| 8221 | |
| 8222 | File Access Permissions |
| 8223 | Every file in the file system has a set of access permissions. |
| 8224 | These permissions are used in determining whether a process may |
| 8225 | perform a requested operation on the file (such as opening a file |
| 8226 | for writing). Access permissions are established at the time a |
| 8227 | file is created. They may be changed at some later time through |
| 8228 | the chmod(2) call. |
| 8229 | |
| 8230 | File access is broken down according to whether a file may be: |
| 8231 | read, written, or executed. Directory files use the execute |
| 8232 | permission to control if the directory may be searched. |
| 8233 | |
| 8234 | File access permissions are interpreted by the system as they |
| 8235 | apply to three different classes of users: the owner of the file, |
| 8236 | those users in the file's group, anyone else. Every file has an |
| 8237 | independent set of access permissions for each of these classes. |
| 8238 | When an access check is made, the system decides if permission |
| 8239 | should be granted by checking the access information applicable |
| 8240 | to the caller. |
| 8241 | |
| 8242 | Read, write, and execute/search permissions on a file are granted |
| 8243 | to a process if: |
| 8244 | |
| 8245 | The process's effective user ID is that of the superuser. (Note: |
| 8246 | even the superuser cannot execute a non-executable file.) |
| 8247 | |
| 8248 | The process's effective user ID matches the user ID of the owner |
| 8249 | of the file and the owner permissions allow the access. |
| 8250 | |
| 8251 | The process's effective user ID does not match the user ID of the |
| 8252 | owner of the file, and either the process's effective group ID |
| 8253 | matches the group ID of the file, or the group ID of the file is |
| 8254 | in the process's group access list, and the group permissions |
| 8255 | allow the access. |
| 8256 | |
| 8257 | Neither the effective user ID nor effective group ID and group |
| 8258 | access list of the process match the corresponding user ID and |
| 8259 | group ID of the file, but the permissions for ``other users'' |
| 8260 | allow access. |
| 8261 | |
| 8262 | Otherwise, permission is denied. |
| 8263 | |
| 8264 | Sockets and Address Families |
| 8265 | A socket is an endpoint for communication between processes. |
| 8266 | Each socket has queues for sending and receiving data. |
| 8267 | |
| 8268 | Sockets are typed according to their communications properties. |
| 8269 | These properties include whether messages sent and received at a |
| 8270 | socket require the name of the partner, whether communication is |
| 8271 | reliable, the format used in naming message recipients, etc. |
| 8272 | |
| 8273 | Each instance of the system supports some collection of socket |
| 8274 | types; consult socket(2) for more information about the types |
| 8275 | available and their properties. |
| 8276 | |
| 8277 | Each instance of the system supports some number of sets of |
| 8278 | communications protocols. Each protocol set supports addresses |
| 8279 | of a certain format. An Address Family is the set of addresses |
| 8280 | for a specific group of protocols. Each socket has an address |
| 8281 | chosen from the address family in which the socket was created. |
| 8282 | |
| 8283 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 8284 | intro(3), perror(3) |
| 8285 | |
| 8286 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 8287 | An k\bkq\bqu\bue\beu\bue\be manual page appeared in Version 6 AT&T UNIX. |
| 8288 | |
| 8289 | N\bNA\bAM\bME\bE |
| 8290 | e\bex\bxe\bec\bcv\bve\be, e\bex\bxe\bec\bct\bt - execute a file |
| 8291 | |
| 8292 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 8293 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 8294 | |
| 8295 | _\bi_\bn_\bt |
| 8296 | e\bex\bxe\bec\bcv\bve\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b], _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); |
| 8297 | |
| 8298 | _\bi_\bn_\bt |
| 8299 | e\bex\bxe\bec\bct\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b], _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); |
| 8300 | |
| 8301 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 8302 | e\bex\bxe\bec\bcv\bve\be() transforms the calling process into a new process. The new |
| 8303 | process is constructed from an ordinary file, whose name is pointed to by |
| 8304 | _\bp_\ba_\bt_\bh, called the _\bn_\be_\bw _\bp_\br_\bo_\bc_\be_\bs_\bs _\bf_\bi_\bl_\be. This file is either an executable |
| 8305 | object file, or a file of data for an interpreter. An executable object |
| 8306 | file consists of an identifying header, followed by pages of data |
| 8307 | representing the initial program (text) and initialized data pages. |
| 8308 | Additional pages may be specified by the header to be initialized with |
| 8309 | zero data; see elf(5). |
| 8310 | |
| 8311 | An interpreter file begins with a line of the form: |
| 8312 | |
| 8313 | #\b#!\b! _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br [_\ba_\br_\bg] |
| 8314 | |
| 8315 | When an interpreter file is passed to e\bex\bxe\bec\bcv\bve\be() the system instead calls |
| 8316 | e\bex\bxe\bec\bcv\bve\be() with the specified _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br. If the optional _\ba_\br_\bg is |
| 8317 | specified, it becomes the first argument to the _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br, and the |
| 8318 | original _\bp_\ba_\bt_\bh becomes the second argument; otherwise, _\bp_\ba_\bt_\bh becomes the |
| 8319 | first argument. The original arguments are shifted over to become the |
| 8320 | subsequent arguments. The zeroth argument, normally the name of the file |
| 8321 | being executed, is left unchanged. |
| 8322 | |
| 8323 | The argument _\ba_\br_\bg_\bv is a pointer to a null-terminated array of character |
| 8324 | pointers to NUL-terminated character strings. These strings construct |
| 8325 | the argument list to be made available to the new process. At least one |
| 8326 | non-null argument must be present in the array; by custom, the first |
| 8327 | element should be the name of the executed program (for example, the last |
| 8328 | component of _\bp_\ba_\bt_\bh). |
| 8329 | |
| 8330 | The argument _\be_\bn_\bv_\bp is also a pointer to a null-terminated array of |
| 8331 | character pointers to NUL-terminated strings. A pointer to this array is |
| 8332 | normally stored in the global variable _\be_\bn_\bv_\bi_\br_\bo_\bn. These strings pass |
| 8333 | information to the new process that is not directly an argument to the |
| 8334 | command (see environ(7)). |
| 8335 | |
| 8336 | File descriptors open in the calling process image remain open in the new |
| 8337 | process image, except for those for which the close-on-exec flag is set |
| 8338 | (see close(2) and fcntl(2)). Descriptors that remain open are unaffected |
| 8339 | by e\bex\bxe\bec\bcv\bve\be(). In the case of a new setuid or setgid executable being |
| 8340 | executed, if file descriptors 0, 1, or 2 (representing stdin, stdout, and |
| 8341 | stderr) are currently unallocated, these descriptors will be opened to |
| 8342 | point to some system file like _\b/_\bd_\be_\bv_\b/_\bn_\bu_\bl_\bl. The intent is to ensure these |
| 8343 | descriptors are not unallocated, since many libraries make assumptions |
| 8344 | about the use of these 3 file descriptors. |
| 8345 | |
| 8346 | Signals set to be ignored in the calling process are set to be ignored in |
| 8347 | the new process. Signals which are set to be caught in the calling |
| 8348 | process image are set to default action in the new process image. |
| 8349 | Blocked signals remain blocked regardless of changes to the signal |
| 8350 | action. The signal stack is reset to be undefined (see sigaction(2) for |
| 8351 | more information). |
| 8352 | |
| 8353 | If the set-user-ID mode bit of the new process image file is set (see |
| 8354 | chmod(2)), the effective user ID of the new process image is set to the |
| 8355 | owner ID of the new process image file. If the set-group-ID mode bit of |
| 8356 | the new process image file is set, the effective group ID of the new |
| 8357 | process image is set to the group ID of the new process image file. (The |
| 8358 | effective group ID is the first element of the group list.) The real |
| 8359 | user ID, real group ID and other group IDs of the new process image |
| 8360 | remain the same as the calling process image. After any set-user-ID and |
| 8361 | set-group-ID processing, the effective user ID is recorded as the saved |
| 8362 | set-user-ID, and the effective group ID is recorded as the saved set- |
| 8363 | group-ID. These values may be used in changing the effective IDs later |
| 8364 | (see setuid(2)). The set-user-ID and set-group-ID bits have no effect if |
| 8365 | the new process image file is located on a file system mounted with the |
| 8366 | nosuid flag. The process will be started without the new permissions. |
| 8367 | |
| 8368 | The new process also inherits the following attributes from the calling |
| 8369 | process: |
| 8370 | |
| 8371 | process ID see getpid(2) |
| 8372 | parent process ID see getppid(2) |
| 8373 | process group ID see getpgrp(2) |
| 8374 | session ID see getsid(2) |
| 8375 | access groups see getgroups(2) |
| 8376 | working directory see chdir(2) |
| 8377 | root directory see chroot(2) |
| 8378 | control terminal see termios(4) |
| 8379 | resource usages see getrusage(2) |
| 8380 | interval timers see getitimer(2) (unless process image file is |
| 8381 | setuid or setgid, in which case all timers are |
| 8382 | disabled) |
| 8383 | resource limits see getrlimit(2) |
| 8384 | file mode mask see umask(2) |
| 8385 | signal mask see sigaction(2), sigsetmask(3) |
| 8386 | |
| 8387 | When a program is executed as a result of an e\bex\bxe\bec\bcv\bve\be() call, it is entered |
| 8388 | as follows: |
| 8389 | |
| 8390 | main(int argc, char **argv, char **envp) |
| 8391 | |
| 8392 | where _\ba_\br_\bg_\bc is the number of elements in _\ba_\br_\bg_\bv (the ``arg count'') and _\ba_\br_\bg_\bv |
| 8393 | points to the array of character pointers to the arguments themselves. |
| 8394 | |
| 8395 | The e\bex\bxe\bec\bct\bt() function is equivalent to e\bex\bxe\bec\bcv\bve\be() with the additional |
| 8396 | property that it executes the file with the process tracing facilities |
| 8397 | enabled (see ptrace(2)). |
| 8398 | |
| 8399 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 8400 | As the e\bex\bxe\bec\bcv\bve\be() function overlays the current process image with a new |
| 8401 | process image the successful call has no process to return to. If |
| 8402 | e\bex\bxe\bec\bcv\bve\be() does return to the calling process an error has occurred; the |
| 8403 | return value will be -1 and the global variable _\be_\br_\br_\bn_\bo is set to indicate |
| 8404 | the error. |
| 8405 | |
| 8406 | E\bER\bRR\bRO\bOR\bRS\bS |
| 8407 | e\bex\bxe\bec\bcv\bve\be() will fail and return to the calling process if: |
| 8408 | |
| 8409 | [ENOTDIR] A component of the path prefix is not a directory. |
| 8410 | |
| 8411 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 8412 | characters, or an entire pathname (including the |
| 8413 | terminating NUL) exceeded PATH_MAX bytes. |
| 8414 | |
| 8415 | [ENOENT] The new process file does not exist. |
| 8416 | |
| 8417 | [ELOOP] Too many symbolic links were encountered in |
| 8418 | translating the pathname. |
| 8419 | |
| 8420 | [EACCES] Search permission is denied for a component of the |
| 8421 | path prefix. |
| 8422 | |
| 8423 | [EACCES] The new process file is not an ordinary file. |
| 8424 | |
| 8425 | [EACCES] The new process file mode denies execute permission. |
| 8426 | |
| 8427 | [EACCES] The new process file is on a filesystem mounted with |
| 8428 | execution disabled (MNT_NOEXEC in <_\bs_\by_\bs_\b/_\bm_\bo_\bu_\bn_\bt_\b._\bh>). |
| 8429 | |
| 8430 | [ENOEXEC] The new process file has the appropriate access |
| 8431 | permission, but has an invalid magic number in its |
| 8432 | header. |
| 8433 | |
| 8434 | [ETXTBSY] The new process file is a pure procedure (shared text) |
| 8435 | file that is currently open for writing or reading by |
| 8436 | some process. |
| 8437 | |
| 8438 | [ENOMEM] The new process requires more virtual memory than is |
| 8439 | allowed by the imposed maximum (getrlimit(2)). |
| 8440 | |
| 8441 | [E2BIG] The number of bytes in the new process's argument list |
| 8442 | is larger than the system-imposed limit. The limit in |
| 8443 | the system as released is 262144 bytes (NCARGS in |
| 8444 | <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh>). |
| 8445 | |
| 8446 | [EFAULT] The new process file is not as long as indicated by |
| 8447 | the size values in its header. |
| 8448 | |
| 8449 | [EFAULT] _\bp_\ba_\bt_\bh, _\ba_\br_\bg_\bv, or _\be_\bn_\bv_\bp point to an illegal address. |
| 8450 | |
| 8451 | [EINVAL] _\ba_\br_\bg_\bv did not contain at least one element. |
| 8452 | |
| 8453 | [EIO] An I/O error occurred while reading from the file |
| 8454 | system. |
| 8455 | |
| 8456 | [ENFILE] During startup of an _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br, the system file |
| 8457 | table was found to be full. |
| 8458 | |
| 8459 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 8460 | _exit(2), fork(2), execl(3), exit(3), elf(5), environ(7) |
| 8461 | |
| 8462 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 8463 | The e\bex\bxe\bec\bcv\bve\be() function is expected to conform to IEEE Std 1003.1-2008 |
| 8464 | (``POSIX.1''). The e\bex\bxe\bec\bct\bt() function should not be used in portable |
| 8465 | applications. |
| 8466 | |
| 8467 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 8468 | The predecessor of these functions, the former e\bex\bxe\bec\bc() system call, first |
| 8469 | appeared in Version 1 AT&T UNIX. The e\bex\bxe\bec\bcv\bve\be() function first appeared in |
| 8470 | Version 7 AT&T UNIX. |
| 8471 | |
| 8472 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 8473 | If a program is _\bs_\be_\bt_\bu_\bi_\bd to a non-superuser, but is executed when the real |
| 8474 | _\bu_\bi_\bd is ``root'', then the process has some of the powers of a superuser |
| 8475 | as well. |
| 8476 | |
| 8477 | N\bNA\bAM\bME\bE |
| 8478 | e\bex\bxe\bec\bcv\bve\be, e\bex\bxe\bec\bct\bt - execute a file |
| 8479 | |
| 8480 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 8481 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 8482 | |
| 8483 | _\bi_\bn_\bt |
| 8484 | e\bex\bxe\bec\bcv\bve\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b], _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); |
| 8485 | |
| 8486 | _\bi_\bn_\bt |
| 8487 | e\bex\bxe\bec\bct\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b], _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); |
| 8488 | |
| 8489 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 8490 | e\bex\bxe\bec\bcv\bve\be() transforms the calling process into a new process. The new |
| 8491 | process is constructed from an ordinary file, whose name is pointed to by |
| 8492 | _\bp_\ba_\bt_\bh, called the _\bn_\be_\bw _\bp_\br_\bo_\bc_\be_\bs_\bs _\bf_\bi_\bl_\be. This file is either an executable |
| 8493 | object file, or a file of data for an interpreter. An executable object |
| 8494 | file consists of an identifying header, followed by pages of data |
| 8495 | representing the initial program (text) and initialized data pages. |
| 8496 | Additional pages may be specified by the header to be initialized with |
| 8497 | zero data; see elf(5). |
| 8498 | |
| 8499 | An interpreter file begins with a line of the form: |
| 8500 | |
| 8501 | #\b#!\b! _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br [_\ba_\br_\bg] |
| 8502 | |
| 8503 | When an interpreter file is passed to e\bex\bxe\bec\bcv\bve\be() the system instead calls |
| 8504 | e\bex\bxe\bec\bcv\bve\be() with the specified _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br. If the optional _\ba_\br_\bg is |
| 8505 | specified, it becomes the first argument to the _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br, and the |
| 8506 | original _\bp_\ba_\bt_\bh becomes the second argument; otherwise, _\bp_\ba_\bt_\bh becomes the |
| 8507 | first argument. The original arguments are shifted over to become the |
| 8508 | subsequent arguments. The zeroth argument, normally the name of the file |
| 8509 | being executed, is left unchanged. |
| 8510 | |
| 8511 | The argument _\ba_\br_\bg_\bv is a pointer to a null-terminated array of character |
| 8512 | pointers to NUL-terminated character strings. These strings construct |
| 8513 | the argument list to be made available to the new process. At least one |
| 8514 | non-null argument must be present in the array; by custom, the first |
| 8515 | element should be the name of the executed program (for example, the last |
| 8516 | component of _\bp_\ba_\bt_\bh). |
| 8517 | |
| 8518 | The argument _\be_\bn_\bv_\bp is also a pointer to a null-terminated array of |
| 8519 | character pointers to NUL-terminated strings. A pointer to this array is |
| 8520 | normally stored in the global variable _\be_\bn_\bv_\bi_\br_\bo_\bn. These strings pass |
| 8521 | information to the new process that is not directly an argument to the |
| 8522 | command (see environ(7)). |
| 8523 | |
| 8524 | File descriptors open in the calling process image remain open in the new |
| 8525 | process image, except for those for which the close-on-exec flag is set |
| 8526 | (see close(2) and fcntl(2)). Descriptors that remain open are unaffected |
| 8527 | by e\bex\bxe\bec\bcv\bve\be(). In the case of a new setuid or setgid executable being |
| 8528 | executed, if file descriptors 0, 1, or 2 (representing stdin, stdout, and |
| 8529 | stderr) are currently unallocated, these descriptors will be opened to |
| 8530 | point to some system file like _\b/_\bd_\be_\bv_\b/_\bn_\bu_\bl_\bl. The intent is to ensure these |
| 8531 | descriptors are not unallocated, since many libraries make assumptions |
| 8532 | about the use of these 3 file descriptors. |
| 8533 | |
| 8534 | Signals set to be ignored in the calling process are set to be ignored in |
| 8535 | the new process. Signals which are set to be caught in the calling |
| 8536 | process image are set to default action in the new process image. |
| 8537 | Blocked signals remain blocked regardless of changes to the signal |
| 8538 | action. The signal stack is reset to be undefined (see sigaction(2) for |
| 8539 | more information). |
| 8540 | |
| 8541 | If the set-user-ID mode bit of the new process image file is set (see |
| 8542 | chmod(2)), the effective user ID of the new process image is set to the |
| 8543 | owner ID of the new process image file. If the set-group-ID mode bit of |
| 8544 | the new process image file is set, the effective group ID of the new |
| 8545 | process image is set to the group ID of the new process image file. (The |
| 8546 | effective group ID is the first element of the group list.) The real |
| 8547 | user ID, real group ID and other group IDs of the new process image |
| 8548 | remain the same as the calling process image. After any set-user-ID and |
| 8549 | set-group-ID processing, the effective user ID is recorded as the saved |
| 8550 | set-user-ID, and the effective group ID is recorded as the saved set- |
| 8551 | group-ID. These values may be used in changing the effective IDs later |
| 8552 | (see setuid(2)). The set-user-ID and set-group-ID bits have no effect if |
| 8553 | the new process image file is located on a file system mounted with the |
| 8554 | nosuid flag. The process will be started without the new permissions. |
| 8555 | |
| 8556 | The new process also inherits the following attributes from the calling |
| 8557 | process: |
| 8558 | |
| 8559 | process ID see getpid(2) |
| 8560 | parent process ID see getppid(2) |
| 8561 | process group ID see getpgrp(2) |
| 8562 | session ID see getsid(2) |
| 8563 | access groups see getgroups(2) |
| 8564 | working directory see chdir(2) |
| 8565 | root directory see chroot(2) |
| 8566 | control terminal see termios(4) |
| 8567 | resource usages see getrusage(2) |
| 8568 | interval timers see getitimer(2) (unless process image file is |
| 8569 | setuid or setgid, in which case all timers are |
| 8570 | disabled) |
| 8571 | resource limits see getrlimit(2) |
| 8572 | file mode mask see umask(2) |
| 8573 | signal mask see sigaction(2), sigsetmask(3) |
| 8574 | |
| 8575 | When a program is executed as a result of an e\bex\bxe\bec\bcv\bve\be() call, it is entered |
| 8576 | as follows: |
| 8577 | |
| 8578 | main(int argc, char **argv, char **envp) |
| 8579 | |
| 8580 | where _\ba_\br_\bg_\bc is the number of elements in _\ba_\br_\bg_\bv (the ``arg count'') and _\ba_\br_\bg_\bv |
| 8581 | points to the array of character pointers to the arguments themselves. |
| 8582 | |
| 8583 | The e\bex\bxe\bec\bct\bt() function is equivalent to e\bex\bxe\bec\bcv\bve\be() with the additional |
| 8584 | property that it executes the file with the process tracing facilities |
| 8585 | enabled (see ptrace(2)). |
| 8586 | |
| 8587 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 8588 | As the e\bex\bxe\bec\bcv\bve\be() function overlays the current process image with a new |
| 8589 | process image the successful call has no process to return to. If |
| 8590 | e\bex\bxe\bec\bcv\bve\be() does return to the calling process an error has occurred; the |
| 8591 | return value will be -1 and the global variable _\be_\br_\br_\bn_\bo is set to indicate |
| 8592 | the error. |
| 8593 | |
| 8594 | E\bER\bRR\bRO\bOR\bRS\bS |
| 8595 | e\bex\bxe\bec\bcv\bve\be() will fail and return to the calling process if: |
| 8596 | |
| 8597 | [ENOTDIR] A component of the path prefix is not a directory. |
| 8598 | |
| 8599 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 8600 | characters, or an entire pathname (including the |
| 8601 | terminating NUL) exceeded PATH_MAX bytes. |
| 8602 | |
| 8603 | [ENOENT] The new process file does not exist. |
| 8604 | |
| 8605 | [ELOOP] Too many symbolic links were encountered in |
| 8606 | translating the pathname. |
| 8607 | |
| 8608 | [EACCES] Search permission is denied for a component of the |
| 8609 | path prefix. |
| 8610 | |
| 8611 | [EACCES] The new process file is not an ordinary file. |
| 8612 | |
| 8613 | [EACCES] The new process file mode denies execute permission. |
| 8614 | |
| 8615 | [EACCES] The new process file is on a filesystem mounted with |
| 8616 | execution disabled (MNT_NOEXEC in <_\bs_\by_\bs_\b/_\bm_\bo_\bu_\bn_\bt_\b._\bh>). |
| 8617 | |
| 8618 | [ENOEXEC] The new process file has the appropriate access |
| 8619 | permission, but has an invalid magic number in its |
| 8620 | header. |
| 8621 | |
| 8622 | [ETXTBSY] The new process file is a pure procedure (shared text) |
| 8623 | file that is currently open for writing or reading by |
| 8624 | some process. |
| 8625 | |
| 8626 | [ENOMEM] The new process requires more virtual memory than is |
| 8627 | allowed by the imposed maximum (getrlimit(2)). |
| 8628 | |
| 8629 | [E2BIG] The number of bytes in the new process's argument list |
| 8630 | is larger than the system-imposed limit. The limit in |
| 8631 | the system as released is 262144 bytes (NCARGS in |
| 8632 | <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh>). |
| 8633 | |
| 8634 | [EFAULT] The new process file is not as long as indicated by |
| 8635 | the size values in its header. |
| 8636 | |
| 8637 | [EFAULT] _\bp_\ba_\bt_\bh, _\ba_\br_\bg_\bv, or _\be_\bn_\bv_\bp point to an illegal address. |
| 8638 | |
| 8639 | [EINVAL] _\ba_\br_\bg_\bv did not contain at least one element. |
| 8640 | |
| 8641 | [EIO] An I/O error occurred while reading from the file |
| 8642 | system. |
| 8643 | |
| 8644 | [ENFILE] During startup of an _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br, the system file |
| 8645 | table was found to be full. |
| 8646 | |
| 8647 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 8648 | _exit(2), fork(2), execl(3), exit(3), elf(5), environ(7) |
| 8649 | |
| 8650 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 8651 | The e\bex\bxe\bec\bcv\bve\be() function is expected to conform to IEEE Std 1003.1-2008 |
| 8652 | (``POSIX.1''). The e\bex\bxe\bec\bct\bt() function should not be used in portable |
| 8653 | applications. |
| 8654 | |
| 8655 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 8656 | The predecessor of these functions, the former e\bex\bxe\bec\bc() system call, first |
| 8657 | appeared in Version 1 AT&T UNIX. The e\bex\bxe\bec\bcv\bve\be() function first appeared in |
| 8658 | Version 7 AT&T UNIX. |
| 8659 | |
| 8660 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 8661 | If a program is _\bs_\be_\bt_\bu_\bi_\bd to a non-superuser, but is executed when the real |
| 8662 | _\bu_\bi_\bd is ``root'', then the process has some of the powers of a superuser |
| 8663 | as well. |
| 8664 | |
| 8665 | N\bNA\bAM\bME\bE |
| 8666 | a\bac\bcc\bce\bes\bss\bs, f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt - check access permissions of a file or pathname |
| 8667 | |
| 8668 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 8669 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 8670 | |
| 8671 | _\bi_\bn_\bt |
| 8672 | a\bac\bcc\bce\bes\bss\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\ba_\bm_\bo_\bd_\be); |
| 8673 | |
| 8674 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 8675 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 8676 | |
| 8677 | _\bi_\bn_\bt |
| 8678 | f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\ba_\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 8679 | |
| 8680 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 8681 | The a\bac\bcc\bce\bes\bss\bs() function checks the accessibility of the file named by _\bp_\ba_\bt_\bh |
| 8682 | for the access permissions indicated by _\ba_\bm_\bo_\bd_\be. The _\ba_\bm_\bo_\bd_\be argument is |
| 8683 | either the bitwise OR of one or more of the access permissions to be |
| 8684 | checked (R_OK for read permission, W_OK for write permission, and X_OK |
| 8685 | for execute/search permission) or the existence test, F_OK. All |
| 8686 | components of the pathname _\bp_\ba_\bt_\bh are checked for access permissions |
| 8687 | (including F_OK). |
| 8688 | |
| 8689 | The real user ID is used in place of the effective user ID and the real |
| 8690 | group access list (including the real group ID) is used in place of the |
| 8691 | effective ID for verifying permission. |
| 8692 | |
| 8693 | If the invoking process has superuser privileges, a\bac\bcc\bce\bes\bss\bs() will always |
| 8694 | indicate success for R_OK and W_OK, regardless of the actual file |
| 8695 | permission bits. Likewise, for X_OK, if the file has any of the execute |
| 8696 | bits set and _\bp_\ba_\bt_\bh is not a directory, a\bac\bcc\bce\bes\bss\bs() will indicate success. |
| 8697 | |
| 8698 | The f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() function is equivalent to a\bac\bcc\bce\bes\bss\bs() except that where _\bp_\ba_\bt_\bh |
| 8699 | specifies a relative path, the file whose accessibility is checked is |
| 8700 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 8701 | instead of the current working directory. |
| 8702 | |
| 8703 | If f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 8704 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 8705 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to a\bac\bcc\bce\bes\bss\bs(). |
| 8706 | |
| 8707 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 8708 | values: |
| 8709 | |
| 8710 | AT_EACCESS The checks for accessibility are performed using the |
| 8711 | effective user and group IDs instead of the real user |
| 8712 | and group IDs. |
| 8713 | |
| 8714 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 8715 | If _\bp_\ba_\bt_\bh cannot be found or if any of the desired access modes would not |
| 8716 | be granted, then a -1 value is returned; otherwise a 0 value is returned. |
| 8717 | |
| 8718 | E\bER\bRR\bRO\bOR\bRS\bS |
| 8719 | Access to the file is denied if: |
| 8720 | |
| 8721 | [ENOTDIR] A component of the path prefix is not a directory. |
| 8722 | |
| 8723 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 8724 | characters, or an entire pathname (including the |
| 8725 | terminating NUL) exceeded PATH_MAX bytes. |
| 8726 | |
| 8727 | [ENOENT] The named file does not exist. |
| 8728 | |
| 8729 | [ELOOP] Too many symbolic links were encountered in |
| 8730 | translating the pathname. |
| 8731 | |
| 8732 | [EROFS] Write access is requested for a file on a read-only |
| 8733 | file system. |
| 8734 | |
| 8735 | [ETXTBSY] Write access is requested for a pure procedure (shared |
| 8736 | text) file presently being executed. |
| 8737 | |
| 8738 | [EACCES] Permission bits of the file mode do not permit the |
| 8739 | requested access, or search permission is denied on a |
| 8740 | component of the path prefix. The owner of a file has |
| 8741 | permission checked with respect to the ``owner'' read, |
| 8742 | write, and execute mode bits, members of the file's |
| 8743 | group other than the owner have permission checked |
| 8744 | with respect to the ``group'' mode bits, and all |
| 8745 | others have permissions checked with respect to the |
| 8746 | ``other'' mode bits. |
| 8747 | |
| 8748 | [EPERM] Write access has been requested and the named file has |
| 8749 | its immutable flag set (see chflags(2)). |
| 8750 | |
| 8751 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 8752 | space. |
| 8753 | |
| 8754 | [EIO] An I/O error occurred while reading from or writing to |
| 8755 | the file system. |
| 8756 | |
| 8757 | [EINVAL] An invalid value was specified for _\ba_\bm_\bo_\bd_\be. |
| 8758 | |
| 8759 | Additionally, f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() will fail if: |
| 8760 | |
| 8761 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 8762 | AT_EACCESS. |
| 8763 | |
| 8764 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 8765 | argument is neither AT_FDCWD nor a valid file |
| 8766 | descriptor. |
| 8767 | |
| 8768 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 8769 | argument is a valid file descriptor but it does not |
| 8770 | reference a directory. |
| 8771 | |
| 8772 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 8773 | permission is denied for the directory which the _\bf_\bd |
| 8774 | file descriptor references. |
| 8775 | |
| 8776 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 8777 | chmod(2), stat(2) |
| 8778 | |
| 8779 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 8780 | The a\bac\bcc\bce\bes\bss\bs() and f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 8781 | (``POSIX.1''). |
| 8782 | |
| 8783 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 8784 | a\bac\bcc\bce\bes\bss\bs() first appeared as an internal kernel function in Version 1 AT&T |
| 8785 | UNIX and was reimplemented in C before the release of Version 4 AT&T |
| 8786 | UNIX. It was first promoted to a system call in the Programmer's |
| 8787 | Workbench (PWB/UNIX), which was later ported to Version 7 AT&T UNIX and |
| 8788 | 2BSD. |
| 8789 | |
| 8790 | The f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() function appeared in OpenBSD 5.0. |
| 8791 | |
| 8792 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 8793 | Ken Thompson first implemented the a\bac\bcc\bce\bes\bss\bs() kernel function in C. |
| 8794 | |
| 8795 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 8796 | a\bac\bcc\bce\bes\bss\bs() and f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() should never be used for actual access control. |
| 8797 | Doing so can result in a time of check vs. time of use security hole. |
| 8798 | |
| 8799 | N\bNA\bAM\bME\bE |
| 8800 | c\bch\bhd\bdi\bir\br, f\bfc\bch\bhd\bdi\bir\br - change current working directory |
| 8801 | |
| 8802 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 8803 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 8804 | |
| 8805 | _\bi_\bn_\bt |
| 8806 | c\bch\bhd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
| 8807 | |
| 8808 | _\bi_\bn_\bt |
| 8809 | f\bfc\bch\bhd\bdi\bir\br(_\bi_\bn_\bt _\bf_\bd); |
| 8810 | |
| 8811 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 8812 | The _\bp_\ba_\bt_\bh argument points to the pathname of a directory. The c\bch\bhd\bdi\bir\br() |
| 8813 | function causes the named directory to become the current working |
| 8814 | directory, that is, the starting point for path searches of pathnames not |
| 8815 | beginning with a slash (`/'). |
| 8816 | |
| 8817 | The f\bfc\bch\bhd\bdi\bir\br() function causes the directory referenced by _\bf_\bd to become the |
| 8818 | current working directory, the starting point for path searches of |
| 8819 | pathnames not beginning with a slash (`/'). |
| 8820 | |
| 8821 | In order for a directory to become the current directory, a process must |
| 8822 | have execute (search) access to the directory. |
| 8823 | |
| 8824 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 8825 | Upon successful completion, the value 0 is returned; otherwise the |
| 8826 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 8827 | error. |
| 8828 | |
| 8829 | E\bER\bRR\bRO\bOR\bRS\bS |
| 8830 | c\bch\bhd\bdi\bir\br() will fail and the current working directory will be unchanged if |
| 8831 | one or more of the following are true: |
| 8832 | |
| 8833 | [ENOTDIR] A component of the path prefix is not a directory. |
| 8834 | |
| 8835 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 8836 | characters, or an entire pathname (including the |
| 8837 | terminating NUL) exceeded PATH_MAX bytes. |
| 8838 | |
| 8839 | [ENOENT] The named directory does not exist. |
| 8840 | |
| 8841 | [ELOOP] Too many symbolic links were encountered in |
| 8842 | translating the pathname. |
| 8843 | |
| 8844 | [EACCES] Search permission is denied for any component of the |
| 8845 | pathname. |
| 8846 | |
| 8847 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 8848 | space. |
| 8849 | |
| 8850 | [EIO] An I/O error occurred while reading from the file |
| 8851 | system. |
| 8852 | |
| 8853 | f\bfc\bch\bhd\bdi\bir\br() will fail and the current working directory will be unchanged if |
| 8854 | one or more of the following are true: |
| 8855 | |
| 8856 | [EACCES] Search permission is denied for the directory |
| 8857 | referenced by the file descriptor. |
| 8858 | |
| 8859 | [ENOTDIR] The file descriptor does not reference a directory. |
| 8860 | |
| 8861 | [EBADF] The argument _\bf_\bd is not a valid file descriptor. |
| 8862 | |
| 8863 | [EIO] An I/O error occurred while reading from the file |
| 8864 | system. |
| 8865 | |
| 8866 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 8867 | chroot(2) |
| 8868 | |
| 8869 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 8870 | The c\bch\bhd\bdi\bir\br() and f\bfc\bch\bhd\bdi\bir\br() functions are expected to conform to IEEE Std |
| 8871 | 1003.1-2008 (``POSIX.1''). |
| 8872 | |
| 8873 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 8874 | The c\bch\bhd\bdi\bir\br() system call first appeared in Version 1 AT&T UNIX, and |
| 8875 | f\bfc\bch\bhd\bdi\bir\br() in 4.3BSD-Reno. |
| 8876 | |
| 8877 | N\bNA\bAM\bME\bE |
| 8878 | c\bch\bhf\bfl\bla\bag\bgs\bs, c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt, f\bfc\bch\bhf\bfl\bla\bag\bgs\bs - set file flags |
| 8879 | |
| 8880 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 8881 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 8882 | |
| 8883 | _\bi_\bn_\bt |
| 8884 | c\bch\bhf\bfl\bla\bag\bgs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 8885 | |
| 8886 | _\bi_\bn_\bt |
| 8887 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs(_\bi_\bn_\bt _\bf_\bd, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 8888 | |
| 8889 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 8890 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 8891 | |
| 8892 | _\bi_\bn_\bt |
| 8893 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\ba_\bt_\bf_\bl_\ba_\bg_\bs); |
| 8894 | |
| 8895 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 8896 | The file whose name is given by _\bp_\ba_\bt_\bh or referenced by the descriptor _\bf_\bd |
| 8897 | has its flags changed to _\bf_\bl_\ba_\bg_\bs. |
| 8898 | |
| 8899 | The flags are the bitwise OR of zero or more of the following values: |
| 8900 | |
| 8901 | UF_NODUMP Do not dump the file. |
| 8902 | UF_IMMUTABLE The file may not be changed. |
| 8903 | UF_APPEND The file may only be appended to. |
| 8904 | SF_ARCHIVED The file may be archived. |
| 8905 | SF_IMMUTABLE The file may not be changed. |
| 8906 | SF_APPEND The file may only be appended to. |
| 8907 | |
| 8908 | The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the |
| 8909 | owner of a file or the superuser. |
| 8910 | |
| 8911 | The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or |
| 8912 | unset by the superuser. They may be set at any time, but normally may |
| 8913 | only be unset when the system is in single-user mode. (See init(8) for |
| 8914 | details.) |
| 8915 | |
| 8916 | The c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except in the case |
| 8917 | where _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be |
| 8918 | changed is determined relative to the directory associated with the file |
| 8919 | descriptor _\bf_\bd instead of the current working directory. |
| 8920 | |
| 8921 | If c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 8922 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 8923 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to c\bch\bhf\bfl\bla\bag\bgs\bs(). |
| 8924 | |
| 8925 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 8926 | values: |
| 8927 | |
| 8928 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the flags |
| 8929 | of the symbolic link are changed. |
| 8930 | |
| 8931 | The f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except that the file |
| 8932 | whose flags are changed is specified by the file descriptor _\bf_\bd. |
| 8933 | |
| 8934 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 8935 | Upon successful completion, the value 0 is returned; otherwise the |
| 8936 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 8937 | error. |
| 8938 | |
| 8939 | E\bER\bRR\bRO\bOR\bRS\bS |
| 8940 | c\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
| 8941 | |
| 8942 | [ENOTDIR] A component of the path prefix is not a directory. |
| 8943 | |
| 8944 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 8945 | characters, or an entire pathname (including the |
| 8946 | terminating NUL) exceeded PATH_MAX bytes. |
| 8947 | |
| 8948 | [ENOENT] The named file does not exist. |
| 8949 | |
| 8950 | [EACCES] Search permission is denied for a component of the |
| 8951 | path prefix. |
| 8952 | |
| 8953 | [ELOOP] Too many symbolic links were encountered in |
| 8954 | translating the pathname. |
| 8955 | |
| 8956 | [EPERM] The effective user ID does not match the owner of the |
| 8957 | file and the effective user ID is not the superuser, |
| 8958 | or the effective user ID is not the superuser and at |
| 8959 | least one of the super-user-only flags for the named |
| 8960 | file would be changed. |
| 8961 | |
| 8962 | [EOPNOTSUPP] The named file resides on a file system that does not |
| 8963 | support file flags. |
| 8964 | |
| 8965 | [EROFS] The named file resides on a read-only file system. |
| 8966 | |
| 8967 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 8968 | space. |
| 8969 | |
| 8970 | [EIO] An I/O error occurred while reading from or writing to |
| 8971 | the file system. |
| 8972 | |
| 8973 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
| 8974 | |
| 8975 | [EINVAL] The descriptor references a block or character device |
| 8976 | and the effective user ID is not the superuser. |
| 8977 | |
| 8978 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
| 8979 | |
| 8980 | [EBADF] The descriptor is not valid. |
| 8981 | |
| 8982 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
| 8983 | |
| 8984 | [EINVAL] The descriptor references a block or character device |
| 8985 | and the effective user ID is not the superuser. |
| 8986 | |
| 8987 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
| 8988 | |
| 8989 | [EPERM] The effective user ID does not match the owner of the |
| 8990 | file and the effective user ID is not the superuser, |
| 8991 | or the effective user ID is not the superuser and at |
| 8992 | least one of the super-user-only flags for the named |
| 8993 | file would be changed. |
| 8994 | |
| 8995 | [EOPNOTSUPP] The named file resides on a file system that does not |
| 8996 | support file flags. |
| 8997 | |
| 8998 | [EROFS] The file resides on a read-only file system. |
| 8999 | |
| 9000 | [EIO] An I/O error occurred while reading from or writing to |
| 9001 | the file system. |
| 9002 | |
| 9003 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 9004 | chflags(1), init(8) |
| 9005 | |
| 9006 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 9007 | The c\bch\bhf\bfl\bla\bag\bgs\bs() and f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() functions first appeared in 4.4BSD. The |
| 9008 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function first appeared in FreeBSD 10.0. It was added to |
| 9009 | OpenBSD in OpenBSD 5.7. |
| 9010 | |
| 9011 | N\bNA\bAM\bME\bE |
| 9012 | c\bch\bhm\bmo\bod\bd, f\bfc\bch\bhm\bmo\bod\bda\bat\bt, f\bfc\bch\bhm\bmo\bod\bd - change mode of file |
| 9013 | |
| 9014 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9015 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 9016 | |
| 9017 | _\bi_\bn_\bt |
| 9018 | c\bch\bhm\bmo\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 9019 | |
| 9020 | _\bi_\bn_\bt |
| 9021 | f\bfc\bch\bhm\bmo\bod\bd(_\bi_\bn_\bt _\bf_\bd, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 9022 | |
| 9023 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 9024 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 9025 | |
| 9026 | _\bi_\bn_\bt |
| 9027 | f\bfc\bch\bhm\bmo\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 9028 | |
| 9029 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 9030 | The c\bch\bhm\bmo\bod\bd() function sets the file permission bits of the file specified |
| 9031 | by the pathname _\bp_\ba_\bt_\bh to _\bm_\bo_\bd_\be. c\bch\bhm\bmo\bod\bd() verifies that the process owner |
| 9032 | (user) either owns the specified file or is the superuser. |
| 9033 | |
| 9034 | The _\bm_\bo_\bd_\be argument is the bitwise OR of zero or more of the permission bit |
| 9035 | masks from the following list: |
| 9036 | |
| 9037 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 9038 | #define S_IRUSR 0000400 /* R for owner */ |
| 9039 | #define S_IWUSR 0000200 /* W for owner */ |
| 9040 | #define S_IXUSR 0000100 /* X for owner */ |
| 9041 | |
| 9042 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 9043 | #define S_IRGRP 0000040 /* R for group */ |
| 9044 | #define S_IWGRP 0000020 /* W for group */ |
| 9045 | #define S_IXGRP 0000010 /* X for group */ |
| 9046 | |
| 9047 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 9048 | #define S_IROTH 0000004 /* R for other */ |
| 9049 | #define S_IWOTH 0000002 /* W for other */ |
| 9050 | #define S_IXOTH 0000001 /* X for other */ |
| 9051 | |
| 9052 | #define S_ISUID 0004000 /* set user id on execution */ |
| 9053 | #define S_ISGID 0002000 /* set group id on execution */ |
| 9054 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 9055 | |
| 9056 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a file, it is ignored. |
| 9057 | |
| 9058 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a directory, an unprivileged |
| 9059 | user may not delete or rename files of other users in that directory. |
| 9060 | The sticky bit may be set by any user on a directory which the user owns |
| 9061 | or has appropriate permissions. For more details of the properties of |
| 9062 | the sticky bit, see sticky(8). |
| 9063 | |
| 9064 | Writing or changing the owner of a file turns off the set-user-ID and |
| 9065 | set-group-ID bits unless the user is the superuser. This makes the |
| 9066 | system somewhat more secure by protecting set-user-ID (set-group-ID) |
| 9067 | files from remaining set-user-ID (set-group-ID) if they are modified, at |
| 9068 | the expense of a degree of compatibility. |
| 9069 | |
| 9070 | The f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function is equivalent to c\bch\bhm\bmo\bod\bd() except in the case where |
| 9071 | _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be changed is |
| 9072 | determined relative to the directory associated with the file descriptor |
| 9073 | _\bf_\bd instead of the current working directory. |
| 9074 | |
| 9075 | If f\bfc\bch\bhm\bmo\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 9076 | in the _\bf_\bd parameter, the current working directory is used. If _\bf_\bl_\ba_\bg is |
| 9077 | also zero, the behavior is identical to a call to c\bch\bhm\bmo\bod\bd(). |
| 9078 | |
| 9079 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 9080 | values: |
| 9081 | |
| 9082 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the mode |
| 9083 | of the symbolic link is changed. |
| 9084 | |
| 9085 | The f\bfc\bch\bhm\bmo\bod\bd() function is equivalent to c\bch\bhm\bmo\bod\bd() except that the file whose |
| 9086 | permissions are changed is specified by the file descriptor _\bf_\bd. |
| 9087 | |
| 9088 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 9089 | Upon successful completion, the value 0 is returned; otherwise the |
| 9090 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 9091 | error. |
| 9092 | |
| 9093 | E\bER\bRR\bRO\bOR\bRS\bS |
| 9094 | The c\bch\bhm\bmo\bod\bd() and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions will fail and the file mode will be |
| 9095 | unchanged if: |
| 9096 | |
| 9097 | [ENOTDIR] A component of the path prefix is not a directory. |
| 9098 | |
| 9099 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 9100 | characters, or an entire pathname (including the |
| 9101 | terminating NUL) exceeded PATH_MAX bytes. |
| 9102 | |
| 9103 | [ENOENT] The named file does not exist. |
| 9104 | |
| 9105 | [EACCES] Search permission is denied for a component of the |
| 9106 | path prefix. |
| 9107 | |
| 9108 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
| 9109 | described above. |
| 9110 | |
| 9111 | [ELOOP] Too many symbolic links were encountered in |
| 9112 | translating the pathname. |
| 9113 | |
| 9114 | [EPERM] The effective user ID does not match the owner of the |
| 9115 | file and the effective user ID is not the superuser. |
| 9116 | |
| 9117 | [EROFS] The named file resides on a read-only file system. |
| 9118 | |
| 9119 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 9120 | space. |
| 9121 | |
| 9122 | [EIO] An I/O error occurred while reading from or writing to |
| 9123 | the file system. |
| 9124 | |
| 9125 | Additionally, the f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function will fail if: |
| 9126 | |
| 9127 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 9128 | AT_SYMLINK_NOFOLLOW. |
| 9129 | |
| 9130 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 9131 | argument is neither AT_FDCWD nor a valid file |
| 9132 | descriptor. |
| 9133 | |
| 9134 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 9135 | argument is a valid file descriptor but it does not |
| 9136 | reference a directory. |
| 9137 | |
| 9138 | [EOPNOTSUPP] The _\bf_\bl_\ba_\bg argument specifies AT_SYMLINK_NOFOLLOW on a |
| 9139 | symbolic link and the file system does not support |
| 9140 | that operation. |
| 9141 | |
| 9142 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 9143 | permission is denied for the directory which the _\bf_\bd |
| 9144 | file descriptor references. |
| 9145 | |
| 9146 | f\bfc\bch\bhm\bmo\bod\bd() will fail and the file mode will be unchanged if: |
| 9147 | |
| 9148 | [EBADF] The descriptor is not valid. |
| 9149 | |
| 9150 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
| 9151 | |
| 9152 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
| 9153 | described above. |
| 9154 | |
| 9155 | [EPERM] The effective user ID does not match the owner of the |
| 9156 | file and the effective user ID is not the superuser. |
| 9157 | |
| 9158 | [EROFS] The file resides on a read-only file system. |
| 9159 | |
| 9160 | [EIO] An I/O error occurred while reading from or writing to |
| 9161 | the file system. |
| 9162 | |
| 9163 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 9164 | chmod(1), chown(2), open(2), stat(2), sticky(8) |
| 9165 | |
| 9166 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 9167 | The c\bch\bhm\bmo\bod\bd(), f\bfc\bch\bhm\bmo\bod\bd(), and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions are expected to conform |
| 9168 | to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 9169 | |
| 9170 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 9171 | The c\bch\bhm\bmo\bod\bd() system call first appeared in Version 1 AT&T UNIX; f\bfc\bch\bhm\bmo\bod\bd() |
| 9172 | in 4.1cBSD; and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
| 9173 | |
| 9174 | N\bNA\bAM\bME\bE |
| 9175 | c\bch\bhm\bmo\bod\bd, f\bfc\bch\bhm\bmo\bod\bda\bat\bt, f\bfc\bch\bhm\bmo\bod\bd - change mode of file |
| 9176 | |
| 9177 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9178 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 9179 | |
| 9180 | _\bi_\bn_\bt |
| 9181 | c\bch\bhm\bmo\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 9182 | |
| 9183 | _\bi_\bn_\bt |
| 9184 | f\bfc\bch\bhm\bmo\bod\bd(_\bi_\bn_\bt _\bf_\bd, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 9185 | |
| 9186 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 9187 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 9188 | |
| 9189 | _\bi_\bn_\bt |
| 9190 | f\bfc\bch\bhm\bmo\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 9191 | |
| 9192 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 9193 | The c\bch\bhm\bmo\bod\bd() function sets the file permission bits of the file specified |
| 9194 | by the pathname _\bp_\ba_\bt_\bh to _\bm_\bo_\bd_\be. c\bch\bhm\bmo\bod\bd() verifies that the process owner |
| 9195 | (user) either owns the specified file or is the superuser. |
| 9196 | |
| 9197 | The _\bm_\bo_\bd_\be argument is the bitwise OR of zero or more of the permission bit |
| 9198 | masks from the following list: |
| 9199 | |
| 9200 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 9201 | #define S_IRUSR 0000400 /* R for owner */ |
| 9202 | #define S_IWUSR 0000200 /* W for owner */ |
| 9203 | #define S_IXUSR 0000100 /* X for owner */ |
| 9204 | |
| 9205 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 9206 | #define S_IRGRP 0000040 /* R for group */ |
| 9207 | #define S_IWGRP 0000020 /* W for group */ |
| 9208 | #define S_IXGRP 0000010 /* X for group */ |
| 9209 | |
| 9210 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 9211 | #define S_IROTH 0000004 /* R for other */ |
| 9212 | #define S_IWOTH 0000002 /* W for other */ |
| 9213 | #define S_IXOTH 0000001 /* X for other */ |
| 9214 | |
| 9215 | #define S_ISUID 0004000 /* set user id on execution */ |
| 9216 | #define S_ISGID 0002000 /* set group id on execution */ |
| 9217 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 9218 | |
| 9219 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a file, it is ignored. |
| 9220 | |
| 9221 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a directory, an unprivileged |
| 9222 | user may not delete or rename files of other users in that directory. |
| 9223 | The sticky bit may be set by any user on a directory which the user owns |
| 9224 | or has appropriate permissions. For more details of the properties of |
| 9225 | the sticky bit, see sticky(8). |
| 9226 | |
| 9227 | Writing or changing the owner of a file turns off the set-user-ID and |
| 9228 | set-group-ID bits unless the user is the superuser. This makes the |
| 9229 | system somewhat more secure by protecting set-user-ID (set-group-ID) |
| 9230 | files from remaining set-user-ID (set-group-ID) if they are modified, at |
| 9231 | the expense of a degree of compatibility. |
| 9232 | |
| 9233 | The f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function is equivalent to c\bch\bhm\bmo\bod\bd() except in the case where |
| 9234 | _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be changed is |
| 9235 | determined relative to the directory associated with the file descriptor |
| 9236 | _\bf_\bd instead of the current working directory. |
| 9237 | |
| 9238 | If f\bfc\bch\bhm\bmo\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 9239 | in the _\bf_\bd parameter, the current working directory is used. If _\bf_\bl_\ba_\bg is |
| 9240 | also zero, the behavior is identical to a call to c\bch\bhm\bmo\bod\bd(). |
| 9241 | |
| 9242 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 9243 | values: |
| 9244 | |
| 9245 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the mode |
| 9246 | of the symbolic link is changed. |
| 9247 | |
| 9248 | The f\bfc\bch\bhm\bmo\bod\bd() function is equivalent to c\bch\bhm\bmo\bod\bd() except that the file whose |
| 9249 | permissions are changed is specified by the file descriptor _\bf_\bd. |
| 9250 | |
| 9251 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 9252 | Upon successful completion, the value 0 is returned; otherwise the |
| 9253 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 9254 | error. |
| 9255 | |
| 9256 | E\bER\bRR\bRO\bOR\bRS\bS |
| 9257 | The c\bch\bhm\bmo\bod\bd() and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions will fail and the file mode will be |
| 9258 | unchanged if: |
| 9259 | |
| 9260 | [ENOTDIR] A component of the path prefix is not a directory. |
| 9261 | |
| 9262 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 9263 | characters, or an entire pathname (including the |
| 9264 | terminating NUL) exceeded PATH_MAX bytes. |
| 9265 | |
| 9266 | [ENOENT] The named file does not exist. |
| 9267 | |
| 9268 | [EACCES] Search permission is denied for a component of the |
| 9269 | path prefix. |
| 9270 | |
| 9271 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
| 9272 | described above. |
| 9273 | |
| 9274 | [ELOOP] Too many symbolic links were encountered in |
| 9275 | translating the pathname. |
| 9276 | |
| 9277 | [EPERM] The effective user ID does not match the owner of the |
| 9278 | file and the effective user ID is not the superuser. |
| 9279 | |
| 9280 | [EROFS] The named file resides on a read-only file system. |
| 9281 | |
| 9282 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 9283 | space. |
| 9284 | |
| 9285 | [EIO] An I/O error occurred while reading from or writing to |
| 9286 | the file system. |
| 9287 | |
| 9288 | Additionally, the f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function will fail if: |
| 9289 | |
| 9290 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 9291 | AT_SYMLINK_NOFOLLOW. |
| 9292 | |
| 9293 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 9294 | argument is neither AT_FDCWD nor a valid file |
| 9295 | descriptor. |
| 9296 | |
| 9297 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 9298 | argument is a valid file descriptor but it does not |
| 9299 | reference a directory. |
| 9300 | |
| 9301 | [EOPNOTSUPP] The _\bf_\bl_\ba_\bg argument specifies AT_SYMLINK_NOFOLLOW on a |
| 9302 | symbolic link and the file system does not support |
| 9303 | that operation. |
| 9304 | |
| 9305 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 9306 | permission is denied for the directory which the _\bf_\bd |
| 9307 | file descriptor references. |
| 9308 | |
| 9309 | f\bfc\bch\bhm\bmo\bod\bd() will fail and the file mode will be unchanged if: |
| 9310 | |
| 9311 | [EBADF] The descriptor is not valid. |
| 9312 | |
| 9313 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
| 9314 | |
| 9315 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
| 9316 | described above. |
| 9317 | |
| 9318 | [EPERM] The effective user ID does not match the owner of the |
| 9319 | file and the effective user ID is not the superuser. |
| 9320 | |
| 9321 | [EROFS] The file resides on a read-only file system. |
| 9322 | |
| 9323 | [EIO] An I/O error occurred while reading from or writing to |
| 9324 | the file system. |
| 9325 | |
| 9326 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 9327 | chmod(1), chown(2), open(2), stat(2), sticky(8) |
| 9328 | |
| 9329 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 9330 | The c\bch\bhm\bmo\bod\bd(), f\bfc\bch\bhm\bmo\bod\bd(), and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions are expected to conform |
| 9331 | to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 9332 | |
| 9333 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 9334 | The c\bch\bhm\bmo\bod\bd() system call first appeared in Version 1 AT&T UNIX; f\bfc\bch\bhm\bmo\bod\bd() |
| 9335 | in 4.1cBSD; and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
| 9336 | |
| 9337 | N\bNA\bAM\bME\bE |
| 9338 | c\bch\bho\bow\bwn\bn, l\blc\bch\bho\bow\bwn\bn, f\bfc\bch\bho\bow\bwn\bna\bat\bt, f\bfc\bch\bho\bow\bwn\bn - change owner and group of a file or |
| 9339 | link |
| 9340 | |
| 9341 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9342 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 9343 | |
| 9344 | _\bi_\bn_\bt |
| 9345 | c\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 9346 | |
| 9347 | _\bi_\bn_\bt |
| 9348 | l\blc\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 9349 | |
| 9350 | _\bi_\bn_\bt |
| 9351 | f\bfc\bch\bho\bow\bwn\bn(_\bi_\bn_\bt _\bf_\bd, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 9352 | |
| 9353 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 9354 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 9355 | |
| 9356 | _\bi_\bn_\bt |
| 9357 | f\bfc\bch\bho\bow\bwn\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 9358 | |
| 9359 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 9360 | The owner ID and group ID of the file (or link) named by _\bp_\ba_\bt_\bh or |
| 9361 | referenced by _\bf_\bd is changed as specified by the arguments _\bo_\bw_\bn_\be_\br and |
| 9362 | _\bg_\br_\bo_\bu_\bp. The owner of a file may change the _\bg_\br_\bo_\bu_\bp to a group of which he |
| 9363 | or she is a member, but the change _\bo_\bw_\bn_\be_\br capability is restricted to the |
| 9364 | superuser. |
| 9365 | |
| 9366 | By default, c\bch\bho\bow\bwn\bn() clears the set-user-ID and set-group-ID bits on the |
| 9367 | file to prevent accidental or mischievous creation of set-user-ID and |
| 9368 | set-group-ID programs. This behaviour can be overridden by setting the |
| 9369 | sysctl(8) variable _\bf_\bs_\b._\bp_\bo_\bs_\bi_\bx_\b._\bs_\be_\bt_\bu_\bi_\bd to zero. |
| 9370 | |
| 9371 | l\blc\bch\bho\bow\bwn\bn() operates similarly to how c\bch\bho\bow\bwn\bn() operated on older systems, and |
| 9372 | does not follow symbolic links. It allows the owner and group of a |
| 9373 | symbolic link to be set. |
| 9374 | |
| 9375 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() function is equivalent to either the c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn() |
| 9376 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 9377 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose ownership is changed is |
| 9378 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 9379 | instead of the current working directory. |
| 9380 | |
| 9381 | If f\bfc\bch\bho\bow\bwn\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 9382 | in the _\bf_\bd parameter, the current working directory is used and the |
| 9383 | behavior is identical to a call to c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn(), depending on |
| 9384 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 9385 | |
| 9386 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 9387 | values: |
| 9388 | |
| 9389 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
| 9390 | ownership of the symbolic link is changed. |
| 9391 | |
| 9392 | f\bfc\bch\bho\bow\bwn\bn() is particularly useful when used in conjunction with the file |
| 9393 | locking primitives (see flock(2)). |
| 9394 | |
| 9395 | One of the owner or group IDs may be left unchanged by specifying it as |
| 9396 | -1. |
| 9397 | |
| 9398 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 9399 | Upon successful completion, the value 0 is returned; otherwise the |
| 9400 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 9401 | error. |
| 9402 | |
| 9403 | E\bER\bRR\bRO\bOR\bRS\bS |
| 9404 | c\bch\bho\bow\bwn\bn(), l\blc\bch\bho\bow\bwn\bn(), and f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail and the file or link will be |
| 9405 | unchanged if: |
| 9406 | |
| 9407 | [ENOTDIR] A component of the path prefix is not a directory. |
| 9408 | |
| 9409 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 9410 | characters, or an entire pathname (including the |
| 9411 | terminating NUL) exceeded PATH_MAX bytes. |
| 9412 | |
| 9413 | [ENOENT] The named file does not exist. |
| 9414 | |
| 9415 | [EACCES] Search permission is denied for a component of the |
| 9416 | path prefix. |
| 9417 | |
| 9418 | [ELOOP] Too many symbolic links were encountered in |
| 9419 | translating the pathname. |
| 9420 | |
| 9421 | [EPERM] The effective user ID is not the superuser. |
| 9422 | |
| 9423 | [EROFS] The named file resides on a read-only file system. |
| 9424 | |
| 9425 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 9426 | space. |
| 9427 | |
| 9428 | [EIO] An I/O error occurred while reading from or writing to |
| 9429 | the file system. |
| 9430 | |
| 9431 | Additionally, f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail if: |
| 9432 | |
| 9433 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 9434 | AT_SYMLINK_NOFOLLOW. |
| 9435 | |
| 9436 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 9437 | argument is neither AT_FDCWD nor a valid file |
| 9438 | descriptor. |
| 9439 | |
| 9440 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 9441 | argument is a valid file descriptor but it does not |
| 9442 | reference a directory. |
| 9443 | |
| 9444 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 9445 | permission is denied for the directory which the _\bf_\bd |
| 9446 | file descriptor references. |
| 9447 | |
| 9448 | f\bfc\bch\bho\bow\bwn\bn() will fail if: |
| 9449 | |
| 9450 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
| 9451 | |
| 9452 | [EINVAL] _\bf_\bd refers to a socket, not a file. |
| 9453 | |
| 9454 | [EPERM] The effective user ID is not the superuser. |
| 9455 | |
| 9456 | [EROFS] The named file resides on a read-only file system. |
| 9457 | |
| 9458 | [EIO] An I/O error occurred while reading from or writing to |
| 9459 | the file system. |
| 9460 | |
| 9461 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 9462 | chgrp(1), chmod(2), flock(2), chown(8) |
| 9463 | |
| 9464 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 9465 | The c\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), and l\blc\bch\bho\bow\bwn\bn() functions are expected to |
| 9466 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 9467 | |
| 9468 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 9469 | The c\bch\bho\bow\bwn\bn() system call first appeared in Version 1 AT&T UNIX. Since |
| 9470 | Version 6 AT&T UNIX it supports changing the group as well, and in |
| 9471 | Version 7 AT&T UNIX _\bg_\br_\bo_\bu_\bp was made a separate argument. |
| 9472 | |
| 9473 | The f\bfc\bch\bho\bow\bwn\bn() system call first appeared in 4.1cBSD. |
| 9474 | |
| 9475 | The c\bch\bho\bow\bwn\bn() and f\bfc\bch\bho\bow\bwn\bn() system calls were changed to follow symbolic |
| 9476 | links in 4.4BSD; therefore, and for compatibility with AT&T System V |
| 9477 | Release 4 UNIX, the l\blc\bch\bho\bow\bwn\bn() system call was added to OpenBSD 2.1. |
| 9478 | |
| 9479 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() system call has been available since OpenBSD 5.0. |
| 9480 | |
| 9481 | N\bNA\bAM\bME\bE |
| 9482 | c\bch\bho\bow\bwn\bn, l\blc\bch\bho\bow\bwn\bn, f\bfc\bch\bho\bow\bwn\bna\bat\bt, f\bfc\bch\bho\bow\bwn\bn - change owner and group of a file or |
| 9483 | link |
| 9484 | |
| 9485 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9486 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 9487 | |
| 9488 | _\bi_\bn_\bt |
| 9489 | c\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 9490 | |
| 9491 | _\bi_\bn_\bt |
| 9492 | l\blc\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 9493 | |
| 9494 | _\bi_\bn_\bt |
| 9495 | f\bfc\bch\bho\bow\bwn\bn(_\bi_\bn_\bt _\bf_\bd, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 9496 | |
| 9497 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 9498 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 9499 | |
| 9500 | _\bi_\bn_\bt |
| 9501 | f\bfc\bch\bho\bow\bwn\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 9502 | |
| 9503 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 9504 | The owner ID and group ID of the file (or link) named by _\bp_\ba_\bt_\bh or |
| 9505 | referenced by _\bf_\bd is changed as specified by the arguments _\bo_\bw_\bn_\be_\br and |
| 9506 | _\bg_\br_\bo_\bu_\bp. The owner of a file may change the _\bg_\br_\bo_\bu_\bp to a group of which he |
| 9507 | or she is a member, but the change _\bo_\bw_\bn_\be_\br capability is restricted to the |
| 9508 | superuser. |
| 9509 | |
| 9510 | By default, c\bch\bho\bow\bwn\bn() clears the set-user-ID and set-group-ID bits on the |
| 9511 | file to prevent accidental or mischievous creation of set-user-ID and |
| 9512 | set-group-ID programs. This behaviour can be overridden by setting the |
| 9513 | sysctl(8) variable _\bf_\bs_\b._\bp_\bo_\bs_\bi_\bx_\b._\bs_\be_\bt_\bu_\bi_\bd to zero. |
| 9514 | |
| 9515 | l\blc\bch\bho\bow\bwn\bn() operates similarly to how c\bch\bho\bow\bwn\bn() operated on older systems, and |
| 9516 | does not follow symbolic links. It allows the owner and group of a |
| 9517 | symbolic link to be set. |
| 9518 | |
| 9519 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() function is equivalent to either the c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn() |
| 9520 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 9521 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose ownership is changed is |
| 9522 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 9523 | instead of the current working directory. |
| 9524 | |
| 9525 | If f\bfc\bch\bho\bow\bwn\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 9526 | in the _\bf_\bd parameter, the current working directory is used and the |
| 9527 | behavior is identical to a call to c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn(), depending on |
| 9528 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 9529 | |
| 9530 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 9531 | values: |
| 9532 | |
| 9533 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
| 9534 | ownership of the symbolic link is changed. |
| 9535 | |
| 9536 | f\bfc\bch\bho\bow\bwn\bn() is particularly useful when used in conjunction with the file |
| 9537 | locking primitives (see flock(2)). |
| 9538 | |
| 9539 | One of the owner or group IDs may be left unchanged by specifying it as |
| 9540 | -1. |
| 9541 | |
| 9542 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 9543 | Upon successful completion, the value 0 is returned; otherwise the |
| 9544 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 9545 | error. |
| 9546 | |
| 9547 | E\bER\bRR\bRO\bOR\bRS\bS |
| 9548 | c\bch\bho\bow\bwn\bn(), l\blc\bch\bho\bow\bwn\bn(), and f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail and the file or link will be |
| 9549 | unchanged if: |
| 9550 | |
| 9551 | [ENOTDIR] A component of the path prefix is not a directory. |
| 9552 | |
| 9553 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 9554 | characters, or an entire pathname (including the |
| 9555 | terminating NUL) exceeded PATH_MAX bytes. |
| 9556 | |
| 9557 | [ENOENT] The named file does not exist. |
| 9558 | |
| 9559 | [EACCES] Search permission is denied for a component of the |
| 9560 | path prefix. |
| 9561 | |
| 9562 | [ELOOP] Too many symbolic links were encountered in |
| 9563 | translating the pathname. |
| 9564 | |
| 9565 | [EPERM] The effective user ID is not the superuser. |
| 9566 | |
| 9567 | [EROFS] The named file resides on a read-only file system. |
| 9568 | |
| 9569 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 9570 | space. |
| 9571 | |
| 9572 | [EIO] An I/O error occurred while reading from or writing to |
| 9573 | the file system. |
| 9574 | |
| 9575 | Additionally, f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail if: |
| 9576 | |
| 9577 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 9578 | AT_SYMLINK_NOFOLLOW. |
| 9579 | |
| 9580 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 9581 | argument is neither AT_FDCWD nor a valid file |
| 9582 | descriptor. |
| 9583 | |
| 9584 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 9585 | argument is a valid file descriptor but it does not |
| 9586 | reference a directory. |
| 9587 | |
| 9588 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 9589 | permission is denied for the directory which the _\bf_\bd |
| 9590 | file descriptor references. |
| 9591 | |
| 9592 | f\bfc\bch\bho\bow\bwn\bn() will fail if: |
| 9593 | |
| 9594 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
| 9595 | |
| 9596 | [EINVAL] _\bf_\bd refers to a socket, not a file. |
| 9597 | |
| 9598 | [EPERM] The effective user ID is not the superuser. |
| 9599 | |
| 9600 | [EROFS] The named file resides on a read-only file system. |
| 9601 | |
| 9602 | [EIO] An I/O error occurred while reading from or writing to |
| 9603 | the file system. |
| 9604 | |
| 9605 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 9606 | chgrp(1), chmod(2), flock(2), chown(8) |
| 9607 | |
| 9608 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 9609 | The c\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), and l\blc\bch\bho\bow\bwn\bn() functions are expected to |
| 9610 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 9611 | |
| 9612 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 9613 | The c\bch\bho\bow\bwn\bn() system call first appeared in Version 1 AT&T UNIX. Since |
| 9614 | Version 6 AT&T UNIX it supports changing the group as well, and in |
| 9615 | Version 7 AT&T UNIX _\bg_\br_\bo_\bu_\bp was made a separate argument. |
| 9616 | |
| 9617 | The f\bfc\bch\bho\bow\bwn\bn() system call first appeared in 4.1cBSD. |
| 9618 | |
| 9619 | The c\bch\bho\bow\bwn\bn() and f\bfc\bch\bho\bow\bwn\bn() system calls were changed to follow symbolic |
| 9620 | links in 4.4BSD; therefore, and for compatibility with AT&T System V |
| 9621 | Release 4 UNIX, the l\blc\bch\bho\bow\bwn\bn() system call was added to OpenBSD 2.1. |
| 9622 | |
| 9623 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() system call has been available since OpenBSD 5.0. |
| 9624 | |
| 9625 | N\bNA\bAM\bME\bE |
| 9626 | f\bfc\bcn\bnt\btl\bl - file control |
| 9627 | |
| 9628 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9629 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 9630 | |
| 9631 | _\bi_\bn_\bt |
| 9632 | f\bfc\bcn\bnt\btl\bl(_\bi_\bn_\bt _\bf_\bd, _\bi_\bn_\bt _\bc_\bm_\bd, _\b._\b._\b.); |
| 9633 | |
| 9634 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 9635 | The f\bfc\bcn\bnt\btl\bl() provides control over the properties of a file that is |
| 9636 | already open. The argument _\bf_\bd is a descriptor to be operated on by _\bc_\bm_\bd |
| 9637 | as described below. The third parameter is called _\ba_\br_\bg and is technically |
| 9638 | a pointer to _\bv_\bo_\bi_\bd, but is interpreted as an int by some commands, a |
| 9639 | pointer to a struct flock by others (see below), and ignored by the rest. |
| 9640 | |
| 9641 | The commands are: |
| 9642 | |
| 9643 | F_DUPFD Return a new descriptor as follows: |
| 9644 | |
| 9645 | +\b+\bo\bo Lowest numbered available descriptor greater than or |
| 9646 | equal to _\ba_\br_\bg (interpreted as an int). |
| 9647 | +\b+\bo\bo Same object references as the original descriptor. |
| 9648 | +\b+\bo\bo New descriptor shares the same file offset if the |
| 9649 | object was a file. |
| 9650 | +\b+\bo\bo Same access mode (read, write or read/write). |
| 9651 | +\b+\bo\bo Same file status flags (i.e., both file descriptors |
| 9652 | share the same file status flags). |
| 9653 | +\b+\bo\bo The close-on-exec flag associated with the new file |
| 9654 | descriptor is set to remain open across execve(2) |
| 9655 | calls. |
| 9656 | |
| 9657 | F_DUPFD_CLOEXEC Like F_DUPFD, but the FD_CLOEXEC flag associated with |
| 9658 | the new file descriptor is set, so the file descriptor |
| 9659 | is closed when execve(2) is called. |
| 9660 | |
| 9661 | F_GETFD Get the close-on-exec flag associated with the file |
| 9662 | descriptor _\bf_\bd as FD_CLOEXEC. If the returned value |
| 9663 | ANDed with FD_CLOEXEC is 0, the file will remain open |
| 9664 | across e\bex\bxe\bec\bc(), otherwise the file will be closed upon |
| 9665 | execution of e\bex\bxe\bec\bc() (_\ba_\br_\bg is ignored). |
| 9666 | |
| 9667 | F_SETFD Set the close-on-exec flag associated with _\bf_\bd to _\ba_\br_\bg, |
| 9668 | where _\ba_\br_\bg (interpreted as an int) is either 0 or |
| 9669 | FD_CLOEXEC, as described above. |
| 9670 | |
| 9671 | F_GETFL Get file status flags associated with the file |
| 9672 | descriptor _\bf_\bd, as described below (_\ba_\br_\bg is ignored). |
| 9673 | |
| 9674 | F_SETFL Set file status flags associated with the file |
| 9675 | descriptor _\bf_\bd to _\ba_\br_\bg (interpreted as an int). |
| 9676 | |
| 9677 | F_GETOWN Get the process ID or process group currently receiving |
| 9678 | SIGIO and SIGURG signals; process groups are returned as |
| 9679 | negative values (_\ba_\br_\bg is ignored). |
| 9680 | |
| 9681 | F_SETOWN Set the process or process group to receive SIGIO and |
| 9682 | SIGURG signals; process groups are specified by |
| 9683 | supplying _\ba_\br_\bg (interpreted as an int) as negative, |
| 9684 | otherwise _\ba_\br_\bg is taken as a process ID. |
| 9685 | |
| 9686 | The flags for the F_GETFL and F_SETFL commands are as follows: |
| 9687 | |
| 9688 | O_NONBLOCK Non-blocking I/O; if no data is available to a read(2) call, |
| 9689 | or if a write(2) operation would block, the read or write |
| 9690 | call returns -1 with the error EAGAIN. |
| 9691 | |
| 9692 | O_APPEND Force each write to append at the end of file; corresponds |
| 9693 | to the O_APPEND flag of open(2). |
| 9694 | |
| 9695 | O_ASYNC Enable the SIGIO signal to be sent to the process group when |
| 9696 | I/O is possible, e.g., upon availability of data to be read. |
| 9697 | |
| 9698 | O_SYNC Cause writes to be synchronous. Data will be written to the |
| 9699 | physical device instead of just being stored in the buffer |
| 9700 | cache; corresponds to the O_SYNC flag of open(2). |
| 9701 | |
| 9702 | Several commands are available for doing advisory file locking; they all |
| 9703 | operate on the following structure: |
| 9704 | |
| 9705 | struct flock { |
| 9706 | off_t l_start; /* starting offset */ |
| 9707 | off_t l_len; /* len = 0 means until end of file */ |
| 9708 | pid_t l_pid; /* lock owner */ |
| 9709 | short l_type; /* lock type: read/write, etc. */ |
| 9710 | short l_whence; /* type of l_start */ |
| 9711 | }; |
| 9712 | |
| 9713 | The commands available for advisory record locking are as follows: |
| 9714 | |
| 9715 | F_GETLK Get the first lock that blocks the lock description pointed to |
| 9716 | by the third argument, _\ba_\br_\bg, taken as a pointer to a _\bs_\bt_\br_\bu_\bc_\bt |
| 9717 | _\bf_\bl_\bo_\bc_\bk (see above). The information retrieved overwrites the |
| 9718 | information passed to f\bfc\bcn\bnt\btl\bl() in the _\bf_\bl_\bo_\bc_\bk structure. If no |
| 9719 | lock is found that would prevent this lock from being created, |
| 9720 | the structure is left unchanged by this function call except |
| 9721 | for the lock type which is set to F_UNLCK. |
| 9722 | |
| 9723 | F_SETLK Set or clear a file segment lock according to the lock |
| 9724 | description pointed to by the third argument, _\ba_\br_\bg, taken as a |
| 9725 | pointer to a _\bs_\bt_\br_\bu_\bc_\bt _\bf_\bl_\bo_\bc_\bk (see above). F_SETLK is used to |
| 9726 | establish shared (or read) locks (F_RDLCK) or exclusive (or |
| 9727 | write) locks (F_WRLCK), as well as remove either type of lock |
| 9728 | (F_UNLCK). If a shared or exclusive lock cannot be set, |
| 9729 | f\bfc\bcn\bnt\btl\bl() returns immediately with EAGAIN. |
| 9730 | |
| 9731 | F_SETLKW This command is the same as F_SETLK except that if a shared or |
| 9732 | exclusive lock is blocked by other locks, the process waits |
| 9733 | until the request can be satisfied. If a signal that is to be |
| 9734 | caught is received while f\bfc\bcn\bnt\btl\bl() is waiting for a region, the |
| 9735 | f\bfc\bcn\bnt\btl\bl() will be interrupted if the signal handler has not |
| 9736 | specified the SA_RESTART (see sigaction(2)). |
| 9737 | |
| 9738 | When a shared lock has been set on a segment of a file, other processes |
| 9739 | can set shared locks on that segment or a portion of it. A shared lock |
| 9740 | prevents any other process from setting an exclusive lock on any portion |
| 9741 | of the protected area. A request for a shared lock fails if the file |
| 9742 | descriptor was not opened with read access. |
| 9743 | |
| 9744 | An exclusive lock prevents any other process from setting a shared lock |
| 9745 | or an exclusive lock on any portion of the protected area. A request for |
| 9746 | an exclusive lock fails if the file was not opened with write access. |
| 9747 | |
| 9748 | The value of _\bl_\b__\bw_\bh_\be_\bn_\bc_\be is SEEK_SET, SEEK_CUR, or SEEK_END to indicate that |
| 9749 | the relative offset, _\bl_\b__\bs_\bt_\ba_\br_\bt bytes, will be measured from the start of |
| 9750 | the file, current position, or end of the file, respectively. The value |
| 9751 | of _\bl_\b__\bl_\be_\bn is the number of consecutive bytes to be locked. If _\bl_\b__\bl_\be_\bn is |
| 9752 | negative, the result is undefined. The _\bl_\b__\bp_\bi_\bd field is only used with |
| 9753 | F_GETLK to return the process ID of the process holding a blocking lock. |
| 9754 | After a successful F_GETLK request, the value of _\bl_\b__\bw_\bh_\be_\bn_\bc_\be is SEEK_SET. |
| 9755 | |
| 9756 | Locks may start and extend beyond the current end of a file, but may not |
| 9757 | start or extend before the beginning of the file. A lock is set to |
| 9758 | extend to the largest possible value of the file offset for that file if |
| 9759 | _\bl_\b__\bl_\be_\bn is set to zero. If _\bl_\b__\bw_\bh_\be_\bn_\bc_\be and _\bl_\b__\bs_\bt_\ba_\br_\bt point to the beginning of |
| 9760 | the file, and _\bl_\b__\bl_\be_\bn is zero, the entire file is locked. If an |
| 9761 | application wishes only to do entire file locking, the flock(2) system |
| 9762 | call is much more efficient. |
| 9763 | |
| 9764 | There is at most one type of lock set for each byte in the file. Before |
| 9765 | a successful return from an F_SETLK or an F_SETLKW request when the |
| 9766 | calling process has previously existing locks on bytes in the region |
| 9767 | specified by the request, the previous lock type for each byte in the |
| 9768 | specified region is replaced by the new lock type. As specified above |
| 9769 | under the descriptions of shared locks and exclusive locks, an F_SETLK or |
| 9770 | an F_SETLKW request fails or blocks respectively when another process has |
| 9771 | existing locks on bytes in the specified region and the type of any of |
| 9772 | those locks conflicts with the type specified in the request. |
| 9773 | |
| 9774 | This interface follows the completely stupid semantics of System V and |
| 9775 | IEEE Std 1003.1-1988 (``POSIX.1'') that require that all locks associated |
| 9776 | with a file for a given process are removed when _\ba_\bn_\by file descriptor for |
| 9777 | that file is closed by that process. This semantic means that |
| 9778 | applications must be aware of any files that a subroutine library may |
| 9779 | access. For example if an application for updating the password file |
| 9780 | locks the password file database while making the update, and then calls |
| 9781 | getpwnam(3) to retrieve a record, the lock will be lost because |
| 9782 | getpwnam(3) opens, reads, and closes the password database. The database |
| 9783 | close will release all locks that the process has associated with the |
| 9784 | database, even if the library routine never requested a lock on the |
| 9785 | database. Another minor semantic problem with this interface is that |
| 9786 | locks are not inherited by a child process created using the fork(2) |
| 9787 | function. The flock(2) interface has much more rational last close |
| 9788 | semantics and allows locks to be inherited by child processes. flock(2) |
| 9789 | is recommended for applications that want to ensure the integrity of |
| 9790 | their locks when using library routines or wish to pass locks to their |
| 9791 | children. Note that flock(2) and f\bfc\bcn\bnt\btl\bl() locks may be safely used |
| 9792 | concurrently. |
| 9793 | |
| 9794 | All locks associated with a file for a given process are removed when the |
| 9795 | process terminates. |
| 9796 | |
| 9797 | A potential for deadlock occurs if a process controlling a locked region |
| 9798 | is put to sleep by attempting to lock the locked region of another |
| 9799 | process. This implementation detects that sleeping until a locked region |
| 9800 | is unlocked would cause a deadlock and fails with an EDEADLK error. |
| 9801 | |
| 9802 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 9803 | Upon successful completion, the value returned depends on _\bc_\bm_\bd as follows: |
| 9804 | |
| 9805 | F_DUPFD A new file descriptor. |
| 9806 | |
| 9807 | F_DUPFD_CLOEXEC A new file descriptor. |
| 9808 | |
| 9809 | F_GETFD Value of flag (only the low-order bit is defined). |
| 9810 | |
| 9811 | F_GETFL Value of flags. |
| 9812 | |
| 9813 | F_GETOWN Value of file descriptor owner. |
| 9814 | |
| 9815 | other Value other than -1. |
| 9816 | |
| 9817 | Otherwise, a value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the |
| 9818 | error. |
| 9819 | |
| 9820 | E\bER\bRR\bRO\bOR\bRS\bS |
| 9821 | f\bfc\bcn\bnt\btl\bl() will fail if: |
| 9822 | |
| 9823 | [EAGAIN] The argument _\bc_\bm_\bd is F_SETLK, the type of lock (_\bl_\b__\bt_\by_\bp_\be) |
| 9824 | is a shared lock (F_RDLCK) or exclusive lock |
| 9825 | (F_WRLCK), and the segment of a file to be locked is |
| 9826 | already exclusive-locked by another process; or the |
| 9827 | type is an exclusive lock and some portion of the |
| 9828 | segment of a file to be locked is already shared- |
| 9829 | locked or exclusive-locked by another process. |
| 9830 | |
| 9831 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 9832 | |
| 9833 | The argument _\bc_\bm_\bd is F_SETLK or F_SETLKW, the type of |
| 9834 | lock (_\bl_\b__\bt_\by_\bp_\be) is a shared lock (F_RDLCK), and _\bf_\bd is |
| 9835 | not a valid file descriptor open for reading. |
| 9836 | |
| 9837 | The argument _\bc_\bm_\bd is F_SETLK or F_SETLKW, the type of |
| 9838 | lock (_\bl_\b__\bt_\by_\bp_\be) is an exclusive lock (F_WRLCK), and _\bf_\bd |
| 9839 | is not a valid file descriptor open for writing. |
| 9840 | |
| 9841 | [EDEADLK] The argument _\bc_\bm_\bd is F_SETLKW, and a deadlock condition |
| 9842 | was detected. |
| 9843 | |
| 9844 | [EINTR] The argument _\bc_\bm_\bd is invalid. |
| 9845 | |
| 9846 | The argument _\bc_\bm_\bd is F_SETLKW, and the function was |
| 9847 | interrupted by a signal. |
| 9848 | |
| 9849 | [EINVAL] _\bc_\bm_\bd is F_DUPFD and _\ba_\br_\bg is negative or greater than the |
| 9850 | maximum allowable number (see getdtablesize(3)). |
| 9851 | |
| 9852 | The argument _\bc_\bm_\bd is F_GETLK, F_SETLK, or F_SETLKW and |
| 9853 | the data to which _\ba_\br_\bg points is not valid, or _\bf_\bd |
| 9854 | refers to a file that does not support locking. |
| 9855 | |
| 9856 | [EMFILE] The argument _\bc_\bm_\bd is F_DUPFD and the maximum number of |
| 9857 | open file descriptors permitted for the process are |
| 9858 | already in use, or no file descriptors greater than or |
| 9859 | equal to _\ba_\br_\bg are available. |
| 9860 | |
| 9861 | [ENOLCK] The argument _\bc_\bm_\bd is F_SETLK or F_SETLKW, and |
| 9862 | satisfying the lock or unlock request would result in |
| 9863 | the number of locked regions in the system exceeding a |
| 9864 | system-imposed limit. |
| 9865 | |
| 9866 | [ESRCH] _\bc_\bm_\bd is F_SETOWN and the process ID given in _\ba_\br_\bg is not |
| 9867 | in use. |
| 9868 | |
| 9869 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 9870 | close(2), execve(2), flock(2), open(2), sigaction(2), getdtablesize(3) |
| 9871 | |
| 9872 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 9873 | The f\bfc\bcn\bnt\btl\bl() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 9874 | |
| 9875 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 9876 | The f\bfc\bcn\bnt\btl\bl() function call appeared in 4.2BSD. |
| 9877 | |
| 9878 | N\bNA\bAM\bME\bE |
| 9879 | f\bfs\bsy\byn\bnc\bc, f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc - synchronize a file's in-core state with that on disk |
| 9880 | |
| 9881 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9882 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 9883 | |
| 9884 | _\bi_\bn_\bt |
| 9885 | f\bfs\bsy\byn\bnc\bc(_\bi_\bn_\bt _\bf_\bd); |
| 9886 | |
| 9887 | _\bi_\bn_\bt |
| 9888 | f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc(_\bi_\bn_\bt _\bf_\bd); |
| 9889 | |
| 9890 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 9891 | The f\bfs\bsy\byn\bnc\bc() function causes all modified data and attributes of _\bf_\bd to be |
| 9892 | moved to a permanent storage device. This normally results in all in- |
| 9893 | core modified copies of buffers for the associated file to be written to |
| 9894 | a disk. |
| 9895 | |
| 9896 | The f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() function is similar to f\bfs\bsy\byn\bnc\bc() except that it only |
| 9897 | guarantees modified data (and metadata necessary to read that data) is |
| 9898 | committed to storage. Other file modifications may be left |
| 9899 | unsynchronized. |
| 9900 | |
| 9901 | f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() should be used by programs that require a file to |
| 9902 | be in a known state, for example, in building a simple transaction |
| 9903 | facility. |
| 9904 | |
| 9905 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 9906 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions return the value 0 if successful; |
| 9907 | otherwise the value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
| 9908 | to indicate the error. |
| 9909 | |
| 9910 | E\bER\bRR\bRO\bOR\bRS\bS |
| 9911 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions fail if: |
| 9912 | |
| 9913 | [EBADF] _\bf_\bd is not a valid descriptor. |
| 9914 | |
| 9915 | [EINVAL] _\bf_\bd does not refer to a file which can be synchronized. |
| 9916 | |
| 9917 | [EIO] An I/O error occurred while reading from or writing to |
| 9918 | the file system. |
| 9919 | |
| 9920 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 9921 | sync(2), sync(8) |
| 9922 | |
| 9923 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 9924 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions conform to IEEE Std 1003.1-2008 |
| 9925 | (``POSIX.1''). |
| 9926 | |
| 9927 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 9928 | The f\bfs\bsy\byn\bnc\bc() system call first appeared in 4.1cBSD, and the f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() |
| 9929 | function has been available since OpenBSD 5.4. |
| 9930 | |
| 9931 | B\bBU\bUG\bGS\bS |
| 9932 | The f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() function is currently a wrapper around f\bfs\bsy\byn\bnc\bc(), so it |
| 9933 | synchronizes more state than necessary. |
| 9934 | |
| 9935 | N\bNA\bAM\bME\bE |
| 9936 | f\bfh\bho\bop\bpe\ben\bn, f\bfh\bhs\bst\bta\bat\bt, f\bfh\bhs\bst\bta\bat\btf\bfs\bs - access file via file handle |
| 9937 | |
| 9938 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9939 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 9940 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 9941 | |
| 9942 | _\bi_\bn_\bt |
| 9943 | f\bfh\bho\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 9944 | |
| 9945 | _\bi_\bn_\bt |
| 9946 | f\bfh\bhs\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 9947 | |
| 9948 | _\bi_\bn_\bt |
| 9949 | f\bfh\bhs\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
| 9950 | |
| 9951 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 9952 | These functions provide a means to access a file given the file handle |
| 9953 | _\bf_\bh_\bp. As this method bypasses directory access restrictions, these calls |
| 9954 | are restricted to the superuser. |
| 9955 | |
| 9956 | f\bfh\bho\bop\bpe\ben\bn() opens the file referenced by _\bf_\bh_\bp for reading and/or writing as |
| 9957 | specified by the argument _\bf_\bl_\ba_\bg_\bs and returns the file descriptor to the |
| 9958 | calling process. The _\bf_\bl_\ba_\bg_\bs are specified by _\bo_\br'ing together the flags |
| 9959 | used for the open(2) call. All said flags are valid except for O_CREAT. |
| 9960 | |
| 9961 | f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() provide the functionality of the fstat(2) and |
| 9962 | fstatfs(2) calls except that they return information for the file |
| 9963 | referred to by _\bf_\bh_\bp rather than an open file. |
| 9964 | |
| 9965 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 9966 | Upon successful completion, f\bfh\bho\bop\bpe\ben\bn() returns the file descriptor for the |
| 9967 | opened file, while f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() return 0. Otherwise, -1 is |
| 9968 | returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 9969 | |
| 9970 | E\bER\bRR\bRO\bOR\bRS\bS |
| 9971 | In addition to the errors returned by open(2), fstat(2), and fstatfs(2) |
| 9972 | respectively, f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() will return |
| 9973 | |
| 9974 | [EINVAL] Calling f\bfh\bho\bop\bpe\ben\bn() with O_CREAT set. |
| 9975 | |
| 9976 | [ESTALE] The file handle _\bf_\bh_\bp is no longer valid. |
| 9977 | |
| 9978 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 9979 | fstat(2), fstatfs(2), getfh(2), open(2) |
| 9980 | |
| 9981 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 9982 | The f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() functions first appeared in |
| 9983 | NetBSD 1.5. |
| 9984 | |
| 9985 | N\bNA\bAM\bME\bE |
| 9986 | f\bfh\bho\bop\bpe\ben\bn, f\bfh\bhs\bst\bta\bat\bt, f\bfh\bhs\bst\bta\bat\btf\bfs\bs - access file via file handle |
| 9987 | |
| 9988 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 9989 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 9990 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 9991 | |
| 9992 | _\bi_\bn_\bt |
| 9993 | f\bfh\bho\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 9994 | |
| 9995 | _\bi_\bn_\bt |
| 9996 | f\bfh\bhs\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 9997 | |
| 9998 | _\bi_\bn_\bt |
| 9999 | f\bfh\bhs\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
| 10000 | |
| 10001 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10002 | These functions provide a means to access a file given the file handle |
| 10003 | _\bf_\bh_\bp. As this method bypasses directory access restrictions, these calls |
| 10004 | are restricted to the superuser. |
| 10005 | |
| 10006 | f\bfh\bho\bop\bpe\ben\bn() opens the file referenced by _\bf_\bh_\bp for reading and/or writing as |
| 10007 | specified by the argument _\bf_\bl_\ba_\bg_\bs and returns the file descriptor to the |
| 10008 | calling process. The _\bf_\bl_\ba_\bg_\bs are specified by _\bo_\br'ing together the flags |
| 10009 | used for the open(2) call. All said flags are valid except for O_CREAT. |
| 10010 | |
| 10011 | f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() provide the functionality of the fstat(2) and |
| 10012 | fstatfs(2) calls except that they return information for the file |
| 10013 | referred to by _\bf_\bh_\bp rather than an open file. |
| 10014 | |
| 10015 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10016 | Upon successful completion, f\bfh\bho\bop\bpe\ben\bn() returns the file descriptor for the |
| 10017 | opened file, while f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() return 0. Otherwise, -1 is |
| 10018 | returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 10019 | |
| 10020 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10021 | In addition to the errors returned by open(2), fstat(2), and fstatfs(2) |
| 10022 | respectively, f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() will return |
| 10023 | |
| 10024 | [EINVAL] Calling f\bfh\bho\bop\bpe\ben\bn() with O_CREAT set. |
| 10025 | |
| 10026 | [ESTALE] The file handle _\bf_\bh_\bp is no longer valid. |
| 10027 | |
| 10028 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 10029 | fstat(2), fstatfs(2), getfh(2), open(2) |
| 10030 | |
| 10031 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 10032 | The f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() functions first appeared in |
| 10033 | NetBSD 1.5. |
| 10034 | |
| 10035 | N\bNA\bAM\bME\bE |
| 10036 | f\bfh\bho\bop\bpe\ben\bn, f\bfh\bhs\bst\bta\bat\bt, f\bfh\bhs\bst\bta\bat\btf\bfs\bs - access file via file handle |
| 10037 | |
| 10038 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 10039 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 10040 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 10041 | |
| 10042 | _\bi_\bn_\bt |
| 10043 | f\bfh\bho\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 10044 | |
| 10045 | _\bi_\bn_\bt |
| 10046 | f\bfh\bhs\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 10047 | |
| 10048 | _\bi_\bn_\bt |
| 10049 | f\bfh\bhs\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
| 10050 | |
| 10051 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10052 | These functions provide a means to access a file given the file handle |
| 10053 | _\bf_\bh_\bp. As this method bypasses directory access restrictions, these calls |
| 10054 | are restricted to the superuser. |
| 10055 | |
| 10056 | f\bfh\bho\bop\bpe\ben\bn() opens the file referenced by _\bf_\bh_\bp for reading and/or writing as |
| 10057 | specified by the argument _\bf_\bl_\ba_\bg_\bs and returns the file descriptor to the |
| 10058 | calling process. The _\bf_\bl_\ba_\bg_\bs are specified by _\bo_\br'ing together the flags |
| 10059 | used for the open(2) call. All said flags are valid except for O_CREAT. |
| 10060 | |
| 10061 | f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() provide the functionality of the fstat(2) and |
| 10062 | fstatfs(2) calls except that they return information for the file |
| 10063 | referred to by _\bf_\bh_\bp rather than an open file. |
| 10064 | |
| 10065 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10066 | Upon successful completion, f\bfh\bho\bop\bpe\ben\bn() returns the file descriptor for the |
| 10067 | opened file, while f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() return 0. Otherwise, -1 is |
| 10068 | returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 10069 | |
| 10070 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10071 | In addition to the errors returned by open(2), fstat(2), and fstatfs(2) |
| 10072 | respectively, f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() will return |
| 10073 | |
| 10074 | [EINVAL] Calling f\bfh\bho\bop\bpe\ben\bn() with O_CREAT set. |
| 10075 | |
| 10076 | [ESTALE] The file handle _\bf_\bh_\bp is no longer valid. |
| 10077 | |
| 10078 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 10079 | fstat(2), fstatfs(2), getfh(2), open(2) |
| 10080 | |
| 10081 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 10082 | The f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() functions first appeared in |
| 10083 | NetBSD 1.5. |
| 10084 | |
| 10085 | N\bNA\bAM\bME\bE |
| 10086 | f\bfl\blo\boc\bck\bk - apply or remove an advisory lock on an open file |
| 10087 | |
| 10088 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 10089 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 10090 | |
| 10091 | _\bi_\bn_\bt |
| 10092 | f\bfl\blo\boc\bck\bk(_\bi_\bn_\bt _\bf_\bd, _\bi_\bn_\bt _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn); |
| 10093 | |
| 10094 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10095 | f\bfl\blo\boc\bck\bk() applies or removes an _\ba_\bd_\bv_\bi_\bs_\bo_\br_\by lock on the file associated with |
| 10096 | the file descriptor _\bf_\bd. The _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn argument is one of: |
| 10097 | |
| 10098 | LOCK_SH Apply a shared lock. |
| 10099 | LOCK_EX Apply an exclusive lock. |
| 10100 | LOCK_UN Remove an existing lock. |
| 10101 | |
| 10102 | LOCK_SH and LOCK_EX may be combined with the optional LOCK_NB for |
| 10103 | nonblocking mode. |
| 10104 | |
| 10105 | Advisory locks allow cooperating processes to perform consistent |
| 10106 | operations on files, but do not guarantee consistency (i.e., processes |
| 10107 | may still access files without using advisory locks possibly resulting in |
| 10108 | inconsistencies). |
| 10109 | |
| 10110 | The locking mechanism allows two types of locks: _\bs_\bh_\ba_\br_\be_\bd locks and |
| 10111 | _\be_\bx_\bc_\bl_\bu_\bs_\bi_\bv_\be locks. At any time multiple shared locks may be applied to a |
| 10112 | file, but at no time are multiple exclusive, or both shared and |
| 10113 | exclusive, locks allowed simultaneously on a file. |
| 10114 | |
| 10115 | A shared lock may be _\bu_\bp_\bg_\br_\ba_\bd_\be_\bd to an exclusive lock, and vice versa, |
| 10116 | simply by specifying the appropriate lock type; this results in the |
| 10117 | previous lock being released and the new lock applied (possibly after |
| 10118 | other processes have gained and released the lock). |
| 10119 | |
| 10120 | Requesting a lock on an object that is already locked normally causes the |
| 10121 | caller to be blocked until the lock may be acquired. If _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn is the |
| 10122 | bitwise OR of LOCK_NB and LOCK_SH or LOCK_EX, then this will not happen; |
| 10123 | instead the call will fail and the error EWOULDBLOCK will be returned. |
| 10124 | |
| 10125 | N\bNO\bOT\bTE\bES\bS |
| 10126 | Locks are on files, not file descriptors. That is, file descriptors |
| 10127 | duplicated through dup(2) or fork(2) do not result in multiple instances |
| 10128 | of a lock, but rather multiple references to a single lock. If a process |
| 10129 | holding a lock on a file forks and the child explicitly unlocks the file, |
| 10130 | the parent will lose its lock. |
| 10131 | |
| 10132 | Processes blocked awaiting a lock may be awakened by signals. |
| 10133 | |
| 10134 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10135 | Upon successful completion, the value 0 is returned; otherwise the |
| 10136 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 10137 | error. |
| 10138 | |
| 10139 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10140 | The f\bfl\blo\boc\bck\bk() call fails if: |
| 10141 | |
| 10142 | [EWOULDBLOCK] The file is locked and the LOCK_NB option was |
| 10143 | specified. |
| 10144 | |
| 10145 | [EBADF] The argument _\bf_\bd is an invalid descriptor. |
| 10146 | |
| 10147 | [EINVAL] The argument _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn has an invalid value. |
| 10148 | |
| 10149 | [EOPNOTSUPP] The referenced descriptor is not of the correct type. |
| 10150 | |
| 10151 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 10152 | close(2), dup(2), execve(2), fcntl(2), fork(2), open(2) |
| 10153 | |
| 10154 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 10155 | The f\bfl\blo\boc\bck\bk() system call first appeared in 4.1cBSD. |
| 10156 | |
| 10157 | N\bNA\bAM\bME\bE |
| 10158 | f\bfo\bor\brk\bk - create a new process |
| 10159 | |
| 10160 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 10161 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 10162 | |
| 10163 | _\bp_\bi_\bd_\b__\bt |
| 10164 | f\bfo\bor\brk\bk(_\bv_\bo_\bi_\bd); |
| 10165 | |
| 10166 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10167 | f\bfo\bor\brk\bk() causes creation of a new process. The new process (child process) |
| 10168 | is an exact copy of the calling process (parent process) except for the |
| 10169 | following: |
| 10170 | |
| 10171 | +\b+\bo\bo The child process has a unique process ID, which also does not |
| 10172 | match any existing process group ID. |
| 10173 | |
| 10174 | +\b+\bo\bo The child process has a different parent process ID (i.e., the |
| 10175 | process ID of the parent process). |
| 10176 | |
| 10177 | +\b+\bo\bo The child process has a single thread. |
| 10178 | |
| 10179 | +\b+\bo\bo The child process has its own copy of the parent's descriptors. |
| 10180 | These descriptors reference the same underlying objects, so |
| 10181 | that, for instance, file pointers in file objects are shared |
| 10182 | between the child and the parent, so that an lseek(2) on a |
| 10183 | descriptor in the child process can affect a subsequent read(2) |
| 10184 | or write(2) by the parent. This descriptor copying is also |
| 10185 | used by the shell to establish standard input and output for |
| 10186 | newly created processes as well as to set up pipes. |
| 10187 | |
| 10188 | +\b+\bo\bo The child process has no fcntl(2)-style file locks. |
| 10189 | |
| 10190 | +\b+\bo\bo The child process' resource utilizations are set to 0; see |
| 10191 | getrusage(2). |
| 10192 | |
| 10193 | +\b+\bo\bo All interval timers are cleared; see setitimer(2). |
| 10194 | |
| 10195 | +\b+\bo\bo The child process' semaphore undo values are set to 0; see |
| 10196 | semop(2). |
| 10197 | |
| 10198 | +\b+\bo\bo The child process' pending signals set is empty. |
| 10199 | |
| 10200 | +\b+\bo\bo The child process has no memory locks; see mlock(2) and |
| 10201 | mlockall(2). |
| 10202 | |
| 10203 | In general, the child process should call _exit(2) rather than exit(3). |
| 10204 | Otherwise, any stdio buffers that exist both in the parent and child will |
| 10205 | be flushed twice. Similarly, _exit(2) should be used to prevent |
| 10206 | atexit(3) routines from being called twice (once in the parent and once |
| 10207 | in the child). |
| 10208 | |
| 10209 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10210 | Upon successful completion, f\bfo\bor\brk\bk() returns a value of 0 to the child |
| 10211 | process and returns the process ID of the child process to the parent |
| 10212 | process. Otherwise, a value of -1 is returned to the parent process, no |
| 10213 | child process is created, and the global variable _\be_\br_\br_\bn_\bo is set to |
| 10214 | indicate the error. |
| 10215 | |
| 10216 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10217 | f\bfo\bor\brk\bk() will fail and no child process will be created if: |
| 10218 | |
| 10219 | [EAGAIN] The system-imposed limits on the total number of processes or |
| 10220 | total number of threads under execution would be exceeded. |
| 10221 | These limits are configuration dependent. |
| 10222 | |
| 10223 | [EAGAIN] The limit RLIMIT_NPROC on the total number of processes under |
| 10224 | execution by the user ID would be exceeded. |
| 10225 | |
| 10226 | [ENOMEM] There is insufficient swap space for the new process. |
| 10227 | |
| 10228 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 10229 | execve(2), getrusage(2), wait(2) |
| 10230 | |
| 10231 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 10232 | The f\bfo\bor\brk\bk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 10233 | |
| 10234 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 10235 | The f\bfo\bor\brk\bk() system call first appeared in Version 1 AT&T UNIX. |
| 10236 | |
| 10237 | N\bNA\bAM\bME\bE |
| 10238 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf, f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf - get configurable pathname variables |
| 10239 | |
| 10240 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 10241 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 10242 | |
| 10243 | _\bl_\bo_\bn_\bg |
| 10244 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bn_\ba_\bm_\be); |
| 10245 | |
| 10246 | _\bl_\bo_\bn_\bg |
| 10247 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf(_\bi_\bn_\bt _\bf_\bd, _\bi_\bn_\bt _\bn_\ba_\bm_\be); |
| 10248 | |
| 10249 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10250 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf() and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf() functions provide a method for |
| 10251 | applications to determine the current value of a configurable system |
| 10252 | limit or option variable associated with a pathname or file descriptor. |
| 10253 | |
| 10254 | For p\bpa\bat\bth\bhc\bco\bon\bnf\bf, the _\bp_\ba_\bt_\bh argument is the name of a file or directory. For |
| 10255 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf, the _\bf_\bd argument is an open file descriptor. The _\bn_\ba_\bm_\be argument |
| 10256 | specifies the system variable to be queried. Symbolic constants for each |
| 10257 | name value are found in the include file <_\bu_\bn_\bi_\bs_\bt_\bd_\b._\bh>. |
| 10258 | |
| 10259 | The available values are as follows: |
| 10260 | |
| 10261 | _PC_LINK_MAX |
| 10262 | The maximum file link count. |
| 10263 | |
| 10264 | _PC_MAX_CANON |
| 10265 | The maximum number of bytes in a terminal canonical input line. |
| 10266 | |
| 10267 | _PC_MAX_INPUT |
| 10268 | The maximum number of bytes for which space is available in a |
| 10269 | terminal input queue. |
| 10270 | |
| 10271 | _PC_NAME_MAX |
| 10272 | The maximum number of bytes in a file name. |
| 10273 | |
| 10274 | _PC_PATH_MAX |
| 10275 | The maximum number of bytes in a pathname. |
| 10276 | |
| 10277 | _PC_PIPE_BUF |
| 10278 | The maximum number of bytes which will be written atomically to a |
| 10279 | pipe. |
| 10280 | |
| 10281 | _PC_CHOWN_RESTRICTED |
| 10282 | Returns 1 if appropriate privileges are required for the chown(2) |
| 10283 | system call, otherwise 0. IEEE Std 1003.1-2001 (``POSIX.1'') |
| 10284 | requires appropriate privilege in all cases, but this behavior |
| 10285 | was optional in prior editions of the standard. |
| 10286 | |
| 10287 | _PC_NO_TRUNC |
| 10288 | Returns 1 if attempts to use pathname components longer than |
| 10289 | {NAME_MAX} will result in an [ENAMETOOLONG] error; otherwise, |
| 10290 | such components will be truncated to {NAME_MAX}. IEEE Std |
| 10291 | 1003.1-2001 (``POSIX.1'') requires the error in all cases, but |
| 10292 | this behavior was optional in prior editions of the standard, and |
| 10293 | some non-POSIX-compliant file systems do not support this |
| 10294 | behavior. |
| 10295 | |
| 10296 | _PC_VDISABLE |
| 10297 | Returns the terminal character disabling value. |
| 10298 | |
| 10299 | _PC_2_SYMLINKS |
| 10300 | Returns 1 if the filesystem supports the creation of symbolic |
| 10301 | links within the specified directory; the meaning of |
| 10302 | _PC_2_SYMLINKS is unspecified for non-directory files. |
| 10303 | |
| 10304 | _PC_ALLOC_SIZE_MIN |
| 10305 | Minimum number of bytes of storage allocated for any portion of a |
| 10306 | file. |
| 10307 | |
| 10308 | _PC_ASYNC_IO |
| 10309 | Returns 1 if asynchronous I/O is supported, otherwise 0. |
| 10310 | |
| 10311 | _PC_FILESIZEBITS |
| 10312 | Number of bits needed to represent the maximum file size. |
| 10313 | |
| 10314 | _PC_PRIO_IO |
| 10315 | Returns 1 if prioritized I/O is supported, otherwise 0. |
| 10316 | |
| 10317 | _PC_REC_INCR_XFER_SIZE |
| 10318 | Recommended increment for file transfer sizes between |
| 10319 | _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE. |
| 10320 | |
| 10321 | _PC_REC_MAX_XFER_SIZE |
| 10322 | Maximum recommended file transfer size. |
| 10323 | |
| 10324 | _PC_REC_MIN_XFER_SIZE |
| 10325 | Minimum recommended file transfer size. |
| 10326 | |
| 10327 | _PC_REC_XFER_ALIGN |
| 10328 | Recommended file transfer buffer alignment. |
| 10329 | |
| 10330 | _PC_SYMLINK_MAX |
| 10331 | Maximum number of bytes in a symbolic link. |
| 10332 | |
| 10333 | _PC_SYNC_IO |
| 10334 | Returns 1 if synchronized I/O is supported, otherwise 0. |
| 10335 | |
| 10336 | _PC_TIMESTAMP_RESOLUTION |
| 10337 | The resolution in nanoseconds of file timestamps. |
| 10338 | |
| 10339 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10340 | If the call to p\bpa\bat\bth\bhc\bco\bon\bnf\bf or f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf is not successful, -1 is returned |
| 10341 | and _\be_\br_\br_\bn_\bo is set appropriately. Otherwise, if the variable is associated |
| 10342 | with functionality that does not have a limit in the system, -1 is |
| 10343 | returned and _\be_\br_\br_\bn_\bo is not modified. Otherwise, the current variable |
| 10344 | value is returned. |
| 10345 | |
| 10346 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10347 | If any of the following conditions occur, the p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf |
| 10348 | functions shall return -1 and set _\be_\br_\br_\bn_\bo to the corresponding value. |
| 10349 | |
| 10350 | [EINVAL] The value of the _\bn_\ba_\bm_\be argument is invalid. |
| 10351 | |
| 10352 | [EINVAL] The implementation does not support an association of |
| 10353 | the variable name with the associated file. |
| 10354 | |
| 10355 | [EIO] An I/O error occurred while reading from the file |
| 10356 | system. |
| 10357 | |
| 10358 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf() will fail if: |
| 10359 | |
| 10360 | [ENOTDIR] A component of the path prefix is not a directory. |
| 10361 | |
| 10362 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters |
| 10363 | (but see _PC_NO_TRUNC above), or an entire pathname |
| 10364 | (including the terminating NUL) exceeded PATH_MAX |
| 10365 | bytes. |
| 10366 | |
| 10367 | [ENOENT] The named file does not exist. |
| 10368 | |
| 10369 | [EACCES] Search permission is denied for a component of the |
| 10370 | path prefix. |
| 10371 | |
| 10372 | [ELOOP] Too many symbolic links were encountered in |
| 10373 | translating the pathname. |
| 10374 | |
| 10375 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 10376 | space. |
| 10377 | |
| 10378 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf() will fail if: |
| 10379 | |
| 10380 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 10381 | |
| 10382 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 10383 | sysconf(3), sysctl(3) |
| 10384 | |
| 10385 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 10386 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf functions conform to IEEE Std 1003.1-2008 |
| 10387 | (``POSIX.1''). |
| 10388 | |
| 10389 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 10390 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf functions first appeared in 4.4BSD. |
| 10391 | |
| 10392 | N\bNA\bAM\bME\bE |
| 10393 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 10394 | |
| 10395 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 10396 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 10397 | |
| 10398 | _\bi_\bn_\bt |
| 10399 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 10400 | |
| 10401 | _\bi_\bn_\bt |
| 10402 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 10403 | |
| 10404 | _\bi_\bn_\bt |
| 10405 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 10406 | |
| 10407 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 10408 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 10409 | |
| 10410 | _\bi_\bn_\bt |
| 10411 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 10412 | |
| 10413 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10414 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 10415 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 10416 | required, but all directories listed in the path name leading to the file |
| 10417 | must be searchable. |
| 10418 | |
| 10419 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 10420 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 10421 | itself, not the file the link references. |
| 10422 | |
| 10423 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 10424 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 10425 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 10426 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 10427 | instead of the current working directory. |
| 10428 | |
| 10429 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 10430 | in the _\bf_\bd parameter, the current working directory is used and the |
| 10431 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 10432 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 10433 | |
| 10434 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 10435 | values: |
| 10436 | |
| 10437 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 10438 | of the symbolic link is returned. |
| 10439 | |
| 10440 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 10441 | known by the file descriptor _\bf_\bd. |
| 10442 | |
| 10443 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 10444 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 10445 | concerning the file. |
| 10446 | |
| 10447 | struct stat { |
| 10448 | dev_t st_dev; /* inode's device */ |
| 10449 | ino_t st_ino; /* inode's number */ |
| 10450 | mode_t st_mode; /* inode protection mode */ |
| 10451 | nlink_t st_nlink; /* number of hard links */ |
| 10452 | uid_t st_uid; /* user ID of the file's owner */ |
| 10453 | gid_t st_gid; /* group ID of the file's group */ |
| 10454 | dev_t st_rdev; /* device type */ |
| 10455 | struct timespec st_atim; /* time of last access */ |
| 10456 | struct timespec st_mtim; /* time of last data modification */ |
| 10457 | struct timespec st_ctim; /* time of last file status change */ |
| 10458 | off_t st_size; /* file size, in bytes */ |
| 10459 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 10460 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 10461 | u_int32_t st_flags; /* user defined flags for file */ |
| 10462 | u_int32_t st_gen; /* file generation number */ |
| 10463 | }; |
| 10464 | |
| 10465 | The time-related fields of struct stat are represented in struct timespec |
| 10466 | format, which has nanosecond precision. However, the actual precision is |
| 10467 | generally limited by the file system holding the file. The fields are as |
| 10468 | follows: |
| 10469 | |
| 10470 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 10471 | system object was created and updated by the utimes(2) and |
| 10472 | read(2) system calls. |
| 10473 | |
| 10474 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 10475 | truncate(2), utimes(2), and write(2) system calls. For |
| 10476 | directories, changed by any system call that alters which |
| 10477 | files are in the directory, such as the unlink(2), rename(2), |
| 10478 | mkdir(2), and symlink(2) system calls. |
| 10479 | |
| 10480 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 10481 | modification). Changed by the chmod(2), chown(2), link(2), |
| 10482 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 10483 | |
| 10484 | In addition, all the time fields are set to the current time when a file |
| 10485 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 10486 | open(2), and symlink(2) system calls. |
| 10487 | |
| 10488 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 10489 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 10490 | respective struct timespec member. Deprecated macros are also provided |
| 10491 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 10492 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 10493 | |
| 10494 | The size-related fields of the struct stat are as follows: |
| 10495 | |
| 10496 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 10497 | |
| 10498 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 10499 | 512-byte units. As short symbolic links are stored in the |
| 10500 | inode, this number may be zero. |
| 10501 | |
| 10502 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 10503 | |
| 10504 | #define S_IFMT 0170000 /* type of file mask */ |
| 10505 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 10506 | #define S_IFCHR 0020000 /* character special */ |
| 10507 | #define S_IFDIR 0040000 /* directory */ |
| 10508 | #define S_IFBLK 0060000 /* block special */ |
| 10509 | #define S_IFREG 0100000 /* regular */ |
| 10510 | #define S_IFLNK 0120000 /* symbolic link */ |
| 10511 | #define S_IFSOCK 0140000 /* socket */ |
| 10512 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 10513 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 10514 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 10515 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 10516 | #define S_IRUSR 0000400 /* R for owner */ |
| 10517 | #define S_IWUSR 0000200 /* W for owner */ |
| 10518 | #define S_IXUSR 0000100 /* X for owner */ |
| 10519 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 10520 | #define S_IRGRP 0000040 /* R for group */ |
| 10521 | #define S_IWGRP 0000020 /* W for group */ |
| 10522 | #define S_IXGRP 0000010 /* X for group */ |
| 10523 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 10524 | #define S_IROTH 0000004 /* R for other */ |
| 10525 | #define S_IWOTH 0000002 /* W for other */ |
| 10526 | #define S_IXOTH 0000001 /* X for other */ |
| 10527 | |
| 10528 | The following macros test a file's type. If the file is of that type, a |
| 10529 | non-zero value is returned; otherwise, 0 is returned. |
| 10530 | |
| 10531 | S_ISBLK(st_mode m) /* block special */ |
| 10532 | S_ISCHR(st_mode m) /* char special */ |
| 10533 | S_ISDIR(st_mode m) /* directory */ |
| 10534 | S_ISFIFO(st_mode m) /* fifo */ |
| 10535 | S_ISLNK(st_mode m) /* symbolic link */ |
| 10536 | S_ISREG(st_mode m) /* regular file */ |
| 10537 | S_ISSOCK(st_mode m) /* socket */ |
| 10538 | |
| 10539 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 10540 | |
| 10541 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10542 | Upon successful completion, the value 0 is returned; otherwise the |
| 10543 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 10544 | error. |
| 10545 | |
| 10546 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10547 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 10548 | |
| 10549 | [ENOTDIR] A component of the path prefix is not a directory. |
| 10550 | |
| 10551 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 10552 | characters, or an entire pathname (including the |
| 10553 | terminating NUL) exceeded PATH_MAX bytes. |
| 10554 | |
| 10555 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 10556 | empty path. |
| 10557 | |
| 10558 | [EACCES] Search permission is denied for a component of the |
| 10559 | path prefix. |
| 10560 | |
| 10561 | [ELOOP] Too many symbolic links were encountered in |
| 10562 | translating the pathname. |
| 10563 | |
| 10564 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 10565 | |
| 10566 | [EIO] An I/O error occurred while reading from or writing to |
| 10567 | the file system. |
| 10568 | |
| 10569 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 10570 | |
| 10571 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 10572 | AT_SYMLINK_NOFOLLOW. |
| 10573 | |
| 10574 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 10575 | argument is neither AT_FDCWD nor a valid file |
| 10576 | descriptor. |
| 10577 | |
| 10578 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 10579 | argument is a valid file descriptor but it does not |
| 10580 | reference a directory. |
| 10581 | |
| 10582 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 10583 | permission is denied for the directory which the _\bf_\bd |
| 10584 | file descriptor references. |
| 10585 | |
| 10586 | f\bfs\bst\bta\bat\bt() will fail if: |
| 10587 | |
| 10588 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 10589 | |
| 10590 | [EFAULT] _\bs_\bb points to an invalid address. |
| 10591 | |
| 10592 | [EIO] An I/O error occurred while reading from the file |
| 10593 | system. |
| 10594 | |
| 10595 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 10596 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 10597 | |
| 10598 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 10599 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 10600 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 10601 | |
| 10602 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 10603 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 10604 | |
| 10605 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 10606 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 10607 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 10608 | in Version 7 AT&T UNIX. |
| 10609 | |
| 10610 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 10611 | appeared in OpenBSD 5.0. |
| 10612 | |
| 10613 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 10614 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 10615 | |
| 10616 | Certain programs written when the timestamps were just of type time_t |
| 10617 | assumed that the members were consecutive (and could therefore be treated |
| 10618 | as an array and have their address passed directly to utime(3)). The |
| 10619 | transition to timestamps of type struct timespec broke them irrevocably. |
| 10620 | |
| 10621 | B\bBU\bUG\bGS\bS |
| 10622 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 10623 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 10624 | the time fields. |
| 10625 | |
| 10626 | N\bNA\bAM\bME\bE |
| 10627 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 10628 | |
| 10629 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 10630 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 10631 | |
| 10632 | _\bi_\bn_\bt |
| 10633 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 10634 | |
| 10635 | _\bi_\bn_\bt |
| 10636 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 10637 | |
| 10638 | _\bi_\bn_\bt |
| 10639 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 10640 | |
| 10641 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 10642 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 10643 | |
| 10644 | _\bi_\bn_\bt |
| 10645 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 10646 | |
| 10647 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10648 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 10649 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 10650 | required, but all directories listed in the path name leading to the file |
| 10651 | must be searchable. |
| 10652 | |
| 10653 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 10654 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 10655 | itself, not the file the link references. |
| 10656 | |
| 10657 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 10658 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 10659 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 10660 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 10661 | instead of the current working directory. |
| 10662 | |
| 10663 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 10664 | in the _\bf_\bd parameter, the current working directory is used and the |
| 10665 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 10666 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 10667 | |
| 10668 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 10669 | values: |
| 10670 | |
| 10671 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 10672 | of the symbolic link is returned. |
| 10673 | |
| 10674 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 10675 | known by the file descriptor _\bf_\bd. |
| 10676 | |
| 10677 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 10678 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 10679 | concerning the file. |
| 10680 | |
| 10681 | struct stat { |
| 10682 | dev_t st_dev; /* inode's device */ |
| 10683 | ino_t st_ino; /* inode's number */ |
| 10684 | mode_t st_mode; /* inode protection mode */ |
| 10685 | nlink_t st_nlink; /* number of hard links */ |
| 10686 | uid_t st_uid; /* user ID of the file's owner */ |
| 10687 | gid_t st_gid; /* group ID of the file's group */ |
| 10688 | dev_t st_rdev; /* device type */ |
| 10689 | struct timespec st_atim; /* time of last access */ |
| 10690 | struct timespec st_mtim; /* time of last data modification */ |
| 10691 | struct timespec st_ctim; /* time of last file status change */ |
| 10692 | off_t st_size; /* file size, in bytes */ |
| 10693 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 10694 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 10695 | u_int32_t st_flags; /* user defined flags for file */ |
| 10696 | u_int32_t st_gen; /* file generation number */ |
| 10697 | }; |
| 10698 | |
| 10699 | The time-related fields of struct stat are represented in struct timespec |
| 10700 | format, which has nanosecond precision. However, the actual precision is |
| 10701 | generally limited by the file system holding the file. The fields are as |
| 10702 | follows: |
| 10703 | |
| 10704 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 10705 | system object was created and updated by the utimes(2) and |
| 10706 | read(2) system calls. |
| 10707 | |
| 10708 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 10709 | truncate(2), utimes(2), and write(2) system calls. For |
| 10710 | directories, changed by any system call that alters which |
| 10711 | files are in the directory, such as the unlink(2), rename(2), |
| 10712 | mkdir(2), and symlink(2) system calls. |
| 10713 | |
| 10714 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 10715 | modification). Changed by the chmod(2), chown(2), link(2), |
| 10716 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 10717 | |
| 10718 | In addition, all the time fields are set to the current time when a file |
| 10719 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 10720 | open(2), and symlink(2) system calls. |
| 10721 | |
| 10722 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 10723 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 10724 | respective struct timespec member. Deprecated macros are also provided |
| 10725 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 10726 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 10727 | |
| 10728 | The size-related fields of the struct stat are as follows: |
| 10729 | |
| 10730 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 10731 | |
| 10732 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 10733 | 512-byte units. As short symbolic links are stored in the |
| 10734 | inode, this number may be zero. |
| 10735 | |
| 10736 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 10737 | |
| 10738 | #define S_IFMT 0170000 /* type of file mask */ |
| 10739 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 10740 | #define S_IFCHR 0020000 /* character special */ |
| 10741 | #define S_IFDIR 0040000 /* directory */ |
| 10742 | #define S_IFBLK 0060000 /* block special */ |
| 10743 | #define S_IFREG 0100000 /* regular */ |
| 10744 | #define S_IFLNK 0120000 /* symbolic link */ |
| 10745 | #define S_IFSOCK 0140000 /* socket */ |
| 10746 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 10747 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 10748 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 10749 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 10750 | #define S_IRUSR 0000400 /* R for owner */ |
| 10751 | #define S_IWUSR 0000200 /* W for owner */ |
| 10752 | #define S_IXUSR 0000100 /* X for owner */ |
| 10753 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 10754 | #define S_IRGRP 0000040 /* R for group */ |
| 10755 | #define S_IWGRP 0000020 /* W for group */ |
| 10756 | #define S_IXGRP 0000010 /* X for group */ |
| 10757 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 10758 | #define S_IROTH 0000004 /* R for other */ |
| 10759 | #define S_IWOTH 0000002 /* W for other */ |
| 10760 | #define S_IXOTH 0000001 /* X for other */ |
| 10761 | |
| 10762 | The following macros test a file's type. If the file is of that type, a |
| 10763 | non-zero value is returned; otherwise, 0 is returned. |
| 10764 | |
| 10765 | S_ISBLK(st_mode m) /* block special */ |
| 10766 | S_ISCHR(st_mode m) /* char special */ |
| 10767 | S_ISDIR(st_mode m) /* directory */ |
| 10768 | S_ISFIFO(st_mode m) /* fifo */ |
| 10769 | S_ISLNK(st_mode m) /* symbolic link */ |
| 10770 | S_ISREG(st_mode m) /* regular file */ |
| 10771 | S_ISSOCK(st_mode m) /* socket */ |
| 10772 | |
| 10773 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 10774 | |
| 10775 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10776 | Upon successful completion, the value 0 is returned; otherwise the |
| 10777 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 10778 | error. |
| 10779 | |
| 10780 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10781 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 10782 | |
| 10783 | [ENOTDIR] A component of the path prefix is not a directory. |
| 10784 | |
| 10785 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 10786 | characters, or an entire pathname (including the |
| 10787 | terminating NUL) exceeded PATH_MAX bytes. |
| 10788 | |
| 10789 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 10790 | empty path. |
| 10791 | |
| 10792 | [EACCES] Search permission is denied for a component of the |
| 10793 | path prefix. |
| 10794 | |
| 10795 | [ELOOP] Too many symbolic links were encountered in |
| 10796 | translating the pathname. |
| 10797 | |
| 10798 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 10799 | |
| 10800 | [EIO] An I/O error occurred while reading from or writing to |
| 10801 | the file system. |
| 10802 | |
| 10803 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 10804 | |
| 10805 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 10806 | AT_SYMLINK_NOFOLLOW. |
| 10807 | |
| 10808 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 10809 | argument is neither AT_FDCWD nor a valid file |
| 10810 | descriptor. |
| 10811 | |
| 10812 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 10813 | argument is a valid file descriptor but it does not |
| 10814 | reference a directory. |
| 10815 | |
| 10816 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 10817 | permission is denied for the directory which the _\bf_\bd |
| 10818 | file descriptor references. |
| 10819 | |
| 10820 | f\bfs\bst\bta\bat\bt() will fail if: |
| 10821 | |
| 10822 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 10823 | |
| 10824 | [EFAULT] _\bs_\bb points to an invalid address. |
| 10825 | |
| 10826 | [EIO] An I/O error occurred while reading from the file |
| 10827 | system. |
| 10828 | |
| 10829 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 10830 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 10831 | |
| 10832 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 10833 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 10834 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 10835 | |
| 10836 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 10837 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 10838 | |
| 10839 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 10840 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 10841 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 10842 | in Version 7 AT&T UNIX. |
| 10843 | |
| 10844 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 10845 | appeared in OpenBSD 5.0. |
| 10846 | |
| 10847 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 10848 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 10849 | |
| 10850 | Certain programs written when the timestamps were just of type time_t |
| 10851 | assumed that the members were consecutive (and could therefore be treated |
| 10852 | as an array and have their address passed directly to utime(3)). The |
| 10853 | transition to timestamps of type struct timespec broke them irrevocably. |
| 10854 | |
| 10855 | B\bBU\bUG\bGS\bS |
| 10856 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 10857 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 10858 | the time fields. |
| 10859 | |
| 10860 | N\bNA\bAM\bME\bE |
| 10861 | s\bst\bta\bat\btf\bfs\bs, f\bfs\bst\bta\bat\btf\bfs\bs - get file system statistics |
| 10862 | |
| 10863 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 10864 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 10865 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
| 10866 | |
| 10867 | _\bi_\bn_\bt |
| 10868 | s\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
| 10869 | |
| 10870 | _\bi_\bn_\bt |
| 10871 | f\bfs\bst\bta\bat\btf\bfs\bs(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
| 10872 | |
| 10873 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10874 | s\bst\bta\bat\btf\bfs\bs() returns information about a mounted file system. _\bp_\ba_\bt_\bh is the |
| 10875 | path name of any file within the mounted file system. _\bb_\bu_\bf is a pointer |
| 10876 | to a s\bst\bta\bat\btf\bfs\bs structure defined as follows: |
| 10877 | |
| 10878 | typedef struct { int32_t val[2]; } fsid_t; |
| 10879 | |
| 10880 | #define MFSNAMELEN 16 /* length of fs type name, including nul */ |
| 10881 | #define MNAMELEN 90 /* length of buffer for returned name */ |
| 10882 | |
| 10883 | struct statfs { |
| 10884 | u_int32_t f_flags; /* copy of mount flags */ |
| 10885 | u_int32_t f_bsize; /* file system block size */ |
| 10886 | u_int32_t f_iosize; /* optimal transfer block size */ |
| 10887 | |
| 10888 | /* unit is f_bsize */ |
| 10889 | u_int64_t f_blocks; /* total data blocks in file system */ |
| 10890 | u_int64_t f_bfree; /* free blocks in fs */ |
| 10891 | int64_t f_bavail; /* free blocks avail to non-superuser */ |
| 10892 | |
| 10893 | u_int64_t f_files; /* total file nodes in file system */ |
| 10894 | u_int64_t f_ffree; /* free file nodes in fs */ |
| 10895 | int64_t f_favail; /* free file nodes avail to non-root */ |
| 10896 | |
| 10897 | u_int64_t f_syncwrites; /* count of sync writes since mount */ |
| 10898 | u_int64_t f_syncreads; /* count of sync reads since mount */ |
| 10899 | u_int64_t f_asyncwrites; /* count of async writes since mount */ |
| 10900 | u_int64_t f_asyncreads; /* count of async reads since mount */ |
| 10901 | |
| 10902 | fsid_t f_fsid; /* file system id */ |
| 10903 | u_int32_t f_namemax; /* maximum filename length */ |
| 10904 | uid_t f_owner; /* user that mounted the file system */ |
| 10905 | u_int64_t f_ctime; /* last mount [-u] time */ |
| 10906 | |
| 10907 | char f_fstypename[MFSNAMELEN]; /* fs type name */ |
| 10908 | char f_mntonname[MNAMELEN]; /* directory on which mounted */ |
| 10909 | char f_mntfromname[MNAMELEN]; /* mounted file system */ |
| 10910 | char f_mntfromspec[MNAMELEN]; /* special for mount request */ |
| 10911 | union mount_info mount_info; /* per-filesystem mount options */ |
| 10912 | }; |
| 10913 | |
| 10914 | f\bfs\bst\bta\bat\btf\bfs\bs() returns the same information about an open file referenced by |
| 10915 | descriptor _\bf_\bd. |
| 10916 | |
| 10917 | Note that _\bf_\b__\bf_\bs_\bi_\bd will be empty unless the user is the superuser. |
| 10918 | |
| 10919 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10920 | Upon successful completion, the value 0 is returned; otherwise the |
| 10921 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 10922 | error. |
| 10923 | |
| 10924 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10925 | s\bst\bta\bat\btf\bfs\bs() fails if one or more of the following are true: |
| 10926 | |
| 10927 | [ENOTDIR] A component of the path prefix of _\bp_\ba_\bt_\bh is not a |
| 10928 | directory. |
| 10929 | |
| 10930 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 10931 | characters, or an entire pathname (including the |
| 10932 | terminating NUL) exceeded PATH_MAX bytes. |
| 10933 | |
| 10934 | [ENOENT] The file referred to by _\bp_\ba_\bt_\bh does not exist. |
| 10935 | |
| 10936 | [EACCES] Search permission is denied for a component of the |
| 10937 | path prefix of _\bp_\ba_\bt_\bh. |
| 10938 | |
| 10939 | [ELOOP] Too many symbolic links were encountered in |
| 10940 | translating _\bp_\ba_\bt_\bh. |
| 10941 | |
| 10942 | [EFAULT] _\bb_\bu_\bf or _\bp_\ba_\bt_\bh points to an invalid address. |
| 10943 | |
| 10944 | [EIO] An I/O error occurred while reading from or writing to |
| 10945 | the file system. |
| 10946 | |
| 10947 | f\bfs\bst\bta\bat\btf\bfs\bs() fails if one or more of the following are true: |
| 10948 | |
| 10949 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 10950 | |
| 10951 | [EFAULT] _\bb_\bu_\bf points to an invalid address. |
| 10952 | |
| 10953 | [EIO] An I/O error occurred while reading from or writing to |
| 10954 | the file system. |
| 10955 | |
| 10956 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 10957 | df(1), getfsstat(2), mount(2), stat(2) |
| 10958 | |
| 10959 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 10960 | The s\bst\bta\bat\btf\bfs\bs() function first appeared in 4.4BSD. |
| 10961 | |
| 10962 | N\bNA\bAM\bME\bE |
| 10963 | f\bfs\bsy\byn\bnc\bc, f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc - synchronize a file's in-core state with that on disk |
| 10964 | |
| 10965 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 10966 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 10967 | |
| 10968 | _\bi_\bn_\bt |
| 10969 | f\bfs\bsy\byn\bnc\bc(_\bi_\bn_\bt _\bf_\bd); |
| 10970 | |
| 10971 | _\bi_\bn_\bt |
| 10972 | f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc(_\bi_\bn_\bt _\bf_\bd); |
| 10973 | |
| 10974 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 10975 | The f\bfs\bsy\byn\bnc\bc() function causes all modified data and attributes of _\bf_\bd to be |
| 10976 | moved to a permanent storage device. This normally results in all in- |
| 10977 | core modified copies of buffers for the associated file to be written to |
| 10978 | a disk. |
| 10979 | |
| 10980 | The f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() function is similar to f\bfs\bsy\byn\bnc\bc() except that it only |
| 10981 | guarantees modified data (and metadata necessary to read that data) is |
| 10982 | committed to storage. Other file modifications may be left |
| 10983 | unsynchronized. |
| 10984 | |
| 10985 | f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() should be used by programs that require a file to |
| 10986 | be in a known state, for example, in building a simple transaction |
| 10987 | facility. |
| 10988 | |
| 10989 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 10990 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions return the value 0 if successful; |
| 10991 | otherwise the value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
| 10992 | to indicate the error. |
| 10993 | |
| 10994 | E\bER\bRR\bRO\bOR\bRS\bS |
| 10995 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions fail if: |
| 10996 | |
| 10997 | [EBADF] _\bf_\bd is not a valid descriptor. |
| 10998 | |
| 10999 | [EINVAL] _\bf_\bd does not refer to a file which can be synchronized. |
| 11000 | |
| 11001 | [EIO] An I/O error occurred while reading from or writing to |
| 11002 | the file system. |
| 11003 | |
| 11004 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11005 | sync(2), sync(8) |
| 11006 | |
| 11007 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11008 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions conform to IEEE Std 1003.1-2008 |
| 11009 | (``POSIX.1''). |
| 11010 | |
| 11011 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11012 | The f\bfs\bsy\byn\bnc\bc() system call first appeared in 4.1cBSD, and the f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() |
| 11013 | function has been available since OpenBSD 5.4. |
| 11014 | |
| 11015 | B\bBU\bUG\bGS\bS |
| 11016 | The f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() function is currently a wrapper around f\bfs\bsy\byn\bnc\bc(), so it |
| 11017 | synchronizes more state than necessary. |
| 11018 | |
| 11019 | N\bNA\bAM\bME\bE |
| 11020 | t\btr\bru\bun\bnc\bca\bat\bte\be, f\bft\btr\bru\bun\bnc\bca\bat\bte\be - truncate or extend a file to a specified length |
| 11021 | |
| 11022 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11023 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 11024 | |
| 11025 | _\bi_\bn_\bt |
| 11026 | t\btr\bru\bun\bnc\bca\bat\bte\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bo_\bf_\bf_\b__\bt _\bl_\be_\bn_\bg_\bt_\bh); |
| 11027 | |
| 11028 | _\bi_\bn_\bt |
| 11029 | f\bft\btr\bru\bun\bnc\bca\bat\bte\be(_\bi_\bn_\bt _\bf_\bd, _\bo_\bf_\bf_\b__\bt _\bl_\be_\bn_\bg_\bt_\bh); |
| 11030 | |
| 11031 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11032 | t\btr\bru\bun\bnc\bca\bat\bte\be() causes the file named by _\bp_\ba_\bt_\bh or referenced by _\bf_\bd to be |
| 11033 | truncated or extended to _\bl_\be_\bn_\bg_\bt_\bh bytes in size. If the file was larger |
| 11034 | than this size, the extra data is lost. If the file was smaller than |
| 11035 | this size, it will be extended as if by writing bytes with the value |
| 11036 | zero. With f\bft\btr\bru\bun\bnc\bca\bat\bte\be(), the file must be open for writing. |
| 11037 | |
| 11038 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11039 | Upon successful completion, the value 0 is returned; otherwise the |
| 11040 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 11041 | error. |
| 11042 | |
| 11043 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11044 | t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() will succeed unless: |
| 11045 | |
| 11046 | [EINVAL] The _\bl_\be_\bn_\bg_\bt_\bh is a negative value. |
| 11047 | |
| 11048 | [EIO] An I/O error occurred updating the inode. |
| 11049 | |
| 11050 | In addition, t\btr\bru\bun\bnc\bca\bat\bte\be() may return the following errors: |
| 11051 | |
| 11052 | [ENOTDIR] A component of the path prefix is not a directory. |
| 11053 | |
| 11054 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 11055 | characters, or an entire pathname (including the |
| 11056 | terminating NUL) exceeded PATH_MAX bytes. |
| 11057 | |
| 11058 | [ENOENT] The named file does not exist. |
| 11059 | |
| 11060 | [EACCES] Search permission is denied for a component of the |
| 11061 | path prefix. |
| 11062 | |
| 11063 | [EACCES] The named file is not writable by the user. |
| 11064 | |
| 11065 | [ELOOP] Too many symbolic links were encountered in |
| 11066 | translating the pathname. |
| 11067 | |
| 11068 | [EISDIR] The named file is a directory. |
| 11069 | |
| 11070 | [EROFS] The named file resides on a read-only file system. |
| 11071 | |
| 11072 | [ETXTBSY] The file is a pure procedure (shared text) file that |
| 11073 | is being executed. |
| 11074 | |
| 11075 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 11076 | space. |
| 11077 | |
| 11078 | f\bft\btr\bru\bun\bnc\bca\bat\bte\be() may return the following errors: |
| 11079 | |
| 11080 | [EBADF] The _\bf_\bd is not a valid descriptor. |
| 11081 | |
| 11082 | [EINVAL] The _\bf_\bd references a socket, not a file. |
| 11083 | |
| 11084 | [EINVAL] The _\bf_\bd is not open for writing. |
| 11085 | |
| 11086 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11087 | open(2) |
| 11088 | |
| 11089 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11090 | The t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() functions conform to IEEE Std 1003.1-2008 |
| 11091 | (``POSIX.1''). |
| 11092 | |
| 11093 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11094 | The t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() system calls first appeared in 4.1cBSD. |
| 11095 | |
| 11096 | B\bBU\bUG\bGS\bS |
| 11097 | These calls should be generalized to allow ranges of bytes in a file to |
| 11098 | be discarded. |
| 11099 | |
| 11100 | Use of t\btr\bru\bun\bnc\bca\bat\bte\be() to extend a file is not portable. |
| 11101 | |
| 11102 | N\bNA\bAM\bME\bE |
| 11103 | u\but\bti\bim\bme\bes\bs, f\bfu\but\bti\bim\bme\bes\bs, u\but\bti\bim\bme\ben\bns\bsa\bat\bt, f\bfu\but\bti\bim\bme\ben\bns\bs - set file access and modification |
| 11104 | times |
| 11105 | |
| 11106 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11107 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 11108 | |
| 11109 | _\bi_\bn_\bt |
| 11110 | u\but\bti\bim\bme\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
| 11111 | |
| 11112 | _\bi_\bn_\bt |
| 11113 | f\bfu\but\bti\bim\bme\bes\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
| 11114 | |
| 11115 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 11116 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 11117 | |
| 11118 | _\bi_\bn_\bt |
| 11119 | u\but\bti\bim\bme\ben\bns\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b], |
| 11120 | _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 11121 | |
| 11122 | _\bi_\bn_\bt |
| 11123 | f\bfu\but\bti\bim\bme\ben\bns\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b]); |
| 11124 | |
| 11125 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11126 | The access and modification times of the file named by _\bp_\ba_\bt_\bh or referenced |
| 11127 | by _\bf_\bd are changed as specified by the argument _\bt_\bi_\bm_\be_\bs. |
| 11128 | |
| 11129 | If _\bt_\bi_\bm_\be_\bs is NULL, the access and modification times are set to the |
| 11130 | current time. The caller must be the owner of the file, have permission |
| 11131 | to write the file, or be the superuser. |
| 11132 | |
| 11133 | If _\bt_\bi_\bm_\be_\bs is non-null, it is assumed to point to an array of two timeval |
| 11134 | structures. The access time is set to the value of the first element, |
| 11135 | and the modification time is set to the value of the second element. The |
| 11136 | caller must be the owner of the file or be the superuser. |
| 11137 | |
| 11138 | In either case, the inode-change-time of the file is set to the current |
| 11139 | time. |
| 11140 | |
| 11141 | The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() are equivalent to u\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\bes\bs(), |
| 11142 | respectively, with the following differences. |
| 11143 | |
| 11144 | Both u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() take two timespec values instead of two |
| 11145 | timeval values. Further, either of the _\bt_\bv_\b__\bn_\bs_\be_\bc fields can be set to one |
| 11146 | of the following special values defined in <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>: |
| 11147 | |
| 11148 | UTIME_NOW Set the respective timestamp to the greatest value |
| 11149 | supported that is not greater than the current time. |
| 11150 | UTIME_OMIT Do not change the respective timestamp. |
| 11151 | |
| 11152 | Additionally, if the _\bp_\ba_\bt_\bh argument to u\but\bti\bim\bme\ben\bns\bsa\bat\bt() specifies a relative |
| 11153 | path, the file whose timestamps are changed is determined relative to the |
| 11154 | directory associated with file descriptor _\bf_\bd instead of the current |
| 11155 | working directory. |
| 11156 | |
| 11157 | If u\but\bti\bim\bme\ben\bns\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 11158 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 11159 | |
| 11160 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 11161 | values: |
| 11162 | |
| 11163 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
| 11164 | timestamps of the symbolic link are changed. |
| 11165 | |
| 11166 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11167 | Upon successful completion, the value 0 is returned; otherwise the |
| 11168 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 11169 | error. |
| 11170 | |
| 11171 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11172 | u\but\bti\bim\bme\bes\bs() and u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
| 11173 | |
| 11174 | [EACCES] Search permission is denied for a component of the |
| 11175 | path prefix; or the _\bt_\bi_\bm_\be_\bs argument is NULL and the |
| 11176 | effective user ID of the process does not match the |
| 11177 | owner of the file, and is not the superuser, and write |
| 11178 | access is denied. |
| 11179 | |
| 11180 | [EFAULT] _\bf_\bi_\bl_\be or _\bt_\bi_\bm_\be_\bs points outside the process's allocated |
| 11181 | address space. |
| 11182 | |
| 11183 | [EIO] An I/O error occurred while reading or writing the |
| 11184 | affected inode. |
| 11185 | |
| 11186 | [ELOOP] Too many symbolic links were encountered in |
| 11187 | translating the pathname. |
| 11188 | |
| 11189 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 11190 | characters, or an entire pathname (including the |
| 11191 | terminating NUL) exceeded PATH_MAX bytes. |
| 11192 | |
| 11193 | [ENOENT] The named file does not exist. |
| 11194 | |
| 11195 | [ENOTDIR] A component of the path prefix is not a directory. |
| 11196 | |
| 11197 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
| 11198 | process's effective user ID does not match the owner |
| 11199 | of the file and is not the superuser. |
| 11200 | |
| 11201 | [EROFS] The file system containing the file is mounted read- |
| 11202 | only. |
| 11203 | |
| 11204 | Additionally, u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
| 11205 | |
| 11206 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 11207 | AT_SYMLINK_NOFOLLOW. |
| 11208 | |
| 11209 | [EBADF] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
| 11210 | argument is neither AT_FDCWD nor a valid file |
| 11211 | descriptor. |
| 11212 | |
| 11213 | [ENOTDIR] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
| 11214 | argument is a valid file descriptor but it does not |
| 11215 | reference a directory. |
| 11216 | |
| 11217 | [EACCES] The _\bf_\bi_\bl_\be argument specifies a relative path but search |
| 11218 | permission is denied for the directory which the _\bf_\bd |
| 11219 | file descriptor references. |
| 11220 | |
| 11221 | f\bfu\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\ben\bns\bs() will fail if: |
| 11222 | |
| 11223 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
| 11224 | |
| 11225 | [EACCES] The _\bt_\bi_\bm_\be_\bs argument is NULL and the effective user ID |
| 11226 | of the process does not match the owner of the file, |
| 11227 | and is not the superuser, and write access is denied. |
| 11228 | |
| 11229 | [EFAULT] _\bt_\bi_\bm_\be_\bs points outside the process's allocated address |
| 11230 | space. |
| 11231 | |
| 11232 | [EIO] An I/O error occurred while reading or writing the |
| 11233 | affected inode. |
| 11234 | |
| 11235 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
| 11236 | process's effective user ID does not match the owner |
| 11237 | of the file and is not the superuser. |
| 11238 | |
| 11239 | [EROFS] The file system containing the file is mounted read- |
| 11240 | only. |
| 11241 | |
| 11242 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11243 | clock_gettime(2), stat(2), utime(3) |
| 11244 | |
| 11245 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11246 | The u\but\bti\bim\bme\bes\bs(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), and f\bfu\but\bti\bim\bme\ben\bns\bs() functions conform to IEEE Std |
| 11247 | 1003.1-2008 (``POSIX.1''). |
| 11248 | |
| 11249 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11250 | The predecessors of u\but\bti\bim\bme\bes\bs() were s\bsm\bmd\bda\bat\bte\be() in Version 1 AT&T UNIX, |
| 11251 | m\bmd\bda\bat\bte\be() in Version 3 AT&T UNIX, and u\but\bti\bim\bme\be() in Version 7 AT&T UNIX; the |
| 11252 | latter first supported the concept of an access time in addition to the |
| 11253 | modification time. |
| 11254 | |
| 11255 | The u\but\bti\bim\bme\bes\bs() function call appeared in 4.2BSD. The f\bfu\but\bti\bim\bme\bes\bs() function |
| 11256 | call appeared in NetBSD 1.2. The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() function |
| 11257 | calls appeared in OpenBSD 5.0. |
| 11258 | |
| 11259 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 11260 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and |
| 11261 | f\bfu\but\bti\bim\bme\ben\bns\bs() shall mark the last file status change timestamp (i.e. |
| 11262 | _\bs_\bt_\b__\bc_\bt_\bi_\bm) for update upon successful completion. However, currently some |
| 11263 | filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the |
| 11264 | modification timestamp argument. |
| 11265 | |
| 11266 | N\bNA\bAM\bME\bE |
| 11267 | u\but\bti\bim\bme\bes\bs, f\bfu\but\bti\bim\bme\bes\bs, u\but\bti\bim\bme\ben\bns\bsa\bat\bt, f\bfu\but\bti\bim\bme\ben\bns\bs - set file access and modification |
| 11268 | times |
| 11269 | |
| 11270 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11271 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 11272 | |
| 11273 | _\bi_\bn_\bt |
| 11274 | u\but\bti\bim\bme\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
| 11275 | |
| 11276 | _\bi_\bn_\bt |
| 11277 | f\bfu\but\bti\bim\bme\bes\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
| 11278 | |
| 11279 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 11280 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 11281 | |
| 11282 | _\bi_\bn_\bt |
| 11283 | u\but\bti\bim\bme\ben\bns\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b], |
| 11284 | _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 11285 | |
| 11286 | _\bi_\bn_\bt |
| 11287 | f\bfu\but\bti\bim\bme\ben\bns\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b]); |
| 11288 | |
| 11289 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11290 | The access and modification times of the file named by _\bp_\ba_\bt_\bh or referenced |
| 11291 | by _\bf_\bd are changed as specified by the argument _\bt_\bi_\bm_\be_\bs. |
| 11292 | |
| 11293 | If _\bt_\bi_\bm_\be_\bs is NULL, the access and modification times are set to the |
| 11294 | current time. The caller must be the owner of the file, have permission |
| 11295 | to write the file, or be the superuser. |
| 11296 | |
| 11297 | If _\bt_\bi_\bm_\be_\bs is non-null, it is assumed to point to an array of two timeval |
| 11298 | structures. The access time is set to the value of the first element, |
| 11299 | and the modification time is set to the value of the second element. The |
| 11300 | caller must be the owner of the file or be the superuser. |
| 11301 | |
| 11302 | In either case, the inode-change-time of the file is set to the current |
| 11303 | time. |
| 11304 | |
| 11305 | The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() are equivalent to u\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\bes\bs(), |
| 11306 | respectively, with the following differences. |
| 11307 | |
| 11308 | Both u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() take two timespec values instead of two |
| 11309 | timeval values. Further, either of the _\bt_\bv_\b__\bn_\bs_\be_\bc fields can be set to one |
| 11310 | of the following special values defined in <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>: |
| 11311 | |
| 11312 | UTIME_NOW Set the respective timestamp to the greatest value |
| 11313 | supported that is not greater than the current time. |
| 11314 | UTIME_OMIT Do not change the respective timestamp. |
| 11315 | |
| 11316 | Additionally, if the _\bp_\ba_\bt_\bh argument to u\but\bti\bim\bme\ben\bns\bsa\bat\bt() specifies a relative |
| 11317 | path, the file whose timestamps are changed is determined relative to the |
| 11318 | directory associated with file descriptor _\bf_\bd instead of the current |
| 11319 | working directory. |
| 11320 | |
| 11321 | If u\but\bti\bim\bme\ben\bns\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 11322 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 11323 | |
| 11324 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 11325 | values: |
| 11326 | |
| 11327 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
| 11328 | timestamps of the symbolic link are changed. |
| 11329 | |
| 11330 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11331 | Upon successful completion, the value 0 is returned; otherwise the |
| 11332 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 11333 | error. |
| 11334 | |
| 11335 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11336 | u\but\bti\bim\bme\bes\bs() and u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
| 11337 | |
| 11338 | [EACCES] Search permission is denied for a component of the |
| 11339 | path prefix; or the _\bt_\bi_\bm_\be_\bs argument is NULL and the |
| 11340 | effective user ID of the process does not match the |
| 11341 | owner of the file, and is not the superuser, and write |
| 11342 | access is denied. |
| 11343 | |
| 11344 | [EFAULT] _\bf_\bi_\bl_\be or _\bt_\bi_\bm_\be_\bs points outside the process's allocated |
| 11345 | address space. |
| 11346 | |
| 11347 | [EIO] An I/O error occurred while reading or writing the |
| 11348 | affected inode. |
| 11349 | |
| 11350 | [ELOOP] Too many symbolic links were encountered in |
| 11351 | translating the pathname. |
| 11352 | |
| 11353 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 11354 | characters, or an entire pathname (including the |
| 11355 | terminating NUL) exceeded PATH_MAX bytes. |
| 11356 | |
| 11357 | [ENOENT] The named file does not exist. |
| 11358 | |
| 11359 | [ENOTDIR] A component of the path prefix is not a directory. |
| 11360 | |
| 11361 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
| 11362 | process's effective user ID does not match the owner |
| 11363 | of the file and is not the superuser. |
| 11364 | |
| 11365 | [EROFS] The file system containing the file is mounted read- |
| 11366 | only. |
| 11367 | |
| 11368 | Additionally, u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
| 11369 | |
| 11370 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 11371 | AT_SYMLINK_NOFOLLOW. |
| 11372 | |
| 11373 | [EBADF] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
| 11374 | argument is neither AT_FDCWD nor a valid file |
| 11375 | descriptor. |
| 11376 | |
| 11377 | [ENOTDIR] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
| 11378 | argument is a valid file descriptor but it does not |
| 11379 | reference a directory. |
| 11380 | |
| 11381 | [EACCES] The _\bf_\bi_\bl_\be argument specifies a relative path but search |
| 11382 | permission is denied for the directory which the _\bf_\bd |
| 11383 | file descriptor references. |
| 11384 | |
| 11385 | f\bfu\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\ben\bns\bs() will fail if: |
| 11386 | |
| 11387 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
| 11388 | |
| 11389 | [EACCES] The _\bt_\bi_\bm_\be_\bs argument is NULL and the effective user ID |
| 11390 | of the process does not match the owner of the file, |
| 11391 | and is not the superuser, and write access is denied. |
| 11392 | |
| 11393 | [EFAULT] _\bt_\bi_\bm_\be_\bs points outside the process's allocated address |
| 11394 | space. |
| 11395 | |
| 11396 | [EIO] An I/O error occurred while reading or writing the |
| 11397 | affected inode. |
| 11398 | |
| 11399 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
| 11400 | process's effective user ID does not match the owner |
| 11401 | of the file and is not the superuser. |
| 11402 | |
| 11403 | [EROFS] The file system containing the file is mounted read- |
| 11404 | only. |
| 11405 | |
| 11406 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11407 | clock_gettime(2), stat(2), utime(3) |
| 11408 | |
| 11409 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11410 | The u\but\bti\bim\bme\bes\bs(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), and f\bfu\but\bti\bim\bme\ben\bns\bs() functions conform to IEEE Std |
| 11411 | 1003.1-2008 (``POSIX.1''). |
| 11412 | |
| 11413 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11414 | The predecessors of u\but\bti\bim\bme\bes\bs() were s\bsm\bmd\bda\bat\bte\be() in Version 1 AT&T UNIX, |
| 11415 | m\bmd\bda\bat\bte\be() in Version 3 AT&T UNIX, and u\but\bti\bim\bme\be() in Version 7 AT&T UNIX; the |
| 11416 | latter first supported the concept of an access time in addition to the |
| 11417 | modification time. |
| 11418 | |
| 11419 | The u\but\bti\bim\bme\bes\bs() function call appeared in 4.2BSD. The f\bfu\but\bti\bim\bme\bes\bs() function |
| 11420 | call appeared in NetBSD 1.2. The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() function |
| 11421 | calls appeared in OpenBSD 5.0. |
| 11422 | |
| 11423 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 11424 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and |
| 11425 | f\bfu\but\bti\bim\bme\ben\bns\bs() shall mark the last file status change timestamp (i.e. |
| 11426 | _\bs_\bt_\b__\bc_\bt_\bi_\bm) for update upon successful completion. However, currently some |
| 11427 | filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the |
| 11428 | modification timestamp argument. |
| 11429 | |
| 11430 | N\bNA\bAM\bME\bE |
| 11431 | g\bge\bet\btd\bde\ben\bnt\bts\bs - get directory entries in a filesystem independent format |
| 11432 | |
| 11433 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11434 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<d\bdi\bir\bre\ben\bnt\bt.\b.h\bh>\b> |
| 11435 | |
| 11436 | _\bi_\bn_\bt |
| 11437 | g\bge\bet\btd\bde\ben\bnt\bts\bs(_\bi_\bn_\bt _\bf_\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 11438 | |
| 11439 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11440 | g\bge\bet\btd\bde\ben\bnt\bts\bs() reads directory entries from the directory referenced by the |
| 11441 | file descriptor _\bf_\bd into the buffer pointed to by _\bb_\bu_\bf, in a filesystem |
| 11442 | independent format. Up to _\bn_\bb_\by_\bt_\be_\bs of data will be transferred. _\bn_\bb_\by_\bt_\be_\bs |
| 11443 | must be greater than or equal to the block size associated with the file |
| 11444 | (see stat(2)). Some filesystems may not support g\bge\bet\btd\bde\ben\bnt\bts\bs() with buffers |
| 11445 | smaller than this size. |
| 11446 | |
| 11447 | The data in the buffer is a series of _\bd_\bi_\br_\be_\bn_\bt structures each containing |
| 11448 | at least the following entries: |
| 11449 | |
| 11450 | ino_t d_fileno; |
| 11451 | off_t d_off; |
| 11452 | u_int16_t d_reclen; |
| 11453 | u_int8_t d_type; |
| 11454 | u_int8_t d_namlen; |
| 11455 | char d_name[MAXNAMLEN + 1]; /* see below */ |
| 11456 | |
| 11457 | The _\bd_\b__\bf_\bi_\bl_\be_\bn_\bo entry is a number which is unique for each distinct file in |
| 11458 | the filesystem. Files that are linked by hard links (see link(2)) have |
| 11459 | the same _\bd_\b__\bf_\bi_\bl_\be_\bn_\bo. The _\bd_\b__\bo_\bf_\bf entry is the file offset of the next entry. |
| 11460 | The _\bd_\b__\br_\be_\bc_\bl_\be_\bn entry is the length, in bytes, of the directory record. |
| 11461 | |
| 11462 | The _\bd_\b__\bt_\by_\bp_\be is the type of file, where the following are possible types: |
| 11463 | DT_UNKNOWN, DT_FIFO, DT_CHR, DT_DIR, DT_BLK, DT_REG, DT_LNK, and DT_SOCK. |
| 11464 | |
| 11465 | The _\bd_\b__\bn_\ba_\bm_\bl_\be_\bn entry specifies the length of the file name excluding the |
| 11466 | NUL byte. Thus the actual size of _\bd_\b__\bn_\ba_\bm_\be may vary from 1 to MAXNAMLEN + |
| 11467 | 1. |
| 11468 | |
| 11469 | The _\bd_\b__\bn_\ba_\bm_\be entry contains a NUL-terminated file name. |
| 11470 | |
| 11471 | Entries may be separated by extra space. The _\bd_\b__\br_\be_\bc_\bl_\be_\bn entry may be used |
| 11472 | as an offset from the start of a _\bd_\bi_\br_\be_\bn_\bt structure to the next structure, |
| 11473 | if any. |
| 11474 | |
| 11475 | Invalid entries with _\bd_\b__\bf_\bi_\bl_\be_\bn_\bo set to 0 may be returned among regular |
| 11476 | entries. |
| 11477 | |
| 11478 | The actual number of bytes transferred is returned. The current position |
| 11479 | pointer associated with _\bf_\bd is set to point to the next block of entries. |
| 11480 | The pointer may not advance by the number of bytes returned by |
| 11481 | g\bge\bet\btd\bde\ben\bnt\bts\bs(). |
| 11482 | |
| 11483 | The current position pointer may be set and retrieved by lseek(2). The |
| 11484 | current position pointer should only be set to a value returned by |
| 11485 | lseek(2), the value of _\bd_\b__\bo_\bf_\bf from an entry, or zero. |
| 11486 | |
| 11487 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11488 | If successful, the number of bytes actually transferred is returned. A |
| 11489 | value of zero is returned when the end of the directory has been reached. |
| 11490 | Otherwise, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to |
| 11491 | indicate the error. |
| 11492 | |
| 11493 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11494 | g\bge\bet\btd\bde\ben\bnt\bts\bs() will fail if: |
| 11495 | |
| 11496 | [EBADF] _\bf_\bd is not a valid file descriptor open for reading. |
| 11497 | |
| 11498 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 11499 | address space. |
| 11500 | |
| 11501 | [EINVAL] The file referenced by _\bf_\bd is not a directory, or |
| 11502 | _\bn_\bb_\by_\bt_\be_\bs is too small for returning a directory entry or |
| 11503 | block of entries, or the current position pointer is |
| 11504 | invalid. |
| 11505 | |
| 11506 | [EIO] An I/O error occurred while reading from or writing to |
| 11507 | the file system. |
| 11508 | |
| 11509 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11510 | lseek(2), open(2), opendir(3), dirent(5) |
| 11511 | |
| 11512 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11513 | The g\bge\bet\btd\bde\ben\bnt\bts\bs() call is not a portable interface and should not be used |
| 11514 | directly by applications. Use readdir(3) instead. |
| 11515 | |
| 11516 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11517 | The g\bge\bet\btd\bdi\bir\bre\ben\bnt\btr\bri\bie\bes\bs() function first appeared in 4.4BSD. In OpenBSD 5.5 |
| 11518 | the _\bd_\b__\bo_\bf_\bf entry was added to _\bs_\bt_\br_\bu_\bc_\bt _\bd_\bi_\br_\be_\bn_\bt and g\bge\bet\btd\bdi\bir\bre\ben\bnt\btr\bri\bie\bes\bs() was |
| 11519 | replaced with g\bge\bet\btd\bde\ben\bnt\bts\bs(). |
| 11520 | |
| 11521 | N\bNA\bAM\bME\bE |
| 11522 | g\bge\bet\btd\bdt\bta\bab\bbl\ble\bec\bco\bou\bun\bnt\bt - get descriptor table count |
| 11523 | |
| 11524 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11525 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 11526 | |
| 11527 | _\bi_\bn_\bt |
| 11528 | g\bge\bet\btd\bdt\bta\bab\bbl\ble\bec\bco\bou\bun\bnt\bt(_\bv_\bo_\bi_\bd); |
| 11529 | |
| 11530 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11531 | k\bkq\bqu\bue\beu\bue\be returns the number of file descriptors the process currently has |
| 11532 | open. |
| 11533 | |
| 11534 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11535 | getrlimit(2), getdtablesize(3) |
| 11536 | |
| 11537 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11538 | The k\bkq\bqu\bue\beu\bue\be function appeared in OpenBSD 5.2. |
| 11539 | |
| 11540 | N\bNA\bAM\bME\bE |
| 11541 | g\bge\bet\btg\bgi\bid\bd, g\bge\bet\bte\beg\bgi\bid\bd - get group process identification |
| 11542 | |
| 11543 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11544 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 11545 | |
| 11546 | _\bg_\bi_\bd_\b__\bt |
| 11547 | g\bge\bet\btg\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
| 11548 | |
| 11549 | _\bg_\bi_\bd_\b__\bt |
| 11550 | g\bge\bet\bte\beg\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
| 11551 | |
| 11552 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11553 | The g\bge\bet\btg\bgi\bid\bd() function returns the real group ID of the calling process |
| 11554 | and the g\bge\bet\bte\beg\bgi\bid\bd() function returns the effective group ID of the calling |
| 11555 | process. |
| 11556 | |
| 11557 | The real group ID is specified at login time. |
| 11558 | |
| 11559 | The real group ID is the group of the user who invoked the program. As |
| 11560 | the effective group ID gives the process additional permissions during |
| 11561 | the execution of ``_\bs_\be_\bt_\b-_\bg_\br_\bo_\bu_\bp_\b-_\bI_\bD'' mode processes, g\bge\bet\btg\bgi\bid\bd() is used to |
| 11562 | determine the real group ID of the calling process. |
| 11563 | |
| 11564 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11565 | The g\bge\bet\btg\bgi\bid\bd() and g\bge\bet\bte\beg\bgi\bid\bd() functions are always successful, and no return |
| 11566 | value is reserved to indicate an error. |
| 11567 | |
| 11568 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11569 | getgroups(2), getresgid(2), getuid(2), setgid(2), setregid(2) |
| 11570 | |
| 11571 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11572 | The g\bge\bet\btg\bgi\bid\bd() and g\bge\bet\bte\beg\bgi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 11573 | (``POSIX.1''). |
| 11574 | |
| 11575 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11576 | The g\bge\bet\btg\bgi\bid\bd() system call first appeared in Version 4 AT&T UNIX, and |
| 11577 | g\bge\bet\bte\beg\bgi\bid\bd() in Version 7 AT&T UNIX. |
| 11578 | |
| 11579 | N\bNA\bAM\bME\bE |
| 11580 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by - get entropy |
| 11581 | |
| 11582 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11583 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 11584 | |
| 11585 | _\bi_\bn_\bt |
| 11586 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by(_\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bl_\be_\bn); |
| 11587 | |
| 11588 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11589 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by() fills a buffer with high-quality entropy, which can be used |
| 11590 | as input for process-context pseudorandom generators like arc4random(3). |
| 11591 | |
| 11592 | The maximum buffer size permitted is 256 bytes. If _\bb_\bu_\bf_\bl_\be_\bn exceeds this, |
| 11593 | an error of EIO will be indicated. |
| 11594 | |
| 11595 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by() is not intended for regular code; please use the |
| 11596 | arc4random(3) family of functions instead. |
| 11597 | |
| 11598 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11599 | Upon successful completion, the value 0 is returned; otherwise the |
| 11600 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 11601 | error. |
| 11602 | |
| 11603 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11604 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by() will succeed unless: |
| 11605 | |
| 11606 | [EFAULT] The _\bb_\bu_\bf parameter points to an invalid address. |
| 11607 | |
| 11608 | [EIO] Too many bytes requested, or some other fatal error |
| 11609 | occurred. |
| 11610 | |
| 11611 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11612 | arc4random(3) |
| 11613 | |
| 11614 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11615 | The g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by() function appeared in OpenBSD 5.6. |
| 11616 | |
| 11617 | N\bNA\bAM\bME\bE |
| 11618 | g\bge\bet\btu\bui\bid\bd, g\bge\bet\bte\beu\bui\bid\bd - get user identification |
| 11619 | |
| 11620 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11621 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 11622 | |
| 11623 | _\bu_\bi_\bd_\b__\bt |
| 11624 | g\bge\bet\btu\bui\bid\bd(_\bv_\bo_\bi_\bd); |
| 11625 | |
| 11626 | _\bu_\bi_\bd_\b__\bt |
| 11627 | g\bge\bet\bte\beu\bui\bid\bd(_\bv_\bo_\bi_\bd); |
| 11628 | |
| 11629 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11630 | The g\bge\bet\btu\bui\bid\bd() function returns the real user ID of the calling process. |
| 11631 | The g\bge\bet\bte\beu\bui\bid\bd() function returns the effective user ID of the calling |
| 11632 | process. |
| 11633 | |
| 11634 | The real user ID is that of the user who has invoked the program. As the |
| 11635 | effective user ID gives the process additional permissions during |
| 11636 | execution of ``_\bs_\be_\bt_\b-_\bu_\bs_\be_\br_\b-_\bI_\bD'' mode processes, g\bge\bet\btu\bui\bid\bd() is used to |
| 11637 | determine the real user ID of the calling process. |
| 11638 | |
| 11639 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11640 | The g\bge\bet\btu\bui\bid\bd() and g\bge\bet\bte\beu\bui\bid\bd() functions are always successful, and no return |
| 11641 | value is reserved to indicate an error. |
| 11642 | |
| 11643 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11644 | getgid(2), getresuid(2), setreuid(2), setuid(2) |
| 11645 | |
| 11646 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11647 | The g\bge\bet\btu\bui\bid\bd() and g\bge\bet\bte\beu\bui\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 11648 | (``POSIX.1''). |
| 11649 | |
| 11650 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11651 | The g\bge\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX, and |
| 11652 | g\bge\bet\bte\beu\bui\bid\bd() in Version 7 AT&T UNIX. |
| 11653 | |
| 11654 | N\bNA\bAM\bME\bE |
| 11655 | g\bge\bet\btf\bfh\bh - get file handle |
| 11656 | |
| 11657 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11658 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 11659 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
| 11660 | |
| 11661 | _\bi_\bn_\bt |
| 11662 | g\bge\bet\btf\bfh\bh(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp); |
| 11663 | |
| 11664 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11665 | g\bge\bet\btf\bfh\bh() returns a file handle for the specified file or directory _\bp_\ba_\bt_\bh in |
| 11666 | the file handle pointed to by _\bf_\bh_\bp. This system call is restricted to the |
| 11667 | superuser. |
| 11668 | |
| 11669 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11670 | Upon successful completion, the value 0 is returned; otherwise the |
| 11671 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 11672 | error. |
| 11673 | |
| 11674 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11675 | g\bge\bet\btf\bfh\bh() fails if one or more of the following are true: |
| 11676 | |
| 11677 | [ENOTDIR] A component of the path prefix of _\bp_\ba_\bt_\bh is not a |
| 11678 | directory. |
| 11679 | |
| 11680 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 11681 | characters, or an entire pathname (including the |
| 11682 | terminating NUL) exceeded PATH_MAX bytes. |
| 11683 | |
| 11684 | [ENOENT] The file referred to by _\bp_\ba_\bt_\bh does not exist. |
| 11685 | |
| 11686 | [EACCES] Search permission is denied for a component of the |
| 11687 | path prefix of _\bp_\ba_\bt_\bh. |
| 11688 | |
| 11689 | [ELOOP] Too many symbolic links were encountered in |
| 11690 | translating _\bp_\ba_\bt_\bh. |
| 11691 | |
| 11692 | [EPERM] The effective user ID is not the superuser. |
| 11693 | |
| 11694 | [EFAULT] _\bf_\bh_\bp or _\bp_\ba_\bt_\bh points to an invalid address. |
| 11695 | |
| 11696 | [EIO] An I/O error occurred while reading from or writing to |
| 11697 | the file system. |
| 11698 | |
| 11699 | [EINVAL] A portion of _\bp_\ba_\bt_\bh refers to a remote file system. |
| 11700 | |
| 11701 | [EOPNOTSUPP] A portion of _\bp_\ba_\bt_\bh refers to a remote file system. |
| 11702 | |
| 11703 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11704 | fhstat(2) |
| 11705 | |
| 11706 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11707 | The g\bge\bet\btf\bfh\bh() function first appeared in 4.4BSD. |
| 11708 | |
| 11709 | N\bNA\bAM\bME\bE |
| 11710 | g\bge\bet\btf\bfs\bss\bst\bta\bat\bt - get list of all mounted file systems |
| 11711 | |
| 11712 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11713 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 11714 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
| 11715 | |
| 11716 | _\bi_\bn_\bt |
| 11717 | g\bge\bet\btf\bfs\bss\bst\bta\bat\bt(_\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 11718 | |
| 11719 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11720 | g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() returns information about all mounted file systems. _\bb_\bu_\bf is a |
| 11721 | pointer to an array of statfs(2) structures defined as follows: |
| 11722 | |
| 11723 | typedef struct { int32_t val[2]; } fsid_t; |
| 11724 | |
| 11725 | #define MFSNAMELEN 16 /* length of fs type name, including nul */ |
| 11726 | #define MNAMELEN 90 /* length of buffer for returned name */ |
| 11727 | |
| 11728 | struct statfs { |
| 11729 | u_int32_t f_flags; /* copy of mount flags */ |
| 11730 | u_int32_t f_bsize; /* file system block size */ |
| 11731 | u_int32_t f_iosize; /* optimal transfer block size */ |
| 11732 | |
| 11733 | /* unit is f_bsize */ |
| 11734 | u_int64_t f_blocks; /* total data blocks in file system */ |
| 11735 | u_int64_t f_bfree; /* free blocks in fs */ |
| 11736 | int64_t f_bavail; /* free blocks avail to non-superuser */ |
| 11737 | |
| 11738 | u_int64_t f_files; /* total file nodes in file system */ |
| 11739 | u_int64_t f_ffree; /* free file nodes in fs */ |
| 11740 | int64_t f_favail; /* free file nodes avail to non-root */ |
| 11741 | |
| 11742 | u_int64_t f_syncwrites; /* count of sync writes since mount */ |
| 11743 | u_int64_t f_syncreads; /* count of sync reads since mount */ |
| 11744 | u_int64_t f_asyncwrites; /* count of async writes since mount */ |
| 11745 | u_int64_t f_asyncreads; /* count of async reads since mount */ |
| 11746 | |
| 11747 | fsid_t f_fsid; /* file system id */ |
| 11748 | u_int32_t f_namemax; /* maximum filename length */ |
| 11749 | uid_t f_owner; /* user that mounted the file system */ |
| 11750 | u_int64_t f_ctime; /* last mount [-u] time */ |
| 11751 | |
| 11752 | char f_fstypename[MFSNAMELEN]; /* fs type name */ |
| 11753 | char f_mntonname[MNAMELEN]; /* directory on which mounted */ |
| 11754 | char f_mntfromname[MNAMELEN]; /* mounted file system */ |
| 11755 | char f_mntfromspec[MNAMELEN]; /* special for mount request */ |
| 11756 | union mount_info mount_info; /* per-filesystem mount options */ |
| 11757 | }; |
| 11758 | |
| 11759 | The buffer is filled with an array of _\bs_\bt_\ba_\bt_\bf_\bs structures, one for each |
| 11760 | mounted file system up to the size specified by _\bb_\bu_\bf_\bs_\bi_\bz_\be. |
| 11761 | |
| 11762 | If _\bb_\bu_\bf is NULL, g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() returns just the number of mounted file |
| 11763 | systems. |
| 11764 | |
| 11765 | Normally _\bf_\bl_\ba_\bg_\bs should be specified as MNT_WAIT. If _\bf_\bl_\ba_\bg_\bs is set to |
| 11766 | MNT_NOWAIT, g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() will return the information it has available |
| 11767 | without requesting an update from each file system. Thus, some of the |
| 11768 | information will be out of date, but g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() will not block waiting |
| 11769 | for information from a file system that is unable to respond. If no |
| 11770 | flags are provided, MNT_WAIT is assumed. |
| 11771 | |
| 11772 | Note that _\bf_\b__\bf_\bs_\bi_\bd will be empty unless the user is the superuser. |
| 11773 | |
| 11774 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11775 | Upon successful completion, the number of _\bs_\bt_\ba_\bt_\bf_\bs structures is returned. |
| 11776 | Otherwise, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to |
| 11777 | indicate the error. |
| 11778 | |
| 11779 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11780 | g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() fails if one or more of the following are true: |
| 11781 | |
| 11782 | [EFAULT] _\bb_\bu_\bf points to an invalid address. |
| 11783 | |
| 11784 | [EIO] An I/O error occurred while reading from or writing to |
| 11785 | the file system. |
| 11786 | |
| 11787 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11788 | statfs(2), fstab(5), mount(8) |
| 11789 | |
| 11790 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11791 | The g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() function first appeared in 4.4BSD. |
| 11792 | |
| 11793 | N\bNA\bAM\bME\bE |
| 11794 | g\bge\bet\btg\bgi\bid\bd, g\bge\bet\bte\beg\bgi\bid\bd - get group process identification |
| 11795 | |
| 11796 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11797 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 11798 | |
| 11799 | _\bg_\bi_\bd_\b__\bt |
| 11800 | g\bge\bet\btg\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
| 11801 | |
| 11802 | _\bg_\bi_\bd_\b__\bt |
| 11803 | g\bge\bet\bte\beg\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
| 11804 | |
| 11805 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11806 | The g\bge\bet\btg\bgi\bid\bd() function returns the real group ID of the calling process |
| 11807 | and the g\bge\bet\bte\beg\bgi\bid\bd() function returns the effective group ID of the calling |
| 11808 | process. |
| 11809 | |
| 11810 | The real group ID is specified at login time. |
| 11811 | |
| 11812 | The real group ID is the group of the user who invoked the program. As |
| 11813 | the effective group ID gives the process additional permissions during |
| 11814 | the execution of ``_\bs_\be_\bt_\b-_\bg_\br_\bo_\bu_\bp_\b-_\bI_\bD'' mode processes, g\bge\bet\btg\bgi\bid\bd() is used to |
| 11815 | determine the real group ID of the calling process. |
| 11816 | |
| 11817 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11818 | The g\bge\bet\btg\bgi\bid\bd() and g\bge\bet\bte\beg\bgi\bid\bd() functions are always successful, and no return |
| 11819 | value is reserved to indicate an error. |
| 11820 | |
| 11821 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11822 | getgroups(2), getresgid(2), getuid(2), setgid(2), setregid(2) |
| 11823 | |
| 11824 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11825 | The g\bge\bet\btg\bgi\bid\bd() and g\bge\bet\bte\beg\bgi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 11826 | (``POSIX.1''). |
| 11827 | |
| 11828 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11829 | The g\bge\bet\btg\bgi\bid\bd() system call first appeared in Version 4 AT&T UNIX, and |
| 11830 | g\bge\bet\bte\beg\bgi\bid\bd() in Version 7 AT&T UNIX. |
| 11831 | |
| 11832 | N\bNA\bAM\bME\bE |
| 11833 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs - get group access list |
| 11834 | |
| 11835 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11836 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 11837 | |
| 11838 | _\bi_\bn_\bt |
| 11839 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs(_\bi_\bn_\bt _\bg_\bi_\bd_\bs_\be_\bt_\bl_\be_\bn, _\bg_\bi_\bd_\b__\bt _\b*_\bg_\bi_\bd_\bs_\be_\bt); |
| 11840 | |
| 11841 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11842 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() gets the current group access list of the current user |
| 11843 | process and stores it in the array _\bg_\bi_\bd_\bs_\be_\bt. The parameter _\bg_\bi_\bd_\bs_\be_\bt_\bl_\be_\bn |
| 11844 | indicates the number of entries that may be placed in _\bg_\bi_\bd_\bs_\be_\bt. |
| 11845 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() returns the actual number of groups returned in _\bg_\bi_\bd_\bs_\be_\bt. No |
| 11846 | more than {NGROUPS_MAX} will ever be returned. If _\bg_\bi_\bd_\bs_\be_\bt_\bl_\be_\bn is 0, |
| 11847 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() returns the number of groups without modifying the _\bg_\bi_\bd_\bs_\be_\bt |
| 11848 | array. |
| 11849 | |
| 11850 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11851 | A successful call returns the number of groups in the group set. A value |
| 11852 | of -1 indicates that an error occurred, and the error code is stored in |
| 11853 | the global variable _\be_\br_\br_\bn_\bo. |
| 11854 | |
| 11855 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11856 | The possible errors for g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() are: |
| 11857 | |
| 11858 | [EINVAL] The argument _\bg_\bi_\bd_\bs_\be_\bt_\bl_\be_\bn is smaller than the number of |
| 11859 | groups in the group set. |
| 11860 | |
| 11861 | [EFAULT] The argument _\bg_\bi_\bd_\bs_\be_\bt specifies an invalid address. |
| 11862 | |
| 11863 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11864 | getgid(2), setgid(2), setgroups(2), initgroups(3) |
| 11865 | |
| 11866 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11867 | The g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 11868 | |
| 11869 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11870 | The g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() system call first appeared in 4.1cBSD. |
| 11871 | |
| 11872 | N\bNA\bAM\bME\bE |
| 11873 | g\bge\bet\bti\bit\bti\bim\bme\ber\br, s\bse\bet\bti\bit\bti\bim\bme\ber\br - get/set value of interval timer |
| 11874 | |
| 11875 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11876 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 11877 | |
| 11878 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_R\bRE\bEA\bAL\bL 0\b0 |
| 11879 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_V\bVI\bIR\bRT\bTU\bUA\bAL\bL 1\b1 |
| 11880 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_P\bPR\bRO\bOF\bF 2\b2 |
| 11881 | |
| 11882 | _\bi_\bn_\bt |
| 11883 | g\bge\bet\bti\bit\bti\bim\bme\ber\br(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bv_\ba_\bl_\bu_\be); |
| 11884 | |
| 11885 | _\bi_\bn_\bt |
| 11886 | s\bse\bet\bti\bit\bti\bim\bme\ber\br(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bv_\ba_\bl_\bu_\be, |
| 11887 | _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bo_\bv_\ba_\bl_\bu_\be); |
| 11888 | |
| 11889 | _\bv_\bo_\bi_\bd |
| 11890 | t\bti\bim\bme\ber\brc\bcl\ble\bea\bar\br(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*); |
| 11891 | |
| 11892 | _\bi_\bn_\bt |
| 11893 | t\bti\bim\bme\ber\bri\bis\bss\bse\bet\bt(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*); |
| 11894 | |
| 11895 | _\bi_\bn_\bt |
| 11896 | t\bti\bim\bme\ber\brc\bcm\bmp\bp(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bC_\bM_\bP); |
| 11897 | |
| 11898 | _\bv_\bo_\bi_\bd |
| 11899 | t\bti\bim\bme\ber\brs\bsu\bub\bb(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\br_\be_\bs); |
| 11900 | |
| 11901 | _\bv_\bo_\bi_\bd |
| 11902 | t\bti\bim\bme\ber\bra\bad\bdd\bd(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\br_\be_\bs); |
| 11903 | |
| 11904 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11905 | The system provides each process with three interval timers, defined in |
| 11906 | <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. The g\bge\bet\bti\bit\bti\bim\bme\ber\br() call returns the current value for the |
| 11907 | timer specified in _\bw_\bh_\bi_\bc_\bh in the structure at _\bv_\ba_\bl_\bu_\be. The s\bse\bet\bti\bit\bti\bim\bme\ber\br() call |
| 11908 | sets a timer to the specified _\bv_\ba_\bl_\bu_\be (returning the previous value of the |
| 11909 | timer if _\bo_\bv_\ba_\bl_\bu_\be is non-null). |
| 11910 | |
| 11911 | A timer value is defined by the _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl structure: |
| 11912 | |
| 11913 | struct itimerval { |
| 11914 | struct timeval it_interval; /* timer interval */ |
| 11915 | struct timeval it_value; /* current value */ |
| 11916 | }; |
| 11917 | |
| 11918 | If _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be is non-zero, it indicates the time to the next timer |
| 11919 | expiration. If _\bi_\bt_\b__\bi_\bn_\bt_\be_\br_\bv_\ba_\bl is non-zero, it specifies a value to be used |
| 11920 | in reloading _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be when the timer expires. Setting _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be to 0 |
| 11921 | disables a timer. Setting _\bi_\bt_\b__\bi_\bn_\bt_\be_\br_\bv_\ba_\bl to 0 causes a timer to be disabled |
| 11922 | after its next expiration (assuming _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be is non-zero). |
| 11923 | |
| 11924 | Time values smaller than the resolution of the system clock are rounded |
| 11925 | up to this resolution (typically 10 milliseconds). |
| 11926 | |
| 11927 | The ITIMER_REAL timer decrements in real time. A SIGALRM signal is |
| 11928 | delivered when this timer expires. |
| 11929 | |
| 11930 | The ITIMER_VIRTUAL timer decrements in process virtual time. It runs |
| 11931 | only when the process is executing. A SIGVTALRM signal is delivered when |
| 11932 | it expires. |
| 11933 | |
| 11934 | The ITIMER_PROF timer decrements both in process virtual time and when |
| 11935 | the system is running on behalf of the process. It is designed to be |
| 11936 | used by interpreters in statistically profiling the execution of |
| 11937 | interpreted programs. Each time the ITIMER_PROF timer expires, the |
| 11938 | SIGPROF signal is delivered. Because this signal may interrupt in- |
| 11939 | progress system calls, programs using this timer must be prepared to |
| 11940 | restart interrupted system calls. |
| 11941 | |
| 11942 | The remaining five functions are in fact macros for manipulating time |
| 11943 | values, defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. |
| 11944 | |
| 11945 | t\bti\bim\bme\ber\brc\bcl\ble\bea\bar\br(_\ba) sets the time value in _\ba to zero. |
| 11946 | |
| 11947 | t\bti\bim\bme\ber\bri\bis\bss\bse\bet\bt(_\ba) tests if the time value in _\ba is non-zero. |
| 11948 | |
| 11949 | t\bti\bim\bme\ber\brc\bcm\bmp\bp(_\ba, _\bb, _\bC_\bM_\bP) compares two time values in the form _\ba CMP _\bb, where |
| 11950 | _\bC_\bM_\bP is <, <=, ==, !=, >=, or > . |
| 11951 | |
| 11952 | t\bti\bim\bme\ber\brs\bsu\bub\bb(_\ba, _\bb, _\br_\be_\bs) subtracts _\ba - _\bb and stores the result in _\br_\be_\bs. |
| 11953 | |
| 11954 | t\bti\bim\bme\ber\bra\bad\bdd\bd(_\ba, _\bb, _\br_\be_\bs) adds two timers and stores the result in _\br_\be_\bs. |
| 11955 | |
| 11956 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 11957 | Upon successful completion, the value 0 is returned; otherwise the |
| 11958 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 11959 | error. |
| 11960 | |
| 11961 | E\bER\bRR\bRO\bOR\bRS\bS |
| 11962 | g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() will fail if: |
| 11963 | |
| 11964 | [EFAULT] The _\bv_\ba_\bl_\bu_\be parameter specified a bad address. |
| 11965 | |
| 11966 | [EINVAL] An unrecognized value for _\bw_\bh_\bi_\bc_\bh was specified. |
| 11967 | |
| 11968 | In addition, s\bse\bet\bti\bit\bti\bim\bme\ber\br() may return the following error: |
| 11969 | |
| 11970 | [EINVAL] _\bv_\ba_\bl_\bu_\be or _\bo_\bv_\ba_\bl_\bu_\be specified a time that was too large to |
| 11971 | be handled. |
| 11972 | |
| 11973 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 11974 | clock_gettime(2), gettimeofday(2), poll(2), select(2), sigaction(2) |
| 11975 | |
| 11976 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 11977 | The g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() functions conform to IEEE Std 1003.1-2008 |
| 11978 | (``POSIX.1''). |
| 11979 | |
| 11980 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 11981 | The g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() system calls first appeared in 4.1cBSD. |
| 11982 | |
| 11983 | N\bNA\bAM\bME\bE |
| 11984 | g\bge\bet\btl\blo\bog\bgi\bin\bn, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br, s\bse\bet\btl\blo\bog\bgi\bin\bn - get/set login name |
| 11985 | |
| 11986 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 11987 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 11988 | |
| 11989 | _\bc_\bh_\ba_\br _\b* |
| 11990 | g\bge\bet\btl\blo\bog\bgi\bin\bn(_\bv_\bo_\bi_\bd); |
| 11991 | |
| 11992 | _\bi_\bn_\bt |
| 11993 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br(_\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bi_\bz_\be_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
| 11994 | |
| 11995 | _\bi_\bn_\bt |
| 11996 | s\bse\bet\btl\blo\bog\bgi\bin\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); |
| 11997 | |
| 11998 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 11999 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() routine returns the login name of the user associated with |
| 12000 | the current session, as previously set by s\bse\bet\btl\blo\bog\bgi\bin\bn(). The name is |
| 12001 | normally associated with a login shell at the time a session is created, |
| 12002 | and is inherited by all processes descended from the login shell. (This |
| 12003 | is true even if some of those processes assume another user ID, for |
| 12004 | example when su(1) is used.) |
| 12005 | |
| 12006 | The g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() routine is a reentrant version of g\bge\bet\btl\blo\bog\bgi\bin\bn(). It is |
| 12007 | functionally identical to g\bge\bet\btl\blo\bog\bgi\bin\bn() except that the caller must provide |
| 12008 | a buffer, _\bn_\ba_\bm_\be, in which to store the user's login name and a |
| 12009 | corresponding length parameter, _\bn_\ba_\bm_\be_\bl_\be_\bn, that specifies the size of the |
| 12010 | buffer. The buffer should be large enough to store the login name and a |
| 12011 | trailing NUL (typically LOGIN_NAME_MAX bytes). |
| 12012 | |
| 12013 | s\bse\bet\btl\blo\bog\bgi\bin\bn() sets the login name of the user associated with the current |
| 12014 | session to _\bn_\ba_\bm_\be. This call is restricted to the superuser, and is |
| 12015 | normally used only when a new session is being created on behalf of the |
| 12016 | named user (for example, at login time, or when a remote shell is |
| 12017 | invoked). |
| 12018 | |
| 12019 | _\bN_\bO_\bT_\bE: There is only one login name per session. |
| 12020 | |
| 12021 | It is _\bC_\bR_\bI_\bT_\bI_\bC_\bA_\bL_\bL_\bY important to ensure that s\bse\bet\btl\blo\bog\bgi\bin\bn() is only ever called |
| 12022 | after the process has taken adequate steps to ensure that it is detached |
| 12023 | from its parent's session. The _\bO_\bN_\bL_\bY way to do this is via the s\bse\bet\bts\bsi\bid\bd() |
| 12024 | function. The d\bda\bae\bem\bmo\bon\bn() function calls s\bse\bet\bts\bsi\bid\bd() which is an ideal way of |
| 12025 | detaching from a controlling terminal and forking into the background. |
| 12026 | |
| 12027 | In particular, neither i\bio\boc\bct\btl\bl(_\bt_\bt_\by_\bf_\bd, _\bT_\bI_\bO_\bC_\bN_\bO_\bT_\bT_\bY, _\b._\b._\b.) nor s\bse\bet\btp\bpg\bgr\brp\bp(_\b._\b._\b.) is |
| 12028 | sufficient to create a new session. |
| 12029 | |
| 12030 | Once a parent process has called s\bse\bet\bts\bsi\bid\bd(), it is acceptable for some |
| 12031 | child of that process to then call s\bse\bet\btl\blo\bog\bgi\bin\bn(), even though it is not the |
| 12032 | session leader. Beware, however, that _\bA_\bL_\bL processes in the session will |
| 12033 | change their login name at the same time, even the parent. |
| 12034 | |
| 12035 | This is different from traditional UNIX privilege inheritance and as such |
| 12036 | can be counter-intuitive. |
| 12037 | |
| 12038 | Since the s\bse\bet\btl\blo\bog\bgi\bin\bn() routine is restricted to the super-user, it is |
| 12039 | assumed that (like all other privileged programs) the programmer has |
| 12040 | taken adequate precautions to prevent security violations. |
| 12041 | |
| 12042 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12043 | If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn() succeeds, it returns a pointer to a NUL- |
| 12044 | terminated string in a static buffer. If the name has not been set, it |
| 12045 | returns NULL. If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() succeeds, a value of 0 is |
| 12046 | returned, else the error number is returned. If a call to s\bse\bet\btl\blo\bog\bgi\bin\bn() |
| 12047 | succeeds, a value of 0 is returned. If s\bse\bet\btl\blo\bog\bgi\bin\bn() fails, a value of -1 |
| 12048 | is returned and an error code is placed in the global location _\be_\br_\br_\bn_\bo. |
| 12049 | |
| 12050 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12051 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() and s\bse\bet\btl\blo\bog\bgi\bin\bn() will succeed unless: |
| 12052 | |
| 12053 | [EFAULT] The _\bn_\ba_\bm_\be parameter points to an invalid address. |
| 12054 | |
| 12055 | In addition, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() may return the following error: |
| 12056 | |
| 12057 | [ERANGE] The value of _\bn_\ba_\bm_\be_\bl_\be_\bn is not large enough to store the |
| 12058 | user's login name and a trailing NUL. |
| 12059 | |
| 12060 | s\bse\bet\btl\blo\bog\bgi\bin\bn() may return the following errors: |
| 12061 | |
| 12062 | [EINVAL] The _\bn_\ba_\bm_\be parameter pointed to a string that was too |
| 12063 | long. Login names are limited to LOGIN_NAME_MAX-1 |
| 12064 | characters, currently 31. |
| 12065 | |
| 12066 | [EPERM] The caller tried to set the login name and was not the |
| 12067 | superuser. |
| 12068 | |
| 12069 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12070 | setsid(2) |
| 12071 | |
| 12072 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12073 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() and g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() functions conform to IEEE Std 1003.1-2008 |
| 12074 | (``POSIX.1''). |
| 12075 | |
| 12076 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12077 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() function first appeared in 4.2BSD. |
| 12078 | |
| 12079 | B\bBU\bUG\bGS\bS |
| 12080 | In earlier versions of the system, g\bge\bet\btl\blo\bog\bgi\bin\bn() failed unless the process |
| 12081 | was associated with a login terminal. The current implementation (using |
| 12082 | s\bse\bet\btl\blo\bog\bgi\bin\bn()) allows getlogin to succeed even when the process has no |
| 12083 | controlling terminal. In earlier versions of the system, the value |
| 12084 | returned by g\bge\bet\btl\blo\bog\bgi\bin\bn() could not be trusted without checking the user ID. |
| 12085 | Portable programs should probably still make this check. |
| 12086 | |
| 12087 | N\bNA\bAM\bME\bE |
| 12088 | g\bge\bet\btl\blo\bog\bgi\bin\bn, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br, s\bse\bet\btl\blo\bog\bgi\bin\bn - get/set login name |
| 12089 | |
| 12090 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12091 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 12092 | |
| 12093 | _\bc_\bh_\ba_\br _\b* |
| 12094 | g\bge\bet\btl\blo\bog\bgi\bin\bn(_\bv_\bo_\bi_\bd); |
| 12095 | |
| 12096 | _\bi_\bn_\bt |
| 12097 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br(_\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bi_\bz_\be_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
| 12098 | |
| 12099 | _\bi_\bn_\bt |
| 12100 | s\bse\bet\btl\blo\bog\bgi\bin\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); |
| 12101 | |
| 12102 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12103 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() routine returns the login name of the user associated with |
| 12104 | the current session, as previously set by s\bse\bet\btl\blo\bog\bgi\bin\bn(). The name is |
| 12105 | normally associated with a login shell at the time a session is created, |
| 12106 | and is inherited by all processes descended from the login shell. (This |
| 12107 | is true even if some of those processes assume another user ID, for |
| 12108 | example when su(1) is used.) |
| 12109 | |
| 12110 | The g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() routine is a reentrant version of g\bge\bet\btl\blo\bog\bgi\bin\bn(). It is |
| 12111 | functionally identical to g\bge\bet\btl\blo\bog\bgi\bin\bn() except that the caller must provide |
| 12112 | a buffer, _\bn_\ba_\bm_\be, in which to store the user's login name and a |
| 12113 | corresponding length parameter, _\bn_\ba_\bm_\be_\bl_\be_\bn, that specifies the size of the |
| 12114 | buffer. The buffer should be large enough to store the login name and a |
| 12115 | trailing NUL (typically LOGIN_NAME_MAX bytes). |
| 12116 | |
| 12117 | s\bse\bet\btl\blo\bog\bgi\bin\bn() sets the login name of the user associated with the current |
| 12118 | session to _\bn_\ba_\bm_\be. This call is restricted to the superuser, and is |
| 12119 | normally used only when a new session is being created on behalf of the |
| 12120 | named user (for example, at login time, or when a remote shell is |
| 12121 | invoked). |
| 12122 | |
| 12123 | _\bN_\bO_\bT_\bE: There is only one login name per session. |
| 12124 | |
| 12125 | It is _\bC_\bR_\bI_\bT_\bI_\bC_\bA_\bL_\bL_\bY important to ensure that s\bse\bet\btl\blo\bog\bgi\bin\bn() is only ever called |
| 12126 | after the process has taken adequate steps to ensure that it is detached |
| 12127 | from its parent's session. The _\bO_\bN_\bL_\bY way to do this is via the s\bse\bet\bts\bsi\bid\bd() |
| 12128 | function. The d\bda\bae\bem\bmo\bon\bn() function calls s\bse\bet\bts\bsi\bid\bd() which is an ideal way of |
| 12129 | detaching from a controlling terminal and forking into the background. |
| 12130 | |
| 12131 | In particular, neither i\bio\boc\bct\btl\bl(_\bt_\bt_\by_\bf_\bd, _\bT_\bI_\bO_\bC_\bN_\bO_\bT_\bT_\bY, _\b._\b._\b.) nor s\bse\bet\btp\bpg\bgr\brp\bp(_\b._\b._\b.) is |
| 12132 | sufficient to create a new session. |
| 12133 | |
| 12134 | Once a parent process has called s\bse\bet\bts\bsi\bid\bd(), it is acceptable for some |
| 12135 | child of that process to then call s\bse\bet\btl\blo\bog\bgi\bin\bn(), even though it is not the |
| 12136 | session leader. Beware, however, that _\bA_\bL_\bL processes in the session will |
| 12137 | change their login name at the same time, even the parent. |
| 12138 | |
| 12139 | This is different from traditional UNIX privilege inheritance and as such |
| 12140 | can be counter-intuitive. |
| 12141 | |
| 12142 | Since the s\bse\bet\btl\blo\bog\bgi\bin\bn() routine is restricted to the super-user, it is |
| 12143 | assumed that (like all other privileged programs) the programmer has |
| 12144 | taken adequate precautions to prevent security violations. |
| 12145 | |
| 12146 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12147 | If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn() succeeds, it returns a pointer to a NUL- |
| 12148 | terminated string in a static buffer. If the name has not been set, it |
| 12149 | returns NULL. If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() succeeds, a value of 0 is |
| 12150 | returned, else the error number is returned. If a call to s\bse\bet\btl\blo\bog\bgi\bin\bn() |
| 12151 | succeeds, a value of 0 is returned. If s\bse\bet\btl\blo\bog\bgi\bin\bn() fails, a value of -1 |
| 12152 | is returned and an error code is placed in the global location _\be_\br_\br_\bn_\bo. |
| 12153 | |
| 12154 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12155 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() and s\bse\bet\btl\blo\bog\bgi\bin\bn() will succeed unless: |
| 12156 | |
| 12157 | [EFAULT] The _\bn_\ba_\bm_\be parameter points to an invalid address. |
| 12158 | |
| 12159 | In addition, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() may return the following error: |
| 12160 | |
| 12161 | [ERANGE] The value of _\bn_\ba_\bm_\be_\bl_\be_\bn is not large enough to store the |
| 12162 | user's login name and a trailing NUL. |
| 12163 | |
| 12164 | s\bse\bet\btl\blo\bog\bgi\bin\bn() may return the following errors: |
| 12165 | |
| 12166 | [EINVAL] The _\bn_\ba_\bm_\be parameter pointed to a string that was too |
| 12167 | long. Login names are limited to LOGIN_NAME_MAX-1 |
| 12168 | characters, currently 31. |
| 12169 | |
| 12170 | [EPERM] The caller tried to set the login name and was not the |
| 12171 | superuser. |
| 12172 | |
| 12173 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12174 | setsid(2) |
| 12175 | |
| 12176 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12177 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() and g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() functions conform to IEEE Std 1003.1-2008 |
| 12178 | (``POSIX.1''). |
| 12179 | |
| 12180 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12181 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() function first appeared in 4.2BSD. |
| 12182 | |
| 12183 | B\bBU\bUG\bGS\bS |
| 12184 | In earlier versions of the system, g\bge\bet\btl\blo\bog\bgi\bin\bn() failed unless the process |
| 12185 | was associated with a login terminal. The current implementation (using |
| 12186 | s\bse\bet\btl\blo\bog\bgi\bin\bn()) allows getlogin to succeed even when the process has no |
| 12187 | controlling terminal. In earlier versions of the system, the value |
| 12188 | returned by g\bge\bet\btl\blo\bog\bgi\bin\bn() could not be trusted without checking the user ID. |
| 12189 | Portable programs should probably still make this check. |
| 12190 | |
| 12191 | N\bNA\bAM\bME\bE |
| 12192 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be - get name of connected peer |
| 12193 | |
| 12194 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12195 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 12196 | |
| 12197 | _\bi_\bn_\bt |
| 12198 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bn_\ba_\bm_\be_\bl_\be_\bn); |
| 12199 | |
| 12200 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12201 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() returns the address information of the peer connected to |
| 12202 | socket _\bs. One common use occurs when a process inherits an open socket, |
| 12203 | such as TCP servers forked from inetd(8). In this scenario, |
| 12204 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() is used to determine the connecting client's IP address. |
| 12205 | |
| 12206 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() takes three parameters: |
| 12207 | |
| 12208 | _\bs contains the file descriptor of the socket whose peer should be looked |
| 12209 | up. |
| 12210 | |
| 12211 | _\bn_\ba_\bm_\be points to a sockaddr structure that will hold the address |
| 12212 | information for the connected peer. Normal use requires one to use a |
| 12213 | structure specific to the protocol family in use, such as sockaddr_in |
| 12214 | (IPv4) or sockaddr_in6 (IPv6), cast to a (struct sockaddr *). |
| 12215 | |
| 12216 | For greater portability, especially with the newer protocol families, the |
| 12217 | new struct sockaddr_storage should be used. sockaddr_storage is large |
| 12218 | enough to hold any of the other sockaddr_* variants. On return, it can |
| 12219 | be cast to the correct sockaddr type, based on the protocol family |
| 12220 | contained in its ss_family field. |
| 12221 | |
| 12222 | _\bn_\ba_\bm_\be_\bl_\be_\bn indicates the amount of space pointed to by _\bn_\ba_\bm_\be, in bytes. |
| 12223 | |
| 12224 | If address information for the local end of the socket is required, the |
| 12225 | getsockname(2) function should be used instead. |
| 12226 | |
| 12227 | If _\bn_\ba_\bm_\be does not point to enough space to hold the entire socket address, |
| 12228 | the result will be truncated to _\bn_\ba_\bm_\be_\bl_\be_\bn bytes. |
| 12229 | |
| 12230 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12231 | If the call succeeds, a 0 is returned and _\bn_\ba_\bm_\be_\bl_\be_\bn is set to the actual |
| 12232 | size of the socket address returned in _\bn_\ba_\bm_\be. Otherwise, _\be_\br_\br_\bn_\bo is set and |
| 12233 | a value of -1 is returned. |
| 12234 | |
| 12235 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12236 | On failure, _\be_\br_\br_\bn_\bo is set to one of the following: |
| 12237 | |
| 12238 | [EBADF] The argument _\bs is not a valid descriptor. |
| 12239 | |
| 12240 | [ENOTSOCK] The argument _\bs is a file, not a socket. |
| 12241 | |
| 12242 | [ENOTCONN] The socket is not connected. |
| 12243 | |
| 12244 | [ENOBUFS] Insufficient resources were available in the system to |
| 12245 | perform the operation. |
| 12246 | |
| 12247 | [EFAULT] The _\bn_\ba_\bm_\be or _\bn_\ba_\bm_\be_\bl_\be_\bn parameter points to memory not in |
| 12248 | a valid part of the process address space. |
| 12249 | |
| 12250 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12251 | accept(2), bind(2), getsockname(2), socket(2), getpeereid(3) |
| 12252 | |
| 12253 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12254 | The g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() function conforms to IEEE Std 1003.1-2008 |
| 12255 | (``POSIX.1''). |
| 12256 | |
| 12257 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12258 | The g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() function call appeared in 4.2BSD. |
| 12259 | |
| 12260 | N\bNA\bAM\bME\bE |
| 12261 | g\bge\bet\btp\bpg\bgr\brp\bp, g\bge\bet\btp\bpg\bgi\bid\bd - get process group |
| 12262 | |
| 12263 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12264 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 12265 | |
| 12266 | _\bp_\bi_\bd_\b__\bt |
| 12267 | g\bge\bet\btp\bpg\bgr\brp\bp(_\bv_\bo_\bi_\bd); |
| 12268 | |
| 12269 | _\bp_\bi_\bd_\b__\bt |
| 12270 | g\bge\bet\btp\bpg\bgi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd); |
| 12271 | |
| 12272 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12273 | The process group of the current process is returned by g\bge\bet\btp\bpg\bgr\brp\bp(). The |
| 12274 | process group of the _\bp_\bi_\bd process is returned by g\bge\bet\btp\bpg\bgi\bid\bd(). If _\bp_\bi_\bd is |
| 12275 | zero, g\bge\bet\btp\bpg\bgi\bid\bd() returns the process group of the current process. |
| 12276 | |
| 12277 | Process groups are used for distribution of signals, and by terminals to |
| 12278 | arbitrate requests for their input: processes that have the same process |
| 12279 | group as the terminal are foreground and may read, while others will |
| 12280 | block with a signal if they attempt to read. |
| 12281 | |
| 12282 | These calls are thus used by programs such as csh(1) to create process |
| 12283 | groups in implementing job control. The t\btc\bcg\bge\bet\btp\bpg\bgr\brp\bp() and t\btc\bcs\bse\bet\btp\bpg\bgr\brp\bp() |
| 12284 | calls are used to get/set the process group of the control terminal. |
| 12285 | |
| 12286 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12287 | g\bge\bet\btp\bpg\bgr\brp\bp() always succeeds, however g\bge\bet\btp\bpg\bgi\bid\bd() will succeed unless: |
| 12288 | |
| 12289 | [EPERM] The current process and the process _\bp_\bi_\bd are not in the |
| 12290 | same session. |
| 12291 | |
| 12292 | [ESRCH] There is no process with a process ID equal to _\bp_\bi_\bd. |
| 12293 | |
| 12294 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12295 | setpgid(2), termios(4) |
| 12296 | |
| 12297 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12298 | The g\bge\bet\btp\bpg\bgr\brp\bp() and g\bge\bet\btp\bpg\bgi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 12299 | (``POSIX.1''). |
| 12300 | |
| 12301 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12302 | A g\bge\bet\btp\bpg\bgr\brp\bp() function call that took a _\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd argument appeared in |
| 12303 | 4.0BSD. This version, without an argument, is derived from its usage in |
| 12304 | System V Release 4, and first appeared in NetBSD 0.9. |
| 12305 | |
| 12306 | The g\bge\bet\btp\bpg\bgi\bid\bd() function call is derived from its usage in System V Release |
| 12307 | 4, and first appeared in NetBSD 1.2a. |
| 12308 | |
| 12309 | N\bNA\bAM\bME\bE |
| 12310 | g\bge\bet\btp\bpg\bgr\brp\bp, g\bge\bet\btp\bpg\bgi\bid\bd - get process group |
| 12311 | |
| 12312 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12313 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 12314 | |
| 12315 | _\bp_\bi_\bd_\b__\bt |
| 12316 | g\bge\bet\btp\bpg\bgr\brp\bp(_\bv_\bo_\bi_\bd); |
| 12317 | |
| 12318 | _\bp_\bi_\bd_\b__\bt |
| 12319 | g\bge\bet\btp\bpg\bgi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd); |
| 12320 | |
| 12321 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12322 | The process group of the current process is returned by g\bge\bet\btp\bpg\bgr\brp\bp(). The |
| 12323 | process group of the _\bp_\bi_\bd process is returned by g\bge\bet\btp\bpg\bgi\bid\bd(). If _\bp_\bi_\bd is |
| 12324 | zero, g\bge\bet\btp\bpg\bgi\bid\bd() returns the process group of the current process. |
| 12325 | |
| 12326 | Process groups are used for distribution of signals, and by terminals to |
| 12327 | arbitrate requests for their input: processes that have the same process |
| 12328 | group as the terminal are foreground and may read, while others will |
| 12329 | block with a signal if they attempt to read. |
| 12330 | |
| 12331 | These calls are thus used by programs such as csh(1) to create process |
| 12332 | groups in implementing job control. The t\btc\bcg\bge\bet\btp\bpg\bgr\brp\bp() and t\btc\bcs\bse\bet\btp\bpg\bgr\brp\bp() |
| 12333 | calls are used to get/set the process group of the control terminal. |
| 12334 | |
| 12335 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12336 | g\bge\bet\btp\bpg\bgr\brp\bp() always succeeds, however g\bge\bet\btp\bpg\bgi\bid\bd() will succeed unless: |
| 12337 | |
| 12338 | [EPERM] The current process and the process _\bp_\bi_\bd are not in the |
| 12339 | same session. |
| 12340 | |
| 12341 | [ESRCH] There is no process with a process ID equal to _\bp_\bi_\bd. |
| 12342 | |
| 12343 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12344 | setpgid(2), termios(4) |
| 12345 | |
| 12346 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12347 | The g\bge\bet\btp\bpg\bgr\brp\bp() and g\bge\bet\btp\bpg\bgi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 12348 | (``POSIX.1''). |
| 12349 | |
| 12350 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12351 | A g\bge\bet\btp\bpg\bgr\brp\bp() function call that took a _\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd argument appeared in |
| 12352 | 4.0BSD. This version, without an argument, is derived from its usage in |
| 12353 | System V Release 4, and first appeared in NetBSD 0.9. |
| 12354 | |
| 12355 | The g\bge\bet\btp\bpg\bgi\bid\bd() function call is derived from its usage in System V Release |
| 12356 | 4, and first appeared in NetBSD 1.2a. |
| 12357 | |
| 12358 | N\bNA\bAM\bME\bE |
| 12359 | g\bge\bet\btp\bpi\bid\bd, g\bge\bet\btp\bpp\bpi\bid\bd - get parent or calling process identification |
| 12360 | |
| 12361 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12362 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 12363 | |
| 12364 | _\bp_\bi_\bd_\b__\bt |
| 12365 | g\bge\bet\btp\bpi\bid\bd(_\bv_\bo_\bi_\bd); |
| 12366 | |
| 12367 | _\bp_\bi_\bd_\b__\bt |
| 12368 | g\bge\bet\btp\bpp\bpi\bid\bd(_\bv_\bo_\bi_\bd); |
| 12369 | |
| 12370 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12371 | g\bge\bet\btp\bpi\bid\bd() returns the process ID of the calling process. Though the ID is |
| 12372 | guaranteed to be unique, it should _\bN_\bO_\bT be used for constructing temporary |
| 12373 | file names; see mkstemp(3) instead. |
| 12374 | |
| 12375 | g\bge\bet\btp\bpp\bpi\bid\bd() returns the process ID of the parent of the calling process. |
| 12376 | |
| 12377 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12378 | These functions are always successful, and no return value is reserved to |
| 12379 | indicate an error. |
| 12380 | |
| 12381 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12382 | gethostid(3) |
| 12383 | |
| 12384 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12385 | g\bge\bet\btp\bpi\bid\bd() and g\bge\bet\btp\bpp\bpi\bid\bd() conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 12386 | |
| 12387 | N\bNA\bAM\bME\bE |
| 12388 | g\bge\bet\btp\bpi\bid\bd, g\bge\bet\btp\bpp\bpi\bid\bd - get parent or calling process identification |
| 12389 | |
| 12390 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12391 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 12392 | |
| 12393 | _\bp_\bi_\bd_\b__\bt |
| 12394 | g\bge\bet\btp\bpi\bid\bd(_\bv_\bo_\bi_\bd); |
| 12395 | |
| 12396 | _\bp_\bi_\bd_\b__\bt |
| 12397 | g\bge\bet\btp\bpp\bpi\bid\bd(_\bv_\bo_\bi_\bd); |
| 12398 | |
| 12399 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12400 | g\bge\bet\btp\bpi\bid\bd() returns the process ID of the calling process. Though the ID is |
| 12401 | guaranteed to be unique, it should _\bN_\bO_\bT be used for constructing temporary |
| 12402 | file names; see mkstemp(3) instead. |
| 12403 | |
| 12404 | g\bge\bet\btp\bpp\bpi\bid\bd() returns the process ID of the parent of the calling process. |
| 12405 | |
| 12406 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12407 | These functions are always successful, and no return value is reserved to |
| 12408 | indicate an error. |
| 12409 | |
| 12410 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12411 | gethostid(3) |
| 12412 | |
| 12413 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12414 | g\bge\bet\btp\bpi\bid\bd() and g\bge\bet\btp\bpp\bpi\bid\bd() conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 12415 | |
| 12416 | N\bNA\bAM\bME\bE |
| 12417 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by, s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by - get/set process scheduling priority |
| 12418 | |
| 12419 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12420 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 12421 | |
| 12422 | _\bi_\bn_\bt |
| 12423 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bi_\bd_\b__\bt _\bw_\bh_\bo); |
| 12424 | |
| 12425 | _\bi_\bn_\bt |
| 12426 | s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bi_\bd_\b__\bt _\bw_\bh_\bo, _\bi_\bn_\bt _\bp_\br_\bi_\bo); |
| 12427 | |
| 12428 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12429 | The scheduling priority of the process, process group, or user, as |
| 12430 | indicated by _\bw_\bh_\bi_\bc_\bh and _\bw_\bh_\bo is obtained with the g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call and |
| 12431 | set with the s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call. _\bw_\bh_\bi_\bc_\bh is one of PRIO_PROCESS, |
| 12432 | PRIO_PGRP, or PRIO_USER, and _\bw_\bh_\bo is interpreted relative to _\bw_\bh_\bi_\bc_\bh (a |
| 12433 | process identifier for PRIO_PROCESS, process group identifier for |
| 12434 | PRIO_PGRP, and a user ID for PRIO_USER). A zero value of _\bw_\bh_\bo denotes the |
| 12435 | current process, process group, or user. _\bp_\br_\bi_\bo is a value in the range |
| 12436 | -20 to 20. The default priority is 0; lower priorities cause more |
| 12437 | favorable scheduling. |
| 12438 | |
| 12439 | The g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call returns the highest priority (lowest numerical |
| 12440 | value) enjoyed by any of the specified processes. The s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call |
| 12441 | sets the priorities of all of the specified processes to the specified |
| 12442 | value. Priority values outside the range -20 to 20 are truncated to the |
| 12443 | appropriate limit. Only the superuser may lower priorities. |
| 12444 | |
| 12445 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12446 | Since g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() can legitimately return the value -1, it is necessary |
| 12447 | to clear the external variable _\be_\br_\br_\bn_\bo prior to the call, then check it |
| 12448 | afterward to determine if a -1 is an error or a legitimate value. The |
| 12449 | s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call returns 0 if there is no error, or -1 if there is. |
| 12450 | |
| 12451 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12452 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() will fail if: |
| 12453 | |
| 12454 | [ESRCH] No process was located using the _\bw_\bh_\bi_\bc_\bh and _\bw_\bh_\bo values |
| 12455 | specified. |
| 12456 | |
| 12457 | [EINVAL] _\bw_\bh_\bi_\bc_\bh was not one of PRIO_PROCESS, PRIO_PGRP, or |
| 12458 | PRIO_USER. |
| 12459 | |
| 12460 | In addition, s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() will fail if: |
| 12461 | |
| 12462 | [EPERM] A process was located, but neither its effective nor |
| 12463 | real user ID matched the effective user ID of the |
| 12464 | caller. |
| 12465 | |
| 12466 | [EACCES] A non-superuser attempted to lower a process priority. |
| 12467 | |
| 12468 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12469 | nice(1), fork(2), renice(8) |
| 12470 | |
| 12471 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12472 | The g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() functions conform to IEEE Std |
| 12473 | 1003.1-2008 (``POSIX.1''). |
| 12474 | |
| 12475 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12476 | The predecessor of these functions, the former n\bni\bic\bce\be() system call, |
| 12477 | appeared in Version 3 AT&T UNIX and was removed in 4.3BSD-Reno. The |
| 12478 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() system calls appeared in 4.1cBSD. |
| 12479 | |
| 12480 | N\bNA\bAM\bME\bE |
| 12481 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd, g\bge\bet\btr\bre\bes\bsu\bui\bid\bd, s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd, s\bse\bet\btr\bre\bes\bsu\bui\bid\bd - get or set real, effective |
| 12482 | and saved user or group ID |
| 12483 | |
| 12484 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12485 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 12486 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 12487 | |
| 12488 | _\bi_\bn_\bt |
| 12489 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\b*_\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\bs_\bg_\bi_\bd); |
| 12490 | |
| 12491 | _\bi_\bn_\bt |
| 12492 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\b*_\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\bs_\bu_\bi_\bd); |
| 12493 | |
| 12494 | _\bi_\bn_\bt |
| 12495 | s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\bs_\bg_\bi_\bd); |
| 12496 | |
| 12497 | _\bi_\bn_\bt |
| 12498 | s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\bs_\bu_\bi_\bd); |
| 12499 | |
| 12500 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12501 | The s\bse\bet\btr\bre\bes\bsu\bui\bid\bd() function sets the real, effective and saved user IDs of |
| 12502 | the current process. The analogous s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd() sets the real, effective |
| 12503 | and saved group IDs. |
| 12504 | |
| 12505 | Privileged processes may set these IDs to arbitrary values. Unprivileged |
| 12506 | processes are restricted in that each of the new IDs must match one of |
| 12507 | the current IDs. |
| 12508 | |
| 12509 | Passing -1 as an argument causes the corresponding value to remain |
| 12510 | unchanged. |
| 12511 | |
| 12512 | The g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() and g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() calls retrieve the real, effective, and |
| 12513 | saved group and user IDs of the current process, respectively. |
| 12514 | |
| 12515 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12516 | Upon successful completion, the value 0 is returned; otherwise the |
| 12517 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 12518 | error. |
| 12519 | |
| 12520 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12521 | [EPERM] The calling process was not privileged and tried to |
| 12522 | change one or more IDs to a value which was not the |
| 12523 | current real ID, the current effective ID nor the |
| 12524 | current saved ID. |
| 12525 | |
| 12526 | [EFAULT] An address passed to g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() or g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() was |
| 12527 | invalid. |
| 12528 | |
| 12529 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12530 | getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), |
| 12531 | setregid(2), setreuid(2), setuid(2) |
| 12532 | |
| 12533 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12534 | These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') |
| 12535 | specification. While they are not completely portable, they are the |
| 12536 | least ambiguous way to manage user and group IDs. |
| 12537 | |
| 12538 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12539 | These functions first appeared in HP-UX. |
| 12540 | |
| 12541 | N\bNA\bAM\bME\bE |
| 12542 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd, g\bge\bet\btr\bre\bes\bsu\bui\bid\bd, s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd, s\bse\bet\btr\bre\bes\bsu\bui\bid\bd - get or set real, effective |
| 12543 | and saved user or group ID |
| 12544 | |
| 12545 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12546 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 12547 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 12548 | |
| 12549 | _\bi_\bn_\bt |
| 12550 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\b*_\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\bs_\bg_\bi_\bd); |
| 12551 | |
| 12552 | _\bi_\bn_\bt |
| 12553 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\b*_\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\bs_\bu_\bi_\bd); |
| 12554 | |
| 12555 | _\bi_\bn_\bt |
| 12556 | s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\bs_\bg_\bi_\bd); |
| 12557 | |
| 12558 | _\bi_\bn_\bt |
| 12559 | s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\bs_\bu_\bi_\bd); |
| 12560 | |
| 12561 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12562 | The s\bse\bet\btr\bre\bes\bsu\bui\bid\bd() function sets the real, effective and saved user IDs of |
| 12563 | the current process. The analogous s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd() sets the real, effective |
| 12564 | and saved group IDs. |
| 12565 | |
| 12566 | Privileged processes may set these IDs to arbitrary values. Unprivileged |
| 12567 | processes are restricted in that each of the new IDs must match one of |
| 12568 | the current IDs. |
| 12569 | |
| 12570 | Passing -1 as an argument causes the corresponding value to remain |
| 12571 | unchanged. |
| 12572 | |
| 12573 | The g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() and g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() calls retrieve the real, effective, and |
| 12574 | saved group and user IDs of the current process, respectively. |
| 12575 | |
| 12576 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12577 | Upon successful completion, the value 0 is returned; otherwise the |
| 12578 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 12579 | error. |
| 12580 | |
| 12581 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12582 | [EPERM] The calling process was not privileged and tried to |
| 12583 | change one or more IDs to a value which was not the |
| 12584 | current real ID, the current effective ID nor the |
| 12585 | current saved ID. |
| 12586 | |
| 12587 | [EFAULT] An address passed to g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() or g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() was |
| 12588 | invalid. |
| 12589 | |
| 12590 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12591 | getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), |
| 12592 | setregid(2), setreuid(2), setuid(2) |
| 12593 | |
| 12594 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12595 | These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') |
| 12596 | specification. While they are not completely portable, they are the |
| 12597 | least ambiguous way to manage user and group IDs. |
| 12598 | |
| 12599 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12600 | These functions first appeared in HP-UX. |
| 12601 | |
| 12602 | N\bNA\bAM\bME\bE |
| 12603 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt, s\bse\bet\btr\brl\bli\bim\bmi\bit\bt - control maximum system resource consumption |
| 12604 | |
| 12605 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12606 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 12607 | |
| 12608 | _\bi_\bn_\bt |
| 12609 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt(_\bi_\bn_\bt _\br_\be_\bs_\bo_\bu_\br_\bc_\be, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bl_\bi_\bm_\bi_\bt _\b*_\br_\bl_\bp); |
| 12610 | |
| 12611 | _\bi_\bn_\bt |
| 12612 | s\bse\bet\btr\brl\bli\bim\bmi\bit\bt(_\bi_\bn_\bt _\br_\be_\bs_\bo_\bu_\br_\bc_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\br_\bl_\bi_\bm_\bi_\bt _\b*_\br_\bl_\bp); |
| 12613 | |
| 12614 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12615 | Limits on the consumption of system resources by the current process and |
| 12616 | each process it creates may be obtained with the g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() call, and |
| 12617 | set with the s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() call. |
| 12618 | |
| 12619 | The _\br_\be_\bs_\bo_\bu_\br_\bc_\be parameter is one of the following: |
| 12620 | |
| 12621 | RLIMIT_CORE The largest size (in bytes) _\bc_\bo_\br_\be file that may be |
| 12622 | created. |
| 12623 | |
| 12624 | RLIMIT_CPU The maximum amount of CPU time (in seconds) to be used by |
| 12625 | each process. |
| 12626 | |
| 12627 | RLIMIT_DATA The maximum size (in bytes) of the data segment for a |
| 12628 | process; this includes memory allocated via malloc(3) and |
| 12629 | all other anonymous memory mapped via mmap(2). |
| 12630 | |
| 12631 | RLIMIT_FSIZE The largest size (in bytes) file that may be created. |
| 12632 | |
| 12633 | RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into |
| 12634 | memory using the mlock(2) function. |
| 12635 | |
| 12636 | RLIMIT_NOFILE The maximum number of open files for this process. |
| 12637 | |
| 12638 | RLIMIT_NPROC The maximum number of simultaneous processes for this |
| 12639 | user id. |
| 12640 | |
| 12641 | RLIMIT_RSS The maximum size (in bytes) to which a process's resident |
| 12642 | set size may grow. This imposes a limit on the amount of |
| 12643 | physical memory to be given to a process; if memory is |
| 12644 | tight, the system will prefer to take memory from |
| 12645 | processes that are exceeding their declared resident set |
| 12646 | size. |
| 12647 | |
| 12648 | RLIMIT_STACK The maximum size (in bytes) of the stack segment for a |
| 12649 | process, which defines how far a process's stack segment |
| 12650 | may be extended. Stack extension is performed |
| 12651 | automatically by the system, and is only used by the main |
| 12652 | thread of a process. |
| 12653 | |
| 12654 | A resource limit is specified as a soft limit and a hard limit. When a |
| 12655 | soft limit is exceeded a process may receive a signal (for example, if |
| 12656 | the CPU time or file size is exceeded), but it will be allowed to |
| 12657 | continue execution until it reaches the hard limit (or modifies its |
| 12658 | resource limit). The _\br_\bl_\bi_\bm_\bi_\bt structure is used to specify the hard and |
| 12659 | soft limits on a resource, |
| 12660 | |
| 12661 | struct rlimit { |
| 12662 | rlim_t rlim_cur; /* current (soft) limit */ |
| 12663 | rlim_t rlim_max; /* hard limit */ |
| 12664 | }; |
| 12665 | |
| 12666 | Only the superuser may raise the maximum limits. Other users may only |
| 12667 | alter _\br_\bl_\bi_\bm_\b__\bc_\bu_\br within the range from 0 to _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx or (irreversibly) |
| 12668 | lower _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx. |
| 12669 | |
| 12670 | An ``infinite'' value for a limit is defined as RLIM_INFINITY. |
| 12671 | |
| 12672 | A value of RLIM_SAVED_CUR or RLIM_SAVED_MAX will be stored in _\br_\bl_\bi_\bm_\b__\bc_\bu_\br or |
| 12673 | _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx respectively by g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() if the value for the current or |
| 12674 | maximum resource limit cannot be stored in an rlim_t. The values |
| 12675 | RLIM_SAVED_CUR and RLIM_SAVED_MAX should not be used in a call to |
| 12676 | s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() unless they were returned by a previous call to g\bge\bet\btr\brl\bli\bim\bmi\bit\bt(). |
| 12677 | |
| 12678 | Because this information is stored in the per-process information, this |
| 12679 | system call must be executed directly by the shell if it is to affect all |
| 12680 | future processes created by the shell; l\bli\bim\bmi\bit\bt is thus a built-in command |
| 12681 | to csh(1) and u\bul\bli\bim\bmi\bit\bt is the sh(1) equivalent. |
| 12682 | |
| 12683 | The system refuses to extend the data or stack space when the limits |
| 12684 | would be exceeded in the normal way: a brk(2) call fails if the data |
| 12685 | space limit is reached. When the stack limit is reached, the process |
| 12686 | receives a segmentation fault (SIGSEGV); if this signal is not caught by |
| 12687 | a handler using the signal stack, this signal will kill the process. |
| 12688 | |
| 12689 | A file I/O operation that would create a file larger than the process' |
| 12690 | soft limit will cause the write to fail and a signal SIGXFSZ to be |
| 12691 | generated; this normally terminates the process, but may be caught. When |
| 12692 | the soft CPU time limit is exceeded, a signal SIGXCPU is sent to the |
| 12693 | offending process. |
| 12694 | |
| 12695 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12696 | Upon successful completion, the value 0 is returned; otherwise the |
| 12697 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 12698 | error. |
| 12699 | |
| 12700 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12701 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() will fail if: |
| 12702 | |
| 12703 | [EFAULT] The address specified for _\br_\bl_\bp is invalid. |
| 12704 | |
| 12705 | [EINVAL] An unrecognized value for _\br_\be_\bs_\bo_\bu_\br_\bc_\be was specified. |
| 12706 | |
| 12707 | In addition, s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() may return the following errors: |
| 12708 | |
| 12709 | [EINVAL] The new _\br_\bl_\bi_\bm_\b__\bc_\bu_\br is greater than the new _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx. |
| 12710 | |
| 12711 | [EPERM] The new _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx is greater than the current maximum |
| 12712 | limit value, and the caller is not the superuser. |
| 12713 | |
| 12714 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12715 | csh(1), sh(1), quotactl(2), sigaction(2), sigaltstack(2), sysctl(3) |
| 12716 | |
| 12717 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12718 | The g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() functions conform to IEEE Std 1003.1-2008 |
| 12719 | (``POSIX.1''). |
| 12720 | |
| 12721 | The RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS resources are non- |
| 12722 | standard extensions. |
| 12723 | |
| 12724 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12725 | The g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() system calls first appeared in 4.1cBSD. |
| 12726 | |
| 12727 | B\bBU\bUG\bGS\bS |
| 12728 | The RLIMIT_AS resource is missing. |
| 12729 | |
| 12730 | N\bNA\bAM\bME\bE |
| 12731 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be, s\bse\bet\btr\brt\bta\bab\bbl\ble\be - get and set the default routing table of the |
| 12732 | current process |
| 12733 | |
| 12734 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12735 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 12736 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 12737 | |
| 12738 | _\bi_\bn_\bt |
| 12739 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be(_\bv_\bo_\bi_\bd); |
| 12740 | |
| 12741 | _\bi_\bn_\bt |
| 12742 | s\bse\bet\btr\brt\bta\bab\bbl\ble\be(_\bi_\bn_\bt _\br_\bt_\ba_\bb_\bl_\be_\bi_\bd); |
| 12743 | |
| 12744 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12745 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be() and s\bse\bet\btr\brt\bta\bab\bbl\ble\be() manipulate the routing table and routing |
| 12746 | domain associated with the current process. |
| 12747 | |
| 12748 | Only the superuser is allowed to change the process routing table if it |
| 12749 | is already set to a non-zero value. |
| 12750 | |
| 12751 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12752 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be() returns the routing table of the current process. Upon |
| 12753 | successful completion, s\bse\bet\btr\brt\bta\bab\bbl\ble\be() returns 0 if the call succeeds, -1 if |
| 12754 | it fails. |
| 12755 | |
| 12756 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12757 | The call succeeds unless: |
| 12758 | |
| 12759 | [EINVAL] The value of the _\br_\bt_\ba_\bb_\bl_\be_\bi_\bd argument is not a valid |
| 12760 | routing table. |
| 12761 | |
| 12762 | [EPERM] The user is not the superuser and the routing table of |
| 12763 | the calling process is already set to a non-zero |
| 12764 | value. |
| 12765 | |
| 12766 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12767 | getsockopt(2), route(8) |
| 12768 | |
| 12769 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12770 | The g\bge\bet\btr\brt\bta\bab\bbl\ble\be() and s\bse\bet\btr\brt\bta\bab\bbl\ble\be() system calls appeared in OpenBSD 4.8. |
| 12771 | |
| 12772 | N\bNA\bAM\bME\bE |
| 12773 | g\bge\bet\btr\bru\bus\bsa\bag\bge\be - get information about resource utilization |
| 12774 | |
| 12775 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12776 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 12777 | |
| 12778 | _\bi_\bn_\bt |
| 12779 | g\bge\bet\btr\bru\bus\bsa\bag\bge\be(_\bi_\bn_\bt _\bw_\bh_\bo, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 12780 | |
| 12781 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12782 | g\bge\bet\btr\bru\bus\bsa\bag\bge\be() returns resource usage information for argument _\bw_\bh_\bo, which |
| 12783 | can be one of the following: |
| 12784 | |
| 12785 | RUSAGE_SELF Resources used by the current process. |
| 12786 | |
| 12787 | RUSAGE_CHILDREN Resources used by all the terminated children of |
| 12788 | the current process. |
| 12789 | |
| 12790 | RUSAGE_THREAD Resources used by the current thread. |
| 12791 | |
| 12792 | The buffer to which _\br_\bu_\bs_\ba_\bg_\be points will be filled in with the following |
| 12793 | structure: |
| 12794 | |
| 12795 | struct rusage { |
| 12796 | struct timeval ru_utime; /* user time used */ |
| 12797 | struct timeval ru_stime; /* system time used */ |
| 12798 | long ru_maxrss; /* max resident set size */ |
| 12799 | long ru_ixrss; /* integral shared text memory size */ |
| 12800 | long ru_idrss; /* integral unshared data size */ |
| 12801 | long ru_isrss; /* integral unshared stack size */ |
| 12802 | long ru_minflt; /* page reclaims */ |
| 12803 | long ru_majflt; /* page faults */ |
| 12804 | long ru_nswap; /* swaps */ |
| 12805 | long ru_inblock; /* block input operations */ |
| 12806 | long ru_oublock; /* block output operations */ |
| 12807 | long ru_msgsnd; /* messages sent */ |
| 12808 | long ru_msgrcv; /* messages received */ |
| 12809 | long ru_nsignals; /* signals received */ |
| 12810 | long ru_nvcsw; /* voluntary context switches */ |
| 12811 | long ru_nivcsw; /* involuntary context switches */ |
| 12812 | }; |
| 12813 | |
| 12814 | The fields are interpreted as follows: |
| 12815 | |
| 12816 | _\br_\bu_\b__\bu_\bt_\bi_\bm_\be the total amount of time spent executing in user mode. |
| 12817 | |
| 12818 | _\br_\bu_\b__\bs_\bt_\bi_\bm_\be the total amount of time spent in the system executing on |
| 12819 | behalf of the process(es). |
| 12820 | |
| 12821 | _\br_\bu_\b__\bm_\ba_\bx_\br_\bs_\bs the maximum resident set size utilized (in kilobytes). |
| 12822 | |
| 12823 | _\br_\bu_\b__\bi_\bx_\br_\bs_\bs an ``integral'' value indicating the amount of memory used |
| 12824 | by the text segment that was also shared among other |
| 12825 | processes. This value is expressed in units of kilobytes * |
| 12826 | ticks-of-execution. |
| 12827 | |
| 12828 | _\br_\bu_\b__\bi_\bd_\br_\bs_\bs an integral value of the amount of unshared memory residing |
| 12829 | in the data segment of a process (expressed in units of |
| 12830 | kilobytes * ticks-of-execution). |
| 12831 | |
| 12832 | _\br_\bu_\b__\bi_\bs_\br_\bs_\bs an integral value of the amount of unshared memory residing |
| 12833 | in the stack segment of a process (expressed in units of |
| 12834 | kilobytes * ticks-of-execution). |
| 12835 | |
| 12836 | _\br_\bu_\b__\bm_\bi_\bn_\bf_\bl_\bt the number of page faults serviced without any I/O activity; |
| 12837 | here I/O activity is avoided by ``reclaiming'' a page frame |
| 12838 | from the list of pages awaiting reallocation. |
| 12839 | |
| 12840 | _\br_\bu_\b__\bm_\ba_\bj_\bf_\bl_\bt the number of page faults serviced that required I/O |
| 12841 | activity. |
| 12842 | |
| 12843 | _\br_\bu_\b__\bn_\bs_\bw_\ba_\bp the number of times a process was ``swapped'' out of main |
| 12844 | memory. |
| 12845 | |
| 12846 | _\br_\bu_\b__\bi_\bn_\bb_\bl_\bo_\bc_\bk the number of times the file system had to perform input. |
| 12847 | |
| 12848 | _\br_\bu_\b__\bo_\bu_\bb_\bl_\bo_\bc_\bk the number of times the file system had to perform output. |
| 12849 | |
| 12850 | _\br_\bu_\b__\bm_\bs_\bg_\bs_\bn_\bd the number of IPC messages sent. |
| 12851 | |
| 12852 | _\br_\bu_\b__\bm_\bs_\bg_\br_\bc_\bv the number of IPC messages received. |
| 12853 | |
| 12854 | _\br_\bu_\b__\bn_\bs_\bi_\bg_\bn_\ba_\bl_\bs the number of signals delivered. |
| 12855 | |
| 12856 | _\br_\bu_\b__\bn_\bv_\bc_\bs_\bw the number of times a context switch resulted due to a |
| 12857 | process voluntarily giving up the processor before its time |
| 12858 | slice was completed (usually to await availability of a |
| 12859 | resource). |
| 12860 | |
| 12861 | _\br_\bu_\b__\bn_\bi_\bv_\bc_\bs_\bw the number of times a context switch resulted due to a |
| 12862 | higher priority process becoming runnable or because the |
| 12863 | current process exceeded its time slice. |
| 12864 | |
| 12865 | N\bNO\bOT\bTE\bES\bS |
| 12866 | The numbers _\br_\bu_\b__\bi_\bn_\bb_\bl_\bo_\bc_\bk and _\br_\bu_\b__\bo_\bu_\bb_\bl_\bo_\bc_\bk account only for real I/O; data |
| 12867 | supplied by the caching mechanism is charged only to the first process to |
| 12868 | read or write the data. |
| 12869 | |
| 12870 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12871 | Upon successful completion, the value 0 is returned; otherwise the |
| 12872 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 12873 | error. |
| 12874 | |
| 12875 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12876 | g\bge\bet\btr\bru\bus\bsa\bag\bge\be() will fail if: |
| 12877 | |
| 12878 | [EINVAL] The _\bw_\bh_\bo parameter is not a valid value. |
| 12879 | |
| 12880 | [EFAULT] The address specified by the _\br_\bu_\bs_\ba_\bg_\be parameter is not |
| 12881 | in a valid part of the process address space. |
| 12882 | |
| 12883 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12884 | clock_gettime(2), gettimeofday(2), wait(2) |
| 12885 | |
| 12886 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12887 | The g\bge\bet\btr\bru\bus\bsa\bag\bge\be() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 12888 | |
| 12889 | The RUSAGE_THREAD flag is an extension to that specification. |
| 12890 | |
| 12891 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12892 | A predecessor to g\bge\bet\btr\bru\bus\bsa\bag\bge\be(), t\bti\bim\bme\bes\bs(), first appeared in Version 3 AT&T |
| 12893 | UNIX. The g\bge\bet\btr\bru\bus\bsa\bag\bge\be() system call first appeared in 4.1cBSD. |
| 12894 | |
| 12895 | The RUSAGE_THREAD flag has been available since OpenBSD 4.8. |
| 12896 | |
| 12897 | B\bBU\bUG\bGS\bS |
| 12898 | There is no way to obtain information about a child process that has not |
| 12899 | yet terminated. |
| 12900 | |
| 12901 | N\bNA\bAM\bME\bE |
| 12902 | g\bge\bet\bts\bsi\bid\bd - get process session |
| 12903 | |
| 12904 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12905 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 12906 | |
| 12907 | _\bp_\bi_\bd_\b__\bt |
| 12908 | g\bge\bet\bts\bsi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd); |
| 12909 | |
| 12910 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12911 | The session ID of the process identified by _\bp_\bi_\bd is returned by g\bge\bet\bts\bsi\bid\bd(). |
| 12912 | If _\bp_\bi_\bd is zero, g\bge\bet\bts\bsi\bid\bd() returns the session ID of the current process. |
| 12913 | |
| 12914 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12915 | Upon successful completion, the function g\bge\bet\bts\bsi\bid\bd() returns the session ID |
| 12916 | of the specified process; otherwise, it returns a value of -1 and sets |
| 12917 | _\be_\br_\br_\bn_\bo to indicate an error. |
| 12918 | |
| 12919 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12920 | g\bge\bet\bts\bsi\bid\bd() will succeed unless: |
| 12921 | |
| 12922 | [EPERM] The current process and the process _\bp_\bi_\bd are not in the |
| 12923 | same session. |
| 12924 | |
| 12925 | [ESRCH] There is no process with a process ID equal to _\bp_\bi_\bd. |
| 12926 | |
| 12927 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 12928 | getpgid(2), getpgrp(2), setpgid(2), setsid(2), termios(4) |
| 12929 | |
| 12930 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 12931 | g\bge\bet\bts\bsi\bid\bd() conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 12932 | |
| 12933 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 12934 | The g\bge\bet\bts\bsi\bid\bd() function call is derived from its usage in AT&T System V |
| 12935 | UNIX, and is mandated by X/Open Portability Guide Issue 4 (``XPG4''). |
| 12936 | |
| 12937 | N\bNA\bAM\bME\bE |
| 12938 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be - get socket name |
| 12939 | |
| 12940 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 12941 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 12942 | |
| 12943 | _\bi_\bn_\bt |
| 12944 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bn_\ba_\bm_\be_\bl_\be_\bn); |
| 12945 | |
| 12946 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 12947 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() returns the locally bound address information for a |
| 12948 | specified socket. |
| 12949 | |
| 12950 | Common uses of this function are as follows: |
| 12951 | |
| 12952 | +\b+\bo\bo When bind(2) is called with a port number of 0 (indicating the kernel |
| 12953 | should pick an ephemeral port) g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() is used to retrieve the |
| 12954 | kernel-assigned port number. |
| 12955 | |
| 12956 | +\b+\bo\bo When a process calls bind(2) on a wildcard IP address, g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() |
| 12957 | is used to retrieve the local IP address for the connection. |
| 12958 | |
| 12959 | +\b+\bo\bo When a function wishes to know the address family of a socket, |
| 12960 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() can be used. |
| 12961 | |
| 12962 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() takes three parameters: |
| 12963 | |
| 12964 | _\bs contains the file descriptor for the socket to be looked up. |
| 12965 | |
| 12966 | _\bn_\ba_\bm_\be points to a sockaddr structure which will hold the resulting address |
| 12967 | information. Normal use requires one to use a structure specific to the |
| 12968 | protocol family in use, such as sockaddr_in (IPv4) or sockaddr_in6 |
| 12969 | (IPv6), cast to a (struct sockaddr *). |
| 12970 | |
| 12971 | For greater portability (such as newer protocol families) the new |
| 12972 | structure sockaddr_storage exists. sockaddr_storage is large enough to |
| 12973 | hold any of the other sockaddr_* variants. On return, it should be cast |
| 12974 | to the correct sockaddr type, according to the current protocol family. |
| 12975 | |
| 12976 | _\bn_\ba_\bm_\be_\bl_\be_\bn indicates the amount of space pointed to by _\bn_\ba_\bm_\be, in bytes. Upon |
| 12977 | return, _\bn_\ba_\bm_\be_\bl_\be_\bn is set to the actual size of the returned address |
| 12978 | information. |
| 12979 | |
| 12980 | If the address of the destination socket for a given socket connection is |
| 12981 | needed, the getpeername(2) function should be used instead. |
| 12982 | |
| 12983 | If _\bn_\ba_\bm_\be does not point to enough space to hold the entire socket address, |
| 12984 | the result will be truncated to _\bn_\ba_\bm_\be_\bl_\be_\bn bytes. |
| 12985 | |
| 12986 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 12987 | On success, g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() returns a 0, and _\bn_\ba_\bm_\be_\bl_\be_\bn is set to the actual |
| 12988 | size of the socket address returned in _\bn_\ba_\bm_\be. Otherwise, _\be_\br_\br_\bn_\bo is set, |
| 12989 | and a value of -1 is returned. |
| 12990 | |
| 12991 | E\bER\bRR\bRO\bOR\bRS\bS |
| 12992 | If g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() fails, _\be_\br_\br_\bn_\bo is set to one of the following: |
| 12993 | |
| 12994 | [EBADF] The argument _\bs is not a valid descriptor. |
| 12995 | |
| 12996 | [ENOTSOCK] The argument _\bs is a file, not a socket. |
| 12997 | |
| 12998 | [ENOBUFS] Insufficient resources were available in the system to |
| 12999 | perform the operation. |
| 13000 | |
| 13001 | [EFAULT] The _\bn_\ba_\bm_\be or _\bn_\ba_\bm_\be_\bl_\be_\bn parameter points to memory not in |
| 13002 | a valid part of the process address space. |
| 13003 | |
| 13004 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13005 | accept(2), bind(2), getpeername(2), socket(2), getpeereid(3) |
| 13006 | |
| 13007 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 13008 | The g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() function conforms to IEEE Std 1003.1-2008 |
| 13009 | (``POSIX.1''). |
| 13010 | |
| 13011 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 13012 | The g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() function call appeared in 4.2BSD. |
| 13013 | |
| 13014 | N\bNA\bAM\bME\bE |
| 13015 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt, s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt - get and set options on sockets |
| 13016 | |
| 13017 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13018 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 13019 | |
| 13020 | _\bi_\bn_\bt |
| 13021 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bl_\be_\bv_\be_\bl, _\bi_\bn_\bt _\bo_\bp_\bt_\bn_\ba_\bm_\be, _\bv_\bo_\bi_\bd _\b*_\bo_\bp_\bt_\bv_\ba_\bl, |
| 13022 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bo_\bp_\bt_\bl_\be_\bn); |
| 13023 | |
| 13024 | _\bi_\bn_\bt |
| 13025 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bl_\be_\bv_\be_\bl, _\bi_\bn_\bt _\bo_\bp_\bt_\bn_\ba_\bm_\be, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bo_\bp_\bt_\bv_\ba_\bl, |
| 13026 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bo_\bp_\bt_\bl_\be_\bn); |
| 13027 | |
| 13028 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13029 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() manipulate the _\bo_\bp_\bt_\bi_\bo_\bn_\bs associated with a |
| 13030 | socket. Options may exist at multiple protocol levels; they are always |
| 13031 | present at the uppermost ``socket'' level. |
| 13032 | |
| 13033 | When manipulating socket options the level at which the option resides |
| 13034 | and the name of the option must be specified. To manipulate options at |
| 13035 | the socket level, _\bl_\be_\bv_\be_\bl is specified as SOL_SOCKET. To manipulate |
| 13036 | options at any other level the protocol number of the appropriate |
| 13037 | protocol controlling the option is supplied. For example, to indicate |
| 13038 | that an option is to be interpreted by the TCP protocol, _\bl_\be_\bv_\be_\bl should be |
| 13039 | set to the protocol number of TCP; see getprotoent(3). |
| 13040 | |
| 13041 | The parameters _\bo_\bp_\bt_\bv_\ba_\bl and _\bo_\bp_\bt_\bl_\be_\bn are used to access option values for |
| 13042 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() they identify a buffer in which the value |
| 13043 | for the requested option(s) are to be returned. For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), _\bo_\bp_\bt_\bl_\be_\bn |
| 13044 | is a value-result parameter, initially containing the size of the buffer |
| 13045 | pointed to by _\bo_\bp_\bt_\bv_\ba_\bl, and modified on return to indicate the actual size |
| 13046 | of the value returned. If no option value is to be supplied or returned, |
| 13047 | _\bo_\bp_\bt_\bv_\ba_\bl may be NULL. |
| 13048 | |
| 13049 | _\bo_\bp_\bt_\bn_\ba_\bm_\be and any specified options are passed uninterpreted to the |
| 13050 | appropriate protocol module for interpretation. The include file |
| 13051 | <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh> contains definitions for socket level options, described |
| 13052 | below. Options at other protocol levels vary in format and name; consult |
| 13053 | the appropriate entries in section 4 of the manual. |
| 13054 | |
| 13055 | Most socket-level options utilize an int parameter for _\bo_\bp_\bt_\bv_\ba_\bl. For |
| 13056 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), the parameter should be non-zero to enable a boolean |
| 13057 | option, or zero if the option is to be disabled. SO_LINGER uses a struct |
| 13058 | linger parameter, defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>, which specifies the desired |
| 13059 | state of the option and the linger interval (see below). SO_SNDTIMEO and |
| 13060 | SO_RCVTIMEO use a struct timeval parameter, defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. |
| 13061 | |
| 13062 | The following options are recognized at the socket level. Except as |
| 13063 | noted, each may be examined with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and set with s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). |
| 13064 | |
| 13065 | SO_DEBUG enables recording of debugging information |
| 13066 | SO_REUSEADDR enables local address reuse |
| 13067 | SO_REUSEPORT enables duplicate address and port bindings |
| 13068 | SO_KEEPALIVE enables keep connections alive |
| 13069 | SO_DONTROUTE enables routing bypass; not supported |
| 13070 | SO_LINGER linger on close if data present |
| 13071 | SO_BROADCAST enables permission to transmit broadcast messages |
| 13072 | SO_OOBINLINE enables reception of out-of-band data in band |
| 13073 | SO_BINDANY enables binding to any address |
| 13074 | SO_SNDBUF set buffer size for output |
| 13075 | SO_RCVBUF set buffer size for input |
| 13076 | SO_SNDLOWAT set minimum count for output |
| 13077 | SO_RCVLOWAT set minimum count for input |
| 13078 | SO_SNDTIMEO set timeout value for output |
| 13079 | SO_RCVTIMEO set timeout value for input |
| 13080 | SO_TIMESTAMP enables reception of a timestamp with datagrams |
| 13081 | SO_PEERCRED get the credentials from other side of connection |
| 13082 | SO_RTABLE set the routing table used for route lookups |
| 13083 | SO_SPLICE splice two sockets together or get data length |
| 13084 | SO_TYPE get the type of the socket (get only) |
| 13085 | SO_ERROR get and clear error on the socket (get only) |
| 13086 | |
| 13087 | SO_DEBUG enables debugging in the underlying protocol modules. |
| 13088 | SO_REUSEADDR indicates that the rules used in validating addresses |
| 13089 | supplied in a bind(2) call should allow reuse of local addresses. |
| 13090 | SO_REUSEPORT allows completely duplicate bindings by multiple processes |
| 13091 | if they all set SO_REUSEPORT before binding the port. This option |
| 13092 | permits multiple instances of a program to each receive UDP/IP multicast |
| 13093 | or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables |
| 13094 | the periodic transmission of messages on a connected socket. Should the |
| 13095 | connected party fail to respond to these messages, the connection is |
| 13096 | considered broken and processes using the socket are notified via a |
| 13097 | SIGPIPE signal when attempting to send data. |
| 13098 | |
| 13099 | SO_LINGER controls the action taken when unsent messages are queued on |
| 13100 | socket and a close(2) is performed. If the socket promises reliable |
| 13101 | delivery of data and SO_LINGER is set, the system will block the process |
| 13102 | on the close(2) attempt until it is able to transmit the data or until it |
| 13103 | decides it is unable to deliver the information (a timeout period |
| 13104 | measured in seconds, termed the linger interval, is specified in the |
| 13105 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() call when SO_LINGER is requested). If SO_LINGER is disabled |
| 13106 | and a close(2) is issued, the system will process the close in a manner |
| 13107 | that allows the process to continue as quickly as possible. |
| 13108 | |
| 13109 | The option SO_BROADCAST requests permission to send broadcast datagrams |
| 13110 | on the socket. Broadcast was a privileged operation in earlier versions |
| 13111 | of the system. With protocols that support out-of-band data, the |
| 13112 | SO_OOBINLINE option requests that out-of-band data be placed in the |
| 13113 | normal data input queue as received; it will then be accessible with |
| 13114 | recv(2) or read(2) calls without the MSG_OOB flag. Some protocols always |
| 13115 | behave as if this option is set. |
| 13116 | |
| 13117 | SO_BINDANY allows the socket to be bound to addresses which are not local |
| 13118 | to the machine, so it can be used to make a transparent proxy. Note that |
| 13119 | this option is limited to the super-user. In order to receive packets |
| 13120 | for these addresses, SO_BINDANY needs to be combined with matching |
| 13121 | outgoing pf(4) rules with the _\bd_\bi_\bv_\be_\br_\bt_\b-_\br_\be_\bp_\bl_\by parameter. For example, with |
| 13122 | the following rule the socket receives packets for 192.168.0.10 even if |
| 13123 | it is not a local address: |
| 13124 | |
| 13125 | pass out inet from 192.168.0.10 divert-reply |
| 13126 | |
| 13127 | SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes |
| 13128 | allocated for output and input buffers, respectively. The buffer size |
| 13129 | may be increased for high-volume connections, or may be decreased to |
| 13130 | limit the possible backlog of incoming data. The system places an |
| 13131 | absolute limit on these values. |
| 13132 | |
| 13133 | SO_SNDLOWAT is an option to set the minimum count for output operations. |
| 13134 | Most output operations process all of the data supplied by the call, |
| 13135 | delivering data to the protocol for transmission and blocking as |
| 13136 | necessary for flow control. Nonblocking output operations will process |
| 13137 | as much data as permitted subject to flow control without blocking, but |
| 13138 | will process no data if flow control does not allow the smaller of the |
| 13139 | low water mark value or the entire request to be processed. A select(2) |
| 13140 | or poll(2) operation testing the ability to write to a socket will return |
| 13141 | true only if the low water mark amount could be processed. The default |
| 13142 | value for SO_SNDLOWAT is set to a convenient size for network efficiency, |
| 13143 | often 1024. SO_RCVLOWAT is an option to set the minimum count for input |
| 13144 | operations. In general, receive calls will block until any (non-zero) |
| 13145 | amount of data is received, then return with the smaller of the amount |
| 13146 | available or the amount requested. The default value for SO_RCVLOWAT is |
| 13147 | 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls |
| 13148 | normally wait until they have received the smaller of the low water mark |
| 13149 | value or the requested amount. Receive calls may still return less than |
| 13150 | the low water mark if an error occurs, a signal is caught, or the type of |
| 13151 | data next in the receive queue is different than that returned. |
| 13152 | |
| 13153 | SO_SNDTIMEO is an option to set a timeout value for output operations. |
| 13154 | It accepts a struct timeval parameter with the number of seconds and |
| 13155 | microseconds used to limit waits for output operations to complete. If a |
| 13156 | send operation has blocked for this much time, it returns with a partial |
| 13157 | count or with the error EWOULDBLOCK if no data was sent. In the current |
| 13158 | implementation, this timer is restarted each time additional data are |
| 13159 | delivered to the protocol, implying that the limit applies to output |
| 13160 | portions ranging in size from the low water mark to the high water mark |
| 13161 | for output. SO_RCVTIMEO is an option to set a timeout value for input |
| 13162 | operations. It accepts a struct timeval parameter with the number of |
| 13163 | seconds and microseconds used to limit waits for input operations to |
| 13164 | complete. In the current implementation, this timer is restarted each |
| 13165 | time additional data are received by the protocol, and thus the limit is |
| 13166 | in effect an inactivity timer. If a receive operation has been blocked |
| 13167 | for this much time without receiving additional data, it returns with a |
| 13168 | short count or with the error EWOULDBLOCK if no data were received. |
| 13169 | |
| 13170 | If the SO_TIMESTAMP option is enabled on a SOCK_DGRAM socket, the |
| 13171 | recvmsg(2) call will return a timestamp corresponding to when the |
| 13172 | datagram was received. The msg_control field in the msghdr structure |
| 13173 | points to a buffer that contains a cmsghdr structure followed by a struct |
| 13174 | timeval. The cmsghdr fields have the following values: |
| 13175 | |
| 13176 | cmsg_len = CMSG_LEN(sizeof(struct timeval)) |
| 13177 | cmsg_level = SOL_SOCKET |
| 13178 | cmsg_type = SCM_TIMESTAMP |
| 13179 | |
| 13180 | SO_PEERCRED fetches the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\bp_\be_\be_\br_\bc_\br_\be_\bd credentials from the other |
| 13181 | side of the connection (currently only possible on AF_UNIX sockets). |
| 13182 | These credentials are from the time that bind(2) or connect(2) were |
| 13183 | called. |
| 13184 | |
| 13185 | The SO_RTABLE option gets or sets the routing table which will be used by |
| 13186 | the socket for address lookups. If a protocol family of the socket |
| 13187 | doesn't support switching routing tables, the ENOPROTOOPT error is |
| 13188 | returned. Only the superuser is allowed to change the routing table if |
| 13189 | it is already set to a non-zero value. A socket's chosen routing table |
| 13190 | is initialized from the process's configuration, previously selected |
| 13191 | using setrtable(2). |
| 13192 | |
| 13193 | SO_SPLICE can splice together two TCP or UDP sockets for zero-copy data |
| 13194 | transfers. Both sockets must be of the same type. In the first form, |
| 13195 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() is called with the source socket _\bs and the drain socket's |
| 13196 | _\bi_\bn_\bt file descriptor as _\bo_\bp_\bt_\bv_\ba_\bl. In the second form, _\bo_\bp_\bt_\bv_\ba_\bl is a _\bs_\bt_\br_\bu_\bc_\bt |
| 13197 | _\bs_\bp_\bl_\bi_\bc_\be with the drain socket in _\bs_\bp_\b__\bf_\bd, a positive maximum number of bytes |
| 13198 | or 0 in _\bs_\bp_\b__\bm_\ba_\bx and an idle timeout _\bs_\bp_\b__\bi_\bd_\bl_\be in the form of a _\bs_\bt_\br_\bu_\bc_\bt |
| 13199 | _\bt_\bi_\bm_\be_\bv_\ba_\bl. If -1 is given as drain socket, the source socket _\bs gets |
| 13200 | unspliced. Otherwise the spliced data transfer continues within the |
| 13201 | kernel until the optional maximum is reached, one of the connections |
| 13202 | terminates, idle timeout expires or an error occurs. A successful |
| 13203 | select(2), poll(2), or kqueue(2) operation testing the ability to read |
| 13204 | from the source socket indicates that the splicing has terminated. The |
| 13205 | error status can be examined with SO_ERROR at the source socket. The |
| 13206 | ETIMEDOUT error is set if there was no data transferred between two |
| 13207 | sockets during the _\bs_\bp_\b__\bi_\bd_\bl_\be period of time. The EFBIG error is set after |
| 13208 | exactly _\bs_\bp_\b__\bm_\ba_\bx bytes have been transferred. Note that if a maximum is |
| 13209 | given, it is only guaranteed that no more bytes are transferred. A short |
| 13210 | splice can happen, but then a second call to splice will transfer the |
| 13211 | remaining data immediately. The SO_SPLICE option with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and |
| 13212 | an _\bo_\bf_\bf_\b__\bt value as _\bo_\bp_\bt_\bv_\ba_\bl can be used to retrieve the number of bytes |
| 13213 | transferred so far from the source socket _\bs. A successful new splice |
| 13214 | resets this number. |
| 13215 | |
| 13216 | Finally, SO_TYPE and SO_ERROR are options used only with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). |
| 13217 | SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful |
| 13218 | for servers that inherit sockets on startup. SO_ERROR returns any |
| 13219 | pending error on the socket and clears the error status. It may be used |
| 13220 | to check for asynchronous errors on connected datagram sockets or for |
| 13221 | other asynchronous errors. |
| 13222 | |
| 13223 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13224 | Upon successful completion, the value 0 is returned; otherwise the |
| 13225 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 13226 | error. |
| 13227 | |
| 13228 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13229 | The call succeeds unless: |
| 13230 | |
| 13231 | [EBADF] The argument _\bs is not a valid descriptor. |
| 13232 | |
| 13233 | [ENOTSOCK] The argument _\bs is a file, not a socket. |
| 13234 | |
| 13235 | [ENOPROTOOPT] The option is unknown at the level indicated. |
| 13236 | |
| 13237 | [EOPNOTSUPP] The option is unsupported. |
| 13238 | |
| 13239 | [EFAULT] The address pointed to by _\bo_\bp_\bt_\bv_\ba_\bl is not in a valid |
| 13240 | part of the process address space. For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), |
| 13241 | this error may also be returned if _\bo_\bp_\bt_\bl_\be_\bn is not in a |
| 13242 | valid part of the process address space. |
| 13243 | |
| 13244 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13245 | connect(2), getrtable(2), ioctl(2), poll(2), select(2), socket(2), |
| 13246 | getprotoent(3), divert(4), pf.conf(5), protocols(5), sosplice(9) |
| 13247 | |
| 13248 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 13249 | The g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() functions conform to IEEE Std |
| 13250 | 1003.1-2008 (``POSIX.1''). |
| 13251 | |
| 13252 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 13253 | The g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() system call appeared in 4.2BSD. |
| 13254 | |
| 13255 | B\bBU\bUG\bGS\bS |
| 13256 | Several of the socket options should be handled at lower levels of the |
| 13257 | system. |
| 13258 | |
| 13259 | N\bNA\bAM\bME\bE |
| 13260 | g\bge\bet\btt\bth\bhr\bri\bid\bd - get thread identifier |
| 13261 | |
| 13262 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13263 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 13264 | |
| 13265 | _\bp_\bi_\bd_\b__\bt |
| 13266 | g\bge\bet\btt\bth\bhr\bri\bid\bd(_\bv_\bo_\bi_\bd); |
| 13267 | |
| 13268 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13269 | k\bkq\bqu\bue\beu\bue\be returns the thread ID of the calling thread. This is used in the |
| 13270 | implementation of the thread library (-\b-l\blp\bpt\bth\bhr\bre\bea\bad\bd) and can appear in the |
| 13271 | output of system utilities such as ps(1) and kdump(1). |
| 13272 | |
| 13273 | Thread IDs are not a stable interface and should not be used directly by |
| 13274 | applications except for correlation with system utility output. |
| 13275 | Applications should use the _\bp_\bt_\bh_\br_\be_\ba_\bd_\b__\bt values from pthread_self(3) and |
| 13276 | pthread_create(3) to identify threads within the process itself. |
| 13277 | |
| 13278 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13279 | This function is always successful, and no return value is reserved to |
| 13280 | indicate an error. |
| 13281 | |
| 13282 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13283 | __tfork(2), getpid(2), pthread_create(3), pthread_self(3) |
| 13284 | |
| 13285 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 13286 | The k\bkq\bqu\bue\beu\bue\be syscall is specific to OpenBSD and should not be used in |
| 13287 | portable applications. |
| 13288 | |
| 13289 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 13290 | The k\bkq\bqu\bue\beu\bue\be syscall appeared in OpenBSD 3.9. |
| 13291 | |
| 13292 | N\bNA\bAM\bME\bE |
| 13293 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by, s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by - get/set date and time |
| 13294 | |
| 13295 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13296 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 13297 | |
| 13298 | _\bi_\bn_\bt |
| 13299 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be _\b*_\bt_\bz_\bp); |
| 13300 | |
| 13301 | _\bi_\bn_\bt |
| 13302 | s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bp, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be _\b*_\bt_\bz_\bp); |
| 13303 | |
| 13304 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13305 | N\bNo\bot\bte\be:\b: t\bti\bim\bme\bez\bzo\bon\bne\be i\bis\bs n\bno\bo l\blo\bon\bng\bge\ber\br u\bus\bse\bed\bd;\b; t\bth\bhi\bis\bs i\bin\bnf\bfo\bor\brm\bma\bat\bti\bio\bon\bn i\bis\bs k\bke\bep\bpt\bt o\bou\but\bts\bsi\bid\bde\be t\bth\bhe\be |
| 13306 | k\bke\ber\brn\bne\bel\bl.\b. |
| 13307 | |
| 13308 | The system's notion of the current Greenwich time and the current time |
| 13309 | zone is obtained with the g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() call, and set with the |
| 13310 | s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() call. The time is expressed in seconds and microseconds |
| 13311 | since midnight (0 hour), January 1, 1970. The resolution of the system |
| 13312 | clock is hardware dependent, and the time may be updated continuously or |
| 13313 | in ``ticks''. If _\bt_\bp or _\bt_\bz_\bp is NULL, the associated time information will |
| 13314 | not be returned or set. |
| 13315 | |
| 13316 | The structures pointed to by _\bt_\bp and _\bt_\bz_\bp are defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
| 13317 | |
| 13318 | struct timeval { |
| 13319 | time_t tv_sec; /* seconds since Jan. 1, 1970 */ |
| 13320 | suseconds_t tv_usec; /* and microseconds */ |
| 13321 | }; |
| 13322 | |
| 13323 | struct timezone { |
| 13324 | int tz_minuteswest; /* of Greenwich */ |
| 13325 | int tz_dsttime; /* type of dst correction to apply */ |
| 13326 | }; |
| 13327 | |
| 13328 | The _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be structure indicates the local time zone (measured in minutes |
| 13329 | of time westward from Greenwich), and a flag that, if nonzero, indicates |
| 13330 | that Daylight Saving time applies locally during the appropriate part of |
| 13331 | the year. |
| 13332 | |
| 13333 | Only the superuser may set the time of day or time zone. If the system |
| 13334 | securelevel is greater than 1 (see init(8)), the time may only be |
| 13335 | advanced. This limitation is imposed to prevent a malicious superuser |
| 13336 | from setting arbitrary time stamps on files. The system time can still |
| 13337 | be adjusted backwards using the adjtime(2) system call even when the |
| 13338 | system is secure. |
| 13339 | |
| 13340 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13341 | Upon successful completion, the value 0 is returned; otherwise the |
| 13342 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 13343 | error. |
| 13344 | |
| 13345 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13346 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() and s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() will succeed unless: |
| 13347 | |
| 13348 | [EFAULT] An argument address referenced invalid memory. |
| 13349 | |
| 13350 | In addition, s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() may return the following error: |
| 13351 | |
| 13352 | [EPERM] A user other than the superuser attempted to set the |
| 13353 | time. |
| 13354 | |
| 13355 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13356 | date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3) |
| 13357 | |
| 13358 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 13359 | The g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() function conforms to IEEE Std 1003.1-2008 |
| 13360 | (``POSIX.1''). |
| 13361 | |
| 13362 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 13363 | As predecessors of these functions, former system calls t\bti\bim\bme\be() and |
| 13364 | s\bst\bti\bim\bme\be() first appeared in Version 1 AT&T UNIX, and f\bft\bti\bim\bme\be() first appeared |
| 13365 | in Version 7 AT&T UNIX. The g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() and s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() system |
| 13366 | calls first appeared in 4.1cBSD. |
| 13367 | |
| 13368 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 13369 | Setting the time with s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() is dangerous; if possible use |
| 13370 | adjtime(2) instead. Many daemon programming techniques utilize time- |
| 13371 | delta techniques using the results from g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() instead of from |
| 13372 | clock_gettime(2) on the CLOCK_MONOTONIC clock. Time jumps can cause |
| 13373 | these programs to malfunction in unexpected ways. If the time must be |
| 13374 | set, consider rebooting the machine for safety. |
| 13375 | |
| 13376 | N\bNA\bAM\bME\bE |
| 13377 | g\bge\bet\btu\bui\bid\bd, g\bge\bet\bte\beu\bui\bid\bd - get user identification |
| 13378 | |
| 13379 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13380 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 13381 | |
| 13382 | _\bu_\bi_\bd_\b__\bt |
| 13383 | g\bge\bet\btu\bui\bid\bd(_\bv_\bo_\bi_\bd); |
| 13384 | |
| 13385 | _\bu_\bi_\bd_\b__\bt |
| 13386 | g\bge\bet\bte\beu\bui\bid\bd(_\bv_\bo_\bi_\bd); |
| 13387 | |
| 13388 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13389 | The g\bge\bet\btu\bui\bid\bd() function returns the real user ID of the calling process. |
| 13390 | The g\bge\bet\bte\beu\bui\bid\bd() function returns the effective user ID of the calling |
| 13391 | process. |
| 13392 | |
| 13393 | The real user ID is that of the user who has invoked the program. As the |
| 13394 | effective user ID gives the process additional permissions during |
| 13395 | execution of ``_\bs_\be_\bt_\b-_\bu_\bs_\be_\br_\b-_\bI_\bD'' mode processes, g\bge\bet\btu\bui\bid\bd() is used to |
| 13396 | determine the real user ID of the calling process. |
| 13397 | |
| 13398 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13399 | The g\bge\bet\btu\bui\bid\bd() and g\bge\bet\bte\beu\bui\bid\bd() functions are always successful, and no return |
| 13400 | value is reserved to indicate an error. |
| 13401 | |
| 13402 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13403 | getgid(2), getresuid(2), setreuid(2), setuid(2) |
| 13404 | |
| 13405 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 13406 | The g\bge\bet\btu\bui\bid\bd() and g\bge\bet\bte\beu\bui\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 13407 | (``POSIX.1''). |
| 13408 | |
| 13409 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 13410 | The g\bge\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX, and |
| 13411 | g\bge\bet\bte\beu\bui\bid\bd() in Version 7 AT&T UNIX. |
| 13412 | |
| 13413 | N\bNA\bAM\bME\bE |
| 13414 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be - manage i386 per-thread %fs base |
| 13415 | address |
| 13416 | |
| 13417 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13418 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13419 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13420 | |
| 13421 | _\bi_\bn_\bt |
| 13422 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
| 13423 | |
| 13424 | _\bi_\bn_\bt |
| 13425 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
| 13426 | |
| 13427 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13428 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() copies the current base address of the segment that, by |
| 13429 | default, is referenced by the %fs selector into the memory referenced by |
| 13430 | _\bb_\ba_\bs_\be. |
| 13431 | |
| 13432 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() sets the base address of the segment that, by default, |
| 13433 | is referenced by %fs to the address _\bb_\ba_\bs_\be. |
| 13434 | |
| 13435 | The segment base address is local to each thread. The initial thread of |
| 13436 | a new process inherits its segment base address from the parent thread. |
| 13437 | __tfork(2) sets the initial segment base address for threads that it |
| 13438 | creates. |
| 13439 | |
| 13440 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() functions |
| 13441 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13442 | |
| 13443 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13444 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() |
| 13445 | return 0. Otherwise, a value of -1 is returned and the global variable |
| 13446 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 13447 | |
| 13448 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13449 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() will fail if: |
| 13450 | |
| 13451 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
| 13452 | |
| 13453 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13454 | __tfork(2), fork(2) |
| 13455 | |
| 13456 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13457 | |
| 13458 | N\bNA\bAM\bME\bE |
| 13459 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be - manage i386 per-thread %gs base |
| 13460 | address |
| 13461 | |
| 13462 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13463 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13464 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13465 | |
| 13466 | _\bi_\bn_\bt |
| 13467 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
| 13468 | |
| 13469 | _\bi_\bn_\bt |
| 13470 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
| 13471 | |
| 13472 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13473 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() copies the current base address of the segment that, by |
| 13474 | default, is referenced by the %gs selector into the memory referenced by |
| 13475 | _\bb_\ba_\bs_\be. |
| 13476 | |
| 13477 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() sets the base address of the segment that, by default, |
| 13478 | is referenced by %gs to the address _\bb_\ba_\bs_\be. |
| 13479 | |
| 13480 | The segment base address is local to each thread. The initial thread of |
| 13481 | a new process inherits its segment base address from the parent thread. |
| 13482 | __tfork(2) sets the initial segment base address for threads that it |
| 13483 | creates. |
| 13484 | |
| 13485 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() functions |
| 13486 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13487 | |
| 13488 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13489 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() |
| 13490 | return 0. Otherwise, a value of -1 is returned and the global variable |
| 13491 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 13492 | |
| 13493 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13494 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() will fail if: |
| 13495 | |
| 13496 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
| 13497 | |
| 13498 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13499 | __tfork(2), fork(2) |
| 13500 | |
| 13501 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13502 | |
| 13503 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 13504 | The ELF Thread-Local Storage ABI reserves %gs for its own use and |
| 13505 | requires that the dynamic linker and thread library set it to reference |
| 13506 | data-structures internal to and shared between them. Programs should use |
| 13507 | the __thread storage class keyword instead of using these calls. To be |
| 13508 | maximally portable, programs that require per-thread data should use the |
| 13509 | p\bpt\bth\bhr\bre\bea\bad\bd_\b_k\bke\bey\by_\b_c\bcr\bre\bea\bat\bte\be() interface. |
| 13510 | |
| 13511 | N\bNA\bAM\bME\bE |
| 13512 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm - manage i386 per-process I/O permission |
| 13513 | bitmap |
| 13514 | |
| 13515 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13516 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13517 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13518 | |
| 13519 | _\bi_\bn_\bt |
| 13520 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm(_\bu_\b__\bl_\bo_\bn_\bg _\b*_\bi_\bo_\bm_\ba_\bp); |
| 13521 | |
| 13522 | _\bi_\bn_\bt |
| 13523 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm(_\bu_\b__\bl_\bo_\bn_\bg _\b*_\bi_\bo_\bm_\ba_\bp); |
| 13524 | |
| 13525 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13526 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() copies the current I/O permission bitmap into the |
| 13527 | memory referenced by _\bi_\bo_\bm_\ba_\bp. |
| 13528 | |
| 13529 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() sets the I/O permission bitmap from the data pointed to |
| 13530 | by _\bi_\bo_\bm_\ba_\bp. This call may only be made by the superuser. Additionally, it |
| 13531 | is only permitted when the securelevel(7) is less than or equal to 0 or |
| 13532 | the _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be sysctl has been set to a non-zero value. |
| 13533 | |
| 13534 | The permission bitmap contains 1024 bits in 32 longwords. If bit _\bn is |
| 13535 | clear in the bitmap, then access is granted to I/O port _\bn. If bit _\bn is |
| 13536 | set in the bitmap, then an attempt to access I/O port _\bn results in |
| 13537 | delivery of a SIGBUS signal unless the process's I/O permission level |
| 13538 | would grant I/O access. |
| 13539 | |
| 13540 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() functions |
| 13541 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13542 | |
| 13543 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13544 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() |
| 13545 | return 0. Otherwise, a value of -1 is returned and the global variable |
| 13546 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 13547 | |
| 13548 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13549 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() will fail if: |
| 13550 | |
| 13551 | [EFAULT] _\bi_\bo_\bm_\ba_\bp points outside the process's allocated address space. |
| 13552 | |
| 13553 | Additionally i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() will fail if: |
| 13554 | |
| 13555 | [EPERM] The caller was not the superuser, or the securelevel is greater |
| 13556 | than zero and _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be has not been set to a non- |
| 13557 | zero value. |
| 13558 | |
| 13559 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13560 | i386_iopl(2) |
| 13561 | |
| 13562 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13563 | |
| 13564 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 13565 | You can really hose your machine if you enable user-level I/O and write |
| 13566 | to hardware ports without care. |
| 13567 | |
| 13568 | B\bBU\bUG\bGS\bS |
| 13569 | The bitmap should really cover 65536 bits, but that's just too big for |
| 13570 | allocation in a kernel structure. If you need access to ports beyond |
| 13571 | 1024, use i386_iopl(2). |
| 13572 | |
| 13573 | N\bNA\bAM\bME\bE |
| 13574 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt - manage i386 per-process Local Descriptor |
| 13575 | Table entries |
| 13576 | |
| 13577 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13578 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13579 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bse\beg\bgm\bme\ben\bnt\bts\bs.\b.h\bh>\b> |
| 13580 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13581 | |
| 13582 | _\bi_\bn_\bt |
| 13583 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl, _\bu_\bn_\bi_\bo_\bn _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br _\b*_\bd_\be_\bs_\bc_\bs, _\bi_\bn_\bt _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs); |
| 13584 | |
| 13585 | _\bi_\bn_\bt |
| 13586 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl, _\bu_\bn_\bi_\bo_\bn _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br _\b*_\bd_\be_\bs_\bc_\bs, _\bi_\bn_\bt _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs); |
| 13587 | |
| 13588 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13589 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() returns a list of the i386 descriptors in the current |
| 13590 | process' LDT. i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() sets a list of i386 descriptors in the |
| 13591 | current process' LDT. For both routines, _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl specifies the index |
| 13592 | of the selector in the LDT at which to begin and _\bd_\be_\bs_\bc_\bs points to an array |
| 13593 | of _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs descriptors to be set or returned. |
| 13594 | |
| 13595 | Each entry in the _\bd_\be_\bs_\bc_\bs array can be either a segment_descriptor or a |
| 13596 | gate_descriptor, as defined in <_\bi_\b3_\b8_\b6_\b/_\bs_\be_\bg_\bm_\be_\bn_\bt_\bs_\b._\bh>. These structures are |
| 13597 | defined by the architecture as disjoint bit-fields, so care must be taken |
| 13598 | in constructing them. |
| 13599 | |
| 13600 | Before this API can be used the functionality has to be enabled using the |
| 13601 | machdep.userldt sysctl(8) variable. |
| 13602 | |
| 13603 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() functions must be |
| 13604 | compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13605 | |
| 13606 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13607 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() returns the number of i386 |
| 13608 | descriptors copied into _\bd_\be_\bs_\bc_\bs from the current process' LDT. Otherwise, |
| 13609 | a value of -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to |
| 13610 | indicate the error. |
| 13611 | |
| 13612 | Upon successful completion, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() returns the first selector |
| 13613 | set; if the kernel allocated a descriptor in the LDT, the allocated index |
| 13614 | is returned. Otherwise, a value of -1 is returned and the global |
| 13615 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 13616 | |
| 13617 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13618 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() will fail if: |
| 13619 | |
| 13620 | [EINVAL] An inappropriate parameter was used for _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl or _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs. |
| 13621 | |
| 13622 | [EACCES] The caller attempted to use a descriptor that would circumvent |
| 13623 | protection or cause a failure. |
| 13624 | |
| 13625 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 13626 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13627 | |
| 13628 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 13629 | You can really hose your process using this. |
| 13630 | |
| 13631 | N\bNA\bAM\bME\bE |
| 13632 | i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl - change the i386 I/O privilege level |
| 13633 | |
| 13634 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13635 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13636 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13637 | |
| 13638 | _\bi_\bn_\bt |
| 13639 | i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl(_\bi_\bn_\bt _\bi_\bo_\bp_\bl); |
| 13640 | |
| 13641 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13642 | i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl() sets the i386 I/O privilege level to the value specified by |
| 13643 | _\bi_\bo_\bp_\bl. |
| 13644 | |
| 13645 | This call may only be made by the superuser. Additionally, it is only |
| 13646 | permitted when the securelevel(7) is less than or equal to 0 or the |
| 13647 | _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be sysctl has been set to a non-zero value. |
| 13648 | |
| 13649 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl() function must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13650 | |
| 13651 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13652 | Upon successful completion, i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl() returns 0. Otherwise, a value of |
| 13653 | -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 13654 | error. |
| 13655 | |
| 13656 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13657 | i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl() will fail if: |
| 13658 | |
| 13659 | [EPERM] The caller was not the superuser, or the securelevel is greater |
| 13660 | than zero and _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be has not been set to a non- |
| 13661 | zero value. |
| 13662 | |
| 13663 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13664 | i386_get_ioperm(2), securelevel(7) |
| 13665 | |
| 13666 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 13667 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13668 | |
| 13669 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 13670 | You can really hose your machine if you enable user-level I/O and write |
| 13671 | to hardware ports without care. |
| 13672 | |
| 13673 | N\bNA\bAM\bME\bE |
| 13674 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be - manage i386 per-thread %fs base |
| 13675 | address |
| 13676 | |
| 13677 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13678 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13679 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13680 | |
| 13681 | _\bi_\bn_\bt |
| 13682 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
| 13683 | |
| 13684 | _\bi_\bn_\bt |
| 13685 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
| 13686 | |
| 13687 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13688 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() copies the current base address of the segment that, by |
| 13689 | default, is referenced by the %fs selector into the memory referenced by |
| 13690 | _\bb_\ba_\bs_\be. |
| 13691 | |
| 13692 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() sets the base address of the segment that, by default, |
| 13693 | is referenced by %fs to the address _\bb_\ba_\bs_\be. |
| 13694 | |
| 13695 | The segment base address is local to each thread. The initial thread of |
| 13696 | a new process inherits its segment base address from the parent thread. |
| 13697 | __tfork(2) sets the initial segment base address for threads that it |
| 13698 | creates. |
| 13699 | |
| 13700 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() functions |
| 13701 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13702 | |
| 13703 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13704 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() |
| 13705 | return 0. Otherwise, a value of -1 is returned and the global variable |
| 13706 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 13707 | |
| 13708 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13709 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() will fail if: |
| 13710 | |
| 13711 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
| 13712 | |
| 13713 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13714 | __tfork(2), fork(2) |
| 13715 | |
| 13716 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13717 | |
| 13718 | N\bNA\bAM\bME\bE |
| 13719 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be - manage i386 per-thread %gs base |
| 13720 | address |
| 13721 | |
| 13722 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13723 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13724 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13725 | |
| 13726 | _\bi_\bn_\bt |
| 13727 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
| 13728 | |
| 13729 | _\bi_\bn_\bt |
| 13730 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
| 13731 | |
| 13732 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13733 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() copies the current base address of the segment that, by |
| 13734 | default, is referenced by the %gs selector into the memory referenced by |
| 13735 | _\bb_\ba_\bs_\be. |
| 13736 | |
| 13737 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() sets the base address of the segment that, by default, |
| 13738 | is referenced by %gs to the address _\bb_\ba_\bs_\be. |
| 13739 | |
| 13740 | The segment base address is local to each thread. The initial thread of |
| 13741 | a new process inherits its segment base address from the parent thread. |
| 13742 | __tfork(2) sets the initial segment base address for threads that it |
| 13743 | creates. |
| 13744 | |
| 13745 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() functions |
| 13746 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13747 | |
| 13748 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13749 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() |
| 13750 | return 0. Otherwise, a value of -1 is returned and the global variable |
| 13751 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 13752 | |
| 13753 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13754 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() will fail if: |
| 13755 | |
| 13756 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
| 13757 | |
| 13758 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13759 | __tfork(2), fork(2) |
| 13760 | |
| 13761 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13762 | |
| 13763 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 13764 | The ELF Thread-Local Storage ABI reserves %gs for its own use and |
| 13765 | requires that the dynamic linker and thread library set it to reference |
| 13766 | data-structures internal to and shared between them. Programs should use |
| 13767 | the __thread storage class keyword instead of using these calls. To be |
| 13768 | maximally portable, programs that require per-thread data should use the |
| 13769 | p\bpt\bth\bhr\bre\bea\bad\bd_\b_k\bke\bey\by_\b_c\bcr\bre\bea\bat\bte\be() interface. |
| 13770 | |
| 13771 | N\bNA\bAM\bME\bE |
| 13772 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm - manage i386 per-process I/O permission |
| 13773 | bitmap |
| 13774 | |
| 13775 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13776 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13777 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13778 | |
| 13779 | _\bi_\bn_\bt |
| 13780 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm(_\bu_\b__\bl_\bo_\bn_\bg _\b*_\bi_\bo_\bm_\ba_\bp); |
| 13781 | |
| 13782 | _\bi_\bn_\bt |
| 13783 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm(_\bu_\b__\bl_\bo_\bn_\bg _\b*_\bi_\bo_\bm_\ba_\bp); |
| 13784 | |
| 13785 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13786 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() copies the current I/O permission bitmap into the |
| 13787 | memory referenced by _\bi_\bo_\bm_\ba_\bp. |
| 13788 | |
| 13789 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() sets the I/O permission bitmap from the data pointed to |
| 13790 | by _\bi_\bo_\bm_\ba_\bp. This call may only be made by the superuser. Additionally, it |
| 13791 | is only permitted when the securelevel(7) is less than or equal to 0 or |
| 13792 | the _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be sysctl has been set to a non-zero value. |
| 13793 | |
| 13794 | The permission bitmap contains 1024 bits in 32 longwords. If bit _\bn is |
| 13795 | clear in the bitmap, then access is granted to I/O port _\bn. If bit _\bn is |
| 13796 | set in the bitmap, then an attempt to access I/O port _\bn results in |
| 13797 | delivery of a SIGBUS signal unless the process's I/O permission level |
| 13798 | would grant I/O access. |
| 13799 | |
| 13800 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() functions |
| 13801 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13802 | |
| 13803 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13804 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() |
| 13805 | return 0. Otherwise, a value of -1 is returned and the global variable |
| 13806 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 13807 | |
| 13808 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13809 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() will fail if: |
| 13810 | |
| 13811 | [EFAULT] _\bi_\bo_\bm_\ba_\bp points outside the process's allocated address space. |
| 13812 | |
| 13813 | Additionally i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() will fail if: |
| 13814 | |
| 13815 | [EPERM] The caller was not the superuser, or the securelevel is greater |
| 13816 | than zero and _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be has not been set to a non- |
| 13817 | zero value. |
| 13818 | |
| 13819 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 13820 | i386_iopl(2) |
| 13821 | |
| 13822 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13823 | |
| 13824 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 13825 | You can really hose your machine if you enable user-level I/O and write |
| 13826 | to hardware ports without care. |
| 13827 | |
| 13828 | B\bBU\bUG\bGS\bS |
| 13829 | The bitmap should really cover 65536 bits, but that's just too big for |
| 13830 | allocation in a kernel structure. If you need access to ports beyond |
| 13831 | 1024, use i386_iopl(2). |
| 13832 | |
| 13833 | N\bNA\bAM\bME\bE |
| 13834 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt - manage i386 per-process Local Descriptor |
| 13835 | Table entries |
| 13836 | |
| 13837 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13838 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13839 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bse\beg\bgm\bme\ben\bnt\bts\bs.\b.h\bh>\b> |
| 13840 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13841 | |
| 13842 | _\bi_\bn_\bt |
| 13843 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl, _\bu_\bn_\bi_\bo_\bn _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br _\b*_\bd_\be_\bs_\bc_\bs, _\bi_\bn_\bt _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs); |
| 13844 | |
| 13845 | _\bi_\bn_\bt |
| 13846 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl, _\bu_\bn_\bi_\bo_\bn _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br _\b*_\bd_\be_\bs_\bc_\bs, _\bi_\bn_\bt _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs); |
| 13847 | |
| 13848 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13849 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() returns a list of the i386 descriptors in the current |
| 13850 | process' LDT. i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() sets a list of i386 descriptors in the |
| 13851 | current process' LDT. For both routines, _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl specifies the index |
| 13852 | of the selector in the LDT at which to begin and _\bd_\be_\bs_\bc_\bs points to an array |
| 13853 | of _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs descriptors to be set or returned. |
| 13854 | |
| 13855 | Each entry in the _\bd_\be_\bs_\bc_\bs array can be either a segment_descriptor or a |
| 13856 | gate_descriptor, as defined in <_\bi_\b3_\b8_\b6_\b/_\bs_\be_\bg_\bm_\be_\bn_\bt_\bs_\b._\bh>. These structures are |
| 13857 | defined by the architecture as disjoint bit-fields, so care must be taken |
| 13858 | in constructing them. |
| 13859 | |
| 13860 | Before this API can be used the functionality has to be enabled using the |
| 13861 | machdep.userldt sysctl(8) variable. |
| 13862 | |
| 13863 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() functions must be |
| 13864 | compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13865 | |
| 13866 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13867 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() returns the number of i386 |
| 13868 | descriptors copied into _\bd_\be_\bs_\bc_\bs from the current process' LDT. Otherwise, |
| 13869 | a value of -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to |
| 13870 | indicate the error. |
| 13871 | |
| 13872 | Upon successful completion, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() returns the first selector |
| 13873 | set; if the kernel allocated a descriptor in the LDT, the allocated index |
| 13874 | is returned. Otherwise, a value of -1 is returned and the global |
| 13875 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 13876 | |
| 13877 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13878 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() will fail if: |
| 13879 | |
| 13880 | [EINVAL] An inappropriate parameter was used for _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl or _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs. |
| 13881 | |
| 13882 | [EACCES] The caller attempted to use a descriptor that would circumvent |
| 13883 | protection or cause a failure. |
| 13884 | |
| 13885 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 13886 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13887 | |
| 13888 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
| 13889 | You can really hose your process using this. |
| 13890 | |
| 13891 | N\bNA\bAM\bME\bE |
| 13892 | i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6 - set virtual 8086 processor registers and mode |
| 13893 | |
| 13894 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13895 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 13896 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 13897 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bse\beg\bgm\bme\ben\bnt\bts\bs.\b.h\bh>\b> |
| 13898 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 13899 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/v\bvm\bm8\b86\b6.\b.h\bh>\b> |
| 13900 | |
| 13901 | _\bi_\bn_\bt |
| 13902 | i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6(_\bs_\bt_\br_\bu_\bc_\bt _\bv_\bm_\b8_\b6_\b__\bs_\bt_\br_\bu_\bc_\bt _\b*_\bv_\bm_\bc_\bp); |
| 13903 | |
| 13904 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13905 | i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6() will set the process into virtual 8086 mode using the |
| 13906 | registers and selectors specified by the context pointed to by _\bv_\bm_\bc_\bp. The |
| 13907 | processor registers are set from _\bv_\bm_\bc_\bp_\b-_\b>_\bs_\bu_\bb_\bs_\bt_\br_\b._\br_\be_\bg_\bs, and the emulated |
| 13908 | processor type from _\bv_\bm_\bc_\bp_\b-_\b>_\bs_\bu_\bb_\bs_\bt_\br_\b._\bs_\bs_\b__\bc_\bp_\bu_\b__\bt_\by_\bp_\be. |
| 13909 | |
| 13910 | The kernel keeps a pointer to the context, and uses the tables stored at |
| 13911 | _\bv_\bm_\bc_\bp_\b-_\b>_\bi_\bn_\bt_\b__\bb_\by_\bu_\bs_\be_\br and _\bv_\bm_\bc_\bp_\b-_\b>_\bi_\bn_\bt_\b2_\b1_\b__\bb_\by_\bu_\bs_\be_\br for fast virtual interrupt |
| 13912 | handling. If the _\bnth bit is clear in the first of these arrays, then the |
| 13913 | kernel may directly emulate the real-mode x86 INT _\bn instruction handling. |
| 13914 | If the _\bnth bit is set, then the process is delivered a signal when an INT |
| 13915 | instruction is executed. |
| 13916 | |
| 13917 | Since MS-DOS puts many DOS functions onto interrupt 21, it is handled |
| 13918 | specially: the _\bkth bit in the _\bv_\bm_\bc_\bp_\b-_\b>_\bi_\bn_\bt_\b2_\b1_\b__\bb_\by_\bu_\bs_\be_\br array is checked when |
| 13919 | INT _\b2_\b1 is requested and the _\ba_\bh register is _\bk. |
| 13920 | |
| 13921 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6() function must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
| 13922 | |
| 13923 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 13924 | This routine does not normally return: 32-bit mode will be restored by |
| 13925 | the delivery of a signal to the process. In case of an error in setting |
| 13926 | the VM86 mode, a value of -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
| 13927 | set to indicate the error. |
| 13928 | |
| 13929 | E\bER\bRR\bRO\bOR\bRS\bS |
| 13930 | i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6() will fail if: |
| 13931 | |
| 13932 | [EFAULT] The state at _\bv_\bm_\bc_\bp was not readable to the user process. |
| 13933 | |
| 13934 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 13935 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
| 13936 | |
| 13937 | N\bNA\bAM\bME\bE |
| 13938 | i\bin\bnt\btr\bro\bo - introduction to system calls and error numbers |
| 13939 | |
| 13940 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 13941 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<e\ber\brr\brn\bno\bo.\b.h\bh>\b> |
| 13942 | |
| 13943 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 13944 | The manual pages in section 2 provide an overview of the system calls, |
| 13945 | their error returns, and other common definitions and concepts. |
| 13946 | |
| 13947 | D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS |
| 13948 | Nearly all of the system calls provide an error number via the identifier |
| 13949 | errno, which expands to an addressable location of type _\bi_\bn_\bt. The address |
| 13950 | of _\be_\br_\br_\bn_\bo in each thread is guaranteed to be unique for the lifetime of |
| 13951 | the thread. Applications must use _\be_\br_\br_\bn_\bo as defined in <_\be_\br_\br_\bn_\bo_\b._\bh> and not |
| 13952 | attempt to use a custom definition. |
| 13953 | |
| 13954 | When a system call detects an error, it returns an integer value |
| 13955 | indicating failure (usually -1) and sets the variable _\be_\br_\br_\bn_\bo accordingly. |
| 13956 | (This allows interpretation of the failure on receiving a -1 and to take |
| 13957 | action accordingly.) Successful calls never set _\be_\br_\br_\bn_\bo; once set, it |
| 13958 | remains until another error occurs. It should only be examined after an |
| 13959 | error. Note that a number of system calls overload the meanings of these |
| 13960 | error numbers, and that the meanings must be interpreted according to the |
| 13961 | type and circumstances of the call. |
| 13962 | |
| 13963 | The following is a complete list of the errors and their names as given |
| 13964 | in <_\bs_\by_\bs_\b/_\be_\br_\br_\bn_\bo_\b._\bh>. |
| 13965 | |
| 13966 | 0 _\bU_\bn_\bd_\be_\bf_\bi_\bn_\be_\bd _\be_\br_\br_\bo_\br_\b: _\b0. Not used. |
| 13967 | |
| 13968 | 1 EPERM _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bp_\be_\br_\bm_\bi_\bt_\bt_\be_\bd. An attempt was made to perform an |
| 13969 | operation limited to processes with appropriate privileges or to |
| 13970 | the owner of a file or other resources. |
| 13971 | |
| 13972 | 2 ENOENT _\bN_\bo _\bs_\bu_\bc_\bh _\bf_\bi_\bl_\be _\bo_\br _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. A component of a specified pathname |
| 13973 | did not exist, or the pathname was an empty string. |
| 13974 | |
| 13975 | 3 ESRCH _\bN_\bo _\bs_\bu_\bc_\bh _\bp_\br_\bo_\bc_\be_\bs_\bs. No process could be found which corresponds to |
| 13976 | the given process ID. |
| 13977 | |
| 13978 | 4 EINTR _\bI_\bn_\bt_\be_\br_\br_\bu_\bp_\bt_\be_\bd _\bs_\by_\bs_\bt_\be_\bm _\bc_\ba_\bl_\bl. An asynchronous signal (such as SIGINT |
| 13979 | or SIGQUIT) was caught by the thread during the execution of an |
| 13980 | interruptible function. If the signal handler performs a normal |
| 13981 | return, the interrupted function call will seem to have returned |
| 13982 | the error condition. |
| 13983 | |
| 13984 | 5 EIO _\bI_\bn_\bp_\bu_\bt_\b/_\bo_\bu_\bt_\bp_\bu_\bt _\be_\br_\br_\bo_\br. Some physical input or output error occurred. |
| 13985 | This error will not be reported until a subsequent operation on |
| 13986 | the same file descriptor and may be lost (overwritten) by any |
| 13987 | subsequent errors. |
| 13988 | |
| 13989 | 6 ENXIO _\bD_\be_\bv_\bi_\bc_\be _\bn_\bo_\bt _\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\bd. Input or output on a special file referred |
| 13990 | to a device that did not exist, or made a request beyond the |
| 13991 | limits of the device. This error may also occur when, for |
| 13992 | example, a tape drive is not online or no disk pack is loaded on |
| 13993 | a drive. |
| 13994 | |
| 13995 | 7 E2BIG _\bA_\br_\bg_\bu_\bm_\be_\bn_\bt _\bl_\bi_\bs_\bt _\bt_\bo_\bo _\bl_\bo_\bn_\bg. The number of bytes used for the argument |
| 13996 | and environment list of the new process exceeded the limit NCARGS |
| 13997 | (specified in <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh>). |
| 13998 | |
| 13999 | 8 ENOEXEC _\bE_\bx_\be_\bc _\bf_\bo_\br_\bm_\ba_\bt _\be_\br_\br_\bo_\br. A request was made to execute a file that, |
| 14000 | although it has the appropriate permissions, was not in the |
| 14001 | format required for an executable file. |
| 14002 | |
| 14003 | 9 EBADF _\bB_\ba_\bd _\bf_\bi_\bl_\be _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br. A file descriptor argument was out of range, |
| 14004 | referred to no open file, or a read (write) request was made to a |
| 14005 | file that was only open for writing (reading). |
| 14006 | |
| 14007 | 10 ECHILD _\bN_\bo _\bc_\bh_\bi_\bl_\bd _\bp_\br_\bo_\bc_\be_\bs_\bs_\be_\bs. A wait(2) or waitpid(2) function was |
| 14008 | executed by a process that had no existing or unwaited-for child |
| 14009 | processes. |
| 14010 | |
| 14011 | 11 EDEADLK _\bR_\be_\bs_\bo_\bu_\br_\bc_\be _\bd_\be_\ba_\bd_\bl_\bo_\bc_\bk _\ba_\bv_\bo_\bi_\bd_\be_\bd. An attempt was made to lock a |
| 14012 | system resource that would have resulted in a deadlock situation. |
| 14013 | |
| 14014 | 12 ENOMEM _\bC_\ba_\bn_\bn_\bo_\bt _\ba_\bl_\bl_\bo_\bc_\ba_\bt_\be _\bm_\be_\bm_\bo_\br_\by. The new process image required more |
| 14015 | memory than was allowed by the hardware or by system-imposed |
| 14016 | memory management constraints. A lack of swap space is normally |
| 14017 | temporary; however, a lack of core is not. Soft limits may be |
| 14018 | increased to their corresponding hard limits. |
| 14019 | |
| 14020 | 13 EACCES _\bP_\be_\br_\bm_\bi_\bs_\bs_\bi_\bo_\bn _\bd_\be_\bn_\bi_\be_\bd. An attempt was made to access a file in a |
| 14021 | way forbidden by its file access permissions. |
| 14022 | |
| 14023 | 14 EFAULT _\bB_\ba_\bd _\ba_\bd_\bd_\br_\be_\bs_\bs. The system detected an invalid address in |
| 14024 | attempting to use an argument of a call. |
| 14025 | |
| 14026 | 15 ENOTBLK _\bB_\bl_\bo_\bc_\bk _\bd_\be_\bv_\bi_\bc_\be _\br_\be_\bq_\bu_\bi_\br_\be_\bd. A block device operation was attempted |
| 14027 | on a non-block device or file. |
| 14028 | |
| 14029 | 16 EBUSY _\bD_\be_\bv_\bi_\bc_\be _\bb_\bu_\bs_\by. An attempt to use a system resource which was in |
| 14030 | use at the time in a manner which would have conflicted with the |
| 14031 | request. |
| 14032 | |
| 14033 | 17 EEXIST _\bF_\bi_\bl_\be _\be_\bx_\bi_\bs_\bt_\bs. An existing file was mentioned in an inappropriate |
| 14034 | context, for instance, as the new link name in a link(2) |
| 14035 | function. |
| 14036 | |
| 14037 | 18 EXDEV _\bC_\br_\bo_\bs_\bs_\b-_\bd_\be_\bv_\bi_\bc_\be _\bl_\bi_\bn_\bk. A hard link to a file on another file system |
| 14038 | was attempted. |
| 14039 | |
| 14040 | 19 ENODEV _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd _\bb_\by _\bd_\be_\bv_\bi_\bc_\be. An attempt was made to apply |
| 14041 | an inappropriate function to a device, for example, trying to |
| 14042 | read a write-only device such as a printer. |
| 14043 | |
| 14044 | 20 ENOTDIR _\bN_\bo_\bt _\ba _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. A component of the specified pathname |
| 14045 | existed, but it was not a directory, when a directory was |
| 14046 | expected. |
| 14047 | |
| 14048 | 21 EISDIR _\bI_\bs _\ba _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. An attempt was made to open a directory with |
| 14049 | write mode specified. |
| 14050 | |
| 14051 | 22 EINVAL _\bI_\bn_\bv_\ba_\bl_\bi_\bd _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt. Some invalid argument was supplied. (For |
| 14052 | example, specifying an undefined signal to a signal(3) or kill(2) |
| 14053 | function). |
| 14054 | |
| 14055 | 23 ENFILE _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bo_\bp_\be_\bn _\bf_\bi_\bl_\be_\bs _\bi_\bn _\bs_\by_\bs_\bt_\be_\bm. Maximum number of file |
| 14056 | descriptors allowable on the system has been reached and a |
| 14057 | request for an open cannot be satisfied until at least one has |
| 14058 | been closed. The sysctl(3) variable _\bk_\be_\br_\bn_\b._\bm_\ba_\bx_\bf_\bi_\bl_\be_\bs contains the |
| 14059 | current limit. |
| 14060 | |
| 14061 | 24 EMFILE _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bo_\bp_\be_\bn _\bf_\bi_\bl_\be_\bs. The maximum number of file descriptors |
| 14062 | allowable for this process has been reached and a request for an |
| 14063 | open cannot be satisfied until at least one has been closed. |
| 14064 | getdtablesize(3) will obtain the current limit. |
| 14065 | |
| 14066 | 25 ENOTTY _\bI_\bn_\ba_\bp_\bp_\br_\bo_\bp_\br_\bi_\ba_\bt_\be _\bi_\bo_\bc_\bt_\bl _\bf_\bo_\br _\bd_\be_\bv_\bi_\bc_\be. A control function (see |
| 14067 | ioctl(2)) was attempted for a file or special device for which |
| 14068 | the operation was inappropriate. |
| 14069 | |
| 14070 | 26 ETXTBSY _\bT_\be_\bx_\bt _\bf_\bi_\bl_\be _\bb_\bu_\bs_\by. An attempt was made either to execute a pure |
| 14071 | procedure (shared text) file which was open for writing by |
| 14072 | another process, or to open with write access a pure procedure |
| 14073 | file that is currently being executed. |
| 14074 | |
| 14075 | 27 EFBIG _\bF_\bi_\bl_\be _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be. The size of a file exceeded the maximum. (The |
| 14076 | system-wide maximum file size is 2**63 bytes. Each file system |
| 14077 | may impose a lower limit for files contained within it.) |
| 14078 | |
| 14079 | 28 ENOSPC _\bN_\bo _\bs_\bp_\ba_\bc_\be _\bl_\be_\bf_\bt _\bo_\bn _\bd_\be_\bv_\bi_\bc_\be. A write(2) to an ordinary file, the |
| 14080 | creation of a directory or symbolic link, or the creation of a |
| 14081 | directory entry failed because no more disk blocks were available |
| 14082 | on the file system, or the allocation of an inode for a newly |
| 14083 | created file failed because no more inodes were available on the |
| 14084 | file system. |
| 14085 | |
| 14086 | 29 ESPIPE _\bI_\bl_\bl_\be_\bg_\ba_\bl _\bs_\be_\be_\bk. An lseek(2) function was issued on a socket, pipe |
| 14087 | or FIFO. |
| 14088 | |
| 14089 | 30 EROFS _\bR_\be_\ba_\bd_\b-_\bo_\bn_\bl_\by _\bf_\bi_\bl_\be _\bs_\by_\bs_\bt_\be_\bm. An attempt was made to modify a file or |
| 14090 | create a directory on a file system that was read-only at the |
| 14091 | time. |
| 14092 | |
| 14093 | 31 EMLINK _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bl_\bi_\bn_\bk_\bs. The maximum allowable number of hard links to a |
| 14094 | single file has been exceeded (see pathconf(2) for how to obtain |
| 14095 | this value). |
| 14096 | |
| 14097 | 32 EPIPE _\bB_\br_\bo_\bk_\be_\bn _\bp_\bi_\bp_\be. A write on a pipe, socket or FIFO for which there |
| 14098 | is no process to read the data. |
| 14099 | |
| 14100 | 33 EDOM _\bN_\bu_\bm_\be_\br_\bi_\bc_\ba_\bl _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt _\bo_\bu_\bt _\bo_\bf _\bd_\bo_\bm_\ba_\bi_\bn. A numerical input argument was |
| 14101 | outside the defined domain of the mathematical function. |
| 14102 | |
| 14103 | 34 ERANGE _\bR_\be_\bs_\bu_\bl_\bt _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be. A result of the function was too large to fit |
| 14104 | in the available space (perhaps exceeded precision). |
| 14105 | |
| 14106 | 35 EAGAIN _\bR_\be_\bs_\bo_\bu_\br_\bc_\be _\bt_\be_\bm_\bp_\bo_\br_\ba_\br_\bi_\bl_\by _\bu_\bn_\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. This is a temporary condition |
| 14107 | and later calls to the same routine may complete normally. |
| 14108 | |
| 14109 | 36 EINPROGRESS _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bw _\bi_\bn _\bp_\br_\bo_\bg_\br_\be_\bs_\bs. An operation that takes a long |
| 14110 | time to complete (such as a connect(2)) was attempted on a non- |
| 14111 | blocking object (see fcntl(2)). |
| 14112 | |
| 14113 | 37 EALREADY _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\ba_\bl_\br_\be_\ba_\bd_\by _\bi_\bn _\bp_\br_\bo_\bg_\br_\be_\bs_\bs. An operation was attempted on |
| 14114 | a non-blocking object that already had an operation in progress. |
| 14115 | |
| 14116 | 38 ENOTSOCK _\bS_\bo_\bc_\bk_\be_\bt _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bo_\bn _\bn_\bo_\bn_\b-_\bs_\bo_\bc_\bk_\be_\bt. Self-explanatory. |
| 14117 | |
| 14118 | 39 EDESTADDRREQ _\bD_\be_\bs_\bt_\bi_\bn_\ba_\bt_\bi_\bo_\bn _\ba_\bd_\bd_\br_\be_\bs_\bs _\br_\be_\bq_\bu_\bi_\br_\be_\bd. A required address was |
| 14119 | omitted from an operation on a socket. |
| 14120 | |
| 14121 | 40 EMSGSIZE _\bM_\be_\bs_\bs_\ba_\bg_\be _\bt_\bo_\bo _\bl_\bo_\bn_\bg. A message sent on a socket was larger than |
| 14122 | the internal message buffer or some other network limit. |
| 14123 | |
| 14124 | 41 EPROTOTYPE _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bw_\br_\bo_\bn_\bg _\bt_\by_\bp_\be _\bf_\bo_\br _\bs_\bo_\bc_\bk_\be_\bt. A protocol was specified |
| 14125 | that does not support the semantics of the socket type requested. |
| 14126 | For example, you cannot use the Internet UDP protocol with type |
| 14127 | SOCK_STREAM. |
| 14128 | |
| 14129 | 42 ENOPROTOOPT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bn_\bo_\bt _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. A bad option or level was |
| 14130 | specified in a getsockopt(2) or setsockopt(2) call. |
| 14131 | |
| 14132 | 43 EPROTONOSUPPORT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The protocol has not been |
| 14133 | configured into the system or no implementation for it exists. |
| 14134 | |
| 14135 | 44 ESOCKTNOSUPPORT _\bS_\bo_\bc_\bk_\be_\bt _\bt_\by_\bp_\be _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The support for the socket |
| 14136 | type has not been configured into the system or no implementation |
| 14137 | for it exists. |
| 14138 | |
| 14139 | 45 EOPNOTSUPP _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The attempted operation is not |
| 14140 | supported for the type of object referenced. Usually this occurs |
| 14141 | when a file descriptor refers to a file or socket that cannot |
| 14142 | support this operation, for example, trying to _\ba_\bc_\bc_\be_\bp_\bt a |
| 14143 | connection on a datagram socket. |
| 14144 | |
| 14145 | 46 EPFNOSUPPORT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bf_\ba_\bm_\bi_\bl_\by _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The protocol family has |
| 14146 | not been configured into the system or no implementation for it |
| 14147 | exists. |
| 14148 | |
| 14149 | 47 EAFNOSUPPORT _\bA_\bd_\bd_\br_\be_\bs_\bs _\bf_\ba_\bm_\bi_\bl_\by _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd _\bb_\by _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bf_\ba_\bm_\bi_\bl_\by. An |
| 14150 | address incompatible with the requested protocol was used. For |
| 14151 | example, you shouldn't necessarily expect to be able to use NS |
| 14152 | addresses with Internet protocols. |
| 14153 | |
| 14154 | 48 EADDRINUSE _\bA_\bd_\bd_\br_\be_\bs_\bs _\ba_\bl_\br_\be_\ba_\bd_\by _\bi_\bn _\bu_\bs_\be. Only one usage of each address is |
| 14155 | normally permitted. |
| 14156 | |
| 14157 | 49 EADDRNOTAVAIL _\bC_\ba_\bn_\b'_\bt _\ba_\bs_\bs_\bi_\bg_\bn _\br_\be_\bq_\bu_\be_\bs_\bt_\be_\bd _\ba_\bd_\bd_\br_\be_\bs_\bs. Normally results from an |
| 14158 | attempt to create a socket with an address not on this machine. |
| 14159 | |
| 14160 | 50 ENETDOWN _\bN_\be_\bt_\bw_\bo_\br_\bk _\bi_\bs _\bd_\bo_\bw_\bn. A socket operation encountered a dead |
| 14161 | network. |
| 14162 | |
| 14163 | 51 ENETUNREACH _\bN_\be_\bt_\bw_\bo_\br_\bk _\bi_\bs _\bu_\bn_\br_\be_\ba_\bc_\bh_\ba_\bb_\bl_\be. A socket operation was attempted |
| 14164 | to an unreachable network. |
| 14165 | |
| 14166 | 52 ENETRESET _\bN_\be_\bt_\bw_\bo_\br_\bk _\bd_\br_\bo_\bp_\bp_\be_\bd _\bc_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\bo_\bn _\br_\be_\bs_\be_\bt. The host you were |
| 14167 | connected to crashed and rebooted. |
| 14168 | |
| 14169 | 53 ECONNABORTED _\bS_\bo_\bf_\bt_\bw_\ba_\br_\be _\bc_\ba_\bu_\bs_\be_\bd _\bc_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\ba_\bb_\bo_\br_\bt. A connection abort was |
| 14170 | caused internal to your host machine. |
| 14171 | |
| 14172 | 54 ECONNRESET _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\br_\be_\bs_\be_\bt _\bb_\by _\bp_\be_\be_\br. A connection was forcibly closed |
| 14173 | by a peer. This normally results from a loss of the connection |
| 14174 | on the remote socket due to a timeout or a reboot. |
| 14175 | |
| 14176 | 55 ENOBUFS _\bN_\bo _\bb_\bu_\bf_\bf_\be_\br _\bs_\bp_\ba_\bc_\be _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. An operation on a socket or pipe |
| 14177 | was not performed because the system lacked sufficient buffer |
| 14178 | space or because a queue was full. |
| 14179 | |
| 14180 | 56 EISCONN _\bS_\bo_\bc_\bk_\be_\bt _\bi_\bs _\ba_\bl_\br_\be_\ba_\bd_\by _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd. A connect(2) request was made on |
| 14181 | an already connected socket; or, a sendto(2) or sendmsg(2) |
| 14182 | request on a connected socket specified a destination when |
| 14183 | already connected. |
| 14184 | |
| 14185 | 57 ENOTCONN _\bS_\bo_\bc_\bk_\be_\bt _\bi_\bs _\bn_\bo_\bt _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd. A request to send or receive data |
| 14186 | was disallowed because the socket was not connected and (when |
| 14187 | sending on a datagram socket) no address was supplied. |
| 14188 | |
| 14189 | 58 ESHUTDOWN _\bC_\ba_\bn_\b'_\bt _\bs_\be_\bn_\bd _\ba_\bf_\bt_\be_\br _\bs_\bo_\bc_\bk_\be_\bt _\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn. A request to send data was |
| 14190 | disallowed because the socket had already been shut down with a |
| 14191 | previous shutdown(2) call. |
| 14192 | |
| 14193 | 59 ETOOMANYREFS _\bT_\bo_\bo _\bm_\ba_\bn_\by _\br_\be_\bf_\be_\br_\be_\bn_\bc_\be_\bs_\b: _\bc_\ba_\bn_\b'_\bt _\bs_\bp_\bl_\bi_\bc_\be. Not used in OpenBSD. |
| 14194 | |
| 14195 | 60 ETIMEDOUT _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bt_\bi_\bm_\be_\bd _\bo_\bu_\bt. A connect(2) or send(2) request failed |
| 14196 | because the connected party did not properly respond after a |
| 14197 | period of time. (The timeout period is dependent on the |
| 14198 | communication protocol.) |
| 14199 | |
| 14200 | 61 ECONNREFUSED _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\br_\be_\bf_\bu_\bs_\be_\bd. No connection could be made because |
| 14201 | the target machine actively refused it. This usually results |
| 14202 | from trying to connect to a service that is inactive on the |
| 14203 | foreign host. |
| 14204 | |
| 14205 | 62 ELOOP _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bl_\be_\bv_\be_\bl_\bs _\bo_\bf _\bs_\by_\bm_\bb_\bo_\bl_\bi_\bc _\bl_\bi_\bn_\bk_\bs. A path name lookup involved |
| 14206 | more than 32 (SYMLOOP_MAX) symbolic links. |
| 14207 | |
| 14208 | 63 ENAMETOOLONG _\bF_\bi_\bl_\be _\bn_\ba_\bm_\be _\bt_\bo_\bo _\bl_\bo_\bn_\bg. A component of a pathname exceeded |
| 14209 | 255 (NAME_MAX) characters, or an entire pathname (including the |
| 14210 | terminating NUL) exceeded 1024 (PATH_MAX) bytes. |
| 14211 | |
| 14212 | 64 EHOSTDOWN _\bH_\bo_\bs_\bt _\bi_\bs _\bd_\bo_\bw_\bn. A socket operation failed because the |
| 14213 | destination host was down. |
| 14214 | |
| 14215 | 65 EHOSTUNREACH _\bN_\bo _\br_\bo_\bu_\bt_\be _\bt_\bo _\bh_\bo_\bs_\bt. A socket operation was attempted to an |
| 14216 | unreachable host. |
| 14217 | |
| 14218 | 66 ENOTEMPTY _\bD_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bn_\bo_\bt _\be_\bm_\bp_\bt_\by. A directory with entries other than `.' |
| 14219 | and `..' was supplied to a remove directory or rename call. |
| 14220 | |
| 14221 | 67 EPROCLIM _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bp_\br_\bo_\bc_\be_\bs_\bs_\be_\bs. |
| 14222 | |
| 14223 | 68 EUSERS _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bu_\bs_\be_\br_\bs. The quota system ran out of table entries. |
| 14224 | |
| 14225 | 69 EDQUOT _\bD_\bi_\bs_\bc _\bq_\bu_\bo_\bt_\ba _\be_\bx_\bc_\be_\be_\bd_\be_\bd. A write(2) to an ordinary file, the |
| 14226 | creation of a directory or symbolic link, or the creation of a |
| 14227 | directory entry failed because the user's quota of disk blocks |
| 14228 | was exhausted, or the allocation of an inode for a newly created |
| 14229 | file failed because the user's quota of inodes was exhausted. |
| 14230 | |
| 14231 | 70 ESTALE _\bS_\bt_\ba_\bl_\be _\bN_\bF_\bS _\bf_\bi_\bl_\be _\bh_\ba_\bn_\bd_\bl_\be. An attempt was made to access an open |
| 14232 | file on an NFS filesystem which is now unavailable as referenced |
| 14233 | by the file descriptor. This may indicate the file was deleted |
| 14234 | on the NFS server or some other catastrophic event occurred. |
| 14235 | |
| 14236 | 72 EBADRPC _\bR_\bP_\bC _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bs _\bb_\ba_\bd. Exchange of rpc(3) information was |
| 14237 | unsuccessful. |
| 14238 | |
| 14239 | 73 ERPCMISMATCH _\bR_\bP_\bC _\bv_\be_\br_\bs_\bi_\bo_\bn _\bw_\br_\bo_\bn_\bg. The version of rpc(3) on the remote |
| 14240 | peer is not compatible with the local version. |
| 14241 | |
| 14242 | 74 EPROGUNAVAIL _\bR_\bP_\bC _\bp_\br_\bo_\bg_\b. _\bn_\bo_\bt _\ba_\bv_\ba_\bi_\bl. The requested rpc(3) program is not |
| 14243 | registered on the remote host. |
| 14244 | |
| 14245 | 75 EPROGMISMATCH _\bP_\br_\bo_\bg_\br_\ba_\bm _\bv_\be_\br_\bs_\bi_\bo_\bn _\bw_\br_\bo_\bn_\bg. The requested version of the |
| 14246 | rpc(3) program is not available on the remote host. |
| 14247 | |
| 14248 | 76 EPROCUNAVAIL _\bB_\ba_\bd _\bp_\br_\bo_\bc_\be_\bd_\bu_\br_\be _\bf_\bo_\br _\bp_\br_\bo_\bg_\br_\ba_\bm. An rpc(3) call was attempted |
| 14249 | for a procedure which doesn't exist in the remote program. |
| 14250 | |
| 14251 | 77 ENOLCK _\bN_\bo _\bl_\bo_\bc_\bk_\bs _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. A system-imposed limit on the number of |
| 14252 | simultaneous file locks was reached. |
| 14253 | |
| 14254 | 78 ENOSYS _\bF_\bu_\bn_\bc_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd. Attempted a system call that is not |
| 14255 | available on this system. |
| 14256 | |
| 14257 | 79 EFTYPE _\bI_\bn_\ba_\bp_\bp_\br_\bo_\bp_\br_\bi_\ba_\bt_\be _\bf_\bi_\bl_\be _\bt_\by_\bp_\be _\bo_\br _\bf_\bo_\br_\bm_\ba_\bt. The file contains invalid |
| 14258 | data or set to invalid modes. |
| 14259 | |
| 14260 | 80 EAUTH _\bA_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\be_\br_\br_\bo_\br. Attempted to use an invalid authentication |
| 14261 | ticket to mount a NFS filesystem. |
| 14262 | |
| 14263 | 81 ENEEDAUTH _\bN_\be_\be_\bd _\ba_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\bo_\br. An authentication ticket must be |
| 14264 | obtained before the given NFS filesystem may be mounted. |
| 14265 | |
| 14266 | 82 EIPSEC _\bI_\bP_\bs_\be_\bc _\bp_\br_\bo_\bc_\be_\bs_\bs_\bi_\bn_\bg _\bf_\ba_\bi_\bl_\bu_\br_\be. IPsec subsystem error. Not used in |
| 14267 | OpenBSD. |
| 14268 | |
| 14269 | 83 ENOATTR _\bA_\bt_\bt_\br_\bi_\bb_\bu_\bt_\be _\bn_\bo_\bt _\bf_\bo_\bu_\bn_\bd. A UFS Extended Attribute is not found for |
| 14270 | the specified pathname. |
| 14271 | |
| 14272 | 84 EILSEQ _\bI_\bl_\bl_\be_\bg_\ba_\bl _\bb_\by_\bt_\be _\bs_\be_\bq_\bu_\be_\bn_\bc_\be. An illegal sequence of bytes was used |
| 14273 | when using wide characters. |
| 14274 | |
| 14275 | 85 ENOMEDIUM _\bN_\bo _\bm_\be_\bd_\bi_\bu_\bm _\bf_\bo_\bu_\bn_\bd. Attempted to use a removable media device |
| 14276 | with no medium present. |
| 14277 | |
| 14278 | 86 EMEDIUMTYPE _\bW_\br_\bo_\bn_\bg _\bm_\be_\bd_\bi_\bu_\bm _\bt_\by_\bp_\be. Attempted to use a removable media |
| 14279 | device with incorrect or incompatible medium. |
| 14280 | |
| 14281 | 87 EOVERFLOW _\bV_\ba_\bl_\bu_\be _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be _\bt_\bo _\bb_\be _\bs_\bt_\bo_\br_\be_\bd _\bi_\bn _\bd_\ba_\bt_\ba _\bt_\by_\bp_\be. A numerical |
| 14282 | result of the function was too large to be stored in the caller |
| 14283 | provided space. |
| 14284 | |
| 14285 | 88 ECANCELED _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bc_\ba_\bn_\bc_\be_\bl_\be_\bd. The requested operation was canceled. |
| 14286 | |
| 14287 | 89 EIDRM _\bI_\bd_\be_\bn_\bt_\bi_\bf_\bi_\be_\br _\br_\be_\bm_\bo_\bv_\be_\bd. An IPC identifier was removed while the |
| 14288 | current thread was waiting on it. |
| 14289 | |
| 14290 | 90 ENOMSG _\bN_\bo _\bm_\be_\bs_\bs_\ba_\bg_\be _\bo_\bf _\bd_\be_\bs_\bi_\br_\be_\bd _\bt_\by_\bp_\be. An IPC message queue does not |
| 14291 | contain a message of the desired type, or a message catalog does |
| 14292 | not contain the requested message. |
| 14293 | |
| 14294 | 91 ENOTSUP _\bN_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The operation has requested an unsupported |
| 14295 | value. |
| 14296 | |
| 14297 | D\bDE\bEF\bFI\bIN\bNI\bIT\bTI\bIO\bON\bNS\bS |
| 14298 | Process |
| 14299 | A process is a collection of one or more threads, plus the |
| 14300 | resources shared by those threads such as process ID, address |
| 14301 | space, user IDs and group IDs, and root directory and current |
| 14302 | working directory. |
| 14303 | |
| 14304 | Process ID |
| 14305 | Each active process in the system is uniquely identified by a |
| 14306 | non-negative integer called a process ID. The range of this ID |
| 14307 | is from 1 to 32766. |
| 14308 | |
| 14309 | Parent Process ID |
| 14310 | A new process is created by a currently active process; (see |
| 14311 | fork(2)). The parent process ID of a process is initially the |
| 14312 | process ID of its creator. If the creating process exits, the |
| 14313 | parent process ID of each child is set to the ID of a system |
| 14314 | process, init(8). |
| 14315 | |
| 14316 | Process Group |
| 14317 | Each active process is a member of a process group that is |
| 14318 | identified by a non-negative integer called the process group ID. |
| 14319 | This is the process ID of the group leader. This grouping |
| 14320 | permits the signaling of related processes (see termios(4)) and |
| 14321 | the job control mechanisms of csh(1). |
| 14322 | |
| 14323 | Session |
| 14324 | A session is a set of one or more process groups. A session is |
| 14325 | created by a successful call to setsid(2), which causes the |
| 14326 | caller to become the only member of the only process group in the |
| 14327 | new session. |
| 14328 | |
| 14329 | Session Leader |
| 14330 | A process that has created a new session by a successful call to |
| 14331 | setsid(2), is known as a session leader. Only a session leader |
| 14332 | may acquire a terminal as its controlling terminal (see |
| 14333 | termios(4)). |
| 14334 | |
| 14335 | Controlling Process |
| 14336 | A session leader with a controlling terminal is a controlling |
| 14337 | process. |
| 14338 | |
| 14339 | Controlling Terminal |
| 14340 | A terminal that is associated with a session is known as the |
| 14341 | controlling terminal for that session and its members. |
| 14342 | |
| 14343 | Terminal Process Group ID |
| 14344 | A terminal may be acquired by a session leader as its controlling |
| 14345 | terminal. Once a terminal is associated with a session, any of |
| 14346 | the process groups within the session may be placed into the |
| 14347 | foreground by setting the terminal process group ID to the ID of |
| 14348 | the process group. This facility is used to arbitrate between |
| 14349 | multiple jobs contending for the same terminal; (see csh(1) and |
| 14350 | tty(4)). |
| 14351 | |
| 14352 | Orphaned Process Group |
| 14353 | A process group is considered to be _\bo_\br_\bp_\bh_\ba_\bn_\be_\bd if it is not under |
| 14354 | the control of a job control shell. More precisely, a process |
| 14355 | group is orphaned when none of its members has a parent process |
| 14356 | that is in the same session as the group, but is in a different |
| 14357 | process group. Note that when a process exits, the parent |
| 14358 | process for its children is changed to be init(8), which is in a |
| 14359 | separate session. Not all members of an orphaned process group |
| 14360 | are necessarily orphaned processes (those whose creating process |
| 14361 | has exited). The process group of a session leader is orphaned |
| 14362 | by definition. |
| 14363 | |
| 14364 | Thread A thread is a preemptively scheduled flow of control within a |
| 14365 | process, with its own set of register values, floating point |
| 14366 | environment, thread ID, signal mask, pending signal set, |
| 14367 | alternate signal stack, thread control block address, resource |
| 14368 | utilization, errno variable location, and values for thread- |
| 14369 | specific keys. A process initially has just one thread, a |
| 14370 | duplicate of the thread in the parent process that created this |
| 14371 | process. |
| 14372 | |
| 14373 | Real User ID and Real Group ID |
| 14374 | Each user on the system is identified by a positive integer |
| 14375 | termed the real user ID. |
| 14376 | |
| 14377 | Each user is also a member of one or more groups. One of these |
| 14378 | groups is distinguished from others and used in implementing |
| 14379 | accounting facilities. The positive integer corresponding to |
| 14380 | this distinguished group is termed the real group ID. |
| 14381 | |
| 14382 | All processes have a real user ID and real group ID. These are |
| 14383 | initialized from the equivalent attributes of the process that |
| 14384 | created it. |
| 14385 | |
| 14386 | Effective User ID, Effective Group ID, and Group Access List |
| 14387 | Access to system resources is governed by two values: the |
| 14388 | effective user ID, and the group access list. The first member |
| 14389 | of the group access list is also known as the effective group ID. |
| 14390 | (In POSIX.1, the group access list is known as the set of |
| 14391 | supplementary group IDs, and it is unspecified whether the |
| 14392 | effective group ID is a member of the list.) |
| 14393 | |
| 14394 | The effective user ID and effective group ID are initially the |
| 14395 | process's real user ID and real group ID respectively. Either |
| 14396 | may be modified through execution of a set-user-ID or set-group- |
| 14397 | ID file (possibly by one of its ancestors) (see execve(2)). By |
| 14398 | convention, the effective group ID (the first member of the group |
| 14399 | access list) is duplicated, so that the execution of a set-group- |
| 14400 | ID program does not result in the loss of the original (real) |
| 14401 | group ID. |
| 14402 | |
| 14403 | The group access list is a set of group IDs used only in |
| 14404 | determining resource accessibility. Access checks are performed |
| 14405 | as described below in ``File Access Permissions''. |
| 14406 | |
| 14407 | Saved Set User ID and Saved Set Group ID |
| 14408 | When a process executes a new file, the effective user ID is set |
| 14409 | to the owner of the file if the file is set-user-ID, and the |
| 14410 | effective group ID (first element of the group access list) is |
| 14411 | set to the group of the file if the file is set-group-ID. The |
| 14412 | effective user ID of the process is then recorded as the saved |
| 14413 | set-user-ID, and the effective group ID of the process is |
| 14414 | recorded as the saved set-group-ID. These values may be used to |
| 14415 | regain those values as the effective user or group ID after |
| 14416 | reverting to the real ID (see setuid(2)). (In POSIX.1, the saved |
| 14417 | set-user-ID and saved set-group-ID are optional, and are used in |
| 14418 | setuid and setgid, but this does not work as desired for the |
| 14419 | superuser.) |
| 14420 | |
| 14421 | Superuser |
| 14422 | A process is recognized as a _\bs_\bu_\bp_\be_\br_\bu_\bs_\be_\br process and is granted |
| 14423 | special privileges if its effective user ID is 0. |
| 14424 | |
| 14425 | Special Processes |
| 14426 | The processes with process IDs of 0 and 1 are special. Process 0 |
| 14427 | is the scheduler. Process 1 is the initialization process |
| 14428 | init(8), and is the ancestor of every other process in the |
| 14429 | system. It is used to control the process structure. |
| 14430 | |
| 14431 | Descriptor |
| 14432 | An integer assigned by the system when a file is referenced by |
| 14433 | open(2) or dup(2), or when a socket is created by pipe(2), |
| 14434 | socket(2) or socketpair(2), which uniquely identifies an access |
| 14435 | path to that file or socket from a given process or any of its |
| 14436 | children. |
| 14437 | |
| 14438 | File Name |
| 14439 | Names consisting of up to 255 (NAME_MAX) characters may be used |
| 14440 | to name an ordinary file, special file, or directory. |
| 14441 | |
| 14442 | These characters may be arbitrary eight-bit values, excluding 0 |
| 14443 | (NUL) and the ASCII code for `/' (slash). |
| 14444 | |
| 14445 | Note that it is generally unwise to use `*', `?', `[' or `]' as |
| 14446 | part of file names because of the special meaning attached to |
| 14447 | these characters by the shell. |
| 14448 | |
| 14449 | Note also that NAME_MAX is an upper limit fixed by the kernel, |
| 14450 | meant to be used for sizing buffers. Some filesystems may have |
| 14451 | additional restrictions. These can be queried using pathconf(2) |
| 14452 | and fpathconf(2). |
| 14453 | |
| 14454 | Path Name |
| 14455 | A path name is a NUL-terminated character string starting with an |
| 14456 | optional slash `/', followed by zero or more directory names |
| 14457 | separated by slashes, optionally followed by a file name. The |
| 14458 | total length of a path name must be less than 1024 (PATH_MAX) |
| 14459 | characters. Additional restrictions may apply, depending upon |
| 14460 | the filesystem, to be queried with pathconf(2) or fpathconf(2) if |
| 14461 | needed. |
| 14462 | |
| 14463 | If a path name begins with a slash, the path search begins at the |
| 14464 | _\br_\bo_\bo_\bt directory. Otherwise, the search begins from the current |
| 14465 | working directory. A slash by itself names the root directory. |
| 14466 | An empty pathname is invalid. |
| 14467 | |
| 14468 | Directory |
| 14469 | A directory is a special type of file that contains entries that |
| 14470 | are references to other files. Directory entries are called |
| 14471 | links. By convention, a directory contains at least two links, |
| 14472 | `.' and `..', referred to as _\bd_\bo_\bt and _\bd_\bo_\bt_\b-_\bd_\bo_\bt respectively. Dot |
| 14473 | refers to the directory itself and dot-dot refers to its parent |
| 14474 | directory. |
| 14475 | |
| 14476 | Root Directory and Current Working Directory |
| 14477 | Each process has associated with it a concept of a root directory |
| 14478 | and a current working directory for the purpose of resolving path |
| 14479 | name searches. A process's root directory need not be the root |
| 14480 | directory of the root file system. |
| 14481 | |
| 14482 | File Access Permissions |
| 14483 | Every file in the file system has a set of access permissions. |
| 14484 | These permissions are used in determining whether a process may |
| 14485 | perform a requested operation on the file (such as opening a file |
| 14486 | for writing). Access permissions are established at the time a |
| 14487 | file is created. They may be changed at some later time through |
| 14488 | the chmod(2) call. |
| 14489 | |
| 14490 | File access is broken down according to whether a file may be: |
| 14491 | read, written, or executed. Directory files use the execute |
| 14492 | permission to control if the directory may be searched. |
| 14493 | |
| 14494 | File access permissions are interpreted by the system as they |
| 14495 | apply to three different classes of users: the owner of the file, |
| 14496 | those users in the file's group, anyone else. Every file has an |
| 14497 | independent set of access permissions for each of these classes. |
| 14498 | When an access check is made, the system decides if permission |
| 14499 | should be granted by checking the access information applicable |
| 14500 | to the caller. |
| 14501 | |
| 14502 | Read, write, and execute/search permissions on a file are granted |
| 14503 | to a process if: |
| 14504 | |
| 14505 | The process's effective user ID is that of the superuser. (Note: |
| 14506 | even the superuser cannot execute a non-executable file.) |
| 14507 | |
| 14508 | The process's effective user ID matches the user ID of the owner |
| 14509 | of the file and the owner permissions allow the access. |
| 14510 | |
| 14511 | The process's effective user ID does not match the user ID of the |
| 14512 | owner of the file, and either the process's effective group ID |
| 14513 | matches the group ID of the file, or the group ID of the file is |
| 14514 | in the process's group access list, and the group permissions |
| 14515 | allow the access. |
| 14516 | |
| 14517 | Neither the effective user ID nor effective group ID and group |
| 14518 | access list of the process match the corresponding user ID and |
| 14519 | group ID of the file, but the permissions for ``other users'' |
| 14520 | allow access. |
| 14521 | |
| 14522 | Otherwise, permission is denied. |
| 14523 | |
| 14524 | Sockets and Address Families |
| 14525 | A socket is an endpoint for communication between processes. |
| 14526 | Each socket has queues for sending and receiving data. |
| 14527 | |
| 14528 | Sockets are typed according to their communications properties. |
| 14529 | These properties include whether messages sent and received at a |
| 14530 | socket require the name of the partner, whether communication is |
| 14531 | reliable, the format used in naming message recipients, etc. |
| 14532 | |
| 14533 | Each instance of the system supports some collection of socket |
| 14534 | types; consult socket(2) for more information about the types |
| 14535 | available and their properties. |
| 14536 | |
| 14537 | Each instance of the system supports some number of sets of |
| 14538 | communications protocols. Each protocol set supports addresses |
| 14539 | of a certain format. An Address Family is the set of addresses |
| 14540 | for a specific group of protocols. Each socket has an address |
| 14541 | chosen from the address family in which the socket was created. |
| 14542 | |
| 14543 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 14544 | intro(3), perror(3) |
| 14545 | |
| 14546 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 14547 | An k\bkq\bqu\bue\beu\bue\be manual page appeared in Version 6 AT&T UNIX. |
| 14548 | |
| 14549 | N\bNA\bAM\bME\bE |
| 14550 | i\bio\boc\bct\btl\bl - control device |
| 14551 | |
| 14552 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 14553 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/i\bio\boc\bct\btl\bl.\b.h\bh>\b> |
| 14554 | |
| 14555 | _\bi_\bn_\bt |
| 14556 | i\bio\boc\bct\btl\bl(_\bi_\bn_\bt _\bd, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\br_\be_\bq_\bu_\be_\bs_\bt, _\b._\b._\b.); |
| 14557 | |
| 14558 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 14559 | The i\bio\boc\bct\btl\bl() function manipulates the underlying device parameters of |
| 14560 | special files. In particular, many operating characteristics of |
| 14561 | character special files (e.g., terminals) may be controlled with i\bio\boc\bct\btl\bl() |
| 14562 | requests. |
| 14563 | |
| 14564 | The argument _\bd must be an open file descriptor. The third argument is |
| 14565 | called _\ba_\br_\bg and contains additional information needed by this device to |
| 14566 | perform the requested function. _\ba_\br_\bg is either an int or a pointer to a |
| 14567 | device-specific data structure, depending upon the given _\br_\be_\bq_\bu_\be_\bs_\bt. |
| 14568 | |
| 14569 | An k\bkq\bqu\bue\beu\bue\be _\br_\be_\bq_\bu_\be_\bs_\bt has encoded in it whether the argument is an ``in'' |
| 14570 | parameter or ``out'' parameter, and the size of the third argument (_\ba_\br_\bg) |
| 14571 | in bytes. Macros and defines used in specifying an ioctl _\br_\be_\bq_\bu_\be_\bs_\bt are |
| 14572 | located in the file <_\bs_\by_\bs_\b/_\bi_\bo_\bc_\bt_\bl_\b._\bh>. |
| 14573 | |
| 14574 | G\bGE\bEN\bNE\bER\bRI\bIC\bC I\bIO\bOC\bCT\bTL\bLS\bS |
| 14575 | Some ioctls are applicable to any file descriptor. These include: |
| 14576 | |
| 14577 | FIOCLEX |
| 14578 | Set close-on-exec flag. The file will be closed when exec(3) is |
| 14579 | invoked. |
| 14580 | |
| 14581 | FIONCLEX |
| 14582 | Clear close-on-exec flag. The file will remain open across |
| 14583 | exec(3). |
| 14584 | |
| 14585 | Some generic ioctls are not implemented for all types of file |
| 14586 | descriptors. These include: |
| 14587 | |
| 14588 | FIONREAD _\bi_\bn_\bt _\b* |
| 14589 | Get the number of bytes that are immediately available for |
| 14590 | reading. |
| 14591 | |
| 14592 | FIONBIO _\bi_\bn_\bt _\b* |
| 14593 | Set non-blocking I/O mode if the argument is non-zero. In non- |
| 14594 | blocking mode, read(2) or write(2) calls return -1 and set _\be_\br_\br_\bn_\bo |
| 14595 | to EAGAIN immediately when no data is available. |
| 14596 | |
| 14597 | FIOASYNC _\bi_\bn_\bt _\b* |
| 14598 | Set asynchronous I/O mode if the argument is non-zero. In |
| 14599 | asynchronous mode, the process or process group specified by |
| 14600 | FIOSETOWN will start receiving SIGIO signals when data is |
| 14601 | available. The SIGIO signal will be delivered when data is |
| 14602 | available on the file descriptor. |
| 14603 | |
| 14604 | FIOSETOWN, FIOGETOWN _\bi_\bn_\bt _\b* |
| 14605 | Set/get the process or the process group (if negative) that |
| 14606 | should receive SIGIO signals when data is available. |
| 14607 | |
| 14608 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 14609 | If an error has occurred, a value of -1 is returned and _\be_\br_\br_\bn_\bo is set to |
| 14610 | indicate the error. |
| 14611 | |
| 14612 | E\bER\bRR\bRO\bOR\bRS\bS |
| 14613 | i\bio\boc\bct\btl\bl() will fail if: |
| 14614 | |
| 14615 | [EBADF] _\bd is not a valid descriptor. |
| 14616 | |
| 14617 | [ENOTTY] _\bd is not associated with a character special device. |
| 14618 | |
| 14619 | [ENOTTY] The specified request does not apply to the kind of |
| 14620 | object that the descriptor _\bd references. |
| 14621 | |
| 14622 | [EINVAL] _\br_\be_\bq_\bu_\be_\bs_\bt or _\ba_\br_\bg is not valid. |
| 14623 | |
| 14624 | [EFAULT] _\ba_\br_\bg points outside the process's allocated address |
| 14625 | space. |
| 14626 | |
| 14627 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 14628 | cdio(1), chio(1), mt(1), execve(2), fcntl(2), intro(4), tty(4) |
| 14629 | |
| 14630 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 14631 | An i\bio\boc\bct\btl\bl() function call appeared in Version 7 AT&T UNIX. |
| 14632 | |
| 14633 | N\bNA\bAM\bME\bE |
| 14634 | i\bis\bss\bse\bet\btu\bug\bgi\bid\bd - is current executable running setuid or setgid |
| 14635 | |
| 14636 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 14637 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 14638 | |
| 14639 | _\bi_\bn_\bt |
| 14640 | i\bis\bss\bse\bet\btu\bug\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
| 14641 | |
| 14642 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 14643 | The i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() function returns 1 if the process was made setuid or |
| 14644 | setgid as the result of the last or other previous e\bex\bxe\bec\bcv\bve\be() system calls. |
| 14645 | Otherwise it returns 0. |
| 14646 | |
| 14647 | This system call exists so that library routines (inside libtermlib, |
| 14648 | libc, or other libraries) can guarantee safe behavior when used inside |
| 14649 | setuid or setgid programs. Some library routines may be passed |
| 14650 | insufficient information and hence not know whether the current program |
| 14651 | was started setuid or setgid because higher level calling code may have |
| 14652 | made changes to the uid, euid, gid, or egid. Hence these low-level |
| 14653 | library routines are unable to determine if they are being run with |
| 14654 | elevated or normal privileges. |
| 14655 | |
| 14656 | In particular, it is wise to use this call to determine if a pathname |
| 14657 | returned from a g\bge\bet\bte\ben\bnv\bv() call may safely be used to o\bop\bpe\ben\bn() the specified |
| 14658 | file. Quite often this is not wise because the status of the effective |
| 14659 | uid is not known. |
| 14660 | |
| 14661 | The i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() system call's result is unaffected by calls to s\bse\bet\btu\bui\bid\bd(), |
| 14662 | s\bse\bet\btg\bgi\bid\bd(), or other such calls. In case of a f\bfo\bor\brk\bk(), the child process |
| 14663 | inherits the same status. |
| 14664 | |
| 14665 | The status of i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() is only affected by e\bex\bxe\bec\bcv\bve\be(). If a child |
| 14666 | process executes a new executable file, a new issetugid status will be |
| 14667 | determined. This status is based on the existing process's uid, euid, |
| 14668 | gid, and egid permissions and on the modes of the executable file. If |
| 14669 | the new executable file modes are setuid or setgid, or if the existing |
| 14670 | process is executing the new image with uid != euid or gid != egid, the |
| 14671 | new process will be considered issetugid. |
| 14672 | |
| 14673 | E\bER\bRR\bRO\bOR\bRS\bS |
| 14674 | The i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() function is always successful, and no return value is |
| 14675 | reserved to indicate an error. |
| 14676 | |
| 14677 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 14678 | execve(2), setegid(2), seteuid(2), setgid(2), setuid(2), getenv(3) |
| 14679 | |
| 14680 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 14681 | The i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() function call first appeared in OpenBSD 2.0. |
| 14682 | |
| 14683 | N\bNA\bAM\bME\bE |
| 14684 | k\bkq\bqu\bue\beu\bue\be, k\bke\bev\bve\ben\bnt\bt - kernel event notification mechanism |
| 14685 | |
| 14686 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 14687 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 14688 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/e\bev\bve\ben\bnt\bt.\b.h\bh>\b> |
| 14689 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 14690 | |
| 14691 | _\bi_\bn_\bt |
| 14692 | k\bkq\bqu\bue\beu\bue\be(_\bv_\bo_\bi_\bd); |
| 14693 | |
| 14694 | _\bi_\bn_\bt |
| 14695 | k\bke\bev\bve\ben\bnt\bt(_\bi_\bn_\bt _\bk_\bq, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs, |
| 14696 | _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\be_\bv_\be_\bn_\bt_\bs, |
| 14697 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
| 14698 | |
| 14699 | E\bEV\bV_\b_S\bSE\bET\bT(_\b&_\bk_\be_\bv, _\bi_\bd_\be_\bn_\bt, _\bf_\bi_\bl_\bt_\be_\br, _\bf_\bl_\ba_\bg_\bs, _\bf_\bf_\bl_\ba_\bg_\bs, _\bd_\ba_\bt_\ba, _\bu_\bd_\ba_\bt_\ba); |
| 14700 | |
| 14701 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 14702 | k\bkq\bqu\bue\beu\bue\be() provides a generic method of notifying the user when an event |
| 14703 | happens or a condition holds, based on the results of small pieces of |
| 14704 | kernel code termed ``filters''. A kevent is identified by the (ident, |
| 14705 | filter) pair; there may only be one unique kevent per kqueue. |
| 14706 | |
| 14707 | The filter is executed upon the initial registration of a kevent in order |
| 14708 | to detect whether a preexisting condition is present, and is also |
| 14709 | executed whenever an event is passed to the filter for evaluation. If |
| 14710 | the filter determines that the condition should be reported, then the |
| 14711 | kevent is placed on the kqueue for the user to retrieve. |
| 14712 | |
| 14713 | The filter is also run when the user attempts to retrieve the kevent from |
| 14714 | the kqueue. If the filter indicates that the condition that triggered |
| 14715 | the event no longer holds, the kevent is removed from the kqueue and is |
| 14716 | not returned. |
| 14717 | |
| 14718 | Multiple events which trigger the filter do not result in multiple |
| 14719 | kevents being placed on the kqueue; instead, the filter will aggregate |
| 14720 | the events into a single struct kevent. Calling c\bcl\blo\bos\bse\be() on a file |
| 14721 | descriptor will remove any kevents that reference the descriptor. |
| 14722 | |
| 14723 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a descriptor. The |
| 14724 | queue is not inherited by a child created with fork(2). Similarly, |
| 14725 | kqueues cannot be passed across UNIX-domain sockets. |
| 14726 | |
| 14727 | k\bke\bev\bve\ben\bnt\bt() is used to register events with the queue, and return any |
| 14728 | pending events to the user. _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt is a pointer to an array of |
| 14729 | _\bk_\be_\bv_\be_\bn_\bt structures, as defined in <_\bs_\by_\bs_\b/_\be_\bv_\be_\bn_\bt_\b._\bh>. All changes contained in |
| 14730 | the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt are applied before any pending events are read from the |
| 14731 | queue. _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs gives the size of _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt. _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt is a pointer to |
| 14732 | an array of kevent structures. _\bn_\be_\bv_\be_\bn_\bt_\bs determines the size of _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
| 14733 | When _\bn_\be_\bv_\be_\bn_\bt_\bs is zero, k\bke\bev\bve\ben\bnt\bt() will return immediately even if there is a |
| 14734 | _\bt_\bi_\bm_\be_\bo_\bu_\bt specified unlike select(2). If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it |
| 14735 | specifies a maximum interval to wait for an event, which will be |
| 14736 | interpreted as a struct timespec. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, k\bke\bev\bve\ben\bnt\bt() |
| 14737 | waits indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
| 14738 | non-null, pointing to a zero-valued _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc structure. The same array |
| 14739 | may be used for the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
| 14740 | |
| 14741 | E\bEV\bV_\b_S\bSE\bET\bT() is a macro which is provided for ease of initializing a kevent |
| 14742 | structure. |
| 14743 | |
| 14744 | The _\bk_\be_\bv_\be_\bn_\bt structure is defined as: |
| 14745 | |
| 14746 | struct kevent { |
| 14747 | uintptr_t ident; /* identifier for this event */ |
| 14748 | short filter; /* filter for event */ |
| 14749 | u_short flags; /* action flags for kqueue */ |
| 14750 | u_int fflags; /* filter flag value */ |
| 14751 | quad_t data; /* filter data value */ |
| 14752 | void *udata; /* opaque user data identifier */ |
| 14753 | }; |
| 14754 | |
| 14755 | The fields of struct kevent are: |
| 14756 | |
| 14757 | ident Value used to identify this event. The exact interpretation |
| 14758 | is determined by the attached filter, but often is a file |
| 14759 | descriptor. |
| 14760 | |
| 14761 | filter Identifies the kernel filter used to process this event. The |
| 14762 | pre-defined system filters are described below. |
| 14763 | |
| 14764 | flags Actions to perform on the event. |
| 14765 | |
| 14766 | fflags Filter-specific flags. |
| 14767 | |
| 14768 | data Filter-specific data value. |
| 14769 | |
| 14770 | udata Opaque user-defined value passed through the kernel unchanged. |
| 14771 | |
| 14772 | The _\bf_\bl_\ba_\bg_\bs field can contain the following values: |
| 14773 | |
| 14774 | EV_ADD Adds the event to the kqueue. Re-adding an existing event |
| 14775 | will modify the parameters of the original event, and not |
| 14776 | result in a duplicate entry. Adding an event |
| 14777 | automatically enables it, unless overridden by the |
| 14778 | EV_DISABLE flag. |
| 14779 | |
| 14780 | EV_ENABLE Permit k\bke\bev\bve\ben\bnt\bt() to return the event if it is triggered. |
| 14781 | |
| 14782 | EV_DISABLE Disable the event so k\bke\bev\bve\ben\bnt\bt() will not return it. The |
| 14783 | filter itself is not disabled. |
| 14784 | |
| 14785 | EV_DELETE Removes the event from the kqueue. Events which are |
| 14786 | attached to file descriptors are automatically deleted on |
| 14787 | the last close of the descriptor. |
| 14788 | |
| 14789 | EV_ONESHOT Causes the event to return only the first occurrence of |
| 14790 | the filter being triggered. After the user retrieves the |
| 14791 | event from the kqueue, it is deleted. |
| 14792 | |
| 14793 | EV_CLEAR After the event is retrieved by the user, its state is |
| 14794 | reset. This is useful for filters which report state |
| 14795 | transitions instead of the current state. Note that some |
| 14796 | filters may automatically set this flag internally. |
| 14797 | |
| 14798 | EV_EOF Filters may set this flag to indicate filter-specific EOF |
| 14799 | condition. |
| 14800 | |
| 14801 | EV_ERROR See _\bR_\bE_\bT_\bU_\bR_\bN _\bV_\bA_\bL_\bU_\bE_\bS below. |
| 14802 | |
| 14803 | The predefined system filters are listed below. Arguments may be passed |
| 14804 | to and from the filter via the _\bf_\bf_\bl_\ba_\bg_\bs and _\bd_\ba_\bt_\ba fields in the kevent |
| 14805 | structure. |
| 14806 | |
| 14807 | EVFILT_READ Takes a descriptor as the identifier, and returns whenever |
| 14808 | there is data available to read. The behavior of the |
| 14809 | filter is slightly different depending on the descriptor |
| 14810 | type. |
| 14811 | |
| 14812 | Sockets |
| 14813 | Sockets which have previously been passed to l\bli\bis\bst\bte\ben\bn() |
| 14814 | return when there is an incoming connection pending. |
| 14815 | _\bd_\ba_\bt_\ba contains the size of the listen backlog. |
| 14816 | |
| 14817 | Other socket descriptors return when there is data to |
| 14818 | be read, subject to the SO_RCVLOWAT value of the |
| 14819 | socket buffer. This may be overridden with a per- |
| 14820 | filter low water mark at the time the filter is added |
| 14821 | by setting the NOTE_LOWAT flag in _\bf_\bf_\bl_\ba_\bg_\bs, and |
| 14822 | specifying the new low water mark in _\bd_\ba_\bt_\ba. On return, |
| 14823 | _\bd_\ba_\bt_\ba contains the number of bytes in the socket |
| 14824 | buffer. |
| 14825 | |
| 14826 | If the read direction of the socket has shutdown, then |
| 14827 | the filter also sets EV_EOF in _\bf_\bl_\ba_\bg_\bs, and returns the |
| 14828 | socket error (if any) in _\bf_\bf_\bl_\ba_\bg_\bs. It is possible for |
| 14829 | EOF to be returned (indicating the connection is gone) |
| 14830 | while there is still data pending in the socket |
| 14831 | buffer. |
| 14832 | |
| 14833 | Vnodes |
| 14834 | Returns when the file pointer is not at the end of |
| 14835 | file. _\bd_\ba_\bt_\ba contains the offset from current position |
| 14836 | to end of file, and may be negative. If NOTE_EOF is |
| 14837 | set in _\bf_\bf_\bl_\ba_\bg_\bs, k\bke\bev\bve\ben\bnt\bt() will also return when the file |
| 14838 | pointer is at the end of file. The end of file |
| 14839 | condition is indicated by the presence of NOTE_EOF in |
| 14840 | _\bf_\bf_\bl_\ba_\bg_\bs on return. |
| 14841 | |
| 14842 | Fifos, Pipes |
| 14843 | Returns when there is data to read; _\bd_\ba_\bt_\ba contains the |
| 14844 | number of bytes available. |
| 14845 | |
| 14846 | When the last writer disconnects, the filter will set |
| 14847 | EV_EOF in _\bf_\bl_\ba_\bg_\bs. This may be cleared by passing in |
| 14848 | EV_CLEAR, at which point the filter will resume |
| 14849 | waiting for data to become available before returning. |
| 14850 | |
| 14851 | BPF devices |
| 14852 | Returns when the BPF buffer is full, the BPF timeout |
| 14853 | has expired, or when the BPF has ``immediate mode'' |
| 14854 | enabled and there is any data to read; _\bd_\ba_\bt_\ba contains |
| 14855 | the number of bytes available. |
| 14856 | |
| 14857 | EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever |
| 14858 | it is possible to write to the descriptor. For sockets, |
| 14859 | pipes, and FIFOs, _\bd_\ba_\bt_\ba will contain the amount of space |
| 14860 | remaining in the write buffer. The filter will set EV_EOF |
| 14861 | when the reader disconnects, and for the FIFO case, this |
| 14862 | may be cleared by use of EV_CLEAR. Note that this filter |
| 14863 | is not supported for vnodes or BPF devices. |
| 14864 | |
| 14865 | For sockets, the low water mark and socket error handling |
| 14866 | is identical to the EVFILT_READ case. |
| 14867 | |
| 14868 | EVFILT_VNODE Takes a file descriptor as the identifier and the events |
| 14869 | to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when one or more of |
| 14870 | the requested events occurs on the descriptor. The events |
| 14871 | to monitor are: |
| 14872 | |
| 14873 | NOTE_DELETE u\bun\bnl\bli\bin\bnk\bk() was called on the file referenced |
| 14874 | by the descriptor. |
| 14875 | |
| 14876 | NOTE_WRITE A write occurred on the file referenced by |
| 14877 | the descriptor. |
| 14878 | |
| 14879 | NOTE_EXTEND The file referenced by the descriptor was |
| 14880 | extended. |
| 14881 | |
| 14882 | NOTE_TRUNCATE The file referenced by the descriptor was |
| 14883 | truncated. |
| 14884 | |
| 14885 | NOTE_ATTRIB The file referenced by the descriptor had |
| 14886 | its attributes changed. |
| 14887 | |
| 14888 | NOTE_LINK The link count on the file changed. |
| 14889 | |
| 14890 | NOTE_RENAME The file referenced by the descriptor was |
| 14891 | renamed. |
| 14892 | |
| 14893 | NOTE_REVOKE Access to the file was revoked via |
| 14894 | revoke(2) or the underlying file system was |
| 14895 | unmounted. |
| 14896 | |
| 14897 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
| 14898 | filter. |
| 14899 | |
| 14900 | EVFILT_PROC Takes the process ID to monitor as the identifier and the |
| 14901 | events to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when the |
| 14902 | process performs one or more of the requested events. If |
| 14903 | a process can normally see another process, it can attach |
| 14904 | an event to it. The events to monitor are: |
| 14905 | |
| 14906 | NOTE_EXIT The process has exited. The exit status |
| 14907 | will be stored in _\bd_\ba_\bt_\ba in the same format |
| 14908 | as the status set by wait(2). |
| 14909 | |
| 14910 | NOTE_FORK The process has called f\bfo\bor\brk\bk(). |
| 14911 | |
| 14912 | NOTE_EXEC The process has executed a new process |
| 14913 | via execve(2) or similar call. |
| 14914 | |
| 14915 | NOTE_TRACK Follow a process across f\bfo\bor\brk\bk() calls. |
| 14916 | The parent process will return with |
| 14917 | NOTE_FORK set in the _\bf_\bf_\bl_\ba_\bg_\bs field, while |
| 14918 | the child process will return with |
| 14919 | NOTE_CHILD set in _\bf_\bf_\bl_\ba_\bg_\bs and the parent |
| 14920 | PID in _\bd_\ba_\bt_\ba. |
| 14921 | |
| 14922 | NOTE_TRACKERR This flag is returned if the system was |
| 14923 | unable to attach an event to the child |
| 14924 | process, usually due to resource |
| 14925 | limitations. |
| 14926 | |
| 14927 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
| 14928 | filter. |
| 14929 | |
| 14930 | EVFILT_SIGNAL Takes the signal number to monitor as the identifier and |
| 14931 | returns when the given signal is delivered to the process. |
| 14932 | This coexists with the s\bsi\big\bgn\bna\bal\bl() and s\bsi\big\bga\bac\bct\bti\bio\bon\bn() |
| 14933 | facilities, and has a lower precedence. The filter will |
| 14934 | record all attempts to deliver a signal to a process, even |
| 14935 | if the signal has been marked as SIG_IGN. Event |
| 14936 | notification happens after normal signal delivery |
| 14937 | processing. _\bd_\ba_\bt_\ba returns the number of times the signal |
| 14938 | has occurred since the last call to k\bke\bev\bve\ben\bnt\bt(). This filter |
| 14939 | automatically sets the EV_CLEAR flag internally. |
| 14940 | |
| 14941 | EVFILT_TIMER Establishes an arbitrary timer identified by _\bi_\bd_\be_\bn_\bt. When |
| 14942 | adding a timer, _\bd_\ba_\bt_\ba specifies the timeout period in |
| 14943 | milliseconds. The timer will be periodic unless |
| 14944 | EV_ONESHOT is specified. On return, _\bd_\ba_\bt_\ba contains the |
| 14945 | number of times the timeout has expired since the last |
| 14946 | call to k\bke\bev\bve\ben\bnt\bt(). This filter automatically sets the |
| 14947 | EV_CLEAR flag internally. |
| 14948 | |
| 14949 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 14950 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a file descriptor. |
| 14951 | If there was an error creating the kernel event queue, a value of -1 is |
| 14952 | returned and errno set. |
| 14953 | |
| 14954 | k\bke\bev\bve\ben\bnt\bt() returns the number of events placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, up to the |
| 14955 | value given by _\bn_\be_\bv_\be_\bn_\bt_\bs. If an error occurs while processing an element |
| 14956 | of the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and there is enough room in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, then the |
| 14957 | event will be placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt with EV_ERROR set in _\bf_\bl_\ba_\bg_\bs and the |
| 14958 | system error in _\bd_\ba_\bt_\ba. Otherwise, -1 will be returned, and errno will be |
| 14959 | set to indicate the error condition. If the time limit expires, then |
| 14960 | k\bke\bev\bve\ben\bnt\bt() returns 0. |
| 14961 | |
| 14962 | E\bER\bRR\bRO\bOR\bRS\bS |
| 14963 | The k\bkq\bqu\bue\beu\bue\be() function fails if: |
| 14964 | |
| 14965 | [ENOMEM] The kernel failed to allocate enough memory for the |
| 14966 | kernel queue. |
| 14967 | |
| 14968 | [EMFILE] The per-process descriptor table is full. |
| 14969 | |
| 14970 | [ENFILE] The system file table is full. |
| 14971 | |
| 14972 | The k\bke\bev\bve\ben\bnt\bt() function fails if: |
| 14973 | |
| 14974 | [EACCES] The process does not have permission to register a |
| 14975 | filter. |
| 14976 | |
| 14977 | [EFAULT] There was an error reading or writing the _\bk_\be_\bv_\be_\bn_\bt |
| 14978 | structure. |
| 14979 | |
| 14980 | [EBADF] The specified descriptor is invalid. |
| 14981 | |
| 14982 | [EINTR] A signal was delivered before the timeout expired and |
| 14983 | before any events were placed on the kqueue for |
| 14984 | return. |
| 14985 | |
| 14986 | [EINVAL] The specified time limit or filter is invalid. |
| 14987 | |
| 14988 | [ENOENT] The event could not be found to be modified or |
| 14989 | deleted. |
| 14990 | |
| 14991 | [ENOMEM] No memory was available to register the event. |
| 14992 | |
| 14993 | [ESRCH] The specified process to attach to does not exist. |
| 14994 | |
| 14995 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 14996 | poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) |
| 14997 | |
| 14998 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 14999 | The k\bkq\bqu\bue\beu\bue\be() and k\bke\bev\bve\ben\bnt\bt() functions first appeared in FreeBSD 4.1. |
| 15000 | |
| 15001 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 15002 | The k\bkq\bqu\bue\beu\bue\be() system and this manual page were written by Jonathan Lemon |
| 15003 | <_\bj_\bl_\be_\bm_\bo_\bn_\b@_\bF_\br_\be_\be_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
| 15004 | |
| 15005 | B\bBU\bUG\bGS\bS |
| 15006 | It is currently not possible to watch FIFOs or AIO that reside on |
| 15007 | anything but a UFS file system. Watching a vnode is possible on UFS, NFS |
| 15008 | and MS-DOS file systems. |
| 15009 | |
| 15010 | The _\bt_\bi_\bm_\be_\bo_\bu_\bt value is limited to 24 hours; longer timeouts will be |
| 15011 | silently reinterpreted as 24 hours. |
| 15012 | |
| 15013 | N\bNA\bAM\bME\bE |
| 15014 | k\bki\bil\bll\bl - send signal to a process |
| 15015 | |
| 15016 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 15017 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 15018 | |
| 15019 | _\bi_\bn_\bt |
| 15020 | k\bki\bil\bll\bl(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bi_\bn_\bt _\bs_\bi_\bg); |
| 15021 | |
| 15022 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 15023 | The k\bki\bil\bll\bl() function sends the signal given by _\bs_\bi_\bg to _\bp_\bi_\bd, a process or a |
| 15024 | group of processes. _\bs_\bi_\bg may be one of the signals specified in |
| 15025 | sigaction(2) or it may be 0, in which case error checking is performed |
| 15026 | but no signal is actually sent. This can be used to check the validity |
| 15027 | of _\bp_\bi_\bd. |
| 15028 | |
| 15029 | For a process to have permission to send a signal to a process designated |
| 15030 | by _\bp_\bi_\bd, the real or effective user ID of the receiving process must match |
| 15031 | that of the sending process or the user must have appropriate privileges |
| 15032 | (such as given by a set-user-ID program or the user is the superuser). A |
| 15033 | single exception is the signal SIGCONT, which may always be sent to any |
| 15034 | process with the same session ID as the caller. |
| 15035 | |
| 15036 | If _\bp_\bi_\bd is greater than zero: |
| 15037 | _\bs_\bi_\bg is sent to the process whose ID is equal to _\bp_\bi_\bd. |
| 15038 | |
| 15039 | If _\bp_\bi_\bd is zero: |
| 15040 | _\bs_\bi_\bg is sent to all processes whose group ID is equal to the |
| 15041 | process group ID of the sender, and for which the process has |
| 15042 | permission; this is a variant of killpg(3). |
| 15043 | |
| 15044 | If _\bp_\bi_\bd is -1: |
| 15045 | If the user has superuser privileges, the signal is sent to all |
| 15046 | processes excluding system processes and the process sending the |
| 15047 | signal. If the user is not the superuser, the signal is sent to |
| 15048 | all processes with the same uid as the user excluding the process |
| 15049 | sending the signal. No error is returned if any process could be |
| 15050 | signaled. |
| 15051 | |
| 15052 | Setuid and setgid processes are dealt with slightly differently. For the |
| 15053 | non-root user, to prevent attacks against such processes, some signal |
| 15054 | deliveries are not permitted and return the error EPERM. The following |
| 15055 | signals are allowed through to this class of processes: SIGKILL, SIGINT, |
| 15056 | SIGTERM, SIGSTOP, SIGTTIN, SIGTTOU, SIGTSTP, SIGHUP, SIGUSR1, SIGUSR2. |
| 15057 | |
| 15058 | For compatibility with System V, if the process number is negative but |
| 15059 | not -1, the signal is sent to all processes whose process group ID is |
| 15060 | equal to the absolute value of the process number. This is a variant of |
| 15061 | killpg(3). |
| 15062 | |
| 15063 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 15064 | Upon successful completion, the value 0 is returned; otherwise the |
| 15065 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 15066 | error. |
| 15067 | |
| 15068 | E\bER\bRR\bRO\bOR\bRS\bS |
| 15069 | k\bki\bil\bll\bl() will fail and no signal will be sent if: |
| 15070 | |
| 15071 | [EINVAL] _\bs_\bi_\bg is not a valid signal number. |
| 15072 | |
| 15073 | [ESRCH] No process can be found corresponding to that |
| 15074 | specified by _\bp_\bi_\bd. |
| 15075 | |
| 15076 | [EPERM] The sending process is not the superuser and its |
| 15077 | effective user ID does not match the effective user ID |
| 15078 | of the receiving process. When signaling a process |
| 15079 | group, this error is returned if none of the members |
| 15080 | of the group could be signaled. |
| 15081 | |
| 15082 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 15083 | getpgrp(2), getpid(2), sigaction(2), killpg(3), raise(3) |
| 15084 | |
| 15085 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 15086 | The k\bki\bil\bll\bl() function is expected to conform to IEEE Std 1003.1-2008 |
| 15087 | (``POSIX.1''). |
| 15088 | |
| 15089 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 15090 | The k\bki\bil\bll\bl() system call first appeared in Version 3 AT&T UNIX. The _\bs_\bi_\bg |
| 15091 | argument was introduced in Version 4 AT&T UNIX. |
| 15092 | |
| 15093 | B\bBU\bUG\bGS\bS |
| 15094 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that k\bki\bil\bll\bl(_\b0, _\bs_\bi_\bg) should |
| 15095 | send signal _\bs_\bi_\bg to the calling process, but OpenBSD doesn't do so for |
| 15096 | historical reasons. |
| 15097 | |
| 15098 | N\bNA\bAM\bME\bE |
| 15099 | k\bkq\bqu\bue\beu\bue\be, k\bke\bev\bve\ben\bnt\bt - kernel event notification mechanism |
| 15100 | |
| 15101 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 15102 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 15103 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/e\bev\bve\ben\bnt\bt.\b.h\bh>\b> |
| 15104 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 15105 | |
| 15106 | _\bi_\bn_\bt |
| 15107 | k\bkq\bqu\bue\beu\bue\be(_\bv_\bo_\bi_\bd); |
| 15108 | |
| 15109 | _\bi_\bn_\bt |
| 15110 | k\bke\bev\bve\ben\bnt\bt(_\bi_\bn_\bt _\bk_\bq, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs, |
| 15111 | _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\be_\bv_\be_\bn_\bt_\bs, |
| 15112 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
| 15113 | |
| 15114 | E\bEV\bV_\b_S\bSE\bET\bT(_\b&_\bk_\be_\bv, _\bi_\bd_\be_\bn_\bt, _\bf_\bi_\bl_\bt_\be_\br, _\bf_\bl_\ba_\bg_\bs, _\bf_\bf_\bl_\ba_\bg_\bs, _\bd_\ba_\bt_\ba, _\bu_\bd_\ba_\bt_\ba); |
| 15115 | |
| 15116 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 15117 | k\bkq\bqu\bue\beu\bue\be() provides a generic method of notifying the user when an event |
| 15118 | happens or a condition holds, based on the results of small pieces of |
| 15119 | kernel code termed ``filters''. A kevent is identified by the (ident, |
| 15120 | filter) pair; there may only be one unique kevent per kqueue. |
| 15121 | |
| 15122 | The filter is executed upon the initial registration of a kevent in order |
| 15123 | to detect whether a preexisting condition is present, and is also |
| 15124 | executed whenever an event is passed to the filter for evaluation. If |
| 15125 | the filter determines that the condition should be reported, then the |
| 15126 | kevent is placed on the kqueue for the user to retrieve. |
| 15127 | |
| 15128 | The filter is also run when the user attempts to retrieve the kevent from |
| 15129 | the kqueue. If the filter indicates that the condition that triggered |
| 15130 | the event no longer holds, the kevent is removed from the kqueue and is |
| 15131 | not returned. |
| 15132 | |
| 15133 | Multiple events which trigger the filter do not result in multiple |
| 15134 | kevents being placed on the kqueue; instead, the filter will aggregate |
| 15135 | the events into a single struct kevent. Calling c\bcl\blo\bos\bse\be() on a file |
| 15136 | descriptor will remove any kevents that reference the descriptor. |
| 15137 | |
| 15138 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a descriptor. The |
| 15139 | queue is not inherited by a child created with fork(2). Similarly, |
| 15140 | kqueues cannot be passed across UNIX-domain sockets. |
| 15141 | |
| 15142 | k\bke\bev\bve\ben\bnt\bt() is used to register events with the queue, and return any |
| 15143 | pending events to the user. _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt is a pointer to an array of |
| 15144 | _\bk_\be_\bv_\be_\bn_\bt structures, as defined in <_\bs_\by_\bs_\b/_\be_\bv_\be_\bn_\bt_\b._\bh>. All changes contained in |
| 15145 | the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt are applied before any pending events are read from the |
| 15146 | queue. _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs gives the size of _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt. _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt is a pointer to |
| 15147 | an array of kevent structures. _\bn_\be_\bv_\be_\bn_\bt_\bs determines the size of _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
| 15148 | When _\bn_\be_\bv_\be_\bn_\bt_\bs is zero, k\bke\bev\bve\ben\bnt\bt() will return immediately even if there is a |
| 15149 | _\bt_\bi_\bm_\be_\bo_\bu_\bt specified unlike select(2). If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it |
| 15150 | specifies a maximum interval to wait for an event, which will be |
| 15151 | interpreted as a struct timespec. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, k\bke\bev\bve\ben\bnt\bt() |
| 15152 | waits indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
| 15153 | non-null, pointing to a zero-valued _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc structure. The same array |
| 15154 | may be used for the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
| 15155 | |
| 15156 | E\bEV\bV_\b_S\bSE\bET\bT() is a macro which is provided for ease of initializing a kevent |
| 15157 | structure. |
| 15158 | |
| 15159 | The _\bk_\be_\bv_\be_\bn_\bt structure is defined as: |
| 15160 | |
| 15161 | struct kevent { |
| 15162 | uintptr_t ident; /* identifier for this event */ |
| 15163 | short filter; /* filter for event */ |
| 15164 | u_short flags; /* action flags for kqueue */ |
| 15165 | u_int fflags; /* filter flag value */ |
| 15166 | quad_t data; /* filter data value */ |
| 15167 | void *udata; /* opaque user data identifier */ |
| 15168 | }; |
| 15169 | |
| 15170 | The fields of struct kevent are: |
| 15171 | |
| 15172 | ident Value used to identify this event. The exact interpretation |
| 15173 | is determined by the attached filter, but often is a file |
| 15174 | descriptor. |
| 15175 | |
| 15176 | filter Identifies the kernel filter used to process this event. The |
| 15177 | pre-defined system filters are described below. |
| 15178 | |
| 15179 | flags Actions to perform on the event. |
| 15180 | |
| 15181 | fflags Filter-specific flags. |
| 15182 | |
| 15183 | data Filter-specific data value. |
| 15184 | |
| 15185 | udata Opaque user-defined value passed through the kernel unchanged. |
| 15186 | |
| 15187 | The _\bf_\bl_\ba_\bg_\bs field can contain the following values: |
| 15188 | |
| 15189 | EV_ADD Adds the event to the kqueue. Re-adding an existing event |
| 15190 | will modify the parameters of the original event, and not |
| 15191 | result in a duplicate entry. Adding an event |
| 15192 | automatically enables it, unless overridden by the |
| 15193 | EV_DISABLE flag. |
| 15194 | |
| 15195 | EV_ENABLE Permit k\bke\bev\bve\ben\bnt\bt() to return the event if it is triggered. |
| 15196 | |
| 15197 | EV_DISABLE Disable the event so k\bke\bev\bve\ben\bnt\bt() will not return it. The |
| 15198 | filter itself is not disabled. |
| 15199 | |
| 15200 | EV_DELETE Removes the event from the kqueue. Events which are |
| 15201 | attached to file descriptors are automatically deleted on |
| 15202 | the last close of the descriptor. |
| 15203 | |
| 15204 | EV_ONESHOT Causes the event to return only the first occurrence of |
| 15205 | the filter being triggered. After the user retrieves the |
| 15206 | event from the kqueue, it is deleted. |
| 15207 | |
| 15208 | EV_CLEAR After the event is retrieved by the user, its state is |
| 15209 | reset. This is useful for filters which report state |
| 15210 | transitions instead of the current state. Note that some |
| 15211 | filters may automatically set this flag internally. |
| 15212 | |
| 15213 | EV_EOF Filters may set this flag to indicate filter-specific EOF |
| 15214 | condition. |
| 15215 | |
| 15216 | EV_ERROR See _\bR_\bE_\bT_\bU_\bR_\bN _\bV_\bA_\bL_\bU_\bE_\bS below. |
| 15217 | |
| 15218 | The predefined system filters are listed below. Arguments may be passed |
| 15219 | to and from the filter via the _\bf_\bf_\bl_\ba_\bg_\bs and _\bd_\ba_\bt_\ba fields in the kevent |
| 15220 | structure. |
| 15221 | |
| 15222 | EVFILT_READ Takes a descriptor as the identifier, and returns whenever |
| 15223 | there is data available to read. The behavior of the |
| 15224 | filter is slightly different depending on the descriptor |
| 15225 | type. |
| 15226 | |
| 15227 | Sockets |
| 15228 | Sockets which have previously been passed to l\bli\bis\bst\bte\ben\bn() |
| 15229 | return when there is an incoming connection pending. |
| 15230 | _\bd_\ba_\bt_\ba contains the size of the listen backlog. |
| 15231 | |
| 15232 | Other socket descriptors return when there is data to |
| 15233 | be read, subject to the SO_RCVLOWAT value of the |
| 15234 | socket buffer. This may be overridden with a per- |
| 15235 | filter low water mark at the time the filter is added |
| 15236 | by setting the NOTE_LOWAT flag in _\bf_\bf_\bl_\ba_\bg_\bs, and |
| 15237 | specifying the new low water mark in _\bd_\ba_\bt_\ba. On return, |
| 15238 | _\bd_\ba_\bt_\ba contains the number of bytes in the socket |
| 15239 | buffer. |
| 15240 | |
| 15241 | If the read direction of the socket has shutdown, then |
| 15242 | the filter also sets EV_EOF in _\bf_\bl_\ba_\bg_\bs, and returns the |
| 15243 | socket error (if any) in _\bf_\bf_\bl_\ba_\bg_\bs. It is possible for |
| 15244 | EOF to be returned (indicating the connection is gone) |
| 15245 | while there is still data pending in the socket |
| 15246 | buffer. |
| 15247 | |
| 15248 | Vnodes |
| 15249 | Returns when the file pointer is not at the end of |
| 15250 | file. _\bd_\ba_\bt_\ba contains the offset from current position |
| 15251 | to end of file, and may be negative. If NOTE_EOF is |
| 15252 | set in _\bf_\bf_\bl_\ba_\bg_\bs, k\bke\bev\bve\ben\bnt\bt() will also return when the file |
| 15253 | pointer is at the end of file. The end of file |
| 15254 | condition is indicated by the presence of NOTE_EOF in |
| 15255 | _\bf_\bf_\bl_\ba_\bg_\bs on return. |
| 15256 | |
| 15257 | Fifos, Pipes |
| 15258 | Returns when there is data to read; _\bd_\ba_\bt_\ba contains the |
| 15259 | number of bytes available. |
| 15260 | |
| 15261 | When the last writer disconnects, the filter will set |
| 15262 | EV_EOF in _\bf_\bl_\ba_\bg_\bs. This may be cleared by passing in |
| 15263 | EV_CLEAR, at which point the filter will resume |
| 15264 | waiting for data to become available before returning. |
| 15265 | |
| 15266 | BPF devices |
| 15267 | Returns when the BPF buffer is full, the BPF timeout |
| 15268 | has expired, or when the BPF has ``immediate mode'' |
| 15269 | enabled and there is any data to read; _\bd_\ba_\bt_\ba contains |
| 15270 | the number of bytes available. |
| 15271 | |
| 15272 | EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever |
| 15273 | it is possible to write to the descriptor. For sockets, |
| 15274 | pipes, and FIFOs, _\bd_\ba_\bt_\ba will contain the amount of space |
| 15275 | remaining in the write buffer. The filter will set EV_EOF |
| 15276 | when the reader disconnects, and for the FIFO case, this |
| 15277 | may be cleared by use of EV_CLEAR. Note that this filter |
| 15278 | is not supported for vnodes or BPF devices. |
| 15279 | |
| 15280 | For sockets, the low water mark and socket error handling |
| 15281 | is identical to the EVFILT_READ case. |
| 15282 | |
| 15283 | EVFILT_VNODE Takes a file descriptor as the identifier and the events |
| 15284 | to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when one or more of |
| 15285 | the requested events occurs on the descriptor. The events |
| 15286 | to monitor are: |
| 15287 | |
| 15288 | NOTE_DELETE u\bun\bnl\bli\bin\bnk\bk() was called on the file referenced |
| 15289 | by the descriptor. |
| 15290 | |
| 15291 | NOTE_WRITE A write occurred on the file referenced by |
| 15292 | the descriptor. |
| 15293 | |
| 15294 | NOTE_EXTEND The file referenced by the descriptor was |
| 15295 | extended. |
| 15296 | |
| 15297 | NOTE_TRUNCATE The file referenced by the descriptor was |
| 15298 | truncated. |
| 15299 | |
| 15300 | NOTE_ATTRIB The file referenced by the descriptor had |
| 15301 | its attributes changed. |
| 15302 | |
| 15303 | NOTE_LINK The link count on the file changed. |
| 15304 | |
| 15305 | NOTE_RENAME The file referenced by the descriptor was |
| 15306 | renamed. |
| 15307 | |
| 15308 | NOTE_REVOKE Access to the file was revoked via |
| 15309 | revoke(2) or the underlying file system was |
| 15310 | unmounted. |
| 15311 | |
| 15312 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
| 15313 | filter. |
| 15314 | |
| 15315 | EVFILT_PROC Takes the process ID to monitor as the identifier and the |
| 15316 | events to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when the |
| 15317 | process performs one or more of the requested events. If |
| 15318 | a process can normally see another process, it can attach |
| 15319 | an event to it. The events to monitor are: |
| 15320 | |
| 15321 | NOTE_EXIT The process has exited. The exit status |
| 15322 | will be stored in _\bd_\ba_\bt_\ba in the same format |
| 15323 | as the status set by wait(2). |
| 15324 | |
| 15325 | NOTE_FORK The process has called f\bfo\bor\brk\bk(). |
| 15326 | |
| 15327 | NOTE_EXEC The process has executed a new process |
| 15328 | via execve(2) or similar call. |
| 15329 | |
| 15330 | NOTE_TRACK Follow a process across f\bfo\bor\brk\bk() calls. |
| 15331 | The parent process will return with |
| 15332 | NOTE_FORK set in the _\bf_\bf_\bl_\ba_\bg_\bs field, while |
| 15333 | the child process will return with |
| 15334 | NOTE_CHILD set in _\bf_\bf_\bl_\ba_\bg_\bs and the parent |
| 15335 | PID in _\bd_\ba_\bt_\ba. |
| 15336 | |
| 15337 | NOTE_TRACKERR This flag is returned if the system was |
| 15338 | unable to attach an event to the child |
| 15339 | process, usually due to resource |
| 15340 | limitations. |
| 15341 | |
| 15342 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
| 15343 | filter. |
| 15344 | |
| 15345 | EVFILT_SIGNAL Takes the signal number to monitor as the identifier and |
| 15346 | returns when the given signal is delivered to the process. |
| 15347 | This coexists with the s\bsi\big\bgn\bna\bal\bl() and s\bsi\big\bga\bac\bct\bti\bio\bon\bn() |
| 15348 | facilities, and has a lower precedence. The filter will |
| 15349 | record all attempts to deliver a signal to a process, even |
| 15350 | if the signal has been marked as SIG_IGN. Event |
| 15351 | notification happens after normal signal delivery |
| 15352 | processing. _\bd_\ba_\bt_\ba returns the number of times the signal |
| 15353 | has occurred since the last call to k\bke\bev\bve\ben\bnt\bt(). This filter |
| 15354 | automatically sets the EV_CLEAR flag internally. |
| 15355 | |
| 15356 | EVFILT_TIMER Establishes an arbitrary timer identified by _\bi_\bd_\be_\bn_\bt. When |
| 15357 | adding a timer, _\bd_\ba_\bt_\ba specifies the timeout period in |
| 15358 | milliseconds. The timer will be periodic unless |
| 15359 | EV_ONESHOT is specified. On return, _\bd_\ba_\bt_\ba contains the |
| 15360 | number of times the timeout has expired since the last |
| 15361 | call to k\bke\bev\bve\ben\bnt\bt(). This filter automatically sets the |
| 15362 | EV_CLEAR flag internally. |
| 15363 | |
| 15364 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 15365 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a file descriptor. |
| 15366 | If there was an error creating the kernel event queue, a value of -1 is |
| 15367 | returned and errno set. |
| 15368 | |
| 15369 | k\bke\bev\bve\ben\bnt\bt() returns the number of events placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, up to the |
| 15370 | value given by _\bn_\be_\bv_\be_\bn_\bt_\bs. If an error occurs while processing an element |
| 15371 | of the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and there is enough room in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, then the |
| 15372 | event will be placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt with EV_ERROR set in _\bf_\bl_\ba_\bg_\bs and the |
| 15373 | system error in _\bd_\ba_\bt_\ba. Otherwise, -1 will be returned, and errno will be |
| 15374 | set to indicate the error condition. If the time limit expires, then |
| 15375 | k\bke\bev\bve\ben\bnt\bt() returns 0. |
| 15376 | |
| 15377 | E\bER\bRR\bRO\bOR\bRS\bS |
| 15378 | The k\bkq\bqu\bue\beu\bue\be() function fails if: |
| 15379 | |
| 15380 | [ENOMEM] The kernel failed to allocate enough memory for the |
| 15381 | kernel queue. |
| 15382 | |
| 15383 | [EMFILE] The per-process descriptor table is full. |
| 15384 | |
| 15385 | [ENFILE] The system file table is full. |
| 15386 | |
| 15387 | The k\bke\bev\bve\ben\bnt\bt() function fails if: |
| 15388 | |
| 15389 | [EACCES] The process does not have permission to register a |
| 15390 | filter. |
| 15391 | |
| 15392 | [EFAULT] There was an error reading or writing the _\bk_\be_\bv_\be_\bn_\bt |
| 15393 | structure. |
| 15394 | |
| 15395 | [EBADF] The specified descriptor is invalid. |
| 15396 | |
| 15397 | [EINTR] A signal was delivered before the timeout expired and |
| 15398 | before any events were placed on the kqueue for |
| 15399 | return. |
| 15400 | |
| 15401 | [EINVAL] The specified time limit or filter is invalid. |
| 15402 | |
| 15403 | [ENOENT] The event could not be found to be modified or |
| 15404 | deleted. |
| 15405 | |
| 15406 | [ENOMEM] No memory was available to register the event. |
| 15407 | |
| 15408 | [ESRCH] The specified process to attach to does not exist. |
| 15409 | |
| 15410 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 15411 | poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) |
| 15412 | |
| 15413 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 15414 | The k\bkq\bqu\bue\beu\bue\be() and k\bke\bev\bve\ben\bnt\bt() functions first appeared in FreeBSD 4.1. |
| 15415 | |
| 15416 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 15417 | The k\bkq\bqu\bue\beu\bue\be() system and this manual page were written by Jonathan Lemon |
| 15418 | <_\bj_\bl_\be_\bm_\bo_\bn_\b@_\bF_\br_\be_\be_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
| 15419 | |
| 15420 | B\bBU\bUG\bGS\bS |
| 15421 | It is currently not possible to watch FIFOs or AIO that reside on |
| 15422 | anything but a UFS file system. Watching a vnode is possible on UFS, NFS |
| 15423 | and MS-DOS file systems. |
| 15424 | |
| 15425 | The _\bt_\bi_\bm_\be_\bo_\bu_\bt value is limited to 24 hours; longer timeouts will be |
| 15426 | silently reinterpreted as 24 hours. |
| 15427 | |
| 15428 | N\bNA\bAM\bME\bE |
| 15429 | k\bkt\btr\bra\bac\bce\be - process tracing |
| 15430 | |
| 15431 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 15432 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 15433 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 15434 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 15435 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/k\bkt\btr\bra\bac\bce\be.\b.h\bh>\b> |
| 15436 | |
| 15437 | _\bi_\bn_\bt |
| 15438 | k\bkt\btr\bra\bac\bce\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\br_\ba_\bc_\be_\bf_\bi_\bl_\be, _\bi_\bn_\bt _\bo_\bp_\bs, _\bi_\bn_\bt _\bt_\br_\bp_\bo_\bi_\bn_\bt_\bs, _\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd); |
| 15439 | |
| 15440 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 15441 | The k\bkt\btr\bra\bac\bce\be() function enables or disables tracing of one or more |
| 15442 | processes. Users may only trace their own processes. Only the superuser |
| 15443 | can trace setuid or setgid programs. k\bkt\btr\bra\bac\bce\be() is only available on |
| 15444 | kernels compiled with the K\bKT\bTR\bRA\bAC\bCE\bE option. |
| 15445 | |
| 15446 | _\bt_\br_\ba_\bc_\be_\bf_\bi_\bl_\be gives the pathname of the file to be used for tracing. The |
| 15447 | file must exist, be writable by the calling process, and not be a |
| 15448 | symbolic link. All trace records are always appended to the file, so the |
| 15449 | file must be truncated to zero length to discard previous trace data. If |
| 15450 | tracing points are being disabled (see KTROP_CLEAR below), _\bt_\br_\ba_\bc_\be_\bf_\bi_\bl_\be may |
| 15451 | be NULL. |
| 15452 | |
| 15453 | The _\bo_\bp_\bs parameter specifies the requested ktrace operation. The defined |
| 15454 | operations are: |
| 15455 | |
| 15456 | KTROP_SET Enable trace points specified in _\bt_\br_\bp_\bo_\bi_\bn_\bt_\bs. |
| 15457 | KTROP_CLEAR Disable trace points specified in _\bt_\br_\bp_\bo_\bi_\bn_\bt_\bs. |
| 15458 | KTROP_CLEARFILE Stop all tracing. |
| 15459 | KTRFLAG_DESCEND The tracing change should apply to the specified |
| 15460 | process and all its current children. |
| 15461 | |
| 15462 | The _\bt_\br_\bp_\bo_\bi_\bn_\bt_\bs parameter specifies the trace points of interest. The |
| 15463 | defined trace points are: |
| 15464 | |
| 15465 | KTRFAC_SYSCALL Trace system calls. |
| 15466 | KTRFAC_SYSRET Trace return values from system calls. |
| 15467 | KTRFAC_NAMEI Trace name lookup operations. |
| 15468 | KTRFAC_GENIO Trace all I/O (note that this option can generate |
| 15469 | much output). |
| 15470 | KTRFAC_PSIG Trace posted signals. |
| 15471 | KTRFAC_EMUL Trace emulation changes. |
| 15472 | KTRFAC_CSW Trace context switch points. |
| 15473 | KTRFAC_STRUCT Trace various structs |
| 15474 | KTRFAC_USER Trace user data coming from utrace(2) calls. |
| 15475 | KTRFAC_INHERIT Inherit tracing to future children. |
| 15476 | |
| 15477 | The _\bp_\bi_\bd parameter refers to a process ID. If it is negative, it refers |
| 15478 | to a process group ID. |
| 15479 | |
| 15480 | Each tracing event outputs a record composed of a generic header followed |
| 15481 | by a trace point specific structure. The generic header is: |
| 15482 | |
| 15483 | struct ktr_header { |
| 15484 | uint ktr_type; /* trace record type */ |
| 15485 | pid_t ktr_pid; /* process id */ |
| 15486 | pid_t ktr_tid; /* thread id */ |
| 15487 | struct timespec ktr_time; /* timestamp */ |
| 15488 | char ktr_comm[MAXCOMLEN+1]; /* command name */ |
| 15489 | size_t ktr_len; /* length of buf */ |
| 15490 | }; |
| 15491 | |
| 15492 | The _\bk_\bt_\br_\b__\bl_\be_\bn field specifies the length of the _\bk_\bt_\br_\b__\bt_\by_\bp_\be data that follows |
| 15493 | this header. The _\bk_\bt_\br_\b__\bp_\bi_\bd, _\bk_\bt_\br_\b__\bt_\bi_\bd, and _\bk_\bt_\br_\b__\bc_\bo_\bm_\bm fields specify the |
| 15494 | process, thread, and command generating the record. The _\bk_\bt_\br_\b__\bt_\bi_\bm_\be field |
| 15495 | gives the time (with nanosecond resolution) that the record was |
| 15496 | generated. |
| 15497 | |
| 15498 | The generic header is followed by _\bk_\bt_\br_\b__\bl_\be_\bn bytes of a _\bk_\bt_\br_\b__\bt_\by_\bp_\be record. |
| 15499 | The type specific records are defined in the <_\bs_\by_\bs_\b/_\bk_\bt_\br_\ba_\bc_\be_\b._\bh> include file. |
| 15500 | |
| 15501 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 15502 | Upon successful completion, the value 0 is returned; otherwise the |
| 15503 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 15504 | error. |
| 15505 | |
| 15506 | E\bER\bRR\bRO\bOR\bRS\bS |
| 15507 | k\bkt\btr\bra\bac\bce\be() will fail if: |
| 15508 | |
| 15509 | [ENOTDIR] A component of the path prefix is not a directory. |
| 15510 | |
| 15511 | [EINVAL] No trace points were selected. |
| 15512 | |
| 15513 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, |
| 15514 | or an entire pathname (including the terminating NUL) |
| 15515 | exceeded PATH_MAX bytes. |
| 15516 | |
| 15517 | [ENOENT] The named tracefile does not exist. |
| 15518 | |
| 15519 | [EACCES] Search permission is denied for a component of the path |
| 15520 | prefix or the path refers to a symbolic link. |
| 15521 | |
| 15522 | [ELOOP] Too many symbolic links were encountered in translating |
| 15523 | the pathname. |
| 15524 | |
| 15525 | [EIO] An I/O error occurred while reading from or writing to |
| 15526 | the file system. |
| 15527 | |
| 15528 | [ESRCH] No process can be found corresponding to that specified |
| 15529 | by _\bp_\bi_\bd. |
| 15530 | |
| 15531 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 15532 | kdump(1), ktrace(1), utrace(2) |
| 15533 | |
| 15534 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 15535 | A k\bkt\btr\bra\bac\bce\be() function call first appeared in 4.4BSD. |
| 15536 | |
| 15537 | N\bNA\bAM\bME\bE |
| 15538 | c\bch\bho\bow\bwn\bn, l\blc\bch\bho\bow\bwn\bn, f\bfc\bch\bho\bow\bwn\bna\bat\bt, f\bfc\bch\bho\bow\bwn\bn - change owner and group of a file or |
| 15539 | link |
| 15540 | |
| 15541 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 15542 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 15543 | |
| 15544 | _\bi_\bn_\bt |
| 15545 | c\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 15546 | |
| 15547 | _\bi_\bn_\bt |
| 15548 | l\blc\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 15549 | |
| 15550 | _\bi_\bn_\bt |
| 15551 | f\bfc\bch\bho\bow\bwn\bn(_\bi_\bn_\bt _\bf_\bd, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
| 15552 | |
| 15553 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 15554 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 15555 | |
| 15556 | _\bi_\bn_\bt |
| 15557 | f\bfc\bch\bho\bow\bwn\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 15558 | |
| 15559 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 15560 | The owner ID and group ID of the file (or link) named by _\bp_\ba_\bt_\bh or |
| 15561 | referenced by _\bf_\bd is changed as specified by the arguments _\bo_\bw_\bn_\be_\br and |
| 15562 | _\bg_\br_\bo_\bu_\bp. The owner of a file may change the _\bg_\br_\bo_\bu_\bp to a group of which he |
| 15563 | or she is a member, but the change _\bo_\bw_\bn_\be_\br capability is restricted to the |
| 15564 | superuser. |
| 15565 | |
| 15566 | By default, c\bch\bho\bow\bwn\bn() clears the set-user-ID and set-group-ID bits on the |
| 15567 | file to prevent accidental or mischievous creation of set-user-ID and |
| 15568 | set-group-ID programs. This behaviour can be overridden by setting the |
| 15569 | sysctl(8) variable _\bf_\bs_\b._\bp_\bo_\bs_\bi_\bx_\b._\bs_\be_\bt_\bu_\bi_\bd to zero. |
| 15570 | |
| 15571 | l\blc\bch\bho\bow\bwn\bn() operates similarly to how c\bch\bho\bow\bwn\bn() operated on older systems, and |
| 15572 | does not follow symbolic links. It allows the owner and group of a |
| 15573 | symbolic link to be set. |
| 15574 | |
| 15575 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() function is equivalent to either the c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn() |
| 15576 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 15577 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose ownership is changed is |
| 15578 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 15579 | instead of the current working directory. |
| 15580 | |
| 15581 | If f\bfc\bch\bho\bow\bwn\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 15582 | in the _\bf_\bd parameter, the current working directory is used and the |
| 15583 | behavior is identical to a call to c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn(), depending on |
| 15584 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 15585 | |
| 15586 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 15587 | values: |
| 15588 | |
| 15589 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
| 15590 | ownership of the symbolic link is changed. |
| 15591 | |
| 15592 | f\bfc\bch\bho\bow\bwn\bn() is particularly useful when used in conjunction with the file |
| 15593 | locking primitives (see flock(2)). |
| 15594 | |
| 15595 | One of the owner or group IDs may be left unchanged by specifying it as |
| 15596 | -1. |
| 15597 | |
| 15598 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 15599 | Upon successful completion, the value 0 is returned; otherwise the |
| 15600 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 15601 | error. |
| 15602 | |
| 15603 | E\bER\bRR\bRO\bOR\bRS\bS |
| 15604 | c\bch\bho\bow\bwn\bn(), l\blc\bch\bho\bow\bwn\bn(), and f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail and the file or link will be |
| 15605 | unchanged if: |
| 15606 | |
| 15607 | [ENOTDIR] A component of the path prefix is not a directory. |
| 15608 | |
| 15609 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 15610 | characters, or an entire pathname (including the |
| 15611 | terminating NUL) exceeded PATH_MAX bytes. |
| 15612 | |
| 15613 | [ENOENT] The named file does not exist. |
| 15614 | |
| 15615 | [EACCES] Search permission is denied for a component of the |
| 15616 | path prefix. |
| 15617 | |
| 15618 | [ELOOP] Too many symbolic links were encountered in |
| 15619 | translating the pathname. |
| 15620 | |
| 15621 | [EPERM] The effective user ID is not the superuser. |
| 15622 | |
| 15623 | [EROFS] The named file resides on a read-only file system. |
| 15624 | |
| 15625 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 15626 | space. |
| 15627 | |
| 15628 | [EIO] An I/O error occurred while reading from or writing to |
| 15629 | the file system. |
| 15630 | |
| 15631 | Additionally, f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail if: |
| 15632 | |
| 15633 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 15634 | AT_SYMLINK_NOFOLLOW. |
| 15635 | |
| 15636 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 15637 | argument is neither AT_FDCWD nor a valid file |
| 15638 | descriptor. |
| 15639 | |
| 15640 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 15641 | argument is a valid file descriptor but it does not |
| 15642 | reference a directory. |
| 15643 | |
| 15644 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 15645 | permission is denied for the directory which the _\bf_\bd |
| 15646 | file descriptor references. |
| 15647 | |
| 15648 | f\bfc\bch\bho\bow\bwn\bn() will fail if: |
| 15649 | |
| 15650 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
| 15651 | |
| 15652 | [EINVAL] _\bf_\bd refers to a socket, not a file. |
| 15653 | |
| 15654 | [EPERM] The effective user ID is not the superuser. |
| 15655 | |
| 15656 | [EROFS] The named file resides on a read-only file system. |
| 15657 | |
| 15658 | [EIO] An I/O error occurred while reading from or writing to |
| 15659 | the file system. |
| 15660 | |
| 15661 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 15662 | chgrp(1), chmod(2), flock(2), chown(8) |
| 15663 | |
| 15664 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 15665 | The c\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), and l\blc\bch\bho\bow\bwn\bn() functions are expected to |
| 15666 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 15667 | |
| 15668 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 15669 | The c\bch\bho\bow\bwn\bn() system call first appeared in Version 1 AT&T UNIX. Since |
| 15670 | Version 6 AT&T UNIX it supports changing the group as well, and in |
| 15671 | Version 7 AT&T UNIX _\bg_\br_\bo_\bu_\bp was made a separate argument. |
| 15672 | |
| 15673 | The f\bfc\bch\bho\bow\bwn\bn() system call first appeared in 4.1cBSD. |
| 15674 | |
| 15675 | The c\bch\bho\bow\bwn\bn() and f\bfc\bch\bho\bow\bwn\bn() system calls were changed to follow symbolic |
| 15676 | links in 4.4BSD; therefore, and for compatibility with AT&T System V |
| 15677 | Release 4 UNIX, the l\blc\bch\bho\bow\bwn\bn() system call was added to OpenBSD 2.1. |
| 15678 | |
| 15679 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() system call has been available since OpenBSD 5.0. |
| 15680 | |
| 15681 | N\bNA\bAM\bME\bE |
| 15682 | l\bli\bin\bnk\bk, l\bli\bin\bnk\bka\bat\bt - make hard link to a file |
| 15683 | |
| 15684 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 15685 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 15686 | |
| 15687 | _\bi_\bn_\bt |
| 15688 | l\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
| 15689 | |
| 15690 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 15691 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 15692 | |
| 15693 | _\bi_\bn_\bt |
| 15694 | l\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bi_\bn_\bt _\bf_\bd_\b2, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 15695 | |
| 15696 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 15697 | The l\bli\bin\bnk\bk() function atomically creates the specified directory entry |
| 15698 | (hard link) _\bn_\ba_\bm_\be_\b2 with the attributes of the underlying object pointed at |
| 15699 | by _\bn_\ba_\bm_\be_\b1. If the link is successful: the link count of the underlying |
| 15700 | object is incremented; _\bn_\ba_\bm_\be_\b1 and _\bn_\ba_\bm_\be_\b2 share equal access and rights to |
| 15701 | the underlying object. |
| 15702 | |
| 15703 | If _\bn_\ba_\bm_\be_\b1 is removed, the file _\bn_\ba_\bm_\be_\b2 is not deleted and the link count of |
| 15704 | the underlying object is decremented. |
| 15705 | |
| 15706 | _\bn_\ba_\bm_\be_\b1 must exist for the hard link to succeed and both _\bn_\ba_\bm_\be_\b1 and _\bn_\ba_\bm_\be_\b2 |
| 15707 | must be in the same file system. As mandated by POSIX.1 _\bn_\ba_\bm_\be_\b1 may not be |
| 15708 | a directory. |
| 15709 | |
| 15710 | The l\bli\bin\bnk\bka\bat\bt() function is equivalent to l\bli\bin\bnk\bk() except that where _\bn_\ba_\bm_\be_\b1 or |
| 15711 | _\bn_\ba_\bm_\be_\b2 specifies a relative path, the directory entries linked are |
| 15712 | resolved relative to the directories associated with file descriptors _\bf_\bd_\b1 |
| 15713 | or _\bf_\bd_\b2 (respectively) instead of the current working directory. |
| 15714 | |
| 15715 | If l\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 15716 | in the _\bf_\bd_\b1 or _\bf_\bd_\b2 parameter, the current working directory is used for |
| 15717 | resolving the respective _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument. |
| 15718 | |
| 15719 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 15720 | values: |
| 15721 | |
| 15722 | AT_SYMLINK_FOLLOW If _\bn_\ba_\bm_\be_\b1 names a symbolic link, a new link for |
| 15723 | the target of the symbolic link is created. |
| 15724 | |
| 15725 | If the AT_SYMLINK_FOLLOW flag is clear and _\bn_\ba_\bm_\be_\b1 names a symbolic link, a |
| 15726 | new link is created for the symbolic link _\bn_\ba_\bm_\be_\b1 and not its target. |
| 15727 | |
| 15728 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 15729 | Upon successful completion, the value 0 is returned; otherwise the |
| 15730 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 15731 | error. |
| 15732 | |
| 15733 | E\bER\bRR\bRO\bOR\bRS\bS |
| 15734 | l\bli\bin\bnk\bk() and l\bli\bin\bnk\bka\bat\bt() will fail and no link will be created if: |
| 15735 | |
| 15736 | [ENOTDIR] A component of either path prefix is not a directory. |
| 15737 | |
| 15738 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 15739 | characters, or an entire pathname (including the |
| 15740 | terminating NUL) exceeded PATH_MAX bytes. |
| 15741 | |
| 15742 | [ENOENT] A component of either path prefix does not exist. |
| 15743 | |
| 15744 | [EOPNOTSUPP] The file system containing the file named by _\bn_\ba_\bm_\be_\b1 |
| 15745 | does not support links. |
| 15746 | |
| 15747 | [EMLINK] The link count of the file named by _\bn_\ba_\bm_\be_\b1 would exceed |
| 15748 | LINK_MAX. |
| 15749 | |
| 15750 | [EACCES] A component of either path prefix denies search |
| 15751 | permission. |
| 15752 | |
| 15753 | [EACCES] The requested link requires writing in a directory |
| 15754 | with a mode that denies write permission. |
| 15755 | |
| 15756 | [ELOOP] Too many symbolic links were encountered in |
| 15757 | translating one of the pathnames. |
| 15758 | |
| 15759 | [ENOENT] The file named by _\bn_\ba_\bm_\be_\b1 does not exist. |
| 15760 | |
| 15761 | [EEXIST] The link named by _\bn_\ba_\bm_\be_\b2 does exist. |
| 15762 | |
| 15763 | [EPERM] The file named by _\bn_\ba_\bm_\be_\b1 is a directory and the |
| 15764 | effective user ID is not superuser, or the file system |
| 15765 | containing the file does not permit the use of l\bli\bin\bnk\bk() |
| 15766 | on a directory. |
| 15767 | |
| 15768 | [EPERM] The file named by _\bn_\ba_\bm_\be_\b1 is flagged immutable or |
| 15769 | append-only. |
| 15770 | |
| 15771 | [EXDEV] The link named by _\bn_\ba_\bm_\be_\b2 and the file named by _\bn_\ba_\bm_\be_\b1 |
| 15772 | are on different file systems. |
| 15773 | |
| 15774 | [ENOSPC] The directory in which the entry for the new link is |
| 15775 | being placed cannot be extended because there is no |
| 15776 | space left on the file system containing the |
| 15777 | directory. |
| 15778 | |
| 15779 | [EDQUOT] The directory in which the entry for the new link is |
| 15780 | being placed cannot be extended because the user's |
| 15781 | quota of disk blocks on the file system containing the |
| 15782 | directory has been exhausted. |
| 15783 | |
| 15784 | [EIO] An I/O error occurred while reading from or writing to |
| 15785 | the file system to make the directory entry. |
| 15786 | |
| 15787 | [EROFS] The requested link requires writing in a directory on |
| 15788 | a read-only file system. |
| 15789 | |
| 15790 | [EFAULT] One of the pathnames specified is outside the |
| 15791 | process's allocated address space. |
| 15792 | |
| 15793 | Additionally, l\bli\bin\bnk\bka\bat\bt() will fail if: |
| 15794 | |
| 15795 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 15796 | AT_SYMLINK_FOLLOW. |
| 15797 | |
| 15798 | [EBADF] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
| 15799 | and the _\bf_\bd_\b1 or _\bf_\bd_\b2 argument, respectively, is neither |
| 15800 | AT_FDCWD nor a valid file descriptor. |
| 15801 | |
| 15802 | [ENOTDIR] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
| 15803 | and the _\bf_\bd_\b1 or _\bf_\bd_\b2 argument, respectively, is a valid |
| 15804 | file descriptor but it does not reference a directory. |
| 15805 | |
| 15806 | [EACCES] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
| 15807 | but search permission is denied for the directory |
| 15808 | which the _\bf_\bd_\b1 or _\bf_\bd_\b2 file descriptor, respectively, |
| 15809 | references. |
| 15810 | |
| 15811 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 15812 | ln(1), readlink(2), symlink(2), unlink(2) |
| 15813 | |
| 15814 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 15815 | The l\bli\bin\bnk\bk() and l\bli\bin\bnk\bka\bat\bt() functions are expected to conform to IEEE Std |
| 15816 | 1003.1-2008 (``POSIX.1''). |
| 15817 | |
| 15818 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 15819 | The l\bli\bin\bnk\bk() system call first appeared in Version 1 AT&T UNIX. The |
| 15820 | l\bli\bin\bnk\bka\bat\bt() function appeared in OpenBSD 5.0. |
| 15821 | |
| 15822 | N\bNA\bAM\bME\bE |
| 15823 | l\bli\bin\bnk\bk, l\bli\bin\bnk\bka\bat\bt - make hard link to a file |
| 15824 | |
| 15825 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 15826 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 15827 | |
| 15828 | _\bi_\bn_\bt |
| 15829 | l\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
| 15830 | |
| 15831 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 15832 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 15833 | |
| 15834 | _\bi_\bn_\bt |
| 15835 | l\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bi_\bn_\bt _\bf_\bd_\b2, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 15836 | |
| 15837 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 15838 | The l\bli\bin\bnk\bk() function atomically creates the specified directory entry |
| 15839 | (hard link) _\bn_\ba_\bm_\be_\b2 with the attributes of the underlying object pointed at |
| 15840 | by _\bn_\ba_\bm_\be_\b1. If the link is successful: the link count of the underlying |
| 15841 | object is incremented; _\bn_\ba_\bm_\be_\b1 and _\bn_\ba_\bm_\be_\b2 share equal access and rights to |
| 15842 | the underlying object. |
| 15843 | |
| 15844 | If _\bn_\ba_\bm_\be_\b1 is removed, the file _\bn_\ba_\bm_\be_\b2 is not deleted and the link count of |
| 15845 | the underlying object is decremented. |
| 15846 | |
| 15847 | _\bn_\ba_\bm_\be_\b1 must exist for the hard link to succeed and both _\bn_\ba_\bm_\be_\b1 and _\bn_\ba_\bm_\be_\b2 |
| 15848 | must be in the same file system. As mandated by POSIX.1 _\bn_\ba_\bm_\be_\b1 may not be |
| 15849 | a directory. |
| 15850 | |
| 15851 | The l\bli\bin\bnk\bka\bat\bt() function is equivalent to l\bli\bin\bnk\bk() except that where _\bn_\ba_\bm_\be_\b1 or |
| 15852 | _\bn_\ba_\bm_\be_\b2 specifies a relative path, the directory entries linked are |
| 15853 | resolved relative to the directories associated with file descriptors _\bf_\bd_\b1 |
| 15854 | or _\bf_\bd_\b2 (respectively) instead of the current working directory. |
| 15855 | |
| 15856 | If l\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 15857 | in the _\bf_\bd_\b1 or _\bf_\bd_\b2 parameter, the current working directory is used for |
| 15858 | resolving the respective _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument. |
| 15859 | |
| 15860 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 15861 | values: |
| 15862 | |
| 15863 | AT_SYMLINK_FOLLOW If _\bn_\ba_\bm_\be_\b1 names a symbolic link, a new link for |
| 15864 | the target of the symbolic link is created. |
| 15865 | |
| 15866 | If the AT_SYMLINK_FOLLOW flag is clear and _\bn_\ba_\bm_\be_\b1 names a symbolic link, a |
| 15867 | new link is created for the symbolic link _\bn_\ba_\bm_\be_\b1 and not its target. |
| 15868 | |
| 15869 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 15870 | Upon successful completion, the value 0 is returned; otherwise the |
| 15871 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 15872 | error. |
| 15873 | |
| 15874 | E\bER\bRR\bRO\bOR\bRS\bS |
| 15875 | l\bli\bin\bnk\bk() and l\bli\bin\bnk\bka\bat\bt() will fail and no link will be created if: |
| 15876 | |
| 15877 | [ENOTDIR] A component of either path prefix is not a directory. |
| 15878 | |
| 15879 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 15880 | characters, or an entire pathname (including the |
| 15881 | terminating NUL) exceeded PATH_MAX bytes. |
| 15882 | |
| 15883 | [ENOENT] A component of either path prefix does not exist. |
| 15884 | |
| 15885 | [EOPNOTSUPP] The file system containing the file named by _\bn_\ba_\bm_\be_\b1 |
| 15886 | does not support links. |
| 15887 | |
| 15888 | [EMLINK] The link count of the file named by _\bn_\ba_\bm_\be_\b1 would exceed |
| 15889 | LINK_MAX. |
| 15890 | |
| 15891 | [EACCES] A component of either path prefix denies search |
| 15892 | permission. |
| 15893 | |
| 15894 | [EACCES] The requested link requires writing in a directory |
| 15895 | with a mode that denies write permission. |
| 15896 | |
| 15897 | [ELOOP] Too many symbolic links were encountered in |
| 15898 | translating one of the pathnames. |
| 15899 | |
| 15900 | [ENOENT] The file named by _\bn_\ba_\bm_\be_\b1 does not exist. |
| 15901 | |
| 15902 | [EEXIST] The link named by _\bn_\ba_\bm_\be_\b2 does exist. |
| 15903 | |
| 15904 | [EPERM] The file named by _\bn_\ba_\bm_\be_\b1 is a directory and the |
| 15905 | effective user ID is not superuser, or the file system |
| 15906 | containing the file does not permit the use of l\bli\bin\bnk\bk() |
| 15907 | on a directory. |
| 15908 | |
| 15909 | [EPERM] The file named by _\bn_\ba_\bm_\be_\b1 is flagged immutable or |
| 15910 | append-only. |
| 15911 | |
| 15912 | [EXDEV] The link named by _\bn_\ba_\bm_\be_\b2 and the file named by _\bn_\ba_\bm_\be_\b1 |
| 15913 | are on different file systems. |
| 15914 | |
| 15915 | [ENOSPC] The directory in which the entry for the new link is |
| 15916 | being placed cannot be extended because there is no |
| 15917 | space left on the file system containing the |
| 15918 | directory. |
| 15919 | |
| 15920 | [EDQUOT] The directory in which the entry for the new link is |
| 15921 | being placed cannot be extended because the user's |
| 15922 | quota of disk blocks on the file system containing the |
| 15923 | directory has been exhausted. |
| 15924 | |
| 15925 | [EIO] An I/O error occurred while reading from or writing to |
| 15926 | the file system to make the directory entry. |
| 15927 | |
| 15928 | [EROFS] The requested link requires writing in a directory on |
| 15929 | a read-only file system. |
| 15930 | |
| 15931 | [EFAULT] One of the pathnames specified is outside the |
| 15932 | process's allocated address space. |
| 15933 | |
| 15934 | Additionally, l\bli\bin\bnk\bka\bat\bt() will fail if: |
| 15935 | |
| 15936 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 15937 | AT_SYMLINK_FOLLOW. |
| 15938 | |
| 15939 | [EBADF] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
| 15940 | and the _\bf_\bd_\b1 or _\bf_\bd_\b2 argument, respectively, is neither |
| 15941 | AT_FDCWD nor a valid file descriptor. |
| 15942 | |
| 15943 | [ENOTDIR] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
| 15944 | and the _\bf_\bd_\b1 or _\bf_\bd_\b2 argument, respectively, is a valid |
| 15945 | file descriptor but it does not reference a directory. |
| 15946 | |
| 15947 | [EACCES] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
| 15948 | but search permission is denied for the directory |
| 15949 | which the _\bf_\bd_\b1 or _\bf_\bd_\b2 file descriptor, respectively, |
| 15950 | references. |
| 15951 | |
| 15952 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 15953 | ln(1), readlink(2), symlink(2), unlink(2) |
| 15954 | |
| 15955 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 15956 | The l\bli\bin\bnk\bk() and l\bli\bin\bnk\bka\bat\bt() functions are expected to conform to IEEE Std |
| 15957 | 1003.1-2008 (``POSIX.1''). |
| 15958 | |
| 15959 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 15960 | The l\bli\bin\bnk\bk() system call first appeared in Version 1 AT&T UNIX. The |
| 15961 | l\bli\bin\bnk\bka\bat\bt() function appeared in OpenBSD 5.0. |
| 15962 | |
| 15963 | N\bNA\bAM\bME\bE |
| 15964 | l\bli\bis\bst\bte\ben\bn - listen for connections on a socket |
| 15965 | |
| 15966 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 15967 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 15968 | |
| 15969 | _\bi_\bn_\bt |
| 15970 | l\bli\bis\bst\bte\ben\bn(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bb_\ba_\bc_\bk_\bl_\bo_\bg); |
| 15971 | |
| 15972 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 15973 | To accept connections, a socket is first created with socket(2), a |
| 15974 | willingness to accept incoming connections and a queue limit for incoming |
| 15975 | connections are specified with l\bli\bis\bst\bte\ben\bn(), and then the connections are |
| 15976 | accepted with accept(2). The l\bli\bis\bst\bte\ben\bn() call applies only to sockets of |
| 15977 | type SOCK_STREAM or SOCK_SEQPACKET. |
| 15978 | |
| 15979 | The _\bb_\ba_\bc_\bk_\bl_\bo_\bg parameter defines the maximum length the queue of pending |
| 15980 | connections may grow to. If a connection request arrives with the queue |
| 15981 | full the client may receive an error with an indication of ECONNREFUSED, |
| 15982 | or, if the underlying protocol supports retransmission, the request may |
| 15983 | be ignored so that retries may succeed. |
| 15984 | |
| 15985 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 15986 | Upon successful completion, the value 0 is returned; otherwise the |
| 15987 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 15988 | error. |
| 15989 | |
| 15990 | E\bER\bRR\bRO\bOR\bRS\bS |
| 15991 | l\bli\bis\bst\bte\ben\bn() will fail if: |
| 15992 | |
| 15993 | [EBADF] The argument _\bs is not a valid descriptor. |
| 15994 | |
| 15995 | [ENOTSOCK] The argument _\bs is not a socket. |
| 15996 | |
| 15997 | [EOPNOTSUPP] The socket is not of a type that supports the |
| 15998 | operation l\bli\bis\bst\bte\ben\bn(). |
| 15999 | |
| 16000 | [EINVAL] The socket is already connected. |
| 16001 | |
| 16002 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16003 | accept(2), connect(2), socket(2), sysctl(8) |
| 16004 | |
| 16005 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 16006 | The l\bli\bis\bst\bte\ben\bn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 16007 | |
| 16008 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16009 | The l\bli\bis\bst\bte\ben\bn() system call first appeared in 4.1cBSD. |
| 16010 | |
| 16011 | B\bBU\bUG\bGS\bS |
| 16012 | The _\bb_\ba_\bc_\bk_\bl_\bo_\bg is currently limited (silently) to the value of the |
| 16013 | kern.somaxconn sysctl, which defaults to 128. |
| 16014 | |
| 16015 | N\bNA\bAM\bME\bE |
| 16016 | l\bls\bse\bee\bek\bk - reposition read/write file offset |
| 16017 | |
| 16018 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16019 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 16020 | |
| 16021 | _\bo_\bf_\bf_\b__\bt |
| 16022 | l\bls\bse\bee\bek\bk(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bi_\bn_\bt _\bw_\bh_\be_\bn_\bc_\be); |
| 16023 | |
| 16024 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16025 | The l\bls\bse\bee\bek\bk() function repositions the offset of the file descriptor _\bf_\bi_\bl_\bd_\be_\bs |
| 16026 | to the argument _\bo_\bf_\bf_\bs_\be_\bt according to the directive _\bw_\bh_\be_\bn_\bc_\be. The argument |
| 16027 | _\bf_\bi_\bl_\bd_\be_\bs must be an open file descriptor. l\bls\bse\bee\bek\bk() repositions the file |
| 16028 | pointer _\bf_\bi_\bl_\bd_\be_\bs as follows: |
| 16029 | |
| 16030 | If _\bw_\bh_\be_\bn_\bc_\be is SEEK_SET, the offset is set to _\bo_\bf_\bf_\bs_\be_\bt bytes. |
| 16031 | |
| 16032 | If _\bw_\bh_\be_\bn_\bc_\be is SEEK_CUR, the offset is set to its current location |
| 16033 | plus _\bo_\bf_\bf_\bs_\be_\bt bytes. |
| 16034 | |
| 16035 | If _\bw_\bh_\be_\bn_\bc_\be is SEEK_END, the offset is set to the size of the file |
| 16036 | plus _\bo_\bf_\bf_\bs_\be_\bt bytes. |
| 16037 | |
| 16038 | The l\bls\bse\bee\bek\bk() function allows the file offset to be set beyond the end of |
| 16039 | the existing end-of-file of the file. If data is later written at this |
| 16040 | point, subsequent reads of the data in the gap return bytes of zeros |
| 16041 | (until data is actually written into the gap). |
| 16042 | |
| 16043 | Some devices are incapable of seeking. The value of the pointer |
| 16044 | associated with such a device is undefined. |
| 16045 | |
| 16046 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16047 | Upon successful completion, l\bls\bse\bee\bek\bk() returns the resulting offset location |
| 16048 | as measured in bytes from the beginning of the file. Otherwise, a value |
| 16049 | of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 16050 | |
| 16051 | E\bER\bRR\bRO\bOR\bRS\bS |
| 16052 | l\bls\bse\bee\bek\bk() will fail and the file pointer will remain unchanged if: |
| 16053 | |
| 16054 | [EBADF] _\bf_\bi_\bl_\bd_\be_\bs is not an open file descriptor. |
| 16055 | |
| 16056 | [ESPIPE] _\bf_\bi_\bl_\bd_\be_\bs is associated with a pipe, socket, or FIFO. |
| 16057 | |
| 16058 | [EINVAL] _\bw_\bh_\be_\bn_\bc_\be is not a proper value or the resulting offset |
| 16059 | would be negative on a file system or special device |
| 16060 | that does not allow negative offsets to be used. |
| 16061 | |
| 16062 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16063 | dup(2), open(2) |
| 16064 | |
| 16065 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 16066 | The l\bls\bse\bee\bek\bk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 16067 | |
| 16068 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16069 | A s\bse\bee\bek\bk() system call first appeared in Version 1 AT&T UNIX. In Version 7 |
| 16070 | AT&T UNIX it was renamed to l\bls\bse\bee\bek\bk() for ``long seek'' due to a larger |
| 16071 | _\bo_\bf_\bf_\bs_\be_\bt argument type. |
| 16072 | |
| 16073 | B\bBU\bUG\bGS\bS |
| 16074 | This document's use of _\bw_\bh_\be_\bn_\bc_\be is incorrect English, but is maintained for |
| 16075 | historical reasons. |
| 16076 | |
| 16077 | N\bNA\bAM\bME\bE |
| 16078 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 16079 | |
| 16080 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16081 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16082 | |
| 16083 | _\bi_\bn_\bt |
| 16084 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 16085 | |
| 16086 | _\bi_\bn_\bt |
| 16087 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 16088 | |
| 16089 | _\bi_\bn_\bt |
| 16090 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 16091 | |
| 16092 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16093 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 16094 | |
| 16095 | _\bi_\bn_\bt |
| 16096 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 16097 | |
| 16098 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16099 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 16100 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 16101 | required, but all directories listed in the path name leading to the file |
| 16102 | must be searchable. |
| 16103 | |
| 16104 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 16105 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 16106 | itself, not the file the link references. |
| 16107 | |
| 16108 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 16109 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 16110 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 16111 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 16112 | instead of the current working directory. |
| 16113 | |
| 16114 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 16115 | in the _\bf_\bd parameter, the current working directory is used and the |
| 16116 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 16117 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 16118 | |
| 16119 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 16120 | values: |
| 16121 | |
| 16122 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 16123 | of the symbolic link is returned. |
| 16124 | |
| 16125 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 16126 | known by the file descriptor _\bf_\bd. |
| 16127 | |
| 16128 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 16129 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 16130 | concerning the file. |
| 16131 | |
| 16132 | struct stat { |
| 16133 | dev_t st_dev; /* inode's device */ |
| 16134 | ino_t st_ino; /* inode's number */ |
| 16135 | mode_t st_mode; /* inode protection mode */ |
| 16136 | nlink_t st_nlink; /* number of hard links */ |
| 16137 | uid_t st_uid; /* user ID of the file's owner */ |
| 16138 | gid_t st_gid; /* group ID of the file's group */ |
| 16139 | dev_t st_rdev; /* device type */ |
| 16140 | struct timespec st_atim; /* time of last access */ |
| 16141 | struct timespec st_mtim; /* time of last data modification */ |
| 16142 | struct timespec st_ctim; /* time of last file status change */ |
| 16143 | off_t st_size; /* file size, in bytes */ |
| 16144 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 16145 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 16146 | u_int32_t st_flags; /* user defined flags for file */ |
| 16147 | u_int32_t st_gen; /* file generation number */ |
| 16148 | }; |
| 16149 | |
| 16150 | The time-related fields of struct stat are represented in struct timespec |
| 16151 | format, which has nanosecond precision. However, the actual precision is |
| 16152 | generally limited by the file system holding the file. The fields are as |
| 16153 | follows: |
| 16154 | |
| 16155 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 16156 | system object was created and updated by the utimes(2) and |
| 16157 | read(2) system calls. |
| 16158 | |
| 16159 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 16160 | truncate(2), utimes(2), and write(2) system calls. For |
| 16161 | directories, changed by any system call that alters which |
| 16162 | files are in the directory, such as the unlink(2), rename(2), |
| 16163 | mkdir(2), and symlink(2) system calls. |
| 16164 | |
| 16165 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 16166 | modification). Changed by the chmod(2), chown(2), link(2), |
| 16167 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 16168 | |
| 16169 | In addition, all the time fields are set to the current time when a file |
| 16170 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 16171 | open(2), and symlink(2) system calls. |
| 16172 | |
| 16173 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 16174 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 16175 | respective struct timespec member. Deprecated macros are also provided |
| 16176 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 16177 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 16178 | |
| 16179 | The size-related fields of the struct stat are as follows: |
| 16180 | |
| 16181 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 16182 | |
| 16183 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 16184 | 512-byte units. As short symbolic links are stored in the |
| 16185 | inode, this number may be zero. |
| 16186 | |
| 16187 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 16188 | |
| 16189 | #define S_IFMT 0170000 /* type of file mask */ |
| 16190 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 16191 | #define S_IFCHR 0020000 /* character special */ |
| 16192 | #define S_IFDIR 0040000 /* directory */ |
| 16193 | #define S_IFBLK 0060000 /* block special */ |
| 16194 | #define S_IFREG 0100000 /* regular */ |
| 16195 | #define S_IFLNK 0120000 /* symbolic link */ |
| 16196 | #define S_IFSOCK 0140000 /* socket */ |
| 16197 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 16198 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 16199 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 16200 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 16201 | #define S_IRUSR 0000400 /* R for owner */ |
| 16202 | #define S_IWUSR 0000200 /* W for owner */ |
| 16203 | #define S_IXUSR 0000100 /* X for owner */ |
| 16204 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 16205 | #define S_IRGRP 0000040 /* R for group */ |
| 16206 | #define S_IWGRP 0000020 /* W for group */ |
| 16207 | #define S_IXGRP 0000010 /* X for group */ |
| 16208 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 16209 | #define S_IROTH 0000004 /* R for other */ |
| 16210 | #define S_IWOTH 0000002 /* W for other */ |
| 16211 | #define S_IXOTH 0000001 /* X for other */ |
| 16212 | |
| 16213 | The following macros test a file's type. If the file is of that type, a |
| 16214 | non-zero value is returned; otherwise, 0 is returned. |
| 16215 | |
| 16216 | S_ISBLK(st_mode m) /* block special */ |
| 16217 | S_ISCHR(st_mode m) /* char special */ |
| 16218 | S_ISDIR(st_mode m) /* directory */ |
| 16219 | S_ISFIFO(st_mode m) /* fifo */ |
| 16220 | S_ISLNK(st_mode m) /* symbolic link */ |
| 16221 | S_ISREG(st_mode m) /* regular file */ |
| 16222 | S_ISSOCK(st_mode m) /* socket */ |
| 16223 | |
| 16224 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 16225 | |
| 16226 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16227 | Upon successful completion, the value 0 is returned; otherwise the |
| 16228 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16229 | error. |
| 16230 | |
| 16231 | E\bER\bRR\bRO\bOR\bRS\bS |
| 16232 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 16233 | |
| 16234 | [ENOTDIR] A component of the path prefix is not a directory. |
| 16235 | |
| 16236 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 16237 | characters, or an entire pathname (including the |
| 16238 | terminating NUL) exceeded PATH_MAX bytes. |
| 16239 | |
| 16240 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 16241 | empty path. |
| 16242 | |
| 16243 | [EACCES] Search permission is denied for a component of the |
| 16244 | path prefix. |
| 16245 | |
| 16246 | [ELOOP] Too many symbolic links were encountered in |
| 16247 | translating the pathname. |
| 16248 | |
| 16249 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 16250 | |
| 16251 | [EIO] An I/O error occurred while reading from or writing to |
| 16252 | the file system. |
| 16253 | |
| 16254 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 16255 | |
| 16256 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 16257 | AT_SYMLINK_NOFOLLOW. |
| 16258 | |
| 16259 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16260 | argument is neither AT_FDCWD nor a valid file |
| 16261 | descriptor. |
| 16262 | |
| 16263 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16264 | argument is a valid file descriptor but it does not |
| 16265 | reference a directory. |
| 16266 | |
| 16267 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 16268 | permission is denied for the directory which the _\bf_\bd |
| 16269 | file descriptor references. |
| 16270 | |
| 16271 | f\bfs\bst\bta\bat\bt() will fail if: |
| 16272 | |
| 16273 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 16274 | |
| 16275 | [EFAULT] _\bs_\bb points to an invalid address. |
| 16276 | |
| 16277 | [EIO] An I/O error occurred while reading from the file |
| 16278 | system. |
| 16279 | |
| 16280 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16281 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 16282 | |
| 16283 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 16284 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 16285 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 16286 | |
| 16287 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 16288 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 16289 | |
| 16290 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16291 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 16292 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 16293 | in Version 7 AT&T UNIX. |
| 16294 | |
| 16295 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 16296 | appeared in OpenBSD 5.0. |
| 16297 | |
| 16298 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 16299 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 16300 | |
| 16301 | Certain programs written when the timestamps were just of type time_t |
| 16302 | assumed that the members were consecutive (and could therefore be treated |
| 16303 | as an array and have their address passed directly to utime(3)). The |
| 16304 | transition to timestamps of type struct timespec broke them irrevocably. |
| 16305 | |
| 16306 | B\bBU\bUG\bGS\bS |
| 16307 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 16308 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 16309 | the time fields. |
| 16310 | |
| 16311 | N\bNA\bAM\bME\bE |
| 16312 | m\bma\bad\bdv\bvi\bis\bse\be, p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be - give advice about use of memory |
| 16313 | |
| 16314 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16315 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 16316 | |
| 16317 | _\bi_\bn_\bt |
| 16318 | m\bma\bad\bdv\bvi\bis\bse\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bb_\be_\bh_\ba_\bv); |
| 16319 | |
| 16320 | _\bi_\bn_\bt |
| 16321 | p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bb_\be_\bh_\ba_\bv); |
| 16322 | |
| 16323 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16324 | The m\bma\bad\bdv\bvi\bis\bse\be() system call allows a process that has knowledge of its |
| 16325 | memory behavior to describe it to the system. The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() |
| 16326 | interface has the same effect, but returns the error value instead of |
| 16327 | only setting _\be_\br_\br_\bn_\bo. |
| 16328 | |
| 16329 | The possible behaviors are: |
| 16330 | |
| 16331 | MADV_NORMAL No further special treatment needed. |
| 16332 | |
| 16333 | MADV_RANDOM Expect random page access patterns. |
| 16334 | |
| 16335 | MADV_SEQUENTIAL Expect sequential page references. |
| 16336 | |
| 16337 | MADV_WILLNEED The pages will be referenced soon. |
| 16338 | |
| 16339 | MADV_DONTNEED The pages will not be referenced soon. |
| 16340 | |
| 16341 | MADV_SPACEAVAIL Ensure that resources are reserved. |
| 16342 | |
| 16343 | MADV_FREE The pages don't contain any useful data and can be |
| 16344 | recycled. |
| 16345 | |
| 16346 | Portable programs that call the p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() interface should use the |
| 16347 | aliases POSIX_MADV_NORMAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, |
| 16348 | POSIX_MADV_WILLNEED, and POSIX_MADV_DONTNEED rather than the flags |
| 16349 | described above. |
| 16350 | |
| 16351 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16352 | The m\bma\bad\bdv\bvi\bis\bse\be() function returns the value 0 if successful; otherwise the |
| 16353 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16354 | error. |
| 16355 | |
| 16356 | If successful, the p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() function will return zero. Otherwise |
| 16357 | an error number will be returned to indicate the error. |
| 16358 | |
| 16359 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16360 | mincore(2), minherit(2), mprotect(2), msync(2), munmap(2) |
| 16361 | |
| 16362 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 16363 | The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() system call conforms to IEEE Std 1003.1-2008 |
| 16364 | (``POSIX.1''). |
| 16365 | |
| 16366 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16367 | The m\bma\bad\bdv\bvi\bis\bse\be() function first appeared in 4.4BSD. The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() |
| 16368 | function first appeared in OpenBSD 4.8. |
| 16369 | |
| 16370 | B\bBU\bUG\bGS\bS |
| 16371 | The MADV_WILLNEED behavior is ignored. The MADV_SPACEAVAIL behavior is |
| 16372 | not implemented and will always fail. |
| 16373 | |
| 16374 | N\bNA\bAM\bME\bE |
| 16375 | m\bmi\bin\bnc\bco\bor\bre\be - determine residency of memory pages |
| 16376 | |
| 16377 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16378 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 16379 | |
| 16380 | _\bi_\bn_\bt |
| 16381 | m\bmi\bin\bnc\bco\bor\bre\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bc_\bh_\ba_\br _\b*_\bv_\be_\bc); |
| 16382 | |
| 16383 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16384 | The m\bmi\bin\bnc\bco\bor\bre\be() system call allows a process to obtain information about |
| 16385 | whether pages are core resident. Here the current core residency of the |
| 16386 | pages is returned in the character array _\bv_\be_\bc, with a value of 1 meaning |
| 16387 | that the page is in-core. |
| 16388 | |
| 16389 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16390 | Upon successful completion, the value 0 is returned; otherwise the |
| 16391 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16392 | error. |
| 16393 | |
| 16394 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16395 | madvise(2), minherit(2), mlock(2), mprotect(2), msync(2), munmap(2) |
| 16396 | |
| 16397 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16398 | The m\bmi\bin\bnc\bco\bor\bre\be() function first appeared in 4.4BSD. |
| 16399 | |
| 16400 | N\bNA\bAM\bME\bE |
| 16401 | m\bmi\bin\bnh\bhe\ber\bri\bit\bt - control the inheritance of pages |
| 16402 | |
| 16403 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16404 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 16405 | |
| 16406 | _\bi_\bn_\bt |
| 16407 | m\bmi\bin\bnh\bhe\ber\bri\bit\bt(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bi_\bn_\bh_\be_\br_\bi_\bt); |
| 16408 | |
| 16409 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16410 | The m\bmi\bin\bnh\bhe\ber\bri\bit\bt() system call changes the specified pages to have the |
| 16411 | inheritance characteristic _\bi_\bn_\bh_\be_\br_\bi_\bt. A page's inheritance characteristic |
| 16412 | controls how it will be mapped in child processes as created by fork(2). |
| 16413 | |
| 16414 | The possible inheritance characteristics are: |
| 16415 | |
| 16416 | MAP_INHERIT_NONE Pages are not mapped in the child process. |
| 16417 | MAP_INHERIT_COPY Private copy of pages are mapped in the child |
| 16418 | process. |
| 16419 | MAP_INHERIT_SHARE Mapped pages are shared between the parent and |
| 16420 | child processes. |
| 16421 | MAP_INHERIT_ZERO New anonymous pages (initialized to all zero |
| 16422 | bytes) are mapped in the child process. |
| 16423 | |
| 16424 | Not all implementations will guarantee that the inheritance |
| 16425 | characteristic can be set on a page basis; the granularity of changes may |
| 16426 | be as large as an entire region. |
| 16427 | |
| 16428 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16429 | Upon successful completion, the value 0 is returned; otherwise the |
| 16430 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16431 | error. |
| 16432 | |
| 16433 | E\bER\bRR\bRO\bOR\bRS\bS |
| 16434 | The m\bmi\bin\bnh\bhe\ber\bri\bit\bt() system call will fail if: |
| 16435 | |
| 16436 | [EINVAL] The virtual address range specified by the _\ba_\bd_\bd_\br and |
| 16437 | _\bl_\be_\bn arguments is not valid. |
| 16438 | |
| 16439 | [EINVAL] The _\bi_\bn_\bh_\be_\br_\bi_\bt argument is invalid. |
| 16440 | |
| 16441 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16442 | madvise(2), mincore(2), mprotect(2), msync(2), munmap(2) |
| 16443 | |
| 16444 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16445 | The m\bmi\bin\bnh\bhe\ber\bri\bit\bt() function first appeared in OpenBSD 2.0. |
| 16446 | |
| 16447 | N\bNA\bAM\bME\bE |
| 16448 | m\bmk\bkd\bdi\bir\br, m\bmk\bkd\bdi\bir\bra\bat\bt - make a directory file |
| 16449 | |
| 16450 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16451 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16452 | |
| 16453 | _\bi_\bn_\bt |
| 16454 | m\bmk\bkd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 16455 | |
| 16456 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16457 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 16458 | |
| 16459 | _\bi_\bn_\bt |
| 16460 | m\bmk\bkd\bdi\bir\bra\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 16461 | |
| 16462 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16463 | The directory _\bp_\ba_\bt_\bh is created with the access permissions specified by |
| 16464 | _\bm_\bo_\bd_\be and restricted by the umask(2) of the calling process. |
| 16465 | |
| 16466 | The directory's owner ID is set to the process's effective user ID. The |
| 16467 | directory's group ID is set to that of the parent directory in which it |
| 16468 | is created. |
| 16469 | |
| 16470 | The m\bmk\bkd\bdi\bir\bra\bat\bt() function is equivalent to m\bmk\bkd\bdi\bir\br() except that where _\bp_\ba_\bt_\bh |
| 16471 | specifies a relative path, the newly created directory is created |
| 16472 | relative to the directory associated with file descriptor _\bf_\bd instead of |
| 16473 | the current working directory. |
| 16474 | |
| 16475 | If m\bmk\bkd\bdi\bir\bra\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 16476 | in the _\bf_\bd parameter, the current working directory is used and the |
| 16477 | behavior is identical to a call to m\bmk\bkd\bdi\bir\br(). |
| 16478 | |
| 16479 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16480 | Upon successful completion, the value 0 is returned; otherwise the |
| 16481 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16482 | error. |
| 16483 | |
| 16484 | E\bER\bRR\bRO\bOR\bRS\bS |
| 16485 | m\bmk\bkd\bdi\bir\br() and m\bmk\bkd\bdi\bir\bra\bat\bt() will fail and no directory will be created if: |
| 16486 | |
| 16487 | [ENOTDIR] A component of the path prefix is not a directory. |
| 16488 | |
| 16489 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 16490 | characters, or an entire pathname (including the |
| 16491 | terminating NUL) exceeded PATH_MAX bytes. |
| 16492 | |
| 16493 | [ENOENT] A component of the path prefix does not exist. |
| 16494 | |
| 16495 | [EACCES] Search permission is denied for a component of the |
| 16496 | path prefix. |
| 16497 | |
| 16498 | [ELOOP] Too many symbolic links were encountered in |
| 16499 | translating the pathname. |
| 16500 | |
| 16501 | [EROFS] The named file resides on a read-only file system. |
| 16502 | |
| 16503 | [EEXIST] The named file exists. |
| 16504 | |
| 16505 | [ENOSPC] The new directory cannot be created because there is |
| 16506 | no space left on the file system that will contain the |
| 16507 | directory. |
| 16508 | |
| 16509 | [ENOSPC] There are no free inodes on the file system on which |
| 16510 | the directory is being created. |
| 16511 | |
| 16512 | [EDQUOT] The new directory cannot be created because the user's |
| 16513 | quota of disk blocks on the file system that will |
| 16514 | contain the directory has been exhausted. |
| 16515 | |
| 16516 | [EDQUOT] The user's quota of inodes on the file system on which |
| 16517 | the directory is being created has been exhausted. |
| 16518 | |
| 16519 | [EIO] An I/O error occurred while making the directory entry |
| 16520 | or allocating the inode. |
| 16521 | |
| 16522 | [EIO] An I/O error occurred while reading from or writing to |
| 16523 | the file system. |
| 16524 | |
| 16525 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 16526 | space. |
| 16527 | |
| 16528 | Additionally, m\bmk\bkd\bdi\bir\bra\bat\bt() will fail if: |
| 16529 | |
| 16530 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16531 | argument is neither AT_FDCWD nor a valid file |
| 16532 | descriptor. |
| 16533 | |
| 16534 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16535 | argument is a valid file descriptor but it does not |
| 16536 | reference a directory. |
| 16537 | |
| 16538 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 16539 | permission is denied for the directory which the _\bf_\bd |
| 16540 | file descriptor references. |
| 16541 | |
| 16542 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16543 | chmod(2), stat(2), umask(2) |
| 16544 | |
| 16545 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 16546 | The m\bmk\bkd\bdi\bir\br() and m\bmk\bkd\bdi\bir\bra\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 16547 | (``POSIX.1''). |
| 16548 | |
| 16549 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16550 | A m\bmk\bkd\bdi\bir\br() system call first appeared in Version 1 AT&T UNIX. It was |
| 16551 | renamed to m\bma\bak\bkd\bdi\bir\br() in Version 2 AT&T UNIX. However, it did not exist |
| 16552 | from Version 4 AT&T UNIX to 4.1BSD; in those releases, mknod(2) had to be |
| 16553 | used. Since m\bmk\bkd\bdi\bir\br() reappeared in 4.1cBSD, it no longer requires |
| 16554 | superuser privileges and it automatically creates the `.' and `..' |
| 16555 | directory entries. |
| 16556 | |
| 16557 | The m\bmk\bkd\bdi\bir\bra\bat\bt() system call has been available since OpenBSD 5.0. |
| 16558 | |
| 16559 | N\bNA\bAM\bME\bE |
| 16560 | m\bmk\bkd\bdi\bir\br, m\bmk\bkd\bdi\bir\bra\bat\bt - make a directory file |
| 16561 | |
| 16562 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16563 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16564 | |
| 16565 | _\bi_\bn_\bt |
| 16566 | m\bmk\bkd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 16567 | |
| 16568 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16569 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 16570 | |
| 16571 | _\bi_\bn_\bt |
| 16572 | m\bmk\bkd\bdi\bir\bra\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 16573 | |
| 16574 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16575 | The directory _\bp_\ba_\bt_\bh is created with the access permissions specified by |
| 16576 | _\bm_\bo_\bd_\be and restricted by the umask(2) of the calling process. |
| 16577 | |
| 16578 | The directory's owner ID is set to the process's effective user ID. The |
| 16579 | directory's group ID is set to that of the parent directory in which it |
| 16580 | is created. |
| 16581 | |
| 16582 | The m\bmk\bkd\bdi\bir\bra\bat\bt() function is equivalent to m\bmk\bkd\bdi\bir\br() except that where _\bp_\ba_\bt_\bh |
| 16583 | specifies a relative path, the newly created directory is created |
| 16584 | relative to the directory associated with file descriptor _\bf_\bd instead of |
| 16585 | the current working directory. |
| 16586 | |
| 16587 | If m\bmk\bkd\bdi\bir\bra\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 16588 | in the _\bf_\bd parameter, the current working directory is used and the |
| 16589 | behavior is identical to a call to m\bmk\bkd\bdi\bir\br(). |
| 16590 | |
| 16591 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16592 | Upon successful completion, the value 0 is returned; otherwise the |
| 16593 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16594 | error. |
| 16595 | |
| 16596 | E\bER\bRR\bRO\bOR\bRS\bS |
| 16597 | m\bmk\bkd\bdi\bir\br() and m\bmk\bkd\bdi\bir\bra\bat\bt() will fail and no directory will be created if: |
| 16598 | |
| 16599 | [ENOTDIR] A component of the path prefix is not a directory. |
| 16600 | |
| 16601 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 16602 | characters, or an entire pathname (including the |
| 16603 | terminating NUL) exceeded PATH_MAX bytes. |
| 16604 | |
| 16605 | [ENOENT] A component of the path prefix does not exist. |
| 16606 | |
| 16607 | [EACCES] Search permission is denied for a component of the |
| 16608 | path prefix. |
| 16609 | |
| 16610 | [ELOOP] Too many symbolic links were encountered in |
| 16611 | translating the pathname. |
| 16612 | |
| 16613 | [EROFS] The named file resides on a read-only file system. |
| 16614 | |
| 16615 | [EEXIST] The named file exists. |
| 16616 | |
| 16617 | [ENOSPC] The new directory cannot be created because there is |
| 16618 | no space left on the file system that will contain the |
| 16619 | directory. |
| 16620 | |
| 16621 | [ENOSPC] There are no free inodes on the file system on which |
| 16622 | the directory is being created. |
| 16623 | |
| 16624 | [EDQUOT] The new directory cannot be created because the user's |
| 16625 | quota of disk blocks on the file system that will |
| 16626 | contain the directory has been exhausted. |
| 16627 | |
| 16628 | [EDQUOT] The user's quota of inodes on the file system on which |
| 16629 | the directory is being created has been exhausted. |
| 16630 | |
| 16631 | [EIO] An I/O error occurred while making the directory entry |
| 16632 | or allocating the inode. |
| 16633 | |
| 16634 | [EIO] An I/O error occurred while reading from or writing to |
| 16635 | the file system. |
| 16636 | |
| 16637 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 16638 | space. |
| 16639 | |
| 16640 | Additionally, m\bmk\bkd\bdi\bir\bra\bat\bt() will fail if: |
| 16641 | |
| 16642 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16643 | argument is neither AT_FDCWD nor a valid file |
| 16644 | descriptor. |
| 16645 | |
| 16646 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16647 | argument is a valid file descriptor but it does not |
| 16648 | reference a directory. |
| 16649 | |
| 16650 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 16651 | permission is denied for the directory which the _\bf_\bd |
| 16652 | file descriptor references. |
| 16653 | |
| 16654 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16655 | chmod(2), stat(2), umask(2) |
| 16656 | |
| 16657 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 16658 | The m\bmk\bkd\bdi\bir\br() and m\bmk\bkd\bdi\bir\bra\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 16659 | (``POSIX.1''). |
| 16660 | |
| 16661 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16662 | A m\bmk\bkd\bdi\bir\br() system call first appeared in Version 1 AT&T UNIX. It was |
| 16663 | renamed to m\bma\bak\bkd\bdi\bir\br() in Version 2 AT&T UNIX. However, it did not exist |
| 16664 | from Version 4 AT&T UNIX to 4.1BSD; in those releases, mknod(2) had to be |
| 16665 | used. Since m\bmk\bkd\bdi\bir\br() reappeared in 4.1cBSD, it no longer requires |
| 16666 | superuser privileges and it automatically creates the `.' and `..' |
| 16667 | directory entries. |
| 16668 | |
| 16669 | The m\bmk\bkd\bdi\bir\bra\bat\bt() system call has been available since OpenBSD 5.0. |
| 16670 | |
| 16671 | N\bNA\bAM\bME\bE |
| 16672 | m\bmk\bkf\bfi\bif\bfo\bo, m\bmk\bkf\bfi\bif\bfo\boa\bat\bt - make a FIFO file |
| 16673 | |
| 16674 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16675 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16676 | |
| 16677 | _\bi_\bn_\bt |
| 16678 | m\bmk\bkf\bfi\bif\bfo\bo(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 16679 | |
| 16680 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16681 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 16682 | |
| 16683 | _\bi_\bn_\bt |
| 16684 | m\bmk\bkf\bfi\bif\bfo\boa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 16685 | |
| 16686 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16687 | m\bmk\bkf\bfi\bif\bfo\bo() creates a new FIFO file with name _\bp_\ba_\bt_\bh. The access permissions |
| 16688 | are specified by _\bm_\bo_\bd_\be and restricted by the umask(2) of the calling |
| 16689 | process. |
| 16690 | |
| 16691 | The FIFO's owner ID is set to the process's effective user ID. The |
| 16692 | FIFO's group ID is set to that of the parent directory in which it is |
| 16693 | created. |
| 16694 | |
| 16695 | The m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() function is equivalent to m\bmk\bkf\bfi\bif\bfo\bo() except that where _\bp_\ba_\bt_\bh |
| 16696 | specifies a relative path, the newly created FIFO is created relative to |
| 16697 | the directory associated with file descriptor _\bf_\bd instead of the current |
| 16698 | working directory. |
| 16699 | |
| 16700 | If m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 16701 | in the _\bf_\bd parameter, the current working directory is used and the |
| 16702 | behavior is identical to a call to m\bmk\bkf\bfi\bif\bfo\bo(). |
| 16703 | |
| 16704 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16705 | Upon successful completion, the value 0 is returned; otherwise the |
| 16706 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16707 | error. |
| 16708 | |
| 16709 | E\bER\bRR\bRO\bOR\bRS\bS |
| 16710 | m\bmk\bkf\bfi\bif\bfo\bo() and m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() will fail and no FIFO will be created if: |
| 16711 | |
| 16712 | [EOPNOTSUPP] The kernel has not been configured to support FIFOs. |
| 16713 | |
| 16714 | [ENOTDIR] A component of the path prefix is not a directory. |
| 16715 | |
| 16716 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 16717 | characters, or an entire pathname (including the |
| 16718 | terminating NUL) exceeded PATH_MAX bytes. |
| 16719 | |
| 16720 | [ENOENT] A component of the path prefix does not exist. |
| 16721 | |
| 16722 | [EACCES] Search permission is denied for a component of the |
| 16723 | path prefix. |
| 16724 | |
| 16725 | [ELOOP] Too many symbolic links were encountered in |
| 16726 | translating the pathname. |
| 16727 | |
| 16728 | [EROFS] The named file resides on a read-only file system. |
| 16729 | |
| 16730 | [EEXIST] The named file exists. |
| 16731 | |
| 16732 | [ENOSPC] The directory in which the entry for the new FIFO is |
| 16733 | being placed cannot be extended because there is no |
| 16734 | space left on the file system containing the |
| 16735 | directory. |
| 16736 | |
| 16737 | [ENOSPC] There are no free inodes on the file system on which |
| 16738 | the FIFO is being created. |
| 16739 | |
| 16740 | [EDQUOT] The directory in which the entry for the new FIFO is |
| 16741 | being placed cannot be extended because the user's |
| 16742 | quota of disk blocks on the file system containing the |
| 16743 | directory has been exhausted. |
| 16744 | |
| 16745 | [EDQUOT] The user's quota of inodes on the file system on which |
| 16746 | the FIFO is being created has been exhausted. |
| 16747 | |
| 16748 | [EIO] An I/O error occurred while making the directory entry |
| 16749 | or allocating the inode. |
| 16750 | |
| 16751 | [EIO] An I/O error occurred while reading from or writing to |
| 16752 | the file system. |
| 16753 | |
| 16754 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 16755 | space. |
| 16756 | |
| 16757 | Additionally, m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() will fail if: |
| 16758 | |
| 16759 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16760 | argument is neither AT_FDCWD nor a valid file |
| 16761 | descriptor. |
| 16762 | |
| 16763 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16764 | argument is a valid file descriptor but it does not |
| 16765 | reference a directory. |
| 16766 | |
| 16767 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 16768 | permission is denied for the directory which the _\bf_\bd |
| 16769 | file descriptor references. |
| 16770 | |
| 16771 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16772 | chmod(2), stat(2), umask(2) |
| 16773 | |
| 16774 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 16775 | The m\bmk\bkf\bfi\bif\bfo\bo and m\bmk\bkf\bfi\bif\bfo\boa\bat\bt functions conform to IEEE Std 1003.1-2008 |
| 16776 | (``POSIX.1''). |
| 16777 | |
| 16778 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16779 | The m\bmk\bkf\bfi\bif\bfo\boa\bat\bt function appeared in OpenBSD 5.0. |
| 16780 | |
| 16781 | N\bNA\bAM\bME\bE |
| 16782 | m\bmk\bkf\bfi\bif\bfo\bo, m\bmk\bkf\bfi\bif\bfo\boa\bat\bt - make a FIFO file |
| 16783 | |
| 16784 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16785 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16786 | |
| 16787 | _\bi_\bn_\bt |
| 16788 | m\bmk\bkf\bfi\bif\bfo\bo(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 16789 | |
| 16790 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16791 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 16792 | |
| 16793 | _\bi_\bn_\bt |
| 16794 | m\bmk\bkf\bfi\bif\bfo\boa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
| 16795 | |
| 16796 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16797 | m\bmk\bkf\bfi\bif\bfo\bo() creates a new FIFO file with name _\bp_\ba_\bt_\bh. The access permissions |
| 16798 | are specified by _\bm_\bo_\bd_\be and restricted by the umask(2) of the calling |
| 16799 | process. |
| 16800 | |
| 16801 | The FIFO's owner ID is set to the process's effective user ID. The |
| 16802 | FIFO's group ID is set to that of the parent directory in which it is |
| 16803 | created. |
| 16804 | |
| 16805 | The m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() function is equivalent to m\bmk\bkf\bfi\bif\bfo\bo() except that where _\bp_\ba_\bt_\bh |
| 16806 | specifies a relative path, the newly created FIFO is created relative to |
| 16807 | the directory associated with file descriptor _\bf_\bd instead of the current |
| 16808 | working directory. |
| 16809 | |
| 16810 | If m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 16811 | in the _\bf_\bd parameter, the current working directory is used and the |
| 16812 | behavior is identical to a call to m\bmk\bkf\bfi\bif\bfo\bo(). |
| 16813 | |
| 16814 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16815 | Upon successful completion, the value 0 is returned; otherwise the |
| 16816 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16817 | error. |
| 16818 | |
| 16819 | E\bER\bRR\bRO\bOR\bRS\bS |
| 16820 | m\bmk\bkf\bfi\bif\bfo\bo() and m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() will fail and no FIFO will be created if: |
| 16821 | |
| 16822 | [EOPNOTSUPP] The kernel has not been configured to support FIFOs. |
| 16823 | |
| 16824 | [ENOTDIR] A component of the path prefix is not a directory. |
| 16825 | |
| 16826 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 16827 | characters, or an entire pathname (including the |
| 16828 | terminating NUL) exceeded PATH_MAX bytes. |
| 16829 | |
| 16830 | [ENOENT] A component of the path prefix does not exist. |
| 16831 | |
| 16832 | [EACCES] Search permission is denied for a component of the |
| 16833 | path prefix. |
| 16834 | |
| 16835 | [ELOOP] Too many symbolic links were encountered in |
| 16836 | translating the pathname. |
| 16837 | |
| 16838 | [EROFS] The named file resides on a read-only file system. |
| 16839 | |
| 16840 | [EEXIST] The named file exists. |
| 16841 | |
| 16842 | [ENOSPC] The directory in which the entry for the new FIFO is |
| 16843 | being placed cannot be extended because there is no |
| 16844 | space left on the file system containing the |
| 16845 | directory. |
| 16846 | |
| 16847 | [ENOSPC] There are no free inodes on the file system on which |
| 16848 | the FIFO is being created. |
| 16849 | |
| 16850 | [EDQUOT] The directory in which the entry for the new FIFO is |
| 16851 | being placed cannot be extended because the user's |
| 16852 | quota of disk blocks on the file system containing the |
| 16853 | directory has been exhausted. |
| 16854 | |
| 16855 | [EDQUOT] The user's quota of inodes on the file system on which |
| 16856 | the FIFO is being created has been exhausted. |
| 16857 | |
| 16858 | [EIO] An I/O error occurred while making the directory entry |
| 16859 | or allocating the inode. |
| 16860 | |
| 16861 | [EIO] An I/O error occurred while reading from or writing to |
| 16862 | the file system. |
| 16863 | |
| 16864 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 16865 | space. |
| 16866 | |
| 16867 | Additionally, m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() will fail if: |
| 16868 | |
| 16869 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16870 | argument is neither AT_FDCWD nor a valid file |
| 16871 | descriptor. |
| 16872 | |
| 16873 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16874 | argument is a valid file descriptor but it does not |
| 16875 | reference a directory. |
| 16876 | |
| 16877 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 16878 | permission is denied for the directory which the _\bf_\bd |
| 16879 | file descriptor references. |
| 16880 | |
| 16881 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 16882 | chmod(2), stat(2), umask(2) |
| 16883 | |
| 16884 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 16885 | The m\bmk\bkf\bfi\bif\bfo\bo and m\bmk\bkf\bfi\bif\bfo\boa\bat\bt functions conform to IEEE Std 1003.1-2008 |
| 16886 | (``POSIX.1''). |
| 16887 | |
| 16888 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 16889 | The m\bmk\bkf\bfi\bif\bfo\boa\bat\bt function appeared in OpenBSD 5.0. |
| 16890 | |
| 16891 | N\bNA\bAM\bME\bE |
| 16892 | m\bmk\bkn\bno\bod\bd, m\bmk\bkn\bno\bod\bda\bat\bt - make a special file node |
| 16893 | |
| 16894 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 16895 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16896 | |
| 16897 | _\bi_\bn_\bt |
| 16898 | m\bmk\bkn\bno\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bd_\be_\bv_\b__\bt _\bd_\be_\bv); |
| 16899 | |
| 16900 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 16901 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 16902 | |
| 16903 | _\bi_\bn_\bt |
| 16904 | m\bmk\bkn\bno\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bd_\be_\bv_\b__\bt _\bd_\be_\bv); |
| 16905 | |
| 16906 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16907 | The m\bmk\bkn\bno\bod\bd() function creates _\bp_\ba_\bt_\bh with a file type and mode of _\bm_\bo_\bd_\be, as |
| 16908 | modified by umask(2). Only FIFO and device special files are supported |
| 16909 | by this implementation. |
| 16910 | |
| 16911 | If _\bm_\bo_\bd_\be is the bitwise OR of S_IFIFO and zero or more file permissions, |
| 16912 | and _\bd_\be_\bv is zero, then a FIFO is created. If _\bm_\bo_\bd_\be is the bitwise OR of |
| 16913 | S_IFCHR or S_IFBLK and zero or more file permissions, then a character or |
| 16914 | block device special (respectively) is created with major and minor |
| 16915 | device numbers extracted from _\bd_\be_\bv. |
| 16916 | |
| 16917 | The m\bmk\bkn\bno\bod\bda\bat\bt() function is equivalent to m\bmk\bkn\bno\bod\bd() except that where _\bp_\ba_\bt_\bh |
| 16918 | specifies a relative path, the newly created device special file is |
| 16919 | created relative to the directory associated with file descriptor _\bf_\bd |
| 16920 | instead of the current working directory. |
| 16921 | |
| 16922 | If m\bmk\bkn\bno\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 16923 | in the _\bf_\bd parameter, the current working directory is used and the |
| 16924 | behavior is identical to a call to m\bmk\bkn\bno\bod\bd(). |
| 16925 | |
| 16926 | Creating a device special file with m\bmk\bkn\bno\bod\bd() or m\bmk\bkn\bno\bod\bda\bat\bt() requires |
| 16927 | superuser privileges. |
| 16928 | |
| 16929 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 16930 | Upon successful completion, the value 0 is returned; otherwise the |
| 16931 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 16932 | error. |
| 16933 | |
| 16934 | E\bER\bRR\bRO\bOR\bRS\bS |
| 16935 | m\bmk\bkn\bno\bod\bd() and m\bmk\bkn\bno\bod\bda\bat\bt() will fail and the file will be not created if: |
| 16936 | |
| 16937 | [EINVAL] _\bm_\bo_\bd_\be is an invalid file type or _\bd_\be_\bv is an invalid |
| 16938 | value for that file type. |
| 16939 | |
| 16940 | [ENOTDIR] A component of the path prefix is not a directory. |
| 16941 | |
| 16942 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 16943 | characters, or an entire pathname (including the |
| 16944 | terminating NUL) exceeded PATH_MAX bytes. |
| 16945 | |
| 16946 | [ENOENT] A component of the path prefix does not exist. |
| 16947 | |
| 16948 | [EACCES] Search permission is denied for a component of the |
| 16949 | path prefix. |
| 16950 | |
| 16951 | [ELOOP] Too many symbolic links were encountered in |
| 16952 | translating the pathname. |
| 16953 | |
| 16954 | [EPERM] _\bm_\bo_\bd_\be is a device special and the process's effective |
| 16955 | user ID is not superuser. |
| 16956 | |
| 16957 | [EIO] An I/O error occurred while making the directory entry |
| 16958 | or allocating the inode. |
| 16959 | |
| 16960 | [ENOSPC] The directory in which the entry for the new node is |
| 16961 | being placed cannot be extended because there is no |
| 16962 | space left on the file system containing the |
| 16963 | directory. |
| 16964 | |
| 16965 | [ENOSPC] There are no free inodes on the file system on which |
| 16966 | the node is being created. |
| 16967 | |
| 16968 | [EDQUOT] The directory in which the entry for the new node is |
| 16969 | being placed cannot be extended because the user's |
| 16970 | quota of disk blocks on the file system containing the |
| 16971 | directory has been exhausted. |
| 16972 | |
| 16973 | [EDQUOT] The user's quota of inodes on the file system on which |
| 16974 | the node is being created has been exhausted. |
| 16975 | |
| 16976 | [EROFS] The named file resides on a read-only file system. |
| 16977 | |
| 16978 | [EEXIST] The named file exists. |
| 16979 | |
| 16980 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 16981 | space. |
| 16982 | |
| 16983 | [EINVAL] The process is running within an alternate root |
| 16984 | directory, as created by chroot(2). |
| 16985 | |
| 16986 | Additionally, m\bmk\bkn\bno\bod\bda\bat\bt() will fail if: |
| 16987 | |
| 16988 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16989 | argument is neither AT_FDCWD nor a valid file |
| 16990 | descriptor. |
| 16991 | |
| 16992 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 16993 | argument is a valid file descriptor but it does not |
| 16994 | reference a directory. |
| 16995 | |
| 16996 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 16997 | permission is denied for the directory which the _\bf_\bd |
| 16998 | file descriptor references. |
| 16999 | |
| 17000 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17001 | chmod(2), chroot(2), mkfifo(2), stat(2), umask(2) |
| 17002 | |
| 17003 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 17004 | The m\bmk\bkn\bno\bod\bd() and m\bmk\bkn\bno\bod\bda\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 17005 | (``POSIX.1''). |
| 17006 | |
| 17007 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17008 | The m\bmk\bkn\bno\bod\bd() system call first appeared in Version 4 AT&T UNIX, and |
| 17009 | m\bmk\bkn\bno\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
| 17010 | |
| 17011 | N\bNA\bAM\bME\bE |
| 17012 | m\bmk\bkn\bno\bod\bd, m\bmk\bkn\bno\bod\bda\bat\bt - make a special file node |
| 17013 | |
| 17014 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17015 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 17016 | |
| 17017 | _\bi_\bn_\bt |
| 17018 | m\bmk\bkn\bno\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bd_\be_\bv_\b__\bt _\bd_\be_\bv); |
| 17019 | |
| 17020 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 17021 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 17022 | |
| 17023 | _\bi_\bn_\bt |
| 17024 | m\bmk\bkn\bno\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bd_\be_\bv_\b__\bt _\bd_\be_\bv); |
| 17025 | |
| 17026 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17027 | The m\bmk\bkn\bno\bod\bd() function creates _\bp_\ba_\bt_\bh with a file type and mode of _\bm_\bo_\bd_\be, as |
| 17028 | modified by umask(2). Only FIFO and device special files are supported |
| 17029 | by this implementation. |
| 17030 | |
| 17031 | If _\bm_\bo_\bd_\be is the bitwise OR of S_IFIFO and zero or more file permissions, |
| 17032 | and _\bd_\be_\bv is zero, then a FIFO is created. If _\bm_\bo_\bd_\be is the bitwise OR of |
| 17033 | S_IFCHR or S_IFBLK and zero or more file permissions, then a character or |
| 17034 | block device special (respectively) is created with major and minor |
| 17035 | device numbers extracted from _\bd_\be_\bv. |
| 17036 | |
| 17037 | The m\bmk\bkn\bno\bod\bda\bat\bt() function is equivalent to m\bmk\bkn\bno\bod\bd() except that where _\bp_\ba_\bt_\bh |
| 17038 | specifies a relative path, the newly created device special file is |
| 17039 | created relative to the directory associated with file descriptor _\bf_\bd |
| 17040 | instead of the current working directory. |
| 17041 | |
| 17042 | If m\bmk\bkn\bno\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 17043 | in the _\bf_\bd parameter, the current working directory is used and the |
| 17044 | behavior is identical to a call to m\bmk\bkn\bno\bod\bd(). |
| 17045 | |
| 17046 | Creating a device special file with m\bmk\bkn\bno\bod\bd() or m\bmk\bkn\bno\bod\bda\bat\bt() requires |
| 17047 | superuser privileges. |
| 17048 | |
| 17049 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17050 | Upon successful completion, the value 0 is returned; otherwise the |
| 17051 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 17052 | error. |
| 17053 | |
| 17054 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17055 | m\bmk\bkn\bno\bod\bd() and m\bmk\bkn\bno\bod\bda\bat\bt() will fail and the file will be not created if: |
| 17056 | |
| 17057 | [EINVAL] _\bm_\bo_\bd_\be is an invalid file type or _\bd_\be_\bv is an invalid |
| 17058 | value for that file type. |
| 17059 | |
| 17060 | [ENOTDIR] A component of the path prefix is not a directory. |
| 17061 | |
| 17062 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 17063 | characters, or an entire pathname (including the |
| 17064 | terminating NUL) exceeded PATH_MAX bytes. |
| 17065 | |
| 17066 | [ENOENT] A component of the path prefix does not exist. |
| 17067 | |
| 17068 | [EACCES] Search permission is denied for a component of the |
| 17069 | path prefix. |
| 17070 | |
| 17071 | [ELOOP] Too many symbolic links were encountered in |
| 17072 | translating the pathname. |
| 17073 | |
| 17074 | [EPERM] _\bm_\bo_\bd_\be is a device special and the process's effective |
| 17075 | user ID is not superuser. |
| 17076 | |
| 17077 | [EIO] An I/O error occurred while making the directory entry |
| 17078 | or allocating the inode. |
| 17079 | |
| 17080 | [ENOSPC] The directory in which the entry for the new node is |
| 17081 | being placed cannot be extended because there is no |
| 17082 | space left on the file system containing the |
| 17083 | directory. |
| 17084 | |
| 17085 | [ENOSPC] There are no free inodes on the file system on which |
| 17086 | the node is being created. |
| 17087 | |
| 17088 | [EDQUOT] The directory in which the entry for the new node is |
| 17089 | being placed cannot be extended because the user's |
| 17090 | quota of disk blocks on the file system containing the |
| 17091 | directory has been exhausted. |
| 17092 | |
| 17093 | [EDQUOT] The user's quota of inodes on the file system on which |
| 17094 | the node is being created has been exhausted. |
| 17095 | |
| 17096 | [EROFS] The named file resides on a read-only file system. |
| 17097 | |
| 17098 | [EEXIST] The named file exists. |
| 17099 | |
| 17100 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 17101 | space. |
| 17102 | |
| 17103 | [EINVAL] The process is running within an alternate root |
| 17104 | directory, as created by chroot(2). |
| 17105 | |
| 17106 | Additionally, m\bmk\bkn\bno\bod\bda\bat\bt() will fail if: |
| 17107 | |
| 17108 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 17109 | argument is neither AT_FDCWD nor a valid file |
| 17110 | descriptor. |
| 17111 | |
| 17112 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 17113 | argument is a valid file descriptor but it does not |
| 17114 | reference a directory. |
| 17115 | |
| 17116 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 17117 | permission is denied for the directory which the _\bf_\bd |
| 17118 | file descriptor references. |
| 17119 | |
| 17120 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17121 | chmod(2), chroot(2), mkfifo(2), stat(2), umask(2) |
| 17122 | |
| 17123 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 17124 | The m\bmk\bkn\bno\bod\bd() and m\bmk\bkn\bno\bod\bda\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 17125 | (``POSIX.1''). |
| 17126 | |
| 17127 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17128 | The m\bmk\bkn\bno\bod\bd() system call first appeared in Version 4 AT&T UNIX, and |
| 17129 | m\bmk\bkn\bno\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
| 17130 | |
| 17131 | N\bNA\bAM\bME\bE |
| 17132 | m\bml\blo\boc\bck\bk, m\bmu\bun\bnl\blo\boc\bck\bk - lock (unlock) physical pages in memory |
| 17133 | |
| 17134 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17135 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 17136 | |
| 17137 | _\bi_\bn_\bt |
| 17138 | m\bml\blo\boc\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
| 17139 | |
| 17140 | _\bi_\bn_\bt |
| 17141 | m\bmu\bun\bnl\blo\boc\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
| 17142 | |
| 17143 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17144 | The m\bml\blo\boc\bck\bk() system call locks into memory the physical pages associated |
| 17145 | with the virtual address range starting at _\ba_\bd_\bd_\br for _\bl_\be_\bn bytes. The |
| 17146 | m\bmu\bun\bnl\blo\boc\bck\bk() call unlocks pages previously locked by one or more m\bml\blo\boc\bck\bk() |
| 17147 | calls. For both, the _\ba_\bd_\bd_\br parameter should be aligned to a multiple of |
| 17148 | the page size. If the _\bl_\be_\bn parameter is not a multiple of the page size, |
| 17149 | it will be rounded up to be so. The entire range must be allocated. |
| 17150 | |
| 17151 | After an m\bml\blo\boc\bck\bk() call, the indicated pages will cause neither a non- |
| 17152 | resident page nor address-translation fault until they are unlocked. |
| 17153 | They may still cause protection-violation faults or TLB-miss faults on |
| 17154 | architectures with software-managed TLBs. The physical pages remain in |
| 17155 | memory until all locked mappings for the pages are removed. Multiple |
| 17156 | processes may have the same physical pages locked via their own virtual |
| 17157 | address mappings. A single process may likewise have pages multiply |
| 17158 | locked via different virtual mappings of the same pages or via nested |
| 17159 | m\bml\blo\boc\bck\bk() calls on the same address range. Unlocking is performed |
| 17160 | explicitly by m\bmu\bun\bnl\blo\boc\bck\bk() or implicitly by a call to munmap(2) which |
| 17161 | deallocates the unmapped address range. Locked mappings are not |
| 17162 | inherited by the child process after a fork(2). |
| 17163 | |
| 17164 | Since physical memory is a potentially scarce resource, processes are |
| 17165 | limited in how much they can lock down. A single process can m\bml\blo\boc\bck\bk() the |
| 17166 | minimum of a system-wide ``wired pages'' limit and the per-process |
| 17167 | RLIMIT_MEMLOCK resource limit. |
| 17168 | |
| 17169 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17170 | The m\bml\blo\boc\bck\bk() and m\bmu\bun\bnl\blo\boc\bck\bk() functions return the value 0 if successful; |
| 17171 | otherwise the value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
| 17172 | to indicate the error. |
| 17173 | |
| 17174 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17175 | m\bml\blo\boc\bck\bk() will fail if: |
| 17176 | |
| 17177 | [EINVAL] The address given is not page aligned or the length is |
| 17178 | negative. |
| 17179 | |
| 17180 | [EAGAIN] Locking the indicated range would exceed either the |
| 17181 | system or per-process limit for locked memory. |
| 17182 | |
| 17183 | [ENOMEM] Some portion of the indicated address range is not |
| 17184 | allocated. There was an error faulting/mapping a |
| 17185 | page. |
| 17186 | |
| 17187 | m\bmu\bun\bnl\blo\boc\bck\bk() will fail if: |
| 17188 | |
| 17189 | [EINVAL] The address given is not page aligned or _\ba_\bd_\bd_\br and _\bs_\bi_\bz_\be |
| 17190 | specify a region that would extend beyond the end of |
| 17191 | the address space. |
| 17192 | |
| 17193 | [ENOMEM] Some portion of the indicated address range is not |
| 17194 | allocated. Some portion of the indicated address |
| 17195 | range is not locked. |
| 17196 | |
| 17197 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17198 | fork(2), mincore(2), minherit(2), mlockall(2), mmap(2), munmap(2), |
| 17199 | setrlimit(2), getpagesize(3) |
| 17200 | |
| 17201 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17202 | The m\bml\blo\boc\bck\bk() and m\bmu\bun\bnl\blo\boc\bck\bk() functions first appeared in 4.4BSD. |
| 17203 | |
| 17204 | B\bBU\bUG\bGS\bS |
| 17205 | Unlike Sun's implementation, multiple m\bml\blo\boc\bck\bk() calls on the same address |
| 17206 | range require the corresponding number of m\bmu\bun\bnl\blo\boc\bck\bk() calls to actually |
| 17207 | unlock the pages, i.e., m\bml\blo\boc\bck\bk() nests. This should be considered a |
| 17208 | consequence of the implementation and not a feature. |
| 17209 | |
| 17210 | The per-process resource limit is a limit on the amount of virtual memory |
| 17211 | locked, while the system-wide limit is for the number of locked physical |
| 17212 | pages. Hence a process with two distinct locked mappings of the same |
| 17213 | physical page counts as 2 pages against the per-process limit and as only |
| 17214 | a single page in the system limit. |
| 17215 | |
| 17216 | N\bNA\bAM\bME\bE |
| 17217 | m\bml\blo\boc\bck\bka\bal\bll\bl, m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl - lock (unlock) the address space of a process |
| 17218 | |
| 17219 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17220 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 17221 | |
| 17222 | _\bi_\bn_\bt |
| 17223 | m\bml\blo\boc\bck\bka\bal\bll\bl(_\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 17224 | |
| 17225 | _\bi_\bn_\bt |
| 17226 | m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl(_\bv_\bo_\bi_\bd); |
| 17227 | |
| 17228 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17229 | The m\bml\blo\boc\bck\bka\bal\bll\bl() system call locks into memory the physical pages |
| 17230 | associated with the address space of a process until the address space is |
| 17231 | unlocked, the process exits, or execs another program image. |
| 17232 | |
| 17233 | The following flags affect the behavior of m\bml\blo\boc\bck\bka\bal\bll\bl(): |
| 17234 | |
| 17235 | MCL_CURRENT Lock all pages currently mapped into the process's address |
| 17236 | space. |
| 17237 | |
| 17238 | MCL_FUTURE Lock all pages mapped into the process's address space in |
| 17239 | the future, at the time the mapping is established. Note |
| 17240 | that this may cause future mappings to fail if those |
| 17241 | mappings cause resource limits to be exceeded. |
| 17242 | |
| 17243 | Since physical memory is a potentially scarce resource, processes are |
| 17244 | limited in how much they can lock down. A single process can lock the |
| 17245 | minimum of a system-wide ``wired pages'' limit and the per-process |
| 17246 | RLIMIT_MEMLOCK resource limit. |
| 17247 | |
| 17248 | The m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() call unlocks any locked memory regions in the process |
| 17249 | address space. Any regions mapped after an m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() call will not be |
| 17250 | locked. |
| 17251 | |
| 17252 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17253 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions return the value 0 if |
| 17254 | successful; otherwise the value -1 is returned and the global variable |
| 17255 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 17256 | |
| 17257 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17258 | m\bml\blo\boc\bck\bka\bal\bll\bl() will fail if: |
| 17259 | |
| 17260 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs argument is zero or includes unimplemented |
| 17261 | flags. |
| 17262 | |
| 17263 | [ENOMEM] Locking all of the pages currently mapped would exceed |
| 17264 | either the system or per-process limit for locked |
| 17265 | memory. |
| 17266 | |
| 17267 | [EAGAIN] Some or all of the memory mapped into the process's |
| 17268 | address space could not be locked when the call was |
| 17269 | made. |
| 17270 | |
| 17271 | [EPERM] The calling process does not have the appropriate |
| 17272 | privileges to perform the requested operation. |
| 17273 | |
| 17274 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17275 | mincore(2), mlock(2), mmap(2), munmap(2), setrlimit(2) |
| 17276 | |
| 17277 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 17278 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions conform to IEEE Std 1003.1-2008 |
| 17279 | (``POSIX.1''). |
| 17280 | |
| 17281 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17282 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions first appeared in OpenBSD 2.9. |
| 17283 | |
| 17284 | B\bBU\bUG\bGS\bS |
| 17285 | The per-process resource limit is a limit on the amount of virtual memory |
| 17286 | locked, while the system-wide limit is for the number of locked physical |
| 17287 | pages. Hence a process with two distinct locked mappings of the same |
| 17288 | physical page counts as 2 pages against the per-process limit and only as |
| 17289 | a single page in the system limit. |
| 17290 | |
| 17291 | N\bNA\bAM\bME\bE |
| 17292 | m\bmm\bma\bap\bp - map files or devices into memory |
| 17293 | |
| 17294 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17295 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 17296 | |
| 17297 | _\bv_\bo_\bi_\bd _\b* |
| 17298 | m\bmm\bma\bap\bp(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bp_\br_\bo_\bt, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\bf_\bd, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 17299 | |
| 17300 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17301 | The m\bmm\bma\bap\bp() function causes the contents of _\bf_\bd, starting at _\bo_\bf_\bf_\bs_\be_\bt, to be |
| 17302 | mapped in memory at the given _\ba_\bd_\bd_\br. The mapping will extend at least _\bl_\be_\bn |
| 17303 | bytes, subject to page alignment restrictions. |
| 17304 | |
| 17305 | The _\ba_\bd_\bd_\br argument describes the address where the system should place the |
| 17306 | mapping. If the MAP_FIXED flag is specified, the allocation will happen |
| 17307 | at the specified address, replacing any previously established mappings |
| 17308 | in its range. Otherwise, the mapping will be placed at the available |
| 17309 | spot at _\ba_\bd_\bd_\br; failing that it will be placed "close by". If _\ba_\bd_\bd_\br is NULL |
| 17310 | the system can pick any address. Except for MAP_FIXED mappings, the |
| 17311 | system will never replace existing mappings. |
| 17312 | |
| 17313 | The _\bl_\be_\bn argument describes the minimum amount of bytes the mapping will |
| 17314 | span. Since m\bmm\bma\bap\bp() maps pages into memory, _\bl_\be_\bn may be rounded up to hit |
| 17315 | a page boundary. If _\bl_\be_\bn is 0, the mapping will fail with EINVAL. |
| 17316 | |
| 17317 | If an _\bf_\bd and _\bo_\bf_\bf_\bs_\be_\bt are specified, the resulting address may end up not |
| 17318 | on a page boundary, in order to align the page offset in the _\ba_\bd_\bd_\br to the |
| 17319 | page offset in _\bo_\bf_\bf_\bs_\be_\bt. |
| 17320 | |
| 17321 | The protections (region accessibility) are specified in the _\bp_\br_\bo_\bt |
| 17322 | argument. It should either be PROT_NONE (no permissions) or the bitwise |
| 17323 | OR of one or more of the following values: |
| 17324 | |
| 17325 | PROT_EXEC Pages may be executed. |
| 17326 | PROT_READ Pages may be read. |
| 17327 | PROT_WRITE Pages may be written. |
| 17328 | |
| 17329 | The _\bf_\bl_\ba_\bg_\bs parameter specifies the type of the mapped object, mapping |
| 17330 | options, and whether modifications made to the mapped copy of the page |
| 17331 | are private to the process or are to be shared with other references. |
| 17332 | Sharing, mapping type, and options are specified in the _\bf_\bl_\ba_\bg_\bs argument by |
| 17333 | OR'ing the following values. Exactly one of the first two values must be |
| 17334 | specified: |
| 17335 | |
| 17336 | MAP_PRIVATE Modifications are private. |
| 17337 | |
| 17338 | MAP_SHARED Modifications are shared. |
| 17339 | |
| 17340 | Any combination of the following flags may additionally be used: |
| 17341 | |
| 17342 | MAP_ANON Map anonymous memory not associated with any |
| 17343 | specific file. The file descriptor used for |
| 17344 | creating MAP_ANON must currently be -1 indicating no |
| 17345 | name is associated with the region. |
| 17346 | |
| 17347 | MAP_ANONYMOUS Synonym for MAP_ANON. |
| 17348 | |
| 17349 | MAP_FIXED Demand that the mapping is placed at _\ba_\bd_\bd_\br, rather |
| 17350 | than having the system select a location. _\ba_\bd_\bd_\br, _\bl_\be_\bn |
| 17351 | and _\bo_\bf_\bf_\bs_\be_\bt (in the case of _\bf_\bd mappings) must be |
| 17352 | multiples of the page size. Existing mappings in |
| 17353 | the address range will be replaced. Use of this |
| 17354 | option is discouraged. |
| 17355 | |
| 17356 | Finally, the following flags are also provided for source compatibility |
| 17357 | with code written for other operating systems, but are not recommended |
| 17358 | for use in new OpenBSD code: |
| 17359 | |
| 17360 | MAP_COPY Modifications are private and, unlike MAP_PRIVATE, |
| 17361 | modifications made by others are not visible. On |
| 17362 | OpenBSD this behaves just like MAP_PRIVATE. |
| 17363 | |
| 17364 | MAP_FILE Mapped from a regular file, character special file, |
| 17365 | or block special file specified by file descriptor |
| 17366 | _\bf_\bd. On OpenBSD and all systems conforming to IEEE |
| 17367 | Std 1003.1-2008 (``POSIX.1'') this is the default |
| 17368 | mapping type and need not be specified. |
| 17369 | |
| 17370 | MAP_HASSEMAPHORE |
| 17371 | Notify the kernel that the region may contain |
| 17372 | semaphores and that special handling may be |
| 17373 | necessary. On OpenBSD this flag is ignored. |
| 17374 | |
| 17375 | MAP_INHERIT Permit regions to be inherited across exec(3) system |
| 17376 | calls. On OpenBSD this flag is ignored. |
| 17377 | |
| 17378 | MAP_TRYFIXED Attempt to use the hint provided by _\ba_\bd_\bd_\br. On |
| 17379 | OpenBSD this is the default behavior. |
| 17380 | |
| 17381 | The close(2) function does not unmap pages; see munmap(2) for further |
| 17382 | information. |
| 17383 | |
| 17384 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17385 | The m\bmm\bma\bap\bp() function returns a pointer to the mapped region if successful; |
| 17386 | otherwise the value MAP_FAILED is returned and the global variable _\be_\br_\br_\bn_\bo |
| 17387 | is set to indicate the error. A successful return from m\bmm\bma\bap\bp() will never |
| 17388 | return the value MAP_FAILED. |
| 17389 | |
| 17390 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17391 | m\bmm\bma\bap\bp() will fail if: |
| 17392 | |
| 17393 | [EACCES] The flag PROT_READ was specified as part of the _\bp_\br_\bo_\bt |
| 17394 | parameter and _\bf_\bd was not open for reading. The flags |
| 17395 | MAP_SHARED and PROT_WRITE were specified as part of |
| 17396 | the _\bf_\bl_\ba_\bg_\bs and _\bp_\br_\bo_\bt parameters and _\bf_\bd was not open for |
| 17397 | writing. |
| 17398 | |
| 17399 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 17400 | |
| 17401 | [EINVAL] MAP_PRIVATE and MAP_SHARED were both specified. |
| 17402 | |
| 17403 | [EINVAL] MAP_FIXED was specified and the _\ba_\bd_\bd_\br parameter was not |
| 17404 | page aligned. |
| 17405 | |
| 17406 | [EINVAL] _\ba_\bd_\bd_\br and _\bl_\be_\bn specified a region that would extend |
| 17407 | beyond the end of the address space. |
| 17408 | |
| 17409 | [EINVAL] _\bf_\bd did not specify a regular, character special, or |
| 17410 | block special file. |
| 17411 | |
| 17412 | [EINVAL] The allocation _\bl_\be_\bn was 0. |
| 17413 | |
| 17414 | [ENOMEM] MAP_FIXED was specified and the _\ba_\bd_\bd_\br parameter wasn't |
| 17415 | available. MAP_ANON was specified and insufficient |
| 17416 | memory was available. |
| 17417 | |
| 17418 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17419 | madvise(2), mincore(2), mlock(2), mprotect(2), mquery(2), msync(2), |
| 17420 | munmap(2), getpagesize(3) |
| 17421 | |
| 17422 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 17423 | The m\bmm\bma\bap\bp() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 17424 | |
| 17425 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17426 | The m\bmm\bma\bap\bp() system call first appeared in 4.1cBSD. |
| 17427 | |
| 17428 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 17429 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that references to pages |
| 17430 | beyond the end of a mapped object shall generate a SIGBUS signal; |
| 17431 | however, OpenBSD generates a SIGSEGV signal in this case instead. |
| 17432 | |
| 17433 | Additionally, IEEE Std 1003.1-2008 (``POSIX.1'') specifies that m\bmm\bma\bap\bp() |
| 17434 | shall fail with EINVAL if neither MAP_PRIVATE nor MAP_SHARED is specified |
| 17435 | by _\bf_\bl_\ba_\bg_\bs; however, for compatibility with old programs, OpenBSD instead |
| 17436 | defaults to MAP_SHARED for mappings of character special files, and to |
| 17437 | MAP_PRIVATE for all other mappings. New programs should not rely on this |
| 17438 | behavior. |
| 17439 | |
| 17440 | B\bBU\bUG\bGS\bS |
| 17441 | Due to a limitation of the current vm system (see uvm(9)), mapping |
| 17442 | descriptors PROT_WRITE without also specifying PROT_READ is useless |
| 17443 | (results in a segmentation fault when first accessing the mapping). This |
| 17444 | means that such descriptors must be opened with O_RDWR, which requires |
| 17445 | both read and write permissions on the underlying object. |
| 17446 | |
| 17447 | N\bNA\bAM\bME\bE |
| 17448 | m\bmo\bou\bun\bnt\bt, u\bun\bnm\bmo\bou\bun\bnt\bt - mount or dismount a filesystem |
| 17449 | |
| 17450 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17451 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 17452 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
| 17453 | |
| 17454 | _\bi_\bn_\bt |
| 17455 | m\bmo\bou\bun\bnt\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\by_\bp_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bv_\bo_\bi_\bd _\b*_\bd_\ba_\bt_\ba); |
| 17456 | |
| 17457 | _\bi_\bn_\bt |
| 17458 | u\bun\bnm\bmo\bou\bun\bnt\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 17459 | |
| 17460 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17461 | The m\bmo\bou\bun\bnt\bt() function grafts a filesystem object onto the system file tree |
| 17462 | at the point _\bd_\bi_\br. The argument _\bd_\ba_\bt_\ba describes the filesystem object to |
| 17463 | be mounted. The argument _\bt_\by_\bp_\be tells the kernel how to interpret _\bd_\ba_\bt_\ba |
| 17464 | (see _\bt_\by_\bp_\be below). The contents of the filesystem become available |
| 17465 | through the new mount point _\bd_\bi_\br. Any files in _\bd_\bi_\br at the time of a |
| 17466 | successful mount are swept under the carpet, so to speak, and are |
| 17467 | unavailable until the filesystem is unmounted. |
| 17468 | |
| 17469 | The following _\bf_\bl_\ba_\bg_\bs may be specified to suppress default semantics which |
| 17470 | affect filesystem access. |
| 17471 | |
| 17472 | MNT_RDONLY The filesystem should be treated as read-only: even the |
| 17473 | superuser may not write to it. |
| 17474 | |
| 17475 | MNT_NOATIME Do not update the access time on files in the filesystem |
| 17476 | unless the modification or status change times are also |
| 17477 | being updated. |
| 17478 | |
| 17479 | MNT_NOEXEC Do not allow files to be executed from the filesystem. |
| 17480 | |
| 17481 | MNT_NOSUID Do not honor setuid or setgid bits on files when |
| 17482 | executing them. |
| 17483 | |
| 17484 | MNT_NODEV Do not interpret special files on the filesystem. |
| 17485 | |
| 17486 | MNT_SYNCHRONOUS All I/O to the filesystem should be done synchronously. |
| 17487 | |
| 17488 | MNT_ASYNC All I/O to the filesystem should be done asynchronously. |
| 17489 | |
| 17490 | MNT_SOFTDEP Use soft dependencies. Applies to FFS filesystems only |
| 17491 | (see 'softdep' in mount(8)). |
| 17492 | |
| 17493 | The flag MNT_UPDATE indicates that the mount command is being applied to |
| 17494 | an already mounted filesystem. This allows the mount flags to be changed |
| 17495 | without requiring that the filesystem be unmounted and remounted. Some |
| 17496 | filesystems may not allow all flags to be changed. For example, most |
| 17497 | filesystems will not allow a change from read-write to read-only. |
| 17498 | |
| 17499 | The _\bt_\by_\bp_\be argument defines the type of the filesystem. The types of |
| 17500 | filesystems known to the system are defined in <_\bs_\by_\bs_\b/_\bm_\bo_\bu_\bn_\bt_\b._\bh>. _\bd_\ba_\bt_\ba is a |
| 17501 | pointer to a structure that contains the type specific arguments to |
| 17502 | mount. The currently supported types of filesystems and their type |
| 17503 | specific data are: |
| 17504 | |
| 17505 | MOUNT_CD9660 |
| 17506 | struct iso_args { |
| 17507 | char *fspec; /* block special device to mount */ |
| 17508 | struct export_args export_info; |
| 17509 | /* network export info */ |
| 17510 | int flags; /* mounting flags, see below */ |
| 17511 | }; |
| 17512 | #define ISOFSMNT_NORRIP 0x00000001 /* disable Rock Ridge Ext.*/ |
| 17513 | #define ISOFSMNT_GENS 0x00000002 /* enable generation numbers */ |
| 17514 | #define ISOFSMNT_EXTATT 0x00000004 /* enable extended attributes */ |
| 17515 | #define ISOFSMNT_NOJOLIET 0x00000008 /* disable Joliet Ext.*/ |
| 17516 | #define ISOFSMNT_SESS 0x00000010 /* use iso_args.sess */ |
| 17517 | |
| 17518 | MOUNT_FFS |
| 17519 | struct ufs_args { |
| 17520 | char *fspec; /* block special file to mount */ |
| 17521 | struct export_args export_info; |
| 17522 | /* network export information */ |
| 17523 | }; |
| 17524 | |
| 17525 | MOUNT_MFS |
| 17526 | struct mfs_args { |
| 17527 | char *fspec; /* name to export for statfs */ |
| 17528 | struct export_args export_info; |
| 17529 | /* if we can export an MFS */ |
| 17530 | caddr_t base; /* base of filesystem in mem */ |
| 17531 | u_long size; /* size of filesystem */ |
| 17532 | }; |
| 17533 | |
| 17534 | MOUNT_MSDOS |
| 17535 | struct msdosfs_args { |
| 17536 | char *fspec; /* blocks special holding fs to mount */ |
| 17537 | struct export_args export_info; |
| 17538 | /* network export information */ |
| 17539 | uid_t uid; /* uid that owns msdosfs files */ |
| 17540 | gid_t gid; /* gid that owns msdosfs files */ |
| 17541 | mode_t mask; /* mask to be applied for msdosfs perms */ |
| 17542 | int flags; /* see below */ |
| 17543 | }; |
| 17544 | |
| 17545 | /* |
| 17546 | * Msdosfs mount options: |
| 17547 | */ |
| 17548 | #define MSDOSFSMNT_SHORTNAME 1 /* Force old DOS short names only */ |
| 17549 | #define MSDOSFSMNT_LONGNAME 2 /* Force Win'95 long names */ |
| 17550 | #define MSDOSFSMNT_NOWIN95 4 /* Completely ignore Win95 entries */ |
| 17551 | |
| 17552 | MOUNT_NFS |
| 17553 | struct nfs_args { |
| 17554 | int version; /* args structure version */ |
| 17555 | struct sockaddr *addr; /* file server address */ |
| 17556 | int addrlen; /* length of address */ |
| 17557 | int sotype; /* Socket type */ |
| 17558 | int proto; /* and Protocol */ |
| 17559 | u_char *fh; /* File handle to be mounted */ |
| 17560 | int fhsize; /* Size, in bytes, of fh */ |
| 17561 | int flags; /* flags */ |
| 17562 | int wsize; /* write size in bytes */ |
| 17563 | int rsize; /* read size in bytes */ |
| 17564 | int readdirsize; /* readdir size in bytes */ |
| 17565 | int timeo; /* initial timeout in .1 secs */ |
| 17566 | int retrans; /* times to retry send */ |
| 17567 | int maxgrouplist; /* Max. size of group list */ |
| 17568 | int readahead; /* # of blocks to readahead */ |
| 17569 | int leaseterm; /* Term (sec) of lease */ |
| 17570 | int deadthresh; /* Retrans threshold */ |
| 17571 | char *hostname; /* server's name */ |
| 17572 | int acregmin; /* Attr cache file recently modified */ |
| 17573 | int acregmax; /* ac file not recently modified */ |
| 17574 | int acdirmin; /* ac for dir recently modified */ |
| 17575 | int acdirmax; /* ac for dir not recently modified */ |
| 17576 | }; |
| 17577 | |
| 17578 | MOUNT_NTFS |
| 17579 | struct ntfs_args { |
| 17580 | char *fspec; /* block special device to mount */ |
| 17581 | struct export_args export_info; |
| 17582 | /* network export information */ |
| 17583 | uid_t uid; /* uid that owns ntfs files */ |
| 17584 | gid_t gid; /* gid that owns ntfs files */ |
| 17585 | mode_t mode; /* mask to be applied for ntfs perms */ |
| 17586 | u_long flag; /* additional flags */ |
| 17587 | }; |
| 17588 | |
| 17589 | /* |
| 17590 | * ntfs mount options: |
| 17591 | */ |
| 17592 | #define NTFS_MFLAG_CASEINS 0x00000001 |
| 17593 | #define NTFS_MFLAG_ALLNAMES 0x00000002 |
| 17594 | |
| 17595 | MOUNT_UDF |
| 17596 | struct udf_args { |
| 17597 | char *fspec; /* block special device to mount */ |
| 17598 | }; |
| 17599 | |
| 17600 | The u\bun\bnm\bmo\bou\bun\bnt\bt() function call disassociates the filesystem from the |
| 17601 | specified mount point _\bd_\bi_\br. |
| 17602 | |
| 17603 | The _\bf_\bl_\ba_\bg_\bs argument may specify MNT_FORCE to specify that the filesystem |
| 17604 | should be forcibly unmounted even if files are still active. Active |
| 17605 | special devices continue to work, but any further accesses to any other |
| 17606 | active files result in errors even if the filesystem is later remounted. |
| 17607 | |
| 17608 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17609 | Upon successful completion, the value 0 is returned; otherwise the |
| 17610 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 17611 | error. |
| 17612 | |
| 17613 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17614 | m\bmo\bou\bun\bnt\bt() will fail when one of the following occurs: |
| 17615 | |
| 17616 | [EPERM] The caller is not the superuser. |
| 17617 | |
| 17618 | [ENAMETOOLONG] The path name exceeded {MNAMELEN} characters. |
| 17619 | |
| 17620 | [ELOOP] Too many symbolic links were encountered in translating a |
| 17621 | pathname. |
| 17622 | |
| 17623 | [ENOENT] A component of _\bd_\bi_\br does not exist. |
| 17624 | |
| 17625 | [ENOTDIR] A component of _\bn_\ba_\bm_\be is not a directory, or a path prefix |
| 17626 | of _\bs_\bp_\be_\bc_\bi_\ba_\bl is not a directory. |
| 17627 | |
| 17628 | [EINVAL] An argument given was invalid. |
| 17629 | |
| 17630 | [EBUSY] Another process currently holds a reference to _\bd_\bi_\br. |
| 17631 | |
| 17632 | [EFAULT] _\bd_\bi_\br points outside the process's allocated address space. |
| 17633 | |
| 17634 | [EOPNOTSUPP] _\bt_\by_\bp_\be is not supported by the kernel. |
| 17635 | |
| 17636 | The following errors can occur for a ``ufs'' filesystem mount: |
| 17637 | |
| 17638 | [ENODEV] A component of ufs_args _\bf_\bs_\bp_\be_\bc does not exist. |
| 17639 | |
| 17640 | [ENOTBLK] _\bf_\bs_\bp_\be_\bc is not a block device. |
| 17641 | |
| 17642 | [ENXIO] The major device number of _\bf_\bs_\bp_\be_\bc is out of range (this |
| 17643 | indicates no device driver exists for the associated |
| 17644 | hardware). |
| 17645 | |
| 17646 | [EBUSY] _\bf_\bs_\bp_\be_\bc is already mounted. |
| 17647 | |
| 17648 | [EINVAL] The super block for the filesystem had a bad magic number, an |
| 17649 | out of range block size, or an invalid combination of flags. |
| 17650 | |
| 17651 | [ENOMEM] Not enough memory was available to read the cylinder group |
| 17652 | information for the filesystem. |
| 17653 | |
| 17654 | [EIO] An I/O error occurred while reading the super block or |
| 17655 | cylinder group information. |
| 17656 | |
| 17657 | [EFAULT] _\bf_\bs_\bp_\be_\bc points outside the process's allocated address space. |
| 17658 | |
| 17659 | [EROFS] The filesystem was not unmounted cleanly and MNT_FORCE was not |
| 17660 | specified. |
| 17661 | |
| 17662 | [EROFS] An attempt was made to mount a 4.2BSD filesystem without the |
| 17663 | MNT_RDONLY flag. |
| 17664 | |
| 17665 | The following errors can occur for an _\bN_\bF_\bS filesystem mount: |
| 17666 | |
| 17667 | [ETIMEDOUT] _\bN_\bF_\bS timed out trying to contact the server. |
| 17668 | |
| 17669 | [EFAULT] Some part of the information described by nfs_args points |
| 17670 | outside the process's allocated address space. |
| 17671 | |
| 17672 | The following errors can occur for a _\bm_\bf_\bs filesystem mount: |
| 17673 | |
| 17674 | [EMFILE] No space remains in the mount table. |
| 17675 | |
| 17676 | [EINVAL] The super block for the filesystem had a bad magic number or an |
| 17677 | out of range block size. |
| 17678 | |
| 17679 | [ENOMEM] Not enough memory was available to read the cylinder group |
| 17680 | information for the filesystem. |
| 17681 | |
| 17682 | [EIO] A paging error occurred while reading the super block or |
| 17683 | cylinder group information. |
| 17684 | |
| 17685 | [EFAULT] _\bN_\ba_\bm_\be points outside the process's allocated address space. |
| 17686 | |
| 17687 | u\bun\bnm\bmo\bou\bun\bnt\bt() may fail with one of the following errors: |
| 17688 | |
| 17689 | [EPERM] The caller is not the superuser. |
| 17690 | |
| 17691 | [ENOTDIR] A component of the path is not a directory. |
| 17692 | |
| 17693 | [EINVAL] An argument given was invalid. |
| 17694 | |
| 17695 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, |
| 17696 | or an entire pathname (including the terminating NUL) |
| 17697 | exceeded PATH_MAX bytes. |
| 17698 | |
| 17699 | [ELOOP] Too many symbolic links were encountered in translating |
| 17700 | the pathname. |
| 17701 | |
| 17702 | [EINVAL] The requested directory is not in the mount table. |
| 17703 | |
| 17704 | [EBUSY] A process is holding a reference to a file located on the |
| 17705 | filesystem. |
| 17706 | |
| 17707 | [EIO] An I/O error occurred while writing cached filesystem |
| 17708 | information. |
| 17709 | |
| 17710 | [EFAULT] _\bd_\bi_\br points outside the process's allocated address space. |
| 17711 | |
| 17712 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17713 | statfs(2), mfs(8), mount(8), umount(8) |
| 17714 | |
| 17715 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17716 | The m\bmo\bou\bun\bnt\bt() and u\bun\bnm\bmo\bou\bun\bnt\bt() system calls first appeared in Version 1 AT&T |
| 17717 | UNIX. The _\bf_\bl_\ba_\bg_\bs argument is supported by m\bmo\bou\bun\bnt\bt() since Version 5 AT&T |
| 17718 | UNIX and by u\bun\bnm\bmo\bou\bun\bnt\bt() since 4.3BSD-Reno. The current calling convention |
| 17719 | involving _\bt_\by_\bp_\be and _\bd_\ba_\bt_\ba arguments was introduced by 4.3BSD-Reno as well. |
| 17720 | |
| 17721 | B\bBU\bUG\bGS\bS |
| 17722 | Some of the error codes need translation to more obvious messages. |
| 17723 | |
| 17724 | N\bNA\bAM\bME\bE |
| 17725 | m\bmp\bpr\bro\bot\bte\bec\bct\bt - control the protection of pages |
| 17726 | |
| 17727 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17728 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 17729 | |
| 17730 | _\bi_\bn_\bt |
| 17731 | m\bmp\bpr\bro\bot\bte\bec\bct\bt(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bp_\br_\bo_\bt); |
| 17732 | |
| 17733 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17734 | The m\bmp\bpr\bro\bot\bte\bec\bct\bt() system call sets the access protections for the pages that |
| 17735 | contain the address range _\ba_\bd_\bd_\br through _\ba_\bd_\bd_\br + _\bl_\be_\bn - 1 (inclusive). If |
| 17736 | _\bl_\be_\bn is 0, no action is taken on the page that contains _\ba_\bd_\bd_\br. |
| 17737 | |
| 17738 | The protections (region accessibility) are specified in the _\bp_\br_\bo_\bt |
| 17739 | argument. It should either be PROT_NONE (no permissions) or the bitwise |
| 17740 | OR of one or more of the following values: |
| 17741 | |
| 17742 | PROT_EXEC Pages may be executed. |
| 17743 | PROT_READ Pages may be read. |
| 17744 | PROT_WRITE Pages may be written. |
| 17745 | |
| 17746 | Not all implementations will guarantee protection on a page basis; the |
| 17747 | granularity of protection changes may be as large as an entire region. |
| 17748 | Nor will all implementations guarantee to give exactly the requested |
| 17749 | permissions; more permissions may be granted than requested by _\bp_\br_\bo_\bt. |
| 17750 | However, if PROT_WRITE was not specified then the page will not be |
| 17751 | writable. |
| 17752 | |
| 17753 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17754 | Upon successful completion, the value 0 is returned; otherwise the |
| 17755 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 17756 | error. |
| 17757 | |
| 17758 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17759 | m\bmp\bpr\bro\bot\bte\bec\bct\bt() will fail if: |
| 17760 | |
| 17761 | [EACCES] The process does not have sufficient access to the |
| 17762 | underlying memory object to provide the requested |
| 17763 | protection. |
| 17764 | |
| 17765 | [ENOMEM] The process has locked future pages with |
| 17766 | m\bml\blo\boc\bck\bka\bal\bll\bl(_\bM_\bC_\bL_\b__\bF_\bU_\bT_\bU_\bR_\bE), a page being protected is not |
| 17767 | currently accessible, and making it accessible and |
| 17768 | locked would exceed process or system limits. |
| 17769 | |
| 17770 | [EINVAL] The _\bp_\br_\bo_\bt argument is invalid or the specified address |
| 17771 | range would wrap around. |
| 17772 | |
| 17773 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17774 | madvise(2), mincore(2), msync(2), munmap(2) |
| 17775 | |
| 17776 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 17777 | The m\bmp\bpr\bro\bot\bte\bec\bct\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 17778 | |
| 17779 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17780 | The m\bmp\bpr\bro\bot\bte\bec\bct\bt() function first appeared in 4.4BSD. |
| 17781 | |
| 17782 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 17783 | The OpenBSD implementation of m\bmp\bpr\bro\bot\bte\bec\bct\bt() does not require _\ba_\bd_\bd_\br to be |
| 17784 | page-aligned, although other implementations may. |
| 17785 | |
| 17786 | N\bNA\bAM\bME\bE |
| 17787 | m\bmq\bqu\bue\ber\bry\by - provide mapping hints to applications |
| 17788 | |
| 17789 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17790 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 17791 | |
| 17792 | _\bv_\bo_\bi_\bd _\b* |
| 17793 | m\bmq\bqu\bue\ber\bry\by(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bp_\br_\bo_\bt, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\bf_\bd, |
| 17794 | _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 17795 | |
| 17796 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17797 | The m\bmq\bqu\bue\ber\bry\by() system call checks the existing memory mappings of a process |
| 17798 | and returns hints to the caller about where to put a memory mapping. |
| 17799 | This hint can be later used when performing memory mappings with the |
| 17800 | mmap(2) system call with MAP_FIXED in the flags. The _\ba_\bd_\bd_\br argument |
| 17801 | should be a memory location that which the caller specifies the preferred |
| 17802 | address. The _\bs_\bi_\bz_\be argument specifies the requested size of the memory |
| 17803 | area the caller is looking for. The _\bf_\bd and _\bo_\bf_\bf arguments specify the |
| 17804 | file that will be mapped and the offset in it, this is the same as the |
| 17805 | corresponding arguments to mmap(2). |
| 17806 | |
| 17807 | The behavior of the function depends on the _\bf_\bl_\ba_\bg_\bs argument. If set to |
| 17808 | MAP_FIXED the pointer _\ba_\bd_\bd_\br is used as a fixed hint and m\bmq\bqu\bue\ber\bry\by() will |
| 17809 | return MAP_FAILED and set _\be_\br_\br_\bn_\bo to ENOMEM if there is not _\bs_\bi_\bz_\be bytes free |
| 17810 | after that address. Otherwise it will return the hint addr. If no flags |
| 17811 | are set m\bmq\bqu\bue\ber\bry\by() will use _\ba_\bd_\bd_\br as a starting point in memory and will |
| 17812 | search forward to find a memory area with _\bs_\bi_\bz_\be bytes free and that will |
| 17813 | be suitable for creating a mapping for the file and offset specified in |
| 17814 | the _\bf_\bd and _\bo_\bf_\bf arguments. When no such area can be found m\bmq\bqu\bue\ber\bry\by() will |
| 17815 | return and set _\be_\br_\br_\bn_\bo to indicate the error. |
| 17816 | |
| 17817 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17818 | When a memory range satisfying the request is found m\bmq\bqu\bue\ber\bry\by() returns the |
| 17819 | available address. Otherwise, MAP_FAILED is returned and _\be_\br_\br_\bn_\bo is set to |
| 17820 | indicate the error. |
| 17821 | |
| 17822 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17823 | m\bmq\bqu\bue\ber\bry\by() will fail if: |
| 17824 | |
| 17825 | [EINVAL] MAP_FIXED was specified and the requested memory area |
| 17826 | is unavailable. |
| 17827 | |
| 17828 | [ENOMEM] There was not enough memory left after the hint |
| 17829 | specified. |
| 17830 | |
| 17831 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 17832 | |
| 17833 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17834 | mmap(2) |
| 17835 | |
| 17836 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 17837 | The m\bmq\bqu\bue\ber\bry\by() function should not be used in portable applications. |
| 17838 | |
| 17839 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17840 | The m\bmq\bqu\bue\ber\bry\by() function first appeared in OpenBSD 3.4. |
| 17841 | |
| 17842 | N\bNA\bAM\bME\bE |
| 17843 | m\bms\bsg\bgc\bct\btl\bl - message control operations |
| 17844 | |
| 17845 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17846 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bms\bsg\bg.\b.h\bh>\b> |
| 17847 | |
| 17848 | _\bi_\bn_\bt |
| 17849 | m\bms\bsg\bgc\bct\btl\bl(_\bi_\bn_\bt _\bm_\bs_\bq_\bi_\bd, _\bi_\bn_\bt _\bc_\bm_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bq_\bi_\bd_\b__\bd_\bs _\b*_\bb_\bu_\bf); |
| 17850 | |
| 17851 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17852 | The m\bms\bsg\bgc\bct\btl\bl() system call performs some control operations on the message |
| 17853 | queue specified by _\bm_\bs_\bq_\bi_\bd. |
| 17854 | |
| 17855 | Each message queue has a data structure associated with it, parts of |
| 17856 | which may be altered by m\bms\bsg\bgc\bct\btl\bl() and parts of which determine the actions |
| 17857 | of m\bms\bsg\bgc\bct\btl\bl(). The data structure is defined in <_\bs_\by_\bs_\b/_\bm_\bs_\bg_\b._\bh> and contains |
| 17858 | (amongst others) the following members: |
| 17859 | |
| 17860 | struct msqid_ds { |
| 17861 | struct ipc_perm msg_perm; /* msg queue permission bits */ |
| 17862 | u_long msg_cbytes; /* # of bytes in use on the queue */ |
| 17863 | u_long msg_qnum; /* # of msgs in the queue */ |
| 17864 | u_long msg_qbytes; /* max # of bytes on the queue */ |
| 17865 | pid_t msg_lspid; /* pid of last msgsnd() */ |
| 17866 | pid_t msg_lrpid; /* pid of last msgrcv() */ |
| 17867 | time_t msg_stime; /* time of last msgsnd() */ |
| 17868 | time_t msg_rtime; /* time of last msgrcv() */ |
| 17869 | time_t msg_ctime; /* time of last msgctl() */ |
| 17870 | }; |
| 17871 | |
| 17872 | The _\bi_\bp_\bc_\b__\bp_\be_\br_\bm structure used inside the _\bm_\bs_\bq_\bi_\bd_\b__\bd_\bs structure is defined in |
| 17873 | <_\bs_\by_\bs_\b/_\bi_\bp_\bc_\b._\bh> and looks like this: |
| 17874 | |
| 17875 | struct ipc_perm { |
| 17876 | uid_t cuid; /* creator user id */ |
| 17877 | gid_t cgid; /* creator group id */ |
| 17878 | uid_t uid; /* user id */ |
| 17879 | gid_t gid; /* group id */ |
| 17880 | mode_t mode; /* permission (9 bits, see chmod(2)) */ |
| 17881 | u_short seq; /* sequence # (to generate unique id) */ |
| 17882 | key_t key; /* user specified msg/sem/shm key */ |
| 17883 | }; |
| 17884 | |
| 17885 | The operation to be performed by m\bms\bsg\bgc\bct\btl\bl() is specified in _\bc_\bm_\bd and is one |
| 17886 | of: |
| 17887 | |
| 17888 | IPC_STAT Gather information about the message queue and place it in the |
| 17889 | structure pointed to by _\bb_\bu_\bf. |
| 17890 | |
| 17891 | IPC_SET Set the value of the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd, _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd, _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be |
| 17892 | and _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs fields in the structure associated with _\bm_\bs_\bq_\bi_\bd. |
| 17893 | The values are taken from the corresponding fields in the |
| 17894 | structure pointed to by _\bb_\bu_\bf. This operation can only be |
| 17895 | executed by the superuser, or a process that has an effective |
| 17896 | user ID equal to either _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd in the |
| 17897 | data structure associated with the message queue. The value |
| 17898 | of _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs can only be increased by the superuser. Values |
| 17899 | for _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs that exceed the system limit (MSGMNB from |
| 17900 | <_\bs_\by_\bs_\b/_\bm_\bs_\bg_\b._\bh>) are silently truncated to that limit. |
| 17901 | |
| 17902 | IPC_RMID Remove the message queue specified by _\bm_\bs_\bq_\bi_\bd and destroy the |
| 17903 | data associated with it. Only the superuser or a process with |
| 17904 | an effective UID equal to the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd |
| 17905 | values in the data structure associated with the queue can do |
| 17906 | this. |
| 17907 | |
| 17908 | The permission to read from or write to a message queue (see msgsnd(2) |
| 17909 | and msgrcv(2)) is determined by the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be field in the same way |
| 17910 | as is done with files (see chmod(2)), but the effective UID can match |
| 17911 | either the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd field or the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd field, and the |
| 17912 | effective GID can match either _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd or _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd. |
| 17913 | |
| 17914 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17915 | Upon successful completion, the value 0 is returned; otherwise the |
| 17916 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 17917 | error. |
| 17918 | |
| 17919 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17920 | m\bms\bsg\bgc\bct\btl\bl() will fail if: |
| 17921 | |
| 17922 | [EPERM] _\bc_\bm_\bd is equal to IPC_SET or IPC_RMID and the caller is |
| 17923 | not the superuser, nor does the effective UID match |
| 17924 | either the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd or _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd fields of the |
| 17925 | data structure associated with the message queue. |
| 17926 | |
| 17927 | An attempt is made to increase the value of _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs |
| 17928 | through IPC_SET but the caller is not the superuser. |
| 17929 | |
| 17930 | [EACCES] The command is IPC_STAT and the caller has no read |
| 17931 | permission for this message queue. |
| 17932 | |
| 17933 | [EINVAL] _\bm_\bs_\bq_\bi_\bd is not a valid message queue identifier. |
| 17934 | |
| 17935 | _\bc_\bm_\bd is not a valid command. |
| 17936 | |
| 17937 | [EFAULT] _\bb_\bu_\bf specifies an invalid address. |
| 17938 | |
| 17939 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 17940 | msgget(2), msgrcv(2), msgsnd(2) |
| 17941 | |
| 17942 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 17943 | Message queues appeared in AT&T System V Release 1 UNIX. |
| 17944 | |
| 17945 | N\bNA\bAM\bME\bE |
| 17946 | m\bms\bsg\bgg\bge\bet\bt - get message queue |
| 17947 | |
| 17948 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 17949 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bms\bsg\bg.\b.h\bh>\b> |
| 17950 | |
| 17951 | _\bi_\bn_\bt |
| 17952 | m\bms\bsg\bgg\bge\bet\bt(_\bk_\be_\by_\b__\bt _\bk_\be_\by, _\bi_\bn_\bt _\bm_\bs_\bg_\bf_\bl_\bg); |
| 17953 | |
| 17954 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 17955 | m\bms\bsg\bgg\bge\bet\bt() returns the message queue identifier associated with _\bk_\be_\by. A |
| 17956 | message queue identifier is a unique integer greater than zero. |
| 17957 | |
| 17958 | A message queue is created if either _\bk_\be_\by is equal to IPC_PRIVATE, or _\bk_\be_\by |
| 17959 | does not have a message queue identifier associated with it, and the |
| 17960 | IPC_CREAT bit is set in _\bm_\bs_\bg_\bf_\bl_\bg. |
| 17961 | |
| 17962 | If a new message queue is created, the data structure associated with it |
| 17963 | (the _\bm_\bs_\bq_\bi_\bd_\b__\bd_\bs structure, see msgctl(2)) is initialized as follows: |
| 17964 | |
| 17965 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd and _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd are set to the effective UID of the |
| 17966 | calling process. |
| 17967 | |
| 17968 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd are set to the effective GID of the |
| 17969 | calling process. |
| 17970 | |
| 17971 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be is set to the lower 9 bits of _\bm_\bs_\bg_\bf_\bl_\bg. |
| 17972 | |
| 17973 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bc_\bb_\by_\bt_\be_\bs, _\bm_\bs_\bg_\b__\bq_\bn_\bu_\bm, _\bm_\bs_\bg_\b__\bl_\bs_\bp_\bi_\bd, _\bm_\bs_\bg_\b__\bl_\br_\bp_\bi_\bd, _\bm_\bs_\bg_\b__\br_\bt_\bi_\bm_\be, and _\bm_\bs_\bg_\b__\bs_\bt_\bi_\bm_\be |
| 17974 | are set to 0. |
| 17975 | |
| 17976 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs is set to the system wide maximum value for the number of |
| 17977 | bytes in a queue (MSGMNB). |
| 17978 | |
| 17979 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bc_\bt_\bi_\bm_\be is set to the current time. |
| 17980 | |
| 17981 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 17982 | Upon successful completion a positive message queue identifier is |
| 17983 | returned. Otherwise, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
| 17984 | to indicate the error. |
| 17985 | |
| 17986 | E\bER\bRR\bRO\bOR\bRS\bS |
| 17987 | [EACCES] A message queue is already associated with _\bk_\be_\by and the |
| 17988 | caller has no permission to access it. |
| 17989 | |
| 17990 | [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _\bm_\bs_\bg_\bf_\bl_\bg, and a |
| 17991 | message queue is already associated with _\bk_\be_\by. |
| 17992 | |
| 17993 | [ENOSPC] A new message queue could not be created because the |
| 17994 | system limit for the number of message queues has been |
| 17995 | reached. |
| 17996 | |
| 17997 | [ENOENT] IPC_CREAT was not set in _\bm_\bs_\bg_\bf_\bl_\bg and no message queue |
| 17998 | associated with _\bk_\be_\by was found. |
| 17999 | |
| 18000 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18001 | msgctl(2), msgrcv(2), msgsnd(2), ftok(3) |
| 18002 | |
| 18003 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18004 | Message queues appeared in AT&T System V Release 1 UNIX. |
| 18005 | |
| 18006 | N\bNA\bAM\bME\bE |
| 18007 | m\bms\bsg\bgr\brc\bcv\bv - receive a message from a message queue |
| 18008 | |
| 18009 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18010 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bms\bsg\bg.\b.h\bh>\b> |
| 18011 | |
| 18012 | _\bi_\bn_\bt |
| 18013 | m\bms\bsg\bgr\brc\bcv\bv(_\bi_\bn_\bt _\bm_\bs_\bq_\bi_\bd, _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg_\bp, _\bs_\bi_\bz_\be_\b__\bt _\bm_\bs_\bg_\bs_\bz, _\bl_\bo_\bn_\bg _\bm_\bs_\bg_\bt_\by_\bp, _\bi_\bn_\bt _\bm_\bs_\bg_\bf_\bl_\bg); |
| 18014 | |
| 18015 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18016 | The m\bms\bsg\bgr\brc\bcv\bv() function receives a message from the message queue specified |
| 18017 | in _\bm_\bs_\bq_\bi_\bd, and places it into the structure pointed to by _\bm_\bs_\bg_\bp. This |
| 18018 | structure should consist of the following members: |
| 18019 | |
| 18020 | long mtype; /* message type */ |
| 18021 | char mtext[1]; /* body of message */ |
| 18022 | |
| 18023 | _\bm_\bt_\by_\bp_\be is an integer greater than 0 that can be used for selecting |
| 18024 | messages, _\bm_\bt_\be_\bx_\bt is an array of bytes, with a size up to that of the |
| 18025 | system limit (MSGMAX). |
| 18026 | |
| 18027 | The value of _\bm_\bs_\bg_\bt_\by_\bp has one of the following meanings: |
| 18028 | |
| 18029 | +\b+\bo\bo _\bm_\bs_\bg_\bt_\by_\bp is greater than 0. The first message of type _\bm_\bs_\bg_\bt_\by_\bp will be |
| 18030 | received. |
| 18031 | |
| 18032 | +\b+\bo\bo _\bm_\bs_\bg_\bt_\by_\bp is equal to 0. The first message on the queue will be |
| 18033 | received. |
| 18034 | |
| 18035 | +\b+\bo\bo _\bm_\bs_\bg_\bt_\by_\bp is less than 0. The first message of the lowest message type |
| 18036 | that is less than or equal to the absolute value of _\bm_\bs_\bg_\bt_\by_\bp will be |
| 18037 | received. |
| 18038 | |
| 18039 | _\bm_\bs_\bg_\bs_\bz specifies the maximum length of the requested message. If the |
| 18040 | received message has a length greater than _\bm_\bs_\bg_\bs_\bz it will be silently |
| 18041 | truncated if the MSG_NOERROR flag is set in _\bm_\bs_\bg_\bf_\bl_\bg, otherwise an error |
| 18042 | will be returned. |
| 18043 | |
| 18044 | If no matching message is present on the message queue specified by |
| 18045 | _\bm_\bs_\bq_\bi_\bd, the behavior of m\bms\bsg\bgr\brc\bcv\bv() depends on whether the IPC_NOWAIT flag is |
| 18046 | set in _\bm_\bs_\bg_\bf_\bl_\bg or not. If IPC_NOWAIT is set, m\bms\bsg\bgr\brc\bcv\bv() will immediately |
| 18047 | return a value of -1, and set _\be_\br_\br_\bn_\bo to EAGAIN. If IPC_NOWAIT is not set, |
| 18048 | the calling process will be blocked until: |
| 18049 | |
| 18050 | +\b+\bo\bo A message of the requested type becomes available on the message |
| 18051 | queue. |
| 18052 | |
| 18053 | +\b+\bo\bo The message queue is removed, in which case -1 will be returned, and |
| 18054 | _\be_\br_\br_\bn_\bo set to EINVAL. |
| 18055 | |
| 18056 | +\b+\bo\bo A signal is received and caught. -1 is returned, and _\be_\br_\br_\bn_\bo set to |
| 18057 | EINTR. |
| 18058 | |
| 18059 | If a message is successfully received, the data structure associated with |
| 18060 | _\bm_\bs_\bq_\bi_\bd is updated as follows: |
| 18061 | |
| 18062 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bc_\bb_\by_\bt_\be_\bs is decremented by the size of the message. |
| 18063 | |
| 18064 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bl_\br_\bp_\bi_\bd is set to the pid of the caller. |
| 18065 | |
| 18066 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bl_\br_\bt_\bi_\bm_\be is set to the current time. |
| 18067 | |
| 18068 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bq_\bn_\bu_\bm is decremented by 1. |
| 18069 | |
| 18070 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18071 | Upon successful completion, m\bms\bsg\bgr\brc\bcv\bv() returns the number of bytes received |
| 18072 | into the _\bm_\bt_\be_\bx_\bt field of the structure pointed to by _\bm_\bs_\bg_\bp. Otherwise, -1 |
| 18073 | is returned, and _\be_\br_\br_\bn_\bo set to indicate the error. |
| 18074 | |
| 18075 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18076 | m\bms\bsg\bgr\brc\bcv\bv() will fail if: |
| 18077 | |
| 18078 | [EINVAL] _\bm_\bs_\bq_\bi_\bd is not a valid message queue identifier. |
| 18079 | |
| 18080 | _\bm_\bs_\bg_\bs_\bz is less than 0. |
| 18081 | |
| 18082 | [E2BIG] A matching message was received, but its size was |
| 18083 | greater than _\bm_\bs_\bg_\bs_\bz and the MSG_NOERROR flag was not |
| 18084 | set in _\bm_\bs_\bg_\bf_\bl_\bg. |
| 18085 | |
| 18086 | [EACCES] The calling process does not have read access to the |
| 18087 | message queue. |
| 18088 | |
| 18089 | [EFAULT] _\bm_\bs_\bg_\bp points to an invalid address. |
| 18090 | |
| 18091 | [EINTR] The system call was interrupted by the delivery of a |
| 18092 | signal. |
| 18093 | |
| 18094 | [ENOMSG] There is no message of the requested type available on |
| 18095 | the message queue, and IPC_NOWAIT is set in _\bm_\bs_\bg_\bf_\bl_\bg. |
| 18096 | |
| 18097 | [EIDRM] The message queue was removed while m\bms\bsg\bgr\brc\bcv\bv() was |
| 18098 | waiting for a message of the requested type to become |
| 18099 | available on it. |
| 18100 | |
| 18101 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18102 | msgctl(2), msgget(2), msgsnd(2) |
| 18103 | |
| 18104 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18105 | Message queues appeared in AT&T System V Release 1 UNIX. |
| 18106 | |
| 18107 | N\bNA\bAM\bME\bE |
| 18108 | m\bms\bsg\bgs\bsn\bnd\bd - send a message to a message queue |
| 18109 | |
| 18110 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18111 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bms\bsg\bg.\b.h\bh>\b> |
| 18112 | |
| 18113 | _\bi_\bn_\bt |
| 18114 | m\bms\bsg\bgs\bsn\bnd\bd(_\bi_\bn_\bt _\bm_\bs_\bq_\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg_\bp, _\bs_\bi_\bz_\be_\b__\bt _\bm_\bs_\bg_\bs_\bz, _\bi_\bn_\bt _\bm_\bs_\bg_\bf_\bl_\bg); |
| 18115 | |
| 18116 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18117 | The m\bms\bsg\bgs\bsn\bnd\bd() function sends a message to the message queue specified by |
| 18118 | _\bm_\bs_\bq_\bi_\bd. _\bm_\bs_\bg_\bp points to a structure containing the message. This |
| 18119 | structure should consist of the following members: |
| 18120 | |
| 18121 | long mtype; /* message type */ |
| 18122 | char mtext[1]; /* body of message */ |
| 18123 | |
| 18124 | _\bm_\bt_\by_\bp_\be is an integer greater than 0 that can be used for selecting |
| 18125 | messages (see msgrcv(2)); _\bm_\bt_\be_\bx_\bt is an array of _\bm_\bs_\bg_\bs_\bz bytes, with a size |
| 18126 | between 0 and that of the system limit (MSGMAX). |
| 18127 | |
| 18128 | If the number of bytes already on the message queue plus _\bm_\bs_\bg_\bs_\bz is bigger |
| 18129 | than the maximum number of bytes on the message queue (_\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs, |
| 18130 | see msgctl(2)), or the number of messages on all queues system-wide is |
| 18131 | already equal to the system limit, _\bm_\bs_\bg_\bf_\bl_\bg determines the action of |
| 18132 | m\bms\bsg\bgs\bsn\bnd\bd(). If _\bm_\bs_\bg_\bf_\bl_\bg has IPC_NOWAIT mask set in it, the call will return |
| 18133 | immediately. If _\bm_\bs_\bg_\bf_\bl_\bg does not have IPC_NOWAIT set in it, the call will |
| 18134 | block until: |
| 18135 | |
| 18136 | +\b+\bo\bo The condition which caused the call to block does no longer exist. |
| 18137 | The message will be sent. |
| 18138 | |
| 18139 | +\b+\bo\bo The message queue is removed, in which case -1 will be returned, and |
| 18140 | _\be_\br_\br_\bn_\bo is set to EINVAL. |
| 18141 | |
| 18142 | +\b+\bo\bo The caller catches a signal. The call returns with _\be_\br_\br_\bn_\bo set to |
| 18143 | EINTR. |
| 18144 | |
| 18145 | After a successful call, the data structure associated with the message |
| 18146 | queue is updated in the following way: |
| 18147 | |
| 18148 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bc_\bb_\by_\bt_\be_\bs is incremented by the size of the message. |
| 18149 | |
| 18150 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bq_\bn_\bu_\bm is incremented by 1. |
| 18151 | |
| 18152 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bl_\bs_\bp_\bi_\bd is set to the pid of the calling process. |
| 18153 | |
| 18154 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bs_\bt_\bi_\bm_\be is set to the current time. |
| 18155 | |
| 18156 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18157 | Upon successful completion, the value 0 is returned; otherwise the |
| 18158 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 18159 | error. |
| 18160 | |
| 18161 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18162 | m\bms\bsg\bgs\bsn\bnd\bd() will fail if: |
| 18163 | |
| 18164 | [EINVAL] _\bm_\bs_\bq_\bi_\bd is not a valid message queue identifier. |
| 18165 | |
| 18166 | _\bm_\bs_\bg_\bs_\bz is greater than _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs. |
| 18167 | |
| 18168 | [EACCES] The calling process does not have write access to the |
| 18169 | message queue. |
| 18170 | |
| 18171 | [EAGAIN] There was no space for this message either on the |
| 18172 | queue, or in the whole system, and IPC_NOWAIT was set |
| 18173 | in _\bm_\bs_\bg_\bf_\bl_\bg. |
| 18174 | |
| 18175 | [EFAULT] _\bm_\bs_\bg_\bp points to an invalid address. |
| 18176 | |
| 18177 | [EINTR] The system call was interrupted by the delivery of a |
| 18178 | signal. |
| 18179 | |
| 18180 | [EIDRM] The message queue was removed while m\bms\bsg\bgs\bsn\bnd\bd() was |
| 18181 | waiting for a resource to become available in order to |
| 18182 | deliver the message. |
| 18183 | |
| 18184 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18185 | msgctl(2), msgget(2), msgrcv(2) |
| 18186 | |
| 18187 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18188 | Message queues appeared in AT&T System V Release 1 UNIX. |
| 18189 | |
| 18190 | N\bNA\bAM\bME\bE |
| 18191 | m\bms\bsy\byn\bnc\bc - synchronize a mapped region |
| 18192 | |
| 18193 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18194 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 18195 | |
| 18196 | _\bi_\bn_\bt |
| 18197 | m\bms\bsy\byn\bnc\bc(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 18198 | |
| 18199 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18200 | The m\bms\bsy\byn\bnc\bc() system call writes all pages with shared modifications in the |
| 18201 | specified region of the process's address space back to permanent |
| 18202 | storage, and, if requested, invalidates cached data mapped in the region. |
| 18203 | If _\bl_\be_\bn is 0, all modified pages within the region containing _\ba_\bd_\bd_\br will be |
| 18204 | flushed; if _\bl_\be_\bn is non-zero, only modified pages containing _\ba_\bd_\bd_\br and |
| 18205 | _\bl_\be_\bn_\b-_\b1 succeeding locations will be flushed. Any required synchronization |
| 18206 | of memory caches will also take place at this time. Filesystem |
| 18207 | operations on a file that is mapped for shared modifications are |
| 18208 | unpredictable except after an m\bms\bsy\byn\bnc\bc(). |
| 18209 | |
| 18210 | The _\bf_\bl_\ba_\bg_\bs argument is the bitwise OR of zero or more of the following |
| 18211 | values: |
| 18212 | |
| 18213 | MS_ASYNC Perform asynchronous writes. |
| 18214 | MS_SYNC Perform synchronous writes. |
| 18215 | MS_INVALIDATE Invalidate cached data after writing. |
| 18216 | |
| 18217 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18218 | Upon successful completion, the value 0 is returned; otherwise the |
| 18219 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 18220 | error. |
| 18221 | |
| 18222 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18223 | The following errors may be reported: |
| 18224 | |
| 18225 | [EBUSY] The MS_INVALIDATE flag was specified and a portion of |
| 18226 | the specified region was locked with mlock(2). |
| 18227 | |
| 18228 | [EINVAL] The specified _\bf_\bl_\ba_\bg_\bs argument was invalid. |
| 18229 | |
| 18230 | [EINVAL] The _\ba_\bd_\bd_\br parameter was not page aligned or _\ba_\bd_\bd_\br and |
| 18231 | _\bs_\bi_\bz_\be specify a region that would extend beyond the end |
| 18232 | of the address space. |
| 18233 | |
| 18234 | [ENOMEM] Addresses in the specified region are outside the |
| 18235 | range allowed for the address space of the process, or |
| 18236 | specify one or more pages which are unmapped. |
| 18237 | |
| 18238 | [EIO] An I/O error occurred while writing. |
| 18239 | |
| 18240 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18241 | madvise(2), mincore(2), minherit(2), mprotect(2), munmap(2) |
| 18242 | |
| 18243 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18244 | The m\bms\bsy\byn\bnc\bc() function first appeared in 4.4BSD. It was modified to |
| 18245 | conform to IEEE Std 1003.1b-1993 (``POSIX.1b'') |
| 18246 | |
| 18247 | B\bBU\bUG\bGS\bS |
| 18248 | Writes are currently done synchronously even if the MS_ASYNC flag is |
| 18249 | specified. |
| 18250 | |
| 18251 | N\bNA\bAM\bME\bE |
| 18252 | m\bml\blo\boc\bck\bk, m\bmu\bun\bnl\blo\boc\bck\bk - lock (unlock) physical pages in memory |
| 18253 | |
| 18254 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18255 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 18256 | |
| 18257 | _\bi_\bn_\bt |
| 18258 | m\bml\blo\boc\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
| 18259 | |
| 18260 | _\bi_\bn_\bt |
| 18261 | m\bmu\bun\bnl\blo\boc\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
| 18262 | |
| 18263 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18264 | The m\bml\blo\boc\bck\bk() system call locks into memory the physical pages associated |
| 18265 | with the virtual address range starting at _\ba_\bd_\bd_\br for _\bl_\be_\bn bytes. The |
| 18266 | m\bmu\bun\bnl\blo\boc\bck\bk() call unlocks pages previously locked by one or more m\bml\blo\boc\bck\bk() |
| 18267 | calls. For both, the _\ba_\bd_\bd_\br parameter should be aligned to a multiple of |
| 18268 | the page size. If the _\bl_\be_\bn parameter is not a multiple of the page size, |
| 18269 | it will be rounded up to be so. The entire range must be allocated. |
| 18270 | |
| 18271 | After an m\bml\blo\boc\bck\bk() call, the indicated pages will cause neither a non- |
| 18272 | resident page nor address-translation fault until they are unlocked. |
| 18273 | They may still cause protection-violation faults or TLB-miss faults on |
| 18274 | architectures with software-managed TLBs. The physical pages remain in |
| 18275 | memory until all locked mappings for the pages are removed. Multiple |
| 18276 | processes may have the same physical pages locked via their own virtual |
| 18277 | address mappings. A single process may likewise have pages multiply |
| 18278 | locked via different virtual mappings of the same pages or via nested |
| 18279 | m\bml\blo\boc\bck\bk() calls on the same address range. Unlocking is performed |
| 18280 | explicitly by m\bmu\bun\bnl\blo\boc\bck\bk() or implicitly by a call to munmap(2) which |
| 18281 | deallocates the unmapped address range. Locked mappings are not |
| 18282 | inherited by the child process after a fork(2). |
| 18283 | |
| 18284 | Since physical memory is a potentially scarce resource, processes are |
| 18285 | limited in how much they can lock down. A single process can m\bml\blo\boc\bck\bk() the |
| 18286 | minimum of a system-wide ``wired pages'' limit and the per-process |
| 18287 | RLIMIT_MEMLOCK resource limit. |
| 18288 | |
| 18289 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18290 | The m\bml\blo\boc\bck\bk() and m\bmu\bun\bnl\blo\boc\bck\bk() functions return the value 0 if successful; |
| 18291 | otherwise the value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
| 18292 | to indicate the error. |
| 18293 | |
| 18294 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18295 | m\bml\blo\boc\bck\bk() will fail if: |
| 18296 | |
| 18297 | [EINVAL] The address given is not page aligned or the length is |
| 18298 | negative. |
| 18299 | |
| 18300 | [EAGAIN] Locking the indicated range would exceed either the |
| 18301 | system or per-process limit for locked memory. |
| 18302 | |
| 18303 | [ENOMEM] Some portion of the indicated address range is not |
| 18304 | allocated. There was an error faulting/mapping a |
| 18305 | page. |
| 18306 | |
| 18307 | m\bmu\bun\bnl\blo\boc\bck\bk() will fail if: |
| 18308 | |
| 18309 | [EINVAL] The address given is not page aligned or _\ba_\bd_\bd_\br and _\bs_\bi_\bz_\be |
| 18310 | specify a region that would extend beyond the end of |
| 18311 | the address space. |
| 18312 | |
| 18313 | [ENOMEM] Some portion of the indicated address range is not |
| 18314 | allocated. Some portion of the indicated address |
| 18315 | range is not locked. |
| 18316 | |
| 18317 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18318 | fork(2), mincore(2), minherit(2), mlockall(2), mmap(2), munmap(2), |
| 18319 | setrlimit(2), getpagesize(3) |
| 18320 | |
| 18321 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18322 | The m\bml\blo\boc\bck\bk() and m\bmu\bun\bnl\blo\boc\bck\bk() functions first appeared in 4.4BSD. |
| 18323 | |
| 18324 | B\bBU\bUG\bGS\bS |
| 18325 | Unlike Sun's implementation, multiple m\bml\blo\boc\bck\bk() calls on the same address |
| 18326 | range require the corresponding number of m\bmu\bun\bnl\blo\boc\bck\bk() calls to actually |
| 18327 | unlock the pages, i.e., m\bml\blo\boc\bck\bk() nests. This should be considered a |
| 18328 | consequence of the implementation and not a feature. |
| 18329 | |
| 18330 | The per-process resource limit is a limit on the amount of virtual memory |
| 18331 | locked, while the system-wide limit is for the number of locked physical |
| 18332 | pages. Hence a process with two distinct locked mappings of the same |
| 18333 | physical page counts as 2 pages against the per-process limit and as only |
| 18334 | a single page in the system limit. |
| 18335 | |
| 18336 | N\bNA\bAM\bME\bE |
| 18337 | m\bml\blo\boc\bck\bka\bal\bll\bl, m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl - lock (unlock) the address space of a process |
| 18338 | |
| 18339 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18340 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 18341 | |
| 18342 | _\bi_\bn_\bt |
| 18343 | m\bml\blo\boc\bck\bka\bal\bll\bl(_\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 18344 | |
| 18345 | _\bi_\bn_\bt |
| 18346 | m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl(_\bv_\bo_\bi_\bd); |
| 18347 | |
| 18348 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18349 | The m\bml\blo\boc\bck\bka\bal\bll\bl() system call locks into memory the physical pages |
| 18350 | associated with the address space of a process until the address space is |
| 18351 | unlocked, the process exits, or execs another program image. |
| 18352 | |
| 18353 | The following flags affect the behavior of m\bml\blo\boc\bck\bka\bal\bll\bl(): |
| 18354 | |
| 18355 | MCL_CURRENT Lock all pages currently mapped into the process's address |
| 18356 | space. |
| 18357 | |
| 18358 | MCL_FUTURE Lock all pages mapped into the process's address space in |
| 18359 | the future, at the time the mapping is established. Note |
| 18360 | that this may cause future mappings to fail if those |
| 18361 | mappings cause resource limits to be exceeded. |
| 18362 | |
| 18363 | Since physical memory is a potentially scarce resource, processes are |
| 18364 | limited in how much they can lock down. A single process can lock the |
| 18365 | minimum of a system-wide ``wired pages'' limit and the per-process |
| 18366 | RLIMIT_MEMLOCK resource limit. |
| 18367 | |
| 18368 | The m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() call unlocks any locked memory regions in the process |
| 18369 | address space. Any regions mapped after an m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() call will not be |
| 18370 | locked. |
| 18371 | |
| 18372 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18373 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions return the value 0 if |
| 18374 | successful; otherwise the value -1 is returned and the global variable |
| 18375 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 18376 | |
| 18377 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18378 | m\bml\blo\boc\bck\bka\bal\bll\bl() will fail if: |
| 18379 | |
| 18380 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs argument is zero or includes unimplemented |
| 18381 | flags. |
| 18382 | |
| 18383 | [ENOMEM] Locking all of the pages currently mapped would exceed |
| 18384 | either the system or per-process limit for locked |
| 18385 | memory. |
| 18386 | |
| 18387 | [EAGAIN] Some or all of the memory mapped into the process's |
| 18388 | address space could not be locked when the call was |
| 18389 | made. |
| 18390 | |
| 18391 | [EPERM] The calling process does not have the appropriate |
| 18392 | privileges to perform the requested operation. |
| 18393 | |
| 18394 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18395 | mincore(2), mlock(2), mmap(2), munmap(2), setrlimit(2) |
| 18396 | |
| 18397 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 18398 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions conform to IEEE Std 1003.1-2008 |
| 18399 | (``POSIX.1''). |
| 18400 | |
| 18401 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18402 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions first appeared in OpenBSD 2.9. |
| 18403 | |
| 18404 | B\bBU\bUG\bGS\bS |
| 18405 | The per-process resource limit is a limit on the amount of virtual memory |
| 18406 | locked, while the system-wide limit is for the number of locked physical |
| 18407 | pages. Hence a process with two distinct locked mappings of the same |
| 18408 | physical page counts as 2 pages against the per-process limit and only as |
| 18409 | a single page in the system limit. |
| 18410 | |
| 18411 | N\bNA\bAM\bME\bE |
| 18412 | m\bmu\bun\bnm\bma\bap\bp - remove a mapping |
| 18413 | |
| 18414 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18415 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 18416 | |
| 18417 | _\bi_\bn_\bt |
| 18418 | m\bmu\bun\bnm\bma\bap\bp(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
| 18419 | |
| 18420 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18421 | The m\bmu\bun\bnm\bma\bap\bp() system call deletes the mappings for the specified address |
| 18422 | range, and causes further references to addresses within the range to |
| 18423 | generate invalid memory references. |
| 18424 | |
| 18425 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18426 | Upon successful completion, the value 0 is returned; otherwise the |
| 18427 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 18428 | error. |
| 18429 | |
| 18430 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18431 | m\bmu\bun\bnm\bma\bap\bp() will fail if: |
| 18432 | |
| 18433 | [EINVAL] The _\ba_\bd_\bd_\br parameter was not page aligned, _\ba_\bd_\bd_\br and _\bl_\be_\bn |
| 18434 | specify a region that would extend beyond the end of |
| 18435 | the address space, or some part of the region being |
| 18436 | unmapped is not part of the currently valid address |
| 18437 | space. |
| 18438 | |
| 18439 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18440 | madvise(2), mincore(2), mlock(2), mlockall(2), mmap(2), mprotect(2), |
| 18441 | msync(2), getpagesize(3) |
| 18442 | |
| 18443 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18444 | The m\bmu\bun\bnm\bma\bap\bp() system call first appeared in 4.1cBSD. |
| 18445 | |
| 18446 | N\bNA\bAM\bME\bE |
| 18447 | n\bna\ban\bno\bos\bsl\ble\bee\bep\bp - high resolution sleep |
| 18448 | |
| 18449 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18450 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<t\bti\bim\bme\be.\b.h\bh>\b> |
| 18451 | |
| 18452 | _\bi_\bn_\bt |
| 18453 | n\bna\ban\bno\bos\bsl\ble\bee\bep\bp(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\br_\be_\bm_\ba_\bi_\bn_\bd_\be_\br); |
| 18454 | |
| 18455 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18456 | n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() suspends execution of the calling process for the duration |
| 18457 | specified by _\bt_\bi_\bm_\be_\bo_\bu_\bt. An unmasked signal will cause it to terminate the |
| 18458 | sleep early, regardless of the SA_RESTART value on the interrupting |
| 18459 | signal. |
| 18460 | |
| 18461 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18462 | If the n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() function returns because the requested duration has |
| 18463 | elapsed, the value returned will be zero. |
| 18464 | |
| 18465 | If the n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() function returns due to the delivery of a signal, the |
| 18466 | value returned will be -1, and the global variable _\be_\br_\br_\bn_\bo will be set to |
| 18467 | indicate the interruption. If _\br_\be_\bm_\ba_\bi_\bn_\bd_\be_\br is non-null, the timespec |
| 18468 | structure it references is updated to contain the unslept amount (the |
| 18469 | requested duration minus the duration actually slept). |
| 18470 | |
| 18471 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18472 | If any of the following conditions occur, the n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() function shall |
| 18473 | return -1 and set _\be_\br_\br_\bn_\bo to the corresponding value. |
| 18474 | |
| 18475 | [EINTR] k\bkq\bqu\bue\beu\bue\be was interrupted by the delivery of a signal. |
| 18476 | |
| 18477 | [EINVAL] _\bt_\bi_\bm_\be_\bo_\bu_\bt specified a nanosecond value less than zero or |
| 18478 | greater than 1000 million, or a second value less than |
| 18479 | zero or greater than 100 million. |
| 18480 | |
| 18481 | [EFAULT] Either _\bt_\bi_\bm_\be_\bo_\bu_\bt or _\br_\be_\bm_\ba_\bi_\bn_\bd_\be_\br points to memory that is |
| 18482 | not a valid part of the process address space. |
| 18483 | |
| 18484 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18485 | sleep(1), sleep(3) |
| 18486 | |
| 18487 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 18488 | The n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 18489 | |
| 18490 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18491 | The predecessor of this system call, s\bsl\ble\bee\bep\bp(), appeared in Version 3 AT&T |
| 18492 | UNIX, but was removed when alarm(3) was introduced into Version 7 AT&T |
| 18493 | UNIX. The n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() system call has been available since NetBSD 1.3 |
| 18494 | and was ported to OpenBSD 2.1 and FreeBSD 3.0. |
| 18495 | |
| 18496 | N\bNA\bAM\bME\bE |
| 18497 | n\bnf\bfs\bss\bsv\bvc\bc - NFS services |
| 18498 | |
| 18499 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18500 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 18501 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<n\bnf\bfs\bs/\b/n\bnf\bfs\bs.\b.h\bh>\b> |
| 18502 | |
| 18503 | _\bi_\bn_\bt |
| 18504 | n\bnf\bfs\bss\bsv\bvc\bc(_\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bv_\bo_\bi_\bd _\b*_\ba_\br_\bg_\bs_\bt_\br_\bu_\bc_\bt_\bp); |
| 18505 | |
| 18506 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18507 | The n\bnf\bfs\bss\bsv\bvc\bc() function is used by NFS daemons to pass information into the |
| 18508 | kernel and also to enter the kernel as a server daemon. The _\bf_\bl_\ba_\bg_\bs |
| 18509 | argument consists of several bits that show what action is to be taken |
| 18510 | once in the kernel and the _\ba_\br_\bg_\bs_\bt_\br_\bu_\bc_\bt_\bp points to one of two structures |
| 18511 | depending on which bits are set in flags. |
| 18512 | |
| 18513 | To enter an nfsd(8) daemon into the kernel, n\bnf\bfs\bss\bsv\bvc\bc() is called with the |
| 18514 | flag NFSSVC_NFSD and a pointer to a structure: |
| 18515 | |
| 18516 | struct nfsd_srvargs { |
| 18517 | struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ |
| 18518 | uid_t nsd_uid; /* Effective uid mapped to cred */ |
| 18519 | u_int32_t nsd_haddr; /* IP address of client */ |
| 18520 | struct xucred nsd_cr; /* Cred. uid maps to */ |
| 18521 | int nsd_authlen; /* Length of auth string (ret) */ |
| 18522 | u_char *nsd_authstr; /* Auth string (ret) */ |
| 18523 | int nsd_verflen; /* and the verifier */ |
| 18524 | u_char *nsd_verfstr; |
| 18525 | struct timeval nsd_timestamp; /* timestamp from verifier */ |
| 18526 | u_int32_t nsd_ttl; /* credential ttl (sec) */ |
| 18527 | }; |
| 18528 | |
| 18529 | To add further sockets for processing by the nfsd(8) server daemons the |
| 18530 | master nfsd(8) daemon calls n\bnf\bfs\bss\bsv\bvc\bc() with the flag NFSSVC_ADDSOCK and a |
| 18531 | pointer to a structure: |
| 18532 | |
| 18533 | struct nfsd_args { |
| 18534 | int sock; /* Socket to serve */ |
| 18535 | caddr_t name; /* Client address for connection based sockets */ |
| 18536 | int namelen; /* Length of name */ |
| 18537 | }; |
| 18538 | |
| 18539 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18540 | Normally n\bnf\bfs\bss\bsv\bvc\bc does not return unless the server is terminated by a |
| 18541 | signal when a value of 0 is returned. Otherwise, -1 is returned and the |
| 18542 | global variable _\be_\br_\br_\bn_\bo is set to specify the error. |
| 18543 | |
| 18544 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18545 | [EPERM] The caller is not the superuser. |
| 18546 | |
| 18547 | [EINVAL] The flag argument consisted of incompatible or |
| 18548 | otherwise unsupported bits. |
| 18549 | |
| 18550 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18551 | mount_nfs(8), nfsd(8), sysctl(8) |
| 18552 | |
| 18553 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18554 | The n\bnf\bfs\bss\bsv\bvc\bc function first appeared in 4.4BSD. |
| 18555 | |
| 18556 | B\bBU\bUG\bGS\bS |
| 18557 | The n\bnf\bfs\bss\bsv\bvc\bc system call is designed specifically for the NFS support |
| 18558 | daemons and as such is specific to their requirements. Several fields of |
| 18559 | the argument structures are assumed to be valid and sometimes to be |
| 18560 | unchanged from a previous call, such that n\bnf\bfs\bss\bsv\bvc\bc() must be used with |
| 18561 | extreme care. |
| 18562 | |
| 18563 | N\bNA\bAM\bME\bE |
| 18564 | o\bop\bpe\ben\bn, o\bop\bpe\ben\bna\bat\bt - open or create a file for reading or writing |
| 18565 | |
| 18566 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18567 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 18568 | |
| 18569 | _\bi_\bn_\bt |
| 18570 | o\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\b._\b._\b.); |
| 18571 | |
| 18572 | _\bi_\bn_\bt |
| 18573 | o\bop\bpe\ben\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\b._\b._\b.); |
| 18574 | |
| 18575 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18576 | The file name specified by _\bp_\ba_\bt_\bh is opened for reading and/or writing as |
| 18577 | specified by the argument _\bf_\bl_\ba_\bg_\bs and the file descriptor returned to the |
| 18578 | calling process. The _\bf_\bl_\ba_\bg_\bs argument may indicate the file is to be |
| 18579 | created if it does not exist (by specifying the O_CREAT flag), in which |
| 18580 | case the file is created with a mode specified by an additional argument |
| 18581 | of type _\bm_\bo_\bd_\be_\b__\bt as described in chmod(2) and modified by the process' |
| 18582 | umask value (see umask(2)). |
| 18583 | |
| 18584 | The _\bf_\bl_\ba_\bg_\bs specified are a bitwise OR of the following values. Exactly |
| 18585 | one of the first three values (file access modes) must be specified: |
| 18586 | |
| 18587 | O_RDONLY Open for reading only. |
| 18588 | O_WRONLY Open for writing only. |
| 18589 | O_RDWR Open for reading and writing. |
| 18590 | |
| 18591 | Any combination of the following flags may additionally be used: |
| 18592 | |
| 18593 | O_NONBLOCK Do not block on open or for data to become available. |
| 18594 | O_APPEND Append on each write. |
| 18595 | O_CREAT Create file if it does not exist. An additional |
| 18596 | argument of type _\bm_\bo_\bd_\be_\b__\bt must be supplied to the call. |
| 18597 | O_TRUNC Truncate size to 0. |
| 18598 | O_EXCL Error if O_CREAT is set and file exists. |
| 18599 | O_SYNC Perform synchronous I/O operations. |
| 18600 | O_SHLOCK Atomically obtain a shared lock. |
| 18601 | O_EXLOCK Atomically obtain an exclusive lock. |
| 18602 | O_NOFOLLOW If last path element is a symlink, don't follow it. |
| 18603 | O_CLOEXEC Set FD_CLOEXEC (the close-on-exec flag) on the new |
| 18604 | file descriptor. |
| 18605 | O_DIRECTORY Error if _\bp_\ba_\bt_\bh does not name a directory. |
| 18606 | |
| 18607 | Opening a file with O_APPEND set causes each write on the file to be |
| 18608 | appended to the end. If O_TRUNC and a writing mode are specified and the |
| 18609 | file exists, the file is truncated to zero length. If O_EXCL is set with |
| 18610 | O_CREAT and the file already exists, o\bop\bpe\ben\bn() returns an error. This may |
| 18611 | be used to implement a simple exclusive access locking mechanism. If |
| 18612 | either of O_EXCL or O_NOFOLLOW are set and the last component of the |
| 18613 | pathname is a symbolic link, o\bop\bpe\ben\bn() will fail even if the symbolic link |
| 18614 | points to a non-existent name. If the O_NONBLOCK flag is specified, do |
| 18615 | not wait for the device or file to be ready or available. If the o\bop\bpe\ben\bn() |
| 18616 | call would result in the process being blocked for some reason (e.g., |
| 18617 | waiting for carrier on a dialup line), o\bop\bpe\ben\bn() returns immediately. This |
| 18618 | flag also has the effect of making all subsequent I/O on the open file |
| 18619 | non-blocking. If the O_SYNC flag is set, all I/O operations on the file |
| 18620 | will be done synchronously. |
| 18621 | |
| 18622 | A FIFO should either be opened with O_RDONLY or with O_WRONLY. The |
| 18623 | behavior for opening a FIFO with O_RDWR is undefined. |
| 18624 | |
| 18625 | When opening a file, a lock with flock(2) semantics can be obtained by |
| 18626 | setting O_SHLOCK for a shared lock, or O_EXLOCK for an exclusive lock. |
| 18627 | If creating a file with O_CREAT, the request for the lock will never fail |
| 18628 | (provided that the underlying filesystem supports locking). |
| 18629 | |
| 18630 | If o\bop\bpe\ben\bn() is successful, the file pointer used to mark the current |
| 18631 | position within the file is set to the beginning of the file. |
| 18632 | |
| 18633 | When a new file is created it is given the group of the directory which |
| 18634 | contains it. |
| 18635 | |
| 18636 | The new descriptor is set to remain open across execve(2) system calls; |
| 18637 | see close(2) and fcntl(2). |
| 18638 | |
| 18639 | The system imposes a limit on the number of file descriptors open |
| 18640 | simultaneously by one process. getdtablesize(3) returns the current |
| 18641 | system limit. |
| 18642 | |
| 18643 | The o\bop\bpe\ben\bna\bat\bt() function is equivalent to o\bop\bpe\ben\bn() except that where _\bp_\ba_\bt_\bh |
| 18644 | specifies a relative path, the file to be opened is determined relative |
| 18645 | to the directory associated with file descriptor _\bf_\bd instead of the |
| 18646 | current working directory. |
| 18647 | |
| 18648 | If o\bop\bpe\ben\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 18649 | in the _\bf_\bd parameter, the current working directory is used and the |
| 18650 | behavior is identical to a call to o\bop\bpe\ben\bn(). |
| 18651 | |
| 18652 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18653 | If successful, o\bop\bpe\ben\bn() returns a non-negative integer, termed a file |
| 18654 | descriptor. Otherwise, a value of -1 is returned and _\be_\br_\br_\bn_\bo is set to |
| 18655 | indicate the error. |
| 18656 | |
| 18657 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18658 | The o\bop\bpe\ben\bn() and o\bop\bpe\ben\bna\bat\bt() functions will fail if: |
| 18659 | |
| 18660 | [ENOTDIR] A component of the path prefix is not a directory. |
| 18661 | |
| 18662 | [ENOTDIR] O_DIRECTORY is specified and _\bp_\ba_\bt_\bh does not name a |
| 18663 | directory. |
| 18664 | |
| 18665 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 18666 | characters, or an entire pathname (including the |
| 18667 | terminating NUL) exceeded PATH_MAX bytes. |
| 18668 | |
| 18669 | [ENOENT] O_CREAT is not set and the named file does not exist. |
| 18670 | |
| 18671 | [ENOENT] A component of the path name that must exist does not |
| 18672 | exist. |
| 18673 | |
| 18674 | [EACCES] Search permission is denied for a component of the |
| 18675 | path prefix. |
| 18676 | |
| 18677 | [EACCES] The required permissions (for reading and/or writing) |
| 18678 | are denied for the given _\bf_\bl_\ba_\bg_\bs. |
| 18679 | |
| 18680 | [EACCES] O_CREAT is specified, the file does not exist, and the |
| 18681 | directory in which it is to be created does not permit |
| 18682 | writing. |
| 18683 | |
| 18684 | [ELOOP] Too many symbolic links were encountered in |
| 18685 | translating the pathname, or the O_NOFOLLOW flag was |
| 18686 | specified and the target is a symbolic link. |
| 18687 | |
| 18688 | [EISDIR] The named file is a directory, and the arguments |
| 18689 | specify it is to be opened for writing. |
| 18690 | |
| 18691 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs specified for opening the file are not |
| 18692 | valid. |
| 18693 | |
| 18694 | [EROFS] The named file resides on a read-only file system, and |
| 18695 | the file is to be modified. |
| 18696 | |
| 18697 | [EMFILE] The process has already reached its limit for open |
| 18698 | file descriptors. |
| 18699 | |
| 18700 | [ENFILE] The system file table is full. |
| 18701 | |
| 18702 | [ENXIO] The named file is a character special or block special |
| 18703 | file, and the device associated with this special file |
| 18704 | does not exist. |
| 18705 | |
| 18706 | [ENXIO] The named file is a FIFO, the O_NONBLOCK and O_WRONLY |
| 18707 | flags are set, and no process has the file open for |
| 18708 | reading. |
| 18709 | |
| 18710 | [EINTR] The o\bop\bpe\ben\bn() operation was interrupted by a signal. |
| 18711 | |
| 18712 | [EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying |
| 18713 | filesystem does not support locking. |
| 18714 | |
| 18715 | [EWOULDBLOCK] O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is |
| 18716 | specified and the file is already locked. |
| 18717 | |
| 18718 | [ENOSPC] O_CREAT is specified, the file does not exist, and the |
| 18719 | directory in which the entry for the new file is being |
| 18720 | placed cannot be extended because there is no space |
| 18721 | left on the file system containing the directory. |
| 18722 | |
| 18723 | [ENOSPC] O_CREAT is specified, the file does not exist, and |
| 18724 | there are no free inodes on the file system on which |
| 18725 | the file is being created. |
| 18726 | |
| 18727 | [EDQUOT] O_CREAT is specified, the file does not exist, and the |
| 18728 | directory in which the entry for the new file is being |
| 18729 | placed cannot be extended because the user's quota of |
| 18730 | disk blocks on the file system containing the |
| 18731 | directory has been exhausted. |
| 18732 | |
| 18733 | [EDQUOT] O_CREAT is specified, the file does not exist, and the |
| 18734 | user's quota of inodes on the file system on which the |
| 18735 | file is being created has been exhausted. |
| 18736 | |
| 18737 | [EIO] An I/O error occurred while making the directory entry |
| 18738 | or allocating the inode for O_CREAT. |
| 18739 | |
| 18740 | [ETXTBSY] The file is a pure procedure (shared text) file that |
| 18741 | is being executed and the o\bop\bpe\ben\bn() call requests write |
| 18742 | access. |
| 18743 | |
| 18744 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 18745 | space. |
| 18746 | |
| 18747 | [EEXIST] O_CREAT and O_EXCL were specified and the file exists. |
| 18748 | |
| 18749 | [EPERM] The file named by _\bp_\ba_\bt_\bh is flagged append-only but |
| 18750 | O_APPEND was not specified in _\bf_\bl_\ba_\bg_\bs. |
| 18751 | |
| 18752 | [EOPNOTSUPP] An attempt was made to open a socket (not currently |
| 18753 | implemented). |
| 18754 | |
| 18755 | [EBUSY] An attempt was made to open a terminal device that |
| 18756 | requires exclusive access and the specified device has |
| 18757 | already be opened. |
| 18758 | |
| 18759 | Additionally, the o\bop\bpe\ben\bna\bat\bt() function will fail if: |
| 18760 | |
| 18761 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 18762 | argument is neither AT_FDCWD nor a valid file |
| 18763 | descriptor. |
| 18764 | |
| 18765 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 18766 | argument is a valid file descriptor but it does not |
| 18767 | reference a directory. |
| 18768 | |
| 18769 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 18770 | permission is denied for the directory which the _\bf_\bd |
| 18771 | file descriptor references. |
| 18772 | |
| 18773 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 18774 | chflags(2), chmod(2), close(2), dup(2), flock(2), lseek(2), read(2), |
| 18775 | umask(2), write(2), getdtablesize(3) |
| 18776 | |
| 18777 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 18778 | The o\bop\bpe\ben\bn() and o\bop\bpe\ben\bna\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 18779 | (``POSIX.1''). |
| 18780 | |
| 18781 | POSIX specifies three different flavors for synchronous I/O: O_SYNC, |
| 18782 | O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent. |
| 18783 | |
| 18784 | The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should |
| 18785 | not be used if portability is of concern. |
| 18786 | |
| 18787 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 18788 | An o\bop\bpe\ben\bn() system call first appeared in Version 1 AT&T UNIX. The _\bf_\bl_\ba_\bg_\bs |
| 18789 | argument has been supported since 4.2BSD. Before that, a dedicated |
| 18790 | c\bcr\bre\bea\bat\bt() system call had to be used to create new files; it appeared in |
| 18791 | Version 1 AT&T UNIX, was deprecated in 4.3BSD-Reno, and removed in |
| 18792 | OpenBSD 5.0. |
| 18793 | |
| 18794 | The o\bop\bpe\ben\bna\bat\bt() system call has been available since OpenBSD 5.0. |
| 18795 | |
| 18796 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 18797 | The O_TRUNC flag requires that one of O_RDWR or O_WRONLY also be |
| 18798 | specified, else EINVAL is returned. |
| 18799 | |
| 18800 | N\bNA\bAM\bME\bE |
| 18801 | o\bop\bpe\ben\bn, o\bop\bpe\ben\bna\bat\bt - open or create a file for reading or writing |
| 18802 | |
| 18803 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 18804 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 18805 | |
| 18806 | _\bi_\bn_\bt |
| 18807 | o\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\b._\b._\b.); |
| 18808 | |
| 18809 | _\bi_\bn_\bt |
| 18810 | o\bop\bpe\ben\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\b._\b._\b.); |
| 18811 | |
| 18812 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 18813 | The file name specified by _\bp_\ba_\bt_\bh is opened for reading and/or writing as |
| 18814 | specified by the argument _\bf_\bl_\ba_\bg_\bs and the file descriptor returned to the |
| 18815 | calling process. The _\bf_\bl_\ba_\bg_\bs argument may indicate the file is to be |
| 18816 | created if it does not exist (by specifying the O_CREAT flag), in which |
| 18817 | case the file is created with a mode specified by an additional argument |
| 18818 | of type _\bm_\bo_\bd_\be_\b__\bt as described in chmod(2) and modified by the process' |
| 18819 | umask value (see umask(2)). |
| 18820 | |
| 18821 | The _\bf_\bl_\ba_\bg_\bs specified are a bitwise OR of the following values. Exactly |
| 18822 | one of the first three values (file access modes) must be specified: |
| 18823 | |
| 18824 | O_RDONLY Open for reading only. |
| 18825 | O_WRONLY Open for writing only. |
| 18826 | O_RDWR Open for reading and writing. |
| 18827 | |
| 18828 | Any combination of the following flags may additionally be used: |
| 18829 | |
| 18830 | O_NONBLOCK Do not block on open or for data to become available. |
| 18831 | O_APPEND Append on each write. |
| 18832 | O_CREAT Create file if it does not exist. An additional |
| 18833 | argument of type _\bm_\bo_\bd_\be_\b__\bt must be supplied to the call. |
| 18834 | O_TRUNC Truncate size to 0. |
| 18835 | O_EXCL Error if O_CREAT is set and file exists. |
| 18836 | O_SYNC Perform synchronous I/O operations. |
| 18837 | O_SHLOCK Atomically obtain a shared lock. |
| 18838 | O_EXLOCK Atomically obtain an exclusive lock. |
| 18839 | O_NOFOLLOW If last path element is a symlink, don't follow it. |
| 18840 | O_CLOEXEC Set FD_CLOEXEC (the close-on-exec flag) on the new |
| 18841 | file descriptor. |
| 18842 | O_DIRECTORY Error if _\bp_\ba_\bt_\bh does not name a directory. |
| 18843 | |
| 18844 | Opening a file with O_APPEND set causes each write on the file to be |
| 18845 | appended to the end. If O_TRUNC and a writing mode are specified and the |
| 18846 | file exists, the file is truncated to zero length. If O_EXCL is set with |
| 18847 | O_CREAT and the file already exists, o\bop\bpe\ben\bn() returns an error. This may |
| 18848 | be used to implement a simple exclusive access locking mechanism. If |
| 18849 | either of O_EXCL or O_NOFOLLOW are set and the last component of the |
| 18850 | pathname is a symbolic link, o\bop\bpe\ben\bn() will fail even if the symbolic link |
| 18851 | points to a non-existent name. If the O_NONBLOCK flag is specified, do |
| 18852 | not wait for the device or file to be ready or available. If the o\bop\bpe\ben\bn() |
| 18853 | call would result in the process being blocked for some reason (e.g., |
| 18854 | waiting for carrier on a dialup line), o\bop\bpe\ben\bn() returns immediately. This |
| 18855 | flag also has the effect of making all subsequent I/O on the open file |
| 18856 | non-blocking. If the O_SYNC flag is set, all I/O operations on the file |
| 18857 | will be done synchronously. |
| 18858 | |
| 18859 | A FIFO should either be opened with O_RDONLY or with O_WRONLY. The |
| 18860 | behavior for opening a FIFO with O_RDWR is undefined. |
| 18861 | |
| 18862 | When opening a file, a lock with flock(2) semantics can be obtained by |
| 18863 | setting O_SHLOCK for a shared lock, or O_EXLOCK for an exclusive lock. |
| 18864 | If creating a file with O_CREAT, the request for the lock will never fail |
| 18865 | (provided that the underlying filesystem supports locking). |
| 18866 | |
| 18867 | If o\bop\bpe\ben\bn() is successful, the file pointer used to mark the current |
| 18868 | position within the file is set to the beginning of the file. |
| 18869 | |
| 18870 | When a new file is created it is given the group of the directory which |
| 18871 | contains it. |
| 18872 | |
| 18873 | The new descriptor is set to remain open across execve(2) system calls; |
| 18874 | see close(2) and fcntl(2). |
| 18875 | |
| 18876 | The system imposes a limit on the number of file descriptors open |
| 18877 | simultaneously by one process. getdtablesize(3) returns the current |
| 18878 | system limit. |
| 18879 | |
| 18880 | The o\bop\bpe\ben\bna\bat\bt() function is equivalent to o\bop\bpe\ben\bn() except that where _\bp_\ba_\bt_\bh |
| 18881 | specifies a relative path, the file to be opened is determined relative |
| 18882 | to the directory associated with file descriptor _\bf_\bd instead of the |
| 18883 | current working directory. |
| 18884 | |
| 18885 | If o\bop\bpe\ben\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 18886 | in the _\bf_\bd parameter, the current working directory is used and the |
| 18887 | behavior is identical to a call to o\bop\bpe\ben\bn(). |
| 18888 | |
| 18889 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 18890 | If successful, o\bop\bpe\ben\bn() returns a non-negative integer, termed a file |
| 18891 | descriptor. Otherwise, a value of -1 is returned and _\be_\br_\br_\bn_\bo is set to |
| 18892 | indicate the error. |
| 18893 | |
| 18894 | E\bER\bRR\bRO\bOR\bRS\bS |
| 18895 | The o\bop\bpe\ben\bn() and o\bop\bpe\ben\bna\bat\bt() functions will fail if: |
| 18896 | |
| 18897 | [ENOTDIR] A component of the path prefix is not a directory. |
| 18898 | |
| 18899 | [ENOTDIR] O_DIRECTORY is specified and _\bp_\ba_\bt_\bh does not name a |
| 18900 | directory. |
| 18901 | |
| 18902 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 18903 | characters, or an entire pathname (including the |
| 18904 | terminating NUL) exceeded PATH_MAX bytes. |
| 18905 | |
| 18906 | [ENOENT] O_CREAT is not set and the named file does not exist. |
| 18907 | |
| 18908 | [ENOENT] A component of the path name that must exist does not |
| 18909 | exist. |
| 18910 | |
| 18911 | [EACCES] Search permission is denied for a component of the |
| 18912 | path prefix. |
| 18913 | |
| 18914 | [EACCES] The required permissions (for reading and/or writing) |
| 18915 | are denied for the given _\bf_\bl_\ba_\bg_\bs. |
| 18916 | |
| 18917 | [EACCES] O_CREAT is specified, the file does not exist, and the |
| 18918 | directory in which it is to be created does not permit |
| 18919 | writing. |
| 18920 | |
| 18921 | [ELOOP] Too many symbolic links were encountered in |
| 18922 | translating the pathname, or the O_NOFOLLOW flag was |
| 18923 | specified and the target is a symbolic link. |
| 18924 | |
| 18925 | [EISDIR] The named file is a directory, and the arguments |
| 18926 | specify it is to be opened for writing. |
| 18927 | |
| 18928 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs specified for opening the file are not |
| 18929 | valid. |
| 18930 | |
| 18931 | [EROFS] The named file resides on a read-only file system, and |
| 18932 | the file is to be modified. |
| 18933 | |
| 18934 | [EMFILE] The process has already reached its limit for open |
| 18935 | file descriptors. |
| 18936 | |
| 18937 | [ENFILE] The system file table is full. |
| 18938 | |
| 18939 | [ENXIO] The named file is a character special or block special |
| 18940 | file, and the device associated with this special file |
| 18941 | does not exist. |
| 18942 | |
| 18943 | [ENXIO] The named file is a FIFO, the O_NONBLOCK and O_WRONLY |
| 18944 | flags are set, and no process has the file open for |
| 18945 | reading. |
| 18946 | |
| 18947 | [EINTR] The o\bop\bpe\ben\bn() operation was interrupted by a signal. |
| 18948 | |
| 18949 | [EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying |
| 18950 | filesystem does not support locking. |
| 18951 | |
| 18952 | [EWOULDBLOCK] O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is |
| 18953 | specified and the file is already locked. |
| 18954 | |
| 18955 | [ENOSPC] O_CREAT is specified, the file does not exist, and the |
| 18956 | directory in which the entry for the new file is being |
| 18957 | placed cannot be extended because there is no space |
| 18958 | left on the file system containing the directory. |
| 18959 | |
| 18960 | [ENOSPC] O_CREAT is specified, the file does not exist, and |
| 18961 | there are no free inodes on the file system on which |
| 18962 | the file is being created. |
| 18963 | |
| 18964 | [EDQUOT] O_CREAT is specified, the file does not exist, and the |
| 18965 | directory in which the entry for the new file is being |
| 18966 | placed cannot be extended because the user's quota of |
| 18967 | disk blocks on the file system containing the |
| 18968 | directory has been exhausted. |
| 18969 | |
| 18970 | [EDQUOT] O_CREAT is specified, the file does not exist, and the |
| 18971 | user's quota of inodes on the file system on which the |
| 18972 | file is being created has been exhausted. |
| 18973 | |
| 18974 | [EIO] An I/O error occurred while making the directory entry |
| 18975 | or allocating the inode for O_CREAT. |
| 18976 | |
| 18977 | [ETXTBSY] The file is a pure procedure (shared text) file that |
| 18978 | is being executed and the o\bop\bpe\ben\bn() call requests write |
| 18979 | access. |
| 18980 | |
| 18981 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 18982 | space. |
| 18983 | |
| 18984 | [EEXIST] O_CREAT and O_EXCL were specified and the file exists. |
| 18985 | |
| 18986 | [EPERM] The file named by _\bp_\ba_\bt_\bh is flagged append-only but |
| 18987 | O_APPEND was not specified in _\bf_\bl_\ba_\bg_\bs. |
| 18988 | |
| 18989 | [EOPNOTSUPP] An attempt was made to open a socket (not currently |
| 18990 | implemented). |
| 18991 | |
| 18992 | [EBUSY] An attempt was made to open a terminal device that |
| 18993 | requires exclusive access and the specified device has |
| 18994 | already be opened. |
| 18995 | |
| 18996 | Additionally, the o\bop\bpe\ben\bna\bat\bt() function will fail if: |
| 18997 | |
| 18998 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 18999 | argument is neither AT_FDCWD nor a valid file |
| 19000 | descriptor. |
| 19001 | |
| 19002 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 19003 | argument is a valid file descriptor but it does not |
| 19004 | reference a directory. |
| 19005 | |
| 19006 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 19007 | permission is denied for the directory which the _\bf_\bd |
| 19008 | file descriptor references. |
| 19009 | |
| 19010 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 19011 | chflags(2), chmod(2), close(2), dup(2), flock(2), lseek(2), read(2), |
| 19012 | umask(2), write(2), getdtablesize(3) |
| 19013 | |
| 19014 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 19015 | The o\bop\bpe\ben\bn() and o\bop\bpe\ben\bna\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 19016 | (``POSIX.1''). |
| 19017 | |
| 19018 | POSIX specifies three different flavors for synchronous I/O: O_SYNC, |
| 19019 | O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent. |
| 19020 | |
| 19021 | The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should |
| 19022 | not be used if portability is of concern. |
| 19023 | |
| 19024 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 19025 | An o\bop\bpe\ben\bn() system call first appeared in Version 1 AT&T UNIX. The _\bf_\bl_\ba_\bg_\bs |
| 19026 | argument has been supported since 4.2BSD. Before that, a dedicated |
| 19027 | c\bcr\bre\bea\bat\bt() system call had to be used to create new files; it appeared in |
| 19028 | Version 1 AT&T UNIX, was deprecated in 4.3BSD-Reno, and removed in |
| 19029 | OpenBSD 5.0. |
| 19030 | |
| 19031 | The o\bop\bpe\ben\bna\bat\bt() system call has been available since OpenBSD 5.0. |
| 19032 | |
| 19033 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 19034 | The O_TRUNC flag requires that one of O_RDWR or O_WRONLY also be |
| 19035 | specified, else EINVAL is returned. |
| 19036 | |
| 19037 | N\bNA\bAM\bME\bE |
| 19038 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf, f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf - get configurable pathname variables |
| 19039 | |
| 19040 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 19041 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 19042 | |
| 19043 | _\bl_\bo_\bn_\bg |
| 19044 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bn_\ba_\bm_\be); |
| 19045 | |
| 19046 | _\bl_\bo_\bn_\bg |
| 19047 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf(_\bi_\bn_\bt _\bf_\bd, _\bi_\bn_\bt _\bn_\ba_\bm_\be); |
| 19048 | |
| 19049 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 19050 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf() and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf() functions provide a method for |
| 19051 | applications to determine the current value of a configurable system |
| 19052 | limit or option variable associated with a pathname or file descriptor. |
| 19053 | |
| 19054 | For p\bpa\bat\bth\bhc\bco\bon\bnf\bf, the _\bp_\ba_\bt_\bh argument is the name of a file or directory. For |
| 19055 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf, the _\bf_\bd argument is an open file descriptor. The _\bn_\ba_\bm_\be argument |
| 19056 | specifies the system variable to be queried. Symbolic constants for each |
| 19057 | name value are found in the include file <_\bu_\bn_\bi_\bs_\bt_\bd_\b._\bh>. |
| 19058 | |
| 19059 | The available values are as follows: |
| 19060 | |
| 19061 | _PC_LINK_MAX |
| 19062 | The maximum file link count. |
| 19063 | |
| 19064 | _PC_MAX_CANON |
| 19065 | The maximum number of bytes in a terminal canonical input line. |
| 19066 | |
| 19067 | _PC_MAX_INPUT |
| 19068 | The maximum number of bytes for which space is available in a |
| 19069 | terminal input queue. |
| 19070 | |
| 19071 | _PC_NAME_MAX |
| 19072 | The maximum number of bytes in a file name. |
| 19073 | |
| 19074 | _PC_PATH_MAX |
| 19075 | The maximum number of bytes in a pathname. |
| 19076 | |
| 19077 | _PC_PIPE_BUF |
| 19078 | The maximum number of bytes which will be written atomically to a |
| 19079 | pipe. |
| 19080 | |
| 19081 | _PC_CHOWN_RESTRICTED |
| 19082 | Returns 1 if appropriate privileges are required for the chown(2) |
| 19083 | system call, otherwise 0. IEEE Std 1003.1-2001 (``POSIX.1'') |
| 19084 | requires appropriate privilege in all cases, but this behavior |
| 19085 | was optional in prior editions of the standard. |
| 19086 | |
| 19087 | _PC_NO_TRUNC |
| 19088 | Returns 1 if attempts to use pathname components longer than |
| 19089 | {NAME_MAX} will result in an [ENAMETOOLONG] error; otherwise, |
| 19090 | such components will be truncated to {NAME_MAX}. IEEE Std |
| 19091 | 1003.1-2001 (``POSIX.1'') requires the error in all cases, but |
| 19092 | this behavior was optional in prior editions of the standard, and |
| 19093 | some non-POSIX-compliant file systems do not support this |
| 19094 | behavior. |
| 19095 | |
| 19096 | _PC_VDISABLE |
| 19097 | Returns the terminal character disabling value. |
| 19098 | |
| 19099 | _PC_2_SYMLINKS |
| 19100 | Returns 1 if the filesystem supports the creation of symbolic |
| 19101 | links within the specified directory; the meaning of |
| 19102 | _PC_2_SYMLINKS is unspecified for non-directory files. |
| 19103 | |
| 19104 | _PC_ALLOC_SIZE_MIN |
| 19105 | Minimum number of bytes of storage allocated for any portion of a |
| 19106 | file. |
| 19107 | |
| 19108 | _PC_ASYNC_IO |
| 19109 | Returns 1 if asynchronous I/O is supported, otherwise 0. |
| 19110 | |
| 19111 | _PC_FILESIZEBITS |
| 19112 | Number of bits needed to represent the maximum file size. |
| 19113 | |
| 19114 | _PC_PRIO_IO |
| 19115 | Returns 1 if prioritized I/O is supported, otherwise 0. |
| 19116 | |
| 19117 | _PC_REC_INCR_XFER_SIZE |
| 19118 | Recommended increment for file transfer sizes between |
| 19119 | _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE. |
| 19120 | |
| 19121 | _PC_REC_MAX_XFER_SIZE |
| 19122 | Maximum recommended file transfer size. |
| 19123 | |
| 19124 | _PC_REC_MIN_XFER_SIZE |
| 19125 | Minimum recommended file transfer size. |
| 19126 | |
| 19127 | _PC_REC_XFER_ALIGN |
| 19128 | Recommended file transfer buffer alignment. |
| 19129 | |
| 19130 | _PC_SYMLINK_MAX |
| 19131 | Maximum number of bytes in a symbolic link. |
| 19132 | |
| 19133 | _PC_SYNC_IO |
| 19134 | Returns 1 if synchronized I/O is supported, otherwise 0. |
| 19135 | |
| 19136 | _PC_TIMESTAMP_RESOLUTION |
| 19137 | The resolution in nanoseconds of file timestamps. |
| 19138 | |
| 19139 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 19140 | If the call to p\bpa\bat\bth\bhc\bco\bon\bnf\bf or f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf is not successful, -1 is returned |
| 19141 | and _\be_\br_\br_\bn_\bo is set appropriately. Otherwise, if the variable is associated |
| 19142 | with functionality that does not have a limit in the system, -1 is |
| 19143 | returned and _\be_\br_\br_\bn_\bo is not modified. Otherwise, the current variable |
| 19144 | value is returned. |
| 19145 | |
| 19146 | E\bER\bRR\bRO\bOR\bRS\bS |
| 19147 | If any of the following conditions occur, the p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf |
| 19148 | functions shall return -1 and set _\be_\br_\br_\bn_\bo to the corresponding value. |
| 19149 | |
| 19150 | [EINVAL] The value of the _\bn_\ba_\bm_\be argument is invalid. |
| 19151 | |
| 19152 | [EINVAL] The implementation does not support an association of |
| 19153 | the variable name with the associated file. |
| 19154 | |
| 19155 | [EIO] An I/O error occurred while reading from the file |
| 19156 | system. |
| 19157 | |
| 19158 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf() will fail if: |
| 19159 | |
| 19160 | [ENOTDIR] A component of the path prefix is not a directory. |
| 19161 | |
| 19162 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters |
| 19163 | (but see _PC_NO_TRUNC above), or an entire pathname |
| 19164 | (including the terminating NUL) exceeded PATH_MAX |
| 19165 | bytes. |
| 19166 | |
| 19167 | [ENOENT] The named file does not exist. |
| 19168 | |
| 19169 | [EACCES] Search permission is denied for a component of the |
| 19170 | path prefix. |
| 19171 | |
| 19172 | [ELOOP] Too many symbolic links were encountered in |
| 19173 | translating the pathname. |
| 19174 | |
| 19175 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 19176 | space. |
| 19177 | |
| 19178 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf() will fail if: |
| 19179 | |
| 19180 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 19181 | |
| 19182 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 19183 | sysconf(3), sysctl(3) |
| 19184 | |
| 19185 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 19186 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf functions conform to IEEE Std 1003.1-2008 |
| 19187 | (``POSIX.1''). |
| 19188 | |
| 19189 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 19190 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf functions first appeared in 4.4BSD. |
| 19191 | |
| 19192 | N\bNA\bAM\bME\bE |
| 19193 | p\bpi\bip\bpe\be, p\bpi\bip\bpe\be2\b2 - create descriptor pair for interprocess communication |
| 19194 | |
| 19195 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 19196 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 19197 | |
| 19198 | _\bi_\bn_\bt |
| 19199 | p\bpi\bip\bpe\be(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b2_\b]); |
| 19200 | |
| 19201 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 19202 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 19203 | |
| 19204 | _\bi_\bn_\bt |
| 19205 | p\bpi\bip\bpe\be2\b2(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b2_\b], _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 19206 | |
| 19207 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 19208 | The p\bpi\bip\bpe\be() function creates a _\bp_\bi_\bp_\be, which is an object allowing |
| 19209 | unidirectional data flow, and allocates a pair of file descriptors. The |
| 19210 | first descriptor connects to the _\br_\be_\ba_\bd _\be_\bn_\bd of the pipe, and the second |
| 19211 | connects to the _\bw_\br_\bi_\bt_\be _\be_\bn_\bd, so that data written to _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b1_\b] appears on |
| 19212 | (i.e., can be read from) _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b0_\b]. This allows the output of one |
| 19213 | program to be sent to another program: the source's standard output is |
| 19214 | set up to be the write end of the pipe, and the sink's standard input is |
| 19215 | set up to be the read end of the pipe. The pipe itself persists until |
| 19216 | all its associated descriptors are closed. |
| 19217 | |
| 19218 | A pipe whose read or write end has been closed is considered _\bw_\bi_\bd_\bo_\bw_\be_\bd. |
| 19219 | Writing on such a pipe causes the writing process to receive a SIGPIPE |
| 19220 | signal. Widowing a pipe is the only way to deliver end-of-file to a |
| 19221 | reader: after the reader consumes any buffered data, reading a widowed |
| 19222 | pipe returns a zero count. |
| 19223 | |
| 19224 | The p\bpi\bip\bpe\be2\b2() function is identical to p\bpi\bip\bpe\be() except that the non-blocking |
| 19225 | I/O mode on both ends of the pipe is determined by the O_NONBLOCK flag in |
| 19226 | the _\bf_\bl_\ba_\bg_\bs argument and the close-on-exec flag on both the new file |
| 19227 | descriptors is determined by the O_CLOEXEC flag in the _\bf_\bl_\ba_\bg_\bs argument. |
| 19228 | |
| 19229 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 19230 | Upon successful completion, the value 0 is returned; otherwise the |
| 19231 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 19232 | error. |
| 19233 | |
| 19234 | E\bER\bRR\bRO\bOR\bRS\bS |
| 19235 | p\bpi\bip\bpe\be() and p\bpi\bip\bpe\be2\b2() will succeed unless: |
| 19236 | |
| 19237 | [EMFILE] Too many descriptors are active. |
| 19238 | |
| 19239 | [ENFILE] The system file table is full. |
| 19240 | |
| 19241 | [EFAULT] The _\bf_\bi_\bl_\bd_\be_\bs buffer is in an invalid area of the |
| 19242 | process's address space. |
| 19243 | |
| 19244 | In addition, p\bpi\bip\bpe\be2\b2() may return the following error: |
| 19245 | |
| 19246 | [EINVAL] _\bf_\bl_\ba_\bg_\bs is invalid. |
| 19247 | |
| 19248 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 19249 | sh(1), fork(2), read(2), socketpair(2), write(2) |
| 19250 | |
| 19251 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 19252 | The p\bpi\bip\bpe\be() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The |
| 19253 | p\bpi\bip\bpe\be2\b2() function is expected to conform to a future revision of that |
| 19254 | standard. |
| 19255 | |
| 19256 | As an extension, the pipe provided is actually capable of moving data |
| 19257 | bidirectionally. This is compatible with SVR4. However, this is non- |
| 19258 | POSIX behaviour which should not be relied on, for reasons of |
| 19259 | portability. |
| 19260 | |
| 19261 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 19262 | A p\bpi\bip\bpe\be() function call appeared in Version 3 AT&T UNIX. Since Version 4 |
| 19263 | AT&T UNIX, it allocates two distinct file descriptors. The p\bpi\bip\bpe\be2\b2() |
| 19264 | function appeared in OpenBSD 5.7. |
| 19265 | |
| 19266 | N\bNA\bAM\bME\bE |
| 19267 | p\bpi\bip\bpe\be, p\bpi\bip\bpe\be2\b2 - create descriptor pair for interprocess communication |
| 19268 | |
| 19269 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 19270 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 19271 | |
| 19272 | _\bi_\bn_\bt |
| 19273 | p\bpi\bip\bpe\be(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b2_\b]); |
| 19274 | |
| 19275 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 19276 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 19277 | |
| 19278 | _\bi_\bn_\bt |
| 19279 | p\bpi\bip\bpe\be2\b2(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b2_\b], _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 19280 | |
| 19281 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 19282 | The p\bpi\bip\bpe\be() function creates a _\bp_\bi_\bp_\be, which is an object allowing |
| 19283 | unidirectional data flow, and allocates a pair of file descriptors. The |
| 19284 | first descriptor connects to the _\br_\be_\ba_\bd _\be_\bn_\bd of the pipe, and the second |
| 19285 | connects to the _\bw_\br_\bi_\bt_\be _\be_\bn_\bd, so that data written to _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b1_\b] appears on |
| 19286 | (i.e., can be read from) _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b0_\b]. This allows the output of one |
| 19287 | program to be sent to another program: the source's standard output is |
| 19288 | set up to be the write end of the pipe, and the sink's standard input is |
| 19289 | set up to be the read end of the pipe. The pipe itself persists until |
| 19290 | all its associated descriptors are closed. |
| 19291 | |
| 19292 | A pipe whose read or write end has been closed is considered _\bw_\bi_\bd_\bo_\bw_\be_\bd. |
| 19293 | Writing on such a pipe causes the writing process to receive a SIGPIPE |
| 19294 | signal. Widowing a pipe is the only way to deliver end-of-file to a |
| 19295 | reader: after the reader consumes any buffered data, reading a widowed |
| 19296 | pipe returns a zero count. |
| 19297 | |
| 19298 | The p\bpi\bip\bpe\be2\b2() function is identical to p\bpi\bip\bpe\be() except that the non-blocking |
| 19299 | I/O mode on both ends of the pipe is determined by the O_NONBLOCK flag in |
| 19300 | the _\bf_\bl_\ba_\bg_\bs argument and the close-on-exec flag on both the new file |
| 19301 | descriptors is determined by the O_CLOEXEC flag in the _\bf_\bl_\ba_\bg_\bs argument. |
| 19302 | |
| 19303 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 19304 | Upon successful completion, the value 0 is returned; otherwise the |
| 19305 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 19306 | error. |
| 19307 | |
| 19308 | E\bER\bRR\bRO\bOR\bRS\bS |
| 19309 | p\bpi\bip\bpe\be() and p\bpi\bip\bpe\be2\b2() will succeed unless: |
| 19310 | |
| 19311 | [EMFILE] Too many descriptors are active. |
| 19312 | |
| 19313 | [ENFILE] The system file table is full. |
| 19314 | |
| 19315 | [EFAULT] The _\bf_\bi_\bl_\bd_\be_\bs buffer is in an invalid area of the |
| 19316 | process's address space. |
| 19317 | |
| 19318 | In addition, p\bpi\bip\bpe\be2\b2() may return the following error: |
| 19319 | |
| 19320 | [EINVAL] _\bf_\bl_\ba_\bg_\bs is invalid. |
| 19321 | |
| 19322 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 19323 | sh(1), fork(2), read(2), socketpair(2), write(2) |
| 19324 | |
| 19325 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 19326 | The p\bpi\bip\bpe\be() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The |
| 19327 | p\bpi\bip\bpe\be2\b2() function is expected to conform to a future revision of that |
| 19328 | standard. |
| 19329 | |
| 19330 | As an extension, the pipe provided is actually capable of moving data |
| 19331 | bidirectionally. This is compatible with SVR4. However, this is non- |
| 19332 | POSIX behaviour which should not be relied on, for reasons of |
| 19333 | portability. |
| 19334 | |
| 19335 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 19336 | A p\bpi\bip\bpe\be() function call appeared in Version 3 AT&T UNIX. Since Version 4 |
| 19337 | AT&T UNIX, it allocates two distinct file descriptors. The p\bpi\bip\bpe\be2\b2() |
| 19338 | function appeared in OpenBSD 5.7. |
| 19339 | |
| 19340 | N\bNA\bAM\bME\bE |
| 19341 | p\bpo\bol\bll\bl, p\bpp\bpo\bol\bll\bl - synchronous I/O multiplexing |
| 19342 | |
| 19343 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 19344 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<p\bpo\bol\bll\bl.\b.h\bh>\b> |
| 19345 | |
| 19346 | _\bi_\bn_\bt |
| 19347 | p\bpo\bol\bll\bl(_\bs_\bt_\br_\bu_\bc_\bt _\bp_\bo_\bl_\bl_\bf_\bd _\b*_\bf_\bd_\bs, _\bn_\bf_\bd_\bs_\b__\bt _\bn_\bf_\bd_\bs, _\bi_\bn_\bt _\bt_\bi_\bm_\be_\bo_\bu_\bt); |
| 19348 | |
| 19349 | _\bi_\bn_\bt |
| 19350 | p\bpp\bpo\bol\bll\bl(_\bs_\bt_\br_\bu_\bc_\bt _\bp_\bo_\bl_\bl_\bf_\bd _\b*_\bf_\bd_\bs, _\bn_\bf_\bd_\bs_\b__\bt _\bn_\bf_\bd_\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, |
| 19351 | _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bm_\ba_\bs_\bk); |
| 19352 | |
| 19353 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 19354 | p\bpo\bol\bll\bl() provides a mechanism for multiplexing I/O across a set of file |
| 19355 | descriptors. It is similar in function to select(2). Unlike select(2), |
| 19356 | however, it is possible to only pass in data corresponding to the file |
| 19357 | descriptors for which events are wanted. This makes p\bpo\bol\bll\bl() more |
| 19358 | efficient than select(2) in most cases. |
| 19359 | |
| 19360 | The arguments are as follows: |
| 19361 | |
| 19362 | _\bf_\bd_\bs Points to an array of _\bp_\bo_\bl_\bl_\bf_\bd structures, which are defined as: |
| 19363 | |
| 19364 | struct pollfd { |
| 19365 | int fd; |
| 19366 | short events; |
| 19367 | short revents; |
| 19368 | }; |
| 19369 | |
| 19370 | The _\bf_\bd member is an open file descriptor. If _\bf_\bd is -1, the |
| 19371 | _\bp_\bo_\bl_\bl_\bf_\bd structure is considered unused, and _\br_\be_\bv_\be_\bn_\bt_\bs will be |
| 19372 | cleared. |
| 19373 | |
| 19374 | The _\be_\bv_\be_\bn_\bt_\bs and _\br_\be_\bv_\be_\bn_\bt_\bs members are bitmasks of conditions to |
| 19375 | monitor and conditions found, respectively. |
| 19376 | |
| 19377 | _\bn_\bf_\bd_\bs An unsigned integer specifying the number of _\bp_\bo_\bl_\bl_\bf_\bd structures |
| 19378 | in the array. |
| 19379 | |
| 19380 | _\bt_\bi_\bm_\be_\bo_\bu_\bt Maximum interval to wait for the poll to complete, in |
| 19381 | milliseconds. If this value is 0, p\bpo\bol\bll\bl() will return |
| 19382 | immediately. If this value is INFTIM (-1), p\bpo\bol\bll\bl() will block |
| 19383 | indefinitely until a condition is found. |
| 19384 | |
| 19385 | The calling process sets the _\be_\bv_\be_\bn_\bt_\bs bitmask and p\bpo\bol\bll\bl() sets the _\br_\be_\bv_\be_\bn_\bt_\bs |
| 19386 | bitmask. Each call to p\bpo\bol\bll\bl() resets the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask for accuracy. |
| 19387 | The condition flags in the bitmasks are defined as: |
| 19388 | |
| 19389 | POLLIN Data other than high-priority data may be read without |
| 19390 | blocking. |
| 19391 | |
| 19392 | POLLRDNORM Normal data may be read without blocking. |
| 19393 | |
| 19394 | POLLRDBAND Priority data may be read without blocking. |
| 19395 | |
| 19396 | POLLNORM Same as POLLRDNORM. This flag is provided for source code |
| 19397 | compatibility with older programs and should not be used in |
| 19398 | new code. |
| 19399 | |
| 19400 | POLLPRI High-priority data may be read without blocking. |
| 19401 | |
| 19402 | POLLOUT Normal data may be written without blocking. |
| 19403 | |
| 19404 | POLLWRNORM Same as POLLOUT. |
| 19405 | |
| 19406 | POLLWRBAND Priority data may be written. |
| 19407 | |
| 19408 | POLLERR An error has occurred on the device or socket. This flag is |
| 19409 | only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; it is ignored in the |
| 19410 | _\be_\bv_\be_\bn_\bt_\bs member. |
| 19411 | |
| 19412 | POLLHUP The device or socket has been disconnected. This event and |
| 19413 | POLLOUT are mutually-exclusive; a descriptor can never be |
| 19414 | writable if a hangup has occurred. However, this event and |
| 19415 | POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually- |
| 19416 | exclusive. This flag is only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; |
| 19417 | it is ignored in the _\be_\bv_\be_\bn_\bt_\bs member. |
| 19418 | |
| 19419 | POLLNVAL The corresponding file descriptor is invalid. This flag is |
| 19420 | only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; it is ignored in the |
| 19421 | _\be_\bv_\be_\bn_\bt_\bs member. |
| 19422 | |
| 19423 | The significance and semantics of normal, priority, and high-priority |
| 19424 | data are device-specific. |
| 19425 | |
| 19426 | In addition to I/O multiplexing, p\bpo\bol\bll\bl() can be used to generate simple |
| 19427 | timeouts. This functionality may be achieved by passing a null pointer |
| 19428 | for _\bf_\bd_\bs. |
| 19429 | |
| 19430 | The p\bpp\bpo\bol\bll\bl() function is similar to p\bpo\bol\bll\bl() except that it specifies the |
| 19431 | timeout using a timespec structure, and a null pointer is used to specify |
| 19432 | an indefinite timeout instead of INFTIM. Also, if _\bm_\ba_\bs_\bk is a non-null |
| 19433 | pointer, p\bpp\bpo\bol\bll\bl() atomically sets the calling thread's signal mask to the |
| 19434 | signal set pointed to by _\bm_\ba_\bs_\bk for the duration of the function call. In |
| 19435 | this case, the original signal mask will be restored before p\bpp\bpo\bol\bll\bl() |
| 19436 | returns. |
| 19437 | |
| 19438 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 19439 | Upon error, p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() return -1 and set the global variable |
| 19440 | _\be_\br_\br_\bn_\bo to indicate the error. If the timeout interval was reached before |
| 19441 | any events occurred, they return 0. Otherwise, they return the number of |
| 19442 | _\bp_\bo_\bl_\bl_\bf_\bd structures for which _\br_\be_\bv_\be_\bn_\bt_\bs is non-zero. |
| 19443 | |
| 19444 | I\bID\bDI\bIO\bOM\bMS\bS |
| 19445 | Care must be taken when converting code from select(2) to p\bpo\bol\bll\bl() as they |
| 19446 | have slightly different semantics. The first semantic difference is |
| 19447 | that, unlike select(2), p\bpo\bol\bll\bl() has a way of indicating that one or more |
| 19448 | file descriptors is invalid by setting a flag in the _\br_\be_\bv_\be_\bn_\bt_\bs field of |
| 19449 | corresponding entry of _\bf_\bd_\bs, whereas select(2) returns an error (-1) if |
| 19450 | any of the descriptors with bits set in the _\bf_\bd_\b__\bs_\be_\bt are invalid. The |
| 19451 | second difference is that on EOF there is no guarantee that POLLIN will |
| 19452 | be set in _\br_\be_\bv_\be_\bn_\bt_\bs, the caller must also check for POLLHUP. This differs |
| 19453 | from select(2) where EOF is considered as a read event. |
| 19454 | |
| 19455 | Consider the following usage of select(2) that implements a read from the |
| 19456 | standard input with a 60 second time out: |
| 19457 | |
| 19458 | struct timeval timeout; |
| 19459 | fd_set readfds; |
| 19460 | char buf[BUFSIZ]; |
| 19461 | int nready; |
| 19462 | |
| 19463 | timeout.tv_sec = 60; |
| 19464 | timeout.tv_usec = 0; |
| 19465 | FD_ZERO(&readfds); |
| 19466 | FD_SET(STDIN_FILENO); |
| 19467 | nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); |
| 19468 | if (nready == -1) |
| 19469 | err(1, "select"); |
| 19470 | if (nready == 0) |
| 19471 | errx(1, "time out"); |
| 19472 | if (FD_ISSET(STDIN_FILENO, &readfds)) { |
| 19473 | if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) |
| 19474 | err(1, "read"); |
| 19475 | } |
| 19476 | |
| 19477 | This can be converted to p\bpo\bol\bll\bl() as follows: |
| 19478 | |
| 19479 | struct pollfd pdf[1]; |
| 19480 | char buf[BUFSIZ]; |
| 19481 | int nready; |
| 19482 | |
| 19483 | pfd[0].fd = STDIN_FILENO; |
| 19484 | pfd[0].events = POLLIN; |
| 19485 | nready = poll(pfd, 1, 60 * 1000); |
| 19486 | if (nready == -1) |
| 19487 | err(1, "poll"); |
| 19488 | if (nready == 0) |
| 19489 | errx(1, "time out"); |
| 19490 | if ((pfd[0].revents & (POLLERR|POLLNVAL))) |
| 19491 | errx(1, "bad fd %d", pfd[0].fd); |
| 19492 | if ((pfd[0].revents & (POLLIN|POLLHUP))) |
| 19493 | if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) |
| 19494 | err(1, "read"); |
| 19495 | } |
| 19496 | |
| 19497 | E\bER\bRR\bRO\bOR\bRS\bS |
| 19498 | p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() will fail if: |
| 19499 | |
| 19500 | [EFAULT] _\bf_\bd_\bs points outside the process's allocated address |
| 19501 | space. |
| 19502 | |
| 19503 | [EINTR] A signal was caught before any polled events occurred |
| 19504 | and before the timeout elapsed. |
| 19505 | |
| 19506 | [EINVAL] _\bn_\bf_\bd_\bs was greater than the number of available file |
| 19507 | descriptors. |
| 19508 | |
| 19509 | [EINVAL] The timeout passed was invalid. |
| 19510 | |
| 19511 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 19512 | clock_gettime(2), getrlimit(2), read(2), select(2), write(2) |
| 19513 | |
| 19514 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 19515 | The p\bpo\bol\bll\bl() function is compliant with the IEEE Std 1003.1-2008 |
| 19516 | (``POSIX.1'') specification. The p\bpp\bpo\bol\bll\bl() function is a Linux extension. |
| 19517 | |
| 19518 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 19519 | A p\bpo\bol\bll\bl() system call appeared in AT&T System V Release 3 UNIX. The |
| 19520 | p\bpp\bpo\bol\bll\bl() function appeared in OpenBSD 5.4. |
| 19521 | |
| 19522 | B\bBU\bUG\bGS\bS |
| 19523 | The POLLWRBAND flag is accepted but ignored by the kernel. |
| 19524 | |
| 19525 | Because OpenBSD does not implement STREAMS, there is no distinction |
| 19526 | between some of the fields in the _\be_\bv_\be_\bn_\bt_\bs and _\br_\be_\bv_\be_\bn_\bt_\bs bitmasks. As a |
| 19527 | result, the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent. |
| 19528 | |
| 19529 | Internally to the kernel, p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() work poorly if multiple |
| 19530 | processes wait on the same file descriptor. |
| 19531 | |
| 19532 | N\bNA\bAM\bME\bE |
| 19533 | m\bma\bad\bdv\bvi\bis\bse\be, p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be - give advice about use of memory |
| 19534 | |
| 19535 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 19536 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
| 19537 | |
| 19538 | _\bi_\bn_\bt |
| 19539 | m\bma\bad\bdv\bvi\bis\bse\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bb_\be_\bh_\ba_\bv); |
| 19540 | |
| 19541 | _\bi_\bn_\bt |
| 19542 | p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bb_\be_\bh_\ba_\bv); |
| 19543 | |
| 19544 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 19545 | The m\bma\bad\bdv\bvi\bis\bse\be() system call allows a process that has knowledge of its |
| 19546 | memory behavior to describe it to the system. The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() |
| 19547 | interface has the same effect, but returns the error value instead of |
| 19548 | only setting _\be_\br_\br_\bn_\bo. |
| 19549 | |
| 19550 | The possible behaviors are: |
| 19551 | |
| 19552 | MADV_NORMAL No further special treatment needed. |
| 19553 | |
| 19554 | MADV_RANDOM Expect random page access patterns. |
| 19555 | |
| 19556 | MADV_SEQUENTIAL Expect sequential page references. |
| 19557 | |
| 19558 | MADV_WILLNEED The pages will be referenced soon. |
| 19559 | |
| 19560 | MADV_DONTNEED The pages will not be referenced soon. |
| 19561 | |
| 19562 | MADV_SPACEAVAIL Ensure that resources are reserved. |
| 19563 | |
| 19564 | MADV_FREE The pages don't contain any useful data and can be |
| 19565 | recycled. |
| 19566 | |
| 19567 | Portable programs that call the p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() interface should use the |
| 19568 | aliases POSIX_MADV_NORMAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, |
| 19569 | POSIX_MADV_WILLNEED, and POSIX_MADV_DONTNEED rather than the flags |
| 19570 | described above. |
| 19571 | |
| 19572 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 19573 | The m\bma\bad\bdv\bvi\bis\bse\be() function returns the value 0 if successful; otherwise the |
| 19574 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 19575 | error. |
| 19576 | |
| 19577 | If successful, the p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() function will return zero. Otherwise |
| 19578 | an error number will be returned to indicate the error. |
| 19579 | |
| 19580 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 19581 | mincore(2), minherit(2), mprotect(2), msync(2), munmap(2) |
| 19582 | |
| 19583 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 19584 | The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() system call conforms to IEEE Std 1003.1-2008 |
| 19585 | (``POSIX.1''). |
| 19586 | |
| 19587 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 19588 | The m\bma\bad\bdv\bvi\bis\bse\be() function first appeared in 4.4BSD. The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() |
| 19589 | function first appeared in OpenBSD 4.8. |
| 19590 | |
| 19591 | B\bBU\bUG\bGS\bS |
| 19592 | The MADV_WILLNEED behavior is ignored. The MADV_SPACEAVAIL behavior is |
| 19593 | not implemented and will always fail. |
| 19594 | |
| 19595 | N\bNA\bAM\bME\bE |
| 19596 | p\bpo\bol\bll\bl, p\bpp\bpo\bol\bll\bl - synchronous I/O multiplexing |
| 19597 | |
| 19598 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 19599 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<p\bpo\bol\bll\bl.\b.h\bh>\b> |
| 19600 | |
| 19601 | _\bi_\bn_\bt |
| 19602 | p\bpo\bol\bll\bl(_\bs_\bt_\br_\bu_\bc_\bt _\bp_\bo_\bl_\bl_\bf_\bd _\b*_\bf_\bd_\bs, _\bn_\bf_\bd_\bs_\b__\bt _\bn_\bf_\bd_\bs, _\bi_\bn_\bt _\bt_\bi_\bm_\be_\bo_\bu_\bt); |
| 19603 | |
| 19604 | _\bi_\bn_\bt |
| 19605 | p\bpp\bpo\bol\bll\bl(_\bs_\bt_\br_\bu_\bc_\bt _\bp_\bo_\bl_\bl_\bf_\bd _\b*_\bf_\bd_\bs, _\bn_\bf_\bd_\bs_\b__\bt _\bn_\bf_\bd_\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, |
| 19606 | _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bm_\ba_\bs_\bk); |
| 19607 | |
| 19608 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 19609 | p\bpo\bol\bll\bl() provides a mechanism for multiplexing I/O across a set of file |
| 19610 | descriptors. It is similar in function to select(2). Unlike select(2), |
| 19611 | however, it is possible to only pass in data corresponding to the file |
| 19612 | descriptors for which events are wanted. This makes p\bpo\bol\bll\bl() more |
| 19613 | efficient than select(2) in most cases. |
| 19614 | |
| 19615 | The arguments are as follows: |
| 19616 | |
| 19617 | _\bf_\bd_\bs Points to an array of _\bp_\bo_\bl_\bl_\bf_\bd structures, which are defined as: |
| 19618 | |
| 19619 | struct pollfd { |
| 19620 | int fd; |
| 19621 | short events; |
| 19622 | short revents; |
| 19623 | }; |
| 19624 | |
| 19625 | The _\bf_\bd member is an open file descriptor. If _\bf_\bd is -1, the |
| 19626 | _\bp_\bo_\bl_\bl_\bf_\bd structure is considered unused, and _\br_\be_\bv_\be_\bn_\bt_\bs will be |
| 19627 | cleared. |
| 19628 | |
| 19629 | The _\be_\bv_\be_\bn_\bt_\bs and _\br_\be_\bv_\be_\bn_\bt_\bs members are bitmasks of conditions to |
| 19630 | monitor and conditions found, respectively. |
| 19631 | |
| 19632 | _\bn_\bf_\bd_\bs An unsigned integer specifying the number of _\bp_\bo_\bl_\bl_\bf_\bd structures |
| 19633 | in the array. |
| 19634 | |
| 19635 | _\bt_\bi_\bm_\be_\bo_\bu_\bt Maximum interval to wait for the poll to complete, in |
| 19636 | milliseconds. If this value is 0, p\bpo\bol\bll\bl() will return |
| 19637 | immediately. If this value is INFTIM (-1), p\bpo\bol\bll\bl() will block |
| 19638 | indefinitely until a condition is found. |
| 19639 | |
| 19640 | The calling process sets the _\be_\bv_\be_\bn_\bt_\bs bitmask and p\bpo\bol\bll\bl() sets the _\br_\be_\bv_\be_\bn_\bt_\bs |
| 19641 | bitmask. Each call to p\bpo\bol\bll\bl() resets the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask for accuracy. |
| 19642 | The condition flags in the bitmasks are defined as: |
| 19643 | |
| 19644 | POLLIN Data other than high-priority data may be read without |
| 19645 | blocking. |
| 19646 | |
| 19647 | POLLRDNORM Normal data may be read without blocking. |
| 19648 | |
| 19649 | POLLRDBAND Priority data may be read without blocking. |
| 19650 | |
| 19651 | POLLNORM Same as POLLRDNORM. This flag is provided for source code |
| 19652 | compatibility with older programs and should not be used in |
| 19653 | new code. |
| 19654 | |
| 19655 | POLLPRI High-priority data may be read without blocking. |
| 19656 | |
| 19657 | POLLOUT Normal data may be written without blocking. |
| 19658 | |
| 19659 | POLLWRNORM Same as POLLOUT. |
| 19660 | |
| 19661 | POLLWRBAND Priority data may be written. |
| 19662 | |
| 19663 | POLLERR An error has occurred on the device or socket. This flag is |
| 19664 | only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; it is ignored in the |
| 19665 | _\be_\bv_\be_\bn_\bt_\bs member. |
| 19666 | |
| 19667 | POLLHUP The device or socket has been disconnected. This event and |
| 19668 | POLLOUT are mutually-exclusive; a descriptor can never be |
| 19669 | writable if a hangup has occurred. However, this event and |
| 19670 | POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually- |
| 19671 | exclusive. This flag is only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; |
| 19672 | it is ignored in the _\be_\bv_\be_\bn_\bt_\bs member. |
| 19673 | |
| 19674 | POLLNVAL The corresponding file descriptor is invalid. This flag is |
| 19675 | only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; it is ignored in the |
| 19676 | _\be_\bv_\be_\bn_\bt_\bs member. |
| 19677 | |
| 19678 | The significance and semantics of normal, priority, and high-priority |
| 19679 | data are device-specific. |
| 19680 | |
| 19681 | In addition to I/O multiplexing, p\bpo\bol\bll\bl() can be used to generate simple |
| 19682 | timeouts. This functionality may be achieved by passing a null pointer |
| 19683 | for _\bf_\bd_\bs. |
| 19684 | |
| 19685 | The p\bpp\bpo\bol\bll\bl() function is similar to p\bpo\bol\bll\bl() except that it specifies the |
| 19686 | timeout using a timespec structure, and a null pointer is used to specify |
| 19687 | an indefinite timeout instead of INFTIM. Also, if _\bm_\ba_\bs_\bk is a non-null |
| 19688 | pointer, p\bpp\bpo\bol\bll\bl() atomically sets the calling thread's signal mask to the |
| 19689 | signal set pointed to by _\bm_\ba_\bs_\bk for the duration of the function call. In |
| 19690 | this case, the original signal mask will be restored before p\bpp\bpo\bol\bll\bl() |
| 19691 | returns. |
| 19692 | |
| 19693 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 19694 | Upon error, p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() return -1 and set the global variable |
| 19695 | _\be_\br_\br_\bn_\bo to indicate the error. If the timeout interval was reached before |
| 19696 | any events occurred, they return 0. Otherwise, they return the number of |
| 19697 | _\bp_\bo_\bl_\bl_\bf_\bd structures for which _\br_\be_\bv_\be_\bn_\bt_\bs is non-zero. |
| 19698 | |
| 19699 | I\bID\bDI\bIO\bOM\bMS\bS |
| 19700 | Care must be taken when converting code from select(2) to p\bpo\bol\bll\bl() as they |
| 19701 | have slightly different semantics. The first semantic difference is |
| 19702 | that, unlike select(2), p\bpo\bol\bll\bl() has a way of indicating that one or more |
| 19703 | file descriptors is invalid by setting a flag in the _\br_\be_\bv_\be_\bn_\bt_\bs field of |
| 19704 | corresponding entry of _\bf_\bd_\bs, whereas select(2) returns an error (-1) if |
| 19705 | any of the descriptors with bits set in the _\bf_\bd_\b__\bs_\be_\bt are invalid. The |
| 19706 | second difference is that on EOF there is no guarantee that POLLIN will |
| 19707 | be set in _\br_\be_\bv_\be_\bn_\bt_\bs, the caller must also check for POLLHUP. This differs |
| 19708 | from select(2) where EOF is considered as a read event. |
| 19709 | |
| 19710 | Consider the following usage of select(2) that implements a read from the |
| 19711 | standard input with a 60 second time out: |
| 19712 | |
| 19713 | struct timeval timeout; |
| 19714 | fd_set readfds; |
| 19715 | char buf[BUFSIZ]; |
| 19716 | int nready; |
| 19717 | |
| 19718 | timeout.tv_sec = 60; |
| 19719 | timeout.tv_usec = 0; |
| 19720 | FD_ZERO(&readfds); |
| 19721 | FD_SET(STDIN_FILENO); |
| 19722 | nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); |
| 19723 | if (nready == -1) |
| 19724 | err(1, "select"); |
| 19725 | if (nready == 0) |
| 19726 | errx(1, "time out"); |
| 19727 | if (FD_ISSET(STDIN_FILENO, &readfds)) { |
| 19728 | if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) |
| 19729 | err(1, "read"); |
| 19730 | } |
| 19731 | |
| 19732 | This can be converted to p\bpo\bol\bll\bl() as follows: |
| 19733 | |
| 19734 | struct pollfd pdf[1]; |
| 19735 | char buf[BUFSIZ]; |
| 19736 | int nready; |
| 19737 | |
| 19738 | pfd[0].fd = STDIN_FILENO; |
| 19739 | pfd[0].events = POLLIN; |
| 19740 | nready = poll(pfd, 1, 60 * 1000); |
| 19741 | if (nready == -1) |
| 19742 | err(1, "poll"); |
| 19743 | if (nready == 0) |
| 19744 | errx(1, "time out"); |
| 19745 | if ((pfd[0].revents & (POLLERR|POLLNVAL))) |
| 19746 | errx(1, "bad fd %d", pfd[0].fd); |
| 19747 | if ((pfd[0].revents & (POLLIN|POLLHUP))) |
| 19748 | if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) |
| 19749 | err(1, "read"); |
| 19750 | } |
| 19751 | |
| 19752 | E\bER\bRR\bRO\bOR\bRS\bS |
| 19753 | p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() will fail if: |
| 19754 | |
| 19755 | [EFAULT] _\bf_\bd_\bs points outside the process's allocated address |
| 19756 | space. |
| 19757 | |
| 19758 | [EINTR] A signal was caught before any polled events occurred |
| 19759 | and before the timeout elapsed. |
| 19760 | |
| 19761 | [EINVAL] _\bn_\bf_\bd_\bs was greater than the number of available file |
| 19762 | descriptors. |
| 19763 | |
| 19764 | [EINVAL] The timeout passed was invalid. |
| 19765 | |
| 19766 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 19767 | clock_gettime(2), getrlimit(2), read(2), select(2), write(2) |
| 19768 | |
| 19769 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 19770 | The p\bpo\bol\bll\bl() function is compliant with the IEEE Std 1003.1-2008 |
| 19771 | (``POSIX.1'') specification. The p\bpp\bpo\bol\bll\bl() function is a Linux extension. |
| 19772 | |
| 19773 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 19774 | A p\bpo\bol\bll\bl() system call appeared in AT&T System V Release 3 UNIX. The |
| 19775 | p\bpp\bpo\bol\bll\bl() function appeared in OpenBSD 5.4. |
| 19776 | |
| 19777 | B\bBU\bUG\bGS\bS |
| 19778 | The POLLWRBAND flag is accepted but ignored by the kernel. |
| 19779 | |
| 19780 | Because OpenBSD does not implement STREAMS, there is no distinction |
| 19781 | between some of the fields in the _\be_\bv_\be_\bn_\bt_\bs and _\br_\be_\bv_\be_\bn_\bt_\bs bitmasks. As a |
| 19782 | result, the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent. |
| 19783 | |
| 19784 | Internally to the kernel, p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() work poorly if multiple |
| 19785 | processes wait on the same file descriptor. |
| 19786 | |
| 19787 | N\bNA\bAM\bME\bE |
| 19788 | r\bre\bea\bad\bd, r\bre\bea\bad\bdv\bv, p\bpr\bre\bea\bad\bd, p\bpr\bre\bea\bad\bdv\bv - read input |
| 19789 | |
| 19790 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 19791 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 19792 | |
| 19793 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 19794 | r\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 19795 | |
| 19796 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 19797 | p\bpr\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 19798 | |
| 19799 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 19800 | |
| 19801 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 19802 | r\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
| 19803 | |
| 19804 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 19805 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 19806 | |
| 19807 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 19808 | p\bpr\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 19809 | |
| 19810 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 19811 | r\bre\bea\bad\bd() attempts to read _\bn_\bb_\by_\bt_\be_\bs of data from the object referenced by the |
| 19812 | descriptor _\bd into the buffer pointed to by _\bb_\bu_\bf. r\bre\bea\bad\bdv\bv() performs the |
| 19813 | same action, but scatters the input data into the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
| 19814 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
| 19815 | iov[iovcnt-1]. p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() perform the same functions, but read |
| 19816 | from the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the file |
| 19817 | pointer. |
| 19818 | |
| 19819 | For r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
| 19820 | |
| 19821 | struct iovec { |
| 19822 | void *iov_base; |
| 19823 | size_t iov_len; |
| 19824 | }; |
| 19825 | |
| 19826 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
| 19827 | memory where data should be placed. r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will always |
| 19828 | fill an area completely before proceeding to the next. |
| 19829 | |
| 19830 | On objects capable of seeking, the r\bre\bea\bad\bd() starts at a position given by |
| 19831 | the pointer associated with _\bd (see lseek(2)). Upon return from r\bre\bea\bad\bd(), |
| 19832 | the pointer is incremented by the number of bytes actually read. |
| 19833 | |
| 19834 | Objects that are not capable of seeking always read from the current |
| 19835 | position. The value of the pointer associated with such an object is |
| 19836 | undefined. |
| 19837 | |
| 19838 | Upon successful completion, r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() return |
| 19839 | the number of bytes actually read and placed in the buffer. The system |
| 19840 | guarantees to read the number of bytes requested if the descriptor |
| 19841 | references a normal file that has that many bytes left before the end-of- |
| 19842 | file, but in no other case. |
| 19843 | |
| 19844 | Note that r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
| 19845 | the constant IOV_MAX. |
| 19846 | |
| 19847 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 19848 | If successful, the number of bytes actually read is returned. Upon |
| 19849 | reading end-of-file, zero is returned. Otherwise, a -1 is returned and |
| 19850 | the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 19851 | |
| 19852 | E\bER\bRR\bRO\bOR\bRS\bS |
| 19853 | r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() will succeed unless: |
| 19854 | |
| 19855 | [EBADF] _\bd is not a valid file or socket descriptor open for |
| 19856 | reading. |
| 19857 | |
| 19858 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 19859 | address space. |
| 19860 | |
| 19861 | [EIO] An I/O error occurred while reading from the file |
| 19862 | system. |
| 19863 | |
| 19864 | [EINTR] A read from a slow device (i.e. one that might block |
| 19865 | for an arbitrary amount of time) was interrupted by |
| 19866 | the delivery of a signal before any data arrived. |
| 19867 | |
| 19868 | In addition, r\bre\bea\bad\bd() and r\bre\bea\bad\bdv\bv() may return the following errors: |
| 19869 | |
| 19870 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
| 19871 | were ready to be read. |
| 19872 | |
| 19873 | [ENOTCONN] The file is a socket associated with a connection- |
| 19874 | oriented protocol and has not been connected. |
| 19875 | |
| 19876 | [EIO] The process is a member of a background process |
| 19877 | attempting to read from its controlling terminal, the |
| 19878 | process is ignoring or blocking the SIGTTIN signal or |
| 19879 | the process group is orphaned. |
| 19880 | |
| 19881 | r\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bd() may return the following error: |
| 19882 | |
| 19883 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
| 19884 | |
| 19885 | p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() may return the following errors: |
| 19886 | |
| 19887 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
| 19888 | |
| 19889 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
| 19890 | |
| 19891 | r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() may return one of the following errors: |
| 19892 | |
| 19893 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
| 19894 | IOV_MAX. |
| 19895 | |
| 19896 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
| 19897 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 19898 | |
| 19899 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
| 19900 | address space. |
| 19901 | |
| 19902 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 19903 | dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), |
| 19904 | socketpair(2) |
| 19905 | |
| 19906 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 19907 | The r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), and p\bpr\bre\bea\bad\bd() functions conform to IEEE Std |
| 19908 | 1003.1-2008 (``POSIX.1''). |
| 19909 | |
| 19910 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 19911 | A r\bre\bea\bad\bd() system call first appeared in Version 1 AT&T UNIX; r\bre\bea\bad\bdv\bv() in |
| 19912 | 4.1cBSD; p\bpr\bre\bea\bad\bd() in AT&T System V Release 4 UNIX; and p\bpr\bre\bea\bad\bdv\bv() in |
| 19913 | OpenBSD 2.7. |
| 19914 | |
| 19915 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 19916 | Error checks should explicitly test for -1. Code such as |
| 19917 | |
| 19918 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
| 19919 | |
| 19920 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
| 19921 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
| 19922 | error-free r\bre\bea\bad\bd() may appear as a negative number distinct from -1. |
| 19923 | Proper loops should use |
| 19924 | |
| 19925 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
| 19926 | |
| 19927 | N\bNA\bAM\bME\bE |
| 19928 | r\bre\bea\bad\bd, r\bre\bea\bad\bdv\bv, p\bpr\bre\bea\bad\bd, p\bpr\bre\bea\bad\bdv\bv - read input |
| 19929 | |
| 19930 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 19931 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 19932 | |
| 19933 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 19934 | r\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 19935 | |
| 19936 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 19937 | p\bpr\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 19938 | |
| 19939 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 19940 | |
| 19941 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 19942 | r\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
| 19943 | |
| 19944 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 19945 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 19946 | |
| 19947 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 19948 | p\bpr\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 19949 | |
| 19950 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 19951 | r\bre\bea\bad\bd() attempts to read _\bn_\bb_\by_\bt_\be_\bs of data from the object referenced by the |
| 19952 | descriptor _\bd into the buffer pointed to by _\bb_\bu_\bf. r\bre\bea\bad\bdv\bv() performs the |
| 19953 | same action, but scatters the input data into the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
| 19954 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
| 19955 | iov[iovcnt-1]. p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() perform the same functions, but read |
| 19956 | from the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the file |
| 19957 | pointer. |
| 19958 | |
| 19959 | For r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
| 19960 | |
| 19961 | struct iovec { |
| 19962 | void *iov_base; |
| 19963 | size_t iov_len; |
| 19964 | }; |
| 19965 | |
| 19966 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
| 19967 | memory where data should be placed. r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will always |
| 19968 | fill an area completely before proceeding to the next. |
| 19969 | |
| 19970 | On objects capable of seeking, the r\bre\bea\bad\bd() starts at a position given by |
| 19971 | the pointer associated with _\bd (see lseek(2)). Upon return from r\bre\bea\bad\bd(), |
| 19972 | the pointer is incremented by the number of bytes actually read. |
| 19973 | |
| 19974 | Objects that are not capable of seeking always read from the current |
| 19975 | position. The value of the pointer associated with such an object is |
| 19976 | undefined. |
| 19977 | |
| 19978 | Upon successful completion, r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() return |
| 19979 | the number of bytes actually read and placed in the buffer. The system |
| 19980 | guarantees to read the number of bytes requested if the descriptor |
| 19981 | references a normal file that has that many bytes left before the end-of- |
| 19982 | file, but in no other case. |
| 19983 | |
| 19984 | Note that r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
| 19985 | the constant IOV_MAX. |
| 19986 | |
| 19987 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 19988 | If successful, the number of bytes actually read is returned. Upon |
| 19989 | reading end-of-file, zero is returned. Otherwise, a -1 is returned and |
| 19990 | the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 19991 | |
| 19992 | E\bER\bRR\bRO\bOR\bRS\bS |
| 19993 | r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() will succeed unless: |
| 19994 | |
| 19995 | [EBADF] _\bd is not a valid file or socket descriptor open for |
| 19996 | reading. |
| 19997 | |
| 19998 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 19999 | address space. |
| 20000 | |
| 20001 | [EIO] An I/O error occurred while reading from the file |
| 20002 | system. |
| 20003 | |
| 20004 | [EINTR] A read from a slow device (i.e. one that might block |
| 20005 | for an arbitrary amount of time) was interrupted by |
| 20006 | the delivery of a signal before any data arrived. |
| 20007 | |
| 20008 | In addition, r\bre\bea\bad\bd() and r\bre\bea\bad\bdv\bv() may return the following errors: |
| 20009 | |
| 20010 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
| 20011 | were ready to be read. |
| 20012 | |
| 20013 | [ENOTCONN] The file is a socket associated with a connection- |
| 20014 | oriented protocol and has not been connected. |
| 20015 | |
| 20016 | [EIO] The process is a member of a background process |
| 20017 | attempting to read from its controlling terminal, the |
| 20018 | process is ignoring or blocking the SIGTTIN signal or |
| 20019 | the process group is orphaned. |
| 20020 | |
| 20021 | r\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bd() may return the following error: |
| 20022 | |
| 20023 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
| 20024 | |
| 20025 | p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() may return the following errors: |
| 20026 | |
| 20027 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
| 20028 | |
| 20029 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
| 20030 | |
| 20031 | r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() may return one of the following errors: |
| 20032 | |
| 20033 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
| 20034 | IOV_MAX. |
| 20035 | |
| 20036 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
| 20037 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 20038 | |
| 20039 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
| 20040 | address space. |
| 20041 | |
| 20042 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 20043 | dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), |
| 20044 | socketpair(2) |
| 20045 | |
| 20046 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 20047 | The r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), and p\bpr\bre\bea\bad\bd() functions conform to IEEE Std |
| 20048 | 1003.1-2008 (``POSIX.1''). |
| 20049 | |
| 20050 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 20051 | A r\bre\bea\bad\bd() system call first appeared in Version 1 AT&T UNIX; r\bre\bea\bad\bdv\bv() in |
| 20052 | 4.1cBSD; p\bpr\bre\bea\bad\bd() in AT&T System V Release 4 UNIX; and p\bpr\bre\bea\bad\bdv\bv() in |
| 20053 | OpenBSD 2.7. |
| 20054 | |
| 20055 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 20056 | Error checks should explicitly test for -1. Code such as |
| 20057 | |
| 20058 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
| 20059 | |
| 20060 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
| 20061 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
| 20062 | error-free r\bre\bea\bad\bd() may appear as a negative number distinct from -1. |
| 20063 | Proper loops should use |
| 20064 | |
| 20065 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
| 20066 | |
| 20067 | N\bNA\bAM\bME\bE |
| 20068 | p\bpr\bro\bof\bfi\bil\bl - control process profiling |
| 20069 | |
| 20070 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 20071 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 20072 | |
| 20073 | _\bi_\bn_\bt |
| 20074 | p\bpr\bro\bof\bfi\bil\bl(_\bc_\bh_\ba_\br _\b*_\bs_\ba_\bm_\bp_\bl_\be_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bs_\bi_\bz_\be, _\bu_\b__\bl_\bo_\bn_\bg _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt _\bs_\bc_\ba_\bl_\be); |
| 20075 | |
| 20076 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 20077 | The p\bpr\bro\bof\bfi\bil\bl() function enables or disables program counter profiling of |
| 20078 | the current process. If profiling is enabled, then at every clock tick, |
| 20079 | the kernel updates an appropriate count in the _\bs_\ba_\bm_\bp_\bl_\be_\bs buffer. |
| 20080 | |
| 20081 | The buffer _\bs_\ba_\bm_\bp_\bl_\be_\bs contains _\bs_\bi_\bz_\be bytes and is divided into a series of |
| 20082 | 16-bit bins. Each bin counts the number of times the program counter was |
| 20083 | in a particular address range in the process when a clock tick occurred |
| 20084 | while profiling was enabled. For a given program counter address, the |
| 20085 | number of the corresponding bin is given by the relation: |
| 20086 | |
| 20087 | [(pc - offset) / 2] * scale / 65536 |
| 20088 | |
| 20089 | The _\bo_\bf_\bf_\bs_\be_\bt parameter is the lowest address at which the kernel takes |
| 20090 | program counter samples. The _\bs_\bc_\ba_\bl_\be parameter ranges from 1 to 65536 and |
| 20091 | can be used to change the span of the bins. A scale of 65536 maps each |
| 20092 | bin to 2 bytes of address range; a scale of 32768 gives 4 bytes, 16384 |
| 20093 | gives 8 bytes and so on. Intermediate values provide approximate |
| 20094 | intermediate ranges. A _\bs_\bc_\ba_\bl_\be value of 0 disables profiling. |
| 20095 | |
| 20096 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 20097 | If the _\bs_\bc_\ba_\bl_\be value is nonzero and the buffer _\bs_\ba_\bm_\bp_\bl_\be_\bs contains an illegal |
| 20098 | address, p\bpr\bro\bof\bfi\bil\bl() returns -1, profiling is terminated, and _\be_\br_\br_\bn_\bo is set |
| 20099 | appropriately. Otherwise, p\bpr\bro\bof\bfi\bil\bl() returns 0. |
| 20100 | |
| 20101 | F\bFI\bIL\bLE\bES\bS |
| 20102 | _\b/_\bu_\bs_\br_\b/_\bl_\bi_\bb_\b/_\bg_\bc_\br_\bt_\b0_\b._\bo profiling C run-time startup file |
| 20103 | _\bg_\bm_\bo_\bn_\b._\bo_\bu_\bt conventional name for profiling output file |
| 20104 | |
| 20105 | E\bER\bRR\bRO\bOR\bRS\bS |
| 20106 | The following error may be reported: |
| 20107 | |
| 20108 | [EFAULT] The buffer _\bs_\ba_\bm_\bp_\bl_\be_\bs contains an invalid address. |
| 20109 | |
| 20110 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 20111 | gprof(1) |
| 20112 | |
| 20113 | B\bBU\bUG\bGS\bS |
| 20114 | This routine should be named p\bpr\bro\bof\bfi\bil\ble\be(). |
| 20115 | |
| 20116 | The _\bs_\ba_\bm_\bp_\bl_\be_\bs argument should really be a vector of type _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bs_\bh_\bo_\br_\bt. |
| 20117 | |
| 20118 | The format of the gmon.out file is undocumented. |
| 20119 | |
| 20120 | N\bNA\bAM\bME\bE |
| 20121 | s\bse\bel\ble\bec\bct\bt, p\bps\bse\bel\ble\bec\bct\bt - synchronous I/O multiplexing |
| 20122 | |
| 20123 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 20124 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bel\ble\bec\bct\bt.\b.h\bh>\b> |
| 20125 | |
| 20126 | _\bi_\bn_\bt |
| 20127 | s\bse\bel\ble\bec\bct\bt(_\bi_\bn_\bt _\bn_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\br_\be_\ba_\bd_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs, |
| 20128 | _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
| 20129 | |
| 20130 | _\bi_\bn_\bt |
| 20131 | p\bps\bse\bel\ble\bec\bct\bt(_\bi_\bn_\bt _\bn_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\br_\be_\ba_\bd_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs, |
| 20132 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bm_\ba_\bs_\bk); |
| 20133 | |
| 20134 | F\bFD\bD_\b_S\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
| 20135 | |
| 20136 | F\bFD\bD_\b_C\bCL\bLR\bR(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
| 20137 | |
| 20138 | F\bFD\bD_\b_I\bIS\bSS\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
| 20139 | |
| 20140 | F\bFD\bD_\b_Z\bZE\bER\bRO\bO(_\b&_\bf_\bd_\bs_\be_\bt); |
| 20141 | |
| 20142 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 20143 | s\bse\bel\ble\bec\bct\bt() examines the I/O descriptor sets whose addresses are passed in |
| 20144 | _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, and _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs to see if some of their descriptors are |
| 20145 | ready for reading, are ready for writing, or have an exceptional |
| 20146 | condition pending, respectively. The first _\bn_\bf_\bd_\bs descriptors are checked |
| 20147 | in each set; i.e., the descriptors from 0 through _\bn_\bf_\bd_\bs-1 in the |
| 20148 | descriptor sets are examined. On return, s\bse\bel\ble\bec\bct\bt() replaces the given |
| 20149 | descriptor sets with subsets consisting of those descriptors that are |
| 20150 | ready for the requested operation. s\bse\bel\ble\bec\bct\bt() returns the total number of |
| 20151 | ready descriptors in all the sets. |
| 20152 | |
| 20153 | The descriptor sets are stored as bit fields in arrays of integers. The |
| 20154 | following macros are provided for manipulating such descriptor sets: |
| 20155 | F\bFD\bD_\b_Z\bZE\bER\bRO\bO(_\b&_\bf_\bd_\bs_\be_\bt) initializes a descriptor set _\bf_\bd_\bs_\be_\bt to the null set. |
| 20156 | F\bFD\bD_\b_S\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) includes a particular descriptor _\bf_\bd in _\bf_\bd_\bs_\be_\bt. |
| 20157 | F\bFD\bD_\b_C\bCL\bLR\bR(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) removes _\bf_\bd from _\bf_\bd_\bs_\be_\bt. F\bFD\bD_\b_I\bIS\bSS\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) is non- |
| 20158 | zero if _\bf_\bd is a member of _\bf_\bd_\bs_\be_\bt, zero otherwise. The behavior of these |
| 20159 | macros is undefined if a descriptor value is less than zero or greater |
| 20160 | than or equal to FD_SETSIZE, which is normally at least equal to the |
| 20161 | maximum number of descriptors supported by the system. |
| 20162 | |
| 20163 | If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it specifies a maximum interval to wait |
| 20164 | for the selection to complete. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, the select |
| 20165 | blocks indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
| 20166 | non-null, pointing to a zero-valued timeval structure. _\bt_\bi_\bm_\be_\bo_\bu_\bt is not |
| 20167 | changed by s\bse\bel\ble\bec\bct\bt(), and may be reused on subsequent calls; however, it |
| 20168 | is good style to re-initialize it before each invocation of s\bse\bel\ble\bec\bct\bt(). |
| 20169 | |
| 20170 | Any of _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, and _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs may be given as null pointers if |
| 20171 | no descriptors are of interest. |
| 20172 | |
| 20173 | The p\bps\bse\bel\ble\bec\bct\bt() function is similar to s\bse\bel\ble\bec\bct\bt() except that it specifies |
| 20174 | the timeout using a timespec structure. Also, if _\bm_\ba_\bs_\bk is a non-null |
| 20175 | pointer, p\bps\bse\bel\ble\bec\bct\bt() atomically sets the calling thread's signal mask to |
| 20176 | the signal set pointed to by _\bm_\ba_\bs_\bk for the duration of the function call. |
| 20177 | In this case, the original signal mask will be restored before p\bps\bse\bel\ble\bec\bct\bt() |
| 20178 | returns. |
| 20179 | |
| 20180 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 20181 | If successful, s\bse\bel\ble\bec\bct\bt() and p\bps\bse\bel\ble\bec\bct\bt() return the number of ready |
| 20182 | descriptors that are contained in the descriptor sets. If a descriptor |
| 20183 | is included in multiple descriptor sets, each inclusion is counted |
| 20184 | separately. If the time limit expires before any descriptors become |
| 20185 | ready, they return 0. |
| 20186 | |
| 20187 | Otherwise, if s\bse\bel\ble\bec\bct\bt() or p\bps\bse\bel\ble\bec\bct\bt() return with an error, including one |
| 20188 | due to an interrupted call, they return -1, and the descriptor sets will |
| 20189 | be unmodified. |
| 20190 | |
| 20191 | E\bER\bRR\bRO\bOR\bRS\bS |
| 20192 | An error return from s\bse\bel\ble\bec\bct\bt() or p\bps\bse\bel\ble\bec\bct\bt() indicates: |
| 20193 | |
| 20194 | [EFAULT] One or more of _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, or _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs points |
| 20195 | outside the process's allocated address space. |
| 20196 | |
| 20197 | [EBADF] One of the descriptor sets specified an invalid |
| 20198 | descriptor. |
| 20199 | |
| 20200 | [EINTR] A signal was delivered before the time limit expired |
| 20201 | and before any of the selected descriptors became |
| 20202 | ready. |
| 20203 | |
| 20204 | [EINVAL] The specified time limit is invalid. One of its |
| 20205 | components is negative or too large. |
| 20206 | |
| 20207 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 20208 | accept(2), clock_gettime(2), connect(2), gettimeofday(2), poll(2), |
| 20209 | read(2), recv(2), send(2), write(2), getdtablesize(3) |
| 20210 | |
| 20211 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 20212 | The s\bse\bel\ble\bec\bct\bt() system call first appeared in 4.1cBSD. The p\bps\bse\bel\ble\bec\bct\bt() system |
| 20213 | call has been available since OpenBSD 5.4. |
| 20214 | |
| 20215 | B\bBU\bUG\bGS\bS |
| 20216 | Although the provision of getdtablesize(3) was intended to allow user |
| 20217 | programs to be written independent of the kernel limit on the number of |
| 20218 | open files, the dimension of a sufficiently large bit field for select |
| 20219 | remains a problem. The default bit size of _\bf_\bd_\b__\bs_\be_\bt is based on the symbol |
| 20220 | FD_SETSIZE (currently 1024), but that is somewhat smaller than the |
| 20221 | current kernel limit to the number of open files. However, in order to |
| 20222 | accommodate programs which might potentially use a larger number of open |
| 20223 | files with select, it is possible to increase this size within a program |
| 20224 | by providing a larger definition of FD_SETSIZE before the inclusion of |
| 20225 | any headers. The kernel will cope, and the userland libraries provided |
| 20226 | with the system are also ready for large numbers of file descriptors. |
| 20227 | |
| 20228 | Alternatively, to be really safe, it is possible to allocate _\bf_\bd_\b__\bs_\be_\bt bit- |
| 20229 | arrays dynamically. The idea is to permit a program to work properly |
| 20230 | even if it is execve(2)'d with 4000 file descriptors pre-allocated. The |
| 20231 | following illustrates the technique which is used by userland libraries: |
| 20232 | |
| 20233 | fd_set *fdsr; |
| 20234 | int max = fd; |
| 20235 | |
| 20236 | fdsr = calloc(howmany(max+1, NFDBITS), sizeof(fd_mask)); |
| 20237 | if (fdsr == NULL) { |
| 20238 | ... |
| 20239 | return (-1); |
| 20240 | } |
| 20241 | FD_SET(fd, fdsr); |
| 20242 | n = select(max+1, fdsr, NULL, NULL, &tv); |
| 20243 | ... |
| 20244 | free(fdsr); |
| 20245 | |
| 20246 | Alternatively, it is possible to use the poll(2) interface. poll(2) is |
| 20247 | more efficient when the size of s\bse\bel\ble\bec\bct\bt()'s _\bf_\bd_\b__\bs_\be_\bt bit-arrays are very |
| 20248 | large, and for fixed numbers of file descriptors one need not size and |
| 20249 | dynamically allocate a memory object. |
| 20250 | |
| 20251 | s\bse\bel\ble\bec\bct\bt() should probably have been designed to return the time remaining |
| 20252 | from the original timeout, if any, by modifying the time value in place. |
| 20253 | Even though some systems stupidly act in this different way, it is |
| 20254 | unlikely this semantic will ever be commonly implemented, as the change |
| 20255 | causes massive source code compatibility problems. Furthermore, recent |
| 20256 | new standards have dictated the current behaviour. In general, due to |
| 20257 | the existence of those brain-damaged non-conforming systems, it is unwise |
| 20258 | to assume that the timeout value will be unmodified by the s\bse\bel\ble\bec\bct\bt() call, |
| 20259 | and the caller should reinitialize it on each invocation. Calculating |
| 20260 | the delta is easily done by calling gettimeofday(2) before and after the |
| 20261 | call to s\bse\bel\ble\bec\bct\bt(), and using t\bti\bim\bme\ber\brs\bsu\bub\bb() (as described in getitimer(2)). |
| 20262 | |
| 20263 | Internally to the kernel, s\bse\bel\ble\bec\bct\bt() and p\bps\bse\bel\ble\bec\bct\bt() work poorly if multiple |
| 20264 | processes wait on the same file descriptor. Given that, it is rather |
| 20265 | surprising to see that many daemons are written that way. |
| 20266 | |
| 20267 | N\bNA\bAM\bME\bE |
| 20268 | p\bpt\btr\bra\bac\bce\be - process tracing and debugging |
| 20269 | |
| 20270 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 20271 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 20272 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpt\btr\bra\bac\bce\be.\b.h\bh>\b> |
| 20273 | |
| 20274 | _\bi_\bn_\bt |
| 20275 | p\bpt\btr\bra\bac\bce\be(_\bi_\bn_\bt _\br_\be_\bq_\bu_\be_\bs_\bt, _\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bc_\ba_\bd_\bd_\br_\b__\bt _\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bd_\ba_\bt_\ba); |
| 20276 | |
| 20277 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 20278 | p\bpt\btr\bra\bac\bce\be() provides tracing and debugging facilities. It allows one |
| 20279 | process (the _\bt_\br_\ba_\bc_\bi_\bn_\bg process) to control another (the _\bt_\br_\ba_\bc_\be_\bd process). |
| 20280 | Most of the time, the traced process runs normally, but when it receives |
| 20281 | a signal (see sigaction(2)), it stops. The tracing process is expected |
| 20282 | to notice this via wait(2) or the delivery of a SIGCHLD signal, examine |
| 20283 | the state of the stopped process, and cause it to terminate or continue |
| 20284 | as appropriate. p\bpt\btr\bra\bac\bce\be() is the mechanism by which all this happens. |
| 20285 | p\bpt\btr\bra\bac\bce\be() is only available on kernels compiled with the P\bPT\bTR\bRA\bAC\bCE\bE option. |
| 20286 | |
| 20287 | The _\br_\be_\bq_\bu_\be_\bs_\bt argument specifies what operation is being performed; the |
| 20288 | meaning of the rest of the arguments depends on the operation, but except |
| 20289 | for one special case noted below, all p\bpt\btr\bra\bac\bce\be() calls are made by the |
| 20290 | tracing process, and the _\bp_\bi_\bd argument specifies the process ID of the |
| 20291 | traced process. _\br_\be_\bq_\bu_\be_\bs_\bt can be: |
| 20292 | |
| 20293 | PT_TRACE_ME This request is the only one used by the traced process; it |
| 20294 | declares that the process expects to be traced by its |
| 20295 | parent. All the other arguments are ignored. (If the |
| 20296 | parent process does not expect to trace the child, it will |
| 20297 | probably be rather confused by the results; once the traced |
| 20298 | process stops, it cannot be made to continue except via |
| 20299 | p\bpt\btr\bra\bac\bce\be().) When a process has used this request and calls |
| 20300 | execve(2) or any of the routines built on it (such as |
| 20301 | execv(3)), it will stop before executing the first |
| 20302 | instruction of the new image. Also, any setuid or setgid |
| 20303 | bits on the executable being executed will be ignored. |
| 20304 | |
| 20305 | PT_READ_I, PT_READ_D |
| 20306 | These requests read a single int of data from the traced |
| 20307 | process' address space. Traditionally, p\bpt\btr\bra\bac\bce\be() has |
| 20308 | allowed for machines with distinct address spaces for |
| 20309 | instruction and data, which is why there are two requests: |
| 20310 | conceptually, PT_READ_I reads from the instruction space |
| 20311 | and PT_READ_D reads from the data space. In the current |
| 20312 | OpenBSD implementation, these two requests are completely |
| 20313 | identical. The _\ba_\bd_\bd_\br argument specifies the address (in the |
| 20314 | traced process' virtual address space) at which the read is |
| 20315 | to be done. This address does not have to meet any |
| 20316 | alignment constraints. The value read is returned as the |
| 20317 | return value from p\bpt\btr\bra\bac\bce\be(). |
| 20318 | |
| 20319 | PT_WRITE_I, PT_WRITE_D |
| 20320 | These requests parallel PT_READ_I and PT_READ_D, except |
| 20321 | that they write rather than read. The _\bd_\ba_\bt_\ba argument |
| 20322 | supplies the value to be written. |
| 20323 | |
| 20324 | PT_CONTINUE The traced process continues execution. _\ba_\bd_\bd_\br is an address |
| 20325 | specifying the place where execution is to be resumed (a |
| 20326 | new value for the program counter), or (caddr_t)1 to |
| 20327 | indicate that execution is to pick up where it left off. |
| 20328 | _\bd_\ba_\bt_\ba provides a signal number to be delivered to the traced |
| 20329 | process as it resumes execution, or 0 if no signal is to be |
| 20330 | sent. |
| 20331 | |
| 20332 | PT_KILL The traced process terminates, as if PT_CONTINUE had been |
| 20333 | used with SIGKILL given as the signal to be delivered. |
| 20334 | |
| 20335 | PT_ATTACH This request allows a process to gain control of an |
| 20336 | otherwise unrelated process and begin tracing it. It does |
| 20337 | not need any cooperation from the to-be-traced process. In |
| 20338 | this case, _\bp_\bi_\bd specifies the process ID of the to-be-traced |
| 20339 | process, and the other two arguments are ignored. This |
| 20340 | request requires that the target process must have the same |
| 20341 | real UID as the tracing process, and that it must not be |
| 20342 | executing a set-user-ID or set-group-ID executable. |
| 20343 | Additionally, if the kern.global_ptrace sysctl is 0, then |
| 20344 | the target process must be a descendent of the tracing |
| 20345 | process. (If the tracing process is running as root, these |
| 20346 | restrictions do not apply.) The tracing process will see |
| 20347 | the newly traced process stop and may then control it as if |
| 20348 | it had been traced all along. |
| 20349 | |
| 20350 | PT_DETACH This request is like PT_CONTINUE, except that it does not |
| 20351 | allow specifying an alternate place to continue execution, |
| 20352 | and after it succeeds, the traced process is no longer |
| 20353 | traced and continues execution normally. |
| 20354 | |
| 20355 | PT_IO This request is a more general interface that can be used |
| 20356 | instead of PT_READ_D, PT_WRITE_D, PT_READ_I and PT_WRITE_I. |
| 20357 | The I/O request is encoded in a ``struct ptrace_io_desc'' |
| 20358 | defined as: |
| 20359 | |
| 20360 | struct ptrace_io_desc { |
| 20361 | int piod_op; |
| 20362 | void *piod_offs; |
| 20363 | void *piod_addr; |
| 20364 | size_t piod_len; |
| 20365 | }; |
| 20366 | |
| 20367 | Where _\bp_\bi_\bo_\bd_\b__\bo_\bf_\bf_\bs is the offset within the traced process |
| 20368 | where the I/O operation should be made, _\bp_\bi_\bo_\bd_\b__\ba_\bd_\bd_\br is the |
| 20369 | buffer in the parent and _\bp_\bi_\bo_\bd_\b__\bl_\be_\bn is the length of the I/O |
| 20370 | request. The _\bp_\bi_\bo_\bd_\b__\bo_\bp member specifies what operation needs |
| 20371 | to be done. Possible values are: |
| 20372 | |
| 20373 | PIOD_READ_D |
| 20374 | PIOD_WRITE_D |
| 20375 | PIOD_READ_I |
| 20376 | PIOD_WRITE_I |
| 20377 | PIOD_READ_AUXV |
| 20378 | |
| 20379 | See also the description of PT_READ_I for the difference |
| 20380 | between D and I spaces. The PIOD_READ_AUXV operation can |
| 20381 | be used to read from the ELF auxiliary vector. A pointer |
| 20382 | to the descriptor is passed in _\ba_\bd_\bd_\br. On return the |
| 20383 | _\bp_\bi_\bo_\bd_\b__\bl_\be_\bn field in the descriptor will be updated with the |
| 20384 | actual number of bytes transferred. If the requested I/O |
| 20385 | couldn't be successfully performed p\bpt\btr\bra\bac\bce\be() will return -1 |
| 20386 | and set _\be_\br_\br_\bn_\bo. |
| 20387 | |
| 20388 | PT_SET_EVENT_MASK |
| 20389 | This request can be used to specify which events in the |
| 20390 | traced process should be reported to the tracing process. |
| 20391 | These events are specified in a ``struct ptrace_event'' |
| 20392 | defined as: |
| 20393 | |
| 20394 | typedef struct ptrace_event { |
| 20395 | int pe_set_event; |
| 20396 | } ptrace_event_t; |
| 20397 | |
| 20398 | Where _\bp_\be_\b__\bs_\be_\bt_\b__\be_\bv_\be_\bn_\bt is the set of events to be reported. |
| 20399 | This set is formed by OR'ing together the following values: |
| 20400 | |
| 20401 | PTRACE_FORK Report fork(2). |
| 20402 | |
| 20403 | A pointer to this structure is passed in _\ba_\bd_\bd_\br. The _\bd_\ba_\bt_\ba |
| 20404 | argument should be set to sizeof(struct ptrace_event). |
| 20405 | |
| 20406 | PT_GET_EVENT_MASK |
| 20407 | This request can be used to determine which events in the |
| 20408 | traced process will be reported. The information is read |
| 20409 | into the ``struct ptrace_event'' pointed to by _\ba_\bd_\bd_\br. The |
| 20410 | _\bd_\ba_\bt_\ba argument should be set to sizeof(struct ptrace_event). |
| 20411 | |
| 20412 | PT_GET_PROCESS_STATE |
| 20413 | This request reads the state information associated with |
| 20414 | the event that stopped the traced process. The information |
| 20415 | is reported in a ``struct ptrace_state'' defined as: |
| 20416 | |
| 20417 | typedef struct ptrace_state { |
| 20418 | int pe_report_event; |
| 20419 | pid_t pe_other_pid; |
| 20420 | } ptrace_state_t; |
| 20421 | |
| 20422 | Where _\bp_\be_\b__\br_\be_\bp_\bo_\br_\bt_\b__\be_\bv_\be_\bn_\bt is the event being reported. If the |
| 20423 | event being reported is PTRACE_FORK, _\bp_\be_\b__\bo_\bt_\bh_\be_\br_\b__\bp_\bi_\bd will be |
| 20424 | set to the process ID of the other end of the fork. A |
| 20425 | pointer to this structure is passed in _\ba_\bd_\bd_\br. The _\bd_\ba_\bt_\ba |
| 20426 | argument should be set to sizeof(struct ptrace_state). |
| 20427 | |
| 20428 | Additionally, machine-specific requests can exist. Depending on the |
| 20429 | architecture, the following requests may be available under OpenBSD: |
| 20430 | |
| 20431 | PT_GETREGS (all platforms) |
| 20432 | This request reads the traced process' machine registers |
| 20433 | into the ``struct reg'' (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) |
| 20434 | pointed to by _\ba_\bd_\bd_\br. |
| 20435 | |
| 20436 | PT_SETREGS (all platforms) |
| 20437 | This request is the converse of PT_GETREGS; it loads the |
| 20438 | traced process' machine registers from the ``struct reg'' |
| 20439 | (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed to by _\ba_\bd_\bd_\br. |
| 20440 | |
| 20441 | PT_STEP (not available on sparc and sparc64) |
| 20442 | The traced process continues execution, as in request |
| 20443 | PT_CONTINUE; however, execution stops as soon as possible |
| 20444 | after execution of at least one instruction (single-step). |
| 20445 | |
| 20446 | PT_GETFPREGS (not available on aviion, luna88k, sgi and vax) |
| 20447 | This request reads the traced process' floating-point |
| 20448 | registers into the ``struct fpreg'' (defined in |
| 20449 | <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed to by _\ba_\bd_\bd_\br. |
| 20450 | |
| 20451 | PT_SETFPREGS (not available on aviion, luna88k, sgi and vax) |
| 20452 | This request is the converse of PT_GETFPREGS; it loads the |
| 20453 | traced process' floating-point registers from the ``struct |
| 20454 | fpreg'' (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed to by _\ba_\bd_\bd_\br. |
| 20455 | |
| 20456 | PT_GETXMMREGS (i386 only) |
| 20457 | This request reads the traced process' XMM registers into |
| 20458 | the ``struct xmmregs'' (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed |
| 20459 | to by _\ba_\bd_\bd_\br. |
| 20460 | |
| 20461 | PT_SETXMMREGS (i386 only) |
| 20462 | This request is the converse of PT_GETXMMREGS; it loads the |
| 20463 | traced process' XMM registers from the ``struct xmmregs'' |
| 20464 | (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed to by _\ba_\bd_\bd_\br. |
| 20465 | |
| 20466 | PT_WCOOKIE (sparc and sparc64 only) |
| 20467 | This request reads the traced process' `window cookie' into |
| 20468 | the int pointed to by _\ba_\bd_\bd_\br. The window cookie needs to be |
| 20469 | `XOR'ed' to stack-saved program counters. |
| 20470 | |
| 20471 | E\bER\bRR\bRO\bOR\bRS\bS |
| 20472 | Some requests can cause p\bpt\btr\bra\bac\bce\be() to return -1 as a non-error value; to |
| 20473 | disambiguate, _\be_\br_\br_\bn_\bo is set to zero and this should be checked. The |
| 20474 | possible errors are: |
| 20475 | |
| 20476 | [ESRCH] |
| 20477 | No process having the specified process ID exists. |
| 20478 | |
| 20479 | [EINVAL] |
| 20480 | +\b+\bo\bo A process attempted to use PT_ATTACH on itself. |
| 20481 | +\b+\bo\bo The _\br_\be_\bq_\bu_\be_\bs_\bt was not one of the legal requests. |
| 20482 | +\b+\bo\bo The signal number (in _\bd_\ba_\bt_\ba) to PT_CONTINUE was neither 0 nor a |
| 20483 | legal signal number. |
| 20484 | +\b+\bo\bo PT_GETREGS, PT_SETREGS, PT_GETFPREGS, or PT_SETFPREGS was |
| 20485 | attempted on a process with no valid register set. (This is |
| 20486 | normally true only of system processes.) |
| 20487 | |
| 20488 | [EBUSY] |
| 20489 | +\b+\bo\bo PT_ATTACH was attempted on a process that was already being |
| 20490 | traced. |
| 20491 | +\b+\bo\bo A request attempted to manipulate a process that was being |
| 20492 | traced by some process other than the one making the request. |
| 20493 | +\b+\bo\bo A request (other than PT_ATTACH) specified a process that |
| 20494 | wasn't stopped. |
| 20495 | |
| 20496 | [EPERM] |
| 20497 | +\b+\bo\bo A request (other than PT_ATTACH) attempted to manipulate a |
| 20498 | process that wasn't being traced at all. |
| 20499 | +\b+\bo\bo An attempt was made to use PT_ATTACH on a process in violation |
| 20500 | of the requirements listed under PT_ATTACH above. |
| 20501 | +\b+\bo\bo An attempt was made to use PT_ATTACH on a system process. |
| 20502 | |
| 20503 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 20504 | The p\bpt\btr\bra\bac\bce\be() system call first appeared in Version 6 AT&T UNIX. |
| 20505 | |
| 20506 | B\bBU\bUG\bGS\bS |
| 20507 | On several RISC architectures (such as aviion, luna88k, sparc and |
| 20508 | sparc64), the PC is set to the provided PC value for PT_CONTINUE and |
| 20509 | similar calls, and the remainder of the execution pipeline registers are |
| 20510 | set to the following instructions, even if the instruction at PC is a |
| 20511 | branch instruction. Using PT_GETREGS and PT_SETREGS to modify the PC, |
| 20512 | passing (caddr_t)1 to p\bpt\btr\bra\bac\bce\be(), should be able to sidestep this. |
| 20513 | |
| 20514 | N\bNA\bAM\bME\bE |
| 20515 | w\bwr\bri\bit\bte\be, w\bwr\bri\bit\bte\bev\bv, p\bpw\bwr\bri\bit\bte\be, p\bpw\bwr\bri\bit\bte\bev\bv - write output |
| 20516 | |
| 20517 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 20518 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 20519 | |
| 20520 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20521 | w\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 20522 | |
| 20523 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20524 | p\bpw\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 20525 | |
| 20526 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 20527 | |
| 20528 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20529 | w\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
| 20530 | |
| 20531 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 20532 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 20533 | |
| 20534 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20535 | p\bpw\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 20536 | |
| 20537 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 20538 | w\bwr\bri\bit\bte\be() attempts to write _\bn_\bb_\by_\bt_\be_\bs of data to the object referenced by the |
| 20539 | descriptor _\bd from the buffer pointed to by _\bb_\bu_\bf. w\bwr\bri\bit\bte\bev\bv() performs the |
| 20540 | same action, but gathers the output data from the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
| 20541 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
| 20542 | iov[iovcnt-1]. p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() perform the same functions, but |
| 20543 | write to the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the |
| 20544 | file pointer. |
| 20545 | |
| 20546 | For w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
| 20547 | |
| 20548 | struct iovec { |
| 20549 | void *iov_base; |
| 20550 | size_t iov_len; |
| 20551 | }; |
| 20552 | |
| 20553 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
| 20554 | memory from which data should be written. w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will |
| 20555 | always write a complete area before proceeding to the next. |
| 20556 | |
| 20557 | On objects capable of seeking, the w\bwr\bri\bit\bte\be() starts at a position given by |
| 20558 | the pointer associated with _\bd (see lseek(2)). Upon return from w\bwr\bri\bit\bte\be(), |
| 20559 | the pointer is incremented by the number of bytes which were written. If |
| 20560 | a file was opened with the O_APPEND flag (see open(2)), calls to w\bwr\bri\bit\bte\be() |
| 20561 | or w\bwr\bri\bit\bte\bev\bv() will automatically set the pointer to the end of the file |
| 20562 | before writing. |
| 20563 | |
| 20564 | Objects that are not capable of seeking always write from the current |
| 20565 | position. The value of the pointer associated with such an object is |
| 20566 | undefined. |
| 20567 | |
| 20568 | If the real user is not the superuser, then w\bwr\bri\bit\bte\be() clears the set-user- |
| 20569 | ID bit on a file. This prevents penetration of system security by a user |
| 20570 | who ``captures'' a writable set-user-ID file owned by the superuser. |
| 20571 | |
| 20572 | If w\bwr\bri\bit\bte\be() succeeds it will update the st_ctime and st_mtime fields of |
| 20573 | the file's meta-data (see stat(2)). |
| 20574 | |
| 20575 | When using non-blocking I/O on objects such as sockets that are subject |
| 20576 | to flow control, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may write fewer bytes than |
| 20577 | requested; the return value must be noted, and the remainder of the |
| 20578 | operation should be retried when possible. |
| 20579 | |
| 20580 | Note that w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
| 20581 | the constant IOV_MAX. |
| 20582 | |
| 20583 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 20584 | Upon successful completion the number of bytes which were written is |
| 20585 | returned. Otherwise, a -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
| 20586 | set to indicate the error. |
| 20587 | |
| 20588 | E\bER\bRR\bRO\bOR\bRS\bS |
| 20589 | w\bwr\bri\bit\bte\be(), p\bpw\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\bev\bv() will fail and the file pointer |
| 20590 | will remain unchanged if: |
| 20591 | |
| 20592 | [EBADF] _\bd is not a valid descriptor open for writing. |
| 20593 | |
| 20594 | [EFBIG] An attempt was made to write a file that exceeds the |
| 20595 | process's file size limit or the maximum file size. |
| 20596 | |
| 20597 | [ENOSPC] There is no free space remaining on the file system |
| 20598 | containing the file. |
| 20599 | |
| 20600 | [EDQUOT] The user's quota of disk blocks on the file system |
| 20601 | containing the file has been exhausted. |
| 20602 | |
| 20603 | [EINTR] A write to a slow device (i.e. one that might block |
| 20604 | for an arbitrary amount of time) was interrupted by |
| 20605 | the delivery of a signal before any data could be |
| 20606 | written. |
| 20607 | |
| 20608 | [EIO] An I/O error occurred while reading from or writing to |
| 20609 | the file system. |
| 20610 | |
| 20611 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 20612 | address space. |
| 20613 | |
| 20614 | In addition, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may return the following errors: |
| 20615 | |
| 20616 | [EPIPE] An attempt is made to write to a pipe that is not open |
| 20617 | for reading by any process. |
| 20618 | |
| 20619 | [EPIPE] An attempt is made to write to a socket of type |
| 20620 | SOCK_STREAM that is not connected to a peer socket. |
| 20621 | |
| 20622 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
| 20623 | could be written immediately. |
| 20624 | |
| 20625 | [ENETDOWN] The destination address specified a network that is |
| 20626 | down. |
| 20627 | |
| 20628 | [EDESTADDRREQ] The destination is no longer available when writing to |
| 20629 | a UNIX-domain datagram socket on which connect(2) had |
| 20630 | been used to set a destination address. |
| 20631 | |
| 20632 | [EIO] The process is a member of a background process |
| 20633 | attempting to write to its controlling terminal, |
| 20634 | TOSTOP is set on the terminal, the process isn't |
| 20635 | ignoring the SIGTTOUT signal and the thread isn't |
| 20636 | blocking the SIGTTOUT signal, and either the process |
| 20637 | was created with vfork(2) and hasn't successfully |
| 20638 | executed one of the exec functions or the process |
| 20639 | group is orphaned. |
| 20640 | |
| 20641 | w\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\be() may return the following error: |
| 20642 | |
| 20643 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
| 20644 | |
| 20645 | p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() may return the following error: |
| 20646 | |
| 20647 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
| 20648 | |
| 20649 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
| 20650 | |
| 20651 | w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() may return one of the following errors: |
| 20652 | |
| 20653 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
| 20654 | IOV_MAX. |
| 20655 | |
| 20656 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
| 20657 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 20658 | |
| 20659 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
| 20660 | address space. |
| 20661 | |
| 20662 | [ENOBUFS] The system lacked sufficient buffer space or a queue |
| 20663 | was full. |
| 20664 | |
| 20665 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 20666 | fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) |
| 20667 | |
| 20668 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 20669 | The w\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\be() functions conform to IEEE Std |
| 20670 | 1003.1-2008 (``POSIX.1''). |
| 20671 | |
| 20672 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 20673 | The p\bpw\bwr\bri\bit\bte\bev\bv() function call appeared in OpenBSD 2.7. The p\bpw\bwr\bri\bit\bte\be() |
| 20674 | function call appeared in AT&T System V Release 4 UNIX. The w\bwr\bri\bit\bte\bev\bv() |
| 20675 | function call appeared in 4.2BSD. The w\bwr\bri\bit\bte\be() function call appeared in |
| 20676 | Version 2 AT&T UNIX. |
| 20677 | |
| 20678 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 20679 | Error checks should explicitly test for -1. Code such as |
| 20680 | |
| 20681 | while ((nr = write(fd, buf, sizeof(buf))) > 0) |
| 20682 | |
| 20683 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
| 20684 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
| 20685 | error-free w\bwr\bri\bit\bte\be() may appear as a negative number distinct from -1. |
| 20686 | Proper loops should use |
| 20687 | |
| 20688 | while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) |
| 20689 | |
| 20690 | N\bNA\bAM\bME\bE |
| 20691 | w\bwr\bri\bit\bte\be, w\bwr\bri\bit\bte\bev\bv, p\bpw\bwr\bri\bit\bte\be, p\bpw\bwr\bri\bit\bte\bev\bv - write output |
| 20692 | |
| 20693 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 20694 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 20695 | |
| 20696 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20697 | w\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 20698 | |
| 20699 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20700 | p\bpw\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 20701 | |
| 20702 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 20703 | |
| 20704 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20705 | w\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
| 20706 | |
| 20707 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 20708 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 20709 | |
| 20710 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20711 | p\bpw\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 20712 | |
| 20713 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 20714 | w\bwr\bri\bit\bte\be() attempts to write _\bn_\bb_\by_\bt_\be_\bs of data to the object referenced by the |
| 20715 | descriptor _\bd from the buffer pointed to by _\bb_\bu_\bf. w\bwr\bri\bit\bte\bev\bv() performs the |
| 20716 | same action, but gathers the output data from the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
| 20717 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
| 20718 | iov[iovcnt-1]. p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() perform the same functions, but |
| 20719 | write to the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the |
| 20720 | file pointer. |
| 20721 | |
| 20722 | For w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
| 20723 | |
| 20724 | struct iovec { |
| 20725 | void *iov_base; |
| 20726 | size_t iov_len; |
| 20727 | }; |
| 20728 | |
| 20729 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
| 20730 | memory from which data should be written. w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will |
| 20731 | always write a complete area before proceeding to the next. |
| 20732 | |
| 20733 | On objects capable of seeking, the w\bwr\bri\bit\bte\be() starts at a position given by |
| 20734 | the pointer associated with _\bd (see lseek(2)). Upon return from w\bwr\bri\bit\bte\be(), |
| 20735 | the pointer is incremented by the number of bytes which were written. If |
| 20736 | a file was opened with the O_APPEND flag (see open(2)), calls to w\bwr\bri\bit\bte\be() |
| 20737 | or w\bwr\bri\bit\bte\bev\bv() will automatically set the pointer to the end of the file |
| 20738 | before writing. |
| 20739 | |
| 20740 | Objects that are not capable of seeking always write from the current |
| 20741 | position. The value of the pointer associated with such an object is |
| 20742 | undefined. |
| 20743 | |
| 20744 | If the real user is not the superuser, then w\bwr\bri\bit\bte\be() clears the set-user- |
| 20745 | ID bit on a file. This prevents penetration of system security by a user |
| 20746 | who ``captures'' a writable set-user-ID file owned by the superuser. |
| 20747 | |
| 20748 | If w\bwr\bri\bit\bte\be() succeeds it will update the st_ctime and st_mtime fields of |
| 20749 | the file's meta-data (see stat(2)). |
| 20750 | |
| 20751 | When using non-blocking I/O on objects such as sockets that are subject |
| 20752 | to flow control, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may write fewer bytes than |
| 20753 | requested; the return value must be noted, and the remainder of the |
| 20754 | operation should be retried when possible. |
| 20755 | |
| 20756 | Note that w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
| 20757 | the constant IOV_MAX. |
| 20758 | |
| 20759 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 20760 | Upon successful completion the number of bytes which were written is |
| 20761 | returned. Otherwise, a -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
| 20762 | set to indicate the error. |
| 20763 | |
| 20764 | E\bER\bRR\bRO\bOR\bRS\bS |
| 20765 | w\bwr\bri\bit\bte\be(), p\bpw\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\bev\bv() will fail and the file pointer |
| 20766 | will remain unchanged if: |
| 20767 | |
| 20768 | [EBADF] _\bd is not a valid descriptor open for writing. |
| 20769 | |
| 20770 | [EFBIG] An attempt was made to write a file that exceeds the |
| 20771 | process's file size limit or the maximum file size. |
| 20772 | |
| 20773 | [ENOSPC] There is no free space remaining on the file system |
| 20774 | containing the file. |
| 20775 | |
| 20776 | [EDQUOT] The user's quota of disk blocks on the file system |
| 20777 | containing the file has been exhausted. |
| 20778 | |
| 20779 | [EINTR] A write to a slow device (i.e. one that might block |
| 20780 | for an arbitrary amount of time) was interrupted by |
| 20781 | the delivery of a signal before any data could be |
| 20782 | written. |
| 20783 | |
| 20784 | [EIO] An I/O error occurred while reading from or writing to |
| 20785 | the file system. |
| 20786 | |
| 20787 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 20788 | address space. |
| 20789 | |
| 20790 | In addition, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may return the following errors: |
| 20791 | |
| 20792 | [EPIPE] An attempt is made to write to a pipe that is not open |
| 20793 | for reading by any process. |
| 20794 | |
| 20795 | [EPIPE] An attempt is made to write to a socket of type |
| 20796 | SOCK_STREAM that is not connected to a peer socket. |
| 20797 | |
| 20798 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
| 20799 | could be written immediately. |
| 20800 | |
| 20801 | [ENETDOWN] The destination address specified a network that is |
| 20802 | down. |
| 20803 | |
| 20804 | [EDESTADDRREQ] The destination is no longer available when writing to |
| 20805 | a UNIX-domain datagram socket on which connect(2) had |
| 20806 | been used to set a destination address. |
| 20807 | |
| 20808 | [EIO] The process is a member of a background process |
| 20809 | attempting to write to its controlling terminal, |
| 20810 | TOSTOP is set on the terminal, the process isn't |
| 20811 | ignoring the SIGTTOUT signal and the thread isn't |
| 20812 | blocking the SIGTTOUT signal, and either the process |
| 20813 | was created with vfork(2) and hasn't successfully |
| 20814 | executed one of the exec functions or the process |
| 20815 | group is orphaned. |
| 20816 | |
| 20817 | w\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\be() may return the following error: |
| 20818 | |
| 20819 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
| 20820 | |
| 20821 | p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() may return the following error: |
| 20822 | |
| 20823 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
| 20824 | |
| 20825 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
| 20826 | |
| 20827 | w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() may return one of the following errors: |
| 20828 | |
| 20829 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
| 20830 | IOV_MAX. |
| 20831 | |
| 20832 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
| 20833 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 20834 | |
| 20835 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
| 20836 | address space. |
| 20837 | |
| 20838 | [ENOBUFS] The system lacked sufficient buffer space or a queue |
| 20839 | was full. |
| 20840 | |
| 20841 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 20842 | fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) |
| 20843 | |
| 20844 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 20845 | The w\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\be() functions conform to IEEE Std |
| 20846 | 1003.1-2008 (``POSIX.1''). |
| 20847 | |
| 20848 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 20849 | The p\bpw\bwr\bri\bit\bte\bev\bv() function call appeared in OpenBSD 2.7. The p\bpw\bwr\bri\bit\bte\be() |
| 20850 | function call appeared in AT&T System V Release 4 UNIX. The w\bwr\bri\bit\bte\bev\bv() |
| 20851 | function call appeared in 4.2BSD. The w\bwr\bri\bit\bte\be() function call appeared in |
| 20852 | Version 2 AT&T UNIX. |
| 20853 | |
| 20854 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 20855 | Error checks should explicitly test for -1. Code such as |
| 20856 | |
| 20857 | while ((nr = write(fd, buf, sizeof(buf))) > 0) |
| 20858 | |
| 20859 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
| 20860 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
| 20861 | error-free w\bwr\bri\bit\bte\be() may appear as a negative number distinct from -1. |
| 20862 | Proper loops should use |
| 20863 | |
| 20864 | while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) |
| 20865 | |
| 20866 | N\bNA\bAM\bME\bE |
| 20867 | q\bqu\buo\bot\bta\bac\bct\btl\bl - manipulate filesystem quotas |
| 20868 | |
| 20869 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 20870 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\buf\bfs\bs/\b/u\buf\bfs\bs/\b/q\bqu\buo\bot\bta\ba.\b.h\bh>\b> |
| 20871 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 20872 | |
| 20873 | _\bi_\bn_\bt |
| 20874 | q\bqu\buo\bot\bta\bac\bct\btl\bl(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bc_\bm_\bd, _\bi_\bn_\bt _\bi_\bd, _\bc_\bh_\ba_\br _\b*_\ba_\bd_\bd_\br); |
| 20875 | |
| 20876 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 20877 | The q\bqu\buo\bot\bta\bac\bct\btl\bl() call enables, disables and manipulates filesystem quotas. |
| 20878 | A quota control command given by _\bc_\bm_\bd operates on the given filename _\bp_\ba_\bt_\bh |
| 20879 | for the given user _\bi_\bd. The address of an optional command specific data |
| 20880 | structure, _\ba_\bd_\bd_\br, may be given; its interpretation is discussed below with |
| 20881 | each command. |
| 20882 | |
| 20883 | Currently quotas are supported only for the ``ffs'' filesystem. For |
| 20884 | ``ffs'', a command is composed of a primary command (see below) and a |
| 20885 | command type used to interpret the _\bi_\bd. Types are supported for |
| 20886 | interpretation of user identifiers and group identifiers. The ``ffs'' |
| 20887 | specific commands are: |
| 20888 | |
| 20889 | Q_QUOTAON Enable disk quotas for the filesystem specified by _\bp_\ba_\bt_\bh. The |
| 20890 | command type specifies the type of the quotas being enabled. |
| 20891 | The _\ba_\bd_\bd_\br argument specifies a file from which to take the |
| 20892 | quotas. The quota file must exist; it is normally created |
| 20893 | with the quotacheck(8) program. The _\bi_\bd argument is unused. |
| 20894 | Only the superuser may turn quotas on. |
| 20895 | |
| 20896 | Q_QUOTAOFF |
| 20897 | Disable disk quotas for the filesystem specified by _\bp_\ba_\bt_\bh. The |
| 20898 | command type specifies the type of the quotas being disabled. |
| 20899 | The _\ba_\bd_\bd_\br and _\bi_\bd arguments are unused. Only the superuser may |
| 20900 | turn quotas off. |
| 20901 | |
| 20902 | Q_GETQUOTA |
| 20903 | Get disk quota limits and current usage for the user or group |
| 20904 | (as determined by the command type) with identifier _\bi_\bd. _\ba_\bd_\bd_\br |
| 20905 | is a pointer to a struct dqblk structure. |
| 20906 | |
| 20907 | Q_SETQUOTA |
| 20908 | Set disk quota limits for the user or group (as determined by |
| 20909 | the command type) with identifier _\bi_\bd. _\ba_\bd_\bd_\br is a pointer to a |
| 20910 | struct dqblk structure. The usage fields of struct dqblk |
| 20911 | structure are ignored. This call is restricted to the |
| 20912 | superuser. |
| 20913 | |
| 20914 | Q_SETUSE Set disk usage limits for the user or group (as determined by |
| 20915 | the command type) with identifier _\bi_\bd. _\ba_\bd_\bd_\br is a pointer to a |
| 20916 | struct dqblk structure. Only the usage fields are used. This |
| 20917 | call is restricted to the superuser. |
| 20918 | |
| 20919 | Q_SYNC Update the on-disk copy of quota usages. The command type |
| 20920 | specifies which type of quotas are to be updated. The _\bi_\bd and |
| 20921 | _\ba_\bd_\bd_\br parameters are ignored. |
| 20922 | |
| 20923 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 20924 | Upon successful completion, the value 0 is returned; otherwise the |
| 20925 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 20926 | error. |
| 20927 | |
| 20928 | E\bER\bRR\bRO\bOR\bRS\bS |
| 20929 | A q\bqu\buo\bot\bta\bac\bct\btl\bl() call will fail if: |
| 20930 | |
| 20931 | [EOPNOTSUPP] The kernel has not been compiled with the QUOTA |
| 20932 | option. |
| 20933 | |
| 20934 | [EUSERS] The quota table cannot be expanded. |
| 20935 | |
| 20936 | [EINVAL] _\bc_\bm_\bd or the command type is invalid. |
| 20937 | |
| 20938 | [EACCES] In Q_QUOTAON, the quota file is not a plain file. |
| 20939 | |
| 20940 | [EACCES] Search permission is denied for a component of a path |
| 20941 | prefix. |
| 20942 | |
| 20943 | [ENOTDIR] A component of a path prefix was not a directory. |
| 20944 | |
| 20945 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 20946 | characters, or an entire pathname (including the |
| 20947 | terminating NUL) exceeded PATH_MAX bytes. |
| 20948 | |
| 20949 | [ENOENT] A filename does not exist. |
| 20950 | |
| 20951 | [ELOOP] Too many symbolic links were encountered in |
| 20952 | translating a pathname. |
| 20953 | |
| 20954 | [EROFS] In Q_QUOTAON, the quota file resides on a read-only |
| 20955 | filesystem. |
| 20956 | |
| 20957 | [EIO] An I/O error occurred while reading from or writing to |
| 20958 | a file containing quotas. |
| 20959 | |
| 20960 | [EFAULT] An invalid _\ba_\bd_\bd_\br was supplied; the associated structure |
| 20961 | could not be copied in or out of the kernel. |
| 20962 | |
| 20963 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 20964 | space. |
| 20965 | |
| 20966 | [EPERM] The call was privileged and the caller was not the |
| 20967 | superuser. |
| 20968 | |
| 20969 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 20970 | quota(1), fstab(5), edquota(8), quotacheck(8), quotaon(8), repquota(8) |
| 20971 | |
| 20972 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 20973 | The q\bqu\buo\bot\bta\bac\bct\btl\bl() function call appeared in 4.3BSD-Reno. |
| 20974 | |
| 20975 | B\bBU\bUG\bGS\bS |
| 20976 | There should be some way to integrate this call with the resource limit |
| 20977 | interface provided by setrlimit(2) and getrlimit(2). |
| 20978 | |
| 20979 | N\bNA\bAM\bME\bE |
| 20980 | r\bre\bea\bad\bd, r\bre\bea\bad\bdv\bv, p\bpr\bre\bea\bad\bd, p\bpr\bre\bea\bad\bdv\bv - read input |
| 20981 | |
| 20982 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 20983 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 20984 | |
| 20985 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20986 | r\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 20987 | |
| 20988 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20989 | p\bpr\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 20990 | |
| 20991 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 20992 | |
| 20993 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 20994 | r\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
| 20995 | |
| 20996 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 20997 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 20998 | |
| 20999 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21000 | p\bpr\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 21001 | |
| 21002 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 21003 | r\bre\bea\bad\bd() attempts to read _\bn_\bb_\by_\bt_\be_\bs of data from the object referenced by the |
| 21004 | descriptor _\bd into the buffer pointed to by _\bb_\bu_\bf. r\bre\bea\bad\bdv\bv() performs the |
| 21005 | same action, but scatters the input data into the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
| 21006 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
| 21007 | iov[iovcnt-1]. p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() perform the same functions, but read |
| 21008 | from the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the file |
| 21009 | pointer. |
| 21010 | |
| 21011 | For r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
| 21012 | |
| 21013 | struct iovec { |
| 21014 | void *iov_base; |
| 21015 | size_t iov_len; |
| 21016 | }; |
| 21017 | |
| 21018 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
| 21019 | memory where data should be placed. r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will always |
| 21020 | fill an area completely before proceeding to the next. |
| 21021 | |
| 21022 | On objects capable of seeking, the r\bre\bea\bad\bd() starts at a position given by |
| 21023 | the pointer associated with _\bd (see lseek(2)). Upon return from r\bre\bea\bad\bd(), |
| 21024 | the pointer is incremented by the number of bytes actually read. |
| 21025 | |
| 21026 | Objects that are not capable of seeking always read from the current |
| 21027 | position. The value of the pointer associated with such an object is |
| 21028 | undefined. |
| 21029 | |
| 21030 | Upon successful completion, r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() return |
| 21031 | the number of bytes actually read and placed in the buffer. The system |
| 21032 | guarantees to read the number of bytes requested if the descriptor |
| 21033 | references a normal file that has that many bytes left before the end-of- |
| 21034 | file, but in no other case. |
| 21035 | |
| 21036 | Note that r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
| 21037 | the constant IOV_MAX. |
| 21038 | |
| 21039 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 21040 | If successful, the number of bytes actually read is returned. Upon |
| 21041 | reading end-of-file, zero is returned. Otherwise, a -1 is returned and |
| 21042 | the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 21043 | |
| 21044 | E\bER\bRR\bRO\bOR\bRS\bS |
| 21045 | r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() will succeed unless: |
| 21046 | |
| 21047 | [EBADF] _\bd is not a valid file or socket descriptor open for |
| 21048 | reading. |
| 21049 | |
| 21050 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 21051 | address space. |
| 21052 | |
| 21053 | [EIO] An I/O error occurred while reading from the file |
| 21054 | system. |
| 21055 | |
| 21056 | [EINTR] A read from a slow device (i.e. one that might block |
| 21057 | for an arbitrary amount of time) was interrupted by |
| 21058 | the delivery of a signal before any data arrived. |
| 21059 | |
| 21060 | In addition, r\bre\bea\bad\bd() and r\bre\bea\bad\bdv\bv() may return the following errors: |
| 21061 | |
| 21062 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
| 21063 | were ready to be read. |
| 21064 | |
| 21065 | [ENOTCONN] The file is a socket associated with a connection- |
| 21066 | oriented protocol and has not been connected. |
| 21067 | |
| 21068 | [EIO] The process is a member of a background process |
| 21069 | attempting to read from its controlling terminal, the |
| 21070 | process is ignoring or blocking the SIGTTIN signal or |
| 21071 | the process group is orphaned. |
| 21072 | |
| 21073 | r\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bd() may return the following error: |
| 21074 | |
| 21075 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
| 21076 | |
| 21077 | p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() may return the following errors: |
| 21078 | |
| 21079 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
| 21080 | |
| 21081 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
| 21082 | |
| 21083 | r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() may return one of the following errors: |
| 21084 | |
| 21085 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
| 21086 | IOV_MAX. |
| 21087 | |
| 21088 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
| 21089 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 21090 | |
| 21091 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
| 21092 | address space. |
| 21093 | |
| 21094 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 21095 | dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), |
| 21096 | socketpair(2) |
| 21097 | |
| 21098 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 21099 | The r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), and p\bpr\bre\bea\bad\bd() functions conform to IEEE Std |
| 21100 | 1003.1-2008 (``POSIX.1''). |
| 21101 | |
| 21102 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 21103 | A r\bre\bea\bad\bd() system call first appeared in Version 1 AT&T UNIX; r\bre\bea\bad\bdv\bv() in |
| 21104 | 4.1cBSD; p\bpr\bre\bea\bad\bd() in AT&T System V Release 4 UNIX; and p\bpr\bre\bea\bad\bdv\bv() in |
| 21105 | OpenBSD 2.7. |
| 21106 | |
| 21107 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 21108 | Error checks should explicitly test for -1. Code such as |
| 21109 | |
| 21110 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
| 21111 | |
| 21112 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
| 21113 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
| 21114 | error-free r\bre\bea\bad\bd() may appear as a negative number distinct from -1. |
| 21115 | Proper loops should use |
| 21116 | |
| 21117 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
| 21118 | |
| 21119 | N\bNA\bAM\bME\bE |
| 21120 | r\bre\bea\bad\bdl\bli\bin\bnk\bk, r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt - read value of a symbolic link |
| 21121 | |
| 21122 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 21123 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 21124 | |
| 21125 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21126 | r\bre\bea\bad\bdl\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\be_\bs_\bt_\br_\bi_\bc_\bt _\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\br_\be_\bs_\bt_\br_\bi_\bc_\bt _\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz); |
| 21127 | |
| 21128 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 21129 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 21130 | |
| 21131 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21132 | r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz); |
| 21133 | |
| 21134 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 21135 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() function places the contents of the symbolic link _\bp_\ba_\bt_\bh in |
| 21136 | the buffer _\bb_\bu_\bf, which has size _\bb_\bu_\bf_\bs_\bi_\bz. r\bre\bea\bad\bdl\bli\bin\bnk\bk does not append a NUL |
| 21137 | character to _\bb_\bu_\bf. |
| 21138 | |
| 21139 | The r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() function is equivalent to r\bre\bea\bad\bdl\bli\bin\bnk\bk() except that where |
| 21140 | _\bp_\ba_\bt_\bh specifies a relative path, the symbolic link whose contents are read |
| 21141 | is determined relative to the directory associated with file descriptor |
| 21142 | _\bf_\bd instead of the current working directory. |
| 21143 | |
| 21144 | If r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in |
| 21145 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used and |
| 21146 | the behavior is identical to a call to r\bre\bea\bad\bdl\bli\bin\bnk\bk(). |
| 21147 | |
| 21148 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 21149 | The call returns the count of characters placed in the buffer if it |
| 21150 | succeeds, or a -1 if an error occurs, placing the error code in the |
| 21151 | global variable _\be_\br_\br_\bn_\bo. |
| 21152 | |
| 21153 | E\bER\bRR\bRO\bOR\bRS\bS |
| 21154 | r\bre\bea\bad\bdl\bli\bin\bnk\bk() and r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() will fail if: |
| 21155 | |
| 21156 | [ENOTDIR] A component of the path prefix is not a directory. |
| 21157 | |
| 21158 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 21159 | characters, or an entire pathname (including the |
| 21160 | terminating NUL) exceeded PATH_MAX bytes. |
| 21161 | |
| 21162 | [ENOENT] The named file does not exist. |
| 21163 | |
| 21164 | [EACCES] Search permission is denied for a component of the |
| 21165 | path prefix. |
| 21166 | |
| 21167 | [ELOOP] Too many symbolic links were encountered in |
| 21168 | translating the pathname. |
| 21169 | |
| 21170 | [EINVAL] The named file is not a symbolic link. |
| 21171 | |
| 21172 | [EIO] An I/O error occurred while reading from the file |
| 21173 | system. |
| 21174 | |
| 21175 | [EFAULT] _\bb_\bu_\bf or _\bp_\ba_\bt_\bh extends outside the process's allocated |
| 21176 | address space. |
| 21177 | |
| 21178 | Additionally, r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() will fail if: |
| 21179 | |
| 21180 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 21181 | argument is neither AT_FDCWD nor a valid file |
| 21182 | descriptor. |
| 21183 | |
| 21184 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 21185 | argument is a valid file descriptor but it does not |
| 21186 | reference a directory. |
| 21187 | |
| 21188 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 21189 | permission is denied for the directory which the _\bf_\bd |
| 21190 | file descriptor references. |
| 21191 | |
| 21192 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 21193 | lstat(2), stat(2), symlink(2), symlink(7) |
| 21194 | |
| 21195 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 21196 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() and r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 21197 | (``POSIX.1''). |
| 21198 | |
| 21199 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 21200 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() system call first appeared in 4.1cBSD. The r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() |
| 21201 | system call has been available since OpenBSD 5.0. |
| 21202 | |
| 21203 | N\bNA\bAM\bME\bE |
| 21204 | r\bre\bea\bad\bdl\bli\bin\bnk\bk, r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt - read value of a symbolic link |
| 21205 | |
| 21206 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 21207 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 21208 | |
| 21209 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21210 | r\bre\bea\bad\bdl\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\be_\bs_\bt_\br_\bi_\bc_\bt _\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\br_\be_\bs_\bt_\br_\bi_\bc_\bt _\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz); |
| 21211 | |
| 21212 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 21213 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 21214 | |
| 21215 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21216 | r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz); |
| 21217 | |
| 21218 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 21219 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() function places the contents of the symbolic link _\bp_\ba_\bt_\bh in |
| 21220 | the buffer _\bb_\bu_\bf, which has size _\bb_\bu_\bf_\bs_\bi_\bz. r\bre\bea\bad\bdl\bli\bin\bnk\bk does not append a NUL |
| 21221 | character to _\bb_\bu_\bf. |
| 21222 | |
| 21223 | The r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() function is equivalent to r\bre\bea\bad\bdl\bli\bin\bnk\bk() except that where |
| 21224 | _\bp_\ba_\bt_\bh specifies a relative path, the symbolic link whose contents are read |
| 21225 | is determined relative to the directory associated with file descriptor |
| 21226 | _\bf_\bd instead of the current working directory. |
| 21227 | |
| 21228 | If r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in |
| 21229 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used and |
| 21230 | the behavior is identical to a call to r\bre\bea\bad\bdl\bli\bin\bnk\bk(). |
| 21231 | |
| 21232 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 21233 | The call returns the count of characters placed in the buffer if it |
| 21234 | succeeds, or a -1 if an error occurs, placing the error code in the |
| 21235 | global variable _\be_\br_\br_\bn_\bo. |
| 21236 | |
| 21237 | E\bER\bRR\bRO\bOR\bRS\bS |
| 21238 | r\bre\bea\bad\bdl\bli\bin\bnk\bk() and r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() will fail if: |
| 21239 | |
| 21240 | [ENOTDIR] A component of the path prefix is not a directory. |
| 21241 | |
| 21242 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 21243 | characters, or an entire pathname (including the |
| 21244 | terminating NUL) exceeded PATH_MAX bytes. |
| 21245 | |
| 21246 | [ENOENT] The named file does not exist. |
| 21247 | |
| 21248 | [EACCES] Search permission is denied for a component of the |
| 21249 | path prefix. |
| 21250 | |
| 21251 | [ELOOP] Too many symbolic links were encountered in |
| 21252 | translating the pathname. |
| 21253 | |
| 21254 | [EINVAL] The named file is not a symbolic link. |
| 21255 | |
| 21256 | [EIO] An I/O error occurred while reading from the file |
| 21257 | system. |
| 21258 | |
| 21259 | [EFAULT] _\bb_\bu_\bf or _\bp_\ba_\bt_\bh extends outside the process's allocated |
| 21260 | address space. |
| 21261 | |
| 21262 | Additionally, r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() will fail if: |
| 21263 | |
| 21264 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 21265 | argument is neither AT_FDCWD nor a valid file |
| 21266 | descriptor. |
| 21267 | |
| 21268 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 21269 | argument is a valid file descriptor but it does not |
| 21270 | reference a directory. |
| 21271 | |
| 21272 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 21273 | permission is denied for the directory which the _\bf_\bd |
| 21274 | file descriptor references. |
| 21275 | |
| 21276 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 21277 | lstat(2), stat(2), symlink(2), symlink(7) |
| 21278 | |
| 21279 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 21280 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() and r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 21281 | (``POSIX.1''). |
| 21282 | |
| 21283 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 21284 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() system call first appeared in 4.1cBSD. The r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() |
| 21285 | system call has been available since OpenBSD 5.0. |
| 21286 | |
| 21287 | N\bNA\bAM\bME\bE |
| 21288 | r\bre\bea\bad\bd, r\bre\bea\bad\bdv\bv, p\bpr\bre\bea\bad\bd, p\bpr\bre\bea\bad\bdv\bv - read input |
| 21289 | |
| 21290 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 21291 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 21292 | |
| 21293 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21294 | r\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 21295 | |
| 21296 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21297 | p\bpr\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 21298 | |
| 21299 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 21300 | |
| 21301 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21302 | r\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
| 21303 | |
| 21304 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 21305 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 21306 | |
| 21307 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21308 | p\bpr\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 21309 | |
| 21310 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 21311 | r\bre\bea\bad\bd() attempts to read _\bn_\bb_\by_\bt_\be_\bs of data from the object referenced by the |
| 21312 | descriptor _\bd into the buffer pointed to by _\bb_\bu_\bf. r\bre\bea\bad\bdv\bv() performs the |
| 21313 | same action, but scatters the input data into the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
| 21314 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
| 21315 | iov[iovcnt-1]. p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() perform the same functions, but read |
| 21316 | from the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the file |
| 21317 | pointer. |
| 21318 | |
| 21319 | For r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
| 21320 | |
| 21321 | struct iovec { |
| 21322 | void *iov_base; |
| 21323 | size_t iov_len; |
| 21324 | }; |
| 21325 | |
| 21326 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
| 21327 | memory where data should be placed. r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will always |
| 21328 | fill an area completely before proceeding to the next. |
| 21329 | |
| 21330 | On objects capable of seeking, the r\bre\bea\bad\bd() starts at a position given by |
| 21331 | the pointer associated with _\bd (see lseek(2)). Upon return from r\bre\bea\bad\bd(), |
| 21332 | the pointer is incremented by the number of bytes actually read. |
| 21333 | |
| 21334 | Objects that are not capable of seeking always read from the current |
| 21335 | position. The value of the pointer associated with such an object is |
| 21336 | undefined. |
| 21337 | |
| 21338 | Upon successful completion, r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() return |
| 21339 | the number of bytes actually read and placed in the buffer. The system |
| 21340 | guarantees to read the number of bytes requested if the descriptor |
| 21341 | references a normal file that has that many bytes left before the end-of- |
| 21342 | file, but in no other case. |
| 21343 | |
| 21344 | Note that r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
| 21345 | the constant IOV_MAX. |
| 21346 | |
| 21347 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 21348 | If successful, the number of bytes actually read is returned. Upon |
| 21349 | reading end-of-file, zero is returned. Otherwise, a -1 is returned and |
| 21350 | the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 21351 | |
| 21352 | E\bER\bRR\bRO\bOR\bRS\bS |
| 21353 | r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() will succeed unless: |
| 21354 | |
| 21355 | [EBADF] _\bd is not a valid file or socket descriptor open for |
| 21356 | reading. |
| 21357 | |
| 21358 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 21359 | address space. |
| 21360 | |
| 21361 | [EIO] An I/O error occurred while reading from the file |
| 21362 | system. |
| 21363 | |
| 21364 | [EINTR] A read from a slow device (i.e. one that might block |
| 21365 | for an arbitrary amount of time) was interrupted by |
| 21366 | the delivery of a signal before any data arrived. |
| 21367 | |
| 21368 | In addition, r\bre\bea\bad\bd() and r\bre\bea\bad\bdv\bv() may return the following errors: |
| 21369 | |
| 21370 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
| 21371 | were ready to be read. |
| 21372 | |
| 21373 | [ENOTCONN] The file is a socket associated with a connection- |
| 21374 | oriented protocol and has not been connected. |
| 21375 | |
| 21376 | [EIO] The process is a member of a background process |
| 21377 | attempting to read from its controlling terminal, the |
| 21378 | process is ignoring or blocking the SIGTTIN signal or |
| 21379 | the process group is orphaned. |
| 21380 | |
| 21381 | r\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bd() may return the following error: |
| 21382 | |
| 21383 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
| 21384 | |
| 21385 | p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() may return the following errors: |
| 21386 | |
| 21387 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
| 21388 | |
| 21389 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
| 21390 | |
| 21391 | r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() may return one of the following errors: |
| 21392 | |
| 21393 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
| 21394 | IOV_MAX. |
| 21395 | |
| 21396 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
| 21397 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 21398 | |
| 21399 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
| 21400 | address space. |
| 21401 | |
| 21402 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 21403 | dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), |
| 21404 | socketpair(2) |
| 21405 | |
| 21406 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 21407 | The r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), and p\bpr\bre\bea\bad\bd() functions conform to IEEE Std |
| 21408 | 1003.1-2008 (``POSIX.1''). |
| 21409 | |
| 21410 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 21411 | A r\bre\bea\bad\bd() system call first appeared in Version 1 AT&T UNIX; r\bre\bea\bad\bdv\bv() in |
| 21412 | 4.1cBSD; p\bpr\bre\bea\bad\bd() in AT&T System V Release 4 UNIX; and p\bpr\bre\bea\bad\bdv\bv() in |
| 21413 | OpenBSD 2.7. |
| 21414 | |
| 21415 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 21416 | Error checks should explicitly test for -1. Code such as |
| 21417 | |
| 21418 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
| 21419 | |
| 21420 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
| 21421 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
| 21422 | error-free r\bre\bea\bad\bd() may appear as a negative number distinct from -1. |
| 21423 | Proper loops should use |
| 21424 | |
| 21425 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
| 21426 | |
| 21427 | N\bNA\bAM\bME\bE |
| 21428 | r\bre\beb\bbo\boo\bot\bt - reboot system or halt processor |
| 21429 | |
| 21430 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 21431 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 21432 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\beb\bbo\boo\bot\bt.\b.h\bh>\b> |
| 21433 | |
| 21434 | _\bi_\bn_\bt |
| 21435 | r\bre\beb\bbo\boo\bot\bt(_\bi_\bn_\bt _\bh_\bo_\bw_\bt_\bo); |
| 21436 | |
| 21437 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 21438 | r\bre\beb\bbo\boo\bot\bt() reboots the system. Only the superuser may reboot a machine on |
| 21439 | demand. However, a reboot is invoked automatically in the event of |
| 21440 | unrecoverable system failures. |
| 21441 | |
| 21442 | _\bh_\bo_\bw_\bt_\bo is a mask of options; the system call interface allows the |
| 21443 | following options, defined in the include file <_\bs_\by_\bs_\b/_\br_\be_\bb_\bo_\bo_\bt_\b._\bh>, to be |
| 21444 | passed to the new kernel or the new bootstrap and init programs. |
| 21445 | |
| 21446 | RB_AUTOBOOT The default, causing the system to reboot in its usual |
| 21447 | fashion. |
| 21448 | |
| 21449 | RB_ASKNAME Interpreted by the bootstrap program itself, causing it to |
| 21450 | prompt on the console as to what file should be booted. |
| 21451 | Normally, the system is booted from the file |
| 21452 | ``_\bx_\bx(0,0)bsd'', where _\bx_\bx is the default disk name, without |
| 21453 | prompting for the file name. |
| 21454 | |
| 21455 | RB_DFLTROOT Use the compiled in root device. Normally, the system uses |
| 21456 | the device from which it was booted as the root device if |
| 21457 | possible. (The default behavior is dependent on the |
| 21458 | ability of the bootstrap program to determine the drive |
| 21459 | from which it was loaded, which is not possible on all |
| 21460 | systems.) |
| 21461 | |
| 21462 | RB_DUMP Dump kernel memory before rebooting; see savecore(8) for |
| 21463 | more information. |
| 21464 | |
| 21465 | RB_HALT The processor is simply halted; no reboot takes place. |
| 21466 | |
| 21467 | RB_POWERDOWN If used in conjunction with RB_HALT, and if the system |
| 21468 | hardware supports the function, the system will be powered |
| 21469 | off. |
| 21470 | |
| 21471 | RB_USERREQ By default, the system will halt if r\bre\beb\bbo\boo\bot\bt() is called |
| 21472 | during startup (before the system has finished |
| 21473 | autoconfiguration), even if RB_HALT is not specified. This |
| 21474 | is because panic(9)s during startup will probably just |
| 21475 | repeat on the next boot. Use of this option implies that |
| 21476 | the user has requested the action specified (for example, |
| 21477 | using the ddb(4) b\bbo\boo\bot\bt r\bre\beb\bbo\boo\bot\bt command), so the system will |
| 21478 | reboot if a halt is not explicitly requested. |
| 21479 | |
| 21480 | RB_INITNAME An option allowing the specification of an init program |
| 21481 | (see init(8)) other than _\b/_\bs_\bb_\bi_\bn_\b/_\bi_\bn_\bi_\bt to be run when the |
| 21482 | system reboots. This switch is not currently available. |
| 21483 | |
| 21484 | RB_KDB Load the symbol table and enable a built-in debugger in the |
| 21485 | system. This option will have no useful function if the |
| 21486 | kernel is not configured for debugging. Several other |
| 21487 | options have different meaning if combined with this |
| 21488 | option, although their use may not be possible via the |
| 21489 | r\bre\beb\bbo\boo\bot\bt() call. See ddb(4) for more information. |
| 21490 | |
| 21491 | RB_NOSYNC Normally, the disks are sync'd (see sync(8)) before the |
| 21492 | processor is halted or rebooted. This option may be useful |
| 21493 | if file system changes have been made manually or if the |
| 21494 | processor is on fire. |
| 21495 | |
| 21496 | RB_RDONLY Initially mount the root file system read-only. This is |
| 21497 | currently the default, and this option has been deprecated. |
| 21498 | |
| 21499 | RB_SINGLE Normally, the reboot procedure involves an automatic disk |
| 21500 | consistency check and then multi-user operations. |
| 21501 | RB_SINGLE prevents this, booting the system with a single- |
| 21502 | user shell on the console. RB_SINGLE is actually |
| 21503 | interpreted by the init(8) program in the newly booted |
| 21504 | system. |
| 21505 | |
| 21506 | When no options are given (i.e., RB_AUTOBOOT is used), the |
| 21507 | system is rebooted from file _\b/_\bb_\bs_\bd in the root file system |
| 21508 | of unit 0 of a disk chosen in a processor specific way. An |
| 21509 | automatic consistency check of the disks is normally |
| 21510 | performed (see fsck(8)). |
| 21511 | |
| 21512 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 21513 | If successful, this call never returns. Otherwise, a -1 is returned and |
| 21514 | an error is returned in the global variable _\be_\br_\br_\bn_\bo. |
| 21515 | |
| 21516 | E\bER\bRR\bRO\bOR\bRS\bS |
| 21517 | [EPERM] The caller is not the superuser. |
| 21518 | |
| 21519 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 21520 | ddb(4), crash(8), halt(8), init(8), reboot(8), savecore(8), boot(9), |
| 21521 | panic(9) |
| 21522 | |
| 21523 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 21524 | The r\bre\beb\bbo\boo\bot\bt() system call finally appeared in 4.0BSD. |
| 21525 | |
| 21526 | B\bBU\bUG\bGS\bS |
| 21527 | Not all platforms support all possible arguments. |
| 21528 | |
| 21529 | N\bNA\bAM\bME\bE |
| 21530 | r\bre\bec\bcv\bv, r\bre\bec\bcv\bvf\bfr\bro\bom\bm, r\bre\bec\bcv\bvm\bms\bsg\bg - receive a message from a socket |
| 21531 | |
| 21532 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 21533 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 21534 | |
| 21535 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21536 | r\bre\bec\bcv\bv(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 21537 | |
| 21538 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21539 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bf_\br_\bo_\bm, |
| 21540 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bf_\br_\bo_\bm_\bl_\be_\bn); |
| 21541 | |
| 21542 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21543 | r\bre\bec\bcv\bvm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 21544 | |
| 21545 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 21546 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm() and r\bre\bec\bcv\bvm\bms\bsg\bg() are used to receive messages from a socket, _\bs, |
| 21547 | and may be used to receive data on a socket whether or not it is |
| 21548 | connection-oriented. |
| 21549 | |
| 21550 | If _\bf_\br_\bo_\bm is non-null and the socket is not connection-oriented, the source |
| 21551 | address of the message is filled in. _\bf_\br_\bo_\bm_\bl_\be_\bn is a value-result |
| 21552 | parameter, initialized to the size of the buffer associated with _\bf_\br_\bo_\bm, |
| 21553 | and modified on return to indicate the actual size of the address stored |
| 21554 | there. |
| 21555 | |
| 21556 | The r\bre\bec\bcv\bv() call is normally used only on a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd socket (see |
| 21557 | connect(2)) and is identical to r\bre\bec\bcv\bvf\bfr\bro\bom\bm() with a null _\bf_\br_\bo_\bm parameter. |
| 21558 | As it is redundant, it may not be supported in future releases. |
| 21559 | |
| 21560 | On successful completion, all three routines return the number of message |
| 21561 | bytes read. If a message is too long to fit in the supplied buffer, |
| 21562 | excess bytes may be discarded depending on the type of socket the message |
| 21563 | is received from (see socket(2)). |
| 21564 | |
| 21565 | If no messages are available at the socket, the receive call waits for a |
| 21566 | message to arrive, unless the socket is nonblocking (see fcntl(2)) in |
| 21567 | which case the value -1 is returned and the external variable _\be_\br_\br_\bn_\bo set |
| 21568 | to EAGAIN. The receive calls normally return any data available, up to |
| 21569 | the requested amount, rather than waiting for receipt of the full amount |
| 21570 | requested; this behavior is affected by the socket-level options |
| 21571 | SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). |
| 21572 | |
| 21573 | The select(2) or poll(2) system calls may be used to determine when more |
| 21574 | data arrive. |
| 21575 | |
| 21576 | The _\bf_\bl_\ba_\bg_\bs argument is the bitwise OR of zero or more of the following |
| 21577 | values: |
| 21578 | |
| 21579 | MSG_OOB process out-of-band data |
| 21580 | MSG_PEEK peek at incoming message |
| 21581 | MSG_WAITALL wait for full request or error |
| 21582 | MSG_DONTWAIT don't block |
| 21583 | MSG_CMSG_CLOEXEC set the close-on-exec flag on received file |
| 21584 | descriptors |
| 21585 | |
| 21586 | The MSG_OOB flag requests receipt of out-of-band data that would not be |
| 21587 | received in the normal data stream. Some protocols place expedited data |
| 21588 | at the head of the normal data queue, and thus this flag cannot be used |
| 21589 | with such protocols. The MSG_PEEK flag causes the receive operation to |
| 21590 | return data from the beginning of the receive queue without removing that |
| 21591 | data from the queue. Thus, a subsequent receive call will return the |
| 21592 | same data. The MSG_WAITALL flag requests that the operation block until |
| 21593 | the full request is satisfied. However, the call may still return less |
| 21594 | data than requested if a signal is caught, an error or disconnect occurs, |
| 21595 | or the next data to be received is of a different type than that |
| 21596 | returned. The MSG_DONTWAIT flag requests the call to return when it |
| 21597 | would block otherwise. If no data is available, _\be_\br_\br_\bn_\bo is set to EAGAIN. |
| 21598 | This flag is not available in strict ANSI or C99 compilation mode. The |
| 21599 | MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary |
| 21600 | data with r\bre\bec\bcv\bvm\bms\bsg\bg() (see below) have their close-on-exec flag set. |
| 21601 | |
| 21602 | The r\bre\bec\bcv\bvm\bms\bsg\bg() call uses a _\bm_\bs_\bg_\bh_\bd_\br structure to minimize the number of |
| 21603 | directly supplied parameters. This structure has the following form, as |
| 21604 | defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>: |
| 21605 | |
| 21606 | struct msghdr { |
| 21607 | void *msg_name; /* optional address */ |
| 21608 | socklen_t msg_namelen; /* size of address */ |
| 21609 | struct iovec *msg_iov; /* scatter/gather array */ |
| 21610 | unsigned int msg_iovlen; /* # elements in msg_iov */ |
| 21611 | void *msg_control; /* ancillary data, see below */ |
| 21612 | socklen_t msg_controllen; /* ancillary data buffer len */ |
| 21613 | int msg_flags; /* flags on received message */ |
| 21614 | }; |
| 21615 | |
| 21616 | Here _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be and _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be_\bl_\be_\bn specify the source address if the socket is |
| 21617 | unconnected; _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be may be given as a null pointer if no names are |
| 21618 | desired or required. _\bm_\bs_\bg_\b__\bi_\bo_\bv and _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn describe scatter gather |
| 21619 | locations, as discussed in read(2). _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl, which has length |
| 21620 | _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl_\bl_\be_\bn, points to a buffer for other protocol control related |
| 21621 | messages or other miscellaneous ancillary data. The messages are of the |
| 21622 | form: |
| 21623 | |
| 21624 | struct cmsghdr { |
| 21625 | socklen_t cmsg_len; /* data byte count, including hdr */ |
| 21626 | int cmsg_level; /* originating protocol */ |
| 21627 | int cmsg_type; /* protocol-specific type */ |
| 21628 | /* followed by u_char cmsg_data[]; */ |
| 21629 | }; |
| 21630 | |
| 21631 | See CMSG_DATA(3) for how these messages are constructed and decomposed. |
| 21632 | |
| 21633 | Open file descriptors are now passed as ancillary data for AF_UNIX domain |
| 21634 | and socketpair(2) sockets, with _\bc_\bm_\bs_\bg_\b__\bl_\be_\bv_\be_\bl set to SOL_SOCKET and |
| 21635 | _\bc_\bm_\bs_\bg_\b__\bt_\by_\bp_\be set to SCM_RIGHTS. |
| 21636 | |
| 21637 | The _\bm_\bs_\bg_\b__\bf_\bl_\ba_\bg_\bs field is set on return according to the message received. |
| 21638 | It will contain zero or more of the following values: |
| 21639 | |
| 21640 | MSG_OOB Returned to indicate that expedited or out-of-band data |
| 21641 | was received. |
| 21642 | MSG_EOR Indicates end-of-record; the data returned completed a |
| 21643 | record (generally used with sockets of type |
| 21644 | SOCK_SEQPACKET). |
| 21645 | MSG_TRUNC Indicates that the trailing portion of a datagram was |
| 21646 | discarded because the datagram was larger than the |
| 21647 | buffer supplied. |
| 21648 | MSG_CTRUNC Indicates that some control data were discarded due to |
| 21649 | lack of space in the buffer for ancillary data. |
| 21650 | MSG_BCAST Indicates that the packet was received as broadcast. |
| 21651 | MSG_MCAST Indicates that the packet was received as multicast. |
| 21652 | |
| 21653 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 21654 | These calls return the number of bytes received, or -1 if an error |
| 21655 | occurred. |
| 21656 | |
| 21657 | E\bER\bRR\bRO\bOR\bRS\bS |
| 21658 | r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() fail if: |
| 21659 | |
| 21660 | [EBADF] The argument _\bs is an invalid descriptor. |
| 21661 | |
| 21662 | [ENOTCONN] The socket is associated with a connection-oriented |
| 21663 | protocol and has not been connected (see connect(2) and |
| 21664 | accept(2)). |
| 21665 | |
| 21666 | [ENOTSOCK] The argument _\bs does not refer to a socket. |
| 21667 | |
| 21668 | [EAGAIN] The socket is marked non-blocking, and the receive |
| 21669 | operation would block, or a receive timeout had been set, |
| 21670 | and the timeout expired before data were received. |
| 21671 | |
| 21672 | [EINTR] The receive was interrupted by delivery of a signal |
| 21673 | before any data were available. |
| 21674 | |
| 21675 | [EFAULT] The receive buffer pointer(s) point outside the process's |
| 21676 | address space. |
| 21677 | |
| 21678 | [EHOSTUNREACH] A socket operation was attempted to an unreachable host. |
| 21679 | |
| 21680 | [EHOSTDOWN] A socket operation failed because the destination host |
| 21681 | was down. |
| 21682 | |
| 21683 | [ENETDOWN] A socket operation encountered a dead network. |
| 21684 | |
| 21685 | [ECONNREFUSED] The socket is associated with a connection-oriented |
| 21686 | protocol and the connection was forcefully rejected (see |
| 21687 | connect(2)). |
| 21688 | |
| 21689 | In addition, r\bre\bec\bcv\bv() and r\bre\bec\bcv\bvf\bfr\bro\bom\bm() may return the following error: |
| 21690 | |
| 21691 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
| 21692 | |
| 21693 | And r\bre\bec\bcv\bvm\bms\bsg\bg() may return one of the following errors: |
| 21694 | |
| 21695 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
| 21696 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 21697 | |
| 21698 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
| 21699 | than IOV_MAX. |
| 21700 | |
| 21701 | [EMSGSIZE] The receiving program did not have sufficient free |
| 21702 | file descriptor slots. The descriptors are closed and |
| 21703 | any pending data can be returned by another call to |
| 21704 | r\bre\bec\bcv\bvm\bms\bsg\bg(). |
| 21705 | |
| 21706 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 21707 | connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), |
| 21708 | socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) |
| 21709 | |
| 21710 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 21711 | The r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() functions conform to IEEE Std |
| 21712 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST |
| 21713 | flags are extensions to that specification. |
| 21714 | |
| 21715 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 21716 | The r\bre\bec\bcv\bv() function call appeared in 4.2BSD. |
| 21717 | |
| 21718 | N\bNA\bAM\bME\bE |
| 21719 | r\bre\bec\bcv\bv, r\bre\bec\bcv\bvf\bfr\bro\bom\bm, r\bre\bec\bcv\bvm\bms\bsg\bg - receive a message from a socket |
| 21720 | |
| 21721 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 21722 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 21723 | |
| 21724 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21725 | r\bre\bec\bcv\bv(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 21726 | |
| 21727 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21728 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bf_\br_\bo_\bm, |
| 21729 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bf_\br_\bo_\bm_\bl_\be_\bn); |
| 21730 | |
| 21731 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21732 | r\bre\bec\bcv\bvm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 21733 | |
| 21734 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 21735 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm() and r\bre\bec\bcv\bvm\bms\bsg\bg() are used to receive messages from a socket, _\bs, |
| 21736 | and may be used to receive data on a socket whether or not it is |
| 21737 | connection-oriented. |
| 21738 | |
| 21739 | If _\bf_\br_\bo_\bm is non-null and the socket is not connection-oriented, the source |
| 21740 | address of the message is filled in. _\bf_\br_\bo_\bm_\bl_\be_\bn is a value-result |
| 21741 | parameter, initialized to the size of the buffer associated with _\bf_\br_\bo_\bm, |
| 21742 | and modified on return to indicate the actual size of the address stored |
| 21743 | there. |
| 21744 | |
| 21745 | The r\bre\bec\bcv\bv() call is normally used only on a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd socket (see |
| 21746 | connect(2)) and is identical to r\bre\bec\bcv\bvf\bfr\bro\bom\bm() with a null _\bf_\br_\bo_\bm parameter. |
| 21747 | As it is redundant, it may not be supported in future releases. |
| 21748 | |
| 21749 | On successful completion, all three routines return the number of message |
| 21750 | bytes read. If a message is too long to fit in the supplied buffer, |
| 21751 | excess bytes may be discarded depending on the type of socket the message |
| 21752 | is received from (see socket(2)). |
| 21753 | |
| 21754 | If no messages are available at the socket, the receive call waits for a |
| 21755 | message to arrive, unless the socket is nonblocking (see fcntl(2)) in |
| 21756 | which case the value -1 is returned and the external variable _\be_\br_\br_\bn_\bo set |
| 21757 | to EAGAIN. The receive calls normally return any data available, up to |
| 21758 | the requested amount, rather than waiting for receipt of the full amount |
| 21759 | requested; this behavior is affected by the socket-level options |
| 21760 | SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). |
| 21761 | |
| 21762 | The select(2) or poll(2) system calls may be used to determine when more |
| 21763 | data arrive. |
| 21764 | |
| 21765 | The _\bf_\bl_\ba_\bg_\bs argument is the bitwise OR of zero or more of the following |
| 21766 | values: |
| 21767 | |
| 21768 | MSG_OOB process out-of-band data |
| 21769 | MSG_PEEK peek at incoming message |
| 21770 | MSG_WAITALL wait for full request or error |
| 21771 | MSG_DONTWAIT don't block |
| 21772 | MSG_CMSG_CLOEXEC set the close-on-exec flag on received file |
| 21773 | descriptors |
| 21774 | |
| 21775 | The MSG_OOB flag requests receipt of out-of-band data that would not be |
| 21776 | received in the normal data stream. Some protocols place expedited data |
| 21777 | at the head of the normal data queue, and thus this flag cannot be used |
| 21778 | with such protocols. The MSG_PEEK flag causes the receive operation to |
| 21779 | return data from the beginning of the receive queue without removing that |
| 21780 | data from the queue. Thus, a subsequent receive call will return the |
| 21781 | same data. The MSG_WAITALL flag requests that the operation block until |
| 21782 | the full request is satisfied. However, the call may still return less |
| 21783 | data than requested if a signal is caught, an error or disconnect occurs, |
| 21784 | or the next data to be received is of a different type than that |
| 21785 | returned. The MSG_DONTWAIT flag requests the call to return when it |
| 21786 | would block otherwise. If no data is available, _\be_\br_\br_\bn_\bo is set to EAGAIN. |
| 21787 | This flag is not available in strict ANSI or C99 compilation mode. The |
| 21788 | MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary |
| 21789 | data with r\bre\bec\bcv\bvm\bms\bsg\bg() (see below) have their close-on-exec flag set. |
| 21790 | |
| 21791 | The r\bre\bec\bcv\bvm\bms\bsg\bg() call uses a _\bm_\bs_\bg_\bh_\bd_\br structure to minimize the number of |
| 21792 | directly supplied parameters. This structure has the following form, as |
| 21793 | defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>: |
| 21794 | |
| 21795 | struct msghdr { |
| 21796 | void *msg_name; /* optional address */ |
| 21797 | socklen_t msg_namelen; /* size of address */ |
| 21798 | struct iovec *msg_iov; /* scatter/gather array */ |
| 21799 | unsigned int msg_iovlen; /* # elements in msg_iov */ |
| 21800 | void *msg_control; /* ancillary data, see below */ |
| 21801 | socklen_t msg_controllen; /* ancillary data buffer len */ |
| 21802 | int msg_flags; /* flags on received message */ |
| 21803 | }; |
| 21804 | |
| 21805 | Here _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be and _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be_\bl_\be_\bn specify the source address if the socket is |
| 21806 | unconnected; _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be may be given as a null pointer if no names are |
| 21807 | desired or required. _\bm_\bs_\bg_\b__\bi_\bo_\bv and _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn describe scatter gather |
| 21808 | locations, as discussed in read(2). _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl, which has length |
| 21809 | _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl_\bl_\be_\bn, points to a buffer for other protocol control related |
| 21810 | messages or other miscellaneous ancillary data. The messages are of the |
| 21811 | form: |
| 21812 | |
| 21813 | struct cmsghdr { |
| 21814 | socklen_t cmsg_len; /* data byte count, including hdr */ |
| 21815 | int cmsg_level; /* originating protocol */ |
| 21816 | int cmsg_type; /* protocol-specific type */ |
| 21817 | /* followed by u_char cmsg_data[]; */ |
| 21818 | }; |
| 21819 | |
| 21820 | See CMSG_DATA(3) for how these messages are constructed and decomposed. |
| 21821 | |
| 21822 | Open file descriptors are now passed as ancillary data for AF_UNIX domain |
| 21823 | and socketpair(2) sockets, with _\bc_\bm_\bs_\bg_\b__\bl_\be_\bv_\be_\bl set to SOL_SOCKET and |
| 21824 | _\bc_\bm_\bs_\bg_\b__\bt_\by_\bp_\be set to SCM_RIGHTS. |
| 21825 | |
| 21826 | The _\bm_\bs_\bg_\b__\bf_\bl_\ba_\bg_\bs field is set on return according to the message received. |
| 21827 | It will contain zero or more of the following values: |
| 21828 | |
| 21829 | MSG_OOB Returned to indicate that expedited or out-of-band data |
| 21830 | was received. |
| 21831 | MSG_EOR Indicates end-of-record; the data returned completed a |
| 21832 | record (generally used with sockets of type |
| 21833 | SOCK_SEQPACKET). |
| 21834 | MSG_TRUNC Indicates that the trailing portion of a datagram was |
| 21835 | discarded because the datagram was larger than the |
| 21836 | buffer supplied. |
| 21837 | MSG_CTRUNC Indicates that some control data were discarded due to |
| 21838 | lack of space in the buffer for ancillary data. |
| 21839 | MSG_BCAST Indicates that the packet was received as broadcast. |
| 21840 | MSG_MCAST Indicates that the packet was received as multicast. |
| 21841 | |
| 21842 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 21843 | These calls return the number of bytes received, or -1 if an error |
| 21844 | occurred. |
| 21845 | |
| 21846 | E\bER\bRR\bRO\bOR\bRS\bS |
| 21847 | r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() fail if: |
| 21848 | |
| 21849 | [EBADF] The argument _\bs is an invalid descriptor. |
| 21850 | |
| 21851 | [ENOTCONN] The socket is associated with a connection-oriented |
| 21852 | protocol and has not been connected (see connect(2) and |
| 21853 | accept(2)). |
| 21854 | |
| 21855 | [ENOTSOCK] The argument _\bs does not refer to a socket. |
| 21856 | |
| 21857 | [EAGAIN] The socket is marked non-blocking, and the receive |
| 21858 | operation would block, or a receive timeout had been set, |
| 21859 | and the timeout expired before data were received. |
| 21860 | |
| 21861 | [EINTR] The receive was interrupted by delivery of a signal |
| 21862 | before any data were available. |
| 21863 | |
| 21864 | [EFAULT] The receive buffer pointer(s) point outside the process's |
| 21865 | address space. |
| 21866 | |
| 21867 | [EHOSTUNREACH] A socket operation was attempted to an unreachable host. |
| 21868 | |
| 21869 | [EHOSTDOWN] A socket operation failed because the destination host |
| 21870 | was down. |
| 21871 | |
| 21872 | [ENETDOWN] A socket operation encountered a dead network. |
| 21873 | |
| 21874 | [ECONNREFUSED] The socket is associated with a connection-oriented |
| 21875 | protocol and the connection was forcefully rejected (see |
| 21876 | connect(2)). |
| 21877 | |
| 21878 | In addition, r\bre\bec\bcv\bv() and r\bre\bec\bcv\bvf\bfr\bro\bom\bm() may return the following error: |
| 21879 | |
| 21880 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
| 21881 | |
| 21882 | And r\bre\bec\bcv\bvm\bms\bsg\bg() may return one of the following errors: |
| 21883 | |
| 21884 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
| 21885 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 21886 | |
| 21887 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
| 21888 | than IOV_MAX. |
| 21889 | |
| 21890 | [EMSGSIZE] The receiving program did not have sufficient free |
| 21891 | file descriptor slots. The descriptors are closed and |
| 21892 | any pending data can be returned by another call to |
| 21893 | r\bre\bec\bcv\bvm\bms\bsg\bg(). |
| 21894 | |
| 21895 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 21896 | connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), |
| 21897 | socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) |
| 21898 | |
| 21899 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 21900 | The r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() functions conform to IEEE Std |
| 21901 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST |
| 21902 | flags are extensions to that specification. |
| 21903 | |
| 21904 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 21905 | The r\bre\bec\bcv\bv() function call appeared in 4.2BSD. |
| 21906 | |
| 21907 | N\bNA\bAM\bME\bE |
| 21908 | r\bre\bec\bcv\bv, r\bre\bec\bcv\bvf\bfr\bro\bom\bm, r\bre\bec\bcv\bvm\bms\bsg\bg - receive a message from a socket |
| 21909 | |
| 21910 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 21911 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 21912 | |
| 21913 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21914 | r\bre\bec\bcv\bv(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 21915 | |
| 21916 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21917 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bf_\br_\bo_\bm, |
| 21918 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bf_\br_\bo_\bm_\bl_\be_\bn); |
| 21919 | |
| 21920 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 21921 | r\bre\bec\bcv\bvm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 21922 | |
| 21923 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 21924 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm() and r\bre\bec\bcv\bvm\bms\bsg\bg() are used to receive messages from a socket, _\bs, |
| 21925 | and may be used to receive data on a socket whether or not it is |
| 21926 | connection-oriented. |
| 21927 | |
| 21928 | If _\bf_\br_\bo_\bm is non-null and the socket is not connection-oriented, the source |
| 21929 | address of the message is filled in. _\bf_\br_\bo_\bm_\bl_\be_\bn is a value-result |
| 21930 | parameter, initialized to the size of the buffer associated with _\bf_\br_\bo_\bm, |
| 21931 | and modified on return to indicate the actual size of the address stored |
| 21932 | there. |
| 21933 | |
| 21934 | The r\bre\bec\bcv\bv() call is normally used only on a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd socket (see |
| 21935 | connect(2)) and is identical to r\bre\bec\bcv\bvf\bfr\bro\bom\bm() with a null _\bf_\br_\bo_\bm parameter. |
| 21936 | As it is redundant, it may not be supported in future releases. |
| 21937 | |
| 21938 | On successful completion, all three routines return the number of message |
| 21939 | bytes read. If a message is too long to fit in the supplied buffer, |
| 21940 | excess bytes may be discarded depending on the type of socket the message |
| 21941 | is received from (see socket(2)). |
| 21942 | |
| 21943 | If no messages are available at the socket, the receive call waits for a |
| 21944 | message to arrive, unless the socket is nonblocking (see fcntl(2)) in |
| 21945 | which case the value -1 is returned and the external variable _\be_\br_\br_\bn_\bo set |
| 21946 | to EAGAIN. The receive calls normally return any data available, up to |
| 21947 | the requested amount, rather than waiting for receipt of the full amount |
| 21948 | requested; this behavior is affected by the socket-level options |
| 21949 | SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). |
| 21950 | |
| 21951 | The select(2) or poll(2) system calls may be used to determine when more |
| 21952 | data arrive. |
| 21953 | |
| 21954 | The _\bf_\bl_\ba_\bg_\bs argument is the bitwise OR of zero or more of the following |
| 21955 | values: |
| 21956 | |
| 21957 | MSG_OOB process out-of-band data |
| 21958 | MSG_PEEK peek at incoming message |
| 21959 | MSG_WAITALL wait for full request or error |
| 21960 | MSG_DONTWAIT don't block |
| 21961 | MSG_CMSG_CLOEXEC set the close-on-exec flag on received file |
| 21962 | descriptors |
| 21963 | |
| 21964 | The MSG_OOB flag requests receipt of out-of-band data that would not be |
| 21965 | received in the normal data stream. Some protocols place expedited data |
| 21966 | at the head of the normal data queue, and thus this flag cannot be used |
| 21967 | with such protocols. The MSG_PEEK flag causes the receive operation to |
| 21968 | return data from the beginning of the receive queue without removing that |
| 21969 | data from the queue. Thus, a subsequent receive call will return the |
| 21970 | same data. The MSG_WAITALL flag requests that the operation block until |
| 21971 | the full request is satisfied. However, the call may still return less |
| 21972 | data than requested if a signal is caught, an error or disconnect occurs, |
| 21973 | or the next data to be received is of a different type than that |
| 21974 | returned. The MSG_DONTWAIT flag requests the call to return when it |
| 21975 | would block otherwise. If no data is available, _\be_\br_\br_\bn_\bo is set to EAGAIN. |
| 21976 | This flag is not available in strict ANSI or C99 compilation mode. The |
| 21977 | MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary |
| 21978 | data with r\bre\bec\bcv\bvm\bms\bsg\bg() (see below) have their close-on-exec flag set. |
| 21979 | |
| 21980 | The r\bre\bec\bcv\bvm\bms\bsg\bg() call uses a _\bm_\bs_\bg_\bh_\bd_\br structure to minimize the number of |
| 21981 | directly supplied parameters. This structure has the following form, as |
| 21982 | defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>: |
| 21983 | |
| 21984 | struct msghdr { |
| 21985 | void *msg_name; /* optional address */ |
| 21986 | socklen_t msg_namelen; /* size of address */ |
| 21987 | struct iovec *msg_iov; /* scatter/gather array */ |
| 21988 | unsigned int msg_iovlen; /* # elements in msg_iov */ |
| 21989 | void *msg_control; /* ancillary data, see below */ |
| 21990 | socklen_t msg_controllen; /* ancillary data buffer len */ |
| 21991 | int msg_flags; /* flags on received message */ |
| 21992 | }; |
| 21993 | |
| 21994 | Here _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be and _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be_\bl_\be_\bn specify the source address if the socket is |
| 21995 | unconnected; _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be may be given as a null pointer if no names are |
| 21996 | desired or required. _\bm_\bs_\bg_\b__\bi_\bo_\bv and _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn describe scatter gather |
| 21997 | locations, as discussed in read(2). _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl, which has length |
| 21998 | _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl_\bl_\be_\bn, points to a buffer for other protocol control related |
| 21999 | messages or other miscellaneous ancillary data. The messages are of the |
| 22000 | form: |
| 22001 | |
| 22002 | struct cmsghdr { |
| 22003 | socklen_t cmsg_len; /* data byte count, including hdr */ |
| 22004 | int cmsg_level; /* originating protocol */ |
| 22005 | int cmsg_type; /* protocol-specific type */ |
| 22006 | /* followed by u_char cmsg_data[]; */ |
| 22007 | }; |
| 22008 | |
| 22009 | See CMSG_DATA(3) for how these messages are constructed and decomposed. |
| 22010 | |
| 22011 | Open file descriptors are now passed as ancillary data for AF_UNIX domain |
| 22012 | and socketpair(2) sockets, with _\bc_\bm_\bs_\bg_\b__\bl_\be_\bv_\be_\bl set to SOL_SOCKET and |
| 22013 | _\bc_\bm_\bs_\bg_\b__\bt_\by_\bp_\be set to SCM_RIGHTS. |
| 22014 | |
| 22015 | The _\bm_\bs_\bg_\b__\bf_\bl_\ba_\bg_\bs field is set on return according to the message received. |
| 22016 | It will contain zero or more of the following values: |
| 22017 | |
| 22018 | MSG_OOB Returned to indicate that expedited or out-of-band data |
| 22019 | was received. |
| 22020 | MSG_EOR Indicates end-of-record; the data returned completed a |
| 22021 | record (generally used with sockets of type |
| 22022 | SOCK_SEQPACKET). |
| 22023 | MSG_TRUNC Indicates that the trailing portion of a datagram was |
| 22024 | discarded because the datagram was larger than the |
| 22025 | buffer supplied. |
| 22026 | MSG_CTRUNC Indicates that some control data were discarded due to |
| 22027 | lack of space in the buffer for ancillary data. |
| 22028 | MSG_BCAST Indicates that the packet was received as broadcast. |
| 22029 | MSG_MCAST Indicates that the packet was received as multicast. |
| 22030 | |
| 22031 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22032 | These calls return the number of bytes received, or -1 if an error |
| 22033 | occurred. |
| 22034 | |
| 22035 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22036 | r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() fail if: |
| 22037 | |
| 22038 | [EBADF] The argument _\bs is an invalid descriptor. |
| 22039 | |
| 22040 | [ENOTCONN] The socket is associated with a connection-oriented |
| 22041 | protocol and has not been connected (see connect(2) and |
| 22042 | accept(2)). |
| 22043 | |
| 22044 | [ENOTSOCK] The argument _\bs does not refer to a socket. |
| 22045 | |
| 22046 | [EAGAIN] The socket is marked non-blocking, and the receive |
| 22047 | operation would block, or a receive timeout had been set, |
| 22048 | and the timeout expired before data were received. |
| 22049 | |
| 22050 | [EINTR] The receive was interrupted by delivery of a signal |
| 22051 | before any data were available. |
| 22052 | |
| 22053 | [EFAULT] The receive buffer pointer(s) point outside the process's |
| 22054 | address space. |
| 22055 | |
| 22056 | [EHOSTUNREACH] A socket operation was attempted to an unreachable host. |
| 22057 | |
| 22058 | [EHOSTDOWN] A socket operation failed because the destination host |
| 22059 | was down. |
| 22060 | |
| 22061 | [ENETDOWN] A socket operation encountered a dead network. |
| 22062 | |
| 22063 | [ECONNREFUSED] The socket is associated with a connection-oriented |
| 22064 | protocol and the connection was forcefully rejected (see |
| 22065 | connect(2)). |
| 22066 | |
| 22067 | In addition, r\bre\bec\bcv\bv() and r\bre\bec\bcv\bvf\bfr\bro\bom\bm() may return the following error: |
| 22068 | |
| 22069 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
| 22070 | |
| 22071 | And r\bre\bec\bcv\bvm\bms\bsg\bg() may return one of the following errors: |
| 22072 | |
| 22073 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
| 22074 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 22075 | |
| 22076 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
| 22077 | than IOV_MAX. |
| 22078 | |
| 22079 | [EMSGSIZE] The receiving program did not have sufficient free |
| 22080 | file descriptor slots. The descriptors are closed and |
| 22081 | any pending data can be returned by another call to |
| 22082 | r\bre\bec\bcv\bvm\bms\bsg\bg(). |
| 22083 | |
| 22084 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22085 | connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), |
| 22086 | socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) |
| 22087 | |
| 22088 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 22089 | The r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() functions conform to IEEE Std |
| 22090 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST |
| 22091 | flags are extensions to that specification. |
| 22092 | |
| 22093 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 22094 | The r\bre\bec\bcv\bv() function call appeared in 4.2BSD. |
| 22095 | |
| 22096 | N\bNA\bAM\bME\bE |
| 22097 | r\bre\ben\bna\bam\bme\be, r\bre\ben\bna\bam\bme\bea\bat\bt - change the name of a file |
| 22098 | |
| 22099 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22100 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> |
| 22101 | |
| 22102 | _\bi_\bn_\bt |
| 22103 | r\bre\ben\bna\bam\bme\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\br_\bo_\bm, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\bo); |
| 22104 | |
| 22105 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 22106 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> |
| 22107 | |
| 22108 | _\bi_\bn_\bt |
| 22109 | r\bre\ben\bna\bam\bme\bea\bat\bt(_\bi_\bn_\bt _\bf_\br_\bo_\bm_\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\br_\bo_\bm, _\bi_\bn_\bt _\bt_\bo_\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\bo); |
| 22110 | |
| 22111 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22112 | The r\bre\ben\bna\bam\bme\be() function causes the link named _\bf_\br_\bo_\bm to be renamed as _\bt_\bo. If |
| 22113 | _\bt_\bo exists, it is first removed. Both _\bf_\br_\bo_\bm and _\bt_\bo must be of the same |
| 22114 | type (that is, both directories or both non-directories), and must reside |
| 22115 | on the same file system. |
| 22116 | |
| 22117 | r\bre\ben\bna\bam\bme\be() guarantees that if _\bt_\bo already exists, an instance of _\bt_\bo will |
| 22118 | always exist, even if the system should crash in the middle of the |
| 22119 | operation. |
| 22120 | |
| 22121 | If the final component of _\bf_\br_\bo_\bm is a symbolic link, the symbolic link is |
| 22122 | renamed, not the file or directory to which it points. |
| 22123 | |
| 22124 | The r\bre\ben\bna\bam\bme\bea\bat\bt() function is equivalent to r\bre\ben\bna\bam\bme\be() except that where _\bf_\br_\bo_\bm |
| 22125 | or _\bt_\bo specifies a relative path, the directory entry names used are |
| 22126 | resolved relative to the directories associated with file descriptors |
| 22127 | _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd (respectively) instead of the current working directory. |
| 22128 | |
| 22129 | If r\bre\ben\bna\bam\bme\bea\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 22130 | in the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd parameter, the current working directory is used |
| 22131 | for resolving the respective _\bf_\br_\bo_\bm or _\bt_\bo argument. |
| 22132 | |
| 22133 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22134 | Upon successful completion, the value 0 is returned; otherwise the |
| 22135 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 22136 | error. |
| 22137 | |
| 22138 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22139 | r\bre\ben\bna\bam\bme\be() and r\bre\ben\bna\bam\bme\bea\bat\bt() will fail and neither of the argument files will |
| 22140 | be affected if: |
| 22141 | |
| 22142 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 22143 | characters, or an entire pathname (including the |
| 22144 | terminating NUL) exceeded PATH_MAX bytes. |
| 22145 | |
| 22146 | [ENOENT] A component of the _\bf_\br_\bo_\bm path does not exist, or a path |
| 22147 | prefix of _\bt_\bo does not exist. |
| 22148 | |
| 22149 | [EACCES] A component of either path prefix denies search |
| 22150 | permission. |
| 22151 | |
| 22152 | [EACCES] The requested change requires writing in a directory |
| 22153 | that denies write permission. |
| 22154 | |
| 22155 | [EACCES] The _\bf_\br_\bo_\bm argument is a directory and denies write |
| 22156 | permission. |
| 22157 | |
| 22158 | [EPERM] The directory containing _\bf_\br_\bo_\bm is marked sticky, and |
| 22159 | neither the containing directory nor _\bf_\br_\bo_\bm are owned by |
| 22160 | the effective user ID. |
| 22161 | |
| 22162 | [EPERM] The _\bt_\bo file exists, the directory containing _\bt_\bo is |
| 22163 | marked sticky, and neither the containing directory |
| 22164 | nor _\bt_\bo are owned by the effective user ID. |
| 22165 | |
| 22166 | [ELOOP] Too many symbolic links were encountered in |
| 22167 | translating either pathname. |
| 22168 | |
| 22169 | [EMLINK] The link count on the source file or destination |
| 22170 | directory is at the maximum. A rename cannot be |
| 22171 | completed under these conditions. |
| 22172 | |
| 22173 | [ENOTDIR] A component of either path prefix is not a directory. |
| 22174 | |
| 22175 | [ENOTDIR] _\bf_\br_\bo_\bm is a directory, but _\bt_\bo is not a directory. |
| 22176 | |
| 22177 | [EISDIR] _\bt_\bo is a directory, but _\bf_\br_\bo_\bm is not a directory. |
| 22178 | |
| 22179 | [EXDEV] The link named by _\bt_\bo and the file named by _\bf_\br_\bo_\bm are on |
| 22180 | different logical devices (file systems). Note that |
| 22181 | this error code will not be returned if the |
| 22182 | implementation permits cross-device links. |
| 22183 | |
| 22184 | [ENOSPC] The directory in which the entry for the new name is |
| 22185 | being placed cannot be extended because there is no |
| 22186 | space left on the file system containing the |
| 22187 | directory. |
| 22188 | |
| 22189 | [EDQUOT] The directory in which the entry for the new name is |
| 22190 | being placed cannot be extended because the user's |
| 22191 | quota of disk blocks on the file system containing the |
| 22192 | directory has been exhausted. |
| 22193 | |
| 22194 | [EIO] An I/O error occurred while making or updating a |
| 22195 | directory entry. |
| 22196 | |
| 22197 | [EROFS] The requested link requires writing in a directory on |
| 22198 | a read-only file system. |
| 22199 | |
| 22200 | [EFAULT] _\bf_\br_\bo_\bm or _\bt_\bo points outside the process's allocated |
| 22201 | address space. |
| 22202 | |
| 22203 | [EINVAL] _\bf_\br_\bo_\bm is a parent directory of _\bt_\bo, or an attempt is |
| 22204 | made to rename `.' or `..'. |
| 22205 | |
| 22206 | [ENOTEMPTY] _\bt_\bo is a directory and is not empty. |
| 22207 | |
| 22208 | Additionally, r\bre\ben\bna\bam\bme\bea\bat\bt() will fail if: |
| 22209 | |
| 22210 | [EBADF] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path and |
| 22211 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd argument, respectively, is neither |
| 22212 | AT_FDCWD nor a valid file descriptor. |
| 22213 | |
| 22214 | [ENOTDIR] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path and |
| 22215 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd argument, respectively, is a valid |
| 22216 | file descriptor but it does not reference a directory. |
| 22217 | |
| 22218 | [EACCES] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path but |
| 22219 | search permission is denied for the directory which |
| 22220 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd file descriptor, respectively, |
| 22221 | references. |
| 22222 | |
| 22223 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22224 | mv(1), open(2), symlink(7) |
| 22225 | |
| 22226 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 22227 | The r\bre\ben\bna\bam\bme\be() and r\bre\ben\bna\bam\bme\bea\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 22228 | (``POSIX.1''). |
| 22229 | |
| 22230 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 22231 | The r\bre\ben\bna\bam\bme\bea\bat\bt() function appeared in OpenBSD 5.0. |
| 22232 | |
| 22233 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 22234 | The system can deadlock if a loop in the file system graph is present. |
| 22235 | This loop takes the form of an entry in directory `_\ba', say `_\ba_\b/_\bf_\bo_\bo', being |
| 22236 | a hard link to directory `_\bb', and an entry in directory `_\bb', say `_\bb_\b/_\bb_\ba_\br', |
| 22237 | being a hard link to directory `_\ba'. When such a loop exists and two |
| 22238 | separate processes attempt to perform `rename a/foo b/bar' and `rename |
| 22239 | b/bar a/foo', respectively, the system may deadlock attempting to lock |
| 22240 | both directories for modification. Hard links to directories should be |
| 22241 | replaced by symbolic links by the system administrator. |
| 22242 | |
| 22243 | N\bNA\bAM\bME\bE |
| 22244 | r\bre\ben\bna\bam\bme\be, r\bre\ben\bna\bam\bme\bea\bat\bt - change the name of a file |
| 22245 | |
| 22246 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22247 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> |
| 22248 | |
| 22249 | _\bi_\bn_\bt |
| 22250 | r\bre\ben\bna\bam\bme\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\br_\bo_\bm, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\bo); |
| 22251 | |
| 22252 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 22253 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> |
| 22254 | |
| 22255 | _\bi_\bn_\bt |
| 22256 | r\bre\ben\bna\bam\bme\bea\bat\bt(_\bi_\bn_\bt _\bf_\br_\bo_\bm_\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\br_\bo_\bm, _\bi_\bn_\bt _\bt_\bo_\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\bo); |
| 22257 | |
| 22258 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22259 | The r\bre\ben\bna\bam\bme\be() function causes the link named _\bf_\br_\bo_\bm to be renamed as _\bt_\bo. If |
| 22260 | _\bt_\bo exists, it is first removed. Both _\bf_\br_\bo_\bm and _\bt_\bo must be of the same |
| 22261 | type (that is, both directories or both non-directories), and must reside |
| 22262 | on the same file system. |
| 22263 | |
| 22264 | r\bre\ben\bna\bam\bme\be() guarantees that if _\bt_\bo already exists, an instance of _\bt_\bo will |
| 22265 | always exist, even if the system should crash in the middle of the |
| 22266 | operation. |
| 22267 | |
| 22268 | If the final component of _\bf_\br_\bo_\bm is a symbolic link, the symbolic link is |
| 22269 | renamed, not the file or directory to which it points. |
| 22270 | |
| 22271 | The r\bre\ben\bna\bam\bme\bea\bat\bt() function is equivalent to r\bre\ben\bna\bam\bme\be() except that where _\bf_\br_\bo_\bm |
| 22272 | or _\bt_\bo specifies a relative path, the directory entry names used are |
| 22273 | resolved relative to the directories associated with file descriptors |
| 22274 | _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd (respectively) instead of the current working directory. |
| 22275 | |
| 22276 | If r\bre\ben\bna\bam\bme\bea\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 22277 | in the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd parameter, the current working directory is used |
| 22278 | for resolving the respective _\bf_\br_\bo_\bm or _\bt_\bo argument. |
| 22279 | |
| 22280 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22281 | Upon successful completion, the value 0 is returned; otherwise the |
| 22282 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 22283 | error. |
| 22284 | |
| 22285 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22286 | r\bre\ben\bna\bam\bme\be() and r\bre\ben\bna\bam\bme\bea\bat\bt() will fail and neither of the argument files will |
| 22287 | be affected if: |
| 22288 | |
| 22289 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 22290 | characters, or an entire pathname (including the |
| 22291 | terminating NUL) exceeded PATH_MAX bytes. |
| 22292 | |
| 22293 | [ENOENT] A component of the _\bf_\br_\bo_\bm path does not exist, or a path |
| 22294 | prefix of _\bt_\bo does not exist. |
| 22295 | |
| 22296 | [EACCES] A component of either path prefix denies search |
| 22297 | permission. |
| 22298 | |
| 22299 | [EACCES] The requested change requires writing in a directory |
| 22300 | that denies write permission. |
| 22301 | |
| 22302 | [EACCES] The _\bf_\br_\bo_\bm argument is a directory and denies write |
| 22303 | permission. |
| 22304 | |
| 22305 | [EPERM] The directory containing _\bf_\br_\bo_\bm is marked sticky, and |
| 22306 | neither the containing directory nor _\bf_\br_\bo_\bm are owned by |
| 22307 | the effective user ID. |
| 22308 | |
| 22309 | [EPERM] The _\bt_\bo file exists, the directory containing _\bt_\bo is |
| 22310 | marked sticky, and neither the containing directory |
| 22311 | nor _\bt_\bo are owned by the effective user ID. |
| 22312 | |
| 22313 | [ELOOP] Too many symbolic links were encountered in |
| 22314 | translating either pathname. |
| 22315 | |
| 22316 | [EMLINK] The link count on the source file or destination |
| 22317 | directory is at the maximum. A rename cannot be |
| 22318 | completed under these conditions. |
| 22319 | |
| 22320 | [ENOTDIR] A component of either path prefix is not a directory. |
| 22321 | |
| 22322 | [ENOTDIR] _\bf_\br_\bo_\bm is a directory, but _\bt_\bo is not a directory. |
| 22323 | |
| 22324 | [EISDIR] _\bt_\bo is a directory, but _\bf_\br_\bo_\bm is not a directory. |
| 22325 | |
| 22326 | [EXDEV] The link named by _\bt_\bo and the file named by _\bf_\br_\bo_\bm are on |
| 22327 | different logical devices (file systems). Note that |
| 22328 | this error code will not be returned if the |
| 22329 | implementation permits cross-device links. |
| 22330 | |
| 22331 | [ENOSPC] The directory in which the entry for the new name is |
| 22332 | being placed cannot be extended because there is no |
| 22333 | space left on the file system containing the |
| 22334 | directory. |
| 22335 | |
| 22336 | [EDQUOT] The directory in which the entry for the new name is |
| 22337 | being placed cannot be extended because the user's |
| 22338 | quota of disk blocks on the file system containing the |
| 22339 | directory has been exhausted. |
| 22340 | |
| 22341 | [EIO] An I/O error occurred while making or updating a |
| 22342 | directory entry. |
| 22343 | |
| 22344 | [EROFS] The requested link requires writing in a directory on |
| 22345 | a read-only file system. |
| 22346 | |
| 22347 | [EFAULT] _\bf_\br_\bo_\bm or _\bt_\bo points outside the process's allocated |
| 22348 | address space. |
| 22349 | |
| 22350 | [EINVAL] _\bf_\br_\bo_\bm is a parent directory of _\bt_\bo, or an attempt is |
| 22351 | made to rename `.' or `..'. |
| 22352 | |
| 22353 | [ENOTEMPTY] _\bt_\bo is a directory and is not empty. |
| 22354 | |
| 22355 | Additionally, r\bre\ben\bna\bam\bme\bea\bat\bt() will fail if: |
| 22356 | |
| 22357 | [EBADF] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path and |
| 22358 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd argument, respectively, is neither |
| 22359 | AT_FDCWD nor a valid file descriptor. |
| 22360 | |
| 22361 | [ENOTDIR] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path and |
| 22362 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd argument, respectively, is a valid |
| 22363 | file descriptor but it does not reference a directory. |
| 22364 | |
| 22365 | [EACCES] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path but |
| 22366 | search permission is denied for the directory which |
| 22367 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd file descriptor, respectively, |
| 22368 | references. |
| 22369 | |
| 22370 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22371 | mv(1), open(2), symlink(7) |
| 22372 | |
| 22373 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 22374 | The r\bre\ben\bna\bam\bme\be() and r\bre\ben\bna\bam\bme\bea\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 22375 | (``POSIX.1''). |
| 22376 | |
| 22377 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 22378 | The r\bre\ben\bna\bam\bme\bea\bat\bt() function appeared in OpenBSD 5.0. |
| 22379 | |
| 22380 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 22381 | The system can deadlock if a loop in the file system graph is present. |
| 22382 | This loop takes the form of an entry in directory `_\ba', say `_\ba_\b/_\bf_\bo_\bo', being |
| 22383 | a hard link to directory `_\bb', and an entry in directory `_\bb', say `_\bb_\b/_\bb_\ba_\br', |
| 22384 | being a hard link to directory `_\ba'. When such a loop exists and two |
| 22385 | separate processes attempt to perform `rename a/foo b/bar' and `rename |
| 22386 | b/bar a/foo', respectively, the system may deadlock attempting to lock |
| 22387 | both directories for modification. Hard links to directories should be |
| 22388 | replaced by symbolic links by the system administrator. |
| 22389 | |
| 22390 | N\bNA\bAM\bME\bE |
| 22391 | r\bre\bev\bvo\bok\bke\be - revoke file access |
| 22392 | |
| 22393 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22394 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 22395 | |
| 22396 | _\bi_\bn_\bt |
| 22397 | r\bre\bev\bvo\bok\bke\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
| 22398 | |
| 22399 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22400 | The r\bre\bev\bvo\bok\bke\be function invalidates all current open file descriptors in the |
| 22401 | system for the file named by _\bp_\ba_\bt_\bh. Subsequent operations on any such |
| 22402 | descriptors fail, with the exceptions that a r\bre\bea\bad\bd() from a character |
| 22403 | device file which has been revoked returns a count of zero (end of file), |
| 22404 | and a c\bcl\blo\bos\bse\be() call will succeed. If the file is a special file for a |
| 22405 | device which is open, the device close function is called as if all open |
| 22406 | references to the file had been closed. |
| 22407 | |
| 22408 | Access to a file may be revoked only by its owner or the superuser. The |
| 22409 | r\bre\bev\bvo\bok\bke\be function is normally used to prepare a terminal device for a new |
| 22410 | login session, preventing any access by a previous user of the terminal. |
| 22411 | |
| 22412 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22413 | Upon successful completion, the value 0 is returned; otherwise the |
| 22414 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 22415 | error. |
| 22416 | |
| 22417 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22418 | Access to the named file is revoked unless one of the following: |
| 22419 | |
| 22420 | [ENOTDIR] A component of the path prefix is not a directory. |
| 22421 | |
| 22422 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 22423 | characters, or an entire pathname (including the |
| 22424 | terminating NUL) exceeded PATH_MAX bytes. |
| 22425 | |
| 22426 | [ENOENT] The named file or a component of the path name does |
| 22427 | not exist. |
| 22428 | |
| 22429 | [EACCES] Search permission is denied for a component of the |
| 22430 | path prefix. |
| 22431 | |
| 22432 | [ELOOP] Too many symbolic links were encountered in |
| 22433 | translating the pathname. |
| 22434 | |
| 22435 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 22436 | space. |
| 22437 | |
| 22438 | [EPERM] The caller is neither the owner of the file nor the |
| 22439 | superuser. |
| 22440 | |
| 22441 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22442 | close(2) |
| 22443 | |
| 22444 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 22445 | The r\bre\bev\bvo\bok\bke\be function was introduced in 4.3BSD-Reno. |
| 22446 | |
| 22447 | N\bNA\bAM\bME\bE |
| 22448 | r\brm\bmd\bdi\bir\br - remove a directory file |
| 22449 | |
| 22450 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22451 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 22452 | |
| 22453 | _\bi_\bn_\bt |
| 22454 | r\brm\bmd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
| 22455 | |
| 22456 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22457 | r\brm\bmd\bdi\bir\br() removes a directory file whose name is given by _\bp_\ba_\bt_\bh. The |
| 22458 | directory must not have any entries other than `.' and `..'. |
| 22459 | |
| 22460 | There is no r\brm\bmd\bdi\bir\bra\bat\bt() function; to remove a directory with a path |
| 22461 | relative to the directory associated with a file descriptor use the |
| 22462 | unlinkat(2) function with the AT_REMOVEDIR flag. |
| 22463 | |
| 22464 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22465 | Upon successful completion, the value 0 is returned; otherwise the |
| 22466 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 22467 | error. |
| 22468 | |
| 22469 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22470 | The named file is removed unless: |
| 22471 | |
| 22472 | [ENOTDIR] A component of the path is not a directory. |
| 22473 | |
| 22474 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 22475 | characters, or an entire pathname (including the |
| 22476 | terminating NUL) exceeded PATH_MAX bytes. |
| 22477 | |
| 22478 | [ENOENT] The named directory does not exist. |
| 22479 | |
| 22480 | [ELOOP] Too many symbolic links were encountered in |
| 22481 | translating the pathname. |
| 22482 | |
| 22483 | [ENOTEMPTY] The named directory contains files other than `.' and |
| 22484 | `..' in it. |
| 22485 | |
| 22486 | [EACCES] Search permission is denied for a component of the |
| 22487 | path prefix. |
| 22488 | |
| 22489 | [EACCES] Write permission is denied on the directory containing |
| 22490 | the directory to be removed. |
| 22491 | |
| 22492 | [EPERM] The directory containing the directory to be removed |
| 22493 | is marked sticky, and neither the containing directory |
| 22494 | nor the directory to be removed are owned by the |
| 22495 | effective user ID. |
| 22496 | |
| 22497 | [EPERM] The directory to be removed or the directory |
| 22498 | containing it has its immutable or append-only flag |
| 22499 | set (see chflags(2)). |
| 22500 | |
| 22501 | [EBUSY] The directory to be removed is the mount point for a |
| 22502 | mounted file system or the current directory. |
| 22503 | |
| 22504 | [EIO] An I/O error occurred while deleting the directory |
| 22505 | entry or deallocating the inode. |
| 22506 | |
| 22507 | [EROFS] The directory entry to be removed resides on a read- |
| 22508 | only file system. |
| 22509 | |
| 22510 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 22511 | space. |
| 22512 | |
| 22513 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22514 | rmdir(1), chflags(2), mkdir(2), unlink(2) |
| 22515 | |
| 22516 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 22517 | r\brm\bmd\bdi\bir\br() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 22518 | |
| 22519 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 22520 | The r\brm\bmd\bdi\bir\br() function call appeared in 4.2BSD. |
| 22521 | |
| 22522 | N\bNA\bAM\bME\bE |
| 22523 | b\bbr\brk\bk, s\bsb\bbr\brk\bk - change data segment size |
| 22524 | |
| 22525 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22526 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 22527 | |
| 22528 | _\bi_\bn_\bt |
| 22529 | b\bbr\brk\bk(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br); |
| 22530 | |
| 22531 | _\bv_\bo_\bi_\bd _\b* |
| 22532 | s\bsb\bbr\brk\bk(_\bi_\bn_\bt _\bi_\bn_\bc_\br); |
| 22533 | |
| 22534 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22535 | T\bTh\bhe\be b\bbr\brk\bk(\b()\b) a\ban\bnd\bd s\bsb\bbr\brk\bk(\b()\b) f\bfu\bun\bnc\bct\bti\bio\bon\bns\bs a\bar\bre\be h\bhi\bis\bst\bto\bor\bri\bic\bca\bal\bl c\bcu\bur\bri\bio\bos\bsi\bit\bti\bie\bes\bs l\ble\bef\bft\bt o\bov\bve\ber\br f\bfr\bro\bom\bm |
| 22536 | e\bea\bar\brl\bli\bie\ber\br d\bda\bay\bys\bs b\bbe\bef\bfo\bor\bre\be t\bth\bhe\be a\bad\bdv\bve\ben\bnt\bt o\bof\bf v\bvi\bir\brt\btu\bua\bal\bl m\bme\bem\bmo\bor\bry\by m\bma\ban\bna\bag\bge\bem\bme\ben\bnt\bt.\b. The b\bbr\brk\bk() |
| 22537 | function sets the break or lowest address of a process's data segment |
| 22538 | (uninitialized data) to _\ba_\bd_\bd_\br (immediately above bss). Data addressing is |
| 22539 | restricted between _\ba_\bd_\bd_\br and the lowest stack pointer to the stack |
| 22540 | segment. Memory is allocated by b\bbr\brk\bk() in page size pieces; if _\ba_\bd_\bd_\br is |
| 22541 | not evenly divisible by the system page size, it is increased to the next |
| 22542 | page boundary. |
| 22543 | |
| 22544 | The current value of the program break is reliably returned by |
| 22545 | ``sbrk(0)'' (see also end(3)). The getrlimit(2) system call may be used |
| 22546 | to determine the maximum permissible size of the _\bd_\ba_\bt_\ba segment; it will |
| 22547 | not be possible to set the break beyond the _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx value returned from |
| 22548 | a call to getrlimit(2), e.g., ``etext + rlp->rlim_max'' (see end(3) for |
| 22549 | the definition of _\be_\bt_\be_\bx_\bt). |
| 22550 | |
| 22551 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22552 | The b\bbr\brk\bk() function returns the value 0 if successful; otherwise the |
| 22553 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 22554 | error. |
| 22555 | |
| 22556 | The s\bsb\bbr\brk\bk() function returns a pointer to the base of the new storage if |
| 22557 | successful; otherwise -1 with _\be_\br_\br_\bn_\bo set to indicate why the allocation |
| 22558 | failed. |
| 22559 | |
| 22560 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22561 | s\bsb\bbr\brk\bk() will fail and no additional memory will be allocated if one of the |
| 22562 | following are true: |
| 22563 | |
| 22564 | [ENOMEM] The limit, as set by setrlimit(2), was exceeded. |
| 22565 | |
| 22566 | [ENOMEM] The maximum possible size of a data segment (compiled |
| 22567 | into the system) was exceeded. |
| 22568 | |
| 22569 | [ENOMEM] Insufficient space existed in the swap area to support |
| 22570 | the expansion. |
| 22571 | |
| 22572 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22573 | execve(2), getrlimit(2), mmap(2), end(3), malloc(3) |
| 22574 | |
| 22575 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 22576 | A b\bbr\brk\bk() function call appeared in Version 7 AT&T UNIX. |
| 22577 | |
| 22578 | B\bBU\bUG\bGS\bS |
| 22579 | Setting the break may fail due to a temporary lack of swap space. It is |
| 22580 | not possible to distinguish this from a failure caused by exceeding the |
| 22581 | maximum size of the data segment without consulting getrlimit(2). |
| 22582 | |
| 22583 | N\bNA\bAM\bME\bE |
| 22584 | s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd - yield the processor |
| 22585 | |
| 22586 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22587 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsc\bch\bhe\bed\bd.\b.h\bh>\b> |
| 22588 | |
| 22589 | _\bi_\bn_\bt |
| 22590 | s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd(_\bv_\bo_\bi_\bd); |
| 22591 | |
| 22592 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22593 | The s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd() function makes the current thread yield the processor |
| 22594 | and be put at the end of its run queue without altering its priority. |
| 22595 | |
| 22596 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22597 | Upon successful completion, the value 0 is returned; otherwise the |
| 22598 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 22599 | error. |
| 22600 | |
| 22601 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 22602 | The s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd() function conforms to IEEE Std 1003.1-2008 |
| 22603 | (``POSIX.1''). |
| 22604 | |
| 22605 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 22606 | The s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd() system call appeared in OpenBSD 4.2. |
| 22607 | |
| 22608 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 22609 | The effect of s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd() is only precisely defined for real-time |
| 22610 | scheduling classes, none of which are currently supported by OpenBSD. |
| 22611 | |
| 22612 | N\bNA\bAM\bME\bE |
| 22613 | s\bse\bel\ble\bec\bct\bt, p\bps\bse\bel\ble\bec\bct\bt - synchronous I/O multiplexing |
| 22614 | |
| 22615 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22616 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bel\ble\bec\bct\bt.\b.h\bh>\b> |
| 22617 | |
| 22618 | _\bi_\bn_\bt |
| 22619 | s\bse\bel\ble\bec\bct\bt(_\bi_\bn_\bt _\bn_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\br_\be_\ba_\bd_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs, |
| 22620 | _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
| 22621 | |
| 22622 | _\bi_\bn_\bt |
| 22623 | p\bps\bse\bel\ble\bec\bct\bt(_\bi_\bn_\bt _\bn_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\br_\be_\ba_\bd_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs, |
| 22624 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bm_\ba_\bs_\bk); |
| 22625 | |
| 22626 | F\bFD\bD_\b_S\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
| 22627 | |
| 22628 | F\bFD\bD_\b_C\bCL\bLR\bR(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
| 22629 | |
| 22630 | F\bFD\bD_\b_I\bIS\bSS\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
| 22631 | |
| 22632 | F\bFD\bD_\b_Z\bZE\bER\bRO\bO(_\b&_\bf_\bd_\bs_\be_\bt); |
| 22633 | |
| 22634 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22635 | s\bse\bel\ble\bec\bct\bt() examines the I/O descriptor sets whose addresses are passed in |
| 22636 | _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, and _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs to see if some of their descriptors are |
| 22637 | ready for reading, are ready for writing, or have an exceptional |
| 22638 | condition pending, respectively. The first _\bn_\bf_\bd_\bs descriptors are checked |
| 22639 | in each set; i.e., the descriptors from 0 through _\bn_\bf_\bd_\bs-1 in the |
| 22640 | descriptor sets are examined. On return, s\bse\bel\ble\bec\bct\bt() replaces the given |
| 22641 | descriptor sets with subsets consisting of those descriptors that are |
| 22642 | ready for the requested operation. s\bse\bel\ble\bec\bct\bt() returns the total number of |
| 22643 | ready descriptors in all the sets. |
| 22644 | |
| 22645 | The descriptor sets are stored as bit fields in arrays of integers. The |
| 22646 | following macros are provided for manipulating such descriptor sets: |
| 22647 | F\bFD\bD_\b_Z\bZE\bER\bRO\bO(_\b&_\bf_\bd_\bs_\be_\bt) initializes a descriptor set _\bf_\bd_\bs_\be_\bt to the null set. |
| 22648 | F\bFD\bD_\b_S\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) includes a particular descriptor _\bf_\bd in _\bf_\bd_\bs_\be_\bt. |
| 22649 | F\bFD\bD_\b_C\bCL\bLR\bR(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) removes _\bf_\bd from _\bf_\bd_\bs_\be_\bt. F\bFD\bD_\b_I\bIS\bSS\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) is non- |
| 22650 | zero if _\bf_\bd is a member of _\bf_\bd_\bs_\be_\bt, zero otherwise. The behavior of these |
| 22651 | macros is undefined if a descriptor value is less than zero or greater |
| 22652 | than or equal to FD_SETSIZE, which is normally at least equal to the |
| 22653 | maximum number of descriptors supported by the system. |
| 22654 | |
| 22655 | If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it specifies a maximum interval to wait |
| 22656 | for the selection to complete. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, the select |
| 22657 | blocks indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
| 22658 | non-null, pointing to a zero-valued timeval structure. _\bt_\bi_\bm_\be_\bo_\bu_\bt is not |
| 22659 | changed by s\bse\bel\ble\bec\bct\bt(), and may be reused on subsequent calls; however, it |
| 22660 | is good style to re-initialize it before each invocation of s\bse\bel\ble\bec\bct\bt(). |
| 22661 | |
| 22662 | Any of _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, and _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs may be given as null pointers if |
| 22663 | no descriptors are of interest. |
| 22664 | |
| 22665 | The p\bps\bse\bel\ble\bec\bct\bt() function is similar to s\bse\bel\ble\bec\bct\bt() except that it specifies |
| 22666 | the timeout using a timespec structure. Also, if _\bm_\ba_\bs_\bk is a non-null |
| 22667 | pointer, p\bps\bse\bel\ble\bec\bct\bt() atomically sets the calling thread's signal mask to |
| 22668 | the signal set pointed to by _\bm_\ba_\bs_\bk for the duration of the function call. |
| 22669 | In this case, the original signal mask will be restored before p\bps\bse\bel\ble\bec\bct\bt() |
| 22670 | returns. |
| 22671 | |
| 22672 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22673 | If successful, s\bse\bel\ble\bec\bct\bt() and p\bps\bse\bel\ble\bec\bct\bt() return the number of ready |
| 22674 | descriptors that are contained in the descriptor sets. If a descriptor |
| 22675 | is included in multiple descriptor sets, each inclusion is counted |
| 22676 | separately. If the time limit expires before any descriptors become |
| 22677 | ready, they return 0. |
| 22678 | |
| 22679 | Otherwise, if s\bse\bel\ble\bec\bct\bt() or p\bps\bse\bel\ble\bec\bct\bt() return with an error, including one |
| 22680 | due to an interrupted call, they return -1, and the descriptor sets will |
| 22681 | be unmodified. |
| 22682 | |
| 22683 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22684 | An error return from s\bse\bel\ble\bec\bct\bt() or p\bps\bse\bel\ble\bec\bct\bt() indicates: |
| 22685 | |
| 22686 | [EFAULT] One or more of _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, or _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs points |
| 22687 | outside the process's allocated address space. |
| 22688 | |
| 22689 | [EBADF] One of the descriptor sets specified an invalid |
| 22690 | descriptor. |
| 22691 | |
| 22692 | [EINTR] A signal was delivered before the time limit expired |
| 22693 | and before any of the selected descriptors became |
| 22694 | ready. |
| 22695 | |
| 22696 | [EINVAL] The specified time limit is invalid. One of its |
| 22697 | components is negative or too large. |
| 22698 | |
| 22699 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22700 | accept(2), clock_gettime(2), connect(2), gettimeofday(2), poll(2), |
| 22701 | read(2), recv(2), send(2), write(2), getdtablesize(3) |
| 22702 | |
| 22703 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 22704 | The s\bse\bel\ble\bec\bct\bt() system call first appeared in 4.1cBSD. The p\bps\bse\bel\ble\bec\bct\bt() system |
| 22705 | call has been available since OpenBSD 5.4. |
| 22706 | |
| 22707 | B\bBU\bUG\bGS\bS |
| 22708 | Although the provision of getdtablesize(3) was intended to allow user |
| 22709 | programs to be written independent of the kernel limit on the number of |
| 22710 | open files, the dimension of a sufficiently large bit field for select |
| 22711 | remains a problem. The default bit size of _\bf_\bd_\b__\bs_\be_\bt is based on the symbol |
| 22712 | FD_SETSIZE (currently 1024), but that is somewhat smaller than the |
| 22713 | current kernel limit to the number of open files. However, in order to |
| 22714 | accommodate programs which might potentially use a larger number of open |
| 22715 | files with select, it is possible to increase this size within a program |
| 22716 | by providing a larger definition of FD_SETSIZE before the inclusion of |
| 22717 | any headers. The kernel will cope, and the userland libraries provided |
| 22718 | with the system are also ready for large numbers of file descriptors. |
| 22719 | |
| 22720 | Alternatively, to be really safe, it is possible to allocate _\bf_\bd_\b__\bs_\be_\bt bit- |
| 22721 | arrays dynamically. The idea is to permit a program to work properly |
| 22722 | even if it is execve(2)'d with 4000 file descriptors pre-allocated. The |
| 22723 | following illustrates the technique which is used by userland libraries: |
| 22724 | |
| 22725 | fd_set *fdsr; |
| 22726 | int max = fd; |
| 22727 | |
| 22728 | fdsr = calloc(howmany(max+1, NFDBITS), sizeof(fd_mask)); |
| 22729 | if (fdsr == NULL) { |
| 22730 | ... |
| 22731 | return (-1); |
| 22732 | } |
| 22733 | FD_SET(fd, fdsr); |
| 22734 | n = select(max+1, fdsr, NULL, NULL, &tv); |
| 22735 | ... |
| 22736 | free(fdsr); |
| 22737 | |
| 22738 | Alternatively, it is possible to use the poll(2) interface. poll(2) is |
| 22739 | more efficient when the size of s\bse\bel\ble\bec\bct\bt()'s _\bf_\bd_\b__\bs_\be_\bt bit-arrays are very |
| 22740 | large, and for fixed numbers of file descriptors one need not size and |
| 22741 | dynamically allocate a memory object. |
| 22742 | |
| 22743 | s\bse\bel\ble\bec\bct\bt() should probably have been designed to return the time remaining |
| 22744 | from the original timeout, if any, by modifying the time value in place. |
| 22745 | Even though some systems stupidly act in this different way, it is |
| 22746 | unlikely this semantic will ever be commonly implemented, as the change |
| 22747 | causes massive source code compatibility problems. Furthermore, recent |
| 22748 | new standards have dictated the current behaviour. In general, due to |
| 22749 | the existence of those brain-damaged non-conforming systems, it is unwise |
| 22750 | to assume that the timeout value will be unmodified by the s\bse\bel\ble\bec\bct\bt() call, |
| 22751 | and the caller should reinitialize it on each invocation. Calculating |
| 22752 | the delta is easily done by calling gettimeofday(2) before and after the |
| 22753 | call to s\bse\bel\ble\bec\bct\bt(), and using t\bti\bim\bme\ber\brs\bsu\bub\bb() (as described in getitimer(2)). |
| 22754 | |
| 22755 | Internally to the kernel, s\bse\bel\ble\bec\bct\bt() and p\bps\bse\bel\ble\bec\bct\bt() work poorly if multiple |
| 22756 | processes wait on the same file descriptor. Given that, it is rather |
| 22757 | surprising to see that many daemons are written that way. |
| 22758 | |
| 22759 | N\bNA\bAM\bME\bE |
| 22760 | s\bse\bem\bmc\bct\btl\bl - semaphore control operations |
| 22761 | |
| 22762 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22763 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bem\bm.\b.h\bh>\b> |
| 22764 | |
| 22765 | _\bi_\bn_\bt |
| 22766 | s\bse\bem\bmc\bct\btl\bl(_\bi_\bn_\bt _\bs_\be_\bm_\bi_\bd, _\bi_\bn_\bt _\bs_\be_\bm_\bn_\bu_\bm, _\bi_\bn_\bt _\bc_\bm_\bd, _\bu_\bn_\bi_\bo_\bn _\bs_\be_\bm_\bu_\bn _\ba_\br_\bg); |
| 22767 | |
| 22768 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22769 | The s\bse\bem\bmc\bct\btl\bl() system call provides a number of control operations on the |
| 22770 | semaphore specified by _\bs_\be_\bm_\bn_\bu_\bm and _\bs_\be_\bm_\bi_\bd. The operation to be performed |
| 22771 | is specified in _\bc_\bm_\bd (see below). _\ba_\br_\bg is a union of the following fields: |
| 22772 | |
| 22773 | int val; /* value for SETVAL */ |
| 22774 | struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */ |
| 22775 | u_short *array; /* array for GETALL & SETALL */ |
| 22776 | |
| 22777 | The semid_ds structure used in the IPC_SET and IPC_STAT commands is |
| 22778 | defined as follows in <_\bs_\by_\bs_\b/_\bs_\be_\bm_\b._\bh>: |
| 22779 | |
| 22780 | struct semid_ds { |
| 22781 | struct ipc_perm sem_perm; /* operation permissions */ |
| 22782 | struct sem *sem_base; /* semaphore set */ |
| 22783 | u_short sem_nsems; /* number of sems in set */ |
| 22784 | time_t sem_otime; /* last operation time */ |
| 22785 | time_t sem_ctime; /* last change time */ |
| 22786 | }; |
| 22787 | |
| 22788 | The ipc_perm structure used inside the semid_ds structure is defined in |
| 22789 | <_\bs_\by_\bs_\b/_\bi_\bp_\bc_\b._\bh> and looks like this: |
| 22790 | |
| 22791 | struct ipc_perm { |
| 22792 | uid_t cuid; /* creator user id */ |
| 22793 | gid_t cgid; /* creator group id */ |
| 22794 | uid_t uid; /* user id */ |
| 22795 | gid_t gid; /* group id */ |
| 22796 | mode_t mode; /* r/w permission (see chmod(2)) */ |
| 22797 | u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ |
| 22798 | key_t key; /* user specified msg/sem/shm key */ |
| 22799 | }; |
| 22800 | |
| 22801 | s\bse\bem\bmc\bct\btl\bl() provides the following operations: |
| 22802 | |
| 22803 | GETVAL Return the value of the semaphore. |
| 22804 | |
| 22805 | SETVAL Set the value of the semaphore to _\ba_\br_\bg_\b._\bv_\ba_\bl. |
| 22806 | |
| 22807 | GETPID Return the pid of the last process that did an operation on |
| 22808 | this semaphore. |
| 22809 | |
| 22810 | GETNCNT Return the number of processes waiting to acquire the |
| 22811 | semaphore. |
| 22812 | |
| 22813 | GETZCNT Return the number of processes waiting for the value of the |
| 22814 | semaphore to reach 0. |
| 22815 | |
| 22816 | GETALL Return the values for all the semaphores associated with |
| 22817 | _\bs_\be_\bm_\bi_\bd. |
| 22818 | |
| 22819 | SETALL Set the values for all the semaphores that are associated with |
| 22820 | the semaphore identifier _\bs_\be_\bm_\bi_\bd to the corresponding values in |
| 22821 | _\ba_\br_\bg_\b._\ba_\br_\br_\ba_\by. |
| 22822 | |
| 22823 | IPC_STAT Gather statistics about a semaphore and place the information |
| 22824 | in the semid_ds structure pointed to by _\ba_\br_\bg_\b._\bb_\bu_\bf (see above). |
| 22825 | |
| 22826 | IPC_SET Set the value of the _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd, _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and |
| 22827 | _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be fields in the structure associated with the |
| 22828 | semaphore. The values are taken from the corresponding fields |
| 22829 | in the structure pointed to by _\ba_\br_\bg_\b._\bb_\bu_\bf. This operation can |
| 22830 | only be executed by the superuser, or a process that has an |
| 22831 | effective user ID equal to either _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or |
| 22832 | _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd in the data structure associated with the message |
| 22833 | queue. |
| 22834 | |
| 22835 | IPC_RMID Remove the semaphores associated with _\bs_\be_\bm_\bi_\bd from the system |
| 22836 | and destroy the data structures associated with it. Only the |
| 22837 | superuser or a process with an effective UID equal to the |
| 22838 | _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd values in the data structure |
| 22839 | associated with the semaphore can do this. |
| 22840 | |
| 22841 | The permission to read or change a message queue (see semop(2)) is |
| 22842 | determined by the _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be field in the same way as is done with |
| 22843 | files (see chmod(2)), but the effective UID can match either the |
| 22844 | _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd field or the _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd field, and the effective GID can |
| 22845 | match either _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd or _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd. |
| 22846 | |
| 22847 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22848 | For the GETVAL, GETPID, GETNCNT, and GETZCNT operations, s\bse\bem\bmc\bct\btl\bl() returns |
| 22849 | one of the values described above if successful. All other operations |
| 22850 | will make s\bse\bem\bmc\bct\btl\bl() return 0 if no errors occur. Otherwise -1 is returned |
| 22851 | and _\be_\br_\br_\bn_\bo set to reflect the error. |
| 22852 | |
| 22853 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22854 | s\bse\bem\bmc\bct\btl\bl() will fail if: |
| 22855 | |
| 22856 | [EPERM] _\bc_\bm_\bd is equal to IPC_SET or IPC_RMID and the caller is |
| 22857 | not the superuser, nor does the effective UID match |
| 22858 | either the _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd or _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd fields of the |
| 22859 | data structure associated with the message queue. |
| 22860 | |
| 22861 | [EACCES] The caller has no operation permission for this |
| 22862 | semaphore. |
| 22863 | |
| 22864 | [EINVAL] _\bs_\be_\bm_\bi_\bd is not a valid message semaphore identifier. |
| 22865 | |
| 22866 | _\bc_\bm_\bd is not a valid command. |
| 22867 | |
| 22868 | [EFAULT] _\ba_\br_\bg_\b._\bb_\bu_\bf or _\ba_\br_\bg_\b._\ba_\br_\br_\ba_\by specify an invalid address. |
| 22869 | |
| 22870 | [ERANGE] _\bc_\bm_\bd is equal to SETVAL or SETALL and _\ba_\br_\bg_\b._\bv_\ba_\bl or the |
| 22871 | values in _\ba_\br_\bg_\b._\ba_\br_\br_\ba_\by are greater than the system- |
| 22872 | imposed limit. |
| 22873 | |
| 22874 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22875 | semget(2), semop(2) |
| 22876 | |
| 22877 | N\bNA\bAM\bME\bE |
| 22878 | s\bse\bem\bmg\bge\bet\bt - get semaphore set |
| 22879 | |
| 22880 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22881 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bem\bm.\b.h\bh>\b> |
| 22882 | |
| 22883 | _\bi_\bn_\bt |
| 22884 | s\bse\bem\bmg\bge\bet\bt(_\bk_\be_\by_\b__\bt _\bk_\be_\by, _\bi_\bn_\bt _\bn_\bs_\be_\bm_\bs, _\bi_\bn_\bt _\bs_\be_\bm_\bf_\bl_\bg); |
| 22885 | |
| 22886 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22887 | The s\bse\bem\bmg\bge\bet\bt() system call returns the semaphore identifier associated with |
| 22888 | _\bk_\be_\by. |
| 22889 | |
| 22890 | A new set containing _\bn_\bs_\be_\bm_\bs semaphores is created if either _\bk_\be_\by is equal |
| 22891 | to IPC_PRIVATE, or _\bk_\be_\by does not have a semaphore set associated with it |
| 22892 | and the IPC_CREAT bit is set in _\bs_\be_\bm_\bf_\bl_\bg. |
| 22893 | |
| 22894 | The access modes of the created semaphores is specified in _\bs_\be_\bm_\bf_\bl_\bg as a |
| 22895 | bitwise OR of zero or more of the following values: |
| 22896 | |
| 22897 | SEM_A alter permission for owner |
| 22898 | SEM_R read permission for owner |
| 22899 | |
| 22900 | SEM_A >> 3 alter permission for group |
| 22901 | SEM_R >> 3 read permission for group |
| 22902 | |
| 22903 | SEM_A >> 6 alter permission for other |
| 22904 | SEM_R >> 6 read permission for other |
| 22905 | |
| 22906 | If a new set of semaphores is created, the data structure associated with |
| 22907 | it (the _\bs_\be_\bm_\bi_\bd_\b__\bd_\bs structure, see semctl(2)) is initialized as follows: |
| 22908 | |
| 22909 | +\b+\bo\bo _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd and _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd are set to the effective UID of the |
| 22910 | calling process. |
| 22911 | |
| 22912 | +\b+\bo\bo _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd are set to the effective GID of the |
| 22913 | calling process. |
| 22914 | |
| 22915 | +\b+\bo\bo _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be is set to the lower 9 bits of _\bs_\be_\bm_\bf_\bl_\bg. |
| 22916 | |
| 22917 | +\b+\bo\bo _\bs_\be_\bm_\b__\bn_\bs_\be_\bm_\bs is set to the value of _\bn_\bs_\be_\bm_\bs. |
| 22918 | |
| 22919 | +\b+\bo\bo _\bs_\be_\bm_\b__\bc_\bt_\bi_\bm_\be is set to the current time. |
| 22920 | |
| 22921 | +\b+\bo\bo _\bs_\be_\bm_\b__\bo_\bt_\bi_\bm_\be is set to 0. |
| 22922 | |
| 22923 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 22924 | s\bse\bem\bmg\bge\bet\bt() returns a non-negative semaphore identifier if successful. |
| 22925 | Otherwise, -1 is returned and _\be_\br_\br_\bn_\bo is set to reflect the error. |
| 22926 | |
| 22927 | E\bER\bRR\bRO\bOR\bRS\bS |
| 22928 | [EACCES] The caller has no permission to access a semaphore set |
| 22929 | already associated with _\bk_\be_\by. |
| 22930 | |
| 22931 | [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _\bs_\be_\bm_\bf_\bl_\bg, and a |
| 22932 | semaphore set is already associated with _\bk_\be_\by. |
| 22933 | |
| 22934 | [EINVAL] _\bn_\bs_\be_\bm_\bs is less than or equal to 0 or greater than the |
| 22935 | system limit for the number in a semaphore set. |
| 22936 | |
| 22937 | A semaphore set associated with _\bk_\be_\by exists, but has |
| 22938 | fewer semaphores than the number specified in _\bn_\bs_\be_\bm_\bs. |
| 22939 | |
| 22940 | [ENOSPC] A new set of semaphores could not be created because |
| 22941 | the system limit for the number of semaphores or the |
| 22942 | number of semaphore sets has been reached. |
| 22943 | |
| 22944 | [ENOENT] IPC_CREAT was not set in _\bs_\be_\bm_\bf_\bl_\bg and no semaphore set |
| 22945 | associated with _\bk_\be_\by was found. |
| 22946 | |
| 22947 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 22948 | semctl(2), semop(2), ftok(3) |
| 22949 | |
| 22950 | N\bNA\bAM\bME\bE |
| 22951 | s\bse\bem\bmo\bop\bp - semaphore operations |
| 22952 | |
| 22953 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 22954 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bem\bm.\b.h\bh>\b> |
| 22955 | |
| 22956 | _\bi_\bn_\bt |
| 22957 | s\bse\bem\bmo\bop\bp(_\bi_\bn_\bt _\bs_\be_\bm_\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\be_\bm_\bb_\bu_\bf _\b*_\bs_\bo_\bp_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bs_\bo_\bp_\bs); |
| 22958 | |
| 22959 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 22960 | s\bse\bem\bmo\bop\bp() provides a number of atomic operations on a set of semaphores. |
| 22961 | The semaphore set is specified by _\bs_\be_\bm_\bi_\bd. _\bs_\bo_\bp_\bs is an array of semaphore |
| 22962 | operations, _\bn_\bs_\bo_\bp_\bs is the number of operations in this array. The _\bs_\be_\bm_\bb_\bu_\bf |
| 22963 | structures in the array contain the following members: |
| 22964 | |
| 22965 | u_short sem_num; /* semaphore # */ |
| 22966 | short sem_op; /* semaphore operation */ |
| 22967 | short sem_flg; /* operation flags */ |
| 22968 | |
| 22969 | Each operation (specified in _\bs_\be_\bm_\b__\bo_\bp) is applied to semaphore number |
| 22970 | _\bs_\be_\bm_\b__\bn_\bu_\bm in the set of semaphores specified by _\bs_\be_\bm_\bi_\bd. The value of _\bs_\be_\bm_\b__\bo_\bp |
| 22971 | determines the action taken in the following way: |
| 22972 | |
| 22973 | +\b+\bo\bo _\bs_\be_\bm_\b__\bo_\bp is less than 0. The current process is blocked until the |
| 22974 | value of the semaphore is greater than or equal to the absolute value |
| 22975 | of _\bs_\be_\bm_\b__\bo_\bp. The absolute value of _\bs_\be_\bm_\b__\bo_\bp is then subtracted from the |
| 22976 | value of the semaphore, and the calling process continues. Negative |
| 22977 | values of _\bs_\be_\bm_\b__\bo_\bp are thus used to enter critical regions. |
| 22978 | |
| 22979 | +\b+\bo\bo _\bs_\be_\bm_\b__\bo_\bp is greater than 0. Its value is added to the value of the |
| 22980 | specified semaphore. This is used to leave critical regions. |
| 22981 | |
| 22982 | +\b+\bo\bo _\bs_\be_\bm_\b__\bo_\bp is equal to 0. The calling process is blocked until the value |
| 22983 | of the specified semaphore reaches 0. |
| 22984 | |
| 22985 | The behavior of each operation is influenced by the flags set in _\bs_\be_\bm_\b__\bf_\bl_\bg |
| 22986 | in the following way: |
| 22987 | |
| 22988 | IPC_NOWAIT In the case where the calling process would normally block, |
| 22989 | waiting for a semaphore to reach a certain value, IPC_NOWAIT |
| 22990 | makes the call return immediately, returning a value of -1 |
| 22991 | and setting _\be_\br_\br_\bn_\bo to EAGAIN. |
| 22992 | |
| 22993 | SEM_UNDO Keep track of the changes that this call makes to the value |
| 22994 | of a semaphore, so that they can be undone when the calling |
| 22995 | process terminates. This is useful to prevent other |
| 22996 | processes waiting on a semaphore to block forever, should |
| 22997 | the process that has the semaphore locked terminate in a |
| 22998 | critical section. |
| 22999 | |
| 23000 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23001 | Upon successful completion, the value 0 is returned; otherwise the |
| 23002 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 23003 | error. |
| 23004 | |
| 23005 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23006 | s\bse\bem\bmo\bop\bp() will fail if: |
| 23007 | |
| 23008 | [EINVAL] There is no semaphore associated with _\bs_\be_\bm_\bi_\bd. |
| 23009 | |
| 23010 | [EIDRM] The semaphore set was removed while the process was |
| 23011 | waiting for one of its semaphores to reach a certain |
| 23012 | value. |
| 23013 | |
| 23014 | [EACCES] The calling process has no permission to access the |
| 23015 | specified semaphore set. |
| 23016 | |
| 23017 | [E2BIG] The value of _\bn_\bs_\bo_\bp_\bs is too big. The maximum is |
| 23018 | specified in MAX_SOPS in <_\bs_\by_\bs_\b/_\bs_\be_\bm_\b._\bh>. |
| 23019 | |
| 23020 | [EFBIG] _\bs_\be_\bm_\b__\bn_\bu_\bm in one of the sem_buf structures is less than |
| 23021 | 0, or greater than the actual number of semaphores in |
| 23022 | the set specified by _\bs_\be_\bm_\bi_\bd. |
| 23023 | |
| 23024 | [ENOSPC] SEM_UNDO was requested, and there is not enough space |
| 23025 | left in the kernel to store the undo information. |
| 23026 | |
| 23027 | [EAGAIN] The requested operation can not immediately be |
| 23028 | performed, and IPC_NOWAIT was set in _\bs_\be_\bm_\b__\bf_\bl_\bg. |
| 23029 | |
| 23030 | [EFAULT] _\bs_\bo_\bp_\bs points to an illegal address. |
| 23031 | |
| 23032 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23033 | semctl(2), semget(2) |
| 23034 | |
| 23035 | N\bNA\bAM\bME\bE |
| 23036 | s\bse\ben\bnd\bd, s\bse\ben\bnd\bdt\bto\bo, s\bse\ben\bnd\bdm\bms\bsg\bg - send a message from a socket |
| 23037 | |
| 23038 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23039 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 23040 | |
| 23041 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23042 | s\bse\ben\bnd\bd(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 23043 | |
| 23044 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23045 | s\bse\ben\bnd\bdt\bto\bo(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, |
| 23046 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bt_\bo, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bt_\bo_\bl_\be_\bn); |
| 23047 | |
| 23048 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23049 | s\bse\ben\bnd\bdm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 23050 | |
| 23051 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23052 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() are used to transmit a message to another |
| 23053 | socket. s\bse\ben\bnd\bd() may be used only when the socket is in a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd state, |
| 23054 | while s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may be used at any time. |
| 23055 | |
| 23056 | The address of the target is given by _\bt_\bo with _\bt_\bo_\bl_\be_\bn specifying its size. |
| 23057 | The length of the message is given by _\bl_\be_\bn. If the message is too long to |
| 23058 | pass atomically through the underlying protocol, the error EMSGSIZE is |
| 23059 | returned, and the message is not transmitted. |
| 23060 | |
| 23061 | No indication of failure to deliver is implicit in a s\bse\ben\bnd\bd(). Locally |
| 23062 | detected errors are indicated by a return value of -1. |
| 23063 | |
| 23064 | If no messages space is available at the socket to hold the message to be |
| 23065 | transmitted, then s\bse\ben\bnd\bd() normally blocks, unless the socket has been |
| 23066 | placed in non-blocking I/O mode. The select(2) or poll(2) system calls |
| 23067 | may be used to determine when it is possible to send more data. |
| 23068 | |
| 23069 | The _\bf_\bl_\ba_\bg_\bs parameter may include one or more of the following: |
| 23070 | |
| 23071 | MSG_DONTROUTE bypass routing tables, silently ignored |
| 23072 | MSG_DONTWAIT don't block |
| 23073 | MSG_EOR terminate the record (SOCK_SEQPACKET only) |
| 23074 | MSG_NOSIGNAL don't send SIGPIPE |
| 23075 | MSG_OOB process out-of-band data |
| 23076 | |
| 23077 | The flag MSG_OOB is used to send ``out-of-band'' data on sockets that |
| 23078 | support this notion (e.g., SOCK_STREAM); the underlying protocol must |
| 23079 | also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not |
| 23080 | to send the SIGPIPE signal if an attempt to send is made on a socket that |
| 23081 | is shut down for writing or no longer connected. |
| 23082 | |
| 23083 | See recv(2) for a description of the _\bm_\bs_\bg_\bh_\bd_\br structure. |
| 23084 | |
| 23085 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23086 | The call returns the number of characters sent, or -1 if an error |
| 23087 | occurred. |
| 23088 | |
| 23089 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23090 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() fail if: |
| 23091 | |
| 23092 | [EBADF] An invalid descriptor was specified. |
| 23093 | |
| 23094 | [ENOTSOCK] The argument _\bs is not a socket. |
| 23095 | |
| 23096 | [EFAULT] An invalid user space address was specified for a |
| 23097 | parameter. |
| 23098 | |
| 23099 | [EMSGSIZE] The socket requires that message be sent atomically, |
| 23100 | and the size of the message to be sent made this |
| 23101 | impossible. |
| 23102 | |
| 23103 | [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT |
| 23104 | flag is set and the requested operation would block. |
| 23105 | |
| 23106 | [ENOBUFS] The system was unable to allocate an internal buffer. |
| 23107 | The operation may succeed when buffers become |
| 23108 | available. |
| 23109 | |
| 23110 | [ENOBUFS] The output queue for a network interface was full. |
| 23111 | This generally indicates that the interface has |
| 23112 | stopped sending, but may be caused by transient |
| 23113 | congestion. |
| 23114 | |
| 23115 | [EACCES] The SO_BROADCAST option is not set on the socket, and |
| 23116 | a broadcast address was given as the destination. |
| 23117 | |
| 23118 | [EHOSTUNREACH] The destination address specified an unreachable host. |
| 23119 | |
| 23120 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs parameter is invalid. |
| 23121 | |
| 23122 | [EHOSTDOWN] The destination address specified a host that is down. |
| 23123 | |
| 23124 | [ENETDOWN] The destination address specified a network that is |
| 23125 | down. |
| 23126 | |
| 23127 | [ECONNREFUSED] The destination host rejected the message (or a |
| 23128 | previous one). This error can only be returned by |
| 23129 | connected sockets. |
| 23130 | |
| 23131 | [ENOPROTOOPT] There was a problem sending the message. This error |
| 23132 | can only be returned by connected sockets. |
| 23133 | |
| 23134 | [EDESTADDRREQ] The socket is not connected, and no destination |
| 23135 | address was specified. |
| 23136 | |
| 23137 | [EPIPE] The socket is shut down for writing or not longer |
| 23138 | connected and the MSG_NOSIGNAL flag is set. |
| 23139 | |
| 23140 | In addition, s\bse\ben\bnd\bd() and s\bse\ben\bnd\bdt\bto\bo() may return the following error: |
| 23141 | |
| 23142 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
| 23143 | |
| 23144 | s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
| 23145 | |
| 23146 | [EAFNOSUPPORT] Addresses in the specified address family cannot be |
| 23147 | used with this socket. |
| 23148 | |
| 23149 | [EISCONN] The socket is already connected, and a destination |
| 23150 | address was specified. |
| 23151 | |
| 23152 | s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
| 23153 | |
| 23154 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
| 23155 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 23156 | |
| 23157 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
| 23158 | than IOV_MAX. |
| 23159 | |
| 23160 | [EMFILE] The message contains control information utilizing |
| 23161 | CMSG_DATA(3) to pass file descriptors, but too many |
| 23162 | file descriptors are already in-flight. |
| 23163 | |
| 23164 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23165 | fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), |
| 23166 | write(2), CMSG_DATA(3) |
| 23167 | |
| 23168 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 23169 | The s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() functions conform to IEEE Std |
| 23170 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are |
| 23171 | extensions to that specification. |
| 23172 | |
| 23173 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23174 | The s\bse\ben\bnd\bd() function call appeared in 4.2BSD. |
| 23175 | |
| 23176 | N\bNA\bAM\bME\bE |
| 23177 | s\bse\ben\bnd\bd, s\bse\ben\bnd\bdt\bto\bo, s\bse\ben\bnd\bdm\bms\bsg\bg - send a message from a socket |
| 23178 | |
| 23179 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23180 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 23181 | |
| 23182 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23183 | s\bse\ben\bnd\bd(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 23184 | |
| 23185 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23186 | s\bse\ben\bnd\bdt\bto\bo(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, |
| 23187 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bt_\bo, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bt_\bo_\bl_\be_\bn); |
| 23188 | |
| 23189 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23190 | s\bse\ben\bnd\bdm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 23191 | |
| 23192 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23193 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() are used to transmit a message to another |
| 23194 | socket. s\bse\ben\bnd\bd() may be used only when the socket is in a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd state, |
| 23195 | while s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may be used at any time. |
| 23196 | |
| 23197 | The address of the target is given by _\bt_\bo with _\bt_\bo_\bl_\be_\bn specifying its size. |
| 23198 | The length of the message is given by _\bl_\be_\bn. If the message is too long to |
| 23199 | pass atomically through the underlying protocol, the error EMSGSIZE is |
| 23200 | returned, and the message is not transmitted. |
| 23201 | |
| 23202 | No indication of failure to deliver is implicit in a s\bse\ben\bnd\bd(). Locally |
| 23203 | detected errors are indicated by a return value of -1. |
| 23204 | |
| 23205 | If no messages space is available at the socket to hold the message to be |
| 23206 | transmitted, then s\bse\ben\bnd\bd() normally blocks, unless the socket has been |
| 23207 | placed in non-blocking I/O mode. The select(2) or poll(2) system calls |
| 23208 | may be used to determine when it is possible to send more data. |
| 23209 | |
| 23210 | The _\bf_\bl_\ba_\bg_\bs parameter may include one or more of the following: |
| 23211 | |
| 23212 | MSG_DONTROUTE bypass routing tables, silently ignored |
| 23213 | MSG_DONTWAIT don't block |
| 23214 | MSG_EOR terminate the record (SOCK_SEQPACKET only) |
| 23215 | MSG_NOSIGNAL don't send SIGPIPE |
| 23216 | MSG_OOB process out-of-band data |
| 23217 | |
| 23218 | The flag MSG_OOB is used to send ``out-of-band'' data on sockets that |
| 23219 | support this notion (e.g., SOCK_STREAM); the underlying protocol must |
| 23220 | also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not |
| 23221 | to send the SIGPIPE signal if an attempt to send is made on a socket that |
| 23222 | is shut down for writing or no longer connected. |
| 23223 | |
| 23224 | See recv(2) for a description of the _\bm_\bs_\bg_\bh_\bd_\br structure. |
| 23225 | |
| 23226 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23227 | The call returns the number of characters sent, or -1 if an error |
| 23228 | occurred. |
| 23229 | |
| 23230 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23231 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() fail if: |
| 23232 | |
| 23233 | [EBADF] An invalid descriptor was specified. |
| 23234 | |
| 23235 | [ENOTSOCK] The argument _\bs is not a socket. |
| 23236 | |
| 23237 | [EFAULT] An invalid user space address was specified for a |
| 23238 | parameter. |
| 23239 | |
| 23240 | [EMSGSIZE] The socket requires that message be sent atomically, |
| 23241 | and the size of the message to be sent made this |
| 23242 | impossible. |
| 23243 | |
| 23244 | [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT |
| 23245 | flag is set and the requested operation would block. |
| 23246 | |
| 23247 | [ENOBUFS] The system was unable to allocate an internal buffer. |
| 23248 | The operation may succeed when buffers become |
| 23249 | available. |
| 23250 | |
| 23251 | [ENOBUFS] The output queue for a network interface was full. |
| 23252 | This generally indicates that the interface has |
| 23253 | stopped sending, but may be caused by transient |
| 23254 | congestion. |
| 23255 | |
| 23256 | [EACCES] The SO_BROADCAST option is not set on the socket, and |
| 23257 | a broadcast address was given as the destination. |
| 23258 | |
| 23259 | [EHOSTUNREACH] The destination address specified an unreachable host. |
| 23260 | |
| 23261 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs parameter is invalid. |
| 23262 | |
| 23263 | [EHOSTDOWN] The destination address specified a host that is down. |
| 23264 | |
| 23265 | [ENETDOWN] The destination address specified a network that is |
| 23266 | down. |
| 23267 | |
| 23268 | [ECONNREFUSED] The destination host rejected the message (or a |
| 23269 | previous one). This error can only be returned by |
| 23270 | connected sockets. |
| 23271 | |
| 23272 | [ENOPROTOOPT] There was a problem sending the message. This error |
| 23273 | can only be returned by connected sockets. |
| 23274 | |
| 23275 | [EDESTADDRREQ] The socket is not connected, and no destination |
| 23276 | address was specified. |
| 23277 | |
| 23278 | [EPIPE] The socket is shut down for writing or not longer |
| 23279 | connected and the MSG_NOSIGNAL flag is set. |
| 23280 | |
| 23281 | In addition, s\bse\ben\bnd\bd() and s\bse\ben\bnd\bdt\bto\bo() may return the following error: |
| 23282 | |
| 23283 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
| 23284 | |
| 23285 | s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
| 23286 | |
| 23287 | [EAFNOSUPPORT] Addresses in the specified address family cannot be |
| 23288 | used with this socket. |
| 23289 | |
| 23290 | [EISCONN] The socket is already connected, and a destination |
| 23291 | address was specified. |
| 23292 | |
| 23293 | s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
| 23294 | |
| 23295 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
| 23296 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 23297 | |
| 23298 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
| 23299 | than IOV_MAX. |
| 23300 | |
| 23301 | [EMFILE] The message contains control information utilizing |
| 23302 | CMSG_DATA(3) to pass file descriptors, but too many |
| 23303 | file descriptors are already in-flight. |
| 23304 | |
| 23305 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23306 | fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), |
| 23307 | write(2), CMSG_DATA(3) |
| 23308 | |
| 23309 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 23310 | The s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() functions conform to IEEE Std |
| 23311 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are |
| 23312 | extensions to that specification. |
| 23313 | |
| 23314 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23315 | The s\bse\ben\bnd\bd() function call appeared in 4.2BSD. |
| 23316 | |
| 23317 | N\bNA\bAM\bME\bE |
| 23318 | s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg - send a message to syslogd |
| 23319 | |
| 23320 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23321 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 23322 | |
| 23323 | _\bi_\bn_\bt |
| 23324 | s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
| 23325 | |
| 23326 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23327 | s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg() is used to transmit a syslog(3) formatted message direct to |
| 23328 | syslogd(8) without requiring the allocation of a socket. This is used |
| 23329 | internally by syslog_r(3), so that messages can be sent during difficult |
| 23330 | situations. |
| 23331 | |
| 23332 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23333 | Upon successful completion, the value 0 is returned; otherwise the |
| 23334 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 23335 | error. |
| 23336 | |
| 23337 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23338 | s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg() can fail if: |
| 23339 | |
| 23340 | [ENOTCONN] The message cannot be sent, likely because syslogd(8) |
| 23341 | is not running. |
| 23342 | |
| 23343 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23344 | syslog_r(3), syslogd(8) |
| 23345 | |
| 23346 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23347 | The s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg() function call appeared in OpenBSD 5.6. |
| 23348 | |
| 23349 | N\bNA\bAM\bME\bE |
| 23350 | s\bse\ben\bnd\bd, s\bse\ben\bnd\bdt\bto\bo, s\bse\ben\bnd\bdm\bms\bsg\bg - send a message from a socket |
| 23351 | |
| 23352 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23353 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 23354 | |
| 23355 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23356 | s\bse\ben\bnd\bd(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 23357 | |
| 23358 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23359 | s\bse\ben\bnd\bdt\bto\bo(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, |
| 23360 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bt_\bo, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bt_\bo_\bl_\be_\bn); |
| 23361 | |
| 23362 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 23363 | s\bse\ben\bnd\bdm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 23364 | |
| 23365 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23366 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() are used to transmit a message to another |
| 23367 | socket. s\bse\ben\bnd\bd() may be used only when the socket is in a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd state, |
| 23368 | while s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may be used at any time. |
| 23369 | |
| 23370 | The address of the target is given by _\bt_\bo with _\bt_\bo_\bl_\be_\bn specifying its size. |
| 23371 | The length of the message is given by _\bl_\be_\bn. If the message is too long to |
| 23372 | pass atomically through the underlying protocol, the error EMSGSIZE is |
| 23373 | returned, and the message is not transmitted. |
| 23374 | |
| 23375 | No indication of failure to deliver is implicit in a s\bse\ben\bnd\bd(). Locally |
| 23376 | detected errors are indicated by a return value of -1. |
| 23377 | |
| 23378 | If no messages space is available at the socket to hold the message to be |
| 23379 | transmitted, then s\bse\ben\bnd\bd() normally blocks, unless the socket has been |
| 23380 | placed in non-blocking I/O mode. The select(2) or poll(2) system calls |
| 23381 | may be used to determine when it is possible to send more data. |
| 23382 | |
| 23383 | The _\bf_\bl_\ba_\bg_\bs parameter may include one or more of the following: |
| 23384 | |
| 23385 | MSG_DONTROUTE bypass routing tables, silently ignored |
| 23386 | MSG_DONTWAIT don't block |
| 23387 | MSG_EOR terminate the record (SOCK_SEQPACKET only) |
| 23388 | MSG_NOSIGNAL don't send SIGPIPE |
| 23389 | MSG_OOB process out-of-band data |
| 23390 | |
| 23391 | The flag MSG_OOB is used to send ``out-of-band'' data on sockets that |
| 23392 | support this notion (e.g., SOCK_STREAM); the underlying protocol must |
| 23393 | also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not |
| 23394 | to send the SIGPIPE signal if an attempt to send is made on a socket that |
| 23395 | is shut down for writing or no longer connected. |
| 23396 | |
| 23397 | See recv(2) for a description of the _\bm_\bs_\bg_\bh_\bd_\br structure. |
| 23398 | |
| 23399 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23400 | The call returns the number of characters sent, or -1 if an error |
| 23401 | occurred. |
| 23402 | |
| 23403 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23404 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() fail if: |
| 23405 | |
| 23406 | [EBADF] An invalid descriptor was specified. |
| 23407 | |
| 23408 | [ENOTSOCK] The argument _\bs is not a socket. |
| 23409 | |
| 23410 | [EFAULT] An invalid user space address was specified for a |
| 23411 | parameter. |
| 23412 | |
| 23413 | [EMSGSIZE] The socket requires that message be sent atomically, |
| 23414 | and the size of the message to be sent made this |
| 23415 | impossible. |
| 23416 | |
| 23417 | [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT |
| 23418 | flag is set and the requested operation would block. |
| 23419 | |
| 23420 | [ENOBUFS] The system was unable to allocate an internal buffer. |
| 23421 | The operation may succeed when buffers become |
| 23422 | available. |
| 23423 | |
| 23424 | [ENOBUFS] The output queue for a network interface was full. |
| 23425 | This generally indicates that the interface has |
| 23426 | stopped sending, but may be caused by transient |
| 23427 | congestion. |
| 23428 | |
| 23429 | [EACCES] The SO_BROADCAST option is not set on the socket, and |
| 23430 | a broadcast address was given as the destination. |
| 23431 | |
| 23432 | [EHOSTUNREACH] The destination address specified an unreachable host. |
| 23433 | |
| 23434 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs parameter is invalid. |
| 23435 | |
| 23436 | [EHOSTDOWN] The destination address specified a host that is down. |
| 23437 | |
| 23438 | [ENETDOWN] The destination address specified a network that is |
| 23439 | down. |
| 23440 | |
| 23441 | [ECONNREFUSED] The destination host rejected the message (or a |
| 23442 | previous one). This error can only be returned by |
| 23443 | connected sockets. |
| 23444 | |
| 23445 | [ENOPROTOOPT] There was a problem sending the message. This error |
| 23446 | can only be returned by connected sockets. |
| 23447 | |
| 23448 | [EDESTADDRREQ] The socket is not connected, and no destination |
| 23449 | address was specified. |
| 23450 | |
| 23451 | [EPIPE] The socket is shut down for writing or not longer |
| 23452 | connected and the MSG_NOSIGNAL flag is set. |
| 23453 | |
| 23454 | In addition, s\bse\ben\bnd\bd() and s\bse\ben\bnd\bdt\bto\bo() may return the following error: |
| 23455 | |
| 23456 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
| 23457 | |
| 23458 | s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
| 23459 | |
| 23460 | [EAFNOSUPPORT] Addresses in the specified address family cannot be |
| 23461 | used with this socket. |
| 23462 | |
| 23463 | [EISCONN] The socket is already connected, and a destination |
| 23464 | address was specified. |
| 23465 | |
| 23466 | s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
| 23467 | |
| 23468 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
| 23469 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 23470 | |
| 23471 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
| 23472 | than IOV_MAX. |
| 23473 | |
| 23474 | [EMFILE] The message contains control information utilizing |
| 23475 | CMSG_DATA(3) to pass file descriptors, but too many |
| 23476 | file descriptors are already in-flight. |
| 23477 | |
| 23478 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23479 | fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), |
| 23480 | write(2), CMSG_DATA(3) |
| 23481 | |
| 23482 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 23483 | The s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() functions conform to IEEE Std |
| 23484 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are |
| 23485 | extensions to that specification. |
| 23486 | |
| 23487 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23488 | The s\bse\ben\bnd\bd() function call appeared in 4.2BSD. |
| 23489 | |
| 23490 | N\bNA\bAM\bME\bE |
| 23491 | s\bse\bet\btu\bui\bid\bd, s\bse\bet\bte\beu\bui\bid\bd, s\bse\bet\btg\bgi\bid\bd, s\bse\bet\bte\beg\bgi\bid\bd - set user and group ID |
| 23492 | |
| 23493 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23494 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 23495 | |
| 23496 | _\bi_\bn_\bt |
| 23497 | s\bse\bet\btu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\bu_\bi_\bd); |
| 23498 | |
| 23499 | _\bi_\bn_\bt |
| 23500 | s\bse\bet\bte\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
| 23501 | |
| 23502 | _\bi_\bn_\bt |
| 23503 | s\bse\bet\btg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
| 23504 | |
| 23505 | _\bi_\bn_\bt |
| 23506 | s\bse\bet\bte\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
| 23507 | |
| 23508 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23509 | The s\bse\bet\btu\bui\bid\bd() function sets the real and effective user IDs and the saved |
| 23510 | set-user-ID of the current process to the specified value. The s\bse\bet\btu\bui\bid\bd() |
| 23511 | function is permitted if the effective user ID is that of the superuser, |
| 23512 | or if the specified user ID is the same as the effective user ID. If |
| 23513 | not, but the specified user ID is the same as the real user ID, s\bse\bet\btu\bui\bid\bd() |
| 23514 | will set the effective user ID to the real user ID. |
| 23515 | |
| 23516 | The s\bse\bet\btg\bgi\bid\bd() function sets the real and effective group IDs and the saved |
| 23517 | set-group-ID of the current process to the specified value. The s\bse\bet\btg\bgi\bid\bd() |
| 23518 | function is permitted if the effective user ID is that of the superuser, |
| 23519 | or if the specified group ID is the same as the effective group ID. If |
| 23520 | not, but the specified group ID is the same as the real group ID, |
| 23521 | s\bse\bet\btg\bgi\bid\bd() will set the effective group ID to the real group ID. |
| 23522 | Supplementary group IDs remain unchanged. |
| 23523 | |
| 23524 | The s\bse\bet\bte\beu\bui\bid\bd() function (s\bse\bet\bte\beg\bgi\bid\bd()) sets the effective user ID (group ID) |
| 23525 | of the current process. The effective user ID may be set to the value of |
| 23526 | the real user ID or the saved set-user-ID (see intro(2) and execve(2)); |
| 23527 | in this way, the effective user ID of a set-user-ID executable may be |
| 23528 | toggled by switching to the real user ID, then re-enabled by reverting to |
| 23529 | the set-user-ID value. Similarly, the effective group ID may be set to |
| 23530 | the value of the real group ID or the saved set-group-ID. |
| 23531 | |
| 23532 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23533 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions return the |
| 23534 | value 0 if successful; otherwise the value -1 is returned and the global |
| 23535 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 23536 | |
| 23537 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23538 | s\bse\bet\btu\bui\bid\bd() and s\bse\bet\bte\beu\bui\bid\bd() will succeed unless: |
| 23539 | |
| 23540 | [EPERM] The user is not the superuser and the requested _\bu_\bi_\bd or |
| 23541 | _\be_\bu_\bi_\bd is not the process's real, effective, or saved |
| 23542 | UID. |
| 23543 | |
| 23544 | s\bse\bet\btg\bgi\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() will succeed unless: |
| 23545 | |
| 23546 | [EPERM] The user is not the superuser and the requested _\bg_\bi_\bd or |
| 23547 | _\be_\bg_\bi_\bd is not the process's real, effective, or saved |
| 23548 | GID. |
| 23549 | |
| 23550 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23551 | getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), |
| 23552 | setresgid(2), setresuid(2), setreuid(2) |
| 23553 | |
| 23554 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 23555 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions conform to |
| 23556 | IEEE Std 1003.1-2008 (``POSIX.1''). |
| 23557 | |
| 23558 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23559 | The s\bse\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX; s\bse\bet\btg\bgi\bid\bd() |
| 23560 | in Version 4 AT&T UNIX; and s\bse\bet\bte\beu\bui\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() in 4.2BSD. |
| 23561 | |
| 23562 | N\bNA\bAM\bME\bE |
| 23563 | s\bse\bet\btu\bui\bid\bd, s\bse\bet\bte\beu\bui\bid\bd, s\bse\bet\btg\bgi\bid\bd, s\bse\bet\bte\beg\bgi\bid\bd - set user and group ID |
| 23564 | |
| 23565 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23566 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 23567 | |
| 23568 | _\bi_\bn_\bt |
| 23569 | s\bse\bet\btu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\bu_\bi_\bd); |
| 23570 | |
| 23571 | _\bi_\bn_\bt |
| 23572 | s\bse\bet\bte\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
| 23573 | |
| 23574 | _\bi_\bn_\bt |
| 23575 | s\bse\bet\btg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
| 23576 | |
| 23577 | _\bi_\bn_\bt |
| 23578 | s\bse\bet\bte\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
| 23579 | |
| 23580 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23581 | The s\bse\bet\btu\bui\bid\bd() function sets the real and effective user IDs and the saved |
| 23582 | set-user-ID of the current process to the specified value. The s\bse\bet\btu\bui\bid\bd() |
| 23583 | function is permitted if the effective user ID is that of the superuser, |
| 23584 | or if the specified user ID is the same as the effective user ID. If |
| 23585 | not, but the specified user ID is the same as the real user ID, s\bse\bet\btu\bui\bid\bd() |
| 23586 | will set the effective user ID to the real user ID. |
| 23587 | |
| 23588 | The s\bse\bet\btg\bgi\bid\bd() function sets the real and effective group IDs and the saved |
| 23589 | set-group-ID of the current process to the specified value. The s\bse\bet\btg\bgi\bid\bd() |
| 23590 | function is permitted if the effective user ID is that of the superuser, |
| 23591 | or if the specified group ID is the same as the effective group ID. If |
| 23592 | not, but the specified group ID is the same as the real group ID, |
| 23593 | s\bse\bet\btg\bgi\bid\bd() will set the effective group ID to the real group ID. |
| 23594 | Supplementary group IDs remain unchanged. |
| 23595 | |
| 23596 | The s\bse\bet\bte\beu\bui\bid\bd() function (s\bse\bet\bte\beg\bgi\bid\bd()) sets the effective user ID (group ID) |
| 23597 | of the current process. The effective user ID may be set to the value of |
| 23598 | the real user ID or the saved set-user-ID (see intro(2) and execve(2)); |
| 23599 | in this way, the effective user ID of a set-user-ID executable may be |
| 23600 | toggled by switching to the real user ID, then re-enabled by reverting to |
| 23601 | the set-user-ID value. Similarly, the effective group ID may be set to |
| 23602 | the value of the real group ID or the saved set-group-ID. |
| 23603 | |
| 23604 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23605 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions return the |
| 23606 | value 0 if successful; otherwise the value -1 is returned and the global |
| 23607 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 23608 | |
| 23609 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23610 | s\bse\bet\btu\bui\bid\bd() and s\bse\bet\bte\beu\bui\bid\bd() will succeed unless: |
| 23611 | |
| 23612 | [EPERM] The user is not the superuser and the requested _\bu_\bi_\bd or |
| 23613 | _\be_\bu_\bi_\bd is not the process's real, effective, or saved |
| 23614 | UID. |
| 23615 | |
| 23616 | s\bse\bet\btg\bgi\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() will succeed unless: |
| 23617 | |
| 23618 | [EPERM] The user is not the superuser and the requested _\bg_\bi_\bd or |
| 23619 | _\be_\bg_\bi_\bd is not the process's real, effective, or saved |
| 23620 | GID. |
| 23621 | |
| 23622 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23623 | getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), |
| 23624 | setresgid(2), setresuid(2), setreuid(2) |
| 23625 | |
| 23626 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 23627 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions conform to |
| 23628 | IEEE Std 1003.1-2008 (``POSIX.1''). |
| 23629 | |
| 23630 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23631 | The s\bse\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX; s\bse\bet\btg\bgi\bid\bd() |
| 23632 | in Version 4 AT&T UNIX; and s\bse\bet\bte\beu\bui\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() in 4.2BSD. |
| 23633 | |
| 23634 | N\bNA\bAM\bME\bE |
| 23635 | s\bse\bet\btu\bui\bid\bd, s\bse\bet\bte\beu\bui\bid\bd, s\bse\bet\btg\bgi\bid\bd, s\bse\bet\bte\beg\bgi\bid\bd - set user and group ID |
| 23636 | |
| 23637 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23638 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 23639 | |
| 23640 | _\bi_\bn_\bt |
| 23641 | s\bse\bet\btu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\bu_\bi_\bd); |
| 23642 | |
| 23643 | _\bi_\bn_\bt |
| 23644 | s\bse\bet\bte\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
| 23645 | |
| 23646 | _\bi_\bn_\bt |
| 23647 | s\bse\bet\btg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
| 23648 | |
| 23649 | _\bi_\bn_\bt |
| 23650 | s\bse\bet\bte\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
| 23651 | |
| 23652 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23653 | The s\bse\bet\btu\bui\bid\bd() function sets the real and effective user IDs and the saved |
| 23654 | set-user-ID of the current process to the specified value. The s\bse\bet\btu\bui\bid\bd() |
| 23655 | function is permitted if the effective user ID is that of the superuser, |
| 23656 | or if the specified user ID is the same as the effective user ID. If |
| 23657 | not, but the specified user ID is the same as the real user ID, s\bse\bet\btu\bui\bid\bd() |
| 23658 | will set the effective user ID to the real user ID. |
| 23659 | |
| 23660 | The s\bse\bet\btg\bgi\bid\bd() function sets the real and effective group IDs and the saved |
| 23661 | set-group-ID of the current process to the specified value. The s\bse\bet\btg\bgi\bid\bd() |
| 23662 | function is permitted if the effective user ID is that of the superuser, |
| 23663 | or if the specified group ID is the same as the effective group ID. If |
| 23664 | not, but the specified group ID is the same as the real group ID, |
| 23665 | s\bse\bet\btg\bgi\bid\bd() will set the effective group ID to the real group ID. |
| 23666 | Supplementary group IDs remain unchanged. |
| 23667 | |
| 23668 | The s\bse\bet\bte\beu\bui\bid\bd() function (s\bse\bet\bte\beg\bgi\bid\bd()) sets the effective user ID (group ID) |
| 23669 | of the current process. The effective user ID may be set to the value of |
| 23670 | the real user ID or the saved set-user-ID (see intro(2) and execve(2)); |
| 23671 | in this way, the effective user ID of a set-user-ID executable may be |
| 23672 | toggled by switching to the real user ID, then re-enabled by reverting to |
| 23673 | the set-user-ID value. Similarly, the effective group ID may be set to |
| 23674 | the value of the real group ID or the saved set-group-ID. |
| 23675 | |
| 23676 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23677 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions return the |
| 23678 | value 0 if successful; otherwise the value -1 is returned and the global |
| 23679 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 23680 | |
| 23681 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23682 | s\bse\bet\btu\bui\bid\bd() and s\bse\bet\bte\beu\bui\bid\bd() will succeed unless: |
| 23683 | |
| 23684 | [EPERM] The user is not the superuser and the requested _\bu_\bi_\bd or |
| 23685 | _\be_\bu_\bi_\bd is not the process's real, effective, or saved |
| 23686 | UID. |
| 23687 | |
| 23688 | s\bse\bet\btg\bgi\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() will succeed unless: |
| 23689 | |
| 23690 | [EPERM] The user is not the superuser and the requested _\bg_\bi_\bd or |
| 23691 | _\be_\bg_\bi_\bd is not the process's real, effective, or saved |
| 23692 | GID. |
| 23693 | |
| 23694 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23695 | getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), |
| 23696 | setresgid(2), setresuid(2), setreuid(2) |
| 23697 | |
| 23698 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 23699 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions conform to |
| 23700 | IEEE Std 1003.1-2008 (``POSIX.1''). |
| 23701 | |
| 23702 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23703 | The s\bse\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX; s\bse\bet\btg\bgi\bid\bd() |
| 23704 | in Version 4 AT&T UNIX; and s\bse\bet\bte\beu\bui\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() in 4.2BSD. |
| 23705 | |
| 23706 | N\bNA\bAM\bME\bE |
| 23707 | s\bse\bet\btg\bgr\bro\bou\bup\bps\bs - set group access list |
| 23708 | |
| 23709 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23710 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 23711 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 23712 | |
| 23713 | _\bi_\bn_\bt |
| 23714 | s\bse\bet\btg\bgr\bro\bou\bup\bps\bs(_\bi_\bn_\bt _\bn_\bg_\br_\bo_\bu_\bp_\bs, _\bc_\bo_\bn_\bs_\bt _\bg_\bi_\bd_\b__\bt _\b*_\bg_\bi_\bd_\bs_\be_\bt); |
| 23715 | |
| 23716 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23717 | s\bse\bet\btg\bgr\bro\bou\bup\bps\bs() sets the group access list of the current user process |
| 23718 | according to the array _\bg_\bi_\bd_\bs_\be_\bt. The parameter _\bn_\bg_\br_\bo_\bu_\bp_\bs indicates the |
| 23719 | number of entries in the array and must be no more than {NGROUPS_MAX}. |
| 23720 | |
| 23721 | Only the superuser may set new groups. |
| 23722 | |
| 23723 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23724 | Upon successful completion, the value 0 is returned; otherwise the |
| 23725 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 23726 | error. |
| 23727 | |
| 23728 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23729 | The s\bse\bet\btg\bgr\bro\bou\bup\bps\bs() call will fail if: |
| 23730 | |
| 23731 | [EINVAL] The value of _\bn_\bg_\br_\bo_\bu_\bp_\bs is greater than {NGROUPS_MAX}. |
| 23732 | |
| 23733 | [EPERM] The caller is not the superuser. |
| 23734 | |
| 23735 | [EFAULT] The address specified for _\bg_\bi_\bd_\bs_\be_\bt is outside the |
| 23736 | process address space. |
| 23737 | |
| 23738 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23739 | getgroups(2), setgid(2), setregid(2), initgroups(3) |
| 23740 | |
| 23741 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23742 | The s\bse\bet\btg\bgr\bro\bou\bup\bps\bs() system call first appeared in 4.1cBSD. |
| 23743 | |
| 23744 | N\bNA\bAM\bME\bE |
| 23745 | g\bge\bet\bti\bit\bti\bim\bme\ber\br, s\bse\bet\bti\bit\bti\bim\bme\ber\br - get/set value of interval timer |
| 23746 | |
| 23747 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23748 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 23749 | |
| 23750 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_R\bRE\bEA\bAL\bL 0\b0 |
| 23751 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_V\bVI\bIR\bRT\bTU\bUA\bAL\bL 1\b1 |
| 23752 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_P\bPR\bRO\bOF\bF 2\b2 |
| 23753 | |
| 23754 | _\bi_\bn_\bt |
| 23755 | g\bge\bet\bti\bit\bti\bim\bme\ber\br(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bv_\ba_\bl_\bu_\be); |
| 23756 | |
| 23757 | _\bi_\bn_\bt |
| 23758 | s\bse\bet\bti\bit\bti\bim\bme\ber\br(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bv_\ba_\bl_\bu_\be, |
| 23759 | _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bo_\bv_\ba_\bl_\bu_\be); |
| 23760 | |
| 23761 | _\bv_\bo_\bi_\bd |
| 23762 | t\bti\bim\bme\ber\brc\bcl\ble\bea\bar\br(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*); |
| 23763 | |
| 23764 | _\bi_\bn_\bt |
| 23765 | t\bti\bim\bme\ber\bri\bis\bss\bse\bet\bt(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*); |
| 23766 | |
| 23767 | _\bi_\bn_\bt |
| 23768 | t\bti\bim\bme\ber\brc\bcm\bmp\bp(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bC_\bM_\bP); |
| 23769 | |
| 23770 | _\bv_\bo_\bi_\bd |
| 23771 | t\bti\bim\bme\ber\brs\bsu\bub\bb(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\br_\be_\bs); |
| 23772 | |
| 23773 | _\bv_\bo_\bi_\bd |
| 23774 | t\bti\bim\bme\ber\bra\bad\bdd\bd(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\br_\be_\bs); |
| 23775 | |
| 23776 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23777 | The system provides each process with three interval timers, defined in |
| 23778 | <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. The g\bge\bet\bti\bit\bti\bim\bme\ber\br() call returns the current value for the |
| 23779 | timer specified in _\bw_\bh_\bi_\bc_\bh in the structure at _\bv_\ba_\bl_\bu_\be. The s\bse\bet\bti\bit\bti\bim\bme\ber\br() call |
| 23780 | sets a timer to the specified _\bv_\ba_\bl_\bu_\be (returning the previous value of the |
| 23781 | timer if _\bo_\bv_\ba_\bl_\bu_\be is non-null). |
| 23782 | |
| 23783 | A timer value is defined by the _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl structure: |
| 23784 | |
| 23785 | struct itimerval { |
| 23786 | struct timeval it_interval; /* timer interval */ |
| 23787 | struct timeval it_value; /* current value */ |
| 23788 | }; |
| 23789 | |
| 23790 | If _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be is non-zero, it indicates the time to the next timer |
| 23791 | expiration. If _\bi_\bt_\b__\bi_\bn_\bt_\be_\br_\bv_\ba_\bl is non-zero, it specifies a value to be used |
| 23792 | in reloading _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be when the timer expires. Setting _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be to 0 |
| 23793 | disables a timer. Setting _\bi_\bt_\b__\bi_\bn_\bt_\be_\br_\bv_\ba_\bl to 0 causes a timer to be disabled |
| 23794 | after its next expiration (assuming _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be is non-zero). |
| 23795 | |
| 23796 | Time values smaller than the resolution of the system clock are rounded |
| 23797 | up to this resolution (typically 10 milliseconds). |
| 23798 | |
| 23799 | The ITIMER_REAL timer decrements in real time. A SIGALRM signal is |
| 23800 | delivered when this timer expires. |
| 23801 | |
| 23802 | The ITIMER_VIRTUAL timer decrements in process virtual time. It runs |
| 23803 | only when the process is executing. A SIGVTALRM signal is delivered when |
| 23804 | it expires. |
| 23805 | |
| 23806 | The ITIMER_PROF timer decrements both in process virtual time and when |
| 23807 | the system is running on behalf of the process. It is designed to be |
| 23808 | used by interpreters in statistically profiling the execution of |
| 23809 | interpreted programs. Each time the ITIMER_PROF timer expires, the |
| 23810 | SIGPROF signal is delivered. Because this signal may interrupt in- |
| 23811 | progress system calls, programs using this timer must be prepared to |
| 23812 | restart interrupted system calls. |
| 23813 | |
| 23814 | The remaining five functions are in fact macros for manipulating time |
| 23815 | values, defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. |
| 23816 | |
| 23817 | t\bti\bim\bme\ber\brc\bcl\ble\bea\bar\br(_\ba) sets the time value in _\ba to zero. |
| 23818 | |
| 23819 | t\bti\bim\bme\ber\bri\bis\bss\bse\bet\bt(_\ba) tests if the time value in _\ba is non-zero. |
| 23820 | |
| 23821 | t\bti\bim\bme\ber\brc\bcm\bmp\bp(_\ba, _\bb, _\bC_\bM_\bP) compares two time values in the form _\ba CMP _\bb, where |
| 23822 | _\bC_\bM_\bP is <, <=, ==, !=, >=, or > . |
| 23823 | |
| 23824 | t\bti\bim\bme\ber\brs\bsu\bub\bb(_\ba, _\bb, _\br_\be_\bs) subtracts _\ba - _\bb and stores the result in _\br_\be_\bs. |
| 23825 | |
| 23826 | t\bti\bim\bme\ber\bra\bad\bdd\bd(_\ba, _\bb, _\br_\be_\bs) adds two timers and stores the result in _\br_\be_\bs. |
| 23827 | |
| 23828 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23829 | Upon successful completion, the value 0 is returned; otherwise the |
| 23830 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 23831 | error. |
| 23832 | |
| 23833 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23834 | g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() will fail if: |
| 23835 | |
| 23836 | [EFAULT] The _\bv_\ba_\bl_\bu_\be parameter specified a bad address. |
| 23837 | |
| 23838 | [EINVAL] An unrecognized value for _\bw_\bh_\bi_\bc_\bh was specified. |
| 23839 | |
| 23840 | In addition, s\bse\bet\bti\bit\bti\bim\bme\ber\br() may return the following error: |
| 23841 | |
| 23842 | [EINVAL] _\bv_\ba_\bl_\bu_\be or _\bo_\bv_\ba_\bl_\bu_\be specified a time that was too large to |
| 23843 | be handled. |
| 23844 | |
| 23845 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23846 | clock_gettime(2), gettimeofday(2), poll(2), select(2), sigaction(2) |
| 23847 | |
| 23848 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 23849 | The g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() functions conform to IEEE Std 1003.1-2008 |
| 23850 | (``POSIX.1''). |
| 23851 | |
| 23852 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23853 | The g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() system calls first appeared in 4.1cBSD. |
| 23854 | |
| 23855 | N\bNA\bAM\bME\bE |
| 23856 | g\bge\bet\btl\blo\bog\bgi\bin\bn, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br, s\bse\bet\btl\blo\bog\bgi\bin\bn - get/set login name |
| 23857 | |
| 23858 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23859 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 23860 | |
| 23861 | _\bc_\bh_\ba_\br _\b* |
| 23862 | g\bge\bet\btl\blo\bog\bgi\bin\bn(_\bv_\bo_\bi_\bd); |
| 23863 | |
| 23864 | _\bi_\bn_\bt |
| 23865 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br(_\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bi_\bz_\be_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
| 23866 | |
| 23867 | _\bi_\bn_\bt |
| 23868 | s\bse\bet\btl\blo\bog\bgi\bin\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); |
| 23869 | |
| 23870 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23871 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() routine returns the login name of the user associated with |
| 23872 | the current session, as previously set by s\bse\bet\btl\blo\bog\bgi\bin\bn(). The name is |
| 23873 | normally associated with a login shell at the time a session is created, |
| 23874 | and is inherited by all processes descended from the login shell. (This |
| 23875 | is true even if some of those processes assume another user ID, for |
| 23876 | example when su(1) is used.) |
| 23877 | |
| 23878 | The g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() routine is a reentrant version of g\bge\bet\btl\blo\bog\bgi\bin\bn(). It is |
| 23879 | functionally identical to g\bge\bet\btl\blo\bog\bgi\bin\bn() except that the caller must provide |
| 23880 | a buffer, _\bn_\ba_\bm_\be, in which to store the user's login name and a |
| 23881 | corresponding length parameter, _\bn_\ba_\bm_\be_\bl_\be_\bn, that specifies the size of the |
| 23882 | buffer. The buffer should be large enough to store the login name and a |
| 23883 | trailing NUL (typically LOGIN_NAME_MAX bytes). |
| 23884 | |
| 23885 | s\bse\bet\btl\blo\bog\bgi\bin\bn() sets the login name of the user associated with the current |
| 23886 | session to _\bn_\ba_\bm_\be. This call is restricted to the superuser, and is |
| 23887 | normally used only when a new session is being created on behalf of the |
| 23888 | named user (for example, at login time, or when a remote shell is |
| 23889 | invoked). |
| 23890 | |
| 23891 | _\bN_\bO_\bT_\bE: There is only one login name per session. |
| 23892 | |
| 23893 | It is _\bC_\bR_\bI_\bT_\bI_\bC_\bA_\bL_\bL_\bY important to ensure that s\bse\bet\btl\blo\bog\bgi\bin\bn() is only ever called |
| 23894 | after the process has taken adequate steps to ensure that it is detached |
| 23895 | from its parent's session. The _\bO_\bN_\bL_\bY way to do this is via the s\bse\bet\bts\bsi\bid\bd() |
| 23896 | function. The d\bda\bae\bem\bmo\bon\bn() function calls s\bse\bet\bts\bsi\bid\bd() which is an ideal way of |
| 23897 | detaching from a controlling terminal and forking into the background. |
| 23898 | |
| 23899 | In particular, neither i\bio\boc\bct\btl\bl(_\bt_\bt_\by_\bf_\bd, _\bT_\bI_\bO_\bC_\bN_\bO_\bT_\bT_\bY, _\b._\b._\b.) nor s\bse\bet\btp\bpg\bgr\brp\bp(_\b._\b._\b.) is |
| 23900 | sufficient to create a new session. |
| 23901 | |
| 23902 | Once a parent process has called s\bse\bet\bts\bsi\bid\bd(), it is acceptable for some |
| 23903 | child of that process to then call s\bse\bet\btl\blo\bog\bgi\bin\bn(), even though it is not the |
| 23904 | session leader. Beware, however, that _\bA_\bL_\bL processes in the session will |
| 23905 | change their login name at the same time, even the parent. |
| 23906 | |
| 23907 | This is different from traditional UNIX privilege inheritance and as such |
| 23908 | can be counter-intuitive. |
| 23909 | |
| 23910 | Since the s\bse\bet\btl\blo\bog\bgi\bin\bn() routine is restricted to the super-user, it is |
| 23911 | assumed that (like all other privileged programs) the programmer has |
| 23912 | taken adequate precautions to prevent security violations. |
| 23913 | |
| 23914 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23915 | If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn() succeeds, it returns a pointer to a NUL- |
| 23916 | terminated string in a static buffer. If the name has not been set, it |
| 23917 | returns NULL. If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() succeeds, a value of 0 is |
| 23918 | returned, else the error number is returned. If a call to s\bse\bet\btl\blo\bog\bgi\bin\bn() |
| 23919 | succeeds, a value of 0 is returned. If s\bse\bet\btl\blo\bog\bgi\bin\bn() fails, a value of -1 |
| 23920 | is returned and an error code is placed in the global location _\be_\br_\br_\bn_\bo. |
| 23921 | |
| 23922 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23923 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() and s\bse\bet\btl\blo\bog\bgi\bin\bn() will succeed unless: |
| 23924 | |
| 23925 | [EFAULT] The _\bn_\ba_\bm_\be parameter points to an invalid address. |
| 23926 | |
| 23927 | In addition, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() may return the following error: |
| 23928 | |
| 23929 | [ERANGE] The value of _\bn_\ba_\bm_\be_\bl_\be_\bn is not large enough to store the |
| 23930 | user's login name and a trailing NUL. |
| 23931 | |
| 23932 | s\bse\bet\btl\blo\bog\bgi\bin\bn() may return the following errors: |
| 23933 | |
| 23934 | [EINVAL] The _\bn_\ba_\bm_\be parameter pointed to a string that was too |
| 23935 | long. Login names are limited to LOGIN_NAME_MAX-1 |
| 23936 | characters, currently 31. |
| 23937 | |
| 23938 | [EPERM] The caller tried to set the login name and was not the |
| 23939 | superuser. |
| 23940 | |
| 23941 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 23942 | setsid(2) |
| 23943 | |
| 23944 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 23945 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() and g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() functions conform to IEEE Std 1003.1-2008 |
| 23946 | (``POSIX.1''). |
| 23947 | |
| 23948 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 23949 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() function first appeared in 4.2BSD. |
| 23950 | |
| 23951 | B\bBU\bUG\bGS\bS |
| 23952 | In earlier versions of the system, g\bge\bet\btl\blo\bog\bgi\bin\bn() failed unless the process |
| 23953 | was associated with a login terminal. The current implementation (using |
| 23954 | s\bse\bet\btl\blo\bog\bgi\bin\bn()) allows getlogin to succeed even when the process has no |
| 23955 | controlling terminal. In earlier versions of the system, the value |
| 23956 | returned by g\bge\bet\btl\blo\bog\bgi\bin\bn() could not be trusted without checking the user ID. |
| 23957 | Portable programs should probably still make this check. |
| 23958 | |
| 23959 | N\bNA\bAM\bME\bE |
| 23960 | s\bse\bet\btp\bpg\bgi\bid\bd, s\bse\bet\btp\bpg\bgr\brp\bp - set process group |
| 23961 | |
| 23962 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 23963 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 23964 | |
| 23965 | _\bi_\bn_\bt |
| 23966 | s\bse\bet\btp\bpg\bgi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bp_\bi_\bd_\b__\bt _\bp_\bg_\br_\bp); |
| 23967 | |
| 23968 | _\bi_\bn_\bt |
| 23969 | s\bse\bet\btp\bpg\bgr\brp\bp(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bp_\bi_\bd_\b__\bt _\bp_\bg_\br_\bp); |
| 23970 | |
| 23971 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 23972 | s\bse\bet\btp\bpg\bgi\bid\bd() sets the process group of the specified process _\bp_\bi_\bd to the |
| 23973 | specified _\bp_\bg_\br_\bp. If _\bp_\bi_\bd is zero, then the call applies to the current |
| 23974 | process. If _\bp_\bg_\br_\bp is zero, the process ID of the specified process is |
| 23975 | used. |
| 23976 | |
| 23977 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 23978 | Upon successful completion, the value 0 is returned; otherwise the |
| 23979 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 23980 | error. |
| 23981 | |
| 23982 | E\bER\bRR\bRO\bOR\bRS\bS |
| 23983 | s\bse\bet\btp\bpg\bgi\bid\bd() will fail and the process group will not be altered if: |
| 23984 | |
| 23985 | [EACCES] The value of the _\bp_\bi_\bd argument matches the process ID |
| 23986 | of a child process of the calling process, and the |
| 23987 | child process has successfully executed one of the |
| 23988 | exec functions. |
| 23989 | |
| 23990 | [EINVAL] The value of the _\bp_\bg_\br_\bp argument is less than zero. |
| 23991 | |
| 23992 | [EPERM] The requested process is a descendant of the calling |
| 23993 | process, and is either a session leader or not in the |
| 23994 | same session as the calling process. |
| 23995 | |
| 23996 | [EPERM] The value of the _\bp_\bg_\br_\bp argument is neither the PID of |
| 23997 | the process indicated by the _\bp_\bi_\bd argument nor the |
| 23998 | process group ID of an existing process group in the |
| 23999 | same session as the calling process. |
| 24000 | |
| 24001 | [ESRCH] The value of the _\bp_\bi_\bd argument does not match the |
| 24002 | process ID of the calling process or of a descendant |
| 24003 | of the calling process. |
| 24004 | |
| 24005 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24006 | getpgrp(2), setsid(2) |
| 24007 | |
| 24008 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24009 | s\bse\bet\btp\bpg\bgr\brp\bp() is identical to s\bse\bet\btp\bpg\bgi\bid\bd(), and is retained for calling |
| 24010 | convention compatibility with historical versions of BSD. |
| 24011 | |
| 24012 | The s\bse\bet\btp\bpg\bgi\bid\bd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 24013 | |
| 24014 | N\bNA\bAM\bME\bE |
| 24015 | s\bse\bet\btp\bpg\bgi\bid\bd, s\bse\bet\btp\bpg\bgr\brp\bp - set process group |
| 24016 | |
| 24017 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24018 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 24019 | |
| 24020 | _\bi_\bn_\bt |
| 24021 | s\bse\bet\btp\bpg\bgi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bp_\bi_\bd_\b__\bt _\bp_\bg_\br_\bp); |
| 24022 | |
| 24023 | _\bi_\bn_\bt |
| 24024 | s\bse\bet\btp\bpg\bgr\brp\bp(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bp_\bi_\bd_\b__\bt _\bp_\bg_\br_\bp); |
| 24025 | |
| 24026 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24027 | s\bse\bet\btp\bpg\bgi\bid\bd() sets the process group of the specified process _\bp_\bi_\bd to the |
| 24028 | specified _\bp_\bg_\br_\bp. If _\bp_\bi_\bd is zero, then the call applies to the current |
| 24029 | process. If _\bp_\bg_\br_\bp is zero, the process ID of the specified process is |
| 24030 | used. |
| 24031 | |
| 24032 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24033 | Upon successful completion, the value 0 is returned; otherwise the |
| 24034 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 24035 | error. |
| 24036 | |
| 24037 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24038 | s\bse\bet\btp\bpg\bgi\bid\bd() will fail and the process group will not be altered if: |
| 24039 | |
| 24040 | [EACCES] The value of the _\bp_\bi_\bd argument matches the process ID |
| 24041 | of a child process of the calling process, and the |
| 24042 | child process has successfully executed one of the |
| 24043 | exec functions. |
| 24044 | |
| 24045 | [EINVAL] The value of the _\bp_\bg_\br_\bp argument is less than zero. |
| 24046 | |
| 24047 | [EPERM] The requested process is a descendant of the calling |
| 24048 | process, and is either a session leader or not in the |
| 24049 | same session as the calling process. |
| 24050 | |
| 24051 | [EPERM] The value of the _\bp_\bg_\br_\bp argument is neither the PID of |
| 24052 | the process indicated by the _\bp_\bi_\bd argument nor the |
| 24053 | process group ID of an existing process group in the |
| 24054 | same session as the calling process. |
| 24055 | |
| 24056 | [ESRCH] The value of the _\bp_\bi_\bd argument does not match the |
| 24057 | process ID of the calling process or of a descendant |
| 24058 | of the calling process. |
| 24059 | |
| 24060 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24061 | getpgrp(2), setsid(2) |
| 24062 | |
| 24063 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24064 | s\bse\bet\btp\bpg\bgr\brp\bp() is identical to s\bse\bet\btp\bpg\bgi\bid\bd(), and is retained for calling |
| 24065 | convention compatibility with historical versions of BSD. |
| 24066 | |
| 24067 | The s\bse\bet\btp\bpg\bgi\bid\bd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 24068 | |
| 24069 | N\bNA\bAM\bME\bE |
| 24070 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by, s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by - get/set process scheduling priority |
| 24071 | |
| 24072 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24073 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 24074 | |
| 24075 | _\bi_\bn_\bt |
| 24076 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bi_\bd_\b__\bt _\bw_\bh_\bo); |
| 24077 | |
| 24078 | _\bi_\bn_\bt |
| 24079 | s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bi_\bd_\b__\bt _\bw_\bh_\bo, _\bi_\bn_\bt _\bp_\br_\bi_\bo); |
| 24080 | |
| 24081 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24082 | The scheduling priority of the process, process group, or user, as |
| 24083 | indicated by _\bw_\bh_\bi_\bc_\bh and _\bw_\bh_\bo is obtained with the g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call and |
| 24084 | set with the s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call. _\bw_\bh_\bi_\bc_\bh is one of PRIO_PROCESS, |
| 24085 | PRIO_PGRP, or PRIO_USER, and _\bw_\bh_\bo is interpreted relative to _\bw_\bh_\bi_\bc_\bh (a |
| 24086 | process identifier for PRIO_PROCESS, process group identifier for |
| 24087 | PRIO_PGRP, and a user ID for PRIO_USER). A zero value of _\bw_\bh_\bo denotes the |
| 24088 | current process, process group, or user. _\bp_\br_\bi_\bo is a value in the range |
| 24089 | -20 to 20. The default priority is 0; lower priorities cause more |
| 24090 | favorable scheduling. |
| 24091 | |
| 24092 | The g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call returns the highest priority (lowest numerical |
| 24093 | value) enjoyed by any of the specified processes. The s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call |
| 24094 | sets the priorities of all of the specified processes to the specified |
| 24095 | value. Priority values outside the range -20 to 20 are truncated to the |
| 24096 | appropriate limit. Only the superuser may lower priorities. |
| 24097 | |
| 24098 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24099 | Since g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() can legitimately return the value -1, it is necessary |
| 24100 | to clear the external variable _\be_\br_\br_\bn_\bo prior to the call, then check it |
| 24101 | afterward to determine if a -1 is an error or a legitimate value. The |
| 24102 | s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call returns 0 if there is no error, or -1 if there is. |
| 24103 | |
| 24104 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24105 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() will fail if: |
| 24106 | |
| 24107 | [ESRCH] No process was located using the _\bw_\bh_\bi_\bc_\bh and _\bw_\bh_\bo values |
| 24108 | specified. |
| 24109 | |
| 24110 | [EINVAL] _\bw_\bh_\bi_\bc_\bh was not one of PRIO_PROCESS, PRIO_PGRP, or |
| 24111 | PRIO_USER. |
| 24112 | |
| 24113 | In addition, s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() will fail if: |
| 24114 | |
| 24115 | [EPERM] A process was located, but neither its effective nor |
| 24116 | real user ID matched the effective user ID of the |
| 24117 | caller. |
| 24118 | |
| 24119 | [EACCES] A non-superuser attempted to lower a process priority. |
| 24120 | |
| 24121 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24122 | nice(1), fork(2), renice(8) |
| 24123 | |
| 24124 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24125 | The g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() functions conform to IEEE Std |
| 24126 | 1003.1-2008 (``POSIX.1''). |
| 24127 | |
| 24128 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24129 | The predecessor of these functions, the former n\bni\bic\bce\be() system call, |
| 24130 | appeared in Version 3 AT&T UNIX and was removed in 4.3BSD-Reno. The |
| 24131 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() system calls appeared in 4.1cBSD. |
| 24132 | |
| 24133 | N\bNA\bAM\bME\bE |
| 24134 | s\bse\bet\btr\bre\beg\bgi\bid\bd - set real and effective group IDs |
| 24135 | |
| 24136 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24137 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 24138 | |
| 24139 | _\bi_\bn_\bt |
| 24140 | s\bse\bet\btr\bre\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
| 24141 | |
| 24142 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24143 | The real and effective group IDs of the current process are set according |
| 24144 | to the arguments. The saved group ID will be set to the new value of the |
| 24145 | real group ID if a real group ID is specified and either the new real |
| 24146 | group ID value is different from the current value or the new value of |
| 24147 | the effective group ID differs from the current saved group ID. |
| 24148 | |
| 24149 | Unprivileged users may change either group ID to the current value of the |
| 24150 | real, effective, or saved group ID. Only the superuser may make other |
| 24151 | changes. |
| 24152 | |
| 24153 | Supplying a value of -1 for either the real or effective group ID forces |
| 24154 | the system to substitute the current ID in place of the -1 parameter. |
| 24155 | |
| 24156 | The s\bse\bet\btr\bre\beg\bgi\bid\bd() function was intended to allow swapping the real and |
| 24157 | effective group IDs in set-group-ID programs to temporarily relinquish |
| 24158 | the set-group-ID value. This purpose is now better served by the use of |
| 24159 | the setegid(2) function. |
| 24160 | |
| 24161 | When setting the real and effective group IDs to the same value, the |
| 24162 | setgid(2) function is preferred. |
| 24163 | |
| 24164 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24165 | Upon successful completion, the value 0 is returned; otherwise the |
| 24166 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 24167 | error. |
| 24168 | |
| 24169 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24170 | [EPERM] The current process is not the superuser and a change |
| 24171 | other than changing the effective group ID to the real |
| 24172 | group ID was specified. |
| 24173 | |
| 24174 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24175 | getgid(2), setegid(2), setgid(2), setresgid(2), setreuid(2) |
| 24176 | |
| 24177 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24178 | The s\bse\bet\btr\bre\beg\bgi\bid\bd() function conforms to the IEEE Std 1003.1-2008 |
| 24179 | (``POSIX.1'') specification, except that the conditions for changing the |
| 24180 | saved group ID differ and that, if it is changed, the saved group ID is |
| 24181 | set to the real group ID instead of the effective group ID. |
| 24182 | |
| 24183 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24184 | The s\bse\bet\btr\bre\beg\bgi\bid\bd() system call first appeared in 4.1cBSD, predating POSIX. A |
| 24185 | semantically different version appeared in 4.4BSD. The current version, |
| 24186 | with the original semantics restored, appeared in OpenBSD 3.3. |
| 24187 | |
| 24188 | N\bNA\bAM\bME\bE |
| 24189 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd, g\bge\bet\btr\bre\bes\bsu\bui\bid\bd, s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd, s\bse\bet\btr\bre\bes\bsu\bui\bid\bd - get or set real, effective |
| 24190 | and saved user or group ID |
| 24191 | |
| 24192 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24193 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 24194 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 24195 | |
| 24196 | _\bi_\bn_\bt |
| 24197 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\b*_\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\bs_\bg_\bi_\bd); |
| 24198 | |
| 24199 | _\bi_\bn_\bt |
| 24200 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\b*_\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\bs_\bu_\bi_\bd); |
| 24201 | |
| 24202 | _\bi_\bn_\bt |
| 24203 | s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\bs_\bg_\bi_\bd); |
| 24204 | |
| 24205 | _\bi_\bn_\bt |
| 24206 | s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\bs_\bu_\bi_\bd); |
| 24207 | |
| 24208 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24209 | The s\bse\bet\btr\bre\bes\bsu\bui\bid\bd() function sets the real, effective and saved user IDs of |
| 24210 | the current process. The analogous s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd() sets the real, effective |
| 24211 | and saved group IDs. |
| 24212 | |
| 24213 | Privileged processes may set these IDs to arbitrary values. Unprivileged |
| 24214 | processes are restricted in that each of the new IDs must match one of |
| 24215 | the current IDs. |
| 24216 | |
| 24217 | Passing -1 as an argument causes the corresponding value to remain |
| 24218 | unchanged. |
| 24219 | |
| 24220 | The g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() and g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() calls retrieve the real, effective, and |
| 24221 | saved group and user IDs of the current process, respectively. |
| 24222 | |
| 24223 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24224 | Upon successful completion, the value 0 is returned; otherwise the |
| 24225 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 24226 | error. |
| 24227 | |
| 24228 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24229 | [EPERM] The calling process was not privileged and tried to |
| 24230 | change one or more IDs to a value which was not the |
| 24231 | current real ID, the current effective ID nor the |
| 24232 | current saved ID. |
| 24233 | |
| 24234 | [EFAULT] An address passed to g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() or g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() was |
| 24235 | invalid. |
| 24236 | |
| 24237 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24238 | getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), |
| 24239 | setregid(2), setreuid(2), setuid(2) |
| 24240 | |
| 24241 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24242 | These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') |
| 24243 | specification. While they are not completely portable, they are the |
| 24244 | least ambiguous way to manage user and group IDs. |
| 24245 | |
| 24246 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24247 | These functions first appeared in HP-UX. |
| 24248 | |
| 24249 | N\bNA\bAM\bME\bE |
| 24250 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd, g\bge\bet\btr\bre\bes\bsu\bui\bid\bd, s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd, s\bse\bet\btr\bre\bes\bsu\bui\bid\bd - get or set real, effective |
| 24251 | and saved user or group ID |
| 24252 | |
| 24253 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24254 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 24255 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 24256 | |
| 24257 | _\bi_\bn_\bt |
| 24258 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\b*_\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\bs_\bg_\bi_\bd); |
| 24259 | |
| 24260 | _\bi_\bn_\bt |
| 24261 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\b*_\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\bs_\bu_\bi_\bd); |
| 24262 | |
| 24263 | _\bi_\bn_\bt |
| 24264 | s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\bs_\bg_\bi_\bd); |
| 24265 | |
| 24266 | _\bi_\bn_\bt |
| 24267 | s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\bs_\bu_\bi_\bd); |
| 24268 | |
| 24269 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24270 | The s\bse\bet\btr\bre\bes\bsu\bui\bid\bd() function sets the real, effective and saved user IDs of |
| 24271 | the current process. The analogous s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd() sets the real, effective |
| 24272 | and saved group IDs. |
| 24273 | |
| 24274 | Privileged processes may set these IDs to arbitrary values. Unprivileged |
| 24275 | processes are restricted in that each of the new IDs must match one of |
| 24276 | the current IDs. |
| 24277 | |
| 24278 | Passing -1 as an argument causes the corresponding value to remain |
| 24279 | unchanged. |
| 24280 | |
| 24281 | The g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() and g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() calls retrieve the real, effective, and |
| 24282 | saved group and user IDs of the current process, respectively. |
| 24283 | |
| 24284 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24285 | Upon successful completion, the value 0 is returned; otherwise the |
| 24286 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 24287 | error. |
| 24288 | |
| 24289 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24290 | [EPERM] The calling process was not privileged and tried to |
| 24291 | change one or more IDs to a value which was not the |
| 24292 | current real ID, the current effective ID nor the |
| 24293 | current saved ID. |
| 24294 | |
| 24295 | [EFAULT] An address passed to g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() or g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() was |
| 24296 | invalid. |
| 24297 | |
| 24298 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24299 | getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), |
| 24300 | setregid(2), setreuid(2), setuid(2) |
| 24301 | |
| 24302 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24303 | These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') |
| 24304 | specification. While they are not completely portable, they are the |
| 24305 | least ambiguous way to manage user and group IDs. |
| 24306 | |
| 24307 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24308 | These functions first appeared in HP-UX. |
| 24309 | |
| 24310 | N\bNA\bAM\bME\bE |
| 24311 | s\bse\bet\btr\bre\beu\bui\bid\bd - set real and effective user IDs |
| 24312 | |
| 24313 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24314 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 24315 | |
| 24316 | _\bi_\bn_\bt |
| 24317 | s\bse\bet\btr\bre\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
| 24318 | |
| 24319 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24320 | The real and effective user IDs of the current process are set according |
| 24321 | to the arguments. The saved user ID will be set to the new value of the |
| 24322 | real user ID if a real user ID is specified and either the new real user |
| 24323 | ID value is different from the current value or the new value of the |
| 24324 | effective user ID differs from the current saved user ID. |
| 24325 | |
| 24326 | Unprivileged users may change either user ID to the current value of the |
| 24327 | real, effective, or saved user ID. Only the superuser may make other |
| 24328 | changes. |
| 24329 | |
| 24330 | Supplying a value of -1 for either the real or effective user ID forces |
| 24331 | the system to substitute the current ID in place of the -1 parameter. |
| 24332 | |
| 24333 | The s\bse\bet\btr\bre\beu\bui\bid\bd() function was intended to allow swapping the real and |
| 24334 | effective user IDs in set-user-ID programs to temporarily relinquish the |
| 24335 | set-user-ID value. This purpose is now better served by the use of the |
| 24336 | seteuid(2) function. |
| 24337 | |
| 24338 | When setting the real and effective user IDs to the same value, the |
| 24339 | setuid(2) function is preferred. |
| 24340 | |
| 24341 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24342 | Upon successful completion, the value 0 is returned; otherwise the |
| 24343 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 24344 | error. |
| 24345 | |
| 24346 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24347 | [EPERM] The current process is not the superuser and a change |
| 24348 | other than changing the effective user ID to the real |
| 24349 | user ID was specified. |
| 24350 | |
| 24351 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24352 | getuid(2), seteuid(2), setregid(2), setresuid(2), setuid(2) |
| 24353 | |
| 24354 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24355 | The s\bse\bet\btr\bre\beu\bui\bid\bd() function conforms to the IEEE Std 1003.1-2008 |
| 24356 | (``POSIX.1'') specification, except that the conditions for changing the |
| 24357 | saved user ID differ and that, if it is changed, the saved user ID is set |
| 24358 | to the real user ID instead of the effective user ID. |
| 24359 | |
| 24360 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24361 | The s\bse\bet\btr\bre\beu\bui\bid\bd() system call first appeared in 4.1cBSD, predating POSIX. A |
| 24362 | semantically different version appeared in 4.4BSD. The current version, |
| 24363 | with the original semantics restored, appeared in OpenBSD 3.3. |
| 24364 | |
| 24365 | N\bNA\bAM\bME\bE |
| 24366 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt, s\bse\bet\btr\brl\bli\bim\bmi\bit\bt - control maximum system resource consumption |
| 24367 | |
| 24368 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24369 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 24370 | |
| 24371 | _\bi_\bn_\bt |
| 24372 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt(_\bi_\bn_\bt _\br_\be_\bs_\bo_\bu_\br_\bc_\be, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bl_\bi_\bm_\bi_\bt _\b*_\br_\bl_\bp); |
| 24373 | |
| 24374 | _\bi_\bn_\bt |
| 24375 | s\bse\bet\btr\brl\bli\bim\bmi\bit\bt(_\bi_\bn_\bt _\br_\be_\bs_\bo_\bu_\br_\bc_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\br_\bl_\bi_\bm_\bi_\bt _\b*_\br_\bl_\bp); |
| 24376 | |
| 24377 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24378 | Limits on the consumption of system resources by the current process and |
| 24379 | each process it creates may be obtained with the g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() call, and |
| 24380 | set with the s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() call. |
| 24381 | |
| 24382 | The _\br_\be_\bs_\bo_\bu_\br_\bc_\be parameter is one of the following: |
| 24383 | |
| 24384 | RLIMIT_CORE The largest size (in bytes) _\bc_\bo_\br_\be file that may be |
| 24385 | created. |
| 24386 | |
| 24387 | RLIMIT_CPU The maximum amount of CPU time (in seconds) to be used by |
| 24388 | each process. |
| 24389 | |
| 24390 | RLIMIT_DATA The maximum size (in bytes) of the data segment for a |
| 24391 | process; this includes memory allocated via malloc(3) and |
| 24392 | all other anonymous memory mapped via mmap(2). |
| 24393 | |
| 24394 | RLIMIT_FSIZE The largest size (in bytes) file that may be created. |
| 24395 | |
| 24396 | RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into |
| 24397 | memory using the mlock(2) function. |
| 24398 | |
| 24399 | RLIMIT_NOFILE The maximum number of open files for this process. |
| 24400 | |
| 24401 | RLIMIT_NPROC The maximum number of simultaneous processes for this |
| 24402 | user id. |
| 24403 | |
| 24404 | RLIMIT_RSS The maximum size (in bytes) to which a process's resident |
| 24405 | set size may grow. This imposes a limit on the amount of |
| 24406 | physical memory to be given to a process; if memory is |
| 24407 | tight, the system will prefer to take memory from |
| 24408 | processes that are exceeding their declared resident set |
| 24409 | size. |
| 24410 | |
| 24411 | RLIMIT_STACK The maximum size (in bytes) of the stack segment for a |
| 24412 | process, which defines how far a process's stack segment |
| 24413 | may be extended. Stack extension is performed |
| 24414 | automatically by the system, and is only used by the main |
| 24415 | thread of a process. |
| 24416 | |
| 24417 | A resource limit is specified as a soft limit and a hard limit. When a |
| 24418 | soft limit is exceeded a process may receive a signal (for example, if |
| 24419 | the CPU time or file size is exceeded), but it will be allowed to |
| 24420 | continue execution until it reaches the hard limit (or modifies its |
| 24421 | resource limit). The _\br_\bl_\bi_\bm_\bi_\bt structure is used to specify the hard and |
| 24422 | soft limits on a resource, |
| 24423 | |
| 24424 | struct rlimit { |
| 24425 | rlim_t rlim_cur; /* current (soft) limit */ |
| 24426 | rlim_t rlim_max; /* hard limit */ |
| 24427 | }; |
| 24428 | |
| 24429 | Only the superuser may raise the maximum limits. Other users may only |
| 24430 | alter _\br_\bl_\bi_\bm_\b__\bc_\bu_\br within the range from 0 to _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx or (irreversibly) |
| 24431 | lower _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx. |
| 24432 | |
| 24433 | An ``infinite'' value for a limit is defined as RLIM_INFINITY. |
| 24434 | |
| 24435 | A value of RLIM_SAVED_CUR or RLIM_SAVED_MAX will be stored in _\br_\bl_\bi_\bm_\b__\bc_\bu_\br or |
| 24436 | _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx respectively by g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() if the value for the current or |
| 24437 | maximum resource limit cannot be stored in an rlim_t. The values |
| 24438 | RLIM_SAVED_CUR and RLIM_SAVED_MAX should not be used in a call to |
| 24439 | s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() unless they were returned by a previous call to g\bge\bet\btr\brl\bli\bim\bmi\bit\bt(). |
| 24440 | |
| 24441 | Because this information is stored in the per-process information, this |
| 24442 | system call must be executed directly by the shell if it is to affect all |
| 24443 | future processes created by the shell; l\bli\bim\bmi\bit\bt is thus a built-in command |
| 24444 | to csh(1) and u\bul\bli\bim\bmi\bit\bt is the sh(1) equivalent. |
| 24445 | |
| 24446 | The system refuses to extend the data or stack space when the limits |
| 24447 | would be exceeded in the normal way: a brk(2) call fails if the data |
| 24448 | space limit is reached. When the stack limit is reached, the process |
| 24449 | receives a segmentation fault (SIGSEGV); if this signal is not caught by |
| 24450 | a handler using the signal stack, this signal will kill the process. |
| 24451 | |
| 24452 | A file I/O operation that would create a file larger than the process' |
| 24453 | soft limit will cause the write to fail and a signal SIGXFSZ to be |
| 24454 | generated; this normally terminates the process, but may be caught. When |
| 24455 | the soft CPU time limit is exceeded, a signal SIGXCPU is sent to the |
| 24456 | offending process. |
| 24457 | |
| 24458 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24459 | Upon successful completion, the value 0 is returned; otherwise the |
| 24460 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 24461 | error. |
| 24462 | |
| 24463 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24464 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() will fail if: |
| 24465 | |
| 24466 | [EFAULT] The address specified for _\br_\bl_\bp is invalid. |
| 24467 | |
| 24468 | [EINVAL] An unrecognized value for _\br_\be_\bs_\bo_\bu_\br_\bc_\be was specified. |
| 24469 | |
| 24470 | In addition, s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() may return the following errors: |
| 24471 | |
| 24472 | [EINVAL] The new _\br_\bl_\bi_\bm_\b__\bc_\bu_\br is greater than the new _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx. |
| 24473 | |
| 24474 | [EPERM] The new _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx is greater than the current maximum |
| 24475 | limit value, and the caller is not the superuser. |
| 24476 | |
| 24477 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24478 | csh(1), sh(1), quotactl(2), sigaction(2), sigaltstack(2), sysctl(3) |
| 24479 | |
| 24480 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24481 | The g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() functions conform to IEEE Std 1003.1-2008 |
| 24482 | (``POSIX.1''). |
| 24483 | |
| 24484 | The RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS resources are non- |
| 24485 | standard extensions. |
| 24486 | |
| 24487 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24488 | The g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() system calls first appeared in 4.1cBSD. |
| 24489 | |
| 24490 | B\bBU\bUG\bGS\bS |
| 24491 | The RLIMIT_AS resource is missing. |
| 24492 | |
| 24493 | N\bNA\bAM\bME\bE |
| 24494 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be, s\bse\bet\btr\brt\bta\bab\bbl\ble\be - get and set the default routing table of the |
| 24495 | current process |
| 24496 | |
| 24497 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24498 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 24499 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 24500 | |
| 24501 | _\bi_\bn_\bt |
| 24502 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be(_\bv_\bo_\bi_\bd); |
| 24503 | |
| 24504 | _\bi_\bn_\bt |
| 24505 | s\bse\bet\btr\brt\bta\bab\bbl\ble\be(_\bi_\bn_\bt _\br_\bt_\ba_\bb_\bl_\be_\bi_\bd); |
| 24506 | |
| 24507 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24508 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be() and s\bse\bet\btr\brt\bta\bab\bbl\ble\be() manipulate the routing table and routing |
| 24509 | domain associated with the current process. |
| 24510 | |
| 24511 | Only the superuser is allowed to change the process routing table if it |
| 24512 | is already set to a non-zero value. |
| 24513 | |
| 24514 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24515 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be() returns the routing table of the current process. Upon |
| 24516 | successful completion, s\bse\bet\btr\brt\bta\bab\bbl\ble\be() returns 0 if the call succeeds, -1 if |
| 24517 | it fails. |
| 24518 | |
| 24519 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24520 | The call succeeds unless: |
| 24521 | |
| 24522 | [EINVAL] The value of the _\br_\bt_\ba_\bb_\bl_\be_\bi_\bd argument is not a valid |
| 24523 | routing table. |
| 24524 | |
| 24525 | [EPERM] The user is not the superuser and the routing table of |
| 24526 | the calling process is already set to a non-zero |
| 24527 | value. |
| 24528 | |
| 24529 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24530 | getsockopt(2), route(8) |
| 24531 | |
| 24532 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24533 | The g\bge\bet\btr\brt\bta\bab\bbl\ble\be() and s\bse\bet\btr\brt\bta\bab\bbl\ble\be() system calls appeared in OpenBSD 4.8. |
| 24534 | |
| 24535 | N\bNA\bAM\bME\bE |
| 24536 | s\bse\bet\bts\bsi\bid\bd - create session and set process group ID |
| 24537 | |
| 24538 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24539 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 24540 | |
| 24541 | _\bp_\bi_\bd_\b__\bt |
| 24542 | s\bse\bet\bts\bsi\bid\bd(_\bv_\bo_\bi_\bd); |
| 24543 | |
| 24544 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24545 | The s\bse\bet\bts\bsi\bid\bd function creates a new session. The calling process is the |
| 24546 | session leader of the new session, is the process group leader of a new |
| 24547 | process group and has no controlling terminal. The calling process is |
| 24548 | the only process in either the session or the process group. |
| 24549 | |
| 24550 | Upon successful completion, the s\bse\bet\bts\bsi\bid\bd function returns the value of the |
| 24551 | process group ID of the new process group, which is the same as the |
| 24552 | process ID of the calling process. |
| 24553 | |
| 24554 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24555 | If an error occurs, s\bse\bet\bts\bsi\bid\bd returns -1 and the global variable _\be_\br_\br_\bn_\bo is |
| 24556 | set to indicate the error, as follows: |
| 24557 | |
| 24558 | [EPERM] The calling process is already a process group leader, |
| 24559 | or the process group ID of a process other than the |
| 24560 | calling process matches the process ID of the calling |
| 24561 | process. |
| 24562 | |
| 24563 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24564 | getsid(2), setpgid(2), tcgetpgrp(3), tcsetpgrp(3) |
| 24565 | |
| 24566 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24567 | The s\bse\bet\bts\bsi\bid\bd function is expected to be compliant with the IEEE Std |
| 24568 | 1003.1-2008 (``POSIX.1'') specification. |
| 24569 | |
| 24570 | N\bNA\bAM\bME\bE |
| 24571 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt, s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt - get and set options on sockets |
| 24572 | |
| 24573 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24574 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 24575 | |
| 24576 | _\bi_\bn_\bt |
| 24577 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bl_\be_\bv_\be_\bl, _\bi_\bn_\bt _\bo_\bp_\bt_\bn_\ba_\bm_\be, _\bv_\bo_\bi_\bd _\b*_\bo_\bp_\bt_\bv_\ba_\bl, |
| 24578 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bo_\bp_\bt_\bl_\be_\bn); |
| 24579 | |
| 24580 | _\bi_\bn_\bt |
| 24581 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bl_\be_\bv_\be_\bl, _\bi_\bn_\bt _\bo_\bp_\bt_\bn_\ba_\bm_\be, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bo_\bp_\bt_\bv_\ba_\bl, |
| 24582 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bo_\bp_\bt_\bl_\be_\bn); |
| 24583 | |
| 24584 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24585 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() manipulate the _\bo_\bp_\bt_\bi_\bo_\bn_\bs associated with a |
| 24586 | socket. Options may exist at multiple protocol levels; they are always |
| 24587 | present at the uppermost ``socket'' level. |
| 24588 | |
| 24589 | When manipulating socket options the level at which the option resides |
| 24590 | and the name of the option must be specified. To manipulate options at |
| 24591 | the socket level, _\bl_\be_\bv_\be_\bl is specified as SOL_SOCKET. To manipulate |
| 24592 | options at any other level the protocol number of the appropriate |
| 24593 | protocol controlling the option is supplied. For example, to indicate |
| 24594 | that an option is to be interpreted by the TCP protocol, _\bl_\be_\bv_\be_\bl should be |
| 24595 | set to the protocol number of TCP; see getprotoent(3). |
| 24596 | |
| 24597 | The parameters _\bo_\bp_\bt_\bv_\ba_\bl and _\bo_\bp_\bt_\bl_\be_\bn are used to access option values for |
| 24598 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() they identify a buffer in which the value |
| 24599 | for the requested option(s) are to be returned. For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), _\bo_\bp_\bt_\bl_\be_\bn |
| 24600 | is a value-result parameter, initially containing the size of the buffer |
| 24601 | pointed to by _\bo_\bp_\bt_\bv_\ba_\bl, and modified on return to indicate the actual size |
| 24602 | of the value returned. If no option value is to be supplied or returned, |
| 24603 | _\bo_\bp_\bt_\bv_\ba_\bl may be NULL. |
| 24604 | |
| 24605 | _\bo_\bp_\bt_\bn_\ba_\bm_\be and any specified options are passed uninterpreted to the |
| 24606 | appropriate protocol module for interpretation. The include file |
| 24607 | <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh> contains definitions for socket level options, described |
| 24608 | below. Options at other protocol levels vary in format and name; consult |
| 24609 | the appropriate entries in section 4 of the manual. |
| 24610 | |
| 24611 | Most socket-level options utilize an int parameter for _\bo_\bp_\bt_\bv_\ba_\bl. For |
| 24612 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), the parameter should be non-zero to enable a boolean |
| 24613 | option, or zero if the option is to be disabled. SO_LINGER uses a struct |
| 24614 | linger parameter, defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>, which specifies the desired |
| 24615 | state of the option and the linger interval (see below). SO_SNDTIMEO and |
| 24616 | SO_RCVTIMEO use a struct timeval parameter, defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. |
| 24617 | |
| 24618 | The following options are recognized at the socket level. Except as |
| 24619 | noted, each may be examined with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and set with s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). |
| 24620 | |
| 24621 | SO_DEBUG enables recording of debugging information |
| 24622 | SO_REUSEADDR enables local address reuse |
| 24623 | SO_REUSEPORT enables duplicate address and port bindings |
| 24624 | SO_KEEPALIVE enables keep connections alive |
| 24625 | SO_DONTROUTE enables routing bypass; not supported |
| 24626 | SO_LINGER linger on close if data present |
| 24627 | SO_BROADCAST enables permission to transmit broadcast messages |
| 24628 | SO_OOBINLINE enables reception of out-of-band data in band |
| 24629 | SO_BINDANY enables binding to any address |
| 24630 | SO_SNDBUF set buffer size for output |
| 24631 | SO_RCVBUF set buffer size for input |
| 24632 | SO_SNDLOWAT set minimum count for output |
| 24633 | SO_RCVLOWAT set minimum count for input |
| 24634 | SO_SNDTIMEO set timeout value for output |
| 24635 | SO_RCVTIMEO set timeout value for input |
| 24636 | SO_TIMESTAMP enables reception of a timestamp with datagrams |
| 24637 | SO_PEERCRED get the credentials from other side of connection |
| 24638 | SO_RTABLE set the routing table used for route lookups |
| 24639 | SO_SPLICE splice two sockets together or get data length |
| 24640 | SO_TYPE get the type of the socket (get only) |
| 24641 | SO_ERROR get and clear error on the socket (get only) |
| 24642 | |
| 24643 | SO_DEBUG enables debugging in the underlying protocol modules. |
| 24644 | SO_REUSEADDR indicates that the rules used in validating addresses |
| 24645 | supplied in a bind(2) call should allow reuse of local addresses. |
| 24646 | SO_REUSEPORT allows completely duplicate bindings by multiple processes |
| 24647 | if they all set SO_REUSEPORT before binding the port. This option |
| 24648 | permits multiple instances of a program to each receive UDP/IP multicast |
| 24649 | or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables |
| 24650 | the periodic transmission of messages on a connected socket. Should the |
| 24651 | connected party fail to respond to these messages, the connection is |
| 24652 | considered broken and processes using the socket are notified via a |
| 24653 | SIGPIPE signal when attempting to send data. |
| 24654 | |
| 24655 | SO_LINGER controls the action taken when unsent messages are queued on |
| 24656 | socket and a close(2) is performed. If the socket promises reliable |
| 24657 | delivery of data and SO_LINGER is set, the system will block the process |
| 24658 | on the close(2) attempt until it is able to transmit the data or until it |
| 24659 | decides it is unable to deliver the information (a timeout period |
| 24660 | measured in seconds, termed the linger interval, is specified in the |
| 24661 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() call when SO_LINGER is requested). If SO_LINGER is disabled |
| 24662 | and a close(2) is issued, the system will process the close in a manner |
| 24663 | that allows the process to continue as quickly as possible. |
| 24664 | |
| 24665 | The option SO_BROADCAST requests permission to send broadcast datagrams |
| 24666 | on the socket. Broadcast was a privileged operation in earlier versions |
| 24667 | of the system. With protocols that support out-of-band data, the |
| 24668 | SO_OOBINLINE option requests that out-of-band data be placed in the |
| 24669 | normal data input queue as received; it will then be accessible with |
| 24670 | recv(2) or read(2) calls without the MSG_OOB flag. Some protocols always |
| 24671 | behave as if this option is set. |
| 24672 | |
| 24673 | SO_BINDANY allows the socket to be bound to addresses which are not local |
| 24674 | to the machine, so it can be used to make a transparent proxy. Note that |
| 24675 | this option is limited to the super-user. In order to receive packets |
| 24676 | for these addresses, SO_BINDANY needs to be combined with matching |
| 24677 | outgoing pf(4) rules with the _\bd_\bi_\bv_\be_\br_\bt_\b-_\br_\be_\bp_\bl_\by parameter. For example, with |
| 24678 | the following rule the socket receives packets for 192.168.0.10 even if |
| 24679 | it is not a local address: |
| 24680 | |
| 24681 | pass out inet from 192.168.0.10 divert-reply |
| 24682 | |
| 24683 | SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes |
| 24684 | allocated for output and input buffers, respectively. The buffer size |
| 24685 | may be increased for high-volume connections, or may be decreased to |
| 24686 | limit the possible backlog of incoming data. The system places an |
| 24687 | absolute limit on these values. |
| 24688 | |
| 24689 | SO_SNDLOWAT is an option to set the minimum count for output operations. |
| 24690 | Most output operations process all of the data supplied by the call, |
| 24691 | delivering data to the protocol for transmission and blocking as |
| 24692 | necessary for flow control. Nonblocking output operations will process |
| 24693 | as much data as permitted subject to flow control without blocking, but |
| 24694 | will process no data if flow control does not allow the smaller of the |
| 24695 | low water mark value or the entire request to be processed. A select(2) |
| 24696 | or poll(2) operation testing the ability to write to a socket will return |
| 24697 | true only if the low water mark amount could be processed. The default |
| 24698 | value for SO_SNDLOWAT is set to a convenient size for network efficiency, |
| 24699 | often 1024. SO_RCVLOWAT is an option to set the minimum count for input |
| 24700 | operations. In general, receive calls will block until any (non-zero) |
| 24701 | amount of data is received, then return with the smaller of the amount |
| 24702 | available or the amount requested. The default value for SO_RCVLOWAT is |
| 24703 | 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls |
| 24704 | normally wait until they have received the smaller of the low water mark |
| 24705 | value or the requested amount. Receive calls may still return less than |
| 24706 | the low water mark if an error occurs, a signal is caught, or the type of |
| 24707 | data next in the receive queue is different than that returned. |
| 24708 | |
| 24709 | SO_SNDTIMEO is an option to set a timeout value for output operations. |
| 24710 | It accepts a struct timeval parameter with the number of seconds and |
| 24711 | microseconds used to limit waits for output operations to complete. If a |
| 24712 | send operation has blocked for this much time, it returns with a partial |
| 24713 | count or with the error EWOULDBLOCK if no data was sent. In the current |
| 24714 | implementation, this timer is restarted each time additional data are |
| 24715 | delivered to the protocol, implying that the limit applies to output |
| 24716 | portions ranging in size from the low water mark to the high water mark |
| 24717 | for output. SO_RCVTIMEO is an option to set a timeout value for input |
| 24718 | operations. It accepts a struct timeval parameter with the number of |
| 24719 | seconds and microseconds used to limit waits for input operations to |
| 24720 | complete. In the current implementation, this timer is restarted each |
| 24721 | time additional data are received by the protocol, and thus the limit is |
| 24722 | in effect an inactivity timer. If a receive operation has been blocked |
| 24723 | for this much time without receiving additional data, it returns with a |
| 24724 | short count or with the error EWOULDBLOCK if no data were received. |
| 24725 | |
| 24726 | If the SO_TIMESTAMP option is enabled on a SOCK_DGRAM socket, the |
| 24727 | recvmsg(2) call will return a timestamp corresponding to when the |
| 24728 | datagram was received. The msg_control field in the msghdr structure |
| 24729 | points to a buffer that contains a cmsghdr structure followed by a struct |
| 24730 | timeval. The cmsghdr fields have the following values: |
| 24731 | |
| 24732 | cmsg_len = CMSG_LEN(sizeof(struct timeval)) |
| 24733 | cmsg_level = SOL_SOCKET |
| 24734 | cmsg_type = SCM_TIMESTAMP |
| 24735 | |
| 24736 | SO_PEERCRED fetches the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\bp_\be_\be_\br_\bc_\br_\be_\bd credentials from the other |
| 24737 | side of the connection (currently only possible on AF_UNIX sockets). |
| 24738 | These credentials are from the time that bind(2) or connect(2) were |
| 24739 | called. |
| 24740 | |
| 24741 | The SO_RTABLE option gets or sets the routing table which will be used by |
| 24742 | the socket for address lookups. If a protocol family of the socket |
| 24743 | doesn't support switching routing tables, the ENOPROTOOPT error is |
| 24744 | returned. Only the superuser is allowed to change the routing table if |
| 24745 | it is already set to a non-zero value. A socket's chosen routing table |
| 24746 | is initialized from the process's configuration, previously selected |
| 24747 | using setrtable(2). |
| 24748 | |
| 24749 | SO_SPLICE can splice together two TCP or UDP sockets for zero-copy data |
| 24750 | transfers. Both sockets must be of the same type. In the first form, |
| 24751 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() is called with the source socket _\bs and the drain socket's |
| 24752 | _\bi_\bn_\bt file descriptor as _\bo_\bp_\bt_\bv_\ba_\bl. In the second form, _\bo_\bp_\bt_\bv_\ba_\bl is a _\bs_\bt_\br_\bu_\bc_\bt |
| 24753 | _\bs_\bp_\bl_\bi_\bc_\be with the drain socket in _\bs_\bp_\b__\bf_\bd, a positive maximum number of bytes |
| 24754 | or 0 in _\bs_\bp_\b__\bm_\ba_\bx and an idle timeout _\bs_\bp_\b__\bi_\bd_\bl_\be in the form of a _\bs_\bt_\br_\bu_\bc_\bt |
| 24755 | _\bt_\bi_\bm_\be_\bv_\ba_\bl. If -1 is given as drain socket, the source socket _\bs gets |
| 24756 | unspliced. Otherwise the spliced data transfer continues within the |
| 24757 | kernel until the optional maximum is reached, one of the connections |
| 24758 | terminates, idle timeout expires or an error occurs. A successful |
| 24759 | select(2), poll(2), or kqueue(2) operation testing the ability to read |
| 24760 | from the source socket indicates that the splicing has terminated. The |
| 24761 | error status can be examined with SO_ERROR at the source socket. The |
| 24762 | ETIMEDOUT error is set if there was no data transferred between two |
| 24763 | sockets during the _\bs_\bp_\b__\bi_\bd_\bl_\be period of time. The EFBIG error is set after |
| 24764 | exactly _\bs_\bp_\b__\bm_\ba_\bx bytes have been transferred. Note that if a maximum is |
| 24765 | given, it is only guaranteed that no more bytes are transferred. A short |
| 24766 | splice can happen, but then a second call to splice will transfer the |
| 24767 | remaining data immediately. The SO_SPLICE option with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and |
| 24768 | an _\bo_\bf_\bf_\b__\bt value as _\bo_\bp_\bt_\bv_\ba_\bl can be used to retrieve the number of bytes |
| 24769 | transferred so far from the source socket _\bs. A successful new splice |
| 24770 | resets this number. |
| 24771 | |
| 24772 | Finally, SO_TYPE and SO_ERROR are options used only with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). |
| 24773 | SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful |
| 24774 | for servers that inherit sockets on startup. SO_ERROR returns any |
| 24775 | pending error on the socket and clears the error status. It may be used |
| 24776 | to check for asynchronous errors on connected datagram sockets or for |
| 24777 | other asynchronous errors. |
| 24778 | |
| 24779 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24780 | Upon successful completion, the value 0 is returned; otherwise the |
| 24781 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 24782 | error. |
| 24783 | |
| 24784 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24785 | The call succeeds unless: |
| 24786 | |
| 24787 | [EBADF] The argument _\bs is not a valid descriptor. |
| 24788 | |
| 24789 | [ENOTSOCK] The argument _\bs is a file, not a socket. |
| 24790 | |
| 24791 | [ENOPROTOOPT] The option is unknown at the level indicated. |
| 24792 | |
| 24793 | [EOPNOTSUPP] The option is unsupported. |
| 24794 | |
| 24795 | [EFAULT] The address pointed to by _\bo_\bp_\bt_\bv_\ba_\bl is not in a valid |
| 24796 | part of the process address space. For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), |
| 24797 | this error may also be returned if _\bo_\bp_\bt_\bl_\be_\bn is not in a |
| 24798 | valid part of the process address space. |
| 24799 | |
| 24800 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24801 | connect(2), getrtable(2), ioctl(2), poll(2), select(2), socket(2), |
| 24802 | getprotoent(3), divert(4), pf.conf(5), protocols(5), sosplice(9) |
| 24803 | |
| 24804 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24805 | The g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() functions conform to IEEE Std |
| 24806 | 1003.1-2008 (``POSIX.1''). |
| 24807 | |
| 24808 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24809 | The g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() system call appeared in 4.2BSD. |
| 24810 | |
| 24811 | B\bBU\bUG\bGS\bS |
| 24812 | Several of the socket options should be handled at lower levels of the |
| 24813 | system. |
| 24814 | |
| 24815 | N\bNA\bAM\bME\bE |
| 24816 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by, s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by - get/set date and time |
| 24817 | |
| 24818 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24819 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 24820 | |
| 24821 | _\bi_\bn_\bt |
| 24822 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be _\b*_\bt_\bz_\bp); |
| 24823 | |
| 24824 | _\bi_\bn_\bt |
| 24825 | s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bp, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be _\b*_\bt_\bz_\bp); |
| 24826 | |
| 24827 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24828 | N\bNo\bot\bte\be:\b: t\bti\bim\bme\bez\bzo\bon\bne\be i\bis\bs n\bno\bo l\blo\bon\bng\bge\ber\br u\bus\bse\bed\bd;\b; t\bth\bhi\bis\bs i\bin\bnf\bfo\bor\brm\bma\bat\bti\bio\bon\bn i\bis\bs k\bke\bep\bpt\bt o\bou\but\bts\bsi\bid\bde\be t\bth\bhe\be |
| 24829 | k\bke\ber\brn\bne\bel\bl.\b. |
| 24830 | |
| 24831 | The system's notion of the current Greenwich time and the current time |
| 24832 | zone is obtained with the g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() call, and set with the |
| 24833 | s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() call. The time is expressed in seconds and microseconds |
| 24834 | since midnight (0 hour), January 1, 1970. The resolution of the system |
| 24835 | clock is hardware dependent, and the time may be updated continuously or |
| 24836 | in ``ticks''. If _\bt_\bp or _\bt_\bz_\bp is NULL, the associated time information will |
| 24837 | not be returned or set. |
| 24838 | |
| 24839 | The structures pointed to by _\bt_\bp and _\bt_\bz_\bp are defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
| 24840 | |
| 24841 | struct timeval { |
| 24842 | time_t tv_sec; /* seconds since Jan. 1, 1970 */ |
| 24843 | suseconds_t tv_usec; /* and microseconds */ |
| 24844 | }; |
| 24845 | |
| 24846 | struct timezone { |
| 24847 | int tz_minuteswest; /* of Greenwich */ |
| 24848 | int tz_dsttime; /* type of dst correction to apply */ |
| 24849 | }; |
| 24850 | |
| 24851 | The _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be structure indicates the local time zone (measured in minutes |
| 24852 | of time westward from Greenwich), and a flag that, if nonzero, indicates |
| 24853 | that Daylight Saving time applies locally during the appropriate part of |
| 24854 | the year. |
| 24855 | |
| 24856 | Only the superuser may set the time of day or time zone. If the system |
| 24857 | securelevel is greater than 1 (see init(8)), the time may only be |
| 24858 | advanced. This limitation is imposed to prevent a malicious superuser |
| 24859 | from setting arbitrary time stamps on files. The system time can still |
| 24860 | be adjusted backwards using the adjtime(2) system call even when the |
| 24861 | system is secure. |
| 24862 | |
| 24863 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24864 | Upon successful completion, the value 0 is returned; otherwise the |
| 24865 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 24866 | error. |
| 24867 | |
| 24868 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24869 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() and s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() will succeed unless: |
| 24870 | |
| 24871 | [EFAULT] An argument address referenced invalid memory. |
| 24872 | |
| 24873 | In addition, s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() may return the following error: |
| 24874 | |
| 24875 | [EPERM] A user other than the superuser attempted to set the |
| 24876 | time. |
| 24877 | |
| 24878 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24879 | date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3) |
| 24880 | |
| 24881 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24882 | The g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() function conforms to IEEE Std 1003.1-2008 |
| 24883 | (``POSIX.1''). |
| 24884 | |
| 24885 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24886 | As predecessors of these functions, former system calls t\bti\bim\bme\be() and |
| 24887 | s\bst\bti\bim\bme\be() first appeared in Version 1 AT&T UNIX, and f\bft\bti\bim\bme\be() first appeared |
| 24888 | in Version 7 AT&T UNIX. The g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() and s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() system |
| 24889 | calls first appeared in 4.1cBSD. |
| 24890 | |
| 24891 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 24892 | Setting the time with s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() is dangerous; if possible use |
| 24893 | adjtime(2) instead. Many daemon programming techniques utilize time- |
| 24894 | delta techniques using the results from g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() instead of from |
| 24895 | clock_gettime(2) on the CLOCK_MONOTONIC clock. Time jumps can cause |
| 24896 | these programs to malfunction in unexpected ways. If the time must be |
| 24897 | set, consider rebooting the machine for safety. |
| 24898 | |
| 24899 | N\bNA\bAM\bME\bE |
| 24900 | s\bse\bet\btu\bui\bid\bd, s\bse\bet\bte\beu\bui\bid\bd, s\bse\bet\btg\bgi\bid\bd, s\bse\bet\bte\beg\bgi\bid\bd - set user and group ID |
| 24901 | |
| 24902 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24903 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 24904 | |
| 24905 | _\bi_\bn_\bt |
| 24906 | s\bse\bet\btu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\bu_\bi_\bd); |
| 24907 | |
| 24908 | _\bi_\bn_\bt |
| 24909 | s\bse\bet\bte\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
| 24910 | |
| 24911 | _\bi_\bn_\bt |
| 24912 | s\bse\bet\btg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
| 24913 | |
| 24914 | _\bi_\bn_\bt |
| 24915 | s\bse\bet\bte\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
| 24916 | |
| 24917 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24918 | The s\bse\bet\btu\bui\bid\bd() function sets the real and effective user IDs and the saved |
| 24919 | set-user-ID of the current process to the specified value. The s\bse\bet\btu\bui\bid\bd() |
| 24920 | function is permitted if the effective user ID is that of the superuser, |
| 24921 | or if the specified user ID is the same as the effective user ID. If |
| 24922 | not, but the specified user ID is the same as the real user ID, s\bse\bet\btu\bui\bid\bd() |
| 24923 | will set the effective user ID to the real user ID. |
| 24924 | |
| 24925 | The s\bse\bet\btg\bgi\bid\bd() function sets the real and effective group IDs and the saved |
| 24926 | set-group-ID of the current process to the specified value. The s\bse\bet\btg\bgi\bid\bd() |
| 24927 | function is permitted if the effective user ID is that of the superuser, |
| 24928 | or if the specified group ID is the same as the effective group ID. If |
| 24929 | not, but the specified group ID is the same as the real group ID, |
| 24930 | s\bse\bet\btg\bgi\bid\bd() will set the effective group ID to the real group ID. |
| 24931 | Supplementary group IDs remain unchanged. |
| 24932 | |
| 24933 | The s\bse\bet\bte\beu\bui\bid\bd() function (s\bse\bet\bte\beg\bgi\bid\bd()) sets the effective user ID (group ID) |
| 24934 | of the current process. The effective user ID may be set to the value of |
| 24935 | the real user ID or the saved set-user-ID (see intro(2) and execve(2)); |
| 24936 | in this way, the effective user ID of a set-user-ID executable may be |
| 24937 | toggled by switching to the real user ID, then re-enabled by reverting to |
| 24938 | the set-user-ID value. Similarly, the effective group ID may be set to |
| 24939 | the value of the real group ID or the saved set-group-ID. |
| 24940 | |
| 24941 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 24942 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions return the |
| 24943 | value 0 if successful; otherwise the value -1 is returned and the global |
| 24944 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 24945 | |
| 24946 | E\bER\bRR\bRO\bOR\bRS\bS |
| 24947 | s\bse\bet\btu\bui\bid\bd() and s\bse\bet\bte\beu\bui\bid\bd() will succeed unless: |
| 24948 | |
| 24949 | [EPERM] The user is not the superuser and the requested _\bu_\bi_\bd or |
| 24950 | _\be_\bu_\bi_\bd is not the process's real, effective, or saved |
| 24951 | UID. |
| 24952 | |
| 24953 | s\bse\bet\btg\bgi\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() will succeed unless: |
| 24954 | |
| 24955 | [EPERM] The user is not the superuser and the requested _\bg_\bi_\bd or |
| 24956 | _\be_\bg_\bi_\bd is not the process's real, effective, or saved |
| 24957 | GID. |
| 24958 | |
| 24959 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 24960 | getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), |
| 24961 | setresgid(2), setresuid(2), setreuid(2) |
| 24962 | |
| 24963 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 24964 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions conform to |
| 24965 | IEEE Std 1003.1-2008 (``POSIX.1''). |
| 24966 | |
| 24967 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 24968 | The s\bse\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX; s\bse\bet\btg\bgi\bid\bd() |
| 24969 | in Version 4 AT&T UNIX; and s\bse\bet\bte\beu\bui\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() in 4.2BSD. |
| 24970 | |
| 24971 | N\bNA\bAM\bME\bE |
| 24972 | s\bsh\bhm\bma\bat\bt, s\bsh\bhm\bmd\bdt\bt - map/unmap shared memory |
| 24973 | |
| 24974 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 24975 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsh\bhm\bm.\b.h\bh>\b> |
| 24976 | |
| 24977 | _\bv_\bo_\bi_\bd _\b* |
| 24978 | s\bsh\bhm\bma\bat\bt(_\bi_\bn_\bt _\bs_\bh_\bm_\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bs_\bh_\bm_\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bs_\bh_\bm_\bf_\bl_\bg); |
| 24979 | |
| 24980 | _\bi_\bn_\bt |
| 24981 | s\bsh\bhm\bmd\bdt\bt(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bs_\bh_\bm_\ba_\bd_\bd_\br); |
| 24982 | |
| 24983 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 24984 | s\bsh\bhm\bma\bat\bt() maps the shared memory segment associated with the shared memory |
| 24985 | identifier _\bs_\bh_\bm_\bi_\bd into the address space of the calling process. The |
| 24986 | address at which the segment is mapped is determined by the _\bs_\bh_\bm_\ba_\bd_\bd_\br |
| 24987 | parameter. If it is equal to 0, the system will pick an address itself. |
| 24988 | Otherwise, an attempt is made to map the shared memory segment at the |
| 24989 | address _\bs_\bh_\bm_\ba_\bd_\bd_\br specifies. If SHM_RND is set in _\bs_\bh_\bm_\bf_\bl_\bg, the system will |
| 24990 | round the address down to a multiple of SHMLBA bytes (SHMLBA is defined |
| 24991 | in <_\bs_\by_\bs_\b/_\bs_\bh_\bm_\b._\bh>). |
| 24992 | |
| 24993 | A shared memory segment can be mapped read-only by specifying the |
| 24994 | SHM_RDONLY flag in _\bs_\bh_\bm_\bf_\bl_\bg. |
| 24995 | |
| 24996 | s\bsh\bhm\bmd\bdt\bt() unmaps the shared memory segment that is currently mapped at |
| 24997 | _\bs_\bh_\bm_\ba_\bd_\bd_\br from the calling process' address space. _\bs_\bh_\bm_\ba_\bd_\bd_\br must be a value |
| 24998 | returned by a prior s\bsh\bhm\bma\bat\bt() call. A shared memory segment will remain |
| 24999 | existent until it is removed by a call to shmctl(2) with the IPC_RMID |
| 25000 | command. |
| 25001 | |
| 25002 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25003 | s\bsh\bhm\bma\bat\bt() returns the address at which the shared memory segment has been |
| 25004 | mapped into the calling process' address space when successful, s\bsh\bhm\bmd\bdt\bt() |
| 25005 | returns 0 on successful completion. Otherwise, a value of -1 is |
| 25006 | returned, and the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 25007 | |
| 25008 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25009 | s\bsh\bhm\bma\bat\bt() will fail if: |
| 25010 | |
| 25011 | [EACCES] The calling process has no permission to access this |
| 25012 | shared memory segment. |
| 25013 | |
| 25014 | [ENOMEM] There is not enough available data space for the |
| 25015 | calling process to map the shared memory segment. |
| 25016 | |
| 25017 | [EINVAL] _\bs_\bh_\bm_\bi_\bd is not a valid shared memory identifier. |
| 25018 | |
| 25019 | _\bs_\bh_\bm_\ba_\bd_\bd_\br specifies an illegal address. |
| 25020 | |
| 25021 | [EMFILE] The number of shared memory segments has reached the |
| 25022 | system-wide limit. |
| 25023 | |
| 25024 | s\bsh\bhm\bmd\bdt\bt() will fail if: |
| 25025 | |
| 25026 | [EINVAL] _\bs_\bh_\bm_\ba_\bd_\bd_\br is not the start address of a mapped shared |
| 25027 | memory segment. |
| 25028 | |
| 25029 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25030 | ipcrm(1), ipcs(1), mmap(2), shmctl(2), shmget(2) |
| 25031 | |
| 25032 | N\bNA\bAM\bME\bE |
| 25033 | s\bsh\bhm\bmc\bct\btl\bl - shared memory control operations |
| 25034 | |
| 25035 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25036 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsh\bhm\bm.\b.h\bh>\b> |
| 25037 | |
| 25038 | _\bi_\bn_\bt |
| 25039 | s\bsh\bhm\bmc\bct\btl\bl(_\bi_\bn_\bt _\bs_\bh_\bm_\bi_\bd, _\bi_\bn_\bt _\bc_\bm_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bh_\bm_\bi_\bd_\b__\bd_\bs _\b*_\bb_\bu_\bf); |
| 25040 | |
| 25041 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25042 | The s\bsh\bhm\bmc\bct\btl\bl() system call performs some control operations on the shared |
| 25043 | memory area specified by _\bs_\bh_\bm_\bi_\bd. |
| 25044 | |
| 25045 | Each shared memory segment has a data structure associated with it, parts |
| 25046 | of which may be altered by s\bsh\bhm\bmc\bct\btl\bl() and parts of which determine the |
| 25047 | actions of s\bsh\bhm\bmc\bct\btl\bl(). |
| 25048 | |
| 25049 | This structure is defined as follows in <_\bs_\by_\bs_\b/_\bs_\bh_\bm_\b._\bh>: |
| 25050 | |
| 25051 | struct shmid_ds { |
| 25052 | struct ipc_perm shm_perm; /* operation permissions */ |
| 25053 | int shm_segsz; /* size of segment in bytes */ |
| 25054 | pid_t shm_lpid; /* pid of last shm op */ |
| 25055 | pid_t shm_cpid; /* pid of creator */ |
| 25056 | short shm_nattch; /* # of current attaches */ |
| 25057 | time_t shm_atime; /* last shmat() time*/ |
| 25058 | time_t shm_dtime; /* last shmdt() time */ |
| 25059 | time_t shm_ctime; /* last change by shmctl() */ |
| 25060 | void *shm_internal; /* sysv stupidity */ |
| 25061 | }; |
| 25062 | |
| 25063 | The ipc_perm structure used inside the shmid_ds structure is defined in |
| 25064 | <_\bs_\by_\bs_\b/_\bi_\bp_\bc_\b._\bh> and looks like this: |
| 25065 | |
| 25066 | struct ipc_perm { |
| 25067 | uid_t cuid; /* creator user id */ |
| 25068 | gid_t cgid; /* creator group id */ |
| 25069 | uid_t uid; /* user id */ |
| 25070 | gid_t gid; /* group id */ |
| 25071 | mode_t mode; /* r/w permission (see chmod(2)) */ |
| 25072 | u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ |
| 25073 | key_t key; /* user specified msg/sem/shm key */ |
| 25074 | }; |
| 25075 | |
| 25076 | The operation to be performed by s\bsh\bhm\bmc\bct\btl\bl() is specified in _\bc_\bm_\bd and is one |
| 25077 | of: |
| 25078 | |
| 25079 | IPC_STAT Gather information about the shared memory segment and place |
| 25080 | it in the structure pointed to by _\bb_\bu_\bf. |
| 25081 | |
| 25082 | IPC_SET Set the value of the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd, _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and |
| 25083 | _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be fields in the structure associated with _\bs_\bh_\bm_\bi_\bd. |
| 25084 | The values are taken from the corresponding fields in the |
| 25085 | structure pointed to by _\bb_\bu_\bf. This operation can only be |
| 25086 | executed by the superuser, or a process that has an effective |
| 25087 | user ID equal to either _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd in the |
| 25088 | data structure associated with the shared memory segment. |
| 25089 | |
| 25090 | IPC_RMID Mark the shared memory segment specified by _\bs_\bh_\bm_\bi_\bd for removal |
| 25091 | when it is no longer in use by any process. When it is |
| 25092 | removed, all data associated with it will be destroyed too. |
| 25093 | Only the superuser or a process with an effective UID equal to |
| 25094 | the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd values in the data structure |
| 25095 | associated with the queue can do this. |
| 25096 | |
| 25097 | The read and write permissions on a shared memory identifier are |
| 25098 | determined by the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be field in the same way as is done with |
| 25099 | files (see chmod(2)), but the effective UID can match either the |
| 25100 | _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd field or the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd field, and the effective GID can |
| 25101 | match either _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd or _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd. |
| 25102 | |
| 25103 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25104 | Upon successful completion, the value 0 is returned; otherwise the |
| 25105 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 25106 | error. |
| 25107 | |
| 25108 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25109 | s\bsh\bhm\bmc\bct\btl\bl() will fail if: |
| 25110 | |
| 25111 | [EPERM] _\bc_\bm_\bd is equal to IPC_SET or IPC_RMID and the caller is |
| 25112 | not the superuser, nor does the effective UID match |
| 25113 | either the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd or _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd fields of the |
| 25114 | data structure associated with the shared memory |
| 25115 | segment. |
| 25116 | |
| 25117 | An attempt is made to increase the value of _\bs_\bh_\bm_\b__\bq_\bb_\by_\bt_\be_\bs |
| 25118 | through IPC_SET but the caller is not the superuser. |
| 25119 | |
| 25120 | [EACCES] The command is IPC_STAT and the caller has no read |
| 25121 | permission for this shared memory segment. |
| 25122 | |
| 25123 | [EINVAL] _\bs_\bh_\bm_\bi_\bd is not a valid shared memory segment identifier. |
| 25124 | |
| 25125 | _\bc_\bm_\bd is not a valid command. |
| 25126 | |
| 25127 | [EFAULT] _\bb_\bu_\bf specifies an invalid address. |
| 25128 | |
| 25129 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25130 | shmat(2), shmget(2) |
| 25131 | |
| 25132 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 25133 | Segments which are marked for removal (but not yet removed since they are |
| 25134 | still in use) can be attached to by new callers using shmat(2). This is |
| 25135 | permitted as an extension beyond the standards. |
| 25136 | |
| 25137 | N\bNA\bAM\bME\bE |
| 25138 | s\bsh\bhm\bma\bat\bt, s\bsh\bhm\bmd\bdt\bt - map/unmap shared memory |
| 25139 | |
| 25140 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25141 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsh\bhm\bm.\b.h\bh>\b> |
| 25142 | |
| 25143 | _\bv_\bo_\bi_\bd _\b* |
| 25144 | s\bsh\bhm\bma\bat\bt(_\bi_\bn_\bt _\bs_\bh_\bm_\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bs_\bh_\bm_\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bs_\bh_\bm_\bf_\bl_\bg); |
| 25145 | |
| 25146 | _\bi_\bn_\bt |
| 25147 | s\bsh\bhm\bmd\bdt\bt(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bs_\bh_\bm_\ba_\bd_\bd_\br); |
| 25148 | |
| 25149 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25150 | s\bsh\bhm\bma\bat\bt() maps the shared memory segment associated with the shared memory |
| 25151 | identifier _\bs_\bh_\bm_\bi_\bd into the address space of the calling process. The |
| 25152 | address at which the segment is mapped is determined by the _\bs_\bh_\bm_\ba_\bd_\bd_\br |
| 25153 | parameter. If it is equal to 0, the system will pick an address itself. |
| 25154 | Otherwise, an attempt is made to map the shared memory segment at the |
| 25155 | address _\bs_\bh_\bm_\ba_\bd_\bd_\br specifies. If SHM_RND is set in _\bs_\bh_\bm_\bf_\bl_\bg, the system will |
| 25156 | round the address down to a multiple of SHMLBA bytes (SHMLBA is defined |
| 25157 | in <_\bs_\by_\bs_\b/_\bs_\bh_\bm_\b._\bh>). |
| 25158 | |
| 25159 | A shared memory segment can be mapped read-only by specifying the |
| 25160 | SHM_RDONLY flag in _\bs_\bh_\bm_\bf_\bl_\bg. |
| 25161 | |
| 25162 | s\bsh\bhm\bmd\bdt\bt() unmaps the shared memory segment that is currently mapped at |
| 25163 | _\bs_\bh_\bm_\ba_\bd_\bd_\br from the calling process' address space. _\bs_\bh_\bm_\ba_\bd_\bd_\br must be a value |
| 25164 | returned by a prior s\bsh\bhm\bma\bat\bt() call. A shared memory segment will remain |
| 25165 | existent until it is removed by a call to shmctl(2) with the IPC_RMID |
| 25166 | command. |
| 25167 | |
| 25168 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25169 | s\bsh\bhm\bma\bat\bt() returns the address at which the shared memory segment has been |
| 25170 | mapped into the calling process' address space when successful, s\bsh\bhm\bmd\bdt\bt() |
| 25171 | returns 0 on successful completion. Otherwise, a value of -1 is |
| 25172 | returned, and the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 25173 | |
| 25174 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25175 | s\bsh\bhm\bma\bat\bt() will fail if: |
| 25176 | |
| 25177 | [EACCES] The calling process has no permission to access this |
| 25178 | shared memory segment. |
| 25179 | |
| 25180 | [ENOMEM] There is not enough available data space for the |
| 25181 | calling process to map the shared memory segment. |
| 25182 | |
| 25183 | [EINVAL] _\bs_\bh_\bm_\bi_\bd is not a valid shared memory identifier. |
| 25184 | |
| 25185 | _\bs_\bh_\bm_\ba_\bd_\bd_\br specifies an illegal address. |
| 25186 | |
| 25187 | [EMFILE] The number of shared memory segments has reached the |
| 25188 | system-wide limit. |
| 25189 | |
| 25190 | s\bsh\bhm\bmd\bdt\bt() will fail if: |
| 25191 | |
| 25192 | [EINVAL] _\bs_\bh_\bm_\ba_\bd_\bd_\br is not the start address of a mapped shared |
| 25193 | memory segment. |
| 25194 | |
| 25195 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25196 | ipcrm(1), ipcs(1), mmap(2), shmctl(2), shmget(2) |
| 25197 | |
| 25198 | N\bNA\bAM\bME\bE |
| 25199 | s\bsh\bhm\bmg\bge\bet\bt - get shared memory area identifier |
| 25200 | |
| 25201 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25202 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsh\bhm\bm.\b.h\bh>\b> |
| 25203 | |
| 25204 | _\bi_\bn_\bt |
| 25205 | s\bsh\bhm\bmg\bge\bet\bt(_\bk_\be_\by_\b__\bt _\bk_\be_\by, _\bs_\bi_\bz_\be_\b__\bt _\bs_\bi_\bz_\be, _\bi_\bn_\bt _\bs_\bh_\bm_\bf_\bl_\bg); |
| 25206 | |
| 25207 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25208 | s\bsh\bhm\bmg\bge\bet\bt() returns the shared memory identifier associated with the key |
| 25209 | _\bk_\be_\by. |
| 25210 | |
| 25211 | A shared memory segment is created if either _\bk_\be_\by is equal to IPC_PRIVATE, |
| 25212 | or _\bk_\be_\by does not have a shared memory segment identifier associated with |
| 25213 | it, and the IPC_CREAT bit is set in _\bs_\bh_\bm_\bf_\bl_\bg. |
| 25214 | |
| 25215 | If a new shared memory segment is created, the data structure associated |
| 25216 | with it (the _\bs_\bh_\bm_\bi_\bd_\b__\bd_\bs structure, see shmctl(2)) is initialized as |
| 25217 | follows: |
| 25218 | |
| 25219 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd and _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd are set to the effective uid of the |
| 25220 | calling process. |
| 25221 | |
| 25222 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd are set to the effective gid of the |
| 25223 | calling process. |
| 25224 | |
| 25225 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be is set to the lower 9 bits of _\bs_\bh_\bm_\bf_\bl_\bg. |
| 25226 | |
| 25227 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bl_\bp_\bi_\bd, _\bs_\bh_\bm_\b__\bn_\ba_\bt_\bt_\bc_\bh, _\bs_\bh_\bm_\b__\ba_\bt_\bi_\bm_\be, and _\bs_\bh_\bm_\b__\bd_\bt_\bi_\bm_\be are set to 0. |
| 25228 | |
| 25229 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bc_\bt_\bi_\bm_\be is set to the current time. |
| 25230 | |
| 25231 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bs_\be_\bg_\bs_\bz is set to the value of _\bs_\bi_\bz_\be. |
| 25232 | |
| 25233 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25234 | Upon successful completion a positive shared memory segment identifier is |
| 25235 | returned. Otherwise, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
| 25236 | to indicate the error. |
| 25237 | |
| 25238 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25239 | [EACCES] A shared memory segment is already associated with _\bk_\be_\by |
| 25240 | and the caller has no permission to access it. |
| 25241 | |
| 25242 | [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _\bs_\bh_\bm_\bf_\bl_\bg, and a |
| 25243 | shared memory segment is already associated with _\bk_\be_\by. |
| 25244 | |
| 25245 | [EINVAL] A shared memory segment is already associated with _\bk_\be_\by |
| 25246 | and its _\bs_\bi_\bz_\be is less than the requested size. |
| 25247 | |
| 25248 | [ENOSPC] A new shared memory identifier could not be created |
| 25249 | because the system limit for the number of shared |
| 25250 | memory identifiers has been reached. |
| 25251 | |
| 25252 | [ENOENT] IPC_CREAT was not set in _\bs_\bh_\bm_\bf_\bl_\bg and no shared memory |
| 25253 | segment associated with _\bk_\be_\by was found. |
| 25254 | |
| 25255 | [ENOMEM] There is not enough memory left to create a shared |
| 25256 | memory segment of the requested size. |
| 25257 | |
| 25258 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25259 | ipcrm(1), ipcs(1), mmap(2), shmat(2), shmctl(2), ftok(3) |
| 25260 | |
| 25261 | N\bNA\bAM\bME\bE |
| 25262 | s\bsh\bhu\but\btd\bdo\bow\bwn\bn - disable sends or receives on a socket |
| 25263 | |
| 25264 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25265 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 25266 | |
| 25267 | _\bi_\bn_\bt |
| 25268 | s\bsh\bhu\but\btd\bdo\bow\bwn\bn(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bh_\bo_\bw); |
| 25269 | |
| 25270 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25271 | The s\bsh\bhu\but\btd\bdo\bow\bwn\bn() system call disables sends or receives on a socket. |
| 25272 | |
| 25273 | If the file descriptor _\bs is associated with a SOCK_STREAM socket, all or |
| 25274 | part of the full-duplex connection will be shut down. |
| 25275 | |
| 25276 | The _\bh_\bo_\bw argument specifies the type of shutdown. Possible values are: |
| 25277 | |
| 25278 | SHUT_RD Further receives will be disallowed. |
| 25279 | |
| 25280 | SHUT_WR Further sends will be disallowed. This may cause |
| 25281 | actions specific to the protocol family of the socket |
| 25282 | _\bs to happen. |
| 25283 | |
| 25284 | SHUT_RDWR Further sends and receives will be disallowed. |
| 25285 | |
| 25286 | The following protocol specific actions apply to the use of SHUT_WR based |
| 25287 | on the properties of the socket associated with the file descriptor _\bs: |
| 25288 | |
| 25289 | DOMAIN TYPE PROTOCOL RETURN VALUE AND ACTION |
| 25290 | |
| 25291 | |
| 25292 | AF_INET SOCK_DGRAM IPPROTO_UDP Return 0. ICMP messages |
| 25293 | will _\bn_\bo_\bt be generated. |
| 25294 | AF_INET SOCK_STREAM IPPROTO_TCP Return 0. Send queued |
| 25295 | data, wait for ACK, then |
| 25296 | send FIN. |
| 25297 | AF_INET6 SOCK_DGRAM IPPROTO_UDP Return 0. ICMP messages |
| 25298 | will _\bn_\bo_\bt be generated. |
| 25299 | AF_INET6 SOCK_STREAM IPPROTO_TCP Return 0. Send queued |
| 25300 | data, wait for ACK, then |
| 25301 | send FIN. |
| 25302 | |
| 25303 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25304 | Upon successful completion, the value 0 is returned; otherwise the |
| 25305 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 25306 | error. |
| 25307 | |
| 25308 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25309 | The s\bsh\bhu\but\btd\bdo\bow\bwn\bn() system call fails if: |
| 25310 | |
| 25311 | [EBADF] The _\bs argument is not a valid file descriptor. |
| 25312 | |
| 25313 | [EINVAL] The _\bh_\bo_\bw argument is invalid. |
| 25314 | |
| 25315 | [ENOTCONN] The _\bs argument specifies a SOCK_STREAM socket which is |
| 25316 | not connected. |
| 25317 | |
| 25318 | [ENOTSOCK] The _\bs argument does not refer to a socket. |
| 25319 | |
| 25320 | [EOPNOTSUPP] The socket associated with the file descriptor _\bs does |
| 25321 | not support this operation. |
| 25322 | |
| 25323 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25324 | connect(2), socket(2), inet(4), inet6(4) |
| 25325 | |
| 25326 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 25327 | The s\bsh\bhu\but\btd\bdo\bow\bwn\bn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 25328 | |
| 25329 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 25330 | The s\bsh\bhu\but\btd\bdo\bow\bwn\bn() system call first appeared in 4.1cBSD. The SHUT_RD, |
| 25331 | SHUT_WR, and SHUT_RDWR constants appeared in IEEE Std 1003.1g-2000 |
| 25332 | (``POSIX.1g''). |
| 25333 | |
| 25334 | B\bBU\bUG\bGS\bS |
| 25335 | The ICMP ``port unreachable'' message should be generated in response to |
| 25336 | datagrams received on a local port to which _\bs is bound after s\bsh\bhu\but\btd\bdo\bow\bwn\bn() |
| 25337 | is called. |
| 25338 | |
| 25339 | N\bNA\bAM\bME\bE |
| 25340 | s\bsi\big\bga\bac\bct\bti\bio\bon\bn - software signal facilities |
| 25341 | |
| 25342 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25343 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 25344 | |
| 25345 | struct sigaction { |
| 25346 | union { /* signal handler */ |
| 25347 | void (*__sa_handler)(int); |
| 25348 | void (*__sa_sigaction)(int, siginfo_t *, void *); |
| 25349 | } __sigaction_u; |
| 25350 | sigset_t sa_mask; /* signal mask to apply */ |
| 25351 | int sa_flags; /* see signal options below */ |
| 25352 | }; |
| 25353 | |
| 25354 | #\b#d\bde\bef\bfi\bin\bne\be s\bsa\ba_\b_h\bha\ban\bnd\bdl\ble\ber\br _\b__\b_s\bsi\big\bga\bac\bct\bti\bio\bon\bn_\b_u\bu.\b._\b__\b_s\bsa\ba_\b_h\bha\ban\bnd\bdl\ble\ber\br |
| 25355 | #\b#d\bde\bef\bfi\bin\bne\be s\bsa\ba_\b_s\bsi\big\bga\bac\bct\bti\bio\bon\bn _\b__\b_s\bsi\big\bga\bac\bct\bti\bio\bon\bn_\b_u\bu.\b._\b__\b_s\bsa\ba_\b_s\bsi\big\bga\bac\bct\bti\bio\bon\bn |
| 25356 | |
| 25357 | _\bi_\bn_\bt |
| 25358 | s\bsi\big\bga\bac\bct\bti\bio\bon\bn(_\bi_\bn_\bt _\bs_\bi_\bg, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn _\b*_\ba_\bc_\bt, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn _\b*_\bo_\ba_\bc_\bt); |
| 25359 | |
| 25360 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25361 | The system defines a set of signals that may be delivered to a process. |
| 25362 | Signal delivery resembles the occurrence of a hardware interrupt: the |
| 25363 | signal is normally blocked from further occurrence, the current process |
| 25364 | context is saved, and a new one is built. A process may specify a |
| 25365 | _\bh_\ba_\bn_\bd_\bl_\be_\br to which a signal is delivered, or specify that a signal is to be |
| 25366 | _\bi_\bg_\bn_\bo_\br_\be_\bd. A process may also specify that a default action is to be taken |
| 25367 | by the system when a signal occurs. A signal may also be _\bb_\bl_\bo_\bc_\bk_\be_\bd, in |
| 25368 | which case its delivery is postponed until it is _\bu_\bn_\bb_\bl_\bo_\bc_\bk_\be_\bd. The action |
| 25369 | to be taken on delivery is determined at the time of delivery. Normally, |
| 25370 | signal handlers execute on the current stack of the process. This may be |
| 25371 | changed, on a per-handler basis, so that signals are taken on a special |
| 25372 | _\bs_\bi_\bg_\bn_\ba_\bl _\bs_\bt_\ba_\bc_\bk. |
| 25373 | |
| 25374 | Signal routines normally execute with the signal that caused their |
| 25375 | invocation _\bb_\bl_\bo_\bc_\bk_\be_\bd, but other signals may yet occur. A global _\bs_\bi_\bg_\bn_\ba_\bl |
| 25376 | _\bm_\ba_\bs_\bk defines the set of signals currently blocked from delivery to a |
| 25377 | process. The signal mask for a process is initialized from that of its |
| 25378 | parent (normally empty). It may be changed with a sigprocmask(2) call, |
| 25379 | or when a signal is delivered to the process. |
| 25380 | |
| 25381 | When a signal condition arises for a process, the signal is added to a |
| 25382 | set of signals pending for the process. If the signal is not currently |
| 25383 | _\bb_\bl_\bo_\bc_\bk_\be_\bd by the process then it is delivered to the process. Signals may |
| 25384 | be delivered any time a process enters the operating system (e.g., during |
| 25385 | a system call, page fault or trap, or clock interrupt). If multiple |
| 25386 | signals are ready to be delivered at the same time, any signals that |
| 25387 | could be caused by traps are delivered first. Additional signals may be |
| 25388 | processed at the same time, with each appearing to interrupt the handlers |
| 25389 | for the previous signals before their first instructions. The set of |
| 25390 | pending signals is returned by the sigpending(2) function. When a caught |
| 25391 | signal is delivered, the current state of the process is saved, a new |
| 25392 | signal mask is calculated (as described below), and the signal handler is |
| 25393 | invoked. The call to the handler is arranged so that if the signal |
| 25394 | handling routine returns normally the process will resume execution in |
| 25395 | the context from before the signal's delivery. If the process wishes to |
| 25396 | resume in a different context, then it must arrange to restore the |
| 25397 | previous context itself. |
| 25398 | |
| 25399 | When a signal is delivered to a process a new signal mask is installed |
| 25400 | for the duration of the process' signal handler (or until a |
| 25401 | sigprocmask(2) call is made). This mask is formed by taking the union of |
| 25402 | the current signal mask set, the signal to be delivered, and the signal |
| 25403 | mask _\bs_\ba_\b__\bm_\ba_\bs_\bk associated with the handler to be invoked, but always |
| 25404 | excluding SIGKILL and SIGSTOP. |
| 25405 | |
| 25406 | s\bsi\big\bga\bac\bct\bti\bio\bon\bn() assigns an action for a signal specified by _\bs_\bi_\bg. If _\ba_\bc_\bt is |
| 25407 | non-zero, it specifies an action (SIG_DFL, SIG_IGN, or a handler routine) |
| 25408 | and mask to be used when delivering the specified signal. If _\bo_\ba_\bc_\bt is |
| 25409 | non-zero, the previous handling information for the signal is returned to |
| 25410 | the user. |
| 25411 | |
| 25412 | Once a signal handler is installed, it normally remains installed until |
| 25413 | another s\bsi\big\bga\bac\bct\bti\bio\bon\bn() call is made, or an execve(2) is performed. The |
| 25414 | value of _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br (or, if the SA_SIGINFO flag is set, the value of |
| 25415 | _\bs_\ba_\b__\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn instead) indicates what action should be performed when a |
| 25416 | signal arrives. A signal-specific default action may be reset by setting |
| 25417 | _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br to SIG_DFL. Alternately, if the SA_RESETHAND flag is set the |
| 25418 | default action will be reinstated when the signal is first posted. The |
| 25419 | defaults are process termination, possibly with core dump; no action; |
| 25420 | stopping the process; or continuing the process. See the signal list |
| 25421 | below for each signal's default action. If _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br is SIG_DFL, the |
| 25422 | default action for the signal is to discard the signal, and if a signal |
| 25423 | is pending, the pending signal is discarded even if the signal is masked. |
| 25424 | If _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br is set to SIG_IGN, current and pending instances of the |
| 25425 | signal are ignored and discarded. If _\bs_\bi_\bg is SIGCHLD and _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br is |
| 25426 | set to SIG_IGN, the SA_NOCLDWAIT flag (described below) is implied. |
| 25427 | |
| 25428 | Options may be specified by setting _\bs_\ba_\b__\bf_\bl_\ba_\bg_\bs. The meaning of the various |
| 25429 | bits is as follows: |
| 25430 | |
| 25431 | SA_NOCLDSTOP If this bit is set when installing a catching |
| 25432 | function for the SIGCHLD signal, the SIGCHLD signal |
| 25433 | will be generated only when a child process exits, |
| 25434 | not when a child process stops. |
| 25435 | |
| 25436 | SA_NOCLDWAIT If this bit is set when calling s\bsi\big\bga\bac\bct\bti\bio\bon\bn() for the |
| 25437 | SIGCHLD signal, the system will not create zombie |
| 25438 | processes when children of the calling process |
| 25439 | exit, though existing zombies will remain. If the |
| 25440 | calling process subsequently issues a waitpid(2) |
| 25441 | (or equivalent) and there are no previously |
| 25442 | existing zombie child processes that match the |
| 25443 | waitpid(2) criteria, it blocks until all of the |
| 25444 | calling process's child processes that would match |
| 25445 | terminate, and then returns a value of -1 with |
| 25446 | _\be_\br_\br_\bn_\bo set to ECHILD. |
| 25447 | |
| 25448 | SA_ONSTACK If this bit is set, the system will deliver the |
| 25449 | signal to the process on a _\bs_\bi_\bg_\bn_\ba_\bl _\bs_\bt_\ba_\bc_\bk, specified |
| 25450 | with sigaltstack(2). |
| 25451 | |
| 25452 | SA_NODEFER If this bit is set, further occurrences of the |
| 25453 | delivered signal are not masked during the |
| 25454 | execution of the handler. |
| 25455 | |
| 25456 | SA_RESETHAND If this bit is set, the handler is reset back to |
| 25457 | SIG_DFL at the moment the signal is delivered. |
| 25458 | |
| 25459 | SA_SIGINFO If this bit is set, the 2nd argument of the handler |
| 25460 | is set to be a pointer to a _\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b__\bt structure as |
| 25461 | described in <_\bs_\by_\bs_\b/_\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b._\bh>. It provides much |
| 25462 | more information about the causes and attributes of |
| 25463 | the signal that is being delivered. |
| 25464 | |
| 25465 | SA_RESTART If a signal is caught during the system calls |
| 25466 | listed below, the call may be forced to terminate |
| 25467 | with the error EINTR, the call may return with a |
| 25468 | data transfer shorter than requested, or the call |
| 25469 | may be restarted. Restarting of pending calls is |
| 25470 | requested by setting the SA_RESTART bit in |
| 25471 | _\bs_\ba_\b__\bf_\bl_\ba_\bg_\bs. The affected system calls include |
| 25472 | read(2), write(2), sendto(2), recvfrom(2), |
| 25473 | sendmsg(2) and recvmsg(2) on a communications |
| 25474 | channel or a slow device (such as a terminal, but |
| 25475 | not a regular file) and during a wait(2) or |
| 25476 | ioctl(2). However, calls that have already |
| 25477 | committed are not restarted, but instead return a |
| 25478 | partial success (for example, a short read count). |
| 25479 | |
| 25480 | After a fork(2) or vfork(2), all signals, the signal mask, the signal |
| 25481 | stack, and the restart/interrupt flags are inherited by the child. |
| 25482 | |
| 25483 | execve(2) reinstates the default action for all signals which were caught |
| 25484 | and resets all signals to be caught on the user stack. Ignored signals |
| 25485 | remain ignored; the signal mask remains the same; signals that restart |
| 25486 | pending system calls continue to do so. |
| 25487 | |
| 25488 | The following is a list of all signals with names as in the include file |
| 25489 | <_\bs_\bi_\bg_\bn_\ba_\bl_\b._\bh>: |
| 25490 | |
| 25491 | N\bNa\bam\bme\be D\bDe\bef\bfa\bau\bul\blt\bt A\bAc\bct\bti\bio\bon\bn D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn |
| 25492 | SIGHUP terminate process terminal line hangup |
| 25493 | SIGINT terminate process interrupt program |
| 25494 | SIGQUIT create core image quit program |
| 25495 | SIGILL create core image illegal instruction |
| 25496 | SIGTRAP create core image trace trap |
| 25497 | SIGABRT create core image abort(3) call (formerly SIGIOT) |
| 25498 | SIGEMT create core image emulate instruction executed |
| 25499 | SIGFPE create core image floating-point exception |
| 25500 | SIGKILL terminate process kill program (cannot be caught or |
| 25501 | ignored) |
| 25502 | SIGBUS create core image bus error |
| 25503 | SIGSEGV create core image segmentation violation |
| 25504 | SIGSYS create core image system call given invalid argument |
| 25505 | SIGPIPE terminate process write on a pipe with no reader |
| 25506 | SIGALRM terminate process real-time timer expired |
| 25507 | SIGTERM terminate process software termination signal |
| 25508 | SIGURG discard signal urgent condition present on socket |
| 25509 | SIGSTOP stop process stop (cannot be caught or ignored) |
| 25510 | SIGTSTP stop process stop signal generated from keyboard |
| 25511 | SIGCONT discard signal continue after stop |
| 25512 | SIGCHLD discard signal child status has changed |
| 25513 | SIGTTIN stop process background read attempted from control |
| 25514 | terminal |
| 25515 | SIGTTOU stop process background write attempted to control |
| 25516 | terminal |
| 25517 | SIGIO discard signal I/O is possible on a descriptor (see |
| 25518 | fcntl(2)) |
| 25519 | SIGXCPU terminate process CPU time limit exceeded (see |
| 25520 | setrlimit(2)) |
| 25521 | SIGXFSZ terminate process file size limit exceeded (see |
| 25522 | setrlimit(2)) |
| 25523 | SIGVTALRM terminate process virtual time alarm (see setitimer(2)) |
| 25524 | SIGPROF terminate process profiling timer alarm (see |
| 25525 | setitimer(2)) |
| 25526 | SIGWINCH discard signal window size change |
| 25527 | SIGINFO discard signal status request from keyboard |
| 25528 | SIGUSR1 terminate process user defined signal 1 |
| 25529 | SIGUSR2 terminate process user defined signal 2 |
| 25530 | SIGTHR discard signal thread AST |
| 25531 | |
| 25532 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25533 | Upon successful completion, the value 0 is returned; otherwise the |
| 25534 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 25535 | error. |
| 25536 | |
| 25537 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS |
| 25538 | The handler routine can be declared: |
| 25539 | |
| 25540 | void |
| 25541 | handler(int sig) |
| 25542 | |
| 25543 | If the SA_SIGINFO option is enabled, the canonical way to declare it is: |
| 25544 | |
| 25545 | void |
| 25546 | handler(int sig, siginfo_t *sip, struct sigcontext *scp) |
| 25547 | |
| 25548 | Here _\bs_\bi_\bg is the signal number, into which the hardware faults and traps |
| 25549 | are mapped. If the SA_SIGINFO option is set, _\bs_\bi_\bp is a pointer to a |
| 25550 | siginfo_t as described in <_\bs_\by_\bs_\b/_\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b._\bh>. If SA_SIGINFO is not set, |
| 25551 | this pointer will be NULL instead. The function specified in |
| 25552 | _\bs_\ba_\b__\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn will be called instead of the function specified by |
| 25553 | _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br (Note that in some implementations these are in fact the |
| 25554 | same). _\bs_\bc_\bp is a pointer to the _\bs_\bi_\bg_\bc_\bo_\bn_\bt_\be_\bx_\bt structure (defined in |
| 25555 | <_\bs_\bi_\bg_\bn_\ba_\bl_\b._\bh>), used to restore the context from before the signal. |
| 25556 | |
| 25557 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25558 | s\bsi\big\bga\bac\bct\bti\bio\bon\bn() will fail and no new signal handler will be installed if one |
| 25559 | of the following occurs: |
| 25560 | |
| 25561 | [EFAULT] Either _\ba_\bc_\bt or _\bo_\ba_\bc_\bt points to memory that is not a |
| 25562 | valid part of the process address space. |
| 25563 | |
| 25564 | [EINVAL] _\bs_\bi_\bg is not a valid signal number. |
| 25565 | |
| 25566 | [EINVAL] An attempt is made to ignore or supply a handler for |
| 25567 | SIGKILL or SIGSTOP. |
| 25568 | |
| 25569 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25570 | kill(1), kill(2), ptrace(2), sigaltstack(2), sigprocmask(2), |
| 25571 | sigsuspend(2), wait(2), setjmp(3), sigblock(3), sigpause(3), |
| 25572 | sigsetops(3), sigvec(3), tty(4) |
| 25573 | |
| 25574 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 25575 | The s\bsi\big\bga\bac\bct\bti\bio\bon\bn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 25576 | |
| 25577 | The SA_ONSTACK flag and the SIGPROF, SIGSYS, SIGTRAP, SIGVTALRM, SIGXCPU, |
| 25578 | and SIGXFSZ signals conform to the X/Open System Interfaces option of |
| 25579 | that standard. The standard marks SIGPROF as obsolescent. The signals |
| 25580 | SIGEMT, SIGINFO, SIGIO, and SIGWINCH are Berkeley extensions. These |
| 25581 | signals are available on most BSD-derived systems. The SIGTHR signal is |
| 25582 | specific to OpenBSD and is part of the implementation of thread |
| 25583 | cancellation; _\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn and other signal interfaces may reject attempts |
| 25584 | to use or alter the handling of SIGTHR. |
| 25585 | |
| 25586 | The following functions are either reentrant or not interruptible by |
| 25587 | signals and are async-signal-safe. Therefore applications may invoke |
| 25588 | them, without restriction, from signal-catching functions: |
| 25589 | |
| 25590 | Standard Interfaces: |
| 25591 | |
| 25592 | _\b_e\bex\bxi\bit\bt(), _\b_E\bEx\bxi\bit\bt(), a\bab\bbo\bor\brt\bt(), a\bac\bcc\bce\bep\bpt\bt(), a\bac\bcc\bce\bes\bss\bs(), a\bal\bla\bar\brm\bm(), b\bbi\bin\bnd\bd(), |
| 25593 | c\bcf\bfg\bge\bet\bti\bis\bsp\bpe\bee\bed\bd(), c\bcf\bfg\bge\bet\bto\bos\bsp\bpe\bee\bed\bd(), c\bcf\bfs\bse\bet\bti\bis\bsp\bpe\bee\bed\bd(), c\bcf\bfs\bse\bet\bto\bos\bsp\bpe\bee\bed\bd(), c\bch\bhd\bdi\bir\br(), |
| 25594 | c\bch\bhm\bmo\bod\bd(), c\bch\bho\bow\bwn\bn(), c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), c\bcl\blo\bos\bse\be(), c\bco\bon\bnn\bne\bec\bct\bt(), c\bcr\bre\bea\bat\bt(), d\bdu\bup\bp(), |
| 25595 | d\bdu\bup\bp2\b2(), e\bex\bxe\bec\bcl\bl(), e\bex\bxe\bec\bcl\ble\be(), e\bex\bxe\bec\bcv\bv(), e\bex\bxe\bec\bcv\bve\be(), f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt(), f\bfc\bch\bhd\bdi\bir\br(), |
| 25596 | f\bfc\bch\bhm\bmo\bod\bd(), f\bfc\bch\bhm\bmo\bod\bda\bat\bt(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), f\bfc\bcn\bnt\btl\bl(), f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc(), f\bfo\bor\brk\bk(), |
| 25597 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf(), f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), f\bfs\bsy\byn\bnc\bc(), f\bft\btr\bru\bun\bnc\bca\bat\bte\be(), f\bfu\but\bti\bim\bme\ben\bns\bs(), |
| 25598 | f\bfu\but\bti\bim\bme\bes\bs(), g\bge\bet\bte\beg\bgi\bid\bd(), g\bge\bet\bte\beu\bui\bid\bd(), g\bge\bet\btg\bgi\bid\bd(), g\bge\bet\btg\bgr\bro\bou\bup\bps\bs(), g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be(), |
| 25599 | g\bge\bet\btp\bpg\bgr\brp\bp(), g\bge\bet\btp\bpi\bid\bd(), g\bge\bet\btp\bpp\bpi\bid\bd(), g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be(), g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), g\bge\bet\btu\bui\bid\bd(), |
| 25600 | k\bki\bil\bll\bl(), l\bli\bin\bnk\bk(), l\bli\bin\bnk\bka\bat\bt(), l\bli\bis\bst\bte\ben\bn(), l\bls\bse\bee\bek\bk(), l\bls\bst\bta\bat\bt(), m\bmk\bkd\bdi\bir\br(), m\bmk\bkd\bdi\bir\bra\bat\bt(), |
| 25601 | m\bmk\bkf\bfi\bif\bfo\bo(), m\bmk\bkf\bfi\bif\bfo\boa\bat\bt(), m\bmk\bkn\bno\bod\bd(), m\bmk\bkn\bno\bod\bda\bat\bt(), o\bop\bpe\ben\bn(), o\bop\bpe\ben\bna\bat\bt(), p\bpa\bat\bth\bhc\bco\bon\bnf\bf(), |
| 25602 | p\bpa\bau\bus\bse\be(), p\bpi\bip\bpe\be(), p\bpo\bol\bll\bl(), p\bps\bse\bel\ble\bec\bct\bt(), p\bpt\bth\bhr\bre\bea\bad\bd_\b_s\bsi\big\bgm\bma\bas\bsk\bk(), r\bra\bai\bis\bse\be(), r\bre\bea\bad\bd(), |
| 25603 | r\bre\bea\bad\bdl\bli\bin\bnk\bk(), r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt(), r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), r\bre\bec\bcv\bvm\bms\bsg\bg(), r\bre\ben\bna\bam\bme\be(), |
| 25604 | r\bre\ben\bna\bam\bme\bea\bat\bt(), r\brm\bmd\bdi\bir\br(), s\bse\bel\ble\bec\bct\bt(), s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdm\bms\bsg\bg(), s\bse\ben\bnd\bdt\bto\bo(), s\bse\bet\btg\bgi\bid\bd(), |
| 25605 | s\bse\bet\btp\bpg\bgi\bid\bd(), s\bse\bet\bts\bsi\bid\bd(), s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), s\bse\bet\btu\bui\bid\bd(), s\bsh\bhu\but\btd\bdo\bow\bwn\bn(), s\bsi\big\bga\bac\bct\bti\bio\bon\bn(), |
| 25606 | s\bsi\big\bga\bad\bdd\bds\bse\bet\bt(), s\bsi\big\bgd\bde\bel\bls\bse\bet\bt(), s\bsi\big\bge\bem\bmp\bpt\bty\bys\bse\bet\bt(), s\bsi\big\bgf\bfi\bil\bll\bls\bse\bet\bt(), s\bsi\big\bgi\bis\bsm\bme\bem\bmb\bbe\ber\br(), |
| 25607 | s\bsi\big\bgn\bna\bal\bl(), s\bsi\big\bgp\bpa\bau\bus\bse\be(), s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg(), s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk(), s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd(), s\bsl\ble\bee\bep\bp(), |
| 25608 | s\bso\boc\bck\bka\bat\btm\bma\bar\brk\bk(), s\bso\boc\bck\bke\bet\bt(), s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br(), s\bst\bta\bat\bt(), s\bst\btr\brc\bca\bat\bt(), s\bst\btr\brc\bcp\bpy\by(), |
| 25609 | s\bst\btr\brn\bnc\bca\bat\bt(), s\bst\btr\brn\bnc\bcp\bpy\by(), s\bsy\bym\bml\bli\bin\bnk\bk(), s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt(), s\bsy\bys\bsc\bco\bon\bnf\bf(), t\btc\bcd\bdr\bra\bai\bin\bn(), |
| 25610 | t\btc\bcf\bfl\blo\bow\bw(), t\btc\bcf\bfl\blu\bus\bsh\bh(), t\btc\bcg\bge\bet\bta\bat\btt\btr\br(), t\btc\bcg\bge\bet\btp\bpg\bgr\brp\bp(), t\btc\bcs\bse\ben\bnd\bdb\bbr\bre\bea\bak\bk(), |
| 25611 | t\btc\bcs\bse\bet\bta\bat\btt\btr\br(), t\btc\bcs\bse\bet\btp\bpg\bgr\brp\bp(), t\bti\bim\bme\be(), t\bti\bim\bme\bes\bs(), u\bum\bma\bas\bsk\bk(), u\bun\bna\bam\bme\be(), u\bun\bnl\bli\bin\bnk\bk(), |
| 25612 | u\bun\bnl\bli\bin\bnk\bka\bat\bt(), u\but\bti\bim\bme\be(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), u\but\bti\bim\bme\bes\bs(), w\bwa\bai\bit\bt(), w\bwa\bai\bit\btp\bpi\bid\bd(), w\bwr\bri\bit\bte\be(), |
| 25613 | and perhaps some others. |
| 25614 | |
| 25615 | Extension Interfaces: |
| 25616 | |
| 25617 | a\bac\bcc\bce\bep\bpt\bt4\b4(), c\bch\bhf\bfl\bla\bag\bgs\bs(), d\bdu\bup\bp3\b3(), f\bfc\bch\bhf\bfl\bla\bag\bgs\bs(), g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by(), g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(), |
| 25618 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(), p\bpi\bip\bpe\be2\b2(), p\bpp\bpo\bol\bll\bl(), s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg(), s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(), s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(), |
| 25619 | s\bst\btr\brl\blc\bca\bat\bt(), s\bst\btr\brl\blc\bcp\bpy\by(), w\bwa\bai\bit\bt3\b3(), w\bwa\bai\bit\bt4\b4(). |
| 25620 | |
| 25621 | In addition, access and updates to _\be_\br_\br_\bn_\bo are guaranteed to be safe. Most |
| 25622 | functions not in the above lists are considered to be unsafe with respect |
| 25623 | to signals. That is to say, the behaviour of such functions when called |
| 25624 | from a signal handler is undefined. In general though, signal handlers |
| 25625 | should do little more than set a flag, ideally of type volatile |
| 25626 | sig_atomic_t; most other actions are not safe. |
| 25627 | |
| 25628 | Additionally, it is advised that signal handlers guard against |
| 25629 | modification of the external symbol _\be_\br_\br_\bn_\bo by the above functions, saving |
| 25630 | it at entry and restoring it on return, thus: |
| 25631 | |
| 25632 | void |
| 25633 | handler(int sig) |
| 25634 | { |
| 25635 | int save_errno = errno; |
| 25636 | |
| 25637 | ... |
| 25638 | errno = save_errno; |
| 25639 | } |
| 25640 | |
| 25641 | The functions below are async-signal-safe in OpenBSD except when used |
| 25642 | with floating-point arguments or directives, but are probably unsafe on |
| 25643 | other systems: |
| 25644 | |
| 25645 | d\bdp\bpr\bri\bin\bnt\btf\bf() Safe. |
| 25646 | v\bvd\bdp\bpr\bri\bin\bnt\btf\bf() Safe. |
| 25647 | s\bsn\bnp\bpr\bri\bin\bnt\btf\bf() Safe. |
| 25648 | v\bvs\bsn\bnp\bpr\bri\bin\bnt\btf\bf() Safe. |
| 25649 | s\bsy\bys\bsl\blo\bog\bg_\b_r\br() Safe if the _\bs_\by_\bs_\bl_\bo_\bg_\b__\bd_\ba_\bt_\ba struct is initialized as a |
| 25650 | local variable. |
| 25651 | |
| 25652 | N\bNA\bAM\bME\bE |
| 25653 | s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk - set and/or get signal stack context |
| 25654 | |
| 25655 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25656 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 25657 | |
| 25658 | typedef struct sigaltstack { |
| 25659 | void *ss_sp; |
| 25660 | size_t ss_size; |
| 25661 | int ss_flags; |
| 25662 | } stack_t; |
| 25663 | _\bi_\bn_\bt |
| 25664 | s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\ba_\bc_\bk_\b__\bt _\b*_\bs_\bs, _\bs_\bt_\ba_\bc_\bk_\b__\bt _\b*_\bo_\bs_\bs); |
| 25665 | |
| 25666 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25667 | s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk() allows users to define an alternate stack on which signals |
| 25668 | delivered to this thread are to be processed. If _\bs_\bs is non-zero and |
| 25669 | SS_DISABLE is set in _\bs_\bs_\b__\bf_\bl_\ba_\bg_\bs, the signal stack will be disabled. A |
| 25670 | disabled stack will cause all signals to be taken on the regular user |
| 25671 | stack. Trying to disable an active stack will cause k\bkq\bqu\bue\beu\bue\be to return -1 |
| 25672 | with _\be_\br_\br_\bn_\bo set to EPERM. |
| 25673 | |
| 25674 | Otherwise, _\bs_\bs_\b__\bs_\bp specifies a pointer to a space to be used as the signal |
| 25675 | stack and _\bs_\bs_\b__\bs_\bi_\bz_\be specifies the size of that space. When a signal's |
| 25676 | action indicates its handler should execute on the signal stack |
| 25677 | (specified with a sigaction(2) call), the system checks to see if the |
| 25678 | thread is currently executing on that stack. If the thread is not |
| 25679 | currently executing on the signal stack, the system arranges a switch to |
| 25680 | the signal stack for the duration of the signal handler's execution. |
| 25681 | |
| 25682 | If _\bo_\bs_\bs is non-zero, the current signal stack state is returned. The |
| 25683 | _\bs_\bs_\b__\bf_\bl_\ba_\bg_\bs field will contain the value SS_ONSTACK if the thread is |
| 25684 | currently on a signal stack and SS_DISABLE if the signal stack is |
| 25685 | currently disabled. |
| 25686 | |
| 25687 | N\bNO\bOT\bTE\bES\bS |
| 25688 | The value SIGSTKSZ is defined to be the number of bytes/chars that would |
| 25689 | be used to cover the usual case when allocating an alternate stack area. |
| 25690 | The following code fragment is typically used to allocate an alternate |
| 25691 | stack. |
| 25692 | |
| 25693 | if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) |
| 25694 | /* error return */ |
| 25695 | sigstk.ss_size = SIGSTKSZ; |
| 25696 | sigstk.ss_flags = 0; |
| 25697 | if (sigaltstack(&sigstk, 0) == -1) |
| 25698 | perror("sigaltstack"); |
| 25699 | |
| 25700 | An alternative approach is provided for programs with signal handlers |
| 25701 | that require a specific amount of stack space other than the default |
| 25702 | size. The value MINSIGSTKSZ is defined to be the number of bytes/chars |
| 25703 | that is required by the operating system to implement the alternate stack |
| 25704 | feature. In computing an alternate stack size, programs should add |
| 25705 | MINSIGSTKSZ to their stack requirements to allow for the operating system |
| 25706 | overhead. |
| 25707 | |
| 25708 | Signal stacks are automatically adjusted for the direction of stack |
| 25709 | growth and alignment requirements. Signal stacks may or may not be |
| 25710 | protected by the hardware and are not ``grown'' automatically as is done |
| 25711 | for the normal stack. If the stack overflows and this space is not |
| 25712 | protected unpredictable results may occur. |
| 25713 | |
| 25714 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25715 | Upon successful completion, the value 0 is returned; otherwise the |
| 25716 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 25717 | error. |
| 25718 | |
| 25719 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25720 | s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk() will fail and the signal stack context will remain |
| 25721 | unchanged if one of the following occurs. |
| 25722 | |
| 25723 | [EFAULT] Either _\bs_\bs or _\bo_\bs_\bs points to memory that is not a valid part of |
| 25724 | the process address space. |
| 25725 | |
| 25726 | [EINVAL] The _\bs_\bs_\b__\bf_\bl_\ba_\bg_\bs member pointed to by the _\bs_\bs argument contains |
| 25727 | flags other than SS_DISABLE. |
| 25728 | |
| 25729 | [ENOMEM] Size of alternate stack area is less than or equal to |
| 25730 | MINSIGSTKSZ. |
| 25731 | |
| 25732 | [EPERM] An attempt was made to disable an active stack. |
| 25733 | |
| 25734 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25735 | sigaction(2), setjmp(3) |
| 25736 | |
| 25737 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 25738 | The k\bkq\bqu\bue\beu\bue\be function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 25739 | |
| 25740 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 25741 | The predecessor to s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk, the s\bsi\big\bgs\bst\bta\bac\bck\bk() system call, appeared in |
| 25742 | 4.2BSD. |
| 25743 | |
| 25744 | N\bNA\bAM\bME\bE |
| 25745 | s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg - get pending signals |
| 25746 | |
| 25747 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25748 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 25749 | |
| 25750 | _\bi_\bn_\bt |
| 25751 | s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg(_\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bs_\be_\bt); |
| 25752 | |
| 25753 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25754 | The s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg function returns a mask of the signals pending for |
| 25755 | delivery to the calling process in the location indicated by _\bs_\be_\bt. |
| 25756 | Signals may be pending because they are currently masked, or transiently |
| 25757 | before delivery (although the latter case is not normally detectable). |
| 25758 | |
| 25759 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25760 | Upon successful completion, the value 0 is returned; otherwise the |
| 25761 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 25762 | error. |
| 25763 | |
| 25764 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25765 | The s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg function does not currently detect any errors. |
| 25766 | |
| 25767 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25768 | sigaction(2), sigprocmask(2), sigsetops(3) |
| 25769 | |
| 25770 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 25771 | The s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg function is defined by IEEE Std 1003.1-2008 (``POSIX.1''). |
| 25772 | |
| 25773 | N\bNA\bAM\bME\bE |
| 25774 | s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk - manipulate current signal mask |
| 25775 | |
| 25776 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25777 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 25778 | |
| 25779 | _\bi_\bn_\bt |
| 25780 | s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk(_\bi_\bn_\bt _\bh_\bo_\bw, _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bs_\be_\bt, _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bo_\bs_\be_\bt); |
| 25781 | |
| 25782 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25783 | The s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk() function examines and/or changes the current signal |
| 25784 | mask (those signals that are blocked from delivery). Signals are blocked |
| 25785 | if they are members of the current signal mask set. |
| 25786 | |
| 25787 | If _\bs_\be_\bt is not null, the action of s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk() depends on the value of |
| 25788 | the parameter _\bh_\bo_\bw, which can be one of the following values: |
| 25789 | |
| 25790 | SIG_BLOCK The new mask is the union of the current mask and the |
| 25791 | specified _\bs_\be_\bt. |
| 25792 | |
| 25793 | SIG_UNBLOCK The new mask is the intersection of the current mask and the |
| 25794 | complement of the specified _\bs_\be_\bt. |
| 25795 | |
| 25796 | SIG_SETMASK The current mask is replaced by the specified _\bs_\be_\bt. |
| 25797 | |
| 25798 | If _\bo_\bs_\be_\bt is not null, it is set to the previous value of the signal mask. |
| 25799 | When _\bs_\be_\bt is null, the value of _\bh_\bo_\bw is insignificant and the mask remains |
| 25800 | unchanged, providing a way to examine the signal mask without |
| 25801 | modification. |
| 25802 | |
| 25803 | The system quietly disallows SIGKILL or SIGSTOP to be blocked. |
| 25804 | |
| 25805 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25806 | Upon successful completion, the value 0 is returned; otherwise the |
| 25807 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 25808 | error. |
| 25809 | |
| 25810 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25811 | The s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk() call will fail and the signal mask will be unchanged if |
| 25812 | one of the following occurs: |
| 25813 | |
| 25814 | [EINVAL] _\bh_\bo_\bw has a value other than those listed here. |
| 25815 | |
| 25816 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25817 | kill(2), sigaction(2), sigsuspend(2), sigsetops(3) |
| 25818 | |
| 25819 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 25820 | The s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk() function call is expected to conform to IEEE Std |
| 25821 | 1003.1-2008 (``POSIX.1''). |
| 25822 | |
| 25823 | N\bNA\bAM\bME\bE |
| 25824 | s\bsi\big\bgr\bre\bet\btu\bur\brn\bn - return from signal |
| 25825 | |
| 25826 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25827 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 25828 | |
| 25829 | _\bi_\bn_\bt |
| 25830 | s\bsi\big\bgr\bre\bet\btu\bur\brn\bn(_\bs_\bt_\br_\bu_\bc_\bt _\bs_\bi_\bg_\bc_\bo_\bn_\bt_\be_\bx_\bt _\b*_\bs_\bc_\bp); |
| 25831 | |
| 25832 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25833 | s\bsi\big\bgr\bre\bet\btu\bur\brn\bn() allows users to atomically unmask, switch stacks, and return |
| 25834 | from a signal context. The processes signal mask and stack status are |
| 25835 | restored from the context. The system call does not return; the users |
| 25836 | stack pointer, frame pointer, argument pointer, and processor status |
| 25837 | longword are restored from the context. Execution resumes at the |
| 25838 | specified pc. This system call is used by the trampoline code and |
| 25839 | longjmp(3) when returning from a signal to the previously executing |
| 25840 | program. |
| 25841 | |
| 25842 | Note that sigcontext contains machine dependent information. |
| 25843 | |
| 25844 | N\bNO\bOT\bTE\bES\bS |
| 25845 | This system call is not available in 4.2BSD hence it should not be used |
| 25846 | if backward compatibility is needed. |
| 25847 | |
| 25848 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25849 | If successful, the system call does not return. Otherwise, a value of -1 |
| 25850 | is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 25851 | |
| 25852 | E\bER\bRR\bRO\bOR\bRS\bS |
| 25853 | s\bsi\big\bgr\bre\bet\btu\bur\brn\bn() will fail and the process context will remain unchanged if |
| 25854 | one of the following occurs. |
| 25855 | |
| 25856 | [EFAULT] _\bs_\bc_\bp points to memory that is not a valid part of the |
| 25857 | process address space. |
| 25858 | |
| 25859 | [EINVAL] The process status longword is invalid or would |
| 25860 | improperly raise the privilege level of the process. |
| 25861 | |
| 25862 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25863 | sigaction(2), setjmp(3) |
| 25864 | |
| 25865 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 25866 | The s\bsi\big\bgr\bre\bet\btu\bur\brn\bn() function call appeared in 4.3BSD. |
| 25867 | |
| 25868 | N\bNA\bAM\bME\bE |
| 25869 | s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd - atomically change the signal mask and wait for interrupt |
| 25870 | |
| 25871 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25872 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
| 25873 | |
| 25874 | _\bi_\bn_\bt |
| 25875 | s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd(_\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bs_\bi_\bg_\bm_\ba_\bs_\bk); |
| 25876 | |
| 25877 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25878 | s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd() temporarily changes the blocked signal mask to the set to |
| 25879 | which _\bs_\bi_\bg_\bm_\ba_\bs_\bk points, and then waits for a signal to arrive; on return |
| 25880 | the previous set of masked signals is restored. The signal mask set is |
| 25881 | usually empty to indicate that all signals are to be unblocked for the |
| 25882 | duration of the call. |
| 25883 | |
| 25884 | In normal usage, a signal is blocked using sigprocmask(2) to begin a |
| 25885 | critical section, variables modified on the occurrence of the signal are |
| 25886 | examined to determine that there is no work to be done, and the process |
| 25887 | pauses awaiting work by using s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd() with the previous mask |
| 25888 | returned by sigprocmask(2). |
| 25889 | |
| 25890 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25891 | The s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd() function always terminates by being interrupted, |
| 25892 | returning -1 with _\be_\br_\br_\bn_\bo set to EINTR. |
| 25893 | |
| 25894 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 25895 | sigaction(2), sigprocmask(2), sigsetops(3) |
| 25896 | |
| 25897 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 25898 | The s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd function call conforms to IEEE Std 1003.1-2008 |
| 25899 | (``POSIX.1''). |
| 25900 | |
| 25901 | N\bNA\bAM\bME\bE |
| 25902 | s\bso\boc\bck\bke\bet\bt - create an endpoint for communication |
| 25903 | |
| 25904 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 25905 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 25906 | |
| 25907 | _\bi_\bn_\bt |
| 25908 | s\bso\boc\bck\bke\bet\bt(_\bi_\bn_\bt _\bd_\bo_\bm_\ba_\bi_\bn, _\bi_\bn_\bt _\bt_\by_\bp_\be, _\bi_\bn_\bt _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl); |
| 25909 | |
| 25910 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 25911 | s\bso\boc\bck\bke\bet\bt() creates an endpoint for communication and returns a descriptor. |
| 25912 | |
| 25913 | The _\bd_\bo_\bm_\ba_\bi_\bn parameter specifies a communications domain within which |
| 25914 | communication will take place; this selects the protocol family which |
| 25915 | should be used. These families are defined in the include file |
| 25916 | <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>. The currently understood formats are: |
| 25917 | |
| 25918 | AF_UNIX UNIX internal protocols |
| 25919 | AF_INET ARPA Internet protocols |
| 25920 | AF_INET6 IPv6 (Internet Protocol version 6) protocols |
| 25921 | |
| 25922 | The socket has the indicated _\bt_\by_\bp_\be, which specifies the semantics of |
| 25923 | communication. Currently defined types are: |
| 25924 | |
| 25925 | SOCK_STREAM |
| 25926 | SOCK_DGRAM |
| 25927 | SOCK_RAW |
| 25928 | SOCK_SEQPACKET |
| 25929 | |
| 25930 | A SOCK_STREAM type provides sequenced, reliable, two-way connection based |
| 25931 | byte streams. An out-of-band data transmission mechanism may be |
| 25932 | supported. A SOCK_DGRAM socket supports datagrams (connectionless, |
| 25933 | unreliable messages of a fixed (typically small) maximum length). A |
| 25934 | SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way |
| 25935 | connection-based data transmission path for datagrams of fixed maximum |
| 25936 | length; a consumer may be required to read an entire packet with each |
| 25937 | read system call. This facility is protocol specific, and presently |
| 25938 | implemented only for AF_UNIX. SOCK_RAW sockets provide access to |
| 25939 | internal network protocols and interfaces, and are available only to the |
| 25940 | superuser. |
| 25941 | |
| 25942 | Any combination of the following flags may additionally be used in the |
| 25943 | _\bt_\by_\bp_\be argument: |
| 25944 | |
| 25945 | SOCK_CLOEXEC Set close-on-exec flag on the new descriptor. |
| 25946 | SOCK_NONBLOCK Set non-blocking I/O mode on the new socket. |
| 25947 | |
| 25948 | The _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl specifies a particular protocol to be used with the socket. |
| 25949 | Normally only a single protocol exists to support a particular socket |
| 25950 | type within a given protocol family. However, it is possible that many |
| 25951 | protocols may exist, in which case a particular protocol must be |
| 25952 | specified in this manner. The protocol number to use is particular to |
| 25953 | the ``communication domain'' in which communication is to take place; see |
| 25954 | protocols(5). A value of 0 for _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl will let the system select an |
| 25955 | appropriate protocol for the requested socket type. |
| 25956 | |
| 25957 | Sockets of type SOCK_STREAM are full-duplex byte streams. A stream |
| 25958 | socket must be in a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd state before any data may be sent or |
| 25959 | received on it. A connection to another socket is created with a |
| 25960 | connect(2) call. Once connected, data may be transferred using read(2) |
| 25961 | and write(2) calls or some variant of the send(2) and recv(2) calls. |
| 25962 | When a session has been completed a close(2) may be performed. Out-of- |
| 25963 | band data may also be transmitted as described in send(2) and received as |
| 25964 | described in recv(2). |
| 25965 | |
| 25966 | The communications protocols used to implement a SOCK_STREAM ensure that |
| 25967 | data is not lost or duplicated. If a piece of data for which the peer |
| 25968 | protocol has buffer space cannot be successfully transmitted within a |
| 25969 | reasonable length of time, then the connection is considered broken and |
| 25970 | calls will indicate an error with -1 returns and with ETIMEDOUT as the |
| 25971 | specific code in the global variable _\be_\br_\br_\bn_\bo. The protocols optionally |
| 25972 | keep sockets ``warm'' by forcing transmissions roughly every minute in |
| 25973 | the absence of other activity. An error is then indicated if no response |
| 25974 | can be elicited on an otherwise idle connection for an extended period |
| 25975 | (e.g., 5 minutes). A SIGPIPE signal is raised if a process sends on a |
| 25976 | broken stream; this causes naive processes, which do not handle the |
| 25977 | signal, to exit. |
| 25978 | |
| 25979 | SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM |
| 25980 | sockets. The only difference is that read(2) calls will return only the |
| 25981 | amount of data requested, and any remaining in the arriving packet will |
| 25982 | be discarded. |
| 25983 | |
| 25984 | SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to |
| 25985 | correspondents named in send(2) calls. Datagrams are generally received |
| 25986 | with recvfrom(2), which returns the next datagram with its return |
| 25987 | address. |
| 25988 | |
| 25989 | An fcntl(2) call can be used to specify a process group to receive a |
| 25990 | SIGURG signal when the out-of-band data arrives. It may also enable non- |
| 25991 | blocking I/O and asynchronous notification of I/O events via SIGIO. |
| 25992 | |
| 25993 | The operation of sockets is controlled by socket level _\bo_\bp_\bt_\bi_\bo_\bn_\bs. These |
| 25994 | options are defined in the file <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>. setsockopt(2) and |
| 25995 | getsockopt(2) are used to set and get options, respectively. |
| 25996 | |
| 25997 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 25998 | A -1 is returned if an error occurs, otherwise the return value is a |
| 25999 | descriptor referencing the socket. |
| 26000 | |
| 26001 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26002 | The s\bso\boc\bck\bke\bet\bt() call fails if: |
| 26003 | |
| 26004 | [EAFNOSUPPORT] The specified address family is not supported on this |
| 26005 | machine. |
| 26006 | |
| 26007 | [EPROTONOSUPPORT] The protocol type or the specified protocol is not |
| 26008 | supported within this domain. |
| 26009 | |
| 26010 | [EPROTOTYPE] The combination of the specified protocol and type is |
| 26011 | not supported. |
| 26012 | |
| 26013 | [EMFILE] The per-process descriptor table is full. |
| 26014 | |
| 26015 | [ENFILE] The system file table is full. |
| 26016 | |
| 26017 | [ENOBUFS] Insufficient resources were available in the system to |
| 26018 | perform the operation. |
| 26019 | |
| 26020 | [EACCES] Permission to create a socket of the specified type |
| 26021 | and/or protocol is denied. |
| 26022 | |
| 26023 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26024 | accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), ioctl(2), |
| 26025 | listen(2), poll(2), read(2), recv(2), select(2), send(2), setsockopt(2), |
| 26026 | shutdown(2), socketpair(2), write(2), getprotoent(3), inet(4), inet6(4), |
| 26027 | netintro(4), unix(4) |
| 26028 | |
| 26029 | _\bA_\bn _\bI_\bn_\bt_\br_\bo_\bd_\bu_\bc_\bt_\bo_\br_\by _\b4_\b._\b3 _\bB_\bS_\bD _\bI_\bn_\bt_\be_\br_\bp_\br_\bo_\bc_\be_\bs_\bs _\bC_\bo_\bm_\bm_\bu_\bn_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\bT_\bu_\bt_\bo_\br_\bi_\ba_\bl, reprinted in |
| 26030 | UNIX Programmer's Supplementary Documents Volume 1. |
| 26031 | |
| 26032 | _\bB_\bS_\bD _\bI_\bn_\bt_\be_\br_\bp_\br_\bo_\bc_\be_\bs_\bs _\bC_\bo_\bm_\bm_\bu_\bn_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\bT_\bu_\bt_\bo_\br_\bi_\ba_\bl, reprinted in UNIX Programmer's |
| 26033 | Supplementary Documents Volume 1. |
| 26034 | |
| 26035 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 26036 | The s\bso\boc\bck\bke\bet\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 26037 | |
| 26038 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26039 | The s\bso\boc\bck\bke\bet\bt() system call first appeared in 4.1cBSD. |
| 26040 | |
| 26041 | N\bNA\bAM\bME\bE |
| 26042 | s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br - create a pair of connected sockets |
| 26043 | |
| 26044 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26045 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
| 26046 | |
| 26047 | _\bi_\bn_\bt |
| 26048 | s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br(_\bi_\bn_\bt _\bd, _\bi_\bn_\bt _\bt_\by_\bp_\be, _\bi_\bn_\bt _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl, _\bi_\bn_\bt _\bs_\bv_\b[_\b2_\b]); |
| 26049 | |
| 26050 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26051 | The s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br() call creates an unnamed pair of connected sockets in the |
| 26052 | specified domain _\bd, of the specified _\bt_\by_\bp_\be, and using the optionally |
| 26053 | specified _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl. The descriptors used in referencing the new sockets |
| 26054 | are returned in _\bs_\bv[0] and _\bs_\bv[1]. The two sockets are indistinguishable. |
| 26055 | |
| 26056 | Any combination of the following flags may additionally be used in the |
| 26057 | _\bt_\by_\bp_\be argument: |
| 26058 | |
| 26059 | SOCK_CLOEXEC Set close-on-exec flag on both the new descriptors. |
| 26060 | SOCK_NONBLOCK Set non-blocking I/O mode on both the new sockets. |
| 26061 | |
| 26062 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26063 | Upon successful completion, the value 0 is returned; otherwise the |
| 26064 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 26065 | error. |
| 26066 | |
| 26067 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26068 | The call succeeds unless: |
| 26069 | |
| 26070 | [EAFNOSUPPORT] The specified address family is not supported on this |
| 26071 | machine. |
| 26072 | |
| 26073 | [EPROTONOSUPPORT] The specified protocol is not supported on this |
| 26074 | machine. |
| 26075 | |
| 26076 | [EOPNOTSUPP] The specified protocol does not support creation of |
| 26077 | socket pairs. |
| 26078 | |
| 26079 | [EPROTOTYPE] The combination of the specified protocol and type is |
| 26080 | not supported. |
| 26081 | |
| 26082 | [EMFILE] The per-process descriptor table is full. |
| 26083 | |
| 26084 | [ENFILE] The system file table is full. |
| 26085 | |
| 26086 | [ENOBUFS] Insufficient resources were available in the system to |
| 26087 | perform the operation. |
| 26088 | |
| 26089 | [EFAULT] The address _\bs_\bv does not specify a valid part of the |
| 26090 | process address space. |
| 26091 | |
| 26092 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26093 | pipe(2), read(2), socket(2), write(2) |
| 26094 | |
| 26095 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 26096 | The s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 26097 | |
| 26098 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26099 | The s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br() function call appeared in 4.2BSD. |
| 26100 | |
| 26101 | B\bBU\bUG\bGS\bS |
| 26102 | This call is currently implemented only for the LOCAL domain. Many |
| 26103 | operating systems only accept a _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl of PF_UNSPEC, so that should be |
| 26104 | used instead of PF_LOCAL for maximal portability. |
| 26105 | |
| 26106 | N\bNA\bAM\bME\bE |
| 26107 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
| 26108 | |
| 26109 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26110 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 26111 | |
| 26112 | _\bi_\bn_\bt |
| 26113 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 26114 | |
| 26115 | _\bi_\bn_\bt |
| 26116 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 26117 | |
| 26118 | _\bi_\bn_\bt |
| 26119 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
| 26120 | |
| 26121 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 26122 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 26123 | |
| 26124 | _\bi_\bn_\bt |
| 26125 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 26126 | |
| 26127 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26128 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
| 26129 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
| 26130 | required, but all directories listed in the path name leading to the file |
| 26131 | must be searchable. |
| 26132 | |
| 26133 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
| 26134 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
| 26135 | itself, not the file the link references. |
| 26136 | |
| 26137 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
| 26138 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 26139 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
| 26140 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 26141 | instead of the current working directory. |
| 26142 | |
| 26143 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 26144 | in the _\bf_\bd parameter, the current working directory is used and the |
| 26145 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
| 26146 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
| 26147 | |
| 26148 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 26149 | values: |
| 26150 | |
| 26151 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
| 26152 | of the symbolic link is returned. |
| 26153 | |
| 26154 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
| 26155 | known by the file descriptor _\bf_\bd. |
| 26156 | |
| 26157 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
| 26158 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
| 26159 | concerning the file. |
| 26160 | |
| 26161 | struct stat { |
| 26162 | dev_t st_dev; /* inode's device */ |
| 26163 | ino_t st_ino; /* inode's number */ |
| 26164 | mode_t st_mode; /* inode protection mode */ |
| 26165 | nlink_t st_nlink; /* number of hard links */ |
| 26166 | uid_t st_uid; /* user ID of the file's owner */ |
| 26167 | gid_t st_gid; /* group ID of the file's group */ |
| 26168 | dev_t st_rdev; /* device type */ |
| 26169 | struct timespec st_atim; /* time of last access */ |
| 26170 | struct timespec st_mtim; /* time of last data modification */ |
| 26171 | struct timespec st_ctim; /* time of last file status change */ |
| 26172 | off_t st_size; /* file size, in bytes */ |
| 26173 | blkcnt_t st_blocks; /* blocks allocated for file */ |
| 26174 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
| 26175 | u_int32_t st_flags; /* user defined flags for file */ |
| 26176 | u_int32_t st_gen; /* file generation number */ |
| 26177 | }; |
| 26178 | |
| 26179 | The time-related fields of struct stat are represented in struct timespec |
| 26180 | format, which has nanosecond precision. However, the actual precision is |
| 26181 | generally limited by the file system holding the file. The fields are as |
| 26182 | follows: |
| 26183 | |
| 26184 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
| 26185 | system object was created and updated by the utimes(2) and |
| 26186 | read(2) system calls. |
| 26187 | |
| 26188 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
| 26189 | truncate(2), utimes(2), and write(2) system calls. For |
| 26190 | directories, changed by any system call that alters which |
| 26191 | files are in the directory, such as the unlink(2), rename(2), |
| 26192 | mkdir(2), and symlink(2) system calls. |
| 26193 | |
| 26194 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
| 26195 | modification). Changed by the chmod(2), chown(2), link(2), |
| 26196 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
| 26197 | |
| 26198 | In addition, all the time fields are set to the current time when a file |
| 26199 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
| 26200 | open(2), and symlink(2) system calls. |
| 26201 | |
| 26202 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
| 26203 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
| 26204 | respective struct timespec member. Deprecated macros are also provided |
| 26205 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
| 26206 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
| 26207 | |
| 26208 | The size-related fields of the struct stat are as follows: |
| 26209 | |
| 26210 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
| 26211 | |
| 26212 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
| 26213 | 512-byte units. As short symbolic links are stored in the |
| 26214 | inode, this number may be zero. |
| 26215 | |
| 26216 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
| 26217 | |
| 26218 | #define S_IFMT 0170000 /* type of file mask */ |
| 26219 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
| 26220 | #define S_IFCHR 0020000 /* character special */ |
| 26221 | #define S_IFDIR 0040000 /* directory */ |
| 26222 | #define S_IFBLK 0060000 /* block special */ |
| 26223 | #define S_IFREG 0100000 /* regular */ |
| 26224 | #define S_IFLNK 0120000 /* symbolic link */ |
| 26225 | #define S_IFSOCK 0140000 /* socket */ |
| 26226 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
| 26227 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
| 26228 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
| 26229 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
| 26230 | #define S_IRUSR 0000400 /* R for owner */ |
| 26231 | #define S_IWUSR 0000200 /* W for owner */ |
| 26232 | #define S_IXUSR 0000100 /* X for owner */ |
| 26233 | #define S_IRWXG 0000070 /* RWX mask for group */ |
| 26234 | #define S_IRGRP 0000040 /* R for group */ |
| 26235 | #define S_IWGRP 0000020 /* W for group */ |
| 26236 | #define S_IXGRP 0000010 /* X for group */ |
| 26237 | #define S_IRWXO 0000007 /* RWX mask for other */ |
| 26238 | #define S_IROTH 0000004 /* R for other */ |
| 26239 | #define S_IWOTH 0000002 /* W for other */ |
| 26240 | #define S_IXOTH 0000001 /* X for other */ |
| 26241 | |
| 26242 | The following macros test a file's type. If the file is of that type, a |
| 26243 | non-zero value is returned; otherwise, 0 is returned. |
| 26244 | |
| 26245 | S_ISBLK(st_mode m) /* block special */ |
| 26246 | S_ISCHR(st_mode m) /* char special */ |
| 26247 | S_ISDIR(st_mode m) /* directory */ |
| 26248 | S_ISFIFO(st_mode m) /* fifo */ |
| 26249 | S_ISLNK(st_mode m) /* symbolic link */ |
| 26250 | S_ISREG(st_mode m) /* regular file */ |
| 26251 | S_ISSOCK(st_mode m) /* socket */ |
| 26252 | |
| 26253 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
| 26254 | |
| 26255 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26256 | Upon successful completion, the value 0 is returned; otherwise the |
| 26257 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 26258 | error. |
| 26259 | |
| 26260 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26261 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 26262 | |
| 26263 | [ENOTDIR] A component of the path prefix is not a directory. |
| 26264 | |
| 26265 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 26266 | characters, or an entire pathname (including the |
| 26267 | terminating NUL) exceeded PATH_MAX bytes. |
| 26268 | |
| 26269 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
| 26270 | empty path. |
| 26271 | |
| 26272 | [EACCES] Search permission is denied for a component of the |
| 26273 | path prefix. |
| 26274 | |
| 26275 | [ELOOP] Too many symbolic links were encountered in |
| 26276 | translating the pathname. |
| 26277 | |
| 26278 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
| 26279 | |
| 26280 | [EIO] An I/O error occurred while reading from or writing to |
| 26281 | the file system. |
| 26282 | |
| 26283 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
| 26284 | |
| 26285 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 26286 | AT_SYMLINK_NOFOLLOW. |
| 26287 | |
| 26288 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 26289 | argument is neither AT_FDCWD nor a valid file |
| 26290 | descriptor. |
| 26291 | |
| 26292 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 26293 | argument is a valid file descriptor but it does not |
| 26294 | reference a directory. |
| 26295 | |
| 26296 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 26297 | permission is denied for the directory which the _\bf_\bd |
| 26298 | file descriptor references. |
| 26299 | |
| 26300 | f\bfs\bst\bta\bat\bt() will fail if: |
| 26301 | |
| 26302 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 26303 | |
| 26304 | [EFAULT] _\bs_\bb points to an invalid address. |
| 26305 | |
| 26306 | [EIO] An I/O error occurred while reading from the file |
| 26307 | system. |
| 26308 | |
| 26309 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26310 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
| 26311 | |
| 26312 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 26313 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
| 26314 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
| 26315 | |
| 26316 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
| 26317 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 26318 | |
| 26319 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26320 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
| 26321 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
| 26322 | in Version 7 AT&T UNIX. |
| 26323 | |
| 26324 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
| 26325 | appeared in OpenBSD 5.0. |
| 26326 | |
| 26327 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 26328 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
| 26329 | |
| 26330 | Certain programs written when the timestamps were just of type time_t |
| 26331 | assumed that the members were consecutive (and could therefore be treated |
| 26332 | as an array and have their address passed directly to utime(3)). The |
| 26333 | transition to timestamps of type struct timespec broke them irrevocably. |
| 26334 | |
| 26335 | B\bBU\bUG\bGS\bS |
| 26336 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
| 26337 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
| 26338 | the time fields. |
| 26339 | |
| 26340 | N\bNA\bAM\bME\bE |
| 26341 | s\bst\bta\bat\btf\bfs\bs, f\bfs\bst\bta\bat\btf\bfs\bs - get file system statistics |
| 26342 | |
| 26343 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26344 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 26345 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
| 26346 | |
| 26347 | _\bi_\bn_\bt |
| 26348 | s\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
| 26349 | |
| 26350 | _\bi_\bn_\bt |
| 26351 | f\bfs\bst\bta\bat\btf\bfs\bs(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
| 26352 | |
| 26353 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26354 | s\bst\bta\bat\btf\bfs\bs() returns information about a mounted file system. _\bp_\ba_\bt_\bh is the |
| 26355 | path name of any file within the mounted file system. _\bb_\bu_\bf is a pointer |
| 26356 | to a s\bst\bta\bat\btf\bfs\bs structure defined as follows: |
| 26357 | |
| 26358 | typedef struct { int32_t val[2]; } fsid_t; |
| 26359 | |
| 26360 | #define MFSNAMELEN 16 /* length of fs type name, including nul */ |
| 26361 | #define MNAMELEN 90 /* length of buffer for returned name */ |
| 26362 | |
| 26363 | struct statfs { |
| 26364 | u_int32_t f_flags; /* copy of mount flags */ |
| 26365 | u_int32_t f_bsize; /* file system block size */ |
| 26366 | u_int32_t f_iosize; /* optimal transfer block size */ |
| 26367 | |
| 26368 | /* unit is f_bsize */ |
| 26369 | u_int64_t f_blocks; /* total data blocks in file system */ |
| 26370 | u_int64_t f_bfree; /* free blocks in fs */ |
| 26371 | int64_t f_bavail; /* free blocks avail to non-superuser */ |
| 26372 | |
| 26373 | u_int64_t f_files; /* total file nodes in file system */ |
| 26374 | u_int64_t f_ffree; /* free file nodes in fs */ |
| 26375 | int64_t f_favail; /* free file nodes avail to non-root */ |
| 26376 | |
| 26377 | u_int64_t f_syncwrites; /* count of sync writes since mount */ |
| 26378 | u_int64_t f_syncreads; /* count of sync reads since mount */ |
| 26379 | u_int64_t f_asyncwrites; /* count of async writes since mount */ |
| 26380 | u_int64_t f_asyncreads; /* count of async reads since mount */ |
| 26381 | |
| 26382 | fsid_t f_fsid; /* file system id */ |
| 26383 | u_int32_t f_namemax; /* maximum filename length */ |
| 26384 | uid_t f_owner; /* user that mounted the file system */ |
| 26385 | u_int64_t f_ctime; /* last mount [-u] time */ |
| 26386 | |
| 26387 | char f_fstypename[MFSNAMELEN]; /* fs type name */ |
| 26388 | char f_mntonname[MNAMELEN]; /* directory on which mounted */ |
| 26389 | char f_mntfromname[MNAMELEN]; /* mounted file system */ |
| 26390 | char f_mntfromspec[MNAMELEN]; /* special for mount request */ |
| 26391 | union mount_info mount_info; /* per-filesystem mount options */ |
| 26392 | }; |
| 26393 | |
| 26394 | f\bfs\bst\bta\bat\btf\bfs\bs() returns the same information about an open file referenced by |
| 26395 | descriptor _\bf_\bd. |
| 26396 | |
| 26397 | Note that _\bf_\b__\bf_\bs_\bi_\bd will be empty unless the user is the superuser. |
| 26398 | |
| 26399 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26400 | Upon successful completion, the value 0 is returned; otherwise the |
| 26401 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 26402 | error. |
| 26403 | |
| 26404 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26405 | s\bst\bta\bat\btf\bfs\bs() fails if one or more of the following are true: |
| 26406 | |
| 26407 | [ENOTDIR] A component of the path prefix of _\bp_\ba_\bt_\bh is not a |
| 26408 | directory. |
| 26409 | |
| 26410 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 26411 | characters, or an entire pathname (including the |
| 26412 | terminating NUL) exceeded PATH_MAX bytes. |
| 26413 | |
| 26414 | [ENOENT] The file referred to by _\bp_\ba_\bt_\bh does not exist. |
| 26415 | |
| 26416 | [EACCES] Search permission is denied for a component of the |
| 26417 | path prefix of _\bp_\ba_\bt_\bh. |
| 26418 | |
| 26419 | [ELOOP] Too many symbolic links were encountered in |
| 26420 | translating _\bp_\ba_\bt_\bh. |
| 26421 | |
| 26422 | [EFAULT] _\bb_\bu_\bf or _\bp_\ba_\bt_\bh points to an invalid address. |
| 26423 | |
| 26424 | [EIO] An I/O error occurred while reading from or writing to |
| 26425 | the file system. |
| 26426 | |
| 26427 | f\bfs\bst\bta\bat\btf\bfs\bs() fails if one or more of the following are true: |
| 26428 | |
| 26429 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
| 26430 | |
| 26431 | [EFAULT] _\bb_\bu_\bf points to an invalid address. |
| 26432 | |
| 26433 | [EIO] An I/O error occurred while reading from or writing to |
| 26434 | the file system. |
| 26435 | |
| 26436 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26437 | df(1), getfsstat(2), mount(2), stat(2) |
| 26438 | |
| 26439 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26440 | The s\bst\bta\bat\btf\bfs\bs() function first appeared in 4.4BSD. |
| 26441 | |
| 26442 | N\bNA\bAM\bME\bE |
| 26443 | s\bsw\bwa\bap\bpc\bct\btl\bl - modify swap configuration |
| 26444 | |
| 26445 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26446 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 26447 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsw\bwa\bap\bp.\b.h\bh>\b> |
| 26448 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 26449 | |
| 26450 | _\bi_\bn_\bt |
| 26451 | s\bsw\bwa\bap\bpc\bct\btl\bl(_\bi_\bn_\bt _\bc_\bm_\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\br_\bg, _\bi_\bn_\bt _\bm_\bi_\bs_\bc); |
| 26452 | |
| 26453 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26454 | The s\bsw\bwa\bap\bpc\bct\btl\bl() function is used to add and delete swap devices, and modify |
| 26455 | their configuration. |
| 26456 | |
| 26457 | The _\bc_\bm_\bd parameter specifies the operation to be performed. The _\ba_\br_\bg and |
| 26458 | _\bm_\bi_\bs_\bc parameters have different meanings, depending on the _\bc_\bm_\bd parameter. |
| 26459 | |
| 26460 | If _\bc_\bm_\bd is SWAP_NSWAP, the current number of swap devices in the |
| 26461 | system is returned. The _\ba_\br_\bg and _\bm_\bi_\bs_\bc parameters are ignored. |
| 26462 | |
| 26463 | If _\bc_\bm_\bd is SWAP_STATS, the current statistics for swap devices are |
| 26464 | returned in the _\ba_\br_\bg parameter. No more than _\bm_\bi_\bs_\bc swap devices are |
| 26465 | returned. The _\ba_\br_\bg parameter should point to an array of at least |
| 26466 | _\bm_\bi_\bs_\bc struct swapent structures: |
| 26467 | |
| 26468 | struct swapent { |
| 26469 | dev_t se_dev; /* device id */ |
| 26470 | int se_flags; /* entry flags */ |
| 26471 | int se_nblks; /* total blocks */ |
| 26472 | int se_inuse; /* blocks in use */ |
| 26473 | int se_priority; /* priority */ |
| 26474 | char se_path[PATH_MAX]; /* path to entry */ |
| 26475 | }; |
| 26476 | |
| 26477 | The flags are defined as |
| 26478 | |
| 26479 | SWF_INUSE in use: we have swapped here |
| 26480 | SWF_ENABLE enabled: we can swap here |
| 26481 | SWF_BUSY busy: I/O happening here |
| 26482 | SWF_FAKE fake: still being built |
| 26483 | |
| 26484 | All but SWAP_NSWAP and SWAP_STATS require superuser privileges. |
| 26485 | |
| 26486 | If _\bc_\bm_\bd is SWAP_ON, the _\ba_\br_\bg parameter is used as a pathname of a |
| 26487 | file to enable swapping to. The _\bm_\bi_\bs_\bc parameter is used to set the |
| 26488 | priority of this swap device. |
| 26489 | |
| 26490 | If _\bc_\bm_\bd is SWAP_OFF, the _\ba_\br_\bg parameter is used as the pathname of a |
| 26491 | file to disable swapping from. The _\bm_\bi_\bs_\bc parameter is ignored. |
| 26492 | |
| 26493 | If _\bc_\bm_\bd is SWAP_CTL, the _\ba_\br_\bg and _\bm_\bi_\bs_\bc parameters have the same |
| 26494 | function as for the SWAP_ON case, except that they change the |
| 26495 | priority of a currently enabled swap device. |
| 26496 | |
| 26497 | When swapping is enabled on a block device, the first portion of the disk |
| 26498 | is left unused to prevent any disklabel present from being overwritten. |
| 26499 | This space is allocated from the swap device when the SWAP_ON command is |
| 26500 | used. |
| 26501 | |
| 26502 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26503 | If the _\bc_\bm_\bd parameter is SWAP_NSWAP or SWAP_STATS, s\bsw\bwa\bap\bpc\bct\btl\bl() returns the |
| 26504 | number of swap devices, if successful. The SWAP_NSWAP command is always |
| 26505 | successful. Otherwise it returns 0 on success and -1 on failure, setting |
| 26506 | the global variable _\be_\br_\br_\bn_\bo to indicate the error. |
| 26507 | |
| 26508 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26509 | s\bsw\bwa\bap\bpc\bct\btl\bl() succeeds unless: |
| 26510 | |
| 26511 | [ENOTDIR] A component of the path prefix is not a directory. |
| 26512 | |
| 26513 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 26514 | characters, or an entire pathname (including the |
| 26515 | terminating NUL) exceeded PATH_MAX bytes. |
| 26516 | |
| 26517 | [ENOENT] The named device does not exist. For the SWAP_CTL |
| 26518 | command, the named device is not currently enabled for |
| 26519 | swapping. |
| 26520 | |
| 26521 | [EACCES] Search permission is denied for a component of the |
| 26522 | path prefix. |
| 26523 | |
| 26524 | [ELOOP] Too many symbolic links were encountered in |
| 26525 | translating the pathname. |
| 26526 | |
| 26527 | [EPERM] The caller is not the superuser. |
| 26528 | |
| 26529 | [EBUSY] The device specified by _\ba_\br_\bg has already been made |
| 26530 | available for swapping. |
| 26531 | |
| 26532 | [EINVAL] The device configured by _\ba_\br_\bg has no associated size, |
| 26533 | or the _\bc_\bm_\bd was unknown. |
| 26534 | |
| 26535 | [ENXIO] The major device number of _\ba_\br_\bg is out of range (this |
| 26536 | indicates no device driver exists for the associated |
| 26537 | hardware). |
| 26538 | |
| 26539 | [EIO] An I/O error occurred while opening the swap device. |
| 26540 | |
| 26541 | [EFAULT] _\ba_\br_\bg points outside the process' allocated address |
| 26542 | space. |
| 26543 | |
| 26544 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26545 | config(8), swapctl(8) |
| 26546 | |
| 26547 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26548 | The s\bsw\bwa\bap\bpc\bct\btl\bl() function call appeared in NetBSD 1.3. The _\bs_\be_\b__\bp_\ba_\bt_\bh member |
| 26549 | was added to _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bw_\ba_\bp_\be_\bn_\bt in NetBSD 1.4, when the header file was also |
| 26550 | moved from <_\bv_\bm_\b/_\bv_\bm_\b__\bs_\bw_\ba_\bp_\b._\bh>. |
| 26551 | |
| 26552 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
| 26553 | The current swap system was designed and implemented by Matthew Green |
| 26554 | <_\bm_\br_\bg_\b@_\be_\bt_\be_\br_\bn_\ba_\b._\bc_\bo_\bm_\b._\ba_\bu>, with help from Paul Kranenburg <_\bp_\bk_\b@_\bN_\be_\bt_\bB_\bS_\bD_\b._\bO_\bR_\bG> and |
| 26555 | Leo Weppelman <_\bl_\be_\bo_\b@_\bN_\be_\bt_\bB_\bS_\bD_\b._\bO_\bR_\bG>, and insights from Jason R. Thorpe |
| 26556 | <_\bt_\bh_\bo_\br_\bp_\be_\bj_\b@_\bN_\be_\bt_\bB_\bS_\bD_\b._\bO_\bR_\bG>. |
| 26557 | |
| 26558 | N\bNA\bAM\bME\bE |
| 26559 | s\bsy\bym\bml\bli\bin\bnk\bk, s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt - make symbolic link to a file |
| 26560 | |
| 26561 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26562 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 26563 | |
| 26564 | _\bi_\bn_\bt |
| 26565 | s\bsy\bym\bml\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
| 26566 | |
| 26567 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 26568 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 26569 | |
| 26570 | _\bi_\bn_\bt |
| 26571 | s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
| 26572 | |
| 26573 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26574 | A symbolic link _\bn_\ba_\bm_\be_\b2 is created to _\bn_\ba_\bm_\be_\b1 (_\bn_\ba_\bm_\be_\b2 is the name of the file |
| 26575 | created, _\bn_\ba_\bm_\be_\b1 is the string used in creating the symbolic link). Either |
| 26576 | name may be an arbitrary path name; the files need not be on the same |
| 26577 | file system, and the file specified by _\bn_\ba_\bm_\be_\b1 need not exist at all. |
| 26578 | |
| 26579 | The s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() function is equivalent to s\bsy\bym\bml\bli\bin\bnk\bk() except that where |
| 26580 | _\bn_\ba_\bm_\be_\b2 specifies a relative path, the newly created symbolic link is |
| 26581 | created relative to the directory associated with file descriptor _\bf_\bd |
| 26582 | instead of the current working directory. |
| 26583 | |
| 26584 | If s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in |
| 26585 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used and |
| 26586 | the behavior is identical to a call to s\bsy\bym\bml\bli\bin\bnk\bk(). |
| 26587 | |
| 26588 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26589 | Upon successful completion, the value 0 is returned; otherwise the |
| 26590 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 26591 | error. |
| 26592 | |
| 26593 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26594 | The symbolic link succeeds unless: |
| 26595 | |
| 26596 | [ENOTDIR] A component of the _\bn_\ba_\bm_\be_\b2 prefix is not a directory. |
| 26597 | |
| 26598 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 26599 | characters, or an entire pathname (including the |
| 26600 | terminating NUL) exceeded PATH_MAX bytes. |
| 26601 | |
| 26602 | [ENOENT] The named file does not exist. |
| 26603 | |
| 26604 | [EACCES] A component of the _\bn_\ba_\bm_\be_\b2 path prefix denies search |
| 26605 | permission. |
| 26606 | |
| 26607 | [ELOOP] Too many symbolic links were encountered in |
| 26608 | translating the pathname. |
| 26609 | |
| 26610 | [EEXIST] _\bn_\ba_\bm_\be_\b2 already exists. |
| 26611 | |
| 26612 | [EIO] An I/O error occurred while making the directory entry |
| 26613 | for _\bn_\ba_\bm_\be_\b2, or allocating the inode for _\bn_\ba_\bm_\be_\b2, or |
| 26614 | writing out the link contents of _\bn_\ba_\bm_\be_\b2. |
| 26615 | |
| 26616 | [EROFS] The file _\bn_\ba_\bm_\be_\b2 would reside on a read-only file |
| 26617 | system. |
| 26618 | |
| 26619 | [ENOSPC] The directory in which the entry for the new symbolic |
| 26620 | link is being placed cannot be extended because there |
| 26621 | is no space left on the file system containing the |
| 26622 | directory. |
| 26623 | |
| 26624 | [ENOSPC] The new symbolic link cannot be created because there |
| 26625 | is no space left on the file system that will contain |
| 26626 | the symbolic link. |
| 26627 | |
| 26628 | [ENOSPC] There are no free inodes on the file system on which |
| 26629 | the symbolic link is being created. |
| 26630 | |
| 26631 | [EDQUOT] The directory in which the entry for the new symbolic |
| 26632 | link is being placed cannot be extended because the |
| 26633 | user's quota of disk blocks on the file system |
| 26634 | containing the directory has been exhausted. |
| 26635 | |
| 26636 | [EDQUOT] The new symbolic link cannot be created because the |
| 26637 | user's quota of disk blocks on the file system that |
| 26638 | will contain the symbolic link has been exhausted. |
| 26639 | |
| 26640 | [EDQUOT] The user's quota of inodes on the file system on which |
| 26641 | the symbolic link is being created has been exhausted. |
| 26642 | |
| 26643 | [EIO] An I/O error occurred while making the directory entry |
| 26644 | or allocating the inode. |
| 26645 | |
| 26646 | [EFAULT] _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 points outside the process's allocated |
| 26647 | address space. |
| 26648 | |
| 26649 | Additionally, s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() will fail if: |
| 26650 | |
| 26651 | [EBADF] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path and the |
| 26652 | _\bf_\bd argument is neither AT_FDCWD nor a valid file |
| 26653 | descriptor. |
| 26654 | |
| 26655 | [ENOTDIR] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path and the |
| 26656 | _\bf_\bd argument is a valid file descriptor but it does not |
| 26657 | reference a directory. |
| 26658 | |
| 26659 | [EACCES] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path but |
| 26660 | search permission is denied for the directory which |
| 26661 | the _\bf_\bd file descriptor references. |
| 26662 | |
| 26663 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26664 | ln(1), link(2), readlink(2), unlink(2), symlink(7) |
| 26665 | |
| 26666 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 26667 | The s\bsy\bym\bml\bli\bin\bnk\bk() and s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 26668 | (``POSIX.1''). |
| 26669 | |
| 26670 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26671 | The s\bsy\bym\bml\bli\bin\bnk\bk() system call first appeared in 4.1cBSD. The s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() |
| 26672 | system call has been available since OpenBSD 5.0. |
| 26673 | |
| 26674 | N\bNA\bAM\bME\bE |
| 26675 | s\bsy\bym\bml\bli\bin\bnk\bk, s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt - make symbolic link to a file |
| 26676 | |
| 26677 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26678 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 26679 | |
| 26680 | _\bi_\bn_\bt |
| 26681 | s\bsy\bym\bml\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
| 26682 | |
| 26683 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 26684 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 26685 | |
| 26686 | _\bi_\bn_\bt |
| 26687 | s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
| 26688 | |
| 26689 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26690 | A symbolic link _\bn_\ba_\bm_\be_\b2 is created to _\bn_\ba_\bm_\be_\b1 (_\bn_\ba_\bm_\be_\b2 is the name of the file |
| 26691 | created, _\bn_\ba_\bm_\be_\b1 is the string used in creating the symbolic link). Either |
| 26692 | name may be an arbitrary path name; the files need not be on the same |
| 26693 | file system, and the file specified by _\bn_\ba_\bm_\be_\b1 need not exist at all. |
| 26694 | |
| 26695 | The s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() function is equivalent to s\bsy\bym\bml\bli\bin\bnk\bk() except that where |
| 26696 | _\bn_\ba_\bm_\be_\b2 specifies a relative path, the newly created symbolic link is |
| 26697 | created relative to the directory associated with file descriptor _\bf_\bd |
| 26698 | instead of the current working directory. |
| 26699 | |
| 26700 | If s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in |
| 26701 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used and |
| 26702 | the behavior is identical to a call to s\bsy\bym\bml\bli\bin\bnk\bk(). |
| 26703 | |
| 26704 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26705 | Upon successful completion, the value 0 is returned; otherwise the |
| 26706 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 26707 | error. |
| 26708 | |
| 26709 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26710 | The symbolic link succeeds unless: |
| 26711 | |
| 26712 | [ENOTDIR] A component of the _\bn_\ba_\bm_\be_\b2 prefix is not a directory. |
| 26713 | |
| 26714 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 26715 | characters, or an entire pathname (including the |
| 26716 | terminating NUL) exceeded PATH_MAX bytes. |
| 26717 | |
| 26718 | [ENOENT] The named file does not exist. |
| 26719 | |
| 26720 | [EACCES] A component of the _\bn_\ba_\bm_\be_\b2 path prefix denies search |
| 26721 | permission. |
| 26722 | |
| 26723 | [ELOOP] Too many symbolic links were encountered in |
| 26724 | translating the pathname. |
| 26725 | |
| 26726 | [EEXIST] _\bn_\ba_\bm_\be_\b2 already exists. |
| 26727 | |
| 26728 | [EIO] An I/O error occurred while making the directory entry |
| 26729 | for _\bn_\ba_\bm_\be_\b2, or allocating the inode for _\bn_\ba_\bm_\be_\b2, or |
| 26730 | writing out the link contents of _\bn_\ba_\bm_\be_\b2. |
| 26731 | |
| 26732 | [EROFS] The file _\bn_\ba_\bm_\be_\b2 would reside on a read-only file |
| 26733 | system. |
| 26734 | |
| 26735 | [ENOSPC] The directory in which the entry for the new symbolic |
| 26736 | link is being placed cannot be extended because there |
| 26737 | is no space left on the file system containing the |
| 26738 | directory. |
| 26739 | |
| 26740 | [ENOSPC] The new symbolic link cannot be created because there |
| 26741 | is no space left on the file system that will contain |
| 26742 | the symbolic link. |
| 26743 | |
| 26744 | [ENOSPC] There are no free inodes on the file system on which |
| 26745 | the symbolic link is being created. |
| 26746 | |
| 26747 | [EDQUOT] The directory in which the entry for the new symbolic |
| 26748 | link is being placed cannot be extended because the |
| 26749 | user's quota of disk blocks on the file system |
| 26750 | containing the directory has been exhausted. |
| 26751 | |
| 26752 | [EDQUOT] The new symbolic link cannot be created because the |
| 26753 | user's quota of disk blocks on the file system that |
| 26754 | will contain the symbolic link has been exhausted. |
| 26755 | |
| 26756 | [EDQUOT] The user's quota of inodes on the file system on which |
| 26757 | the symbolic link is being created has been exhausted. |
| 26758 | |
| 26759 | [EIO] An I/O error occurred while making the directory entry |
| 26760 | or allocating the inode. |
| 26761 | |
| 26762 | [EFAULT] _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 points outside the process's allocated |
| 26763 | address space. |
| 26764 | |
| 26765 | Additionally, s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() will fail if: |
| 26766 | |
| 26767 | [EBADF] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path and the |
| 26768 | _\bf_\bd argument is neither AT_FDCWD nor a valid file |
| 26769 | descriptor. |
| 26770 | |
| 26771 | [ENOTDIR] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path and the |
| 26772 | _\bf_\bd argument is a valid file descriptor but it does not |
| 26773 | reference a directory. |
| 26774 | |
| 26775 | [EACCES] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path but |
| 26776 | search permission is denied for the directory which |
| 26777 | the _\bf_\bd file descriptor references. |
| 26778 | |
| 26779 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26780 | ln(1), link(2), readlink(2), unlink(2), symlink(7) |
| 26781 | |
| 26782 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 26783 | The s\bsy\bym\bml\bli\bin\bnk\bk() and s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 26784 | (``POSIX.1''). |
| 26785 | |
| 26786 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26787 | The s\bsy\bym\bml\bli\bin\bnk\bk() system call first appeared in 4.1cBSD. The s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() |
| 26788 | system call has been available since OpenBSD 5.0. |
| 26789 | |
| 26790 | N\bNA\bAM\bME\bE |
| 26791 | s\bsy\byn\bnc\bc - synchronize disk block in-core status with that on disk |
| 26792 | |
| 26793 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26794 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 26795 | |
| 26796 | _\bv_\bo_\bi_\bd |
| 26797 | s\bsy\byn\bnc\bc(_\bv_\bo_\bi_\bd); |
| 26798 | |
| 26799 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26800 | The s\bsy\byn\bnc\bc() function forces a write of dirty (modified) buffers in the |
| 26801 | block buffer cache out to disk. The kernel keeps this information in |
| 26802 | core to reduce the number of disk I/O transfers required by the system. |
| 26803 | As information in the cache is lost after a system crash a s\bsy\byn\bnc\bc() call is |
| 26804 | issued frequently by the in-kernel process update (about every 30 |
| 26805 | seconds). |
| 26806 | |
| 26807 | The function fsync(2) may be used to synchronize individual file |
| 26808 | descriptor attributes. |
| 26809 | |
| 26810 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26811 | fsync(2), sync(8) |
| 26812 | |
| 26813 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 26814 | The s\bsy\byn\bnc\bc() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 26815 | |
| 26816 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26817 | A s\bsy\byn\bnc\bc() function call appeared in Version 2 AT&T UNIX. |
| 26818 | |
| 26819 | B\bBU\bUG\bGS\bS |
| 26820 | s\bsy\byn\bnc\bc() may return before the buffers are completely flushed. |
| 26821 | |
| 26822 | N\bNA\bAM\bME\bE |
| 26823 | s\bsy\bys\bsa\bar\brc\bch\bh - architecture-dependent system call |
| 26824 | |
| 26825 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26826 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 26827 | |
| 26828 | _\bi_\bn_\bt |
| 26829 | s\bsy\bys\bsa\bar\brc\bch\bh(_\bi_\bn_\bt _\bn_\bu_\bm_\bb_\be_\br, _\bv_\bo_\bi_\bd _\b*_\ba_\br_\bg_\bs); |
| 26830 | |
| 26831 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26832 | s\bsy\bys\bsa\bar\brc\bch\bh() performs the architecture-dependent function specified by |
| 26833 | _\bn_\bu_\bm_\bb_\be_\br with the arguments specified by the _\ba_\br_\bg_\bs pointer. _\ba_\br_\bg_\bs is a |
| 26834 | pointer to a structure defining the actual arguments of the function. |
| 26835 | Symbolic constants and argument structures for the architecture-dependent |
| 26836 | functions can be found in the header file <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\bs_\by_\bs_\ba_\br_\bc_\bh_\b._\bh>. |
| 26837 | |
| 26838 | The s\bsy\bys\bsa\bar\brc\bch\bh() system call should never be called directly by user |
| 26839 | programs. Instead, they should access its functions using the |
| 26840 | architecture-dependent library. |
| 26841 | |
| 26842 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26843 | See the manual pages for specific architecture-dependent function calls |
| 26844 | for information about their return values. |
| 26845 | |
| 26846 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26847 | The s\bsy\bys\bsa\bar\brc\bch\bh() function call appeared in NetBSD 0.9a. |
| 26848 | |
| 26849 | N\bNA\bAM\bME\bE |
| 26850 | s\bsy\bys\bsc\bca\bal\bll\bl, _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl - indirect system call |
| 26851 | |
| 26852 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26853 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsy\bys\bsc\bca\bal\bll\bl.\b.h\bh>\b> |
| 26854 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 26855 | |
| 26856 | _\bi_\bn_\bt |
| 26857 | s\bsy\bys\bsc\bca\bal\bll\bl(_\bi_\bn_\bt _\bn_\bu_\bm_\bb_\be_\br, _\b._\b._\b.); |
| 26858 | |
| 26859 | _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl(_\bq_\bu_\ba_\bd_\b__\bt _\bn_\bu_\bm_\bb_\be_\br, _\b._\b._\b.); |
| 26860 | |
| 26861 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26862 | s\bsy\bys\bsc\bca\bal\bll\bl() performs the system call whose assembly language interface has |
| 26863 | the specified _\bn_\bu_\bm_\bb_\be_\br with the specified arguments. Symbolic constants |
| 26864 | for system calls can be found in the header file <_\bs_\by_\bs_\b/_\bs_\by_\bs_\bc_\ba_\bl_\bl_\b._\bh>. |
| 26865 | |
| 26866 | Since different system calls have different return types, a prototype of |
| 26867 | _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl specifying the correct return type should be declared locally. |
| 26868 | This is especially important for system calls returning larger-than-int |
| 26869 | results. |
| 26870 | |
| 26871 | The _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl form should be used when one or more of the parameters is a |
| 26872 | 64-bit argument to ensure that argument alignment is correct. This |
| 26873 | system call is useful for testing new system calls that do not have |
| 26874 | entries in the C library. |
| 26875 | |
| 26876 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26877 | The return values are defined by the system call being invoked. In |
| 26878 | general, for system calls returning _\bi_\bn_\bt, a 0 return value indicates |
| 26879 | success. A -1 return value indicates an error, and an error code is |
| 26880 | stored in _\be_\br_\br_\bn_\bo. |
| 26881 | |
| 26882 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26883 | The predecessor of these functions, the former i\bin\bnd\bdi\bir\br() system call, first |
| 26884 | appeared in Version 4 AT&T UNIX. The s\bsy\bys\bsc\bca\bal\bll\bl() function first appeared |
| 26885 | in 3BSD. |
| 26886 | |
| 26887 | B\bBU\bUG\bGS\bS |
| 26888 | There is no way to simulate system calls that have multiple return values |
| 26889 | such as pipe(2). |
| 26890 | |
| 26891 | N\bNA\bAM\bME\bE |
| 26892 | t\btr\bru\bun\bnc\bca\bat\bte\be, f\bft\btr\bru\bun\bnc\bca\bat\bte\be - truncate or extend a file to a specified length |
| 26893 | |
| 26894 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26895 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 26896 | |
| 26897 | _\bi_\bn_\bt |
| 26898 | t\btr\bru\bun\bnc\bca\bat\bte\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bo_\bf_\bf_\b__\bt _\bl_\be_\bn_\bg_\bt_\bh); |
| 26899 | |
| 26900 | _\bi_\bn_\bt |
| 26901 | f\bft\btr\bru\bun\bnc\bca\bat\bte\be(_\bi_\bn_\bt _\bf_\bd, _\bo_\bf_\bf_\b__\bt _\bl_\be_\bn_\bg_\bt_\bh); |
| 26902 | |
| 26903 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26904 | t\btr\bru\bun\bnc\bca\bat\bte\be() causes the file named by _\bp_\ba_\bt_\bh or referenced by _\bf_\bd to be |
| 26905 | truncated or extended to _\bl_\be_\bn_\bg_\bt_\bh bytes in size. If the file was larger |
| 26906 | than this size, the extra data is lost. If the file was smaller than |
| 26907 | this size, it will be extended as if by writing bytes with the value |
| 26908 | zero. With f\bft\btr\bru\bun\bnc\bca\bat\bte\be(), the file must be open for writing. |
| 26909 | |
| 26910 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26911 | Upon successful completion, the value 0 is returned; otherwise the |
| 26912 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 26913 | error. |
| 26914 | |
| 26915 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26916 | t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() will succeed unless: |
| 26917 | |
| 26918 | [EINVAL] The _\bl_\be_\bn_\bg_\bt_\bh is a negative value. |
| 26919 | |
| 26920 | [EIO] An I/O error occurred updating the inode. |
| 26921 | |
| 26922 | In addition, t\btr\bru\bun\bnc\bca\bat\bte\be() may return the following errors: |
| 26923 | |
| 26924 | [ENOTDIR] A component of the path prefix is not a directory. |
| 26925 | |
| 26926 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 26927 | characters, or an entire pathname (including the |
| 26928 | terminating NUL) exceeded PATH_MAX bytes. |
| 26929 | |
| 26930 | [ENOENT] The named file does not exist. |
| 26931 | |
| 26932 | [EACCES] Search permission is denied for a component of the |
| 26933 | path prefix. |
| 26934 | |
| 26935 | [EACCES] The named file is not writable by the user. |
| 26936 | |
| 26937 | [ELOOP] Too many symbolic links were encountered in |
| 26938 | translating the pathname. |
| 26939 | |
| 26940 | [EISDIR] The named file is a directory. |
| 26941 | |
| 26942 | [EROFS] The named file resides on a read-only file system. |
| 26943 | |
| 26944 | [ETXTBSY] The file is a pure procedure (shared text) file that |
| 26945 | is being executed. |
| 26946 | |
| 26947 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 26948 | space. |
| 26949 | |
| 26950 | f\bft\btr\bru\bun\bnc\bca\bat\bte\be() may return the following errors: |
| 26951 | |
| 26952 | [EBADF] The _\bf_\bd is not a valid descriptor. |
| 26953 | |
| 26954 | [EINVAL] The _\bf_\bd references a socket, not a file. |
| 26955 | |
| 26956 | [EINVAL] The _\bf_\bd is not open for writing. |
| 26957 | |
| 26958 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 26959 | open(2) |
| 26960 | |
| 26961 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 26962 | The t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() functions conform to IEEE Std 1003.1-2008 |
| 26963 | (``POSIX.1''). |
| 26964 | |
| 26965 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 26966 | The t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() system calls first appeared in 4.1cBSD. |
| 26967 | |
| 26968 | B\bBU\bUG\bGS\bS |
| 26969 | These calls should be generalized to allow ranges of bytes in a file to |
| 26970 | be discarded. |
| 26971 | |
| 26972 | Use of t\btr\bru\bun\bnc\bca\bat\bte\be() to extend a file is not portable. |
| 26973 | |
| 26974 | N\bNA\bAM\bME\bE |
| 26975 | u\bum\bma\bas\bsk\bk - set file creation mode mask |
| 26976 | |
| 26977 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 26978 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 26979 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 26980 | |
| 26981 | _\bm_\bo_\bd_\be_\b__\bt |
| 26982 | u\bum\bma\bas\bsk\bk(_\bm_\bo_\bd_\be_\b__\bt _\bn_\bu_\bm_\ba_\bs_\bk); |
| 26983 | |
| 26984 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 26985 | The u\bum\bma\bas\bsk\bk() routine sets the process's file mode creation mask to _\bn_\bu_\bm_\ba_\bs_\bk |
| 26986 | and returns the previous value of the mask. The 9 low-order access |
| 26987 | permission bits of _\bn_\bu_\bm_\ba_\bs_\bk are used by system calls, including open(2), |
| 26988 | mkdir(2), mkfifo(2) and mknod(2) to turn off corresponding bits requested |
| 26989 | in the file mode (see chmod(2)). This clearing allows each user to |
| 26990 | restrict the default access to his files. |
| 26991 | |
| 26992 | The default mask value is S_IWGRP|S_IWOTH (022, write access for the |
| 26993 | owner only). Child processes inherit the mask of the calling process. |
| 26994 | |
| 26995 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 26996 | The previous value of the file mode mask is returned by the call. |
| 26997 | |
| 26998 | E\bER\bRR\bRO\bOR\bRS\bS |
| 26999 | The u\bum\bma\bas\bsk\bk() function is always successful. |
| 27000 | |
| 27001 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 27002 | chmod(2), mkdir(2), mkfifo(2), mknod(2), open(2) |
| 27003 | |
| 27004 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 27005 | The u\bum\bma\bas\bsk\bk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
| 27006 | |
| 27007 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 27008 | The u\bum\bma\bas\bsk\bk() system call first appeared in Version 7 AT&T UNIX. |
| 27009 | |
| 27010 | N\bNA\bAM\bME\bE |
| 27011 | u\bun\bnl\bli\bin\bnk\bk, u\bun\bnl\bli\bin\bnk\bka\bat\bt - remove directory entry |
| 27012 | |
| 27013 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 27014 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 27015 | |
| 27016 | _\bi_\bn_\bt |
| 27017 | u\bun\bnl\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
| 27018 | |
| 27019 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 27020 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 27021 | |
| 27022 | _\bi_\bn_\bt |
| 27023 | u\bun\bnl\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 27024 | |
| 27025 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 27026 | The u\bun\bnl\bli\bin\bnk\bk() function removes the link named by _\bp_\ba_\bt_\bh from its directory |
| 27027 | and decrements the link count of the file which was referenced by the |
| 27028 | link. If that decrement reduces the link count of the file to zero, and |
| 27029 | no process has the file open, then all resources associated with the file |
| 27030 | are reclaimed. If one or more processes have the file open when the last |
| 27031 | link is removed, the link is removed, but the removal of the file is |
| 27032 | delayed until all references to it have been closed. |
| 27033 | |
| 27034 | The u\bun\bnl\bli\bin\bnk\bka\bat\bt() function is equivalent to either the u\bun\bnl\bli\bin\bnk\bk() or rmdir(2) |
| 27035 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 27036 | _\bp_\ba_\bt_\bh specifies a relative path, the directory entry to be removed is |
| 27037 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 27038 | instead of the current working directory. |
| 27039 | |
| 27040 | If u\bun\bnl\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 27041 | in the _\bf_\bd parameter, the current working directory is used and the |
| 27042 | behavior is identical to a call to u\bun\bnl\bli\bin\bnk\bk() or rmdir(2), depending on |
| 27043 | whether or not the AT_REMOVEDIR bit is set in _\bf_\bl_\ba_\bg. |
| 27044 | |
| 27045 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 27046 | values: |
| 27047 | |
| 27048 | AT_REMOVEDIR Remove the directory entry specified by _\bp_\ba_\bt_\bh as a |
| 27049 | directory, not a normal file. |
| 27050 | |
| 27051 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 27052 | Upon successful completion, the value 0 is returned; otherwise the |
| 27053 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 27054 | error. |
| 27055 | |
| 27056 | E\bER\bRR\bRO\bOR\bRS\bS |
| 27057 | The u\bun\bnl\bli\bin\bnk\bk() and u\bun\bnl\bli\bin\bnk\bka\bat\bt() functions will fail if: |
| 27058 | |
| 27059 | [ENOTDIR] A component of the path prefix is not a directory. |
| 27060 | |
| 27061 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 27062 | characters, or an entire pathname (including the |
| 27063 | terminating NUL) exceeded PATH_MAX bytes. |
| 27064 | |
| 27065 | [ENOENT] The named file does not exist. |
| 27066 | |
| 27067 | [EACCES] Search permission is denied for a component of the |
| 27068 | path prefix. |
| 27069 | |
| 27070 | [EACCES] Write permission is denied on the directory containing |
| 27071 | the link to be removed. |
| 27072 | |
| 27073 | [ELOOP] Too many symbolic links were encountered in |
| 27074 | translating the pathname. |
| 27075 | |
| 27076 | [EPERM] The named file is a directory and the effective user |
| 27077 | ID of the process is not the superuser, or the file |
| 27078 | system containing the file does not permit the use of |
| 27079 | u\bun\bnl\bli\bin\bnk\bk() on a directory. |
| 27080 | |
| 27081 | [EPERM] The directory containing the file is marked sticky, |
| 27082 | and neither the containing directory nor the file to |
| 27083 | be removed are owned by the effective user ID. |
| 27084 | |
| 27085 | [EPERM] The named file or the directory containing it has its |
| 27086 | immutable or append-only flag set (see chflags(2)). |
| 27087 | |
| 27088 | [EBUSY] The entry to be unlinked is the mount point for a |
| 27089 | mounted file system. |
| 27090 | |
| 27091 | [EIO] An I/O error occurred while deleting the directory |
| 27092 | entry or deallocating the inode. |
| 27093 | |
| 27094 | [EROFS] The named file resides on a read-only file system. |
| 27095 | |
| 27096 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 27097 | space. |
| 27098 | |
| 27099 | Additionally, u\bun\bnl\bli\bin\bnk\bka\bat\bt() will fail if: |
| 27100 | |
| 27101 | [ENOTDIR] The AT_REMOVEDIR flag bit is set and _\bp_\ba_\bt_\bh does not |
| 27102 | name a directory. |
| 27103 | |
| 27104 | [ENOTEMPTY] The AT_REMOVEDIR flag bit is set and the named |
| 27105 | directory contains files other than `.' and `..' in |
| 27106 | it. |
| 27107 | |
| 27108 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 27109 | AT_REMOVEDIR. |
| 27110 | |
| 27111 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 27112 | argument is neither AT_FDCWD nor a valid file |
| 27113 | descriptor. |
| 27114 | |
| 27115 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 27116 | argument is a valid file descriptor but it does not |
| 27117 | reference a directory. |
| 27118 | |
| 27119 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 27120 | permission is denied for the directory which the _\bf_\bd |
| 27121 | file descriptor references. |
| 27122 | |
| 27123 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 27124 | rm(1), chflags(2), close(2), link(2), rmdir(2), symlink(7) |
| 27125 | |
| 27126 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 27127 | The u\bun\bnl\bli\bin\bnk\bk() and u\bun\bnl\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 27128 | (``POSIX.1''). |
| 27129 | |
| 27130 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 27131 | The u\bun\bnl\bli\bin\bnk\bk() system call first appeared in Version 1 AT&T UNIX. The |
| 27132 | u\bun\bnl\bli\bin\bnk\bka\bat\bt() function appeared in OpenBSD 5.0. |
| 27133 | |
| 27134 | N\bNA\bAM\bME\bE |
| 27135 | u\bun\bnl\bli\bin\bnk\bk, u\bun\bnl\bli\bin\bnk\bka\bat\bt - remove directory entry |
| 27136 | |
| 27137 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 27138 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 27139 | |
| 27140 | _\bi_\bn_\bt |
| 27141 | u\bun\bnl\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
| 27142 | |
| 27143 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 27144 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 27145 | |
| 27146 | _\bi_\bn_\bt |
| 27147 | u\bun\bnl\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 27148 | |
| 27149 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 27150 | The u\bun\bnl\bli\bin\bnk\bk() function removes the link named by _\bp_\ba_\bt_\bh from its directory |
| 27151 | and decrements the link count of the file which was referenced by the |
| 27152 | link. If that decrement reduces the link count of the file to zero, and |
| 27153 | no process has the file open, then all resources associated with the file |
| 27154 | are reclaimed. If one or more processes have the file open when the last |
| 27155 | link is removed, the link is removed, but the removal of the file is |
| 27156 | delayed until all references to it have been closed. |
| 27157 | |
| 27158 | The u\bun\bnl\bli\bin\bnk\bka\bat\bt() function is equivalent to either the u\bun\bnl\bli\bin\bnk\bk() or rmdir(2) |
| 27159 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
| 27160 | _\bp_\ba_\bt_\bh specifies a relative path, the directory entry to be removed is |
| 27161 | determined relative to the directory associated with file descriptor _\bf_\bd |
| 27162 | instead of the current working directory. |
| 27163 | |
| 27164 | If u\bun\bnl\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
| 27165 | in the _\bf_\bd parameter, the current working directory is used and the |
| 27166 | behavior is identical to a call to u\bun\bnl\bli\bin\bnk\bk() or rmdir(2), depending on |
| 27167 | whether or not the AT_REMOVEDIR bit is set in _\bf_\bl_\ba_\bg. |
| 27168 | |
| 27169 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 27170 | values: |
| 27171 | |
| 27172 | AT_REMOVEDIR Remove the directory entry specified by _\bp_\ba_\bt_\bh as a |
| 27173 | directory, not a normal file. |
| 27174 | |
| 27175 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 27176 | Upon successful completion, the value 0 is returned; otherwise the |
| 27177 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 27178 | error. |
| 27179 | |
| 27180 | E\bER\bRR\bRO\bOR\bRS\bS |
| 27181 | The u\bun\bnl\bli\bin\bnk\bk() and u\bun\bnl\bli\bin\bnk\bka\bat\bt() functions will fail if: |
| 27182 | |
| 27183 | [ENOTDIR] A component of the path prefix is not a directory. |
| 27184 | |
| 27185 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 27186 | characters, or an entire pathname (including the |
| 27187 | terminating NUL) exceeded PATH_MAX bytes. |
| 27188 | |
| 27189 | [ENOENT] The named file does not exist. |
| 27190 | |
| 27191 | [EACCES] Search permission is denied for a component of the |
| 27192 | path prefix. |
| 27193 | |
| 27194 | [EACCES] Write permission is denied on the directory containing |
| 27195 | the link to be removed. |
| 27196 | |
| 27197 | [ELOOP] Too many symbolic links were encountered in |
| 27198 | translating the pathname. |
| 27199 | |
| 27200 | [EPERM] The named file is a directory and the effective user |
| 27201 | ID of the process is not the superuser, or the file |
| 27202 | system containing the file does not permit the use of |
| 27203 | u\bun\bnl\bli\bin\bnk\bk() on a directory. |
| 27204 | |
| 27205 | [EPERM] The directory containing the file is marked sticky, |
| 27206 | and neither the containing directory nor the file to |
| 27207 | be removed are owned by the effective user ID. |
| 27208 | |
| 27209 | [EPERM] The named file or the directory containing it has its |
| 27210 | immutable or append-only flag set (see chflags(2)). |
| 27211 | |
| 27212 | [EBUSY] The entry to be unlinked is the mount point for a |
| 27213 | mounted file system. |
| 27214 | |
| 27215 | [EIO] An I/O error occurred while deleting the directory |
| 27216 | entry or deallocating the inode. |
| 27217 | |
| 27218 | [EROFS] The named file resides on a read-only file system. |
| 27219 | |
| 27220 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
| 27221 | space. |
| 27222 | |
| 27223 | Additionally, u\bun\bnl\bli\bin\bnk\bka\bat\bt() will fail if: |
| 27224 | |
| 27225 | [ENOTDIR] The AT_REMOVEDIR flag bit is set and _\bp_\ba_\bt_\bh does not |
| 27226 | name a directory. |
| 27227 | |
| 27228 | [ENOTEMPTY] The AT_REMOVEDIR flag bit is set and the named |
| 27229 | directory contains files other than `.' and `..' in |
| 27230 | it. |
| 27231 | |
| 27232 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 27233 | AT_REMOVEDIR. |
| 27234 | |
| 27235 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 27236 | argument is neither AT_FDCWD nor a valid file |
| 27237 | descriptor. |
| 27238 | |
| 27239 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
| 27240 | argument is a valid file descriptor but it does not |
| 27241 | reference a directory. |
| 27242 | |
| 27243 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
| 27244 | permission is denied for the directory which the _\bf_\bd |
| 27245 | file descriptor references. |
| 27246 | |
| 27247 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 27248 | rm(1), chflags(2), close(2), link(2), rmdir(2), symlink(7) |
| 27249 | |
| 27250 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 27251 | The u\bun\bnl\bli\bin\bnk\bk() and u\bun\bnl\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
| 27252 | (``POSIX.1''). |
| 27253 | |
| 27254 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 27255 | The u\bun\bnl\bli\bin\bnk\bk() system call first appeared in Version 1 AT&T UNIX. The |
| 27256 | u\bun\bnl\bli\bin\bnk\bka\bat\bt() function appeared in OpenBSD 5.0. |
| 27257 | |
| 27258 | N\bNA\bAM\bME\bE |
| 27259 | m\bmo\bou\bun\bnt\bt, u\bun\bnm\bmo\bou\bun\bnt\bt - mount or dismount a filesystem |
| 27260 | |
| 27261 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 27262 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 27263 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
| 27264 | |
| 27265 | _\bi_\bn_\bt |
| 27266 | m\bmo\bou\bun\bnt\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\by_\bp_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bv_\bo_\bi_\bd _\b*_\bd_\ba_\bt_\ba); |
| 27267 | |
| 27268 | _\bi_\bn_\bt |
| 27269 | u\bun\bnm\bmo\bou\bun\bnt\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
| 27270 | |
| 27271 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 27272 | The m\bmo\bou\bun\bnt\bt() function grafts a filesystem object onto the system file tree |
| 27273 | at the point _\bd_\bi_\br. The argument _\bd_\ba_\bt_\ba describes the filesystem object to |
| 27274 | be mounted. The argument _\bt_\by_\bp_\be tells the kernel how to interpret _\bd_\ba_\bt_\ba |
| 27275 | (see _\bt_\by_\bp_\be below). The contents of the filesystem become available |
| 27276 | through the new mount point _\bd_\bi_\br. Any files in _\bd_\bi_\br at the time of a |
| 27277 | successful mount are swept under the carpet, so to speak, and are |
| 27278 | unavailable until the filesystem is unmounted. |
| 27279 | |
| 27280 | The following _\bf_\bl_\ba_\bg_\bs may be specified to suppress default semantics which |
| 27281 | affect filesystem access. |
| 27282 | |
| 27283 | MNT_RDONLY The filesystem should be treated as read-only: even the |
| 27284 | superuser may not write to it. |
| 27285 | |
| 27286 | MNT_NOATIME Do not update the access time on files in the filesystem |
| 27287 | unless the modification or status change times are also |
| 27288 | being updated. |
| 27289 | |
| 27290 | MNT_NOEXEC Do not allow files to be executed from the filesystem. |
| 27291 | |
| 27292 | MNT_NOSUID Do not honor setuid or setgid bits on files when |
| 27293 | executing them. |
| 27294 | |
| 27295 | MNT_NODEV Do not interpret special files on the filesystem. |
| 27296 | |
| 27297 | MNT_SYNCHRONOUS All I/O to the filesystem should be done synchronously. |
| 27298 | |
| 27299 | MNT_ASYNC All I/O to the filesystem should be done asynchronously. |
| 27300 | |
| 27301 | MNT_SOFTDEP Use soft dependencies. Applies to FFS filesystems only |
| 27302 | (see 'softdep' in mount(8)). |
| 27303 | |
| 27304 | The flag MNT_UPDATE indicates that the mount command is being applied to |
| 27305 | an already mounted filesystem. This allows the mount flags to be changed |
| 27306 | without requiring that the filesystem be unmounted and remounted. Some |
| 27307 | filesystems may not allow all flags to be changed. For example, most |
| 27308 | filesystems will not allow a change from read-write to read-only. |
| 27309 | |
| 27310 | The _\bt_\by_\bp_\be argument defines the type of the filesystem. The types of |
| 27311 | filesystems known to the system are defined in <_\bs_\by_\bs_\b/_\bm_\bo_\bu_\bn_\bt_\b._\bh>. _\bd_\ba_\bt_\ba is a |
| 27312 | pointer to a structure that contains the type specific arguments to |
| 27313 | mount. The currently supported types of filesystems and their type |
| 27314 | specific data are: |
| 27315 | |
| 27316 | MOUNT_CD9660 |
| 27317 | struct iso_args { |
| 27318 | char *fspec; /* block special device to mount */ |
| 27319 | struct export_args export_info; |
| 27320 | /* network export info */ |
| 27321 | int flags; /* mounting flags, see below */ |
| 27322 | }; |
| 27323 | #define ISOFSMNT_NORRIP 0x00000001 /* disable Rock Ridge Ext.*/ |
| 27324 | #define ISOFSMNT_GENS 0x00000002 /* enable generation numbers */ |
| 27325 | #define ISOFSMNT_EXTATT 0x00000004 /* enable extended attributes */ |
| 27326 | #define ISOFSMNT_NOJOLIET 0x00000008 /* disable Joliet Ext.*/ |
| 27327 | #define ISOFSMNT_SESS 0x00000010 /* use iso_args.sess */ |
| 27328 | |
| 27329 | MOUNT_FFS |
| 27330 | struct ufs_args { |
| 27331 | char *fspec; /* block special file to mount */ |
| 27332 | struct export_args export_info; |
| 27333 | /* network export information */ |
| 27334 | }; |
| 27335 | |
| 27336 | MOUNT_MFS |
| 27337 | struct mfs_args { |
| 27338 | char *fspec; /* name to export for statfs */ |
| 27339 | struct export_args export_info; |
| 27340 | /* if we can export an MFS */ |
| 27341 | caddr_t base; /* base of filesystem in mem */ |
| 27342 | u_long size; /* size of filesystem */ |
| 27343 | }; |
| 27344 | |
| 27345 | MOUNT_MSDOS |
| 27346 | struct msdosfs_args { |
| 27347 | char *fspec; /* blocks special holding fs to mount */ |
| 27348 | struct export_args export_info; |
| 27349 | /* network export information */ |
| 27350 | uid_t uid; /* uid that owns msdosfs files */ |
| 27351 | gid_t gid; /* gid that owns msdosfs files */ |
| 27352 | mode_t mask; /* mask to be applied for msdosfs perms */ |
| 27353 | int flags; /* see below */ |
| 27354 | }; |
| 27355 | |
| 27356 | /* |
| 27357 | * Msdosfs mount options: |
| 27358 | */ |
| 27359 | #define MSDOSFSMNT_SHORTNAME 1 /* Force old DOS short names only */ |
| 27360 | #define MSDOSFSMNT_LONGNAME 2 /* Force Win'95 long names */ |
| 27361 | #define MSDOSFSMNT_NOWIN95 4 /* Completely ignore Win95 entries */ |
| 27362 | |
| 27363 | MOUNT_NFS |
| 27364 | struct nfs_args { |
| 27365 | int version; /* args structure version */ |
| 27366 | struct sockaddr *addr; /* file server address */ |
| 27367 | int addrlen; /* length of address */ |
| 27368 | int sotype; /* Socket type */ |
| 27369 | int proto; /* and Protocol */ |
| 27370 | u_char *fh; /* File handle to be mounted */ |
| 27371 | int fhsize; /* Size, in bytes, of fh */ |
| 27372 | int flags; /* flags */ |
| 27373 | int wsize; /* write size in bytes */ |
| 27374 | int rsize; /* read size in bytes */ |
| 27375 | int readdirsize; /* readdir size in bytes */ |
| 27376 | int timeo; /* initial timeout in .1 secs */ |
| 27377 | int retrans; /* times to retry send */ |
| 27378 | int maxgrouplist; /* Max. size of group list */ |
| 27379 | int readahead; /* # of blocks to readahead */ |
| 27380 | int leaseterm; /* Term (sec) of lease */ |
| 27381 | int deadthresh; /* Retrans threshold */ |
| 27382 | char *hostname; /* server's name */ |
| 27383 | int acregmin; /* Attr cache file recently modified */ |
| 27384 | int acregmax; /* ac file not recently modified */ |
| 27385 | int acdirmin; /* ac for dir recently modified */ |
| 27386 | int acdirmax; /* ac for dir not recently modified */ |
| 27387 | }; |
| 27388 | |
| 27389 | MOUNT_NTFS |
| 27390 | struct ntfs_args { |
| 27391 | char *fspec; /* block special device to mount */ |
| 27392 | struct export_args export_info; |
| 27393 | /* network export information */ |
| 27394 | uid_t uid; /* uid that owns ntfs files */ |
| 27395 | gid_t gid; /* gid that owns ntfs files */ |
| 27396 | mode_t mode; /* mask to be applied for ntfs perms */ |
| 27397 | u_long flag; /* additional flags */ |
| 27398 | }; |
| 27399 | |
| 27400 | /* |
| 27401 | * ntfs mount options: |
| 27402 | */ |
| 27403 | #define NTFS_MFLAG_CASEINS 0x00000001 |
| 27404 | #define NTFS_MFLAG_ALLNAMES 0x00000002 |
| 27405 | |
| 27406 | MOUNT_UDF |
| 27407 | struct udf_args { |
| 27408 | char *fspec; /* block special device to mount */ |
| 27409 | }; |
| 27410 | |
| 27411 | The u\bun\bnm\bmo\bou\bun\bnt\bt() function call disassociates the filesystem from the |
| 27412 | specified mount point _\bd_\bi_\br. |
| 27413 | |
| 27414 | The _\bf_\bl_\ba_\bg_\bs argument may specify MNT_FORCE to specify that the filesystem |
| 27415 | should be forcibly unmounted even if files are still active. Active |
| 27416 | special devices continue to work, but any further accesses to any other |
| 27417 | active files result in errors even if the filesystem is later remounted. |
| 27418 | |
| 27419 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 27420 | Upon successful completion, the value 0 is returned; otherwise the |
| 27421 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 27422 | error. |
| 27423 | |
| 27424 | E\bER\bRR\bRO\bOR\bRS\bS |
| 27425 | m\bmo\bou\bun\bnt\bt() will fail when one of the following occurs: |
| 27426 | |
| 27427 | [EPERM] The caller is not the superuser. |
| 27428 | |
| 27429 | [ENAMETOOLONG] The path name exceeded {MNAMELEN} characters. |
| 27430 | |
| 27431 | [ELOOP] Too many symbolic links were encountered in translating a |
| 27432 | pathname. |
| 27433 | |
| 27434 | [ENOENT] A component of _\bd_\bi_\br does not exist. |
| 27435 | |
| 27436 | [ENOTDIR] A component of _\bn_\ba_\bm_\be is not a directory, or a path prefix |
| 27437 | of _\bs_\bp_\be_\bc_\bi_\ba_\bl is not a directory. |
| 27438 | |
| 27439 | [EINVAL] An argument given was invalid. |
| 27440 | |
| 27441 | [EBUSY] Another process currently holds a reference to _\bd_\bi_\br. |
| 27442 | |
| 27443 | [EFAULT] _\bd_\bi_\br points outside the process's allocated address space. |
| 27444 | |
| 27445 | [EOPNOTSUPP] _\bt_\by_\bp_\be is not supported by the kernel. |
| 27446 | |
| 27447 | The following errors can occur for a ``ufs'' filesystem mount: |
| 27448 | |
| 27449 | [ENODEV] A component of ufs_args _\bf_\bs_\bp_\be_\bc does not exist. |
| 27450 | |
| 27451 | [ENOTBLK] _\bf_\bs_\bp_\be_\bc is not a block device. |
| 27452 | |
| 27453 | [ENXIO] The major device number of _\bf_\bs_\bp_\be_\bc is out of range (this |
| 27454 | indicates no device driver exists for the associated |
| 27455 | hardware). |
| 27456 | |
| 27457 | [EBUSY] _\bf_\bs_\bp_\be_\bc is already mounted. |
| 27458 | |
| 27459 | [EINVAL] The super block for the filesystem had a bad magic number, an |
| 27460 | out of range block size, or an invalid combination of flags. |
| 27461 | |
| 27462 | [ENOMEM] Not enough memory was available to read the cylinder group |
| 27463 | information for the filesystem. |
| 27464 | |
| 27465 | [EIO] An I/O error occurred while reading the super block or |
| 27466 | cylinder group information. |
| 27467 | |
| 27468 | [EFAULT] _\bf_\bs_\bp_\be_\bc points outside the process's allocated address space. |
| 27469 | |
| 27470 | [EROFS] The filesystem was not unmounted cleanly and MNT_FORCE was not |
| 27471 | specified. |
| 27472 | |
| 27473 | [EROFS] An attempt was made to mount a 4.2BSD filesystem without the |
| 27474 | MNT_RDONLY flag. |
| 27475 | |
| 27476 | The following errors can occur for an _\bN_\bF_\bS filesystem mount: |
| 27477 | |
| 27478 | [ETIMEDOUT] _\bN_\bF_\bS timed out trying to contact the server. |
| 27479 | |
| 27480 | [EFAULT] Some part of the information described by nfs_args points |
| 27481 | outside the process's allocated address space. |
| 27482 | |
| 27483 | The following errors can occur for a _\bm_\bf_\bs filesystem mount: |
| 27484 | |
| 27485 | [EMFILE] No space remains in the mount table. |
| 27486 | |
| 27487 | [EINVAL] The super block for the filesystem had a bad magic number or an |
| 27488 | out of range block size. |
| 27489 | |
| 27490 | [ENOMEM] Not enough memory was available to read the cylinder group |
| 27491 | information for the filesystem. |
| 27492 | |
| 27493 | [EIO] A paging error occurred while reading the super block or |
| 27494 | cylinder group information. |
| 27495 | |
| 27496 | [EFAULT] _\bN_\ba_\bm_\be points outside the process's allocated address space. |
| 27497 | |
| 27498 | u\bun\bnm\bmo\bou\bun\bnt\bt() may fail with one of the following errors: |
| 27499 | |
| 27500 | [EPERM] The caller is not the superuser. |
| 27501 | |
| 27502 | [ENOTDIR] A component of the path is not a directory. |
| 27503 | |
| 27504 | [EINVAL] An argument given was invalid. |
| 27505 | |
| 27506 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, |
| 27507 | or an entire pathname (including the terminating NUL) |
| 27508 | exceeded PATH_MAX bytes. |
| 27509 | |
| 27510 | [ELOOP] Too many symbolic links were encountered in translating |
| 27511 | the pathname. |
| 27512 | |
| 27513 | [EINVAL] The requested directory is not in the mount table. |
| 27514 | |
| 27515 | [EBUSY] A process is holding a reference to a file located on the |
| 27516 | filesystem. |
| 27517 | |
| 27518 | [EIO] An I/O error occurred while writing cached filesystem |
| 27519 | information. |
| 27520 | |
| 27521 | [EFAULT] _\bd_\bi_\br points outside the process's allocated address space. |
| 27522 | |
| 27523 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 27524 | statfs(2), mfs(8), mount(8), umount(8) |
| 27525 | |
| 27526 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 27527 | The m\bmo\bou\bun\bnt\bt() and u\bun\bnm\bmo\bou\bun\bnt\bt() system calls first appeared in Version 1 AT&T |
| 27528 | UNIX. The _\bf_\bl_\ba_\bg_\bs argument is supported by m\bmo\bou\bun\bnt\bt() since Version 5 AT&T |
| 27529 | UNIX and by u\bun\bnm\bmo\bou\bun\bnt\bt() since 4.3BSD-Reno. The current calling convention |
| 27530 | involving _\bt_\by_\bp_\be and _\bd_\ba_\bt_\ba arguments was introduced by 4.3BSD-Reno as well. |
| 27531 | |
| 27532 | B\bBU\bUG\bGS\bS |
| 27533 | Some of the error codes need translation to more obvious messages. |
| 27534 | |
| 27535 | N\bNA\bAM\bME\bE |
| 27536 | u\but\bti\bim\bme\bes\bs, f\bfu\but\bti\bim\bme\bes\bs, u\but\bti\bim\bme\ben\bns\bsa\bat\bt, f\bfu\but\bti\bim\bme\ben\bns\bs - set file access and modification |
| 27537 | times |
| 27538 | |
| 27539 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 27540 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 27541 | |
| 27542 | _\bi_\bn_\bt |
| 27543 | u\but\bti\bim\bme\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
| 27544 | |
| 27545 | _\bi_\bn_\bt |
| 27546 | f\bfu\but\bti\bim\bme\bes\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
| 27547 | |
| 27548 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 27549 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 27550 | |
| 27551 | _\bi_\bn_\bt |
| 27552 | u\but\bti\bim\bme\ben\bns\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b], |
| 27553 | _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 27554 | |
| 27555 | _\bi_\bn_\bt |
| 27556 | f\bfu\but\bti\bim\bme\ben\bns\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b]); |
| 27557 | |
| 27558 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 27559 | The access and modification times of the file named by _\bp_\ba_\bt_\bh or referenced |
| 27560 | by _\bf_\bd are changed as specified by the argument _\bt_\bi_\bm_\be_\bs. |
| 27561 | |
| 27562 | If _\bt_\bi_\bm_\be_\bs is NULL, the access and modification times are set to the |
| 27563 | current time. The caller must be the owner of the file, have permission |
| 27564 | to write the file, or be the superuser. |
| 27565 | |
| 27566 | If _\bt_\bi_\bm_\be_\bs is non-null, it is assumed to point to an array of two timeval |
| 27567 | structures. The access time is set to the value of the first element, |
| 27568 | and the modification time is set to the value of the second element. The |
| 27569 | caller must be the owner of the file or be the superuser. |
| 27570 | |
| 27571 | In either case, the inode-change-time of the file is set to the current |
| 27572 | time. |
| 27573 | |
| 27574 | The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() are equivalent to u\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\bes\bs(), |
| 27575 | respectively, with the following differences. |
| 27576 | |
| 27577 | Both u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() take two timespec values instead of two |
| 27578 | timeval values. Further, either of the _\bt_\bv_\b__\bn_\bs_\be_\bc fields can be set to one |
| 27579 | of the following special values defined in <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>: |
| 27580 | |
| 27581 | UTIME_NOW Set the respective timestamp to the greatest value |
| 27582 | supported that is not greater than the current time. |
| 27583 | UTIME_OMIT Do not change the respective timestamp. |
| 27584 | |
| 27585 | Additionally, if the _\bp_\ba_\bt_\bh argument to u\but\bti\bim\bme\ben\bns\bsa\bat\bt() specifies a relative |
| 27586 | path, the file whose timestamps are changed is determined relative to the |
| 27587 | directory associated with file descriptor _\bf_\bd instead of the current |
| 27588 | working directory. |
| 27589 | |
| 27590 | If u\but\bti\bim\bme\ben\bns\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 27591 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 27592 | |
| 27593 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 27594 | values: |
| 27595 | |
| 27596 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
| 27597 | timestamps of the symbolic link are changed. |
| 27598 | |
| 27599 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 27600 | Upon successful completion, the value 0 is returned; otherwise the |
| 27601 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 27602 | error. |
| 27603 | |
| 27604 | E\bER\bRR\bRO\bOR\bRS\bS |
| 27605 | u\but\bti\bim\bme\bes\bs() and u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
| 27606 | |
| 27607 | [EACCES] Search permission is denied for a component of the |
| 27608 | path prefix; or the _\bt_\bi_\bm_\be_\bs argument is NULL and the |
| 27609 | effective user ID of the process does not match the |
| 27610 | owner of the file, and is not the superuser, and write |
| 27611 | access is denied. |
| 27612 | |
| 27613 | [EFAULT] _\bf_\bi_\bl_\be or _\bt_\bi_\bm_\be_\bs points outside the process's allocated |
| 27614 | address space. |
| 27615 | |
| 27616 | [EIO] An I/O error occurred while reading or writing the |
| 27617 | affected inode. |
| 27618 | |
| 27619 | [ELOOP] Too many symbolic links were encountered in |
| 27620 | translating the pathname. |
| 27621 | |
| 27622 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 27623 | characters, or an entire pathname (including the |
| 27624 | terminating NUL) exceeded PATH_MAX bytes. |
| 27625 | |
| 27626 | [ENOENT] The named file does not exist. |
| 27627 | |
| 27628 | [ENOTDIR] A component of the path prefix is not a directory. |
| 27629 | |
| 27630 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
| 27631 | process's effective user ID does not match the owner |
| 27632 | of the file and is not the superuser. |
| 27633 | |
| 27634 | [EROFS] The file system containing the file is mounted read- |
| 27635 | only. |
| 27636 | |
| 27637 | Additionally, u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
| 27638 | |
| 27639 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 27640 | AT_SYMLINK_NOFOLLOW. |
| 27641 | |
| 27642 | [EBADF] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
| 27643 | argument is neither AT_FDCWD nor a valid file |
| 27644 | descriptor. |
| 27645 | |
| 27646 | [ENOTDIR] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
| 27647 | argument is a valid file descriptor but it does not |
| 27648 | reference a directory. |
| 27649 | |
| 27650 | [EACCES] The _\bf_\bi_\bl_\be argument specifies a relative path but search |
| 27651 | permission is denied for the directory which the _\bf_\bd |
| 27652 | file descriptor references. |
| 27653 | |
| 27654 | f\bfu\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\ben\bns\bs() will fail if: |
| 27655 | |
| 27656 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
| 27657 | |
| 27658 | [EACCES] The _\bt_\bi_\bm_\be_\bs argument is NULL and the effective user ID |
| 27659 | of the process does not match the owner of the file, |
| 27660 | and is not the superuser, and write access is denied. |
| 27661 | |
| 27662 | [EFAULT] _\bt_\bi_\bm_\be_\bs points outside the process's allocated address |
| 27663 | space. |
| 27664 | |
| 27665 | [EIO] An I/O error occurred while reading or writing the |
| 27666 | affected inode. |
| 27667 | |
| 27668 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
| 27669 | process's effective user ID does not match the owner |
| 27670 | of the file and is not the superuser. |
| 27671 | |
| 27672 | [EROFS] The file system containing the file is mounted read- |
| 27673 | only. |
| 27674 | |
| 27675 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 27676 | clock_gettime(2), stat(2), utime(3) |
| 27677 | |
| 27678 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 27679 | The u\but\bti\bim\bme\bes\bs(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), and f\bfu\but\bti\bim\bme\ben\bns\bs() functions conform to IEEE Std |
| 27680 | 1003.1-2008 (``POSIX.1''). |
| 27681 | |
| 27682 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 27683 | The predecessors of u\but\bti\bim\bme\bes\bs() were s\bsm\bmd\bda\bat\bte\be() in Version 1 AT&T UNIX, |
| 27684 | m\bmd\bda\bat\bte\be() in Version 3 AT&T UNIX, and u\but\bti\bim\bme\be() in Version 7 AT&T UNIX; the |
| 27685 | latter first supported the concept of an access time in addition to the |
| 27686 | modification time. |
| 27687 | |
| 27688 | The u\but\bti\bim\bme\bes\bs() function call appeared in 4.2BSD. The f\bfu\but\bti\bim\bme\bes\bs() function |
| 27689 | call appeared in NetBSD 1.2. The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() function |
| 27690 | calls appeared in OpenBSD 5.0. |
| 27691 | |
| 27692 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 27693 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and |
| 27694 | f\bfu\but\bti\bim\bme\ben\bns\bs() shall mark the last file status change timestamp (i.e. |
| 27695 | _\bs_\bt_\b__\bc_\bt_\bi_\bm) for update upon successful completion. However, currently some |
| 27696 | filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the |
| 27697 | modification timestamp argument. |
| 27698 | |
| 27699 | N\bNA\bAM\bME\bE |
| 27700 | u\but\bti\bim\bme\bes\bs, f\bfu\but\bti\bim\bme\bes\bs, u\but\bti\bim\bme\ben\bns\bsa\bat\bt, f\bfu\but\bti\bim\bme\ben\bns\bs - set file access and modification |
| 27701 | times |
| 27702 | |
| 27703 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 27704 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
| 27705 | |
| 27706 | _\bi_\bn_\bt |
| 27707 | u\but\bti\bim\bme\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
| 27708 | |
| 27709 | _\bi_\bn_\bt |
| 27710 | f\bfu\but\bti\bim\bme\bes\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
| 27711 | |
| 27712 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
| 27713 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
| 27714 | |
| 27715 | _\bi_\bn_\bt |
| 27716 | u\but\bti\bim\bme\ben\bns\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b], |
| 27717 | _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
| 27718 | |
| 27719 | _\bi_\bn_\bt |
| 27720 | f\bfu\but\bti\bim\bme\ben\bns\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b]); |
| 27721 | |
| 27722 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 27723 | The access and modification times of the file named by _\bp_\ba_\bt_\bh or referenced |
| 27724 | by _\bf_\bd are changed as specified by the argument _\bt_\bi_\bm_\be_\bs. |
| 27725 | |
| 27726 | If _\bt_\bi_\bm_\be_\bs is NULL, the access and modification times are set to the |
| 27727 | current time. The caller must be the owner of the file, have permission |
| 27728 | to write the file, or be the superuser. |
| 27729 | |
| 27730 | If _\bt_\bi_\bm_\be_\bs is non-null, it is assumed to point to an array of two timeval |
| 27731 | structures. The access time is set to the value of the first element, |
| 27732 | and the modification time is set to the value of the second element. The |
| 27733 | caller must be the owner of the file or be the superuser. |
| 27734 | |
| 27735 | In either case, the inode-change-time of the file is set to the current |
| 27736 | time. |
| 27737 | |
| 27738 | The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() are equivalent to u\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\bes\bs(), |
| 27739 | respectively, with the following differences. |
| 27740 | |
| 27741 | Both u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() take two timespec values instead of two |
| 27742 | timeval values. Further, either of the _\bt_\bv_\b__\bn_\bs_\be_\bc fields can be set to one |
| 27743 | of the following special values defined in <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>: |
| 27744 | |
| 27745 | UTIME_NOW Set the respective timestamp to the greatest value |
| 27746 | supported that is not greater than the current time. |
| 27747 | UTIME_OMIT Do not change the respective timestamp. |
| 27748 | |
| 27749 | Additionally, if the _\bp_\ba_\bt_\bh argument to u\but\bti\bim\bme\ben\bns\bsa\bat\bt() specifies a relative |
| 27750 | path, the file whose timestamps are changed is determined relative to the |
| 27751 | directory associated with file descriptor _\bf_\bd instead of the current |
| 27752 | working directory. |
| 27753 | |
| 27754 | If u\but\bti\bim\bme\ben\bns\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
| 27755 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
| 27756 | |
| 27757 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
| 27758 | values: |
| 27759 | |
| 27760 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
| 27761 | timestamps of the symbolic link are changed. |
| 27762 | |
| 27763 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 27764 | Upon successful completion, the value 0 is returned; otherwise the |
| 27765 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 27766 | error. |
| 27767 | |
| 27768 | E\bER\bRR\bRO\bOR\bRS\bS |
| 27769 | u\but\bti\bim\bme\bes\bs() and u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
| 27770 | |
| 27771 | [EACCES] Search permission is denied for a component of the |
| 27772 | path prefix; or the _\bt_\bi_\bm_\be_\bs argument is NULL and the |
| 27773 | effective user ID of the process does not match the |
| 27774 | owner of the file, and is not the superuser, and write |
| 27775 | access is denied. |
| 27776 | |
| 27777 | [EFAULT] _\bf_\bi_\bl_\be or _\bt_\bi_\bm_\be_\bs points outside the process's allocated |
| 27778 | address space. |
| 27779 | |
| 27780 | [EIO] An I/O error occurred while reading or writing the |
| 27781 | affected inode. |
| 27782 | |
| 27783 | [ELOOP] Too many symbolic links were encountered in |
| 27784 | translating the pathname. |
| 27785 | |
| 27786 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
| 27787 | characters, or an entire pathname (including the |
| 27788 | terminating NUL) exceeded PATH_MAX bytes. |
| 27789 | |
| 27790 | [ENOENT] The named file does not exist. |
| 27791 | |
| 27792 | [ENOTDIR] A component of the path prefix is not a directory. |
| 27793 | |
| 27794 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
| 27795 | process's effective user ID does not match the owner |
| 27796 | of the file and is not the superuser. |
| 27797 | |
| 27798 | [EROFS] The file system containing the file is mounted read- |
| 27799 | only. |
| 27800 | |
| 27801 | Additionally, u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
| 27802 | |
| 27803 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
| 27804 | AT_SYMLINK_NOFOLLOW. |
| 27805 | |
| 27806 | [EBADF] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
| 27807 | argument is neither AT_FDCWD nor a valid file |
| 27808 | descriptor. |
| 27809 | |
| 27810 | [ENOTDIR] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
| 27811 | argument is a valid file descriptor but it does not |
| 27812 | reference a directory. |
| 27813 | |
| 27814 | [EACCES] The _\bf_\bi_\bl_\be argument specifies a relative path but search |
| 27815 | permission is denied for the directory which the _\bf_\bd |
| 27816 | file descriptor references. |
| 27817 | |
| 27818 | f\bfu\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\ben\bns\bs() will fail if: |
| 27819 | |
| 27820 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
| 27821 | |
| 27822 | [EACCES] The _\bt_\bi_\bm_\be_\bs argument is NULL and the effective user ID |
| 27823 | of the process does not match the owner of the file, |
| 27824 | and is not the superuser, and write access is denied. |
| 27825 | |
| 27826 | [EFAULT] _\bt_\bi_\bm_\be_\bs points outside the process's allocated address |
| 27827 | space. |
| 27828 | |
| 27829 | [EIO] An I/O error occurred while reading or writing the |
| 27830 | affected inode. |
| 27831 | |
| 27832 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
| 27833 | process's effective user ID does not match the owner |
| 27834 | of the file and is not the superuser. |
| 27835 | |
| 27836 | [EROFS] The file system containing the file is mounted read- |
| 27837 | only. |
| 27838 | |
| 27839 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 27840 | clock_gettime(2), stat(2), utime(3) |
| 27841 | |
| 27842 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 27843 | The u\but\bti\bim\bme\bes\bs(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), and f\bfu\but\bti\bim\bme\ben\bns\bs() functions conform to IEEE Std |
| 27844 | 1003.1-2008 (``POSIX.1''). |
| 27845 | |
| 27846 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 27847 | The predecessors of u\but\bti\bim\bme\bes\bs() were s\bsm\bmd\bda\bat\bte\be() in Version 1 AT&T UNIX, |
| 27848 | m\bmd\bda\bat\bte\be() in Version 3 AT&T UNIX, and u\but\bti\bim\bme\be() in Version 7 AT&T UNIX; the |
| 27849 | latter first supported the concept of an access time in addition to the |
| 27850 | modification time. |
| 27851 | |
| 27852 | The u\but\bti\bim\bme\bes\bs() function call appeared in 4.2BSD. The f\bfu\but\bti\bim\bme\bes\bs() function |
| 27853 | call appeared in NetBSD 1.2. The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() function |
| 27854 | calls appeared in OpenBSD 5.0. |
| 27855 | |
| 27856 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 27857 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and |
| 27858 | f\bfu\but\bti\bim\bme\ben\bns\bs() shall mark the last file status change timestamp (i.e. |
| 27859 | _\bs_\bt_\b__\bc_\bt_\bi_\bm) for update upon successful completion. However, currently some |
| 27860 | filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the |
| 27861 | modification timestamp argument. |
| 27862 | |
| 27863 | N\bNA\bAM\bME\bE |
| 27864 | u\but\btr\bra\bac\bce\be - insert user record in ktrace log |
| 27865 | |
| 27866 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 27867 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 27868 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
| 27869 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 27870 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/k\bkt\btr\bra\bac\bce\be.\b.h\bh>\b> |
| 27871 | |
| 27872 | _\bi_\bn_\bt |
| 27873 | u\but\btr\bra\bac\bce\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\ba_\bb_\be_\bl, _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
| 27874 | |
| 27875 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 27876 | Adds a record to the process trace with information supplied by the user. |
| 27877 | The record is identified by _\bl_\ba_\bb_\be_\bl and contains _\bl_\be_\bn bytes from memory |
| 27878 | pointed to by _\ba_\bd_\bd_\br. This call only has an effect if the calling process |
| 27879 | is being traced. |
| 27880 | |
| 27881 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 27882 | Upon successful completion, the value 0 is returned; otherwise the |
| 27883 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
| 27884 | error. |
| 27885 | |
| 27886 | E\bER\bRR\bRO\bOR\bRS\bS |
| 27887 | [ENOSYS] The currently running kernel was compiled without |
| 27888 | ktrace(2) support (option KTRACE). |
| 27889 | |
| 27890 | [ENAMETOOLONG] The length of the _\bl_\ba_\bb_\be_\bl string was longer than |
| 27891 | KTR_USER_MAXIDLEN-1. |
| 27892 | |
| 27893 | [EINVAL] The specified data length _\bl_\be_\bn was bigger than |
| 27894 | KTR_USER_MAXLEN. |
| 27895 | |
| 27896 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 27897 | kdump(1), ktrace(1), ktrace(2), options(4) |
| 27898 | |
| 27899 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 27900 | The u\but\btr\bra\bac\bce\be() system call first appeared in FreeBSD 2.2. It was added to |
| 27901 | OpenBSD in OpenBSD 5.4. The _\bl_\ba_\bb_\be_\bl argument is an extension. |
| 27902 | |
| 27903 | N\bNA\bAM\bME\bE |
| 27904 | v\bvf\bfo\bor\brk\bk - spawn new process and block parent |
| 27905 | |
| 27906 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 27907 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 27908 | |
| 27909 | _\bp_\bi_\bd_\b__\bt |
| 27910 | v\bvf\bfo\bor\brk\bk(_\bv_\bo_\bi_\bd); |
| 27911 | |
| 27912 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 27913 | v\bvf\bfo\bor\brk\bk() was originally used to create new processes without fully copying |
| 27914 | the address space of the old process, which is horrendously inefficient |
| 27915 | in a paged environment. It was useful when the purpose of fork(2) would |
| 27916 | have been to create a new system context for an execve(2). Since fork(2) |
| 27917 | is now efficient, even in the above case, the need for v\bvf\bfo\bor\brk\bk() has |
| 27918 | diminished. v\bvf\bfo\bor\brk\bk() differs from fork(2) in that the parent is suspended |
| 27919 | until the child makes a call to execve(2) or an exit (either by a call to |
| 27920 | _exit(2) or abnormally). In addition, fork handlers established using |
| 27921 | pthread_atfork(3) are not called when a multithreaded program calls |
| 27922 | v\bvf\bfo\bor\brk\bk(). |
| 27923 | |
| 27924 | v\bvf\bfo\bor\brk\bk() returns 0 in the child's context and (later) the PID of the child |
| 27925 | in the parent's context. |
| 27926 | |
| 27927 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 27928 | Same as for fork(2). |
| 27929 | |
| 27930 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 27931 | execve(2), fork(2), sigaction(2), wait(2) |
| 27932 | |
| 27933 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 27934 | The v\bvf\bfo\bor\brk\bk() function call appeared in 2.9BSD with the additional |
| 27935 | semantics that the child process ran in the memory of the parent until it |
| 27936 | called execve(2) or exited. That sharing of memory was removed in |
| 27937 | 4.4BSD, leaving just the semantics of blocking the parent until the child |
| 27938 | calls execve(2) or exits. On many other systems the original behavior |
| 27939 | has been restored, making this interface particularly unportable. |
| 27940 | |
| 27941 | B\bBU\bUG\bGS\bS |
| 27942 | To avoid a possible deadlock situation, processes that are children in |
| 27943 | the middle of a v\bvf\bfo\bor\brk\bk() are never sent SIGTTOU or SIGTTIN signals; |
| 27944 | rather, output or ioctl(2) calls are allowed and input attempts result in |
| 27945 | an end-of-file indication. |
| 27946 | |
| 27947 | N\bNA\bAM\bME\bE |
| 27948 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 27949 | |
| 27950 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 27951 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 27952 | |
| 27953 | _\bp_\bi_\bd_\b__\bt |
| 27954 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 27955 | |
| 27956 | _\bp_\bi_\bd_\b__\bt |
| 27957 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 27958 | |
| 27959 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 27960 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 27961 | |
| 27962 | _\bp_\bi_\bd_\b__\bt |
| 27963 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 27964 | |
| 27965 | _\bp_\bi_\bd_\b__\bt |
| 27966 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 27967 | |
| 27968 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 27969 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 27970 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 27971 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 27972 | area, if non-zero, is filled in with termination information about the |
| 27973 | process that exited (see below). |
| 27974 | |
| 27975 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 27976 | to wait for certain child processes, that need resource utilization |
| 27977 | statistics accumulated by child processes, or that require options. The |
| 27978 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 27979 | |
| 27980 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 27981 | wait. The following symbolic constants are currently defined in |
| 27982 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 27983 | |
| 27984 | #define WAIT_ANY (-1) /* any process */ |
| 27985 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 27986 | |
| 27987 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 27988 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 27989 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 27990 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 27991 | call waits for any process whose process group ID equals the absolute |
| 27992 | value of _\bw_\bp_\bi_\bd. |
| 27993 | |
| 27994 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 27995 | bitwise OR of zero or more of the following values: |
| 27996 | |
| 27997 | WCONTINUED Causes status to be reported for stopped child processes that |
| 27998 | have been continued by receipt of a SIGCONT signal. |
| 27999 | |
| 28000 | WNOHANG Indicates that the call should not block if there are no |
| 28001 | processes that wish to report status. |
| 28002 | |
| 28003 | WUNTRACED If set, children of the current process that are stopped due |
| 28004 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 28005 | their status reported. |
| 28006 | |
| 28007 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 28008 | process and all its children is returned (this information is currently |
| 28009 | not available for stopped processes). |
| 28010 | |
| 28011 | When the WNOHANG option is specified and no processes wish to report |
| 28012 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 28013 | |
| 28014 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 28015 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 28016 | |
| 28017 | The following macros may be used to test the manner of exit of the |
| 28018 | process. One of the first three macros will evaluate to a non-zero |
| 28019 | (true) value: |
| 28020 | |
| 28021 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28022 | True if the process has not terminated, and has continued after a |
| 28023 | job control stop. This macro can be true only if the wait call |
| 28024 | specified the WCONTINUED option. |
| 28025 | |
| 28026 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28027 | True if the process terminated normally by a call to _exit(2) or |
| 28028 | exit(3). |
| 28029 | |
| 28030 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28031 | True if the process terminated due to receipt of a signal. |
| 28032 | |
| 28033 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28034 | True if the process has not terminated, but has stopped and can |
| 28035 | be restarted. This macro can be true only if the wait call |
| 28036 | specified the WUNTRACED option or if the child process is being |
| 28037 | traced (see ptrace(2)). |
| 28038 | |
| 28039 | Depending on the values of those macros, the following macros produce the |
| 28040 | remaining status information about the child process: |
| 28041 | |
| 28042 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28043 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 28044 | of the argument passed to _exit(2) or exit(3) by the child. |
| 28045 | |
| 28046 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28047 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 28048 | signal that caused the termination of the process. |
| 28049 | |
| 28050 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28051 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 28052 | termination of the process was accompanied by the creation of a |
| 28053 | core file containing an image of the process when the signal was |
| 28054 | received. |
| 28055 | |
| 28056 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28057 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 28058 | signal that caused the process to stop. |
| 28059 | |
| 28060 | N\bNO\bOT\bTE\bES\bS |
| 28061 | See sigaction(2) for a list of termination signals. A status of 0 |
| 28062 | indicates normal termination. |
| 28063 | |
| 28064 | If a parent process terminates without waiting for all of its child |
| 28065 | processes to terminate, the remaining child processes are assigned the |
| 28066 | parent process 1 ID (the init process ID). |
| 28067 | |
| 28068 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 28069 | may be interrupted or restarted when the signal-catching routine returns, |
| 28070 | depending on the options in effect for the signal; for further |
| 28071 | information, see siginterrupt(3). |
| 28072 | |
| 28073 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 28074 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 28075 | process ID of the child is returned to the calling process. Otherwise, a |
| 28076 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 28077 | |
| 28078 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 28079 | child process, the process ID of the child is returned to the calling |
| 28080 | process. If there are no children not previously awaited, -1 is returned |
| 28081 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 28082 | are no stopped or exited children, 0 is returned. If an error is |
| 28083 | detected or a caught signal aborts the call, a value of -1 is returned |
| 28084 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 28085 | |
| 28086 | E\bER\bRR\bRO\bOR\bRS\bS |
| 28087 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 28088 | |
| 28089 | [ECHILD] The calling process has no existing unwaited-for child |
| 28090 | processes. |
| 28091 | |
| 28092 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 28093 | address. (May not be detected before exit of a child |
| 28094 | process.) |
| 28095 | |
| 28096 | [EINTR] The call was interrupted by a caught signal, or the |
| 28097 | signal did not have the SA_RESTART flag set. |
| 28098 | |
| 28099 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 28100 | argument. |
| 28101 | |
| 28102 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 28103 | _exit(2), sigaction(2), exit(3) |
| 28104 | |
| 28105 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 28106 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 28107 | (``POSIX.1''). |
| 28108 | |
| 28109 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 28110 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 28111 | specification. |
| 28112 | |
| 28113 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 28114 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 28115 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 28116 | first appeared in 4BSD, but the final calling convention was only |
| 28117 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 28118 | appeared in 4.3BSD-Reno. |
| 28119 | |
| 28120 | N\bNA\bAM\bME\bE |
| 28121 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 28122 | |
| 28123 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 28124 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 28125 | |
| 28126 | _\bp_\bi_\bd_\b__\bt |
| 28127 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 28128 | |
| 28129 | _\bp_\bi_\bd_\b__\bt |
| 28130 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 28131 | |
| 28132 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 28133 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 28134 | |
| 28135 | _\bp_\bi_\bd_\b__\bt |
| 28136 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 28137 | |
| 28138 | _\bp_\bi_\bd_\b__\bt |
| 28139 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 28140 | |
| 28141 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 28142 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 28143 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 28144 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 28145 | area, if non-zero, is filled in with termination information about the |
| 28146 | process that exited (see below). |
| 28147 | |
| 28148 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 28149 | to wait for certain child processes, that need resource utilization |
| 28150 | statistics accumulated by child processes, or that require options. The |
| 28151 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 28152 | |
| 28153 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 28154 | wait. The following symbolic constants are currently defined in |
| 28155 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 28156 | |
| 28157 | #define WAIT_ANY (-1) /* any process */ |
| 28158 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 28159 | |
| 28160 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 28161 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 28162 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 28163 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 28164 | call waits for any process whose process group ID equals the absolute |
| 28165 | value of _\bw_\bp_\bi_\bd. |
| 28166 | |
| 28167 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 28168 | bitwise OR of zero or more of the following values: |
| 28169 | |
| 28170 | WCONTINUED Causes status to be reported for stopped child processes that |
| 28171 | have been continued by receipt of a SIGCONT signal. |
| 28172 | |
| 28173 | WNOHANG Indicates that the call should not block if there are no |
| 28174 | processes that wish to report status. |
| 28175 | |
| 28176 | WUNTRACED If set, children of the current process that are stopped due |
| 28177 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 28178 | their status reported. |
| 28179 | |
| 28180 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 28181 | process and all its children is returned (this information is currently |
| 28182 | not available for stopped processes). |
| 28183 | |
| 28184 | When the WNOHANG option is specified and no processes wish to report |
| 28185 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 28186 | |
| 28187 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 28188 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 28189 | |
| 28190 | The following macros may be used to test the manner of exit of the |
| 28191 | process. One of the first three macros will evaluate to a non-zero |
| 28192 | (true) value: |
| 28193 | |
| 28194 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28195 | True if the process has not terminated, and has continued after a |
| 28196 | job control stop. This macro can be true only if the wait call |
| 28197 | specified the WCONTINUED option. |
| 28198 | |
| 28199 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28200 | True if the process terminated normally by a call to _exit(2) or |
| 28201 | exit(3). |
| 28202 | |
| 28203 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28204 | True if the process terminated due to receipt of a signal. |
| 28205 | |
| 28206 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28207 | True if the process has not terminated, but has stopped and can |
| 28208 | be restarted. This macro can be true only if the wait call |
| 28209 | specified the WUNTRACED option or if the child process is being |
| 28210 | traced (see ptrace(2)). |
| 28211 | |
| 28212 | Depending on the values of those macros, the following macros produce the |
| 28213 | remaining status information about the child process: |
| 28214 | |
| 28215 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28216 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 28217 | of the argument passed to _exit(2) or exit(3) by the child. |
| 28218 | |
| 28219 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28220 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 28221 | signal that caused the termination of the process. |
| 28222 | |
| 28223 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28224 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 28225 | termination of the process was accompanied by the creation of a |
| 28226 | core file containing an image of the process when the signal was |
| 28227 | received. |
| 28228 | |
| 28229 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28230 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 28231 | signal that caused the process to stop. |
| 28232 | |
| 28233 | N\bNO\bOT\bTE\bES\bS |
| 28234 | See sigaction(2) for a list of termination signals. A status of 0 |
| 28235 | indicates normal termination. |
| 28236 | |
| 28237 | If a parent process terminates without waiting for all of its child |
| 28238 | processes to terminate, the remaining child processes are assigned the |
| 28239 | parent process 1 ID (the init process ID). |
| 28240 | |
| 28241 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 28242 | may be interrupted or restarted when the signal-catching routine returns, |
| 28243 | depending on the options in effect for the signal; for further |
| 28244 | information, see siginterrupt(3). |
| 28245 | |
| 28246 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 28247 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 28248 | process ID of the child is returned to the calling process. Otherwise, a |
| 28249 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 28250 | |
| 28251 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 28252 | child process, the process ID of the child is returned to the calling |
| 28253 | process. If there are no children not previously awaited, -1 is returned |
| 28254 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 28255 | are no stopped or exited children, 0 is returned. If an error is |
| 28256 | detected or a caught signal aborts the call, a value of -1 is returned |
| 28257 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 28258 | |
| 28259 | E\bER\bRR\bRO\bOR\bRS\bS |
| 28260 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 28261 | |
| 28262 | [ECHILD] The calling process has no existing unwaited-for child |
| 28263 | processes. |
| 28264 | |
| 28265 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 28266 | address. (May not be detected before exit of a child |
| 28267 | process.) |
| 28268 | |
| 28269 | [EINTR] The call was interrupted by a caught signal, or the |
| 28270 | signal did not have the SA_RESTART flag set. |
| 28271 | |
| 28272 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 28273 | argument. |
| 28274 | |
| 28275 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 28276 | _exit(2), sigaction(2), exit(3) |
| 28277 | |
| 28278 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 28279 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 28280 | (``POSIX.1''). |
| 28281 | |
| 28282 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 28283 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 28284 | specification. |
| 28285 | |
| 28286 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 28287 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 28288 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 28289 | first appeared in 4BSD, but the final calling convention was only |
| 28290 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 28291 | appeared in 4.3BSD-Reno. |
| 28292 | |
| 28293 | N\bNA\bAM\bME\bE |
| 28294 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 28295 | |
| 28296 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 28297 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 28298 | |
| 28299 | _\bp_\bi_\bd_\b__\bt |
| 28300 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 28301 | |
| 28302 | _\bp_\bi_\bd_\b__\bt |
| 28303 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 28304 | |
| 28305 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 28306 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 28307 | |
| 28308 | _\bp_\bi_\bd_\b__\bt |
| 28309 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 28310 | |
| 28311 | _\bp_\bi_\bd_\b__\bt |
| 28312 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 28313 | |
| 28314 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 28315 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 28316 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 28317 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 28318 | area, if non-zero, is filled in with termination information about the |
| 28319 | process that exited (see below). |
| 28320 | |
| 28321 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 28322 | to wait for certain child processes, that need resource utilization |
| 28323 | statistics accumulated by child processes, or that require options. The |
| 28324 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 28325 | |
| 28326 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 28327 | wait. The following symbolic constants are currently defined in |
| 28328 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 28329 | |
| 28330 | #define WAIT_ANY (-1) /* any process */ |
| 28331 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 28332 | |
| 28333 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 28334 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 28335 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 28336 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 28337 | call waits for any process whose process group ID equals the absolute |
| 28338 | value of _\bw_\bp_\bi_\bd. |
| 28339 | |
| 28340 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 28341 | bitwise OR of zero or more of the following values: |
| 28342 | |
| 28343 | WCONTINUED Causes status to be reported for stopped child processes that |
| 28344 | have been continued by receipt of a SIGCONT signal. |
| 28345 | |
| 28346 | WNOHANG Indicates that the call should not block if there are no |
| 28347 | processes that wish to report status. |
| 28348 | |
| 28349 | WUNTRACED If set, children of the current process that are stopped due |
| 28350 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 28351 | their status reported. |
| 28352 | |
| 28353 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 28354 | process and all its children is returned (this information is currently |
| 28355 | not available for stopped processes). |
| 28356 | |
| 28357 | When the WNOHANG option is specified and no processes wish to report |
| 28358 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 28359 | |
| 28360 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 28361 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 28362 | |
| 28363 | The following macros may be used to test the manner of exit of the |
| 28364 | process. One of the first three macros will evaluate to a non-zero |
| 28365 | (true) value: |
| 28366 | |
| 28367 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28368 | True if the process has not terminated, and has continued after a |
| 28369 | job control stop. This macro can be true only if the wait call |
| 28370 | specified the WCONTINUED option. |
| 28371 | |
| 28372 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28373 | True if the process terminated normally by a call to _exit(2) or |
| 28374 | exit(3). |
| 28375 | |
| 28376 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28377 | True if the process terminated due to receipt of a signal. |
| 28378 | |
| 28379 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28380 | True if the process has not terminated, but has stopped and can |
| 28381 | be restarted. This macro can be true only if the wait call |
| 28382 | specified the WUNTRACED option or if the child process is being |
| 28383 | traced (see ptrace(2)). |
| 28384 | |
| 28385 | Depending on the values of those macros, the following macros produce the |
| 28386 | remaining status information about the child process: |
| 28387 | |
| 28388 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28389 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 28390 | of the argument passed to _exit(2) or exit(3) by the child. |
| 28391 | |
| 28392 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28393 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 28394 | signal that caused the termination of the process. |
| 28395 | |
| 28396 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28397 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 28398 | termination of the process was accompanied by the creation of a |
| 28399 | core file containing an image of the process when the signal was |
| 28400 | received. |
| 28401 | |
| 28402 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28403 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 28404 | signal that caused the process to stop. |
| 28405 | |
| 28406 | N\bNO\bOT\bTE\bES\bS |
| 28407 | See sigaction(2) for a list of termination signals. A status of 0 |
| 28408 | indicates normal termination. |
| 28409 | |
| 28410 | If a parent process terminates without waiting for all of its child |
| 28411 | processes to terminate, the remaining child processes are assigned the |
| 28412 | parent process 1 ID (the init process ID). |
| 28413 | |
| 28414 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 28415 | may be interrupted or restarted when the signal-catching routine returns, |
| 28416 | depending on the options in effect for the signal; for further |
| 28417 | information, see siginterrupt(3). |
| 28418 | |
| 28419 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 28420 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 28421 | process ID of the child is returned to the calling process. Otherwise, a |
| 28422 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 28423 | |
| 28424 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 28425 | child process, the process ID of the child is returned to the calling |
| 28426 | process. If there are no children not previously awaited, -1 is returned |
| 28427 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 28428 | are no stopped or exited children, 0 is returned. If an error is |
| 28429 | detected or a caught signal aborts the call, a value of -1 is returned |
| 28430 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 28431 | |
| 28432 | E\bER\bRR\bRO\bOR\bRS\bS |
| 28433 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 28434 | |
| 28435 | [ECHILD] The calling process has no existing unwaited-for child |
| 28436 | processes. |
| 28437 | |
| 28438 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 28439 | address. (May not be detected before exit of a child |
| 28440 | process.) |
| 28441 | |
| 28442 | [EINTR] The call was interrupted by a caught signal, or the |
| 28443 | signal did not have the SA_RESTART flag set. |
| 28444 | |
| 28445 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 28446 | argument. |
| 28447 | |
| 28448 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 28449 | _exit(2), sigaction(2), exit(3) |
| 28450 | |
| 28451 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 28452 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 28453 | (``POSIX.1''). |
| 28454 | |
| 28455 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 28456 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 28457 | specification. |
| 28458 | |
| 28459 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 28460 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 28461 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 28462 | first appeared in 4BSD, but the final calling convention was only |
| 28463 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 28464 | appeared in 4.3BSD-Reno. |
| 28465 | |
| 28466 | N\bNA\bAM\bME\bE |
| 28467 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
| 28468 | |
| 28469 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 28470 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 28471 | |
| 28472 | _\bp_\bi_\bd_\b__\bt |
| 28473 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
| 28474 | |
| 28475 | _\bp_\bi_\bd_\b__\bt |
| 28476 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
| 28477 | |
| 28478 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
| 28479 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
| 28480 | |
| 28481 | _\bp_\bi_\bd_\b__\bt |
| 28482 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 28483 | |
| 28484 | _\bp_\bi_\bd_\b__\bt |
| 28485 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
| 28486 | |
| 28487 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 28488 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
| 28489 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
| 28490 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
| 28491 | area, if non-zero, is filled in with termination information about the |
| 28492 | process that exited (see below). |
| 28493 | |
| 28494 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
| 28495 | to wait for certain child processes, that need resource utilization |
| 28496 | statistics accumulated by child processes, or that require options. The |
| 28497 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
| 28498 | |
| 28499 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
| 28500 | wait. The following symbolic constants are currently defined in |
| 28501 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
| 28502 | |
| 28503 | #define WAIT_ANY (-1) /* any process */ |
| 28504 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
| 28505 | |
| 28506 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
| 28507 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
| 28508 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
| 28509 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
| 28510 | call waits for any process whose process group ID equals the absolute |
| 28511 | value of _\bw_\bp_\bi_\bd. |
| 28512 | |
| 28513 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
| 28514 | bitwise OR of zero or more of the following values: |
| 28515 | |
| 28516 | WCONTINUED Causes status to be reported for stopped child processes that |
| 28517 | have been continued by receipt of a SIGCONT signal. |
| 28518 | |
| 28519 | WNOHANG Indicates that the call should not block if there are no |
| 28520 | processes that wish to report status. |
| 28521 | |
| 28522 | WUNTRACED If set, children of the current process that are stopped due |
| 28523 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
| 28524 | their status reported. |
| 28525 | |
| 28526 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
| 28527 | process and all its children is returned (this information is currently |
| 28528 | not available for stopped processes). |
| 28529 | |
| 28530 | When the WNOHANG option is specified and no processes wish to report |
| 28531 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
| 28532 | |
| 28533 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
| 28534 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
| 28535 | |
| 28536 | The following macros may be used to test the manner of exit of the |
| 28537 | process. One of the first three macros will evaluate to a non-zero |
| 28538 | (true) value: |
| 28539 | |
| 28540 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28541 | True if the process has not terminated, and has continued after a |
| 28542 | job control stop. This macro can be true only if the wait call |
| 28543 | specified the WCONTINUED option. |
| 28544 | |
| 28545 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28546 | True if the process terminated normally by a call to _exit(2) or |
| 28547 | exit(3). |
| 28548 | |
| 28549 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28550 | True if the process terminated due to receipt of a signal. |
| 28551 | |
| 28552 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28553 | True if the process has not terminated, but has stopped and can |
| 28554 | be restarted. This macro can be true only if the wait call |
| 28555 | specified the WUNTRACED option or if the child process is being |
| 28556 | traced (see ptrace(2)). |
| 28557 | |
| 28558 | Depending on the values of those macros, the following macros produce the |
| 28559 | remaining status information about the child process: |
| 28560 | |
| 28561 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28562 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
| 28563 | of the argument passed to _exit(2) or exit(3) by the child. |
| 28564 | |
| 28565 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28566 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 28567 | signal that caused the termination of the process. |
| 28568 | |
| 28569 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28570 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
| 28571 | termination of the process was accompanied by the creation of a |
| 28572 | core file containing an image of the process when the signal was |
| 28573 | received. |
| 28574 | |
| 28575 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
| 28576 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
| 28577 | signal that caused the process to stop. |
| 28578 | |
| 28579 | N\bNO\bOT\bTE\bES\bS |
| 28580 | See sigaction(2) for a list of termination signals. A status of 0 |
| 28581 | indicates normal termination. |
| 28582 | |
| 28583 | If a parent process terminates without waiting for all of its child |
| 28584 | processes to terminate, the remaining child processes are assigned the |
| 28585 | parent process 1 ID (the init process ID). |
| 28586 | |
| 28587 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
| 28588 | may be interrupted or restarted when the signal-catching routine returns, |
| 28589 | depending on the options in effect for the signal; for further |
| 28590 | information, see siginterrupt(3). |
| 28591 | |
| 28592 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 28593 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
| 28594 | process ID of the child is returned to the calling process. Otherwise, a |
| 28595 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 28596 | |
| 28597 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
| 28598 | child process, the process ID of the child is returned to the calling |
| 28599 | process. If there are no children not previously awaited, -1 is returned |
| 28600 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
| 28601 | are no stopped or exited children, 0 is returned. If an error is |
| 28602 | detected or a caught signal aborts the call, a value of -1 is returned |
| 28603 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
| 28604 | |
| 28605 | E\bER\bRR\bRO\bOR\bRS\bS |
| 28606 | w\bwa\bai\bit\bt() will fail and return immediately if: |
| 28607 | |
| 28608 | [ECHILD] The calling process has no existing unwaited-for child |
| 28609 | processes. |
| 28610 | |
| 28611 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
| 28612 | address. (May not be detected before exit of a child |
| 28613 | process.) |
| 28614 | |
| 28615 | [EINTR] The call was interrupted by a caught signal, or the |
| 28616 | signal did not have the SA_RESTART flag set. |
| 28617 | |
| 28618 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
| 28619 | argument. |
| 28620 | |
| 28621 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 28622 | _exit(2), sigaction(2), exit(3) |
| 28623 | |
| 28624 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 28625 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
| 28626 | (``POSIX.1''). |
| 28627 | |
| 28628 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
| 28629 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
| 28630 | specification. |
| 28631 | |
| 28632 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 28633 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
| 28634 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
| 28635 | first appeared in 4BSD, but the final calling convention was only |
| 28636 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
| 28637 | appeared in 4.3BSD-Reno. |
| 28638 | |
| 28639 | N\bNA\bAM\bME\bE |
| 28640 | w\bwr\bri\bit\bte\be, w\bwr\bri\bit\bte\bev\bv, p\bpw\bwr\bri\bit\bte\be, p\bpw\bwr\bri\bit\bte\bev\bv - write output |
| 28641 | |
| 28642 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 28643 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 28644 | |
| 28645 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 28646 | w\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 28647 | |
| 28648 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 28649 | p\bpw\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 28650 | |
| 28651 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 28652 | |
| 28653 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 28654 | w\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
| 28655 | |
| 28656 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 28657 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 28658 | |
| 28659 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 28660 | p\bpw\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 28661 | |
| 28662 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 28663 | w\bwr\bri\bit\bte\be() attempts to write _\bn_\bb_\by_\bt_\be_\bs of data to the object referenced by the |
| 28664 | descriptor _\bd from the buffer pointed to by _\bb_\bu_\bf. w\bwr\bri\bit\bte\bev\bv() performs the |
| 28665 | same action, but gathers the output data from the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
| 28666 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
| 28667 | iov[iovcnt-1]. p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() perform the same functions, but |
| 28668 | write to the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the |
| 28669 | file pointer. |
| 28670 | |
| 28671 | For w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
| 28672 | |
| 28673 | struct iovec { |
| 28674 | void *iov_base; |
| 28675 | size_t iov_len; |
| 28676 | }; |
| 28677 | |
| 28678 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
| 28679 | memory from which data should be written. w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will |
| 28680 | always write a complete area before proceeding to the next. |
| 28681 | |
| 28682 | On objects capable of seeking, the w\bwr\bri\bit\bte\be() starts at a position given by |
| 28683 | the pointer associated with _\bd (see lseek(2)). Upon return from w\bwr\bri\bit\bte\be(), |
| 28684 | the pointer is incremented by the number of bytes which were written. If |
| 28685 | a file was opened with the O_APPEND flag (see open(2)), calls to w\bwr\bri\bit\bte\be() |
| 28686 | or w\bwr\bri\bit\bte\bev\bv() will automatically set the pointer to the end of the file |
| 28687 | before writing. |
| 28688 | |
| 28689 | Objects that are not capable of seeking always write from the current |
| 28690 | position. The value of the pointer associated with such an object is |
| 28691 | undefined. |
| 28692 | |
| 28693 | If the real user is not the superuser, then w\bwr\bri\bit\bte\be() clears the set-user- |
| 28694 | ID bit on a file. This prevents penetration of system security by a user |
| 28695 | who ``captures'' a writable set-user-ID file owned by the superuser. |
| 28696 | |
| 28697 | If w\bwr\bri\bit\bte\be() succeeds it will update the st_ctime and st_mtime fields of |
| 28698 | the file's meta-data (see stat(2)). |
| 28699 | |
| 28700 | When using non-blocking I/O on objects such as sockets that are subject |
| 28701 | to flow control, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may write fewer bytes than |
| 28702 | requested; the return value must be noted, and the remainder of the |
| 28703 | operation should be retried when possible. |
| 28704 | |
| 28705 | Note that w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
| 28706 | the constant IOV_MAX. |
| 28707 | |
| 28708 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 28709 | Upon successful completion the number of bytes which were written is |
| 28710 | returned. Otherwise, a -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
| 28711 | set to indicate the error. |
| 28712 | |
| 28713 | E\bER\bRR\bRO\bOR\bRS\bS |
| 28714 | w\bwr\bri\bit\bte\be(), p\bpw\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\bev\bv() will fail and the file pointer |
| 28715 | will remain unchanged if: |
| 28716 | |
| 28717 | [EBADF] _\bd is not a valid descriptor open for writing. |
| 28718 | |
| 28719 | [EFBIG] An attempt was made to write a file that exceeds the |
| 28720 | process's file size limit or the maximum file size. |
| 28721 | |
| 28722 | [ENOSPC] There is no free space remaining on the file system |
| 28723 | containing the file. |
| 28724 | |
| 28725 | [EDQUOT] The user's quota of disk blocks on the file system |
| 28726 | containing the file has been exhausted. |
| 28727 | |
| 28728 | [EINTR] A write to a slow device (i.e. one that might block |
| 28729 | for an arbitrary amount of time) was interrupted by |
| 28730 | the delivery of a signal before any data could be |
| 28731 | written. |
| 28732 | |
| 28733 | [EIO] An I/O error occurred while reading from or writing to |
| 28734 | the file system. |
| 28735 | |
| 28736 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 28737 | address space. |
| 28738 | |
| 28739 | In addition, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may return the following errors: |
| 28740 | |
| 28741 | [EPIPE] An attempt is made to write to a pipe that is not open |
| 28742 | for reading by any process. |
| 28743 | |
| 28744 | [EPIPE] An attempt is made to write to a socket of type |
| 28745 | SOCK_STREAM that is not connected to a peer socket. |
| 28746 | |
| 28747 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
| 28748 | could be written immediately. |
| 28749 | |
| 28750 | [ENETDOWN] The destination address specified a network that is |
| 28751 | down. |
| 28752 | |
| 28753 | [EDESTADDRREQ] The destination is no longer available when writing to |
| 28754 | a UNIX-domain datagram socket on which connect(2) had |
| 28755 | been used to set a destination address. |
| 28756 | |
| 28757 | [EIO] The process is a member of a background process |
| 28758 | attempting to write to its controlling terminal, |
| 28759 | TOSTOP is set on the terminal, the process isn't |
| 28760 | ignoring the SIGTTOUT signal and the thread isn't |
| 28761 | blocking the SIGTTOUT signal, and either the process |
| 28762 | was created with vfork(2) and hasn't successfully |
| 28763 | executed one of the exec functions or the process |
| 28764 | group is orphaned. |
| 28765 | |
| 28766 | w\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\be() may return the following error: |
| 28767 | |
| 28768 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
| 28769 | |
| 28770 | p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() may return the following error: |
| 28771 | |
| 28772 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
| 28773 | |
| 28774 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
| 28775 | |
| 28776 | w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() may return one of the following errors: |
| 28777 | |
| 28778 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
| 28779 | IOV_MAX. |
| 28780 | |
| 28781 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
| 28782 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 28783 | |
| 28784 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
| 28785 | address space. |
| 28786 | |
| 28787 | [ENOBUFS] The system lacked sufficient buffer space or a queue |
| 28788 | was full. |
| 28789 | |
| 28790 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 28791 | fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) |
| 28792 | |
| 28793 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 28794 | The w\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\be() functions conform to IEEE Std |
| 28795 | 1003.1-2008 (``POSIX.1''). |
| 28796 | |
| 28797 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 28798 | The p\bpw\bwr\bri\bit\bte\bev\bv() function call appeared in OpenBSD 2.7. The p\bpw\bwr\bri\bit\bte\be() |
| 28799 | function call appeared in AT&T System V Release 4 UNIX. The w\bwr\bri\bit\bte\bev\bv() |
| 28800 | function call appeared in 4.2BSD. The w\bwr\bri\bit\bte\be() function call appeared in |
| 28801 | Version 2 AT&T UNIX. |
| 28802 | |
| 28803 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 28804 | Error checks should explicitly test for -1. Code such as |
| 28805 | |
| 28806 | while ((nr = write(fd, buf, sizeof(buf))) > 0) |
| 28807 | |
| 28808 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
| 28809 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
| 28810 | error-free w\bwr\bri\bit\bte\be() may appear as a negative number distinct from -1. |
| 28811 | Proper loops should use |
| 28812 | |
| 28813 | while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) |
| 28814 | |
| 28815 | N\bNA\bAM\bME\bE |
| 28816 | w\bwr\bri\bit\bte\be, w\bwr\bri\bit\bte\bev\bv, p\bpw\bwr\bri\bit\bte\be, p\bpw\bwr\bri\bit\bte\bev\bv - write output |
| 28817 | |
| 28818 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 28819 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
| 28820 | |
| 28821 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 28822 | w\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
| 28823 | |
| 28824 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 28825 | p\bpw\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 28826 | |
| 28827 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 28828 | |
| 28829 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 28830 | w\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
| 28831 | |
| 28832 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
| 28833 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
| 28834 | |
| 28835 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
| 28836 | p\bpw\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
| 28837 | |
| 28838 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 28839 | w\bwr\bri\bit\bte\be() attempts to write _\bn_\bb_\by_\bt_\be_\bs of data to the object referenced by the |
| 28840 | descriptor _\bd from the buffer pointed to by _\bb_\bu_\bf. w\bwr\bri\bit\bte\bev\bv() performs the |
| 28841 | same action, but gathers the output data from the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
| 28842 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
| 28843 | iov[iovcnt-1]. p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() perform the same functions, but |
| 28844 | write to the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the |
| 28845 | file pointer. |
| 28846 | |
| 28847 | For w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
| 28848 | |
| 28849 | struct iovec { |
| 28850 | void *iov_base; |
| 28851 | size_t iov_len; |
| 28852 | }; |
| 28853 | |
| 28854 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
| 28855 | memory from which data should be written. w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will |
| 28856 | always write a complete area before proceeding to the next. |
| 28857 | |
| 28858 | On objects capable of seeking, the w\bwr\bri\bit\bte\be() starts at a position given by |
| 28859 | the pointer associated with _\bd (see lseek(2)). Upon return from w\bwr\bri\bit\bte\be(), |
| 28860 | the pointer is incremented by the number of bytes which were written. If |
| 28861 | a file was opened with the O_APPEND flag (see open(2)), calls to w\bwr\bri\bit\bte\be() |
| 28862 | or w\bwr\bri\bit\bte\bev\bv() will automatically set the pointer to the end of the file |
| 28863 | before writing. |
| 28864 | |
| 28865 | Objects that are not capable of seeking always write from the current |
| 28866 | position. The value of the pointer associated with such an object is |
| 28867 | undefined. |
| 28868 | |
| 28869 | If the real user is not the superuser, then w\bwr\bri\bit\bte\be() clears the set-user- |
| 28870 | ID bit on a file. This prevents penetration of system security by a user |
| 28871 | who ``captures'' a writable set-user-ID file owned by the superuser. |
| 28872 | |
| 28873 | If w\bwr\bri\bit\bte\be() succeeds it will update the st_ctime and st_mtime fields of |
| 28874 | the file's meta-data (see stat(2)). |
| 28875 | |
| 28876 | When using non-blocking I/O on objects such as sockets that are subject |
| 28877 | to flow control, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may write fewer bytes than |
| 28878 | requested; the return value must be noted, and the remainder of the |
| 28879 | operation should be retried when possible. |
| 28880 | |
| 28881 | Note that w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
| 28882 | the constant IOV_MAX. |
| 28883 | |
| 28884 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 28885 | Upon successful completion the number of bytes which were written is |
| 28886 | returned. Otherwise, a -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
| 28887 | set to indicate the error. |
| 28888 | |
| 28889 | E\bER\bRR\bRO\bOR\bRS\bS |
| 28890 | w\bwr\bri\bit\bte\be(), p\bpw\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\bev\bv() will fail and the file pointer |
| 28891 | will remain unchanged if: |
| 28892 | |
| 28893 | [EBADF] _\bd is not a valid descriptor open for writing. |
| 28894 | |
| 28895 | [EFBIG] An attempt was made to write a file that exceeds the |
| 28896 | process's file size limit or the maximum file size. |
| 28897 | |
| 28898 | [ENOSPC] There is no free space remaining on the file system |
| 28899 | containing the file. |
| 28900 | |
| 28901 | [EDQUOT] The user's quota of disk blocks on the file system |
| 28902 | containing the file has been exhausted. |
| 28903 | |
| 28904 | [EINTR] A write to a slow device (i.e. one that might block |
| 28905 | for an arbitrary amount of time) was interrupted by |
| 28906 | the delivery of a signal before any data could be |
| 28907 | written. |
| 28908 | |
| 28909 | [EIO] An I/O error occurred while reading from or writing to |
| 28910 | the file system. |
| 28911 | |
| 28912 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
| 28913 | address space. |
| 28914 | |
| 28915 | In addition, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may return the following errors: |
| 28916 | |
| 28917 | [EPIPE] An attempt is made to write to a pipe that is not open |
| 28918 | for reading by any process. |
| 28919 | |
| 28920 | [EPIPE] An attempt is made to write to a socket of type |
| 28921 | SOCK_STREAM that is not connected to a peer socket. |
| 28922 | |
| 28923 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
| 28924 | could be written immediately. |
| 28925 | |
| 28926 | [ENETDOWN] The destination address specified a network that is |
| 28927 | down. |
| 28928 | |
| 28929 | [EDESTADDRREQ] The destination is no longer available when writing to |
| 28930 | a UNIX-domain datagram socket on which connect(2) had |
| 28931 | been used to set a destination address. |
| 28932 | |
| 28933 | [EIO] The process is a member of a background process |
| 28934 | attempting to write to its controlling terminal, |
| 28935 | TOSTOP is set on the terminal, the process isn't |
| 28936 | ignoring the SIGTTOUT signal and the thread isn't |
| 28937 | blocking the SIGTTOUT signal, and either the process |
| 28938 | was created with vfork(2) and hasn't successfully |
| 28939 | executed one of the exec functions or the process |
| 28940 | group is orphaned. |
| 28941 | |
| 28942 | w\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\be() may return the following error: |
| 28943 | |
| 28944 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
| 28945 | |
| 28946 | p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() may return the following error: |
| 28947 | |
| 28948 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
| 28949 | |
| 28950 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
| 28951 | |
| 28952 | w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() may return one of the following errors: |
| 28953 | |
| 28954 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
| 28955 | IOV_MAX. |
| 28956 | |
| 28957 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
| 28958 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
| 28959 | |
| 28960 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
| 28961 | address space. |
| 28962 | |
| 28963 | [ENOBUFS] The system lacked sufficient buffer space or a queue |
| 28964 | was full. |
| 28965 | |
| 28966 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 28967 | fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) |
| 28968 | |
| 28969 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 28970 | The w\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\be() functions conform to IEEE Std |
| 28971 | 1003.1-2008 (``POSIX.1''). |
| 28972 | |
| 28973 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 28974 | The p\bpw\bwr\bri\bit\bte\bev\bv() function call appeared in OpenBSD 2.7. The p\bpw\bwr\bri\bit\bte\be() |
| 28975 | function call appeared in AT&T System V Release 4 UNIX. The w\bwr\bri\bit\bte\bev\bv() |
| 28976 | function call appeared in 4.2BSD. The w\bwr\bri\bit\bte\be() function call appeared in |
| 28977 | Version 2 AT&T UNIX. |
| 28978 | |
| 28979 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
| 28980 | Error checks should explicitly test for -1. Code such as |
| 28981 | |
| 28982 | while ((nr = write(fd, buf, sizeof(buf))) > 0) |
| 28983 | |
| 28984 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
| 28985 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
| 28986 | error-free w\bwr\bri\bit\bte\be() may appear as a negative number distinct from -1. |
| 28987 | Proper loops should use |
| 28988 | |
| 28989 | while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) |
| 28990 | |
| 28991 | N\bNA\bAM\bME\bE |
| 28992 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf - drains the CPU write buffer |
| 28993 | |
| 28994 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 28995 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 28996 | |
| 28997 | _\bi_\bn_\bt |
| 28998 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf(); |
| 28999 | |
| 29000 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 29001 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf() will make sure that all the entries in the processor |
| 29002 | write buffer are written out to memory. |
| 29003 | |
| 29004 | Not all processors support this operation (currently only the SA110 |
| 29005 | does). Those processes that do not, treat this function as a null-op. |
| 29006 | |
| 29007 | E\bER\bRR\bRO\bOR\bRS\bS |
| 29008 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf() will never fail so will always return 0. |
| 29009 | |
| 29010 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 29011 | StrongARM Data Sheet |
| 29012 | |
| 29013 | N\bNA\bAM\bME\bE |
| 29014 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be - clean the CPU data cache and flush the CPU instruction |
| 29015 | cache |
| 29016 | |
| 29017 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 29018 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
| 29019 | |
| 29020 | _\bi_\bn_\bt |
| 29021 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be(_\bu_\b__\bi_\bn_\bt _\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bl_\be_\bn); |
| 29022 | |
| 29023 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 29024 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will make sure that all the entries in the processor |
| 29025 | instruction cache are synchronized with main memory and that any data in |
| 29026 | a write back cache has been cleaned. Some ARM processors (e.g. SA110) |
| 29027 | have separate instruction and data caches, thus any dynamically generated |
| 29028 | or modified code needs to be written back from any data caches to main |
| 29029 | memory and the instruction cache needs to be synchronized with main |
| 29030 | memory. |
| 29031 | |
| 29032 | On such processors, a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will clean the data cache and |
| 29033 | invalidate the processor instruction cache to force reloading from main |
| 29034 | memory. On processors that have a shared instruction and data cache and |
| 29035 | have a write through cache (e.g. ARM6), no action needs to be taken. |
| 29036 | |
| 29037 | The routine takes a start address _\ba_\bd_\bd_\br and a length _\bl_\be_\bn to describe the |
| 29038 | area of memory that needs to be cleaned and synchronized. |
| 29039 | |
| 29040 | E\bER\bRR\bRO\bOR\bRS\bS |
| 29041 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will never fail so will always return 0. |
| 29042 | |
| 29043 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
| 29044 | StrongARM Data Sheet |
| 29045 | |
| 29046 | OpenBSD 5.7 August 14, 2013 OpenBSD 5.7 |