bsd_man2_all

   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