1 # find /usr/share/man/man2 | grep 2 | xargs pr -t | mandoc >> bsd_man2_all
3 KQUEUE(2) System Calls Manual KQUEUE(2)
6 k
\bkq
\bqu
\bue
\beu
\bue
\be, k
\bke
\bev
\bve
\ben
\bnt
\bt - kernel event notification mechanism
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>
14 k
\bkq
\bqu
\bue
\beu
\bue
\be(_
\bv_
\bo_
\bi_
\bd);
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);
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);
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.
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.
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
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.
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.
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.
63 E
\bEV
\bV_
\b_S
\bSE
\bET
\bT() is a macro which is provided for ease of initializing a kevent
66 The _
\bk_
\be_
\bv_
\be_
\bn_
\bt structure is defined as:
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 */
77 The fields of struct kevent are:
79 ident Value used to identify this event. The exact interpretation
80 is determined by the attached filter, but often is a file
83 filter Identifies the kernel filter used to process this event. The
84 pre-defined system filters are described below.
86 flags Actions to perform on the event.
88 fflags Filter-specific flags.
90 data Filter-specific data value.
92 udata Opaque user-defined value passed through the kernel unchanged.
94 The _
\bf_
\bl_
\ba_
\bg_
\bs field can contain the following values:
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
102 EV_ENABLE Permit k
\bke
\bev
\bve
\ben
\bnt
\bt() to return the event if it is triggered.
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.
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.
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.
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.
120 EV_EOF Filters may set this flag to indicate filter-specific EOF
123 EV_ERROR See _
\bR_
\bE_
\bT_
\bU_
\bR_
\bN _
\bV_
\bA_
\bL_
\bU_
\bE_
\bS below.
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
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
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.
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
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
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.
165 Returns when there is data to read; _
\bd_
\ba_
\bt_
\ba contains the
166 number of bytes available.
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.
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.
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.
187 For sockets, the low water mark and socket error handling
188 is identical to the EVFILT_READ case.
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
195 NOTE_DELETE u
\bun
\bnl
\bli
\bin
\bnk
\bk() was called on the file referenced
198 NOTE_WRITE A write occurred on the file referenced by
201 NOTE_EXTEND The file referenced by the descriptor was
204 NOTE_TRUNCATE The file referenced by the descriptor was
207 NOTE_ATTRIB The file referenced by the descriptor had
208 its attributes changed.
210 NOTE_LINK The link count on the file changed.
212 NOTE_RENAME The file referenced by the descriptor was
215 NOTE_REVOKE Access to the file was revoked via
216 revoke(2) or the underlying file system was
219 On return, _
\bf_
\bf_
\bl_
\ba_
\bg_
\bs contains the events which triggered the
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:
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).
232 NOTE_FORK The process has called f
\bfo
\bor
\brk
\bk().
234 NOTE_EXEC The process has executed a new process
235 via execve(2) or similar call.
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.
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
249 On return, _
\bf_
\bf_
\bl_
\ba_
\bg_
\bs contains the events which triggered the
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.
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.
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.
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.
284 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
285 The k
\bkq
\bqu
\bue
\beu
\bue
\be() function fails if:
287 [ENOMEM] The kernel failed to allocate enough memory for the
290 [EMFILE] The per-process descriptor table is full.
292 [ENFILE] The system file table is full.
294 The k
\bke
\bev
\bve
\ben
\bnt
\bt() function fails if:
296 [EACCES] The process does not have permission to register a
299 [EFAULT] There was an error reading or writing the _
\bk_
\be_
\bv_
\be_
\bn_
\bt
302 [EBADF] The specified descriptor is invalid.
304 [EINTR] A signal was delivered before the timeout expired and
305 before any events were placed on the kqueue for
308 [EINVAL] The specified time limit or filter is invalid.
310 [ENOENT] The event could not be found to be modified or
313 [ENOMEM] No memory was available to register the event.
315 [ESRCH] The specified process to attach to does not exist.
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)
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.
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>.
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.
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.
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
377 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
380 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
381 of the symbolic link is returned.
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.
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
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 */
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
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.
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.
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.
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.
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
437 The size-related fields of the struct stat are as follows:
439 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
445 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
482 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
492 [ENOTDIR] A component of the path prefix is not a directory.
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.
498 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
501 [EACCES] Search permission is denied for a component of the
504 [ELOOP] Too many symbolic links were encountered in
505 translating the pathname.
507 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
509 [EIO] An I/O error occurred while reading from or writing to
512 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
514 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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
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.
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.
529 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
531 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
533 [EFAULT] _
\bs_
\bb points to an invalid address.
535 [EIO] An I/O error occurred while reading from the file
538 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
539 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
611 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
614 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
615 of the symbolic link is returned.
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.
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
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 */
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
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.
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.
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.
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.
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
671 The size-related fields of the struct stat are as follows:
673 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
679 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
716 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
726 [ENOTDIR] A component of the path prefix is not a directory.
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.
732 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
735 [EACCES] Search permission is denied for a component of the
738 [ELOOP] Too many symbolic links were encountered in
739 translating the pathname.
741 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
743 [EIO] An I/O error occurred while reading from or writing to
746 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
748 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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
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.
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.
763 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
765 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
767 [EFAULT] _
\bs_
\bb points to an invalid address.
769 [EIO] An I/O error occurred while reading from the file
772 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
773 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
845 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
848 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
849 of the symbolic link is returned.
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.
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
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 */
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
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.
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.
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.
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.
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
905 The size-related fields of the struct stat are as follows:
907 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
913 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
950 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
960 [ENOTDIR] A component of the path prefix is not a directory.
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.
966 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
969 [EACCES] Search permission is denied for a component of the
972 [ELOOP] Too many symbolic links were encountered in
973 translating the pathname.
975 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
977 [EIO] An I/O error occurred while reading from or writing to
980 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
982 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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
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.
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.
997 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
999 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
1001 [EFAULT] _
\bs_
\bb points to an invalid address.
1003 [EIO] An I/O error occurred while reading from the file
1006 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1007 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
1079 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
1082 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
1083 of the symbolic link is returned.
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.
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.
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 */
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
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.
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.
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.
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.
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
1139 The size-related fields of the struct stat are as follows:
1141 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
1147 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
1184 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
1194 [ENOTDIR] A component of the path prefix is not a directory.
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.
1200 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
1203 [EACCES] Search permission is denied for a component of the
1206 [ELOOP] Too many symbolic links were encountered in
1207 translating the pathname.
1209 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
1211 [EIO] An I/O error occurred while reading from or writing to
1214 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
1216 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
1217 AT_SYMLINK_NOFOLLOW.
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
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.
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.
1231 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
1233 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
1235 [EFAULT] _
\bs_
\bb points to an invalid address.
1237 [EIO] An I/O error occurred while reading from the file
1240 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1241 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
1313 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
1316 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
1317 of the symbolic link is returned.
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.
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.
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 */
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
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.
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.
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.
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.
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
1373 The size-related fields of the struct stat are as follows:
1375 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
1381 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
1418 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
1428 [ENOTDIR] A component of the path prefix is not a directory.
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.
1434 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
1437 [EACCES] Search permission is denied for a component of the
1440 [ELOOP] Too many symbolic links were encountered in
1441 translating the pathname.
1443 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
1445 [EIO] An I/O error occurred while reading from or writing to
1448 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
1450 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
1451 AT_SYMLINK_NOFOLLOW.
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
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.
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.
1465 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
1467 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
1469 [EFAULT] _
\bs_
\bb points to an invalid address.
1471 [EIO] An I/O error occurred while reading from the file
1474 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1475 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
1547 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
1550 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
1551 of the symbolic link is returned.
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.
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.
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 */
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
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.
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.
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.
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.
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
1607 The size-related fields of the struct stat are as follows:
1609 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
1615 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
1652 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
1662 [ENOTDIR] A component of the path prefix is not a directory.
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.
1668 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
1671 [EACCES] Search permission is denied for a component of the
1674 [ELOOP] Too many symbolic links were encountered in
1675 translating the pathname.
1677 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
1679 [EIO] An I/O error occurred while reading from or writing to
1682 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
1684 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
1685 AT_SYMLINK_NOFOLLOW.
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
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.
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.
1699 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
1701 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
1703 [EFAULT] _
\bs_
\bb points to an invalid address.
1705 [EIO] An I/O error occurred while reading from the file
1708 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1709 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
1781 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
1784 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
1785 of the symbolic link is returned.
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.
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.
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 */
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
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.
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.
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.
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.
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
1841 The size-related fields of the struct stat are as follows:
1843 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
1849 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
1886 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
1896 [ENOTDIR] A component of the path prefix is not a directory.
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.
1902 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
1905 [EACCES] Search permission is denied for a component of the
1908 [ELOOP] Too many symbolic links were encountered in
1909 translating the pathname.
1911 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
1913 [EIO] An I/O error occurred while reading from or writing to
1916 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
1918 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
1919 AT_SYMLINK_NOFOLLOW.
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
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.
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.
1933 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
1935 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
1937 [EFAULT] _
\bs_
\bb points to an invalid address.
1939 [EIO] An I/O error occurred while reading from the file
1942 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1943 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
1979 _
\bp_
\bi_
\bd_
\b__
\bt
1980 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
2010 #define WAIT_ANY (-1) /* any process */
2011 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
2023 WCONTINUED Causes status to be reported for stopped child processes that
2024 have been continued by receipt of a SIGCONT signal.
2026 WNOHANG Indicates that the call should not block if there are no
2027 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
2065 Depending on the values of those macros, the following macros produce the
2066 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
2112 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
2113 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
2115 [ECHILD] The calling process has no existing unwaited-for child
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
2122 [EINTR] The call was interrupted by a caught signal, or the
2123 signal did not have the SA_RESTART flag set.
2125 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
2128 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
2129 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
2152 _
\bp_
\bi_
\bd_
\b__
\bt
2153 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
2183 #define WAIT_ANY (-1) /* any process */
2184 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
2196 WCONTINUED Causes status to be reported for stopped child processes that
2197 have been continued by receipt of a SIGCONT signal.
2199 WNOHANG Indicates that the call should not block if there are no
2200 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
2238 Depending on the values of those macros, the following macros produce the
2239 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
2285 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
2286 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
2288 [ECHILD] The calling process has no existing unwaited-for child
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
2295 [EINTR] The call was interrupted by a caught signal, or the
2296 signal did not have the SA_RESTART flag set.
2298 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
2301 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
2302 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
2325 _
\bp_
\bi_
\bd_
\b__
\bt
2326 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
2356 #define WAIT_ANY (-1) /* any process */
2357 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
2369 WCONTINUED Causes status to be reported for stopped child processes that
2370 have been continued by receipt of a SIGCONT signal.
2372 WNOHANG Indicates that the call should not block if there are no
2373 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
2411 Depending on the values of those macros, the following macros produce the
2412 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
2458 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
2459 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
2461 [ECHILD] The calling process has no existing unwaited-for child
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
2468 [EINTR] The call was interrupted by a caught signal, or the
2469 signal did not have the SA_RESTART flag set.
2471 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
2474 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
2475 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
2498 _
\bp_
\bi_
\bd_
\b__
\bt
2499 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
2529 #define WAIT_ANY (-1) /* any process */
2530 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
2542 WCONTINUED Causes status to be reported for stopped child processes that
2543 have been continued by receipt of a SIGCONT signal.
2545 WNOHANG Indicates that the call should not block if there are no
2546 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
2584 Depending on the values of those macros, the following macros produce the
2585 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
2631 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
2632 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
2634 [ECHILD] The calling process has no existing unwaited-for child
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
2641 [EINTR] The call was interrupted by a caught signal, or the
2642 signal did not have the SA_RESTART flag set.
2644 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
2647 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
2648 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
2671 _
\bp_
\bi_
\bd_
\b__
\bt
2672 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
2702 #define WAIT_ANY (-1) /* any process */
2703 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
2715 WCONTINUED Causes status to be reported for stopped child processes that
2716 have been continued by receipt of a SIGCONT signal.
2718 WNOHANG Indicates that the call should not block if there are no
2719 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
2757 Depending on the values of those macros, the following macros produce the
2758 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
2804 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
2805 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
2807 [ECHILD] The calling process has no existing unwaited-for child
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
2814 [EINTR] The call was interrupted by a caught signal, or the
2815 signal did not have the SA_RESTART flag set.
2817 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
2820 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
2821 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
2844 _
\bp_
\bi_
\bd_
\b__
\bt
2845 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
2875 #define WAIT_ANY (-1) /* any process */
2876 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
2888 WCONTINUED Causes status to be reported for stopped child processes that
2889 have been continued by receipt of a SIGCONT signal.
2891 WNOHANG Indicates that the call should not block if there are no
2892 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
2930 Depending on the values of those macros, the following macros produce the
2931 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
2977 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
2978 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
2980 [ECHILD] The calling process has no existing unwaited-for child
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
2987 [EINTR] The call was interrupted by a caught signal, or the
2988 signal did not have the SA_RESTART flag set.
2990 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
2993 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
2994 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
3017 _
\bp_
\bi_
\bd_
\b__
\bt
3018 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
3048 #define WAIT_ANY (-1) /* any process */
3049 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
3061 WCONTINUED Causes status to be reported for stopped child processes that
3062 have been continued by receipt of a SIGCONT signal.
3064 WNOHANG Indicates that the call should not block if there are no
3065 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
3103 Depending on the values of those macros, the following macros produce the
3104 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
3150 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
3151 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
3153 [ECHILD] The calling process has no existing unwaited-for child
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
3160 [EINTR] The call was interrupted by a caught signal, or the
3161 signal did not have the SA_RESTART flag set.
3163 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
3166 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
3167 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
3190 _
\bp_
\bi_
\bd_
\b__
\bt
3191 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
3221 #define WAIT_ANY (-1) /* any process */
3222 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
3234 WCONTINUED Causes status to be reported for stopped child processes that
3235 have been continued by receipt of a SIGCONT signal.
3237 WNOHANG Indicates that the call should not block if there are no
3238 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
3276 Depending on the values of those macros, the following macros produce the
3277 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
3323 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
3324 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
3326 [ECHILD] The calling process has no existing unwaited-for child
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
3333 [EINTR] The call was interrupted by a caught signal, or the
3334 signal did not have the SA_RESTART flag set.
3336 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
3339 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
3340 _exit(2), sigaction(2), exit(3)
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
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
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.
3358 _
\b_e
\bex
\bxi
\bit
\bt, _
\b_E
\bEx
\bxi
\bit
\bt - terminate the calling process
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>
3364 _
\b_e
\bex
\bxi
\bit
\bt(_
\bi_
\bn_
\bt _
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
3366 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bst
\btd
\bdl
\bli
\bib
\bb.
\b.h
\bh>
\b>
3369 _
\b_E
\bEx
\bxi
\bit
\bt(_
\bi_
\bn_
\bt _
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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
3375 +
\b+
\bo
\bo All threads in the process are terminated.
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.
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.)
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.
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.
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
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().
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.
3408 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
3409 fork(2), intro(2), sigaction(2), wait(2), exit(3), sysexits(3)
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'').
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
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
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);
3430 _
\b__
\b_s
\bse
\bet
\bt_
\b_t
\btc
\bcb
\bb(_
\bv_
\bo_
\bi_
\bd _
\b*);
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.
3442 On some platforms, this address is also directly mapped to a CPU register
3443 which can be accessed from userspace.
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
3449 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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
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);
3464 _
\b__
\b_s
\bse
\bet
\bt_
\b_t
\btc
\bcb
\bb(_
\bv_
\bo_
\bi_
\bd _
\b*);
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.
3476 On some platforms, this address is also directly mapped to a CPU register
3477 which can be accessed from userspace.
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
3483 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
3490 s
\bsy
\bys
\bsc
\bca
\bal
\bll
\bl, _
\b__
\b_s
\bsy
\bys
\bsc
\bca
\bal
\bll
\bl - indirect system call
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>
3497 s
\bsy
\bys
\bsc
\bca
\bal
\bll
\bl(_
\bi_
\bn_
\bt _
\bn_
\bu_
\bm_
\bb_
\be_
\br, _
\b._
\b._
\b.);
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.);
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>.
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
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.
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.
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
3528 There is no way to simulate system calls that have multiple return values
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
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>
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 */
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);
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);
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.
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.
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.
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).
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
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
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.
3592 [EINVAL] Invalid argument. Some invalid argument was supplied.
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-
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>.
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.
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
3614 _
\b__
\b_t
\bth
\bhr
\brs
\bsi
\big
\bgd
\bdi
\biv
\bve
\ber
\brt
\bt - synchronously accept a signal
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>
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);
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.
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
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.
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.
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
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:
3659 [EWOULDBLOCK] The timeout was reached before a selected signal was
3662 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
3663 sigaction(2), sigprocmask(2), sigwait(3)
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.
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.
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>.
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
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>
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);
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);
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.
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.
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.
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.
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
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
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:
3731 [EINVAL] The _
\bi_
\bd_
\be_
\bn_
\bt argument is NULL.
3733 In addition, _
\b__
\b_t
\bth
\bhr
\brs
\bsl
\ble
\bee
\bep
\bp() may return one of the following errors:
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.
3738 [EINTR] A signal arrived or the _
\ba_
\bb_
\bo_
\br_
\bt argument pointed to a
3741 [EINVAL] The _
\bc_
\bl_
\bo_
\bc_
\bk_
\b__
\bi_
\bd argument is neither CLOCK_REALTIME nor
3744 _
\b__
\b_t
\bth
\bhr
\brw
\bwa
\bak
\bke
\beu
\bup
\bp() may return the following error:
3746 [ESRCH] No threads calling _
\b__
\b_t
\bth
\bhr
\brs
\bsl
\ble
\bee
\bep
\bp() with the same _
\bi_
\bd were
3749 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
3750 pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9)
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.
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
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>.
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
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>
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);
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);
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.
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.
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.
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.
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
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
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:
3821 [EINVAL] The _
\bi_
\bd_
\be_
\bn_
\bt argument is NULL.
3823 In addition, _
\b__
\b_t
\bth
\bhr
\brs
\bsl
\ble
\bee
\bep
\bp() may return one of the following errors:
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.
3828 [EINTR] A signal arrived or the _
\ba_
\bb_
\bo_
\br_
\bt argument pointed to a
3831 [EINVAL] The _
\bc_
\bl_
\bo_
\bc_
\bk_
\b__
\bi_
\bd argument is neither CLOCK_REALTIME nor
3834 _
\b__
\b_t
\bth
\bhr
\brw
\bwa
\bak
\bke
\beu
\bup
\bp() may return the following error:
3836 [ESRCH] No threads calling _
\b__
\b_t
\bth
\bhr
\brs
\bsl
\ble
\bee
\bep
\bp() with the same _
\bi_
\bd were
3839 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
3840 pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9)
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.
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
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>.
3858 _
\b_e
\bex
\bxi
\bit
\bt, _
\b_E
\bEx
\bxi
\bit
\bt - terminate the calling process
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>
3864 _
\b_e
\bex
\bxi
\bit
\bt(_
\bi_
\bn_
\bt _
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
3866 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bst
\btd
\bdl
\bli
\bib
\bb.
\b.h
\bh>
\b>
3869 _
\b_E
\bEx
\bxi
\bit
\bt(_
\bi_
\bn_
\bt _
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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
3875 +
\b+
\bo
\bo All threads in the process are terminated.
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.
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.)
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.
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.
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
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().
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.
3908 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
3909 fork(2), intro(2), sigaction(2), wait(2), exit(3), sysexits(3)
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'').
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
3922 a
\bac
\bcc
\bce
\bep
\bpt
\bt, a
\bac
\bcc
\bce
\bep
\bpt
\bt4
\b4 - accept a connection on a socket
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>
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);
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);
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.
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.
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.
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.
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.
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.
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.
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:
3978 #include <sys/types.h>
3979 #include <sys/socket.h>
3981 struct sockaddr_storage addr;
3982 socklen_t len = sizeof(addr);
3985 retcode = accept(s, (struct sockaddr *)&addr, &len);
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:
3992 [EBADF] The descriptor is invalid.
3994 [ENOTSOCK] The descriptor doesn't reference a socket.
3996 [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM.
3998 [EINTR] A signal was caught before a connection arrived.
4000 [EINVAL] The referenced socket is not listening for connections
4001 (that is, listen(2) has not yet been called).
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.
4006 [EWOULDBLOCK] The socket is marked non-blocking and no connections
4007 are present to be accepted.
4009 [EMFILE] The per-process descriptor table is full.
4011 [ENFILE] The system file table is full.
4013 [ECONNABORTED] A connection has been aborted.
4015 In addition, a
\bac
\bcc
\bce
\bep
\bpt
\bt4
\b4() will fail if
4017 [EINVAL] _
\bf_
\bl_
\ba_
\bg_
\bs is invalid.
4019 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
4020 bind(2), connect(2), listen(2), poll(2), select(2), socket(2)
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
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
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
4037 a
\bac
\bcc
\bce
\bep
\bpt
\bt, a
\bac
\bcc
\bce
\bep
\bpt
\bt4
\b4 - accept a connection on a socket
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>
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);
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);
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.
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.
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.
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.
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.
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.
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.
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:
4093 #include <sys/types.h>
4094 #include <sys/socket.h>
4096 struct sockaddr_storage addr;
4097 socklen_t len = sizeof(addr);
4100 retcode = accept(s, (struct sockaddr *)&addr, &len);
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:
4107 [EBADF] The descriptor is invalid.
4109 [ENOTSOCK] The descriptor doesn't reference a socket.
4111 [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM.
4113 [EINTR] A signal was caught before a connection arrived.
4115 [EINVAL] The referenced socket is not listening for connections
4116 (that is, listen(2) has not yet been called).
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.
4121 [EWOULDBLOCK] The socket is marked non-blocking and no connections
4122 are present to be accepted.
4124 [EMFILE] The per-process descriptor table is full.
4126 [ENFILE] The system file table is full.
4128 [ECONNABORTED] A connection has been aborted.
4130 In addition, a
\bac
\bcc
\bce
\bep
\bpt
\bt4
\b4() will fail if
4132 [EINVAL] _
\bf_
\bl_
\ba_
\bg_
\bs is invalid.
4134 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
4135 bind(2), connect(2), listen(2), poll(2), select(2), socket(2)
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
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
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
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
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>
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);
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>
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);
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
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.
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.
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.
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().
4193 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
4196 AT_EACCESS The checks for accessibility are performed using the
4197 effective user and group IDs instead of the real user
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.
4204 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
4205 Access to the file is denied if:
4207 [ENOTDIR] A component of the path prefix is not a directory.
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.
4213 [ENOENT] The named file does not exist.
4215 [ELOOP] Too many symbolic links were encountered in
4216 translating the pathname.
4218 [EROFS] Write access is requested for a file on a read-only
4221 [ETXTBSY] Write access is requested for a pure procedure (shared
4222 text) file presently being executed.
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.
4234 [EPERM] Write access has been requested and the named file has
4235 its immutable flag set (see chflags(2)).
4237 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
4240 [EIO] An I/O error occurred while reading from or writing to
4243 [EINVAL] An invalid value was specified for _
\ba_
\bm_
\bo_
\bd_
\be.
4245 Additionally, f
\bfa
\bac
\bcc
\bce
\bes
\bss
\bsa
\bat
\bt() will fail if:
4247 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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
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.
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.
4262 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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
4276 The f
\bfa
\bac
\bcc
\bce
\bes
\bss
\bsa
\bat
\bt() function appeared in OpenBSD 5.0.
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.
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.
4286 a
\bac
\bcc
\bct
\bt - enable or disable process accounting
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>
4292 a
\bac
\bcc
\bct
\bt(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bf_
\bi_
\bl_
\be);
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.
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).
4307 This call is permitted only to the superuser.
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
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
4319 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
4320 a
\bac
\bcc
\bct
\bt() will fail if one of the following is true:
4322 [EPERM] The caller is not the superuser.
4324 [ENOTDIR] A component of the path prefix is not a directory.
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.
4330 [ENOENT] The named file does not exist.
4332 [EACCES] Search permission is denied for a component of the
4333 path prefix, or the path name is not a regular file.
4335 [ELOOP] Too many symbolic links were encountered in
4336 translating the pathname.
4338 [EROFS] The named file resides on a read-only file system.
4340 [EFAULT] _
\bf_
\bi_
\bl_
\be points outside the process's allocated address
4343 [EIO] An I/O error occurred while reading from or writing to
4346 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
4347 acct(5), accton(8), sa(8)
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.
4353 a
\bad
\bdj
\bjf
\bfr
\bre
\beq
\bq - correct the rate of the system clock
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>
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);
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.
4367 If _
\bo_
\bl_
\bd_
\bf_
\br_
\be_
\bq is non-null, the current value is returned.
4369 Only the superuser may adjust the frequency.
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
4376 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
4377 a
\bad
\bdj
\bjf
\bfr
\bre
\beq
\bq() will fail if:
4379 [EFAULT] Either of the arguments point outside the process's
4380 allocated address space.
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.
4385 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
4386 date(1), adjtime(2), gettimeofday(2), ntpd(8)
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.
4392 a
\bad
\bdj
\bjt
\bti
\bim
\bme
\be - correct the time to allow synchronization of the system clock
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>
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);
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
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.
4420 Only the superuser may adjust the time using the a
\bad
\bdj
\bjt
\bti
\bim
\bme
\be() function.
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
4427 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
4428 a
\bad
\bdj
\bjt
\bti
\bim
\bme
\be() will fail if:
4430 [EFAULT] Either of the arguments point outside the process's
4431 allocated address space.
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.
4436 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
4437 date(1), adjfreq(2), gettimeofday(2), ntpd(8)
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.
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
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
4505 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
4507 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
4524 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
4526 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
4527 These functions originally appeared in FreeBSD.
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.
4533 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
4593 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
4595 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
4612 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
4614 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
4615 These functions originally appeared in FreeBSD.
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.
4621 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
4681 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
4683 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
4700 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
4702 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
4703 These functions originally appeared in FreeBSD.
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.
4709 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
4769 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
4771 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
4788 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
4790 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
4791 These functions originally appeared in FreeBSD.
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.
4797 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
4857 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
4859 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
4876 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
4878 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
4879 These functions originally appeared in FreeBSD.
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.
4885 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
4945 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
4947 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
4964 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
4966 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
4967 These functions originally appeared in FreeBSD.
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.
4973 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5033 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5035 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5052 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5054 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5055 These functions originally appeared in FreeBSD.
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.
5061 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5121 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5123 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5140 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5142 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5143 These functions originally appeared in FreeBSD.
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.
5149 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5209 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5211 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5228 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5230 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5231 These functions originally appeared in FreeBSD.
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.
5237 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5297 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5299 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5316 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5318 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5319 These functions originally appeared in FreeBSD.
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.
5325 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5385 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5387 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5404 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5406 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5407 These functions originally appeared in FreeBSD.
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.
5413 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5473 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5475 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5492 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5494 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5495 These functions originally appeared in FreeBSD.
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.
5501 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5561 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5563 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5580 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5582 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5583 These functions originally appeared in FreeBSD.
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.
5589 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5649 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5651 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5668 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5670 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5671 These functions originally appeared in FreeBSD.
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.
5677 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5737 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5739 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5756 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5758 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5759 These functions originally appeared in FreeBSD.
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.
5765 Root credentials are needed to use these functions.
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
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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);
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.
5825 The i
\bin
\bn*
\b*() functions return data read from the specified I/O port.
5827 The o
\bou
\but
\bt*
\b*() functions write data to the specified I/O port.
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.
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
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().
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().
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().
5844 N
\bNo
\bot
\bte
\be: Code using these functions must be compiled using -
\b-l
\bla
\bal
\blp
\bph
\bha
\ba.
5846 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
5847 These functions originally appeared in FreeBSD.
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.
5853 Root credentials are needed to use these functions.
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
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>
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);
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);
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.
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.
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
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.
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.
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:
5892 [EFAULT] _
\bb_
\ba_
\bs_
\be points outside the process's allocated address space.
5894 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
5906 a
\bam
\bmd
\bd6
\b64
\b4_
\b_i
\bio
\bop
\bpl
\bl - change the amd64 I/O privilege level
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>
5913 a
\bam
\bmd
\bd6
\b64
\b4_
\b_i
\bio
\bop
\bpl
\bl(_
\bi_
\bn_
\bt _
\bi_
\bo_
\bp_
\bl);
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
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.
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.
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
5931 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
5932 a
\bam
\bmd
\bd6
\b64
\b4_
\b_i
\bio
\bop
\bpl
\bl() will fail if:
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-
5938 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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.
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
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>
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);
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);
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.
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.
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
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.
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.
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:
5985 [EFAULT] _
\bb_
\ba_
\bs_
\be points outside the process's allocated address space.
5987 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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
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>
6005 a
\bar
\brm
\bm_
\b_d
\bdr
\bra
\bai
\bin
\bn_
\b_w
\bwr
\bri
\bit
\bte
\beb
\bbu
\buf
\bf();
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.
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.
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.
6017 R
\bRE
\bEF
\bFE
\bER
\bRE
\bEN
\bNC
\bCE
\bES
\bS
6018 StrongARM Data Sheet
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
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>
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);
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
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.
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.
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.
6050 R
\bRE
\bEF
\bFE
\bER
\bRE
\bEN
\bNC
\bCE
\bES
\bS
6051 StrongARM Data Sheet
6054 b
\bbi
\bin
\bnd
\bd - bind a name to a socket
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>
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);
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.
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
6073 The rules used in name binding vary between communication domains.
6074 Consult the manual entries in section 4 for detailed information.
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
6081 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
6082 The b
\bbi
\bin
\bnd
\bd() function will fail if:
6084 [EBADF] _
\bs is not a valid descriptor.
6086 [ENOTSOCK] _
\bs is not a socket.
6088 [EADDRNOTAVAIL] The specified address is not available from the local
6091 [EADDRINUSE] The specified address is already in use.
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.
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.
6099 [ENOBUFS] Insufficient buffer space is available.
6101 [EACCES] The requested address is protected, and the current
6102 user has inadequate permission to access it.
6104 [EFAULT] The _
\bn_
\ba_
\bm_
\be parameter is not in a valid part of the user
6107 The following errors are specific to binding names in the UNIX-domain.
6109 [ENOTDIR] A component of the path prefix is not a directory.
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.
6115 [ENOENT] A prefix component of the path name does not exist.
6117 [ELOOP] Too many symbolic links were encountered in
6118 translating the pathname.
6120 [EIO] An I/O error occurred while making the directory entry
6121 or allocating the inode.
6123 [EROFS] The name would reside on a read-only file system.
6125 [EISDIR] An empty pathname was specified.
6127 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
6128 connect(2), getsockname(2), listen(2), socket(2)
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'').
6133 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
6134 The b
\bbi
\bin
\bnd
\bd() system call first appeared in 4.1cBSD.
6137 b
\bbr
\brk
\bk, s
\bsb
\bbr
\brk
\bk - change data segment size
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>
6143 b
\bbr
\brk
\bk(_
\bv_
\bo_
\bi_
\bd _
\b*_
\ba_
\bd_
\bd_
\br);
6145 _
\bv_
\bo_
\bi_
\bd _
\b*
6146 s
\bsb
\bbr
\brk
\bk(_
\bi_
\bn_
\bt _
\bi_
\bn_
\bc_
\br);
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
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).
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
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
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
6178 [ENOMEM] The limit, as set by setrlimit(2), was exceeded.
6180 [ENOMEM] The maximum possible size of a data segment (compiled
6181 into the system) was exceeded.
6183 [ENOMEM] Insufficient space existed in the swap area to support
6186 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
6187 execve(2), getrlimit(2), mmap(2), end(3), malloc(3)
6189 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
6190 A b
\bbr
\brk
\bk() function call appeared in Version 7 AT&T UNIX.
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).
6198 c
\bch
\bhd
\bdi
\bir
\br, f
\bfc
\bch
\bhd
\bdi
\bir
\br - change current working directory
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>
6204 c
\bch
\bhd
\bdi
\bir
\br(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bp_
\ba_
\bt_
\bh);
6207 f
\bfc
\bch
\bhd
\bdi
\bir
\br(_
\bi_
\bn_
\bt _
\bf_
\bd);
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 (`/').
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 (`/').
6219 In order for a directory to become the current directory, a process must
6220 have execute (search) access to the directory.
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
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:
6231 [ENOTDIR] A component of the path prefix is not a directory.
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.
6237 [ENOENT] The named directory does not exist.
6239 [ELOOP] Too many symbolic links were encountered in
6240 translating the pathname.
6242 [EACCES] Search permission is denied for any component of the
6245 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
6248 [EIO] An I/O error occurred while reading from the file
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:
6254 [EACCES] Search permission is denied for the directory
6255 referenced by the file descriptor.
6257 [ENOTDIR] The file descriptor does not reference a directory.
6259 [EBADF] The argument _
\bf_
\bd is not a valid file descriptor.
6261 [EIO] An I/O error occurred while reading from the file
6264 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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'').
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.
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
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>
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);
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);
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>
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);
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.
6297 The flags are the bitwise OR of zero or more of the following values:
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.
6306 The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the
6307 owner of a file or the superuser.
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
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.
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().
6323 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
6326 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the flags
6327 of the symbolic link are changed.
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.
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
6337 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
6338 c
\bch
\bhf
\bfl
\bla
\bag
\bgs
\bs() will fail if:
6340 [ENOTDIR] A component of the path prefix is not a directory.
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.
6346 [ENOENT] The named file does not exist.
6348 [EACCES] Search permission is denied for a component of the
6351 [ELOOP] Too many symbolic links were encountered in
6352 translating the pathname.
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.
6360 [EOPNOTSUPP] The named file resides on a file system that does not
6363 [EROFS] The named file resides on a read-only file system.
6365 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
6368 [EIO] An I/O error occurred while reading from or writing to
6371 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs value is invalid.
6373 [EINVAL] The descriptor references a block or character device
6374 and the effective user ID is not the superuser.
6376 f
\bfc
\bch
\bhf
\bfl
\bla
\bag
\bgs
\bs() will fail if:
6378 [EBADF] The descriptor is not valid.
6380 [EINVAL] _
\bf_
\bd refers to a socket, not to a file.
6382 [EINVAL] The descriptor references a block or character device
6383 and the effective user ID is not the superuser.
6385 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs value is invalid.
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.
6393 [EOPNOTSUPP] The named file resides on a file system that does not
6396 [EROFS] The file resides on a read-only file system.
6398 [EIO] An I/O error occurred while reading from or writing to
6401 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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
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>
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);
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);
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>
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);
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.
6431 The flags are the bitwise OR of zero or more of the following values:
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.
6440 The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the
6441 owner of a file or the superuser.
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
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.
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().
6457 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
6460 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the flags
6461 of the symbolic link are changed.
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.
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
6471 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
6472 c
\bch
\bhf
\bfl
\bla
\bag
\bgs
\bs() will fail if:
6474 [ENOTDIR] A component of the path prefix is not a directory.
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.
6480 [ENOENT] The named file does not exist.
6482 [EACCES] Search permission is denied for a component of the
6485 [ELOOP] Too many symbolic links were encountered in
6486 translating the pathname.
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.
6494 [EOPNOTSUPP] The named file resides on a file system that does not
6497 [EROFS] The named file resides on a read-only file system.
6499 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
6502 [EIO] An I/O error occurred while reading from or writing to
6505 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs value is invalid.
6507 [EINVAL] The descriptor references a block or character device
6508 and the effective user ID is not the superuser.
6510 f
\bfc
\bch
\bhf
\bfl
\bla
\bag
\bgs
\bs() will fail if:
6512 [EBADF] The descriptor is not valid.
6514 [EINVAL] _
\bf_
\bd refers to a socket, not to a file.
6516 [EINVAL] The descriptor references a block or character device
6517 and the effective user ID is not the superuser.
6519 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs value is invalid.
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.
6527 [EOPNOTSUPP] The named file resides on a file system that does not
6530 [EROFS] The file resides on a read-only file system.
6532 [EIO] An I/O error occurred while reading from or writing to
6535 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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
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>
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);
6553 f
\bfc
\bch
\bhm
\bmo
\bod
\bd(_
\bi_
\bn_
\bt _
\bf_
\bd, _
\bm_
\bo_
\bd_
\be_
\b__
\bt _
\bm_
\bo_
\bd_
\be);
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>
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);
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.
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:
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 */
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 */
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 */
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 */
6588 If mode ISVTX (the _
\bs_
\bt_
\bi_
\bc_
\bk_
\by _
\bb_
\bi_
\bt) is set on a file, it is ignored.
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).
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.
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.
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().
6611 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
6614 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the mode
6615 of the symbolic link is changed.
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.
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
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
6629 [ENOTDIR] A component of the path prefix is not a directory.
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.
6635 [ENOENT] The named file does not exist.
6637 [EACCES] Search permission is denied for a component of the
6640 [EINVAL] _
\bm_
\bo_
\bd_
\be contains bits other than the file type and those
6643 [ELOOP] Too many symbolic links were encountered in
6644 translating the pathname.
6646 [EPERM] The effective user ID does not match the owner of the
6647 file and the effective user ID is not the superuser.
6649 [EROFS] The named file resides on a read-only file system.
6651 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
6654 [EIO] An I/O error occurred while reading from or writing to
6657 Additionally, the f
\bfc
\bch
\bhm
\bmo
\bod
\bda
\bat
\bt() function will fail if:
6659 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
6660 AT_SYMLINK_NOFOLLOW.
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
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.
6670 [EOPNOTSUPP] The _
\bf_
\bl_
\ba_
\bg argument specifies AT_SYMLINK_NOFOLLOW on a
6671 symbolic link and the file system does not support
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.
6678 f
\bfc
\bch
\bhm
\bmo
\bod
\bd() will fail and the file mode will be unchanged if:
6680 [EBADF] The descriptor is not valid.
6682 [EINVAL] _
\bf_
\bd refers to a socket, not to a file.
6684 [EINVAL] _
\bm_
\bo_
\bd_
\be contains bits other than the file type and those
6687 [EPERM] The effective user ID does not match the owner of the
6688 file and the effective user ID is not the superuser.
6690 [EROFS] The file resides on a read-only file system.
6692 [EIO] An I/O error occurred while reading from or writing to
6695 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
6696 chmod(1), chown(2), open(2), stat(2), sticky(8)
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'').
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.
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
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.
6755 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
6758 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the
6759 ownership of the symbolic link is changed.
6761 f
\bfc
\bch
\bho
\bow
\bwn
\bn() is particularly useful when used in conjunction with the file
6762 locking primitives (see flock(2)).
6764 One of the owner or group IDs may be left unchanged by specifying it as
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
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
6776 [ENOTDIR] A component of the path prefix is not a directory.
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.
6782 [ENOENT] The named file does not exist.
6784 [EACCES] Search permission is denied for a component of the
6787 [ELOOP] Too many symbolic links were encountered in
6788 translating the pathname.
6790 [EPERM] The effective user ID is not the superuser.
6792 [EROFS] The named file resides on a read-only file system.
6794 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
6797 [EIO] An I/O error occurred while reading from or writing to
6800 Additionally, f
\bfc
\bch
\bho
\bow
\bwn
\bna
\bat
\bt() will fail if:
6802 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
6803 AT_SYMLINK_NOFOLLOW.
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
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.
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.
6817 f
\bfc
\bch
\bho
\bow
\bwn
\bn() will fail if:
6819 [EBADF] _
\bf_
\bd does not refer to a valid descriptor.
6821 [EINVAL] _
\bf_
\bd refers to a socket, not a file.
6823 [EPERM] The effective user ID is not the superuser.
6825 [EROFS] The named file resides on a read-only file system.
6827 [EIO] An I/O error occurred while reading from or writing to
6830 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
6831 chgrp(1), chmod(2), flock(2), chown(8)
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'').
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.
6842 The f
\bfc
\bch
\bho
\bow
\bwn
\bn() system call first appeared in 4.1cBSD.
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.
6848 The f
\bfc
\bch
\bho
\bow
\bwn
\bna
\bat
\bt() system call has been available since OpenBSD 5.0.
6851 c
\bch
\bhr
\bro
\boo
\bot
\bt - change root directory
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>
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);
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 `/'.
6864 In order for a directory to become the root directory a process must have
6865 execute (search) access for that directory.
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
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.
6876 This call is restricted to the superuser.
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
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.
6891 if (chroot(newroot) != 0 || chdir("/") != 0)
6892 err(1, "%s", newroot);
6893 setresuid(getuid(), getuid(), getuid());
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:
6898 [ENOTDIR] A component of the path name is not a directory.
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.
6904 [ENOENT] The named directory does not exist.
6906 [EACCES] Search permission is denied for any component of the
6909 [ELOOP] Too many symbolic links were encountered in
6910 translating the pathname.
6912 [EFAULT] _
\bd_
\bi_
\br_
\bn_
\ba_
\bm_
\be points outside the process's allocated address
6915 [EIO] An I/O error occurred while reading from or writing to
6918 [EPERM] The caller is not the superuser.
6920 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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.
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
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>
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);
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);
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);
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.
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:
6957 CLOCK_REALTIME time that increments as a wall clock should
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
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
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
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
6976 The structure pointed to by _
\bt_
\bp is defined in <_
\bs_
\by_
\bs_
\b/_
\bt_
\bi_
\bm_
\be_
\b._
\bh> as:
6979 time_t tv_sec; /* seconds */
6980 long tv_nsec; /* and nanoseconds */
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.
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.
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
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:
7001 [EINVAL] _
\bc_
\bl_
\bo_
\bc_
\bk_
\b__
\bi_
\bd is not a valid value.
7003 [EFAULT] The _
\bt_
\bp argument address referenced invalid memory.
7005 In addition, c
\bcl
\blo
\boc
\bck
\bk_
\b_s
\bse
\bet
\btt
\bti
\bim
\bme
\be() may return the following errors:
7007 [EPERM] A user other than the superuser attempted to set the
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
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)
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'').
7023 The CLOCK_UPTIME clock is an extension to that.
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.
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
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>
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);
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);
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);
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.
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:
7054 CLOCK_REALTIME time that increments as a wall clock should
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
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
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
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
7073 The structure pointed to by _
\bt_
\bp is defined in <_
\bs_
\by_
\bs_
\b/_
\bt_
\bi_
\bm_
\be_
\b._
\bh> as:
7076 time_t tv_sec; /* seconds */
7077 long tv_nsec; /* and nanoseconds */
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.
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.
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
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:
7098 [EINVAL] _
\bc_
\bl_
\bo_
\bc_
\bk_
\b__
\bi_
\bd is not a valid value.
7100 [EFAULT] The _
\bt_
\bp argument address referenced invalid memory.
7102 In addition, c
\bcl
\blo
\boc
\bck
\bk_
\b_s
\bse
\bet
\btt
\bti
\bim
\bme
\be() may return the following errors:
7104 [EPERM] A user other than the superuser attempted to set the
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
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)
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'').
7120 The CLOCK_UPTIME clock is an extension to that.
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.
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
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>
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);
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);
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);
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.
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:
7151 CLOCK_REALTIME time that increments as a wall clock should
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
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
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
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
7170 The structure pointed to by _
\bt_
\bp is defined in <_
\bs_
\by_
\bs_
\b/_
\bt_
\bi_
\bm_
\be_
\b._
\bh> as:
7173 time_t tv_sec; /* seconds */
7174 long tv_nsec; /* and nanoseconds */
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.
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.
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
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:
7195 [EINVAL] _
\bc_
\bl_
\bo_
\bc_
\bk_
\b__
\bi_
\bd is not a valid value.
7197 [EFAULT] The _
\bt_
\bp argument address referenced invalid memory.
7199 In addition, c
\bcl
\blo
\boc
\bck
\bk_
\b_s
\bse
\bet
\btt
\bti
\bim
\bme
\be() may return the following errors:
7201 [EPERM] A user other than the superuser attempted to set the
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
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)
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'').
7217 The CLOCK_UPTIME clock is an extension to that.
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.
7225 c
\bcl
\blo
\bos
\bse
\be - delete a descriptor
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>
7231 c
\bcl
\blo
\bos
\bse
\be(_
\bi_
\bn_
\bt _
\bd);
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.
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
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.
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
7267 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
7268 c
\bcl
\blo
\bos
\bse
\be() will fail if:
7270 [EBADF] _
\bd is not an active descriptor.
7272 [EINTR] An interrupt was received.
7274 [EIO] An I/O error occurred while writing to the file
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)
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'').
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.
7288 c
\bcl
\blo
\bos
\bse
\bef
\bfr
\bro
\bom
\bm - delete many descriptors
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>
7294 c
\bcl
\blo
\bos
\bse
\bef
\bfr
\bro
\bom
\bm(_
\bi_
\bn_
\bt _
\bf_
\bd);
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.
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
7306 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
7307 c
\bcl
\blo
\bos
\bse
\bef
\bfr
\bro
\bom
\bm() will fail if:
7309 [EBADF] _
\bf_
\bd is greater than all open file descriptors.
7311 [EINTR] An interrupt was received.
7313 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
7317 c
\bco
\bon
\bnn
\bne
\bec
\bct
\bt - initiate a connection on a socket
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>
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);
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.
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.
7343 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
7344 The c
\bco
\bon
\bnn
\bne
\bec
\bct
\bt() call fails if:
7346 [EBADF] _
\bs is not a valid descriptor.
7348 [ENOTSOCK] _
\bs is not a socket.
7350 [EADDRNOTAVAIL] The specified address is not available on this
7353 [EAFNOSUPPORT] Addresses in the specified address family cannot be
7354 used with this socket.
7356 [EISCONN] The socket is already connected.
7358 [ETIMEDOUT] Connection establishment timed out without
7359 establishing a connection.
7361 [EINVAL] A TCP connection with a local broadcast, the all-ones
7362 or a multicast address as the peer was attempted.
7364 [ECONNREFUSED] The attempt to connect was forcefully rejected.
7366 [EHOSTUNREACH] The destination address specified an unreachable host.
7368 [EINTR] A connect was interrupted before it succeeded by the
7369 delivery of a signal.
7371 [ENETUNREACH] The network isn't reachable from this host.
7373 [EADDRINUSE] The address is already in use.
7375 [EFAULT] The _
\bn_
\ba_
\bm_
\be parameter specifies an area outside the
7376 process address space.
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.
7384 [EALREADY] The socket is non-blocking and a previous connection
7385 attempt has not yet been completed.
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.
7390 [ENOTDIR] A component of the path prefix is not a directory.
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.
7396 [ENOENT] The named socket does not exist.
7398 [EACCES] Search permission is denied for a component of the
7401 [EACCES] Write access to the named socket is denied.
7403 [ELOOP] Too many symbolic links were encountered in
7404 translating the pathname.
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.
7410 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
7411 accept(2), getsockname(2), getsockopt(2), poll(2), select(2), socket(2)
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'').
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.
7420 d
\bdu
\bup
\bp, d
\bdu
\bup
\bp2
\b2, d
\bdu
\bup
\bp3
\b3 - duplicate an existing file descriptor
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>
7426 d
\bdu
\bup
\bp(_
\bi_
\bn_
\bt _
\bo_
\bl_
\bd_
\bd);
7429 d
\bdu
\bup
\bp2
\b2(_
\bi_
\bn_
\bt _
\bo_
\bl_
\bd_
\bd, _
\bi_
\bn_
\bt _
\bn_
\be_
\bw_
\bd);
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>
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);
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.
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.
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.
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().
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.
7470 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
7471 d
\bdu
\bup
\bp() will fail if:
7473 [EBADF] _
\bo_
\bl_
\bd_
\bd is not a valid active descriptor.
7475 [EMFILE] Too many descriptors are active.
7477 d
\bdu
\bup
\bp2
\b2() and d
\bdu
\bup
\bp3
\b3() will fail if:
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.
7483 [EINTR] An interrupt was received.
7485 [EIO] An I/O error occurred while writing to the file
7488 In addition, d
\bdu
\bup
\bp3
\b3() will return the following error:
7490 [EINVAL] _
\bo_
\bl_
\bd_
\bd is equal to _
\bn_
\be_
\bw_
\bd or _
\bf_
\bl_
\ba_
\bg_
\bs is invalid.
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)
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
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.
7506 d
\bdu
\bup
\bp, d
\bdu
\bup
\bp2
\b2, d
\bdu
\bup
\bp3
\b3 - duplicate an existing file descriptor
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>
7512 d
\bdu
\bup
\bp(_
\bi_
\bn_
\bt _
\bo_
\bl_
\bd_
\bd);
7515 d
\bdu
\bup
\bp2
\b2(_
\bi_
\bn_
\bt _
\bo_
\bl_
\bd_
\bd, _
\bi_
\bn_
\bt _
\bn_
\be_
\bw_
\bd);
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>
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);
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.
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.
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.
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().
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.
7556 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
7557 d
\bdu
\bup
\bp() will fail if:
7559 [EBADF] _
\bo_
\bl_
\bd_
\bd is not a valid active descriptor.
7561 [EMFILE] Too many descriptors are active.
7563 d
\bdu
\bup
\bp2
\b2() and d
\bdu
\bup
\bp3
\b3() will fail if:
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.
7569 [EINTR] An interrupt was received.
7571 [EIO] An I/O error occurred while writing to the file
7574 In addition, d
\bdu
\bup
\bp3
\b3() will return the following error:
7576 [EINVAL] _
\bo_
\bl_
\bd_
\bd is equal to _
\bn_
\be_
\bw_
\bd or _
\bf_
\bl_
\ba_
\bg_
\bs is invalid.
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)
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
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.
7592 d
\bdu
\bup
\bp, d
\bdu
\bup
\bp2
\b2, d
\bdu
\bup
\bp3
\b3 - duplicate an existing file descriptor
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>
7598 d
\bdu
\bup
\bp(_
\bi_
\bn_
\bt _
\bo_
\bl_
\bd_
\bd);
7601 d
\bdu
\bup
\bp2
\b2(_
\bi_
\bn_
\bt _
\bo_
\bl_
\bd_
\bd, _
\bi_
\bn_
\bt _
\bn_
\be_
\bw_
\bd);
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>
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);
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.
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.
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.
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().
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.
7642 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
7643 d
\bdu
\bup
\bp() will fail if:
7645 [EBADF] _
\bo_
\bl_
\bd_
\bd is not a valid active descriptor.
7647 [EMFILE] Too many descriptors are active.
7649 d
\bdu
\bup
\bp2
\b2() and d
\bdu
\bup
\bp3
\b3() will fail if:
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.
7655 [EINTR] An interrupt was received.
7657 [EIO] An I/O error occurred while writing to the file
7660 In addition, d
\bdu
\bup
\bp3
\b3() will return the following error:
7662 [EINVAL] _
\bo_
\bl_
\bd_
\bd is equal to _
\bn_
\be_
\bw_
\bd or _
\bf_
\bl_
\ba_
\bg_
\bs is invalid.
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)
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
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.
7678 i
\bin
\bnt
\btr
\bro
\bo - introduction to system calls and error numbers
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>
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.
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.
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.
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>.
7706 0 _
\bU_
\bn_
\bd_
\be_
\bf_
\bi_
\bn_
\be_
\bd _
\be_
\br_
\br_
\bo_
\br_
\b: _
\b0. Not used.
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.
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.
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.
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.
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
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
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>).
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.
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).
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
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.
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.
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.
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.
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.
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
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)
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
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.
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
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.
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)
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
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.
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.
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.
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.)
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
7826 29 ESPIPE _
\bI_
\bl_
\bl_
\be_
\bg_
\ba_
\bl _
\bs_
\be_
\be_
\bk. An lseek(2) function was issued on a socket, pipe
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
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
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.
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.
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).
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.
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)).
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.
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.
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.
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.
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
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.
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.
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
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.
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
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.
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
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.
7900 50 ENETDOWN _
\bN_
\be_
\bt_
\bw_
\bo_
\br_
\bk _
\bi_
\bs _
\bd_
\bo_
\bw_
\bn. A socket operation encountered a dead
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.
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.
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.
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.
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.
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
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.
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.
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.
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.)
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
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.
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.
7952 64 EHOSTDOWN _
\bH_
\bo_
\bs_
\bt _
\bi_
\bs _
\bd_
\bo_
\bw_
\bn. A socket operation failed because the
7953 destination host was down.
7955 65 EHOSTUNREACH _
\bN_
\bo _
\br_
\bo_
\bu_
\bt_
\be _
\bt_
\bo _
\bh_
\bo_
\bs_
\bt. A socket operation was attempted to an
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.
7961 67 EPROCLIM _
\bT_
\bo_
\bo _
\bm_
\ba_
\bn_
\by _
\bp_
\br_
\bo_
\bc_
\be_
\bs_
\bs_
\be_
\bs.
7963 68 EUSERS _
\bT_
\bo_
\bo _
\bm_
\ba_
\bn_
\by _
\bu_
\bs_
\be_
\br_
\bs. The quota system ran out of table entries.
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.
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.
7976 72 EBADRPC _
\bR_
\bP_
\bC _
\bs_
\bt_
\br_
\bu_
\bc_
\bt _
\bi_
\bs _
\bb_
\ba_
\bd. Exchange of rpc(3) information was
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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
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.
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.
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.
8034 91 ENOTSUP _
\bN_
\bo_
\bt _
\bs_
\bu_
\bp_
\bp_
\bo_
\br_
\bt_
\be_
\bd. The operation has requested an unsupported
8037 D
\bDE
\bEF
\bFI
\bIN
\bNI
\bIT
\bTI
\bIO
\bON
\bNS
\bS
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
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
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
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).
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
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
8076 A session leader with a controlling terminal is a controlling
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.
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
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
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
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.
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.
8122 All processes have a real user ID and real group ID. These are
8123 initialized from the equivalent attributes of the process that
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.)
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)
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''.
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
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.
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.
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
8179 Names consisting of up to 255 (NAME_MAX) characters may be used
8180 to name an ordinary file, special file, or directory.
8182 These characters may be arbitrary eight-bit values, excluding 0
8183 (NUL) and the ASCII code for `/' (slash).
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.
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)
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
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.
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
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.
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
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.
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
8242 Read, write, and execute/search permissions on a file are granted
8245 The process's effective user ID is that of the superuser. (Note:
8246 even the superuser cannot execute a non-executable file.)
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.
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
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''
8262 Otherwise, permission is denied.
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.
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.
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.
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.
8283 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
8290 e
\bex
\bxe
\bec
\bcv
\bve
\be, e
\bex
\bxe
\bec
\bct
\bt - execute a file
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>
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]);
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]);
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).
8311 An interpreter file begins with a line of the form:
8313 #
\b#!
\b! _
\bi_
\bn_
\bt_
\be_
\br_
\bp_
\br_
\be_
\bt_
\be_
\br [_
\ba_
\br_
\bg]
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.
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).
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)).
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.
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
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.
8368 The new process also inherits the following attributes from the calling
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
8383 resource limits see getrlimit(2)
8384 file mode mask see umask(2)
8385 signal mask see sigaction(2), sigsetmask(3)
8387 When a program is executed as a result of an e
\bex
\bxe
\bec
\bcv
\bve
\be() call, it is entered
8390 main(int argc, char **argv, char **envp)
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.
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)).
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
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:
8409 [ENOTDIR] A component of the path prefix is not a directory.
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.
8415 [ENOENT] The new process file does not exist.
8417 [ELOOP] Too many symbolic links were encountered in
8418 translating the pathname.
8420 [EACCES] Search permission is denied for a component of the
8423 [EACCES] The new process file is not an ordinary file.
8425 [EACCES] The new process file mode denies execute permission.
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>).
8430 [ENOEXEC] The new process file has the appropriate access
8431 permission, but has an invalid magic number in its
8434 [ETXTBSY] The new process file is a pure procedure (shared text)
8435 file that is currently open for writing or reading by
8438 [ENOMEM] The new process requires more virtual memory than is
8439 allowed by the imposed maximum (getrlimit(2)).
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>).
8446 [EFAULT] The new process file is not as long as indicated by
8447 the size values in its header.
8449 [EFAULT] _
\bp_
\ba_
\bt_
\bh, _
\ba_
\br_
\bg_
\bv, or _
\be_
\bn_
\bv_
\bp point to an illegal address.
8451 [EINVAL] _
\ba_
\br_
\bg_
\bv did not contain at least one element.
8453 [EIO] An I/O error occurred while reading from the file
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.
8459 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
8460 _exit(2), fork(2), execl(3), exit(3), elf(5), environ(7)
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
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.
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
8478 e
\bex
\bxe
\bec
\bcv
\bve
\be, e
\bex
\bxe
\bec
\bct
\bt - execute a file
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>
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]);
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]);
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).
8499 An interpreter file begins with a line of the form:
8501 #
\b#!
\b! _
\bi_
\bn_
\bt_
\be_
\br_
\bp_
\br_
\be_
\bt_
\be_
\br [_
\ba_
\br_
\bg]
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.
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).
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)).
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.
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
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.
8556 The new process also inherits the following attributes from the calling
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
8571 resource limits see getrlimit(2)
8572 file mode mask see umask(2)
8573 signal mask see sigaction(2), sigsetmask(3)
8575 When a program is executed as a result of an e
\bex
\bxe
\bec
\bcv
\bve
\be() call, it is entered
8578 main(int argc, char **argv, char **envp)
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.
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)).
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
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:
8597 [ENOTDIR] A component of the path prefix is not a directory.
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.
8603 [ENOENT] The new process file does not exist.
8605 [ELOOP] Too many symbolic links were encountered in
8606 translating the pathname.
8608 [EACCES] Search permission is denied for a component of the
8611 [EACCES] The new process file is not an ordinary file.
8613 [EACCES] The new process file mode denies execute permission.
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>).
8618 [ENOEXEC] The new process file has the appropriate access
8619 permission, but has an invalid magic number in its
8622 [ETXTBSY] The new process file is a pure procedure (shared text)
8623 file that is currently open for writing or reading by
8626 [ENOMEM] The new process requires more virtual memory than is
8627 allowed by the imposed maximum (getrlimit(2)).
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>).
8634 [EFAULT] The new process file is not as long as indicated by
8635 the size values in its header.
8637 [EFAULT] _
\bp_
\ba_
\bt_
\bh, _
\ba_
\br_
\bg_
\bv, or _
\be_
\bn_
\bv_
\bp point to an illegal address.
8639 [EINVAL] _
\ba_
\br_
\bg_
\bv did not contain at least one element.
8641 [EIO] An I/O error occurred while reading from the file
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.
8647 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
8648 _exit(2), fork(2), execl(3), exit(3), elf(5), environ(7)
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
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.
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
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
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>
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);
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>
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);
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
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.
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.
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.
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().
8707 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
8710 AT_EACCESS The checks for accessibility are performed using the
8711 effective user and group IDs instead of the real user
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.
8718 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
8719 Access to the file is denied if:
8721 [ENOTDIR] A component of the path prefix is not a directory.
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.
8727 [ENOENT] The named file does not exist.
8729 [ELOOP] Too many symbolic links were encountered in
8730 translating the pathname.
8732 [EROFS] Write access is requested for a file on a read-only
8735 [ETXTBSY] Write access is requested for a pure procedure (shared
8736 text) file presently being executed.
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.
8748 [EPERM] Write access has been requested and the named file has
8749 its immutable flag set (see chflags(2)).
8751 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
8754 [EIO] An I/O error occurred while reading from or writing to
8757 [EINVAL] An invalid value was specified for _
\ba_
\bm_
\bo_
\bd_
\be.
8759 Additionally, f
\bfa
\bac
\bcc
\bce
\bes
\bss
\bsa
\bat
\bt() will fail if:
8761 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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
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.
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.
8776 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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
8790 The f
\bfa
\bac
\bcc
\bce
\bes
\bss
\bsa
\bat
\bt() function appeared in OpenBSD 5.0.
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.
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.
8800 c
\bch
\bhd
\bdi
\bir
\br, f
\bfc
\bch
\bhd
\bdi
\bir
\br - change current working directory
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>
8806 c
\bch
\bhd
\bdi
\bir
\br(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bp_
\ba_
\bt_
\bh);
8809 f
\bfc
\bch
\bhd
\bdi
\bir
\br(_
\bi_
\bn_
\bt _
\bf_
\bd);
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 (`/').
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 (`/').
8821 In order for a directory to become the current directory, a process must
8822 have execute (search) access to the directory.
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
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:
8833 [ENOTDIR] A component of the path prefix is not a directory.
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.
8839 [ENOENT] The named directory does not exist.
8841 [ELOOP] Too many symbolic links were encountered in
8842 translating the pathname.
8844 [EACCES] Search permission is denied for any component of the
8847 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
8850 [EIO] An I/O error occurred while reading from the file
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:
8856 [EACCES] Search permission is denied for the directory
8857 referenced by the file descriptor.
8859 [ENOTDIR] The file descriptor does not reference a directory.
8861 [EBADF] The argument _
\bf_
\bd is not a valid file descriptor.
8863 [EIO] An I/O error occurred while reading from the file
8866 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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'').
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.
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
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>
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);
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);
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>
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);
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.
8899 The flags are the bitwise OR of zero or more of the following values:
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.
8908 The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the
8909 owner of a file or the superuser.
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
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.
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().
8925 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
8928 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the flags
8929 of the symbolic link are changed.
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.
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
8939 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
8940 c
\bch
\bhf
\bfl
\bla
\bag
\bgs
\bs() will fail if:
8942 [ENOTDIR] A component of the path prefix is not a directory.
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.
8948 [ENOENT] The named file does not exist.
8950 [EACCES] Search permission is denied for a component of the
8953 [ELOOP] Too many symbolic links were encountered in
8954 translating the pathname.
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.
8962 [EOPNOTSUPP] The named file resides on a file system that does not
8965 [EROFS] The named file resides on a read-only file system.
8967 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
8970 [EIO] An I/O error occurred while reading from or writing to
8973 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs value is invalid.
8975 [EINVAL] The descriptor references a block or character device
8976 and the effective user ID is not the superuser.
8978 f
\bfc
\bch
\bhf
\bfl
\bla
\bag
\bgs
\bs() will fail if:
8980 [EBADF] The descriptor is not valid.
8982 [EINVAL] _
\bf_
\bd refers to a socket, not to a file.
8984 [EINVAL] The descriptor references a block or character device
8985 and the effective user ID is not the superuser.
8987 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs value is invalid.
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.
8995 [EOPNOTSUPP] The named file resides on a file system that does not
8998 [EROFS] The file resides on a read-only file system.
9000 [EIO] An I/O error occurred while reading from or writing to
9003 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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
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>
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);
9021 f
\bfc
\bch
\bhm
\bmo
\bod
\bd(_
\bi_
\bn_
\bt _
\bf_
\bd, _
\bm_
\bo_
\bd_
\be_
\b__
\bt _
\bm_
\bo_
\bd_
\be);
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>
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);
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.
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:
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 */
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 */
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 */
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 */
9056 If mode ISVTX (the _
\bs_
\bt_
\bi_
\bc_
\bk_
\by _
\bb_
\bi_
\bt) is set on a file, it is ignored.
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).
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.
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.
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().
9079 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
9082 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the mode
9083 of the symbolic link is changed.
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.
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
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
9097 [ENOTDIR] A component of the path prefix is not a directory.
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.
9103 [ENOENT] The named file does not exist.
9105 [EACCES] Search permission is denied for a component of the
9108 [EINVAL] _
\bm_
\bo_
\bd_
\be contains bits other than the file type and those
9111 [ELOOP] Too many symbolic links were encountered in
9112 translating the pathname.
9114 [EPERM] The effective user ID does not match the owner of the
9115 file and the effective user ID is not the superuser.
9117 [EROFS] The named file resides on a read-only file system.
9119 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
9122 [EIO] An I/O error occurred while reading from or writing to
9125 Additionally, the f
\bfc
\bch
\bhm
\bmo
\bod
\bda
\bat
\bt() function will fail if:
9127 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
9128 AT_SYMLINK_NOFOLLOW.
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
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.
9138 [EOPNOTSUPP] The _
\bf_
\bl_
\ba_
\bg argument specifies AT_SYMLINK_NOFOLLOW on a
9139 symbolic link and the file system does not support
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.
9146 f
\bfc
\bch
\bhm
\bmo
\bod
\bd() will fail and the file mode will be unchanged if:
9148 [EBADF] The descriptor is not valid.
9150 [EINVAL] _
\bf_
\bd refers to a socket, not to a file.
9152 [EINVAL] _
\bm_
\bo_
\bd_
\be contains bits other than the file type and those
9155 [EPERM] The effective user ID does not match the owner of the
9156 file and the effective user ID is not the superuser.
9158 [EROFS] The file resides on a read-only file system.
9160 [EIO] An I/O error occurred while reading from or writing to
9163 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
9164 chmod(1), chown(2), open(2), stat(2), sticky(8)
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'').
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.
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
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>
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);
9184 f
\bfc
\bch
\bhm
\bmo
\bod
\bd(_
\bi_
\bn_
\bt _
\bf_
\bd, _
\bm_
\bo_
\bd_
\be_
\b__
\bt _
\bm_
\bo_
\bd_
\be);
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>
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);
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.
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:
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 */
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 */
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 */
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 */
9219 If mode ISVTX (the _
\bs_
\bt_
\bi_
\bc_
\bk_
\by _
\bb_
\bi_
\bt) is set on a file, it is ignored.
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).
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.
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.
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().
9242 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
9245 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the mode
9246 of the symbolic link is changed.
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.
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
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
9260 [ENOTDIR] A component of the path prefix is not a directory.
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.
9266 [ENOENT] The named file does not exist.
9268 [EACCES] Search permission is denied for a component of the
9271 [EINVAL] _
\bm_
\bo_
\bd_
\be contains bits other than the file type and those
9274 [ELOOP] Too many symbolic links were encountered in
9275 translating the pathname.
9277 [EPERM] The effective user ID does not match the owner of the
9278 file and the effective user ID is not the superuser.
9280 [EROFS] The named file resides on a read-only file system.
9282 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
9285 [EIO] An I/O error occurred while reading from or writing to
9288 Additionally, the f
\bfc
\bch
\bhm
\bmo
\bod
\bda
\bat
\bt() function will fail if:
9290 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
9291 AT_SYMLINK_NOFOLLOW.
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
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.
9301 [EOPNOTSUPP] The _
\bf_
\bl_
\ba_
\bg argument specifies AT_SYMLINK_NOFOLLOW on a
9302 symbolic link and the file system does not support
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.
9309 f
\bfc
\bch
\bhm
\bmo
\bod
\bd() will fail and the file mode will be unchanged if:
9311 [EBADF] The descriptor is not valid.
9313 [EINVAL] _
\bf_
\bd refers to a socket, not to a file.
9315 [EINVAL] _
\bm_
\bo_
\bd_
\be contains bits other than the file type and those
9318 [EPERM] The effective user ID does not match the owner of the
9319 file and the effective user ID is not the superuser.
9321 [EROFS] The file resides on a read-only file system.
9323 [EIO] An I/O error occurred while reading from or writing to
9326 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
9327 chmod(1), chown(2), open(2), stat(2), sticky(8)
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'').
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.
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
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.
9386 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
9389 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the
9390 ownership of the symbolic link is changed.
9392 f
\bfc
\bch
\bho
\bow
\bwn
\bn() is particularly useful when used in conjunction with the file
9393 locking primitives (see flock(2)).
9395 One of the owner or group IDs may be left unchanged by specifying it as
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
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
9407 [ENOTDIR] A component of the path prefix is not a directory.
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.
9413 [ENOENT] The named file does not exist.
9415 [EACCES] Search permission is denied for a component of the
9418 [ELOOP] Too many symbolic links were encountered in
9419 translating the pathname.
9421 [EPERM] The effective user ID is not the superuser.
9423 [EROFS] The named file resides on a read-only file system.
9425 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
9428 [EIO] An I/O error occurred while reading from or writing to
9431 Additionally, f
\bfc
\bch
\bho
\bow
\bwn
\bna
\bat
\bt() will fail if:
9433 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
9434 AT_SYMLINK_NOFOLLOW.
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
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.
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.
9448 f
\bfc
\bch
\bho
\bow
\bwn
\bn() will fail if:
9450 [EBADF] _
\bf_
\bd does not refer to a valid descriptor.
9452 [EINVAL] _
\bf_
\bd refers to a socket, not a file.
9454 [EPERM] The effective user ID is not the superuser.
9456 [EROFS] The named file resides on a read-only file system.
9458 [EIO] An I/O error occurred while reading from or writing to
9461 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
9462 chgrp(1), chmod(2), flock(2), chown(8)
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'').
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.
9473 The f
\bfc
\bch
\bho
\bow
\bwn
\bn() system call first appeared in 4.1cBSD.
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.
9479 The f
\bfc
\bch
\bho
\bow
\bwn
\bna
\bat
\bt() system call has been available since OpenBSD 5.0.
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
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.
9530 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
9533 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the
9534 ownership of the symbolic link is changed.
9536 f
\bfc
\bch
\bho
\bow
\bwn
\bn() is particularly useful when used in conjunction with the file
9537 locking primitives (see flock(2)).
9539 One of the owner or group IDs may be left unchanged by specifying it as
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
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
9551 [ENOTDIR] A component of the path prefix is not a directory.
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.
9557 [ENOENT] The named file does not exist.
9559 [EACCES] Search permission is denied for a component of the
9562 [ELOOP] Too many symbolic links were encountered in
9563 translating the pathname.
9565 [EPERM] The effective user ID is not the superuser.
9567 [EROFS] The named file resides on a read-only file system.
9569 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
9572 [EIO] An I/O error occurred while reading from or writing to
9575 Additionally, f
\bfc
\bch
\bho
\bow
\bwn
\bna
\bat
\bt() will fail if:
9577 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
9578 AT_SYMLINK_NOFOLLOW.
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
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.
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.
9592 f
\bfc
\bch
\bho
\bow
\bwn
\bn() will fail if:
9594 [EBADF] _
\bf_
\bd does not refer to a valid descriptor.
9596 [EINVAL] _
\bf_
\bd refers to a socket, not a file.
9598 [EPERM] The effective user ID is not the superuser.
9600 [EROFS] The named file resides on a read-only file system.
9602 [EIO] An I/O error occurred while reading from or writing to
9605 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
9606 chgrp(1), chmod(2), flock(2), chown(8)
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'').
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.
9617 The f
\bfc
\bch
\bho
\bow
\bwn
\bn() system call first appeared in 4.1cBSD.
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.
9623 The f
\bfc
\bch
\bho
\bow
\bwn
\bna
\bat
\bt() system call has been available since OpenBSD 5.0.
9626 f
\bfc
\bcn
\bnt
\btl
\bl - file control
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>
9632 f
\bfc
\bcn
\bnt
\btl
\bl(_
\bi_
\bn_
\bt _
\bf_
\bd, _
\bi_
\bn_
\bt _
\bc_
\bm_
\bd, _
\b._
\b._
\b.);
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.
9643 F_DUPFD Return a new descriptor as follows:
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
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)
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.
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).
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.
9671 F_GETFL Get file status flags associated with the file
9672 descriptor _
\bf_
\bd, as described below (_
\ba_
\br_
\bg is ignored).
9674 F_SETFL Set file status flags associated with the file
9675 descriptor _
\bf_
\bd to _
\ba_
\br_
\bg (interpreted as an int).
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).
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.
9686 The flags for the F_GETFL and F_SETFL commands are as follows:
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.
9692 O_APPEND Force each write to append at the end of file; corresponds
9693 to the O_APPEND flag of open(2).
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.
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).
9702 Several commands are available for doing advisory file locking; they all
9703 operate on the following structure:
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 */
9713 The commands available for advisory record locking are as follows:
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.
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.
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)).
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.
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.
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.
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.
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.
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
9794 All locks associated with a file for a given process are removed when the
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.
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:
9805 F_DUPFD A new file descriptor.
9807 F_DUPFD_CLOEXEC A new file descriptor.
9809 F_GETFD Value of flag (only the low-order bit is defined).
9811 F_GETFL Value of flags.
9813 F_GETOWN Value of file descriptor owner.
9815 other Value other than -1.
9817 Otherwise, a value of -1 is returned and _
\be_
\br_
\br_
\bn_
\bo is set to indicate the
9820 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
9821 f
\bfc
\bcn
\bnt
\btl
\bl() will fail if:
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.
9831 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
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.
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.
9841 [EDEADLK] The argument _
\bc_
\bm_
\bd is F_SETLKW, and a deadlock condition
9844 [EINTR] The argument _
\bc_
\bm_
\bd is invalid.
9846 The argument _
\bc_
\bm_
\bd is F_SETLKW, and the function was
9847 interrupted by a signal.
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)).
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.
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.
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.
9866 [ESRCH] _
\bc_
\bm_
\bd is F_SETOWN and the process ID given in _
\ba_
\br_
\bg is not
9869 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
9870 close(2), execve(2), flock(2), open(2), sigaction(2), getdtablesize(3)
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'').
9875 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
9876 The f
\bfc
\bcn
\bnt
\btl
\bl() function call appeared in 4.2BSD.
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
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>
9885 f
\bfs
\bsy
\byn
\bnc
\bc(_
\bi_
\bn_
\bt _
\bf_
\bd);
9888 f
\bfd
\bda
\bat
\bta
\bas
\bsy
\byn
\bnc
\bc(_
\bi_
\bn_
\bt _
\bf_
\bd);
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
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
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
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.
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:
9913 [EBADF] _
\bf_
\bd is not a valid descriptor.
9915 [EINVAL] _
\bf_
\bd does not refer to a file which can be synchronized.
9917 [EIO] An I/O error occurred while reading from or writing to
9920 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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.
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.
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
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>
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);
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);
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);
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.
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.
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.
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.
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
9974 [EINVAL] Calling f
\bfh
\bho
\bop
\bpe
\ben
\bn() with O_CREAT set.
9976 [ESTALE] The file handle _
\bf_
\bh_
\bp is no longer valid.
9978 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
9979 fstat(2), fstatfs(2), getfh(2), open(2)
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
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
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>
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);
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);
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);
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.
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.
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.
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.
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
10024 [EINVAL] Calling f
\bfh
\bho
\bop
\bpe
\ben
\bn() with O_CREAT set.
10026 [ESTALE] The file handle _
\bf_
\bh_
\bp is no longer valid.
10028 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
10029 fstat(2), fstatfs(2), getfh(2), open(2)
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
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
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>
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);
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);
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);
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.
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.
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.
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.
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
10074 [EINVAL] Calling f
\bfh
\bho
\bop
\bpe
\ben
\bn() with O_CREAT set.
10076 [ESTALE] The file handle _
\bf_
\bh_
\bp is no longer valid.
10078 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
10079 fstat(2), fstatfs(2), getfh(2), open(2)
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
10086 f
\bfl
\blo
\boc
\bck
\bk - apply or remove an advisory lock on an open file
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>
10092 f
\bfl
\blo
\boc
\bck
\bk(_
\bi_
\bn_
\bt _
\bf_
\bd, _
\bi_
\bn_
\bt _
\bo_
\bp_
\be_
\br_
\ba_
\bt_
\bi_
\bo_
\bn);
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:
10098 LOCK_SH Apply a shared lock.
10099 LOCK_EX Apply an exclusive lock.
10100 LOCK_UN Remove an existing lock.
10102 LOCK_SH and LOCK_EX may be combined with the optional LOCK_NB for
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
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.
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).
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.
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.
10132 Processes blocked awaiting a lock may be awakened by signals.
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
10139 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
10140 The f
\bfl
\blo
\boc
\bck
\bk() call fails if:
10142 [EWOULDBLOCK] The file is locked and the LOCK_NB option was
10145 [EBADF] The argument _
\bf_
\bd is an invalid descriptor.
10147 [EINVAL] The argument _
\bo_
\bp_
\be_
\br_
\ba_
\bt_
\bi_
\bo_
\bn has an invalid value.
10149 [EOPNOTSUPP] The referenced descriptor is not of the correct type.
10151 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
10152 close(2), dup(2), execve(2), fcntl(2), fork(2), open(2)
10154 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
10155 The f
\bfl
\blo
\boc
\bck
\bk() system call first appeared in 4.1cBSD.
10158 f
\bfo
\bor
\brk
\bk - create a new process
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>
10163 _
\bp_
\bi_
\bd_
\b__
\bt
10164 f
\bfo
\bor
\brk
\bk(_
\bv_
\bo_
\bi_
\bd);
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
10171 +
\b+
\bo
\bo The child process has a unique process ID, which also does not
10172 match any existing process group ID.
10174 +
\b+
\bo
\bo The child process has a different parent process ID (i.e., the
10175 process ID of the parent process).
10177 +
\b+
\bo
\bo The child process has a single thread.
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.
10188 +
\b+
\bo
\bo The child process has no fcntl(2)-style file locks.
10190 +
\b+
\bo
\bo The child process' resource utilizations are set to 0; see
10193 +
\b+
\bo
\bo All interval timers are cleared; see setitimer(2).
10195 +
\b+
\bo
\bo The child process' semaphore undo values are set to 0; see
10198 +
\b+
\bo
\bo The child process' pending signals set is empty.
10200 +
\b+
\bo
\bo The child process has no memory locks; see mlock(2) and
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
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.
10216 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
10217 f
\bfo
\bor
\brk
\bk() will fail and no child process will be created if:
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.
10223 [EAGAIN] The limit RLIMIT_NPROC on the total number of processes under
10224 execution by the user ID would be exceeded.
10226 [ENOMEM] There is insufficient swap space for the new process.
10228 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
10229 execve(2), getrusage(2), wait(2)
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'').
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.
10238 p
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf, f
\bfp
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf - get configurable pathname variables
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>
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);
10247 f
\bfp
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf(_
\bi_
\bn_
\bt _
\bf_
\bd, _
\bi_
\bn_
\bt _
\bn_
\ba_
\bm_
\be);
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.
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>.
10259 The available values are as follows:
10262 The maximum file link count.
10265 The maximum number of bytes in a terminal canonical input line.
10268 The maximum number of bytes for which space is available in a
10269 terminal input queue.
10272 The maximum number of bytes in a file name.
10275 The maximum number of bytes in a pathname.
10278 The maximum number of bytes which will be written atomically to a
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.
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
10297 Returns the terminal character disabling value.
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.
10305 Minimum number of bytes of storage allocated for any portion of a
10309 Returns 1 if asynchronous I/O is supported, otherwise 0.
10312 Number of bits needed to represent the maximum file size.
10315 Returns 1 if prioritized I/O is supported, otherwise 0.
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.
10321 _PC_REC_MAX_XFER_SIZE
10322 Maximum recommended file transfer size.
10324 _PC_REC_MIN_XFER_SIZE
10325 Minimum recommended file transfer size.
10328 Recommended file transfer buffer alignment.
10331 Maximum number of bytes in a symbolic link.
10334 Returns 1 if synchronized I/O is supported, otherwise 0.
10336 _PC_TIMESTAMP_RESOLUTION
10337 The resolution in nanoseconds of file timestamps.
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
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.
10350 [EINVAL] The value of the _
\bn_
\ba_
\bm_
\be argument is invalid.
10352 [EINVAL] The implementation does not support an association of
10353 the variable name with the associated file.
10355 [EIO] An I/O error occurred while reading from the file
10358 p
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf() will fail if:
10360 [ENOTDIR] A component of the path prefix is not a directory.
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
10367 [ENOENT] The named file does not exist.
10369 [EACCES] Search permission is denied for a component of the
10372 [ELOOP] Too many symbolic links were encountered in
10373 translating the pathname.
10375 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
10378 f
\bfp
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf() will fail if:
10380 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
10382 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
10383 sysconf(3), sysctl(3)
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
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.
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
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>
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);
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);
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);
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>
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);
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.
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.
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.
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.
10434 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
10437 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
10438 of the symbolic link is returned.
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.
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.
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 */
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
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.
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.
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.
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.
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
10494 The size-related fields of the struct stat are as follows:
10496 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
10502 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
10539 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
10549 [ENOTDIR] A component of the path prefix is not a directory.
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.
10555 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
10558 [EACCES] Search permission is denied for a component of the
10561 [ELOOP] Too many symbolic links were encountered in
10562 translating the pathname.
10564 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
10566 [EIO] An I/O error occurred while reading from or writing to
10569 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
10571 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
10572 AT_SYMLINK_NOFOLLOW.
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
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.
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.
10586 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
10588 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
10590 [EFAULT] _
\bs_
\bb points to an invalid address.
10592 [EIO] An I/O error occurred while reading from the file
10595 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
10596 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
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);
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);
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);
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>
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);
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.
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.
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.
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.
10668 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
10671 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
10672 of the symbolic link is returned.
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.
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.
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 */
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
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.
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.
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.
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.
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
10728 The size-related fields of the struct stat are as follows:
10730 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
10736 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
10773 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
10783 [ENOTDIR] A component of the path prefix is not a directory.
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.
10789 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
10792 [EACCES] Search permission is denied for a component of the
10795 [ELOOP] Too many symbolic links were encountered in
10796 translating the pathname.
10798 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
10800 [EIO] An I/O error occurred while reading from or writing to
10803 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
10805 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
10806 AT_SYMLINK_NOFOLLOW.
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
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.
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.
10820 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
10822 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
10824 [EFAULT] _
\bs_
\bb points to an invalid address.
10826 [EIO] An I/O error occurred while reading from the file
10829 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
10830 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
10861 s
\bst
\bta
\bat
\btf
\bfs
\bs, f
\bfs
\bst
\bta
\bat
\btf
\bfs
\bs - get file system statistics
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>
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);
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);
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:
10878 typedef struct { int32_t val[2]; } fsid_t;
10880 #define MFSNAMELEN 16 /* length of fs type name, including nul */
10881 #define MNAMELEN 90 /* length of buffer for returned name */
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 */
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 */
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 */
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 */
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 */
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 */
10914 f
\bfs
\bst
\bta
\bat
\btf
\bfs
\bs() returns the same information about an open file referenced by
10915 descriptor _
\bf_
\bd.
10917 Note that _
\bf_
\b__
\bf_
\bs_
\bi_
\bd will be empty unless the user is the superuser.
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
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:
10927 [ENOTDIR] A component of the path prefix of _
\bp_
\ba_
\bt_
\bh is not a
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.
10934 [ENOENT] The file referred to by _
\bp_
\ba_
\bt_
\bh does not exist.
10936 [EACCES] Search permission is denied for a component of the
10937 path prefix of _
\bp_
\ba_
\bt_
\bh.
10939 [ELOOP] Too many symbolic links were encountered in
10940 translating _
\bp_
\ba_
\bt_
\bh.
10942 [EFAULT] _
\bb_
\bu_
\bf or _
\bp_
\ba_
\bt_
\bh points to an invalid address.
10944 [EIO] An I/O error occurred while reading from or writing to
10947 f
\bfs
\bst
\bta
\bat
\btf
\bfs
\bs() fails if one or more of the following are true:
10949 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
10951 [EFAULT] _
\bb_
\bu_
\bf points to an invalid address.
10953 [EIO] An I/O error occurred while reading from or writing to
10956 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
10957 df(1), getfsstat(2), mount(2), stat(2)
10959 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
10960 The s
\bst
\bta
\bat
\btf
\bfs
\bs() function first appeared in 4.4BSD.
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
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>
10969 f
\bfs
\bsy
\byn
\bnc
\bc(_
\bi_
\bn_
\bt _
\bf_
\bd);
10972 f
\bfd
\bda
\bat
\bta
\bas
\bsy
\byn
\bnc
\bc(_
\bi_
\bn_
\bt _
\bf_
\bd);
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
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
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
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.
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:
10997 [EBADF] _
\bf_
\bd is not a valid descriptor.
10999 [EINVAL] _
\bf_
\bd does not refer to a file which can be synchronized.
11001 [EIO] An I/O error occurred while reading from or writing to
11004 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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.
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.
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
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>
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);
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);
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.
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
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:
11046 [EINVAL] The _
\bl_
\be_
\bn_
\bg_
\bt_
\bh is a negative value.
11048 [EIO] An I/O error occurred updating the inode.
11050 In addition, t
\btr
\bru
\bun
\bnc
\bca
\bat
\bte
\be() may return the following errors:
11052 [ENOTDIR] A component of the path prefix is not a directory.
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.
11058 [ENOENT] The named file does not exist.
11060 [EACCES] Search permission is denied for a component of the
11063 [EACCES] The named file is not writable by the user.
11065 [ELOOP] Too many symbolic links were encountered in
11066 translating the pathname.
11068 [EISDIR] The named file is a directory.
11070 [EROFS] The named file resides on a read-only file system.
11072 [ETXTBSY] The file is a pure procedure (shared text) file that
11075 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
11078 f
\bft
\btr
\bru
\bun
\bnc
\bca
\bat
\bte
\be() may return the following errors:
11080 [EBADF] The _
\bf_
\bd is not a valid descriptor.
11082 [EINVAL] The _
\bf_
\bd references a socket, not a file.
11084 [EINVAL] The _
\bf_
\bd is not open for writing.
11086 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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.
11097 These calls should be generalized to allow ranges of bytes in a file to
11100 Use of t
\btr
\bru
\bun
\bnc
\bca
\bat
\bte
\be() to extend a file is not portable.
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
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>
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);
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);
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>
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);
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]);
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.
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.
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.
11138 In either case, the inode-change-time of the file is set to the current
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.
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>:
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.
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
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.
11160 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
11163 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the
11164 timestamps of the symbolic link are changed.
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
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:
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
11180 [EFAULT] _
\bf_
\bi_
\bl_
\be or _
\bt_
\bi_
\bm_
\be_
\bs points outside the process's allocated
11183 [EIO] An I/O error occurred while reading or writing the
11186 [ELOOP] Too many symbolic links were encountered in
11187 translating the pathname.
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.
11193 [ENOENT] The named file does not exist.
11195 [ENOTDIR] A component of the path prefix is not a directory.
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.
11201 [EROFS] The file system containing the file is mounted read-
11204 Additionally, u
\but
\bti
\bim
\bme
\ben
\bns
\bsa
\bat
\bt() will fail if:
11206 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
11207 AT_SYMLINK_NOFOLLOW.
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
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.
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.
11221 f
\bfu
\but
\bti
\bim
\bme
\bes
\bs() and f
\bfu
\but
\bti
\bim
\bme
\ben
\bns
\bs() will fail if:
11223 [EBADF] _
\bf_
\bd does not refer to a valid descriptor.
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.
11229 [EFAULT] _
\bt_
\bi_
\bm_
\be_
\bs points outside the process's allocated address
11232 [EIO] An I/O error occurred while reading or writing the
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.
11239 [EROFS] The file system containing the file is mounted read-
11242 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11243 clock_gettime(2), stat(2), utime(3)
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'').
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
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.
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.
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
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>
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);
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);
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>
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);
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]);
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.
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.
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.
11302 In either case, the inode-change-time of the file is set to the current
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.
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>:
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.
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
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.
11324 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
11327 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the
11328 timestamps of the symbolic link are changed.
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
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:
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
11344 [EFAULT] _
\bf_
\bi_
\bl_
\be or _
\bt_
\bi_
\bm_
\be_
\bs points outside the process's allocated
11347 [EIO] An I/O error occurred while reading or writing the
11350 [ELOOP] Too many symbolic links were encountered in
11351 translating the pathname.
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.
11357 [ENOENT] The named file does not exist.
11359 [ENOTDIR] A component of the path prefix is not a directory.
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.
11365 [EROFS] The file system containing the file is mounted read-
11368 Additionally, u
\but
\bti
\bim
\bme
\ben
\bns
\bsa
\bat
\bt() will fail if:
11370 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
11371 AT_SYMLINK_NOFOLLOW.
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
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.
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.
11385 f
\bfu
\but
\bti
\bim
\bme
\bes
\bs() and f
\bfu
\but
\bti
\bim
\bme
\ben
\bns
\bs() will fail if:
11387 [EBADF] _
\bf_
\bd does not refer to a valid descriptor.
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.
11393 [EFAULT] _
\bt_
\bi_
\bm_
\be_
\bs points outside the process's allocated address
11396 [EIO] An I/O error occurred while reading or writing the
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.
11403 [EROFS] The file system containing the file is mounted read-
11406 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11407 clock_gettime(2), stat(2), utime(3)
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'').
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
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.
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.
11431 g
\bge
\bet
\btd
\bde
\ben
\bnt
\bts
\bs - get directory entries in a filesystem independent format
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>
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);
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.
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:
11452 u_int16_t d_reclen;
11455 char d_name[MAXNAMLEN + 1]; /* see below */
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.
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.
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 +
11469 The _
\bd_
\b__
\bn_
\ba_
\bm_
\be entry contains a NUL-terminated file name.
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,
11475 Invalid entries with _
\bd_
\b__
\bf_
\bi_
\bl_
\be_
\bn_
\bo set to 0 may be returned among regular
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().
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.
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.
11493 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
11494 g
\bge
\bet
\btd
\bde
\ben
\bnt
\bts
\bs() will fail if:
11496 [EBADF] _
\bf_
\bd is not a valid file descriptor open for reading.
11498 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
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
11506 [EIO] An I/O error occurred while reading from or writing to
11509 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11510 lseek(2), open(2), opendir(3), dirent(5)
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.
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().
11522 g
\bge
\bet
\btd
\bdt
\bta
\bab
\bbl
\ble
\bec
\bco
\bou
\bun
\bnt
\bt - get descriptor table count
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>
11528 g
\bge
\bet
\btd
\bdt
\bta
\bab
\bbl
\ble
\bec
\bco
\bou
\bun
\bnt
\bt(_
\bv_
\bo_
\bi_
\bd);
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
11534 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11535 getrlimit(2), getdtablesize(3)
11537 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
11538 The k
\bkq
\bqu
\bue
\beu
\bue
\be function appeared in OpenBSD 5.2.
11541 g
\bge
\bet
\btg
\bgi
\bid
\bd, g
\bge
\bet
\bte
\beg
\bgi
\bid
\bd - get group process identification
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>
11546 _
\bg_
\bi_
\bd_
\b__
\bt
11547 g
\bge
\bet
\btg
\bgi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
11549 _
\bg_
\bi_
\bd_
\b__
\bt
11550 g
\bge
\bet
\bte
\beg
\bgi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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
11557 The real group ID is specified at login time.
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.
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.
11568 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11569 getgroups(2), getresgid(2), getuid(2), setgid(2), setregid(2)
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
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.
11580 g
\bge
\bet
\bte
\ben
\bnt
\btr
\bro
\bop
\bpy
\by - get entropy
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>
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);
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).
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.
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.
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
11603 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
11604 g
\bge
\bet
\bte
\ben
\bnt
\btr
\bro
\bop
\bpy
\by() will succeed unless:
11606 [EFAULT] The _
\bb_
\bu_
\bf parameter points to an invalid address.
11608 [EIO] Too many bytes requested, or some other fatal error
11611 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
11618 g
\bge
\bet
\btu
\bui
\bid
\bd, g
\bge
\bet
\bte
\beu
\bui
\bid
\bd - get user identification
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>
11623 _
\bu_
\bi_
\bd_
\b__
\bt
11624 g
\bge
\bet
\btu
\bui
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
11626 _
\bu_
\bi_
\bd_
\b__
\bt
11627 g
\bge
\bet
\bte
\beu
\bui
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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
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.
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.
11643 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11644 getgid(2), getresuid(2), setreuid(2), setuid(2)
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
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.
11655 g
\bge
\bet
\btf
\bfh
\bh - get file handle
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>
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);
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
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
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:
11677 [ENOTDIR] A component of the path prefix of _
\bp_
\ba_
\bt_
\bh is not a
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.
11684 [ENOENT] The file referred to by _
\bp_
\ba_
\bt_
\bh does not exist.
11686 [EACCES] Search permission is denied for a component of the
11687 path prefix of _
\bp_
\ba_
\bt_
\bh.
11689 [ELOOP] Too many symbolic links were encountered in
11690 translating _
\bp_
\ba_
\bt_
\bh.
11692 [EPERM] The effective user ID is not the superuser.
11694 [EFAULT] _
\bf_
\bh_
\bp or _
\bp_
\ba_
\bt_
\bh points to an invalid address.
11696 [EIO] An I/O error occurred while reading from or writing to
11699 [EINVAL] A portion of _
\bp_
\ba_
\bt_
\bh refers to a remote file system.
11701 [EOPNOTSUPP] A portion of _
\bp_
\ba_
\bt_
\bh refers to a remote file system.
11703 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11706 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
11707 The g
\bge
\bet
\btf
\bfh
\bh() function first appeared in 4.4BSD.
11710 g
\bge
\bet
\btf
\bfs
\bss
\bst
\bta
\bat
\bt - get list of all mounted file systems
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>
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);
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:
11723 typedef struct { int32_t val[2]; } fsid_t;
11725 #define MFSNAMELEN 16 /* length of fs type name, including nul */
11726 #define MNAMELEN 90 /* length of buffer for returned name */
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 */
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 */
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 */
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 */
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 */
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 */
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.
11762 If _
\bb_
\bu_
\bf is NULL, g
\bge
\bet
\btf
\bfs
\bss
\bst
\bta
\bat
\bt() returns just the number of mounted file
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.
11772 Note that _
\bf_
\b__
\bf_
\bs_
\bi_
\bd will be empty unless the user is the superuser.
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.
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:
11782 [EFAULT] _
\bb_
\bu_
\bf points to an invalid address.
11784 [EIO] An I/O error occurred while reading from or writing to
11787 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11788 statfs(2), fstab(5), mount(8)
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.
11794 g
\bge
\bet
\btg
\bgi
\bid
\bd, g
\bge
\bet
\bte
\beg
\bgi
\bid
\bd - get group process identification
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>
11799 _
\bg_
\bi_
\bd_
\b__
\bt
11800 g
\bge
\bet
\btg
\bgi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
11802 _
\bg_
\bi_
\bd_
\b__
\bt
11803 g
\bge
\bet
\bte
\beg
\bgi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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
11810 The real group ID is specified at login time.
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.
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.
11821 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11822 getgroups(2), getresgid(2), getuid(2), setgid(2), setregid(2)
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
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.
11833 g
\bge
\bet
\btg
\bgr
\bro
\bou
\bup
\bps
\bs - get group access list
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>
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);
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
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.
11855 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
11856 The possible errors for g
\bge
\bet
\btg
\bgr
\bro
\bou
\bup
\bps
\bs() are:
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.
11861 [EFAULT] The argument _
\bg_
\bi_
\bd_
\bs_
\be_
\bt specifies an invalid address.
11863 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11864 getgid(2), setgid(2), setgroups(2), initgroups(3)
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'').
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.
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
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>
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
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);
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);
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*);
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*);
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);
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);
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);
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).
11911 A timer value is defined by the _
\bi_
\bt_
\bi_
\bm_
\be_
\br_
\bv_
\ba_
\bl structure:
11914 struct timeval it_interval; /* timer interval */
11915 struct timeval it_value; /* current value */
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).
11924 Time values smaller than the resolution of the system clock are rounded
11925 up to this resolution (typically 10 milliseconds).
11927 The ITIMER_REAL timer decrements in real time. A SIGALRM signal is
11928 delivered when this timer expires.
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
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.
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>.
11945 t
\bti
\bim
\bme
\ber
\brc
\bcl
\ble
\bea
\bar
\br(_
\ba) sets the time value in _
\ba to zero.
11947 t
\bti
\bim
\bme
\ber
\bri
\bis
\bss
\bse
\bet
\bt(_
\ba) tests if the time value in _
\ba is non-zero.
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 > .
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.
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.
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
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:
11964 [EFAULT] The _
\bv_
\ba_
\bl_
\bu_
\be parameter specified a bad address.
11966 [EINVAL] An unrecognized value for _
\bw_
\bh_
\bi_
\bc_
\bh was specified.
11968 In addition, s
\bse
\bet
\bti
\bit
\bti
\bim
\bme
\ber
\br() may return the following error:
11970 [EINVAL] _
\bv_
\ba_
\bl_
\bu_
\be or _
\bo_
\bv_
\ba_
\bl_
\bu_
\be specified a time that was too large to
11973 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
11974 clock_gettime(2), gettimeofday(2), poll(2), select(2), sigaction(2)
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
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.
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
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>
11989 _
\bc_
\bh_
\ba_
\br _
\b*
11990 g
\bge
\bet
\btl
\blo
\bog
\bgi
\bin
\bn(_
\bv_
\bo_
\bi_
\bd);
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);
11996 s
\bse
\bet
\btl
\blo
\bog
\bgi
\bin
\bn(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bn_
\ba_
\bm_
\be);
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.)
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).
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
12019 _
\bN_
\bO_
\bT_
\bE: There is only one login name per session.
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.
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.
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.
12035 This is different from traditional UNIX privilege inheritance and as such
12036 can be counter-intuitive.
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.
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.
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:
12053 [EFAULT] The _
\bn_
\ba_
\bm_
\be parameter points to an invalid address.
12055 In addition, g
\bge
\bet
\btl
\blo
\bog
\bgi
\bin
\bn_
\b_r
\br() may return the following error:
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.
12060 s
\bse
\bet
\btl
\blo
\bog
\bgi
\bin
\bn() may return the following errors:
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.
12066 [EPERM] The caller tried to set the login name and was not the
12069 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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.
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.
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
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>
12093 _
\bc_
\bh_
\ba_
\br _
\b*
12094 g
\bge
\bet
\btl
\blo
\bog
\bgi
\bin
\bn(_
\bv_
\bo_
\bi_
\bd);
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);
12100 s
\bse
\bet
\btl
\blo
\bog
\bgi
\bin
\bn(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bn_
\ba_
\bm_
\be);
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.)
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).
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
12123 _
\bN_
\bO_
\bT_
\bE: There is only one login name per session.
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.
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.
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.
12139 This is different from traditional UNIX privilege inheritance and as such
12140 can be counter-intuitive.
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.
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.
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:
12157 [EFAULT] The _
\bn_
\ba_
\bm_
\be parameter points to an invalid address.
12159 In addition, g
\bge
\bet
\btl
\blo
\bog
\bgi
\bin
\bn_
\b_r
\br() may return the following error:
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.
12164 s
\bse
\bet
\btl
\blo
\bog
\bgi
\bin
\bn() may return the following errors:
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.
12170 [EPERM] The caller tried to set the login name and was not the
12173 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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.
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.
12192 g
\bge
\bet
\btp
\bpe
\bee
\ber
\brn
\bna
\bam
\bme
\be - get name of connected peer
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>
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);
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.
12206 g
\bge
\bet
\btp
\bpe
\bee
\ber
\brn
\bna
\bam
\bme
\be() takes three parameters:
12208 _
\bs contains the file descriptor of the socket whose peer should be looked
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 *).
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.
12222 _
\bn_
\ba_
\bm_
\be_
\bl_
\be_
\bn indicates the amount of space pointed to by _
\bn_
\ba_
\bm_
\be, in bytes.
12224 If address information for the local end of the socket is required, the
12225 getsockname(2) function should be used instead.
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.
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.
12235 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
12236 On failure, _
\be_
\br_
\br_
\bn_
\bo is set to one of the following:
12238 [EBADF] The argument _
\bs is not a valid descriptor.
12240 [ENOTSOCK] The argument _
\bs is a file, not a socket.
12242 [ENOTCONN] The socket is not connected.
12244 [ENOBUFS] Insufficient resources were available in the system to
12245 perform the operation.
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.
12250 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
12251 accept(2), bind(2), getsockname(2), socket(2), getpeereid(3)
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
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.
12261 g
\bge
\bet
\btp
\bpg
\bgr
\brp
\bp, g
\bge
\bet
\btp
\bpg
\bgi
\bid
\bd - get process group
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>
12266 _
\bp_
\bi_
\bd_
\b__
\bt
12267 g
\bge
\bet
\btp
\bpg
\bgr
\brp
\bp(_
\bv_
\bo_
\bi_
\bd);
12269 _
\bp_
\bi_
\bd_
\b__
\bt
12270 g
\bge
\bet
\btp
\bpg
\bgi
\bid
\bd(_
\bp_
\bi_
\bd_
\b__
\bt _
\bp_
\bi_
\bd);
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.
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.
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.
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:
12289 [EPERM] The current process and the process _
\bp_
\bi_
\bd are not in the
12292 [ESRCH] There is no process with a process ID equal to _
\bp_
\bi_
\bd.
12294 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
12295 setpgid(2), termios(4)
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
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.
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.
12310 g
\bge
\bet
\btp
\bpg
\bgr
\brp
\bp, g
\bge
\bet
\btp
\bpg
\bgi
\bid
\bd - get process group
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>
12315 _
\bp_
\bi_
\bd_
\b__
\bt
12316 g
\bge
\bet
\btp
\bpg
\bgr
\brp
\bp(_
\bv_
\bo_
\bi_
\bd);
12318 _
\bp_
\bi_
\bd_
\b__
\bt
12319 g
\bge
\bet
\btp
\bpg
\bgi
\bid
\bd(_
\bp_
\bi_
\bd_
\b__
\bt _
\bp_
\bi_
\bd);
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.
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.
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.
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:
12338 [EPERM] The current process and the process _
\bp_
\bi_
\bd are not in the
12341 [ESRCH] There is no process with a process ID equal to _
\bp_
\bi_
\bd.
12343 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
12344 setpgid(2), termios(4)
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
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.
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.
12359 g
\bge
\bet
\btp
\bpi
\bid
\bd, g
\bge
\bet
\btp
\bpp
\bpi
\bid
\bd - get parent or calling process identification
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>
12364 _
\bp_
\bi_
\bd_
\b__
\bt
12365 g
\bge
\bet
\btp
\bpi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
12367 _
\bp_
\bi_
\bd_
\b__
\bt
12368 g
\bge
\bet
\btp
\bpp
\bpi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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.
12375 g
\bge
\bet
\btp
\bpp
\bpi
\bid
\bd() returns the process ID of the parent of the calling process.
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
12381 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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'').
12388 g
\bge
\bet
\btp
\bpi
\bid
\bd, g
\bge
\bet
\btp
\bpp
\bpi
\bid
\bd - get parent or calling process identification
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>
12393 _
\bp_
\bi_
\bd_
\b__
\bt
12394 g
\bge
\bet
\btp
\bpi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
12396 _
\bp_
\bi_
\bd_
\b__
\bt
12397 g
\bge
\bet
\btp
\bpp
\bpi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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.
12404 g
\bge
\bet
\btp
\bpp
\bpi
\bid
\bd() returns the process ID of the parent of the calling process.
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
12410 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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'').
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
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>
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);
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);
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.
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.
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.
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:
12454 [ESRCH] No process was located using the _
\bw_
\bh_
\bi_
\bc_
\bh and _
\bw_
\bh_
\bo values
12457 [EINVAL] _
\bw_
\bh_
\bi_
\bc_
\bh was not one of PRIO_PROCESS, PRIO_PGRP, or
12460 In addition, s
\bse
\bet
\btp
\bpr
\bri
\bio
\bor
\bri
\bit
\bty
\by() will fail if:
12462 [EPERM] A process was located, but neither its effective nor
12463 real user ID matched the effective user ID of the
12466 [EACCES] A non-superuser attempted to lower a process priority.
12468 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
12469 nice(1), fork(2), renice(8)
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'').
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.
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
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>
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);
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);
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);
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);
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.
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
12509 Passing -1 as an argument causes the corresponding value to remain
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.
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
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
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
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)
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.
12538 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
12539 These functions first appeared in HP-UX.
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
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>
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);
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);
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);
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);
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.
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
12570 Passing -1 as an argument causes the corresponding value to remain
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.
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
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
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
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)
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.
12599 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
12600 These functions first appeared in HP-UX.
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
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>
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);
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);
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.
12619 The _
\br_
\be_
\bs_
\bo_
\bu_
\br_
\bc_
\be parameter is one of the following:
12621 RLIMIT_CORE The largest size (in bytes) _
\bc_
\bo_
\br_
\be file that may be
12624 RLIMIT_CPU The maximum amount of CPU time (in seconds) to be used by
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).
12631 RLIMIT_FSIZE The largest size (in bytes) file that may be created.
12633 RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into
12634 memory using the mlock(2) function.
12636 RLIMIT_NOFILE The maximum number of open files for this process.
12638 RLIMIT_NPROC The maximum number of simultaneous processes for this
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
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.
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,
12662 rlim_t rlim_cur; /* current (soft) limit */
12663 rlim_t rlim_max; /* hard limit */
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.
12670 An ``infinite'' value for a limit is defined as RLIM_INFINITY.
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().
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.
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.
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
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
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:
12703 [EFAULT] The address specified for _
\br_
\bl_
\bp is invalid.
12705 [EINVAL] An unrecognized value for _
\br_
\be_
\bs_
\bo_
\bu_
\br_
\bc_
\be was specified.
12707 In addition, s
\bse
\bet
\btr
\brl
\bli
\bim
\bmi
\bit
\bt() may return the following errors:
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.
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.
12714 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
12715 csh(1), sh(1), quotactl(2), sigaction(2), sigaltstack(2), sysctl(3)
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
12721 The RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS resources are non-
12722 standard extensions.
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.
12728 The RLIMIT_AS resource is missing.
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
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>
12739 g
\bge
\bet
\btr
\brt
\bta
\bab
\bbl
\ble
\be(_
\bv_
\bo_
\bi_
\bd);
12742 s
\bse
\bet
\btr
\brt
\bta
\bab
\bbl
\ble
\be(_
\bi_
\bn_
\bt _
\br_
\bt_
\ba_
\bb_
\bl_
\be_
\bi_
\bd);
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.
12748 Only the superuser is allowed to change the process routing table if it
12749 is already set to a non-zero value.
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
12756 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
12757 The call succeeds unless:
12759 [EINVAL] The value of the _
\br_
\bt_
\ba_
\bb_
\bl_
\be_
\bi_
\bd argument is not a valid
12762 [EPERM] The user is not the superuser and the routing table of
12763 the calling process is already set to a non-zero
12766 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
12767 getsockopt(2), route(8)
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.
12773 g
\bge
\bet
\btr
\bru
\bus
\bsa
\bag
\bge
\be - get information about resource utilization
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>
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);
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:
12785 RUSAGE_SELF Resources used by the current process.
12787 RUSAGE_CHILDREN Resources used by all the terminated children of
12788 the current process.
12790 RUSAGE_THREAD Resources used by the current thread.
12792 The buffer to which _
\br_
\bu_
\bs_
\ba_
\bg_
\be points will be filled in with the following
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 */
12814 The fields are interpreted as follows:
12816 _
\br_
\bu_
\b__
\bu_
\bt_
\bi_
\bm_
\be the total amount of time spent executing in user mode.
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).
12821 _
\br_
\bu_
\b__
\bm_
\ba_
\bx_
\br_
\bs_
\bs the maximum resident set size utilized (in kilobytes).
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.
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).
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).
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.
12840 _
\br_
\bu_
\b__
\bm_
\ba_
\bj_
\bf_
\bl_
\bt the number of page faults serviced that required I/O
12843 _
\br_
\bu_
\b__
\bn_
\bs_
\bw_
\ba_
\bp the number of times a process was ``swapped'' out of main
12846 _
\br_
\bu_
\b__
\bi_
\bn_
\bb_
\bl_
\bo_
\bc_
\bk the number of times the file system had to perform input.
12848 _
\br_
\bu_
\b__
\bo_
\bu_
\bb_
\bl_
\bo_
\bc_
\bk the number of times the file system had to perform output.
12850 _
\br_
\bu_
\b__
\bm_
\bs_
\bg_
\bs_
\bn_
\bd the number of IPC messages sent.
12852 _
\br_
\bu_
\b__
\bm_
\bs_
\bg_
\br_
\bc_
\bv the number of IPC messages received.
12854 _
\br_
\bu_
\b__
\bn_
\bs_
\bi_
\bg_
\bn_
\ba_
\bl_
\bs the number of signals delivered.
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
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.
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.
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
12875 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
12876 g
\bge
\bet
\btr
\bru
\bus
\bsa
\bag
\bge
\be() will fail if:
12878 [EINVAL] The _
\bw_
\bh_
\bo parameter is not a valid value.
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.
12883 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
12884 clock_gettime(2), gettimeofday(2), wait(2)
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'').
12889 The RUSAGE_THREAD flag is an extension to that specification.
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.
12895 The RUSAGE_THREAD flag has been available since OpenBSD 4.8.
12898 There is no way to obtain information about a child process that has not
12902 g
\bge
\bet
\bts
\bsi
\bid
\bd - get process session
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>
12907 _
\bp_
\bi_
\bd_
\b__
\bt
12908 g
\bge
\bet
\bts
\bsi
\bid
\bd(_
\bp_
\bi_
\bd_
\b__
\bt _
\bp_
\bi_
\bd);
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.
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.
12919 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
12920 g
\bge
\bet
\bts
\bsi
\bid
\bd() will succeed unless:
12922 [EPERM] The current process and the process _
\bp_
\bi_
\bd are not in the
12925 [ESRCH] There is no process with a process ID equal to _
\bp_
\bi_
\bd.
12927 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
12928 getpgid(2), getpgrp(2), setpgid(2), setsid(2), termios(4)
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'').
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'').
12938 g
\bge
\bet
\bts
\bso
\boc
\bck
\bkn
\bna
\bam
\bme
\be - get socket name
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>
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);
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
12950 Common uses of this function are as follows:
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.
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.
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.
12962 g
\bge
\bet
\bts
\bso
\boc
\bck
\bkn
\bna
\bam
\bme
\be() takes three parameters:
12964 _
\bs contains the file descriptor for the socket to be looked up.
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 *).
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.
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
12980 If the address of the destination socket for a given socket connection is
12981 needed, the getpeername(2) function should be used instead.
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.
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.
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:
12994 [EBADF] The argument _
\bs is not a valid descriptor.
12996 [ENOTSOCK] The argument _
\bs is a file, not a socket.
12998 [ENOBUFS] Insufficient resources were available in the system to
12999 perform the operation.
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.
13004 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13005 accept(2), bind(2), getpeername(2), socket(2), getpeereid(3)
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
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.
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
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>
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);
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);
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.
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).
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.
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.
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>.
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().
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)
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.
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.
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.
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:
13125 pass out inet from 192.168.0.10 divert-reply
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.
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.
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.
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:
13176 cmsg_len = CMSG_LEN(sizeof(struct timeval))
13177 cmsg_level = SOL_SOCKET
13178 cmsg_type = SCM_TIMESTAMP
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
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).
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.
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.
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
13228 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
13229 The call succeeds unless:
13231 [EBADF] The argument _
\bs is not a valid descriptor.
13233 [ENOTSOCK] The argument _
\bs is a file, not a socket.
13235 [ENOPROTOOPT] The option is unknown at the level indicated.
13237 [EOPNOTSUPP] The option is unsupported.
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.
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)
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'').
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.
13256 Several of the socket options should be handled at lower levels of the
13260 g
\bge
\bet
\btt
\bth
\bhr
\bri
\bid
\bd - get thread identifier
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>
13265 _
\bp_
\bi_
\bd_
\b__
\bt
13266 g
\bge
\bet
\btt
\bth
\bhr
\bri
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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).
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.
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
13282 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13283 __tfork(2), getpid(2), pthread_create(3), pthread_self(3)
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.
13289 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
13290 The k
\bkq
\bqu
\bue
\beu
\bue
\be syscall appeared in OpenBSD 3.9.
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
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>
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);
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);
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.
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.
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:
13319 time_t tv_sec; /* seconds since Jan. 1, 1970 */
13320 suseconds_t tv_usec; /* and microseconds */
13324 int tz_minuteswest; /* of Greenwich */
13325 int tz_dsttime; /* type of dst correction to apply */
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
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
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
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:
13348 [EFAULT] An argument address referenced invalid memory.
13350 In addition, s
\bse
\bet
\btt
\bti
\bim
\bme
\beo
\bof
\bfd
\bda
\bay
\by() may return the following error:
13352 [EPERM] A user other than the superuser attempted to set the
13355 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13356 date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3)
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
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.
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.
13377 g
\bge
\bet
\btu
\bui
\bid
\bd, g
\bge
\bet
\bte
\beu
\bui
\bid
\bd - get user identification
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>
13382 _
\bu_
\bi_
\bd_
\b__
\bt
13383 g
\bge
\bet
\btu
\bui
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
13385 _
\bu_
\bi_
\bd_
\b__
\bt
13386 g
\bge
\bet
\bte
\beu
\bui
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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
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.
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.
13402 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13403 getgid(2), getresuid(2), setreuid(2), setuid(2)
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
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.
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
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>
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);
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);
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
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.
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
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.
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.
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:
13451 [EFAULT] _
\bb_
\ba_
\bs_
\be points outside the process's allocated address space.
13453 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13454 __tfork(2), fork(2)
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.
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
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>
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);
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);
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
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.
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
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.
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.
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:
13496 [EFAULT] _
\bb_
\ba_
\bs_
\be points outside the process's allocated address space.
13498 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13499 __tfork(2), fork(2)
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.
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.
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
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>
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);
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);
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.
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.
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.
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.
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.
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:
13551 [EFAULT] _
\bi_
\bo_
\bm_
\ba_
\bp points outside the process's allocated address space.
13553 Additionally i
\bi3
\b38
\b86
\b6_
\b_s
\bse
\bet
\bt_
\b_i
\bio
\bop
\bpe
\ber
\brm
\bm() will fail if:
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-
13559 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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.
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).
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
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>
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);
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);
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.
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.
13600 Before this API can be used the functionality has to be enabled using the
13601 machdep.userldt sysctl(8) variable.
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.
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.
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.
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:
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.
13622 [EACCES] The caller attempted to use a descriptor that would circumvent
13623 protection or cause a failure.
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.
13628 W
\bWA
\bAR
\bRN
\bNI
\bIN
\bNG
\bG
13629 You can really hose your process using this.
13632 i
\bi3
\b38
\b86
\b6_
\b_i
\bio
\bop
\bpl
\bl - change the i386 I/O privilege level
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>
13639 i
\bi3
\b38
\b86
\b6_
\b_i
\bio
\bop
\bpl
\bl(_
\bi_
\bn_
\bt _
\bi_
\bo_
\bp_
\bl);
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
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.
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.
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
13656 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
13657 i
\bi3
\b38
\b86
\b6_
\b_i
\bio
\bop
\bpl
\bl() will fail if:
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-
13663 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13664 i386_get_ioperm(2), securelevel(7)
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.
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.
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
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>
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);
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);
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
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.
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
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.
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.
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:
13711 [EFAULT] _
\bb_
\ba_
\bs_
\be points outside the process's allocated address space.
13713 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13714 __tfork(2), fork(2)
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.
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
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>
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);
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);
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
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.
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
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.
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.
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:
13756 [EFAULT] _
\bb_
\ba_
\bs_
\be points outside the process's allocated address space.
13758 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
13759 __tfork(2), fork(2)
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.
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.
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
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>
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);
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);
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.
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.
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.
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.
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.
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:
13811 [EFAULT] _
\bi_
\bo_
\bm_
\ba_
\bp points outside the process's allocated address space.
13813 Additionally i
\bi3
\b38
\b86
\b6_
\b_s
\bse
\bet
\bt_
\b_i
\bio
\bop
\bpe
\ber
\brm
\bm() will fail if:
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-
13819 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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.
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).
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
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>
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);
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);
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.
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.
13860 Before this API can be used the functionality has to be enabled using the
13861 machdep.userldt sysctl(8) variable.
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.
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.
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.
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:
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.
13882 [EACCES] The caller attempted to use a descriptor that would circumvent
13883 protection or cause a failure.
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.
13888 W
\bWA
\bAR
\bRN
\bNI
\bIN
\bNG
\bG
13889 You can really hose your process using this.
13892 i
\bi3
\b38
\b86
\b6_
\b_v
\bvm
\bm8
\b86
\b6 - set virtual 8086 processor registers and mode
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>
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);
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.
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.
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.
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.
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.
13929 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
13930 i
\bi3
\b38
\b86
\b6_
\b_v
\bvm
\bm8
\b86
\b6() will fail if:
13932 [EFAULT] The state at _
\bv_
\bm_
\bc_
\bp was not readable to the user process.
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.
13938 i
\bin
\bnt
\btr
\bro
\bo - introduction to system calls and error numbers
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>
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.
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.
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.
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>.
13966 0 _
\bU_
\bn_
\bd_
\be_
\bf_
\bi_
\bn_
\be_
\bd _
\be_
\br_
\br_
\bo_
\br_
\b: _
\b0. Not used.
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.
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.
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.
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.
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
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
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>).
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.
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).
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
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.
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.
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.
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.
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.
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
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)
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
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.
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
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.
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)
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
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.
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.
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.
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.)
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
14086 29 ESPIPE _
\bI_
\bl_
\bl_
\be_
\bg_
\ba_
\bl _
\bs_
\be_
\be_
\bk. An lseek(2) function was issued on a socket, pipe
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
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
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.
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.
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).
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.
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)).
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.
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.
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.
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.
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
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.
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.
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
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.
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
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.
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.
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.
14160 50 ENETDOWN _
\bN_
\be_
\bt_
\bw_
\bo_
\br_
\bk _
\bi_
\bs _
\bd_
\bo_
\bw_
\bn. A socket operation encountered a dead
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.
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.
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.
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.
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.
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
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.
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.
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.
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.)
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
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.
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.
14212 64 EHOSTDOWN _
\bH_
\bo_
\bs_
\bt _
\bi_
\bs _
\bd_
\bo_
\bw_
\bn. A socket operation failed because the
14213 destination host was down.
14215 65 EHOSTUNREACH _
\bN_
\bo _
\br_
\bo_
\bu_
\bt_
\be _
\bt_
\bo _
\bh_
\bo_
\bs_
\bt. A socket operation was attempted to an
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.
14221 67 EPROCLIM _
\bT_
\bo_
\bo _
\bm_
\ba_
\bn_
\by _
\bp_
\br_
\bo_
\bc_
\be_
\bs_
\bs_
\be_
\bs.
14223 68 EUSERS _
\bT_
\bo_
\bo _
\bm_
\ba_
\bn_
\by _
\bu_
\bs_
\be_
\br_
\bs. The quota system ran out of table entries.
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.
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.
14236 72 EBADRPC _
\bR_
\bP_
\bC _
\bs_
\bt_
\br_
\bu_
\bc_
\bt _
\bi_
\bs _
\bb_
\ba_
\bd. Exchange of rpc(3) information was
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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
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.
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.
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.
14294 91 ENOTSUP _
\bN_
\bo_
\bt _
\bs_
\bu_
\bp_
\bp_
\bo_
\br_
\bt_
\be_
\bd. The operation has requested an unsupported
14297 D
\bDE
\bEF
\bFI
\bIN
\bNI
\bIT
\bTI
\bIO
\bON
\bNS
\bS
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
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.
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
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).
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
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
14335 Controlling Process
14336 A session leader with a controlling terminal is a controlling
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.
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
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
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
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.
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.
14382 All processes have a real user ID and real group ID. These are
14383 initialized from the equivalent attributes of the process that
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.)
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)
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''.
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
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.
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.
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
14439 Names consisting of up to 255 (NAME_MAX) characters may be used
14440 to name an ordinary file, special file, or directory.
14442 These characters may be arbitrary eight-bit values, excluding 0
14443 (NUL) and the ASCII code for `/' (slash).
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.
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)
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
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.
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
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.
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
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.
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
14502 Read, write, and execute/search permissions on a file are granted
14505 The process's effective user ID is that of the superuser. (Note:
14506 even the superuser cannot execute a non-executable file.)
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.
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
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''
14522 Otherwise, permission is denied.
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.
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.
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.
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.
14543 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
14544 intro(3), perror(3)
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.
14550 i
\bio
\boc
\bct
\btl
\bl - control device
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>
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.);
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()
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.
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>.
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:
14578 Set close-on-exec flag. The file will be closed when exec(3) is
14582 Clear close-on-exec flag. The file will remain open across
14585 Some generic ioctls are not implemented for all types of file
14586 descriptors. These include:
14588 FIONREAD _
\bi_
\bn_
\bt _
\b*
14589 Get the number of bytes that are immediately available for
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.
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.
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.
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.
14612 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
14613 i
\bio
\boc
\bct
\btl
\bl() will fail if:
14615 [EBADF] _
\bd is not a valid descriptor.
14617 [ENOTTY] _
\bd is not associated with a character special device.
14619 [ENOTTY] The specified request does not apply to the kind of
14620 object that the descriptor _
\bd references.
14622 [EINVAL] _
\br_
\be_
\bq_
\bu_
\be_
\bs_
\bt or _
\ba_
\br_
\bg is not valid.
14624 [EFAULT] _
\ba_
\br_
\bg points outside the process's allocated address
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)
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.
14634 i
\bis
\bss
\bse
\bet
\btu
\bug
\bgi
\bid
\bd - is current executable running setuid or setgid
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>
14640 i
\bis
\bss
\bse
\bet
\btu
\bug
\bgi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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.
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.
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
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.
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.
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.
14677 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
14678 execve(2), setegid(2), seteuid(2), setgid(2), setuid(2), getenv(3)
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.
14684 k
\bkq
\bqu
\bue
\beu
\bue
\be, k
\bke
\bev
\bve
\ben
\bnt
\bt - kernel event notification mechanism
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>
14692 k
\bkq
\bqu
\bue
\beu
\bue
\be(_
\bv_
\bo_
\bi_
\bd);
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);
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);
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.
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.
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
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.
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.
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.
14741 E
\bEV
\bV_
\b_S
\bSE
\bET
\bT() is a macro which is provided for ease of initializing a kevent
14744 The _
\bk_
\be_
\bv_
\be_
\bn_
\bt structure is defined as:
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 */
14755 The fields of struct kevent are:
14757 ident Value used to identify this event. The exact interpretation
14758 is determined by the attached filter, but often is a file
14761 filter Identifies the kernel filter used to process this event. The
14762 pre-defined system filters are described below.
14764 flags Actions to perform on the event.
14766 fflags Filter-specific flags.
14768 data Filter-specific data value.
14770 udata Opaque user-defined value passed through the kernel unchanged.
14772 The _
\bf_
\bl_
\ba_
\bg_
\bs field can contain the following values:
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
14780 EV_ENABLE Permit k
\bke
\bev
\bve
\ben
\bnt
\bt() to return the event if it is triggered.
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.
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.
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.
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.
14798 EV_EOF Filters may set this flag to indicate filter-specific EOF
14801 EV_ERROR See _
\bR_
\bE_
\bT_
\bU_
\bR_
\bN _
\bV_
\bA_
\bL_
\bU_
\bE_
\bS below.
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
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
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.
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
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
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.
14843 Returns when there is data to read; _
\bd_
\ba_
\bt_
\ba contains the
14844 number of bytes available.
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.
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.
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.
14865 For sockets, the low water mark and socket error handling
14866 is identical to the EVFILT_READ case.
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
14873 NOTE_DELETE u
\bun
\bnl
\bli
\bin
\bnk
\bk() was called on the file referenced
14876 NOTE_WRITE A write occurred on the file referenced by
14879 NOTE_EXTEND The file referenced by the descriptor was
14882 NOTE_TRUNCATE The file referenced by the descriptor was
14885 NOTE_ATTRIB The file referenced by the descriptor had
14886 its attributes changed.
14888 NOTE_LINK The link count on the file changed.
14890 NOTE_RENAME The file referenced by the descriptor was
14893 NOTE_REVOKE Access to the file was revoked via
14894 revoke(2) or the underlying file system was
14897 On return, _
\bf_
\bf_
\bl_
\ba_
\bg_
\bs contains the events which triggered the
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:
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).
14910 NOTE_FORK The process has called f
\bfo
\bor
\brk
\bk().
14912 NOTE_EXEC The process has executed a new process
14913 via execve(2) or similar call.
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.
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
14927 On return, _
\bf_
\bf_
\bl_
\ba_
\bg_
\bs contains the events which triggered the
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.
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.
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.
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.
14962 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
14963 The k
\bkq
\bqu
\bue
\beu
\bue
\be() function fails if:
14965 [ENOMEM] The kernel failed to allocate enough memory for the
14968 [EMFILE] The per-process descriptor table is full.
14970 [ENFILE] The system file table is full.
14972 The k
\bke
\bev
\bve
\ben
\bnt
\bt() function fails if:
14974 [EACCES] The process does not have permission to register a
14977 [EFAULT] There was an error reading or writing the _
\bk_
\be_
\bv_
\be_
\bn_
\bt
14980 [EBADF] The specified descriptor is invalid.
14982 [EINTR] A signal was delivered before the timeout expired and
14983 before any events were placed on the kqueue for
14986 [EINVAL] The specified time limit or filter is invalid.
14988 [ENOENT] The event could not be found to be modified or
14991 [ENOMEM] No memory was available to register the event.
14993 [ESRCH] The specified process to attach to does not exist.
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)
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.
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>.
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.
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.
15014 k
\bki
\bil
\bll
\bl - send signal to a process
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>
15020 k
\bki
\bil
\bll
\bl(_
\bp_
\bi_
\bd_
\b__
\bt _
\bp_
\bi_
\bd, _
\bi_
\bn_
\bt _
\bs_
\bi_
\bg);
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
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.
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.
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).
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
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.
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
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
15068 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
15069 k
\bki
\bil
\bll
\bl() will fail and no signal will be sent if:
15071 [EINVAL] _
\bs_
\bi_
\bg is not a valid signal number.
15073 [ESRCH] No process can be found corresponding to that
15074 specified by _
\bp_
\bi_
\bd.
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.
15082 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
15083 getpgrp(2), getpid(2), sigaction(2), killpg(3), raise(3)
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
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.
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.
15099 k
\bkq
\bqu
\bue
\beu
\bue
\be, k
\bke
\bev
\bve
\ben
\bnt
\bt - kernel event notification mechanism
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>
15107 k
\bkq
\bqu
\bue
\beu
\bue
\be(_
\bv_
\bo_
\bi_
\bd);
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);
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);
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.
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.
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
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.
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.
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.
15156 E
\bEV
\bV_
\b_S
\bSE
\bET
\bT() is a macro which is provided for ease of initializing a kevent
15159 The _
\bk_
\be_
\bv_
\be_
\bn_
\bt structure is defined as:
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 */
15170 The fields of struct kevent are:
15172 ident Value used to identify this event. The exact interpretation
15173 is determined by the attached filter, but often is a file
15176 filter Identifies the kernel filter used to process this event. The
15177 pre-defined system filters are described below.
15179 flags Actions to perform on the event.
15181 fflags Filter-specific flags.
15183 data Filter-specific data value.
15185 udata Opaque user-defined value passed through the kernel unchanged.
15187 The _
\bf_
\bl_
\ba_
\bg_
\bs field can contain the following values:
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
15195 EV_ENABLE Permit k
\bke
\bev
\bve
\ben
\bnt
\bt() to return the event if it is triggered.
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.
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.
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.
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.
15213 EV_EOF Filters may set this flag to indicate filter-specific EOF
15216 EV_ERROR See _
\bR_
\bE_
\bT_
\bU_
\bR_
\bN _
\bV_
\bA_
\bL_
\bU_
\bE_
\bS below.
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
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
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.
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
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
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.
15258 Returns when there is data to read; _
\bd_
\ba_
\bt_
\ba contains the
15259 number of bytes available.
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.
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.
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.
15280 For sockets, the low water mark and socket error handling
15281 is identical to the EVFILT_READ case.
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
15288 NOTE_DELETE u
\bun
\bnl
\bli
\bin
\bnk
\bk() was called on the file referenced
15291 NOTE_WRITE A write occurred on the file referenced by
15294 NOTE_EXTEND The file referenced by the descriptor was
15297 NOTE_TRUNCATE The file referenced by the descriptor was
15300 NOTE_ATTRIB The file referenced by the descriptor had
15301 its attributes changed.
15303 NOTE_LINK The link count on the file changed.
15305 NOTE_RENAME The file referenced by the descriptor was
15308 NOTE_REVOKE Access to the file was revoked via
15309 revoke(2) or the underlying file system was
15312 On return, _
\bf_
\bf_
\bl_
\ba_
\bg_
\bs contains the events which triggered the
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:
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).
15325 NOTE_FORK The process has called f
\bfo
\bor
\brk
\bk().
15327 NOTE_EXEC The process has executed a new process
15328 via execve(2) or similar call.
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.
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
15342 On return, _
\bf_
\bf_
\bl_
\ba_
\bg_
\bs contains the events which triggered the
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.
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.
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.
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.
15377 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
15378 The k
\bkq
\bqu
\bue
\beu
\bue
\be() function fails if:
15380 [ENOMEM] The kernel failed to allocate enough memory for the
15383 [EMFILE] The per-process descriptor table is full.
15385 [ENFILE] The system file table is full.
15387 The k
\bke
\bev
\bve
\ben
\bnt
\bt() function fails if:
15389 [EACCES] The process does not have permission to register a
15392 [EFAULT] There was an error reading or writing the _
\bk_
\be_
\bv_
\be_
\bn_
\bt
15395 [EBADF] The specified descriptor is invalid.
15397 [EINTR] A signal was delivered before the timeout expired and
15398 before any events were placed on the kqueue for
15401 [EINVAL] The specified time limit or filter is invalid.
15403 [ENOENT] The event could not be found to be modified or
15406 [ENOMEM] No memory was available to register the event.
15408 [ESRCH] The specified process to attach to does not exist.
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)
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.
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>.
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.
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.
15429 k
\bkt
\btr
\bra
\bac
\bce
\be - process tracing
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>
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);
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.
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
15453 The _
\bo_
\bp_
\bs parameter specifies the requested ktrace operation. The defined
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.
15462 The _
\bt_
\br_
\bp_
\bo_
\bi_
\bn_
\bt_
\bs parameter specifies the trace points of interest. The
15463 defined trace points are:
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
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.
15477 The _
\bp_
\bi_
\bd parameter refers to a process ID. If it is negative, it refers
15478 to a process group ID.
15480 Each tracing event outputs a record composed of a generic header followed
15481 by a trace point specific structure. The generic header is:
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 */
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
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.
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
15506 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
15507 k
\bkt
\btr
\bra
\bac
\bce
\be() will fail if:
15509 [ENOTDIR] A component of the path prefix is not a directory.
15511 [EINVAL] No trace points were selected.
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.
15517 [ENOENT] The named tracefile does not exist.
15519 [EACCES] Search permission is denied for a component of the path
15520 prefix or the path refers to a symbolic link.
15522 [ELOOP] Too many symbolic links were encountered in translating
15525 [EIO] An I/O error occurred while reading from or writing to
15528 [ESRCH] No process can be found corresponding to that specified
15531 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
15532 kdump(1), ktrace(1), utrace(2)
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.
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
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>
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);
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);
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);
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>
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);
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
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.
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.
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.
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.
15586 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
15589 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the
15590 ownership of the symbolic link is changed.
15592 f
\bfc
\bch
\bho
\bow
\bwn
\bn() is particularly useful when used in conjunction with the file
15593 locking primitives (see flock(2)).
15595 One of the owner or group IDs may be left unchanged by specifying it as
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
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
15607 [ENOTDIR] A component of the path prefix is not a directory.
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.
15613 [ENOENT] The named file does not exist.
15615 [EACCES] Search permission is denied for a component of the
15618 [ELOOP] Too many symbolic links were encountered in
15619 translating the pathname.
15621 [EPERM] The effective user ID is not the superuser.
15623 [EROFS] The named file resides on a read-only file system.
15625 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
15628 [EIO] An I/O error occurred while reading from or writing to
15631 Additionally, f
\bfc
\bch
\bho
\bow
\bwn
\bna
\bat
\bt() will fail if:
15633 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
15634 AT_SYMLINK_NOFOLLOW.
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
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.
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.
15648 f
\bfc
\bch
\bho
\bow
\bwn
\bn() will fail if:
15650 [EBADF] _
\bf_
\bd does not refer to a valid descriptor.
15652 [EINVAL] _
\bf_
\bd refers to a socket, not a file.
15654 [EPERM] The effective user ID is not the superuser.
15656 [EROFS] The named file resides on a read-only file system.
15658 [EIO] An I/O error occurred while reading from or writing to
15661 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
15662 chgrp(1), chmod(2), flock(2), chown(8)
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'').
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.
15673 The f
\bfc
\bch
\bho
\bow
\bwn
\bn() system call first appeared in 4.1cBSD.
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.
15679 The f
\bfc
\bch
\bho
\bow
\bwn
\bna
\bat
\bt() system call has been available since OpenBSD 5.0.
15682 l
\bli
\bin
\bnk
\bk, l
\bli
\bin
\bnk
\bka
\bat
\bt - make hard link to a file
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>
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);
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>
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);
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.
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.
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
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.
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.
15719 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
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.
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.
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
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:
15736 [ENOTDIR] A component of either path prefix is not a directory.
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.
15742 [ENOENT] A component of either path prefix does not exist.
15744 [EOPNOTSUPP] The file system containing the file named by _
\bn_
\ba_
\bm_
\be_
\b1
15745 does not support links.
15747 [EMLINK] The link count of the file named by _
\bn_
\ba_
\bm_
\be_
\b1 would exceed
15750 [EACCES] A component of either path prefix denies search
15753 [EACCES] The requested link requires writing in a directory
15754 with a mode that denies write permission.
15756 [ELOOP] Too many symbolic links were encountered in
15757 translating one of the pathnames.
15759 [ENOENT] The file named by _
\bn_
\ba_
\bm_
\be_
\b1 does not exist.
15761 [EEXIST] The link named by _
\bn_
\ba_
\bm_
\be_
\b2 does exist.
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()
15768 [EPERM] The file named by _
\bn_
\ba_
\bm_
\be_
\b1 is flagged immutable or
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.
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
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.
15784 [EIO] An I/O error occurred while reading from or writing to
15785 the file system to make the directory entry.
15787 [EROFS] The requested link requires writing in a directory on
15788 a read-only file system.
15790 [EFAULT] One of the pathnames specified is outside the
15791 process's allocated address space.
15793 Additionally, l
\bli
\bin
\bnk
\bka
\bat
\bt() will fail if:
15795 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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.
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.
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,
15811 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
15812 ln(1), readlink(2), symlink(2), unlink(2)
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'').
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.
15823 l
\bli
\bin
\bnk
\bk, l
\bli
\bin
\bnk
\bka
\bat
\bt - make hard link to a file
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>
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);
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>
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);
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.
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.
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
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.
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.
15860 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
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.
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.
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
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:
15877 [ENOTDIR] A component of either path prefix is not a directory.
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.
15883 [ENOENT] A component of either path prefix does not exist.
15885 [EOPNOTSUPP] The file system containing the file named by _
\bn_
\ba_
\bm_
\be_
\b1
15886 does not support links.
15888 [EMLINK] The link count of the file named by _
\bn_
\ba_
\bm_
\be_
\b1 would exceed
15891 [EACCES] A component of either path prefix denies search
15894 [EACCES] The requested link requires writing in a directory
15895 with a mode that denies write permission.
15897 [ELOOP] Too many symbolic links were encountered in
15898 translating one of the pathnames.
15900 [ENOENT] The file named by _
\bn_
\ba_
\bm_
\be_
\b1 does not exist.
15902 [EEXIST] The link named by _
\bn_
\ba_
\bm_
\be_
\b2 does exist.
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()
15909 [EPERM] The file named by _
\bn_
\ba_
\bm_
\be_
\b1 is flagged immutable or
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.
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
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.
15925 [EIO] An I/O error occurred while reading from or writing to
15926 the file system to make the directory entry.
15928 [EROFS] The requested link requires writing in a directory on
15929 a read-only file system.
15931 [EFAULT] One of the pathnames specified is outside the
15932 process's allocated address space.
15934 Additionally, l
\bli
\bin
\bnk
\bka
\bat
\bt() will fail if:
15936 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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.
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.
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,
15952 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
15953 ln(1), readlink(2), symlink(2), unlink(2)
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'').
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.
15964 l
\bli
\bis
\bst
\bte
\ben
\bn - listen for connections on a socket
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>
15970 l
\bli
\bis
\bst
\bte
\ben
\bn(_
\bi_
\bn_
\bt _
\bs, _
\bi_
\bn_
\bt _
\bb_
\ba_
\bc_
\bk_
\bl_
\bo_
\bg);
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.
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.
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
15990 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
15991 l
\bli
\bis
\bst
\bte
\ben
\bn() will fail if:
15993 [EBADF] The argument _
\bs is not a valid descriptor.
15995 [ENOTSOCK] The argument _
\bs is not a socket.
15997 [EOPNOTSUPP] The socket is not of a type that supports the
15998 operation l
\bli
\bis
\bst
\bte
\ben
\bn().
16000 [EINVAL] The socket is already connected.
16002 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16003 accept(2), connect(2), socket(2), sysctl(8)
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'').
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.
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.
16016 l
\bls
\bse
\bee
\bek
\bk - reposition read/write file offset
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>
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);
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:
16030 If _
\bw_
\bh_
\be_
\bn_
\bc_
\be is SEEK_SET, the offset is set to _
\bo_
\bf_
\bf_
\bs_
\be_
\bt bytes.
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.
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.
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).
16043 Some devices are incapable of seeking. The value of the pointer
16044 associated with such a device is undefined.
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.
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:
16054 [EBADF] _
\bf_
\bi_
\bl_
\bd_
\be_
\bs is not an open file descriptor.
16056 [ESPIPE] _
\bf_
\bi_
\bl_
\bd_
\be_
\bs is associated with a pipe, socket, or FIFO.
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.
16062 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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'').
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.
16074 This document's use of _
\bw_
\bh_
\be_
\bn_
\bc_
\be is incorrect English, but is maintained for
16075 historical reasons.
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
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>
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);
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);
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);
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>
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);
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.
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.
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.
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.
16119 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
16122 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
16123 of the symbolic link is returned.
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.
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.
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 */
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
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.
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.
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.
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.
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
16179 The size-related fields of the struct stat are as follows:
16181 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
16187 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
16224 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
16234 [ENOTDIR] A component of the path prefix is not a directory.
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.
16240 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
16243 [EACCES] Search permission is denied for a component of the
16246 [ELOOP] Too many symbolic links were encountered in
16247 translating the pathname.
16249 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
16251 [EIO] An I/O error occurred while reading from or writing to
16254 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
16256 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
16257 AT_SYMLINK_NOFOLLOW.
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
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.
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.
16271 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
16273 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
16275 [EFAULT] _
\bs_
\bb points to an invalid address.
16277 [EIO] An I/O error occurred while reading from the file
16280 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16281 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
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
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>
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);
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);
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.
16329 The possible behaviors are:
16331 MADV_NORMAL No further special treatment needed.
16333 MADV_RANDOM Expect random page access patterns.
16335 MADV_SEQUENTIAL Expect sequential page references.
16337 MADV_WILLNEED The pages will be referenced soon.
16339 MADV_DONTNEED The pages will not be referenced soon.
16341 MADV_SPACEAVAIL Ensure that resources are reserved.
16343 MADV_FREE The pages don't contain any useful data and can be
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
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
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.
16359 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16360 mincore(2), minherit(2), mprotect(2), msync(2), munmap(2)
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
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.
16371 The MADV_WILLNEED behavior is ignored. The MADV_SPACEAVAIL behavior is
16372 not implemented and will always fail.
16375 m
\bmi
\bin
\bnc
\bco
\bor
\bre
\be - determine residency of memory pages
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>
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);
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.
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
16394 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16395 madvise(2), minherit(2), mlock(2), mprotect(2), msync(2), munmap(2)
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.
16401 m
\bmi
\bin
\bnh
\bhe
\ber
\bri
\bit
\bt - control the inheritance of pages
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>
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);
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).
16414 The possible inheritance characteristics are:
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
16419 MAP_INHERIT_SHARE Mapped pages are shared between the parent and
16421 MAP_INHERIT_ZERO New anonymous pages (initialized to all zero
16422 bytes) are mapped in the child process.
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.
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
16433 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
16434 The m
\bmi
\bin
\bnh
\bhe
\ber
\bri
\bit
\bt() system call will fail if:
16436 [EINVAL] The virtual address range specified by the _
\ba_
\bd_
\bd_
\br and
16437 _
\bl_
\be_
\bn arguments is not valid.
16439 [EINVAL] The _
\bi_
\bn_
\bh_
\be_
\br_
\bi_
\bt argument is invalid.
16441 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16442 madvise(2), mincore(2), mprotect(2), msync(2), munmap(2)
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.
16448 m
\bmk
\bkd
\bdi
\bir
\br, m
\bmk
\bkd
\bdi
\bir
\bra
\bat
\bt - make a directory file
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>
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);
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>
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);
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.
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
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.
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().
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
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:
16487 [ENOTDIR] A component of the path prefix is not a directory.
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.
16493 [ENOENT] A component of the path prefix does not exist.
16495 [EACCES] Search permission is denied for a component of the
16498 [ELOOP] Too many symbolic links were encountered in
16499 translating the pathname.
16501 [EROFS] The named file resides on a read-only file system.
16503 [EEXIST] The named file exists.
16505 [ENOSPC] The new directory cannot be created because there is
16506 no space left on the file system that will contain the
16509 [ENOSPC] There are no free inodes on the file system on which
16510 the directory is being created.
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.
16516 [EDQUOT] The user's quota of inodes on the file system on which
16517 the directory is being created has been exhausted.
16519 [EIO] An I/O error occurred while making the directory entry
16520 or allocating the inode.
16522 [EIO] An I/O error occurred while reading from or writing to
16525 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
16528 Additionally, m
\bmk
\bkd
\bdi
\bir
\bra
\bat
\bt() will fail if:
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
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.
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.
16542 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16543 chmod(2), stat(2), umask(2)
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
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 `..'
16557 The m
\bmk
\bkd
\bdi
\bir
\bra
\bat
\bt() system call has been available since OpenBSD 5.0.
16560 m
\bmk
\bkd
\bdi
\bir
\br, m
\bmk
\bkd
\bdi
\bir
\bra
\bat
\bt - make a directory file
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>
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);
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>
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);
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.
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
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.
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().
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
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:
16599 [ENOTDIR] A component of the path prefix is not a directory.
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.
16605 [ENOENT] A component of the path prefix does not exist.
16607 [EACCES] Search permission is denied for a component of the
16610 [ELOOP] Too many symbolic links were encountered in
16611 translating the pathname.
16613 [EROFS] The named file resides on a read-only file system.
16615 [EEXIST] The named file exists.
16617 [ENOSPC] The new directory cannot be created because there is
16618 no space left on the file system that will contain the
16621 [ENOSPC] There are no free inodes on the file system on which
16622 the directory is being created.
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.
16628 [EDQUOT] The user's quota of inodes on the file system on which
16629 the directory is being created has been exhausted.
16631 [EIO] An I/O error occurred while making the directory entry
16632 or allocating the inode.
16634 [EIO] An I/O error occurred while reading from or writing to
16637 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
16640 Additionally, m
\bmk
\bkd
\bdi
\bir
\bra
\bat
\bt() will fail if:
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
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.
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.
16654 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16655 chmod(2), stat(2), umask(2)
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
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 `..'
16669 The m
\bmk
\bkd
\bdi
\bir
\bra
\bat
\bt() system call has been available since OpenBSD 5.0.
16672 m
\bmk
\bkf
\bfi
\bif
\bfo
\bo, m
\bmk
\bkf
\bfi
\bif
\bfo
\boa
\bat
\bt - make a FIFO file
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>
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);
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>
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);
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
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
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
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().
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
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:
16712 [EOPNOTSUPP] The kernel has not been configured to support FIFOs.
16714 [ENOTDIR] A component of the path prefix is not a directory.
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.
16720 [ENOENT] A component of the path prefix does not exist.
16722 [EACCES] Search permission is denied for a component of the
16725 [ELOOP] Too many symbolic links were encountered in
16726 translating the pathname.
16728 [EROFS] The named file resides on a read-only file system.
16730 [EEXIST] The named file exists.
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
16737 [ENOSPC] There are no free inodes on the file system on which
16738 the FIFO is being created.
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.
16745 [EDQUOT] The user's quota of inodes on the file system on which
16746 the FIFO is being created has been exhausted.
16748 [EIO] An I/O error occurred while making the directory entry
16749 or allocating the inode.
16751 [EIO] An I/O error occurred while reading from or writing to
16754 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
16757 Additionally, m
\bmk
\bkf
\bfi
\bif
\bfo
\boa
\bat
\bt() will fail if:
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
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.
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.
16771 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16772 chmod(2), stat(2), umask(2)
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
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.
16782 m
\bmk
\bkf
\bfi
\bif
\bfo
\bo, m
\bmk
\bkf
\bfi
\bif
\bfo
\boa
\bat
\bt - make a FIFO file
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>
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);
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>
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);
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
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
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
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().
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
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:
16822 [EOPNOTSUPP] The kernel has not been configured to support FIFOs.
16824 [ENOTDIR] A component of the path prefix is not a directory.
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.
16830 [ENOENT] A component of the path prefix does not exist.
16832 [EACCES] Search permission is denied for a component of the
16835 [ELOOP] Too many symbolic links were encountered in
16836 translating the pathname.
16838 [EROFS] The named file resides on a read-only file system.
16840 [EEXIST] The named file exists.
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
16847 [ENOSPC] There are no free inodes on the file system on which
16848 the FIFO is being created.
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.
16855 [EDQUOT] The user's quota of inodes on the file system on which
16856 the FIFO is being created has been exhausted.
16858 [EIO] An I/O error occurred while making the directory entry
16859 or allocating the inode.
16861 [EIO] An I/O error occurred while reading from or writing to
16864 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
16867 Additionally, m
\bmk
\bkf
\bfi
\bif
\bfo
\boa
\bat
\bt() will fail if:
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
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.
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.
16881 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
16882 chmod(2), stat(2), umask(2)
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
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.
16892 m
\bmk
\bkn
\bno
\bod
\bd, m
\bmk
\bkn
\bno
\bod
\bda
\bat
\bt - make a special file node
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>
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);
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>
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);
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.
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.
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.
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().
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.
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
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:
16937 [EINVAL] _
\bm_
\bo_
\bd_
\be is an invalid file type or _
\bd_
\be_
\bv is an invalid
16938 value for that file type.
16940 [ENOTDIR] A component of the path prefix is not a directory.
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.
16946 [ENOENT] A component of the path prefix does not exist.
16948 [EACCES] Search permission is denied for a component of the
16951 [ELOOP] Too many symbolic links were encountered in
16952 translating the pathname.
16954 [EPERM] _
\bm_
\bo_
\bd_
\be is a device special and the process's effective
16955 user ID is not superuser.
16957 [EIO] An I/O error occurred while making the directory entry
16958 or allocating the inode.
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
16965 [ENOSPC] There are no free inodes on the file system on which
16966 the node is being created.
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.
16973 [EDQUOT] The user's quota of inodes on the file system on which
16974 the node is being created has been exhausted.
16976 [EROFS] The named file resides on a read-only file system.
16978 [EEXIST] The named file exists.
16980 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
16983 [EINVAL] The process is running within an alternate root
16984 directory, as created by chroot(2).
16986 Additionally, m
\bmk
\bkn
\bno
\bod
\bda
\bat
\bt() will fail if:
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
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.
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.
17000 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
17001 chmod(2), chroot(2), mkfifo(2), stat(2), umask(2)
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
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.
17012 m
\bmk
\bkn
\bno
\bod
\bd, m
\bmk
\bkn
\bno
\bod
\bda
\bat
\bt - make a special file node
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>
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);
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>
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);
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.
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.
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.
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().
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.
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
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:
17057 [EINVAL] _
\bm_
\bo_
\bd_
\be is an invalid file type or _
\bd_
\be_
\bv is an invalid
17058 value for that file type.
17060 [ENOTDIR] A component of the path prefix is not a directory.
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.
17066 [ENOENT] A component of the path prefix does not exist.
17068 [EACCES] Search permission is denied for a component of the
17071 [ELOOP] Too many symbolic links were encountered in
17072 translating the pathname.
17074 [EPERM] _
\bm_
\bo_
\bd_
\be is a device special and the process's effective
17075 user ID is not superuser.
17077 [EIO] An I/O error occurred while making the directory entry
17078 or allocating the inode.
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
17085 [ENOSPC] There are no free inodes on the file system on which
17086 the node is being created.
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.
17093 [EDQUOT] The user's quota of inodes on the file system on which
17094 the node is being created has been exhausted.
17096 [EROFS] The named file resides on a read-only file system.
17098 [EEXIST] The named file exists.
17100 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
17103 [EINVAL] The process is running within an alternate root
17104 directory, as created by chroot(2).
17106 Additionally, m
\bmk
\bkn
\bno
\bod
\bda
\bat
\bt() will fail if:
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
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.
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.
17120 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
17121 chmod(2), chroot(2), mkfifo(2), stat(2), umask(2)
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
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.
17132 m
\bml
\blo
\boc
\bck
\bk, m
\bmu
\bun
\bnl
\blo
\boc
\bck
\bk - lock (unlock) physical pages in memory
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>
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);
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);
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.
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).
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.
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.
17174 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
17175 m
\bml
\blo
\boc
\bck
\bk() will fail if:
17177 [EINVAL] The address given is not page aligned or the length is
17180 [EAGAIN] Locking the indicated range would exceed either the
17181 system or per-process limit for locked memory.
17183 [ENOMEM] Some portion of the indicated address range is not
17184 allocated. There was an error faulting/mapping a
17187 m
\bmu
\bun
\bnl
\blo
\boc
\bck
\bk() will fail if:
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
17193 [ENOMEM] Some portion of the indicated address range is not
17194 allocated. Some portion of the indicated address
17195 range is not locked.
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)
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.
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.
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.
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
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>
17223 m
\bml
\blo
\boc
\bck
\bka
\bal
\bll
\bl(_
\bi_
\bn_
\bt _
\bf_
\bl_
\ba_
\bg_
\bs);
17226 m
\bmu
\bun
\bnl
\blo
\boc
\bck
\bka
\bal
\bll
\bl(_
\bv_
\bo_
\bi_
\bd);
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.
17233 The following flags affect the behavior of m
\bml
\blo
\boc
\bck
\bka
\bal
\bll
\bl():
17235 MCL_CURRENT Lock all pages currently mapped into the process's address
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.
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.
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
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.
17257 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
17258 m
\bml
\blo
\boc
\bck
\bka
\bal
\bll
\bl() will fail if:
17260 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs argument is zero or includes unimplemented
17263 [ENOMEM] Locking all of the pages currently mapped would exceed
17264 either the system or per-process limit for locked
17267 [EAGAIN] Some or all of the memory mapped into the process's
17268 address space could not be locked when the call was
17271 [EPERM] The calling process does not have the appropriate
17272 privileges to perform the requested operation.
17274 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
17275 mincore(2), mlock(2), mmap(2), munmap(2), setrlimit(2)
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
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.
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.
17292 m
\bmm
\bma
\bap
\bp - map files or devices into memory
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>
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);
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.
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.
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.
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.
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:
17325 PROT_EXEC Pages may be executed.
17326 PROT_READ Pages may be read.
17327 PROT_WRITE Pages may be written.
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
17336 MAP_PRIVATE Modifications are private.
17338 MAP_SHARED Modifications are shared.
17340 Any combination of the following flags may additionally be used:
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.
17347 MAP_ANONYMOUS Synonym for MAP_ANON.
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.
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:
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.
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.
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.
17375 MAP_INHERIT Permit regions to be inherited across exec(3) system
17376 calls. On OpenBSD this flag is ignored.
17378 MAP_TRYFIXED Attempt to use the hint provided by _
\ba_
\bd_
\bd_
\br. On
17379 OpenBSD this is the default behavior.
17381 The close(2) function does not unmap pages; see munmap(2) for further
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.
17390 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
17391 m
\bmm
\bma
\bap
\bp() will fail if:
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
17399 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
17401 [EINVAL] MAP_PRIVATE and MAP_SHARED were both specified.
17403 [EINVAL] MAP_FIXED was specified and the _
\ba_
\bd_
\bd_
\br parameter was not
17406 [EINVAL] _
\ba_
\bd_
\bd_
\br and _
\bl_
\be_
\bn specified a region that would extend
17407 beyond the end of the address space.
17409 [EINVAL] _
\bf_
\bd did not specify a regular, character special, or
17410 block special file.
17412 [EINVAL] The allocation _
\bl_
\be_
\bn was 0.
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.
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)
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'').
17425 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
17426 The m
\bmm
\bma
\bap
\bp() system call first appeared in 4.1cBSD.
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.
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
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.
17448 m
\bmo
\bou
\bun
\bnt
\bt, u
\bun
\bnm
\bmo
\bou
\bun
\bnt
\bt - mount or dismount a filesystem
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>
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);
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);
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.
17469 The following _
\bf_
\bl_
\ba_
\bg_
\bs may be specified to suppress default semantics which
17470 affect filesystem access.
17472 MNT_RDONLY The filesystem should be treated as read-only: even the
17473 superuser may not write to it.
17475 MNT_NOATIME Do not update the access time on files in the filesystem
17476 unless the modification or status change times are also
17479 MNT_NOEXEC Do not allow files to be executed from the filesystem.
17481 MNT_NOSUID Do not honor setuid or setgid bits on files when
17484 MNT_NODEV Do not interpret special files on the filesystem.
17486 MNT_SYNCHRONOUS All I/O to the filesystem should be done synchronously.
17488 MNT_ASYNC All I/O to the filesystem should be done asynchronously.
17490 MNT_SOFTDEP Use soft dependencies. Applies to FFS filesystems only
17491 (see 'softdep' in mount(8)).
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.
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
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 */
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 */
17520 char *fspec; /* block special file to mount */
17521 struct export_args export_info;
17522 /* network export information */
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 */
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 */
17546 * Msdosfs mount options:
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 */
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 */
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 */
17590 * ntfs mount options:
17592 #define NTFS_MFLAG_CASEINS 0x00000001
17593 #define NTFS_MFLAG_ALLNAMES 0x00000002
17597 char *fspec; /* block special device to mount */
17600 The u
\bun
\bnm
\bmo
\bou
\bun
\bnt
\bt() function call disassociates the filesystem from the
17601 specified mount point _
\bd_
\bi_
\br.
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.
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
17613 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
17614 m
\bmo
\bou
\bun
\bnt
\bt() will fail when one of the following occurs:
17616 [EPERM] The caller is not the superuser.
17618 [ENAMETOOLONG] The path name exceeded {MNAMELEN} characters.
17620 [ELOOP] Too many symbolic links were encountered in translating a
17623 [ENOENT] A component of _
\bd_
\bi_
\br does not exist.
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.
17628 [EINVAL] An argument given was invalid.
17630 [EBUSY] Another process currently holds a reference to _
\bd_
\bi_
\br.
17632 [EFAULT] _
\bd_
\bi_
\br points outside the process's allocated address space.
17634 [EOPNOTSUPP] _
\bt_
\by_
\bp_
\be is not supported by the kernel.
17636 The following errors can occur for a ``ufs'' filesystem mount:
17638 [ENODEV] A component of ufs_args _
\bf_
\bs_
\bp_
\be_
\bc does not exist.
17640 [ENOTBLK] _
\bf_
\bs_
\bp_
\be_
\bc is not a block device.
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
17646 [EBUSY] _
\bf_
\bs_
\bp_
\be_
\bc is already mounted.
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.
17651 [ENOMEM] Not enough memory was available to read the cylinder group
17652 information for the filesystem.
17654 [EIO] An I/O error occurred while reading the super block or
17655 cylinder group information.
17657 [EFAULT] _
\bf_
\bs_
\bp_
\be_
\bc points outside the process's allocated address space.
17659 [EROFS] The filesystem was not unmounted cleanly and MNT_FORCE was not
17662 [EROFS] An attempt was made to mount a 4.2BSD filesystem without the
17665 The following errors can occur for an _
\bN_
\bF_
\bS filesystem mount:
17667 [ETIMEDOUT] _
\bN_
\bF_
\bS timed out trying to contact the server.
17669 [EFAULT] Some part of the information described by nfs_args points
17670 outside the process's allocated address space.
17672 The following errors can occur for a _
\bm_
\bf_
\bs filesystem mount:
17674 [EMFILE] No space remains in the mount table.
17676 [EINVAL] The super block for the filesystem had a bad magic number or an
17677 out of range block size.
17679 [ENOMEM] Not enough memory was available to read the cylinder group
17680 information for the filesystem.
17682 [EIO] A paging error occurred while reading the super block or
17683 cylinder group information.
17685 [EFAULT] _
\bN_
\ba_
\bm_
\be points outside the process's allocated address space.
17687 u
\bun
\bnm
\bmo
\bou
\bun
\bnt
\bt() may fail with one of the following errors:
17689 [EPERM] The caller is not the superuser.
17691 [ENOTDIR] A component of the path is not a directory.
17693 [EINVAL] An argument given was invalid.
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.
17699 [ELOOP] Too many symbolic links were encountered in translating
17702 [EINVAL] The requested directory is not in the mount table.
17704 [EBUSY] A process is holding a reference to a file located on the
17707 [EIO] An I/O error occurred while writing cached filesystem
17710 [EFAULT] _
\bd_
\bi_
\br points outside the process's allocated address space.
17712 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
17713 statfs(2), mfs(8), mount(8), umount(8)
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.
17722 Some of the error codes need translation to more obvious messages.
17725 m
\bmp
\bpr
\bro
\bot
\bte
\bec
\bct
\bt - control the protection of pages
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>
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);
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.
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:
17742 PROT_EXEC Pages may be executed.
17743 PROT_READ Pages may be read.
17744 PROT_WRITE Pages may be written.
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
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
17758 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
17759 m
\bmp
\bpr
\bro
\bot
\bte
\bec
\bct
\bt() will fail if:
17761 [EACCES] The process does not have sufficient access to the
17762 underlying memory object to provide the requested
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.
17770 [EINVAL] The _
\bp_
\br_
\bo_
\bt argument is invalid or the specified address
17771 range would wrap around.
17773 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
17774 madvise(2), mincore(2), msync(2), munmap(2)
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'').
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.
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.
17787 m
\bmq
\bqu
\bue
\ber
\bry
\by - provide mapping hints to applications
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>
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);
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).
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.
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.
17822 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
17823 m
\bmq
\bqu
\bue
\ber
\bry
\by() will fail if:
17825 [EINVAL] MAP_FIXED was specified and the requested memory area
17828 [ENOMEM] There was not enough memory left after the hint
17831 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
17833 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
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.
17843 m
\bms
\bsg
\bgc
\bct
\btl
\bl - message control operations
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>
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);
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.
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:
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() */
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:
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 */
17885 The operation to be performed by m
\bms
\bsg
\bgc
\bct
\btl
\bl() is specified in _
\bc_
\bm_
\bd and is one
17888 IPC_STAT Gather information about the message queue and place it in the
17889 structure pointed to by _
\bb_
\bu_
\bf.
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.
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
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.
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
17919 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
17920 m
\bms
\bsg
\bgc
\bct
\btl
\bl() will fail if:
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.
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.
17930 [EACCES] The command is IPC_STAT and the caller has no read
17931 permission for this message queue.
17933 [EINVAL] _
\bm_
\bs_
\bq_
\bi_
\bd is not a valid message queue identifier.
17935 _
\bc_
\bm_
\bd is not a valid command.
17937 [EFAULT] _
\bb_
\bu_
\bf specifies an invalid address.
17939 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
17940 msgget(2), msgrcv(2), msgsnd(2)
17942 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
17943 Message queues appeared in AT&T System V Release 1 UNIX.
17946 m
\bms
\bsg
\bgg
\bge
\bet
\bt - get message queue
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>
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);
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.
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.
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:
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
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
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.
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
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).
17979 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bc_
\bt_
\bi_
\bm_
\be is set to the current time.
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.
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.
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.
17993 [ENOSPC] A new message queue could not be created because the
17994 system limit for the number of message queues has been
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.
18000 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
18001 msgctl(2), msgrcv(2), msgsnd(2), ftok(3)
18003 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
18004 Message queues appeared in AT&T System V Release 1 UNIX.
18007 m
\bms
\bsg
\bgr
\brc
\bcv
\bv - receive a message from a message queue
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>
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);
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:
18020 long mtype; /* message type */
18021 char mtext[1]; /* body of message */
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).
18027 The value of _
\bm_
\bs_
\bg_
\bt_
\by_
\bp has one of the following meanings:
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
18032 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\bt_
\by_
\bp is equal to 0. The first message on the queue will be
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
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
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:
18050 +
\b+
\bo
\bo A message of the requested type becomes available on the message
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.
18056 +
\b+
\bo
\bo A signal is received and caught. -1 is returned, and _
\be_
\br_
\br_
\bn_
\bo set to
18059 If a message is successfully received, the data structure associated with
18060 _
\bm_
\bs_
\bq_
\bi_
\bd is updated as follows:
18062 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bc_
\bb_
\by_
\bt_
\be_
\bs is decremented by the size of the message.
18064 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bl_
\br_
\bp_
\bi_
\bd is set to the pid of the caller.
18066 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bl_
\br_
\bt_
\bi_
\bm_
\be is set to the current time.
18068 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bq_
\bn_
\bu_
\bm is decremented by 1.
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.
18075 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
18076 m
\bms
\bsg
\bgr
\brc
\bcv
\bv() will fail if:
18078 [EINVAL] _
\bm_
\bs_
\bq_
\bi_
\bd is not a valid message queue identifier.
18080 _
\bm_
\bs_
\bg_
\bs_
\bz is less than 0.
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.
18086 [EACCES] The calling process does not have read access to the
18089 [EFAULT] _
\bm_
\bs_
\bg_
\bp points to an invalid address.
18091 [EINTR] The system call was interrupted by the delivery of a
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.
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
18101 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
18102 msgctl(2), msgget(2), msgsnd(2)
18104 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
18105 Message queues appeared in AT&T System V Release 1 UNIX.
18108 m
\bms
\bsg
\bgs
\bsn
\bnd
\bd - send a message to a message queue
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>
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);
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:
18121 long mtype; /* message type */
18122 char mtext[1]; /* body of message */
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).
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
18136 +
\b+
\bo
\bo The condition which caused the call to block does no longer exist.
18137 The message will be sent.
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.
18142 +
\b+
\bo
\bo The caller catches a signal. The call returns with _
\be_
\br_
\br_
\bn_
\bo set to
18145 After a successful call, the data structure associated with the message
18146 queue is updated in the following way:
18148 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bc_
\bb_
\by_
\bt_
\be_
\bs is incremented by the size of the message.
18150 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bq_
\bn_
\bu_
\bm is incremented by 1.
18152 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bl_
\bs_
\bp_
\bi_
\bd is set to the pid of the calling process.
18154 +
\b+
\bo
\bo _
\bm_
\bs_
\bg_
\b__
\bs_
\bt_
\bi_
\bm_
\be is set to the current time.
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
18161 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
18162 m
\bms
\bsg
\bgs
\bsn
\bnd
\bd() will fail if:
18164 [EINVAL] _
\bm_
\bs_
\bq_
\bi_
\bd is not a valid message queue identifier.
18166 _
\bm_
\bs_
\bg_
\bs_
\bz is greater than _
\bm_
\bs_
\bg_
\b__
\bq_
\bb_
\by_
\bt_
\be_
\bs.
18168 [EACCES] The calling process does not have write access to the
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.
18175 [EFAULT] _
\bm_
\bs_
\bg_
\bp points to an invalid address.
18177 [EINTR] The system call was interrupted by the delivery of a
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.
18184 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
18185 msgctl(2), msgget(2), msgrcv(2)
18187 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
18188 Message queues appeared in AT&T System V Release 1 UNIX.
18191 m
\bms
\bsy
\byn
\bnc
\bc - synchronize a mapped region
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>
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);
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().
18210 The _
\bf_
\bl_
\ba_
\bg_
\bs argument is the bitwise OR of zero or more of the following
18213 MS_ASYNC Perform asynchronous writes.
18214 MS_SYNC Perform synchronous writes.
18215 MS_INVALIDATE Invalidate cached data after writing.
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
18222 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
18223 The following errors may be reported:
18225 [EBUSY] The MS_INVALIDATE flag was specified and a portion of
18226 the specified region was locked with mlock(2).
18228 [EINVAL] The specified _
\bf_
\bl_
\ba_
\bg_
\bs argument was invalid.
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.
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.
18238 [EIO] An I/O error occurred while writing.
18240 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
18241 madvise(2), mincore(2), minherit(2), mprotect(2), munmap(2)
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'')
18248 Writes are currently done synchronously even if the MS_ASYNC flag is
18252 m
\bml
\blo
\boc
\bck
\bk, m
\bmu
\bun
\bnl
\blo
\boc
\bck
\bk - lock (unlock) physical pages in memory
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>
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);
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);
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.
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).
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.
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.
18294 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
18295 m
\bml
\blo
\boc
\bck
\bk() will fail if:
18297 [EINVAL] The address given is not page aligned or the length is
18300 [EAGAIN] Locking the indicated range would exceed either the
18301 system or per-process limit for locked memory.
18303 [ENOMEM] Some portion of the indicated address range is not
18304 allocated. There was an error faulting/mapping a
18307 m
\bmu
\bun
\bnl
\blo
\boc
\bck
\bk() will fail if:
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
18313 [ENOMEM] Some portion of the indicated address range is not
18314 allocated. Some portion of the indicated address
18315 range is not locked.
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)
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.
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.
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.
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
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>
18343 m
\bml
\blo
\boc
\bck
\bka
\bal
\bll
\bl(_
\bi_
\bn_
\bt _
\bf_
\bl_
\ba_
\bg_
\bs);
18346 m
\bmu
\bun
\bnl
\blo
\boc
\bck
\bka
\bal
\bll
\bl(_
\bv_
\bo_
\bi_
\bd);
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.
18353 The following flags affect the behavior of m
\bml
\blo
\boc
\bck
\bka
\bal
\bll
\bl():
18355 MCL_CURRENT Lock all pages currently mapped into the process's address
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.
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.
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
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.
18377 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
18378 m
\bml
\blo
\boc
\bck
\bka
\bal
\bll
\bl() will fail if:
18380 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs argument is zero or includes unimplemented
18383 [ENOMEM] Locking all of the pages currently mapped would exceed
18384 either the system or per-process limit for locked
18387 [EAGAIN] Some or all of the memory mapped into the process's
18388 address space could not be locked when the call was
18391 [EPERM] The calling process does not have the appropriate
18392 privileges to perform the requested operation.
18394 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
18395 mincore(2), mlock(2), mmap(2), munmap(2), setrlimit(2)
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
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.
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.
18412 m
\bmu
\bun
\bnm
\bma
\bap
\bp - remove a mapping
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>
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);
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.
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
18430 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
18431 m
\bmu
\bun
\bnm
\bma
\bap
\bp() will fail if:
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
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)
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.
18447 n
\bna
\ban
\bno
\bos
\bsl
\ble
\bee
\bep
\bp - high resolution sleep
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>
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);
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
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.
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).
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.
18475 [EINTR] k
\bkq
\bqu
\bue
\beu
\bue
\be was interrupted by the delivery of a signal.
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.
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.
18484 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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'').
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.
18497 n
\bnf
\bfs
\bss
\bsv
\bvc
\bc - NFS services
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>
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);
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.
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:
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) */
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:
18534 int sock; /* Socket to serve */
18535 caddr_t name; /* Client address for connection based sockets */
18536 int namelen; /* Length of name */
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.
18544 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
18545 [EPERM] The caller is not the superuser.
18547 [EINVAL] The flag argument consisted of incompatible or
18548 otherwise unsupported bits.
18550 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
18551 mount_nfs(8), nfsd(8), sysctl(8)
18553 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
18554 The n
\bnf
\bfs
\bss
\bsv
\bvc
\bc function first appeared in 4.4BSD.
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
18564 o
\bop
\bpe
\ben
\bn, o
\bop
\bpe
\ben
\bna
\bat
\bt - open or create a file for reading or writing
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>
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.);
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.);
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)).
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:
18587 O_RDONLY Open for reading only.
18588 O_WRONLY Open for writing only.
18589 O_RDWR Open for reading and writing.
18591 Any combination of the following flags may additionally be used:
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
18605 O_DIRECTORY Error if _
\bp_
\ba_
\bt_
\bh does not name a directory.
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.
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.
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).
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.
18633 When a new file is created it is given the group of the directory which
18636 The new descriptor is set to remain open across execve(2) system calls;
18637 see close(2) and fcntl(2).
18639 The system imposes a limit on the number of file descriptors open
18640 simultaneously by one process. getdtablesize(3) returns the current
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.
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().
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.
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:
18660 [ENOTDIR] A component of the path prefix is not a directory.
18662 [ENOTDIR] O_DIRECTORY is specified and _
\bp_
\ba_
\bt_
\bh does not name a
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.
18669 [ENOENT] O_CREAT is not set and the named file does not exist.
18671 [ENOENT] A component of the path name that must exist does not
18674 [EACCES] Search permission is denied for a component of the
18677 [EACCES] The required permissions (for reading and/or writing)
18678 are denied for the given _
\bf_
\bl_
\ba_
\bg_
\bs.
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
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.
18688 [EISDIR] The named file is a directory, and the arguments
18689 specify it is to be opened for writing.
18691 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs specified for opening the file are not
18694 [EROFS] The named file resides on a read-only file system, and
18695 the file is to be modified.
18697 [EMFILE] The process has already reached its limit for open
18700 [ENFILE] The system file table is full.
18702 [ENXIO] The named file is a character special or block special
18703 file, and the device associated with this special file
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
18710 [EINTR] The o
\bop
\bpe
\ben
\bn() operation was interrupted by a signal.
18712 [EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying
18713 filesystem does not support locking.
18715 [EWOULDBLOCK] O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is
18716 specified and the file is already locked.
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.
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.
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.
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.
18737 [EIO] An I/O error occurred while making the directory entry
18738 or allocating the inode for O_CREAT.
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
18744 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
18747 [EEXIST] O_CREAT and O_EXCL were specified and the file exists.
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.
18752 [EOPNOTSUPP] An attempt was made to open a socket (not currently
18755 [EBUSY] An attempt was made to open a terminal device that
18756 requires exclusive access and the specified device has
18759 Additionally, the o
\bop
\bpe
\ben
\bna
\bat
\bt() function will fail if:
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
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.
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.
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)
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
18781 POSIX specifies three different flavors for synchronous I/O: O_SYNC,
18782 O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent.
18784 The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should
18785 not be used if portability is of concern.
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
18794 The o
\bop
\bpe
\ben
\bna
\bat
\bt() system call has been available since OpenBSD 5.0.
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.
18801 o
\bop
\bpe
\ben
\bn, o
\bop
\bpe
\ben
\bna
\bat
\bt - open or create a file for reading or writing
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>
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.);
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.);
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)).
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:
18824 O_RDONLY Open for reading only.
18825 O_WRONLY Open for writing only.
18826 O_RDWR Open for reading and writing.
18828 Any combination of the following flags may additionally be used:
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
18842 O_DIRECTORY Error if _
\bp_
\ba_
\bt_
\bh does not name a directory.
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.
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.
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).
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.
18870 When a new file is created it is given the group of the directory which
18873 The new descriptor is set to remain open across execve(2) system calls;
18874 see close(2) and fcntl(2).
18876 The system imposes a limit on the number of file descriptors open
18877 simultaneously by one process. getdtablesize(3) returns the current
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.
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().
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.
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:
18897 [ENOTDIR] A component of the path prefix is not a directory.
18899 [ENOTDIR] O_DIRECTORY is specified and _
\bp_
\ba_
\bt_
\bh does not name a
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.
18906 [ENOENT] O_CREAT is not set and the named file does not exist.
18908 [ENOENT] A component of the path name that must exist does not
18911 [EACCES] Search permission is denied for a component of the
18914 [EACCES] The required permissions (for reading and/or writing)
18915 are denied for the given _
\bf_
\bl_
\ba_
\bg_
\bs.
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
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.
18925 [EISDIR] The named file is a directory, and the arguments
18926 specify it is to be opened for writing.
18928 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs specified for opening the file are not
18931 [EROFS] The named file resides on a read-only file system, and
18932 the file is to be modified.
18934 [EMFILE] The process has already reached its limit for open
18937 [ENFILE] The system file table is full.
18939 [ENXIO] The named file is a character special or block special
18940 file, and the device associated with this special file
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
18947 [EINTR] The o
\bop
\bpe
\ben
\bn() operation was interrupted by a signal.
18949 [EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying
18950 filesystem does not support locking.
18952 [EWOULDBLOCK] O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is
18953 specified and the file is already locked.
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.
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.
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.
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.
18974 [EIO] An I/O error occurred while making the directory entry
18975 or allocating the inode for O_CREAT.
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
18981 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
18984 [EEXIST] O_CREAT and O_EXCL were specified and the file exists.
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.
18989 [EOPNOTSUPP] An attempt was made to open a socket (not currently
18992 [EBUSY] An attempt was made to open a terminal device that
18993 requires exclusive access and the specified device has
18996 Additionally, the o
\bop
\bpe
\ben
\bna
\bat
\bt() function will fail if:
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
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.
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.
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)
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
19018 POSIX specifies three different flavors for synchronous I/O: O_SYNC,
19019 O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent.
19021 The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should
19022 not be used if portability is of concern.
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
19031 The o
\bop
\bpe
\ben
\bna
\bat
\bt() system call has been available since OpenBSD 5.0.
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.
19038 p
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf, f
\bfp
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf - get configurable pathname variables
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>
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);
19047 f
\bfp
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf(_
\bi_
\bn_
\bt _
\bf_
\bd, _
\bi_
\bn_
\bt _
\bn_
\ba_
\bm_
\be);
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.
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>.
19059 The available values are as follows:
19062 The maximum file link count.
19065 The maximum number of bytes in a terminal canonical input line.
19068 The maximum number of bytes for which space is available in a
19069 terminal input queue.
19072 The maximum number of bytes in a file name.
19075 The maximum number of bytes in a pathname.
19078 The maximum number of bytes which will be written atomically to a
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.
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
19097 Returns the terminal character disabling value.
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.
19105 Minimum number of bytes of storage allocated for any portion of a
19109 Returns 1 if asynchronous I/O is supported, otherwise 0.
19112 Number of bits needed to represent the maximum file size.
19115 Returns 1 if prioritized I/O is supported, otherwise 0.
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.
19121 _PC_REC_MAX_XFER_SIZE
19122 Maximum recommended file transfer size.
19124 _PC_REC_MIN_XFER_SIZE
19125 Minimum recommended file transfer size.
19128 Recommended file transfer buffer alignment.
19131 Maximum number of bytes in a symbolic link.
19134 Returns 1 if synchronized I/O is supported, otherwise 0.
19136 _PC_TIMESTAMP_RESOLUTION
19137 The resolution in nanoseconds of file timestamps.
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
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.
19150 [EINVAL] The value of the _
\bn_
\ba_
\bm_
\be argument is invalid.
19152 [EINVAL] The implementation does not support an association of
19153 the variable name with the associated file.
19155 [EIO] An I/O error occurred while reading from the file
19158 p
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf() will fail if:
19160 [ENOTDIR] A component of the path prefix is not a directory.
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
19167 [ENOENT] The named file does not exist.
19169 [EACCES] Search permission is denied for a component of the
19172 [ELOOP] Too many symbolic links were encountered in
19173 translating the pathname.
19175 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
19178 f
\bfp
\bpa
\bat
\bth
\bhc
\bco
\bon
\bnf
\bf() will fail if:
19180 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
19182 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
19183 sysconf(3), sysctl(3)
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
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.
19193 p
\bpi
\bip
\bpe
\be, p
\bpi
\bip
\bpe
\be2
\b2 - create descriptor pair for interprocess communication
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>
19199 p
\bpi
\bip
\bpe
\be(_
\bi_
\bn_
\bt _
\bf_
\bi_
\bl_
\bd_
\be_
\bs_
\b[_
\b2_
\b]);
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>
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);
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.
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.
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.
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
19234 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
19235 p
\bpi
\bip
\bpe
\be() and p
\bpi
\bip
\bpe
\be2
\b2() will succeed unless:
19237 [EMFILE] Too many descriptors are active.
19239 [ENFILE] The system file table is full.
19241 [EFAULT] The _
\bf_
\bi_
\bl_
\bd_
\be_
\bs buffer is in an invalid area of the
19242 process's address space.
19244 In addition, p
\bpi
\bip
\bpe
\be2
\b2() may return the following error:
19246 [EINVAL] _
\bf_
\bl_
\ba_
\bg_
\bs is invalid.
19248 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
19249 sh(1), fork(2), read(2), socketpair(2), write(2)
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
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
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.
19267 p
\bpi
\bip
\bpe
\be, p
\bpi
\bip
\bpe
\be2
\b2 - create descriptor pair for interprocess communication
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>
19273 p
\bpi
\bip
\bpe
\be(_
\bi_
\bn_
\bt _
\bf_
\bi_
\bl_
\bd_
\be_
\bs_
\b[_
\b2_
\b]);
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>
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);
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.
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.
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.
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
19308 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
19309 p
\bpi
\bip
\bpe
\be() and p
\bpi
\bip
\bpe
\be2
\b2() will succeed unless:
19311 [EMFILE] Too many descriptors are active.
19313 [ENFILE] The system file table is full.
19315 [EFAULT] The _
\bf_
\bi_
\bl_
\bd_
\be_
\bs buffer is in an invalid area of the
19316 process's address space.
19318 In addition, p
\bpi
\bip
\bpe
\be2
\b2() may return the following error:
19320 [EINVAL] _
\bf_
\bl_
\ba_
\bg_
\bs is invalid.
19322 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
19323 sh(1), fork(2), read(2), socketpair(2), write(2)
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
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
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.
19341 p
\bpo
\bol
\bll
\bl, p
\bpp
\bpo
\bol
\bll
\bl - synchronous I/O multiplexing
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>
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);
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);
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.
19360 The arguments are as follows:
19362 _
\bf_
\bd_
\bs Points to an array of _
\bp_
\bo_
\bl_
\bl_
\bf_
\bd structures, which are defined as:
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
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.
19377 _
\bn_
\bf_
\bd_
\bs An unsigned integer specifying the number of _
\bp_
\bo_
\bl_
\bl_
\bf_
\bd structures
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.
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:
19389 POLLIN Data other than high-priority data may be read without
19392 POLLRDNORM Normal data may be read without blocking.
19394 POLLRDBAND Priority data may be read without blocking.
19396 POLLNORM Same as POLLRDNORM. This flag is provided for source code
19397 compatibility with older programs and should not be used in
19400 POLLPRI High-priority data may be read without blocking.
19402 POLLOUT Normal data may be written without blocking.
19404 POLLWRNORM Same as POLLOUT.
19406 POLLWRBAND Priority data may be written.
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.
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.
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.
19423 The significance and semantics of normal, priority, and high-priority
19424 data are device-specific.
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
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()
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.
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.
19455 Consider the following usage of select(2) that implements a read from the
19456 standard input with a 60 second time out:
19458 struct timeval timeout;
19463 timeout.tv_sec = 60;
19464 timeout.tv_usec = 0;
19466 FD_SET(STDIN_FILENO);
19467 nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout);
19471 errx(1, "time out");
19472 if (FD_ISSET(STDIN_FILENO, &readfds)) {
19473 if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
19477 This can be converted to p
\bpo
\bol
\bll
\bl() as follows:
19479 struct pollfd pdf[1];
19483 pfd[0].fd = STDIN_FILENO;
19484 pfd[0].events = POLLIN;
19485 nready = poll(pfd, 1, 60 * 1000);
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)
19497 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
19498 p
\bpo
\bol
\bll
\bl() and p
\bpp
\bpo
\bol
\bll
\bl() will fail if:
19500 [EFAULT] _
\bf_
\bd_
\bs points outside the process's allocated address
19503 [EINTR] A signal was caught before any polled events occurred
19504 and before the timeout elapsed.
19506 [EINVAL] _
\bn_
\bf_
\bd_
\bs was greater than the number of available file
19509 [EINVAL] The timeout passed was invalid.
19511 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
19512 clock_gettime(2), getrlimit(2), read(2), select(2), write(2)
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.
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.
19523 The POLLWRBAND flag is accepted but ignored by the kernel.
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.
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.
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
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>
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);
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);
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.
19550 The possible behaviors are:
19552 MADV_NORMAL No further special treatment needed.
19554 MADV_RANDOM Expect random page access patterns.
19556 MADV_SEQUENTIAL Expect sequential page references.
19558 MADV_WILLNEED The pages will be referenced soon.
19560 MADV_DONTNEED The pages will not be referenced soon.
19562 MADV_SPACEAVAIL Ensure that resources are reserved.
19564 MADV_FREE The pages don't contain any useful data and can be
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
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
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.
19580 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
19581 mincore(2), minherit(2), mprotect(2), msync(2), munmap(2)
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
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.
19592 The MADV_WILLNEED behavior is ignored. The MADV_SPACEAVAIL behavior is
19593 not implemented and will always fail.
19596 p
\bpo
\bol
\bll
\bl, p
\bpp
\bpo
\bol
\bll
\bl - synchronous I/O multiplexing
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>
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);
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);
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.
19615 The arguments are as follows:
19617 _
\bf_
\bd_
\bs Points to an array of _
\bp_
\bo_
\bl_
\bl_
\bf_
\bd structures, which are defined as:
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
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.
19632 _
\bn_
\bf_
\bd_
\bs An unsigned integer specifying the number of _
\bp_
\bo_
\bl_
\bl_
\bf_
\bd structures
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.
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:
19644 POLLIN Data other than high-priority data may be read without
19647 POLLRDNORM Normal data may be read without blocking.
19649 POLLRDBAND Priority data may be read without blocking.
19651 POLLNORM Same as POLLRDNORM. This flag is provided for source code
19652 compatibility with older programs and should not be used in
19655 POLLPRI High-priority data may be read without blocking.
19657 POLLOUT Normal data may be written without blocking.
19659 POLLWRNORM Same as POLLOUT.
19661 POLLWRBAND Priority data may be written.
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.
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.
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.
19678 The significance and semantics of normal, priority, and high-priority
19679 data are device-specific.
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
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()
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.
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.
19710 Consider the following usage of select(2) that implements a read from the
19711 standard input with a 60 second time out:
19713 struct timeval timeout;
19718 timeout.tv_sec = 60;
19719 timeout.tv_usec = 0;
19721 FD_SET(STDIN_FILENO);
19722 nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout);
19726 errx(1, "time out");
19727 if (FD_ISSET(STDIN_FILENO, &readfds)) {
19728 if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
19732 This can be converted to p
\bpo
\bol
\bll
\bl() as follows:
19734 struct pollfd pdf[1];
19738 pfd[0].fd = STDIN_FILENO;
19739 pfd[0].events = POLLIN;
19740 nready = poll(pfd, 1, 60 * 1000);
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)
19752 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
19753 p
\bpo
\bol
\bll
\bl() and p
\bpp
\bpo
\bol
\bll
\bl() will fail if:
19755 [EFAULT] _
\bf_
\bd_
\bs points outside the process's allocated address
19758 [EINTR] A signal was caught before any polled events occurred
19759 and before the timeout elapsed.
19761 [EINVAL] _
\bn_
\bf_
\bd_
\bs was greater than the number of available file
19764 [EINVAL] The timeout passed was invalid.
19766 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
19767 clock_gettime(2), getrlimit(2), read(2), select(2), write(2)
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.
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.
19778 The POLLWRBAND flag is accepted but ignored by the kernel.
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.
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.
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
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>
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);
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);
19799 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bsy
\bys
\bs/
\b/u
\bui
\bio
\bo.
\b.h
\bh>
\b>
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);
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>
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);
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
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:
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.
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.
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
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.
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.
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.
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:
19855 [EBADF] _
\bd is not a valid file or socket descriptor open for
19858 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
19861 [EIO] An I/O error occurred while reading from the file
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.
19868 In addition, r
\bre
\bea
\bad
\bd() and r
\bre
\bea
\bad
\bdv
\bv() may return the following errors:
19870 [EAGAIN] The file was marked for non-blocking I/O, and no data
19871 were ready to be read.
19873 [ENOTCONN] The file is a socket associated with a connection-
19874 oriented protocol and has not been connected.
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.
19881 r
\bre
\bea
\bad
\bd() and p
\bpr
\bre
\bea
\bad
\bd() may return the following error:
19883 [EINVAL] _
\bn_
\bb_
\by_
\bt_
\be_
\bs was larger than SSIZE_MAX.
19885 p
\bpr
\bre
\bea
\bad
\bd() and p
\bpr
\bre
\bea
\bad
\bdv
\bv() may return the following errors:
19887 [EINVAL] _
\bo_
\bf_
\bf_
\bs_
\be_
\bt was negative.
19889 [ESPIPE] _
\bd is associated with a pipe, socket, FIFO, or tty.
19891 r
\bre
\bea
\bad
\bdv
\bv() and p
\bpr
\bre
\bea
\bad
\bdv
\bv() may return one of the following errors:
19893 [EINVAL] _
\bi_
\bo_
\bv_
\bc_
\bn_
\bt was less than or equal to 0, or greater than
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.
19899 [EFAULT] Part of _
\bi_
\bo_
\bv points outside the process's allocated
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),
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'').
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
19915 C
\bCA
\bAV
\bVE
\bEA
\bAT
\bTS
\bS
19916 Error checks should explicitly test for -1. Code such as
19918 while ((nr = read(fd, buf, sizeof(buf))) > 0)
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
19925 while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0)
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
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>
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);
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);
19939 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bsy
\bys
\bs/
\b/u
\bui
\bio
\bo.
\b.h
\bh>
\b>
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);
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>
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);
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
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:
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.
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.
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
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.
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.
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.
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:
19995 [EBADF] _
\bd is not a valid file or socket descriptor open for
19998 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
20001 [EIO] An I/O error occurred while reading from the file
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.
20008 In addition, r
\bre
\bea
\bad
\bd() and r
\bre
\bea
\bad
\bdv
\bv() may return the following errors:
20010 [EAGAIN] The file was marked for non-blocking I/O, and no data
20011 were ready to be read.
20013 [ENOTCONN] The file is a socket associated with a connection-
20014 oriented protocol and has not been connected.
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.
20021 r
\bre
\bea
\bad
\bd() and p
\bpr
\bre
\bea
\bad
\bd() may return the following error:
20023 [EINVAL] _
\bn_
\bb_
\by_
\bt_
\be_
\bs was larger than SSIZE_MAX.
20025 p
\bpr
\bre
\bea
\bad
\bd() and p
\bpr
\bre
\bea
\bad
\bdv
\bv() may return the following errors:
20027 [EINVAL] _
\bo_
\bf_
\bf_
\bs_
\be_
\bt was negative.
20029 [ESPIPE] _
\bd is associated with a pipe, socket, FIFO, or tty.
20031 r
\bre
\bea
\bad
\bdv
\bv() and p
\bpr
\bre
\bea
\bad
\bdv
\bv() may return one of the following errors:
20033 [EINVAL] _
\bi_
\bo_
\bv_
\bc_
\bn_
\bt was less than or equal to 0, or greater than
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.
20039 [EFAULT] Part of _
\bi_
\bo_
\bv points outside the process's allocated
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),
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'').
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
20055 C
\bCA
\bAV
\bVE
\bEA
\bAT
\bTS
\bS
20056 Error checks should explicitly test for -1. Code such as
20058 while ((nr = read(fd, buf, sizeof(buf))) > 0)
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
20065 while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0)
20068 p
\bpr
\bro
\bof
\bfi
\bil
\bl - control process profiling
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>
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);
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.
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:
20087 [(pc - offset) / 2] * scale / 65536
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.
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.
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
20105 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
20106 The following error may be reported:
20108 [EFAULT] The buffer _
\bs_
\ba_
\bm_
\bp_
\bl_
\be_
\bs contains an invalid address.
20110 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
20114 This routine should be named p
\bpr
\bro
\bof
\bfi
\bil
\ble
\be().
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.
20118 The format of the gmon.out file is undocumented.
20121 s
\bse
\bel
\ble
\bec
\bct
\bt, p
\bps
\bse
\bel
\ble
\bec
\bct
\bt - synchronous I/O multiplexing
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>
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);
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);
20134 F
\bFD
\bD_
\b_S
\bSE
\bET
\bT(_
\bf_
\bd, _
\b&_
\bf_
\bd_
\bs_
\be_
\bt);
20136 F
\bFD
\bD_
\b_C
\bCL
\bLR
\bR(_
\bf_
\bd, _
\b&_
\bf_
\bd_
\bs_
\be_
\bt);
20138 F
\bFD
\bD_
\b_I
\bIS
\bSS
\bSE
\bET
\bT(_
\bf_
\bd, _
\b&_
\bf_
\bd_
\bs_
\be_
\bt);
20140 F
\bFD
\bD_
\b_Z
\bZE
\bER
\bRO
\bO(_
\b&_
\bf_
\bd_
\bs_
\be_
\bt);
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.
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.
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().
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.
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()
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.
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
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:
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.
20197 [EBADF] One of the descriptor sets specified an invalid
20200 [EINTR] A signal was delivered before the time limit expired
20201 and before any of the selected descriptors became
20204 [EINVAL] The specified time limit is invalid. One of its
20205 components is negative or too large.
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)
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.
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.
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:
20236 fdsr = calloc(howmany(max+1, NFDBITS), sizeof(fd_mask));
20237 if (fdsr == NULL) {
20242 n = select(max+1, fdsr, NULL, NULL, &tv);
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.
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)).
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.
20268 p
\bpt
\btr
\bra
\bac
\bce
\be - process tracing and debugging
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>
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);
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.
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:
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.
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().
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.
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
20332 PT_KILL The traced process terminates, as if PT_CONTINUE had been
20333 used with SIGKILL given as the signal to be delivered.
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.
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.
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''
20360 struct ptrace_io_desc {
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:
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.
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''
20394 typedef struct ptrace_event {
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:
20401 PTRACE_FORK Report fork(2).
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).
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).
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:
20417 typedef struct ptrace_state {
20418 int pe_report_event;
20419 pid_t pe_other_pid;
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).
20428 Additionally, machine-specific requests can exist. Depending on the
20429 architecture, the following requests may be available under OpenBSD:
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.
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.
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).
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.
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.
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.
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.
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.
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:
20477 No process having the specified process ID exists.
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.)
20489 +
\b+
\bo
\bo PT_ATTACH was attempted on a process that was already being
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
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.
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.
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.
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
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>
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);
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);
20526 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bsy
\bys
\bs/
\b/u
\bui
\bio
\bo.
\b.h
\bh>
\b>
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);
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>
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);
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
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:
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.
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
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
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.
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)).
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.
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.
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.
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:
20592 [EBADF] _
\bd is not a valid descriptor open for writing.
20594 [EFBIG] An attempt was made to write a file that exceeds the
20595 process's file size limit or the maximum file size.
20597 [ENOSPC] There is no free space remaining on the file system
20598 containing the file.
20600 [EDQUOT] The user's quota of disk blocks on the file system
20601 containing the file has been exhausted.
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
20608 [EIO] An I/O error occurred while reading from or writing to
20611 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
20614 In addition, w
\bwr
\bri
\bit
\bte
\be() and w
\bwr
\bri
\bit
\bte
\bev
\bv() may return the following errors:
20616 [EPIPE] An attempt is made to write to a pipe that is not open
20617 for reading by any process.
20619 [EPIPE] An attempt is made to write to a socket of type
20620 SOCK_STREAM that is not connected to a peer socket.
20622 [EAGAIN] The file was marked for non-blocking I/O, and no data
20623 could be written immediately.
20625 [ENETDOWN] The destination address specified a network that is
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.
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
20641 w
\bwr
\bri
\bit
\bte
\be() and p
\bpw
\bwr
\bri
\bit
\bte
\be() may return the following error:
20643 [EINVAL] _
\bn_
\bb_
\by_
\bt_
\be_
\bs was larger than SSIZE_MAX.
20645 p
\bpw
\bwr
\bri
\bit
\bte
\be() and p
\bpw
\bwr
\bri
\bit
\bte
\bev
\bv() may return the following error:
20647 [EINVAL] _
\bo_
\bf_
\bf_
\bs_
\be_
\bt was negative.
20649 [ESPIPE] _
\bd is associated with a pipe, socket, FIFO, or tty.
20651 w
\bwr
\bri
\bit
\bte
\bev
\bv() and p
\bpw
\bwr
\bri
\bit
\bte
\bev
\bv() may return one of the following errors:
20653 [EINVAL] _
\bi_
\bo_
\bv_
\bc_
\bn_
\bt was less than or equal to 0, or greater than
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.
20659 [EFAULT] Part of _
\bi_
\bo_
\bv points outside the process's allocated
20662 [ENOBUFS] The system lacked sufficient buffer space or a queue
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)
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'').
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.
20678 C
\bCA
\bAV
\bVE
\bEA
\bAT
\bTS
\bS
20679 Error checks should explicitly test for -1. Code such as
20681 while ((nr = write(fd, buf, sizeof(buf))) > 0)
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
20688 while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0)
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
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>
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);
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);
20702 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bsy
\bys
\bs/
\b/u
\bui
\bio
\bo.
\b.h
\bh>
\b>
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);
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>
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);
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
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:
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.
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
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
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.
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)).
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.
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.
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.
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:
20768 [EBADF] _
\bd is not a valid descriptor open for writing.
20770 [EFBIG] An attempt was made to write a file that exceeds the
20771 process's file size limit or the maximum file size.
20773 [ENOSPC] There is no free space remaining on the file system
20774 containing the file.
20776 [EDQUOT] The user's quota of disk blocks on the file system
20777 containing the file has been exhausted.
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
20784 [EIO] An I/O error occurred while reading from or writing to
20787 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
20790 In addition, w
\bwr
\bri
\bit
\bte
\be() and w
\bwr
\bri
\bit
\bte
\bev
\bv() may return the following errors:
20792 [EPIPE] An attempt is made to write to a pipe that is not open
20793 for reading by any process.
20795 [EPIPE] An attempt is made to write to a socket of type
20796 SOCK_STREAM that is not connected to a peer socket.
20798 [EAGAIN] The file was marked for non-blocking I/O, and no data
20799 could be written immediately.
20801 [ENETDOWN] The destination address specified a network that is
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.
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
20817 w
\bwr
\bri
\bit
\bte
\be() and p
\bpw
\bwr
\bri
\bit
\bte
\be() may return the following error:
20819 [EINVAL] _
\bn_
\bb_
\by_
\bt_
\be_
\bs was larger than SSIZE_MAX.
20821 p
\bpw
\bwr
\bri
\bit
\bte
\be() and p
\bpw
\bwr
\bri
\bit
\bte
\bev
\bv() may return the following error:
20823 [EINVAL] _
\bo_
\bf_
\bf_
\bs_
\be_
\bt was negative.
20825 [ESPIPE] _
\bd is associated with a pipe, socket, FIFO, or tty.
20827 w
\bwr
\bri
\bit
\bte
\bev
\bv() and p
\bpw
\bwr
\bri
\bit
\bte
\bev
\bv() may return one of the following errors:
20829 [EINVAL] _
\bi_
\bo_
\bv_
\bc_
\bn_
\bt was less than or equal to 0, or greater than
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.
20835 [EFAULT] Part of _
\bi_
\bo_
\bv points outside the process's allocated
20838 [ENOBUFS] The system lacked sufficient buffer space or a queue
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)
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'').
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.
20854 C
\bCA
\bAV
\bVE
\bEA
\bAT
\bTS
\bS
20855 Error checks should explicitly test for -1. Code such as
20857 while ((nr = write(fd, buf, sizeof(buf))) > 0)
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
20864 while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0)
20867 q
\bqu
\buo
\bot
\bta
\bac
\bct
\btl
\bl - manipulate filesystem quotas
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>
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);
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
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:
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.
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
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.
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
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.
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.
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
20928 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
20929 A q
\bqu
\buo
\bot
\bta
\bac
\bct
\btl
\bl() call will fail if:
20931 [EOPNOTSUPP] The kernel has not been compiled with the QUOTA
20934 [EUSERS] The quota table cannot be expanded.
20936 [EINVAL] _
\bc_
\bm_
\bd or the command type is invalid.
20938 [EACCES] In Q_QUOTAON, the quota file is not a plain file.
20940 [EACCES] Search permission is denied for a component of a path
20943 [ENOTDIR] A component of a path prefix was not a directory.
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.
20949 [ENOENT] A filename does not exist.
20951 [ELOOP] Too many symbolic links were encountered in
20952 translating a pathname.
20954 [EROFS] In Q_QUOTAON, the quota file resides on a read-only
20957 [EIO] An I/O error occurred while reading from or writing to
20958 a file containing quotas.
20960 [EFAULT] An invalid _
\ba_
\bd_
\bd_
\br was supplied; the associated structure
20961 could not be copied in or out of the kernel.
20963 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
20966 [EPERM] The call was privileged and the caller was not the
20969 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
20970 quota(1), fstab(5), edquota(8), quotacheck(8), quotaon(8), repquota(8)
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.
20976 There should be some way to integrate this call with the resource limit
20977 interface provided by setrlimit(2) and getrlimit(2).
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
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>
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);
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);
20991 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bsy
\bys
\bs/
\b/u
\bui
\bio
\bo.
\b.h
\bh>
\b>
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);
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>
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);
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
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:
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.
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.
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
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.
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.
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.
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:
21047 [EBADF] _
\bd is not a valid file or socket descriptor open for
21050 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
21053 [EIO] An I/O error occurred while reading from the file
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.
21060 In addition, r
\bre
\bea
\bad
\bd() and r
\bre
\bea
\bad
\bdv
\bv() may return the following errors:
21062 [EAGAIN] The file was marked for non-blocking I/O, and no data
21063 were ready to be read.
21065 [ENOTCONN] The file is a socket associated with a connection-
21066 oriented protocol and has not been connected.
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.
21073 r
\bre
\bea
\bad
\bd() and p
\bpr
\bre
\bea
\bad
\bd() may return the following error:
21075 [EINVAL] _
\bn_
\bb_
\by_
\bt_
\be_
\bs was larger than SSIZE_MAX.
21077 p
\bpr
\bre
\bea
\bad
\bd() and p
\bpr
\bre
\bea
\bad
\bdv
\bv() may return the following errors:
21079 [EINVAL] _
\bo_
\bf_
\bf_
\bs_
\be_
\bt was negative.
21081 [ESPIPE] _
\bd is associated with a pipe, socket, FIFO, or tty.
21083 r
\bre
\bea
\bad
\bdv
\bv() and p
\bpr
\bre
\bea
\bad
\bdv
\bv() may return one of the following errors:
21085 [EINVAL] _
\bi_
\bo_
\bv_
\bc_
\bn_
\bt was less than or equal to 0, or greater than
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.
21091 [EFAULT] Part of _
\bi_
\bo_
\bv points outside the process's allocated
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),
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'').
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
21107 C
\bCA
\bAV
\bVE
\bEA
\bAT
\bTS
\bS
21108 Error checks should explicitly test for -1. Code such as
21110 while ((nr = read(fd, buf, sizeof(buf))) > 0)
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
21117 while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0)
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
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>
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);
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>
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);
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.
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.
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().
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.
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:
21156 [ENOTDIR] A component of the path prefix is not a directory.
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.
21162 [ENOENT] The named file does not exist.
21164 [EACCES] Search permission is denied for a component of the
21167 [ELOOP] Too many symbolic links were encountered in
21168 translating the pathname.
21170 [EINVAL] The named file is not a symbolic link.
21172 [EIO] An I/O error occurred while reading from the file
21175 [EFAULT] _
\bb_
\bu_
\bf or _
\bp_
\ba_
\bt_
\bh extends outside the process's allocated
21178 Additionally, r
\bre
\bea
\bad
\bdl
\bli
\bin
\bnk
\bka
\bat
\bt() will fail if:
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
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.
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.
21192 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
21193 lstat(2), stat(2), symlink(2), symlink(7)
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
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.
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
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>
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);
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>
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);
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.
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.
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().
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.
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:
21240 [ENOTDIR] A component of the path prefix is not a directory.
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.
21246 [ENOENT] The named file does not exist.
21248 [EACCES] Search permission is denied for a component of the
21251 [ELOOP] Too many symbolic links were encountered in
21252 translating the pathname.
21254 [EINVAL] The named file is not a symbolic link.
21256 [EIO] An I/O error occurred while reading from the file
21259 [EFAULT] _
\bb_
\bu_
\bf or _
\bp_
\ba_
\bt_
\bh extends outside the process's allocated
21262 Additionally, r
\bre
\bea
\bad
\bdl
\bli
\bin
\bnk
\bka
\bat
\bt() will fail if:
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
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.
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.
21276 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
21277 lstat(2), stat(2), symlink(2), symlink(7)
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
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.
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
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>
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);
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);
21299 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bsy
\bys
\bs/
\b/u
\bui
\bio
\bo.
\b.h
\bh>
\b>
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);
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>
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);
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
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:
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.
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.
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
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.
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.
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.
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:
21355 [EBADF] _
\bd is not a valid file or socket descriptor open for
21358 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
21361 [EIO] An I/O error occurred while reading from the file
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.
21368 In addition, r
\bre
\bea
\bad
\bd() and r
\bre
\bea
\bad
\bdv
\bv() may return the following errors:
21370 [EAGAIN] The file was marked for non-blocking I/O, and no data
21371 were ready to be read.
21373 [ENOTCONN] The file is a socket associated with a connection-
21374 oriented protocol and has not been connected.
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.
21381 r
\bre
\bea
\bad
\bd() and p
\bpr
\bre
\bea
\bad
\bd() may return the following error:
21383 [EINVAL] _
\bn_
\bb_
\by_
\bt_
\be_
\bs was larger than SSIZE_MAX.
21385 p
\bpr
\bre
\bea
\bad
\bd() and p
\bpr
\bre
\bea
\bad
\bdv
\bv() may return the following errors:
21387 [EINVAL] _
\bo_
\bf_
\bf_
\bs_
\be_
\bt was negative.
21389 [ESPIPE] _
\bd is associated with a pipe, socket, FIFO, or tty.
21391 r
\bre
\bea
\bad
\bdv
\bv() and p
\bpr
\bre
\bea
\bad
\bdv
\bv() may return one of the following errors:
21393 [EINVAL] _
\bi_
\bo_
\bv_
\bc_
\bn_
\bt was less than or equal to 0, or greater than
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.
21399 [EFAULT] Part of _
\bi_
\bo_
\bv points outside the process's allocated
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),
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'').
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
21415 C
\bCA
\bAV
\bVE
\bEA
\bAT
\bTS
\bS
21416 Error checks should explicitly test for -1. Code such as
21418 while ((nr = read(fd, buf, sizeof(buf))) > 0)
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
21425 while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0)
21428 r
\bre
\beb
\bbo
\boo
\bot
\bt - reboot system or halt processor
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>
21435 r
\bre
\beb
\bbo
\boo
\bot
\bt(_
\bi_
\bn_
\bt _
\bh_
\bo_
\bw_
\bt_
\bo);
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.
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.
21446 RB_AUTOBOOT The default, causing the system to reboot in its usual
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.
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
21462 RB_DUMP Dump kernel memory before rebooting; see savecore(8) for
21465 RB_HALT The processor is simply halted; no reboot takes place.
21467 RB_POWERDOWN If used in conjunction with RB_HALT, and if the system
21468 hardware supports the function, the system will be powered
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.
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.
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.
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.
21496 RB_RDONLY Initially mount the root file system read-only. This is
21497 currently the default, and this option has been deprecated.
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
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)).
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.
21516 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
21517 [EPERM] The caller is not the superuser.
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),
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.
21527 Not all platforms support all possible arguments.
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
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>
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);
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);
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);
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.
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
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.
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)).
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).
21573 The select(2) or poll(2) system calls may be used to determine when more
21576 The _
\bf_
\bl_
\ba_
\bg_
\bs argument is the bitwise OR of zero or more of the following
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
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.
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>:
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 */
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
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[]; */
21631 See CMSG_DATA(3) for how these messages are constructed and decomposed.
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.
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:
21640 MSG_OOB Returned to indicate that expedited or out-of-band data
21642 MSG_EOR Indicates end-of-record; the data returned completed a
21643 record (generally used with sockets of type
21645 MSG_TRUNC Indicates that the trailing portion of a datagram was
21646 discarded because the datagram was larger than the
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.
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
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:
21660 [EBADF] The argument _
\bs is an invalid descriptor.
21662 [ENOTCONN] The socket is associated with a connection-oriented
21663 protocol and has not been connected (see connect(2) and
21666 [ENOTSOCK] The argument _
\bs does not refer to a socket.
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.
21672 [EINTR] The receive was interrupted by delivery of a signal
21673 before any data were available.
21675 [EFAULT] The receive buffer pointer(s) point outside the process's
21678 [EHOSTUNREACH] A socket operation was attempted to an unreachable host.
21680 [EHOSTDOWN] A socket operation failed because the destination host
21683 [ENETDOWN] A socket operation encountered a dead network.
21685 [ECONNREFUSED] The socket is associated with a connection-oriented
21686 protocol and the connection was forcefully rejected (see
21689 In addition, r
\bre
\bec
\bcv
\bv() and r
\bre
\bec
\bcv
\bvf
\bfr
\bro
\bom
\bm() may return the following error:
21691 [EINVAL] _
\bl_
\be_
\bn was larger than SSIZE_MAX.
21693 And r
\bre
\bec
\bcv
\bvm
\bms
\bsg
\bg() may return one of the following errors:
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.
21698 [EMSGSIZE] The _
\bm_
\bs_
\bg_
\b__
\bi_
\bo_
\bv_
\bl_
\be_
\bn member of _
\bm_
\bs_
\bg was less than 0 or larger
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().
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)
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.
21715 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
21716 The r
\bre
\bec
\bcv
\bv() function call appeared in 4.2BSD.
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
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>
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);
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);
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);
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.
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
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.
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)).
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).
21762 The select(2) or poll(2) system calls may be used to determine when more
21765 The _
\bf_
\bl_
\ba_
\bg_
\bs argument is the bitwise OR of zero or more of the following
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
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.
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>:
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 */
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
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[]; */
21820 See CMSG_DATA(3) for how these messages are constructed and decomposed.
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.
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:
21829 MSG_OOB Returned to indicate that expedited or out-of-band data
21831 MSG_EOR Indicates end-of-record; the data returned completed a
21832 record (generally used with sockets of type
21834 MSG_TRUNC Indicates that the trailing portion of a datagram was
21835 discarded because the datagram was larger than the
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.
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
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:
21849 [EBADF] The argument _
\bs is an invalid descriptor.
21851 [ENOTCONN] The socket is associated with a connection-oriented
21852 protocol and has not been connected (see connect(2) and
21855 [ENOTSOCK] The argument _
\bs does not refer to a socket.
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.
21861 [EINTR] The receive was interrupted by delivery of a signal
21862 before any data were available.
21864 [EFAULT] The receive buffer pointer(s) point outside the process's
21867 [EHOSTUNREACH] A socket operation was attempted to an unreachable host.
21869 [EHOSTDOWN] A socket operation failed because the destination host
21872 [ENETDOWN] A socket operation encountered a dead network.
21874 [ECONNREFUSED] The socket is associated with a connection-oriented
21875 protocol and the connection was forcefully rejected (see
21878 In addition, r
\bre
\bec
\bcv
\bv() and r
\bre
\bec
\bcv
\bvf
\bfr
\bro
\bom
\bm() may return the following error:
21880 [EINVAL] _
\bl_
\be_
\bn was larger than SSIZE_MAX.
21882 And r
\bre
\bec
\bcv
\bvm
\bms
\bsg
\bg() may return one of the following errors:
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.
21887 [EMSGSIZE] The _
\bm_
\bs_
\bg_
\b__
\bi_
\bo_
\bv_
\bl_
\be_
\bn member of _
\bm_
\bs_
\bg was less than 0 or larger
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().
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)
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.
21904 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
21905 The r
\bre
\bec
\bcv
\bv() function call appeared in 4.2BSD.
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
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>
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);
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);
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);
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.
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
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.
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)).
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).
21951 The select(2) or poll(2) system calls may be used to determine when more
21954 The _
\bf_
\bl_
\ba_
\bg_
\bs argument is the bitwise OR of zero or more of the following
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
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.
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>:
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 */
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
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[]; */
22009 See CMSG_DATA(3) for how these messages are constructed and decomposed.
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.
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:
22018 MSG_OOB Returned to indicate that expedited or out-of-band data
22020 MSG_EOR Indicates end-of-record; the data returned completed a
22021 record (generally used with sockets of type
22023 MSG_TRUNC Indicates that the trailing portion of a datagram was
22024 discarded because the datagram was larger than the
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.
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
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:
22038 [EBADF] The argument _
\bs is an invalid descriptor.
22040 [ENOTCONN] The socket is associated with a connection-oriented
22041 protocol and has not been connected (see connect(2) and
22044 [ENOTSOCK] The argument _
\bs does not refer to a socket.
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.
22050 [EINTR] The receive was interrupted by delivery of a signal
22051 before any data were available.
22053 [EFAULT] The receive buffer pointer(s) point outside the process's
22056 [EHOSTUNREACH] A socket operation was attempted to an unreachable host.
22058 [EHOSTDOWN] A socket operation failed because the destination host
22061 [ENETDOWN] A socket operation encountered a dead network.
22063 [ECONNREFUSED] The socket is associated with a connection-oriented
22064 protocol and the connection was forcefully rejected (see
22067 In addition, r
\bre
\bec
\bcv
\bv() and r
\bre
\bec
\bcv
\bvf
\bfr
\bro
\bom
\bm() may return the following error:
22069 [EINVAL] _
\bl_
\be_
\bn was larger than SSIZE_MAX.
22071 And r
\bre
\bec
\bcv
\bvm
\bms
\bsg
\bg() may return one of the following errors:
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.
22076 [EMSGSIZE] The _
\bm_
\bs_
\bg_
\b__
\bi_
\bo_
\bv_
\bl_
\be_
\bn member of _
\bm_
\bs_
\bg was less than 0 or larger
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().
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)
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.
22093 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
22094 The r
\bre
\bec
\bcv
\bv() function call appeared in 4.2BSD.
22097 r
\bre
\ben
\bna
\bam
\bme
\be, r
\bre
\ben
\bna
\bam
\bme
\bea
\bat
\bt - change the name of a file
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>
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);
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>
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);
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.
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
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.
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.
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.
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
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
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.
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.
22149 [EACCES] A component of either path prefix denies search
22152 [EACCES] The requested change requires writing in a directory
22153 that denies write permission.
22155 [EACCES] The _
\bf_
\br_
\bo_
\bm argument is a directory and denies write
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.
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.
22166 [ELOOP] Too many symbolic links were encountered in
22167 translating either pathname.
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.
22173 [ENOTDIR] A component of either path prefix is not a directory.
22175 [ENOTDIR] _
\bf_
\br_
\bo_
\bm is a directory, but _
\bt_
\bo is not a directory.
22177 [EISDIR] _
\bt_
\bo is a directory, but _
\bf_
\br_
\bo_
\bm is not a directory.
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.
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
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.
22194 [EIO] An I/O error occurred while making or updating a
22197 [EROFS] The requested link requires writing in a directory on
22198 a read-only file system.
22200 [EFAULT] _
\bf_
\br_
\bo_
\bm or _
\bt_
\bo points outside the process's allocated
22203 [EINVAL] _
\bf_
\br_
\bo_
\bm is a parent directory of _
\bt_
\bo, or an attempt is
22204 made to rename `.' or `..'.
22206 [ENOTEMPTY] _
\bt_
\bo is a directory and is not empty.
22208 Additionally, r
\bre
\ben
\bna
\bam
\bme
\bea
\bat
\bt() will fail if:
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.
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.
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,
22223 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
22224 mv(1), open(2), symlink(7)
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
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.
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.
22244 r
\bre
\ben
\bna
\bam
\bme
\be, r
\bre
\ben
\bna
\bam
\bme
\bea
\bat
\bt - change the name of a file
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>
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);
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>
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);
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.
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
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.
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.
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.
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
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
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.
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.
22296 [EACCES] A component of either path prefix denies search
22299 [EACCES] The requested change requires writing in a directory
22300 that denies write permission.
22302 [EACCES] The _
\bf_
\br_
\bo_
\bm argument is a directory and denies write
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.
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.
22313 [ELOOP] Too many symbolic links were encountered in
22314 translating either pathname.
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.
22320 [ENOTDIR] A component of either path prefix is not a directory.
22322 [ENOTDIR] _
\bf_
\br_
\bo_
\bm is a directory, but _
\bt_
\bo is not a directory.
22324 [EISDIR] _
\bt_
\bo is a directory, but _
\bf_
\br_
\bo_
\bm is not a directory.
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.
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
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.
22341 [EIO] An I/O error occurred while making or updating a
22344 [EROFS] The requested link requires writing in a directory on
22345 a read-only file system.
22347 [EFAULT] _
\bf_
\br_
\bo_
\bm or _
\bt_
\bo points outside the process's allocated
22350 [EINVAL] _
\bf_
\br_
\bo_
\bm is a parent directory of _
\bt_
\bo, or an attempt is
22351 made to rename `.' or `..'.
22353 [ENOTEMPTY] _
\bt_
\bo is a directory and is not empty.
22355 Additionally, r
\bre
\ben
\bna
\bam
\bme
\bea
\bat
\bt() will fail if:
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.
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.
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,
22370 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
22371 mv(1), open(2), symlink(7)
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
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.
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.
22391 r
\bre
\bev
\bvo
\bok
\bke
\be - revoke file access
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>
22397 r
\bre
\bev
\bvo
\bok
\bke
\be(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bp_
\ba_
\bt_
\bh);
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.
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.
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
22417 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
22418 Access to the named file is revoked unless one of the following:
22420 [ENOTDIR] A component of the path prefix is not a directory.
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.
22426 [ENOENT] The named file or a component of the path name does
22429 [EACCES] Search permission is denied for a component of the
22432 [ELOOP] Too many symbolic links were encountered in
22433 translating the pathname.
22435 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
22438 [EPERM] The caller is neither the owner of the file nor the
22441 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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.
22448 r
\brm
\bmd
\bdi
\bir
\br - remove a directory file
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>
22454 r
\brm
\bmd
\bdi
\bir
\br(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bp_
\ba_
\bt_
\bh);
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 `..'.
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.
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
22469 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
22470 The named file is removed unless:
22472 [ENOTDIR] A component of the path is not a directory.
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.
22478 [ENOENT] The named directory does not exist.
22480 [ELOOP] Too many symbolic links were encountered in
22481 translating the pathname.
22483 [ENOTEMPTY] The named directory contains files other than `.' and
22486 [EACCES] Search permission is denied for a component of the
22489 [EACCES] Write permission is denied on the directory containing
22490 the directory to be removed.
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
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)).
22501 [EBUSY] The directory to be removed is the mount point for a
22502 mounted file system or the current directory.
22504 [EIO] An I/O error occurred while deleting the directory
22505 entry or deallocating the inode.
22507 [EROFS] The directory entry to be removed resides on a read-
22510 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
22513 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
22514 rmdir(1), chflags(2), mkdir(2), unlink(2)
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'').
22519 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
22520 The r
\brm
\bmd
\bdi
\bir
\br() function call appeared in 4.2BSD.
22523 b
\bbr
\brk
\bk, s
\bsb
\bbr
\brk
\bk - change data segment size
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>
22529 b
\bbr
\brk
\bk(_
\bv_
\bo_
\bi_
\bd _
\b*_
\ba_
\bd_
\bd_
\br);
22531 _
\bv_
\bo_
\bi_
\bd _
\b*
22532 s
\bsb
\bbr
\brk
\bk(_
\bi_
\bn_
\bt _
\bi_
\bn_
\bc_
\br);
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
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).
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
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
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:
22564 [ENOMEM] The limit, as set by setrlimit(2), was exceeded.
22566 [ENOMEM] The maximum possible size of a data segment (compiled
22567 into the system) was exceeded.
22569 [ENOMEM] Insufficient space existed in the swap area to support
22572 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
22573 execve(2), getrlimit(2), mmap(2), end(3), malloc(3)
22575 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
22576 A b
\bbr
\brk
\bk() function call appeared in Version 7 AT&T UNIX.
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).
22584 s
\bsc
\bch
\bhe
\bed
\bd_
\b_y
\byi
\bie
\bel
\bld
\bd - yield the processor
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>
22590 s
\bsc
\bch
\bhe
\bed
\bd_
\b_y
\byi
\bie
\bel
\bld
\bd(_
\bv_
\bo_
\bi_
\bd);
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.
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
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
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.
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.
22613 s
\bse
\bel
\ble
\bec
\bct
\bt, p
\bps
\bse
\bel
\ble
\bec
\bct
\bt - synchronous I/O multiplexing
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>
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);
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);
22626 F
\bFD
\bD_
\b_S
\bSE
\bET
\bT(_
\bf_
\bd, _
\b&_
\bf_
\bd_
\bs_
\be_
\bt);
22628 F
\bFD
\bD_
\b_C
\bCL
\bLR
\bR(_
\bf_
\bd, _
\b&_
\bf_
\bd_
\bs_
\be_
\bt);
22630 F
\bFD
\bD_
\b_I
\bIS
\bSS
\bSE
\bET
\bT(_
\bf_
\bd, _
\b&_
\bf_
\bd_
\bs_
\be_
\bt);
22632 F
\bFD
\bD_
\b_Z
\bZE
\bER
\bRO
\bO(_
\b&_
\bf_
\bd_
\bs_
\be_
\bt);
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.
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.
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().
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.
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()
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.
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
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:
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.
22689 [EBADF] One of the descriptor sets specified an invalid
22692 [EINTR] A signal was delivered before the time limit expired
22693 and before any of the selected descriptors became
22696 [EINVAL] The specified time limit is invalid. One of its
22697 components is negative or too large.
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)
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.
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.
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:
22728 fdsr = calloc(howmany(max+1, NFDBITS), sizeof(fd_mask));
22729 if (fdsr == NULL) {
22734 n = select(max+1, fdsr, NULL, NULL, &tv);
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.
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)).
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.
22760 s
\bse
\bem
\bmc
\bct
\btl
\bl - semaphore control operations
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>
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);
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:
22773 int val; /* value for SETVAL */
22774 struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */
22775 u_short *array; /* array for GETALL & SETALL */
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>:
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 */
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:
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 */
22801 s
\bse
\bem
\bmc
\bct
\btl
\bl() provides the following operations:
22803 GETVAL Return the value of the semaphore.
22805 SETVAL Set the value of the semaphore to _
\ba_
\br_
\bg_
\b._
\bv_
\ba_
\bl.
22807 GETPID Return the pid of the last process that did an operation on
22810 GETNCNT Return the number of processes waiting to acquire the
22813 GETZCNT Return the number of processes waiting for the value of the
22814 semaphore to reach 0.
22816 GETALL Return the values for all the semaphores associated with
22817 _
\bs_
\be_
\bm_
\bi_
\bd.
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.
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).
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
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.
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.
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.
22853 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
22854 s
\bse
\bem
\bmc
\bct
\btl
\bl() will fail if:
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.
22861 [EACCES] The caller has no operation permission for this
22864 [EINVAL] _
\bs_
\be_
\bm_
\bi_
\bd is not a valid message semaphore identifier.
22866 _
\bc_
\bm_
\bd is not a valid command.
22868 [EFAULT] _
\ba_
\br_
\bg_
\b._
\bb_
\bu_
\bf or _
\ba_
\br_
\bg_
\b._
\ba_
\br_
\br_
\ba_
\by specify an invalid address.
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-
22874 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
22875 semget(2), semop(2)
22878 s
\bse
\bem
\bmg
\bge
\bet
\bt - get semaphore set
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>
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);
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
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.
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:
22897 SEM_A alter permission for owner
22898 SEM_R read permission for owner
22900 SEM_A >> 3 alter permission for group
22901 SEM_R >> 3 read permission for group
22903 SEM_A >> 6 alter permission for other
22904 SEM_R >> 6 read permission for other
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:
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
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
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.
22917 +
\b+
\bo
\bo _
\bs_
\be_
\bm_
\b__
\bn_
\bs_
\be_
\bm_
\bs is set to the value of _
\bn_
\bs_
\be_
\bm_
\bs.
22919 +
\b+
\bo
\bo _
\bs_
\be_
\bm_
\b__
\bc_
\bt_
\bi_
\bm_
\be is set to the current time.
22921 +
\b+
\bo
\bo _
\bs_
\be_
\bm_
\b__
\bo_
\bt_
\bi_
\bm_
\be is set to 0.
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.
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.
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.
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.
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.
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.
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.
22947 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
22948 semctl(2), semop(2), ftok(3)
22951 s
\bse
\bem
\bmo
\bop
\bp - semaphore operations
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>
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);
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:
22965 u_short sem_num; /* semaphore # */
22966 short sem_op; /* semaphore operation */
22967 short sem_flg; /* operation flags */
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:
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.
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.
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.
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:
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.
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
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
23005 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
23006 s
\bse
\bem
\bmo
\bop
\bp() will fail if:
23008 [EINVAL] There is no semaphore associated with _
\bs_
\be_
\bm_
\bi_
\bd.
23010 [EIDRM] The semaphore set was removed while the process was
23011 waiting for one of its semaphores to reach a certain
23014 [EACCES] The calling process has no permission to access the
23015 specified semaphore set.
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>.
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.
23024 [ENOSPC] SEM_UNDO was requested, and there is not enough space
23025 left in the kernel to store the undo information.
23027 [EAGAIN] The requested operation can not immediately be
23028 performed, and IPC_NOWAIT was set in _
\bs_
\be_
\bm_
\b__
\bf_
\bl_
\bg.
23030 [EFAULT] _
\bs_
\bo_
\bp_
\bs points to an illegal address.
23032 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
23033 semctl(2), semget(2)
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
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>
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);
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);
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);
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.
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.
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.
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.
23069 The _
\bf_
\bl_
\ba_
\bg_
\bs parameter may include one or more of the following:
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
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.
23083 See recv(2) for a description of the _
\bm_
\bs_
\bg_
\bh_
\bd_
\br structure.
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
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:
23092 [EBADF] An invalid descriptor was specified.
23094 [ENOTSOCK] The argument _
\bs is not a socket.
23096 [EFAULT] An invalid user space address was specified for a
23099 [EMSGSIZE] The socket requires that message be sent atomically,
23100 and the size of the message to be sent made this
23103 [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT
23104 flag is set and the requested operation would block.
23106 [ENOBUFS] The system was unable to allocate an internal buffer.
23107 The operation may succeed when buffers become
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
23115 [EACCES] The SO_BROADCAST option is not set on the socket, and
23116 a broadcast address was given as the destination.
23118 [EHOSTUNREACH] The destination address specified an unreachable host.
23120 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs parameter is invalid.
23122 [EHOSTDOWN] The destination address specified a host that is down.
23124 [ENETDOWN] The destination address specified a network that is
23127 [ECONNREFUSED] The destination host rejected the message (or a
23128 previous one). This error can only be returned by
23131 [ENOPROTOOPT] There was a problem sending the message. This error
23132 can only be returned by connected sockets.
23134 [EDESTADDRREQ] The socket is not connected, and no destination
23135 address was specified.
23137 [EPIPE] The socket is shut down for writing or not longer
23138 connected and the MSG_NOSIGNAL flag is set.
23140 In addition, s
\bse
\ben
\bnd
\bd() and s
\bse
\ben
\bnd
\bdt
\bto
\bo() may return the following error:
23142 [EINVAL] _
\bl_
\be_
\bn was larger than SSIZE_MAX.
23144 s
\bse
\ben
\bnd
\bdt
\bto
\bo() and s
\bse
\ben
\bnd
\bdm
\bms
\bsg
\bg() may return the following errors:
23146 [EAFNOSUPPORT] Addresses in the specified address family cannot be
23147 used with this socket.
23149 [EISCONN] The socket is already connected, and a destination
23150 address was specified.
23152 s
\bse
\ben
\bnd
\bdm
\bms
\bsg
\bg() may return the following errors:
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.
23157 [EMSGSIZE] The _
\bm_
\bs_
\bg_
\b__
\bi_
\bo_
\bv_
\bl_
\be_
\bn member of _
\bm_
\bs_
\bg was less than 0 or larger
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.
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)
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.
23173 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
23174 The s
\bse
\ben
\bnd
\bd() function call appeared in 4.2BSD.
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
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>
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);
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);
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);
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.
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.
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.
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.
23210 The _
\bf_
\bl_
\ba_
\bg_
\bs parameter may include one or more of the following:
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
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.
23224 See recv(2) for a description of the _
\bm_
\bs_
\bg_
\bh_
\bd_
\br structure.
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
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:
23233 [EBADF] An invalid descriptor was specified.
23235 [ENOTSOCK] The argument _
\bs is not a socket.
23237 [EFAULT] An invalid user space address was specified for a
23240 [EMSGSIZE] The socket requires that message be sent atomically,
23241 and the size of the message to be sent made this
23244 [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT
23245 flag is set and the requested operation would block.
23247 [ENOBUFS] The system was unable to allocate an internal buffer.
23248 The operation may succeed when buffers become
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
23256 [EACCES] The SO_BROADCAST option is not set on the socket, and
23257 a broadcast address was given as the destination.
23259 [EHOSTUNREACH] The destination address specified an unreachable host.
23261 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs parameter is invalid.
23263 [EHOSTDOWN] The destination address specified a host that is down.
23265 [ENETDOWN] The destination address specified a network that is
23268 [ECONNREFUSED] The destination host rejected the message (or a
23269 previous one). This error can only be returned by
23272 [ENOPROTOOPT] There was a problem sending the message. This error
23273 can only be returned by connected sockets.
23275 [EDESTADDRREQ] The socket is not connected, and no destination
23276 address was specified.
23278 [EPIPE] The socket is shut down for writing or not longer
23279 connected and the MSG_NOSIGNAL flag is set.
23281 In addition, s
\bse
\ben
\bnd
\bd() and s
\bse
\ben
\bnd
\bdt
\bto
\bo() may return the following error:
23283 [EINVAL] _
\bl_
\be_
\bn was larger than SSIZE_MAX.
23285 s
\bse
\ben
\bnd
\bdt
\bto
\bo() and s
\bse
\ben
\bnd
\bdm
\bms
\bsg
\bg() may return the following errors:
23287 [EAFNOSUPPORT] Addresses in the specified address family cannot be
23288 used with this socket.
23290 [EISCONN] The socket is already connected, and a destination
23291 address was specified.
23293 s
\bse
\ben
\bnd
\bdm
\bms
\bsg
\bg() may return the following errors:
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.
23298 [EMSGSIZE] The _
\bm_
\bs_
\bg_
\b__
\bi_
\bo_
\bv_
\bl_
\be_
\bn member of _
\bm_
\bs_
\bg was less than 0 or larger
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.
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)
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.
23314 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
23315 The s
\bse
\ben
\bnd
\bd() function call appeared in 4.2BSD.
23318 s
\bse
\ben
\bnd
\bds
\bsy
\bys
\bsl
\blo
\bog
\bg - send a message to syslogd
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>
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);
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
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
23337 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
23338 s
\bse
\ben
\bnd
\bds
\bsy
\bys
\bsl
\blo
\bog
\bg() can fail if:
23340 [ENOTCONN] The message cannot be sent, likely because syslogd(8)
23343 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
23344 syslog_r(3), syslogd(8)
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.
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
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>
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);
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);
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);
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.
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.
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.
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.
23383 The _
\bf_
\bl_
\ba_
\bg_
\bs parameter may include one or more of the following:
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
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.
23397 See recv(2) for a description of the _
\bm_
\bs_
\bg_
\bh_
\bd_
\br structure.
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
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:
23406 [EBADF] An invalid descriptor was specified.
23408 [ENOTSOCK] The argument _
\bs is not a socket.
23410 [EFAULT] An invalid user space address was specified for a
23413 [EMSGSIZE] The socket requires that message be sent atomically,
23414 and the size of the message to be sent made this
23417 [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT
23418 flag is set and the requested operation would block.
23420 [ENOBUFS] The system was unable to allocate an internal buffer.
23421 The operation may succeed when buffers become
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
23429 [EACCES] The SO_BROADCAST option is not set on the socket, and
23430 a broadcast address was given as the destination.
23432 [EHOSTUNREACH] The destination address specified an unreachable host.
23434 [EINVAL] The _
\bf_
\bl_
\ba_
\bg_
\bs parameter is invalid.
23436 [EHOSTDOWN] The destination address specified a host that is down.
23438 [ENETDOWN] The destination address specified a network that is
23441 [ECONNREFUSED] The destination host rejected the message (or a
23442 previous one). This error can only be returned by
23445 [ENOPROTOOPT] There was a problem sending the message. This error
23446 can only be returned by connected sockets.
23448 [EDESTADDRREQ] The socket is not connected, and no destination
23449 address was specified.
23451 [EPIPE] The socket is shut down for writing or not longer
23452 connected and the MSG_NOSIGNAL flag is set.
23454 In addition, s
\bse
\ben
\bnd
\bd() and s
\bse
\ben
\bnd
\bdt
\bto
\bo() may return the following error:
23456 [EINVAL] _
\bl_
\be_
\bn was larger than SSIZE_MAX.
23458 s
\bse
\ben
\bnd
\bdt
\bto
\bo() and s
\bse
\ben
\bnd
\bdm
\bms
\bsg
\bg() may return the following errors:
23460 [EAFNOSUPPORT] Addresses in the specified address family cannot be
23461 used with this socket.
23463 [EISCONN] The socket is already connected, and a destination
23464 address was specified.
23466 s
\bse
\ben
\bnd
\bdm
\bms
\bsg
\bg() may return the following errors:
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.
23471 [EMSGSIZE] The _
\bm_
\bs_
\bg_
\b__
\bi_
\bo_
\bv_
\bl_
\be_
\bn member of _
\bm_
\bs_
\bg was less than 0 or larger
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.
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)
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.
23487 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
23488 The s
\bse
\ben
\bnd
\bd() function call appeared in 4.2BSD.
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
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>
23497 s
\bse
\bet
\btu
\bui
\bid
\bd(_
\bu_
\bi_
\bd_
\b__
\bt _
\bu_
\bi_
\bd);
23500 s
\bse
\bet
\bte
\beu
\bui
\bid
\bd(_
\bu_
\bi_
\bd_
\b__
\bt _
\be_
\bu_
\bi_
\bd);
23503 s
\bse
\bet
\btg
\bgi
\bid
\bd(_
\bg_
\bi_
\bd_
\b__
\bt _
\bg_
\bi_
\bd);
23506 s
\bse
\bet
\bte
\beg
\bgi
\bid
\bd(_
\bg_
\bi_
\bd_
\b__
\bt _
\be_
\bg_
\bi_
\bd);
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.
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.
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.
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.
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:
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
23544 s
\bse
\bet
\btg
\bgi
\bid
\bd() and s
\bse
\bet
\bte
\beg
\bgi
\bid
\bd() will succeed unless:
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
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)
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'').
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.
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
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>
23569 s
\bse
\bet
\btu
\bui
\bid
\bd(_
\bu_
\bi_
\bd_
\b__
\bt _
\bu_
\bi_
\bd);
23572 s
\bse
\bet
\bte
\beu
\bui
\bid
\bd(_
\bu_
\bi_
\bd_
\b__
\bt _
\be_
\bu_
\bi_
\bd);
23575 s
\bse
\bet
\btg
\bgi
\bid
\bd(_
\bg_
\bi_
\bd_
\b__
\bt _
\bg_
\bi_
\bd);
23578 s
\bse
\bet
\bte
\beg
\bgi
\bid
\bd(_
\bg_
\bi_
\bd_
\b__
\bt _
\be_
\bg_
\bi_
\bd);
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.
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.
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.
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.
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:
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
23616 s
\bse
\bet
\btg
\bgi
\bid
\bd() and s
\bse
\bet
\bte
\beg
\bgi
\bid
\bd() will succeed unless:
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
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)
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'').
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.
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
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>
23641 s
\bse
\bet
\btu
\bui
\bid
\bd(_
\bu_
\bi_
\bd_
\b__
\bt _
\bu_
\bi_
\bd);
23644 s
\bse
\bet
\bte
\beu
\bui
\bid
\bd(_
\bu_
\bi_
\bd_
\b__
\bt _
\be_
\bu_
\bi_
\bd);
23647 s
\bse
\bet
\btg
\bgi
\bid
\bd(_
\bg_
\bi_
\bd_
\b__
\bt _
\bg_
\bi_
\bd);
23650 s
\bse
\bet
\bte
\beg
\bgi
\bid
\bd(_
\bg_
\bi_
\bd_
\b__
\bt _
\be_
\bg_
\bi_
\bd);
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.
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.
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.
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.
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:
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
23688 s
\bse
\bet
\btg
\bgi
\bid
\bd() and s
\bse
\bet
\bte
\beg
\bgi
\bid
\bd() will succeed unless:
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
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)
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'').
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.
23707 s
\bse
\bet
\btg
\bgr
\bro
\bou
\bup
\bps
\bs - set group access list
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>
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);
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}.
23721 Only the superuser may set new groups.
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
23728 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
23729 The s
\bse
\bet
\btg
\bgr
\bro
\bou
\bup
\bps
\bs() call will fail if:
23731 [EINVAL] The value of _
\bn_
\bg_
\br_
\bo_
\bu_
\bp_
\bs is greater than {NGROUPS_MAX}.
23733 [EPERM] The caller is not the superuser.
23735 [EFAULT] The address specified for _
\bg_
\bi_
\bd_
\bs_
\be_
\bt is outside the
23736 process address space.
23738 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
23739 getgroups(2), setgid(2), setregid(2), initgroups(3)
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.
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
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>
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
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);
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);
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*);
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*);
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);
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);
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);
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).
23783 A timer value is defined by the _
\bi_
\bt_
\bi_
\bm_
\be_
\br_
\bv_
\ba_
\bl structure:
23786 struct timeval it_interval; /* timer interval */
23787 struct timeval it_value; /* current value */
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).
23796 Time values smaller than the resolution of the system clock are rounded
23797 up to this resolution (typically 10 milliseconds).
23799 The ITIMER_REAL timer decrements in real time. A SIGALRM signal is
23800 delivered when this timer expires.
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
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.
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>.
23817 t
\bti
\bim
\bme
\ber
\brc
\bcl
\ble
\bea
\bar
\br(_
\ba) sets the time value in _
\ba to zero.
23819 t
\bti
\bim
\bme
\ber
\bri
\bis
\bss
\bse
\bet
\bt(_
\ba) tests if the time value in _
\ba is non-zero.
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 > .
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.
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.
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
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:
23836 [EFAULT] The _
\bv_
\ba_
\bl_
\bu_
\be parameter specified a bad address.
23838 [EINVAL] An unrecognized value for _
\bw_
\bh_
\bi_
\bc_
\bh was specified.
23840 In addition, s
\bse
\bet
\bti
\bit
\bti
\bim
\bme
\ber
\br() may return the following error:
23842 [EINVAL] _
\bv_
\ba_
\bl_
\bu_
\be or _
\bo_
\bv_
\ba_
\bl_
\bu_
\be specified a time that was too large to
23845 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
23846 clock_gettime(2), gettimeofday(2), poll(2), select(2), sigaction(2)
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
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.
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
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>
23861 _
\bc_
\bh_
\ba_
\br _
\b*
23862 g
\bge
\bet
\btl
\blo
\bog
\bgi
\bin
\bn(_
\bv_
\bo_
\bi_
\bd);
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);
23868 s
\bse
\bet
\btl
\blo
\bog
\bgi
\bin
\bn(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bn_
\ba_
\bm_
\be);
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.)
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).
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
23891 _
\bN_
\bO_
\bT_
\bE: There is only one login name per session.
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.
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.
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.
23907 This is different from traditional UNIX privilege inheritance and as such
23908 can be counter-intuitive.
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.
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.
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:
23925 [EFAULT] The _
\bn_
\ba_
\bm_
\be parameter points to an invalid address.
23927 In addition, g
\bge
\bet
\btl
\blo
\bog
\bgi
\bin
\bn_
\b_r
\br() may return the following error:
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.
23932 s
\bse
\bet
\btl
\blo
\bog
\bgi
\bin
\bn() may return the following errors:
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.
23938 [EPERM] The caller tried to set the login name and was not the
23941 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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.
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.
23960 s
\bse
\bet
\btp
\bpg
\bgi
\bid
\bd, s
\bse
\bet
\btp
\bpg
\bgr
\brp
\bp - set process group
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>
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);
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);
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
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
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:
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
23990 [EINVAL] The value of the _
\bp_
\bg_
\br_
\bp argument is less than zero.
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.
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.
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.
24005 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24006 getpgrp(2), setsid(2)
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.
24012 The s
\bse
\bet
\btp
\bpg
\bgi
\bid
\bd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1'').
24015 s
\bse
\bet
\btp
\bpg
\bgi
\bid
\bd, s
\bse
\bet
\btp
\bpg
\bgr
\brp
\bp - set process group
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>
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);
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);
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
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
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:
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
24045 [EINVAL] The value of the _
\bp_
\bg_
\br_
\bp argument is less than zero.
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.
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.
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.
24060 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24061 getpgrp(2), setsid(2)
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.
24067 The s
\bse
\bet
\btp
\bpg
\bgi
\bid
\bd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1'').
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
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>
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);
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);
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.
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.
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.
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:
24107 [ESRCH] No process was located using the _
\bw_
\bh_
\bi_
\bc_
\bh and _
\bw_
\bh_
\bo values
24110 [EINVAL] _
\bw_
\bh_
\bi_
\bc_
\bh was not one of PRIO_PROCESS, PRIO_PGRP, or
24113 In addition, s
\bse
\bet
\btp
\bpr
\bri
\bio
\bor
\bri
\bit
\bty
\by() will fail if:
24115 [EPERM] A process was located, but neither its effective nor
24116 real user ID matched the effective user ID of the
24119 [EACCES] A non-superuser attempted to lower a process priority.
24121 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24122 nice(1), fork(2), renice(8)
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'').
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.
24134 s
\bse
\bet
\btr
\bre
\beg
\bgi
\bid
\bd - set real and effective group IDs
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>
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);
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.
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
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.
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.
24161 When setting the real and effective group IDs to the same value, the
24162 setgid(2) function is preferred.
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
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.
24174 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24175 getgid(2), setegid(2), setgid(2), setresgid(2), setreuid(2)
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.
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.
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
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>
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);
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);
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);
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);
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.
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
24217 Passing -1 as an argument causes the corresponding value to remain
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.
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
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
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
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)
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.
24246 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
24247 These functions first appeared in HP-UX.
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
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>
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);
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);
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);
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);
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.
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
24278 Passing -1 as an argument causes the corresponding value to remain
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.
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
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
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
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)
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.
24307 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
24308 These functions first appeared in HP-UX.
24311 s
\bse
\bet
\btr
\bre
\beu
\bui
\bid
\bd - set real and effective user IDs
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>
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);
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.
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
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.
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.
24338 When setting the real and effective user IDs to the same value, the
24339 setuid(2) function is preferred.
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
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.
24351 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24352 getuid(2), seteuid(2), setregid(2), setresuid(2), setuid(2)
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.
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.
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
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>
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);
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);
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.
24382 The _
\br_
\be_
\bs_
\bo_
\bu_
\br_
\bc_
\be parameter is one of the following:
24384 RLIMIT_CORE The largest size (in bytes) _
\bc_
\bo_
\br_
\be file that may be
24387 RLIMIT_CPU The maximum amount of CPU time (in seconds) to be used by
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).
24394 RLIMIT_FSIZE The largest size (in bytes) file that may be created.
24396 RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into
24397 memory using the mlock(2) function.
24399 RLIMIT_NOFILE The maximum number of open files for this process.
24401 RLIMIT_NPROC The maximum number of simultaneous processes for this
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
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.
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,
24425 rlim_t rlim_cur; /* current (soft) limit */
24426 rlim_t rlim_max; /* hard limit */
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.
24433 An ``infinite'' value for a limit is defined as RLIM_INFINITY.
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().
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.
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.
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
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
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:
24466 [EFAULT] The address specified for _
\br_
\bl_
\bp is invalid.
24468 [EINVAL] An unrecognized value for _
\br_
\be_
\bs_
\bo_
\bu_
\br_
\bc_
\be was specified.
24470 In addition, s
\bse
\bet
\btr
\brl
\bli
\bim
\bmi
\bit
\bt() may return the following errors:
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.
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.
24477 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24478 csh(1), sh(1), quotactl(2), sigaction(2), sigaltstack(2), sysctl(3)
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
24484 The RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS resources are non-
24485 standard extensions.
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.
24491 The RLIMIT_AS resource is missing.
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
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>
24502 g
\bge
\bet
\btr
\brt
\bta
\bab
\bbl
\ble
\be(_
\bv_
\bo_
\bi_
\bd);
24505 s
\bse
\bet
\btr
\brt
\bta
\bab
\bbl
\ble
\be(_
\bi_
\bn_
\bt _
\br_
\bt_
\ba_
\bb_
\bl_
\be_
\bi_
\bd);
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.
24511 Only the superuser is allowed to change the process routing table if it
24512 is already set to a non-zero value.
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
24519 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
24520 The call succeeds unless:
24522 [EINVAL] The value of the _
\br_
\bt_
\ba_
\bb_
\bl_
\be_
\bi_
\bd argument is not a valid
24525 [EPERM] The user is not the superuser and the routing table of
24526 the calling process is already set to a non-zero
24529 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24530 getsockopt(2), route(8)
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.
24536 s
\bse
\bet
\bts
\bsi
\bid
\bd - create session and set process group ID
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>
24541 _
\bp_
\bi_
\bd_
\b__
\bt
24542 s
\bse
\bet
\bts
\bsi
\bid
\bd(_
\bv_
\bo_
\bi_
\bd);
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.
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.
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:
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
24563 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24564 getsid(2), setpgid(2), tcgetpgrp(3), tcsetpgrp(3)
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.
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
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>
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);
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);
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.
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).
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.
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.
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>.
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().
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)
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.
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.
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.
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:
24681 pass out inet from 192.168.0.10 divert-reply
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.
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.
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.
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:
24732 cmsg_len = CMSG_LEN(sizeof(struct timeval))
24733 cmsg_level = SOL_SOCKET
24734 cmsg_type = SCM_TIMESTAMP
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
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).
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.
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.
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
24784 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
24785 The call succeeds unless:
24787 [EBADF] The argument _
\bs is not a valid descriptor.
24789 [ENOTSOCK] The argument _
\bs is a file, not a socket.
24791 [ENOPROTOOPT] The option is unknown at the level indicated.
24793 [EOPNOTSUPP] The option is unsupported.
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.
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)
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'').
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.
24812 Several of the socket options should be handled at lower levels of the
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
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>
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);
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);
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.
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.
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:
24842 time_t tv_sec; /* seconds since Jan. 1, 1970 */
24843 suseconds_t tv_usec; /* and microseconds */
24847 int tz_minuteswest; /* of Greenwich */
24848 int tz_dsttime; /* type of dst correction to apply */
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
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
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
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:
24871 [EFAULT] An argument address referenced invalid memory.
24873 In addition, s
\bse
\bet
\btt
\bti
\bim
\bme
\beo
\bof
\bfd
\bda
\bay
\by() may return the following error:
24875 [EPERM] A user other than the superuser attempted to set the
24878 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
24879 date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3)
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
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.
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.
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
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>
24906 s
\bse
\bet
\btu
\bui
\bid
\bd(_
\bu_
\bi_
\bd_
\b__
\bt _
\bu_
\bi_
\bd);
24909 s
\bse
\bet
\bte
\beu
\bui
\bid
\bd(_
\bu_
\bi_
\bd_
\b__
\bt _
\be_
\bu_
\bi_
\bd);
24912 s
\bse
\bet
\btg
\bgi
\bid
\bd(_
\bg_
\bi_
\bd_
\b__
\bt _
\bg_
\bi_
\bd);
24915 s
\bse
\bet
\bte
\beg
\bgi
\bid
\bd(_
\bg_
\bi_
\bd_
\b__
\bt _
\be_
\bg_
\bi_
\bd);
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.
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.
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.
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.
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:
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
24953 s
\bse
\bet
\btg
\bgi
\bid
\bd() and s
\bse
\bet
\bte
\beg
\bgi
\bid
\bd() will succeed unless:
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
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)
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'').
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.
24972 s
\bsh
\bhm
\bma
\bat
\bt, s
\bsh
\bhm
\bmd
\bdt
\bt - map/unmap shared memory
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>
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);
24981 s
\bsh
\bhm
\bmd
\bdt
\bt(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bv_
\bo_
\bi_
\bd _
\b*_
\bs_
\bh_
\bm_
\ba_
\bd_
\bd_
\br);
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>).
24993 A shared memory segment can be mapped read-only by specifying the
24994 SHM_RDONLY flag in _
\bs_
\bh_
\bm_
\bf_
\bl_
\bg.
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
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.
25008 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
25009 s
\bsh
\bhm
\bma
\bat
\bt() will fail if:
25011 [EACCES] The calling process has no permission to access this
25012 shared memory segment.
25014 [ENOMEM] There is not enough available data space for the
25015 calling process to map the shared memory segment.
25017 [EINVAL] _
\bs_
\bh_
\bm_
\bi_
\bd is not a valid shared memory identifier.
25019 _
\bs_
\bh_
\bm_
\ba_
\bd_
\bd_
\br specifies an illegal address.
25021 [EMFILE] The number of shared memory segments has reached the
25024 s
\bsh
\bhm
\bmd
\bdt
\bt() will fail if:
25026 [EINVAL] _
\bs_
\bh_
\bm_
\ba_
\bd_
\bd_
\br is not the start address of a mapped shared
25029 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25030 ipcrm(1), ipcs(1), mmap(2), shmctl(2), shmget(2)
25033 s
\bsh
\bhm
\bmc
\bct
\btl
\bl - shared memory control operations
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>
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);
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.
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().
25049 This structure is defined as follows in <_
\bs_
\by_
\bs_
\b/_
\bs_
\bh_
\bm_
\b._
\bh>:
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 */
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:
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 */
25076 The operation to be performed by s
\bsh
\bhm
\bmc
\bct
\btl
\bl() is specified in _
\bc_
\bm_
\bd and is one
25079 IPC_STAT Gather information about the shared memory segment and place
25080 it in the structure pointed to by _
\bb_
\bu_
\bf.
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.
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.
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.
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
25108 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
25109 s
\bsh
\bhm
\bmc
\bct
\btl
\bl() will fail if:
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
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.
25120 [EACCES] The command is IPC_STAT and the caller has no read
25121 permission for this shared memory segment.
25123 [EINVAL] _
\bs_
\bh_
\bm_
\bi_
\bd is not a valid shared memory segment identifier.
25125 _
\bc_
\bm_
\bd is not a valid command.
25127 [EFAULT] _
\bb_
\bu_
\bf specifies an invalid address.
25129 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25130 shmat(2), shmget(2)
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.
25138 s
\bsh
\bhm
\bma
\bat
\bt, s
\bsh
\bhm
\bmd
\bdt
\bt - map/unmap shared memory
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>
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);
25147 s
\bsh
\bhm
\bmd
\bdt
\bt(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bv_
\bo_
\bi_
\bd _
\b*_
\bs_
\bh_
\bm_
\ba_
\bd_
\bd_
\br);
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>).
25159 A shared memory segment can be mapped read-only by specifying the
25160 SHM_RDONLY flag in _
\bs_
\bh_
\bm_
\bf_
\bl_
\bg.
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
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.
25174 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
25175 s
\bsh
\bhm
\bma
\bat
\bt() will fail if:
25177 [EACCES] The calling process has no permission to access this
25178 shared memory segment.
25180 [ENOMEM] There is not enough available data space for the
25181 calling process to map the shared memory segment.
25183 [EINVAL] _
\bs_
\bh_
\bm_
\bi_
\bd is not a valid shared memory identifier.
25185 _
\bs_
\bh_
\bm_
\ba_
\bd_
\bd_
\br specifies an illegal address.
25187 [EMFILE] The number of shared memory segments has reached the
25190 s
\bsh
\bhm
\bmd
\bdt
\bt() will fail if:
25192 [EINVAL] _
\bs_
\bh_
\bm_
\ba_
\bd_
\bd_
\br is not the start address of a mapped shared
25195 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25196 ipcrm(1), ipcs(1), mmap(2), shmctl(2), shmget(2)
25199 s
\bsh
\bhm
\bmg
\bge
\bet
\bt - get shared memory area identifier
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>
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);
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
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.
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
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
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
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.
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.
25229 +
\b+
\bo
\bo _
\bs_
\bh_
\bm_
\b__
\bc_
\bt_
\bi_
\bm_
\be is set to the current time.
25231 +
\b+
\bo
\bo _
\bs_
\bh_
\bm_
\b__
\bs_
\be_
\bg_
\bs_
\bz is set to the value of _
\bs_
\bi_
\bz_
\be.
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.
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.
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.
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.
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.
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.
25255 [ENOMEM] There is not enough memory left to create a shared
25256 memory segment of the requested size.
25258 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25259 ipcrm(1), ipcs(1), mmap(2), shmat(2), shmctl(2), ftok(3)
25262 s
\bsh
\bhu
\but
\btd
\bdo
\bow
\bwn
\bn - disable sends or receives on a socket
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>
25268 s
\bsh
\bhu
\but
\btd
\bdo
\bow
\bwn
\bn(_
\bi_
\bn_
\bt _
\bs, _
\bi_
\bn_
\bt _
\bh_
\bo_
\bw);
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.
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.
25276 The _
\bh_
\bo_
\bw argument specifies the type of shutdown. Possible values are:
25278 SHUT_RD Further receives will be disallowed.
25280 SHUT_WR Further sends will be disallowed. This may cause
25281 actions specific to the protocol family of the socket
25284 SHUT_RDWR Further sends and receives will be disallowed.
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:
25289 DOMAIN TYPE PROTOCOL RETURN VALUE AND ACTION
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
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
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
25308 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
25309 The s
\bsh
\bhu
\but
\btd
\bdo
\bow
\bwn
\bn() system call fails if:
25311 [EBADF] The _
\bs argument is not a valid file descriptor.
25313 [EINVAL] The _
\bh_
\bo_
\bw argument is invalid.
25315 [ENOTCONN] The _
\bs argument specifies a SOCK_STREAM socket which is
25318 [ENOTSOCK] The _
\bs argument does not refer to a socket.
25320 [EOPNOTSUPP] The socket associated with the file descriptor _
\bs does
25321 not support this operation.
25323 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25324 connect(2), socket(2), inet(4), inet6(4)
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'').
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
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()
25340 s
\bsi
\big
\bga
\bac
\bct
\bti
\bio
\bon
\bn - software signal facilities
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>
25346 union { /* signal handler */
25347 void (*__sa_handler)(int);
25348 void (*__sa_sigaction)(int, siginfo_t *, void *);
25350 sigset_t sa_mask; /* signal mask to apply */
25351 int sa_flags; /* see signal options below */
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
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);
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.
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.
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.
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.
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
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.
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:
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.
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.
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).
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.
25456 SA_RESETHAND If this bit is set, the handler is reset back to
25457 SIG_DFL at the moment the signal is delivered.
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.
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).
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.
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.
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>:
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
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
25515 SIGTTOU stop process background write attempted to control
25517 SIGIO discard signal I/O is possible on a descriptor (see
25519 SIGXCPU terminate process CPU time limit exceeded (see
25521 SIGXFSZ terminate process file size limit exceeded (see
25523 SIGVTALRM terminate process virtual time alarm (see setitimer(2))
25524 SIGPROF terminate process profiling timer alarm (see
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
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
25537 E
\bEX
\bXA
\bAM
\bMP
\bPL
\bLE
\bES
\bS
25538 The handler routine can be declared:
25543 If the SA_SIGINFO option is enabled, the canonical way to declare it is:
25546 handler(int sig, siginfo_t *sip, struct sigcontext *scp)
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.
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:
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.
25564 [EINVAL] _
\bs_
\bi_
\bg is not a valid signal number.
25566 [EINVAL] An attempt is made to ignore or supply a handler for
25567 SIGKILL or SIGSTOP.
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)
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'').
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.
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:
25590 Standard Interfaces:
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.
25615 Extension Interfaces:
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().
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.
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:
25635 int save_errno = errno;
25638 errno = save_errno;
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
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
25653 s
\bsi
\big
\bga
\bal
\blt
\bts
\bst
\bta
\bac
\bck
\bk - set and/or get signal stack context
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>
25658 typedef struct sigaltstack {
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);
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.
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.
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.
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
25693 if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
25695 sigstk.ss_size = SIGSTKSZ;
25696 sigstk.ss_flags = 0;
25697 if (sigaltstack(&sigstk, 0) == -1)
25698 perror("sigaltstack");
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
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.
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
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.
25723 [EFAULT] Either _
\bs_
\bs or _
\bo_
\bs_
\bs points to memory that is not a valid part of
25724 the process address space.
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.
25729 [ENOMEM] Size of alternate stack area is less than or equal to
25732 [EPERM] An attempt was made to disable an active stack.
25734 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25735 sigaction(2), setjmp(3)
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'').
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
25745 s
\bsi
\big
\bgp
\bpe
\ben
\bnd
\bdi
\bin
\bng
\bg - get pending signals
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>
25751 s
\bsi
\big
\bgp
\bpe
\ben
\bnd
\bdi
\bin
\bng
\bg(_
\bs_
\bi_
\bg_
\bs_
\be_
\bt_
\b__
\bt _
\b*_
\bs_
\be_
\bt);
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).
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
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.
25767 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25768 sigaction(2), sigprocmask(2), sigsetops(3)
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'').
25774 s
\bsi
\big
\bgp
\bpr
\bro
\boc
\bcm
\bma
\bas
\bsk
\bk - manipulate current signal mask
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>
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);
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.
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:
25790 SIG_BLOCK The new mask is the union of the current mask and the
25791 specified _
\bs_
\be_
\bt.
25793 SIG_UNBLOCK The new mask is the intersection of the current mask and the
25794 complement of the specified _
\bs_
\be_
\bt.
25796 SIG_SETMASK The current mask is replaced by the specified _
\bs_
\be_
\bt.
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
25803 The system quietly disallows SIGKILL or SIGSTOP to be blocked.
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
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:
25814 [EINVAL] _
\bh_
\bo_
\bw has a value other than those listed here.
25816 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25817 kill(2), sigaction(2), sigsuspend(2), sigsetops(3)
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'').
25824 s
\bsi
\big
\bgr
\bre
\bet
\btu
\bur
\brn
\bn - return from signal
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>
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);
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
25842 Note that sigcontext contains machine dependent information.
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.
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.
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.
25856 [EFAULT] _
\bs_
\bc_
\bp points to memory that is not a valid part of the
25857 process address space.
25859 [EINVAL] The process status longword is invalid or would
25860 improperly raise the privilege level of the process.
25862 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25863 sigaction(2), setjmp(3)
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.
25869 s
\bsi
\big
\bgs
\bsu
\bus
\bsp
\bpe
\ben
\bnd
\bd - atomically change the signal mask and wait for interrupt
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>
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);
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.
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).
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.
25894 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
25895 sigaction(2), sigprocmask(2), sigsetops(3)
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
25902 s
\bso
\boc
\bck
\bke
\bet
\bt - create an endpoint for communication
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>
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);
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.
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:
25918 AF_UNIX UNIX internal protocols
25919 AF_INET ARPA Internet protocols
25920 AF_INET6 IPv6 (Internet Protocol version 6) protocols
25922 The socket has the indicated _
\bt_
\by_
\bp_
\be, which specifies the semantics of
25923 communication. Currently defined types are:
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
25942 Any combination of the following flags may additionally be used in the
25943 _
\bt_
\by_
\bp_
\be argument:
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.
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.
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).
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
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
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
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.
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.
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.
26001 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
26002 The s
\bso
\boc
\bck
\bke
\bet
\bt() call fails if:
26004 [EAFNOSUPPORT] The specified address family is not supported on this
26007 [EPROTONOSUPPORT] The protocol type or the specified protocol is not
26008 supported within this domain.
26010 [EPROTOTYPE] The combination of the specified protocol and type is
26013 [EMFILE] The per-process descriptor table is full.
26015 [ENFILE] The system file table is full.
26017 [ENOBUFS] Insufficient resources were available in the system to
26018 perform the operation.
26020 [EACCES] Permission to create a socket of the specified type
26021 and/or protocol is denied.
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)
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.
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.
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'').
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.
26042 s
\bso
\boc
\bck
\bke
\bet
\btp
\bpa
\bai
\bir
\br - create a pair of connected sockets
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>
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]);
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.
26056 Any combination of the following flags may additionally be used in the
26057 _
\bt_
\by_
\bp_
\be argument:
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.
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
26067 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
26068 The call succeeds unless:
26070 [EAFNOSUPPORT] The specified address family is not supported on this
26073 [EPROTONOSUPPORT] The specified protocol is not supported on this
26076 [EOPNOTSUPP] The specified protocol does not support creation of
26079 [EPROTOTYPE] The combination of the specified protocol and type is
26082 [EMFILE] The per-process descriptor table is full.
26084 [ENFILE] The system file table is full.
26086 [ENOBUFS] Insufficient resources were available in the system to
26087 perform the operation.
26089 [EFAULT] The address _
\bs_
\bv does not specify a valid part of the
26090 process address space.
26092 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
26093 pipe(2), read(2), socket(2), write(2)
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'').
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.
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.
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
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>
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);
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);
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);
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>
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);
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.
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.
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.
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.
26148 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
26151 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the status
26152 of the symbolic link is returned.
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.
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.
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 */
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
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.
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.
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.
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.
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
26208 The size-related fields of the struct stat are as follows:
26210 _
\bs_
\bt_
\b__
\bb_
\bl_
\bk_
\bs_
\bi_
\bz_
\be The optimal I/O block size for the file.
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.
26216 The status information word _
\bs_
\bt_
\b__
\bm_
\bo_
\bd_
\be has the following bits:
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 */
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.
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 */
26253 For a list of access modes, see <_
\bs_
\by_
\bs_
\b/_
\bs_
\bt_
\ba_
\bt_
\b._
\bh>, access(2), and chmod(2).
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
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:
26263 [ENOTDIR] A component of the path prefix is not a directory.
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.
26269 [ENOENT] A component of _
\bn_
\ba_
\bm_
\be does not exist or _
\bn_
\ba_
\bm_
\be is the
26272 [EACCES] Search permission is denied for a component of the
26275 [ELOOP] Too many symbolic links were encountered in
26276 translating the pathname.
26278 [EFAULT] _
\bs_
\bb or _
\bn_
\ba_
\bm_
\be points to an invalid address.
26280 [EIO] An I/O error occurred while reading from or writing to
26283 Additionally, f
\bfs
\bst
\bta
\bat
\bta
\bat
\bt() will fail if:
26285 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
26286 AT_SYMLINK_NOFOLLOW.
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
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.
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.
26300 f
\bfs
\bst
\bta
\bat
\bt() will fail if:
26302 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
26304 [EFAULT] _
\bs_
\bb points to an invalid address.
26306 [EIO] An I/O error occurred while reading from the file
26309 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
26310 chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7)
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.
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'').
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.
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.
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.
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.
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
26341 s
\bst
\bta
\bat
\btf
\bfs
\bs, f
\bfs
\bst
\bta
\bat
\btf
\bfs
\bs - get file system statistics
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>
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);
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);
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:
26358 typedef struct { int32_t val[2]; } fsid_t;
26360 #define MFSNAMELEN 16 /* length of fs type name, including nul */
26361 #define MNAMELEN 90 /* length of buffer for returned name */
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 */
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 */
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 */
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 */
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 */
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 */
26394 f
\bfs
\bst
\bta
\bat
\btf
\bfs
\bs() returns the same information about an open file referenced by
26395 descriptor _
\bf_
\bd.
26397 Note that _
\bf_
\b__
\bf_
\bs_
\bi_
\bd will be empty unless the user is the superuser.
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
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:
26407 [ENOTDIR] A component of the path prefix of _
\bp_
\ba_
\bt_
\bh is not a
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.
26414 [ENOENT] The file referred to by _
\bp_
\ba_
\bt_
\bh does not exist.
26416 [EACCES] Search permission is denied for a component of the
26417 path prefix of _
\bp_
\ba_
\bt_
\bh.
26419 [ELOOP] Too many symbolic links were encountered in
26420 translating _
\bp_
\ba_
\bt_
\bh.
26422 [EFAULT] _
\bb_
\bu_
\bf or _
\bp_
\ba_
\bt_
\bh points to an invalid address.
26424 [EIO] An I/O error occurred while reading from or writing to
26427 f
\bfs
\bst
\bta
\bat
\btf
\bfs
\bs() fails if one or more of the following are true:
26429 [EBADF] _
\bf_
\bd is not a valid open file descriptor.
26431 [EFAULT] _
\bb_
\bu_
\bf points to an invalid address.
26433 [EIO] An I/O error occurred while reading from or writing to
26436 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
26437 df(1), getfsstat(2), mount(2), stat(2)
26439 H
\bHI
\bIS
\bST
\bTO
\bOR
\bRY
\bY
26440 The s
\bst
\bta
\bat
\btf
\bfs
\bs() function first appeared in 4.4BSD.
26443 s
\bsw
\bwa
\bap
\bpc
\bct
\btl
\bl - modify swap configuration
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>
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);
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.
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.
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.
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:
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 */
26477 The flags are defined as
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
26484 All but SWAP_NSWAP and SWAP_STATS require superuser privileges.
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.
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.
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.
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
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.
26508 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
26509 s
\bsw
\bwa
\bap
\bpc
\bct
\btl
\bl() succeeds unless:
26511 [ENOTDIR] A component of the path prefix is not a directory.
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.
26517 [ENOENT] The named device does not exist. For the SWAP_CTL
26518 command, the named device is not currently enabled for
26521 [EACCES] Search permission is denied for a component of the
26524 [ELOOP] Too many symbolic links were encountered in
26525 translating the pathname.
26527 [EPERM] The caller is not the superuser.
26529 [EBUSY] The device specified by _
\ba_
\br_
\bg has already been made
26530 available for swapping.
26532 [EINVAL] The device configured by _
\ba_
\br_
\bg has no associated size,
26533 or the _
\bc_
\bm_
\bd was unknown.
26535 [ENXIO] The major device number of _
\ba_
\br_
\bg is out of range (this
26536 indicates no device driver exists for the associated
26539 [EIO] An I/O error occurred while opening the swap device.
26541 [EFAULT] _
\ba_
\br_
\bg points outside the process' allocated address
26544 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
26545 config(8), swapctl(8)
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>.
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>.
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
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>
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);
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>
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);
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.
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.
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().
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
26593 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
26594 The symbolic link succeeds unless:
26596 [ENOTDIR] A component of the _
\bn_
\ba_
\bm_
\be_
\b2 prefix is not a directory.
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.
26602 [ENOENT] The named file does not exist.
26604 [EACCES] A component of the _
\bn_
\ba_
\bm_
\be_
\b2 path prefix denies search
26607 [ELOOP] Too many symbolic links were encountered in
26608 translating the pathname.
26610 [EEXIST] _
\bn_
\ba_
\bm_
\be_
\b2 already exists.
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.
26616 [EROFS] The file _
\bn_
\ba_
\bm_
\be_
\b2 would reside on a read-only file
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
26624 [ENOSPC] The new symbolic link cannot be created because there
26625 is no space left on the file system that will contain
26628 [ENOSPC] There are no free inodes on the file system on which
26629 the symbolic link is being created.
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.
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.
26640 [EDQUOT] The user's quota of inodes on the file system on which
26641 the symbolic link is being created has been exhausted.
26643 [EIO] An I/O error occurred while making the directory entry
26644 or allocating the inode.
26646 [EFAULT] _
\bn_
\ba_
\bm_
\be_
\b1 or _
\bn_
\ba_
\bm_
\be_
\b2 points outside the process's allocated
26649 Additionally, s
\bsy
\bym
\bml
\bli
\bin
\bnk
\bka
\bat
\bt() will fail if:
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
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.
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.
26663 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
26664 ln(1), link(2), readlink(2), unlink(2), symlink(7)
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
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.
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
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>
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);
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>
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);
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.
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.
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().
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
26709 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
26710 The symbolic link succeeds unless:
26712 [ENOTDIR] A component of the _
\bn_
\ba_
\bm_
\be_
\b2 prefix is not a directory.
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.
26718 [ENOENT] The named file does not exist.
26720 [EACCES] A component of the _
\bn_
\ba_
\bm_
\be_
\b2 path prefix denies search
26723 [ELOOP] Too many symbolic links were encountered in
26724 translating the pathname.
26726 [EEXIST] _
\bn_
\ba_
\bm_
\be_
\b2 already exists.
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.
26732 [EROFS] The file _
\bn_
\ba_
\bm_
\be_
\b2 would reside on a read-only file
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
26740 [ENOSPC] The new symbolic link cannot be created because there
26741 is no space left on the file system that will contain
26744 [ENOSPC] There are no free inodes on the file system on which
26745 the symbolic link is being created.
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.
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.
26756 [EDQUOT] The user's quota of inodes on the file system on which
26757 the symbolic link is being created has been exhausted.
26759 [EIO] An I/O error occurred while making the directory entry
26760 or allocating the inode.
26762 [EFAULT] _
\bn_
\ba_
\bm_
\be_
\b1 or _
\bn_
\ba_
\bm_
\be_
\b2 points outside the process's allocated
26765 Additionally, s
\bsy
\bym
\bml
\bli
\bin
\bnk
\bka
\bat
\bt() will fail if:
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
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.
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.
26779 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
26780 ln(1), link(2), readlink(2), unlink(2), symlink(7)
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
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.
26791 s
\bsy
\byn
\bnc
\bc - synchronize disk block in-core status with that on disk
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>
26797 s
\bsy
\byn
\bnc
\bc(_
\bv_
\bo_
\bi_
\bd);
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
26807 The function fsync(2) may be used to synchronize individual file
26808 descriptor attributes.
26810 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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'').
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.
26820 s
\bsy
\byn
\bnc
\bc() may return before the buffers are completely flushed.
26823 s
\bsy
\bys
\bsa
\bar
\brc
\bch
\bh - architecture-dependent system call
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>
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);
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>.
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.
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.
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.
26850 s
\bsy
\bys
\bsc
\bca
\bal
\bll
\bl, _
\b__
\b_s
\bsy
\bys
\bsc
\bca
\bal
\bll
\bl - indirect system call
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>
26857 s
\bsy
\bys
\bsc
\bca
\bal
\bll
\bl(_
\bi_
\bn_
\bt _
\bn_
\bu_
\bm_
\bb_
\be_
\br, _
\b._
\b._
\b.);
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.);
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>.
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
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.
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.
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
26888 There is no way to simulate system calls that have multiple return values
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
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>
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);
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);
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.
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
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:
26918 [EINVAL] The _
\bl_
\be_
\bn_
\bg_
\bt_
\bh is a negative value.
26920 [EIO] An I/O error occurred updating the inode.
26922 In addition, t
\btr
\bru
\bun
\bnc
\bca
\bat
\bte
\be() may return the following errors:
26924 [ENOTDIR] A component of the path prefix is not a directory.
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.
26930 [ENOENT] The named file does not exist.
26932 [EACCES] Search permission is denied for a component of the
26935 [EACCES] The named file is not writable by the user.
26937 [ELOOP] Too many symbolic links were encountered in
26938 translating the pathname.
26940 [EISDIR] The named file is a directory.
26942 [EROFS] The named file resides on a read-only file system.
26944 [ETXTBSY] The file is a pure procedure (shared text) file that
26947 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
26950 f
\bft
\btr
\bru
\bun
\bnc
\bca
\bat
\bte
\be() may return the following errors:
26952 [EBADF] The _
\bf_
\bd is not a valid descriptor.
26954 [EINVAL] The _
\bf_
\bd references a socket, not a file.
26956 [EINVAL] The _
\bf_
\bd is not open for writing.
26958 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
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
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.
26969 These calls should be generalized to allow ranges of bytes in a file to
26972 Use of t
\btr
\bru
\bun
\bnc
\bca
\bat
\bte
\be() to extend a file is not portable.
26975 u
\bum
\bma
\bas
\bsk
\bk - set file creation mode mask
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>
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);
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.
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.
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.
26998 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
26999 The u
\bum
\bma
\bas
\bsk
\bk() function is always successful.
27001 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
27002 chmod(2), mkdir(2), mkfifo(2), mknod(2), open(2)
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'').
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.
27011 u
\bun
\bnl
\bli
\bin
\bnk
\bk, u
\bun
\bnl
\bli
\bin
\bnk
\bka
\bat
\bt - remove directory entry
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>
27017 u
\bun
\bnl
\bli
\bin
\bnk
\bk(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bp_
\ba_
\bt_
\bh);
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>
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);
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.
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.
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.
27045 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
27048 AT_REMOVEDIR Remove the directory entry specified by _
\bp_
\ba_
\bt_
\bh as a
27049 directory, not a normal file.
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
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:
27059 [ENOTDIR] A component of the path prefix is not a directory.
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.
27065 [ENOENT] The named file does not exist.
27067 [EACCES] Search permission is denied for a component of the
27070 [EACCES] Write permission is denied on the directory containing
27071 the link to be removed.
27073 [ELOOP] Too many symbolic links were encountered in
27074 translating the pathname.
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.
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.
27085 [EPERM] The named file or the directory containing it has its
27086 immutable or append-only flag set (see chflags(2)).
27088 [EBUSY] The entry to be unlinked is the mount point for a
27089 mounted file system.
27091 [EIO] An I/O error occurred while deleting the directory
27092 entry or deallocating the inode.
27094 [EROFS] The named file resides on a read-only file system.
27096 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
27099 Additionally, u
\bun
\bnl
\bli
\bin
\bnk
\bka
\bat
\bt() will fail if:
27101 [ENOTDIR] The AT_REMOVEDIR flag bit is set and _
\bp_
\ba_
\bt_
\bh does not
27104 [ENOTEMPTY] The AT_REMOVEDIR flag bit is set and the named
27105 directory contains files other than `.' and `..' in
27108 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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
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.
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.
27123 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
27124 rm(1), chflags(2), close(2), link(2), rmdir(2), symlink(7)
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
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.
27135 u
\bun
\bnl
\bli
\bin
\bnk
\bk, u
\bun
\bnl
\bli
\bin
\bnk
\bka
\bat
\bt - remove directory entry
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>
27141 u
\bun
\bnl
\bli
\bin
\bnk
\bk(_
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bp_
\ba_
\bt_
\bh);
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>
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);
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.
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.
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.
27169 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
27172 AT_REMOVEDIR Remove the directory entry specified by _
\bp_
\ba_
\bt_
\bh as a
27173 directory, not a normal file.
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
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:
27183 [ENOTDIR] A component of the path prefix is not a directory.
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.
27189 [ENOENT] The named file does not exist.
27191 [EACCES] Search permission is denied for a component of the
27194 [EACCES] Write permission is denied on the directory containing
27195 the link to be removed.
27197 [ELOOP] Too many symbolic links were encountered in
27198 translating the pathname.
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.
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.
27209 [EPERM] The named file or the directory containing it has its
27210 immutable or append-only flag set (see chflags(2)).
27212 [EBUSY] The entry to be unlinked is the mount point for a
27213 mounted file system.
27215 [EIO] An I/O error occurred while deleting the directory
27216 entry or deallocating the inode.
27218 [EROFS] The named file resides on a read-only file system.
27220 [EFAULT] _
\bp_
\ba_
\bt_
\bh points outside the process's allocated address
27223 Additionally, u
\bun
\bnl
\bli
\bin
\bnk
\bka
\bat
\bt() will fail if:
27225 [ENOTDIR] The AT_REMOVEDIR flag bit is set and _
\bp_
\ba_
\bt_
\bh does not
27228 [ENOTEMPTY] The AT_REMOVEDIR flag bit is set and the named
27229 directory contains files other than `.' and `..' in
27232 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
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
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.
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.
27247 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
27248 rm(1), chflags(2), close(2), link(2), rmdir(2), symlink(7)
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
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.
27259 m
\bmo
\bou
\bun
\bnt
\bt, u
\bun
\bnm
\bmo
\bou
\bun
\bnt
\bt - mount or dismount a filesystem
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>
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);
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);
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.
27280 The following _
\bf_
\bl_
\ba_
\bg_
\bs may be specified to suppress default semantics which
27281 affect filesystem access.
27283 MNT_RDONLY The filesystem should be treated as read-only: even the
27284 superuser may not write to it.
27286 MNT_NOATIME Do not update the access time on files in the filesystem
27287 unless the modification or status change times are also
27290 MNT_NOEXEC Do not allow files to be executed from the filesystem.
27292 MNT_NOSUID Do not honor setuid or setgid bits on files when
27295 MNT_NODEV Do not interpret special files on the filesystem.
27297 MNT_SYNCHRONOUS All I/O to the filesystem should be done synchronously.
27299 MNT_ASYNC All I/O to the filesystem should be done asynchronously.
27301 MNT_SOFTDEP Use soft dependencies. Applies to FFS filesystems only
27302 (see 'softdep' in mount(8)).
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.
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
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 */
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 */
27331 char *fspec; /* block special file to mount */
27332 struct export_args export_info;
27333 /* network export information */
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 */
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 */
27357 * Msdosfs mount options:
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 */
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 */
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 */
27401 * ntfs mount options:
27403 #define NTFS_MFLAG_CASEINS 0x00000001
27404 #define NTFS_MFLAG_ALLNAMES 0x00000002
27408 char *fspec; /* block special device to mount */
27411 The u
\bun
\bnm
\bmo
\bou
\bun
\bnt
\bt() function call disassociates the filesystem from the
27412 specified mount point _
\bd_
\bi_
\br.
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.
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
27424 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
27425 m
\bmo
\bou
\bun
\bnt
\bt() will fail when one of the following occurs:
27427 [EPERM] The caller is not the superuser.
27429 [ENAMETOOLONG] The path name exceeded {MNAMELEN} characters.
27431 [ELOOP] Too many symbolic links were encountered in translating a
27434 [ENOENT] A component of _
\bd_
\bi_
\br does not exist.
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.
27439 [EINVAL] An argument given was invalid.
27441 [EBUSY] Another process currently holds a reference to _
\bd_
\bi_
\br.
27443 [EFAULT] _
\bd_
\bi_
\br points outside the process's allocated address space.
27445 [EOPNOTSUPP] _
\bt_
\by_
\bp_
\be is not supported by the kernel.
27447 The following errors can occur for a ``ufs'' filesystem mount:
27449 [ENODEV] A component of ufs_args _
\bf_
\bs_
\bp_
\be_
\bc does not exist.
27451 [ENOTBLK] _
\bf_
\bs_
\bp_
\be_
\bc is not a block device.
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
27457 [EBUSY] _
\bf_
\bs_
\bp_
\be_
\bc is already mounted.
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.
27462 [ENOMEM] Not enough memory was available to read the cylinder group
27463 information for the filesystem.
27465 [EIO] An I/O error occurred while reading the super block or
27466 cylinder group information.
27468 [EFAULT] _
\bf_
\bs_
\bp_
\be_
\bc points outside the process's allocated address space.
27470 [EROFS] The filesystem was not unmounted cleanly and MNT_FORCE was not
27473 [EROFS] An attempt was made to mount a 4.2BSD filesystem without the
27476 The following errors can occur for an _
\bN_
\bF_
\bS filesystem mount:
27478 [ETIMEDOUT] _
\bN_
\bF_
\bS timed out trying to contact the server.
27480 [EFAULT] Some part of the information described by nfs_args points
27481 outside the process's allocated address space.
27483 The following errors can occur for a _
\bm_
\bf_
\bs filesystem mount:
27485 [EMFILE] No space remains in the mount table.
27487 [EINVAL] The super block for the filesystem had a bad magic number or an
27488 out of range block size.
27490 [ENOMEM] Not enough memory was available to read the cylinder group
27491 information for the filesystem.
27493 [EIO] A paging error occurred while reading the super block or
27494 cylinder group information.
27496 [EFAULT] _
\bN_
\ba_
\bm_
\be points outside the process's allocated address space.
27498 u
\bun
\bnm
\bmo
\bou
\bun
\bnt
\bt() may fail with one of the following errors:
27500 [EPERM] The caller is not the superuser.
27502 [ENOTDIR] A component of the path is not a directory.
27504 [EINVAL] An argument given was invalid.
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.
27510 [ELOOP] Too many symbolic links were encountered in translating
27513 [EINVAL] The requested directory is not in the mount table.
27515 [EBUSY] A process is holding a reference to a file located on the
27518 [EIO] An I/O error occurred while writing cached filesystem
27521 [EFAULT] _
\bd_
\bi_
\br points outside the process's allocated address space.
27523 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
27524 statfs(2), mfs(8), mount(8), umount(8)
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.
27533 Some of the error codes need translation to more obvious messages.
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
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>
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);
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);
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>
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);
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]);
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.
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.
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.
27571 In either case, the inode-change-time of the file is set to the current
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.
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>:
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.
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
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.
27593 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
27596 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the
27597 timestamps of the symbolic link are changed.
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
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:
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
27613 [EFAULT] _
\bf_
\bi_
\bl_
\be or _
\bt_
\bi_
\bm_
\be_
\bs points outside the process's allocated
27616 [EIO] An I/O error occurred while reading or writing the
27619 [ELOOP] Too many symbolic links were encountered in
27620 translating the pathname.
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.
27626 [ENOENT] The named file does not exist.
27628 [ENOTDIR] A component of the path prefix is not a directory.
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.
27634 [EROFS] The file system containing the file is mounted read-
27637 Additionally, u
\but
\bti
\bim
\bme
\ben
\bns
\bsa
\bat
\bt() will fail if:
27639 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
27640 AT_SYMLINK_NOFOLLOW.
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
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.
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.
27654 f
\bfu
\but
\bti
\bim
\bme
\bes
\bs() and f
\bfu
\but
\bti
\bim
\bme
\ben
\bns
\bs() will fail if:
27656 [EBADF] _
\bf_
\bd does not refer to a valid descriptor.
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.
27662 [EFAULT] _
\bt_
\bi_
\bm_
\be_
\bs points outside the process's allocated address
27665 [EIO] An I/O error occurred while reading or writing the
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.
27672 [EROFS] The file system containing the file is mounted read-
27675 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
27676 clock_gettime(2), stat(2), utime(3)
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'').
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
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.
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.
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
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>
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);
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);
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>
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);
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]);
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.
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.
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.
27735 In either case, the inode-change-time of the file is set to the current
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.
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>:
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.
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
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.
27757 The _
\bf_
\bl_
\ba_
\bg argument is the bitwise OR of zero or more of the following
27760 AT_SYMLINK_NOFOLLOW If _
\bp_
\ba_
\bt_
\bh names a symbolic link, then the
27761 timestamps of the symbolic link are changed.
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
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:
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
27777 [EFAULT] _
\bf_
\bi_
\bl_
\be or _
\bt_
\bi_
\bm_
\be_
\bs points outside the process's allocated
27780 [EIO] An I/O error occurred while reading or writing the
27783 [ELOOP] Too many symbolic links were encountered in
27784 translating the pathname.
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.
27790 [ENOENT] The named file does not exist.
27792 [ENOTDIR] A component of the path prefix is not a directory.
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.
27798 [EROFS] The file system containing the file is mounted read-
27801 Additionally, u
\but
\bti
\bim
\bme
\ben
\bns
\bsa
\bat
\bt() will fail if:
27803 [EINVAL] The value of the _
\bf_
\bl_
\ba_
\bg argument was neither zero nor
27804 AT_SYMLINK_NOFOLLOW.
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
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.
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.
27818 f
\bfu
\but
\bti
\bim
\bme
\bes
\bs() and f
\bfu
\but
\bti
\bim
\bme
\ben
\bns
\bs() will fail if:
27820 [EBADF] _
\bf_
\bd does not refer to a valid descriptor.
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.
27826 [EFAULT] _
\bt_
\bi_
\bm_
\be_
\bs points outside the process's allocated address
27829 [EIO] An I/O error occurred while reading or writing the
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.
27836 [EROFS] The file system containing the file is mounted read-
27839 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
27840 clock_gettime(2), stat(2), utime(3)
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'').
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
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.
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.
27864 u
\but
\btr
\bra
\bac
\bce
\be - insert user record in ktrace log
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>
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);
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
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
27886 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
27887 [ENOSYS] The currently running kernel was compiled without
27888 ktrace(2) support (option KTRACE).
27890 [ENAMETOOLONG] The length of the _
\bl_
\ba_
\bb_
\be_
\bl string was longer than
27891 KTR_USER_MAXIDLEN-1.
27893 [EINVAL] The specified data length _
\bl_
\be_
\bn was bigger than
27896 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
27897 kdump(1), ktrace(1), ktrace(2), options(4)
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.
27904 v
\bvf
\bfo
\bor
\brk
\bk - spawn new process and block parent
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>
27909 _
\bp_
\bi_
\bd_
\b__
\bt
27910 v
\bvf
\bfo
\bor
\brk
\bk(_
\bv_
\bo_
\bi_
\bd);
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().
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.
27927 R
\bRE
\bET
\bTU
\bUR
\bRN
\bN V
\bVA
\bAL
\bLU
\bUE
\bES
\bS
27928 Same as for fork(2).
27930 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
27931 execve(2), fork(2), sigaction(2), wait(2)
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.
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.
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
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>
27953 _
\bp_
\bi_
\bd_
\b__
\bt
27954 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
27984 #define WAIT_ANY (-1) /* any process */
27985 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
27997 WCONTINUED Causes status to be reported for stopped child processes that
27998 have been continued by receipt of a SIGCONT signal.
28000 WNOHANG Indicates that the call should not block if there are no
28001 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
28039 Depending on the values of those macros, the following macros produce the
28040 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
28086 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
28087 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
28089 [ECHILD] The calling process has no existing unwaited-for child
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
28096 [EINTR] The call was interrupted by a caught signal, or the
28097 signal did not have the SA_RESTART flag set.
28099 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
28102 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
28103 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
28126 _
\bp_
\bi_
\bd_
\b__
\bt
28127 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
28157 #define WAIT_ANY (-1) /* any process */
28158 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
28170 WCONTINUED Causes status to be reported for stopped child processes that
28171 have been continued by receipt of a SIGCONT signal.
28173 WNOHANG Indicates that the call should not block if there are no
28174 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
28212 Depending on the values of those macros, the following macros produce the
28213 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
28259 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
28260 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
28262 [ECHILD] The calling process has no existing unwaited-for child
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
28269 [EINTR] The call was interrupted by a caught signal, or the
28270 signal did not have the SA_RESTART flag set.
28272 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
28275 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
28276 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
28299 _
\bp_
\bi_
\bd_
\b__
\bt
28300 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
28330 #define WAIT_ANY (-1) /* any process */
28331 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
28343 WCONTINUED Causes status to be reported for stopped child processes that
28344 have been continued by receipt of a SIGCONT signal.
28346 WNOHANG Indicates that the call should not block if there are no
28347 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
28385 Depending on the values of those macros, the following macros produce the
28386 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
28432 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
28433 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
28435 [ECHILD] The calling process has no existing unwaited-for child
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
28442 [EINTR] The call was interrupted by a caught signal, or the
28443 signal did not have the SA_RESTART flag set.
28445 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
28448 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
28449 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
28472 _
\bp_
\bi_
\bd_
\b__
\bt
28473 w
\bwa
\bai
\bit
\bt(_
\bi_
\bn_
\bt _
\b*_
\bs_
\bt_
\ba_
\bt_
\bu_
\bs);
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);
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>
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);
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);
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).
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().
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>:
28503 #define WAIT_ANY (-1) /* any process */
28504 #define WAIT_MYPGRP 0 /* any process in my process group */
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.
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:
28516 WCONTINUED Causes status to be reported for stopped child processes that
28517 have been continued by receipt of a SIGCONT signal.
28519 WNOHANG Indicates that the call should not block if there are no
28520 processes that wish to report status.
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.
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).
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.
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.
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
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.
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
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.
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)).
28558 Depending on the values of those macros, the following macros produce the
28559 remaining status information about the child process:
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.
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.
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
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.
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.
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).
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).
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.
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.
28605 E
\bER
\bRR
\bRO
\bOR
\bRS
\bS
28606 w
\bwa
\bai
\bit
\bt() will fail and return immediately if:
28608 [ECHILD] The calling process has no existing unwaited-for child
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
28615 [EINTR] The call was interrupted by a caught signal, or the
28616 signal did not have the SA_RESTART flag set.
28618 [EINVAL] Invalid or undefined flags were passed in the _
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs
28621 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
28622 _exit(2), sigaction(2), exit(3)
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
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
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.
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
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>
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);
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);
28651 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bsy
\bys
\bs/
\b/u
\bui
\bio
\bo.
\b.h
\bh>
\b>
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);
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>
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);
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
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:
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.
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
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
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.
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)).
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.
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.
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.
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:
28717 [EBADF] _
\bd is not a valid descriptor open for writing.
28719 [EFBIG] An attempt was made to write a file that exceeds the
28720 process's file size limit or the maximum file size.
28722 [ENOSPC] There is no free space remaining on the file system
28723 containing the file.
28725 [EDQUOT] The user's quota of disk blocks on the file system
28726 containing the file has been exhausted.
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
28733 [EIO] An I/O error occurred while reading from or writing to
28736 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
28739 In addition, w
\bwr
\bri
\bit
\bte
\be() and w
\bwr
\bri
\bit
\bte
\bev
\bv() may return the following errors:
28741 [EPIPE] An attempt is made to write to a pipe that is not open
28742 for reading by any process.
28744 [EPIPE] An attempt is made to write to a socket of type
28745 SOCK_STREAM that is not connected to a peer socket.
28747 [EAGAIN] The file was marked for non-blocking I/O, and no data
28748 could be written immediately.
28750 [ENETDOWN] The destination address specified a network that is
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.
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
28766 w
\bwr
\bri
\bit
\bte
\be() and p
\bpw
\bwr
\bri
\bit
\bte
\be() may return the following error:
28768 [EINVAL] _
\bn_
\bb_
\by_
\bt_
\be_
\bs was larger than SSIZE_MAX.
28770 p
\bpw
\bwr
\bri
\bit
\bte
\be() and p
\bpw
\bwr
\bri
\bit
\bte
\bev
\bv() may return the following error:
28772 [EINVAL] _
\bo_
\bf_
\bf_
\bs_
\be_
\bt was negative.
28774 [ESPIPE] _
\bd is associated with a pipe, socket, FIFO, or tty.
28776 w
\bwr
\bri
\bit
\bte
\bev
\bv() and p
\bpw
\bwr
\bri
\bit
\bte
\bev
\bv() may return one of the following errors:
28778 [EINVAL] _
\bi_
\bo_
\bv_
\bc_
\bn_
\bt was less than or equal to 0, or greater than
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.
28784 [EFAULT] Part of _
\bi_
\bo_
\bv points outside the process's allocated
28787 [ENOBUFS] The system lacked sufficient buffer space or a queue
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)
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'').
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.
28803 C
\bCA
\bAV
\bVE
\bEA
\bAT
\bTS
\bS
28804 Error checks should explicitly test for -1. Code such as
28806 while ((nr = write(fd, buf, sizeof(buf))) > 0)
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
28813 while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0)
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
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>
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);
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);
28827 #
\b#i
\bin
\bnc
\bcl
\blu
\bud
\bde
\be <
\b<s
\bsy
\bys
\bs/
\b/u
\bui
\bio
\bo.
\b.h
\bh>
\b>
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);
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>
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);
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
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:
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.
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
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
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.
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)).
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.
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.
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.
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:
28893 [EBADF] _
\bd is not a valid descriptor open for writing.
28895 [EFBIG] An attempt was made to write a file that exceeds the
28896 process's file size limit or the maximum file size.
28898 [ENOSPC] There is no free space remaining on the file system
28899 containing the file.
28901 [EDQUOT] The user's quota of disk blocks on the file system
28902 containing the file has been exhausted.
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
28909 [EIO] An I/O error occurred while reading from or writing to
28912 [EFAULT] Part of _
\bb_
\bu_
\bf points outside the process's allocated
28915 In addition, w
\bwr
\bri
\bit
\bte
\be() and w
\bwr
\bri
\bit
\bte
\bev
\bv() may return the following errors:
28917 [EPIPE] An attempt is made to write to a pipe that is not open
28918 for reading by any process.
28920 [EPIPE] An attempt is made to write to a socket of type
28921 SOCK_STREAM that is not connected to a peer socket.
28923 [EAGAIN] The file was marked for non-blocking I/O, and no data
28924 could be written immediately.
28926 [ENETDOWN] The destination address specified a network that is
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.
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
28942 w
\bwr
\bri
\bit
\bte
\be() and p
\bpw
\bwr
\bri
\bit
\bte
\be() may return the following error:
28944 [EINVAL] _
\bn_
\bb_
\by_
\bt_
\be_
\bs was larger than SSIZE_MAX.
28946 p
\bpw
\bwr
\bri
\bit
\bte
\be() and p
\bpw
\bwr
\bri
\bit
\bte
\bev
\bv() may return the following error:
28948 [EINVAL] _
\bo_
\bf_
\bf_
\bs_
\be_
\bt was negative.
28950 [ESPIPE] _
\bd is associated with a pipe, socket, FIFO, or tty.
28952 w
\bwr
\bri
\bit
\bte
\bev
\bv() and p
\bpw
\bwr
\bri
\bit
\bte
\bev
\bv() may return one of the following errors:
28954 [EINVAL] _
\bi_
\bo_
\bv_
\bc_
\bn_
\bt was less than or equal to 0, or greater than
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.
28960 [EFAULT] Part of _
\bi_
\bo_
\bv points outside the process's allocated
28963 [ENOBUFS] The system lacked sufficient buffer space or a queue
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)
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'').
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.
28979 C
\bCA
\bAV
\bVE
\bEA
\bAT
\bTS
\bS
28980 Error checks should explicitly test for -1. Code such as
28982 while ((nr = write(fd, buf, sizeof(buf))) > 0)
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
28989 while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0)
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
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>
28998 a
\bar
\brm
\bm_
\b_d
\bdr
\bra
\bai
\bin
\bn_
\b_w
\bwr
\bri
\bit
\bte
\beb
\bbu
\buf
\bf();
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.
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.
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.
29010 R
\bRE
\bEF
\bFE
\bER
\bRE
\bEN
\bNC
\bCE
\bES
\bS
29011 StrongARM Data Sheet
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
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>
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);
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
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.
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.
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.
29043 R
\bRE
\bEF
\bFE
\bER
\bRE
\bEN
\bNC
\bCE
\bES
\bS
29044 StrongARM Data Sheet
29046 OpenBSD 5.7 August 14, 2013 OpenBSD 5.7