6a039e1a |
1 | # find /usr/share/man/man2 | grep 2 | xargs pr -t | mandoc >> bsd_man2_all |
2 | |
3 | KQUEUE(2) System Calls Manual KQUEUE(2) |
4 | |
5 | N\bNA\bAM\bME\bE |
6 | k\bkq\bqu\bue\beu\bue\be, k\bke\bev\bve\ben\bnt\bt - kernel event notification mechanism |
7 | |
8 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
10 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/e\bev\bve\ben\bnt\bt.\b.h\bh>\b> |
11 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
12 | |
13 | _\bi_\bn_\bt |
14 | k\bkq\bqu\bue\beu\bue\be(_\bv_\bo_\bi_\bd); |
15 | |
16 | _\bi_\bn_\bt |
17 | k\bke\bev\bve\ben\bnt\bt(_\bi_\bn_\bt _\bk_\bq, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs, |
18 | _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\be_\bv_\be_\bn_\bt_\bs, |
19 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
20 | |
21 | E\bEV\bV_\b_S\bSE\bET\bT(_\b&_\bk_\be_\bv, _\bi_\bd_\be_\bn_\bt, _\bf_\bi_\bl_\bt_\be_\br, _\bf_\bl_\ba_\bg_\bs, _\bf_\bf_\bl_\ba_\bg_\bs, _\bd_\ba_\bt_\ba, _\bu_\bd_\ba_\bt_\ba); |
22 | |
23 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24 | k\bkq\bqu\bue\beu\bue\be() provides a generic method of notifying the user when an event |
25 | happens or a condition holds, based on the results of small pieces of |
26 | kernel code termed ``filters''. A kevent is identified by the (ident, |
27 | filter) pair; there may only be one unique kevent per kqueue. |
28 | |
29 | The filter is executed upon the initial registration of a kevent in order |
30 | to detect whether a preexisting condition is present, and is also |
31 | executed whenever an event is passed to the filter for evaluation. If |
32 | the filter determines that the condition should be reported, then the |
33 | kevent is placed on the kqueue for the user to retrieve. |
34 | |
35 | The filter is also run when the user attempts to retrieve the kevent from |
36 | the kqueue. If the filter indicates that the condition that triggered |
37 | the event no longer holds, the kevent is removed from the kqueue and is |
38 | not returned. |
39 | |
40 | Multiple events which trigger the filter do not result in multiple |
41 | kevents being placed on the kqueue; instead, the filter will aggregate |
42 | the events into a single struct kevent. Calling c\bcl\blo\bos\bse\be() on a file |
43 | descriptor will remove any kevents that reference the descriptor. |
44 | |
45 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a descriptor. The |
46 | queue is not inherited by a child created with fork(2). Similarly, |
47 | kqueues cannot be passed across UNIX-domain sockets. |
48 | |
49 | k\bke\bev\bve\ben\bnt\bt() is used to register events with the queue, and return any |
50 | pending events to the user. _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt is a pointer to an array of |
51 | _\bk_\be_\bv_\be_\bn_\bt structures, as defined in <_\bs_\by_\bs_\b/_\be_\bv_\be_\bn_\bt_\b._\bh>. All changes contained in |
52 | the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt are applied before any pending events are read from the |
53 | queue. _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs gives the size of _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt. _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt is a pointer to |
54 | an array of kevent structures. _\bn_\be_\bv_\be_\bn_\bt_\bs determines the size of _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
55 | When _\bn_\be_\bv_\be_\bn_\bt_\bs is zero, k\bke\bev\bve\ben\bnt\bt() will return immediately even if there is a |
56 | _\bt_\bi_\bm_\be_\bo_\bu_\bt specified unlike select(2). If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it |
57 | specifies a maximum interval to wait for an event, which will be |
58 | interpreted as a struct timespec. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, k\bke\bev\bve\ben\bnt\bt() |
59 | waits indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
60 | non-null, pointing to a zero-valued _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc structure. The same array |
61 | may be used for the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
62 | |
63 | E\bEV\bV_\b_S\bSE\bET\bT() is a macro which is provided for ease of initializing a kevent |
64 | structure. |
65 | |
66 | The _\bk_\be_\bv_\be_\bn_\bt structure is defined as: |
67 | |
68 | struct kevent { |
69 | uintptr_t ident; /* identifier for this event */ |
70 | short filter; /* filter for event */ |
71 | u_short flags; /* action flags for kqueue */ |
72 | u_int fflags; /* filter flag value */ |
73 | quad_t data; /* filter data value */ |
74 | void *udata; /* opaque user data identifier */ |
75 | }; |
76 | |
77 | The fields of struct kevent are: |
78 | |
79 | ident Value used to identify this event. The exact interpretation |
80 | is determined by the attached filter, but often is a file |
81 | descriptor. |
82 | |
83 | filter Identifies the kernel filter used to process this event. The |
84 | pre-defined system filters are described below. |
85 | |
86 | flags Actions to perform on the event. |
87 | |
88 | fflags Filter-specific flags. |
89 | |
90 | data Filter-specific data value. |
91 | |
92 | udata Opaque user-defined value passed through the kernel unchanged. |
93 | |
94 | The _\bf_\bl_\ba_\bg_\bs field can contain the following values: |
95 | |
96 | EV_ADD Adds the event to the kqueue. Re-adding an existing event |
97 | will modify the parameters of the original event, and not |
98 | result in a duplicate entry. Adding an event |
99 | automatically enables it, unless overridden by the |
100 | EV_DISABLE flag. |
101 | |
102 | EV_ENABLE Permit k\bke\bev\bve\ben\bnt\bt() to return the event if it is triggered. |
103 | |
104 | EV_DISABLE Disable the event so k\bke\bev\bve\ben\bnt\bt() will not return it. The |
105 | filter itself is not disabled. |
106 | |
107 | EV_DELETE Removes the event from the kqueue. Events which are |
108 | attached to file descriptors are automatically deleted on |
109 | the last close of the descriptor. |
110 | |
111 | EV_ONESHOT Causes the event to return only the first occurrence of |
112 | the filter being triggered. After the user retrieves the |
113 | event from the kqueue, it is deleted. |
114 | |
115 | EV_CLEAR After the event is retrieved by the user, its state is |
116 | reset. This is useful for filters which report state |
117 | transitions instead of the current state. Note that some |
118 | filters may automatically set this flag internally. |
119 | |
120 | EV_EOF Filters may set this flag to indicate filter-specific EOF |
121 | condition. |
122 | |
123 | EV_ERROR See _\bR_\bE_\bT_\bU_\bR_\bN _\bV_\bA_\bL_\bU_\bE_\bS below. |
124 | |
125 | The predefined system filters are listed below. Arguments may be passed |
126 | to and from the filter via the _\bf_\bf_\bl_\ba_\bg_\bs and _\bd_\ba_\bt_\ba fields in the kevent |
127 | structure. |
128 | |
129 | EVFILT_READ Takes a descriptor as the identifier, and returns whenever |
130 | there is data available to read. The behavior of the |
131 | filter is slightly different depending on the descriptor |
132 | type. |
133 | |
134 | Sockets |
135 | Sockets which have previously been passed to l\bli\bis\bst\bte\ben\bn() |
136 | return when there is an incoming connection pending. |
137 | _\bd_\ba_\bt_\ba contains the size of the listen backlog. |
138 | |
139 | Other socket descriptors return when there is data to |
140 | be read, subject to the SO_RCVLOWAT value of the |
141 | socket buffer. This may be overridden with a per- |
142 | filter low water mark at the time the filter is added |
143 | by setting the NOTE_LOWAT flag in _\bf_\bf_\bl_\ba_\bg_\bs, and |
144 | specifying the new low water mark in _\bd_\ba_\bt_\ba. On return, |
145 | _\bd_\ba_\bt_\ba contains the number of bytes in the socket |
146 | buffer. |
147 | |
148 | If the read direction of the socket has shutdown, then |
149 | the filter also sets EV_EOF in _\bf_\bl_\ba_\bg_\bs, and returns the |
150 | socket error (if any) in _\bf_\bf_\bl_\ba_\bg_\bs. It is possible for |
151 | EOF to be returned (indicating the connection is gone) |
152 | while there is still data pending in the socket |
153 | buffer. |
154 | |
155 | Vnodes |
156 | Returns when the file pointer is not at the end of |
157 | file. _\bd_\ba_\bt_\ba contains the offset from current position |
158 | to end of file, and may be negative. If NOTE_EOF is |
159 | set in _\bf_\bf_\bl_\ba_\bg_\bs, k\bke\bev\bve\ben\bnt\bt() will also return when the file |
160 | pointer is at the end of file. The end of file |
161 | condition is indicated by the presence of NOTE_EOF in |
162 | _\bf_\bf_\bl_\ba_\bg_\bs on return. |
163 | |
164 | Fifos, Pipes |
165 | Returns when there is data to read; _\bd_\ba_\bt_\ba contains the |
166 | number of bytes available. |
167 | |
168 | When the last writer disconnects, the filter will set |
169 | EV_EOF in _\bf_\bl_\ba_\bg_\bs. This may be cleared by passing in |
170 | EV_CLEAR, at which point the filter will resume |
171 | waiting for data to become available before returning. |
172 | |
173 | BPF devices |
174 | Returns when the BPF buffer is full, the BPF timeout |
175 | has expired, or when the BPF has ``immediate mode'' |
176 | enabled and there is any data to read; _\bd_\ba_\bt_\ba contains |
177 | the number of bytes available. |
178 | |
179 | EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever |
180 | it is possible to write to the descriptor. For sockets, |
181 | pipes, and FIFOs, _\bd_\ba_\bt_\ba will contain the amount of space |
182 | remaining in the write buffer. The filter will set EV_EOF |
183 | when the reader disconnects, and for the FIFO case, this |
184 | may be cleared by use of EV_CLEAR. Note that this filter |
185 | is not supported for vnodes or BPF devices. |
186 | |
187 | For sockets, the low water mark and socket error handling |
188 | is identical to the EVFILT_READ case. |
189 | |
190 | EVFILT_VNODE Takes a file descriptor as the identifier and the events |
191 | to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when one or more of |
192 | the requested events occurs on the descriptor. The events |
193 | to monitor are: |
194 | |
195 | NOTE_DELETE u\bun\bnl\bli\bin\bnk\bk() was called on the file referenced |
196 | by the descriptor. |
197 | |
198 | NOTE_WRITE A write occurred on the file referenced by |
199 | the descriptor. |
200 | |
201 | NOTE_EXTEND The file referenced by the descriptor was |
202 | extended. |
203 | |
204 | NOTE_TRUNCATE The file referenced by the descriptor was |
205 | truncated. |
206 | |
207 | NOTE_ATTRIB The file referenced by the descriptor had |
208 | its attributes changed. |
209 | |
210 | NOTE_LINK The link count on the file changed. |
211 | |
212 | NOTE_RENAME The file referenced by the descriptor was |
213 | renamed. |
214 | |
215 | NOTE_REVOKE Access to the file was revoked via |
216 | revoke(2) or the underlying file system was |
217 | unmounted. |
218 | |
219 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
220 | filter. |
221 | |
222 | EVFILT_PROC Takes the process ID to monitor as the identifier and the |
223 | events to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when the |
224 | process performs one or more of the requested events. If |
225 | a process can normally see another process, it can attach |
226 | an event to it. The events to monitor are: |
227 | |
228 | NOTE_EXIT The process has exited. The exit status |
229 | will be stored in _\bd_\ba_\bt_\ba in the same format |
230 | as the status set by wait(2). |
231 | |
232 | NOTE_FORK The process has called f\bfo\bor\brk\bk(). |
233 | |
234 | NOTE_EXEC The process has executed a new process |
235 | via execve(2) or similar call. |
236 | |
237 | NOTE_TRACK Follow a process across f\bfo\bor\brk\bk() calls. |
238 | The parent process will return with |
239 | NOTE_FORK set in the _\bf_\bf_\bl_\ba_\bg_\bs field, while |
240 | the child process will return with |
241 | NOTE_CHILD set in _\bf_\bf_\bl_\ba_\bg_\bs and the parent |
242 | PID in _\bd_\ba_\bt_\ba. |
243 | |
244 | NOTE_TRACKERR This flag is returned if the system was |
245 | unable to attach an event to the child |
246 | process, usually due to resource |
247 | limitations. |
248 | |
249 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
250 | filter. |
251 | |
252 | EVFILT_SIGNAL Takes the signal number to monitor as the identifier and |
253 | returns when the given signal is delivered to the process. |
254 | This coexists with the s\bsi\big\bgn\bna\bal\bl() and s\bsi\big\bga\bac\bct\bti\bio\bon\bn() |
255 | facilities, and has a lower precedence. The filter will |
256 | record all attempts to deliver a signal to a process, even |
257 | if the signal has been marked as SIG_IGN. Event |
258 | notification happens after normal signal delivery |
259 | processing. _\bd_\ba_\bt_\ba returns the number of times the signal |
260 | has occurred since the last call to k\bke\bev\bve\ben\bnt\bt(). This filter |
261 | automatically sets the EV_CLEAR flag internally. |
262 | |
263 | EVFILT_TIMER Establishes an arbitrary timer identified by _\bi_\bd_\be_\bn_\bt. When |
264 | adding a timer, _\bd_\ba_\bt_\ba specifies the timeout period in |
265 | milliseconds. The timer will be periodic unless |
266 | EV_ONESHOT is specified. On return, _\bd_\ba_\bt_\ba contains the |
267 | number of times the timeout has expired since the last |
268 | call to k\bke\bev\bve\ben\bnt\bt(). This filter automatically sets the |
269 | EV_CLEAR flag internally. |
270 | |
271 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
272 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a file descriptor. |
273 | If there was an error creating the kernel event queue, a value of -1 is |
274 | returned and errno set. |
275 | |
276 | k\bke\bev\bve\ben\bnt\bt() returns the number of events placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, up to the |
277 | value given by _\bn_\be_\bv_\be_\bn_\bt_\bs. If an error occurs while processing an element |
278 | of the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and there is enough room in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, then the |
279 | event will be placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt with EV_ERROR set in _\bf_\bl_\ba_\bg_\bs and the |
280 | system error in _\bd_\ba_\bt_\ba. Otherwise, -1 will be returned, and errno will be |
281 | set to indicate the error condition. If the time limit expires, then |
282 | k\bke\bev\bve\ben\bnt\bt() returns 0. |
283 | |
284 | E\bER\bRR\bRO\bOR\bRS\bS |
285 | The k\bkq\bqu\bue\beu\bue\be() function fails if: |
286 | |
287 | [ENOMEM] The kernel failed to allocate enough memory for the |
288 | kernel queue. |
289 | |
290 | [EMFILE] The per-process descriptor table is full. |
291 | |
292 | [ENFILE] The system file table is full. |
293 | |
294 | The k\bke\bev\bve\ben\bnt\bt() function fails if: |
295 | |
296 | [EACCES] The process does not have permission to register a |
297 | filter. |
298 | |
299 | [EFAULT] There was an error reading or writing the _\bk_\be_\bv_\be_\bn_\bt |
300 | structure. |
301 | |
302 | [EBADF] The specified descriptor is invalid. |
303 | |
304 | [EINTR] A signal was delivered before the timeout expired and |
305 | before any events were placed on the kqueue for |
306 | return. |
307 | |
308 | [EINVAL] The specified time limit or filter is invalid. |
309 | |
310 | [ENOENT] The event could not be found to be modified or |
311 | deleted. |
312 | |
313 | [ENOMEM] No memory was available to register the event. |
314 | |
315 | [ESRCH] The specified process to attach to does not exist. |
316 | |
317 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
318 | poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) |
319 | |
320 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
321 | The k\bkq\bqu\bue\beu\bue\be() and k\bke\bev\bve\ben\bnt\bt() functions first appeared in FreeBSD 4.1. |
322 | |
323 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
324 | The k\bkq\bqu\bue\beu\bue\be() system and this manual page were written by Jonathan Lemon |
325 | <_\bj_\bl_\be_\bm_\bo_\bn_\b@_\bF_\br_\be_\be_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
326 | |
327 | B\bBU\bUG\bGS\bS |
328 | It is currently not possible to watch FIFOs or AIO that reside on |
329 | anything but a UFS file system. Watching a vnode is possible on UFS, NFS |
330 | and MS-DOS file systems. |
331 | |
332 | The _\bt_\bi_\bm_\be_\bo_\bu_\bt value is limited to 24 hours; longer timeouts will be |
333 | silently reinterpreted as 24 hours. |
334 | |
335 | N\bNA\bAM\bME\bE |
336 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
337 | |
338 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
339 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
340 | |
341 | _\bi_\bn_\bt |
342 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
343 | |
344 | _\bi_\bn_\bt |
345 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
346 | |
347 | _\bi_\bn_\bt |
348 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
349 | |
350 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
351 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
352 | |
353 | _\bi_\bn_\bt |
354 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
355 | |
356 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
357 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
358 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
359 | required, but all directories listed in the path name leading to the file |
360 | must be searchable. |
361 | |
362 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
363 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
364 | itself, not the file the link references. |
365 | |
366 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
367 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
368 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
369 | determined relative to the directory associated with file descriptor _\bf_\bd |
370 | instead of the current working directory. |
371 | |
372 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
373 | in the _\bf_\bd parameter, the current working directory is used and the |
374 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
375 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
376 | |
377 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
378 | values: |
379 | |
380 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
381 | of the symbolic link is returned. |
382 | |
383 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
384 | known by the file descriptor _\bf_\bd. |
385 | |
386 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
387 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
388 | concerning the file. |
389 | |
390 | struct stat { |
391 | dev_t st_dev; /* inode's device */ |
392 | ino_t st_ino; /* inode's number */ |
393 | mode_t st_mode; /* inode protection mode */ |
394 | nlink_t st_nlink; /* number of hard links */ |
395 | uid_t st_uid; /* user ID of the file's owner */ |
396 | gid_t st_gid; /* group ID of the file's group */ |
397 | dev_t st_rdev; /* device type */ |
398 | struct timespec st_atim; /* time of last access */ |
399 | struct timespec st_mtim; /* time of last data modification */ |
400 | struct timespec st_ctim; /* time of last file status change */ |
401 | off_t st_size; /* file size, in bytes */ |
402 | blkcnt_t st_blocks; /* blocks allocated for file */ |
403 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
404 | u_int32_t st_flags; /* user defined flags for file */ |
405 | u_int32_t st_gen; /* file generation number */ |
406 | }; |
407 | |
408 | The time-related fields of struct stat are represented in struct timespec |
409 | format, which has nanosecond precision. However, the actual precision is |
410 | generally limited by the file system holding the file. The fields are as |
411 | follows: |
412 | |
413 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
414 | system object was created and updated by the utimes(2) and |
415 | read(2) system calls. |
416 | |
417 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
418 | truncate(2), utimes(2), and write(2) system calls. For |
419 | directories, changed by any system call that alters which |
420 | files are in the directory, such as the unlink(2), rename(2), |
421 | mkdir(2), and symlink(2) system calls. |
422 | |
423 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
424 | modification). Changed by the chmod(2), chown(2), link(2), |
425 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
426 | |
427 | In addition, all the time fields are set to the current time when a file |
428 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
429 | open(2), and symlink(2) system calls. |
430 | |
431 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
432 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
433 | respective struct timespec member. Deprecated macros are also provided |
434 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
435 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
436 | |
437 | The size-related fields of the struct stat are as follows: |
438 | |
439 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
440 | |
441 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
442 | 512-byte units. As short symbolic links are stored in the |
443 | inode, this number may be zero. |
444 | |
445 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
446 | |
447 | #define S_IFMT 0170000 /* type of file mask */ |
448 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
449 | #define S_IFCHR 0020000 /* character special */ |
450 | #define S_IFDIR 0040000 /* directory */ |
451 | #define S_IFBLK 0060000 /* block special */ |
452 | #define S_IFREG 0100000 /* regular */ |
453 | #define S_IFLNK 0120000 /* symbolic link */ |
454 | #define S_IFSOCK 0140000 /* socket */ |
455 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
456 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
457 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
458 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
459 | #define S_IRUSR 0000400 /* R for owner */ |
460 | #define S_IWUSR 0000200 /* W for owner */ |
461 | #define S_IXUSR 0000100 /* X for owner */ |
462 | #define S_IRWXG 0000070 /* RWX mask for group */ |
463 | #define S_IRGRP 0000040 /* R for group */ |
464 | #define S_IWGRP 0000020 /* W for group */ |
465 | #define S_IXGRP 0000010 /* X for group */ |
466 | #define S_IRWXO 0000007 /* RWX mask for other */ |
467 | #define S_IROTH 0000004 /* R for other */ |
468 | #define S_IWOTH 0000002 /* W for other */ |
469 | #define S_IXOTH 0000001 /* X for other */ |
470 | |
471 | The following macros test a file's type. If the file is of that type, a |
472 | non-zero value is returned; otherwise, 0 is returned. |
473 | |
474 | S_ISBLK(st_mode m) /* block special */ |
475 | S_ISCHR(st_mode m) /* char special */ |
476 | S_ISDIR(st_mode m) /* directory */ |
477 | S_ISFIFO(st_mode m) /* fifo */ |
478 | S_ISLNK(st_mode m) /* symbolic link */ |
479 | S_ISREG(st_mode m) /* regular file */ |
480 | S_ISSOCK(st_mode m) /* socket */ |
481 | |
482 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
483 | |
484 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
485 | Upon successful completion, the value 0 is returned; otherwise the |
486 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
487 | error. |
488 | |
489 | E\bER\bRR\bRO\bOR\bRS\bS |
490 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
491 | |
492 | [ENOTDIR] A component of the path prefix is not a directory. |
493 | |
494 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
495 | characters, or an entire pathname (including the |
496 | terminating NUL) exceeded PATH_MAX bytes. |
497 | |
498 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
499 | empty path. |
500 | |
501 | [EACCES] Search permission is denied for a component of the |
502 | path prefix. |
503 | |
504 | [ELOOP] Too many symbolic links were encountered in |
505 | translating the pathname. |
506 | |
507 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
508 | |
509 | [EIO] An I/O error occurred while reading from or writing to |
510 | the file system. |
511 | |
512 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
513 | |
514 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
515 | AT_SYMLINK_NOFOLLOW. |
516 | |
517 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
518 | argument is neither AT_FDCWD nor a valid file |
519 | descriptor. |
520 | |
521 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
522 | argument is a valid file descriptor but it does not |
523 | reference a directory. |
524 | |
525 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
526 | permission is denied for the directory which the _\bf_\bd |
527 | file descriptor references. |
528 | |
529 | f\bfs\bst\bta\bat\bt() will fail if: |
530 | |
531 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
532 | |
533 | [EFAULT] _\bs_\bb points to an invalid address. |
534 | |
535 | [EIO] An I/O error occurred while reading from the file |
536 | system. |
537 | |
538 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
539 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
540 | |
541 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
542 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
543 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
544 | |
545 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
546 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
547 | |
548 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
549 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
550 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
551 | in Version 7 AT&T UNIX. |
552 | |
553 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
554 | appeared in OpenBSD 5.0. |
555 | |
556 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
557 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
558 | |
559 | Certain programs written when the timestamps were just of type time_t |
560 | assumed that the members were consecutive (and could therefore be treated |
561 | as an array and have their address passed directly to utime(3)). The |
562 | transition to timestamps of type struct timespec broke them irrevocably. |
563 | |
564 | B\bBU\bUG\bGS\bS |
565 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
566 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
567 | the time fields. |
568 | |
569 | N\bNA\bAM\bME\bE |
570 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
571 | |
572 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
573 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
574 | |
575 | _\bi_\bn_\bt |
576 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
577 | |
578 | _\bi_\bn_\bt |
579 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
580 | |
581 | _\bi_\bn_\bt |
582 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
583 | |
584 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
585 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
586 | |
587 | _\bi_\bn_\bt |
588 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
589 | |
590 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
591 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
592 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
593 | required, but all directories listed in the path name leading to the file |
594 | must be searchable. |
595 | |
596 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
597 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
598 | itself, not the file the link references. |
599 | |
600 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
601 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
602 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
603 | determined relative to the directory associated with file descriptor _\bf_\bd |
604 | instead of the current working directory. |
605 | |
606 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
607 | in the _\bf_\bd parameter, the current working directory is used and the |
608 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
609 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
610 | |
611 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
612 | values: |
613 | |
614 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
615 | of the symbolic link is returned. |
616 | |
617 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
618 | known by the file descriptor _\bf_\bd. |
619 | |
620 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
621 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
622 | concerning the file. |
623 | |
624 | struct stat { |
625 | dev_t st_dev; /* inode's device */ |
626 | ino_t st_ino; /* inode's number */ |
627 | mode_t st_mode; /* inode protection mode */ |
628 | nlink_t st_nlink; /* number of hard links */ |
629 | uid_t st_uid; /* user ID of the file's owner */ |
630 | gid_t st_gid; /* group ID of the file's group */ |
631 | dev_t st_rdev; /* device type */ |
632 | struct timespec st_atim; /* time of last access */ |
633 | struct timespec st_mtim; /* time of last data modification */ |
634 | struct timespec st_ctim; /* time of last file status change */ |
635 | off_t st_size; /* file size, in bytes */ |
636 | blkcnt_t st_blocks; /* blocks allocated for file */ |
637 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
638 | u_int32_t st_flags; /* user defined flags for file */ |
639 | u_int32_t st_gen; /* file generation number */ |
640 | }; |
641 | |
642 | The time-related fields of struct stat are represented in struct timespec |
643 | format, which has nanosecond precision. However, the actual precision is |
644 | generally limited by the file system holding the file. The fields are as |
645 | follows: |
646 | |
647 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
648 | system object was created and updated by the utimes(2) and |
649 | read(2) system calls. |
650 | |
651 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
652 | truncate(2), utimes(2), and write(2) system calls. For |
653 | directories, changed by any system call that alters which |
654 | files are in the directory, such as the unlink(2), rename(2), |
655 | mkdir(2), and symlink(2) system calls. |
656 | |
657 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
658 | modification). Changed by the chmod(2), chown(2), link(2), |
659 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
660 | |
661 | In addition, all the time fields are set to the current time when a file |
662 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
663 | open(2), and symlink(2) system calls. |
664 | |
665 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
666 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
667 | respective struct timespec member. Deprecated macros are also provided |
668 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
669 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
670 | |
671 | The size-related fields of the struct stat are as follows: |
672 | |
673 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
674 | |
675 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
676 | 512-byte units. As short symbolic links are stored in the |
677 | inode, this number may be zero. |
678 | |
679 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
680 | |
681 | #define S_IFMT 0170000 /* type of file mask */ |
682 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
683 | #define S_IFCHR 0020000 /* character special */ |
684 | #define S_IFDIR 0040000 /* directory */ |
685 | #define S_IFBLK 0060000 /* block special */ |
686 | #define S_IFREG 0100000 /* regular */ |
687 | #define S_IFLNK 0120000 /* symbolic link */ |
688 | #define S_IFSOCK 0140000 /* socket */ |
689 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
690 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
691 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
692 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
693 | #define S_IRUSR 0000400 /* R for owner */ |
694 | #define S_IWUSR 0000200 /* W for owner */ |
695 | #define S_IXUSR 0000100 /* X for owner */ |
696 | #define S_IRWXG 0000070 /* RWX mask for group */ |
697 | #define S_IRGRP 0000040 /* R for group */ |
698 | #define S_IWGRP 0000020 /* W for group */ |
699 | #define S_IXGRP 0000010 /* X for group */ |
700 | #define S_IRWXO 0000007 /* RWX mask for other */ |
701 | #define S_IROTH 0000004 /* R for other */ |
702 | #define S_IWOTH 0000002 /* W for other */ |
703 | #define S_IXOTH 0000001 /* X for other */ |
704 | |
705 | The following macros test a file's type. If the file is of that type, a |
706 | non-zero value is returned; otherwise, 0 is returned. |
707 | |
708 | S_ISBLK(st_mode m) /* block special */ |
709 | S_ISCHR(st_mode m) /* char special */ |
710 | S_ISDIR(st_mode m) /* directory */ |
711 | S_ISFIFO(st_mode m) /* fifo */ |
712 | S_ISLNK(st_mode m) /* symbolic link */ |
713 | S_ISREG(st_mode m) /* regular file */ |
714 | S_ISSOCK(st_mode m) /* socket */ |
715 | |
716 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
717 | |
718 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
719 | Upon successful completion, the value 0 is returned; otherwise the |
720 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
721 | error. |
722 | |
723 | E\bER\bRR\bRO\bOR\bRS\bS |
724 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
725 | |
726 | [ENOTDIR] A component of the path prefix is not a directory. |
727 | |
728 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
729 | characters, or an entire pathname (including the |
730 | terminating NUL) exceeded PATH_MAX bytes. |
731 | |
732 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
733 | empty path. |
734 | |
735 | [EACCES] Search permission is denied for a component of the |
736 | path prefix. |
737 | |
738 | [ELOOP] Too many symbolic links were encountered in |
739 | translating the pathname. |
740 | |
741 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
742 | |
743 | [EIO] An I/O error occurred while reading from or writing to |
744 | the file system. |
745 | |
746 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
747 | |
748 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
749 | AT_SYMLINK_NOFOLLOW. |
750 | |
751 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
752 | argument is neither AT_FDCWD nor a valid file |
753 | descriptor. |
754 | |
755 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
756 | argument is a valid file descriptor but it does not |
757 | reference a directory. |
758 | |
759 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
760 | permission is denied for the directory which the _\bf_\bd |
761 | file descriptor references. |
762 | |
763 | f\bfs\bst\bta\bat\bt() will fail if: |
764 | |
765 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
766 | |
767 | [EFAULT] _\bs_\bb points to an invalid address. |
768 | |
769 | [EIO] An I/O error occurred while reading from the file |
770 | system. |
771 | |
772 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
773 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
774 | |
775 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
776 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
777 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
778 | |
779 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
780 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
781 | |
782 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
783 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
784 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
785 | in Version 7 AT&T UNIX. |
786 | |
787 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
788 | appeared in OpenBSD 5.0. |
789 | |
790 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
791 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
792 | |
793 | Certain programs written when the timestamps were just of type time_t |
794 | assumed that the members were consecutive (and could therefore be treated |
795 | as an array and have their address passed directly to utime(3)). The |
796 | transition to timestamps of type struct timespec broke them irrevocably. |
797 | |
798 | B\bBU\bUG\bGS\bS |
799 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
800 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
801 | the time fields. |
802 | |
803 | N\bNA\bAM\bME\bE |
804 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
805 | |
806 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
807 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
808 | |
809 | _\bi_\bn_\bt |
810 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
811 | |
812 | _\bi_\bn_\bt |
813 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
814 | |
815 | _\bi_\bn_\bt |
816 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
817 | |
818 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
819 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
820 | |
821 | _\bi_\bn_\bt |
822 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
823 | |
824 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
825 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
826 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
827 | required, but all directories listed in the path name leading to the file |
828 | must be searchable. |
829 | |
830 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
831 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
832 | itself, not the file the link references. |
833 | |
834 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
835 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
836 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
837 | determined relative to the directory associated with file descriptor _\bf_\bd |
838 | instead of the current working directory. |
839 | |
840 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
841 | in the _\bf_\bd parameter, the current working directory is used and the |
842 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
843 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
844 | |
845 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
846 | values: |
847 | |
848 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
849 | of the symbolic link is returned. |
850 | |
851 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
852 | known by the file descriptor _\bf_\bd. |
853 | |
854 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
855 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
856 | concerning the file. |
857 | |
858 | struct stat { |
859 | dev_t st_dev; /* inode's device */ |
860 | ino_t st_ino; /* inode's number */ |
861 | mode_t st_mode; /* inode protection mode */ |
862 | nlink_t st_nlink; /* number of hard links */ |
863 | uid_t st_uid; /* user ID of the file's owner */ |
864 | gid_t st_gid; /* group ID of the file's group */ |
865 | dev_t st_rdev; /* device type */ |
866 | struct timespec st_atim; /* time of last access */ |
867 | struct timespec st_mtim; /* time of last data modification */ |
868 | struct timespec st_ctim; /* time of last file status change */ |
869 | off_t st_size; /* file size, in bytes */ |
870 | blkcnt_t st_blocks; /* blocks allocated for file */ |
871 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
872 | u_int32_t st_flags; /* user defined flags for file */ |
873 | u_int32_t st_gen; /* file generation number */ |
874 | }; |
875 | |
876 | The time-related fields of struct stat are represented in struct timespec |
877 | format, which has nanosecond precision. However, the actual precision is |
878 | generally limited by the file system holding the file. The fields are as |
879 | follows: |
880 | |
881 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
882 | system object was created and updated by the utimes(2) and |
883 | read(2) system calls. |
884 | |
885 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
886 | truncate(2), utimes(2), and write(2) system calls. For |
887 | directories, changed by any system call that alters which |
888 | files are in the directory, such as the unlink(2), rename(2), |
889 | mkdir(2), and symlink(2) system calls. |
890 | |
891 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
892 | modification). Changed by the chmod(2), chown(2), link(2), |
893 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
894 | |
895 | In addition, all the time fields are set to the current time when a file |
896 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
897 | open(2), and symlink(2) system calls. |
898 | |
899 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
900 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
901 | respective struct timespec member. Deprecated macros are also provided |
902 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
903 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
904 | |
905 | The size-related fields of the struct stat are as follows: |
906 | |
907 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
908 | |
909 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
910 | 512-byte units. As short symbolic links are stored in the |
911 | inode, this number may be zero. |
912 | |
913 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
914 | |
915 | #define S_IFMT 0170000 /* type of file mask */ |
916 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
917 | #define S_IFCHR 0020000 /* character special */ |
918 | #define S_IFDIR 0040000 /* directory */ |
919 | #define S_IFBLK 0060000 /* block special */ |
920 | #define S_IFREG 0100000 /* regular */ |
921 | #define S_IFLNK 0120000 /* symbolic link */ |
922 | #define S_IFSOCK 0140000 /* socket */ |
923 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
924 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
925 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
926 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
927 | #define S_IRUSR 0000400 /* R for owner */ |
928 | #define S_IWUSR 0000200 /* W for owner */ |
929 | #define S_IXUSR 0000100 /* X for owner */ |
930 | #define S_IRWXG 0000070 /* RWX mask for group */ |
931 | #define S_IRGRP 0000040 /* R for group */ |
932 | #define S_IWGRP 0000020 /* W for group */ |
933 | #define S_IXGRP 0000010 /* X for group */ |
934 | #define S_IRWXO 0000007 /* RWX mask for other */ |
935 | #define S_IROTH 0000004 /* R for other */ |
936 | #define S_IWOTH 0000002 /* W for other */ |
937 | #define S_IXOTH 0000001 /* X for other */ |
938 | |
939 | The following macros test a file's type. If the file is of that type, a |
940 | non-zero value is returned; otherwise, 0 is returned. |
941 | |
942 | S_ISBLK(st_mode m) /* block special */ |
943 | S_ISCHR(st_mode m) /* char special */ |
944 | S_ISDIR(st_mode m) /* directory */ |
945 | S_ISFIFO(st_mode m) /* fifo */ |
946 | S_ISLNK(st_mode m) /* symbolic link */ |
947 | S_ISREG(st_mode m) /* regular file */ |
948 | S_ISSOCK(st_mode m) /* socket */ |
949 | |
950 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
951 | |
952 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
953 | Upon successful completion, the value 0 is returned; otherwise the |
954 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
955 | error. |
956 | |
957 | E\bER\bRR\bRO\bOR\bRS\bS |
958 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
959 | |
960 | [ENOTDIR] A component of the path prefix is not a directory. |
961 | |
962 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
963 | characters, or an entire pathname (including the |
964 | terminating NUL) exceeded PATH_MAX bytes. |
965 | |
966 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
967 | empty path. |
968 | |
969 | [EACCES] Search permission is denied for a component of the |
970 | path prefix. |
971 | |
972 | [ELOOP] Too many symbolic links were encountered in |
973 | translating the pathname. |
974 | |
975 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
976 | |
977 | [EIO] An I/O error occurred while reading from or writing to |
978 | the file system. |
979 | |
980 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
981 | |
982 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
983 | AT_SYMLINK_NOFOLLOW. |
984 | |
985 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
986 | argument is neither AT_FDCWD nor a valid file |
987 | descriptor. |
988 | |
989 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
990 | argument is a valid file descriptor but it does not |
991 | reference a directory. |
992 | |
993 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
994 | permission is denied for the directory which the _\bf_\bd |
995 | file descriptor references. |
996 | |
997 | f\bfs\bst\bta\bat\bt() will fail if: |
998 | |
999 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
1000 | |
1001 | [EFAULT] _\bs_\bb points to an invalid address. |
1002 | |
1003 | [EIO] An I/O error occurred while reading from the file |
1004 | system. |
1005 | |
1006 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
1007 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
1008 | |
1009 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
1010 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
1011 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
1012 | |
1013 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
1014 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
1015 | |
1016 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
1017 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
1018 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
1019 | in Version 7 AT&T UNIX. |
1020 | |
1021 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
1022 | appeared in OpenBSD 5.0. |
1023 | |
1024 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
1025 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
1026 | |
1027 | Certain programs written when the timestamps were just of type time_t |
1028 | assumed that the members were consecutive (and could therefore be treated |
1029 | as an array and have their address passed directly to utime(3)). The |
1030 | transition to timestamps of type struct timespec broke them irrevocably. |
1031 | |
1032 | B\bBU\bUG\bGS\bS |
1033 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
1034 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
1035 | the time fields. |
1036 | |
1037 | N\bNA\bAM\bME\bE |
1038 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
1039 | |
1040 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
1041 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
1042 | |
1043 | _\bi_\bn_\bt |
1044 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1045 | |
1046 | _\bi_\bn_\bt |
1047 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1048 | |
1049 | _\bi_\bn_\bt |
1050 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1051 | |
1052 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
1053 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
1054 | |
1055 | _\bi_\bn_\bt |
1056 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
1057 | |
1058 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
1059 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
1060 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
1061 | required, but all directories listed in the path name leading to the file |
1062 | must be searchable. |
1063 | |
1064 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
1065 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
1066 | itself, not the file the link references. |
1067 | |
1068 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
1069 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
1070 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
1071 | determined relative to the directory associated with file descriptor _\bf_\bd |
1072 | instead of the current working directory. |
1073 | |
1074 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
1075 | in the _\bf_\bd parameter, the current working directory is used and the |
1076 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
1077 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
1078 | |
1079 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
1080 | values: |
1081 | |
1082 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
1083 | of the symbolic link is returned. |
1084 | |
1085 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
1086 | known by the file descriptor _\bf_\bd. |
1087 | |
1088 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
1089 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
1090 | concerning the file. |
1091 | |
1092 | struct stat { |
1093 | dev_t st_dev; /* inode's device */ |
1094 | ino_t st_ino; /* inode's number */ |
1095 | mode_t st_mode; /* inode protection mode */ |
1096 | nlink_t st_nlink; /* number of hard links */ |
1097 | uid_t st_uid; /* user ID of the file's owner */ |
1098 | gid_t st_gid; /* group ID of the file's group */ |
1099 | dev_t st_rdev; /* device type */ |
1100 | struct timespec st_atim; /* time of last access */ |
1101 | struct timespec st_mtim; /* time of last data modification */ |
1102 | struct timespec st_ctim; /* time of last file status change */ |
1103 | off_t st_size; /* file size, in bytes */ |
1104 | blkcnt_t st_blocks; /* blocks allocated for file */ |
1105 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
1106 | u_int32_t st_flags; /* user defined flags for file */ |
1107 | u_int32_t st_gen; /* file generation number */ |
1108 | }; |
1109 | |
1110 | The time-related fields of struct stat are represented in struct timespec |
1111 | format, which has nanosecond precision. However, the actual precision is |
1112 | generally limited by the file system holding the file. The fields are as |
1113 | follows: |
1114 | |
1115 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
1116 | system object was created and updated by the utimes(2) and |
1117 | read(2) system calls. |
1118 | |
1119 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
1120 | truncate(2), utimes(2), and write(2) system calls. For |
1121 | directories, changed by any system call that alters which |
1122 | files are in the directory, such as the unlink(2), rename(2), |
1123 | mkdir(2), and symlink(2) system calls. |
1124 | |
1125 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
1126 | modification). Changed by the chmod(2), chown(2), link(2), |
1127 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
1128 | |
1129 | In addition, all the time fields are set to the current time when a file |
1130 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
1131 | open(2), and symlink(2) system calls. |
1132 | |
1133 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
1134 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
1135 | respective struct timespec member. Deprecated macros are also provided |
1136 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
1137 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
1138 | |
1139 | The size-related fields of the struct stat are as follows: |
1140 | |
1141 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
1142 | |
1143 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
1144 | 512-byte units. As short symbolic links are stored in the |
1145 | inode, this number may be zero. |
1146 | |
1147 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
1148 | |
1149 | #define S_IFMT 0170000 /* type of file mask */ |
1150 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
1151 | #define S_IFCHR 0020000 /* character special */ |
1152 | #define S_IFDIR 0040000 /* directory */ |
1153 | #define S_IFBLK 0060000 /* block special */ |
1154 | #define S_IFREG 0100000 /* regular */ |
1155 | #define S_IFLNK 0120000 /* symbolic link */ |
1156 | #define S_IFSOCK 0140000 /* socket */ |
1157 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
1158 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
1159 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
1160 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
1161 | #define S_IRUSR 0000400 /* R for owner */ |
1162 | #define S_IWUSR 0000200 /* W for owner */ |
1163 | #define S_IXUSR 0000100 /* X for owner */ |
1164 | #define S_IRWXG 0000070 /* RWX mask for group */ |
1165 | #define S_IRGRP 0000040 /* R for group */ |
1166 | #define S_IWGRP 0000020 /* W for group */ |
1167 | #define S_IXGRP 0000010 /* X for group */ |
1168 | #define S_IRWXO 0000007 /* RWX mask for other */ |
1169 | #define S_IROTH 0000004 /* R for other */ |
1170 | #define S_IWOTH 0000002 /* W for other */ |
1171 | #define S_IXOTH 0000001 /* X for other */ |
1172 | |
1173 | The following macros test a file's type. If the file is of that type, a |
1174 | non-zero value is returned; otherwise, 0 is returned. |
1175 | |
1176 | S_ISBLK(st_mode m) /* block special */ |
1177 | S_ISCHR(st_mode m) /* char special */ |
1178 | S_ISDIR(st_mode m) /* directory */ |
1179 | S_ISFIFO(st_mode m) /* fifo */ |
1180 | S_ISLNK(st_mode m) /* symbolic link */ |
1181 | S_ISREG(st_mode m) /* regular file */ |
1182 | S_ISSOCK(st_mode m) /* socket */ |
1183 | |
1184 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
1185 | |
1186 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
1187 | Upon successful completion, the value 0 is returned; otherwise the |
1188 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
1189 | error. |
1190 | |
1191 | E\bER\bRR\bRO\bOR\bRS\bS |
1192 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
1193 | |
1194 | [ENOTDIR] A component of the path prefix is not a directory. |
1195 | |
1196 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
1197 | characters, or an entire pathname (including the |
1198 | terminating NUL) exceeded PATH_MAX bytes. |
1199 | |
1200 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
1201 | empty path. |
1202 | |
1203 | [EACCES] Search permission is denied for a component of the |
1204 | path prefix. |
1205 | |
1206 | [ELOOP] Too many symbolic links were encountered in |
1207 | translating the pathname. |
1208 | |
1209 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
1210 | |
1211 | [EIO] An I/O error occurred while reading from or writing to |
1212 | the file system. |
1213 | |
1214 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
1215 | |
1216 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
1217 | AT_SYMLINK_NOFOLLOW. |
1218 | |
1219 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
1220 | argument is neither AT_FDCWD nor a valid file |
1221 | descriptor. |
1222 | |
1223 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
1224 | argument is a valid file descriptor but it does not |
1225 | reference a directory. |
1226 | |
1227 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
1228 | permission is denied for the directory which the _\bf_\bd |
1229 | file descriptor references. |
1230 | |
1231 | f\bfs\bst\bta\bat\bt() will fail if: |
1232 | |
1233 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
1234 | |
1235 | [EFAULT] _\bs_\bb points to an invalid address. |
1236 | |
1237 | [EIO] An I/O error occurred while reading from the file |
1238 | system. |
1239 | |
1240 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
1241 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
1242 | |
1243 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
1244 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
1245 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
1246 | |
1247 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
1248 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
1249 | |
1250 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
1251 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
1252 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
1253 | in Version 7 AT&T UNIX. |
1254 | |
1255 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
1256 | appeared in OpenBSD 5.0. |
1257 | |
1258 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
1259 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
1260 | |
1261 | Certain programs written when the timestamps were just of type time_t |
1262 | assumed that the members were consecutive (and could therefore be treated |
1263 | as an array and have their address passed directly to utime(3)). The |
1264 | transition to timestamps of type struct timespec broke them irrevocably. |
1265 | |
1266 | B\bBU\bUG\bGS\bS |
1267 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
1268 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
1269 | the time fields. |
1270 | |
1271 | N\bNA\bAM\bME\bE |
1272 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
1273 | |
1274 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
1275 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
1276 | |
1277 | _\bi_\bn_\bt |
1278 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1279 | |
1280 | _\bi_\bn_\bt |
1281 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1282 | |
1283 | _\bi_\bn_\bt |
1284 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1285 | |
1286 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
1287 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
1288 | |
1289 | _\bi_\bn_\bt |
1290 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
1291 | |
1292 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
1293 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
1294 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
1295 | required, but all directories listed in the path name leading to the file |
1296 | must be searchable. |
1297 | |
1298 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
1299 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
1300 | itself, not the file the link references. |
1301 | |
1302 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
1303 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
1304 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
1305 | determined relative to the directory associated with file descriptor _\bf_\bd |
1306 | instead of the current working directory. |
1307 | |
1308 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
1309 | in the _\bf_\bd parameter, the current working directory is used and the |
1310 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
1311 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
1312 | |
1313 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
1314 | values: |
1315 | |
1316 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
1317 | of the symbolic link is returned. |
1318 | |
1319 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
1320 | known by the file descriptor _\bf_\bd. |
1321 | |
1322 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
1323 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
1324 | concerning the file. |
1325 | |
1326 | struct stat { |
1327 | dev_t st_dev; /* inode's device */ |
1328 | ino_t st_ino; /* inode's number */ |
1329 | mode_t st_mode; /* inode protection mode */ |
1330 | nlink_t st_nlink; /* number of hard links */ |
1331 | uid_t st_uid; /* user ID of the file's owner */ |
1332 | gid_t st_gid; /* group ID of the file's group */ |
1333 | dev_t st_rdev; /* device type */ |
1334 | struct timespec st_atim; /* time of last access */ |
1335 | struct timespec st_mtim; /* time of last data modification */ |
1336 | struct timespec st_ctim; /* time of last file status change */ |
1337 | off_t st_size; /* file size, in bytes */ |
1338 | blkcnt_t st_blocks; /* blocks allocated for file */ |
1339 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
1340 | u_int32_t st_flags; /* user defined flags for file */ |
1341 | u_int32_t st_gen; /* file generation number */ |
1342 | }; |
1343 | |
1344 | The time-related fields of struct stat are represented in struct timespec |
1345 | format, which has nanosecond precision. However, the actual precision is |
1346 | generally limited by the file system holding the file. The fields are as |
1347 | follows: |
1348 | |
1349 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
1350 | system object was created and updated by the utimes(2) and |
1351 | read(2) system calls. |
1352 | |
1353 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
1354 | truncate(2), utimes(2), and write(2) system calls. For |
1355 | directories, changed by any system call that alters which |
1356 | files are in the directory, such as the unlink(2), rename(2), |
1357 | mkdir(2), and symlink(2) system calls. |
1358 | |
1359 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
1360 | modification). Changed by the chmod(2), chown(2), link(2), |
1361 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
1362 | |
1363 | In addition, all the time fields are set to the current time when a file |
1364 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
1365 | open(2), and symlink(2) system calls. |
1366 | |
1367 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
1368 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
1369 | respective struct timespec member. Deprecated macros are also provided |
1370 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
1371 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
1372 | |
1373 | The size-related fields of the struct stat are as follows: |
1374 | |
1375 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
1376 | |
1377 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
1378 | 512-byte units. As short symbolic links are stored in the |
1379 | inode, this number may be zero. |
1380 | |
1381 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
1382 | |
1383 | #define S_IFMT 0170000 /* type of file mask */ |
1384 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
1385 | #define S_IFCHR 0020000 /* character special */ |
1386 | #define S_IFDIR 0040000 /* directory */ |
1387 | #define S_IFBLK 0060000 /* block special */ |
1388 | #define S_IFREG 0100000 /* regular */ |
1389 | #define S_IFLNK 0120000 /* symbolic link */ |
1390 | #define S_IFSOCK 0140000 /* socket */ |
1391 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
1392 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
1393 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
1394 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
1395 | #define S_IRUSR 0000400 /* R for owner */ |
1396 | #define S_IWUSR 0000200 /* W for owner */ |
1397 | #define S_IXUSR 0000100 /* X for owner */ |
1398 | #define S_IRWXG 0000070 /* RWX mask for group */ |
1399 | #define S_IRGRP 0000040 /* R for group */ |
1400 | #define S_IWGRP 0000020 /* W for group */ |
1401 | #define S_IXGRP 0000010 /* X for group */ |
1402 | #define S_IRWXO 0000007 /* RWX mask for other */ |
1403 | #define S_IROTH 0000004 /* R for other */ |
1404 | #define S_IWOTH 0000002 /* W for other */ |
1405 | #define S_IXOTH 0000001 /* X for other */ |
1406 | |
1407 | The following macros test a file's type. If the file is of that type, a |
1408 | non-zero value is returned; otherwise, 0 is returned. |
1409 | |
1410 | S_ISBLK(st_mode m) /* block special */ |
1411 | S_ISCHR(st_mode m) /* char special */ |
1412 | S_ISDIR(st_mode m) /* directory */ |
1413 | S_ISFIFO(st_mode m) /* fifo */ |
1414 | S_ISLNK(st_mode m) /* symbolic link */ |
1415 | S_ISREG(st_mode m) /* regular file */ |
1416 | S_ISSOCK(st_mode m) /* socket */ |
1417 | |
1418 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
1419 | |
1420 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
1421 | Upon successful completion, the value 0 is returned; otherwise the |
1422 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
1423 | error. |
1424 | |
1425 | E\bER\bRR\bRO\bOR\bRS\bS |
1426 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
1427 | |
1428 | [ENOTDIR] A component of the path prefix is not a directory. |
1429 | |
1430 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
1431 | characters, or an entire pathname (including the |
1432 | terminating NUL) exceeded PATH_MAX bytes. |
1433 | |
1434 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
1435 | empty path. |
1436 | |
1437 | [EACCES] Search permission is denied for a component of the |
1438 | path prefix. |
1439 | |
1440 | [ELOOP] Too many symbolic links were encountered in |
1441 | translating the pathname. |
1442 | |
1443 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
1444 | |
1445 | [EIO] An I/O error occurred while reading from or writing to |
1446 | the file system. |
1447 | |
1448 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
1449 | |
1450 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
1451 | AT_SYMLINK_NOFOLLOW. |
1452 | |
1453 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
1454 | argument is neither AT_FDCWD nor a valid file |
1455 | descriptor. |
1456 | |
1457 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
1458 | argument is a valid file descriptor but it does not |
1459 | reference a directory. |
1460 | |
1461 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
1462 | permission is denied for the directory which the _\bf_\bd |
1463 | file descriptor references. |
1464 | |
1465 | f\bfs\bst\bta\bat\bt() will fail if: |
1466 | |
1467 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
1468 | |
1469 | [EFAULT] _\bs_\bb points to an invalid address. |
1470 | |
1471 | [EIO] An I/O error occurred while reading from the file |
1472 | system. |
1473 | |
1474 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
1475 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
1476 | |
1477 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
1478 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
1479 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
1480 | |
1481 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
1482 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
1483 | |
1484 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
1485 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
1486 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
1487 | in Version 7 AT&T UNIX. |
1488 | |
1489 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
1490 | appeared in OpenBSD 5.0. |
1491 | |
1492 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
1493 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
1494 | |
1495 | Certain programs written when the timestamps were just of type time_t |
1496 | assumed that the members were consecutive (and could therefore be treated |
1497 | as an array and have their address passed directly to utime(3)). The |
1498 | transition to timestamps of type struct timespec broke them irrevocably. |
1499 | |
1500 | B\bBU\bUG\bGS\bS |
1501 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
1502 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
1503 | the time fields. |
1504 | |
1505 | N\bNA\bAM\bME\bE |
1506 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
1507 | |
1508 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
1509 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
1510 | |
1511 | _\bi_\bn_\bt |
1512 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1513 | |
1514 | _\bi_\bn_\bt |
1515 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1516 | |
1517 | _\bi_\bn_\bt |
1518 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1519 | |
1520 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
1521 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
1522 | |
1523 | _\bi_\bn_\bt |
1524 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
1525 | |
1526 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
1527 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
1528 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
1529 | required, but all directories listed in the path name leading to the file |
1530 | must be searchable. |
1531 | |
1532 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
1533 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
1534 | itself, not the file the link references. |
1535 | |
1536 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
1537 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
1538 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
1539 | determined relative to the directory associated with file descriptor _\bf_\bd |
1540 | instead of the current working directory. |
1541 | |
1542 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
1543 | in the _\bf_\bd parameter, the current working directory is used and the |
1544 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
1545 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
1546 | |
1547 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
1548 | values: |
1549 | |
1550 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
1551 | of the symbolic link is returned. |
1552 | |
1553 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
1554 | known by the file descriptor _\bf_\bd. |
1555 | |
1556 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
1557 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
1558 | concerning the file. |
1559 | |
1560 | struct stat { |
1561 | dev_t st_dev; /* inode's device */ |
1562 | ino_t st_ino; /* inode's number */ |
1563 | mode_t st_mode; /* inode protection mode */ |
1564 | nlink_t st_nlink; /* number of hard links */ |
1565 | uid_t st_uid; /* user ID of the file's owner */ |
1566 | gid_t st_gid; /* group ID of the file's group */ |
1567 | dev_t st_rdev; /* device type */ |
1568 | struct timespec st_atim; /* time of last access */ |
1569 | struct timespec st_mtim; /* time of last data modification */ |
1570 | struct timespec st_ctim; /* time of last file status change */ |
1571 | off_t st_size; /* file size, in bytes */ |
1572 | blkcnt_t st_blocks; /* blocks allocated for file */ |
1573 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
1574 | u_int32_t st_flags; /* user defined flags for file */ |
1575 | u_int32_t st_gen; /* file generation number */ |
1576 | }; |
1577 | |
1578 | The time-related fields of struct stat are represented in struct timespec |
1579 | format, which has nanosecond precision. However, the actual precision is |
1580 | generally limited by the file system holding the file. The fields are as |
1581 | follows: |
1582 | |
1583 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
1584 | system object was created and updated by the utimes(2) and |
1585 | read(2) system calls. |
1586 | |
1587 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
1588 | truncate(2), utimes(2), and write(2) system calls. For |
1589 | directories, changed by any system call that alters which |
1590 | files are in the directory, such as the unlink(2), rename(2), |
1591 | mkdir(2), and symlink(2) system calls. |
1592 | |
1593 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
1594 | modification). Changed by the chmod(2), chown(2), link(2), |
1595 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
1596 | |
1597 | In addition, all the time fields are set to the current time when a file |
1598 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
1599 | open(2), and symlink(2) system calls. |
1600 | |
1601 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
1602 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
1603 | respective struct timespec member. Deprecated macros are also provided |
1604 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
1605 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
1606 | |
1607 | The size-related fields of the struct stat are as follows: |
1608 | |
1609 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
1610 | |
1611 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
1612 | 512-byte units. As short symbolic links are stored in the |
1613 | inode, this number may be zero. |
1614 | |
1615 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
1616 | |
1617 | #define S_IFMT 0170000 /* type of file mask */ |
1618 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
1619 | #define S_IFCHR 0020000 /* character special */ |
1620 | #define S_IFDIR 0040000 /* directory */ |
1621 | #define S_IFBLK 0060000 /* block special */ |
1622 | #define S_IFREG 0100000 /* regular */ |
1623 | #define S_IFLNK 0120000 /* symbolic link */ |
1624 | #define S_IFSOCK 0140000 /* socket */ |
1625 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
1626 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
1627 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
1628 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
1629 | #define S_IRUSR 0000400 /* R for owner */ |
1630 | #define S_IWUSR 0000200 /* W for owner */ |
1631 | #define S_IXUSR 0000100 /* X for owner */ |
1632 | #define S_IRWXG 0000070 /* RWX mask for group */ |
1633 | #define S_IRGRP 0000040 /* R for group */ |
1634 | #define S_IWGRP 0000020 /* W for group */ |
1635 | #define S_IXGRP 0000010 /* X for group */ |
1636 | #define S_IRWXO 0000007 /* RWX mask for other */ |
1637 | #define S_IROTH 0000004 /* R for other */ |
1638 | #define S_IWOTH 0000002 /* W for other */ |
1639 | #define S_IXOTH 0000001 /* X for other */ |
1640 | |
1641 | The following macros test a file's type. If the file is of that type, a |
1642 | non-zero value is returned; otherwise, 0 is returned. |
1643 | |
1644 | S_ISBLK(st_mode m) /* block special */ |
1645 | S_ISCHR(st_mode m) /* char special */ |
1646 | S_ISDIR(st_mode m) /* directory */ |
1647 | S_ISFIFO(st_mode m) /* fifo */ |
1648 | S_ISLNK(st_mode m) /* symbolic link */ |
1649 | S_ISREG(st_mode m) /* regular file */ |
1650 | S_ISSOCK(st_mode m) /* socket */ |
1651 | |
1652 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
1653 | |
1654 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
1655 | Upon successful completion, the value 0 is returned; otherwise the |
1656 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
1657 | error. |
1658 | |
1659 | E\bER\bRR\bRO\bOR\bRS\bS |
1660 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
1661 | |
1662 | [ENOTDIR] A component of the path prefix is not a directory. |
1663 | |
1664 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
1665 | characters, or an entire pathname (including the |
1666 | terminating NUL) exceeded PATH_MAX bytes. |
1667 | |
1668 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
1669 | empty path. |
1670 | |
1671 | [EACCES] Search permission is denied for a component of the |
1672 | path prefix. |
1673 | |
1674 | [ELOOP] Too many symbolic links were encountered in |
1675 | translating the pathname. |
1676 | |
1677 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
1678 | |
1679 | [EIO] An I/O error occurred while reading from or writing to |
1680 | the file system. |
1681 | |
1682 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
1683 | |
1684 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
1685 | AT_SYMLINK_NOFOLLOW. |
1686 | |
1687 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
1688 | argument is neither AT_FDCWD nor a valid file |
1689 | descriptor. |
1690 | |
1691 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
1692 | argument is a valid file descriptor but it does not |
1693 | reference a directory. |
1694 | |
1695 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
1696 | permission is denied for the directory which the _\bf_\bd |
1697 | file descriptor references. |
1698 | |
1699 | f\bfs\bst\bta\bat\bt() will fail if: |
1700 | |
1701 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
1702 | |
1703 | [EFAULT] _\bs_\bb points to an invalid address. |
1704 | |
1705 | [EIO] An I/O error occurred while reading from the file |
1706 | system. |
1707 | |
1708 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
1709 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
1710 | |
1711 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
1712 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
1713 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
1714 | |
1715 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
1716 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
1717 | |
1718 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
1719 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
1720 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
1721 | in Version 7 AT&T UNIX. |
1722 | |
1723 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
1724 | appeared in OpenBSD 5.0. |
1725 | |
1726 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
1727 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
1728 | |
1729 | Certain programs written when the timestamps were just of type time_t |
1730 | assumed that the members were consecutive (and could therefore be treated |
1731 | as an array and have their address passed directly to utime(3)). The |
1732 | transition to timestamps of type struct timespec broke them irrevocably. |
1733 | |
1734 | B\bBU\bUG\bGS\bS |
1735 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
1736 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
1737 | the time fields. |
1738 | |
1739 | N\bNA\bAM\bME\bE |
1740 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
1741 | |
1742 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
1743 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
1744 | |
1745 | _\bi_\bn_\bt |
1746 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1747 | |
1748 | _\bi_\bn_\bt |
1749 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1750 | |
1751 | _\bi_\bn_\bt |
1752 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
1753 | |
1754 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
1755 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
1756 | |
1757 | _\bi_\bn_\bt |
1758 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
1759 | |
1760 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
1761 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
1762 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
1763 | required, but all directories listed in the path name leading to the file |
1764 | must be searchable. |
1765 | |
1766 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
1767 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
1768 | itself, not the file the link references. |
1769 | |
1770 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
1771 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
1772 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
1773 | determined relative to the directory associated with file descriptor _\bf_\bd |
1774 | instead of the current working directory. |
1775 | |
1776 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
1777 | in the _\bf_\bd parameter, the current working directory is used and the |
1778 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
1779 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
1780 | |
1781 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
1782 | values: |
1783 | |
1784 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
1785 | of the symbolic link is returned. |
1786 | |
1787 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
1788 | known by the file descriptor _\bf_\bd. |
1789 | |
1790 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
1791 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
1792 | concerning the file. |
1793 | |
1794 | struct stat { |
1795 | dev_t st_dev; /* inode's device */ |
1796 | ino_t st_ino; /* inode's number */ |
1797 | mode_t st_mode; /* inode protection mode */ |
1798 | nlink_t st_nlink; /* number of hard links */ |
1799 | uid_t st_uid; /* user ID of the file's owner */ |
1800 | gid_t st_gid; /* group ID of the file's group */ |
1801 | dev_t st_rdev; /* device type */ |
1802 | struct timespec st_atim; /* time of last access */ |
1803 | struct timespec st_mtim; /* time of last data modification */ |
1804 | struct timespec st_ctim; /* time of last file status change */ |
1805 | off_t st_size; /* file size, in bytes */ |
1806 | blkcnt_t st_blocks; /* blocks allocated for file */ |
1807 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
1808 | u_int32_t st_flags; /* user defined flags for file */ |
1809 | u_int32_t st_gen; /* file generation number */ |
1810 | }; |
1811 | |
1812 | The time-related fields of struct stat are represented in struct timespec |
1813 | format, which has nanosecond precision. However, the actual precision is |
1814 | generally limited by the file system holding the file. The fields are as |
1815 | follows: |
1816 | |
1817 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
1818 | system object was created and updated by the utimes(2) and |
1819 | read(2) system calls. |
1820 | |
1821 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
1822 | truncate(2), utimes(2), and write(2) system calls. For |
1823 | directories, changed by any system call that alters which |
1824 | files are in the directory, such as the unlink(2), rename(2), |
1825 | mkdir(2), and symlink(2) system calls. |
1826 | |
1827 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
1828 | modification). Changed by the chmod(2), chown(2), link(2), |
1829 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
1830 | |
1831 | In addition, all the time fields are set to the current time when a file |
1832 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
1833 | open(2), and symlink(2) system calls. |
1834 | |
1835 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
1836 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
1837 | respective struct timespec member. Deprecated macros are also provided |
1838 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
1839 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
1840 | |
1841 | The size-related fields of the struct stat are as follows: |
1842 | |
1843 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
1844 | |
1845 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
1846 | 512-byte units. As short symbolic links are stored in the |
1847 | inode, this number may be zero. |
1848 | |
1849 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
1850 | |
1851 | #define S_IFMT 0170000 /* type of file mask */ |
1852 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
1853 | #define S_IFCHR 0020000 /* character special */ |
1854 | #define S_IFDIR 0040000 /* directory */ |
1855 | #define S_IFBLK 0060000 /* block special */ |
1856 | #define S_IFREG 0100000 /* regular */ |
1857 | #define S_IFLNK 0120000 /* symbolic link */ |
1858 | #define S_IFSOCK 0140000 /* socket */ |
1859 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
1860 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
1861 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
1862 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
1863 | #define S_IRUSR 0000400 /* R for owner */ |
1864 | #define S_IWUSR 0000200 /* W for owner */ |
1865 | #define S_IXUSR 0000100 /* X for owner */ |
1866 | #define S_IRWXG 0000070 /* RWX mask for group */ |
1867 | #define S_IRGRP 0000040 /* R for group */ |
1868 | #define S_IWGRP 0000020 /* W for group */ |
1869 | #define S_IXGRP 0000010 /* X for group */ |
1870 | #define S_IRWXO 0000007 /* RWX mask for other */ |
1871 | #define S_IROTH 0000004 /* R for other */ |
1872 | #define S_IWOTH 0000002 /* W for other */ |
1873 | #define S_IXOTH 0000001 /* X for other */ |
1874 | |
1875 | The following macros test a file's type. If the file is of that type, a |
1876 | non-zero value is returned; otherwise, 0 is returned. |
1877 | |
1878 | S_ISBLK(st_mode m) /* block special */ |
1879 | S_ISCHR(st_mode m) /* char special */ |
1880 | S_ISDIR(st_mode m) /* directory */ |
1881 | S_ISFIFO(st_mode m) /* fifo */ |
1882 | S_ISLNK(st_mode m) /* symbolic link */ |
1883 | S_ISREG(st_mode m) /* regular file */ |
1884 | S_ISSOCK(st_mode m) /* socket */ |
1885 | |
1886 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
1887 | |
1888 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
1889 | Upon successful completion, the value 0 is returned; otherwise the |
1890 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
1891 | error. |
1892 | |
1893 | E\bER\bRR\bRO\bOR\bRS\bS |
1894 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
1895 | |
1896 | [ENOTDIR] A component of the path prefix is not a directory. |
1897 | |
1898 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
1899 | characters, or an entire pathname (including the |
1900 | terminating NUL) exceeded PATH_MAX bytes. |
1901 | |
1902 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
1903 | empty path. |
1904 | |
1905 | [EACCES] Search permission is denied for a component of the |
1906 | path prefix. |
1907 | |
1908 | [ELOOP] Too many symbolic links were encountered in |
1909 | translating the pathname. |
1910 | |
1911 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
1912 | |
1913 | [EIO] An I/O error occurred while reading from or writing to |
1914 | the file system. |
1915 | |
1916 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
1917 | |
1918 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
1919 | AT_SYMLINK_NOFOLLOW. |
1920 | |
1921 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
1922 | argument is neither AT_FDCWD nor a valid file |
1923 | descriptor. |
1924 | |
1925 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
1926 | argument is a valid file descriptor but it does not |
1927 | reference a directory. |
1928 | |
1929 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
1930 | permission is denied for the directory which the _\bf_\bd |
1931 | file descriptor references. |
1932 | |
1933 | f\bfs\bst\bta\bat\bt() will fail if: |
1934 | |
1935 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
1936 | |
1937 | [EFAULT] _\bs_\bb points to an invalid address. |
1938 | |
1939 | [EIO] An I/O error occurred while reading from the file |
1940 | system. |
1941 | |
1942 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
1943 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
1944 | |
1945 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
1946 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
1947 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
1948 | |
1949 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
1950 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
1951 | |
1952 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
1953 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
1954 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
1955 | in Version 7 AT&T UNIX. |
1956 | |
1957 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
1958 | appeared in OpenBSD 5.0. |
1959 | |
1960 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
1961 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
1962 | |
1963 | Certain programs written when the timestamps were just of type time_t |
1964 | assumed that the members were consecutive (and could therefore be treated |
1965 | as an array and have their address passed directly to utime(3)). The |
1966 | transition to timestamps of type struct timespec broke them irrevocably. |
1967 | |
1968 | B\bBU\bUG\bGS\bS |
1969 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
1970 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
1971 | the time fields. |
1972 | |
1973 | N\bNA\bAM\bME\bE |
1974 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
1975 | |
1976 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
1977 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
1978 | |
1979 | _\bp_\bi_\bd_\b__\bt |
1980 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
1981 | |
1982 | _\bp_\bi_\bd_\b__\bt |
1983 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
1984 | |
1985 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
1986 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
1987 | |
1988 | _\bp_\bi_\bd_\b__\bt |
1989 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
1990 | |
1991 | _\bp_\bi_\bd_\b__\bt |
1992 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
1993 | |
1994 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
1995 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
1996 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
1997 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
1998 | area, if non-zero, is filled in with termination information about the |
1999 | process that exited (see below). |
2000 | |
2001 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
2002 | to wait for certain child processes, that need resource utilization |
2003 | statistics accumulated by child processes, or that require options. The |
2004 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
2005 | |
2006 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
2007 | wait. The following symbolic constants are currently defined in |
2008 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
2009 | |
2010 | #define WAIT_ANY (-1) /* any process */ |
2011 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
2012 | |
2013 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
2014 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
2015 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
2016 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
2017 | call waits for any process whose process group ID equals the absolute |
2018 | value of _\bw_\bp_\bi_\bd. |
2019 | |
2020 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
2021 | bitwise OR of zero or more of the following values: |
2022 | |
2023 | WCONTINUED Causes status to be reported for stopped child processes that |
2024 | have been continued by receipt of a SIGCONT signal. |
2025 | |
2026 | WNOHANG Indicates that the call should not block if there are no |
2027 | processes that wish to report status. |
2028 | |
2029 | WUNTRACED If set, children of the current process that are stopped due |
2030 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
2031 | their status reported. |
2032 | |
2033 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
2034 | process and all its children is returned (this information is currently |
2035 | not available for stopped processes). |
2036 | |
2037 | When the WNOHANG option is specified and no processes wish to report |
2038 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
2039 | |
2040 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
2041 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
2042 | |
2043 | The following macros may be used to test the manner of exit of the |
2044 | process. One of the first three macros will evaluate to a non-zero |
2045 | (true) value: |
2046 | |
2047 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2048 | True if the process has not terminated, and has continued after a |
2049 | job control stop. This macro can be true only if the wait call |
2050 | specified the WCONTINUED option. |
2051 | |
2052 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2053 | True if the process terminated normally by a call to _exit(2) or |
2054 | exit(3). |
2055 | |
2056 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2057 | True if the process terminated due to receipt of a signal. |
2058 | |
2059 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2060 | True if the process has not terminated, but has stopped and can |
2061 | be restarted. This macro can be true only if the wait call |
2062 | specified the WUNTRACED option or if the child process is being |
2063 | traced (see ptrace(2)). |
2064 | |
2065 | Depending on the values of those macros, the following macros produce the |
2066 | remaining status information about the child process: |
2067 | |
2068 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
2069 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
2070 | of the argument passed to _exit(2) or exit(3) by the child. |
2071 | |
2072 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2073 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2074 | signal that caused the termination of the process. |
2075 | |
2076 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
2077 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
2078 | termination of the process was accompanied by the creation of a |
2079 | core file containing an image of the process when the signal was |
2080 | received. |
2081 | |
2082 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2083 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2084 | signal that caused the process to stop. |
2085 | |
2086 | N\bNO\bOT\bTE\bES\bS |
2087 | See sigaction(2) for a list of termination signals. A status of 0 |
2088 | indicates normal termination. |
2089 | |
2090 | If a parent process terminates without waiting for all of its child |
2091 | processes to terminate, the remaining child processes are assigned the |
2092 | parent process 1 ID (the init process ID). |
2093 | |
2094 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
2095 | may be interrupted or restarted when the signal-catching routine returns, |
2096 | depending on the options in effect for the signal; for further |
2097 | information, see siginterrupt(3). |
2098 | |
2099 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
2100 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
2101 | process ID of the child is returned to the calling process. Otherwise, a |
2102 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2103 | |
2104 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
2105 | child process, the process ID of the child is returned to the calling |
2106 | process. If there are no children not previously awaited, -1 is returned |
2107 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
2108 | are no stopped or exited children, 0 is returned. If an error is |
2109 | detected or a caught signal aborts the call, a value of -1 is returned |
2110 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2111 | |
2112 | E\bER\bRR\bRO\bOR\bRS\bS |
2113 | w\bwa\bai\bit\bt() will fail and return immediately if: |
2114 | |
2115 | [ECHILD] The calling process has no existing unwaited-for child |
2116 | processes. |
2117 | |
2118 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
2119 | address. (May not be detected before exit of a child |
2120 | process.) |
2121 | |
2122 | [EINTR] The call was interrupted by a caught signal, or the |
2123 | signal did not have the SA_RESTART flag set. |
2124 | |
2125 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
2126 | argument. |
2127 | |
2128 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
2129 | _exit(2), sigaction(2), exit(3) |
2130 | |
2131 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
2132 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
2133 | (``POSIX.1''). |
2134 | |
2135 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
2136 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
2137 | specification. |
2138 | |
2139 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
2140 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
2141 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
2142 | first appeared in 4BSD, but the final calling convention was only |
2143 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
2144 | appeared in 4.3BSD-Reno. |
2145 | |
2146 | N\bNA\bAM\bME\bE |
2147 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
2148 | |
2149 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
2150 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2151 | |
2152 | _\bp_\bi_\bd_\b__\bt |
2153 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
2154 | |
2155 | _\bp_\bi_\bd_\b__\bt |
2156 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
2157 | |
2158 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
2159 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2160 | |
2161 | _\bp_\bi_\bd_\b__\bt |
2162 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2163 | |
2164 | _\bp_\bi_\bd_\b__\bt |
2165 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2166 | |
2167 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
2168 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
2169 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
2170 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
2171 | area, if non-zero, is filled in with termination information about the |
2172 | process that exited (see below). |
2173 | |
2174 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
2175 | to wait for certain child processes, that need resource utilization |
2176 | statistics accumulated by child processes, or that require options. The |
2177 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
2178 | |
2179 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
2180 | wait. The following symbolic constants are currently defined in |
2181 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
2182 | |
2183 | #define WAIT_ANY (-1) /* any process */ |
2184 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
2185 | |
2186 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
2187 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
2188 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
2189 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
2190 | call waits for any process whose process group ID equals the absolute |
2191 | value of _\bw_\bp_\bi_\bd. |
2192 | |
2193 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
2194 | bitwise OR of zero or more of the following values: |
2195 | |
2196 | WCONTINUED Causes status to be reported for stopped child processes that |
2197 | have been continued by receipt of a SIGCONT signal. |
2198 | |
2199 | WNOHANG Indicates that the call should not block if there are no |
2200 | processes that wish to report status. |
2201 | |
2202 | WUNTRACED If set, children of the current process that are stopped due |
2203 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
2204 | their status reported. |
2205 | |
2206 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
2207 | process and all its children is returned (this information is currently |
2208 | not available for stopped processes). |
2209 | |
2210 | When the WNOHANG option is specified and no processes wish to report |
2211 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
2212 | |
2213 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
2214 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
2215 | |
2216 | The following macros may be used to test the manner of exit of the |
2217 | process. One of the first three macros will evaluate to a non-zero |
2218 | (true) value: |
2219 | |
2220 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2221 | True if the process has not terminated, and has continued after a |
2222 | job control stop. This macro can be true only if the wait call |
2223 | specified the WCONTINUED option. |
2224 | |
2225 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2226 | True if the process terminated normally by a call to _exit(2) or |
2227 | exit(3). |
2228 | |
2229 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2230 | True if the process terminated due to receipt of a signal. |
2231 | |
2232 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2233 | True if the process has not terminated, but has stopped and can |
2234 | be restarted. This macro can be true only if the wait call |
2235 | specified the WUNTRACED option or if the child process is being |
2236 | traced (see ptrace(2)). |
2237 | |
2238 | Depending on the values of those macros, the following macros produce the |
2239 | remaining status information about the child process: |
2240 | |
2241 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
2242 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
2243 | of the argument passed to _exit(2) or exit(3) by the child. |
2244 | |
2245 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2246 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2247 | signal that caused the termination of the process. |
2248 | |
2249 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
2250 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
2251 | termination of the process was accompanied by the creation of a |
2252 | core file containing an image of the process when the signal was |
2253 | received. |
2254 | |
2255 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2256 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2257 | signal that caused the process to stop. |
2258 | |
2259 | N\bNO\bOT\bTE\bES\bS |
2260 | See sigaction(2) for a list of termination signals. A status of 0 |
2261 | indicates normal termination. |
2262 | |
2263 | If a parent process terminates without waiting for all of its child |
2264 | processes to terminate, the remaining child processes are assigned the |
2265 | parent process 1 ID (the init process ID). |
2266 | |
2267 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
2268 | may be interrupted or restarted when the signal-catching routine returns, |
2269 | depending on the options in effect for the signal; for further |
2270 | information, see siginterrupt(3). |
2271 | |
2272 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
2273 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
2274 | process ID of the child is returned to the calling process. Otherwise, a |
2275 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2276 | |
2277 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
2278 | child process, the process ID of the child is returned to the calling |
2279 | process. If there are no children not previously awaited, -1 is returned |
2280 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
2281 | are no stopped or exited children, 0 is returned. If an error is |
2282 | detected or a caught signal aborts the call, a value of -1 is returned |
2283 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2284 | |
2285 | E\bER\bRR\bRO\bOR\bRS\bS |
2286 | w\bwa\bai\bit\bt() will fail and return immediately if: |
2287 | |
2288 | [ECHILD] The calling process has no existing unwaited-for child |
2289 | processes. |
2290 | |
2291 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
2292 | address. (May not be detected before exit of a child |
2293 | process.) |
2294 | |
2295 | [EINTR] The call was interrupted by a caught signal, or the |
2296 | signal did not have the SA_RESTART flag set. |
2297 | |
2298 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
2299 | argument. |
2300 | |
2301 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
2302 | _exit(2), sigaction(2), exit(3) |
2303 | |
2304 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
2305 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
2306 | (``POSIX.1''). |
2307 | |
2308 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
2309 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
2310 | specification. |
2311 | |
2312 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
2313 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
2314 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
2315 | first appeared in 4BSD, but the final calling convention was only |
2316 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
2317 | appeared in 4.3BSD-Reno. |
2318 | |
2319 | N\bNA\bAM\bME\bE |
2320 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
2321 | |
2322 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
2323 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2324 | |
2325 | _\bp_\bi_\bd_\b__\bt |
2326 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
2327 | |
2328 | _\bp_\bi_\bd_\b__\bt |
2329 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
2330 | |
2331 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
2332 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2333 | |
2334 | _\bp_\bi_\bd_\b__\bt |
2335 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2336 | |
2337 | _\bp_\bi_\bd_\b__\bt |
2338 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2339 | |
2340 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
2341 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
2342 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
2343 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
2344 | area, if non-zero, is filled in with termination information about the |
2345 | process that exited (see below). |
2346 | |
2347 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
2348 | to wait for certain child processes, that need resource utilization |
2349 | statistics accumulated by child processes, or that require options. The |
2350 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
2351 | |
2352 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
2353 | wait. The following symbolic constants are currently defined in |
2354 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
2355 | |
2356 | #define WAIT_ANY (-1) /* any process */ |
2357 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
2358 | |
2359 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
2360 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
2361 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
2362 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
2363 | call waits for any process whose process group ID equals the absolute |
2364 | value of _\bw_\bp_\bi_\bd. |
2365 | |
2366 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
2367 | bitwise OR of zero or more of the following values: |
2368 | |
2369 | WCONTINUED Causes status to be reported for stopped child processes that |
2370 | have been continued by receipt of a SIGCONT signal. |
2371 | |
2372 | WNOHANG Indicates that the call should not block if there are no |
2373 | processes that wish to report status. |
2374 | |
2375 | WUNTRACED If set, children of the current process that are stopped due |
2376 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
2377 | their status reported. |
2378 | |
2379 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
2380 | process and all its children is returned (this information is currently |
2381 | not available for stopped processes). |
2382 | |
2383 | When the WNOHANG option is specified and no processes wish to report |
2384 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
2385 | |
2386 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
2387 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
2388 | |
2389 | The following macros may be used to test the manner of exit of the |
2390 | process. One of the first three macros will evaluate to a non-zero |
2391 | (true) value: |
2392 | |
2393 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2394 | True if the process has not terminated, and has continued after a |
2395 | job control stop. This macro can be true only if the wait call |
2396 | specified the WCONTINUED option. |
2397 | |
2398 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2399 | True if the process terminated normally by a call to _exit(2) or |
2400 | exit(3). |
2401 | |
2402 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2403 | True if the process terminated due to receipt of a signal. |
2404 | |
2405 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2406 | True if the process has not terminated, but has stopped and can |
2407 | be restarted. This macro can be true only if the wait call |
2408 | specified the WUNTRACED option or if the child process is being |
2409 | traced (see ptrace(2)). |
2410 | |
2411 | Depending on the values of those macros, the following macros produce the |
2412 | remaining status information about the child process: |
2413 | |
2414 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
2415 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
2416 | of the argument passed to _exit(2) or exit(3) by the child. |
2417 | |
2418 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2419 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2420 | signal that caused the termination of the process. |
2421 | |
2422 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
2423 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
2424 | termination of the process was accompanied by the creation of a |
2425 | core file containing an image of the process when the signal was |
2426 | received. |
2427 | |
2428 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2429 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2430 | signal that caused the process to stop. |
2431 | |
2432 | N\bNO\bOT\bTE\bES\bS |
2433 | See sigaction(2) for a list of termination signals. A status of 0 |
2434 | indicates normal termination. |
2435 | |
2436 | If a parent process terminates without waiting for all of its child |
2437 | processes to terminate, the remaining child processes are assigned the |
2438 | parent process 1 ID (the init process ID). |
2439 | |
2440 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
2441 | may be interrupted or restarted when the signal-catching routine returns, |
2442 | depending on the options in effect for the signal; for further |
2443 | information, see siginterrupt(3). |
2444 | |
2445 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
2446 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
2447 | process ID of the child is returned to the calling process. Otherwise, a |
2448 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2449 | |
2450 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
2451 | child process, the process ID of the child is returned to the calling |
2452 | process. If there are no children not previously awaited, -1 is returned |
2453 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
2454 | are no stopped or exited children, 0 is returned. If an error is |
2455 | detected or a caught signal aborts the call, a value of -1 is returned |
2456 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2457 | |
2458 | E\bER\bRR\bRO\bOR\bRS\bS |
2459 | w\bwa\bai\bit\bt() will fail and return immediately if: |
2460 | |
2461 | [ECHILD] The calling process has no existing unwaited-for child |
2462 | processes. |
2463 | |
2464 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
2465 | address. (May not be detected before exit of a child |
2466 | process.) |
2467 | |
2468 | [EINTR] The call was interrupted by a caught signal, or the |
2469 | signal did not have the SA_RESTART flag set. |
2470 | |
2471 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
2472 | argument. |
2473 | |
2474 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
2475 | _exit(2), sigaction(2), exit(3) |
2476 | |
2477 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
2478 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
2479 | (``POSIX.1''). |
2480 | |
2481 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
2482 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
2483 | specification. |
2484 | |
2485 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
2486 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
2487 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
2488 | first appeared in 4BSD, but the final calling convention was only |
2489 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
2490 | appeared in 4.3BSD-Reno. |
2491 | |
2492 | N\bNA\bAM\bME\bE |
2493 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
2494 | |
2495 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
2496 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2497 | |
2498 | _\bp_\bi_\bd_\b__\bt |
2499 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
2500 | |
2501 | _\bp_\bi_\bd_\b__\bt |
2502 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
2503 | |
2504 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
2505 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2506 | |
2507 | _\bp_\bi_\bd_\b__\bt |
2508 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2509 | |
2510 | _\bp_\bi_\bd_\b__\bt |
2511 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2512 | |
2513 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
2514 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
2515 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
2516 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
2517 | area, if non-zero, is filled in with termination information about the |
2518 | process that exited (see below). |
2519 | |
2520 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
2521 | to wait for certain child processes, that need resource utilization |
2522 | statistics accumulated by child processes, or that require options. The |
2523 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
2524 | |
2525 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
2526 | wait. The following symbolic constants are currently defined in |
2527 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
2528 | |
2529 | #define WAIT_ANY (-1) /* any process */ |
2530 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
2531 | |
2532 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
2533 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
2534 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
2535 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
2536 | call waits for any process whose process group ID equals the absolute |
2537 | value of _\bw_\bp_\bi_\bd. |
2538 | |
2539 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
2540 | bitwise OR of zero or more of the following values: |
2541 | |
2542 | WCONTINUED Causes status to be reported for stopped child processes that |
2543 | have been continued by receipt of a SIGCONT signal. |
2544 | |
2545 | WNOHANG Indicates that the call should not block if there are no |
2546 | processes that wish to report status. |
2547 | |
2548 | WUNTRACED If set, children of the current process that are stopped due |
2549 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
2550 | their status reported. |
2551 | |
2552 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
2553 | process and all its children is returned (this information is currently |
2554 | not available for stopped processes). |
2555 | |
2556 | When the WNOHANG option is specified and no processes wish to report |
2557 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
2558 | |
2559 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
2560 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
2561 | |
2562 | The following macros may be used to test the manner of exit of the |
2563 | process. One of the first three macros will evaluate to a non-zero |
2564 | (true) value: |
2565 | |
2566 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2567 | True if the process has not terminated, and has continued after a |
2568 | job control stop. This macro can be true only if the wait call |
2569 | specified the WCONTINUED option. |
2570 | |
2571 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2572 | True if the process terminated normally by a call to _exit(2) or |
2573 | exit(3). |
2574 | |
2575 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2576 | True if the process terminated due to receipt of a signal. |
2577 | |
2578 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2579 | True if the process has not terminated, but has stopped and can |
2580 | be restarted. This macro can be true only if the wait call |
2581 | specified the WUNTRACED option or if the child process is being |
2582 | traced (see ptrace(2)). |
2583 | |
2584 | Depending on the values of those macros, the following macros produce the |
2585 | remaining status information about the child process: |
2586 | |
2587 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
2588 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
2589 | of the argument passed to _exit(2) or exit(3) by the child. |
2590 | |
2591 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2592 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2593 | signal that caused the termination of the process. |
2594 | |
2595 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
2596 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
2597 | termination of the process was accompanied by the creation of a |
2598 | core file containing an image of the process when the signal was |
2599 | received. |
2600 | |
2601 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2602 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2603 | signal that caused the process to stop. |
2604 | |
2605 | N\bNO\bOT\bTE\bES\bS |
2606 | See sigaction(2) for a list of termination signals. A status of 0 |
2607 | indicates normal termination. |
2608 | |
2609 | If a parent process terminates without waiting for all of its child |
2610 | processes to terminate, the remaining child processes are assigned the |
2611 | parent process 1 ID (the init process ID). |
2612 | |
2613 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
2614 | may be interrupted or restarted when the signal-catching routine returns, |
2615 | depending on the options in effect for the signal; for further |
2616 | information, see siginterrupt(3). |
2617 | |
2618 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
2619 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
2620 | process ID of the child is returned to the calling process. Otherwise, a |
2621 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2622 | |
2623 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
2624 | child process, the process ID of the child is returned to the calling |
2625 | process. If there are no children not previously awaited, -1 is returned |
2626 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
2627 | are no stopped or exited children, 0 is returned. If an error is |
2628 | detected or a caught signal aborts the call, a value of -1 is returned |
2629 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2630 | |
2631 | E\bER\bRR\bRO\bOR\bRS\bS |
2632 | w\bwa\bai\bit\bt() will fail and return immediately if: |
2633 | |
2634 | [ECHILD] The calling process has no existing unwaited-for child |
2635 | processes. |
2636 | |
2637 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
2638 | address. (May not be detected before exit of a child |
2639 | process.) |
2640 | |
2641 | [EINTR] The call was interrupted by a caught signal, or the |
2642 | signal did not have the SA_RESTART flag set. |
2643 | |
2644 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
2645 | argument. |
2646 | |
2647 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
2648 | _exit(2), sigaction(2), exit(3) |
2649 | |
2650 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
2651 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
2652 | (``POSIX.1''). |
2653 | |
2654 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
2655 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
2656 | specification. |
2657 | |
2658 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
2659 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
2660 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
2661 | first appeared in 4BSD, but the final calling convention was only |
2662 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
2663 | appeared in 4.3BSD-Reno. |
2664 | |
2665 | N\bNA\bAM\bME\bE |
2666 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
2667 | |
2668 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
2669 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2670 | |
2671 | _\bp_\bi_\bd_\b__\bt |
2672 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
2673 | |
2674 | _\bp_\bi_\bd_\b__\bt |
2675 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
2676 | |
2677 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
2678 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2679 | |
2680 | _\bp_\bi_\bd_\b__\bt |
2681 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2682 | |
2683 | _\bp_\bi_\bd_\b__\bt |
2684 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2685 | |
2686 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
2687 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
2688 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
2689 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
2690 | area, if non-zero, is filled in with termination information about the |
2691 | process that exited (see below). |
2692 | |
2693 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
2694 | to wait for certain child processes, that need resource utilization |
2695 | statistics accumulated by child processes, or that require options. The |
2696 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
2697 | |
2698 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
2699 | wait. The following symbolic constants are currently defined in |
2700 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
2701 | |
2702 | #define WAIT_ANY (-1) /* any process */ |
2703 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
2704 | |
2705 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
2706 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
2707 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
2708 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
2709 | call waits for any process whose process group ID equals the absolute |
2710 | value of _\bw_\bp_\bi_\bd. |
2711 | |
2712 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
2713 | bitwise OR of zero or more of the following values: |
2714 | |
2715 | WCONTINUED Causes status to be reported for stopped child processes that |
2716 | have been continued by receipt of a SIGCONT signal. |
2717 | |
2718 | WNOHANG Indicates that the call should not block if there are no |
2719 | processes that wish to report status. |
2720 | |
2721 | WUNTRACED If set, children of the current process that are stopped due |
2722 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
2723 | their status reported. |
2724 | |
2725 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
2726 | process and all its children is returned (this information is currently |
2727 | not available for stopped processes). |
2728 | |
2729 | When the WNOHANG option is specified and no processes wish to report |
2730 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
2731 | |
2732 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
2733 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
2734 | |
2735 | The following macros may be used to test the manner of exit of the |
2736 | process. One of the first three macros will evaluate to a non-zero |
2737 | (true) value: |
2738 | |
2739 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2740 | True if the process has not terminated, and has continued after a |
2741 | job control stop. This macro can be true only if the wait call |
2742 | specified the WCONTINUED option. |
2743 | |
2744 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2745 | True if the process terminated normally by a call to _exit(2) or |
2746 | exit(3). |
2747 | |
2748 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2749 | True if the process terminated due to receipt of a signal. |
2750 | |
2751 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2752 | True if the process has not terminated, but has stopped and can |
2753 | be restarted. This macro can be true only if the wait call |
2754 | specified the WUNTRACED option or if the child process is being |
2755 | traced (see ptrace(2)). |
2756 | |
2757 | Depending on the values of those macros, the following macros produce the |
2758 | remaining status information about the child process: |
2759 | |
2760 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
2761 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
2762 | of the argument passed to _exit(2) or exit(3) by the child. |
2763 | |
2764 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2765 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2766 | signal that caused the termination of the process. |
2767 | |
2768 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
2769 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
2770 | termination of the process was accompanied by the creation of a |
2771 | core file containing an image of the process when the signal was |
2772 | received. |
2773 | |
2774 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2775 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2776 | signal that caused the process to stop. |
2777 | |
2778 | N\bNO\bOT\bTE\bES\bS |
2779 | See sigaction(2) for a list of termination signals. A status of 0 |
2780 | indicates normal termination. |
2781 | |
2782 | If a parent process terminates without waiting for all of its child |
2783 | processes to terminate, the remaining child processes are assigned the |
2784 | parent process 1 ID (the init process ID). |
2785 | |
2786 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
2787 | may be interrupted or restarted when the signal-catching routine returns, |
2788 | depending on the options in effect for the signal; for further |
2789 | information, see siginterrupt(3). |
2790 | |
2791 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
2792 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
2793 | process ID of the child is returned to the calling process. Otherwise, a |
2794 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2795 | |
2796 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
2797 | child process, the process ID of the child is returned to the calling |
2798 | process. If there are no children not previously awaited, -1 is returned |
2799 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
2800 | are no stopped or exited children, 0 is returned. If an error is |
2801 | detected or a caught signal aborts the call, a value of -1 is returned |
2802 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2803 | |
2804 | E\bER\bRR\bRO\bOR\bRS\bS |
2805 | w\bwa\bai\bit\bt() will fail and return immediately if: |
2806 | |
2807 | [ECHILD] The calling process has no existing unwaited-for child |
2808 | processes. |
2809 | |
2810 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
2811 | address. (May not be detected before exit of a child |
2812 | process.) |
2813 | |
2814 | [EINTR] The call was interrupted by a caught signal, or the |
2815 | signal did not have the SA_RESTART flag set. |
2816 | |
2817 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
2818 | argument. |
2819 | |
2820 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
2821 | _exit(2), sigaction(2), exit(3) |
2822 | |
2823 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
2824 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
2825 | (``POSIX.1''). |
2826 | |
2827 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
2828 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
2829 | specification. |
2830 | |
2831 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
2832 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
2833 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
2834 | first appeared in 4BSD, but the final calling convention was only |
2835 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
2836 | appeared in 4.3BSD-Reno. |
2837 | |
2838 | N\bNA\bAM\bME\bE |
2839 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
2840 | |
2841 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
2842 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2843 | |
2844 | _\bp_\bi_\bd_\b__\bt |
2845 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
2846 | |
2847 | _\bp_\bi_\bd_\b__\bt |
2848 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
2849 | |
2850 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
2851 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
2852 | |
2853 | _\bp_\bi_\bd_\b__\bt |
2854 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2855 | |
2856 | _\bp_\bi_\bd_\b__\bt |
2857 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
2858 | |
2859 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
2860 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
2861 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
2862 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
2863 | area, if non-zero, is filled in with termination information about the |
2864 | process that exited (see below). |
2865 | |
2866 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
2867 | to wait for certain child processes, that need resource utilization |
2868 | statistics accumulated by child processes, or that require options. The |
2869 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
2870 | |
2871 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
2872 | wait. The following symbolic constants are currently defined in |
2873 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
2874 | |
2875 | #define WAIT_ANY (-1) /* any process */ |
2876 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
2877 | |
2878 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
2879 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
2880 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
2881 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
2882 | call waits for any process whose process group ID equals the absolute |
2883 | value of _\bw_\bp_\bi_\bd. |
2884 | |
2885 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
2886 | bitwise OR of zero or more of the following values: |
2887 | |
2888 | WCONTINUED Causes status to be reported for stopped child processes that |
2889 | have been continued by receipt of a SIGCONT signal. |
2890 | |
2891 | WNOHANG Indicates that the call should not block if there are no |
2892 | processes that wish to report status. |
2893 | |
2894 | WUNTRACED If set, children of the current process that are stopped due |
2895 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
2896 | their status reported. |
2897 | |
2898 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
2899 | process and all its children is returned (this information is currently |
2900 | not available for stopped processes). |
2901 | |
2902 | When the WNOHANG option is specified and no processes wish to report |
2903 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
2904 | |
2905 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
2906 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
2907 | |
2908 | The following macros may be used to test the manner of exit of the |
2909 | process. One of the first three macros will evaluate to a non-zero |
2910 | (true) value: |
2911 | |
2912 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2913 | True if the process has not terminated, and has continued after a |
2914 | job control stop. This macro can be true only if the wait call |
2915 | specified the WCONTINUED option. |
2916 | |
2917 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2918 | True if the process terminated normally by a call to _exit(2) or |
2919 | exit(3). |
2920 | |
2921 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2922 | True if the process terminated due to receipt of a signal. |
2923 | |
2924 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
2925 | True if the process has not terminated, but has stopped and can |
2926 | be restarted. This macro can be true only if the wait call |
2927 | specified the WUNTRACED option or if the child process is being |
2928 | traced (see ptrace(2)). |
2929 | |
2930 | Depending on the values of those macros, the following macros produce the |
2931 | remaining status information about the child process: |
2932 | |
2933 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
2934 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
2935 | of the argument passed to _exit(2) or exit(3) by the child. |
2936 | |
2937 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2938 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2939 | signal that caused the termination of the process. |
2940 | |
2941 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
2942 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
2943 | termination of the process was accompanied by the creation of a |
2944 | core file containing an image of the process when the signal was |
2945 | received. |
2946 | |
2947 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
2948 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
2949 | signal that caused the process to stop. |
2950 | |
2951 | N\bNO\bOT\bTE\bES\bS |
2952 | See sigaction(2) for a list of termination signals. A status of 0 |
2953 | indicates normal termination. |
2954 | |
2955 | If a parent process terminates without waiting for all of its child |
2956 | processes to terminate, the remaining child processes are assigned the |
2957 | parent process 1 ID (the init process ID). |
2958 | |
2959 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
2960 | may be interrupted or restarted when the signal-catching routine returns, |
2961 | depending on the options in effect for the signal; for further |
2962 | information, see siginterrupt(3). |
2963 | |
2964 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
2965 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
2966 | process ID of the child is returned to the calling process. Otherwise, a |
2967 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2968 | |
2969 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
2970 | child process, the process ID of the child is returned to the calling |
2971 | process. If there are no children not previously awaited, -1 is returned |
2972 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
2973 | are no stopped or exited children, 0 is returned. If an error is |
2974 | detected or a caught signal aborts the call, a value of -1 is returned |
2975 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
2976 | |
2977 | E\bER\bRR\bRO\bOR\bRS\bS |
2978 | w\bwa\bai\bit\bt() will fail and return immediately if: |
2979 | |
2980 | [ECHILD] The calling process has no existing unwaited-for child |
2981 | processes. |
2982 | |
2983 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
2984 | address. (May not be detected before exit of a child |
2985 | process.) |
2986 | |
2987 | [EINTR] The call was interrupted by a caught signal, or the |
2988 | signal did not have the SA_RESTART flag set. |
2989 | |
2990 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
2991 | argument. |
2992 | |
2993 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
2994 | _exit(2), sigaction(2), exit(3) |
2995 | |
2996 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
2997 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
2998 | (``POSIX.1''). |
2999 | |
3000 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
3001 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
3002 | specification. |
3003 | |
3004 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3005 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
3006 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
3007 | first appeared in 4BSD, but the final calling convention was only |
3008 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
3009 | appeared in 4.3BSD-Reno. |
3010 | |
3011 | N\bNA\bAM\bME\bE |
3012 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
3013 | |
3014 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3015 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
3016 | |
3017 | _\bp_\bi_\bd_\b__\bt |
3018 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
3019 | |
3020 | _\bp_\bi_\bd_\b__\bt |
3021 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
3022 | |
3023 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
3024 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
3025 | |
3026 | _\bp_\bi_\bd_\b__\bt |
3027 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
3028 | |
3029 | _\bp_\bi_\bd_\b__\bt |
3030 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
3031 | |
3032 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3033 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
3034 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
3035 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
3036 | area, if non-zero, is filled in with termination information about the |
3037 | process that exited (see below). |
3038 | |
3039 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
3040 | to wait for certain child processes, that need resource utilization |
3041 | statistics accumulated by child processes, or that require options. The |
3042 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
3043 | |
3044 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
3045 | wait. The following symbolic constants are currently defined in |
3046 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
3047 | |
3048 | #define WAIT_ANY (-1) /* any process */ |
3049 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
3050 | |
3051 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
3052 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
3053 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
3054 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
3055 | call waits for any process whose process group ID equals the absolute |
3056 | value of _\bw_\bp_\bi_\bd. |
3057 | |
3058 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
3059 | bitwise OR of zero or more of the following values: |
3060 | |
3061 | WCONTINUED Causes status to be reported for stopped child processes that |
3062 | have been continued by receipt of a SIGCONT signal. |
3063 | |
3064 | WNOHANG Indicates that the call should not block if there are no |
3065 | processes that wish to report status. |
3066 | |
3067 | WUNTRACED If set, children of the current process that are stopped due |
3068 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
3069 | their status reported. |
3070 | |
3071 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
3072 | process and all its children is returned (this information is currently |
3073 | not available for stopped processes). |
3074 | |
3075 | When the WNOHANG option is specified and no processes wish to report |
3076 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
3077 | |
3078 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
3079 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
3080 | |
3081 | The following macros may be used to test the manner of exit of the |
3082 | process. One of the first three macros will evaluate to a non-zero |
3083 | (true) value: |
3084 | |
3085 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
3086 | True if the process has not terminated, and has continued after a |
3087 | job control stop. This macro can be true only if the wait call |
3088 | specified the WCONTINUED option. |
3089 | |
3090 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
3091 | True if the process terminated normally by a call to _exit(2) or |
3092 | exit(3). |
3093 | |
3094 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
3095 | True if the process terminated due to receipt of a signal. |
3096 | |
3097 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
3098 | True if the process has not terminated, but has stopped and can |
3099 | be restarted. This macro can be true only if the wait call |
3100 | specified the WUNTRACED option or if the child process is being |
3101 | traced (see ptrace(2)). |
3102 | |
3103 | Depending on the values of those macros, the following macros produce the |
3104 | remaining status information about the child process: |
3105 | |
3106 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
3107 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
3108 | of the argument passed to _exit(2) or exit(3) by the child. |
3109 | |
3110 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
3111 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
3112 | signal that caused the termination of the process. |
3113 | |
3114 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
3115 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
3116 | termination of the process was accompanied by the creation of a |
3117 | core file containing an image of the process when the signal was |
3118 | received. |
3119 | |
3120 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
3121 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
3122 | signal that caused the process to stop. |
3123 | |
3124 | N\bNO\bOT\bTE\bES\bS |
3125 | See sigaction(2) for a list of termination signals. A status of 0 |
3126 | indicates normal termination. |
3127 | |
3128 | If a parent process terminates without waiting for all of its child |
3129 | processes to terminate, the remaining child processes are assigned the |
3130 | parent process 1 ID (the init process ID). |
3131 | |
3132 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
3133 | may be interrupted or restarted when the signal-catching routine returns, |
3134 | depending on the options in effect for the signal; for further |
3135 | information, see siginterrupt(3). |
3136 | |
3137 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3138 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
3139 | process ID of the child is returned to the calling process. Otherwise, a |
3140 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
3141 | |
3142 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
3143 | child process, the process ID of the child is returned to the calling |
3144 | process. If there are no children not previously awaited, -1 is returned |
3145 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
3146 | are no stopped or exited children, 0 is returned. If an error is |
3147 | detected or a caught signal aborts the call, a value of -1 is returned |
3148 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
3149 | |
3150 | E\bER\bRR\bRO\bOR\bRS\bS |
3151 | w\bwa\bai\bit\bt() will fail and return immediately if: |
3152 | |
3153 | [ECHILD] The calling process has no existing unwaited-for child |
3154 | processes. |
3155 | |
3156 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
3157 | address. (May not be detected before exit of a child |
3158 | process.) |
3159 | |
3160 | [EINTR] The call was interrupted by a caught signal, or the |
3161 | signal did not have the SA_RESTART flag set. |
3162 | |
3163 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
3164 | argument. |
3165 | |
3166 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3167 | _exit(2), sigaction(2), exit(3) |
3168 | |
3169 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
3170 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
3171 | (``POSIX.1''). |
3172 | |
3173 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
3174 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
3175 | specification. |
3176 | |
3177 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3178 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
3179 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
3180 | first appeared in 4BSD, but the final calling convention was only |
3181 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
3182 | appeared in 4.3BSD-Reno. |
3183 | |
3184 | N\bNA\bAM\bME\bE |
3185 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
3186 | |
3187 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3188 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
3189 | |
3190 | _\bp_\bi_\bd_\b__\bt |
3191 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
3192 | |
3193 | _\bp_\bi_\bd_\b__\bt |
3194 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
3195 | |
3196 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
3197 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
3198 | |
3199 | _\bp_\bi_\bd_\b__\bt |
3200 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
3201 | |
3202 | _\bp_\bi_\bd_\b__\bt |
3203 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
3204 | |
3205 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3206 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
3207 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
3208 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
3209 | area, if non-zero, is filled in with termination information about the |
3210 | process that exited (see below). |
3211 | |
3212 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
3213 | to wait for certain child processes, that need resource utilization |
3214 | statistics accumulated by child processes, or that require options. The |
3215 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
3216 | |
3217 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
3218 | wait. The following symbolic constants are currently defined in |
3219 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
3220 | |
3221 | #define WAIT_ANY (-1) /* any process */ |
3222 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
3223 | |
3224 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
3225 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
3226 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
3227 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
3228 | call waits for any process whose process group ID equals the absolute |
3229 | value of _\bw_\bp_\bi_\bd. |
3230 | |
3231 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
3232 | bitwise OR of zero or more of the following values: |
3233 | |
3234 | WCONTINUED Causes status to be reported for stopped child processes that |
3235 | have been continued by receipt of a SIGCONT signal. |
3236 | |
3237 | WNOHANG Indicates that the call should not block if there are no |
3238 | processes that wish to report status. |
3239 | |
3240 | WUNTRACED If set, children of the current process that are stopped due |
3241 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
3242 | their status reported. |
3243 | |
3244 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
3245 | process and all its children is returned (this information is currently |
3246 | not available for stopped processes). |
3247 | |
3248 | When the WNOHANG option is specified and no processes wish to report |
3249 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
3250 | |
3251 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
3252 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
3253 | |
3254 | The following macros may be used to test the manner of exit of the |
3255 | process. One of the first three macros will evaluate to a non-zero |
3256 | (true) value: |
3257 | |
3258 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
3259 | True if the process has not terminated, and has continued after a |
3260 | job control stop. This macro can be true only if the wait call |
3261 | specified the WCONTINUED option. |
3262 | |
3263 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
3264 | True if the process terminated normally by a call to _exit(2) or |
3265 | exit(3). |
3266 | |
3267 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
3268 | True if the process terminated due to receipt of a signal. |
3269 | |
3270 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
3271 | True if the process has not terminated, but has stopped and can |
3272 | be restarted. This macro can be true only if the wait call |
3273 | specified the WUNTRACED option or if the child process is being |
3274 | traced (see ptrace(2)). |
3275 | |
3276 | Depending on the values of those macros, the following macros produce the |
3277 | remaining status information about the child process: |
3278 | |
3279 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
3280 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
3281 | of the argument passed to _exit(2) or exit(3) by the child. |
3282 | |
3283 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
3284 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
3285 | signal that caused the termination of the process. |
3286 | |
3287 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
3288 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
3289 | termination of the process was accompanied by the creation of a |
3290 | core file containing an image of the process when the signal was |
3291 | received. |
3292 | |
3293 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
3294 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
3295 | signal that caused the process to stop. |
3296 | |
3297 | N\bNO\bOT\bTE\bES\bS |
3298 | See sigaction(2) for a list of termination signals. A status of 0 |
3299 | indicates normal termination. |
3300 | |
3301 | If a parent process terminates without waiting for all of its child |
3302 | processes to terminate, the remaining child processes are assigned the |
3303 | parent process 1 ID (the init process ID). |
3304 | |
3305 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
3306 | may be interrupted or restarted when the signal-catching routine returns, |
3307 | depending on the options in effect for the signal; for further |
3308 | information, see siginterrupt(3). |
3309 | |
3310 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3311 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
3312 | process ID of the child is returned to the calling process. Otherwise, a |
3313 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
3314 | |
3315 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
3316 | child process, the process ID of the child is returned to the calling |
3317 | process. If there are no children not previously awaited, -1 is returned |
3318 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
3319 | are no stopped or exited children, 0 is returned. If an error is |
3320 | detected or a caught signal aborts the call, a value of -1 is returned |
3321 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
3322 | |
3323 | E\bER\bRR\bRO\bOR\bRS\bS |
3324 | w\bwa\bai\bit\bt() will fail and return immediately if: |
3325 | |
3326 | [ECHILD] The calling process has no existing unwaited-for child |
3327 | processes. |
3328 | |
3329 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
3330 | address. (May not be detected before exit of a child |
3331 | process.) |
3332 | |
3333 | [EINTR] The call was interrupted by a caught signal, or the |
3334 | signal did not have the SA_RESTART flag set. |
3335 | |
3336 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
3337 | argument. |
3338 | |
3339 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3340 | _exit(2), sigaction(2), exit(3) |
3341 | |
3342 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
3343 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
3344 | (``POSIX.1''). |
3345 | |
3346 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
3347 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
3348 | specification. |
3349 | |
3350 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3351 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
3352 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
3353 | first appeared in 4BSD, but the final calling convention was only |
3354 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
3355 | appeared in 4.3BSD-Reno. |
3356 | |
3357 | N\bNA\bAM\bME\bE |
3358 | _\b_e\bex\bxi\bit\bt, _\b_E\bEx\bxi\bit\bt - terminate the calling process |
3359 | |
3360 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3361 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
3362 | |
3363 | _\bv_\bo_\bi_\bd |
3364 | _\b_e\bex\bxi\bit\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\bt_\bu_\bs); |
3365 | |
3366 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdl\bli\bib\bb.\b.h\bh>\b> |
3367 | |
3368 | _\bv_\bo_\bi_\bd |
3369 | _\b_E\bEx\bxi\bit\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\bt_\bu_\bs); |
3370 | |
3371 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3372 | The _\b_e\bex\bxi\bit\bt() and _\b_E\bEx\bxi\bit\bt() functions terminate a process with the following |
3373 | consequences: |
3374 | |
3375 | +\b+\bo\bo All threads in the process are terminated. |
3376 | |
3377 | +\b+\bo\bo All open file descriptors in the calling process are closed. This |
3378 | may entail delays; for example, waiting for output to drain. A |
3379 | process in this state may not be killed, as it is already dying. |
3380 | |
3381 | +\b+\bo\bo If the parent process of the calling process has an outstanding |
3382 | wait(2) call or catches the SIGCHLD signal, it is notified of the |
3383 | calling process's termination and _\bs_\bt_\ba_\bt_\bu_\bs is set as defined by |
3384 | wait(2). (Note that typically only the lower 8 bits of _\bs_\bt_\ba_\bt_\bu_\bs are |
3385 | passed on to the parent, thus negative values have less meaning.) |
3386 | |
3387 | +\b+\bo\bo The parent process ID of all of the calling process's existing child |
3388 | processes are set to 1; the initialization process (see the |
3389 | DEFINITIONS section of intro(2)) inherits each of these processes. |
3390 | |
3391 | +\b+\bo\bo If the termination of the process causes any process group to become |
3392 | orphaned (usually because the parents of all members of the group |
3393 | have now exited; see Orphaned Process Group in intro(2)), and if any |
3394 | member of the orphaned group is stopped, the SIGHUP and SIGCONT |
3395 | signals are sent to all members of the newly orphaned process group. |
3396 | |
3397 | +\b+\bo\bo If the process is a controlling process (see intro(2)), the SIGHUP |
3398 | signal is sent to the foreground process group of the controlling |
3399 | terminal, and all current access to the controlling terminal is |
3400 | revoked. |
3401 | |
3402 | Most C programs call the library routine exit(3), which flushes buffers, |
3403 | closes streams, unlinks temporary files, etc., and then calls _\b_e\bex\bxi\bit\bt(). |
3404 | |
3405 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3406 | _\b_e\bex\bxi\bit\bt() and _\b_E\bEx\bxi\bit\bt() can never return. |
3407 | |
3408 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3409 | fork(2), intro(2), sigaction(2), wait(2), exit(3), sysexits(3) |
3410 | |
3411 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
3412 | The _\b_e\bex\bxi\bit\bt() function conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
3413 | _\b_E\bEx\bxi\bit\bt() function conforms to ISO/IEC 9899:1999 (``ISO C99''). |
3414 | |
3415 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3416 | An e\bex\bxi\bit\bt() system call first appeared in Version 1 AT&T UNIX. It accepts |
3417 | the _\bs_\bt_\ba_\bt_\bu_\bs argument since Version 2 AT&T UNIX. An _\b_e\bex\bxi\bit\bt() variant first |
3418 | appeared in Version 7 AT&T UNIX. The _\b_E\bEx\bxi\bit\bt() function appeared in |
3419 | OpenBSD 3.6. |
3420 | |
3421 | N\bNA\bAM\bME\bE |
3422 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb, _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb - get and set the address of the thread control |
3423 | block of the current thread |
3424 | |
3425 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3426 | _\bv_\bo_\bi_\bd _\b* |
3427 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb(_\bv_\bo_\bi_\bd); |
3428 | |
3429 | _\bv_\bo_\bi_\bd |
3430 | _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb(_\bv_\bo_\bi_\bd _\b*); |
3431 | |
3432 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3433 | The _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() and _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb() functions are for use by librthread and |
3434 | other parts of the system runtime to retrieve and set the address of the |
3435 | current thread's thread control block (TCB). This is used to locate per- |
3436 | thread data such as _\be_\br_\br_\bn_\bo. Each kernel-level thread in a process has a |
3437 | separate value for this address, which can be obtained and changed via |
3438 | these system calls. New threads (including the first thread of a new |
3439 | process) created using fork(2), vfork(2), or __tfork(2), inherit the TCB |
3440 | address of the thread that created them. execve(2) resets it to zero. |
3441 | |
3442 | On some platforms, this address is also directly mapped to a CPU register |
3443 | which can be accessed from userspace. |
3444 | |
3445 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3446 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() returns the address of the thread control block of the |
3447 | current thread. |
3448 | |
3449 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3450 | __tfork(2) |
3451 | |
3452 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3453 | The _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() and _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb() system calls appeared in OpenBSD 5.1. |
3454 | |
3455 | N\bNA\bAM\bME\bE |
3456 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb, _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb - get and set the address of the thread control |
3457 | block of the current thread |
3458 | |
3459 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3460 | _\bv_\bo_\bi_\bd _\b* |
3461 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb(_\bv_\bo_\bi_\bd); |
3462 | |
3463 | _\bv_\bo_\bi_\bd |
3464 | _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb(_\bv_\bo_\bi_\bd _\b*); |
3465 | |
3466 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3467 | The _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() and _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb() functions are for use by librthread and |
3468 | other parts of the system runtime to retrieve and set the address of the |
3469 | current thread's thread control block (TCB). This is used to locate per- |
3470 | thread data such as _\be_\br_\br_\bn_\bo. Each kernel-level thread in a process has a |
3471 | separate value for this address, which can be obtained and changed via |
3472 | these system calls. New threads (including the first thread of a new |
3473 | process) created using fork(2), vfork(2), or __tfork(2), inherit the TCB |
3474 | address of the thread that created them. execve(2) resets it to zero. |
3475 | |
3476 | On some platforms, this address is also directly mapped to a CPU register |
3477 | which can be accessed from userspace. |
3478 | |
3479 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3480 | _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() returns the address of the thread control block of the |
3481 | current thread. |
3482 | |
3483 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3484 | __tfork(2) |
3485 | |
3486 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3487 | The _\b__\b_g\bge\bet\bt_\b_t\btc\bcb\bb() and _\b__\b_s\bse\bet\bt_\b_t\btc\bcb\bb() system calls appeared in OpenBSD 5.1. |
3488 | |
3489 | N\bNA\bAM\bME\bE |
3490 | s\bsy\bys\bsc\bca\bal\bll\bl, _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl - indirect system call |
3491 | |
3492 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3493 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsy\bys\bsc\bca\bal\bll\bl.\b.h\bh>\b> |
3494 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
3495 | |
3496 | _\bi_\bn_\bt |
3497 | s\bsy\bys\bsc\bca\bal\bll\bl(_\bi_\bn_\bt _\bn_\bu_\bm_\bb_\be_\br, _\b._\b._\b.); |
3498 | |
3499 | _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl(_\bq_\bu_\ba_\bd_\b__\bt _\bn_\bu_\bm_\bb_\be_\br, _\b._\b._\b.); |
3500 | |
3501 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3502 | s\bsy\bys\bsc\bca\bal\bll\bl() performs the system call whose assembly language interface has |
3503 | the specified _\bn_\bu_\bm_\bb_\be_\br with the specified arguments. Symbolic constants |
3504 | for system calls can be found in the header file <_\bs_\by_\bs_\b/_\bs_\by_\bs_\bc_\ba_\bl_\bl_\b._\bh>. |
3505 | |
3506 | Since different system calls have different return types, a prototype of |
3507 | _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl specifying the correct return type should be declared locally. |
3508 | This is especially important for system calls returning larger-than-int |
3509 | results. |
3510 | |
3511 | The _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl form should be used when one or more of the parameters is a |
3512 | 64-bit argument to ensure that argument alignment is correct. This |
3513 | system call is useful for testing new system calls that do not have |
3514 | entries in the C library. |
3515 | |
3516 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3517 | The return values are defined by the system call being invoked. In |
3518 | general, for system calls returning _\bi_\bn_\bt, a 0 return value indicates |
3519 | success. A -1 return value indicates an error, and an error code is |
3520 | stored in _\be_\br_\br_\bn_\bo. |
3521 | |
3522 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3523 | The predecessor of these functions, the former i\bin\bnd\bdi\bir\br() system call, first |
3524 | appeared in Version 4 AT&T UNIX. The s\bsy\bys\bsc\bca\bal\bll\bl() function first appeared |
3525 | in 3BSD. |
3526 | |
3527 | B\bBU\bUG\bGS\bS |
3528 | There is no way to simulate system calls that have multiple return values |
3529 | such as pipe(2). |
3530 | |
3531 | N\bNA\bAM\bME\bE |
3532 | _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd, _\b__\b_t\btf\bfo\bor\brk\bk - create a new kernel thread in the current |
3533 | process |
3534 | |
3535 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3536 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
3537 | |
3538 | struct __tfork { |
3539 | void *tf_tcb; /* TCB address for new thread */ |
3540 | pid_t *tf_tid; /* where to write child's thread ID */ |
3541 | void *tf_stack; /* stack address for new thread */ |
3542 | }; |
3543 | |
3544 | _\bp_\bi_\bd_\b__\bt |
3545 | _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\b__\b__\bt_\bf_\bo_\br_\bk _\b*_\bp_\ba_\br_\ba_\bm_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bp_\bs_\bi_\bz_\be, |
3546 | _\bv_\bo_\bi_\bd _\b(_\b*_\bs_\bt_\ba_\br_\bt_\bf_\bu_\bn_\bc_\b)_\b(_\bv_\bo_\bi_\bd _\b*_\b), _\bv_\bo_\bi_\bd _\b*_\bs_\bt_\ba_\br_\bt_\ba_\br_\bg); |
3547 | |
3548 | _\bp_\bi_\bd_\b__\bt |
3549 | _\b__\b_t\btf\bfo\bor\brk\bk(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\b__\b__\bt_\bf_\bo_\br_\bk _\b*_\bp_\ba_\br_\ba_\bm_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bp_\bs_\bi_\bz_\be); |
3550 | |
3551 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3552 | The _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() function creates a new kernel thread in the current |
3553 | process. The new thread starts by calling _\bs_\bt_\ba_\br_\bt_\bf_\bu_\bn_\bc, passing _\bs_\bt_\ba_\br_\bt_\ba_\br_\bg as |
3554 | the only argument. If _\bs_\bt_\ba_\br_\bt_\bf_\bu_\bn_\bc returns, the thread will exit. |
3555 | |
3556 | The _\bp_\ba_\br_\ba_\bm_\bs argument provides parameters used by the kernel during thread |
3557 | creation. The new thread's thread control block (TCB) address is set to |
3558 | _\bt_\bf_\b__\bt_\bc_\bb. If _\bt_\bf_\b__\bt_\bi_\bd is not NULL, the new thread's thread ID is returned to |
3559 | the user at that address, with the guarantee that this is done before |
3560 | returning to userspace in either the calling thread or the new thread. |
3561 | If _\bt_\bf_\b__\bs_\bt_\ba_\bc_\bk is not NULL, the new thread's stack is initialized to start |
3562 | at that address. On hppa and hppa64, that is the lowest address used; on |
3563 | other architectures that is the address after the highest address used. |
3564 | |
3565 | The _\bp_\bs_\bi_\bz_\be argument provides the size of the _\bs_\bt_\br_\bu_\bc_\bt _\b__\b__\bt_\bf_\bo_\br_\bk passed via the |
3566 | _\bp_\ba_\br_\ba_\bm_\bs argument. |
3567 | |
3568 | The underlying system call used to create the thread is _\b__\b_t\btf\bfo\bor\brk\bk(). |
3569 | Because the new thread returns without a stack frame, the syscall cannot |
3570 | be directly used from C and is therefore not provided as a function. |
3571 | However, the syscall may show up in the output of kdump(1). |
3572 | |
3573 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3574 | Upon successful completion, _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() returns in the calling |
3575 | thread the thread ID of new thread. The _\b__\b_t\btf\bfo\bor\brk\bk() syscall itself, on |
3576 | success, returns a value of 0 in the new thread and returns the thread ID |
3577 | of the new thread to the calling thread. Otherwise, a value of -1 is |
3578 | returned, no thread is created, and the global variable _\be_\br_\br_\bn_\bo is set to |
3579 | indicate an error. |
3580 | |
3581 | E\bER\bRR\bRO\bOR\bRS\bS |
3582 | _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() and _\b__\b_t\btf\bfo\bor\brk\bk() will fail and no thread will be created |
3583 | if: |
3584 | |
3585 | [ENOMEM] Cannot allocate memory. The new process image |
3586 | required more memory than was allowed by the hardware |
3587 | or by system-imposed memory management constraints. A |
3588 | lack of swap space is normally temporary; however, a |
3589 | lack of core is not. Soft limits may be increased to |
3590 | their corresponding hard limits. |
3591 | |
3592 | [EINVAL] Invalid argument. Some invalid argument was supplied. |
3593 | |
3594 | [EAGAIN] Resource temporarily unavailable. The system-imposed |
3595 | limit on the total number of threads under execution |
3596 | would be exceeded. This limit is configuration- |
3597 | dependent. |
3598 | |
3599 | [EAGAIN] Resource temporarily unavailable. The system-imposed |
3600 | limit MAXUPRC on the total number of threads under |
3601 | execution by a single user would be exceeded. MAXUPRC |
3602 | is currently defined in <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh> as CHILD_MAX, |
3603 | which is currently defined as 80 in <_\bs_\by_\bs_\b/_\bs_\by_\bs_\bl_\bi_\bm_\bi_\bt_\bs_\b._\bh>. |
3604 | |
3605 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
3606 | The _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() function and _\b__\b_t\btf\bfo\bor\brk\bk() syscall are specific to |
3607 | OpenBSD and should not be used in portable applications. |
3608 | |
3609 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3610 | The _\b__\b_t\btf\bfo\bor\brk\bk_\b_t\bth\bhr\bre\bea\bad\bd() function and _\b__\b_t\btf\bfo\bor\brk\bk() syscall appeared in |
3611 | OpenBSD 5.1. |
3612 | |
3613 | N\bNA\bAM\bME\bE |
3614 | _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt - synchronously accept a signal |
3615 | |
3616 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3617 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
3618 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
3619 | |
3620 | _\bi_\bn_\bt |
3621 | _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt(_\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\bs_\be_\bt, _\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b__\bt _\b*_\bi_\bn_\bf_\bo, |
3622 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
3623 | |
3624 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3625 | The _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() function is used to implement s\bsi\big\bgw\bwa\bai\bit\bt(). It selects |
3626 | a signal pending for the calling thread or process from _\bs_\be_\bt, atomically |
3627 | clears it from that set of pending signals, and returns that signal |
3628 | number. If prior to the call to _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() there are multiple |
3629 | pending instances of a single signal number, it is undefined whether upon |
3630 | successful return there are any remaining pending signals for that signal |
3631 | number. If no signal in _\bs_\be_\bt is pending at the time of the call, the |
3632 | thread shall be suspended until one or more becomes pending. The signals |
3633 | defined by _\bs_\be_\bt should have been blocked in all threads in the process at |
3634 | the time of the call to _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt(); otherwise the signal may be |
3635 | delivered to some thread that does not have it blocked. |
3636 | |
3637 | If more than one thread is using _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() to wait for the same |
3638 | signal, no more than one of these threads shall return from |
3639 | _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() for any given signal that is sent. Which thread returns |
3640 | from _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() if more than a single thread is waiting is |
3641 | unspecified. |
3642 | |
3643 | If the _\bi_\bn_\bf_\bo argument is not NULL, then a _\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b__\bt will be stored there |
3644 | which has the selected signal number in its _\bs_\bi_\b__\bs_\bi_\bg_\bn_\bo member and the cause |
3645 | of the signal in its _\bs_\bi_\b__\bc_\bo_\bd_\be member. |
3646 | |
3647 | If the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument is not NULL and no selected signal is currently |
3648 | pending, then _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() will wait no longer than the specified |
3649 | time period for a signal to arrive before failing. |
3650 | |
3651 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3652 | If successful, the number of the signal that was accepted is returned. |
3653 | Otherwise, a value of -1 is returned and errno is set to indicate the |
3654 | error. |
3655 | |
3656 | E\bER\bRR\bRO\bOR\bRS\bS |
3657 | _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() will succeed unless: |
3658 | |
3659 | [EWOULDBLOCK] The timeout was reached before a selected signal was |
3660 | received. |
3661 | |
3662 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3663 | sigaction(2), sigprocmask(2), sigwait(3) |
3664 | |
3665 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
3666 | The _\b__\b_t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() function is specific to OpenBSD and should not be |
3667 | used in portable applications. |
3668 | |
3669 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3670 | A t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() syscall appeared in OpenBSD 3.9. The _\bi_\bn_\bf_\bo and _\bt_\bi_\bm_\be_\bo_\bu_\bt |
3671 | arguments were added in OpenBSD 4.9. |
3672 | |
3673 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
3674 | The t\bth\bhr\brs\bsi\big\bgd\bdi\biv\bve\ber\brt\bt() syscall was created by Ted Unangst <_\bt_\be_\bd_\bu_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
3675 | This manual page was written by Philip Guenther <_\bg_\bu_\be_\bn_\bt_\bh_\be_\br_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
3676 | |
3677 | N\bNA\bAM\bME\bE |
3678 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp, _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp - userspace thread sleep and wakeup |
3679 | |
3680 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3681 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
3682 | |
3683 | _\bi_\bn_\bt |
3684 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bl_\ba_\bt_\bi_\bl_\be _\bv_\bo_\bi_\bd _\b*_\bi_\bd, _\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, |
3685 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\ba_\bb_\bs_\bt_\bi_\bm_\be, _\bv_\bo_\bi_\bd _\b*_\bl_\bo_\bc_\bk, _\bc_\bo_\bn_\bs_\bt _\bi_\bn_\bt _\b*_\ba_\bb_\bo_\br_\bt); |
3686 | |
3687 | _\bi_\bn_\bt |
3688 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bl_\ba_\bt_\bi_\bl_\be _\bv_\bo_\bi_\bd _\b*_\bi_\bd, _\bi_\bn_\bt _\bc_\bo_\bu_\bn_\bt); |
3689 | |
3690 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3691 | The _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() functions provide thread sleep and |
3692 | wakeup primitives with which synchronization primitives such as mutexes |
3693 | and condition variables can be implemented. _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() blocks the |
3694 | calling thread on the abstract ``wait channel'' identified by the _\bi_\bd |
3695 | argument until another thread calls _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() with the same _\bi_\bd value. |
3696 | If the _\ba_\bb_\bs_\bt_\bi_\bm_\be argument is not NULL, then it specifies an absolute time, |
3697 | measured against the _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd clock, after which _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() should time |
3698 | out and return. If the specified time is in the past then _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() |
3699 | will return immediately without blocking. |
3700 | |
3701 | The _\bl_\bo_\bc_\bk argument, if not NULL, points to a locked spinlock that will be |
3702 | unlocked by _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() atomically with respect to calls to |
3703 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(), such that if another thread locks the spinlock before |
3704 | calling _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() with the same _\bi_\bd, then the thread that called |
3705 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will be eligible for being woken up and unblocked. |
3706 | |
3707 | The _\ba_\bb_\bo_\br_\bt argument, if not NULL, points to an _\bi_\bn_\bt that will be examined |
3708 | after unlocking the spinlock pointed to by _\bl_\bo_\bc_\bk and immediately before |
3709 | blocking. If that _\bi_\bn_\bt is non-zero then _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will immediately |
3710 | return EINTR without blocking. This provides a mechanism for a signal |
3711 | handler to keep a call to _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() from blocking, even if the signal |
3712 | is delivered immediately before the call. |
3713 | |
3714 | The _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() function unblocks one or more threads that are sleeping |
3715 | on the wait channel identified by _\bi_\bd. The number of threads unblocked is |
3716 | specified by the _\bc_\bo_\bu_\bn_\bt argument, except that if zero is specified then |
3717 | all threads sleeping on that _\bi_\bd are unblocked. |
3718 | |
3719 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3720 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will return zero if woken by a matching call to |
3721 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(), otherwise an error number will be returned to indicate the |
3722 | error. |
3723 | |
3724 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() will return zero if at least one matching call to |
3725 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() was unblocked, otherwise an error number will be returned to |
3726 | indicate the error. |
3727 | |
3728 | E\bER\bRR\bRO\bOR\bRS\bS |
3729 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() will fail if: |
3730 | |
3731 | [EINVAL] The _\bi_\bd_\be_\bn_\bt argument is NULL. |
3732 | |
3733 | In addition, _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() may return one of the following errors: |
3734 | |
3735 | [EWOULDBLOCK] The time specified by the _\ba_\bb_\bs_\bt_\bi_\bm_\be and _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd |
3736 | arguments was reached. |
3737 | |
3738 | [EINTR] A signal arrived or the _\ba_\bb_\bo_\br_\bt argument pointed to a |
3739 | non-zero value. |
3740 | |
3741 | [EINVAL] The _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd argument is neither CLOCK_REALTIME nor |
3742 | CLOCK_MONOTONIC. |
3743 | |
3744 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() may return the following error: |
3745 | |
3746 | [ESRCH] No threads calling _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() with the same _\bi_\bd were |
3747 | found. |
3748 | |
3749 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3750 | pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9) |
3751 | |
3752 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
3753 | The _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() functions are specific to OpenBSD and |
3754 | should not be used in portable applications. |
3755 | |
3756 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3757 | The t\bth\bhr\brs\bsl\ble\bee\bep\bp() and t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() syscalls appeared in OpenBSD 3.9. The |
3758 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd and _\ba_\bb_\bs_\bt_\bi_\bm_\be arguments were added in OpenBSD 4.9. The functions |
3759 | were renamed to _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() and the _\ba_\bb_\bo_\br_\bt argument was |
3760 | added in OpenBSD 5.1 |
3761 | |
3762 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
3763 | The t\bth\bhr\brs\bsl\ble\bee\bep\bp() and t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() syscalls were created by Ted Unangst |
3764 | <_\bt_\be_\bd_\bu_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. This manual page was written by Philip Guenther |
3765 | <_\bg_\bu_\be_\bn_\bt_\bh_\be_\br_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
3766 | |
3767 | N\bNA\bAM\bME\bE |
3768 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp, _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp - userspace thread sleep and wakeup |
3769 | |
3770 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3771 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
3772 | |
3773 | _\bi_\bn_\bt |
3774 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bl_\ba_\bt_\bi_\bl_\be _\bv_\bo_\bi_\bd _\b*_\bi_\bd, _\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, |
3775 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\ba_\bb_\bs_\bt_\bi_\bm_\be, _\bv_\bo_\bi_\bd _\b*_\bl_\bo_\bc_\bk, _\bc_\bo_\bn_\bs_\bt _\bi_\bn_\bt _\b*_\ba_\bb_\bo_\br_\bt); |
3776 | |
3777 | _\bi_\bn_\bt |
3778 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bl_\ba_\bt_\bi_\bl_\be _\bv_\bo_\bi_\bd _\b*_\bi_\bd, _\bi_\bn_\bt _\bc_\bo_\bu_\bn_\bt); |
3779 | |
3780 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3781 | The _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() functions provide thread sleep and |
3782 | wakeup primitives with which synchronization primitives such as mutexes |
3783 | and condition variables can be implemented. _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() blocks the |
3784 | calling thread on the abstract ``wait channel'' identified by the _\bi_\bd |
3785 | argument until another thread calls _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() with the same _\bi_\bd value. |
3786 | If the _\ba_\bb_\bs_\bt_\bi_\bm_\be argument is not NULL, then it specifies an absolute time, |
3787 | measured against the _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd clock, after which _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() should time |
3788 | out and return. If the specified time is in the past then _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() |
3789 | will return immediately without blocking. |
3790 | |
3791 | The _\bl_\bo_\bc_\bk argument, if not NULL, points to a locked spinlock that will be |
3792 | unlocked by _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() atomically with respect to calls to |
3793 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(), such that if another thread locks the spinlock before |
3794 | calling _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() with the same _\bi_\bd, then the thread that called |
3795 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will be eligible for being woken up and unblocked. |
3796 | |
3797 | The _\ba_\bb_\bo_\br_\bt argument, if not NULL, points to an _\bi_\bn_\bt that will be examined |
3798 | after unlocking the spinlock pointed to by _\bl_\bo_\bc_\bk and immediately before |
3799 | blocking. If that _\bi_\bn_\bt is non-zero then _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will immediately |
3800 | return EINTR without blocking. This provides a mechanism for a signal |
3801 | handler to keep a call to _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() from blocking, even if the signal |
3802 | is delivered immediately before the call. |
3803 | |
3804 | The _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() function unblocks one or more threads that are sleeping |
3805 | on the wait channel identified by _\bi_\bd. The number of threads unblocked is |
3806 | specified by the _\bc_\bo_\bu_\bn_\bt argument, except that if zero is specified then |
3807 | all threads sleeping on that _\bi_\bd are unblocked. |
3808 | |
3809 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3810 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() will return zero if woken by a matching call to |
3811 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp(), otherwise an error number will be returned to indicate the |
3812 | error. |
3813 | |
3814 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() will return zero if at least one matching call to |
3815 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() was unblocked, otherwise an error number will be returned to |
3816 | indicate the error. |
3817 | |
3818 | E\bER\bRR\bRO\bOR\bRS\bS |
3819 | _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() will fail if: |
3820 | |
3821 | [EINVAL] The _\bi_\bd_\be_\bn_\bt argument is NULL. |
3822 | |
3823 | In addition, _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() may return one of the following errors: |
3824 | |
3825 | [EWOULDBLOCK] The time specified by the _\ba_\bb_\bs_\bt_\bi_\bm_\be and _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd |
3826 | arguments was reached. |
3827 | |
3828 | [EINTR] A signal arrived or the _\ba_\bb_\bo_\br_\bt argument pointed to a |
3829 | non-zero value. |
3830 | |
3831 | [EINVAL] The _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd argument is neither CLOCK_REALTIME nor |
3832 | CLOCK_MONOTONIC. |
3833 | |
3834 | _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() may return the following error: |
3835 | |
3836 | [ESRCH] No threads calling _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() with the same _\bi_\bd were |
3837 | found. |
3838 | |
3839 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3840 | pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9) |
3841 | |
3842 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
3843 | The _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() functions are specific to OpenBSD and |
3844 | should not be used in portable applications. |
3845 | |
3846 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3847 | The t\bth\bhr\brs\bsl\ble\bee\bep\bp() and t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() syscalls appeared in OpenBSD 3.9. The |
3848 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd and _\ba_\bb_\bs_\bt_\bi_\bm_\be arguments were added in OpenBSD 4.9. The functions |
3849 | were renamed to _\b__\b_t\bth\bhr\brs\bsl\ble\bee\bep\bp() and _\b__\b_t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() and the _\ba_\bb_\bo_\br_\bt argument was |
3850 | added in OpenBSD 5.1 |
3851 | |
3852 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
3853 | The t\bth\bhr\brs\bsl\ble\bee\bep\bp() and t\bth\bhr\brw\bwa\bak\bke\beu\bup\bp() syscalls were created by Ted Unangst |
3854 | <_\bt_\be_\bd_\bu_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. This manual page was written by Philip Guenther |
3855 | <_\bg_\bu_\be_\bn_\bt_\bh_\be_\br_\b@_\bO_\bp_\be_\bn_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
3856 | |
3857 | N\bNA\bAM\bME\bE |
3858 | _\b_e\bex\bxi\bit\bt, _\b_E\bEx\bxi\bit\bt - terminate the calling process |
3859 | |
3860 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3861 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
3862 | |
3863 | _\bv_\bo_\bi_\bd |
3864 | _\b_e\bex\bxi\bit\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\bt_\bu_\bs); |
3865 | |
3866 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdl\bli\bib\bb.\b.h\bh>\b> |
3867 | |
3868 | _\bv_\bo_\bi_\bd |
3869 | _\b_E\bEx\bxi\bit\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\bt_\bu_\bs); |
3870 | |
3871 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3872 | The _\b_e\bex\bxi\bit\bt() and _\b_E\bEx\bxi\bit\bt() functions terminate a process with the following |
3873 | consequences: |
3874 | |
3875 | +\b+\bo\bo All threads in the process are terminated. |
3876 | |
3877 | +\b+\bo\bo All open file descriptors in the calling process are closed. This |
3878 | may entail delays; for example, waiting for output to drain. A |
3879 | process in this state may not be killed, as it is already dying. |
3880 | |
3881 | +\b+\bo\bo If the parent process of the calling process has an outstanding |
3882 | wait(2) call or catches the SIGCHLD signal, it is notified of the |
3883 | calling process's termination and _\bs_\bt_\ba_\bt_\bu_\bs is set as defined by |
3884 | wait(2). (Note that typically only the lower 8 bits of _\bs_\bt_\ba_\bt_\bu_\bs are |
3885 | passed on to the parent, thus negative values have less meaning.) |
3886 | |
3887 | +\b+\bo\bo The parent process ID of all of the calling process's existing child |
3888 | processes are set to 1; the initialization process (see the |
3889 | DEFINITIONS section of intro(2)) inherits each of these processes. |
3890 | |
3891 | +\b+\bo\bo If the termination of the process causes any process group to become |
3892 | orphaned (usually because the parents of all members of the group |
3893 | have now exited; see Orphaned Process Group in intro(2)), and if any |
3894 | member of the orphaned group is stopped, the SIGHUP and SIGCONT |
3895 | signals are sent to all members of the newly orphaned process group. |
3896 | |
3897 | +\b+\bo\bo If the process is a controlling process (see intro(2)), the SIGHUP |
3898 | signal is sent to the foreground process group of the controlling |
3899 | terminal, and all current access to the controlling terminal is |
3900 | revoked. |
3901 | |
3902 | Most C programs call the library routine exit(3), which flushes buffers, |
3903 | closes streams, unlinks temporary files, etc., and then calls _\b_e\bex\bxi\bit\bt(). |
3904 | |
3905 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3906 | _\b_e\bex\bxi\bit\bt() and _\b_E\bEx\bxi\bit\bt() can never return. |
3907 | |
3908 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
3909 | fork(2), intro(2), sigaction(2), wait(2), exit(3), sysexits(3) |
3910 | |
3911 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
3912 | The _\b_e\bex\bxi\bit\bt() function conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
3913 | _\b_E\bEx\bxi\bit\bt() function conforms to ISO/IEC 9899:1999 (``ISO C99''). |
3914 | |
3915 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
3916 | An e\bex\bxi\bit\bt() system call first appeared in Version 1 AT&T UNIX. It accepts |
3917 | the _\bs_\bt_\ba_\bt_\bu_\bs argument since Version 2 AT&T UNIX. An _\b_e\bex\bxi\bit\bt() variant first |
3918 | appeared in Version 7 AT&T UNIX. The _\b_E\bEx\bxi\bit\bt() function appeared in |
3919 | OpenBSD 3.6. |
3920 | |
3921 | N\bNA\bAM\bME\bE |
3922 | a\bac\bcc\bce\bep\bpt\bt, a\bac\bcc\bce\bep\bpt\bt4\b4 - accept a connection on a socket |
3923 | |
3924 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
3925 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
3926 | |
3927 | _\bi_\bn_\bt |
3928 | a\bac\bcc\bce\bep\bpt\bt(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\ba_\bd_\bd_\br, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\ba_\bd_\bd_\br_\bl_\be_\bn); |
3929 | |
3930 | _\bi_\bn_\bt |
3931 | a\bac\bcc\bce\bep\bpt\bt4\b4(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\ba_\bd_\bd_\br, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\ba_\bd_\bd_\br_\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
3932 | |
3933 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
3934 | The argument _\bs is a socket that has been created with socket(2), bound to |
3935 | an address with bind(2), and is listening for connections after a |
3936 | listen(2). The a\bac\bcc\bce\bep\bpt\bt() call extracts the first connection request on |
3937 | the queue of pending connections, creates a new socket with the same non- |
3938 | blocking I/O mode as _\bs, and allocates a new file descriptor for the |
3939 | socket with the close-on-exec flag clear. |
3940 | |
3941 | The a\bac\bcc\bce\bep\bpt\bt4\b4() system call is similar, however the non-blocking I/O mode |
3942 | of the new socket is determined by the SOCK_NONBLOCK flag in the _\bf_\bl_\ba_\bg_\bs |
3943 | argument and the close-on-exec flag on the new file descriptor is |
3944 | determined by the SOCK_CLOEXEC flag in the _\bf_\bl_\ba_\bg_\bs argument. |
3945 | |
3946 | If no pending connections are present on the queue, and the socket is not |
3947 | marked as non-blocking, a\bac\bcc\bce\bep\bpt\bt() blocks the caller until a connection is |
3948 | present. If the socket is marked non-blocking and no pending connections |
3949 | are present on the queue, a\bac\bcc\bce\bep\bpt\bt() returns an error as described below. |
3950 | The accepted socket may not be used to accept more connections. The |
3951 | original socket _\bs remains open. |
3952 | |
3953 | The argument _\ba_\bd_\bd_\br is a result parameter that is filled in with the |
3954 | address of the connecting entity as known to the communications layer. |
3955 | The exact format of the _\ba_\bd_\bd_\br parameter is determined by the domain in |
3956 | which the communication is occurring. The structure sockaddr_storage |
3957 | exists for greater portability. It is large enough to hold any of the |
3958 | types that may be returned in the _\ba_\bd_\bd_\br parameter. |
3959 | |
3960 | The _\ba_\bd_\bd_\br_\bl_\be_\bn is a value-result parameter; it should initially contain the |
3961 | amount of space pointed to by _\ba_\bd_\bd_\br; on return it will contain the actual |
3962 | length (in bytes) of the address returned. If _\ba_\bd_\bd_\br_\bl_\be_\bn does not point to |
3963 | enough space to hold the entire socket address, the result will be |
3964 | truncated to the initial value of _\ba_\bd_\bd_\br_\bl_\be_\bn (in bytes). This call is used |
3965 | with connection-based socket types, currently with SOCK_STREAM. |
3966 | |
3967 | It is possible to select(2) or poll(2) a socket for the purposes of doing |
3968 | an a\bac\bcc\bce\bep\bpt\bt() by selecting it for read. |
3969 | |
3970 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
3971 | The call returns -1 on error. If it succeeds, it returns a non-negative |
3972 | integer that is a descriptor for the accepted socket. |
3973 | |
3974 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS |
3975 | The following code uses struct sockaddr_storage to allocate enough space |
3976 | for the returned address: |
3977 | |
3978 | #include <sys/types.h> |
3979 | #include <sys/socket.h> |
3980 | |
3981 | struct sockaddr_storage addr; |
3982 | socklen_t len = sizeof(addr); |
3983 | int retcode; |
3984 | |
3985 | retcode = accept(s, (struct sockaddr *)&addr, &len); |
3986 | if (retcode == -1) |
3987 | err(1, "accept"); |
3988 | |
3989 | E\bER\bRR\bRO\bOR\bRS\bS |
3990 | a\bac\bcc\bce\bep\bpt\bt() and a\bac\bcc\bce\bep\bpt\bt4\b4() will fail if: |
3991 | |
3992 | [EBADF] The descriptor is invalid. |
3993 | |
3994 | [ENOTSOCK] The descriptor doesn't reference a socket. |
3995 | |
3996 | [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM. |
3997 | |
3998 | [EINTR] A signal was caught before a connection arrived. |
3999 | |
4000 | [EINVAL] The referenced socket is not listening for connections |
4001 | (that is, listen(2) has not yet been called). |
4002 | |
4003 | [EFAULT] The _\ba_\bd_\bd_\br or _\ba_\bd_\bd_\br_\bl_\be_\bn parameter is not in a valid part |
4004 | of the process address space. |
4005 | |
4006 | [EWOULDBLOCK] The socket is marked non-blocking and no connections |
4007 | are present to be accepted. |
4008 | |
4009 | [EMFILE] The per-process descriptor table is full. |
4010 | |
4011 | [ENFILE] The system file table is full. |
4012 | |
4013 | [ECONNABORTED] A connection has been aborted. |
4014 | |
4015 | In addition, a\bac\bcc\bce\bep\bpt\bt4\b4() will fail if |
4016 | |
4017 | [EINVAL] _\bf_\bl_\ba_\bg_\bs is invalid. |
4018 | |
4019 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
4020 | bind(2), connect(2), listen(2), poll(2), select(2), socket(2) |
4021 | |
4022 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
4023 | The a\bac\bcc\bce\bep\bpt\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
4024 | The a\bac\bcc\bce\bep\bpt\bt4\b4() function is expected to conform to a future revision of |
4025 | that standard. |
4026 | |
4027 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4028 | The a\bac\bcc\bce\bep\bpt\bt() system call first appeared in 4.1cBSD and a\bac\bcc\bce\bep\bpt\bt4\b4() in |
4029 | OpenBSD 5.7. |
4030 | |
4031 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4032 | When EMFILE or ENFILE is returned, new connections are neither dequeued |
4033 | nor discarded. Thus considerable care is required in select(2) and |
4034 | poll(2) loops. |
4035 | |
4036 | N\bNA\bAM\bME\bE |
4037 | a\bac\bcc\bce\bep\bpt\bt, a\bac\bcc\bce\bep\bpt\bt4\b4 - accept a connection on a socket |
4038 | |
4039 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4040 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
4041 | |
4042 | _\bi_\bn_\bt |
4043 | a\bac\bcc\bce\bep\bpt\bt(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\ba_\bd_\bd_\br, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\ba_\bd_\bd_\br_\bl_\be_\bn); |
4044 | |
4045 | _\bi_\bn_\bt |
4046 | a\bac\bcc\bce\bep\bpt\bt4\b4(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\ba_\bd_\bd_\br, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\ba_\bd_\bd_\br_\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
4047 | |
4048 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4049 | The argument _\bs is a socket that has been created with socket(2), bound to |
4050 | an address with bind(2), and is listening for connections after a |
4051 | listen(2). The a\bac\bcc\bce\bep\bpt\bt() call extracts the first connection request on |
4052 | the queue of pending connections, creates a new socket with the same non- |
4053 | blocking I/O mode as _\bs, and allocates a new file descriptor for the |
4054 | socket with the close-on-exec flag clear. |
4055 | |
4056 | The a\bac\bcc\bce\bep\bpt\bt4\b4() system call is similar, however the non-blocking I/O mode |
4057 | of the new socket is determined by the SOCK_NONBLOCK flag in the _\bf_\bl_\ba_\bg_\bs |
4058 | argument and the close-on-exec flag on the new file descriptor is |
4059 | determined by the SOCK_CLOEXEC flag in the _\bf_\bl_\ba_\bg_\bs argument. |
4060 | |
4061 | If no pending connections are present on the queue, and the socket is not |
4062 | marked as non-blocking, a\bac\bcc\bce\bep\bpt\bt() blocks the caller until a connection is |
4063 | present. If the socket is marked non-blocking and no pending connections |
4064 | are present on the queue, a\bac\bcc\bce\bep\bpt\bt() returns an error as described below. |
4065 | The accepted socket may not be used to accept more connections. The |
4066 | original socket _\bs remains open. |
4067 | |
4068 | The argument _\ba_\bd_\bd_\br is a result parameter that is filled in with the |
4069 | address of the connecting entity as known to the communications layer. |
4070 | The exact format of the _\ba_\bd_\bd_\br parameter is determined by the domain in |
4071 | which the communication is occurring. The structure sockaddr_storage |
4072 | exists for greater portability. It is large enough to hold any of the |
4073 | types that may be returned in the _\ba_\bd_\bd_\br parameter. |
4074 | |
4075 | The _\ba_\bd_\bd_\br_\bl_\be_\bn is a value-result parameter; it should initially contain the |
4076 | amount of space pointed to by _\ba_\bd_\bd_\br; on return it will contain the actual |
4077 | length (in bytes) of the address returned. If _\ba_\bd_\bd_\br_\bl_\be_\bn does not point to |
4078 | enough space to hold the entire socket address, the result will be |
4079 | truncated to the initial value of _\ba_\bd_\bd_\br_\bl_\be_\bn (in bytes). This call is used |
4080 | with connection-based socket types, currently with SOCK_STREAM. |
4081 | |
4082 | It is possible to select(2) or poll(2) a socket for the purposes of doing |
4083 | an a\bac\bcc\bce\bep\bpt\bt() by selecting it for read. |
4084 | |
4085 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
4086 | The call returns -1 on error. If it succeeds, it returns a non-negative |
4087 | integer that is a descriptor for the accepted socket. |
4088 | |
4089 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS |
4090 | The following code uses struct sockaddr_storage to allocate enough space |
4091 | for the returned address: |
4092 | |
4093 | #include <sys/types.h> |
4094 | #include <sys/socket.h> |
4095 | |
4096 | struct sockaddr_storage addr; |
4097 | socklen_t len = sizeof(addr); |
4098 | int retcode; |
4099 | |
4100 | retcode = accept(s, (struct sockaddr *)&addr, &len); |
4101 | if (retcode == -1) |
4102 | err(1, "accept"); |
4103 | |
4104 | E\bER\bRR\bRO\bOR\bRS\bS |
4105 | a\bac\bcc\bce\bep\bpt\bt() and a\bac\bcc\bce\bep\bpt\bt4\b4() will fail if: |
4106 | |
4107 | [EBADF] The descriptor is invalid. |
4108 | |
4109 | [ENOTSOCK] The descriptor doesn't reference a socket. |
4110 | |
4111 | [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM. |
4112 | |
4113 | [EINTR] A signal was caught before a connection arrived. |
4114 | |
4115 | [EINVAL] The referenced socket is not listening for connections |
4116 | (that is, listen(2) has not yet been called). |
4117 | |
4118 | [EFAULT] The _\ba_\bd_\bd_\br or _\ba_\bd_\bd_\br_\bl_\be_\bn parameter is not in a valid part |
4119 | of the process address space. |
4120 | |
4121 | [EWOULDBLOCK] The socket is marked non-blocking and no connections |
4122 | are present to be accepted. |
4123 | |
4124 | [EMFILE] The per-process descriptor table is full. |
4125 | |
4126 | [ENFILE] The system file table is full. |
4127 | |
4128 | [ECONNABORTED] A connection has been aborted. |
4129 | |
4130 | In addition, a\bac\bcc\bce\bep\bpt\bt4\b4() will fail if |
4131 | |
4132 | [EINVAL] _\bf_\bl_\ba_\bg_\bs is invalid. |
4133 | |
4134 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
4135 | bind(2), connect(2), listen(2), poll(2), select(2), socket(2) |
4136 | |
4137 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
4138 | The a\bac\bcc\bce\bep\bpt\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
4139 | The a\bac\bcc\bce\bep\bpt\bt4\b4() function is expected to conform to a future revision of |
4140 | that standard. |
4141 | |
4142 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4143 | The a\bac\bcc\bce\bep\bpt\bt() system call first appeared in 4.1cBSD and a\bac\bcc\bce\bep\bpt\bt4\b4() in |
4144 | OpenBSD 5.7. |
4145 | |
4146 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4147 | When EMFILE or ENFILE is returned, new connections are neither dequeued |
4148 | nor discarded. Thus considerable care is required in select(2) and |
4149 | poll(2) loops. |
4150 | |
4151 | N\bNA\bAM\bME\bE |
4152 | a\bac\bcc\bce\bes\bss\bs, f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt - check access permissions of a file or pathname |
4153 | |
4154 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4155 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
4156 | |
4157 | _\bi_\bn_\bt |
4158 | a\bac\bcc\bce\bes\bss\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\ba_\bm_\bo_\bd_\be); |
4159 | |
4160 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
4161 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
4162 | |
4163 | _\bi_\bn_\bt |
4164 | f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\ba_\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
4165 | |
4166 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4167 | The a\bac\bcc\bce\bes\bss\bs() function checks the accessibility of the file named by _\bp_\ba_\bt_\bh |
4168 | for the access permissions indicated by _\ba_\bm_\bo_\bd_\be. The _\ba_\bm_\bo_\bd_\be argument is |
4169 | either the bitwise OR of one or more of the access permissions to be |
4170 | checked (R_OK for read permission, W_OK for write permission, and X_OK |
4171 | for execute/search permission) or the existence test, F_OK. All |
4172 | components of the pathname _\bp_\ba_\bt_\bh are checked for access permissions |
4173 | (including F_OK). |
4174 | |
4175 | The real user ID is used in place of the effective user ID and the real |
4176 | group access list (including the real group ID) is used in place of the |
4177 | effective ID for verifying permission. |
4178 | |
4179 | If the invoking process has superuser privileges, a\bac\bcc\bce\bes\bss\bs() will always |
4180 | indicate success for R_OK and W_OK, regardless of the actual file |
4181 | permission bits. Likewise, for X_OK, if the file has any of the execute |
4182 | bits set and _\bp_\ba_\bt_\bh is not a directory, a\bac\bcc\bce\bes\bss\bs() will indicate success. |
4183 | |
4184 | The f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() function is equivalent to a\bac\bcc\bce\bes\bss\bs() except that where _\bp_\ba_\bt_\bh |
4185 | specifies a relative path, the file whose accessibility is checked is |
4186 | determined relative to the directory associated with file descriptor _\bf_\bd |
4187 | instead of the current working directory. |
4188 | |
4189 | If f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
4190 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
4191 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to a\bac\bcc\bce\bes\bss\bs(). |
4192 | |
4193 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
4194 | values: |
4195 | |
4196 | AT_EACCESS The checks for accessibility are performed using the |
4197 | effective user and group IDs instead of the real user |
4198 | and group IDs. |
4199 | |
4200 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
4201 | If _\bp_\ba_\bt_\bh cannot be found or if any of the desired access modes would not |
4202 | be granted, then a -1 value is returned; otherwise a 0 value is returned. |
4203 | |
4204 | E\bER\bRR\bRO\bOR\bRS\bS |
4205 | Access to the file is denied if: |
4206 | |
4207 | [ENOTDIR] A component of the path prefix is not a directory. |
4208 | |
4209 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
4210 | characters, or an entire pathname (including the |
4211 | terminating NUL) exceeded PATH_MAX bytes. |
4212 | |
4213 | [ENOENT] The named file does not exist. |
4214 | |
4215 | [ELOOP] Too many symbolic links were encountered in |
4216 | translating the pathname. |
4217 | |
4218 | [EROFS] Write access is requested for a file on a read-only |
4219 | file system. |
4220 | |
4221 | [ETXTBSY] Write access is requested for a pure procedure (shared |
4222 | text) file presently being executed. |
4223 | |
4224 | [EACCES] Permission bits of the file mode do not permit the |
4225 | requested access, or search permission is denied on a |
4226 | component of the path prefix. The owner of a file has |
4227 | permission checked with respect to the ``owner'' read, |
4228 | write, and execute mode bits, members of the file's |
4229 | group other than the owner have permission checked |
4230 | with respect to the ``group'' mode bits, and all |
4231 | others have permissions checked with respect to the |
4232 | ``other'' mode bits. |
4233 | |
4234 | [EPERM] Write access has been requested and the named file has |
4235 | its immutable flag set (see chflags(2)). |
4236 | |
4237 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
4238 | space. |
4239 | |
4240 | [EIO] An I/O error occurred while reading from or writing to |
4241 | the file system. |
4242 | |
4243 | [EINVAL] An invalid value was specified for _\ba_\bm_\bo_\bd_\be. |
4244 | |
4245 | Additionally, f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() will fail if: |
4246 | |
4247 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
4248 | AT_EACCESS. |
4249 | |
4250 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
4251 | argument is neither AT_FDCWD nor a valid file |
4252 | descriptor. |
4253 | |
4254 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
4255 | argument is a valid file descriptor but it does not |
4256 | reference a directory. |
4257 | |
4258 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
4259 | permission is denied for the directory which the _\bf_\bd |
4260 | file descriptor references. |
4261 | |
4262 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
4263 | chmod(2), stat(2) |
4264 | |
4265 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
4266 | The a\bac\bcc\bce\bes\bss\bs() and f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() functions conform to IEEE Std 1003.1-2008 |
4267 | (``POSIX.1''). |
4268 | |
4269 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4270 | a\bac\bcc\bce\bes\bss\bs() first appeared as an internal kernel function in Version 1 AT&T |
4271 | UNIX and was reimplemented in C before the release of Version 4 AT&T |
4272 | UNIX. It was first promoted to a system call in the Programmer's |
4273 | Workbench (PWB/UNIX), which was later ported to Version 7 AT&T UNIX and |
4274 | 2BSD. |
4275 | |
4276 | The f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() function appeared in OpenBSD 5.0. |
4277 | |
4278 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
4279 | Ken Thompson first implemented the a\bac\bcc\bce\bes\bss\bs() kernel function in C. |
4280 | |
4281 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4282 | a\bac\bcc\bce\bes\bss\bs() and f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() should never be used for actual access control. |
4283 | Doing so can result in a time of check vs. time of use security hole. |
4284 | |
4285 | N\bNA\bAM\bME\bE |
4286 | a\bac\bcc\bct\bt - enable or disable process accounting |
4287 | |
4288 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4289 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
4290 | |
4291 | _\bi_\bn_\bt |
4292 | a\bac\bcc\bct\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be); |
4293 | |
4294 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4295 | The a\bac\bcc\bct\bt() call enables or disables the collection of system accounting |
4296 | records. If _\bf_\bi_\bl_\be is NULL, accounting is disabled. If _\bf_\bi_\bl_\be is an |
4297 | existing, NUL-terminated pathname, record collection is enabled and for |
4298 | every process initiated which terminates under normal conditions an |
4299 | accounting record is appended to _\bf_\bi_\bl_\be. Abnormal conditions of |
4300 | termination are reboots or other fatal system problems. Records for |
4301 | processes which never terminate cannot be produced by a\bac\bcc\bct\bt(). a\bac\bcc\bct\bt() is |
4302 | only available on kernels compiled with the A\bAC\bCC\bCO\bOU\bUN\bNT\bTI\bIN\bNG\bG option. |
4303 | |
4304 | For more information on the record structure used by a\bac\bcc\bct\bt(), see |
4305 | _\b/_\bu_\bs_\br_\b/_\bi_\bn_\bc_\bl_\bu_\bd_\be_\b/_\bs_\by_\bs_\b/_\ba_\bc_\bc_\bt_\b._\bh and acct(5). |
4306 | |
4307 | This call is permitted only to the superuser. |
4308 | |
4309 | N\bNO\bOT\bTE\bES\bS |
4310 | Accounting is automatically disabled when the file system the accounting |
4311 | file resides on runs out of space; it is enabled when space once again |
4312 | becomes available. |
4313 | |
4314 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
4315 | Upon successful completion, the value 0 is returned; otherwise the |
4316 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
4317 | error. |
4318 | |
4319 | E\bER\bRR\bRO\bOR\bRS\bS |
4320 | a\bac\bcc\bct\bt() will fail if one of the following is true: |
4321 | |
4322 | [EPERM] The caller is not the superuser. |
4323 | |
4324 | [ENOTDIR] A component of the path prefix is not a directory. |
4325 | |
4326 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
4327 | characters, or an entire pathname (including the |
4328 | terminating NUL) exceeded PATH_MAX bytes. |
4329 | |
4330 | [ENOENT] The named file does not exist. |
4331 | |
4332 | [EACCES] Search permission is denied for a component of the |
4333 | path prefix, or the path name is not a regular file. |
4334 | |
4335 | [ELOOP] Too many symbolic links were encountered in |
4336 | translating the pathname. |
4337 | |
4338 | [EROFS] The named file resides on a read-only file system. |
4339 | |
4340 | [EFAULT] _\bf_\bi_\bl_\be points outside the process's allocated address |
4341 | space. |
4342 | |
4343 | [EIO] An I/O error occurred while reading from or writing to |
4344 | the file system. |
4345 | |
4346 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
4347 | acct(5), accton(8), sa(8) |
4348 | |
4349 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4350 | An a\bac\bcc\bct\bt() function call appeared in Version 7 AT&T UNIX. |
4351 | |
4352 | N\bNA\bAM\bME\bE |
4353 | a\bad\bdj\bjf\bfr\bre\beq\bq - correct the rate of the system clock |
4354 | |
4355 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4356 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
4357 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
4358 | |
4359 | _\bi_\bn_\bt |
4360 | a\bad\bdj\bjf\bfr\bre\beq\bq(_\bc_\bo_\bn_\bs_\bt _\bi_\bn_\bt_\b6_\b4_\b__\bt _\b*_\bf_\br_\be_\bq, _\bi_\bn_\bt_\b6_\b4_\b__\bt _\b*_\bo_\bl_\bd_\bf_\br_\be_\bq); |
4361 | |
4362 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4363 | a\bad\bdj\bjf\bfr\bre\beq\bq() adjusts the rate in which time progresses if _\bf_\br_\be_\bq is non-null. |
4364 | The unit of the rate of adjustment is nanoseconds per second, shifted |
4365 | left 32 bits to allow for fractional values. |
4366 | |
4367 | If _\bo_\bl_\bd_\bf_\br_\be_\bq is non-null, the current value is returned. |
4368 | |
4369 | Only the superuser may adjust the frequency. |
4370 | |
4371 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
4372 | Upon successful completion, the value 0 is returned; otherwise the |
4373 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
4374 | error. |
4375 | |
4376 | E\bER\bRR\bRO\bOR\bRS\bS |
4377 | a\bad\bdj\bjf\bfr\bre\beq\bq() will fail if: |
4378 | |
4379 | [EFAULT] Either of the arguments point outside the process's |
4380 | allocated address space. |
4381 | |
4382 | [EPERM] The _\bf_\br_\be_\bq argument is non-null and the process's |
4383 | effective user ID is not that of the superuser. |
4384 | |
4385 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
4386 | date(1), adjtime(2), gettimeofday(2), ntpd(8) |
4387 | |
4388 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4389 | The a\bad\bdj\bjf\bfr\bre\beq\bq() function call first appeared in OpenBSD 4.0. |
4390 | |
4391 | N\bNA\bAM\bME\bE |
4392 | a\bad\bdj\bjt\bti\bim\bme\be - correct the time to allow synchronization of the system clock |
4393 | |
4394 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4395 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
4396 | |
4397 | _\bi_\bn_\bt |
4398 | a\bad\bdj\bjt\bti\bim\bme\be(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bd_\be_\bl_\bt_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bo_\bl_\bd_\bd_\be_\bl_\bt_\ba); |
4399 | |
4400 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4401 | a\bad\bdj\bjt\bti\bim\bme\be() makes small adjustments to the system time, as returned by |
4402 | gettimeofday(2), advancing or retarding it by the time specified by the |
4403 | timeval _\bd_\be_\bl_\bt_\ba. If _\bd_\be_\bl_\bt_\ba is negative, the clock is slowed down by |
4404 | incrementing it more slowly than normal until the correction is complete. |
4405 | If _\bd_\be_\bl_\bt_\ba is positive, a larger increment than normal is used. The skew |
4406 | used to perform the correction is generally a fraction of one percent. |
4407 | Thus, the time is always a monotonically increasing function. A time |
4408 | correction from an earlier call to a\bad\bdj\bjt\bti\bim\bme\be() may not be finished when |
4409 | a\bad\bdj\bjt\bti\bim\bme\be() is called again. If _\bd_\be_\bl_\bt_\ba is null, no adjustment is done. If |
4410 | _\bo_\bl_\bd_\bd_\be_\bl_\bt_\ba is non-null, the structure pointed to will contain, upon return, |
4411 | the number of microseconds still to be corrected from the earlier call. |
4412 | Setting the time with settimeofday(2) will cancel any in-progress time |
4413 | adjustment. |
4414 | |
4415 | This call may be used by time servers that synchronize the clocks of |
4416 | computers in a local area network. Such time servers would slow down the |
4417 | clocks of some machines and speed up the clocks of others to bring them |
4418 | to the average network time. |
4419 | |
4420 | Only the superuser may adjust the time using the a\bad\bdj\bjt\bti\bim\bme\be() function. |
4421 | |
4422 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
4423 | Upon successful completion, the value 0 is returned; otherwise the |
4424 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
4425 | error. |
4426 | |
4427 | E\bER\bRR\bRO\bOR\bRS\bS |
4428 | a\bad\bdj\bjt\bti\bim\bme\be() will fail if: |
4429 | |
4430 | [EFAULT] Either of the arguments point outside the process's |
4431 | allocated address space. |
4432 | |
4433 | [EPERM] The d\bde\bel\blt\bta\ba() argument is non-null and the process's |
4434 | effective user ID is not that of the superuser. |
4435 | |
4436 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
4437 | date(1), adjfreq(2), gettimeofday(2), ntpd(8) |
4438 | |
4439 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4440 | The a\bad\bdj\bjt\bti\bim\bme\be() function call appeared in 4.3BSD. |
4441 | |
4442 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4443 | Other operating systems restrict calling k\bkq\bqu\bue\beu\bue\be to the superuser and |
4444 | might not allow requesting the current correction without specifying a |
4445 | new value. |
4446 | |
4447 | N\bNA\bAM\bME\bE |
4448 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
4449 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
4450 | ports and memory access functions |
4451 | |
4452 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4453 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
4454 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
4455 | |
4456 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4457 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4458 | |
4459 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4460 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4461 | |
4462 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4463 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4464 | |
4465 | _\bi_\bn_\bt |
4466 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
4467 | |
4468 | _\bv_\bo_\bi_\bd _\b* |
4469 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4470 | |
4471 | _\bv_\bo_\bi_\bd |
4472 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4473 | |
4474 | _\bv_\bo_\bi_\bd |
4475 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4476 | |
4477 | _\bv_\bo_\bi_\bd |
4478 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4479 | |
4480 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4481 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4482 | |
4483 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4484 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4485 | |
4486 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4487 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4488 | |
4489 | _\bv_\bo_\bi_\bd |
4490 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4491 | |
4492 | _\bv_\bo_\bi_\bd |
4493 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4494 | |
4495 | _\bv_\bo_\bi_\bd |
4496 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4497 | |
4498 | _\bv_\bo_\bi_\bd |
4499 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4500 | |
4501 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4502 | The functions in libalpha give userland programs access to the I/O ports |
4503 | on the OpenBSD/alpha platform. |
4504 | |
4505 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
4506 | |
4507 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
4508 | |
4509 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
4510 | disables access if _\bo_\bn is FALSE. |
4511 | |
4512 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
4513 | memory. |
4514 | |
4515 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
4516 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4517 | |
4518 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
4519 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4520 | |
4521 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
4522 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4523 | |
4524 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
4525 | |
4526 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4527 | These functions originally appeared in FreeBSD. |
4528 | |
4529 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4530 | Only BWX bus access method is supported for now. Machines requiring swiz |
4531 | type access are not supported. |
4532 | |
4533 | Root credentials are needed to use these functions. |
4534 | |
4535 | N\bNA\bAM\bME\bE |
4536 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
4537 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
4538 | ports and memory access functions |
4539 | |
4540 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4541 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
4542 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
4543 | |
4544 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4545 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4546 | |
4547 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4548 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4549 | |
4550 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4551 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4552 | |
4553 | _\bi_\bn_\bt |
4554 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
4555 | |
4556 | _\bv_\bo_\bi_\bd _\b* |
4557 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4558 | |
4559 | _\bv_\bo_\bi_\bd |
4560 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4561 | |
4562 | _\bv_\bo_\bi_\bd |
4563 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4564 | |
4565 | _\bv_\bo_\bi_\bd |
4566 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4567 | |
4568 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4569 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4570 | |
4571 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4572 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4573 | |
4574 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4575 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4576 | |
4577 | _\bv_\bo_\bi_\bd |
4578 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4579 | |
4580 | _\bv_\bo_\bi_\bd |
4581 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4582 | |
4583 | _\bv_\bo_\bi_\bd |
4584 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4585 | |
4586 | _\bv_\bo_\bi_\bd |
4587 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4588 | |
4589 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4590 | The functions in libalpha give userland programs access to the I/O ports |
4591 | on the OpenBSD/alpha platform. |
4592 | |
4593 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
4594 | |
4595 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
4596 | |
4597 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
4598 | disables access if _\bo_\bn is FALSE. |
4599 | |
4600 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
4601 | memory. |
4602 | |
4603 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
4604 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4605 | |
4606 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
4607 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4608 | |
4609 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
4610 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4611 | |
4612 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
4613 | |
4614 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4615 | These functions originally appeared in FreeBSD. |
4616 | |
4617 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4618 | Only BWX bus access method is supported for now. Machines requiring swiz |
4619 | type access are not supported. |
4620 | |
4621 | Root credentials are needed to use these functions. |
4622 | |
4623 | N\bNA\bAM\bME\bE |
4624 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
4625 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
4626 | ports and memory access functions |
4627 | |
4628 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4629 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
4630 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
4631 | |
4632 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4633 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4634 | |
4635 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4636 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4637 | |
4638 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4639 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4640 | |
4641 | _\bi_\bn_\bt |
4642 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
4643 | |
4644 | _\bv_\bo_\bi_\bd _\b* |
4645 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4646 | |
4647 | _\bv_\bo_\bi_\bd |
4648 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4649 | |
4650 | _\bv_\bo_\bi_\bd |
4651 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4652 | |
4653 | _\bv_\bo_\bi_\bd |
4654 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4655 | |
4656 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4657 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4658 | |
4659 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4660 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4661 | |
4662 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4663 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4664 | |
4665 | _\bv_\bo_\bi_\bd |
4666 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4667 | |
4668 | _\bv_\bo_\bi_\bd |
4669 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4670 | |
4671 | _\bv_\bo_\bi_\bd |
4672 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4673 | |
4674 | _\bv_\bo_\bi_\bd |
4675 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4676 | |
4677 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4678 | The functions in libalpha give userland programs access to the I/O ports |
4679 | on the OpenBSD/alpha platform. |
4680 | |
4681 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
4682 | |
4683 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
4684 | |
4685 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
4686 | disables access if _\bo_\bn is FALSE. |
4687 | |
4688 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
4689 | memory. |
4690 | |
4691 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
4692 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4693 | |
4694 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
4695 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4696 | |
4697 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
4698 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4699 | |
4700 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
4701 | |
4702 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4703 | These functions originally appeared in FreeBSD. |
4704 | |
4705 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4706 | Only BWX bus access method is supported for now. Machines requiring swiz |
4707 | type access are not supported. |
4708 | |
4709 | Root credentials are needed to use these functions. |
4710 | |
4711 | N\bNA\bAM\bME\bE |
4712 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
4713 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
4714 | ports and memory access functions |
4715 | |
4716 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4717 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
4718 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
4719 | |
4720 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4721 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4722 | |
4723 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4724 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4725 | |
4726 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4727 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4728 | |
4729 | _\bi_\bn_\bt |
4730 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
4731 | |
4732 | _\bv_\bo_\bi_\bd _\b* |
4733 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4734 | |
4735 | _\bv_\bo_\bi_\bd |
4736 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4737 | |
4738 | _\bv_\bo_\bi_\bd |
4739 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4740 | |
4741 | _\bv_\bo_\bi_\bd |
4742 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4743 | |
4744 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4745 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4746 | |
4747 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4748 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4749 | |
4750 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4751 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4752 | |
4753 | _\bv_\bo_\bi_\bd |
4754 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4755 | |
4756 | _\bv_\bo_\bi_\bd |
4757 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4758 | |
4759 | _\bv_\bo_\bi_\bd |
4760 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4761 | |
4762 | _\bv_\bo_\bi_\bd |
4763 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4764 | |
4765 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4766 | The functions in libalpha give userland programs access to the I/O ports |
4767 | on the OpenBSD/alpha platform. |
4768 | |
4769 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
4770 | |
4771 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
4772 | |
4773 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
4774 | disables access if _\bo_\bn is FALSE. |
4775 | |
4776 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
4777 | memory. |
4778 | |
4779 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
4780 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4781 | |
4782 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
4783 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4784 | |
4785 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
4786 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4787 | |
4788 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
4789 | |
4790 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4791 | These functions originally appeared in FreeBSD. |
4792 | |
4793 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4794 | Only BWX bus access method is supported for now. Machines requiring swiz |
4795 | type access are not supported. |
4796 | |
4797 | Root credentials are needed to use these functions. |
4798 | |
4799 | N\bNA\bAM\bME\bE |
4800 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
4801 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
4802 | ports and memory access functions |
4803 | |
4804 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4805 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
4806 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
4807 | |
4808 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4809 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4810 | |
4811 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4812 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4813 | |
4814 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4815 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4816 | |
4817 | _\bi_\bn_\bt |
4818 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
4819 | |
4820 | _\bv_\bo_\bi_\bd _\b* |
4821 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4822 | |
4823 | _\bv_\bo_\bi_\bd |
4824 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4825 | |
4826 | _\bv_\bo_\bi_\bd |
4827 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4828 | |
4829 | _\bv_\bo_\bi_\bd |
4830 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4831 | |
4832 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4833 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4834 | |
4835 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4836 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4837 | |
4838 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4839 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4840 | |
4841 | _\bv_\bo_\bi_\bd |
4842 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4843 | |
4844 | _\bv_\bo_\bi_\bd |
4845 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4846 | |
4847 | _\bv_\bo_\bi_\bd |
4848 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4849 | |
4850 | _\bv_\bo_\bi_\bd |
4851 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4852 | |
4853 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4854 | The functions in libalpha give userland programs access to the I/O ports |
4855 | on the OpenBSD/alpha platform. |
4856 | |
4857 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
4858 | |
4859 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
4860 | |
4861 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
4862 | disables access if _\bo_\bn is FALSE. |
4863 | |
4864 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
4865 | memory. |
4866 | |
4867 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
4868 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4869 | |
4870 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
4871 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4872 | |
4873 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
4874 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4875 | |
4876 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
4877 | |
4878 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4879 | These functions originally appeared in FreeBSD. |
4880 | |
4881 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4882 | Only BWX bus access method is supported for now. Machines requiring swiz |
4883 | type access are not supported. |
4884 | |
4885 | Root credentials are needed to use these functions. |
4886 | |
4887 | N\bNA\bAM\bME\bE |
4888 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
4889 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
4890 | ports and memory access functions |
4891 | |
4892 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4893 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
4894 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
4895 | |
4896 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4897 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4898 | |
4899 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4900 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4901 | |
4902 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4903 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4904 | |
4905 | _\bi_\bn_\bt |
4906 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
4907 | |
4908 | _\bv_\bo_\bi_\bd _\b* |
4909 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4910 | |
4911 | _\bv_\bo_\bi_\bd |
4912 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4913 | |
4914 | _\bv_\bo_\bi_\bd |
4915 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4916 | |
4917 | _\bv_\bo_\bi_\bd |
4918 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4919 | |
4920 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4921 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4922 | |
4923 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4924 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4925 | |
4926 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4927 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
4928 | |
4929 | _\bv_\bo_\bi_\bd |
4930 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4931 | |
4932 | _\bv_\bo_\bi_\bd |
4933 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
4934 | |
4935 | _\bv_\bo_\bi_\bd |
4936 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
4937 | |
4938 | _\bv_\bo_\bi_\bd |
4939 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
4940 | |
4941 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
4942 | The functions in libalpha give userland programs access to the I/O ports |
4943 | on the OpenBSD/alpha platform. |
4944 | |
4945 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
4946 | |
4947 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
4948 | |
4949 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
4950 | disables access if _\bo_\bn is FALSE. |
4951 | |
4952 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
4953 | memory. |
4954 | |
4955 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
4956 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4957 | |
4958 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
4959 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4960 | |
4961 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
4962 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
4963 | |
4964 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
4965 | |
4966 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
4967 | These functions originally appeared in FreeBSD. |
4968 | |
4969 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
4970 | Only BWX bus access method is supported for now. Machines requiring swiz |
4971 | type access are not supported. |
4972 | |
4973 | Root credentials are needed to use these functions. |
4974 | |
4975 | N\bNA\bAM\bME\bE |
4976 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
4977 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
4978 | ports and memory access functions |
4979 | |
4980 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
4981 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
4982 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
4983 | |
4984 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
4985 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4986 | |
4987 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
4988 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4989 | |
4990 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
4991 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
4992 | |
4993 | _\bi_\bn_\bt |
4994 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
4995 | |
4996 | _\bv_\bo_\bi_\bd _\b* |
4997 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
4998 | |
4999 | _\bv_\bo_\bi_\bd |
5000 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5001 | |
5002 | _\bv_\bo_\bi_\bd |
5003 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5004 | |
5005 | _\bv_\bo_\bi_\bd |
5006 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5007 | |
5008 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5009 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5010 | |
5011 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5012 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5013 | |
5014 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5015 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5016 | |
5017 | _\bv_\bo_\bi_\bd |
5018 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5019 | |
5020 | _\bv_\bo_\bi_\bd |
5021 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5022 | |
5023 | _\bv_\bo_\bi_\bd |
5024 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5025 | |
5026 | _\bv_\bo_\bi_\bd |
5027 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5028 | |
5029 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5030 | The functions in libalpha give userland programs access to the I/O ports |
5031 | on the OpenBSD/alpha platform. |
5032 | |
5033 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5034 | |
5035 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5036 | |
5037 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5038 | disables access if _\bo_\bn is FALSE. |
5039 | |
5040 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5041 | memory. |
5042 | |
5043 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5044 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5045 | |
5046 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5047 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5048 | |
5049 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5050 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5051 | |
5052 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5053 | |
5054 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5055 | These functions originally appeared in FreeBSD. |
5056 | |
5057 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5058 | Only BWX bus access method is supported for now. Machines requiring swiz |
5059 | type access are not supported. |
5060 | |
5061 | Root credentials are needed to use these functions. |
5062 | |
5063 | N\bNA\bAM\bME\bE |
5064 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5065 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5066 | ports and memory access functions |
5067 | |
5068 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5069 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5070 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5071 | |
5072 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5073 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5074 | |
5075 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5076 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5077 | |
5078 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5079 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5080 | |
5081 | _\bi_\bn_\bt |
5082 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5083 | |
5084 | _\bv_\bo_\bi_\bd _\b* |
5085 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5086 | |
5087 | _\bv_\bo_\bi_\bd |
5088 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5089 | |
5090 | _\bv_\bo_\bi_\bd |
5091 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5092 | |
5093 | _\bv_\bo_\bi_\bd |
5094 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5095 | |
5096 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5097 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5098 | |
5099 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5100 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5101 | |
5102 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5103 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5104 | |
5105 | _\bv_\bo_\bi_\bd |
5106 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5107 | |
5108 | _\bv_\bo_\bi_\bd |
5109 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5110 | |
5111 | _\bv_\bo_\bi_\bd |
5112 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5113 | |
5114 | _\bv_\bo_\bi_\bd |
5115 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5116 | |
5117 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5118 | The functions in libalpha give userland programs access to the I/O ports |
5119 | on the OpenBSD/alpha platform. |
5120 | |
5121 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5122 | |
5123 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5124 | |
5125 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5126 | disables access if _\bo_\bn is FALSE. |
5127 | |
5128 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5129 | memory. |
5130 | |
5131 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5132 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5133 | |
5134 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5135 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5136 | |
5137 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5138 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5139 | |
5140 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5141 | |
5142 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5143 | These functions originally appeared in FreeBSD. |
5144 | |
5145 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5146 | Only BWX bus access method is supported for now. Machines requiring swiz |
5147 | type access are not supported. |
5148 | |
5149 | Root credentials are needed to use these functions. |
5150 | |
5151 | N\bNA\bAM\bME\bE |
5152 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5153 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5154 | ports and memory access functions |
5155 | |
5156 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5157 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5158 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5159 | |
5160 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5161 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5162 | |
5163 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5164 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5165 | |
5166 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5167 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5168 | |
5169 | _\bi_\bn_\bt |
5170 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5171 | |
5172 | _\bv_\bo_\bi_\bd _\b* |
5173 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5174 | |
5175 | _\bv_\bo_\bi_\bd |
5176 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5177 | |
5178 | _\bv_\bo_\bi_\bd |
5179 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5180 | |
5181 | _\bv_\bo_\bi_\bd |
5182 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5183 | |
5184 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5185 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5186 | |
5187 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5188 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5189 | |
5190 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5191 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5192 | |
5193 | _\bv_\bo_\bi_\bd |
5194 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5195 | |
5196 | _\bv_\bo_\bi_\bd |
5197 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5198 | |
5199 | _\bv_\bo_\bi_\bd |
5200 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5201 | |
5202 | _\bv_\bo_\bi_\bd |
5203 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5204 | |
5205 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5206 | The functions in libalpha give userland programs access to the I/O ports |
5207 | on the OpenBSD/alpha platform. |
5208 | |
5209 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5210 | |
5211 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5212 | |
5213 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5214 | disables access if _\bo_\bn is FALSE. |
5215 | |
5216 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5217 | memory. |
5218 | |
5219 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5220 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5221 | |
5222 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5223 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5224 | |
5225 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5226 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5227 | |
5228 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5229 | |
5230 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5231 | These functions originally appeared in FreeBSD. |
5232 | |
5233 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5234 | Only BWX bus access method is supported for now. Machines requiring swiz |
5235 | type access are not supported. |
5236 | |
5237 | Root credentials are needed to use these functions. |
5238 | |
5239 | N\bNA\bAM\bME\bE |
5240 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5241 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5242 | ports and memory access functions |
5243 | |
5244 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5245 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5246 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5247 | |
5248 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5249 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5250 | |
5251 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5252 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5253 | |
5254 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5255 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5256 | |
5257 | _\bi_\bn_\bt |
5258 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5259 | |
5260 | _\bv_\bo_\bi_\bd _\b* |
5261 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5262 | |
5263 | _\bv_\bo_\bi_\bd |
5264 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5265 | |
5266 | _\bv_\bo_\bi_\bd |
5267 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5268 | |
5269 | _\bv_\bo_\bi_\bd |
5270 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5271 | |
5272 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5273 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5274 | |
5275 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5276 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5277 | |
5278 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5279 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5280 | |
5281 | _\bv_\bo_\bi_\bd |
5282 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5283 | |
5284 | _\bv_\bo_\bi_\bd |
5285 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5286 | |
5287 | _\bv_\bo_\bi_\bd |
5288 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5289 | |
5290 | _\bv_\bo_\bi_\bd |
5291 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5292 | |
5293 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5294 | The functions in libalpha give userland programs access to the I/O ports |
5295 | on the OpenBSD/alpha platform. |
5296 | |
5297 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5298 | |
5299 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5300 | |
5301 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5302 | disables access if _\bo_\bn is FALSE. |
5303 | |
5304 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5305 | memory. |
5306 | |
5307 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5308 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5309 | |
5310 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5311 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5312 | |
5313 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5314 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5315 | |
5316 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5317 | |
5318 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5319 | These functions originally appeared in FreeBSD. |
5320 | |
5321 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5322 | Only BWX bus access method is supported for now. Machines requiring swiz |
5323 | type access are not supported. |
5324 | |
5325 | Root credentials are needed to use these functions. |
5326 | |
5327 | N\bNA\bAM\bME\bE |
5328 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5329 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5330 | ports and memory access functions |
5331 | |
5332 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5333 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5334 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5335 | |
5336 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5337 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5338 | |
5339 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5340 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5341 | |
5342 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5343 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5344 | |
5345 | _\bi_\bn_\bt |
5346 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5347 | |
5348 | _\bv_\bo_\bi_\bd _\b* |
5349 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5350 | |
5351 | _\bv_\bo_\bi_\bd |
5352 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5353 | |
5354 | _\bv_\bo_\bi_\bd |
5355 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5356 | |
5357 | _\bv_\bo_\bi_\bd |
5358 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5359 | |
5360 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5361 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5362 | |
5363 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5364 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5365 | |
5366 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5367 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5368 | |
5369 | _\bv_\bo_\bi_\bd |
5370 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5371 | |
5372 | _\bv_\bo_\bi_\bd |
5373 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5374 | |
5375 | _\bv_\bo_\bi_\bd |
5376 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5377 | |
5378 | _\bv_\bo_\bi_\bd |
5379 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5380 | |
5381 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5382 | The functions in libalpha give userland programs access to the I/O ports |
5383 | on the OpenBSD/alpha platform. |
5384 | |
5385 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5386 | |
5387 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5388 | |
5389 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5390 | disables access if _\bo_\bn is FALSE. |
5391 | |
5392 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5393 | memory. |
5394 | |
5395 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5396 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5397 | |
5398 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5399 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5400 | |
5401 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5402 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5403 | |
5404 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5405 | |
5406 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5407 | These functions originally appeared in FreeBSD. |
5408 | |
5409 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5410 | Only BWX bus access method is supported for now. Machines requiring swiz |
5411 | type access are not supported. |
5412 | |
5413 | Root credentials are needed to use these functions. |
5414 | |
5415 | N\bNA\bAM\bME\bE |
5416 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5417 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5418 | ports and memory access functions |
5419 | |
5420 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5421 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5422 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5423 | |
5424 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5425 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5426 | |
5427 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5428 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5429 | |
5430 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5431 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5432 | |
5433 | _\bi_\bn_\bt |
5434 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5435 | |
5436 | _\bv_\bo_\bi_\bd _\b* |
5437 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5438 | |
5439 | _\bv_\bo_\bi_\bd |
5440 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5441 | |
5442 | _\bv_\bo_\bi_\bd |
5443 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5444 | |
5445 | _\bv_\bo_\bi_\bd |
5446 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5447 | |
5448 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5449 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5450 | |
5451 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5452 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5453 | |
5454 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5455 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5456 | |
5457 | _\bv_\bo_\bi_\bd |
5458 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5459 | |
5460 | _\bv_\bo_\bi_\bd |
5461 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5462 | |
5463 | _\bv_\bo_\bi_\bd |
5464 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5465 | |
5466 | _\bv_\bo_\bi_\bd |
5467 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5468 | |
5469 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5470 | The functions in libalpha give userland programs access to the I/O ports |
5471 | on the OpenBSD/alpha platform. |
5472 | |
5473 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5474 | |
5475 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5476 | |
5477 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5478 | disables access if _\bo_\bn is FALSE. |
5479 | |
5480 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5481 | memory. |
5482 | |
5483 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5484 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5485 | |
5486 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5487 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5488 | |
5489 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5490 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5491 | |
5492 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5493 | |
5494 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5495 | These functions originally appeared in FreeBSD. |
5496 | |
5497 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5498 | Only BWX bus access method is supported for now. Machines requiring swiz |
5499 | type access are not supported. |
5500 | |
5501 | Root credentials are needed to use these functions. |
5502 | |
5503 | N\bNA\bAM\bME\bE |
5504 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5505 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5506 | ports and memory access functions |
5507 | |
5508 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5509 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5510 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5511 | |
5512 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5513 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5514 | |
5515 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5516 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5517 | |
5518 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5519 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5520 | |
5521 | _\bi_\bn_\bt |
5522 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5523 | |
5524 | _\bv_\bo_\bi_\bd _\b* |
5525 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5526 | |
5527 | _\bv_\bo_\bi_\bd |
5528 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5529 | |
5530 | _\bv_\bo_\bi_\bd |
5531 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5532 | |
5533 | _\bv_\bo_\bi_\bd |
5534 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5535 | |
5536 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5537 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5538 | |
5539 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5540 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5541 | |
5542 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5543 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5544 | |
5545 | _\bv_\bo_\bi_\bd |
5546 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5547 | |
5548 | _\bv_\bo_\bi_\bd |
5549 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5550 | |
5551 | _\bv_\bo_\bi_\bd |
5552 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5553 | |
5554 | _\bv_\bo_\bi_\bd |
5555 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5556 | |
5557 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5558 | The functions in libalpha give userland programs access to the I/O ports |
5559 | on the OpenBSD/alpha platform. |
5560 | |
5561 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5562 | |
5563 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5564 | |
5565 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5566 | disables access if _\bo_\bn is FALSE. |
5567 | |
5568 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5569 | memory. |
5570 | |
5571 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5572 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5573 | |
5574 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5575 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5576 | |
5577 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5578 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5579 | |
5580 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5581 | |
5582 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5583 | These functions originally appeared in FreeBSD. |
5584 | |
5585 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5586 | Only BWX bus access method is supported for now. Machines requiring swiz |
5587 | type access are not supported. |
5588 | |
5589 | Root credentials are needed to use these functions. |
5590 | |
5591 | N\bNA\bAM\bME\bE |
5592 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5593 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5594 | ports and memory access functions |
5595 | |
5596 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5597 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5598 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5599 | |
5600 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5601 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5602 | |
5603 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5604 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5605 | |
5606 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5607 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5608 | |
5609 | _\bi_\bn_\bt |
5610 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5611 | |
5612 | _\bv_\bo_\bi_\bd _\b* |
5613 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5614 | |
5615 | _\bv_\bo_\bi_\bd |
5616 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5617 | |
5618 | _\bv_\bo_\bi_\bd |
5619 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5620 | |
5621 | _\bv_\bo_\bi_\bd |
5622 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5623 | |
5624 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5625 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5626 | |
5627 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5628 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5629 | |
5630 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5631 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5632 | |
5633 | _\bv_\bo_\bi_\bd |
5634 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5635 | |
5636 | _\bv_\bo_\bi_\bd |
5637 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5638 | |
5639 | _\bv_\bo_\bi_\bd |
5640 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5641 | |
5642 | _\bv_\bo_\bi_\bd |
5643 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5644 | |
5645 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5646 | The functions in libalpha give userland programs access to the I/O ports |
5647 | on the OpenBSD/alpha platform. |
5648 | |
5649 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5650 | |
5651 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5652 | |
5653 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5654 | disables access if _\bo_\bn is FALSE. |
5655 | |
5656 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5657 | memory. |
5658 | |
5659 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5660 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5661 | |
5662 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5663 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5664 | |
5665 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5666 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5667 | |
5668 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5669 | |
5670 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5671 | These functions originally appeared in FreeBSD. |
5672 | |
5673 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5674 | Only BWX bus access method is supported for now. Machines requiring swiz |
5675 | type access are not supported. |
5676 | |
5677 | Root credentials are needed to use these functions. |
5678 | |
5679 | N\bNA\bAM\bME\bE |
5680 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5681 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5682 | ports and memory access functions |
5683 | |
5684 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5685 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5686 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5687 | |
5688 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5689 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5690 | |
5691 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5692 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5693 | |
5694 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5695 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5696 | |
5697 | _\bi_\bn_\bt |
5698 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5699 | |
5700 | _\bv_\bo_\bi_\bd _\b* |
5701 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5702 | |
5703 | _\bv_\bo_\bi_\bd |
5704 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5705 | |
5706 | _\bv_\bo_\bi_\bd |
5707 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5708 | |
5709 | _\bv_\bo_\bi_\bd |
5710 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5711 | |
5712 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5713 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5714 | |
5715 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5716 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5717 | |
5718 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5719 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5720 | |
5721 | _\bv_\bo_\bi_\bd |
5722 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5723 | |
5724 | _\bv_\bo_\bi_\bd |
5725 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5726 | |
5727 | _\bv_\bo_\bi_\bd |
5728 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5729 | |
5730 | _\bv_\bo_\bi_\bd |
5731 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5732 | |
5733 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5734 | The functions in libalpha give userland programs access to the I/O ports |
5735 | on the OpenBSD/alpha platform. |
5736 | |
5737 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5738 | |
5739 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5740 | |
5741 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5742 | disables access if _\bo_\bn is FALSE. |
5743 | |
5744 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5745 | memory. |
5746 | |
5747 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5748 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5749 | |
5750 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5751 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5752 | |
5753 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5754 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5755 | |
5756 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5757 | |
5758 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5759 | These functions originally appeared in FreeBSD. |
5760 | |
5761 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5762 | Only BWX bus access method is supported for now. Machines requiring swiz |
5763 | type access are not supported. |
5764 | |
5765 | Root credentials are needed to use these functions. |
5766 | |
5767 | N\bNA\bAM\bME\bE |
5768 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be, i\bin\bnb\bb, i\bin\bnl\bl, i\bin\bnw\bw, i\bio\bop\bpe\ber\brm\bm, m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, o\bou\but\btb\bb, o\bou\but\btl\bl, o\bou\but\btw\bw, r\bre\bea\bad\bdb\bb, |
5769 | r\bre\bea\bad\bdl\bl, r\bre\bea\bad\bdw\bw, u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by, w\bwr\bri\bit\bte\beb\bb, w\bwr\bri\bit\bte\bel\bl, w\bwr\bri\bit\bte\bew\bw - Alpha devices I/O |
5770 | ports and memory access functions |
5771 | |
5772 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5773 | _\bu_\b__\bi_\bn_\bt_\b6_\b4_\b__\bt |
5774 | d\bde\ben\bns\bse\be_\b_b\bba\bas\bse\be(_\bv_\bo_\bi_\bd); |
5775 | |
5776 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5777 | i\bin\bnb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5778 | |
5779 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5780 | i\bin\bnl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5781 | |
5782 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5783 | i\bin\bnw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt); |
5784 | |
5785 | _\bi_\bn_\bt |
5786 | i\bio\bop\bpe\ber\brm\bm(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bf_\br_\bo_\bm, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\bn_\bu_\bm, _\bi_\bn_\bt _\bo_\bn); |
5787 | |
5788 | _\bv_\bo_\bi_\bd _\b* |
5789 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\ba_\bd_\bd_\br_\be_\bs_\bs, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5790 | |
5791 | _\bv_\bo_\bi_\bd |
5792 | o\bou\but\btb\bb(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5793 | |
5794 | _\bv_\bo_\bi_\bd |
5795 | o\bou\but\btl\bl(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5796 | |
5797 | _\bv_\bo_\bi_\bd |
5798 | o\bou\but\btw\bw(_\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bp_\bo_\br_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5799 | |
5800 | _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt |
5801 | r\bre\bea\bad\bdb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5802 | |
5803 | _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt |
5804 | r\bre\bea\bad\bdl\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5805 | |
5806 | _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt |
5807 | r\bre\bea\bad\bdw\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
5808 | |
5809 | _\bv_\bo_\bi_\bd |
5810 | u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bs_\bi_\bz_\be); |
5811 | |
5812 | _\bv_\bo_\bi_\bd |
5813 | w\bwr\bri\bit\bte\beb\bb(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b8_\b__\bt _\bv_\ba_\bl); |
5814 | |
5815 | _\bv_\bo_\bi_\bd |
5816 | w\bwr\bri\bit\bte\bel\bl(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bv_\ba_\bl); |
5817 | |
5818 | _\bv_\bo_\bi_\bd |
5819 | w\bwr\bri\bit\bte\bew\bw(_\bv_\bo_\bi_\bd _\b*_\bh_\ba_\bn_\bd_\bl_\be, _\bu_\b__\bi_\bn_\bt_\b3_\b2_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt_\b1_\b6_\b__\bt _\bv_\ba_\bl); |
5820 | |
5821 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5822 | The functions in libalpha give userland programs access to the I/O ports |
5823 | on the OpenBSD/alpha platform. |
5824 | |
5825 | The i\bin\bn*\b*() functions return data read from the specified I/O port. |
5826 | |
5827 | The o\bou\but\bt*\b*() functions write data to the specified I/O port. |
5828 | |
5829 | i\bio\bop\bpe\ber\brm\bm() enables access to the specified port numbers if _\bo_\bn is TRUE and |
5830 | disables access if _\bo_\bn is FALSE. |
5831 | |
5832 | The m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function allows a user program to map part of a device |
5833 | memory. |
5834 | |
5835 | The u\bun\bnm\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by() function unmaps memory that was previously mapped by |
5836 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5837 | |
5838 | The r\bre\bea\bad\bd*\b*() functions read data from device memory previously mapped by |
5839 | m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5840 | |
5841 | The w\bwr\bri\bit\bte\be*\b*() functions write data to the device memory previously mapped |
5842 | by m\bma\bap\bp_\b_m\bme\bem\bmo\bor\bry\by(). |
5843 | |
5844 | N\bNo\bot\bte\be: Code using these functions must be compiled using -\b-l\bla\bal\blp\bph\bha\ba. |
5845 | |
5846 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
5847 | These functions originally appeared in FreeBSD. |
5848 | |
5849 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
5850 | Only BWX bus access method is supported for now. Machines requiring swiz |
5851 | type access are not supported. |
5852 | |
5853 | Root credentials are needed to use these functions. |
5854 | |
5855 | N\bNA\bAM\bME\bE |
5856 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be, a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be - manage amd64 per-thread %fs base |
5857 | address |
5858 | |
5859 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5860 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
5861 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
5862 | |
5863 | _\bi_\bn_\bt |
5864 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
5865 | |
5866 | _\bi_\bn_\bt |
5867 | a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
5868 | |
5869 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5870 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() copies the current base address of the %fs segment |
5871 | into the memory referenced by _\bb_\ba_\bs_\be. |
5872 | |
5873 | a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() sets the base address of the %fs segment to the |
5874 | address _\bb_\ba_\bs_\be. |
5875 | |
5876 | The segment base address is local to each thread. The initial thread of |
5877 | a new process inherits its segment base address from the parent thread. |
5878 | __tfork(2) sets the initial segment base address for threads that it |
5879 | creates. |
5880 | |
5881 | N\bNo\bot\bte\be:\b: Code using the a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() functions |
5882 | must be compiled using -\b-l\bla\bam\bmd\bd6\b64\b4. |
5883 | |
5884 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
5885 | Upon successful completion, a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() |
5886 | return 0. Otherwise, a value of -1 is returned and the global variable |
5887 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
5888 | |
5889 | E\bER\bRR\bRO\bOR\bRS\bS |
5890 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() will fail if: |
5891 | |
5892 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
5893 | |
5894 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
5895 | __tfork(2), fork(2) |
5896 | |
5897 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
5898 | The ELF Thread-Local Storage ABI reserves %fs for its own use and |
5899 | requires that the dynamic linker and thread library set it to reference |
5900 | data-structures internal to and shared between them. Programs should use |
5901 | the __thread storage class keyword instead of using these calls. To be |
5902 | maximally portable, programs that require per-thread data should use the |
5903 | p\bpt\bth\bhr\bre\bea\bad\bd_\b_k\bke\bey\by_\b_c\bcr\bre\bea\bat\bte\be() interface. |
5904 | |
5905 | N\bNA\bAM\bME\bE |
5906 | a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl - change the amd64 I/O privilege level |
5907 | |
5908 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5909 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
5910 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
5911 | |
5912 | _\bi_\bn_\bt |
5913 | a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl(_\bi_\bn_\bt _\bi_\bo_\bp_\bl); |
5914 | |
5915 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5916 | a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl() sets the amd64 I/O privilege level to the value specified by |
5917 | _\bi_\bo_\bp_\bl. |
5918 | |
5919 | This call may only be made by the superuser. Additionally, it is only |
5920 | permitted when the securelevel(7) is less than or equal to 0 or the |
5921 | _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be sysctl has been set to a non-zero value. |
5922 | |
5923 | N\bNo\bot\bte\be:\b: Code using the a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl() function must be compiled using |
5924 | -\b-l\bla\bam\bmd\bd6\b64\b4. |
5925 | |
5926 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
5927 | Upon successful completion, a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl() returns 0. Otherwise, a value |
5928 | of -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
5929 | error. |
5930 | |
5931 | E\bER\bRR\bRO\bOR\bRS\bS |
5932 | a\bam\bmd\bd6\b64\b4_\b_i\bio\bop\bpl\bl() will fail if: |
5933 | |
5934 | [EPERM] The caller was not the superuser, or the securelevel is greater |
5935 | than zero and _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be has not been set to a non- |
5936 | zero value. |
5937 | |
5938 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
5939 | securelevel(7) |
5940 | |
5941 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
5942 | Intel, _\bA_\bM_\bD_\b6_\b4 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
5943 | |
5944 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
5945 | You can really hose your machine if you enable user-level I/O and write |
5946 | to hardware ports without care. |
5947 | |
5948 | N\bNA\bAM\bME\bE |
5949 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be, a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be - manage amd64 per-thread %fs base |
5950 | address |
5951 | |
5952 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
5953 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
5954 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
5955 | |
5956 | _\bi_\bn_\bt |
5957 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
5958 | |
5959 | _\bi_\bn_\bt |
5960 | a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
5961 | |
5962 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
5963 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() copies the current base address of the %fs segment |
5964 | into the memory referenced by _\bb_\ba_\bs_\be. |
5965 | |
5966 | a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() sets the base address of the %fs segment to the |
5967 | address _\bb_\ba_\bs_\be. |
5968 | |
5969 | The segment base address is local to each thread. The initial thread of |
5970 | a new process inherits its segment base address from the parent thread. |
5971 | __tfork(2) sets the initial segment base address for threads that it |
5972 | creates. |
5973 | |
5974 | N\bNo\bot\bte\be:\b: Code using the a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() functions |
5975 | must be compiled using -\b-l\bla\bam\bmd\bd6\b64\b4. |
5976 | |
5977 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
5978 | Upon successful completion, a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and a\bam\bmd\bd6\b64\b4_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() |
5979 | return 0. Otherwise, a value of -1 is returned and the global variable |
5980 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
5981 | |
5982 | E\bER\bRR\bRO\bOR\bRS\bS |
5983 | a\bam\bmd\bd6\b64\b4_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() will fail if: |
5984 | |
5985 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
5986 | |
5987 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
5988 | __tfork(2), fork(2) |
5989 | |
5990 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
5991 | The ELF Thread-Local Storage ABI reserves %fs for its own use and |
5992 | requires that the dynamic linker and thread library set it to reference |
5993 | data-structures internal to and shared between them. Programs should use |
5994 | the __thread storage class keyword instead of using these calls. To be |
5995 | maximally portable, programs that require per-thread data should use the |
5996 | p\bpt\bth\bhr\bre\bea\bad\bd_\b_k\bke\bey\by_\b_c\bcr\bre\bea\bat\bte\be() interface. |
5997 | |
5998 | N\bNA\bAM\bME\bE |
5999 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf - drains the CPU write buffer |
6000 | |
6001 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6002 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
6003 | |
6004 | _\bi_\bn_\bt |
6005 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf(); |
6006 | |
6007 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6008 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf() will make sure that all the entries in the processor |
6009 | write buffer are written out to memory. |
6010 | |
6011 | Not all processors support this operation (currently only the SA110 |
6012 | does). Those processes that do not, treat this function as a null-op. |
6013 | |
6014 | E\bER\bRR\bRO\bOR\bRS\bS |
6015 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf() will never fail so will always return 0. |
6016 | |
6017 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
6018 | StrongARM Data Sheet |
6019 | |
6020 | N\bNA\bAM\bME\bE |
6021 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be - clean the CPU data cache and flush the CPU instruction |
6022 | cache |
6023 | |
6024 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6025 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
6026 | |
6027 | _\bi_\bn_\bt |
6028 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be(_\bu_\b__\bi_\bn_\bt _\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bl_\be_\bn); |
6029 | |
6030 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6031 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will make sure that all the entries in the processor |
6032 | instruction cache are synchronized with main memory and that any data in |
6033 | a write back cache has been cleaned. Some ARM processors (e.g. SA110) |
6034 | have separate instruction and data caches, thus any dynamically generated |
6035 | or modified code needs to be written back from any data caches to main |
6036 | memory and the instruction cache needs to be synchronized with main |
6037 | memory. |
6038 | |
6039 | On such processors, a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will clean the data cache and |
6040 | invalidate the processor instruction cache to force reloading from main |
6041 | memory. On processors that have a shared instruction and data cache and |
6042 | have a write through cache (e.g. ARM6), no action needs to be taken. |
6043 | |
6044 | The routine takes a start address _\ba_\bd_\bd_\br and a length _\bl_\be_\bn to describe the |
6045 | area of memory that needs to be cleaned and synchronized. |
6046 | |
6047 | E\bER\bRR\bRO\bOR\bRS\bS |
6048 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will never fail so will always return 0. |
6049 | |
6050 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
6051 | StrongARM Data Sheet |
6052 | |
6053 | N\bNA\bAM\bME\bE |
6054 | b\bbi\bin\bnd\bd - bind a name to a socket |
6055 | |
6056 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6057 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
6058 | |
6059 | _\bi_\bn_\bt |
6060 | b\bbi\bin\bnd\bd(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
6061 | |
6062 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6063 | b\bbi\bin\bnd\bd() assigns a name to an unnamed socket. When a socket is created |
6064 | with socket(2) it exists in a name space (address family) but has no name |
6065 | assigned. b\bbi\bin\bnd\bd() requests that _\bn_\ba_\bm_\be be assigned to the socket. _\bn_\ba_\bm_\be_\bl_\be_\bn |
6066 | indicates the amount of space pointed to by _\bn_\ba_\bm_\be, in bytes. |
6067 | |
6068 | N\bNO\bOT\bTE\bES\bS |
6069 | Binding a name in the UNIX-domain creates a socket in the file system |
6070 | that must be deleted by the caller when it is no longer needed (using |
6071 | unlink(2)). |
6072 | |
6073 | The rules used in name binding vary between communication domains. |
6074 | Consult the manual entries in section 4 for detailed information. |
6075 | |
6076 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6077 | Upon successful completion, the value 0 is returned; otherwise the |
6078 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6079 | error. |
6080 | |
6081 | E\bER\bRR\bRO\bOR\bRS\bS |
6082 | The b\bbi\bin\bnd\bd() function will fail if: |
6083 | |
6084 | [EBADF] _\bs is not a valid descriptor. |
6085 | |
6086 | [ENOTSOCK] _\bs is not a socket. |
6087 | |
6088 | [EADDRNOTAVAIL] The specified address is not available from the local |
6089 | machine. |
6090 | |
6091 | [EADDRINUSE] The specified address is already in use. |
6092 | |
6093 | [EINVAL] The socket is already bound to an address, or _\bn_\ba_\bm_\be_\bl_\be_\bn |
6094 | is not a valid length for the supplied address. |
6095 | |
6096 | [EAFNOSUPPORT] The family of the socket and that requested in |
6097 | _\bn_\ba_\bm_\be_\b-_\b>_\bs_\ba_\b__\bf_\ba_\bm_\bi_\bl_\by are not equivalent. |
6098 | |
6099 | [ENOBUFS] Insufficient buffer space is available. |
6100 | |
6101 | [EACCES] The requested address is protected, and the current |
6102 | user has inadequate permission to access it. |
6103 | |
6104 | [EFAULT] The _\bn_\ba_\bm_\be parameter is not in a valid part of the user |
6105 | address space. |
6106 | |
6107 | The following errors are specific to binding names in the UNIX-domain. |
6108 | |
6109 | [ENOTDIR] A component of the path prefix is not a directory. |
6110 | |
6111 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
6112 | characters, or an entire pathname (including the |
6113 | terminating NUL) exceeded PATH_MAX bytes. |
6114 | |
6115 | [ENOENT] A prefix component of the path name does not exist. |
6116 | |
6117 | [ELOOP] Too many symbolic links were encountered in |
6118 | translating the pathname. |
6119 | |
6120 | [EIO] An I/O error occurred while making the directory entry |
6121 | or allocating the inode. |
6122 | |
6123 | [EROFS] The name would reside on a read-only file system. |
6124 | |
6125 | [EISDIR] An empty pathname was specified. |
6126 | |
6127 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
6128 | connect(2), getsockname(2), listen(2), socket(2) |
6129 | |
6130 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
6131 | The b\bbi\bin\bnd\bd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
6132 | |
6133 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
6134 | The b\bbi\bin\bnd\bd() system call first appeared in 4.1cBSD. |
6135 | |
6136 | N\bNA\bAM\bME\bE |
6137 | b\bbr\brk\bk, s\bsb\bbr\brk\bk - change data segment size |
6138 | |
6139 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6140 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
6141 | |
6142 | _\bi_\bn_\bt |
6143 | b\bbr\brk\bk(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br); |
6144 | |
6145 | _\bv_\bo_\bi_\bd _\b* |
6146 | s\bsb\bbr\brk\bk(_\bi_\bn_\bt _\bi_\bn_\bc_\br); |
6147 | |
6148 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6149 | T\bTh\bhe\be b\bbr\brk\bk(\b()\b) a\ban\bnd\bd s\bsb\bbr\brk\bk(\b()\b) f\bfu\bun\bnc\bct\bti\bio\bon\bns\bs a\bar\bre\be h\bhi\bis\bst\bto\bor\bri\bic\bca\bal\bl c\bcu\bur\bri\bio\bos\bsi\bit\bti\bie\bes\bs l\ble\bef\bft\bt o\bov\bve\ber\br f\bfr\bro\bom\bm |
6150 | e\bea\bar\brl\bli\bie\ber\br d\bda\bay\bys\bs b\bbe\bef\bfo\bor\bre\be t\bth\bhe\be a\bad\bdv\bve\ben\bnt\bt o\bof\bf v\bvi\bir\brt\btu\bua\bal\bl m\bme\bem\bmo\bor\bry\by m\bma\ban\bna\bag\bge\bem\bme\ben\bnt\bt.\b. The b\bbr\brk\bk() |
6151 | function sets the break or lowest address of a process's data segment |
6152 | (uninitialized data) to _\ba_\bd_\bd_\br (immediately above bss). Data addressing is |
6153 | restricted between _\ba_\bd_\bd_\br and the lowest stack pointer to the stack |
6154 | segment. Memory is allocated by b\bbr\brk\bk() in page size pieces; if _\ba_\bd_\bd_\br is |
6155 | not evenly divisible by the system page size, it is increased to the next |
6156 | page boundary. |
6157 | |
6158 | The current value of the program break is reliably returned by |
6159 | ``sbrk(0)'' (see also end(3)). The getrlimit(2) system call may be used |
6160 | to determine the maximum permissible size of the _\bd_\ba_\bt_\ba segment; it will |
6161 | not be possible to set the break beyond the _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx value returned from |
6162 | a call to getrlimit(2), e.g., ``etext + rlp->rlim_max'' (see end(3) for |
6163 | the definition of _\be_\bt_\be_\bx_\bt). |
6164 | |
6165 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6166 | The b\bbr\brk\bk() function returns the value 0 if successful; otherwise the |
6167 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6168 | error. |
6169 | |
6170 | The s\bsb\bbr\brk\bk() function returns a pointer to the base of the new storage if |
6171 | successful; otherwise -1 with _\be_\br_\br_\bn_\bo set to indicate why the allocation |
6172 | failed. |
6173 | |
6174 | E\bER\bRR\bRO\bOR\bRS\bS |
6175 | s\bsb\bbr\brk\bk() will fail and no additional memory will be allocated if one of the |
6176 | following are true: |
6177 | |
6178 | [ENOMEM] The limit, as set by setrlimit(2), was exceeded. |
6179 | |
6180 | [ENOMEM] The maximum possible size of a data segment (compiled |
6181 | into the system) was exceeded. |
6182 | |
6183 | [ENOMEM] Insufficient space existed in the swap area to support |
6184 | the expansion. |
6185 | |
6186 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
6187 | execve(2), getrlimit(2), mmap(2), end(3), malloc(3) |
6188 | |
6189 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
6190 | A b\bbr\brk\bk() function call appeared in Version 7 AT&T UNIX. |
6191 | |
6192 | B\bBU\bUG\bGS\bS |
6193 | Setting the break may fail due to a temporary lack of swap space. It is |
6194 | not possible to distinguish this from a failure caused by exceeding the |
6195 | maximum size of the data segment without consulting getrlimit(2). |
6196 | |
6197 | N\bNA\bAM\bME\bE |
6198 | c\bch\bhd\bdi\bir\br, f\bfc\bch\bhd\bdi\bir\br - change current working directory |
6199 | |
6200 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6201 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
6202 | |
6203 | _\bi_\bn_\bt |
6204 | c\bch\bhd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
6205 | |
6206 | _\bi_\bn_\bt |
6207 | f\bfc\bch\bhd\bdi\bir\br(_\bi_\bn_\bt _\bf_\bd); |
6208 | |
6209 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6210 | The _\bp_\ba_\bt_\bh argument points to the pathname of a directory. The c\bch\bhd\bdi\bir\br() |
6211 | function causes the named directory to become the current working |
6212 | directory, that is, the starting point for path searches of pathnames not |
6213 | beginning with a slash (`/'). |
6214 | |
6215 | The f\bfc\bch\bhd\bdi\bir\br() function causes the directory referenced by _\bf_\bd to become the |
6216 | current working directory, the starting point for path searches of |
6217 | pathnames not beginning with a slash (`/'). |
6218 | |
6219 | In order for a directory to become the current directory, a process must |
6220 | have execute (search) access to the directory. |
6221 | |
6222 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6223 | Upon successful completion, the value 0 is returned; otherwise the |
6224 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6225 | error. |
6226 | |
6227 | E\bER\bRR\bRO\bOR\bRS\bS |
6228 | c\bch\bhd\bdi\bir\br() will fail and the current working directory will be unchanged if |
6229 | one or more of the following are true: |
6230 | |
6231 | [ENOTDIR] A component of the path prefix is not a directory. |
6232 | |
6233 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
6234 | characters, or an entire pathname (including the |
6235 | terminating NUL) exceeded PATH_MAX bytes. |
6236 | |
6237 | [ENOENT] The named directory does not exist. |
6238 | |
6239 | [ELOOP] Too many symbolic links were encountered in |
6240 | translating the pathname. |
6241 | |
6242 | [EACCES] Search permission is denied for any component of the |
6243 | pathname. |
6244 | |
6245 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
6246 | space. |
6247 | |
6248 | [EIO] An I/O error occurred while reading from the file |
6249 | system. |
6250 | |
6251 | f\bfc\bch\bhd\bdi\bir\br() will fail and the current working directory will be unchanged if |
6252 | one or more of the following are true: |
6253 | |
6254 | [EACCES] Search permission is denied for the directory |
6255 | referenced by the file descriptor. |
6256 | |
6257 | [ENOTDIR] The file descriptor does not reference a directory. |
6258 | |
6259 | [EBADF] The argument _\bf_\bd is not a valid file descriptor. |
6260 | |
6261 | [EIO] An I/O error occurred while reading from the file |
6262 | system. |
6263 | |
6264 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
6265 | chroot(2) |
6266 | |
6267 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
6268 | The c\bch\bhd\bdi\bir\br() and f\bfc\bch\bhd\bdi\bir\br() functions are expected to conform to IEEE Std |
6269 | 1003.1-2008 (``POSIX.1''). |
6270 | |
6271 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
6272 | The c\bch\bhd\bdi\bir\br() system call first appeared in Version 1 AT&T UNIX, and |
6273 | f\bfc\bch\bhd\bdi\bir\br() in 4.3BSD-Reno. |
6274 | |
6275 | N\bNA\bAM\bME\bE |
6276 | c\bch\bhf\bfl\bla\bag\bgs\bs, c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt, f\bfc\bch\bhf\bfl\bla\bag\bgs\bs - set file flags |
6277 | |
6278 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6279 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
6280 | |
6281 | _\bi_\bn_\bt |
6282 | c\bch\bhf\bfl\bla\bag\bgs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
6283 | |
6284 | _\bi_\bn_\bt |
6285 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs(_\bi_\bn_\bt _\bf_\bd, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
6286 | |
6287 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
6288 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
6289 | |
6290 | _\bi_\bn_\bt |
6291 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\ba_\bt_\bf_\bl_\ba_\bg_\bs); |
6292 | |
6293 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6294 | The file whose name is given by _\bp_\ba_\bt_\bh or referenced by the descriptor _\bf_\bd |
6295 | has its flags changed to _\bf_\bl_\ba_\bg_\bs. |
6296 | |
6297 | The flags are the bitwise OR of zero or more of the following values: |
6298 | |
6299 | UF_NODUMP Do not dump the file. |
6300 | UF_IMMUTABLE The file may not be changed. |
6301 | UF_APPEND The file may only be appended to. |
6302 | SF_ARCHIVED The file may be archived. |
6303 | SF_IMMUTABLE The file may not be changed. |
6304 | SF_APPEND The file may only be appended to. |
6305 | |
6306 | The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the |
6307 | owner of a file or the superuser. |
6308 | |
6309 | The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or |
6310 | unset by the superuser. They may be set at any time, but normally may |
6311 | only be unset when the system is in single-user mode. (See init(8) for |
6312 | details.) |
6313 | |
6314 | The c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except in the case |
6315 | where _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be |
6316 | changed is determined relative to the directory associated with the file |
6317 | descriptor _\bf_\bd instead of the current working directory. |
6318 | |
6319 | If c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
6320 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
6321 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to c\bch\bhf\bfl\bla\bag\bgs\bs(). |
6322 | |
6323 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
6324 | values: |
6325 | |
6326 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the flags |
6327 | of the symbolic link are changed. |
6328 | |
6329 | The f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except that the file |
6330 | whose flags are changed is specified by the file descriptor _\bf_\bd. |
6331 | |
6332 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6333 | Upon successful completion, the value 0 is returned; otherwise the |
6334 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6335 | error. |
6336 | |
6337 | E\bER\bRR\bRO\bOR\bRS\bS |
6338 | c\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
6339 | |
6340 | [ENOTDIR] A component of the path prefix is not a directory. |
6341 | |
6342 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
6343 | characters, or an entire pathname (including the |
6344 | terminating NUL) exceeded PATH_MAX bytes. |
6345 | |
6346 | [ENOENT] The named file does not exist. |
6347 | |
6348 | [EACCES] Search permission is denied for a component of the |
6349 | path prefix. |
6350 | |
6351 | [ELOOP] Too many symbolic links were encountered in |
6352 | translating the pathname. |
6353 | |
6354 | [EPERM] The effective user ID does not match the owner of the |
6355 | file and the effective user ID is not the superuser, |
6356 | or the effective user ID is not the superuser and at |
6357 | least one of the super-user-only flags for the named |
6358 | file would be changed. |
6359 | |
6360 | [EOPNOTSUPP] The named file resides on a file system that does not |
6361 | support file flags. |
6362 | |
6363 | [EROFS] The named file resides on a read-only file system. |
6364 | |
6365 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
6366 | space. |
6367 | |
6368 | [EIO] An I/O error occurred while reading from or writing to |
6369 | the file system. |
6370 | |
6371 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
6372 | |
6373 | [EINVAL] The descriptor references a block or character device |
6374 | and the effective user ID is not the superuser. |
6375 | |
6376 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
6377 | |
6378 | [EBADF] The descriptor is not valid. |
6379 | |
6380 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
6381 | |
6382 | [EINVAL] The descriptor references a block or character device |
6383 | and the effective user ID is not the superuser. |
6384 | |
6385 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
6386 | |
6387 | [EPERM] The effective user ID does not match the owner of the |
6388 | file and the effective user ID is not the superuser, |
6389 | or the effective user ID is not the superuser and at |
6390 | least one of the super-user-only flags for the named |
6391 | file would be changed. |
6392 | |
6393 | [EOPNOTSUPP] The named file resides on a file system that does not |
6394 | support file flags. |
6395 | |
6396 | [EROFS] The file resides on a read-only file system. |
6397 | |
6398 | [EIO] An I/O error occurred while reading from or writing to |
6399 | the file system. |
6400 | |
6401 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
6402 | chflags(1), init(8) |
6403 | |
6404 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
6405 | The c\bch\bhf\bfl\bla\bag\bgs\bs() and f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() functions first appeared in 4.4BSD. The |
6406 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function first appeared in FreeBSD 10.0. It was added to |
6407 | OpenBSD in OpenBSD 5.7. |
6408 | |
6409 | N\bNA\bAM\bME\bE |
6410 | c\bch\bhf\bfl\bla\bag\bgs\bs, c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt, f\bfc\bch\bhf\bfl\bla\bag\bgs\bs - set file flags |
6411 | |
6412 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6413 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
6414 | |
6415 | _\bi_\bn_\bt |
6416 | c\bch\bhf\bfl\bla\bag\bgs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
6417 | |
6418 | _\bi_\bn_\bt |
6419 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs(_\bi_\bn_\bt _\bf_\bd, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
6420 | |
6421 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
6422 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
6423 | |
6424 | _\bi_\bn_\bt |
6425 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\ba_\bt_\bf_\bl_\ba_\bg_\bs); |
6426 | |
6427 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6428 | The file whose name is given by _\bp_\ba_\bt_\bh or referenced by the descriptor _\bf_\bd |
6429 | has its flags changed to _\bf_\bl_\ba_\bg_\bs. |
6430 | |
6431 | The flags are the bitwise OR of zero or more of the following values: |
6432 | |
6433 | UF_NODUMP Do not dump the file. |
6434 | UF_IMMUTABLE The file may not be changed. |
6435 | UF_APPEND The file may only be appended to. |
6436 | SF_ARCHIVED The file may be archived. |
6437 | SF_IMMUTABLE The file may not be changed. |
6438 | SF_APPEND The file may only be appended to. |
6439 | |
6440 | The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the |
6441 | owner of a file or the superuser. |
6442 | |
6443 | The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or |
6444 | unset by the superuser. They may be set at any time, but normally may |
6445 | only be unset when the system is in single-user mode. (See init(8) for |
6446 | details.) |
6447 | |
6448 | The c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except in the case |
6449 | where _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be |
6450 | changed is determined relative to the directory associated with the file |
6451 | descriptor _\bf_\bd instead of the current working directory. |
6452 | |
6453 | If c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
6454 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
6455 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to c\bch\bhf\bfl\bla\bag\bgs\bs(). |
6456 | |
6457 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
6458 | values: |
6459 | |
6460 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the flags |
6461 | of the symbolic link are changed. |
6462 | |
6463 | The f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except that the file |
6464 | whose flags are changed is specified by the file descriptor _\bf_\bd. |
6465 | |
6466 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6467 | Upon successful completion, the value 0 is returned; otherwise the |
6468 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6469 | error. |
6470 | |
6471 | E\bER\bRR\bRO\bOR\bRS\bS |
6472 | c\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
6473 | |
6474 | [ENOTDIR] A component of the path prefix is not a directory. |
6475 | |
6476 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
6477 | characters, or an entire pathname (including the |
6478 | terminating NUL) exceeded PATH_MAX bytes. |
6479 | |
6480 | [ENOENT] The named file does not exist. |
6481 | |
6482 | [EACCES] Search permission is denied for a component of the |
6483 | path prefix. |
6484 | |
6485 | [ELOOP] Too many symbolic links were encountered in |
6486 | translating the pathname. |
6487 | |
6488 | [EPERM] The effective user ID does not match the owner of the |
6489 | file and the effective user ID is not the superuser, |
6490 | or the effective user ID is not the superuser and at |
6491 | least one of the super-user-only flags for the named |
6492 | file would be changed. |
6493 | |
6494 | [EOPNOTSUPP] The named file resides on a file system that does not |
6495 | support file flags. |
6496 | |
6497 | [EROFS] The named file resides on a read-only file system. |
6498 | |
6499 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
6500 | space. |
6501 | |
6502 | [EIO] An I/O error occurred while reading from or writing to |
6503 | the file system. |
6504 | |
6505 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
6506 | |
6507 | [EINVAL] The descriptor references a block or character device |
6508 | and the effective user ID is not the superuser. |
6509 | |
6510 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
6511 | |
6512 | [EBADF] The descriptor is not valid. |
6513 | |
6514 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
6515 | |
6516 | [EINVAL] The descriptor references a block or character device |
6517 | and the effective user ID is not the superuser. |
6518 | |
6519 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
6520 | |
6521 | [EPERM] The effective user ID does not match the owner of the |
6522 | file and the effective user ID is not the superuser, |
6523 | or the effective user ID is not the superuser and at |
6524 | least one of the super-user-only flags for the named |
6525 | file would be changed. |
6526 | |
6527 | [EOPNOTSUPP] The named file resides on a file system that does not |
6528 | support file flags. |
6529 | |
6530 | [EROFS] The file resides on a read-only file system. |
6531 | |
6532 | [EIO] An I/O error occurred while reading from or writing to |
6533 | the file system. |
6534 | |
6535 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
6536 | chflags(1), init(8) |
6537 | |
6538 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
6539 | The c\bch\bhf\bfl\bla\bag\bgs\bs() and f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() functions first appeared in 4.4BSD. The |
6540 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function first appeared in FreeBSD 10.0. It was added to |
6541 | OpenBSD in OpenBSD 5.7. |
6542 | |
6543 | N\bNA\bAM\bME\bE |
6544 | c\bch\bhm\bmo\bod\bd, f\bfc\bch\bhm\bmo\bod\bda\bat\bt, f\bfc\bch\bhm\bmo\bod\bd - change mode of file |
6545 | |
6546 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6547 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
6548 | |
6549 | _\bi_\bn_\bt |
6550 | c\bch\bhm\bmo\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
6551 | |
6552 | _\bi_\bn_\bt |
6553 | f\bfc\bch\bhm\bmo\bod\bd(_\bi_\bn_\bt _\bf_\bd, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
6554 | |
6555 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
6556 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
6557 | |
6558 | _\bi_\bn_\bt |
6559 | f\bfc\bch\bhm\bmo\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
6560 | |
6561 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6562 | The c\bch\bhm\bmo\bod\bd() function sets the file permission bits of the file specified |
6563 | by the pathname _\bp_\ba_\bt_\bh to _\bm_\bo_\bd_\be. c\bch\bhm\bmo\bod\bd() verifies that the process owner |
6564 | (user) either owns the specified file or is the superuser. |
6565 | |
6566 | The _\bm_\bo_\bd_\be argument is the bitwise OR of zero or more of the permission bit |
6567 | masks from the following list: |
6568 | |
6569 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
6570 | #define S_IRUSR 0000400 /* R for owner */ |
6571 | #define S_IWUSR 0000200 /* W for owner */ |
6572 | #define S_IXUSR 0000100 /* X for owner */ |
6573 | |
6574 | #define S_IRWXG 0000070 /* RWX mask for group */ |
6575 | #define S_IRGRP 0000040 /* R for group */ |
6576 | #define S_IWGRP 0000020 /* W for group */ |
6577 | #define S_IXGRP 0000010 /* X for group */ |
6578 | |
6579 | #define S_IRWXO 0000007 /* RWX mask for other */ |
6580 | #define S_IROTH 0000004 /* R for other */ |
6581 | #define S_IWOTH 0000002 /* W for other */ |
6582 | #define S_IXOTH 0000001 /* X for other */ |
6583 | |
6584 | #define S_ISUID 0004000 /* set user id on execution */ |
6585 | #define S_ISGID 0002000 /* set group id on execution */ |
6586 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
6587 | |
6588 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a file, it is ignored. |
6589 | |
6590 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a directory, an unprivileged |
6591 | user may not delete or rename files of other users in that directory. |
6592 | The sticky bit may be set by any user on a directory which the user owns |
6593 | or has appropriate permissions. For more details of the properties of |
6594 | the sticky bit, see sticky(8). |
6595 | |
6596 | Writing or changing the owner of a file turns off the set-user-ID and |
6597 | set-group-ID bits unless the user is the superuser. This makes the |
6598 | system somewhat more secure by protecting set-user-ID (set-group-ID) |
6599 | files from remaining set-user-ID (set-group-ID) if they are modified, at |
6600 | the expense of a degree of compatibility. |
6601 | |
6602 | The f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function is equivalent to c\bch\bhm\bmo\bod\bd() except in the case where |
6603 | _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be changed is |
6604 | determined relative to the directory associated with the file descriptor |
6605 | _\bf_\bd instead of the current working directory. |
6606 | |
6607 | If f\bfc\bch\bhm\bmo\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
6608 | in the _\bf_\bd parameter, the current working directory is used. If _\bf_\bl_\ba_\bg is |
6609 | also zero, the behavior is identical to a call to c\bch\bhm\bmo\bod\bd(). |
6610 | |
6611 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
6612 | values: |
6613 | |
6614 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the mode |
6615 | of the symbolic link is changed. |
6616 | |
6617 | The f\bfc\bch\bhm\bmo\bod\bd() function is equivalent to c\bch\bhm\bmo\bod\bd() except that the file whose |
6618 | permissions are changed is specified by the file descriptor _\bf_\bd. |
6619 | |
6620 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6621 | Upon successful completion, the value 0 is returned; otherwise the |
6622 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6623 | error. |
6624 | |
6625 | E\bER\bRR\bRO\bOR\bRS\bS |
6626 | The c\bch\bhm\bmo\bod\bd() and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions will fail and the file mode will be |
6627 | unchanged if: |
6628 | |
6629 | [ENOTDIR] A component of the path prefix is not a directory. |
6630 | |
6631 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
6632 | characters, or an entire pathname (including the |
6633 | terminating NUL) exceeded PATH_MAX bytes. |
6634 | |
6635 | [ENOENT] The named file does not exist. |
6636 | |
6637 | [EACCES] Search permission is denied for a component of the |
6638 | path prefix. |
6639 | |
6640 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
6641 | described above. |
6642 | |
6643 | [ELOOP] Too many symbolic links were encountered in |
6644 | translating the pathname. |
6645 | |
6646 | [EPERM] The effective user ID does not match the owner of the |
6647 | file and the effective user ID is not the superuser. |
6648 | |
6649 | [EROFS] The named file resides on a read-only file system. |
6650 | |
6651 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
6652 | space. |
6653 | |
6654 | [EIO] An I/O error occurred while reading from or writing to |
6655 | the file system. |
6656 | |
6657 | Additionally, the f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function will fail if: |
6658 | |
6659 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
6660 | AT_SYMLINK_NOFOLLOW. |
6661 | |
6662 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
6663 | argument is neither AT_FDCWD nor a valid file |
6664 | descriptor. |
6665 | |
6666 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
6667 | argument is a valid file descriptor but it does not |
6668 | reference a directory. |
6669 | |
6670 | [EOPNOTSUPP] The _\bf_\bl_\ba_\bg argument specifies AT_SYMLINK_NOFOLLOW on a |
6671 | symbolic link and the file system does not support |
6672 | that operation. |
6673 | |
6674 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
6675 | permission is denied for the directory which the _\bf_\bd |
6676 | file descriptor references. |
6677 | |
6678 | f\bfc\bch\bhm\bmo\bod\bd() will fail and the file mode will be unchanged if: |
6679 | |
6680 | [EBADF] The descriptor is not valid. |
6681 | |
6682 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
6683 | |
6684 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
6685 | described above. |
6686 | |
6687 | [EPERM] The effective user ID does not match the owner of the |
6688 | file and the effective user ID is not the superuser. |
6689 | |
6690 | [EROFS] The file resides on a read-only file system. |
6691 | |
6692 | [EIO] An I/O error occurred while reading from or writing to |
6693 | the file system. |
6694 | |
6695 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
6696 | chmod(1), chown(2), open(2), stat(2), sticky(8) |
6697 | |
6698 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
6699 | The c\bch\bhm\bmo\bod\bd(), f\bfc\bch\bhm\bmo\bod\bd(), and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions are expected to conform |
6700 | to IEEE Std 1003.1-2008 (``POSIX.1''). |
6701 | |
6702 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
6703 | The c\bch\bhm\bmo\bod\bd() system call first appeared in Version 1 AT&T UNIX; f\bfc\bch\bhm\bmo\bod\bd() |
6704 | in 4.1cBSD; and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
6705 | |
6706 | N\bNA\bAM\bME\bE |
6707 | c\bch\bho\bow\bwn\bn, l\blc\bch\bho\bow\bwn\bn, f\bfc\bch\bho\bow\bwn\bna\bat\bt, f\bfc\bch\bho\bow\bwn\bn - change owner and group of a file or |
6708 | link |
6709 | |
6710 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6711 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
6712 | |
6713 | _\bi_\bn_\bt |
6714 | c\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
6715 | |
6716 | _\bi_\bn_\bt |
6717 | l\blc\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
6718 | |
6719 | _\bi_\bn_\bt |
6720 | f\bfc\bch\bho\bow\bwn\bn(_\bi_\bn_\bt _\bf_\bd, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
6721 | |
6722 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
6723 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
6724 | |
6725 | _\bi_\bn_\bt |
6726 | f\bfc\bch\bho\bow\bwn\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
6727 | |
6728 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6729 | The owner ID and group ID of the file (or link) named by _\bp_\ba_\bt_\bh or |
6730 | referenced by _\bf_\bd is changed as specified by the arguments _\bo_\bw_\bn_\be_\br and |
6731 | _\bg_\br_\bo_\bu_\bp. The owner of a file may change the _\bg_\br_\bo_\bu_\bp to a group of which he |
6732 | or she is a member, but the change _\bo_\bw_\bn_\be_\br capability is restricted to the |
6733 | superuser. |
6734 | |
6735 | By default, c\bch\bho\bow\bwn\bn() clears the set-user-ID and set-group-ID bits on the |
6736 | file to prevent accidental or mischievous creation of set-user-ID and |
6737 | set-group-ID programs. This behaviour can be overridden by setting the |
6738 | sysctl(8) variable _\bf_\bs_\b._\bp_\bo_\bs_\bi_\bx_\b._\bs_\be_\bt_\bu_\bi_\bd to zero. |
6739 | |
6740 | l\blc\bch\bho\bow\bwn\bn() operates similarly to how c\bch\bho\bow\bwn\bn() operated on older systems, and |
6741 | does not follow symbolic links. It allows the owner and group of a |
6742 | symbolic link to be set. |
6743 | |
6744 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() function is equivalent to either the c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn() |
6745 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
6746 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose ownership is changed is |
6747 | determined relative to the directory associated with file descriptor _\bf_\bd |
6748 | instead of the current working directory. |
6749 | |
6750 | If f\bfc\bch\bho\bow\bwn\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
6751 | in the _\bf_\bd parameter, the current working directory is used and the |
6752 | behavior is identical to a call to c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn(), depending on |
6753 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
6754 | |
6755 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
6756 | values: |
6757 | |
6758 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
6759 | ownership of the symbolic link is changed. |
6760 | |
6761 | f\bfc\bch\bho\bow\bwn\bn() is particularly useful when used in conjunction with the file |
6762 | locking primitives (see flock(2)). |
6763 | |
6764 | One of the owner or group IDs may be left unchanged by specifying it as |
6765 | -1. |
6766 | |
6767 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6768 | Upon successful completion, the value 0 is returned; otherwise the |
6769 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6770 | error. |
6771 | |
6772 | E\bER\bRR\bRO\bOR\bRS\bS |
6773 | c\bch\bho\bow\bwn\bn(), l\blc\bch\bho\bow\bwn\bn(), and f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail and the file or link will be |
6774 | unchanged if: |
6775 | |
6776 | [ENOTDIR] A component of the path prefix is not a directory. |
6777 | |
6778 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
6779 | characters, or an entire pathname (including the |
6780 | terminating NUL) exceeded PATH_MAX bytes. |
6781 | |
6782 | [ENOENT] The named file does not exist. |
6783 | |
6784 | [EACCES] Search permission is denied for a component of the |
6785 | path prefix. |
6786 | |
6787 | [ELOOP] Too many symbolic links were encountered in |
6788 | translating the pathname. |
6789 | |
6790 | [EPERM] The effective user ID is not the superuser. |
6791 | |
6792 | [EROFS] The named file resides on a read-only file system. |
6793 | |
6794 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
6795 | space. |
6796 | |
6797 | [EIO] An I/O error occurred while reading from or writing to |
6798 | the file system. |
6799 | |
6800 | Additionally, f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail if: |
6801 | |
6802 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
6803 | AT_SYMLINK_NOFOLLOW. |
6804 | |
6805 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
6806 | argument is neither AT_FDCWD nor a valid file |
6807 | descriptor. |
6808 | |
6809 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
6810 | argument is a valid file descriptor but it does not |
6811 | reference a directory. |
6812 | |
6813 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
6814 | permission is denied for the directory which the _\bf_\bd |
6815 | file descriptor references. |
6816 | |
6817 | f\bfc\bch\bho\bow\bwn\bn() will fail if: |
6818 | |
6819 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
6820 | |
6821 | [EINVAL] _\bf_\bd refers to a socket, not a file. |
6822 | |
6823 | [EPERM] The effective user ID is not the superuser. |
6824 | |
6825 | [EROFS] The named file resides on a read-only file system. |
6826 | |
6827 | [EIO] An I/O error occurred while reading from or writing to |
6828 | the file system. |
6829 | |
6830 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
6831 | chgrp(1), chmod(2), flock(2), chown(8) |
6832 | |
6833 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
6834 | The c\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), and l\blc\bch\bho\bow\bwn\bn() functions are expected to |
6835 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
6836 | |
6837 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
6838 | The c\bch\bho\bow\bwn\bn() system call first appeared in Version 1 AT&T UNIX. Since |
6839 | Version 6 AT&T UNIX it supports changing the group as well, and in |
6840 | Version 7 AT&T UNIX _\bg_\br_\bo_\bu_\bp was made a separate argument. |
6841 | |
6842 | The f\bfc\bch\bho\bow\bwn\bn() system call first appeared in 4.1cBSD. |
6843 | |
6844 | The c\bch\bho\bow\bwn\bn() and f\bfc\bch\bho\bow\bwn\bn() system calls were changed to follow symbolic |
6845 | links in 4.4BSD; therefore, and for compatibility with AT&T System V |
6846 | Release 4 UNIX, the l\blc\bch\bho\bow\bwn\bn() system call was added to OpenBSD 2.1. |
6847 | |
6848 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() system call has been available since OpenBSD 5.0. |
6849 | |
6850 | N\bNA\bAM\bME\bE |
6851 | c\bch\bhr\bro\boo\bot\bt - change root directory |
6852 | |
6853 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6854 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
6855 | |
6856 | _\bi_\bn_\bt |
6857 | c\bch\bhr\bro\boo\bot\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br_\bn_\ba_\bm_\be); |
6858 | |
6859 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6860 | _\bd_\bi_\br_\bn_\ba_\bm_\be is the address of the pathname of a directory, terminated by an |
6861 | ASCII NUL. c\bch\bhr\bro\boo\bot\bt() causes _\bd_\bi_\br_\bn_\ba_\bm_\be to become the root directory, that |
6862 | is, the starting point for path searches of pathnames beginning with `/'. |
6863 | |
6864 | In order for a directory to become the root directory a process must have |
6865 | execute (search) access for that directory. |
6866 | |
6867 | If the program is not currently running with an altered root directory, |
6868 | it should be noted that c\bch\bhr\bro\boo\bot\bt() has no effect on the process's current |
6869 | directory. |
6870 | |
6871 | If the program is already running with an altered root directory, the |
6872 | process's current directory is changed to the same new root directory. |
6873 | This prevents the current directory from being further up the directory |
6874 | tree than the altered root directory. |
6875 | |
6876 | This call is restricted to the superuser. |
6877 | |
6878 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6879 | Upon successful completion, the value 0 is returned; otherwise the |
6880 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6881 | error. |
6882 | |
6883 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS |
6884 | The following example changes the root directory to _\bn_\be_\bw_\br_\bo_\bo_\bt, sets the |
6885 | current directory to the new root, and drops some setuid privileges. |
6886 | There may be other privileges which need to be dropped as well. |
6887 | |
6888 | #include <err.h> |
6889 | #include <unistd.h> |
6890 | |
6891 | if (chroot(newroot) != 0 || chdir("/") != 0) |
6892 | err(1, "%s", newroot); |
6893 | setresuid(getuid(), getuid(), getuid()); |
6894 | |
6895 | E\bER\bRR\bRO\bOR\bRS\bS |
6896 | c\bch\bhr\bro\boo\bot\bt() will fail and the root directory will be unchanged if: |
6897 | |
6898 | [ENOTDIR] A component of the path name is not a directory. |
6899 | |
6900 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
6901 | characters, or an entire pathname (including the |
6902 | terminating NUL) exceeded PATH_MAX bytes. |
6903 | |
6904 | [ENOENT] The named directory does not exist. |
6905 | |
6906 | [EACCES] Search permission is denied for any component of the |
6907 | path name. |
6908 | |
6909 | [ELOOP] Too many symbolic links were encountered in |
6910 | translating the pathname. |
6911 | |
6912 | [EFAULT] _\bd_\bi_\br_\bn_\ba_\bm_\be points outside the process's allocated address |
6913 | space. |
6914 | |
6915 | [EIO] An I/O error occurred while reading from or writing to |
6916 | the file system. |
6917 | |
6918 | [EPERM] The caller is not the superuser. |
6919 | |
6920 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
6921 | chdir(2) |
6922 | |
6923 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
6924 | The c\bch\bhr\bro\boo\bot\bt() system call first appeared in Version 7 AT&T UNIX. |
6925 | |
6926 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
6927 | There are ways for a root process to escape from the chroot jail. |
6928 | Changes to the directory hierarchy made from outside the chroot jail may |
6929 | allow a restricted process to escape, even if it is unprivileged. |
6930 | Passing directory file descriptors via recvmsg(2) from outside the chroot |
6931 | jail may also allow a process to escape. |
6932 | |
6933 | N\bNA\bAM\bME\bE |
6934 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs - get/set/calibrate date and |
6935 | time |
6936 | |
6937 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
6938 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<t\bti\bim\bme\be.\b.h\bh>\b> |
6939 | |
6940 | _\bi_\bn_\bt |
6941 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
6942 | |
6943 | _\bi_\bn_\bt |
6944 | c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
6945 | |
6946 | _\bi_\bn_\bt |
6947 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
6948 | |
6949 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
6950 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be() and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions allow the calling |
6951 | process to retrieve or set the value used by a clock which is specified |
6952 | by _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd. |
6953 | |
6954 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd can be a value from clock_getcpuclockid(3) or |
6955 | pthread_getcpuclockid(3) or one of five predefined values: |
6956 | |
6957 | CLOCK_REALTIME time that increments as a wall clock should |
6958 | |
6959 | CLOCK_PROCESS_CPUTIME_ID |
6960 | time that increments when the CPU is running in user or |
6961 | kernel mode on behalf of the calling process |
6962 | |
6963 | CLOCK_THREAD_CPUTIME_ID |
6964 | time that increments when the CPU is running in user or |
6965 | kernel mode on behalf of the calling thread |
6966 | |
6967 | CLOCK_MONOTONIC time that increments as a wall clock should but whose |
6968 | absolute value is meaningless and cannot jump, providing |
6969 | accurate realtime interval measurement, even across |
6970 | suspend and resume |
6971 | |
6972 | CLOCK_UPTIME time whose absolute value is the time the system has |
6973 | been running and not suspended, providing accurate |
6974 | uptime measurement, both absolute and interval |
6975 | |
6976 | The structure pointed to by _\bt_\bp is defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
6977 | |
6978 | struct timespec { |
6979 | time_t tv_sec; /* seconds */ |
6980 | long tv_nsec; /* and nanoseconds */ |
6981 | }; |
6982 | |
6983 | Only the CLOCK_REALTIME clock can be set, and only the superuser may do |
6984 | so. If the system securelevel is greater than 1 (see init(8)), the time |
6985 | may only be advanced. This limitation is imposed to prevent a malicious |
6986 | superuser from setting arbitrary time stamps on files. The system time |
6987 | can still be adjusted backwards using the adjtime(2) system call even |
6988 | when the system is secure. |
6989 | |
6990 | The resolution (granularity) of a clock is returned by the c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() |
6991 | call. This value is placed in a (non-null) _\b*_\bt_\bp. |
6992 | |
6993 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
6994 | Upon successful completion, the value 0 is returned; otherwise the |
6995 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
6996 | error. |
6997 | |
6998 | E\bER\bRR\bRO\bOR\bRS\bS |
6999 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() will fail if: |
7000 | |
7001 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd is not a valid value. |
7002 | |
7003 | [EFAULT] The _\bt_\bp argument address referenced invalid memory. |
7004 | |
7005 | In addition, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() may return the following errors: |
7006 | |
7007 | [EPERM] A user other than the superuser attempted to set the |
7008 | time. |
7009 | |
7010 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd specifies a clock that isn't settable, _\bt_\bp |
7011 | specifies a nanosecond value less than zero or greater |
7012 | than 1000 million, or a value outside the range of the |
7013 | specified clock. |
7014 | |
7015 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7016 | date(1), adjtime(2), getitimer(2), gettimeofday(2), |
7017 | clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) |
7018 | |
7019 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
7020 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(), c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions |
7021 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
7022 | |
7023 | The CLOCK_UPTIME clock is an extension to that. |
7024 | |
7025 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
7026 | The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared |
7027 | in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and |
7028 | was added to OpenBSD in OpenBSD 5.5. |
7029 | |
7030 | N\bNA\bAM\bME\bE |
7031 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs - get/set/calibrate date and |
7032 | time |
7033 | |
7034 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7035 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<t\bti\bim\bme\be.\b.h\bh>\b> |
7036 | |
7037 | _\bi_\bn_\bt |
7038 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
7039 | |
7040 | _\bi_\bn_\bt |
7041 | c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
7042 | |
7043 | _\bi_\bn_\bt |
7044 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
7045 | |
7046 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7047 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be() and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions allow the calling |
7048 | process to retrieve or set the value used by a clock which is specified |
7049 | by _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd. |
7050 | |
7051 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd can be a value from clock_getcpuclockid(3) or |
7052 | pthread_getcpuclockid(3) or one of five predefined values: |
7053 | |
7054 | CLOCK_REALTIME time that increments as a wall clock should |
7055 | |
7056 | CLOCK_PROCESS_CPUTIME_ID |
7057 | time that increments when the CPU is running in user or |
7058 | kernel mode on behalf of the calling process |
7059 | |
7060 | CLOCK_THREAD_CPUTIME_ID |
7061 | time that increments when the CPU is running in user or |
7062 | kernel mode on behalf of the calling thread |
7063 | |
7064 | CLOCK_MONOTONIC time that increments as a wall clock should but whose |
7065 | absolute value is meaningless and cannot jump, providing |
7066 | accurate realtime interval measurement, even across |
7067 | suspend and resume |
7068 | |
7069 | CLOCK_UPTIME time whose absolute value is the time the system has |
7070 | been running and not suspended, providing accurate |
7071 | uptime measurement, both absolute and interval |
7072 | |
7073 | The structure pointed to by _\bt_\bp is defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
7074 | |
7075 | struct timespec { |
7076 | time_t tv_sec; /* seconds */ |
7077 | long tv_nsec; /* and nanoseconds */ |
7078 | }; |
7079 | |
7080 | Only the CLOCK_REALTIME clock can be set, and only the superuser may do |
7081 | so. If the system securelevel is greater than 1 (see init(8)), the time |
7082 | may only be advanced. This limitation is imposed to prevent a malicious |
7083 | superuser from setting arbitrary time stamps on files. The system time |
7084 | can still be adjusted backwards using the adjtime(2) system call even |
7085 | when the system is secure. |
7086 | |
7087 | The resolution (granularity) of a clock is returned by the c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() |
7088 | call. This value is placed in a (non-null) _\b*_\bt_\bp. |
7089 | |
7090 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
7091 | Upon successful completion, the value 0 is returned; otherwise the |
7092 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
7093 | error. |
7094 | |
7095 | E\bER\bRR\bRO\bOR\bRS\bS |
7096 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() will fail if: |
7097 | |
7098 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd is not a valid value. |
7099 | |
7100 | [EFAULT] The _\bt_\bp argument address referenced invalid memory. |
7101 | |
7102 | In addition, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() may return the following errors: |
7103 | |
7104 | [EPERM] A user other than the superuser attempted to set the |
7105 | time. |
7106 | |
7107 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd specifies a clock that isn't settable, _\bt_\bp |
7108 | specifies a nanosecond value less than zero or greater |
7109 | than 1000 million, or a value outside the range of the |
7110 | specified clock. |
7111 | |
7112 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7113 | date(1), adjtime(2), getitimer(2), gettimeofday(2), |
7114 | clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) |
7115 | |
7116 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
7117 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(), c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions |
7118 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
7119 | |
7120 | The CLOCK_UPTIME clock is an extension to that. |
7121 | |
7122 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
7123 | The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared |
7124 | in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and |
7125 | was added to OpenBSD in OpenBSD 5.5. |
7126 | |
7127 | N\bNA\bAM\bME\bE |
7128 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be, c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs - get/set/calibrate date and |
7129 | time |
7130 | |
7131 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7132 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<t\bti\bim\bme\be.\b.h\bh>\b> |
7133 | |
7134 | _\bi_\bn_\bt |
7135 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
7136 | |
7137 | _\bi_\bn_\bt |
7138 | c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
7139 | |
7140 | _\bi_\bn_\bt |
7141 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(_\bc_\bl_\bo_\bc_\bk_\bi_\bd_\b__\bt _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bp); |
7142 | |
7143 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7144 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be() and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions allow the calling |
7145 | process to retrieve or set the value used by a clock which is specified |
7146 | by _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd. |
7147 | |
7148 | _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd can be a value from clock_getcpuclockid(3) or |
7149 | pthread_getcpuclockid(3) or one of five predefined values: |
7150 | |
7151 | CLOCK_REALTIME time that increments as a wall clock should |
7152 | |
7153 | CLOCK_PROCESS_CPUTIME_ID |
7154 | time that increments when the CPU is running in user or |
7155 | kernel mode on behalf of the calling process |
7156 | |
7157 | CLOCK_THREAD_CPUTIME_ID |
7158 | time that increments when the CPU is running in user or |
7159 | kernel mode on behalf of the calling thread |
7160 | |
7161 | CLOCK_MONOTONIC time that increments as a wall clock should but whose |
7162 | absolute value is meaningless and cannot jump, providing |
7163 | accurate realtime interval measurement, even across |
7164 | suspend and resume |
7165 | |
7166 | CLOCK_UPTIME time whose absolute value is the time the system has |
7167 | been running and not suspended, providing accurate |
7168 | uptime measurement, both absolute and interval |
7169 | |
7170 | The structure pointed to by _\bt_\bp is defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
7171 | |
7172 | struct timespec { |
7173 | time_t tv_sec; /* seconds */ |
7174 | long tv_nsec; /* and nanoseconds */ |
7175 | }; |
7176 | |
7177 | Only the CLOCK_REALTIME clock can be set, and only the superuser may do |
7178 | so. If the system securelevel is greater than 1 (see init(8)), the time |
7179 | may only be advanced. This limitation is imposed to prevent a malicious |
7180 | superuser from setting arbitrary time stamps on files. The system time |
7181 | can still be adjusted backwards using the adjtime(2) system call even |
7182 | when the system is secure. |
7183 | |
7184 | The resolution (granularity) of a clock is returned by the c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() |
7185 | call. This value is placed in a (non-null) _\b*_\bt_\bp. |
7186 | |
7187 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
7188 | Upon successful completion, the value 0 is returned; otherwise the |
7189 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
7190 | error. |
7191 | |
7192 | E\bER\bRR\bRO\bOR\bRS\bS |
7193 | c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs() will fail if: |
7194 | |
7195 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd is not a valid value. |
7196 | |
7197 | [EFAULT] The _\bt_\bp argument address referenced invalid memory. |
7198 | |
7199 | In addition, c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() may return the following errors: |
7200 | |
7201 | [EPERM] A user other than the superuser attempted to set the |
7202 | time. |
7203 | |
7204 | [EINVAL] _\bc_\bl_\bo_\bc_\bk_\b__\bi_\bd specifies a clock that isn't settable, _\bt_\bp |
7205 | specifies a nanosecond value less than zero or greater |
7206 | than 1000 million, or a value outside the range of the |
7207 | specified clock. |
7208 | |
7209 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7210 | date(1), adjtime(2), getitimer(2), gettimeofday(2), |
7211 | clock_getcpuclockid(3), ctime(3), pthread_getcpuclockid(3) |
7212 | |
7213 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
7214 | The c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btr\bre\bes\bs(), c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), and c\bcl\blo\boc\bck\bk_\b_s\bse\bet\btt\bti\bim\bme\be() functions |
7215 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
7216 | |
7217 | The CLOCK_UPTIME clock is an extension to that. |
7218 | |
7219 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
7220 | The CLOCK_PROCESS_CPUTIME_ID and CLOCK_THREAD_CPUTIME_ID clocks appeared |
7221 | in OpenBSD 5.4. The CLOCK_UPTIME clock first appeared in FreeBSD 7.0 and |
7222 | was added to OpenBSD in OpenBSD 5.5. |
7223 | |
7224 | N\bNA\bAM\bME\bE |
7225 | c\bcl\blo\bos\bse\be - delete a descriptor |
7226 | |
7227 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7228 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
7229 | |
7230 | _\bi_\bn_\bt |
7231 | c\bcl\blo\bos\bse\be(_\bi_\bn_\bt _\bd); |
7232 | |
7233 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7234 | The c\bcl\blo\bos\bse\be() call deletes a descriptor _\bd from the per-process object |
7235 | reference table. If this is the last reference to the underlying object, |
7236 | the object will be deactivated. For example, on the last close of a |
7237 | file, the current _\bs_\be_\be_\bk pointer associated with the file is lost; on the |
7238 | last close of a socket(2), associated naming information and queued data |
7239 | are discarded; and on the last close of a file holding an advisory lock, |
7240 | the lock is released (see flock(2)). However, the semantics of System V |
7241 | and IEEE Std 1003.1-1988 (``POSIX.1'') dictate that all fcntl(2) advisory |
7242 | record locks associated with a file for a given process are removed when |
7243 | _\ba_\bn_\by file descriptor for that file is closed by that process. |
7244 | |
7245 | When a process exits, all associated file descriptors are freed, but |
7246 | since there is a limit on active descriptors per process, the c\bcl\blo\bos\bse\be() |
7247 | function call is useful when a large quantity of file descriptors are |
7248 | being handled. |
7249 | |
7250 | When a process forks (see fork(2)), all descriptors for the new child |
7251 | process reference the same objects as they did in the parent before the |
7252 | fork. If a new process image is to then be run using execve(2), the |
7253 | process would normally inherit these descriptors. Most of the |
7254 | descriptors can be rearranged with dup2(2) or deleted with c\bcl\blo\bos\bse\be() before |
7255 | the execve(2) is attempted, but since some of these descriptors may still |
7256 | be needed should the execve(2) fail, it is necessary to arrange for them |
7257 | to be closed when the execve(2) succeeds. For this reason, the call |
7258 | f\bfc\bcn\bnt\btl\bl(_\bd, _\bF_\b__\bS_\bE_\bT_\bF_\bD, _\bF_\bD_\b__\bC_\bL_\bO_\bE_\bX_\bE_\bC) is provided, which arranges that a |
7259 | descriptor will be closed after a successful execve(2); the call f\bfc\bcn\bnt\btl\bl(_\bd, |
7260 | _\bF_\b__\bS_\bE_\bT_\bF_\bD, _\b0) restores the default, which is to not close the descriptor. |
7261 | |
7262 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
7263 | Upon successful completion, the value 0 is returned; otherwise the |
7264 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
7265 | error. |
7266 | |
7267 | E\bER\bRR\bRO\bOR\bRS\bS |
7268 | c\bcl\blo\bos\bse\be() will fail if: |
7269 | |
7270 | [EBADF] _\bd is not an active descriptor. |
7271 | |
7272 | [EINTR] An interrupt was received. |
7273 | |
7274 | [EIO] An I/O error occurred while writing to the file |
7275 | system. |
7276 | |
7277 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7278 | accept(2), closefrom(2), dup2(2), execve(2), fcntl(2), flock(2), open(2), |
7279 | pipe(2), socket(2), socketpair(2) |
7280 | |
7281 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
7282 | c\bcl\blo\bos\bse\be() conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
7283 | |
7284 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
7285 | The c\bcl\blo\bos\bse\be() system call first appeared in Version 1 AT&T UNIX. |
7286 | |
7287 | N\bNA\bAM\bME\bE |
7288 | c\bcl\blo\bos\bse\bef\bfr\bro\bom\bm - delete many descriptors |
7289 | |
7290 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7291 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
7292 | |
7293 | _\bi_\bn_\bt |
7294 | c\bcl\blo\bos\bse\bef\bfr\bro\bom\bm(_\bi_\bn_\bt _\bf_\bd); |
7295 | |
7296 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7297 | The c\bcl\blo\bos\bse\bef\bfr\bro\bom\bm() call deletes all descriptors numbered _\bf_\bd and higher from |
7298 | the per-process file descriptor table. It is effectively the same as |
7299 | calling close(2) on each descriptor. |
7300 | |
7301 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
7302 | Upon successful completion, the value 0 is returned; otherwise the |
7303 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
7304 | error. |
7305 | |
7306 | E\bER\bRR\bRO\bOR\bRS\bS |
7307 | c\bcl\blo\bos\bse\bef\bfr\bro\bom\bm() will fail if: |
7308 | |
7309 | [EBADF] _\bf_\bd is greater than all open file descriptors. |
7310 | |
7311 | [EINTR] An interrupt was received. |
7312 | |
7313 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7314 | close(2) |
7315 | |
7316 | N\bNA\bAM\bME\bE |
7317 | c\bco\bon\bnn\bne\bec\bct\bt - initiate a connection on a socket |
7318 | |
7319 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7320 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
7321 | |
7322 | _\bi_\bn_\bt |
7323 | c\bco\bon\bnn\bne\bec\bct\bt(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
7324 | |
7325 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7326 | The parameter _\bs is a socket. If it is of type SOCK_DGRAM, this call |
7327 | specifies the peer with which the socket is to be associated; this |
7328 | address is that to which datagrams are to be sent, and the only address |
7329 | from which datagrams are to be received. If the socket is of type |
7330 | SOCK_STREAM, this call attempts to make a connection to another socket. |
7331 | The other socket is specified by _\bn_\ba_\bm_\be, which is an address in the |
7332 | communications space of the socket. _\bn_\ba_\bm_\be_\bl_\be_\bn indicates the amount of |
7333 | space pointed to by _\bn_\ba_\bm_\be, in bytes. Each communications space interprets |
7334 | the _\bn_\ba_\bm_\be parameter in its own way. Generally, stream sockets may use |
7335 | c\bco\bon\bnn\bne\bec\bct\bt() only once; datagram sockets may use c\bco\bon\bnn\bne\bec\bct\bt() multiple times to |
7336 | change their association. Datagram sockets may dissolve the association |
7337 | by connecting to an invalid address, such as a null address. |
7338 | |
7339 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
7340 | If the connection or binding succeeds, 0 is returned. Otherwise a -1 is |
7341 | returned, and a more specific error code is stored in _\be_\br_\br_\bn_\bo. |
7342 | |
7343 | E\bER\bRR\bRO\bOR\bRS\bS |
7344 | The c\bco\bon\bnn\bne\bec\bct\bt() call fails if: |
7345 | |
7346 | [EBADF] _\bs is not a valid descriptor. |
7347 | |
7348 | [ENOTSOCK] _\bs is not a socket. |
7349 | |
7350 | [EADDRNOTAVAIL] The specified address is not available on this |
7351 | machine. |
7352 | |
7353 | [EAFNOSUPPORT] Addresses in the specified address family cannot be |
7354 | used with this socket. |
7355 | |
7356 | [EISCONN] The socket is already connected. |
7357 | |
7358 | [ETIMEDOUT] Connection establishment timed out without |
7359 | establishing a connection. |
7360 | |
7361 | [EINVAL] A TCP connection with a local broadcast, the all-ones |
7362 | or a multicast address as the peer was attempted. |
7363 | |
7364 | [ECONNREFUSED] The attempt to connect was forcefully rejected. |
7365 | |
7366 | [EHOSTUNREACH] The destination address specified an unreachable host. |
7367 | |
7368 | [EINTR] A connect was interrupted before it succeeded by the |
7369 | delivery of a signal. |
7370 | |
7371 | [ENETUNREACH] The network isn't reachable from this host. |
7372 | |
7373 | [EADDRINUSE] The address is already in use. |
7374 | |
7375 | [EFAULT] The _\bn_\ba_\bm_\be parameter specifies an area outside the |
7376 | process address space. |
7377 | |
7378 | [EINPROGRESS] The socket is non-blocking and the connection cannot |
7379 | be completed immediately. It is possible to select(2) |
7380 | or poll(2) for completion by selecting the socket for |
7381 | writing, and also use getsockopt(2) with SO_ERROR to |
7382 | check for error conditions. |
7383 | |
7384 | [EALREADY] The socket is non-blocking and a previous connection |
7385 | attempt has not yet been completed. |
7386 | |
7387 | The following errors are specific to connecting names in the UNIX-domain. |
7388 | These errors may not apply in future versions of the UNIX IPC domain. |
7389 | |
7390 | [ENOTDIR] A component of the path prefix is not a directory. |
7391 | |
7392 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
7393 | characters, or an entire pathname (including the |
7394 | terminating NUL) exceeded PATH_MAX bytes. |
7395 | |
7396 | [ENOENT] The named socket does not exist. |
7397 | |
7398 | [EACCES] Search permission is denied for a component of the |
7399 | path prefix. |
7400 | |
7401 | [EACCES] Write access to the named socket is denied. |
7402 | |
7403 | [ELOOP] Too many symbolic links were encountered in |
7404 | translating the pathname. |
7405 | |
7406 | [EPROTOTYPE] The file described by _\bn_\ba_\bm_\be is of a different type than |
7407 | _\bs. E.g., _\bs may be of type SOCK_STREAM whereas _\bn_\ba_\bm_\be |
7408 | may refer to a socket of type SOCK_DGRAM. |
7409 | |
7410 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7411 | accept(2), getsockname(2), getsockopt(2), poll(2), select(2), socket(2) |
7412 | |
7413 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
7414 | The c\bco\bon\bnn\bne\bec\bct\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
7415 | |
7416 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
7417 | The c\bco\bon\bnn\bne\bec\bct\bt() system call first appeared in 4.1cBSD. |
7418 | |
7419 | N\bNA\bAM\bME\bE |
7420 | d\bdu\bup\bp, d\bdu\bup\bp2\b2, d\bdu\bup\bp3\b3 - duplicate an existing file descriptor |
7421 | |
7422 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7423 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
7424 | |
7425 | _\bi_\bn_\bt |
7426 | d\bdu\bup\bp(_\bi_\bn_\bt _\bo_\bl_\bd_\bd); |
7427 | |
7428 | _\bi_\bn_\bt |
7429 | d\bdu\bup\bp2\b2(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd); |
7430 | |
7431 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
7432 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
7433 | |
7434 | _\bi_\bn_\bt |
7435 | d\bdu\bup\bp3\b3(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
7436 | |
7437 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7438 | d\bdu\bup\bp() duplicates an existing object descriptor and returns its value to |
7439 | the calling process (_\bn_\be_\bw_\bd = d\bdu\bup\bp(_\bo_\bl_\bd_\bd)). The argument _\bo_\bl_\bd_\bd is a small |
7440 | non-negative integer index in the per-process descriptor table. The |
7441 | value must be less than the size of the table, which is returned by |
7442 | getdtablesize(3). The new descriptor returned by the call is the lowest |
7443 | numbered descriptor currently not in use by the process. |
7444 | |
7445 | The object referenced by the descriptor does not distinguish between _\bo_\bl_\bd_\bd |
7446 | and _\bn_\be_\bw_\bd in any way. Thus if _\bn_\be_\bw_\bd and _\bo_\bl_\bd_\bd are duplicate references to |
7447 | an open file, read(2), write(2) and lseek(2) calls all move a single |
7448 | pointer into the file, and append mode, non-blocking I/O and asynchronous |
7449 | I/O options are shared between the references. If a separate pointer |
7450 | into the file is desired, a different object reference to the file must |
7451 | be obtained by issuing an additional open(2) call. The close-on-exec |
7452 | flag on the new file descriptor is unset. |
7453 | |
7454 | In d\bdu\bup\bp2\b2(), the value of the new descriptor _\bn_\be_\bw_\bd is specified. If this |
7455 | descriptor is already in use, it is first deallocated as if a close(2) |
7456 | call had been done first. When _\bn_\be_\bw_\bd equals _\bo_\bl_\bd_\bd, d\bdu\bup\bp2\b2() just returns |
7457 | without affecting the close-on-exec flag. |
7458 | |
7459 | In d\bdu\bup\bp3\b3(), both the value of the new descriptor and the close-on-exec |
7460 | flag on the new file descriptor are specified: _\bn_\be_\bw_\bd specifies the value |
7461 | and the O_CLOEXEC bit in _\bf_\bl_\ba_\bg_\bs specifies the close-on-exec flag. Unlike |
7462 | d\bdu\bup\bp2\b2(), if _\bo_\bl_\bd_\bd and _\bn_\be_\bw_\bd are equal then d\bdu\bup\bp3\b3() fails. Otherwise, if |
7463 | _\bf_\bl_\ba_\bg_\bs is zero then d\bdu\bup\bp3\b3() is identical to a call to d\bdu\bup\bp2\b2(). |
7464 | |
7465 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
7466 | Upon successful completion, the value of the new descriptor is returned. |
7467 | The value -1 is returned if an error occurs in either call. The external |
7468 | variable _\be_\br_\br_\bn_\bo indicates the cause of the error. |
7469 | |
7470 | E\bER\bRR\bRO\bOR\bRS\bS |
7471 | d\bdu\bup\bp() will fail if: |
7472 | |
7473 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor. |
7474 | |
7475 | [EMFILE] Too many descriptors are active. |
7476 | |
7477 | d\bdu\bup\bp2\b2() and d\bdu\bup\bp3\b3() will fail if: |
7478 | |
7479 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor or _\bn_\be_\bw_\bd is |
7480 | negative or greater than or equal to the process's |
7481 | RLIMIT_NOFILE limit. |
7482 | |
7483 | [EINTR] An interrupt was received. |
7484 | |
7485 | [EIO] An I/O error occurred while writing to the file |
7486 | system. |
7487 | |
7488 | In addition, d\bdu\bup\bp3\b3() will return the following error: |
7489 | |
7490 | [EINVAL] _\bo_\bl_\bd_\bd is equal to _\bn_\be_\bw_\bd or _\bf_\bl_\ba_\bg_\bs is invalid. |
7491 | |
7492 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7493 | accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), |
7494 | socketpair(2), getdtablesize(3) |
7495 | |
7496 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
7497 | d\bdu\bup\bp() and d\bdu\bup\bp2\b2() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
7498 | d\bdu\bup\bp3\b3() function is expected to conform to a future revision of that |
7499 | standard. |
7500 | |
7501 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
7502 | The d\bdu\bup\bp() system call first appeared in Version 3 AT&T UNIX, d\bdu\bup\bp2\b2() in |
7503 | Version 7 AT&T UNIX, and d\bdu\bup\bp3\b3() in OpenBSD 5.7. |
7504 | |
7505 | N\bNA\bAM\bME\bE |
7506 | d\bdu\bup\bp, d\bdu\bup\bp2\b2, d\bdu\bup\bp3\b3 - duplicate an existing file descriptor |
7507 | |
7508 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7509 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
7510 | |
7511 | _\bi_\bn_\bt |
7512 | d\bdu\bup\bp(_\bi_\bn_\bt _\bo_\bl_\bd_\bd); |
7513 | |
7514 | _\bi_\bn_\bt |
7515 | d\bdu\bup\bp2\b2(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd); |
7516 | |
7517 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
7518 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
7519 | |
7520 | _\bi_\bn_\bt |
7521 | d\bdu\bup\bp3\b3(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
7522 | |
7523 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7524 | d\bdu\bup\bp() duplicates an existing object descriptor and returns its value to |
7525 | the calling process (_\bn_\be_\bw_\bd = d\bdu\bup\bp(_\bo_\bl_\bd_\bd)). The argument _\bo_\bl_\bd_\bd is a small |
7526 | non-negative integer index in the per-process descriptor table. The |
7527 | value must be less than the size of the table, which is returned by |
7528 | getdtablesize(3). The new descriptor returned by the call is the lowest |
7529 | numbered descriptor currently not in use by the process. |
7530 | |
7531 | The object referenced by the descriptor does not distinguish between _\bo_\bl_\bd_\bd |
7532 | and _\bn_\be_\bw_\bd in any way. Thus if _\bn_\be_\bw_\bd and _\bo_\bl_\bd_\bd are duplicate references to |
7533 | an open file, read(2), write(2) and lseek(2) calls all move a single |
7534 | pointer into the file, and append mode, non-blocking I/O and asynchronous |
7535 | I/O options are shared between the references. If a separate pointer |
7536 | into the file is desired, a different object reference to the file must |
7537 | be obtained by issuing an additional open(2) call. The close-on-exec |
7538 | flag on the new file descriptor is unset. |
7539 | |
7540 | In d\bdu\bup\bp2\b2(), the value of the new descriptor _\bn_\be_\bw_\bd is specified. If this |
7541 | descriptor is already in use, it is first deallocated as if a close(2) |
7542 | call had been done first. When _\bn_\be_\bw_\bd equals _\bo_\bl_\bd_\bd, d\bdu\bup\bp2\b2() just returns |
7543 | without affecting the close-on-exec flag. |
7544 | |
7545 | In d\bdu\bup\bp3\b3(), both the value of the new descriptor and the close-on-exec |
7546 | flag on the new file descriptor are specified: _\bn_\be_\bw_\bd specifies the value |
7547 | and the O_CLOEXEC bit in _\bf_\bl_\ba_\bg_\bs specifies the close-on-exec flag. Unlike |
7548 | d\bdu\bup\bp2\b2(), if _\bo_\bl_\bd_\bd and _\bn_\be_\bw_\bd are equal then d\bdu\bup\bp3\b3() fails. Otherwise, if |
7549 | _\bf_\bl_\ba_\bg_\bs is zero then d\bdu\bup\bp3\b3() is identical to a call to d\bdu\bup\bp2\b2(). |
7550 | |
7551 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
7552 | Upon successful completion, the value of the new descriptor is returned. |
7553 | The value -1 is returned if an error occurs in either call. The external |
7554 | variable _\be_\br_\br_\bn_\bo indicates the cause of the error. |
7555 | |
7556 | E\bER\bRR\bRO\bOR\bRS\bS |
7557 | d\bdu\bup\bp() will fail if: |
7558 | |
7559 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor. |
7560 | |
7561 | [EMFILE] Too many descriptors are active. |
7562 | |
7563 | d\bdu\bup\bp2\b2() and d\bdu\bup\bp3\b3() will fail if: |
7564 | |
7565 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor or _\bn_\be_\bw_\bd is |
7566 | negative or greater than or equal to the process's |
7567 | RLIMIT_NOFILE limit. |
7568 | |
7569 | [EINTR] An interrupt was received. |
7570 | |
7571 | [EIO] An I/O error occurred while writing to the file |
7572 | system. |
7573 | |
7574 | In addition, d\bdu\bup\bp3\b3() will return the following error: |
7575 | |
7576 | [EINVAL] _\bo_\bl_\bd_\bd is equal to _\bn_\be_\bw_\bd or _\bf_\bl_\ba_\bg_\bs is invalid. |
7577 | |
7578 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7579 | accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), |
7580 | socketpair(2), getdtablesize(3) |
7581 | |
7582 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
7583 | d\bdu\bup\bp() and d\bdu\bup\bp2\b2() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
7584 | d\bdu\bup\bp3\b3() function is expected to conform to a future revision of that |
7585 | standard. |
7586 | |
7587 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
7588 | The d\bdu\bup\bp() system call first appeared in Version 3 AT&T UNIX, d\bdu\bup\bp2\b2() in |
7589 | Version 7 AT&T UNIX, and d\bdu\bup\bp3\b3() in OpenBSD 5.7. |
7590 | |
7591 | N\bNA\bAM\bME\bE |
7592 | d\bdu\bup\bp, d\bdu\bup\bp2\b2, d\bdu\bup\bp3\b3 - duplicate an existing file descriptor |
7593 | |
7594 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7595 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
7596 | |
7597 | _\bi_\bn_\bt |
7598 | d\bdu\bup\bp(_\bi_\bn_\bt _\bo_\bl_\bd_\bd); |
7599 | |
7600 | _\bi_\bn_\bt |
7601 | d\bdu\bup\bp2\b2(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd); |
7602 | |
7603 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
7604 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
7605 | |
7606 | _\bi_\bn_\bt |
7607 | d\bdu\bup\bp3\b3(_\bi_\bn_\bt _\bo_\bl_\bd_\bd, _\bi_\bn_\bt _\bn_\be_\bw_\bd, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
7608 | |
7609 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7610 | d\bdu\bup\bp() duplicates an existing object descriptor and returns its value to |
7611 | the calling process (_\bn_\be_\bw_\bd = d\bdu\bup\bp(_\bo_\bl_\bd_\bd)). The argument _\bo_\bl_\bd_\bd is a small |
7612 | non-negative integer index in the per-process descriptor table. The |
7613 | value must be less than the size of the table, which is returned by |
7614 | getdtablesize(3). The new descriptor returned by the call is the lowest |
7615 | numbered descriptor currently not in use by the process. |
7616 | |
7617 | The object referenced by the descriptor does not distinguish between _\bo_\bl_\bd_\bd |
7618 | and _\bn_\be_\bw_\bd in any way. Thus if _\bn_\be_\bw_\bd and _\bo_\bl_\bd_\bd are duplicate references to |
7619 | an open file, read(2), write(2) and lseek(2) calls all move a single |
7620 | pointer into the file, and append mode, non-blocking I/O and asynchronous |
7621 | I/O options are shared between the references. If a separate pointer |
7622 | into the file is desired, a different object reference to the file must |
7623 | be obtained by issuing an additional open(2) call. The close-on-exec |
7624 | flag on the new file descriptor is unset. |
7625 | |
7626 | In d\bdu\bup\bp2\b2(), the value of the new descriptor _\bn_\be_\bw_\bd is specified. If this |
7627 | descriptor is already in use, it is first deallocated as if a close(2) |
7628 | call had been done first. When _\bn_\be_\bw_\bd equals _\bo_\bl_\bd_\bd, d\bdu\bup\bp2\b2() just returns |
7629 | without affecting the close-on-exec flag. |
7630 | |
7631 | In d\bdu\bup\bp3\b3(), both the value of the new descriptor and the close-on-exec |
7632 | flag on the new file descriptor are specified: _\bn_\be_\bw_\bd specifies the value |
7633 | and the O_CLOEXEC bit in _\bf_\bl_\ba_\bg_\bs specifies the close-on-exec flag. Unlike |
7634 | d\bdu\bup\bp2\b2(), if _\bo_\bl_\bd_\bd and _\bn_\be_\bw_\bd are equal then d\bdu\bup\bp3\b3() fails. Otherwise, if |
7635 | _\bf_\bl_\ba_\bg_\bs is zero then d\bdu\bup\bp3\b3() is identical to a call to d\bdu\bup\bp2\b2(). |
7636 | |
7637 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
7638 | Upon successful completion, the value of the new descriptor is returned. |
7639 | The value -1 is returned if an error occurs in either call. The external |
7640 | variable _\be_\br_\br_\bn_\bo indicates the cause of the error. |
7641 | |
7642 | E\bER\bRR\bRO\bOR\bRS\bS |
7643 | d\bdu\bup\bp() will fail if: |
7644 | |
7645 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor. |
7646 | |
7647 | [EMFILE] Too many descriptors are active. |
7648 | |
7649 | d\bdu\bup\bp2\b2() and d\bdu\bup\bp3\b3() will fail if: |
7650 | |
7651 | [EBADF] _\bo_\bl_\bd_\bd is not a valid active descriptor or _\bn_\be_\bw_\bd is |
7652 | negative or greater than or equal to the process's |
7653 | RLIMIT_NOFILE limit. |
7654 | |
7655 | [EINTR] An interrupt was received. |
7656 | |
7657 | [EIO] An I/O error occurred while writing to the file |
7658 | system. |
7659 | |
7660 | In addition, d\bdu\bup\bp3\b3() will return the following error: |
7661 | |
7662 | [EINVAL] _\bo_\bl_\bd_\bd is equal to _\bn_\be_\bw_\bd or _\bf_\bl_\ba_\bg_\bs is invalid. |
7663 | |
7664 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
7665 | accept(2), close(2), fcntl(2), getrlimit(2), open(2), pipe(2), socket(2), |
7666 | socketpair(2), getdtablesize(3) |
7667 | |
7668 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
7669 | d\bdu\bup\bp() and d\bdu\bup\bp2\b2() conform to IEEE Std 1003.1-2008 (``POSIX.1''). The |
7670 | d\bdu\bup\bp3\b3() function is expected to conform to a future revision of that |
7671 | standard. |
7672 | |
7673 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
7674 | The d\bdu\bup\bp() system call first appeared in Version 3 AT&T UNIX, d\bdu\bup\bp2\b2() in |
7675 | Version 7 AT&T UNIX, and d\bdu\bup\bp3\b3() in OpenBSD 5.7. |
7676 | |
7677 | N\bNA\bAM\bME\bE |
7678 | i\bin\bnt\btr\bro\bo - introduction to system calls and error numbers |
7679 | |
7680 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
7681 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<e\ber\brr\brn\bno\bo.\b.h\bh>\b> |
7682 | |
7683 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
7684 | The manual pages in section 2 provide an overview of the system calls, |
7685 | their error returns, and other common definitions and concepts. |
7686 | |
7687 | D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS |
7688 | Nearly all of the system calls provide an error number via the identifier |
7689 | errno, which expands to an addressable location of type _\bi_\bn_\bt. The address |
7690 | of _\be_\br_\br_\bn_\bo in each thread is guaranteed to be unique for the lifetime of |
7691 | the thread. Applications must use _\be_\br_\br_\bn_\bo as defined in <_\be_\br_\br_\bn_\bo_\b._\bh> and not |
7692 | attempt to use a custom definition. |
7693 | |
7694 | When a system call detects an error, it returns an integer value |
7695 | indicating failure (usually -1) and sets the variable _\be_\br_\br_\bn_\bo accordingly. |
7696 | (This allows interpretation of the failure on receiving a -1 and to take |
7697 | action accordingly.) Successful calls never set _\be_\br_\br_\bn_\bo; once set, it |
7698 | remains until another error occurs. It should only be examined after an |
7699 | error. Note that a number of system calls overload the meanings of these |
7700 | error numbers, and that the meanings must be interpreted according to the |
7701 | type and circumstances of the call. |
7702 | |
7703 | The following is a complete list of the errors and their names as given |
7704 | in <_\bs_\by_\bs_\b/_\be_\br_\br_\bn_\bo_\b._\bh>. |
7705 | |
7706 | 0 _\bU_\bn_\bd_\be_\bf_\bi_\bn_\be_\bd _\be_\br_\br_\bo_\br_\b: _\b0. Not used. |
7707 | |
7708 | 1 EPERM _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bp_\be_\br_\bm_\bi_\bt_\bt_\be_\bd. An attempt was made to perform an |
7709 | operation limited to processes with appropriate privileges or to |
7710 | the owner of a file or other resources. |
7711 | |
7712 | 2 ENOENT _\bN_\bo _\bs_\bu_\bc_\bh _\bf_\bi_\bl_\be _\bo_\br _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. A component of a specified pathname |
7713 | did not exist, or the pathname was an empty string. |
7714 | |
7715 | 3 ESRCH _\bN_\bo _\bs_\bu_\bc_\bh _\bp_\br_\bo_\bc_\be_\bs_\bs. No process could be found which corresponds to |
7716 | the given process ID. |
7717 | |
7718 | 4 EINTR _\bI_\bn_\bt_\be_\br_\br_\bu_\bp_\bt_\be_\bd _\bs_\by_\bs_\bt_\be_\bm _\bc_\ba_\bl_\bl. An asynchronous signal (such as SIGINT |
7719 | or SIGQUIT) was caught by the thread during the execution of an |
7720 | interruptible function. If the signal handler performs a normal |
7721 | return, the interrupted function call will seem to have returned |
7722 | the error condition. |
7723 | |
7724 | 5 EIO _\bI_\bn_\bp_\bu_\bt_\b/_\bo_\bu_\bt_\bp_\bu_\bt _\be_\br_\br_\bo_\br. Some physical input or output error occurred. |
7725 | This error will not be reported until a subsequent operation on |
7726 | the same file descriptor and may be lost (overwritten) by any |
7727 | subsequent errors. |
7728 | |
7729 | 6 ENXIO _\bD_\be_\bv_\bi_\bc_\be _\bn_\bo_\bt _\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\bd. Input or output on a special file referred |
7730 | to a device that did not exist, or made a request beyond the |
7731 | limits of the device. This error may also occur when, for |
7732 | example, a tape drive is not online or no disk pack is loaded on |
7733 | a drive. |
7734 | |
7735 | 7 E2BIG _\bA_\br_\bg_\bu_\bm_\be_\bn_\bt _\bl_\bi_\bs_\bt _\bt_\bo_\bo _\bl_\bo_\bn_\bg. The number of bytes used for the argument |
7736 | and environment list of the new process exceeded the limit NCARGS |
7737 | (specified in <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh>). |
7738 | |
7739 | 8 ENOEXEC _\bE_\bx_\be_\bc _\bf_\bo_\br_\bm_\ba_\bt _\be_\br_\br_\bo_\br. A request was made to execute a file that, |
7740 | although it has the appropriate permissions, was not in the |
7741 | format required for an executable file. |
7742 | |
7743 | 9 EBADF _\bB_\ba_\bd _\bf_\bi_\bl_\be _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br. A file descriptor argument was out of range, |
7744 | referred to no open file, or a read (write) request was made to a |
7745 | file that was only open for writing (reading). |
7746 | |
7747 | 10 ECHILD _\bN_\bo _\bc_\bh_\bi_\bl_\bd _\bp_\br_\bo_\bc_\be_\bs_\bs_\be_\bs. A wait(2) or waitpid(2) function was |
7748 | executed by a process that had no existing or unwaited-for child |
7749 | processes. |
7750 | |
7751 | 11 EDEADLK _\bR_\be_\bs_\bo_\bu_\br_\bc_\be _\bd_\be_\ba_\bd_\bl_\bo_\bc_\bk _\ba_\bv_\bo_\bi_\bd_\be_\bd. An attempt was made to lock a |
7752 | system resource that would have resulted in a deadlock situation. |
7753 | |
7754 | 12 ENOMEM _\bC_\ba_\bn_\bn_\bo_\bt _\ba_\bl_\bl_\bo_\bc_\ba_\bt_\be _\bm_\be_\bm_\bo_\br_\by. The new process image required more |
7755 | memory than was allowed by the hardware or by system-imposed |
7756 | memory management constraints. A lack of swap space is normally |
7757 | temporary; however, a lack of core is not. Soft limits may be |
7758 | increased to their corresponding hard limits. |
7759 | |
7760 | 13 EACCES _\bP_\be_\br_\bm_\bi_\bs_\bs_\bi_\bo_\bn _\bd_\be_\bn_\bi_\be_\bd. An attempt was made to access a file in a |
7761 | way forbidden by its file access permissions. |
7762 | |
7763 | 14 EFAULT _\bB_\ba_\bd _\ba_\bd_\bd_\br_\be_\bs_\bs. The system detected an invalid address in |
7764 | attempting to use an argument of a call. |
7765 | |
7766 | 15 ENOTBLK _\bB_\bl_\bo_\bc_\bk _\bd_\be_\bv_\bi_\bc_\be _\br_\be_\bq_\bu_\bi_\br_\be_\bd. A block device operation was attempted |
7767 | on a non-block device or file. |
7768 | |
7769 | 16 EBUSY _\bD_\be_\bv_\bi_\bc_\be _\bb_\bu_\bs_\by. An attempt to use a system resource which was in |
7770 | use at the time in a manner which would have conflicted with the |
7771 | request. |
7772 | |
7773 | 17 EEXIST _\bF_\bi_\bl_\be _\be_\bx_\bi_\bs_\bt_\bs. An existing file was mentioned in an inappropriate |
7774 | context, for instance, as the new link name in a link(2) |
7775 | function. |
7776 | |
7777 | 18 EXDEV _\bC_\br_\bo_\bs_\bs_\b-_\bd_\be_\bv_\bi_\bc_\be _\bl_\bi_\bn_\bk. A hard link to a file on another file system |
7778 | was attempted. |
7779 | |
7780 | 19 ENODEV _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd _\bb_\by _\bd_\be_\bv_\bi_\bc_\be. An attempt was made to apply |
7781 | an inappropriate function to a device, for example, trying to |
7782 | read a write-only device such as a printer. |
7783 | |
7784 | 20 ENOTDIR _\bN_\bo_\bt _\ba _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. A component of the specified pathname |
7785 | existed, but it was not a directory, when a directory was |
7786 | expected. |
7787 | |
7788 | 21 EISDIR _\bI_\bs _\ba _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. An attempt was made to open a directory with |
7789 | write mode specified. |
7790 | |
7791 | 22 EINVAL _\bI_\bn_\bv_\ba_\bl_\bi_\bd _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt. Some invalid argument was supplied. (For |
7792 | example, specifying an undefined signal to a signal(3) or kill(2) |
7793 | function). |
7794 | |
7795 | 23 ENFILE _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bo_\bp_\be_\bn _\bf_\bi_\bl_\be_\bs _\bi_\bn _\bs_\by_\bs_\bt_\be_\bm. Maximum number of file |
7796 | descriptors allowable on the system has been reached and a |
7797 | request for an open cannot be satisfied until at least one has |
7798 | been closed. The sysctl(3) variable _\bk_\be_\br_\bn_\b._\bm_\ba_\bx_\bf_\bi_\bl_\be_\bs contains the |
7799 | current limit. |
7800 | |
7801 | 24 EMFILE _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bo_\bp_\be_\bn _\bf_\bi_\bl_\be_\bs. The maximum number of file descriptors |
7802 | allowable for this process has been reached and a request for an |
7803 | open cannot be satisfied until at least one has been closed. |
7804 | getdtablesize(3) will obtain the current limit. |
7805 | |
7806 | 25 ENOTTY _\bI_\bn_\ba_\bp_\bp_\br_\bo_\bp_\br_\bi_\ba_\bt_\be _\bi_\bo_\bc_\bt_\bl _\bf_\bo_\br _\bd_\be_\bv_\bi_\bc_\be. A control function (see |
7807 | ioctl(2)) was attempted for a file or special device for which |
7808 | the operation was inappropriate. |
7809 | |
7810 | 26 ETXTBSY _\bT_\be_\bx_\bt _\bf_\bi_\bl_\be _\bb_\bu_\bs_\by. An attempt was made either to execute a pure |
7811 | procedure (shared text) file which was open for writing by |
7812 | another process, or to open with write access a pure procedure |
7813 | file that is currently being executed. |
7814 | |
7815 | 27 EFBIG _\bF_\bi_\bl_\be _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be. The size of a file exceeded the maximum. (The |
7816 | system-wide maximum file size is 2**63 bytes. Each file system |
7817 | may impose a lower limit for files contained within it.) |
7818 | |
7819 | 28 ENOSPC _\bN_\bo _\bs_\bp_\ba_\bc_\be _\bl_\be_\bf_\bt _\bo_\bn _\bd_\be_\bv_\bi_\bc_\be. A write(2) to an ordinary file, the |
7820 | creation of a directory or symbolic link, or the creation of a |
7821 | directory entry failed because no more disk blocks were available |
7822 | on the file system, or the allocation of an inode for a newly |
7823 | created file failed because no more inodes were available on the |
7824 | file system. |
7825 | |
7826 | 29 ESPIPE _\bI_\bl_\bl_\be_\bg_\ba_\bl _\bs_\be_\be_\bk. An lseek(2) function was issued on a socket, pipe |
7827 | or FIFO. |
7828 | |
7829 | 30 EROFS _\bR_\be_\ba_\bd_\b-_\bo_\bn_\bl_\by _\bf_\bi_\bl_\be _\bs_\by_\bs_\bt_\be_\bm. An attempt was made to modify a file or |
7830 | create a directory on a file system that was read-only at the |
7831 | time. |
7832 | |
7833 | 31 EMLINK _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bl_\bi_\bn_\bk_\bs. The maximum allowable number of hard links to a |
7834 | single file has been exceeded (see pathconf(2) for how to obtain |
7835 | this value). |
7836 | |
7837 | 32 EPIPE _\bB_\br_\bo_\bk_\be_\bn _\bp_\bi_\bp_\be. A write on a pipe, socket or FIFO for which there |
7838 | is no process to read the data. |
7839 | |
7840 | 33 EDOM _\bN_\bu_\bm_\be_\br_\bi_\bc_\ba_\bl _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt _\bo_\bu_\bt _\bo_\bf _\bd_\bo_\bm_\ba_\bi_\bn. A numerical input argument was |
7841 | outside the defined domain of the mathematical function. |
7842 | |
7843 | 34 ERANGE _\bR_\be_\bs_\bu_\bl_\bt _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be. A result of the function was too large to fit |
7844 | in the available space (perhaps exceeded precision). |
7845 | |
7846 | 35 EAGAIN _\bR_\be_\bs_\bo_\bu_\br_\bc_\be _\bt_\be_\bm_\bp_\bo_\br_\ba_\br_\bi_\bl_\by _\bu_\bn_\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. This is a temporary condition |
7847 | and later calls to the same routine may complete normally. |
7848 | |
7849 | 36 EINPROGRESS _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bw _\bi_\bn _\bp_\br_\bo_\bg_\br_\be_\bs_\bs. An operation that takes a long |
7850 | time to complete (such as a connect(2)) was attempted on a non- |
7851 | blocking object (see fcntl(2)). |
7852 | |
7853 | 37 EALREADY _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\ba_\bl_\br_\be_\ba_\bd_\by _\bi_\bn _\bp_\br_\bo_\bg_\br_\be_\bs_\bs. An operation was attempted on |
7854 | a non-blocking object that already had an operation in progress. |
7855 | |
7856 | 38 ENOTSOCK _\bS_\bo_\bc_\bk_\be_\bt _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bo_\bn _\bn_\bo_\bn_\b-_\bs_\bo_\bc_\bk_\be_\bt. Self-explanatory. |
7857 | |
7858 | 39 EDESTADDRREQ _\bD_\be_\bs_\bt_\bi_\bn_\ba_\bt_\bi_\bo_\bn _\ba_\bd_\bd_\br_\be_\bs_\bs _\br_\be_\bq_\bu_\bi_\br_\be_\bd. A required address was |
7859 | omitted from an operation on a socket. |
7860 | |
7861 | 40 EMSGSIZE _\bM_\be_\bs_\bs_\ba_\bg_\be _\bt_\bo_\bo _\bl_\bo_\bn_\bg. A message sent on a socket was larger than |
7862 | the internal message buffer or some other network limit. |
7863 | |
7864 | 41 EPROTOTYPE _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bw_\br_\bo_\bn_\bg _\bt_\by_\bp_\be _\bf_\bo_\br _\bs_\bo_\bc_\bk_\be_\bt. A protocol was specified |
7865 | that does not support the semantics of the socket type requested. |
7866 | For example, you cannot use the Internet UDP protocol with type |
7867 | SOCK_STREAM. |
7868 | |
7869 | 42 ENOPROTOOPT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bn_\bo_\bt _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. A bad option or level was |
7870 | specified in a getsockopt(2) or setsockopt(2) call. |
7871 | |
7872 | 43 EPROTONOSUPPORT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The protocol has not been |
7873 | configured into the system or no implementation for it exists. |
7874 | |
7875 | 44 ESOCKTNOSUPPORT _\bS_\bo_\bc_\bk_\be_\bt _\bt_\by_\bp_\be _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The support for the socket |
7876 | type has not been configured into the system or no implementation |
7877 | for it exists. |
7878 | |
7879 | 45 EOPNOTSUPP _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The attempted operation is not |
7880 | supported for the type of object referenced. Usually this occurs |
7881 | when a file descriptor refers to a file or socket that cannot |
7882 | support this operation, for example, trying to _\ba_\bc_\bc_\be_\bp_\bt a |
7883 | connection on a datagram socket. |
7884 | |
7885 | 46 EPFNOSUPPORT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bf_\ba_\bm_\bi_\bl_\by _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The protocol family has |
7886 | not been configured into the system or no implementation for it |
7887 | exists. |
7888 | |
7889 | 47 EAFNOSUPPORT _\bA_\bd_\bd_\br_\be_\bs_\bs _\bf_\ba_\bm_\bi_\bl_\by _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd _\bb_\by _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bf_\ba_\bm_\bi_\bl_\by. An |
7890 | address incompatible with the requested protocol was used. For |
7891 | example, you shouldn't necessarily expect to be able to use NS |
7892 | addresses with Internet protocols. |
7893 | |
7894 | 48 EADDRINUSE _\bA_\bd_\bd_\br_\be_\bs_\bs _\ba_\bl_\br_\be_\ba_\bd_\by _\bi_\bn _\bu_\bs_\be. Only one usage of each address is |
7895 | normally permitted. |
7896 | |
7897 | 49 EADDRNOTAVAIL _\bC_\ba_\bn_\b'_\bt _\ba_\bs_\bs_\bi_\bg_\bn _\br_\be_\bq_\bu_\be_\bs_\bt_\be_\bd _\ba_\bd_\bd_\br_\be_\bs_\bs. Normally results from an |
7898 | attempt to create a socket with an address not on this machine. |
7899 | |
7900 | 50 ENETDOWN _\bN_\be_\bt_\bw_\bo_\br_\bk _\bi_\bs _\bd_\bo_\bw_\bn. A socket operation encountered a dead |
7901 | network. |
7902 | |
7903 | 51 ENETUNREACH _\bN_\be_\bt_\bw_\bo_\br_\bk _\bi_\bs _\bu_\bn_\br_\be_\ba_\bc_\bh_\ba_\bb_\bl_\be. A socket operation was attempted |
7904 | to an unreachable network. |
7905 | |
7906 | 52 ENETRESET _\bN_\be_\bt_\bw_\bo_\br_\bk _\bd_\br_\bo_\bp_\bp_\be_\bd _\bc_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\bo_\bn _\br_\be_\bs_\be_\bt. The host you were |
7907 | connected to crashed and rebooted. |
7908 | |
7909 | 53 ECONNABORTED _\bS_\bo_\bf_\bt_\bw_\ba_\br_\be _\bc_\ba_\bu_\bs_\be_\bd _\bc_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\ba_\bb_\bo_\br_\bt. A connection abort was |
7910 | caused internal to your host machine. |
7911 | |
7912 | 54 ECONNRESET _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\br_\be_\bs_\be_\bt _\bb_\by _\bp_\be_\be_\br. A connection was forcibly closed |
7913 | by a peer. This normally results from a loss of the connection |
7914 | on the remote socket due to a timeout or a reboot. |
7915 | |
7916 | 55 ENOBUFS _\bN_\bo _\bb_\bu_\bf_\bf_\be_\br _\bs_\bp_\ba_\bc_\be _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. An operation on a socket or pipe |
7917 | was not performed because the system lacked sufficient buffer |
7918 | space or because a queue was full. |
7919 | |
7920 | 56 EISCONN _\bS_\bo_\bc_\bk_\be_\bt _\bi_\bs _\ba_\bl_\br_\be_\ba_\bd_\by _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd. A connect(2) request was made on |
7921 | an already connected socket; or, a sendto(2) or sendmsg(2) |
7922 | request on a connected socket specified a destination when |
7923 | already connected. |
7924 | |
7925 | 57 ENOTCONN _\bS_\bo_\bc_\bk_\be_\bt _\bi_\bs _\bn_\bo_\bt _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd. A request to send or receive data |
7926 | was disallowed because the socket was not connected and (when |
7927 | sending on a datagram socket) no address was supplied. |
7928 | |
7929 | 58 ESHUTDOWN _\bC_\ba_\bn_\b'_\bt _\bs_\be_\bn_\bd _\ba_\bf_\bt_\be_\br _\bs_\bo_\bc_\bk_\be_\bt _\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn. A request to send data was |
7930 | disallowed because the socket had already been shut down with a |
7931 | previous shutdown(2) call. |
7932 | |
7933 | 59 ETOOMANYREFS _\bT_\bo_\bo _\bm_\ba_\bn_\by _\br_\be_\bf_\be_\br_\be_\bn_\bc_\be_\bs_\b: _\bc_\ba_\bn_\b'_\bt _\bs_\bp_\bl_\bi_\bc_\be. Not used in OpenBSD. |
7934 | |
7935 | 60 ETIMEDOUT _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bt_\bi_\bm_\be_\bd _\bo_\bu_\bt. A connect(2) or send(2) request failed |
7936 | because the connected party did not properly respond after a |
7937 | period of time. (The timeout period is dependent on the |
7938 | communication protocol.) |
7939 | |
7940 | 61 ECONNREFUSED _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\br_\be_\bf_\bu_\bs_\be_\bd. No connection could be made because |
7941 | the target machine actively refused it. This usually results |
7942 | from trying to connect to a service that is inactive on the |
7943 | foreign host. |
7944 | |
7945 | 62 ELOOP _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bl_\be_\bv_\be_\bl_\bs _\bo_\bf _\bs_\by_\bm_\bb_\bo_\bl_\bi_\bc _\bl_\bi_\bn_\bk_\bs. A path name lookup involved |
7946 | more than 32 (SYMLOOP_MAX) symbolic links. |
7947 | |
7948 | 63 ENAMETOOLONG _\bF_\bi_\bl_\be _\bn_\ba_\bm_\be _\bt_\bo_\bo _\bl_\bo_\bn_\bg. A component of a pathname exceeded |
7949 | 255 (NAME_MAX) characters, or an entire pathname (including the |
7950 | terminating NUL) exceeded 1024 (PATH_MAX) bytes. |
7951 | |
7952 | 64 EHOSTDOWN _\bH_\bo_\bs_\bt _\bi_\bs _\bd_\bo_\bw_\bn. A socket operation failed because the |
7953 | destination host was down. |
7954 | |
7955 | 65 EHOSTUNREACH _\bN_\bo _\br_\bo_\bu_\bt_\be _\bt_\bo _\bh_\bo_\bs_\bt. A socket operation was attempted to an |
7956 | unreachable host. |
7957 | |
7958 | 66 ENOTEMPTY _\bD_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bn_\bo_\bt _\be_\bm_\bp_\bt_\by. A directory with entries other than `.' |
7959 | and `..' was supplied to a remove directory or rename call. |
7960 | |
7961 | 67 EPROCLIM _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bp_\br_\bo_\bc_\be_\bs_\bs_\be_\bs. |
7962 | |
7963 | 68 EUSERS _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bu_\bs_\be_\br_\bs. The quota system ran out of table entries. |
7964 | |
7965 | 69 EDQUOT _\bD_\bi_\bs_\bc _\bq_\bu_\bo_\bt_\ba _\be_\bx_\bc_\be_\be_\bd_\be_\bd. A write(2) to an ordinary file, the |
7966 | creation of a directory or symbolic link, or the creation of a |
7967 | directory entry failed because the user's quota of disk blocks |
7968 | was exhausted, or the allocation of an inode for a newly created |
7969 | file failed because the user's quota of inodes was exhausted. |
7970 | |
7971 | 70 ESTALE _\bS_\bt_\ba_\bl_\be _\bN_\bF_\bS _\bf_\bi_\bl_\be _\bh_\ba_\bn_\bd_\bl_\be. An attempt was made to access an open |
7972 | file on an NFS filesystem which is now unavailable as referenced |
7973 | by the file descriptor. This may indicate the file was deleted |
7974 | on the NFS server or some other catastrophic event occurred. |
7975 | |
7976 | 72 EBADRPC _\bR_\bP_\bC _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bs _\bb_\ba_\bd. Exchange of rpc(3) information was |
7977 | unsuccessful. |
7978 | |
7979 | 73 ERPCMISMATCH _\bR_\bP_\bC _\bv_\be_\br_\bs_\bi_\bo_\bn _\bw_\br_\bo_\bn_\bg. The version of rpc(3) on the remote |
7980 | peer is not compatible with the local version. |
7981 | |
7982 | 74 EPROGUNAVAIL _\bR_\bP_\bC _\bp_\br_\bo_\bg_\b. _\bn_\bo_\bt _\ba_\bv_\ba_\bi_\bl. The requested rpc(3) program is not |
7983 | registered on the remote host. |
7984 | |
7985 | 75 EPROGMISMATCH _\bP_\br_\bo_\bg_\br_\ba_\bm _\bv_\be_\br_\bs_\bi_\bo_\bn _\bw_\br_\bo_\bn_\bg. The requested version of the |
7986 | rpc(3) program is not available on the remote host. |
7987 | |
7988 | 76 EPROCUNAVAIL _\bB_\ba_\bd _\bp_\br_\bo_\bc_\be_\bd_\bu_\br_\be _\bf_\bo_\br _\bp_\br_\bo_\bg_\br_\ba_\bm. An rpc(3) call was attempted |
7989 | for a procedure which doesn't exist in the remote program. |
7990 | |
7991 | 77 ENOLCK _\bN_\bo _\bl_\bo_\bc_\bk_\bs _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. A system-imposed limit on the number of |
7992 | simultaneous file locks was reached. |
7993 | |
7994 | 78 ENOSYS _\bF_\bu_\bn_\bc_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd. Attempted a system call that is not |
7995 | available on this system. |
7996 | |
7997 | 79 EFTYPE _\bI_\bn_\ba_\bp_\bp_\br_\bo_\bp_\br_\bi_\ba_\bt_\be _\bf_\bi_\bl_\be _\bt_\by_\bp_\be _\bo_\br _\bf_\bo_\br_\bm_\ba_\bt. The file contains invalid |
7998 | data or set to invalid modes. |
7999 | |
8000 | 80 EAUTH _\bA_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\be_\br_\br_\bo_\br. Attempted to use an invalid authentication |
8001 | ticket to mount a NFS filesystem. |
8002 | |
8003 | 81 ENEEDAUTH _\bN_\be_\be_\bd _\ba_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\bo_\br. An authentication ticket must be |
8004 | obtained before the given NFS filesystem may be mounted. |
8005 | |
8006 | 82 EIPSEC _\bI_\bP_\bs_\be_\bc _\bp_\br_\bo_\bc_\be_\bs_\bs_\bi_\bn_\bg _\bf_\ba_\bi_\bl_\bu_\br_\be. IPsec subsystem error. Not used in |
8007 | OpenBSD. |
8008 | |
8009 | 83 ENOATTR _\bA_\bt_\bt_\br_\bi_\bb_\bu_\bt_\be _\bn_\bo_\bt _\bf_\bo_\bu_\bn_\bd. A UFS Extended Attribute is not found for |
8010 | the specified pathname. |
8011 | |
8012 | 84 EILSEQ _\bI_\bl_\bl_\be_\bg_\ba_\bl _\bb_\by_\bt_\be _\bs_\be_\bq_\bu_\be_\bn_\bc_\be. An illegal sequence of bytes was used |
8013 | when using wide characters. |
8014 | |
8015 | 85 ENOMEDIUM _\bN_\bo _\bm_\be_\bd_\bi_\bu_\bm _\bf_\bo_\bu_\bn_\bd. Attempted to use a removable media device |
8016 | with no medium present. |
8017 | |
8018 | 86 EMEDIUMTYPE _\bW_\br_\bo_\bn_\bg _\bm_\be_\bd_\bi_\bu_\bm _\bt_\by_\bp_\be. Attempted to use a removable media |
8019 | device with incorrect or incompatible medium. |
8020 | |
8021 | 87 EOVERFLOW _\bV_\ba_\bl_\bu_\be _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be _\bt_\bo _\bb_\be _\bs_\bt_\bo_\br_\be_\bd _\bi_\bn _\bd_\ba_\bt_\ba _\bt_\by_\bp_\be. A numerical |
8022 | result of the function was too large to be stored in the caller |
8023 | provided space. |
8024 | |
8025 | 88 ECANCELED _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bc_\ba_\bn_\bc_\be_\bl_\be_\bd. The requested operation was canceled. |
8026 | |
8027 | 89 EIDRM _\bI_\bd_\be_\bn_\bt_\bi_\bf_\bi_\be_\br _\br_\be_\bm_\bo_\bv_\be_\bd. An IPC identifier was removed while the |
8028 | current thread was waiting on it. |
8029 | |
8030 | 90 ENOMSG _\bN_\bo _\bm_\be_\bs_\bs_\ba_\bg_\be _\bo_\bf _\bd_\be_\bs_\bi_\br_\be_\bd _\bt_\by_\bp_\be. An IPC message queue does not |
8031 | contain a message of the desired type, or a message catalog does |
8032 | not contain the requested message. |
8033 | |
8034 | 91 ENOTSUP _\bN_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The operation has requested an unsupported |
8035 | value. |
8036 | |
8037 | D\bDE\bEF\bFI\bIN\bNI\bIT\bTI\bIO\bON\bNS\bS |
8038 | Process |
8039 | A process is a collection of one or more threads, plus the |
8040 | resources shared by those threads such as process ID, address |
8041 | space, user IDs and group IDs, and root directory and current |
8042 | working directory. |
8043 | |
8044 | Process ID |
8045 | Each active process in the system is uniquely identified by a |
8046 | non-negative integer called a process ID. The range of this ID |
8047 | is from 1 to 32766. |
8048 | |
8049 | Parent Process ID |
8050 | A new process is created by a currently active process; (see |
8051 | fork(2)). The parent process ID of a process is initially the |
8052 | process ID of its creator. If the creating process exits, the |
8053 | parent process ID of each child is set to the ID of a system |
8054 | process, init(8). |
8055 | |
8056 | Process Group |
8057 | Each active process is a member of a process group that is |
8058 | identified by a non-negative integer called the process group ID. |
8059 | This is the process ID of the group leader. This grouping |
8060 | permits the signaling of related processes (see termios(4)) and |
8061 | the job control mechanisms of csh(1). |
8062 | |
8063 | Session |
8064 | A session is a set of one or more process groups. A session is |
8065 | created by a successful call to setsid(2), which causes the |
8066 | caller to become the only member of the only process group in the |
8067 | new session. |
8068 | |
8069 | Session Leader |
8070 | A process that has created a new session by a successful call to |
8071 | setsid(2), is known as a session leader. Only a session leader |
8072 | may acquire a terminal as its controlling terminal (see |
8073 | termios(4)). |
8074 | |
8075 | Controlling Process |
8076 | A session leader with a controlling terminal is a controlling |
8077 | process. |
8078 | |
8079 | Controlling Terminal |
8080 | A terminal that is associated with a session is known as the |
8081 | controlling terminal for that session and its members. |
8082 | |
8083 | Terminal Process Group ID |
8084 | A terminal may be acquired by a session leader as its controlling |
8085 | terminal. Once a terminal is associated with a session, any of |
8086 | the process groups within the session may be placed into the |
8087 | foreground by setting the terminal process group ID to the ID of |
8088 | the process group. This facility is used to arbitrate between |
8089 | multiple jobs contending for the same terminal; (see csh(1) and |
8090 | tty(4)). |
8091 | |
8092 | Orphaned Process Group |
8093 | A process group is considered to be _\bo_\br_\bp_\bh_\ba_\bn_\be_\bd if it is not under |
8094 | the control of a job control shell. More precisely, a process |
8095 | group is orphaned when none of its members has a parent process |
8096 | that is in the same session as the group, but is in a different |
8097 | process group. Note that when a process exits, the parent |
8098 | process for its children is changed to be init(8), which is in a |
8099 | separate session. Not all members of an orphaned process group |
8100 | are necessarily orphaned processes (those whose creating process |
8101 | has exited). The process group of a session leader is orphaned |
8102 | by definition. |
8103 | |
8104 | Thread A thread is a preemptively scheduled flow of control within a |
8105 | process, with its own set of register values, floating point |
8106 | environment, thread ID, signal mask, pending signal set, |
8107 | alternate signal stack, thread control block address, resource |
8108 | utilization, errno variable location, and values for thread- |
8109 | specific keys. A process initially has just one thread, a |
8110 | duplicate of the thread in the parent process that created this |
8111 | process. |
8112 | |
8113 | Real User ID and Real Group ID |
8114 | Each user on the system is identified by a positive integer |
8115 | termed the real user ID. |
8116 | |
8117 | Each user is also a member of one or more groups. One of these |
8118 | groups is distinguished from others and used in implementing |
8119 | accounting facilities. The positive integer corresponding to |
8120 | this distinguished group is termed the real group ID. |
8121 | |
8122 | All processes have a real user ID and real group ID. These are |
8123 | initialized from the equivalent attributes of the process that |
8124 | created it. |
8125 | |
8126 | Effective User ID, Effective Group ID, and Group Access List |
8127 | Access to system resources is governed by two values: the |
8128 | effective user ID, and the group access list. The first member |
8129 | of the group access list is also known as the effective group ID. |
8130 | (In POSIX.1, the group access list is known as the set of |
8131 | supplementary group IDs, and it is unspecified whether the |
8132 | effective group ID is a member of the list.) |
8133 | |
8134 | The effective user ID and effective group ID are initially the |
8135 | process's real user ID and real group ID respectively. Either |
8136 | may be modified through execution of a set-user-ID or set-group- |
8137 | ID file (possibly by one of its ancestors) (see execve(2)). By |
8138 | convention, the effective group ID (the first member of the group |
8139 | access list) is duplicated, so that the execution of a set-group- |
8140 | ID program does not result in the loss of the original (real) |
8141 | group ID. |
8142 | |
8143 | The group access list is a set of group IDs used only in |
8144 | determining resource accessibility. Access checks are performed |
8145 | as described below in ``File Access Permissions''. |
8146 | |
8147 | Saved Set User ID and Saved Set Group ID |
8148 | When a process executes a new file, the effective user ID is set |
8149 | to the owner of the file if the file is set-user-ID, and the |
8150 | effective group ID (first element of the group access list) is |
8151 | set to the group of the file if the file is set-group-ID. The |
8152 | effective user ID of the process is then recorded as the saved |
8153 | set-user-ID, and the effective group ID of the process is |
8154 | recorded as the saved set-group-ID. These values may be used to |
8155 | regain those values as the effective user or group ID after |
8156 | reverting to the real ID (see setuid(2)). (In POSIX.1, the saved |
8157 | set-user-ID and saved set-group-ID are optional, and are used in |
8158 | setuid and setgid, but this does not work as desired for the |
8159 | superuser.) |
8160 | |
8161 | Superuser |
8162 | A process is recognized as a _\bs_\bu_\bp_\be_\br_\bu_\bs_\be_\br process and is granted |
8163 | special privileges if its effective user ID is 0. |
8164 | |
8165 | Special Processes |
8166 | The processes with process IDs of 0 and 1 are special. Process 0 |
8167 | is the scheduler. Process 1 is the initialization process |
8168 | init(8), and is the ancestor of every other process in the |
8169 | system. It is used to control the process structure. |
8170 | |
8171 | Descriptor |
8172 | An integer assigned by the system when a file is referenced by |
8173 | open(2) or dup(2), or when a socket is created by pipe(2), |
8174 | socket(2) or socketpair(2), which uniquely identifies an access |
8175 | path to that file or socket from a given process or any of its |
8176 | children. |
8177 | |
8178 | File Name |
8179 | Names consisting of up to 255 (NAME_MAX) characters may be used |
8180 | to name an ordinary file, special file, or directory. |
8181 | |
8182 | These characters may be arbitrary eight-bit values, excluding 0 |
8183 | (NUL) and the ASCII code for `/' (slash). |
8184 | |
8185 | Note that it is generally unwise to use `*', `?', `[' or `]' as |
8186 | part of file names because of the special meaning attached to |
8187 | these characters by the shell. |
8188 | |
8189 | Note also that NAME_MAX is an upper limit fixed by the kernel, |
8190 | meant to be used for sizing buffers. Some filesystems may have |
8191 | additional restrictions. These can be queried using pathconf(2) |
8192 | and fpathconf(2). |
8193 | |
8194 | Path Name |
8195 | A path name is a NUL-terminated character string starting with an |
8196 | optional slash `/', followed by zero or more directory names |
8197 | separated by slashes, optionally followed by a file name. The |
8198 | total length of a path name must be less than 1024 (PATH_MAX) |
8199 | characters. Additional restrictions may apply, depending upon |
8200 | the filesystem, to be queried with pathconf(2) or fpathconf(2) if |
8201 | needed. |
8202 | |
8203 | If a path name begins with a slash, the path search begins at the |
8204 | _\br_\bo_\bo_\bt directory. Otherwise, the search begins from the current |
8205 | working directory. A slash by itself names the root directory. |
8206 | An empty pathname is invalid. |
8207 | |
8208 | Directory |
8209 | A directory is a special type of file that contains entries that |
8210 | are references to other files. Directory entries are called |
8211 | links. By convention, a directory contains at least two links, |
8212 | `.' and `..', referred to as _\bd_\bo_\bt and _\bd_\bo_\bt_\b-_\bd_\bo_\bt respectively. Dot |
8213 | refers to the directory itself and dot-dot refers to its parent |
8214 | directory. |
8215 | |
8216 | Root Directory and Current Working Directory |
8217 | Each process has associated with it a concept of a root directory |
8218 | and a current working directory for the purpose of resolving path |
8219 | name searches. A process's root directory need not be the root |
8220 | directory of the root file system. |
8221 | |
8222 | File Access Permissions |
8223 | Every file in the file system has a set of access permissions. |
8224 | These permissions are used in determining whether a process may |
8225 | perform a requested operation on the file (such as opening a file |
8226 | for writing). Access permissions are established at the time a |
8227 | file is created. They may be changed at some later time through |
8228 | the chmod(2) call. |
8229 | |
8230 | File access is broken down according to whether a file may be: |
8231 | read, written, or executed. Directory files use the execute |
8232 | permission to control if the directory may be searched. |
8233 | |
8234 | File access permissions are interpreted by the system as they |
8235 | apply to three different classes of users: the owner of the file, |
8236 | those users in the file's group, anyone else. Every file has an |
8237 | independent set of access permissions for each of these classes. |
8238 | When an access check is made, the system decides if permission |
8239 | should be granted by checking the access information applicable |
8240 | to the caller. |
8241 | |
8242 | Read, write, and execute/search permissions on a file are granted |
8243 | to a process if: |
8244 | |
8245 | The process's effective user ID is that of the superuser. (Note: |
8246 | even the superuser cannot execute a non-executable file.) |
8247 | |
8248 | The process's effective user ID matches the user ID of the owner |
8249 | of the file and the owner permissions allow the access. |
8250 | |
8251 | The process's effective user ID does not match the user ID of the |
8252 | owner of the file, and either the process's effective group ID |
8253 | matches the group ID of the file, or the group ID of the file is |
8254 | in the process's group access list, and the group permissions |
8255 | allow the access. |
8256 | |
8257 | Neither the effective user ID nor effective group ID and group |
8258 | access list of the process match the corresponding user ID and |
8259 | group ID of the file, but the permissions for ``other users'' |
8260 | allow access. |
8261 | |
8262 | Otherwise, permission is denied. |
8263 | |
8264 | Sockets and Address Families |
8265 | A socket is an endpoint for communication between processes. |
8266 | Each socket has queues for sending and receiving data. |
8267 | |
8268 | Sockets are typed according to their communications properties. |
8269 | These properties include whether messages sent and received at a |
8270 | socket require the name of the partner, whether communication is |
8271 | reliable, the format used in naming message recipients, etc. |
8272 | |
8273 | Each instance of the system supports some collection of socket |
8274 | types; consult socket(2) for more information about the types |
8275 | available and their properties. |
8276 | |
8277 | Each instance of the system supports some number of sets of |
8278 | communications protocols. Each protocol set supports addresses |
8279 | of a certain format. An Address Family is the set of addresses |
8280 | for a specific group of protocols. Each socket has an address |
8281 | chosen from the address family in which the socket was created. |
8282 | |
8283 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
8284 | intro(3), perror(3) |
8285 | |
8286 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
8287 | An k\bkq\bqu\bue\beu\bue\be manual page appeared in Version 6 AT&T UNIX. |
8288 | |
8289 | N\bNA\bAM\bME\bE |
8290 | e\bex\bxe\bec\bcv\bve\be, e\bex\bxe\bec\bct\bt - execute a file |
8291 | |
8292 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
8293 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
8294 | |
8295 | _\bi_\bn_\bt |
8296 | e\bex\bxe\bec\bcv\bve\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b], _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); |
8297 | |
8298 | _\bi_\bn_\bt |
8299 | e\bex\bxe\bec\bct\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b], _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); |
8300 | |
8301 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
8302 | e\bex\bxe\bec\bcv\bve\be() transforms the calling process into a new process. The new |
8303 | process is constructed from an ordinary file, whose name is pointed to by |
8304 | _\bp_\ba_\bt_\bh, called the _\bn_\be_\bw _\bp_\br_\bo_\bc_\be_\bs_\bs _\bf_\bi_\bl_\be. This file is either an executable |
8305 | object file, or a file of data for an interpreter. An executable object |
8306 | file consists of an identifying header, followed by pages of data |
8307 | representing the initial program (text) and initialized data pages. |
8308 | Additional pages may be specified by the header to be initialized with |
8309 | zero data; see elf(5). |
8310 | |
8311 | An interpreter file begins with a line of the form: |
8312 | |
8313 | #\b#!\b! _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br [_\ba_\br_\bg] |
8314 | |
8315 | When an interpreter file is passed to e\bex\bxe\bec\bcv\bve\be() the system instead calls |
8316 | e\bex\bxe\bec\bcv\bve\be() with the specified _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br. If the optional _\ba_\br_\bg is |
8317 | specified, it becomes the first argument to the _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br, and the |
8318 | original _\bp_\ba_\bt_\bh becomes the second argument; otherwise, _\bp_\ba_\bt_\bh becomes the |
8319 | first argument. The original arguments are shifted over to become the |
8320 | subsequent arguments. The zeroth argument, normally the name of the file |
8321 | being executed, is left unchanged. |
8322 | |
8323 | The argument _\ba_\br_\bg_\bv is a pointer to a null-terminated array of character |
8324 | pointers to NUL-terminated character strings. These strings construct |
8325 | the argument list to be made available to the new process. At least one |
8326 | non-null argument must be present in the array; by custom, the first |
8327 | element should be the name of the executed program (for example, the last |
8328 | component of _\bp_\ba_\bt_\bh). |
8329 | |
8330 | The argument _\be_\bn_\bv_\bp is also a pointer to a null-terminated array of |
8331 | character pointers to NUL-terminated strings. A pointer to this array is |
8332 | normally stored in the global variable _\be_\bn_\bv_\bi_\br_\bo_\bn. These strings pass |
8333 | information to the new process that is not directly an argument to the |
8334 | command (see environ(7)). |
8335 | |
8336 | File descriptors open in the calling process image remain open in the new |
8337 | process image, except for those for which the close-on-exec flag is set |
8338 | (see close(2) and fcntl(2)). Descriptors that remain open are unaffected |
8339 | by e\bex\bxe\bec\bcv\bve\be(). In the case of a new setuid or setgid executable being |
8340 | executed, if file descriptors 0, 1, or 2 (representing stdin, stdout, and |
8341 | stderr) are currently unallocated, these descriptors will be opened to |
8342 | point to some system file like _\b/_\bd_\be_\bv_\b/_\bn_\bu_\bl_\bl. The intent is to ensure these |
8343 | descriptors are not unallocated, since many libraries make assumptions |
8344 | about the use of these 3 file descriptors. |
8345 | |
8346 | Signals set to be ignored in the calling process are set to be ignored in |
8347 | the new process. Signals which are set to be caught in the calling |
8348 | process image are set to default action in the new process image. |
8349 | Blocked signals remain blocked regardless of changes to the signal |
8350 | action. The signal stack is reset to be undefined (see sigaction(2) for |
8351 | more information). |
8352 | |
8353 | If the set-user-ID mode bit of the new process image file is set (see |
8354 | chmod(2)), the effective user ID of the new process image is set to the |
8355 | owner ID of the new process image file. If the set-group-ID mode bit of |
8356 | the new process image file is set, the effective group ID of the new |
8357 | process image is set to the group ID of the new process image file. (The |
8358 | effective group ID is the first element of the group list.) The real |
8359 | user ID, real group ID and other group IDs of the new process image |
8360 | remain the same as the calling process image. After any set-user-ID and |
8361 | set-group-ID processing, the effective user ID is recorded as the saved |
8362 | set-user-ID, and the effective group ID is recorded as the saved set- |
8363 | group-ID. These values may be used in changing the effective IDs later |
8364 | (see setuid(2)). The set-user-ID and set-group-ID bits have no effect if |
8365 | the new process image file is located on a file system mounted with the |
8366 | nosuid flag. The process will be started without the new permissions. |
8367 | |
8368 | The new process also inherits the following attributes from the calling |
8369 | process: |
8370 | |
8371 | process ID see getpid(2) |
8372 | parent process ID see getppid(2) |
8373 | process group ID see getpgrp(2) |
8374 | session ID see getsid(2) |
8375 | access groups see getgroups(2) |
8376 | working directory see chdir(2) |
8377 | root directory see chroot(2) |
8378 | control terminal see termios(4) |
8379 | resource usages see getrusage(2) |
8380 | interval timers see getitimer(2) (unless process image file is |
8381 | setuid or setgid, in which case all timers are |
8382 | disabled) |
8383 | resource limits see getrlimit(2) |
8384 | file mode mask see umask(2) |
8385 | signal mask see sigaction(2), sigsetmask(3) |
8386 | |
8387 | When a program is executed as a result of an e\bex\bxe\bec\bcv\bve\be() call, it is entered |
8388 | as follows: |
8389 | |
8390 | main(int argc, char **argv, char **envp) |
8391 | |
8392 | where _\ba_\br_\bg_\bc is the number of elements in _\ba_\br_\bg_\bv (the ``arg count'') and _\ba_\br_\bg_\bv |
8393 | points to the array of character pointers to the arguments themselves. |
8394 | |
8395 | The e\bex\bxe\bec\bct\bt() function is equivalent to e\bex\bxe\bec\bcv\bve\be() with the additional |
8396 | property that it executes the file with the process tracing facilities |
8397 | enabled (see ptrace(2)). |
8398 | |
8399 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
8400 | As the e\bex\bxe\bec\bcv\bve\be() function overlays the current process image with a new |
8401 | process image the successful call has no process to return to. If |
8402 | e\bex\bxe\bec\bcv\bve\be() does return to the calling process an error has occurred; the |
8403 | return value will be -1 and the global variable _\be_\br_\br_\bn_\bo is set to indicate |
8404 | the error. |
8405 | |
8406 | E\bER\bRR\bRO\bOR\bRS\bS |
8407 | e\bex\bxe\bec\bcv\bve\be() will fail and return to the calling process if: |
8408 | |
8409 | [ENOTDIR] A component of the path prefix is not a directory. |
8410 | |
8411 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
8412 | characters, or an entire pathname (including the |
8413 | terminating NUL) exceeded PATH_MAX bytes. |
8414 | |
8415 | [ENOENT] The new process file does not exist. |
8416 | |
8417 | [ELOOP] Too many symbolic links were encountered in |
8418 | translating the pathname. |
8419 | |
8420 | [EACCES] Search permission is denied for a component of the |
8421 | path prefix. |
8422 | |
8423 | [EACCES] The new process file is not an ordinary file. |
8424 | |
8425 | [EACCES] The new process file mode denies execute permission. |
8426 | |
8427 | [EACCES] The new process file is on a filesystem mounted with |
8428 | execution disabled (MNT_NOEXEC in <_\bs_\by_\bs_\b/_\bm_\bo_\bu_\bn_\bt_\b._\bh>). |
8429 | |
8430 | [ENOEXEC] The new process file has the appropriate access |
8431 | permission, but has an invalid magic number in its |
8432 | header. |
8433 | |
8434 | [ETXTBSY] The new process file is a pure procedure (shared text) |
8435 | file that is currently open for writing or reading by |
8436 | some process. |
8437 | |
8438 | [ENOMEM] The new process requires more virtual memory than is |
8439 | allowed by the imposed maximum (getrlimit(2)). |
8440 | |
8441 | [E2BIG] The number of bytes in the new process's argument list |
8442 | is larger than the system-imposed limit. The limit in |
8443 | the system as released is 262144 bytes (NCARGS in |
8444 | <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh>). |
8445 | |
8446 | [EFAULT] The new process file is not as long as indicated by |
8447 | the size values in its header. |
8448 | |
8449 | [EFAULT] _\bp_\ba_\bt_\bh, _\ba_\br_\bg_\bv, or _\be_\bn_\bv_\bp point to an illegal address. |
8450 | |
8451 | [EINVAL] _\ba_\br_\bg_\bv did not contain at least one element. |
8452 | |
8453 | [EIO] An I/O error occurred while reading from the file |
8454 | system. |
8455 | |
8456 | [ENFILE] During startup of an _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br, the system file |
8457 | table was found to be full. |
8458 | |
8459 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
8460 | _exit(2), fork(2), execl(3), exit(3), elf(5), environ(7) |
8461 | |
8462 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
8463 | The e\bex\bxe\bec\bcv\bve\be() function is expected to conform to IEEE Std 1003.1-2008 |
8464 | (``POSIX.1''). The e\bex\bxe\bec\bct\bt() function should not be used in portable |
8465 | applications. |
8466 | |
8467 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
8468 | The predecessor of these functions, the former e\bex\bxe\bec\bc() system call, first |
8469 | appeared in Version 1 AT&T UNIX. The e\bex\bxe\bec\bcv\bve\be() function first appeared in |
8470 | Version 7 AT&T UNIX. |
8471 | |
8472 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
8473 | If a program is _\bs_\be_\bt_\bu_\bi_\bd to a non-superuser, but is executed when the real |
8474 | _\bu_\bi_\bd is ``root'', then the process has some of the powers of a superuser |
8475 | as well. |
8476 | |
8477 | N\bNA\bAM\bME\bE |
8478 | e\bex\bxe\bec\bcv\bve\be, e\bex\bxe\bec\bct\bt - execute a file |
8479 | |
8480 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
8481 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
8482 | |
8483 | _\bi_\bn_\bt |
8484 | e\bex\bxe\bec\bcv\bve\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b], _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); |
8485 | |
8486 | _\bi_\bn_\bt |
8487 | e\bex\bxe\bec\bct\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b], _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); |
8488 | |
8489 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
8490 | e\bex\bxe\bec\bcv\bve\be() transforms the calling process into a new process. The new |
8491 | process is constructed from an ordinary file, whose name is pointed to by |
8492 | _\bp_\ba_\bt_\bh, called the _\bn_\be_\bw _\bp_\br_\bo_\bc_\be_\bs_\bs _\bf_\bi_\bl_\be. This file is either an executable |
8493 | object file, or a file of data for an interpreter. An executable object |
8494 | file consists of an identifying header, followed by pages of data |
8495 | representing the initial program (text) and initialized data pages. |
8496 | Additional pages may be specified by the header to be initialized with |
8497 | zero data; see elf(5). |
8498 | |
8499 | An interpreter file begins with a line of the form: |
8500 | |
8501 | #\b#!\b! _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br [_\ba_\br_\bg] |
8502 | |
8503 | When an interpreter file is passed to e\bex\bxe\bec\bcv\bve\be() the system instead calls |
8504 | e\bex\bxe\bec\bcv\bve\be() with the specified _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br. If the optional _\ba_\br_\bg is |
8505 | specified, it becomes the first argument to the _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br, and the |
8506 | original _\bp_\ba_\bt_\bh becomes the second argument; otherwise, _\bp_\ba_\bt_\bh becomes the |
8507 | first argument. The original arguments are shifted over to become the |
8508 | subsequent arguments. The zeroth argument, normally the name of the file |
8509 | being executed, is left unchanged. |
8510 | |
8511 | The argument _\ba_\br_\bg_\bv is a pointer to a null-terminated array of character |
8512 | pointers to NUL-terminated character strings. These strings construct |
8513 | the argument list to be made available to the new process. At least one |
8514 | non-null argument must be present in the array; by custom, the first |
8515 | element should be the name of the executed program (for example, the last |
8516 | component of _\bp_\ba_\bt_\bh). |
8517 | |
8518 | The argument _\be_\bn_\bv_\bp is also a pointer to a null-terminated array of |
8519 | character pointers to NUL-terminated strings. A pointer to this array is |
8520 | normally stored in the global variable _\be_\bn_\bv_\bi_\br_\bo_\bn. These strings pass |
8521 | information to the new process that is not directly an argument to the |
8522 | command (see environ(7)). |
8523 | |
8524 | File descriptors open in the calling process image remain open in the new |
8525 | process image, except for those for which the close-on-exec flag is set |
8526 | (see close(2) and fcntl(2)). Descriptors that remain open are unaffected |
8527 | by e\bex\bxe\bec\bcv\bve\be(). In the case of a new setuid or setgid executable being |
8528 | executed, if file descriptors 0, 1, or 2 (representing stdin, stdout, and |
8529 | stderr) are currently unallocated, these descriptors will be opened to |
8530 | point to some system file like _\b/_\bd_\be_\bv_\b/_\bn_\bu_\bl_\bl. The intent is to ensure these |
8531 | descriptors are not unallocated, since many libraries make assumptions |
8532 | about the use of these 3 file descriptors. |
8533 | |
8534 | Signals set to be ignored in the calling process are set to be ignored in |
8535 | the new process. Signals which are set to be caught in the calling |
8536 | process image are set to default action in the new process image. |
8537 | Blocked signals remain blocked regardless of changes to the signal |
8538 | action. The signal stack is reset to be undefined (see sigaction(2) for |
8539 | more information). |
8540 | |
8541 | If the set-user-ID mode bit of the new process image file is set (see |
8542 | chmod(2)), the effective user ID of the new process image is set to the |
8543 | owner ID of the new process image file. If the set-group-ID mode bit of |
8544 | the new process image file is set, the effective group ID of the new |
8545 | process image is set to the group ID of the new process image file. (The |
8546 | effective group ID is the first element of the group list.) The real |
8547 | user ID, real group ID and other group IDs of the new process image |
8548 | remain the same as the calling process image. After any set-user-ID and |
8549 | set-group-ID processing, the effective user ID is recorded as the saved |
8550 | set-user-ID, and the effective group ID is recorded as the saved set- |
8551 | group-ID. These values may be used in changing the effective IDs later |
8552 | (see setuid(2)). The set-user-ID and set-group-ID bits have no effect if |
8553 | the new process image file is located on a file system mounted with the |
8554 | nosuid flag. The process will be started without the new permissions. |
8555 | |
8556 | The new process also inherits the following attributes from the calling |
8557 | process: |
8558 | |
8559 | process ID see getpid(2) |
8560 | parent process ID see getppid(2) |
8561 | process group ID see getpgrp(2) |
8562 | session ID see getsid(2) |
8563 | access groups see getgroups(2) |
8564 | working directory see chdir(2) |
8565 | root directory see chroot(2) |
8566 | control terminal see termios(4) |
8567 | resource usages see getrusage(2) |
8568 | interval timers see getitimer(2) (unless process image file is |
8569 | setuid or setgid, in which case all timers are |
8570 | disabled) |
8571 | resource limits see getrlimit(2) |
8572 | file mode mask see umask(2) |
8573 | signal mask see sigaction(2), sigsetmask(3) |
8574 | |
8575 | When a program is executed as a result of an e\bex\bxe\bec\bcv\bve\be() call, it is entered |
8576 | as follows: |
8577 | |
8578 | main(int argc, char **argv, char **envp) |
8579 | |
8580 | where _\ba_\br_\bg_\bc is the number of elements in _\ba_\br_\bg_\bv (the ``arg count'') and _\ba_\br_\bg_\bv |
8581 | points to the array of character pointers to the arguments themselves. |
8582 | |
8583 | The e\bex\bxe\bec\bct\bt() function is equivalent to e\bex\bxe\bec\bcv\bve\be() with the additional |
8584 | property that it executes the file with the process tracing facilities |
8585 | enabled (see ptrace(2)). |
8586 | |
8587 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
8588 | As the e\bex\bxe\bec\bcv\bve\be() function overlays the current process image with a new |
8589 | process image the successful call has no process to return to. If |
8590 | e\bex\bxe\bec\bcv\bve\be() does return to the calling process an error has occurred; the |
8591 | return value will be -1 and the global variable _\be_\br_\br_\bn_\bo is set to indicate |
8592 | the error. |
8593 | |
8594 | E\bER\bRR\bRO\bOR\bRS\bS |
8595 | e\bex\bxe\bec\bcv\bve\be() will fail and return to the calling process if: |
8596 | |
8597 | [ENOTDIR] A component of the path prefix is not a directory. |
8598 | |
8599 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
8600 | characters, or an entire pathname (including the |
8601 | terminating NUL) exceeded PATH_MAX bytes. |
8602 | |
8603 | [ENOENT] The new process file does not exist. |
8604 | |
8605 | [ELOOP] Too many symbolic links were encountered in |
8606 | translating the pathname. |
8607 | |
8608 | [EACCES] Search permission is denied for a component of the |
8609 | path prefix. |
8610 | |
8611 | [EACCES] The new process file is not an ordinary file. |
8612 | |
8613 | [EACCES] The new process file mode denies execute permission. |
8614 | |
8615 | [EACCES] The new process file is on a filesystem mounted with |
8616 | execution disabled (MNT_NOEXEC in <_\bs_\by_\bs_\b/_\bm_\bo_\bu_\bn_\bt_\b._\bh>). |
8617 | |
8618 | [ENOEXEC] The new process file has the appropriate access |
8619 | permission, but has an invalid magic number in its |
8620 | header. |
8621 | |
8622 | [ETXTBSY] The new process file is a pure procedure (shared text) |
8623 | file that is currently open for writing or reading by |
8624 | some process. |
8625 | |
8626 | [ENOMEM] The new process requires more virtual memory than is |
8627 | allowed by the imposed maximum (getrlimit(2)). |
8628 | |
8629 | [E2BIG] The number of bytes in the new process's argument list |
8630 | is larger than the system-imposed limit. The limit in |
8631 | the system as released is 262144 bytes (NCARGS in |
8632 | <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh>). |
8633 | |
8634 | [EFAULT] The new process file is not as long as indicated by |
8635 | the size values in its header. |
8636 | |
8637 | [EFAULT] _\bp_\ba_\bt_\bh, _\ba_\br_\bg_\bv, or _\be_\bn_\bv_\bp point to an illegal address. |
8638 | |
8639 | [EINVAL] _\ba_\br_\bg_\bv did not contain at least one element. |
8640 | |
8641 | [EIO] An I/O error occurred while reading from the file |
8642 | system. |
8643 | |
8644 | [ENFILE] During startup of an _\bi_\bn_\bt_\be_\br_\bp_\br_\be_\bt_\be_\br, the system file |
8645 | table was found to be full. |
8646 | |
8647 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
8648 | _exit(2), fork(2), execl(3), exit(3), elf(5), environ(7) |
8649 | |
8650 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
8651 | The e\bex\bxe\bec\bcv\bve\be() function is expected to conform to IEEE Std 1003.1-2008 |
8652 | (``POSIX.1''). The e\bex\bxe\bec\bct\bt() function should not be used in portable |
8653 | applications. |
8654 | |
8655 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
8656 | The predecessor of these functions, the former e\bex\bxe\bec\bc() system call, first |
8657 | appeared in Version 1 AT&T UNIX. The e\bex\bxe\bec\bcv\bve\be() function first appeared in |
8658 | Version 7 AT&T UNIX. |
8659 | |
8660 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
8661 | If a program is _\bs_\be_\bt_\bu_\bi_\bd to a non-superuser, but is executed when the real |
8662 | _\bu_\bi_\bd is ``root'', then the process has some of the powers of a superuser |
8663 | as well. |
8664 | |
8665 | N\bNA\bAM\bME\bE |
8666 | a\bac\bcc\bce\bes\bss\bs, f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt - check access permissions of a file or pathname |
8667 | |
8668 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
8669 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
8670 | |
8671 | _\bi_\bn_\bt |
8672 | a\bac\bcc\bce\bes\bss\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\ba_\bm_\bo_\bd_\be); |
8673 | |
8674 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
8675 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
8676 | |
8677 | _\bi_\bn_\bt |
8678 | f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\ba_\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
8679 | |
8680 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
8681 | The a\bac\bcc\bce\bes\bss\bs() function checks the accessibility of the file named by _\bp_\ba_\bt_\bh |
8682 | for the access permissions indicated by _\ba_\bm_\bo_\bd_\be. The _\ba_\bm_\bo_\bd_\be argument is |
8683 | either the bitwise OR of one or more of the access permissions to be |
8684 | checked (R_OK for read permission, W_OK for write permission, and X_OK |
8685 | for execute/search permission) or the existence test, F_OK. All |
8686 | components of the pathname _\bp_\ba_\bt_\bh are checked for access permissions |
8687 | (including F_OK). |
8688 | |
8689 | The real user ID is used in place of the effective user ID and the real |
8690 | group access list (including the real group ID) is used in place of the |
8691 | effective ID for verifying permission. |
8692 | |
8693 | If the invoking process has superuser privileges, a\bac\bcc\bce\bes\bss\bs() will always |
8694 | indicate success for R_OK and W_OK, regardless of the actual file |
8695 | permission bits. Likewise, for X_OK, if the file has any of the execute |
8696 | bits set and _\bp_\ba_\bt_\bh is not a directory, a\bac\bcc\bce\bes\bss\bs() will indicate success. |
8697 | |
8698 | The f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() function is equivalent to a\bac\bcc\bce\bes\bss\bs() except that where _\bp_\ba_\bt_\bh |
8699 | specifies a relative path, the file whose accessibility is checked is |
8700 | determined relative to the directory associated with file descriptor _\bf_\bd |
8701 | instead of the current working directory. |
8702 | |
8703 | If f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
8704 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
8705 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to a\bac\bcc\bce\bes\bss\bs(). |
8706 | |
8707 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
8708 | values: |
8709 | |
8710 | AT_EACCESS The checks for accessibility are performed using the |
8711 | effective user and group IDs instead of the real user |
8712 | and group IDs. |
8713 | |
8714 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
8715 | If _\bp_\ba_\bt_\bh cannot be found or if any of the desired access modes would not |
8716 | be granted, then a -1 value is returned; otherwise a 0 value is returned. |
8717 | |
8718 | E\bER\bRR\bRO\bOR\bRS\bS |
8719 | Access to the file is denied if: |
8720 | |
8721 | [ENOTDIR] A component of the path prefix is not a directory. |
8722 | |
8723 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
8724 | characters, or an entire pathname (including the |
8725 | terminating NUL) exceeded PATH_MAX bytes. |
8726 | |
8727 | [ENOENT] The named file does not exist. |
8728 | |
8729 | [ELOOP] Too many symbolic links were encountered in |
8730 | translating the pathname. |
8731 | |
8732 | [EROFS] Write access is requested for a file on a read-only |
8733 | file system. |
8734 | |
8735 | [ETXTBSY] Write access is requested for a pure procedure (shared |
8736 | text) file presently being executed. |
8737 | |
8738 | [EACCES] Permission bits of the file mode do not permit the |
8739 | requested access, or search permission is denied on a |
8740 | component of the path prefix. The owner of a file has |
8741 | permission checked with respect to the ``owner'' read, |
8742 | write, and execute mode bits, members of the file's |
8743 | group other than the owner have permission checked |
8744 | with respect to the ``group'' mode bits, and all |
8745 | others have permissions checked with respect to the |
8746 | ``other'' mode bits. |
8747 | |
8748 | [EPERM] Write access has been requested and the named file has |
8749 | its immutable flag set (see chflags(2)). |
8750 | |
8751 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
8752 | space. |
8753 | |
8754 | [EIO] An I/O error occurred while reading from or writing to |
8755 | the file system. |
8756 | |
8757 | [EINVAL] An invalid value was specified for _\ba_\bm_\bo_\bd_\be. |
8758 | |
8759 | Additionally, f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() will fail if: |
8760 | |
8761 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
8762 | AT_EACCESS. |
8763 | |
8764 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
8765 | argument is neither AT_FDCWD nor a valid file |
8766 | descriptor. |
8767 | |
8768 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
8769 | argument is a valid file descriptor but it does not |
8770 | reference a directory. |
8771 | |
8772 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
8773 | permission is denied for the directory which the _\bf_\bd |
8774 | file descriptor references. |
8775 | |
8776 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
8777 | chmod(2), stat(2) |
8778 | |
8779 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
8780 | The a\bac\bcc\bce\bes\bss\bs() and f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() functions conform to IEEE Std 1003.1-2008 |
8781 | (``POSIX.1''). |
8782 | |
8783 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
8784 | a\bac\bcc\bce\bes\bss\bs() first appeared as an internal kernel function in Version 1 AT&T |
8785 | UNIX and was reimplemented in C before the release of Version 4 AT&T |
8786 | UNIX. It was first promoted to a system call in the Programmer's |
8787 | Workbench (PWB/UNIX), which was later ported to Version 7 AT&T UNIX and |
8788 | 2BSD. |
8789 | |
8790 | The f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() function appeared in OpenBSD 5.0. |
8791 | |
8792 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
8793 | Ken Thompson first implemented the a\bac\bcc\bce\bes\bss\bs() kernel function in C. |
8794 | |
8795 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
8796 | a\bac\bcc\bce\bes\bss\bs() and f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt() should never be used for actual access control. |
8797 | Doing so can result in a time of check vs. time of use security hole. |
8798 | |
8799 | N\bNA\bAM\bME\bE |
8800 | c\bch\bhd\bdi\bir\br, f\bfc\bch\bhd\bdi\bir\br - change current working directory |
8801 | |
8802 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
8803 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
8804 | |
8805 | _\bi_\bn_\bt |
8806 | c\bch\bhd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
8807 | |
8808 | _\bi_\bn_\bt |
8809 | f\bfc\bch\bhd\bdi\bir\br(_\bi_\bn_\bt _\bf_\bd); |
8810 | |
8811 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
8812 | The _\bp_\ba_\bt_\bh argument points to the pathname of a directory. The c\bch\bhd\bdi\bir\br() |
8813 | function causes the named directory to become the current working |
8814 | directory, that is, the starting point for path searches of pathnames not |
8815 | beginning with a slash (`/'). |
8816 | |
8817 | The f\bfc\bch\bhd\bdi\bir\br() function causes the directory referenced by _\bf_\bd to become the |
8818 | current working directory, the starting point for path searches of |
8819 | pathnames not beginning with a slash (`/'). |
8820 | |
8821 | In order for a directory to become the current directory, a process must |
8822 | have execute (search) access to the directory. |
8823 | |
8824 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
8825 | Upon successful completion, the value 0 is returned; otherwise the |
8826 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
8827 | error. |
8828 | |
8829 | E\bER\bRR\bRO\bOR\bRS\bS |
8830 | c\bch\bhd\bdi\bir\br() will fail and the current working directory will be unchanged if |
8831 | one or more of the following are true: |
8832 | |
8833 | [ENOTDIR] A component of the path prefix is not a directory. |
8834 | |
8835 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
8836 | characters, or an entire pathname (including the |
8837 | terminating NUL) exceeded PATH_MAX bytes. |
8838 | |
8839 | [ENOENT] The named directory does not exist. |
8840 | |
8841 | [ELOOP] Too many symbolic links were encountered in |
8842 | translating the pathname. |
8843 | |
8844 | [EACCES] Search permission is denied for any component of the |
8845 | pathname. |
8846 | |
8847 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
8848 | space. |
8849 | |
8850 | [EIO] An I/O error occurred while reading from the file |
8851 | system. |
8852 | |
8853 | f\bfc\bch\bhd\bdi\bir\br() will fail and the current working directory will be unchanged if |
8854 | one or more of the following are true: |
8855 | |
8856 | [EACCES] Search permission is denied for the directory |
8857 | referenced by the file descriptor. |
8858 | |
8859 | [ENOTDIR] The file descriptor does not reference a directory. |
8860 | |
8861 | [EBADF] The argument _\bf_\bd is not a valid file descriptor. |
8862 | |
8863 | [EIO] An I/O error occurred while reading from the file |
8864 | system. |
8865 | |
8866 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
8867 | chroot(2) |
8868 | |
8869 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
8870 | The c\bch\bhd\bdi\bir\br() and f\bfc\bch\bhd\bdi\bir\br() functions are expected to conform to IEEE Std |
8871 | 1003.1-2008 (``POSIX.1''). |
8872 | |
8873 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
8874 | The c\bch\bhd\bdi\bir\br() system call first appeared in Version 1 AT&T UNIX, and |
8875 | f\bfc\bch\bhd\bdi\bir\br() in 4.3BSD-Reno. |
8876 | |
8877 | N\bNA\bAM\bME\bE |
8878 | c\bch\bhf\bfl\bla\bag\bgs\bs, c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt, f\bfc\bch\bhf\bfl\bla\bag\bgs\bs - set file flags |
8879 | |
8880 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
8881 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
8882 | |
8883 | _\bi_\bn_\bt |
8884 | c\bch\bhf\bfl\bla\bag\bgs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
8885 | |
8886 | _\bi_\bn_\bt |
8887 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs(_\bi_\bn_\bt _\bf_\bd, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
8888 | |
8889 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
8890 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
8891 | |
8892 | _\bi_\bn_\bt |
8893 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\ba_\bt_\bf_\bl_\ba_\bg_\bs); |
8894 | |
8895 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
8896 | The file whose name is given by _\bp_\ba_\bt_\bh or referenced by the descriptor _\bf_\bd |
8897 | has its flags changed to _\bf_\bl_\ba_\bg_\bs. |
8898 | |
8899 | The flags are the bitwise OR of zero or more of the following values: |
8900 | |
8901 | UF_NODUMP Do not dump the file. |
8902 | UF_IMMUTABLE The file may not be changed. |
8903 | UF_APPEND The file may only be appended to. |
8904 | SF_ARCHIVED The file may be archived. |
8905 | SF_IMMUTABLE The file may not be changed. |
8906 | SF_APPEND The file may only be appended to. |
8907 | |
8908 | The UF_IMMUTABLE and UF_APPEND flags may be set or unset by either the |
8909 | owner of a file or the superuser. |
8910 | |
8911 | The SF_ARCHIVED, SF_IMMUTABLE and SF_APPEND flags may only be set or |
8912 | unset by the superuser. They may be set at any time, but normally may |
8913 | only be unset when the system is in single-user mode. (See init(8) for |
8914 | details.) |
8915 | |
8916 | The c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except in the case |
8917 | where _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be |
8918 | changed is determined relative to the directory associated with the file |
8919 | descriptor _\bf_\bd instead of the current working directory. |
8920 | |
8921 | If c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
8922 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
8923 | If _\bf_\bl_\ba_\bg is also zero, the behavior is identical to a call to c\bch\bhf\bfl\bla\bag\bgs\bs(). |
8924 | |
8925 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
8926 | values: |
8927 | |
8928 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the flags |
8929 | of the symbolic link are changed. |
8930 | |
8931 | The f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() function is equivalent to c\bch\bhf\bfl\bla\bag\bgs\bs() except that the file |
8932 | whose flags are changed is specified by the file descriptor _\bf_\bd. |
8933 | |
8934 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
8935 | Upon successful completion, the value 0 is returned; otherwise the |
8936 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
8937 | error. |
8938 | |
8939 | E\bER\bRR\bRO\bOR\bRS\bS |
8940 | c\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
8941 | |
8942 | [ENOTDIR] A component of the path prefix is not a directory. |
8943 | |
8944 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
8945 | characters, or an entire pathname (including the |
8946 | terminating NUL) exceeded PATH_MAX bytes. |
8947 | |
8948 | [ENOENT] The named file does not exist. |
8949 | |
8950 | [EACCES] Search permission is denied for a component of the |
8951 | path prefix. |
8952 | |
8953 | [ELOOP] Too many symbolic links were encountered in |
8954 | translating the pathname. |
8955 | |
8956 | [EPERM] The effective user ID does not match the owner of the |
8957 | file and the effective user ID is not the superuser, |
8958 | or the effective user ID is not the superuser and at |
8959 | least one of the super-user-only flags for the named |
8960 | file would be changed. |
8961 | |
8962 | [EOPNOTSUPP] The named file resides on a file system that does not |
8963 | support file flags. |
8964 | |
8965 | [EROFS] The named file resides on a read-only file system. |
8966 | |
8967 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
8968 | space. |
8969 | |
8970 | [EIO] An I/O error occurred while reading from or writing to |
8971 | the file system. |
8972 | |
8973 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
8974 | |
8975 | [EINVAL] The descriptor references a block or character device |
8976 | and the effective user ID is not the superuser. |
8977 | |
8978 | f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() will fail if: |
8979 | |
8980 | [EBADF] The descriptor is not valid. |
8981 | |
8982 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
8983 | |
8984 | [EINVAL] The descriptor references a block or character device |
8985 | and the effective user ID is not the superuser. |
8986 | |
8987 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs value is invalid. |
8988 | |
8989 | [EPERM] The effective user ID does not match the owner of the |
8990 | file and the effective user ID is not the superuser, |
8991 | or the effective user ID is not the superuser and at |
8992 | least one of the super-user-only flags for the named |
8993 | file would be changed. |
8994 | |
8995 | [EOPNOTSUPP] The named file resides on a file system that does not |
8996 | support file flags. |
8997 | |
8998 | [EROFS] The file resides on a read-only file system. |
8999 | |
9000 | [EIO] An I/O error occurred while reading from or writing to |
9001 | the file system. |
9002 | |
9003 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
9004 | chflags(1), init(8) |
9005 | |
9006 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
9007 | The c\bch\bhf\bfl\bla\bag\bgs\bs() and f\bfc\bch\bhf\bfl\bla\bag\bgs\bs() functions first appeared in 4.4BSD. The |
9008 | c\bch\bhf\bfl\bla\bag\bgs\bsa\bat\bt() function first appeared in FreeBSD 10.0. It was added to |
9009 | OpenBSD in OpenBSD 5.7. |
9010 | |
9011 | N\bNA\bAM\bME\bE |
9012 | c\bch\bhm\bmo\bod\bd, f\bfc\bch\bhm\bmo\bod\bda\bat\bt, f\bfc\bch\bhm\bmo\bod\bd - change mode of file |
9013 | |
9014 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9015 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
9016 | |
9017 | _\bi_\bn_\bt |
9018 | c\bch\bhm\bmo\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
9019 | |
9020 | _\bi_\bn_\bt |
9021 | f\bfc\bch\bhm\bmo\bod\bd(_\bi_\bn_\bt _\bf_\bd, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
9022 | |
9023 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
9024 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
9025 | |
9026 | _\bi_\bn_\bt |
9027 | f\bfc\bch\bhm\bmo\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
9028 | |
9029 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
9030 | The c\bch\bhm\bmo\bod\bd() function sets the file permission bits of the file specified |
9031 | by the pathname _\bp_\ba_\bt_\bh to _\bm_\bo_\bd_\be. c\bch\bhm\bmo\bod\bd() verifies that the process owner |
9032 | (user) either owns the specified file or is the superuser. |
9033 | |
9034 | The _\bm_\bo_\bd_\be argument is the bitwise OR of zero or more of the permission bit |
9035 | masks from the following list: |
9036 | |
9037 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
9038 | #define S_IRUSR 0000400 /* R for owner */ |
9039 | #define S_IWUSR 0000200 /* W for owner */ |
9040 | #define S_IXUSR 0000100 /* X for owner */ |
9041 | |
9042 | #define S_IRWXG 0000070 /* RWX mask for group */ |
9043 | #define S_IRGRP 0000040 /* R for group */ |
9044 | #define S_IWGRP 0000020 /* W for group */ |
9045 | #define S_IXGRP 0000010 /* X for group */ |
9046 | |
9047 | #define S_IRWXO 0000007 /* RWX mask for other */ |
9048 | #define S_IROTH 0000004 /* R for other */ |
9049 | #define S_IWOTH 0000002 /* W for other */ |
9050 | #define S_IXOTH 0000001 /* X for other */ |
9051 | |
9052 | #define S_ISUID 0004000 /* set user id on execution */ |
9053 | #define S_ISGID 0002000 /* set group id on execution */ |
9054 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
9055 | |
9056 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a file, it is ignored. |
9057 | |
9058 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a directory, an unprivileged |
9059 | user may not delete or rename files of other users in that directory. |
9060 | The sticky bit may be set by any user on a directory which the user owns |
9061 | or has appropriate permissions. For more details of the properties of |
9062 | the sticky bit, see sticky(8). |
9063 | |
9064 | Writing or changing the owner of a file turns off the set-user-ID and |
9065 | set-group-ID bits unless the user is the superuser. This makes the |
9066 | system somewhat more secure by protecting set-user-ID (set-group-ID) |
9067 | files from remaining set-user-ID (set-group-ID) if they are modified, at |
9068 | the expense of a degree of compatibility. |
9069 | |
9070 | The f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function is equivalent to c\bch\bhm\bmo\bod\bd() except in the case where |
9071 | _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be changed is |
9072 | determined relative to the directory associated with the file descriptor |
9073 | _\bf_\bd instead of the current working directory. |
9074 | |
9075 | If f\bfc\bch\bhm\bmo\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
9076 | in the _\bf_\bd parameter, the current working directory is used. If _\bf_\bl_\ba_\bg is |
9077 | also zero, the behavior is identical to a call to c\bch\bhm\bmo\bod\bd(). |
9078 | |
9079 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
9080 | values: |
9081 | |
9082 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the mode |
9083 | of the symbolic link is changed. |
9084 | |
9085 | The f\bfc\bch\bhm\bmo\bod\bd() function is equivalent to c\bch\bhm\bmo\bod\bd() except that the file whose |
9086 | permissions are changed is specified by the file descriptor _\bf_\bd. |
9087 | |
9088 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
9089 | Upon successful completion, the value 0 is returned; otherwise the |
9090 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
9091 | error. |
9092 | |
9093 | E\bER\bRR\bRO\bOR\bRS\bS |
9094 | The c\bch\bhm\bmo\bod\bd() and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions will fail and the file mode will be |
9095 | unchanged if: |
9096 | |
9097 | [ENOTDIR] A component of the path prefix is not a directory. |
9098 | |
9099 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
9100 | characters, or an entire pathname (including the |
9101 | terminating NUL) exceeded PATH_MAX bytes. |
9102 | |
9103 | [ENOENT] The named file does not exist. |
9104 | |
9105 | [EACCES] Search permission is denied for a component of the |
9106 | path prefix. |
9107 | |
9108 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
9109 | described above. |
9110 | |
9111 | [ELOOP] Too many symbolic links were encountered in |
9112 | translating the pathname. |
9113 | |
9114 | [EPERM] The effective user ID does not match the owner of the |
9115 | file and the effective user ID is not the superuser. |
9116 | |
9117 | [EROFS] The named file resides on a read-only file system. |
9118 | |
9119 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
9120 | space. |
9121 | |
9122 | [EIO] An I/O error occurred while reading from or writing to |
9123 | the file system. |
9124 | |
9125 | Additionally, the f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function will fail if: |
9126 | |
9127 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
9128 | AT_SYMLINK_NOFOLLOW. |
9129 | |
9130 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
9131 | argument is neither AT_FDCWD nor a valid file |
9132 | descriptor. |
9133 | |
9134 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
9135 | argument is a valid file descriptor but it does not |
9136 | reference a directory. |
9137 | |
9138 | [EOPNOTSUPP] The _\bf_\bl_\ba_\bg argument specifies AT_SYMLINK_NOFOLLOW on a |
9139 | symbolic link and the file system does not support |
9140 | that operation. |
9141 | |
9142 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
9143 | permission is denied for the directory which the _\bf_\bd |
9144 | file descriptor references. |
9145 | |
9146 | f\bfc\bch\bhm\bmo\bod\bd() will fail and the file mode will be unchanged if: |
9147 | |
9148 | [EBADF] The descriptor is not valid. |
9149 | |
9150 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
9151 | |
9152 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
9153 | described above. |
9154 | |
9155 | [EPERM] The effective user ID does not match the owner of the |
9156 | file and the effective user ID is not the superuser. |
9157 | |
9158 | [EROFS] The file resides on a read-only file system. |
9159 | |
9160 | [EIO] An I/O error occurred while reading from or writing to |
9161 | the file system. |
9162 | |
9163 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
9164 | chmod(1), chown(2), open(2), stat(2), sticky(8) |
9165 | |
9166 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
9167 | The c\bch\bhm\bmo\bod\bd(), f\bfc\bch\bhm\bmo\bod\bd(), and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions are expected to conform |
9168 | to IEEE Std 1003.1-2008 (``POSIX.1''). |
9169 | |
9170 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
9171 | The c\bch\bhm\bmo\bod\bd() system call first appeared in Version 1 AT&T UNIX; f\bfc\bch\bhm\bmo\bod\bd() |
9172 | in 4.1cBSD; and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
9173 | |
9174 | N\bNA\bAM\bME\bE |
9175 | c\bch\bhm\bmo\bod\bd, f\bfc\bch\bhm\bmo\bod\bda\bat\bt, f\bfc\bch\bhm\bmo\bod\bd - change mode of file |
9176 | |
9177 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9178 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
9179 | |
9180 | _\bi_\bn_\bt |
9181 | c\bch\bhm\bmo\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
9182 | |
9183 | _\bi_\bn_\bt |
9184 | f\bfc\bch\bhm\bmo\bod\bd(_\bi_\bn_\bt _\bf_\bd, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
9185 | |
9186 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
9187 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
9188 | |
9189 | _\bi_\bn_\bt |
9190 | f\bfc\bch\bhm\bmo\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
9191 | |
9192 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
9193 | The c\bch\bhm\bmo\bod\bd() function sets the file permission bits of the file specified |
9194 | by the pathname _\bp_\ba_\bt_\bh to _\bm_\bo_\bd_\be. c\bch\bhm\bmo\bod\bd() verifies that the process owner |
9195 | (user) either owns the specified file or is the superuser. |
9196 | |
9197 | The _\bm_\bo_\bd_\be argument is the bitwise OR of zero or more of the permission bit |
9198 | masks from the following list: |
9199 | |
9200 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
9201 | #define S_IRUSR 0000400 /* R for owner */ |
9202 | #define S_IWUSR 0000200 /* W for owner */ |
9203 | #define S_IXUSR 0000100 /* X for owner */ |
9204 | |
9205 | #define S_IRWXG 0000070 /* RWX mask for group */ |
9206 | #define S_IRGRP 0000040 /* R for group */ |
9207 | #define S_IWGRP 0000020 /* W for group */ |
9208 | #define S_IXGRP 0000010 /* X for group */ |
9209 | |
9210 | #define S_IRWXO 0000007 /* RWX mask for other */ |
9211 | #define S_IROTH 0000004 /* R for other */ |
9212 | #define S_IWOTH 0000002 /* W for other */ |
9213 | #define S_IXOTH 0000001 /* X for other */ |
9214 | |
9215 | #define S_ISUID 0004000 /* set user id on execution */ |
9216 | #define S_ISGID 0002000 /* set group id on execution */ |
9217 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
9218 | |
9219 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a file, it is ignored. |
9220 | |
9221 | If mode ISVTX (the _\bs_\bt_\bi_\bc_\bk_\by _\bb_\bi_\bt) is set on a directory, an unprivileged |
9222 | user may not delete or rename files of other users in that directory. |
9223 | The sticky bit may be set by any user on a directory which the user owns |
9224 | or has appropriate permissions. For more details of the properties of |
9225 | the sticky bit, see sticky(8). |
9226 | |
9227 | Writing or changing the owner of a file turns off the set-user-ID and |
9228 | set-group-ID bits unless the user is the superuser. This makes the |
9229 | system somewhat more secure by protecting set-user-ID (set-group-ID) |
9230 | files from remaining set-user-ID (set-group-ID) if they are modified, at |
9231 | the expense of a degree of compatibility. |
9232 | |
9233 | The f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function is equivalent to c\bch\bhm\bmo\bod\bd() except in the case where |
9234 | _\bp_\ba_\bt_\bh specifies a relative path. In this case the file to be changed is |
9235 | determined relative to the directory associated with the file descriptor |
9236 | _\bf_\bd instead of the current working directory. |
9237 | |
9238 | If f\bfc\bch\bhm\bmo\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
9239 | in the _\bf_\bd parameter, the current working directory is used. If _\bf_\bl_\ba_\bg is |
9240 | also zero, the behavior is identical to a call to c\bch\bhm\bmo\bod\bd(). |
9241 | |
9242 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
9243 | values: |
9244 | |
9245 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the mode |
9246 | of the symbolic link is changed. |
9247 | |
9248 | The f\bfc\bch\bhm\bmo\bod\bd() function is equivalent to c\bch\bhm\bmo\bod\bd() except that the file whose |
9249 | permissions are changed is specified by the file descriptor _\bf_\bd. |
9250 | |
9251 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
9252 | Upon successful completion, the value 0 is returned; otherwise the |
9253 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
9254 | error. |
9255 | |
9256 | E\bER\bRR\bRO\bOR\bRS\bS |
9257 | The c\bch\bhm\bmo\bod\bd() and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions will fail and the file mode will be |
9258 | unchanged if: |
9259 | |
9260 | [ENOTDIR] A component of the path prefix is not a directory. |
9261 | |
9262 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
9263 | characters, or an entire pathname (including the |
9264 | terminating NUL) exceeded PATH_MAX bytes. |
9265 | |
9266 | [ENOENT] The named file does not exist. |
9267 | |
9268 | [EACCES] Search permission is denied for a component of the |
9269 | path prefix. |
9270 | |
9271 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
9272 | described above. |
9273 | |
9274 | [ELOOP] Too many symbolic links were encountered in |
9275 | translating the pathname. |
9276 | |
9277 | [EPERM] The effective user ID does not match the owner of the |
9278 | file and the effective user ID is not the superuser. |
9279 | |
9280 | [EROFS] The named file resides on a read-only file system. |
9281 | |
9282 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
9283 | space. |
9284 | |
9285 | [EIO] An I/O error occurred while reading from or writing to |
9286 | the file system. |
9287 | |
9288 | Additionally, the f\bfc\bch\bhm\bmo\bod\bda\bat\bt() function will fail if: |
9289 | |
9290 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
9291 | AT_SYMLINK_NOFOLLOW. |
9292 | |
9293 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
9294 | argument is neither AT_FDCWD nor a valid file |
9295 | descriptor. |
9296 | |
9297 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
9298 | argument is a valid file descriptor but it does not |
9299 | reference a directory. |
9300 | |
9301 | [EOPNOTSUPP] The _\bf_\bl_\ba_\bg argument specifies AT_SYMLINK_NOFOLLOW on a |
9302 | symbolic link and the file system does not support |
9303 | that operation. |
9304 | |
9305 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
9306 | permission is denied for the directory which the _\bf_\bd |
9307 | file descriptor references. |
9308 | |
9309 | f\bfc\bch\bhm\bmo\bod\bd() will fail and the file mode will be unchanged if: |
9310 | |
9311 | [EBADF] The descriptor is not valid. |
9312 | |
9313 | [EINVAL] _\bf_\bd refers to a socket, not to a file. |
9314 | |
9315 | [EINVAL] _\bm_\bo_\bd_\be contains bits other than the file type and those |
9316 | described above. |
9317 | |
9318 | [EPERM] The effective user ID does not match the owner of the |
9319 | file and the effective user ID is not the superuser. |
9320 | |
9321 | [EROFS] The file resides on a read-only file system. |
9322 | |
9323 | [EIO] An I/O error occurred while reading from or writing to |
9324 | the file system. |
9325 | |
9326 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
9327 | chmod(1), chown(2), open(2), stat(2), sticky(8) |
9328 | |
9329 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
9330 | The c\bch\bhm\bmo\bod\bd(), f\bfc\bch\bhm\bmo\bod\bd(), and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() functions are expected to conform |
9331 | to IEEE Std 1003.1-2008 (``POSIX.1''). |
9332 | |
9333 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
9334 | The c\bch\bhm\bmo\bod\bd() system call first appeared in Version 1 AT&T UNIX; f\bfc\bch\bhm\bmo\bod\bd() |
9335 | in 4.1cBSD; and f\bfc\bch\bhm\bmo\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
9336 | |
9337 | N\bNA\bAM\bME\bE |
9338 | c\bch\bho\bow\bwn\bn, l\blc\bch\bho\bow\bwn\bn, f\bfc\bch\bho\bow\bwn\bna\bat\bt, f\bfc\bch\bho\bow\bwn\bn - change owner and group of a file or |
9339 | link |
9340 | |
9341 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9342 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
9343 | |
9344 | _\bi_\bn_\bt |
9345 | c\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
9346 | |
9347 | _\bi_\bn_\bt |
9348 | l\blc\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
9349 | |
9350 | _\bi_\bn_\bt |
9351 | f\bfc\bch\bho\bow\bwn\bn(_\bi_\bn_\bt _\bf_\bd, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
9352 | |
9353 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
9354 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
9355 | |
9356 | _\bi_\bn_\bt |
9357 | f\bfc\bch\bho\bow\bwn\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
9358 | |
9359 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
9360 | The owner ID and group ID of the file (or link) named by _\bp_\ba_\bt_\bh or |
9361 | referenced by _\bf_\bd is changed as specified by the arguments _\bo_\bw_\bn_\be_\br and |
9362 | _\bg_\br_\bo_\bu_\bp. The owner of a file may change the _\bg_\br_\bo_\bu_\bp to a group of which he |
9363 | or she is a member, but the change _\bo_\bw_\bn_\be_\br capability is restricted to the |
9364 | superuser. |
9365 | |
9366 | By default, c\bch\bho\bow\bwn\bn() clears the set-user-ID and set-group-ID bits on the |
9367 | file to prevent accidental or mischievous creation of set-user-ID and |
9368 | set-group-ID programs. This behaviour can be overridden by setting the |
9369 | sysctl(8) variable _\bf_\bs_\b._\bp_\bo_\bs_\bi_\bx_\b._\bs_\be_\bt_\bu_\bi_\bd to zero. |
9370 | |
9371 | l\blc\bch\bho\bow\bwn\bn() operates similarly to how c\bch\bho\bow\bwn\bn() operated on older systems, and |
9372 | does not follow symbolic links. It allows the owner and group of a |
9373 | symbolic link to be set. |
9374 | |
9375 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() function is equivalent to either the c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn() |
9376 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
9377 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose ownership is changed is |
9378 | determined relative to the directory associated with file descriptor _\bf_\bd |
9379 | instead of the current working directory. |
9380 | |
9381 | If f\bfc\bch\bho\bow\bwn\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
9382 | in the _\bf_\bd parameter, the current working directory is used and the |
9383 | behavior is identical to a call to c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn(), depending on |
9384 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
9385 | |
9386 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
9387 | values: |
9388 | |
9389 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
9390 | ownership of the symbolic link is changed. |
9391 | |
9392 | f\bfc\bch\bho\bow\bwn\bn() is particularly useful when used in conjunction with the file |
9393 | locking primitives (see flock(2)). |
9394 | |
9395 | One of the owner or group IDs may be left unchanged by specifying it as |
9396 | -1. |
9397 | |
9398 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
9399 | Upon successful completion, the value 0 is returned; otherwise the |
9400 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
9401 | error. |
9402 | |
9403 | E\bER\bRR\bRO\bOR\bRS\bS |
9404 | c\bch\bho\bow\bwn\bn(), l\blc\bch\bho\bow\bwn\bn(), and f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail and the file or link will be |
9405 | unchanged if: |
9406 | |
9407 | [ENOTDIR] A component of the path prefix is not a directory. |
9408 | |
9409 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
9410 | characters, or an entire pathname (including the |
9411 | terminating NUL) exceeded PATH_MAX bytes. |
9412 | |
9413 | [ENOENT] The named file does not exist. |
9414 | |
9415 | [EACCES] Search permission is denied for a component of the |
9416 | path prefix. |
9417 | |
9418 | [ELOOP] Too many symbolic links were encountered in |
9419 | translating the pathname. |
9420 | |
9421 | [EPERM] The effective user ID is not the superuser. |
9422 | |
9423 | [EROFS] The named file resides on a read-only file system. |
9424 | |
9425 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
9426 | space. |
9427 | |
9428 | [EIO] An I/O error occurred while reading from or writing to |
9429 | the file system. |
9430 | |
9431 | Additionally, f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail if: |
9432 | |
9433 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
9434 | AT_SYMLINK_NOFOLLOW. |
9435 | |
9436 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
9437 | argument is neither AT_FDCWD nor a valid file |
9438 | descriptor. |
9439 | |
9440 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
9441 | argument is a valid file descriptor but it does not |
9442 | reference a directory. |
9443 | |
9444 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
9445 | permission is denied for the directory which the _\bf_\bd |
9446 | file descriptor references. |
9447 | |
9448 | f\bfc\bch\bho\bow\bwn\bn() will fail if: |
9449 | |
9450 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
9451 | |
9452 | [EINVAL] _\bf_\bd refers to a socket, not a file. |
9453 | |
9454 | [EPERM] The effective user ID is not the superuser. |
9455 | |
9456 | [EROFS] The named file resides on a read-only file system. |
9457 | |
9458 | [EIO] An I/O error occurred while reading from or writing to |
9459 | the file system. |
9460 | |
9461 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
9462 | chgrp(1), chmod(2), flock(2), chown(8) |
9463 | |
9464 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
9465 | The c\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), and l\blc\bch\bho\bow\bwn\bn() functions are expected to |
9466 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
9467 | |
9468 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
9469 | The c\bch\bho\bow\bwn\bn() system call first appeared in Version 1 AT&T UNIX. Since |
9470 | Version 6 AT&T UNIX it supports changing the group as well, and in |
9471 | Version 7 AT&T UNIX _\bg_\br_\bo_\bu_\bp was made a separate argument. |
9472 | |
9473 | The f\bfc\bch\bho\bow\bwn\bn() system call first appeared in 4.1cBSD. |
9474 | |
9475 | The c\bch\bho\bow\bwn\bn() and f\bfc\bch\bho\bow\bwn\bn() system calls were changed to follow symbolic |
9476 | links in 4.4BSD; therefore, and for compatibility with AT&T System V |
9477 | Release 4 UNIX, the l\blc\bch\bho\bow\bwn\bn() system call was added to OpenBSD 2.1. |
9478 | |
9479 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() system call has been available since OpenBSD 5.0. |
9480 | |
9481 | N\bNA\bAM\bME\bE |
9482 | c\bch\bho\bow\bwn\bn, l\blc\bch\bho\bow\bwn\bn, f\bfc\bch\bho\bow\bwn\bna\bat\bt, f\bfc\bch\bho\bow\bwn\bn - change owner and group of a file or |
9483 | link |
9484 | |
9485 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9486 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
9487 | |
9488 | _\bi_\bn_\bt |
9489 | c\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
9490 | |
9491 | _\bi_\bn_\bt |
9492 | l\blc\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
9493 | |
9494 | _\bi_\bn_\bt |
9495 | f\bfc\bch\bho\bow\bwn\bn(_\bi_\bn_\bt _\bf_\bd, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
9496 | |
9497 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
9498 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
9499 | |
9500 | _\bi_\bn_\bt |
9501 | f\bfc\bch\bho\bow\bwn\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
9502 | |
9503 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
9504 | The owner ID and group ID of the file (or link) named by _\bp_\ba_\bt_\bh or |
9505 | referenced by _\bf_\bd is changed as specified by the arguments _\bo_\bw_\bn_\be_\br and |
9506 | _\bg_\br_\bo_\bu_\bp. The owner of a file may change the _\bg_\br_\bo_\bu_\bp to a group of which he |
9507 | or she is a member, but the change _\bo_\bw_\bn_\be_\br capability is restricted to the |
9508 | superuser. |
9509 | |
9510 | By default, c\bch\bho\bow\bwn\bn() clears the set-user-ID and set-group-ID bits on the |
9511 | file to prevent accidental or mischievous creation of set-user-ID and |
9512 | set-group-ID programs. This behaviour can be overridden by setting the |
9513 | sysctl(8) variable _\bf_\bs_\b._\bp_\bo_\bs_\bi_\bx_\b._\bs_\be_\bt_\bu_\bi_\bd to zero. |
9514 | |
9515 | l\blc\bch\bho\bow\bwn\bn() operates similarly to how c\bch\bho\bow\bwn\bn() operated on older systems, and |
9516 | does not follow symbolic links. It allows the owner and group of a |
9517 | symbolic link to be set. |
9518 | |
9519 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() function is equivalent to either the c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn() |
9520 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
9521 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose ownership is changed is |
9522 | determined relative to the directory associated with file descriptor _\bf_\bd |
9523 | instead of the current working directory. |
9524 | |
9525 | If f\bfc\bch\bho\bow\bwn\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
9526 | in the _\bf_\bd parameter, the current working directory is used and the |
9527 | behavior is identical to a call to c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn(), depending on |
9528 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
9529 | |
9530 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
9531 | values: |
9532 | |
9533 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
9534 | ownership of the symbolic link is changed. |
9535 | |
9536 | f\bfc\bch\bho\bow\bwn\bn() is particularly useful when used in conjunction with the file |
9537 | locking primitives (see flock(2)). |
9538 | |
9539 | One of the owner or group IDs may be left unchanged by specifying it as |
9540 | -1. |
9541 | |
9542 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
9543 | Upon successful completion, the value 0 is returned; otherwise the |
9544 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
9545 | error. |
9546 | |
9547 | E\bER\bRR\bRO\bOR\bRS\bS |
9548 | c\bch\bho\bow\bwn\bn(), l\blc\bch\bho\bow\bwn\bn(), and f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail and the file or link will be |
9549 | unchanged if: |
9550 | |
9551 | [ENOTDIR] A component of the path prefix is not a directory. |
9552 | |
9553 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
9554 | characters, or an entire pathname (including the |
9555 | terminating NUL) exceeded PATH_MAX bytes. |
9556 | |
9557 | [ENOENT] The named file does not exist. |
9558 | |
9559 | [EACCES] Search permission is denied for a component of the |
9560 | path prefix. |
9561 | |
9562 | [ELOOP] Too many symbolic links were encountered in |
9563 | translating the pathname. |
9564 | |
9565 | [EPERM] The effective user ID is not the superuser. |
9566 | |
9567 | [EROFS] The named file resides on a read-only file system. |
9568 | |
9569 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
9570 | space. |
9571 | |
9572 | [EIO] An I/O error occurred while reading from or writing to |
9573 | the file system. |
9574 | |
9575 | Additionally, f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail if: |
9576 | |
9577 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
9578 | AT_SYMLINK_NOFOLLOW. |
9579 | |
9580 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
9581 | argument is neither AT_FDCWD nor a valid file |
9582 | descriptor. |
9583 | |
9584 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
9585 | argument is a valid file descriptor but it does not |
9586 | reference a directory. |
9587 | |
9588 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
9589 | permission is denied for the directory which the _\bf_\bd |
9590 | file descriptor references. |
9591 | |
9592 | f\bfc\bch\bho\bow\bwn\bn() will fail if: |
9593 | |
9594 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
9595 | |
9596 | [EINVAL] _\bf_\bd refers to a socket, not a file. |
9597 | |
9598 | [EPERM] The effective user ID is not the superuser. |
9599 | |
9600 | [EROFS] The named file resides on a read-only file system. |
9601 | |
9602 | [EIO] An I/O error occurred while reading from or writing to |
9603 | the file system. |
9604 | |
9605 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
9606 | chgrp(1), chmod(2), flock(2), chown(8) |
9607 | |
9608 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
9609 | The c\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), and l\blc\bch\bho\bow\bwn\bn() functions are expected to |
9610 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
9611 | |
9612 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
9613 | The c\bch\bho\bow\bwn\bn() system call first appeared in Version 1 AT&T UNIX. Since |
9614 | Version 6 AT&T UNIX it supports changing the group as well, and in |
9615 | Version 7 AT&T UNIX _\bg_\br_\bo_\bu_\bp was made a separate argument. |
9616 | |
9617 | The f\bfc\bch\bho\bow\bwn\bn() system call first appeared in 4.1cBSD. |
9618 | |
9619 | The c\bch\bho\bow\bwn\bn() and f\bfc\bch\bho\bow\bwn\bn() system calls were changed to follow symbolic |
9620 | links in 4.4BSD; therefore, and for compatibility with AT&T System V |
9621 | Release 4 UNIX, the l\blc\bch\bho\bow\bwn\bn() system call was added to OpenBSD 2.1. |
9622 | |
9623 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() system call has been available since OpenBSD 5.0. |
9624 | |
9625 | N\bNA\bAM\bME\bE |
9626 | f\bfc\bcn\bnt\btl\bl - file control |
9627 | |
9628 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9629 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
9630 | |
9631 | _\bi_\bn_\bt |
9632 | f\bfc\bcn\bnt\btl\bl(_\bi_\bn_\bt _\bf_\bd, _\bi_\bn_\bt _\bc_\bm_\bd, _\b._\b._\b.); |
9633 | |
9634 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
9635 | The f\bfc\bcn\bnt\btl\bl() provides control over the properties of a file that is |
9636 | already open. The argument _\bf_\bd is a descriptor to be operated on by _\bc_\bm_\bd |
9637 | as described below. The third parameter is called _\ba_\br_\bg and is technically |
9638 | a pointer to _\bv_\bo_\bi_\bd, but is interpreted as an int by some commands, a |
9639 | pointer to a struct flock by others (see below), and ignored by the rest. |
9640 | |
9641 | The commands are: |
9642 | |
9643 | F_DUPFD Return a new descriptor as follows: |
9644 | |
9645 | +\b+\bo\bo Lowest numbered available descriptor greater than or |
9646 | equal to _\ba_\br_\bg (interpreted as an int). |
9647 | +\b+\bo\bo Same object references as the original descriptor. |
9648 | +\b+\bo\bo New descriptor shares the same file offset if the |
9649 | object was a file. |
9650 | +\b+\bo\bo Same access mode (read, write or read/write). |
9651 | +\b+\bo\bo Same file status flags (i.e., both file descriptors |
9652 | share the same file status flags). |
9653 | +\b+\bo\bo The close-on-exec flag associated with the new file |
9654 | descriptor is set to remain open across execve(2) |
9655 | calls. |
9656 | |
9657 | F_DUPFD_CLOEXEC Like F_DUPFD, but the FD_CLOEXEC flag associated with |
9658 | the new file descriptor is set, so the file descriptor |
9659 | is closed when execve(2) is called. |
9660 | |
9661 | F_GETFD Get the close-on-exec flag associated with the file |
9662 | descriptor _\bf_\bd as FD_CLOEXEC. If the returned value |
9663 | ANDed with FD_CLOEXEC is 0, the file will remain open |
9664 | across e\bex\bxe\bec\bc(), otherwise the file will be closed upon |
9665 | execution of e\bex\bxe\bec\bc() (_\ba_\br_\bg is ignored). |
9666 | |
9667 | F_SETFD Set the close-on-exec flag associated with _\bf_\bd to _\ba_\br_\bg, |
9668 | where _\ba_\br_\bg (interpreted as an int) is either 0 or |
9669 | FD_CLOEXEC, as described above. |
9670 | |
9671 | F_GETFL Get file status flags associated with the file |
9672 | descriptor _\bf_\bd, as described below (_\ba_\br_\bg is ignored). |
9673 | |
9674 | F_SETFL Set file status flags associated with the file |
9675 | descriptor _\bf_\bd to _\ba_\br_\bg (interpreted as an int). |
9676 | |
9677 | F_GETOWN Get the process ID or process group currently receiving |
9678 | SIGIO and SIGURG signals; process groups are returned as |
9679 | negative values (_\ba_\br_\bg is ignored). |
9680 | |
9681 | F_SETOWN Set the process or process group to receive SIGIO and |
9682 | SIGURG signals; process groups are specified by |
9683 | supplying _\ba_\br_\bg (interpreted as an int) as negative, |
9684 | otherwise _\ba_\br_\bg is taken as a process ID. |
9685 | |
9686 | The flags for the F_GETFL and F_SETFL commands are as follows: |
9687 | |
9688 | O_NONBLOCK Non-blocking I/O; if no data is available to a read(2) call, |
9689 | or if a write(2) operation would block, the read or write |
9690 | call returns -1 with the error EAGAIN. |
9691 | |
9692 | O_APPEND Force each write to append at the end of file; corresponds |
9693 | to the O_APPEND flag of open(2). |
9694 | |
9695 | O_ASYNC Enable the SIGIO signal to be sent to the process group when |
9696 | I/O is possible, e.g., upon availability of data to be read. |
9697 | |
9698 | O_SYNC Cause writes to be synchronous. Data will be written to the |
9699 | physical device instead of just being stored in the buffer |
9700 | cache; corresponds to the O_SYNC flag of open(2). |
9701 | |
9702 | Several commands are available for doing advisory file locking; they all |
9703 | operate on the following structure: |
9704 | |
9705 | struct flock { |
9706 | off_t l_start; /* starting offset */ |
9707 | off_t l_len; /* len = 0 means until end of file */ |
9708 | pid_t l_pid; /* lock owner */ |
9709 | short l_type; /* lock type: read/write, etc. */ |
9710 | short l_whence; /* type of l_start */ |
9711 | }; |
9712 | |
9713 | The commands available for advisory record locking are as follows: |
9714 | |
9715 | F_GETLK Get the first lock that blocks the lock description pointed to |
9716 | by the third argument, _\ba_\br_\bg, taken as a pointer to a _\bs_\bt_\br_\bu_\bc_\bt |
9717 | _\bf_\bl_\bo_\bc_\bk (see above). The information retrieved overwrites the |
9718 | information passed to f\bfc\bcn\bnt\btl\bl() in the _\bf_\bl_\bo_\bc_\bk structure. If no |
9719 | lock is found that would prevent this lock from being created, |
9720 | the structure is left unchanged by this function call except |
9721 | for the lock type which is set to F_UNLCK. |
9722 | |
9723 | F_SETLK Set or clear a file segment lock according to the lock |
9724 | description pointed to by the third argument, _\ba_\br_\bg, taken as a |
9725 | pointer to a _\bs_\bt_\br_\bu_\bc_\bt _\bf_\bl_\bo_\bc_\bk (see above). F_SETLK is used to |
9726 | establish shared (or read) locks (F_RDLCK) or exclusive (or |
9727 | write) locks (F_WRLCK), as well as remove either type of lock |
9728 | (F_UNLCK). If a shared or exclusive lock cannot be set, |
9729 | f\bfc\bcn\bnt\btl\bl() returns immediately with EAGAIN. |
9730 | |
9731 | F_SETLKW This command is the same as F_SETLK except that if a shared or |
9732 | exclusive lock is blocked by other locks, the process waits |
9733 | until the request can be satisfied. If a signal that is to be |
9734 | caught is received while f\bfc\bcn\bnt\btl\bl() is waiting for a region, the |
9735 | f\bfc\bcn\bnt\btl\bl() will be interrupted if the signal handler has not |
9736 | specified the SA_RESTART (see sigaction(2)). |
9737 | |
9738 | When a shared lock has been set on a segment of a file, other processes |
9739 | can set shared locks on that segment or a portion of it. A shared lock |
9740 | prevents any other process from setting an exclusive lock on any portion |
9741 | of the protected area. A request for a shared lock fails if the file |
9742 | descriptor was not opened with read access. |
9743 | |
9744 | An exclusive lock prevents any other process from setting a shared lock |
9745 | or an exclusive lock on any portion of the protected area. A request for |
9746 | an exclusive lock fails if the file was not opened with write access. |
9747 | |
9748 | The value of _\bl_\b__\bw_\bh_\be_\bn_\bc_\be is SEEK_SET, SEEK_CUR, or SEEK_END to indicate that |
9749 | the relative offset, _\bl_\b__\bs_\bt_\ba_\br_\bt bytes, will be measured from the start of |
9750 | the file, current position, or end of the file, respectively. The value |
9751 | of _\bl_\b__\bl_\be_\bn is the number of consecutive bytes to be locked. If _\bl_\b__\bl_\be_\bn is |
9752 | negative, the result is undefined. The _\bl_\b__\bp_\bi_\bd field is only used with |
9753 | F_GETLK to return the process ID of the process holding a blocking lock. |
9754 | After a successful F_GETLK request, the value of _\bl_\b__\bw_\bh_\be_\bn_\bc_\be is SEEK_SET. |
9755 | |
9756 | Locks may start and extend beyond the current end of a file, but may not |
9757 | start or extend before the beginning of the file. A lock is set to |
9758 | extend to the largest possible value of the file offset for that file if |
9759 | _\bl_\b__\bl_\be_\bn is set to zero. If _\bl_\b__\bw_\bh_\be_\bn_\bc_\be and _\bl_\b__\bs_\bt_\ba_\br_\bt point to the beginning of |
9760 | the file, and _\bl_\b__\bl_\be_\bn is zero, the entire file is locked. If an |
9761 | application wishes only to do entire file locking, the flock(2) system |
9762 | call is much more efficient. |
9763 | |
9764 | There is at most one type of lock set for each byte in the file. Before |
9765 | a successful return from an F_SETLK or an F_SETLKW request when the |
9766 | calling process has previously existing locks on bytes in the region |
9767 | specified by the request, the previous lock type for each byte in the |
9768 | specified region is replaced by the new lock type. As specified above |
9769 | under the descriptions of shared locks and exclusive locks, an F_SETLK or |
9770 | an F_SETLKW request fails or blocks respectively when another process has |
9771 | existing locks on bytes in the specified region and the type of any of |
9772 | those locks conflicts with the type specified in the request. |
9773 | |
9774 | This interface follows the completely stupid semantics of System V and |
9775 | IEEE Std 1003.1-1988 (``POSIX.1'') that require that all locks associated |
9776 | with a file for a given process are removed when _\ba_\bn_\by file descriptor for |
9777 | that file is closed by that process. This semantic means that |
9778 | applications must be aware of any files that a subroutine library may |
9779 | access. For example if an application for updating the password file |
9780 | locks the password file database while making the update, and then calls |
9781 | getpwnam(3) to retrieve a record, the lock will be lost because |
9782 | getpwnam(3) opens, reads, and closes the password database. The database |
9783 | close will release all locks that the process has associated with the |
9784 | database, even if the library routine never requested a lock on the |
9785 | database. Another minor semantic problem with this interface is that |
9786 | locks are not inherited by a child process created using the fork(2) |
9787 | function. The flock(2) interface has much more rational last close |
9788 | semantics and allows locks to be inherited by child processes. flock(2) |
9789 | is recommended for applications that want to ensure the integrity of |
9790 | their locks when using library routines or wish to pass locks to their |
9791 | children. Note that flock(2) and f\bfc\bcn\bnt\btl\bl() locks may be safely used |
9792 | concurrently. |
9793 | |
9794 | All locks associated with a file for a given process are removed when the |
9795 | process terminates. |
9796 | |
9797 | A potential for deadlock occurs if a process controlling a locked region |
9798 | is put to sleep by attempting to lock the locked region of another |
9799 | process. This implementation detects that sleeping until a locked region |
9800 | is unlocked would cause a deadlock and fails with an EDEADLK error. |
9801 | |
9802 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
9803 | Upon successful completion, the value returned depends on _\bc_\bm_\bd as follows: |
9804 | |
9805 | F_DUPFD A new file descriptor. |
9806 | |
9807 | F_DUPFD_CLOEXEC A new file descriptor. |
9808 | |
9809 | F_GETFD Value of flag (only the low-order bit is defined). |
9810 | |
9811 | F_GETFL Value of flags. |
9812 | |
9813 | F_GETOWN Value of file descriptor owner. |
9814 | |
9815 | other Value other than -1. |
9816 | |
9817 | Otherwise, a value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the |
9818 | error. |
9819 | |
9820 | E\bER\bRR\bRO\bOR\bRS\bS |
9821 | f\bfc\bcn\bnt\btl\bl() will fail if: |
9822 | |
9823 | [EAGAIN] The argument _\bc_\bm_\bd is F_SETLK, the type of lock (_\bl_\b__\bt_\by_\bp_\be) |
9824 | is a shared lock (F_RDLCK) or exclusive lock |
9825 | (F_WRLCK), and the segment of a file to be locked is |
9826 | already exclusive-locked by another process; or the |
9827 | type is an exclusive lock and some portion of the |
9828 | segment of a file to be locked is already shared- |
9829 | locked or exclusive-locked by another process. |
9830 | |
9831 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
9832 | |
9833 | The argument _\bc_\bm_\bd is F_SETLK or F_SETLKW, the type of |
9834 | lock (_\bl_\b__\bt_\by_\bp_\be) is a shared lock (F_RDLCK), and _\bf_\bd is |
9835 | not a valid file descriptor open for reading. |
9836 | |
9837 | The argument _\bc_\bm_\bd is F_SETLK or F_SETLKW, the type of |
9838 | lock (_\bl_\b__\bt_\by_\bp_\be) is an exclusive lock (F_WRLCK), and _\bf_\bd |
9839 | is not a valid file descriptor open for writing. |
9840 | |
9841 | [EDEADLK] The argument _\bc_\bm_\bd is F_SETLKW, and a deadlock condition |
9842 | was detected. |
9843 | |
9844 | [EINTR] The argument _\bc_\bm_\bd is invalid. |
9845 | |
9846 | The argument _\bc_\bm_\bd is F_SETLKW, and the function was |
9847 | interrupted by a signal. |
9848 | |
9849 | [EINVAL] _\bc_\bm_\bd is F_DUPFD and _\ba_\br_\bg is negative or greater than the |
9850 | maximum allowable number (see getdtablesize(3)). |
9851 | |
9852 | The argument _\bc_\bm_\bd is F_GETLK, F_SETLK, or F_SETLKW and |
9853 | the data to which _\ba_\br_\bg points is not valid, or _\bf_\bd |
9854 | refers to a file that does not support locking. |
9855 | |
9856 | [EMFILE] The argument _\bc_\bm_\bd is F_DUPFD and the maximum number of |
9857 | open file descriptors permitted for the process are |
9858 | already in use, or no file descriptors greater than or |
9859 | equal to _\ba_\br_\bg are available. |
9860 | |
9861 | [ENOLCK] The argument _\bc_\bm_\bd is F_SETLK or F_SETLKW, and |
9862 | satisfying the lock or unlock request would result in |
9863 | the number of locked regions in the system exceeding a |
9864 | system-imposed limit. |
9865 | |
9866 | [ESRCH] _\bc_\bm_\bd is F_SETOWN and the process ID given in _\ba_\br_\bg is not |
9867 | in use. |
9868 | |
9869 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
9870 | close(2), execve(2), flock(2), open(2), sigaction(2), getdtablesize(3) |
9871 | |
9872 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
9873 | The f\bfc\bcn\bnt\btl\bl() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
9874 | |
9875 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
9876 | The f\bfc\bcn\bnt\btl\bl() function call appeared in 4.2BSD. |
9877 | |
9878 | N\bNA\bAM\bME\bE |
9879 | f\bfs\bsy\byn\bnc\bc, f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc - synchronize a file's in-core state with that on disk |
9880 | |
9881 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9882 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
9883 | |
9884 | _\bi_\bn_\bt |
9885 | f\bfs\bsy\byn\bnc\bc(_\bi_\bn_\bt _\bf_\bd); |
9886 | |
9887 | _\bi_\bn_\bt |
9888 | f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc(_\bi_\bn_\bt _\bf_\bd); |
9889 | |
9890 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
9891 | The f\bfs\bsy\byn\bnc\bc() function causes all modified data and attributes of _\bf_\bd to be |
9892 | moved to a permanent storage device. This normally results in all in- |
9893 | core modified copies of buffers for the associated file to be written to |
9894 | a disk. |
9895 | |
9896 | The f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() function is similar to f\bfs\bsy\byn\bnc\bc() except that it only |
9897 | guarantees modified data (and metadata necessary to read that data) is |
9898 | committed to storage. Other file modifications may be left |
9899 | unsynchronized. |
9900 | |
9901 | f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() should be used by programs that require a file to |
9902 | be in a known state, for example, in building a simple transaction |
9903 | facility. |
9904 | |
9905 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
9906 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions return the value 0 if successful; |
9907 | otherwise the value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
9908 | to indicate the error. |
9909 | |
9910 | E\bER\bRR\bRO\bOR\bRS\bS |
9911 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions fail if: |
9912 | |
9913 | [EBADF] _\bf_\bd is not a valid descriptor. |
9914 | |
9915 | [EINVAL] _\bf_\bd does not refer to a file which can be synchronized. |
9916 | |
9917 | [EIO] An I/O error occurred while reading from or writing to |
9918 | the file system. |
9919 | |
9920 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
9921 | sync(2), sync(8) |
9922 | |
9923 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
9924 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions conform to IEEE Std 1003.1-2008 |
9925 | (``POSIX.1''). |
9926 | |
9927 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
9928 | The f\bfs\bsy\byn\bnc\bc() system call first appeared in 4.1cBSD, and the f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() |
9929 | function has been available since OpenBSD 5.4. |
9930 | |
9931 | B\bBU\bUG\bGS\bS |
9932 | The f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() function is currently a wrapper around f\bfs\bsy\byn\bnc\bc(), so it |
9933 | synchronizes more state than necessary. |
9934 | |
9935 | N\bNA\bAM\bME\bE |
9936 | f\bfh\bho\bop\bpe\ben\bn, f\bfh\bhs\bst\bta\bat\bt, f\bfh\bhs\bst\bta\bat\btf\bfs\bs - access file via file handle |
9937 | |
9938 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9939 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
9940 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
9941 | |
9942 | _\bi_\bn_\bt |
9943 | f\bfh\bho\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
9944 | |
9945 | _\bi_\bn_\bt |
9946 | f\bfh\bhs\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
9947 | |
9948 | _\bi_\bn_\bt |
9949 | f\bfh\bhs\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
9950 | |
9951 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
9952 | These functions provide a means to access a file given the file handle |
9953 | _\bf_\bh_\bp. As this method bypasses directory access restrictions, these calls |
9954 | are restricted to the superuser. |
9955 | |
9956 | f\bfh\bho\bop\bpe\ben\bn() opens the file referenced by _\bf_\bh_\bp for reading and/or writing as |
9957 | specified by the argument _\bf_\bl_\ba_\bg_\bs and returns the file descriptor to the |
9958 | calling process. The _\bf_\bl_\ba_\bg_\bs are specified by _\bo_\br'ing together the flags |
9959 | used for the open(2) call. All said flags are valid except for O_CREAT. |
9960 | |
9961 | f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() provide the functionality of the fstat(2) and |
9962 | fstatfs(2) calls except that they return information for the file |
9963 | referred to by _\bf_\bh_\bp rather than an open file. |
9964 | |
9965 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
9966 | Upon successful completion, f\bfh\bho\bop\bpe\ben\bn() returns the file descriptor for the |
9967 | opened file, while f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() return 0. Otherwise, -1 is |
9968 | returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
9969 | |
9970 | E\bER\bRR\bRO\bOR\bRS\bS |
9971 | In addition to the errors returned by open(2), fstat(2), and fstatfs(2) |
9972 | respectively, f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() will return |
9973 | |
9974 | [EINVAL] Calling f\bfh\bho\bop\bpe\ben\bn() with O_CREAT set. |
9975 | |
9976 | [ESTALE] The file handle _\bf_\bh_\bp is no longer valid. |
9977 | |
9978 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
9979 | fstat(2), fstatfs(2), getfh(2), open(2) |
9980 | |
9981 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
9982 | The f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() functions first appeared in |
9983 | NetBSD 1.5. |
9984 | |
9985 | N\bNA\bAM\bME\bE |
9986 | f\bfh\bho\bop\bpe\ben\bn, f\bfh\bhs\bst\bta\bat\bt, f\bfh\bhs\bst\bta\bat\btf\bfs\bs - access file via file handle |
9987 | |
9988 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
9989 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
9990 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
9991 | |
9992 | _\bi_\bn_\bt |
9993 | f\bfh\bho\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
9994 | |
9995 | _\bi_\bn_\bt |
9996 | f\bfh\bhs\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
9997 | |
9998 | _\bi_\bn_\bt |
9999 | f\bfh\bhs\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
10000 | |
10001 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10002 | These functions provide a means to access a file given the file handle |
10003 | _\bf_\bh_\bp. As this method bypasses directory access restrictions, these calls |
10004 | are restricted to the superuser. |
10005 | |
10006 | f\bfh\bho\bop\bpe\ben\bn() opens the file referenced by _\bf_\bh_\bp for reading and/or writing as |
10007 | specified by the argument _\bf_\bl_\ba_\bg_\bs and returns the file descriptor to the |
10008 | calling process. The _\bf_\bl_\ba_\bg_\bs are specified by _\bo_\br'ing together the flags |
10009 | used for the open(2) call. All said flags are valid except for O_CREAT. |
10010 | |
10011 | f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() provide the functionality of the fstat(2) and |
10012 | fstatfs(2) calls except that they return information for the file |
10013 | referred to by _\bf_\bh_\bp rather than an open file. |
10014 | |
10015 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10016 | Upon successful completion, f\bfh\bho\bop\bpe\ben\bn() returns the file descriptor for the |
10017 | opened file, while f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() return 0. Otherwise, -1 is |
10018 | returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
10019 | |
10020 | E\bER\bRR\bRO\bOR\bRS\bS |
10021 | In addition to the errors returned by open(2), fstat(2), and fstatfs(2) |
10022 | respectively, f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() will return |
10023 | |
10024 | [EINVAL] Calling f\bfh\bho\bop\bpe\ben\bn() with O_CREAT set. |
10025 | |
10026 | [ESTALE] The file handle _\bf_\bh_\bp is no longer valid. |
10027 | |
10028 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
10029 | fstat(2), fstatfs(2), getfh(2), open(2) |
10030 | |
10031 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
10032 | The f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() functions first appeared in |
10033 | NetBSD 1.5. |
10034 | |
10035 | N\bNA\bAM\bME\bE |
10036 | f\bfh\bho\bop\bpe\ben\bn, f\bfh\bhs\bst\bta\bat\bt, f\bfh\bhs\bst\bta\bat\btf\bfs\bs - access file via file handle |
10037 | |
10038 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
10039 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
10040 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
10041 | |
10042 | _\bi_\bn_\bt |
10043 | f\bfh\bho\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
10044 | |
10045 | _\bi_\bn_\bt |
10046 | f\bfh\bhs\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
10047 | |
10048 | _\bi_\bn_\bt |
10049 | f\bfh\bhs\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
10050 | |
10051 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10052 | These functions provide a means to access a file given the file handle |
10053 | _\bf_\bh_\bp. As this method bypasses directory access restrictions, these calls |
10054 | are restricted to the superuser. |
10055 | |
10056 | f\bfh\bho\bop\bpe\ben\bn() opens the file referenced by _\bf_\bh_\bp for reading and/or writing as |
10057 | specified by the argument _\bf_\bl_\ba_\bg_\bs and returns the file descriptor to the |
10058 | calling process. The _\bf_\bl_\ba_\bg_\bs are specified by _\bo_\br'ing together the flags |
10059 | used for the open(2) call. All said flags are valid except for O_CREAT. |
10060 | |
10061 | f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() provide the functionality of the fstat(2) and |
10062 | fstatfs(2) calls except that they return information for the file |
10063 | referred to by _\bf_\bh_\bp rather than an open file. |
10064 | |
10065 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10066 | Upon successful completion, f\bfh\bho\bop\bpe\ben\bn() returns the file descriptor for the |
10067 | opened file, while f\bfh\bhs\bst\bta\bat\bt() and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() return 0. Otherwise, -1 is |
10068 | returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
10069 | |
10070 | E\bER\bRR\bRO\bOR\bRS\bS |
10071 | In addition to the errors returned by open(2), fstat(2), and fstatfs(2) |
10072 | respectively, f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() will return |
10073 | |
10074 | [EINVAL] Calling f\bfh\bho\bop\bpe\ben\bn() with O_CREAT set. |
10075 | |
10076 | [ESTALE] The file handle _\bf_\bh_\bp is no longer valid. |
10077 | |
10078 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
10079 | fstat(2), fstatfs(2), getfh(2), open(2) |
10080 | |
10081 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
10082 | The f\bfh\bho\bop\bpe\ben\bn(), f\bfh\bhs\bst\bta\bat\bt(), and f\bfh\bhs\bst\bta\bat\btf\bfs\bs() functions first appeared in |
10083 | NetBSD 1.5. |
10084 | |
10085 | N\bNA\bAM\bME\bE |
10086 | f\bfl\blo\boc\bck\bk - apply or remove an advisory lock on an open file |
10087 | |
10088 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
10089 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
10090 | |
10091 | _\bi_\bn_\bt |
10092 | f\bfl\blo\boc\bck\bk(_\bi_\bn_\bt _\bf_\bd, _\bi_\bn_\bt _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn); |
10093 | |
10094 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10095 | f\bfl\blo\boc\bck\bk() applies or removes an _\ba_\bd_\bv_\bi_\bs_\bo_\br_\by lock on the file associated with |
10096 | the file descriptor _\bf_\bd. The _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn argument is one of: |
10097 | |
10098 | LOCK_SH Apply a shared lock. |
10099 | LOCK_EX Apply an exclusive lock. |
10100 | LOCK_UN Remove an existing lock. |
10101 | |
10102 | LOCK_SH and LOCK_EX may be combined with the optional LOCK_NB for |
10103 | nonblocking mode. |
10104 | |
10105 | Advisory locks allow cooperating processes to perform consistent |
10106 | operations on files, but do not guarantee consistency (i.e., processes |
10107 | may still access files without using advisory locks possibly resulting in |
10108 | inconsistencies). |
10109 | |
10110 | The locking mechanism allows two types of locks: _\bs_\bh_\ba_\br_\be_\bd locks and |
10111 | _\be_\bx_\bc_\bl_\bu_\bs_\bi_\bv_\be locks. At any time multiple shared locks may be applied to a |
10112 | file, but at no time are multiple exclusive, or both shared and |
10113 | exclusive, locks allowed simultaneously on a file. |
10114 | |
10115 | A shared lock may be _\bu_\bp_\bg_\br_\ba_\bd_\be_\bd to an exclusive lock, and vice versa, |
10116 | simply by specifying the appropriate lock type; this results in the |
10117 | previous lock being released and the new lock applied (possibly after |
10118 | other processes have gained and released the lock). |
10119 | |
10120 | Requesting a lock on an object that is already locked normally causes the |
10121 | caller to be blocked until the lock may be acquired. If _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn is the |
10122 | bitwise OR of LOCK_NB and LOCK_SH or LOCK_EX, then this will not happen; |
10123 | instead the call will fail and the error EWOULDBLOCK will be returned. |
10124 | |
10125 | N\bNO\bOT\bTE\bES\bS |
10126 | Locks are on files, not file descriptors. That is, file descriptors |
10127 | duplicated through dup(2) or fork(2) do not result in multiple instances |
10128 | of a lock, but rather multiple references to a single lock. If a process |
10129 | holding a lock on a file forks and the child explicitly unlocks the file, |
10130 | the parent will lose its lock. |
10131 | |
10132 | Processes blocked awaiting a lock may be awakened by signals. |
10133 | |
10134 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10135 | Upon successful completion, the value 0 is returned; otherwise the |
10136 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
10137 | error. |
10138 | |
10139 | E\bER\bRR\bRO\bOR\bRS\bS |
10140 | The f\bfl\blo\boc\bck\bk() call fails if: |
10141 | |
10142 | [EWOULDBLOCK] The file is locked and the LOCK_NB option was |
10143 | specified. |
10144 | |
10145 | [EBADF] The argument _\bf_\bd is an invalid descriptor. |
10146 | |
10147 | [EINVAL] The argument _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn has an invalid value. |
10148 | |
10149 | [EOPNOTSUPP] The referenced descriptor is not of the correct type. |
10150 | |
10151 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
10152 | close(2), dup(2), execve(2), fcntl(2), fork(2), open(2) |
10153 | |
10154 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
10155 | The f\bfl\blo\boc\bck\bk() system call first appeared in 4.1cBSD. |
10156 | |
10157 | N\bNA\bAM\bME\bE |
10158 | f\bfo\bor\brk\bk - create a new process |
10159 | |
10160 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
10161 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
10162 | |
10163 | _\bp_\bi_\bd_\b__\bt |
10164 | f\bfo\bor\brk\bk(_\bv_\bo_\bi_\bd); |
10165 | |
10166 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10167 | f\bfo\bor\brk\bk() causes creation of a new process. The new process (child process) |
10168 | is an exact copy of the calling process (parent process) except for the |
10169 | following: |
10170 | |
10171 | +\b+\bo\bo The child process has a unique process ID, which also does not |
10172 | match any existing process group ID. |
10173 | |
10174 | +\b+\bo\bo The child process has a different parent process ID (i.e., the |
10175 | process ID of the parent process). |
10176 | |
10177 | +\b+\bo\bo The child process has a single thread. |
10178 | |
10179 | +\b+\bo\bo The child process has its own copy of the parent's descriptors. |
10180 | These descriptors reference the same underlying objects, so |
10181 | that, for instance, file pointers in file objects are shared |
10182 | between the child and the parent, so that an lseek(2) on a |
10183 | descriptor in the child process can affect a subsequent read(2) |
10184 | or write(2) by the parent. This descriptor copying is also |
10185 | used by the shell to establish standard input and output for |
10186 | newly created processes as well as to set up pipes. |
10187 | |
10188 | +\b+\bo\bo The child process has no fcntl(2)-style file locks. |
10189 | |
10190 | +\b+\bo\bo The child process' resource utilizations are set to 0; see |
10191 | getrusage(2). |
10192 | |
10193 | +\b+\bo\bo All interval timers are cleared; see setitimer(2). |
10194 | |
10195 | +\b+\bo\bo The child process' semaphore undo values are set to 0; see |
10196 | semop(2). |
10197 | |
10198 | +\b+\bo\bo The child process' pending signals set is empty. |
10199 | |
10200 | +\b+\bo\bo The child process has no memory locks; see mlock(2) and |
10201 | mlockall(2). |
10202 | |
10203 | In general, the child process should call _exit(2) rather than exit(3). |
10204 | Otherwise, any stdio buffers that exist both in the parent and child will |
10205 | be flushed twice. Similarly, _exit(2) should be used to prevent |
10206 | atexit(3) routines from being called twice (once in the parent and once |
10207 | in the child). |
10208 | |
10209 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10210 | Upon successful completion, f\bfo\bor\brk\bk() returns a value of 0 to the child |
10211 | process and returns the process ID of the child process to the parent |
10212 | process. Otherwise, a value of -1 is returned to the parent process, no |
10213 | child process is created, and the global variable _\be_\br_\br_\bn_\bo is set to |
10214 | indicate the error. |
10215 | |
10216 | E\bER\bRR\bRO\bOR\bRS\bS |
10217 | f\bfo\bor\brk\bk() will fail and no child process will be created if: |
10218 | |
10219 | [EAGAIN] The system-imposed limits on the total number of processes or |
10220 | total number of threads under execution would be exceeded. |
10221 | These limits are configuration dependent. |
10222 | |
10223 | [EAGAIN] The limit RLIMIT_NPROC on the total number of processes under |
10224 | execution by the user ID would be exceeded. |
10225 | |
10226 | [ENOMEM] There is insufficient swap space for the new process. |
10227 | |
10228 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
10229 | execve(2), getrusage(2), wait(2) |
10230 | |
10231 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
10232 | The f\bfo\bor\brk\bk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
10233 | |
10234 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
10235 | The f\bfo\bor\brk\bk() system call first appeared in Version 1 AT&T UNIX. |
10236 | |
10237 | N\bNA\bAM\bME\bE |
10238 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf, f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf - get configurable pathname variables |
10239 | |
10240 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
10241 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
10242 | |
10243 | _\bl_\bo_\bn_\bg |
10244 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bn_\ba_\bm_\be); |
10245 | |
10246 | _\bl_\bo_\bn_\bg |
10247 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf(_\bi_\bn_\bt _\bf_\bd, _\bi_\bn_\bt _\bn_\ba_\bm_\be); |
10248 | |
10249 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10250 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf() and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf() functions provide a method for |
10251 | applications to determine the current value of a configurable system |
10252 | limit or option variable associated with a pathname or file descriptor. |
10253 | |
10254 | For p\bpa\bat\bth\bhc\bco\bon\bnf\bf, the _\bp_\ba_\bt_\bh argument is the name of a file or directory. For |
10255 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf, the _\bf_\bd argument is an open file descriptor. The _\bn_\ba_\bm_\be argument |
10256 | specifies the system variable to be queried. Symbolic constants for each |
10257 | name value are found in the include file <_\bu_\bn_\bi_\bs_\bt_\bd_\b._\bh>. |
10258 | |
10259 | The available values are as follows: |
10260 | |
10261 | _PC_LINK_MAX |
10262 | The maximum file link count. |
10263 | |
10264 | _PC_MAX_CANON |
10265 | The maximum number of bytes in a terminal canonical input line. |
10266 | |
10267 | _PC_MAX_INPUT |
10268 | The maximum number of bytes for which space is available in a |
10269 | terminal input queue. |
10270 | |
10271 | _PC_NAME_MAX |
10272 | The maximum number of bytes in a file name. |
10273 | |
10274 | _PC_PATH_MAX |
10275 | The maximum number of bytes in a pathname. |
10276 | |
10277 | _PC_PIPE_BUF |
10278 | The maximum number of bytes which will be written atomically to a |
10279 | pipe. |
10280 | |
10281 | _PC_CHOWN_RESTRICTED |
10282 | Returns 1 if appropriate privileges are required for the chown(2) |
10283 | system call, otherwise 0. IEEE Std 1003.1-2001 (``POSIX.1'') |
10284 | requires appropriate privilege in all cases, but this behavior |
10285 | was optional in prior editions of the standard. |
10286 | |
10287 | _PC_NO_TRUNC |
10288 | Returns 1 if attempts to use pathname components longer than |
10289 | {NAME_MAX} will result in an [ENAMETOOLONG] error; otherwise, |
10290 | such components will be truncated to {NAME_MAX}. IEEE Std |
10291 | 1003.1-2001 (``POSIX.1'') requires the error in all cases, but |
10292 | this behavior was optional in prior editions of the standard, and |
10293 | some non-POSIX-compliant file systems do not support this |
10294 | behavior. |
10295 | |
10296 | _PC_VDISABLE |
10297 | Returns the terminal character disabling value. |
10298 | |
10299 | _PC_2_SYMLINKS |
10300 | Returns 1 if the filesystem supports the creation of symbolic |
10301 | links within the specified directory; the meaning of |
10302 | _PC_2_SYMLINKS is unspecified for non-directory files. |
10303 | |
10304 | _PC_ALLOC_SIZE_MIN |
10305 | Minimum number of bytes of storage allocated for any portion of a |
10306 | file. |
10307 | |
10308 | _PC_ASYNC_IO |
10309 | Returns 1 if asynchronous I/O is supported, otherwise 0. |
10310 | |
10311 | _PC_FILESIZEBITS |
10312 | Number of bits needed to represent the maximum file size. |
10313 | |
10314 | _PC_PRIO_IO |
10315 | Returns 1 if prioritized I/O is supported, otherwise 0. |
10316 | |
10317 | _PC_REC_INCR_XFER_SIZE |
10318 | Recommended increment for file transfer sizes between |
10319 | _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE. |
10320 | |
10321 | _PC_REC_MAX_XFER_SIZE |
10322 | Maximum recommended file transfer size. |
10323 | |
10324 | _PC_REC_MIN_XFER_SIZE |
10325 | Minimum recommended file transfer size. |
10326 | |
10327 | _PC_REC_XFER_ALIGN |
10328 | Recommended file transfer buffer alignment. |
10329 | |
10330 | _PC_SYMLINK_MAX |
10331 | Maximum number of bytes in a symbolic link. |
10332 | |
10333 | _PC_SYNC_IO |
10334 | Returns 1 if synchronized I/O is supported, otherwise 0. |
10335 | |
10336 | _PC_TIMESTAMP_RESOLUTION |
10337 | The resolution in nanoseconds of file timestamps. |
10338 | |
10339 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10340 | If the call to p\bpa\bat\bth\bhc\bco\bon\bnf\bf or f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf is not successful, -1 is returned |
10341 | and _\be_\br_\br_\bn_\bo is set appropriately. Otherwise, if the variable is associated |
10342 | with functionality that does not have a limit in the system, -1 is |
10343 | returned and _\be_\br_\br_\bn_\bo is not modified. Otherwise, the current variable |
10344 | value is returned. |
10345 | |
10346 | E\bER\bRR\bRO\bOR\bRS\bS |
10347 | If any of the following conditions occur, the p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf |
10348 | functions shall return -1 and set _\be_\br_\br_\bn_\bo to the corresponding value. |
10349 | |
10350 | [EINVAL] The value of the _\bn_\ba_\bm_\be argument is invalid. |
10351 | |
10352 | [EINVAL] The implementation does not support an association of |
10353 | the variable name with the associated file. |
10354 | |
10355 | [EIO] An I/O error occurred while reading from the file |
10356 | system. |
10357 | |
10358 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf() will fail if: |
10359 | |
10360 | [ENOTDIR] A component of the path prefix is not a directory. |
10361 | |
10362 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters |
10363 | (but see _PC_NO_TRUNC above), or an entire pathname |
10364 | (including the terminating NUL) exceeded PATH_MAX |
10365 | bytes. |
10366 | |
10367 | [ENOENT] The named file does not exist. |
10368 | |
10369 | [EACCES] Search permission is denied for a component of the |
10370 | path prefix. |
10371 | |
10372 | [ELOOP] Too many symbolic links were encountered in |
10373 | translating the pathname. |
10374 | |
10375 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
10376 | space. |
10377 | |
10378 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf() will fail if: |
10379 | |
10380 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
10381 | |
10382 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
10383 | sysconf(3), sysctl(3) |
10384 | |
10385 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
10386 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf functions conform to IEEE Std 1003.1-2008 |
10387 | (``POSIX.1''). |
10388 | |
10389 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
10390 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf functions first appeared in 4.4BSD. |
10391 | |
10392 | N\bNA\bAM\bME\bE |
10393 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
10394 | |
10395 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
10396 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
10397 | |
10398 | _\bi_\bn_\bt |
10399 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
10400 | |
10401 | _\bi_\bn_\bt |
10402 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
10403 | |
10404 | _\bi_\bn_\bt |
10405 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
10406 | |
10407 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
10408 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
10409 | |
10410 | _\bi_\bn_\bt |
10411 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
10412 | |
10413 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10414 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
10415 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
10416 | required, but all directories listed in the path name leading to the file |
10417 | must be searchable. |
10418 | |
10419 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
10420 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
10421 | itself, not the file the link references. |
10422 | |
10423 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
10424 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
10425 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
10426 | determined relative to the directory associated with file descriptor _\bf_\bd |
10427 | instead of the current working directory. |
10428 | |
10429 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
10430 | in the _\bf_\bd parameter, the current working directory is used and the |
10431 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
10432 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
10433 | |
10434 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
10435 | values: |
10436 | |
10437 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
10438 | of the symbolic link is returned. |
10439 | |
10440 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
10441 | known by the file descriptor _\bf_\bd. |
10442 | |
10443 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
10444 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
10445 | concerning the file. |
10446 | |
10447 | struct stat { |
10448 | dev_t st_dev; /* inode's device */ |
10449 | ino_t st_ino; /* inode's number */ |
10450 | mode_t st_mode; /* inode protection mode */ |
10451 | nlink_t st_nlink; /* number of hard links */ |
10452 | uid_t st_uid; /* user ID of the file's owner */ |
10453 | gid_t st_gid; /* group ID of the file's group */ |
10454 | dev_t st_rdev; /* device type */ |
10455 | struct timespec st_atim; /* time of last access */ |
10456 | struct timespec st_mtim; /* time of last data modification */ |
10457 | struct timespec st_ctim; /* time of last file status change */ |
10458 | off_t st_size; /* file size, in bytes */ |
10459 | blkcnt_t st_blocks; /* blocks allocated for file */ |
10460 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
10461 | u_int32_t st_flags; /* user defined flags for file */ |
10462 | u_int32_t st_gen; /* file generation number */ |
10463 | }; |
10464 | |
10465 | The time-related fields of struct stat are represented in struct timespec |
10466 | format, which has nanosecond precision. However, the actual precision is |
10467 | generally limited by the file system holding the file. The fields are as |
10468 | follows: |
10469 | |
10470 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
10471 | system object was created and updated by the utimes(2) and |
10472 | read(2) system calls. |
10473 | |
10474 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
10475 | truncate(2), utimes(2), and write(2) system calls. For |
10476 | directories, changed by any system call that alters which |
10477 | files are in the directory, such as the unlink(2), rename(2), |
10478 | mkdir(2), and symlink(2) system calls. |
10479 | |
10480 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
10481 | modification). Changed by the chmod(2), chown(2), link(2), |
10482 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
10483 | |
10484 | In addition, all the time fields are set to the current time when a file |
10485 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
10486 | open(2), and symlink(2) system calls. |
10487 | |
10488 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
10489 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
10490 | respective struct timespec member. Deprecated macros are also provided |
10491 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
10492 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
10493 | |
10494 | The size-related fields of the struct stat are as follows: |
10495 | |
10496 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
10497 | |
10498 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
10499 | 512-byte units. As short symbolic links are stored in the |
10500 | inode, this number may be zero. |
10501 | |
10502 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
10503 | |
10504 | #define S_IFMT 0170000 /* type of file mask */ |
10505 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
10506 | #define S_IFCHR 0020000 /* character special */ |
10507 | #define S_IFDIR 0040000 /* directory */ |
10508 | #define S_IFBLK 0060000 /* block special */ |
10509 | #define S_IFREG 0100000 /* regular */ |
10510 | #define S_IFLNK 0120000 /* symbolic link */ |
10511 | #define S_IFSOCK 0140000 /* socket */ |
10512 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
10513 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
10514 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
10515 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
10516 | #define S_IRUSR 0000400 /* R for owner */ |
10517 | #define S_IWUSR 0000200 /* W for owner */ |
10518 | #define S_IXUSR 0000100 /* X for owner */ |
10519 | #define S_IRWXG 0000070 /* RWX mask for group */ |
10520 | #define S_IRGRP 0000040 /* R for group */ |
10521 | #define S_IWGRP 0000020 /* W for group */ |
10522 | #define S_IXGRP 0000010 /* X for group */ |
10523 | #define S_IRWXO 0000007 /* RWX mask for other */ |
10524 | #define S_IROTH 0000004 /* R for other */ |
10525 | #define S_IWOTH 0000002 /* W for other */ |
10526 | #define S_IXOTH 0000001 /* X for other */ |
10527 | |
10528 | The following macros test a file's type. If the file is of that type, a |
10529 | non-zero value is returned; otherwise, 0 is returned. |
10530 | |
10531 | S_ISBLK(st_mode m) /* block special */ |
10532 | S_ISCHR(st_mode m) /* char special */ |
10533 | S_ISDIR(st_mode m) /* directory */ |
10534 | S_ISFIFO(st_mode m) /* fifo */ |
10535 | S_ISLNK(st_mode m) /* symbolic link */ |
10536 | S_ISREG(st_mode m) /* regular file */ |
10537 | S_ISSOCK(st_mode m) /* socket */ |
10538 | |
10539 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
10540 | |
10541 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10542 | Upon successful completion, the value 0 is returned; otherwise the |
10543 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
10544 | error. |
10545 | |
10546 | E\bER\bRR\bRO\bOR\bRS\bS |
10547 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
10548 | |
10549 | [ENOTDIR] A component of the path prefix is not a directory. |
10550 | |
10551 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
10552 | characters, or an entire pathname (including the |
10553 | terminating NUL) exceeded PATH_MAX bytes. |
10554 | |
10555 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
10556 | empty path. |
10557 | |
10558 | [EACCES] Search permission is denied for a component of the |
10559 | path prefix. |
10560 | |
10561 | [ELOOP] Too many symbolic links were encountered in |
10562 | translating the pathname. |
10563 | |
10564 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
10565 | |
10566 | [EIO] An I/O error occurred while reading from or writing to |
10567 | the file system. |
10568 | |
10569 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
10570 | |
10571 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
10572 | AT_SYMLINK_NOFOLLOW. |
10573 | |
10574 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
10575 | argument is neither AT_FDCWD nor a valid file |
10576 | descriptor. |
10577 | |
10578 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
10579 | argument is a valid file descriptor but it does not |
10580 | reference a directory. |
10581 | |
10582 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
10583 | permission is denied for the directory which the _\bf_\bd |
10584 | file descriptor references. |
10585 | |
10586 | f\bfs\bst\bta\bat\bt() will fail if: |
10587 | |
10588 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
10589 | |
10590 | [EFAULT] _\bs_\bb points to an invalid address. |
10591 | |
10592 | [EIO] An I/O error occurred while reading from the file |
10593 | system. |
10594 | |
10595 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
10596 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
10597 | |
10598 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
10599 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
10600 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
10601 | |
10602 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
10603 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
10604 | |
10605 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
10606 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
10607 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
10608 | in Version 7 AT&T UNIX. |
10609 | |
10610 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
10611 | appeared in OpenBSD 5.0. |
10612 | |
10613 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
10614 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
10615 | |
10616 | Certain programs written when the timestamps were just of type time_t |
10617 | assumed that the members were consecutive (and could therefore be treated |
10618 | as an array and have their address passed directly to utime(3)). The |
10619 | transition to timestamps of type struct timespec broke them irrevocably. |
10620 | |
10621 | B\bBU\bUG\bGS\bS |
10622 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
10623 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
10624 | the time fields. |
10625 | |
10626 | N\bNA\bAM\bME\bE |
10627 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
10628 | |
10629 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
10630 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
10631 | |
10632 | _\bi_\bn_\bt |
10633 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
10634 | |
10635 | _\bi_\bn_\bt |
10636 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
10637 | |
10638 | _\bi_\bn_\bt |
10639 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
10640 | |
10641 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
10642 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
10643 | |
10644 | _\bi_\bn_\bt |
10645 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
10646 | |
10647 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10648 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
10649 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
10650 | required, but all directories listed in the path name leading to the file |
10651 | must be searchable. |
10652 | |
10653 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
10654 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
10655 | itself, not the file the link references. |
10656 | |
10657 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
10658 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
10659 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
10660 | determined relative to the directory associated with file descriptor _\bf_\bd |
10661 | instead of the current working directory. |
10662 | |
10663 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
10664 | in the _\bf_\bd parameter, the current working directory is used and the |
10665 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
10666 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
10667 | |
10668 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
10669 | values: |
10670 | |
10671 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
10672 | of the symbolic link is returned. |
10673 | |
10674 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
10675 | known by the file descriptor _\bf_\bd. |
10676 | |
10677 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
10678 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
10679 | concerning the file. |
10680 | |
10681 | struct stat { |
10682 | dev_t st_dev; /* inode's device */ |
10683 | ino_t st_ino; /* inode's number */ |
10684 | mode_t st_mode; /* inode protection mode */ |
10685 | nlink_t st_nlink; /* number of hard links */ |
10686 | uid_t st_uid; /* user ID of the file's owner */ |
10687 | gid_t st_gid; /* group ID of the file's group */ |
10688 | dev_t st_rdev; /* device type */ |
10689 | struct timespec st_atim; /* time of last access */ |
10690 | struct timespec st_mtim; /* time of last data modification */ |
10691 | struct timespec st_ctim; /* time of last file status change */ |
10692 | off_t st_size; /* file size, in bytes */ |
10693 | blkcnt_t st_blocks; /* blocks allocated for file */ |
10694 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
10695 | u_int32_t st_flags; /* user defined flags for file */ |
10696 | u_int32_t st_gen; /* file generation number */ |
10697 | }; |
10698 | |
10699 | The time-related fields of struct stat are represented in struct timespec |
10700 | format, which has nanosecond precision. However, the actual precision is |
10701 | generally limited by the file system holding the file. The fields are as |
10702 | follows: |
10703 | |
10704 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
10705 | system object was created and updated by the utimes(2) and |
10706 | read(2) system calls. |
10707 | |
10708 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
10709 | truncate(2), utimes(2), and write(2) system calls. For |
10710 | directories, changed by any system call that alters which |
10711 | files are in the directory, such as the unlink(2), rename(2), |
10712 | mkdir(2), and symlink(2) system calls. |
10713 | |
10714 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
10715 | modification). Changed by the chmod(2), chown(2), link(2), |
10716 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
10717 | |
10718 | In addition, all the time fields are set to the current time when a file |
10719 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
10720 | open(2), and symlink(2) system calls. |
10721 | |
10722 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
10723 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
10724 | respective struct timespec member. Deprecated macros are also provided |
10725 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
10726 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
10727 | |
10728 | The size-related fields of the struct stat are as follows: |
10729 | |
10730 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
10731 | |
10732 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
10733 | 512-byte units. As short symbolic links are stored in the |
10734 | inode, this number may be zero. |
10735 | |
10736 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
10737 | |
10738 | #define S_IFMT 0170000 /* type of file mask */ |
10739 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
10740 | #define S_IFCHR 0020000 /* character special */ |
10741 | #define S_IFDIR 0040000 /* directory */ |
10742 | #define S_IFBLK 0060000 /* block special */ |
10743 | #define S_IFREG 0100000 /* regular */ |
10744 | #define S_IFLNK 0120000 /* symbolic link */ |
10745 | #define S_IFSOCK 0140000 /* socket */ |
10746 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
10747 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
10748 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
10749 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
10750 | #define S_IRUSR 0000400 /* R for owner */ |
10751 | #define S_IWUSR 0000200 /* W for owner */ |
10752 | #define S_IXUSR 0000100 /* X for owner */ |
10753 | #define S_IRWXG 0000070 /* RWX mask for group */ |
10754 | #define S_IRGRP 0000040 /* R for group */ |
10755 | #define S_IWGRP 0000020 /* W for group */ |
10756 | #define S_IXGRP 0000010 /* X for group */ |
10757 | #define S_IRWXO 0000007 /* RWX mask for other */ |
10758 | #define S_IROTH 0000004 /* R for other */ |
10759 | #define S_IWOTH 0000002 /* W for other */ |
10760 | #define S_IXOTH 0000001 /* X for other */ |
10761 | |
10762 | The following macros test a file's type. If the file is of that type, a |
10763 | non-zero value is returned; otherwise, 0 is returned. |
10764 | |
10765 | S_ISBLK(st_mode m) /* block special */ |
10766 | S_ISCHR(st_mode m) /* char special */ |
10767 | S_ISDIR(st_mode m) /* directory */ |
10768 | S_ISFIFO(st_mode m) /* fifo */ |
10769 | S_ISLNK(st_mode m) /* symbolic link */ |
10770 | S_ISREG(st_mode m) /* regular file */ |
10771 | S_ISSOCK(st_mode m) /* socket */ |
10772 | |
10773 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
10774 | |
10775 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10776 | Upon successful completion, the value 0 is returned; otherwise the |
10777 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
10778 | error. |
10779 | |
10780 | E\bER\bRR\bRO\bOR\bRS\bS |
10781 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
10782 | |
10783 | [ENOTDIR] A component of the path prefix is not a directory. |
10784 | |
10785 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
10786 | characters, or an entire pathname (including the |
10787 | terminating NUL) exceeded PATH_MAX bytes. |
10788 | |
10789 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
10790 | empty path. |
10791 | |
10792 | [EACCES] Search permission is denied for a component of the |
10793 | path prefix. |
10794 | |
10795 | [ELOOP] Too many symbolic links were encountered in |
10796 | translating the pathname. |
10797 | |
10798 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
10799 | |
10800 | [EIO] An I/O error occurred while reading from or writing to |
10801 | the file system. |
10802 | |
10803 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
10804 | |
10805 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
10806 | AT_SYMLINK_NOFOLLOW. |
10807 | |
10808 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
10809 | argument is neither AT_FDCWD nor a valid file |
10810 | descriptor. |
10811 | |
10812 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
10813 | argument is a valid file descriptor but it does not |
10814 | reference a directory. |
10815 | |
10816 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
10817 | permission is denied for the directory which the _\bf_\bd |
10818 | file descriptor references. |
10819 | |
10820 | f\bfs\bst\bta\bat\bt() will fail if: |
10821 | |
10822 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
10823 | |
10824 | [EFAULT] _\bs_\bb points to an invalid address. |
10825 | |
10826 | [EIO] An I/O error occurred while reading from the file |
10827 | system. |
10828 | |
10829 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
10830 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
10831 | |
10832 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
10833 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
10834 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
10835 | |
10836 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
10837 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
10838 | |
10839 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
10840 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
10841 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
10842 | in Version 7 AT&T UNIX. |
10843 | |
10844 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
10845 | appeared in OpenBSD 5.0. |
10846 | |
10847 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
10848 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
10849 | |
10850 | Certain programs written when the timestamps were just of type time_t |
10851 | assumed that the members were consecutive (and could therefore be treated |
10852 | as an array and have their address passed directly to utime(3)). The |
10853 | transition to timestamps of type struct timespec broke them irrevocably. |
10854 | |
10855 | B\bBU\bUG\bGS\bS |
10856 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
10857 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
10858 | the time fields. |
10859 | |
10860 | N\bNA\bAM\bME\bE |
10861 | s\bst\bta\bat\btf\bfs\bs, f\bfs\bst\bta\bat\btf\bfs\bs - get file system statistics |
10862 | |
10863 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
10864 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
10865 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
10866 | |
10867 | _\bi_\bn_\bt |
10868 | s\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
10869 | |
10870 | _\bi_\bn_\bt |
10871 | f\bfs\bst\bta\bat\btf\bfs\bs(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
10872 | |
10873 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10874 | s\bst\bta\bat\btf\bfs\bs() returns information about a mounted file system. _\bp_\ba_\bt_\bh is the |
10875 | path name of any file within the mounted file system. _\bb_\bu_\bf is a pointer |
10876 | to a s\bst\bta\bat\btf\bfs\bs structure defined as follows: |
10877 | |
10878 | typedef struct { int32_t val[2]; } fsid_t; |
10879 | |
10880 | #define MFSNAMELEN 16 /* length of fs type name, including nul */ |
10881 | #define MNAMELEN 90 /* length of buffer for returned name */ |
10882 | |
10883 | struct statfs { |
10884 | u_int32_t f_flags; /* copy of mount flags */ |
10885 | u_int32_t f_bsize; /* file system block size */ |
10886 | u_int32_t f_iosize; /* optimal transfer block size */ |
10887 | |
10888 | /* unit is f_bsize */ |
10889 | u_int64_t f_blocks; /* total data blocks in file system */ |
10890 | u_int64_t f_bfree; /* free blocks in fs */ |
10891 | int64_t f_bavail; /* free blocks avail to non-superuser */ |
10892 | |
10893 | u_int64_t f_files; /* total file nodes in file system */ |
10894 | u_int64_t f_ffree; /* free file nodes in fs */ |
10895 | int64_t f_favail; /* free file nodes avail to non-root */ |
10896 | |
10897 | u_int64_t f_syncwrites; /* count of sync writes since mount */ |
10898 | u_int64_t f_syncreads; /* count of sync reads since mount */ |
10899 | u_int64_t f_asyncwrites; /* count of async writes since mount */ |
10900 | u_int64_t f_asyncreads; /* count of async reads since mount */ |
10901 | |
10902 | fsid_t f_fsid; /* file system id */ |
10903 | u_int32_t f_namemax; /* maximum filename length */ |
10904 | uid_t f_owner; /* user that mounted the file system */ |
10905 | u_int64_t f_ctime; /* last mount [-u] time */ |
10906 | |
10907 | char f_fstypename[MFSNAMELEN]; /* fs type name */ |
10908 | char f_mntonname[MNAMELEN]; /* directory on which mounted */ |
10909 | char f_mntfromname[MNAMELEN]; /* mounted file system */ |
10910 | char f_mntfromspec[MNAMELEN]; /* special for mount request */ |
10911 | union mount_info mount_info; /* per-filesystem mount options */ |
10912 | }; |
10913 | |
10914 | f\bfs\bst\bta\bat\btf\bfs\bs() returns the same information about an open file referenced by |
10915 | descriptor _\bf_\bd. |
10916 | |
10917 | Note that _\bf_\b__\bf_\bs_\bi_\bd will be empty unless the user is the superuser. |
10918 | |
10919 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10920 | Upon successful completion, the value 0 is returned; otherwise the |
10921 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
10922 | error. |
10923 | |
10924 | E\bER\bRR\bRO\bOR\bRS\bS |
10925 | s\bst\bta\bat\btf\bfs\bs() fails if one or more of the following are true: |
10926 | |
10927 | [ENOTDIR] A component of the path prefix of _\bp_\ba_\bt_\bh is not a |
10928 | directory. |
10929 | |
10930 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
10931 | characters, or an entire pathname (including the |
10932 | terminating NUL) exceeded PATH_MAX bytes. |
10933 | |
10934 | [ENOENT] The file referred to by _\bp_\ba_\bt_\bh does not exist. |
10935 | |
10936 | [EACCES] Search permission is denied for a component of the |
10937 | path prefix of _\bp_\ba_\bt_\bh. |
10938 | |
10939 | [ELOOP] Too many symbolic links were encountered in |
10940 | translating _\bp_\ba_\bt_\bh. |
10941 | |
10942 | [EFAULT] _\bb_\bu_\bf or _\bp_\ba_\bt_\bh points to an invalid address. |
10943 | |
10944 | [EIO] An I/O error occurred while reading from or writing to |
10945 | the file system. |
10946 | |
10947 | f\bfs\bst\bta\bat\btf\bfs\bs() fails if one or more of the following are true: |
10948 | |
10949 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
10950 | |
10951 | [EFAULT] _\bb_\bu_\bf points to an invalid address. |
10952 | |
10953 | [EIO] An I/O error occurred while reading from or writing to |
10954 | the file system. |
10955 | |
10956 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
10957 | df(1), getfsstat(2), mount(2), stat(2) |
10958 | |
10959 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
10960 | The s\bst\bta\bat\btf\bfs\bs() function first appeared in 4.4BSD. |
10961 | |
10962 | N\bNA\bAM\bME\bE |
10963 | f\bfs\bsy\byn\bnc\bc, f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc - synchronize a file's in-core state with that on disk |
10964 | |
10965 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
10966 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
10967 | |
10968 | _\bi_\bn_\bt |
10969 | f\bfs\bsy\byn\bnc\bc(_\bi_\bn_\bt _\bf_\bd); |
10970 | |
10971 | _\bi_\bn_\bt |
10972 | f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc(_\bi_\bn_\bt _\bf_\bd); |
10973 | |
10974 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
10975 | The f\bfs\bsy\byn\bnc\bc() function causes all modified data and attributes of _\bf_\bd to be |
10976 | moved to a permanent storage device. This normally results in all in- |
10977 | core modified copies of buffers for the associated file to be written to |
10978 | a disk. |
10979 | |
10980 | The f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() function is similar to f\bfs\bsy\byn\bnc\bc() except that it only |
10981 | guarantees modified data (and metadata necessary to read that data) is |
10982 | committed to storage. Other file modifications may be left |
10983 | unsynchronized. |
10984 | |
10985 | f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() should be used by programs that require a file to |
10986 | be in a known state, for example, in building a simple transaction |
10987 | facility. |
10988 | |
10989 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
10990 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions return the value 0 if successful; |
10991 | otherwise the value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
10992 | to indicate the error. |
10993 | |
10994 | E\bER\bRR\bRO\bOR\bRS\bS |
10995 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions fail if: |
10996 | |
10997 | [EBADF] _\bf_\bd is not a valid descriptor. |
10998 | |
10999 | [EINVAL] _\bf_\bd does not refer to a file which can be synchronized. |
11000 | |
11001 | [EIO] An I/O error occurred while reading from or writing to |
11002 | the file system. |
11003 | |
11004 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11005 | sync(2), sync(8) |
11006 | |
11007 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11008 | The f\bfs\bsy\byn\bnc\bc() and f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() functions conform to IEEE Std 1003.1-2008 |
11009 | (``POSIX.1''). |
11010 | |
11011 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11012 | The f\bfs\bsy\byn\bnc\bc() system call first appeared in 4.1cBSD, and the f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() |
11013 | function has been available since OpenBSD 5.4. |
11014 | |
11015 | B\bBU\bUG\bGS\bS |
11016 | The f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc() function is currently a wrapper around f\bfs\bsy\byn\bnc\bc(), so it |
11017 | synchronizes more state than necessary. |
11018 | |
11019 | N\bNA\bAM\bME\bE |
11020 | t\btr\bru\bun\bnc\bca\bat\bte\be, f\bft\btr\bru\bun\bnc\bca\bat\bte\be - truncate or extend a file to a specified length |
11021 | |
11022 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11023 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
11024 | |
11025 | _\bi_\bn_\bt |
11026 | t\btr\bru\bun\bnc\bca\bat\bte\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bo_\bf_\bf_\b__\bt _\bl_\be_\bn_\bg_\bt_\bh); |
11027 | |
11028 | _\bi_\bn_\bt |
11029 | f\bft\btr\bru\bun\bnc\bca\bat\bte\be(_\bi_\bn_\bt _\bf_\bd, _\bo_\bf_\bf_\b__\bt _\bl_\be_\bn_\bg_\bt_\bh); |
11030 | |
11031 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11032 | t\btr\bru\bun\bnc\bca\bat\bte\be() causes the file named by _\bp_\ba_\bt_\bh or referenced by _\bf_\bd to be |
11033 | truncated or extended to _\bl_\be_\bn_\bg_\bt_\bh bytes in size. If the file was larger |
11034 | than this size, the extra data is lost. If the file was smaller than |
11035 | this size, it will be extended as if by writing bytes with the value |
11036 | zero. With f\bft\btr\bru\bun\bnc\bca\bat\bte\be(), the file must be open for writing. |
11037 | |
11038 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11039 | Upon successful completion, the value 0 is returned; otherwise the |
11040 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
11041 | error. |
11042 | |
11043 | E\bER\bRR\bRO\bOR\bRS\bS |
11044 | t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() will succeed unless: |
11045 | |
11046 | [EINVAL] The _\bl_\be_\bn_\bg_\bt_\bh is a negative value. |
11047 | |
11048 | [EIO] An I/O error occurred updating the inode. |
11049 | |
11050 | In addition, t\btr\bru\bun\bnc\bca\bat\bte\be() may return the following errors: |
11051 | |
11052 | [ENOTDIR] A component of the path prefix is not a directory. |
11053 | |
11054 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
11055 | characters, or an entire pathname (including the |
11056 | terminating NUL) exceeded PATH_MAX bytes. |
11057 | |
11058 | [ENOENT] The named file does not exist. |
11059 | |
11060 | [EACCES] Search permission is denied for a component of the |
11061 | path prefix. |
11062 | |
11063 | [EACCES] The named file is not writable by the user. |
11064 | |
11065 | [ELOOP] Too many symbolic links were encountered in |
11066 | translating the pathname. |
11067 | |
11068 | [EISDIR] The named file is a directory. |
11069 | |
11070 | [EROFS] The named file resides on a read-only file system. |
11071 | |
11072 | [ETXTBSY] The file is a pure procedure (shared text) file that |
11073 | is being executed. |
11074 | |
11075 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
11076 | space. |
11077 | |
11078 | f\bft\btr\bru\bun\bnc\bca\bat\bte\be() may return the following errors: |
11079 | |
11080 | [EBADF] The _\bf_\bd is not a valid descriptor. |
11081 | |
11082 | [EINVAL] The _\bf_\bd references a socket, not a file. |
11083 | |
11084 | [EINVAL] The _\bf_\bd is not open for writing. |
11085 | |
11086 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11087 | open(2) |
11088 | |
11089 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11090 | The t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() functions conform to IEEE Std 1003.1-2008 |
11091 | (``POSIX.1''). |
11092 | |
11093 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11094 | The t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() system calls first appeared in 4.1cBSD. |
11095 | |
11096 | B\bBU\bUG\bGS\bS |
11097 | These calls should be generalized to allow ranges of bytes in a file to |
11098 | be discarded. |
11099 | |
11100 | Use of t\btr\bru\bun\bnc\bca\bat\bte\be() to extend a file is not portable. |
11101 | |
11102 | N\bNA\bAM\bME\bE |
11103 | u\but\bti\bim\bme\bes\bs, f\bfu\but\bti\bim\bme\bes\bs, u\but\bti\bim\bme\ben\bns\bsa\bat\bt, f\bfu\but\bti\bim\bme\ben\bns\bs - set file access and modification |
11104 | times |
11105 | |
11106 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11107 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
11108 | |
11109 | _\bi_\bn_\bt |
11110 | u\but\bti\bim\bme\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
11111 | |
11112 | _\bi_\bn_\bt |
11113 | f\bfu\but\bti\bim\bme\bes\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
11114 | |
11115 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
11116 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
11117 | |
11118 | _\bi_\bn_\bt |
11119 | u\but\bti\bim\bme\ben\bns\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b], |
11120 | _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
11121 | |
11122 | _\bi_\bn_\bt |
11123 | f\bfu\but\bti\bim\bme\ben\bns\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b]); |
11124 | |
11125 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11126 | The access and modification times of the file named by _\bp_\ba_\bt_\bh or referenced |
11127 | by _\bf_\bd are changed as specified by the argument _\bt_\bi_\bm_\be_\bs. |
11128 | |
11129 | If _\bt_\bi_\bm_\be_\bs is NULL, the access and modification times are set to the |
11130 | current time. The caller must be the owner of the file, have permission |
11131 | to write the file, or be the superuser. |
11132 | |
11133 | If _\bt_\bi_\bm_\be_\bs is non-null, it is assumed to point to an array of two timeval |
11134 | structures. The access time is set to the value of the first element, |
11135 | and the modification time is set to the value of the second element. The |
11136 | caller must be the owner of the file or be the superuser. |
11137 | |
11138 | In either case, the inode-change-time of the file is set to the current |
11139 | time. |
11140 | |
11141 | The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() are equivalent to u\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\bes\bs(), |
11142 | respectively, with the following differences. |
11143 | |
11144 | Both u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() take two timespec values instead of two |
11145 | timeval values. Further, either of the _\bt_\bv_\b__\bn_\bs_\be_\bc fields can be set to one |
11146 | of the following special values defined in <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>: |
11147 | |
11148 | UTIME_NOW Set the respective timestamp to the greatest value |
11149 | supported that is not greater than the current time. |
11150 | UTIME_OMIT Do not change the respective timestamp. |
11151 | |
11152 | Additionally, if the _\bp_\ba_\bt_\bh argument to u\but\bti\bim\bme\ben\bns\bsa\bat\bt() specifies a relative |
11153 | path, the file whose timestamps are changed is determined relative to the |
11154 | directory associated with file descriptor _\bf_\bd instead of the current |
11155 | working directory. |
11156 | |
11157 | If u\but\bti\bim\bme\ben\bns\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
11158 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
11159 | |
11160 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
11161 | values: |
11162 | |
11163 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
11164 | timestamps of the symbolic link are changed. |
11165 | |
11166 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11167 | Upon successful completion, the value 0 is returned; otherwise the |
11168 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
11169 | error. |
11170 | |
11171 | E\bER\bRR\bRO\bOR\bRS\bS |
11172 | u\but\bti\bim\bme\bes\bs() and u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
11173 | |
11174 | [EACCES] Search permission is denied for a component of the |
11175 | path prefix; or the _\bt_\bi_\bm_\be_\bs argument is NULL and the |
11176 | effective user ID of the process does not match the |
11177 | owner of the file, and is not the superuser, and write |
11178 | access is denied. |
11179 | |
11180 | [EFAULT] _\bf_\bi_\bl_\be or _\bt_\bi_\bm_\be_\bs points outside the process's allocated |
11181 | address space. |
11182 | |
11183 | [EIO] An I/O error occurred while reading or writing the |
11184 | affected inode. |
11185 | |
11186 | [ELOOP] Too many symbolic links were encountered in |
11187 | translating the pathname. |
11188 | |
11189 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
11190 | characters, or an entire pathname (including the |
11191 | terminating NUL) exceeded PATH_MAX bytes. |
11192 | |
11193 | [ENOENT] The named file does not exist. |
11194 | |
11195 | [ENOTDIR] A component of the path prefix is not a directory. |
11196 | |
11197 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
11198 | process's effective user ID does not match the owner |
11199 | of the file and is not the superuser. |
11200 | |
11201 | [EROFS] The file system containing the file is mounted read- |
11202 | only. |
11203 | |
11204 | Additionally, u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
11205 | |
11206 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
11207 | AT_SYMLINK_NOFOLLOW. |
11208 | |
11209 | [EBADF] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
11210 | argument is neither AT_FDCWD nor a valid file |
11211 | descriptor. |
11212 | |
11213 | [ENOTDIR] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
11214 | argument is a valid file descriptor but it does not |
11215 | reference a directory. |
11216 | |
11217 | [EACCES] The _\bf_\bi_\bl_\be argument specifies a relative path but search |
11218 | permission is denied for the directory which the _\bf_\bd |
11219 | file descriptor references. |
11220 | |
11221 | f\bfu\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\ben\bns\bs() will fail if: |
11222 | |
11223 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
11224 | |
11225 | [EACCES] The _\bt_\bi_\bm_\be_\bs argument is NULL and the effective user ID |
11226 | of the process does not match the owner of the file, |
11227 | and is not the superuser, and write access is denied. |
11228 | |
11229 | [EFAULT] _\bt_\bi_\bm_\be_\bs points outside the process's allocated address |
11230 | space. |
11231 | |
11232 | [EIO] An I/O error occurred while reading or writing the |
11233 | affected inode. |
11234 | |
11235 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
11236 | process's effective user ID does not match the owner |
11237 | of the file and is not the superuser. |
11238 | |
11239 | [EROFS] The file system containing the file is mounted read- |
11240 | only. |
11241 | |
11242 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11243 | clock_gettime(2), stat(2), utime(3) |
11244 | |
11245 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11246 | The u\but\bti\bim\bme\bes\bs(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), and f\bfu\but\bti\bim\bme\ben\bns\bs() functions conform to IEEE Std |
11247 | 1003.1-2008 (``POSIX.1''). |
11248 | |
11249 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11250 | The predecessors of u\but\bti\bim\bme\bes\bs() were s\bsm\bmd\bda\bat\bte\be() in Version 1 AT&T UNIX, |
11251 | m\bmd\bda\bat\bte\be() in Version 3 AT&T UNIX, and u\but\bti\bim\bme\be() in Version 7 AT&T UNIX; the |
11252 | latter first supported the concept of an access time in addition to the |
11253 | modification time. |
11254 | |
11255 | The u\but\bti\bim\bme\bes\bs() function call appeared in 4.2BSD. The f\bfu\but\bti\bim\bme\bes\bs() function |
11256 | call appeared in NetBSD 1.2. The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() function |
11257 | calls appeared in OpenBSD 5.0. |
11258 | |
11259 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
11260 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and |
11261 | f\bfu\but\bti\bim\bme\ben\bns\bs() shall mark the last file status change timestamp (i.e. |
11262 | _\bs_\bt_\b__\bc_\bt_\bi_\bm) for update upon successful completion. However, currently some |
11263 | filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the |
11264 | modification timestamp argument. |
11265 | |
11266 | N\bNA\bAM\bME\bE |
11267 | u\but\bti\bim\bme\bes\bs, f\bfu\but\bti\bim\bme\bes\bs, u\but\bti\bim\bme\ben\bns\bsa\bat\bt, f\bfu\but\bti\bim\bme\ben\bns\bs - set file access and modification |
11268 | times |
11269 | |
11270 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11271 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
11272 | |
11273 | _\bi_\bn_\bt |
11274 | u\but\bti\bim\bme\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
11275 | |
11276 | _\bi_\bn_\bt |
11277 | f\bfu\but\bti\bim\bme\bes\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
11278 | |
11279 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
11280 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
11281 | |
11282 | _\bi_\bn_\bt |
11283 | u\but\bti\bim\bme\ben\bns\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b], |
11284 | _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
11285 | |
11286 | _\bi_\bn_\bt |
11287 | f\bfu\but\bti\bim\bme\ben\bns\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b]); |
11288 | |
11289 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11290 | The access and modification times of the file named by _\bp_\ba_\bt_\bh or referenced |
11291 | by _\bf_\bd are changed as specified by the argument _\bt_\bi_\bm_\be_\bs. |
11292 | |
11293 | If _\bt_\bi_\bm_\be_\bs is NULL, the access and modification times are set to the |
11294 | current time. The caller must be the owner of the file, have permission |
11295 | to write the file, or be the superuser. |
11296 | |
11297 | If _\bt_\bi_\bm_\be_\bs is non-null, it is assumed to point to an array of two timeval |
11298 | structures. The access time is set to the value of the first element, |
11299 | and the modification time is set to the value of the second element. The |
11300 | caller must be the owner of the file or be the superuser. |
11301 | |
11302 | In either case, the inode-change-time of the file is set to the current |
11303 | time. |
11304 | |
11305 | The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() are equivalent to u\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\bes\bs(), |
11306 | respectively, with the following differences. |
11307 | |
11308 | Both u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() take two timespec values instead of two |
11309 | timeval values. Further, either of the _\bt_\bv_\b__\bn_\bs_\be_\bc fields can be set to one |
11310 | of the following special values defined in <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>: |
11311 | |
11312 | UTIME_NOW Set the respective timestamp to the greatest value |
11313 | supported that is not greater than the current time. |
11314 | UTIME_OMIT Do not change the respective timestamp. |
11315 | |
11316 | Additionally, if the _\bp_\ba_\bt_\bh argument to u\but\bti\bim\bme\ben\bns\bsa\bat\bt() specifies a relative |
11317 | path, the file whose timestamps are changed is determined relative to the |
11318 | directory associated with file descriptor _\bf_\bd instead of the current |
11319 | working directory. |
11320 | |
11321 | If u\but\bti\bim\bme\ben\bns\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
11322 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
11323 | |
11324 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
11325 | values: |
11326 | |
11327 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
11328 | timestamps of the symbolic link are changed. |
11329 | |
11330 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11331 | Upon successful completion, the value 0 is returned; otherwise the |
11332 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
11333 | error. |
11334 | |
11335 | E\bER\bRR\bRO\bOR\bRS\bS |
11336 | u\but\bti\bim\bme\bes\bs() and u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
11337 | |
11338 | [EACCES] Search permission is denied for a component of the |
11339 | path prefix; or the _\bt_\bi_\bm_\be_\bs argument is NULL and the |
11340 | effective user ID of the process does not match the |
11341 | owner of the file, and is not the superuser, and write |
11342 | access is denied. |
11343 | |
11344 | [EFAULT] _\bf_\bi_\bl_\be or _\bt_\bi_\bm_\be_\bs points outside the process's allocated |
11345 | address space. |
11346 | |
11347 | [EIO] An I/O error occurred while reading or writing the |
11348 | affected inode. |
11349 | |
11350 | [ELOOP] Too many symbolic links were encountered in |
11351 | translating the pathname. |
11352 | |
11353 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
11354 | characters, or an entire pathname (including the |
11355 | terminating NUL) exceeded PATH_MAX bytes. |
11356 | |
11357 | [ENOENT] The named file does not exist. |
11358 | |
11359 | [ENOTDIR] A component of the path prefix is not a directory. |
11360 | |
11361 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
11362 | process's effective user ID does not match the owner |
11363 | of the file and is not the superuser. |
11364 | |
11365 | [EROFS] The file system containing the file is mounted read- |
11366 | only. |
11367 | |
11368 | Additionally, u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
11369 | |
11370 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
11371 | AT_SYMLINK_NOFOLLOW. |
11372 | |
11373 | [EBADF] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
11374 | argument is neither AT_FDCWD nor a valid file |
11375 | descriptor. |
11376 | |
11377 | [ENOTDIR] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
11378 | argument is a valid file descriptor but it does not |
11379 | reference a directory. |
11380 | |
11381 | [EACCES] The _\bf_\bi_\bl_\be argument specifies a relative path but search |
11382 | permission is denied for the directory which the _\bf_\bd |
11383 | file descriptor references. |
11384 | |
11385 | f\bfu\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\ben\bns\bs() will fail if: |
11386 | |
11387 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
11388 | |
11389 | [EACCES] The _\bt_\bi_\bm_\be_\bs argument is NULL and the effective user ID |
11390 | of the process does not match the owner of the file, |
11391 | and is not the superuser, and write access is denied. |
11392 | |
11393 | [EFAULT] _\bt_\bi_\bm_\be_\bs points outside the process's allocated address |
11394 | space. |
11395 | |
11396 | [EIO] An I/O error occurred while reading or writing the |
11397 | affected inode. |
11398 | |
11399 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
11400 | process's effective user ID does not match the owner |
11401 | of the file and is not the superuser. |
11402 | |
11403 | [EROFS] The file system containing the file is mounted read- |
11404 | only. |
11405 | |
11406 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11407 | clock_gettime(2), stat(2), utime(3) |
11408 | |
11409 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11410 | The u\but\bti\bim\bme\bes\bs(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), and f\bfu\but\bti\bim\bme\ben\bns\bs() functions conform to IEEE Std |
11411 | 1003.1-2008 (``POSIX.1''). |
11412 | |
11413 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11414 | The predecessors of u\but\bti\bim\bme\bes\bs() were s\bsm\bmd\bda\bat\bte\be() in Version 1 AT&T UNIX, |
11415 | m\bmd\bda\bat\bte\be() in Version 3 AT&T UNIX, and u\but\bti\bim\bme\be() in Version 7 AT&T UNIX; the |
11416 | latter first supported the concept of an access time in addition to the |
11417 | modification time. |
11418 | |
11419 | The u\but\bti\bim\bme\bes\bs() function call appeared in 4.2BSD. The f\bfu\but\bti\bim\bme\bes\bs() function |
11420 | call appeared in NetBSD 1.2. The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() function |
11421 | calls appeared in OpenBSD 5.0. |
11422 | |
11423 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
11424 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and |
11425 | f\bfu\but\bti\bim\bme\ben\bns\bs() shall mark the last file status change timestamp (i.e. |
11426 | _\bs_\bt_\b__\bc_\bt_\bi_\bm) for update upon successful completion. However, currently some |
11427 | filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the |
11428 | modification timestamp argument. |
11429 | |
11430 | N\bNA\bAM\bME\bE |
11431 | g\bge\bet\btd\bde\ben\bnt\bts\bs - get directory entries in a filesystem independent format |
11432 | |
11433 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11434 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<d\bdi\bir\bre\ben\bnt\bt.\b.h\bh>\b> |
11435 | |
11436 | _\bi_\bn_\bt |
11437 | g\bge\bet\btd\bde\ben\bnt\bts\bs(_\bi_\bn_\bt _\bf_\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
11438 | |
11439 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11440 | g\bge\bet\btd\bde\ben\bnt\bts\bs() reads directory entries from the directory referenced by the |
11441 | file descriptor _\bf_\bd into the buffer pointed to by _\bb_\bu_\bf, in a filesystem |
11442 | independent format. Up to _\bn_\bb_\by_\bt_\be_\bs of data will be transferred. _\bn_\bb_\by_\bt_\be_\bs |
11443 | must be greater than or equal to the block size associated with the file |
11444 | (see stat(2)). Some filesystems may not support g\bge\bet\btd\bde\ben\bnt\bts\bs() with buffers |
11445 | smaller than this size. |
11446 | |
11447 | The data in the buffer is a series of _\bd_\bi_\br_\be_\bn_\bt structures each containing |
11448 | at least the following entries: |
11449 | |
11450 | ino_t d_fileno; |
11451 | off_t d_off; |
11452 | u_int16_t d_reclen; |
11453 | u_int8_t d_type; |
11454 | u_int8_t d_namlen; |
11455 | char d_name[MAXNAMLEN + 1]; /* see below */ |
11456 | |
11457 | The _\bd_\b__\bf_\bi_\bl_\be_\bn_\bo entry is a number which is unique for each distinct file in |
11458 | the filesystem. Files that are linked by hard links (see link(2)) have |
11459 | the same _\bd_\b__\bf_\bi_\bl_\be_\bn_\bo. The _\bd_\b__\bo_\bf_\bf entry is the file offset of the next entry. |
11460 | The _\bd_\b__\br_\be_\bc_\bl_\be_\bn entry is the length, in bytes, of the directory record. |
11461 | |
11462 | The _\bd_\b__\bt_\by_\bp_\be is the type of file, where the following are possible types: |
11463 | DT_UNKNOWN, DT_FIFO, DT_CHR, DT_DIR, DT_BLK, DT_REG, DT_LNK, and DT_SOCK. |
11464 | |
11465 | The _\bd_\b__\bn_\ba_\bm_\bl_\be_\bn entry specifies the length of the file name excluding the |
11466 | NUL byte. Thus the actual size of _\bd_\b__\bn_\ba_\bm_\be may vary from 1 to MAXNAMLEN + |
11467 | 1. |
11468 | |
11469 | The _\bd_\b__\bn_\ba_\bm_\be entry contains a NUL-terminated file name. |
11470 | |
11471 | Entries may be separated by extra space. The _\bd_\b__\br_\be_\bc_\bl_\be_\bn entry may be used |
11472 | as an offset from the start of a _\bd_\bi_\br_\be_\bn_\bt structure to the next structure, |
11473 | if any. |
11474 | |
11475 | Invalid entries with _\bd_\b__\bf_\bi_\bl_\be_\bn_\bo set to 0 may be returned among regular |
11476 | entries. |
11477 | |
11478 | The actual number of bytes transferred is returned. The current position |
11479 | pointer associated with _\bf_\bd is set to point to the next block of entries. |
11480 | The pointer may not advance by the number of bytes returned by |
11481 | g\bge\bet\btd\bde\ben\bnt\bts\bs(). |
11482 | |
11483 | The current position pointer may be set and retrieved by lseek(2). The |
11484 | current position pointer should only be set to a value returned by |
11485 | lseek(2), the value of _\bd_\b__\bo_\bf_\bf from an entry, or zero. |
11486 | |
11487 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11488 | If successful, the number of bytes actually transferred is returned. A |
11489 | value of zero is returned when the end of the directory has been reached. |
11490 | Otherwise, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to |
11491 | indicate the error. |
11492 | |
11493 | E\bER\bRR\bRO\bOR\bRS\bS |
11494 | g\bge\bet\btd\bde\ben\bnt\bts\bs() will fail if: |
11495 | |
11496 | [EBADF] _\bf_\bd is not a valid file descriptor open for reading. |
11497 | |
11498 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
11499 | address space. |
11500 | |
11501 | [EINVAL] The file referenced by _\bf_\bd is not a directory, or |
11502 | _\bn_\bb_\by_\bt_\be_\bs is too small for returning a directory entry or |
11503 | block of entries, or the current position pointer is |
11504 | invalid. |
11505 | |
11506 | [EIO] An I/O error occurred while reading from or writing to |
11507 | the file system. |
11508 | |
11509 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11510 | lseek(2), open(2), opendir(3), dirent(5) |
11511 | |
11512 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11513 | The g\bge\bet\btd\bde\ben\bnt\bts\bs() call is not a portable interface and should not be used |
11514 | directly by applications. Use readdir(3) instead. |
11515 | |
11516 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11517 | The g\bge\bet\btd\bdi\bir\bre\ben\bnt\btr\bri\bie\bes\bs() function first appeared in 4.4BSD. In OpenBSD 5.5 |
11518 | the _\bd_\b__\bo_\bf_\bf entry was added to _\bs_\bt_\br_\bu_\bc_\bt _\bd_\bi_\br_\be_\bn_\bt and g\bge\bet\btd\bdi\bir\bre\ben\bnt\btr\bri\bie\bes\bs() was |
11519 | replaced with g\bge\bet\btd\bde\ben\bnt\bts\bs(). |
11520 | |
11521 | N\bNA\bAM\bME\bE |
11522 | g\bge\bet\btd\bdt\bta\bab\bbl\ble\bec\bco\bou\bun\bnt\bt - get descriptor table count |
11523 | |
11524 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11525 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
11526 | |
11527 | _\bi_\bn_\bt |
11528 | g\bge\bet\btd\bdt\bta\bab\bbl\ble\bec\bco\bou\bun\bnt\bt(_\bv_\bo_\bi_\bd); |
11529 | |
11530 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11531 | k\bkq\bqu\bue\beu\bue\be returns the number of file descriptors the process currently has |
11532 | open. |
11533 | |
11534 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11535 | getrlimit(2), getdtablesize(3) |
11536 | |
11537 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11538 | The k\bkq\bqu\bue\beu\bue\be function appeared in OpenBSD 5.2. |
11539 | |
11540 | N\bNA\bAM\bME\bE |
11541 | g\bge\bet\btg\bgi\bid\bd, g\bge\bet\bte\beg\bgi\bid\bd - get group process identification |
11542 | |
11543 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11544 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
11545 | |
11546 | _\bg_\bi_\bd_\b__\bt |
11547 | g\bge\bet\btg\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
11548 | |
11549 | _\bg_\bi_\bd_\b__\bt |
11550 | g\bge\bet\bte\beg\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
11551 | |
11552 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11553 | The g\bge\bet\btg\bgi\bid\bd() function returns the real group ID of the calling process |
11554 | and the g\bge\bet\bte\beg\bgi\bid\bd() function returns the effective group ID of the calling |
11555 | process. |
11556 | |
11557 | The real group ID is specified at login time. |
11558 | |
11559 | The real group ID is the group of the user who invoked the program. As |
11560 | the effective group ID gives the process additional permissions during |
11561 | the execution of ``_\bs_\be_\bt_\b-_\bg_\br_\bo_\bu_\bp_\b-_\bI_\bD'' mode processes, g\bge\bet\btg\bgi\bid\bd() is used to |
11562 | determine the real group ID of the calling process. |
11563 | |
11564 | E\bER\bRR\bRO\bOR\bRS\bS |
11565 | The g\bge\bet\btg\bgi\bid\bd() and g\bge\bet\bte\beg\bgi\bid\bd() functions are always successful, and no return |
11566 | value is reserved to indicate an error. |
11567 | |
11568 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11569 | getgroups(2), getresgid(2), getuid(2), setgid(2), setregid(2) |
11570 | |
11571 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11572 | The g\bge\bet\btg\bgi\bid\bd() and g\bge\bet\bte\beg\bgi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
11573 | (``POSIX.1''). |
11574 | |
11575 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11576 | The g\bge\bet\btg\bgi\bid\bd() system call first appeared in Version 4 AT&T UNIX, and |
11577 | g\bge\bet\bte\beg\bgi\bid\bd() in Version 7 AT&T UNIX. |
11578 | |
11579 | N\bNA\bAM\bME\bE |
11580 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by - get entropy |
11581 | |
11582 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11583 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
11584 | |
11585 | _\bi_\bn_\bt |
11586 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by(_\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bl_\be_\bn); |
11587 | |
11588 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11589 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by() fills a buffer with high-quality entropy, which can be used |
11590 | as input for process-context pseudorandom generators like arc4random(3). |
11591 | |
11592 | The maximum buffer size permitted is 256 bytes. If _\bb_\bu_\bf_\bl_\be_\bn exceeds this, |
11593 | an error of EIO will be indicated. |
11594 | |
11595 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by() is not intended for regular code; please use the |
11596 | arc4random(3) family of functions instead. |
11597 | |
11598 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11599 | Upon successful completion, the value 0 is returned; otherwise the |
11600 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
11601 | error. |
11602 | |
11603 | E\bER\bRR\bRO\bOR\bRS\bS |
11604 | g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by() will succeed unless: |
11605 | |
11606 | [EFAULT] The _\bb_\bu_\bf parameter points to an invalid address. |
11607 | |
11608 | [EIO] Too many bytes requested, or some other fatal error |
11609 | occurred. |
11610 | |
11611 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11612 | arc4random(3) |
11613 | |
11614 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11615 | The g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by() function appeared in OpenBSD 5.6. |
11616 | |
11617 | N\bNA\bAM\bME\bE |
11618 | g\bge\bet\btu\bui\bid\bd, g\bge\bet\bte\beu\bui\bid\bd - get user identification |
11619 | |
11620 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11621 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
11622 | |
11623 | _\bu_\bi_\bd_\b__\bt |
11624 | g\bge\bet\btu\bui\bid\bd(_\bv_\bo_\bi_\bd); |
11625 | |
11626 | _\bu_\bi_\bd_\b__\bt |
11627 | g\bge\bet\bte\beu\bui\bid\bd(_\bv_\bo_\bi_\bd); |
11628 | |
11629 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11630 | The g\bge\bet\btu\bui\bid\bd() function returns the real user ID of the calling process. |
11631 | The g\bge\bet\bte\beu\bui\bid\bd() function returns the effective user ID of the calling |
11632 | process. |
11633 | |
11634 | The real user ID is that of the user who has invoked the program. As the |
11635 | effective user ID gives the process additional permissions during |
11636 | execution of ``_\bs_\be_\bt_\b-_\bu_\bs_\be_\br_\b-_\bI_\bD'' mode processes, g\bge\bet\btu\bui\bid\bd() is used to |
11637 | determine the real user ID of the calling process. |
11638 | |
11639 | E\bER\bRR\bRO\bOR\bRS\bS |
11640 | The g\bge\bet\btu\bui\bid\bd() and g\bge\bet\bte\beu\bui\bid\bd() functions are always successful, and no return |
11641 | value is reserved to indicate an error. |
11642 | |
11643 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11644 | getgid(2), getresuid(2), setreuid(2), setuid(2) |
11645 | |
11646 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11647 | The g\bge\bet\btu\bui\bid\bd() and g\bge\bet\bte\beu\bui\bid\bd() functions conform to IEEE Std 1003.1-2008 |
11648 | (``POSIX.1''). |
11649 | |
11650 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11651 | The g\bge\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX, and |
11652 | g\bge\bet\bte\beu\bui\bid\bd() in Version 7 AT&T UNIX. |
11653 | |
11654 | N\bNA\bAM\bME\bE |
11655 | g\bge\bet\btf\bfh\bh - get file handle |
11656 | |
11657 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11658 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
11659 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
11660 | |
11661 | _\bi_\bn_\bt |
11662 | g\bge\bet\btf\bfh\bh(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bf_\bh_\ba_\bn_\bd_\bl_\be_\b__\bt _\b*_\bf_\bh_\bp); |
11663 | |
11664 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11665 | g\bge\bet\btf\bfh\bh() returns a file handle for the specified file or directory _\bp_\ba_\bt_\bh in |
11666 | the file handle pointed to by _\bf_\bh_\bp. This system call is restricted to the |
11667 | superuser. |
11668 | |
11669 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11670 | Upon successful completion, the value 0 is returned; otherwise the |
11671 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
11672 | error. |
11673 | |
11674 | E\bER\bRR\bRO\bOR\bRS\bS |
11675 | g\bge\bet\btf\bfh\bh() fails if one or more of the following are true: |
11676 | |
11677 | [ENOTDIR] A component of the path prefix of _\bp_\ba_\bt_\bh is not a |
11678 | directory. |
11679 | |
11680 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
11681 | characters, or an entire pathname (including the |
11682 | terminating NUL) exceeded PATH_MAX bytes. |
11683 | |
11684 | [ENOENT] The file referred to by _\bp_\ba_\bt_\bh does not exist. |
11685 | |
11686 | [EACCES] Search permission is denied for a component of the |
11687 | path prefix of _\bp_\ba_\bt_\bh. |
11688 | |
11689 | [ELOOP] Too many symbolic links were encountered in |
11690 | translating _\bp_\ba_\bt_\bh. |
11691 | |
11692 | [EPERM] The effective user ID is not the superuser. |
11693 | |
11694 | [EFAULT] _\bf_\bh_\bp or _\bp_\ba_\bt_\bh points to an invalid address. |
11695 | |
11696 | [EIO] An I/O error occurred while reading from or writing to |
11697 | the file system. |
11698 | |
11699 | [EINVAL] A portion of _\bp_\ba_\bt_\bh refers to a remote file system. |
11700 | |
11701 | [EOPNOTSUPP] A portion of _\bp_\ba_\bt_\bh refers to a remote file system. |
11702 | |
11703 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11704 | fhstat(2) |
11705 | |
11706 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11707 | The g\bge\bet\btf\bfh\bh() function first appeared in 4.4BSD. |
11708 | |
11709 | N\bNA\bAM\bME\bE |
11710 | g\bge\bet\btf\bfs\bss\bst\bta\bat\bt - get list of all mounted file systems |
11711 | |
11712 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11713 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
11714 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
11715 | |
11716 | _\bi_\bn_\bt |
11717 | g\bge\bet\btf\bfs\bss\bst\bta\bat\bt(_\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz_\be, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
11718 | |
11719 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11720 | g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() returns information about all mounted file systems. _\bb_\bu_\bf is a |
11721 | pointer to an array of statfs(2) structures defined as follows: |
11722 | |
11723 | typedef struct { int32_t val[2]; } fsid_t; |
11724 | |
11725 | #define MFSNAMELEN 16 /* length of fs type name, including nul */ |
11726 | #define MNAMELEN 90 /* length of buffer for returned name */ |
11727 | |
11728 | struct statfs { |
11729 | u_int32_t f_flags; /* copy of mount flags */ |
11730 | u_int32_t f_bsize; /* file system block size */ |
11731 | u_int32_t f_iosize; /* optimal transfer block size */ |
11732 | |
11733 | /* unit is f_bsize */ |
11734 | u_int64_t f_blocks; /* total data blocks in file system */ |
11735 | u_int64_t f_bfree; /* free blocks in fs */ |
11736 | int64_t f_bavail; /* free blocks avail to non-superuser */ |
11737 | |
11738 | u_int64_t f_files; /* total file nodes in file system */ |
11739 | u_int64_t f_ffree; /* free file nodes in fs */ |
11740 | int64_t f_favail; /* free file nodes avail to non-root */ |
11741 | |
11742 | u_int64_t f_syncwrites; /* count of sync writes since mount */ |
11743 | u_int64_t f_syncreads; /* count of sync reads since mount */ |
11744 | u_int64_t f_asyncwrites; /* count of async writes since mount */ |
11745 | u_int64_t f_asyncreads; /* count of async reads since mount */ |
11746 | |
11747 | fsid_t f_fsid; /* file system id */ |
11748 | u_int32_t f_namemax; /* maximum filename length */ |
11749 | uid_t f_owner; /* user that mounted the file system */ |
11750 | u_int64_t f_ctime; /* last mount [-u] time */ |
11751 | |
11752 | char f_fstypename[MFSNAMELEN]; /* fs type name */ |
11753 | char f_mntonname[MNAMELEN]; /* directory on which mounted */ |
11754 | char f_mntfromname[MNAMELEN]; /* mounted file system */ |
11755 | char f_mntfromspec[MNAMELEN]; /* special for mount request */ |
11756 | union mount_info mount_info; /* per-filesystem mount options */ |
11757 | }; |
11758 | |
11759 | The buffer is filled with an array of _\bs_\bt_\ba_\bt_\bf_\bs structures, one for each |
11760 | mounted file system up to the size specified by _\bb_\bu_\bf_\bs_\bi_\bz_\be. |
11761 | |
11762 | If _\bb_\bu_\bf is NULL, g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() returns just the number of mounted file |
11763 | systems. |
11764 | |
11765 | Normally _\bf_\bl_\ba_\bg_\bs should be specified as MNT_WAIT. If _\bf_\bl_\ba_\bg_\bs is set to |
11766 | MNT_NOWAIT, g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() will return the information it has available |
11767 | without requesting an update from each file system. Thus, some of the |
11768 | information will be out of date, but g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() will not block waiting |
11769 | for information from a file system that is unable to respond. If no |
11770 | flags are provided, MNT_WAIT is assumed. |
11771 | |
11772 | Note that _\bf_\b__\bf_\bs_\bi_\bd will be empty unless the user is the superuser. |
11773 | |
11774 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11775 | Upon successful completion, the number of _\bs_\bt_\ba_\bt_\bf_\bs structures is returned. |
11776 | Otherwise, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to |
11777 | indicate the error. |
11778 | |
11779 | E\bER\bRR\bRO\bOR\bRS\bS |
11780 | g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() fails if one or more of the following are true: |
11781 | |
11782 | [EFAULT] _\bb_\bu_\bf points to an invalid address. |
11783 | |
11784 | [EIO] An I/O error occurred while reading from or writing to |
11785 | the file system. |
11786 | |
11787 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11788 | statfs(2), fstab(5), mount(8) |
11789 | |
11790 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11791 | The g\bge\bet\btf\bfs\bss\bst\bta\bat\bt() function first appeared in 4.4BSD. |
11792 | |
11793 | N\bNA\bAM\bME\bE |
11794 | g\bge\bet\btg\bgi\bid\bd, g\bge\bet\bte\beg\bgi\bid\bd - get group process identification |
11795 | |
11796 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11797 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
11798 | |
11799 | _\bg_\bi_\bd_\b__\bt |
11800 | g\bge\bet\btg\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
11801 | |
11802 | _\bg_\bi_\bd_\b__\bt |
11803 | g\bge\bet\bte\beg\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
11804 | |
11805 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11806 | The g\bge\bet\btg\bgi\bid\bd() function returns the real group ID of the calling process |
11807 | and the g\bge\bet\bte\beg\bgi\bid\bd() function returns the effective group ID of the calling |
11808 | process. |
11809 | |
11810 | The real group ID is specified at login time. |
11811 | |
11812 | The real group ID is the group of the user who invoked the program. As |
11813 | the effective group ID gives the process additional permissions during |
11814 | the execution of ``_\bs_\be_\bt_\b-_\bg_\br_\bo_\bu_\bp_\b-_\bI_\bD'' mode processes, g\bge\bet\btg\bgi\bid\bd() is used to |
11815 | determine the real group ID of the calling process. |
11816 | |
11817 | E\bER\bRR\bRO\bOR\bRS\bS |
11818 | The g\bge\bet\btg\bgi\bid\bd() and g\bge\bet\bte\beg\bgi\bid\bd() functions are always successful, and no return |
11819 | value is reserved to indicate an error. |
11820 | |
11821 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11822 | getgroups(2), getresgid(2), getuid(2), setgid(2), setregid(2) |
11823 | |
11824 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11825 | The g\bge\bet\btg\bgi\bid\bd() and g\bge\bet\bte\beg\bgi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
11826 | (``POSIX.1''). |
11827 | |
11828 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11829 | The g\bge\bet\btg\bgi\bid\bd() system call first appeared in Version 4 AT&T UNIX, and |
11830 | g\bge\bet\bte\beg\bgi\bid\bd() in Version 7 AT&T UNIX. |
11831 | |
11832 | N\bNA\bAM\bME\bE |
11833 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs - get group access list |
11834 | |
11835 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11836 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
11837 | |
11838 | _\bi_\bn_\bt |
11839 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs(_\bi_\bn_\bt _\bg_\bi_\bd_\bs_\be_\bt_\bl_\be_\bn, _\bg_\bi_\bd_\b__\bt _\b*_\bg_\bi_\bd_\bs_\be_\bt); |
11840 | |
11841 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11842 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() gets the current group access list of the current user |
11843 | process and stores it in the array _\bg_\bi_\bd_\bs_\be_\bt. The parameter _\bg_\bi_\bd_\bs_\be_\bt_\bl_\be_\bn |
11844 | indicates the number of entries that may be placed in _\bg_\bi_\bd_\bs_\be_\bt. |
11845 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() returns the actual number of groups returned in _\bg_\bi_\bd_\bs_\be_\bt. No |
11846 | more than {NGROUPS_MAX} will ever be returned. If _\bg_\bi_\bd_\bs_\be_\bt_\bl_\be_\bn is 0, |
11847 | g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() returns the number of groups without modifying the _\bg_\bi_\bd_\bs_\be_\bt |
11848 | array. |
11849 | |
11850 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11851 | A successful call returns the number of groups in the group set. A value |
11852 | of -1 indicates that an error occurred, and the error code is stored in |
11853 | the global variable _\be_\br_\br_\bn_\bo. |
11854 | |
11855 | E\bER\bRR\bRO\bOR\bRS\bS |
11856 | The possible errors for g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() are: |
11857 | |
11858 | [EINVAL] The argument _\bg_\bi_\bd_\bs_\be_\bt_\bl_\be_\bn is smaller than the number of |
11859 | groups in the group set. |
11860 | |
11861 | [EFAULT] The argument _\bg_\bi_\bd_\bs_\be_\bt specifies an invalid address. |
11862 | |
11863 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11864 | getgid(2), setgid(2), setgroups(2), initgroups(3) |
11865 | |
11866 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11867 | The g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
11868 | |
11869 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11870 | The g\bge\bet\btg\bgr\bro\bou\bup\bps\bs() system call first appeared in 4.1cBSD. |
11871 | |
11872 | N\bNA\bAM\bME\bE |
11873 | g\bge\bet\bti\bit\bti\bim\bme\ber\br, s\bse\bet\bti\bit\bti\bim\bme\ber\br - get/set value of interval timer |
11874 | |
11875 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11876 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
11877 | |
11878 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_R\bRE\bEA\bAL\bL 0\b0 |
11879 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_V\bVI\bIR\bRT\bTU\bUA\bAL\bL 1\b1 |
11880 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_P\bPR\bRO\bOF\bF 2\b2 |
11881 | |
11882 | _\bi_\bn_\bt |
11883 | g\bge\bet\bti\bit\bti\bim\bme\ber\br(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bv_\ba_\bl_\bu_\be); |
11884 | |
11885 | _\bi_\bn_\bt |
11886 | s\bse\bet\bti\bit\bti\bim\bme\ber\br(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bv_\ba_\bl_\bu_\be, |
11887 | _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bo_\bv_\ba_\bl_\bu_\be); |
11888 | |
11889 | _\bv_\bo_\bi_\bd |
11890 | t\bti\bim\bme\ber\brc\bcl\ble\bea\bar\br(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*); |
11891 | |
11892 | _\bi_\bn_\bt |
11893 | t\bti\bim\bme\ber\bri\bis\bss\bse\bet\bt(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*); |
11894 | |
11895 | _\bi_\bn_\bt |
11896 | t\bti\bim\bme\ber\brc\bcm\bmp\bp(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bC_\bM_\bP); |
11897 | |
11898 | _\bv_\bo_\bi_\bd |
11899 | t\bti\bim\bme\ber\brs\bsu\bub\bb(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\br_\be_\bs); |
11900 | |
11901 | _\bv_\bo_\bi_\bd |
11902 | t\bti\bim\bme\ber\bra\bad\bdd\bd(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\br_\be_\bs); |
11903 | |
11904 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11905 | The system provides each process with three interval timers, defined in |
11906 | <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. The g\bge\bet\bti\bit\bti\bim\bme\ber\br() call returns the current value for the |
11907 | timer specified in _\bw_\bh_\bi_\bc_\bh in the structure at _\bv_\ba_\bl_\bu_\be. The s\bse\bet\bti\bit\bti\bim\bme\ber\br() call |
11908 | sets a timer to the specified _\bv_\ba_\bl_\bu_\be (returning the previous value of the |
11909 | timer if _\bo_\bv_\ba_\bl_\bu_\be is non-null). |
11910 | |
11911 | A timer value is defined by the _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl structure: |
11912 | |
11913 | struct itimerval { |
11914 | struct timeval it_interval; /* timer interval */ |
11915 | struct timeval it_value; /* current value */ |
11916 | }; |
11917 | |
11918 | If _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be is non-zero, it indicates the time to the next timer |
11919 | expiration. If _\bi_\bt_\b__\bi_\bn_\bt_\be_\br_\bv_\ba_\bl is non-zero, it specifies a value to be used |
11920 | in reloading _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be when the timer expires. Setting _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be to 0 |
11921 | disables a timer. Setting _\bi_\bt_\b__\bi_\bn_\bt_\be_\br_\bv_\ba_\bl to 0 causes a timer to be disabled |
11922 | after its next expiration (assuming _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be is non-zero). |
11923 | |
11924 | Time values smaller than the resolution of the system clock are rounded |
11925 | up to this resolution (typically 10 milliseconds). |
11926 | |
11927 | The ITIMER_REAL timer decrements in real time. A SIGALRM signal is |
11928 | delivered when this timer expires. |
11929 | |
11930 | The ITIMER_VIRTUAL timer decrements in process virtual time. It runs |
11931 | only when the process is executing. A SIGVTALRM signal is delivered when |
11932 | it expires. |
11933 | |
11934 | The ITIMER_PROF timer decrements both in process virtual time and when |
11935 | the system is running on behalf of the process. It is designed to be |
11936 | used by interpreters in statistically profiling the execution of |
11937 | interpreted programs. Each time the ITIMER_PROF timer expires, the |
11938 | SIGPROF signal is delivered. Because this signal may interrupt in- |
11939 | progress system calls, programs using this timer must be prepared to |
11940 | restart interrupted system calls. |
11941 | |
11942 | The remaining five functions are in fact macros for manipulating time |
11943 | values, defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. |
11944 | |
11945 | t\bti\bim\bme\ber\brc\bcl\ble\bea\bar\br(_\ba) sets the time value in _\ba to zero. |
11946 | |
11947 | t\bti\bim\bme\ber\bri\bis\bss\bse\bet\bt(_\ba) tests if the time value in _\ba is non-zero. |
11948 | |
11949 | t\bti\bim\bme\ber\brc\bcm\bmp\bp(_\ba, _\bb, _\bC_\bM_\bP) compares two time values in the form _\ba CMP _\bb, where |
11950 | _\bC_\bM_\bP is <, <=, ==, !=, >=, or > . |
11951 | |
11952 | t\bti\bim\bme\ber\brs\bsu\bub\bb(_\ba, _\bb, _\br_\be_\bs) subtracts _\ba - _\bb and stores the result in _\br_\be_\bs. |
11953 | |
11954 | t\bti\bim\bme\ber\bra\bad\bdd\bd(_\ba, _\bb, _\br_\be_\bs) adds two timers and stores the result in _\br_\be_\bs. |
11955 | |
11956 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
11957 | Upon successful completion, the value 0 is returned; otherwise the |
11958 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
11959 | error. |
11960 | |
11961 | E\bER\bRR\bRO\bOR\bRS\bS |
11962 | g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() will fail if: |
11963 | |
11964 | [EFAULT] The _\bv_\ba_\bl_\bu_\be parameter specified a bad address. |
11965 | |
11966 | [EINVAL] An unrecognized value for _\bw_\bh_\bi_\bc_\bh was specified. |
11967 | |
11968 | In addition, s\bse\bet\bti\bit\bti\bim\bme\ber\br() may return the following error: |
11969 | |
11970 | [EINVAL] _\bv_\ba_\bl_\bu_\be or _\bo_\bv_\ba_\bl_\bu_\be specified a time that was too large to |
11971 | be handled. |
11972 | |
11973 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
11974 | clock_gettime(2), gettimeofday(2), poll(2), select(2), sigaction(2) |
11975 | |
11976 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
11977 | The g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() functions conform to IEEE Std 1003.1-2008 |
11978 | (``POSIX.1''). |
11979 | |
11980 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
11981 | The g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() system calls first appeared in 4.1cBSD. |
11982 | |
11983 | N\bNA\bAM\bME\bE |
11984 | g\bge\bet\btl\blo\bog\bgi\bin\bn, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br, s\bse\bet\btl\blo\bog\bgi\bin\bn - get/set login name |
11985 | |
11986 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
11987 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
11988 | |
11989 | _\bc_\bh_\ba_\br _\b* |
11990 | g\bge\bet\btl\blo\bog\bgi\bin\bn(_\bv_\bo_\bi_\bd); |
11991 | |
11992 | _\bi_\bn_\bt |
11993 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br(_\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bi_\bz_\be_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
11994 | |
11995 | _\bi_\bn_\bt |
11996 | s\bse\bet\btl\blo\bog\bgi\bin\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); |
11997 | |
11998 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
11999 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() routine returns the login name of the user associated with |
12000 | the current session, as previously set by s\bse\bet\btl\blo\bog\bgi\bin\bn(). The name is |
12001 | normally associated with a login shell at the time a session is created, |
12002 | and is inherited by all processes descended from the login shell. (This |
12003 | is true even if some of those processes assume another user ID, for |
12004 | example when su(1) is used.) |
12005 | |
12006 | The g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() routine is a reentrant version of g\bge\bet\btl\blo\bog\bgi\bin\bn(). It is |
12007 | functionally identical to g\bge\bet\btl\blo\bog\bgi\bin\bn() except that the caller must provide |
12008 | a buffer, _\bn_\ba_\bm_\be, in which to store the user's login name and a |
12009 | corresponding length parameter, _\bn_\ba_\bm_\be_\bl_\be_\bn, that specifies the size of the |
12010 | buffer. The buffer should be large enough to store the login name and a |
12011 | trailing NUL (typically LOGIN_NAME_MAX bytes). |
12012 | |
12013 | s\bse\bet\btl\blo\bog\bgi\bin\bn() sets the login name of the user associated with the current |
12014 | session to _\bn_\ba_\bm_\be. This call is restricted to the superuser, and is |
12015 | normally used only when a new session is being created on behalf of the |
12016 | named user (for example, at login time, or when a remote shell is |
12017 | invoked). |
12018 | |
12019 | _\bN_\bO_\bT_\bE: There is only one login name per session. |
12020 | |
12021 | It is _\bC_\bR_\bI_\bT_\bI_\bC_\bA_\bL_\bL_\bY important to ensure that s\bse\bet\btl\blo\bog\bgi\bin\bn() is only ever called |
12022 | after the process has taken adequate steps to ensure that it is detached |
12023 | from its parent's session. The _\bO_\bN_\bL_\bY way to do this is via the s\bse\bet\bts\bsi\bid\bd() |
12024 | function. The d\bda\bae\bem\bmo\bon\bn() function calls s\bse\bet\bts\bsi\bid\bd() which is an ideal way of |
12025 | detaching from a controlling terminal and forking into the background. |
12026 | |
12027 | In particular, neither i\bio\boc\bct\btl\bl(_\bt_\bt_\by_\bf_\bd, _\bT_\bI_\bO_\bC_\bN_\bO_\bT_\bT_\bY, _\b._\b._\b.) nor s\bse\bet\btp\bpg\bgr\brp\bp(_\b._\b._\b.) is |
12028 | sufficient to create a new session. |
12029 | |
12030 | Once a parent process has called s\bse\bet\bts\bsi\bid\bd(), it is acceptable for some |
12031 | child of that process to then call s\bse\bet\btl\blo\bog\bgi\bin\bn(), even though it is not the |
12032 | session leader. Beware, however, that _\bA_\bL_\bL processes in the session will |
12033 | change their login name at the same time, even the parent. |
12034 | |
12035 | This is different from traditional UNIX privilege inheritance and as such |
12036 | can be counter-intuitive. |
12037 | |
12038 | Since the s\bse\bet\btl\blo\bog\bgi\bin\bn() routine is restricted to the super-user, it is |
12039 | assumed that (like all other privileged programs) the programmer has |
12040 | taken adequate precautions to prevent security violations. |
12041 | |
12042 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12043 | If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn() succeeds, it returns a pointer to a NUL- |
12044 | terminated string in a static buffer. If the name has not been set, it |
12045 | returns NULL. If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() succeeds, a value of 0 is |
12046 | returned, else the error number is returned. If a call to s\bse\bet\btl\blo\bog\bgi\bin\bn() |
12047 | succeeds, a value of 0 is returned. If s\bse\bet\btl\blo\bog\bgi\bin\bn() fails, a value of -1 |
12048 | is returned and an error code is placed in the global location _\be_\br_\br_\bn_\bo. |
12049 | |
12050 | E\bER\bRR\bRO\bOR\bRS\bS |
12051 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() and s\bse\bet\btl\blo\bog\bgi\bin\bn() will succeed unless: |
12052 | |
12053 | [EFAULT] The _\bn_\ba_\bm_\be parameter points to an invalid address. |
12054 | |
12055 | In addition, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() may return the following error: |
12056 | |
12057 | [ERANGE] The value of _\bn_\ba_\bm_\be_\bl_\be_\bn is not large enough to store the |
12058 | user's login name and a trailing NUL. |
12059 | |
12060 | s\bse\bet\btl\blo\bog\bgi\bin\bn() may return the following errors: |
12061 | |
12062 | [EINVAL] The _\bn_\ba_\bm_\be parameter pointed to a string that was too |
12063 | long. Login names are limited to LOGIN_NAME_MAX-1 |
12064 | characters, currently 31. |
12065 | |
12066 | [EPERM] The caller tried to set the login name and was not the |
12067 | superuser. |
12068 | |
12069 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12070 | setsid(2) |
12071 | |
12072 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12073 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() and g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() functions conform to IEEE Std 1003.1-2008 |
12074 | (``POSIX.1''). |
12075 | |
12076 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12077 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() function first appeared in 4.2BSD. |
12078 | |
12079 | B\bBU\bUG\bGS\bS |
12080 | In earlier versions of the system, g\bge\bet\btl\blo\bog\bgi\bin\bn() failed unless the process |
12081 | was associated with a login terminal. The current implementation (using |
12082 | s\bse\bet\btl\blo\bog\bgi\bin\bn()) allows getlogin to succeed even when the process has no |
12083 | controlling terminal. In earlier versions of the system, the value |
12084 | returned by g\bge\bet\btl\blo\bog\bgi\bin\bn() could not be trusted without checking the user ID. |
12085 | Portable programs should probably still make this check. |
12086 | |
12087 | N\bNA\bAM\bME\bE |
12088 | g\bge\bet\btl\blo\bog\bgi\bin\bn, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br, s\bse\bet\btl\blo\bog\bgi\bin\bn - get/set login name |
12089 | |
12090 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12091 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
12092 | |
12093 | _\bc_\bh_\ba_\br _\b* |
12094 | g\bge\bet\btl\blo\bog\bgi\bin\bn(_\bv_\bo_\bi_\bd); |
12095 | |
12096 | _\bi_\bn_\bt |
12097 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br(_\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bi_\bz_\be_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
12098 | |
12099 | _\bi_\bn_\bt |
12100 | s\bse\bet\btl\blo\bog\bgi\bin\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); |
12101 | |
12102 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12103 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() routine returns the login name of the user associated with |
12104 | the current session, as previously set by s\bse\bet\btl\blo\bog\bgi\bin\bn(). The name is |
12105 | normally associated with a login shell at the time a session is created, |
12106 | and is inherited by all processes descended from the login shell. (This |
12107 | is true even if some of those processes assume another user ID, for |
12108 | example when su(1) is used.) |
12109 | |
12110 | The g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() routine is a reentrant version of g\bge\bet\btl\blo\bog\bgi\bin\bn(). It is |
12111 | functionally identical to g\bge\bet\btl\blo\bog\bgi\bin\bn() except that the caller must provide |
12112 | a buffer, _\bn_\ba_\bm_\be, in which to store the user's login name and a |
12113 | corresponding length parameter, _\bn_\ba_\bm_\be_\bl_\be_\bn, that specifies the size of the |
12114 | buffer. The buffer should be large enough to store the login name and a |
12115 | trailing NUL (typically LOGIN_NAME_MAX bytes). |
12116 | |
12117 | s\bse\bet\btl\blo\bog\bgi\bin\bn() sets the login name of the user associated with the current |
12118 | session to _\bn_\ba_\bm_\be. This call is restricted to the superuser, and is |
12119 | normally used only when a new session is being created on behalf of the |
12120 | named user (for example, at login time, or when a remote shell is |
12121 | invoked). |
12122 | |
12123 | _\bN_\bO_\bT_\bE: There is only one login name per session. |
12124 | |
12125 | It is _\bC_\bR_\bI_\bT_\bI_\bC_\bA_\bL_\bL_\bY important to ensure that s\bse\bet\btl\blo\bog\bgi\bin\bn() is only ever called |
12126 | after the process has taken adequate steps to ensure that it is detached |
12127 | from its parent's session. The _\bO_\bN_\bL_\bY way to do this is via the s\bse\bet\bts\bsi\bid\bd() |
12128 | function. The d\bda\bae\bem\bmo\bon\bn() function calls s\bse\bet\bts\bsi\bid\bd() which is an ideal way of |
12129 | detaching from a controlling terminal and forking into the background. |
12130 | |
12131 | In particular, neither i\bio\boc\bct\btl\bl(_\bt_\bt_\by_\bf_\bd, _\bT_\bI_\bO_\bC_\bN_\bO_\bT_\bT_\bY, _\b._\b._\b.) nor s\bse\bet\btp\bpg\bgr\brp\bp(_\b._\b._\b.) is |
12132 | sufficient to create a new session. |
12133 | |
12134 | Once a parent process has called s\bse\bet\bts\bsi\bid\bd(), it is acceptable for some |
12135 | child of that process to then call s\bse\bet\btl\blo\bog\bgi\bin\bn(), even though it is not the |
12136 | session leader. Beware, however, that _\bA_\bL_\bL processes in the session will |
12137 | change their login name at the same time, even the parent. |
12138 | |
12139 | This is different from traditional UNIX privilege inheritance and as such |
12140 | can be counter-intuitive. |
12141 | |
12142 | Since the s\bse\bet\btl\blo\bog\bgi\bin\bn() routine is restricted to the super-user, it is |
12143 | assumed that (like all other privileged programs) the programmer has |
12144 | taken adequate precautions to prevent security violations. |
12145 | |
12146 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12147 | If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn() succeeds, it returns a pointer to a NUL- |
12148 | terminated string in a static buffer. If the name has not been set, it |
12149 | returns NULL. If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() succeeds, a value of 0 is |
12150 | returned, else the error number is returned. If a call to s\bse\bet\btl\blo\bog\bgi\bin\bn() |
12151 | succeeds, a value of 0 is returned. If s\bse\bet\btl\blo\bog\bgi\bin\bn() fails, a value of -1 |
12152 | is returned and an error code is placed in the global location _\be_\br_\br_\bn_\bo. |
12153 | |
12154 | E\bER\bRR\bRO\bOR\bRS\bS |
12155 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() and s\bse\bet\btl\blo\bog\bgi\bin\bn() will succeed unless: |
12156 | |
12157 | [EFAULT] The _\bn_\ba_\bm_\be parameter points to an invalid address. |
12158 | |
12159 | In addition, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() may return the following error: |
12160 | |
12161 | [ERANGE] The value of _\bn_\ba_\bm_\be_\bl_\be_\bn is not large enough to store the |
12162 | user's login name and a trailing NUL. |
12163 | |
12164 | s\bse\bet\btl\blo\bog\bgi\bin\bn() may return the following errors: |
12165 | |
12166 | [EINVAL] The _\bn_\ba_\bm_\be parameter pointed to a string that was too |
12167 | long. Login names are limited to LOGIN_NAME_MAX-1 |
12168 | characters, currently 31. |
12169 | |
12170 | [EPERM] The caller tried to set the login name and was not the |
12171 | superuser. |
12172 | |
12173 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12174 | setsid(2) |
12175 | |
12176 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12177 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() and g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() functions conform to IEEE Std 1003.1-2008 |
12178 | (``POSIX.1''). |
12179 | |
12180 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12181 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() function first appeared in 4.2BSD. |
12182 | |
12183 | B\bBU\bUG\bGS\bS |
12184 | In earlier versions of the system, g\bge\bet\btl\blo\bog\bgi\bin\bn() failed unless the process |
12185 | was associated with a login terminal. The current implementation (using |
12186 | s\bse\bet\btl\blo\bog\bgi\bin\bn()) allows getlogin to succeed even when the process has no |
12187 | controlling terminal. In earlier versions of the system, the value |
12188 | returned by g\bge\bet\btl\blo\bog\bgi\bin\bn() could not be trusted without checking the user ID. |
12189 | Portable programs should probably still make this check. |
12190 | |
12191 | N\bNA\bAM\bME\bE |
12192 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be - get name of connected peer |
12193 | |
12194 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12195 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
12196 | |
12197 | _\bi_\bn_\bt |
12198 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bn_\ba_\bm_\be_\bl_\be_\bn); |
12199 | |
12200 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12201 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() returns the address information of the peer connected to |
12202 | socket _\bs. One common use occurs when a process inherits an open socket, |
12203 | such as TCP servers forked from inetd(8). In this scenario, |
12204 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() is used to determine the connecting client's IP address. |
12205 | |
12206 | g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() takes three parameters: |
12207 | |
12208 | _\bs contains the file descriptor of the socket whose peer should be looked |
12209 | up. |
12210 | |
12211 | _\bn_\ba_\bm_\be points to a sockaddr structure that will hold the address |
12212 | information for the connected peer. Normal use requires one to use a |
12213 | structure specific to the protocol family in use, such as sockaddr_in |
12214 | (IPv4) or sockaddr_in6 (IPv6), cast to a (struct sockaddr *). |
12215 | |
12216 | For greater portability, especially with the newer protocol families, the |
12217 | new struct sockaddr_storage should be used. sockaddr_storage is large |
12218 | enough to hold any of the other sockaddr_* variants. On return, it can |
12219 | be cast to the correct sockaddr type, based on the protocol family |
12220 | contained in its ss_family field. |
12221 | |
12222 | _\bn_\ba_\bm_\be_\bl_\be_\bn indicates the amount of space pointed to by _\bn_\ba_\bm_\be, in bytes. |
12223 | |
12224 | If address information for the local end of the socket is required, the |
12225 | getsockname(2) function should be used instead. |
12226 | |
12227 | If _\bn_\ba_\bm_\be does not point to enough space to hold the entire socket address, |
12228 | the result will be truncated to _\bn_\ba_\bm_\be_\bl_\be_\bn bytes. |
12229 | |
12230 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12231 | If the call succeeds, a 0 is returned and _\bn_\ba_\bm_\be_\bl_\be_\bn is set to the actual |
12232 | size of the socket address returned in _\bn_\ba_\bm_\be. Otherwise, _\be_\br_\br_\bn_\bo is set and |
12233 | a value of -1 is returned. |
12234 | |
12235 | E\bER\bRR\bRO\bOR\bRS\bS |
12236 | On failure, _\be_\br_\br_\bn_\bo is set to one of the following: |
12237 | |
12238 | [EBADF] The argument _\bs is not a valid descriptor. |
12239 | |
12240 | [ENOTSOCK] The argument _\bs is a file, not a socket. |
12241 | |
12242 | [ENOTCONN] The socket is not connected. |
12243 | |
12244 | [ENOBUFS] Insufficient resources were available in the system to |
12245 | perform the operation. |
12246 | |
12247 | [EFAULT] The _\bn_\ba_\bm_\be or _\bn_\ba_\bm_\be_\bl_\be_\bn parameter points to memory not in |
12248 | a valid part of the process address space. |
12249 | |
12250 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12251 | accept(2), bind(2), getsockname(2), socket(2), getpeereid(3) |
12252 | |
12253 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12254 | The g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() function conforms to IEEE Std 1003.1-2008 |
12255 | (``POSIX.1''). |
12256 | |
12257 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12258 | The g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be() function call appeared in 4.2BSD. |
12259 | |
12260 | N\bNA\bAM\bME\bE |
12261 | g\bge\bet\btp\bpg\bgr\brp\bp, g\bge\bet\btp\bpg\bgi\bid\bd - get process group |
12262 | |
12263 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12264 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
12265 | |
12266 | _\bp_\bi_\bd_\b__\bt |
12267 | g\bge\bet\btp\bpg\bgr\brp\bp(_\bv_\bo_\bi_\bd); |
12268 | |
12269 | _\bp_\bi_\bd_\b__\bt |
12270 | g\bge\bet\btp\bpg\bgi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd); |
12271 | |
12272 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12273 | The process group of the current process is returned by g\bge\bet\btp\bpg\bgr\brp\bp(). The |
12274 | process group of the _\bp_\bi_\bd process is returned by g\bge\bet\btp\bpg\bgi\bid\bd(). If _\bp_\bi_\bd is |
12275 | zero, g\bge\bet\btp\bpg\bgi\bid\bd() returns the process group of the current process. |
12276 | |
12277 | Process groups are used for distribution of signals, and by terminals to |
12278 | arbitrate requests for their input: processes that have the same process |
12279 | group as the terminal are foreground and may read, while others will |
12280 | block with a signal if they attempt to read. |
12281 | |
12282 | These calls are thus used by programs such as csh(1) to create process |
12283 | groups in implementing job control. The t\btc\bcg\bge\bet\btp\bpg\bgr\brp\bp() and t\btc\bcs\bse\bet\btp\bpg\bgr\brp\bp() |
12284 | calls are used to get/set the process group of the control terminal. |
12285 | |
12286 | E\bER\bRR\bRO\bOR\bRS\bS |
12287 | g\bge\bet\btp\bpg\bgr\brp\bp() always succeeds, however g\bge\bet\btp\bpg\bgi\bid\bd() will succeed unless: |
12288 | |
12289 | [EPERM] The current process and the process _\bp_\bi_\bd are not in the |
12290 | same session. |
12291 | |
12292 | [ESRCH] There is no process with a process ID equal to _\bp_\bi_\bd. |
12293 | |
12294 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12295 | setpgid(2), termios(4) |
12296 | |
12297 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12298 | The g\bge\bet\btp\bpg\bgr\brp\bp() and g\bge\bet\btp\bpg\bgi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
12299 | (``POSIX.1''). |
12300 | |
12301 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12302 | A g\bge\bet\btp\bpg\bgr\brp\bp() function call that took a _\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd argument appeared in |
12303 | 4.0BSD. This version, without an argument, is derived from its usage in |
12304 | System V Release 4, and first appeared in NetBSD 0.9. |
12305 | |
12306 | The g\bge\bet\btp\bpg\bgi\bid\bd() function call is derived from its usage in System V Release |
12307 | 4, and first appeared in NetBSD 1.2a. |
12308 | |
12309 | N\bNA\bAM\bME\bE |
12310 | g\bge\bet\btp\bpg\bgr\brp\bp, g\bge\bet\btp\bpg\bgi\bid\bd - get process group |
12311 | |
12312 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12313 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
12314 | |
12315 | _\bp_\bi_\bd_\b__\bt |
12316 | g\bge\bet\btp\bpg\bgr\brp\bp(_\bv_\bo_\bi_\bd); |
12317 | |
12318 | _\bp_\bi_\bd_\b__\bt |
12319 | g\bge\bet\btp\bpg\bgi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd); |
12320 | |
12321 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12322 | The process group of the current process is returned by g\bge\bet\btp\bpg\bgr\brp\bp(). The |
12323 | process group of the _\bp_\bi_\bd process is returned by g\bge\bet\btp\bpg\bgi\bid\bd(). If _\bp_\bi_\bd is |
12324 | zero, g\bge\bet\btp\bpg\bgi\bid\bd() returns the process group of the current process. |
12325 | |
12326 | Process groups are used for distribution of signals, and by terminals to |
12327 | arbitrate requests for their input: processes that have the same process |
12328 | group as the terminal are foreground and may read, while others will |
12329 | block with a signal if they attempt to read. |
12330 | |
12331 | These calls are thus used by programs such as csh(1) to create process |
12332 | groups in implementing job control. The t\btc\bcg\bge\bet\btp\bpg\bgr\brp\bp() and t\btc\bcs\bse\bet\btp\bpg\bgr\brp\bp() |
12333 | calls are used to get/set the process group of the control terminal. |
12334 | |
12335 | E\bER\bRR\bRO\bOR\bRS\bS |
12336 | g\bge\bet\btp\bpg\bgr\brp\bp() always succeeds, however g\bge\bet\btp\bpg\bgi\bid\bd() will succeed unless: |
12337 | |
12338 | [EPERM] The current process and the process _\bp_\bi_\bd are not in the |
12339 | same session. |
12340 | |
12341 | [ESRCH] There is no process with a process ID equal to _\bp_\bi_\bd. |
12342 | |
12343 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12344 | setpgid(2), termios(4) |
12345 | |
12346 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12347 | The g\bge\bet\btp\bpg\bgr\brp\bp() and g\bge\bet\btp\bpg\bgi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
12348 | (``POSIX.1''). |
12349 | |
12350 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12351 | A g\bge\bet\btp\bpg\bgr\brp\bp() function call that took a _\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd argument appeared in |
12352 | 4.0BSD. This version, without an argument, is derived from its usage in |
12353 | System V Release 4, and first appeared in NetBSD 0.9. |
12354 | |
12355 | The g\bge\bet\btp\bpg\bgi\bid\bd() function call is derived from its usage in System V Release |
12356 | 4, and first appeared in NetBSD 1.2a. |
12357 | |
12358 | N\bNA\bAM\bME\bE |
12359 | g\bge\bet\btp\bpi\bid\bd, g\bge\bet\btp\bpp\bpi\bid\bd - get parent or calling process identification |
12360 | |
12361 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12362 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
12363 | |
12364 | _\bp_\bi_\bd_\b__\bt |
12365 | g\bge\bet\btp\bpi\bid\bd(_\bv_\bo_\bi_\bd); |
12366 | |
12367 | _\bp_\bi_\bd_\b__\bt |
12368 | g\bge\bet\btp\bpp\bpi\bid\bd(_\bv_\bo_\bi_\bd); |
12369 | |
12370 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12371 | g\bge\bet\btp\bpi\bid\bd() returns the process ID of the calling process. Though the ID is |
12372 | guaranteed to be unique, it should _\bN_\bO_\bT be used for constructing temporary |
12373 | file names; see mkstemp(3) instead. |
12374 | |
12375 | g\bge\bet\btp\bpp\bpi\bid\bd() returns the process ID of the parent of the calling process. |
12376 | |
12377 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12378 | These functions are always successful, and no return value is reserved to |
12379 | indicate an error. |
12380 | |
12381 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12382 | gethostid(3) |
12383 | |
12384 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12385 | g\bge\bet\btp\bpi\bid\bd() and g\bge\bet\btp\bpp\bpi\bid\bd() conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
12386 | |
12387 | N\bNA\bAM\bME\bE |
12388 | g\bge\bet\btp\bpi\bid\bd, g\bge\bet\btp\bpp\bpi\bid\bd - get parent or calling process identification |
12389 | |
12390 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12391 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
12392 | |
12393 | _\bp_\bi_\bd_\b__\bt |
12394 | g\bge\bet\btp\bpi\bid\bd(_\bv_\bo_\bi_\bd); |
12395 | |
12396 | _\bp_\bi_\bd_\b__\bt |
12397 | g\bge\bet\btp\bpp\bpi\bid\bd(_\bv_\bo_\bi_\bd); |
12398 | |
12399 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12400 | g\bge\bet\btp\bpi\bid\bd() returns the process ID of the calling process. Though the ID is |
12401 | guaranteed to be unique, it should _\bN_\bO_\bT be used for constructing temporary |
12402 | file names; see mkstemp(3) instead. |
12403 | |
12404 | g\bge\bet\btp\bpp\bpi\bid\bd() returns the process ID of the parent of the calling process. |
12405 | |
12406 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12407 | These functions are always successful, and no return value is reserved to |
12408 | indicate an error. |
12409 | |
12410 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12411 | gethostid(3) |
12412 | |
12413 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12414 | g\bge\bet\btp\bpi\bid\bd() and g\bge\bet\btp\bpp\bpi\bid\bd() conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
12415 | |
12416 | N\bNA\bAM\bME\bE |
12417 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by, s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by - get/set process scheduling priority |
12418 | |
12419 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12420 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
12421 | |
12422 | _\bi_\bn_\bt |
12423 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bi_\bd_\b__\bt _\bw_\bh_\bo); |
12424 | |
12425 | _\bi_\bn_\bt |
12426 | s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bi_\bd_\b__\bt _\bw_\bh_\bo, _\bi_\bn_\bt _\bp_\br_\bi_\bo); |
12427 | |
12428 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12429 | The scheduling priority of the process, process group, or user, as |
12430 | indicated by _\bw_\bh_\bi_\bc_\bh and _\bw_\bh_\bo is obtained with the g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call and |
12431 | set with the s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call. _\bw_\bh_\bi_\bc_\bh is one of PRIO_PROCESS, |
12432 | PRIO_PGRP, or PRIO_USER, and _\bw_\bh_\bo is interpreted relative to _\bw_\bh_\bi_\bc_\bh (a |
12433 | process identifier for PRIO_PROCESS, process group identifier for |
12434 | PRIO_PGRP, and a user ID for PRIO_USER). A zero value of _\bw_\bh_\bo denotes the |
12435 | current process, process group, or user. _\bp_\br_\bi_\bo is a value in the range |
12436 | -20 to 20. The default priority is 0; lower priorities cause more |
12437 | favorable scheduling. |
12438 | |
12439 | The g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call returns the highest priority (lowest numerical |
12440 | value) enjoyed by any of the specified processes. The s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call |
12441 | sets the priorities of all of the specified processes to the specified |
12442 | value. Priority values outside the range -20 to 20 are truncated to the |
12443 | appropriate limit. Only the superuser may lower priorities. |
12444 | |
12445 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12446 | Since g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() can legitimately return the value -1, it is necessary |
12447 | to clear the external variable _\be_\br_\br_\bn_\bo prior to the call, then check it |
12448 | afterward to determine if a -1 is an error or a legitimate value. The |
12449 | s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call returns 0 if there is no error, or -1 if there is. |
12450 | |
12451 | E\bER\bRR\bRO\bOR\bRS\bS |
12452 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() will fail if: |
12453 | |
12454 | [ESRCH] No process was located using the _\bw_\bh_\bi_\bc_\bh and _\bw_\bh_\bo values |
12455 | specified. |
12456 | |
12457 | [EINVAL] _\bw_\bh_\bi_\bc_\bh was not one of PRIO_PROCESS, PRIO_PGRP, or |
12458 | PRIO_USER. |
12459 | |
12460 | In addition, s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() will fail if: |
12461 | |
12462 | [EPERM] A process was located, but neither its effective nor |
12463 | real user ID matched the effective user ID of the |
12464 | caller. |
12465 | |
12466 | [EACCES] A non-superuser attempted to lower a process priority. |
12467 | |
12468 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12469 | nice(1), fork(2), renice(8) |
12470 | |
12471 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12472 | The g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() functions conform to IEEE Std |
12473 | 1003.1-2008 (``POSIX.1''). |
12474 | |
12475 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12476 | The predecessor of these functions, the former n\bni\bic\bce\be() system call, |
12477 | appeared in Version 3 AT&T UNIX and was removed in 4.3BSD-Reno. The |
12478 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() system calls appeared in 4.1cBSD. |
12479 | |
12480 | N\bNA\bAM\bME\bE |
12481 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd, g\bge\bet\btr\bre\bes\bsu\bui\bid\bd, s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd, s\bse\bet\btr\bre\bes\bsu\bui\bid\bd - get or set real, effective |
12482 | and saved user or group ID |
12483 | |
12484 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12485 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
12486 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
12487 | |
12488 | _\bi_\bn_\bt |
12489 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\b*_\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\bs_\bg_\bi_\bd); |
12490 | |
12491 | _\bi_\bn_\bt |
12492 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\b*_\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\bs_\bu_\bi_\bd); |
12493 | |
12494 | _\bi_\bn_\bt |
12495 | s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\bs_\bg_\bi_\bd); |
12496 | |
12497 | _\bi_\bn_\bt |
12498 | s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\bs_\bu_\bi_\bd); |
12499 | |
12500 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12501 | The s\bse\bet\btr\bre\bes\bsu\bui\bid\bd() function sets the real, effective and saved user IDs of |
12502 | the current process. The analogous s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd() sets the real, effective |
12503 | and saved group IDs. |
12504 | |
12505 | Privileged processes may set these IDs to arbitrary values. Unprivileged |
12506 | processes are restricted in that each of the new IDs must match one of |
12507 | the current IDs. |
12508 | |
12509 | Passing -1 as an argument causes the corresponding value to remain |
12510 | unchanged. |
12511 | |
12512 | The g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() and g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() calls retrieve the real, effective, and |
12513 | saved group and user IDs of the current process, respectively. |
12514 | |
12515 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12516 | Upon successful completion, the value 0 is returned; otherwise the |
12517 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
12518 | error. |
12519 | |
12520 | E\bER\bRR\bRO\bOR\bRS\bS |
12521 | [EPERM] The calling process was not privileged and tried to |
12522 | change one or more IDs to a value which was not the |
12523 | current real ID, the current effective ID nor the |
12524 | current saved ID. |
12525 | |
12526 | [EFAULT] An address passed to g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() or g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() was |
12527 | invalid. |
12528 | |
12529 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12530 | getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), |
12531 | setregid(2), setreuid(2), setuid(2) |
12532 | |
12533 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12534 | These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') |
12535 | specification. While they are not completely portable, they are the |
12536 | least ambiguous way to manage user and group IDs. |
12537 | |
12538 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12539 | These functions first appeared in HP-UX. |
12540 | |
12541 | N\bNA\bAM\bME\bE |
12542 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd, g\bge\bet\btr\bre\bes\bsu\bui\bid\bd, s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd, s\bse\bet\btr\bre\bes\bsu\bui\bid\bd - get or set real, effective |
12543 | and saved user or group ID |
12544 | |
12545 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12546 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
12547 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
12548 | |
12549 | _\bi_\bn_\bt |
12550 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\b*_\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\bs_\bg_\bi_\bd); |
12551 | |
12552 | _\bi_\bn_\bt |
12553 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\b*_\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\bs_\bu_\bi_\bd); |
12554 | |
12555 | _\bi_\bn_\bt |
12556 | s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\bs_\bg_\bi_\bd); |
12557 | |
12558 | _\bi_\bn_\bt |
12559 | s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\bs_\bu_\bi_\bd); |
12560 | |
12561 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12562 | The s\bse\bet\btr\bre\bes\bsu\bui\bid\bd() function sets the real, effective and saved user IDs of |
12563 | the current process. The analogous s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd() sets the real, effective |
12564 | and saved group IDs. |
12565 | |
12566 | Privileged processes may set these IDs to arbitrary values. Unprivileged |
12567 | processes are restricted in that each of the new IDs must match one of |
12568 | the current IDs. |
12569 | |
12570 | Passing -1 as an argument causes the corresponding value to remain |
12571 | unchanged. |
12572 | |
12573 | The g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() and g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() calls retrieve the real, effective, and |
12574 | saved group and user IDs of the current process, respectively. |
12575 | |
12576 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12577 | Upon successful completion, the value 0 is returned; otherwise the |
12578 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
12579 | error. |
12580 | |
12581 | E\bER\bRR\bRO\bOR\bRS\bS |
12582 | [EPERM] The calling process was not privileged and tried to |
12583 | change one or more IDs to a value which was not the |
12584 | current real ID, the current effective ID nor the |
12585 | current saved ID. |
12586 | |
12587 | [EFAULT] An address passed to g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() or g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() was |
12588 | invalid. |
12589 | |
12590 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12591 | getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), |
12592 | setregid(2), setreuid(2), setuid(2) |
12593 | |
12594 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12595 | These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') |
12596 | specification. While they are not completely portable, they are the |
12597 | least ambiguous way to manage user and group IDs. |
12598 | |
12599 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12600 | These functions first appeared in HP-UX. |
12601 | |
12602 | N\bNA\bAM\bME\bE |
12603 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt, s\bse\bet\btr\brl\bli\bim\bmi\bit\bt - control maximum system resource consumption |
12604 | |
12605 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12606 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
12607 | |
12608 | _\bi_\bn_\bt |
12609 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt(_\bi_\bn_\bt _\br_\be_\bs_\bo_\bu_\br_\bc_\be, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bl_\bi_\bm_\bi_\bt _\b*_\br_\bl_\bp); |
12610 | |
12611 | _\bi_\bn_\bt |
12612 | s\bse\bet\btr\brl\bli\bim\bmi\bit\bt(_\bi_\bn_\bt _\br_\be_\bs_\bo_\bu_\br_\bc_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\br_\bl_\bi_\bm_\bi_\bt _\b*_\br_\bl_\bp); |
12613 | |
12614 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12615 | Limits on the consumption of system resources by the current process and |
12616 | each process it creates may be obtained with the g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() call, and |
12617 | set with the s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() call. |
12618 | |
12619 | The _\br_\be_\bs_\bo_\bu_\br_\bc_\be parameter is one of the following: |
12620 | |
12621 | RLIMIT_CORE The largest size (in bytes) _\bc_\bo_\br_\be file that may be |
12622 | created. |
12623 | |
12624 | RLIMIT_CPU The maximum amount of CPU time (in seconds) to be used by |
12625 | each process. |
12626 | |
12627 | RLIMIT_DATA The maximum size (in bytes) of the data segment for a |
12628 | process; this includes memory allocated via malloc(3) and |
12629 | all other anonymous memory mapped via mmap(2). |
12630 | |
12631 | RLIMIT_FSIZE The largest size (in bytes) file that may be created. |
12632 | |
12633 | RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into |
12634 | memory using the mlock(2) function. |
12635 | |
12636 | RLIMIT_NOFILE The maximum number of open files for this process. |
12637 | |
12638 | RLIMIT_NPROC The maximum number of simultaneous processes for this |
12639 | user id. |
12640 | |
12641 | RLIMIT_RSS The maximum size (in bytes) to which a process's resident |
12642 | set size may grow. This imposes a limit on the amount of |
12643 | physical memory to be given to a process; if memory is |
12644 | tight, the system will prefer to take memory from |
12645 | processes that are exceeding their declared resident set |
12646 | size. |
12647 | |
12648 | RLIMIT_STACK The maximum size (in bytes) of the stack segment for a |
12649 | process, which defines how far a process's stack segment |
12650 | may be extended. Stack extension is performed |
12651 | automatically by the system, and is only used by the main |
12652 | thread of a process. |
12653 | |
12654 | A resource limit is specified as a soft limit and a hard limit. When a |
12655 | soft limit is exceeded a process may receive a signal (for example, if |
12656 | the CPU time or file size is exceeded), but it will be allowed to |
12657 | continue execution until it reaches the hard limit (or modifies its |
12658 | resource limit). The _\br_\bl_\bi_\bm_\bi_\bt structure is used to specify the hard and |
12659 | soft limits on a resource, |
12660 | |
12661 | struct rlimit { |
12662 | rlim_t rlim_cur; /* current (soft) limit */ |
12663 | rlim_t rlim_max; /* hard limit */ |
12664 | }; |
12665 | |
12666 | Only the superuser may raise the maximum limits. Other users may only |
12667 | alter _\br_\bl_\bi_\bm_\b__\bc_\bu_\br within the range from 0 to _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx or (irreversibly) |
12668 | lower _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx. |
12669 | |
12670 | An ``infinite'' value for a limit is defined as RLIM_INFINITY. |
12671 | |
12672 | A value of RLIM_SAVED_CUR or RLIM_SAVED_MAX will be stored in _\br_\bl_\bi_\bm_\b__\bc_\bu_\br or |
12673 | _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx respectively by g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() if the value for the current or |
12674 | maximum resource limit cannot be stored in an rlim_t. The values |
12675 | RLIM_SAVED_CUR and RLIM_SAVED_MAX should not be used in a call to |
12676 | s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() unless they were returned by a previous call to g\bge\bet\btr\brl\bli\bim\bmi\bit\bt(). |
12677 | |
12678 | Because this information is stored in the per-process information, this |
12679 | system call must be executed directly by the shell if it is to affect all |
12680 | future processes created by the shell; l\bli\bim\bmi\bit\bt is thus a built-in command |
12681 | to csh(1) and u\bul\bli\bim\bmi\bit\bt is the sh(1) equivalent. |
12682 | |
12683 | The system refuses to extend the data or stack space when the limits |
12684 | would be exceeded in the normal way: a brk(2) call fails if the data |
12685 | space limit is reached. When the stack limit is reached, the process |
12686 | receives a segmentation fault (SIGSEGV); if this signal is not caught by |
12687 | a handler using the signal stack, this signal will kill the process. |
12688 | |
12689 | A file I/O operation that would create a file larger than the process' |
12690 | soft limit will cause the write to fail and a signal SIGXFSZ to be |
12691 | generated; this normally terminates the process, but may be caught. When |
12692 | the soft CPU time limit is exceeded, a signal SIGXCPU is sent to the |
12693 | offending process. |
12694 | |
12695 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12696 | Upon successful completion, the value 0 is returned; otherwise the |
12697 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
12698 | error. |
12699 | |
12700 | E\bER\bRR\bRO\bOR\bRS\bS |
12701 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() will fail if: |
12702 | |
12703 | [EFAULT] The address specified for _\br_\bl_\bp is invalid. |
12704 | |
12705 | [EINVAL] An unrecognized value for _\br_\be_\bs_\bo_\bu_\br_\bc_\be was specified. |
12706 | |
12707 | In addition, s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() may return the following errors: |
12708 | |
12709 | [EINVAL] The new _\br_\bl_\bi_\bm_\b__\bc_\bu_\br is greater than the new _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx. |
12710 | |
12711 | [EPERM] The new _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx is greater than the current maximum |
12712 | limit value, and the caller is not the superuser. |
12713 | |
12714 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12715 | csh(1), sh(1), quotactl(2), sigaction(2), sigaltstack(2), sysctl(3) |
12716 | |
12717 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12718 | The g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() functions conform to IEEE Std 1003.1-2008 |
12719 | (``POSIX.1''). |
12720 | |
12721 | The RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS resources are non- |
12722 | standard extensions. |
12723 | |
12724 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12725 | The g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() system calls first appeared in 4.1cBSD. |
12726 | |
12727 | B\bBU\bUG\bGS\bS |
12728 | The RLIMIT_AS resource is missing. |
12729 | |
12730 | N\bNA\bAM\bME\bE |
12731 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be, s\bse\bet\btr\brt\bta\bab\bbl\ble\be - get and set the default routing table of the |
12732 | current process |
12733 | |
12734 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12735 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
12736 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
12737 | |
12738 | _\bi_\bn_\bt |
12739 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be(_\bv_\bo_\bi_\bd); |
12740 | |
12741 | _\bi_\bn_\bt |
12742 | s\bse\bet\btr\brt\bta\bab\bbl\ble\be(_\bi_\bn_\bt _\br_\bt_\ba_\bb_\bl_\be_\bi_\bd); |
12743 | |
12744 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12745 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be() and s\bse\bet\btr\brt\bta\bab\bbl\ble\be() manipulate the routing table and routing |
12746 | domain associated with the current process. |
12747 | |
12748 | Only the superuser is allowed to change the process routing table if it |
12749 | is already set to a non-zero value. |
12750 | |
12751 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12752 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be() returns the routing table of the current process. Upon |
12753 | successful completion, s\bse\bet\btr\brt\bta\bab\bbl\ble\be() returns 0 if the call succeeds, -1 if |
12754 | it fails. |
12755 | |
12756 | E\bER\bRR\bRO\bOR\bRS\bS |
12757 | The call succeeds unless: |
12758 | |
12759 | [EINVAL] The value of the _\br_\bt_\ba_\bb_\bl_\be_\bi_\bd argument is not a valid |
12760 | routing table. |
12761 | |
12762 | [EPERM] The user is not the superuser and the routing table of |
12763 | the calling process is already set to a non-zero |
12764 | value. |
12765 | |
12766 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12767 | getsockopt(2), route(8) |
12768 | |
12769 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12770 | The g\bge\bet\btr\brt\bta\bab\bbl\ble\be() and s\bse\bet\btr\brt\bta\bab\bbl\ble\be() system calls appeared in OpenBSD 4.8. |
12771 | |
12772 | N\bNA\bAM\bME\bE |
12773 | g\bge\bet\btr\bru\bus\bsa\bag\bge\be - get information about resource utilization |
12774 | |
12775 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12776 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
12777 | |
12778 | _\bi_\bn_\bt |
12779 | g\bge\bet\btr\bru\bus\bsa\bag\bge\be(_\bi_\bn_\bt _\bw_\bh_\bo, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
12780 | |
12781 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12782 | g\bge\bet\btr\bru\bus\bsa\bag\bge\be() returns resource usage information for argument _\bw_\bh_\bo, which |
12783 | can be one of the following: |
12784 | |
12785 | RUSAGE_SELF Resources used by the current process. |
12786 | |
12787 | RUSAGE_CHILDREN Resources used by all the terminated children of |
12788 | the current process. |
12789 | |
12790 | RUSAGE_THREAD Resources used by the current thread. |
12791 | |
12792 | The buffer to which _\br_\bu_\bs_\ba_\bg_\be points will be filled in with the following |
12793 | structure: |
12794 | |
12795 | struct rusage { |
12796 | struct timeval ru_utime; /* user time used */ |
12797 | struct timeval ru_stime; /* system time used */ |
12798 | long ru_maxrss; /* max resident set size */ |
12799 | long ru_ixrss; /* integral shared text memory size */ |
12800 | long ru_idrss; /* integral unshared data size */ |
12801 | long ru_isrss; /* integral unshared stack size */ |
12802 | long ru_minflt; /* page reclaims */ |
12803 | long ru_majflt; /* page faults */ |
12804 | long ru_nswap; /* swaps */ |
12805 | long ru_inblock; /* block input operations */ |
12806 | long ru_oublock; /* block output operations */ |
12807 | long ru_msgsnd; /* messages sent */ |
12808 | long ru_msgrcv; /* messages received */ |
12809 | long ru_nsignals; /* signals received */ |
12810 | long ru_nvcsw; /* voluntary context switches */ |
12811 | long ru_nivcsw; /* involuntary context switches */ |
12812 | }; |
12813 | |
12814 | The fields are interpreted as follows: |
12815 | |
12816 | _\br_\bu_\b__\bu_\bt_\bi_\bm_\be the total amount of time spent executing in user mode. |
12817 | |
12818 | _\br_\bu_\b__\bs_\bt_\bi_\bm_\be the total amount of time spent in the system executing on |
12819 | behalf of the process(es). |
12820 | |
12821 | _\br_\bu_\b__\bm_\ba_\bx_\br_\bs_\bs the maximum resident set size utilized (in kilobytes). |
12822 | |
12823 | _\br_\bu_\b__\bi_\bx_\br_\bs_\bs an ``integral'' value indicating the amount of memory used |
12824 | by the text segment that was also shared among other |
12825 | processes. This value is expressed in units of kilobytes * |
12826 | ticks-of-execution. |
12827 | |
12828 | _\br_\bu_\b__\bi_\bd_\br_\bs_\bs an integral value of the amount of unshared memory residing |
12829 | in the data segment of a process (expressed in units of |
12830 | kilobytes * ticks-of-execution). |
12831 | |
12832 | _\br_\bu_\b__\bi_\bs_\br_\bs_\bs an integral value of the amount of unshared memory residing |
12833 | in the stack segment of a process (expressed in units of |
12834 | kilobytes * ticks-of-execution). |
12835 | |
12836 | _\br_\bu_\b__\bm_\bi_\bn_\bf_\bl_\bt the number of page faults serviced without any I/O activity; |
12837 | here I/O activity is avoided by ``reclaiming'' a page frame |
12838 | from the list of pages awaiting reallocation. |
12839 | |
12840 | _\br_\bu_\b__\bm_\ba_\bj_\bf_\bl_\bt the number of page faults serviced that required I/O |
12841 | activity. |
12842 | |
12843 | _\br_\bu_\b__\bn_\bs_\bw_\ba_\bp the number of times a process was ``swapped'' out of main |
12844 | memory. |
12845 | |
12846 | _\br_\bu_\b__\bi_\bn_\bb_\bl_\bo_\bc_\bk the number of times the file system had to perform input. |
12847 | |
12848 | _\br_\bu_\b__\bo_\bu_\bb_\bl_\bo_\bc_\bk the number of times the file system had to perform output. |
12849 | |
12850 | _\br_\bu_\b__\bm_\bs_\bg_\bs_\bn_\bd the number of IPC messages sent. |
12851 | |
12852 | _\br_\bu_\b__\bm_\bs_\bg_\br_\bc_\bv the number of IPC messages received. |
12853 | |
12854 | _\br_\bu_\b__\bn_\bs_\bi_\bg_\bn_\ba_\bl_\bs the number of signals delivered. |
12855 | |
12856 | _\br_\bu_\b__\bn_\bv_\bc_\bs_\bw the number of times a context switch resulted due to a |
12857 | process voluntarily giving up the processor before its time |
12858 | slice was completed (usually to await availability of a |
12859 | resource). |
12860 | |
12861 | _\br_\bu_\b__\bn_\bi_\bv_\bc_\bs_\bw the number of times a context switch resulted due to a |
12862 | higher priority process becoming runnable or because the |
12863 | current process exceeded its time slice. |
12864 | |
12865 | N\bNO\bOT\bTE\bES\bS |
12866 | The numbers _\br_\bu_\b__\bi_\bn_\bb_\bl_\bo_\bc_\bk and _\br_\bu_\b__\bo_\bu_\bb_\bl_\bo_\bc_\bk account only for real I/O; data |
12867 | supplied by the caching mechanism is charged only to the first process to |
12868 | read or write the data. |
12869 | |
12870 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12871 | Upon successful completion, the value 0 is returned; otherwise the |
12872 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
12873 | error. |
12874 | |
12875 | E\bER\bRR\bRO\bOR\bRS\bS |
12876 | g\bge\bet\btr\bru\bus\bsa\bag\bge\be() will fail if: |
12877 | |
12878 | [EINVAL] The _\bw_\bh_\bo parameter is not a valid value. |
12879 | |
12880 | [EFAULT] The address specified by the _\br_\bu_\bs_\ba_\bg_\be parameter is not |
12881 | in a valid part of the process address space. |
12882 | |
12883 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12884 | clock_gettime(2), gettimeofday(2), wait(2) |
12885 | |
12886 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12887 | The g\bge\bet\btr\bru\bus\bsa\bag\bge\be() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
12888 | |
12889 | The RUSAGE_THREAD flag is an extension to that specification. |
12890 | |
12891 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12892 | A predecessor to g\bge\bet\btr\bru\bus\bsa\bag\bge\be(), t\bti\bim\bme\bes\bs(), first appeared in Version 3 AT&T |
12893 | UNIX. The g\bge\bet\btr\bru\bus\bsa\bag\bge\be() system call first appeared in 4.1cBSD. |
12894 | |
12895 | The RUSAGE_THREAD flag has been available since OpenBSD 4.8. |
12896 | |
12897 | B\bBU\bUG\bGS\bS |
12898 | There is no way to obtain information about a child process that has not |
12899 | yet terminated. |
12900 | |
12901 | N\bNA\bAM\bME\bE |
12902 | g\bge\bet\bts\bsi\bid\bd - get process session |
12903 | |
12904 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12905 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
12906 | |
12907 | _\bp_\bi_\bd_\b__\bt |
12908 | g\bge\bet\bts\bsi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd); |
12909 | |
12910 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12911 | The session ID of the process identified by _\bp_\bi_\bd is returned by g\bge\bet\bts\bsi\bid\bd(). |
12912 | If _\bp_\bi_\bd is zero, g\bge\bet\bts\bsi\bid\bd() returns the session ID of the current process. |
12913 | |
12914 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12915 | Upon successful completion, the function g\bge\bet\bts\bsi\bid\bd() returns the session ID |
12916 | of the specified process; otherwise, it returns a value of -1 and sets |
12917 | _\be_\br_\br_\bn_\bo to indicate an error. |
12918 | |
12919 | E\bER\bRR\bRO\bOR\bRS\bS |
12920 | g\bge\bet\bts\bsi\bid\bd() will succeed unless: |
12921 | |
12922 | [EPERM] The current process and the process _\bp_\bi_\bd are not in the |
12923 | same session. |
12924 | |
12925 | [ESRCH] There is no process with a process ID equal to _\bp_\bi_\bd. |
12926 | |
12927 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
12928 | getpgid(2), getpgrp(2), setpgid(2), setsid(2), termios(4) |
12929 | |
12930 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
12931 | g\bge\bet\bts\bsi\bid\bd() conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
12932 | |
12933 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
12934 | The g\bge\bet\bts\bsi\bid\bd() function call is derived from its usage in AT&T System V |
12935 | UNIX, and is mandated by X/Open Portability Guide Issue 4 (``XPG4''). |
12936 | |
12937 | N\bNA\bAM\bME\bE |
12938 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be - get socket name |
12939 | |
12940 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
12941 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
12942 | |
12943 | _\bi_\bn_\bt |
12944 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bn_\ba_\bm_\be_\bl_\be_\bn); |
12945 | |
12946 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
12947 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() returns the locally bound address information for a |
12948 | specified socket. |
12949 | |
12950 | Common uses of this function are as follows: |
12951 | |
12952 | +\b+\bo\bo When bind(2) is called with a port number of 0 (indicating the kernel |
12953 | should pick an ephemeral port) g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() is used to retrieve the |
12954 | kernel-assigned port number. |
12955 | |
12956 | +\b+\bo\bo When a process calls bind(2) on a wildcard IP address, g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() |
12957 | is used to retrieve the local IP address for the connection. |
12958 | |
12959 | +\b+\bo\bo When a function wishes to know the address family of a socket, |
12960 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() can be used. |
12961 | |
12962 | g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() takes three parameters: |
12963 | |
12964 | _\bs contains the file descriptor for the socket to be looked up. |
12965 | |
12966 | _\bn_\ba_\bm_\be points to a sockaddr structure which will hold the resulting address |
12967 | information. Normal use requires one to use a structure specific to the |
12968 | protocol family in use, such as sockaddr_in (IPv4) or sockaddr_in6 |
12969 | (IPv6), cast to a (struct sockaddr *). |
12970 | |
12971 | For greater portability (such as newer protocol families) the new |
12972 | structure sockaddr_storage exists. sockaddr_storage is large enough to |
12973 | hold any of the other sockaddr_* variants. On return, it should be cast |
12974 | to the correct sockaddr type, according to the current protocol family. |
12975 | |
12976 | _\bn_\ba_\bm_\be_\bl_\be_\bn indicates the amount of space pointed to by _\bn_\ba_\bm_\be, in bytes. Upon |
12977 | return, _\bn_\ba_\bm_\be_\bl_\be_\bn is set to the actual size of the returned address |
12978 | information. |
12979 | |
12980 | If the address of the destination socket for a given socket connection is |
12981 | needed, the getpeername(2) function should be used instead. |
12982 | |
12983 | If _\bn_\ba_\bm_\be does not point to enough space to hold the entire socket address, |
12984 | the result will be truncated to _\bn_\ba_\bm_\be_\bl_\be_\bn bytes. |
12985 | |
12986 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
12987 | On success, g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() returns a 0, and _\bn_\ba_\bm_\be_\bl_\be_\bn is set to the actual |
12988 | size of the socket address returned in _\bn_\ba_\bm_\be. Otherwise, _\be_\br_\br_\bn_\bo is set, |
12989 | and a value of -1 is returned. |
12990 | |
12991 | E\bER\bRR\bRO\bOR\bRS\bS |
12992 | If g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() fails, _\be_\br_\br_\bn_\bo is set to one of the following: |
12993 | |
12994 | [EBADF] The argument _\bs is not a valid descriptor. |
12995 | |
12996 | [ENOTSOCK] The argument _\bs is a file, not a socket. |
12997 | |
12998 | [ENOBUFS] Insufficient resources were available in the system to |
12999 | perform the operation. |
13000 | |
13001 | [EFAULT] The _\bn_\ba_\bm_\be or _\bn_\ba_\bm_\be_\bl_\be_\bn parameter points to memory not in |
13002 | a valid part of the process address space. |
13003 | |
13004 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13005 | accept(2), bind(2), getpeername(2), socket(2), getpeereid(3) |
13006 | |
13007 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
13008 | The g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() function conforms to IEEE Std 1003.1-2008 |
13009 | (``POSIX.1''). |
13010 | |
13011 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
13012 | The g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be() function call appeared in 4.2BSD. |
13013 | |
13014 | N\bNA\bAM\bME\bE |
13015 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt, s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt - get and set options on sockets |
13016 | |
13017 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13018 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
13019 | |
13020 | _\bi_\bn_\bt |
13021 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bl_\be_\bv_\be_\bl, _\bi_\bn_\bt _\bo_\bp_\bt_\bn_\ba_\bm_\be, _\bv_\bo_\bi_\bd _\b*_\bo_\bp_\bt_\bv_\ba_\bl, |
13022 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bo_\bp_\bt_\bl_\be_\bn); |
13023 | |
13024 | _\bi_\bn_\bt |
13025 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bl_\be_\bv_\be_\bl, _\bi_\bn_\bt _\bo_\bp_\bt_\bn_\ba_\bm_\be, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bo_\bp_\bt_\bv_\ba_\bl, |
13026 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bo_\bp_\bt_\bl_\be_\bn); |
13027 | |
13028 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13029 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() manipulate the _\bo_\bp_\bt_\bi_\bo_\bn_\bs associated with a |
13030 | socket. Options may exist at multiple protocol levels; they are always |
13031 | present at the uppermost ``socket'' level. |
13032 | |
13033 | When manipulating socket options the level at which the option resides |
13034 | and the name of the option must be specified. To manipulate options at |
13035 | the socket level, _\bl_\be_\bv_\be_\bl is specified as SOL_SOCKET. To manipulate |
13036 | options at any other level the protocol number of the appropriate |
13037 | protocol controlling the option is supplied. For example, to indicate |
13038 | that an option is to be interpreted by the TCP protocol, _\bl_\be_\bv_\be_\bl should be |
13039 | set to the protocol number of TCP; see getprotoent(3). |
13040 | |
13041 | The parameters _\bo_\bp_\bt_\bv_\ba_\bl and _\bo_\bp_\bt_\bl_\be_\bn are used to access option values for |
13042 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() they identify a buffer in which the value |
13043 | for the requested option(s) are to be returned. For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), _\bo_\bp_\bt_\bl_\be_\bn |
13044 | is a value-result parameter, initially containing the size of the buffer |
13045 | pointed to by _\bo_\bp_\bt_\bv_\ba_\bl, and modified on return to indicate the actual size |
13046 | of the value returned. If no option value is to be supplied or returned, |
13047 | _\bo_\bp_\bt_\bv_\ba_\bl may be NULL. |
13048 | |
13049 | _\bo_\bp_\bt_\bn_\ba_\bm_\be and any specified options are passed uninterpreted to the |
13050 | appropriate protocol module for interpretation. The include file |
13051 | <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh> contains definitions for socket level options, described |
13052 | below. Options at other protocol levels vary in format and name; consult |
13053 | the appropriate entries in section 4 of the manual. |
13054 | |
13055 | Most socket-level options utilize an int parameter for _\bo_\bp_\bt_\bv_\ba_\bl. For |
13056 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), the parameter should be non-zero to enable a boolean |
13057 | option, or zero if the option is to be disabled. SO_LINGER uses a struct |
13058 | linger parameter, defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>, which specifies the desired |
13059 | state of the option and the linger interval (see below). SO_SNDTIMEO and |
13060 | SO_RCVTIMEO use a struct timeval parameter, defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. |
13061 | |
13062 | The following options are recognized at the socket level. Except as |
13063 | noted, each may be examined with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and set with s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). |
13064 | |
13065 | SO_DEBUG enables recording of debugging information |
13066 | SO_REUSEADDR enables local address reuse |
13067 | SO_REUSEPORT enables duplicate address and port bindings |
13068 | SO_KEEPALIVE enables keep connections alive |
13069 | SO_DONTROUTE enables routing bypass; not supported |
13070 | SO_LINGER linger on close if data present |
13071 | SO_BROADCAST enables permission to transmit broadcast messages |
13072 | SO_OOBINLINE enables reception of out-of-band data in band |
13073 | SO_BINDANY enables binding to any address |
13074 | SO_SNDBUF set buffer size for output |
13075 | SO_RCVBUF set buffer size for input |
13076 | SO_SNDLOWAT set minimum count for output |
13077 | SO_RCVLOWAT set minimum count for input |
13078 | SO_SNDTIMEO set timeout value for output |
13079 | SO_RCVTIMEO set timeout value for input |
13080 | SO_TIMESTAMP enables reception of a timestamp with datagrams |
13081 | SO_PEERCRED get the credentials from other side of connection |
13082 | SO_RTABLE set the routing table used for route lookups |
13083 | SO_SPLICE splice two sockets together or get data length |
13084 | SO_TYPE get the type of the socket (get only) |
13085 | SO_ERROR get and clear error on the socket (get only) |
13086 | |
13087 | SO_DEBUG enables debugging in the underlying protocol modules. |
13088 | SO_REUSEADDR indicates that the rules used in validating addresses |
13089 | supplied in a bind(2) call should allow reuse of local addresses. |
13090 | SO_REUSEPORT allows completely duplicate bindings by multiple processes |
13091 | if they all set SO_REUSEPORT before binding the port. This option |
13092 | permits multiple instances of a program to each receive UDP/IP multicast |
13093 | or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables |
13094 | the periodic transmission of messages on a connected socket. Should the |
13095 | connected party fail to respond to these messages, the connection is |
13096 | considered broken and processes using the socket are notified via a |
13097 | SIGPIPE signal when attempting to send data. |
13098 | |
13099 | SO_LINGER controls the action taken when unsent messages are queued on |
13100 | socket and a close(2) is performed. If the socket promises reliable |
13101 | delivery of data and SO_LINGER is set, the system will block the process |
13102 | on the close(2) attempt until it is able to transmit the data or until it |
13103 | decides it is unable to deliver the information (a timeout period |
13104 | measured in seconds, termed the linger interval, is specified in the |
13105 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() call when SO_LINGER is requested). If SO_LINGER is disabled |
13106 | and a close(2) is issued, the system will process the close in a manner |
13107 | that allows the process to continue as quickly as possible. |
13108 | |
13109 | The option SO_BROADCAST requests permission to send broadcast datagrams |
13110 | on the socket. Broadcast was a privileged operation in earlier versions |
13111 | of the system. With protocols that support out-of-band data, the |
13112 | SO_OOBINLINE option requests that out-of-band data be placed in the |
13113 | normal data input queue as received; it will then be accessible with |
13114 | recv(2) or read(2) calls without the MSG_OOB flag. Some protocols always |
13115 | behave as if this option is set. |
13116 | |
13117 | SO_BINDANY allows the socket to be bound to addresses which are not local |
13118 | to the machine, so it can be used to make a transparent proxy. Note that |
13119 | this option is limited to the super-user. In order to receive packets |
13120 | for these addresses, SO_BINDANY needs to be combined with matching |
13121 | outgoing pf(4) rules with the _\bd_\bi_\bv_\be_\br_\bt_\b-_\br_\be_\bp_\bl_\by parameter. For example, with |
13122 | the following rule the socket receives packets for 192.168.0.10 even if |
13123 | it is not a local address: |
13124 | |
13125 | pass out inet from 192.168.0.10 divert-reply |
13126 | |
13127 | SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes |
13128 | allocated for output and input buffers, respectively. The buffer size |
13129 | may be increased for high-volume connections, or may be decreased to |
13130 | limit the possible backlog of incoming data. The system places an |
13131 | absolute limit on these values. |
13132 | |
13133 | SO_SNDLOWAT is an option to set the minimum count for output operations. |
13134 | Most output operations process all of the data supplied by the call, |
13135 | delivering data to the protocol for transmission and blocking as |
13136 | necessary for flow control. Nonblocking output operations will process |
13137 | as much data as permitted subject to flow control without blocking, but |
13138 | will process no data if flow control does not allow the smaller of the |
13139 | low water mark value or the entire request to be processed. A select(2) |
13140 | or poll(2) operation testing the ability to write to a socket will return |
13141 | true only if the low water mark amount could be processed. The default |
13142 | value for SO_SNDLOWAT is set to a convenient size for network efficiency, |
13143 | often 1024. SO_RCVLOWAT is an option to set the minimum count for input |
13144 | operations. In general, receive calls will block until any (non-zero) |
13145 | amount of data is received, then return with the smaller of the amount |
13146 | available or the amount requested. The default value for SO_RCVLOWAT is |
13147 | 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls |
13148 | normally wait until they have received the smaller of the low water mark |
13149 | value or the requested amount. Receive calls may still return less than |
13150 | the low water mark if an error occurs, a signal is caught, or the type of |
13151 | data next in the receive queue is different than that returned. |
13152 | |
13153 | SO_SNDTIMEO is an option to set a timeout value for output operations. |
13154 | It accepts a struct timeval parameter with the number of seconds and |
13155 | microseconds used to limit waits for output operations to complete. If a |
13156 | send operation has blocked for this much time, it returns with a partial |
13157 | count or with the error EWOULDBLOCK if no data was sent. In the current |
13158 | implementation, this timer is restarted each time additional data are |
13159 | delivered to the protocol, implying that the limit applies to output |
13160 | portions ranging in size from the low water mark to the high water mark |
13161 | for output. SO_RCVTIMEO is an option to set a timeout value for input |
13162 | operations. It accepts a struct timeval parameter with the number of |
13163 | seconds and microseconds used to limit waits for input operations to |
13164 | complete. In the current implementation, this timer is restarted each |
13165 | time additional data are received by the protocol, and thus the limit is |
13166 | in effect an inactivity timer. If a receive operation has been blocked |
13167 | for this much time without receiving additional data, it returns with a |
13168 | short count or with the error EWOULDBLOCK if no data were received. |
13169 | |
13170 | If the SO_TIMESTAMP option is enabled on a SOCK_DGRAM socket, the |
13171 | recvmsg(2) call will return a timestamp corresponding to when the |
13172 | datagram was received. The msg_control field in the msghdr structure |
13173 | points to a buffer that contains a cmsghdr structure followed by a struct |
13174 | timeval. The cmsghdr fields have the following values: |
13175 | |
13176 | cmsg_len = CMSG_LEN(sizeof(struct timeval)) |
13177 | cmsg_level = SOL_SOCKET |
13178 | cmsg_type = SCM_TIMESTAMP |
13179 | |
13180 | SO_PEERCRED fetches the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\bp_\be_\be_\br_\bc_\br_\be_\bd credentials from the other |
13181 | side of the connection (currently only possible on AF_UNIX sockets). |
13182 | These credentials are from the time that bind(2) or connect(2) were |
13183 | called. |
13184 | |
13185 | The SO_RTABLE option gets or sets the routing table which will be used by |
13186 | the socket for address lookups. If a protocol family of the socket |
13187 | doesn't support switching routing tables, the ENOPROTOOPT error is |
13188 | returned. Only the superuser is allowed to change the routing table if |
13189 | it is already set to a non-zero value. A socket's chosen routing table |
13190 | is initialized from the process's configuration, previously selected |
13191 | using setrtable(2). |
13192 | |
13193 | SO_SPLICE can splice together two TCP or UDP sockets for zero-copy data |
13194 | transfers. Both sockets must be of the same type. In the first form, |
13195 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() is called with the source socket _\bs and the drain socket's |
13196 | _\bi_\bn_\bt file descriptor as _\bo_\bp_\bt_\bv_\ba_\bl. In the second form, _\bo_\bp_\bt_\bv_\ba_\bl is a _\bs_\bt_\br_\bu_\bc_\bt |
13197 | _\bs_\bp_\bl_\bi_\bc_\be with the drain socket in _\bs_\bp_\b__\bf_\bd, a positive maximum number of bytes |
13198 | or 0 in _\bs_\bp_\b__\bm_\ba_\bx and an idle timeout _\bs_\bp_\b__\bi_\bd_\bl_\be in the form of a _\bs_\bt_\br_\bu_\bc_\bt |
13199 | _\bt_\bi_\bm_\be_\bv_\ba_\bl. If -1 is given as drain socket, the source socket _\bs gets |
13200 | unspliced. Otherwise the spliced data transfer continues within the |
13201 | kernel until the optional maximum is reached, one of the connections |
13202 | terminates, idle timeout expires or an error occurs. A successful |
13203 | select(2), poll(2), or kqueue(2) operation testing the ability to read |
13204 | from the source socket indicates that the splicing has terminated. The |
13205 | error status can be examined with SO_ERROR at the source socket. The |
13206 | ETIMEDOUT error is set if there was no data transferred between two |
13207 | sockets during the _\bs_\bp_\b__\bi_\bd_\bl_\be period of time. The EFBIG error is set after |
13208 | exactly _\bs_\bp_\b__\bm_\ba_\bx bytes have been transferred. Note that if a maximum is |
13209 | given, it is only guaranteed that no more bytes are transferred. A short |
13210 | splice can happen, but then a second call to splice will transfer the |
13211 | remaining data immediately. The SO_SPLICE option with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and |
13212 | an _\bo_\bf_\bf_\b__\bt value as _\bo_\bp_\bt_\bv_\ba_\bl can be used to retrieve the number of bytes |
13213 | transferred so far from the source socket _\bs. A successful new splice |
13214 | resets this number. |
13215 | |
13216 | Finally, SO_TYPE and SO_ERROR are options used only with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). |
13217 | SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful |
13218 | for servers that inherit sockets on startup. SO_ERROR returns any |
13219 | pending error on the socket and clears the error status. It may be used |
13220 | to check for asynchronous errors on connected datagram sockets or for |
13221 | other asynchronous errors. |
13222 | |
13223 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13224 | Upon successful completion, the value 0 is returned; otherwise the |
13225 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
13226 | error. |
13227 | |
13228 | E\bER\bRR\bRO\bOR\bRS\bS |
13229 | The call succeeds unless: |
13230 | |
13231 | [EBADF] The argument _\bs is not a valid descriptor. |
13232 | |
13233 | [ENOTSOCK] The argument _\bs is a file, not a socket. |
13234 | |
13235 | [ENOPROTOOPT] The option is unknown at the level indicated. |
13236 | |
13237 | [EOPNOTSUPP] The option is unsupported. |
13238 | |
13239 | [EFAULT] The address pointed to by _\bo_\bp_\bt_\bv_\ba_\bl is not in a valid |
13240 | part of the process address space. For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), |
13241 | this error may also be returned if _\bo_\bp_\bt_\bl_\be_\bn is not in a |
13242 | valid part of the process address space. |
13243 | |
13244 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13245 | connect(2), getrtable(2), ioctl(2), poll(2), select(2), socket(2), |
13246 | getprotoent(3), divert(4), pf.conf(5), protocols(5), sosplice(9) |
13247 | |
13248 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
13249 | The g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() functions conform to IEEE Std |
13250 | 1003.1-2008 (``POSIX.1''). |
13251 | |
13252 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
13253 | The g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() system call appeared in 4.2BSD. |
13254 | |
13255 | B\bBU\bUG\bGS\bS |
13256 | Several of the socket options should be handled at lower levels of the |
13257 | system. |
13258 | |
13259 | N\bNA\bAM\bME\bE |
13260 | g\bge\bet\btt\bth\bhr\bri\bid\bd - get thread identifier |
13261 | |
13262 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13263 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
13264 | |
13265 | _\bp_\bi_\bd_\b__\bt |
13266 | g\bge\bet\btt\bth\bhr\bri\bid\bd(_\bv_\bo_\bi_\bd); |
13267 | |
13268 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13269 | k\bkq\bqu\bue\beu\bue\be returns the thread ID of the calling thread. This is used in the |
13270 | implementation of the thread library (-\b-l\blp\bpt\bth\bhr\bre\bea\bad\bd) and can appear in the |
13271 | output of system utilities such as ps(1) and kdump(1). |
13272 | |
13273 | Thread IDs are not a stable interface and should not be used directly by |
13274 | applications except for correlation with system utility output. |
13275 | Applications should use the _\bp_\bt_\bh_\br_\be_\ba_\bd_\b__\bt values from pthread_self(3) and |
13276 | pthread_create(3) to identify threads within the process itself. |
13277 | |
13278 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13279 | This function is always successful, and no return value is reserved to |
13280 | indicate an error. |
13281 | |
13282 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13283 | __tfork(2), getpid(2), pthread_create(3), pthread_self(3) |
13284 | |
13285 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
13286 | The k\bkq\bqu\bue\beu\bue\be syscall is specific to OpenBSD and should not be used in |
13287 | portable applications. |
13288 | |
13289 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
13290 | The k\bkq\bqu\bue\beu\bue\be syscall appeared in OpenBSD 3.9. |
13291 | |
13292 | N\bNA\bAM\bME\bE |
13293 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by, s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by - get/set date and time |
13294 | |
13295 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13296 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
13297 | |
13298 | _\bi_\bn_\bt |
13299 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be _\b*_\bt_\bz_\bp); |
13300 | |
13301 | _\bi_\bn_\bt |
13302 | s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bp, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be _\b*_\bt_\bz_\bp); |
13303 | |
13304 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13305 | N\bNo\bot\bte\be:\b: t\bti\bim\bme\bez\bzo\bon\bne\be i\bis\bs n\bno\bo l\blo\bon\bng\bge\ber\br u\bus\bse\bed\bd;\b; t\bth\bhi\bis\bs i\bin\bnf\bfo\bor\brm\bma\bat\bti\bio\bon\bn i\bis\bs k\bke\bep\bpt\bt o\bou\but\bts\bsi\bid\bde\be t\bth\bhe\be |
13306 | k\bke\ber\brn\bne\bel\bl.\b. |
13307 | |
13308 | The system's notion of the current Greenwich time and the current time |
13309 | zone is obtained with the g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() call, and set with the |
13310 | s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() call. The time is expressed in seconds and microseconds |
13311 | since midnight (0 hour), January 1, 1970. The resolution of the system |
13312 | clock is hardware dependent, and the time may be updated continuously or |
13313 | in ``ticks''. If _\bt_\bp or _\bt_\bz_\bp is NULL, the associated time information will |
13314 | not be returned or set. |
13315 | |
13316 | The structures pointed to by _\bt_\bp and _\bt_\bz_\bp are defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
13317 | |
13318 | struct timeval { |
13319 | time_t tv_sec; /* seconds since Jan. 1, 1970 */ |
13320 | suseconds_t tv_usec; /* and microseconds */ |
13321 | }; |
13322 | |
13323 | struct timezone { |
13324 | int tz_minuteswest; /* of Greenwich */ |
13325 | int tz_dsttime; /* type of dst correction to apply */ |
13326 | }; |
13327 | |
13328 | The _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be structure indicates the local time zone (measured in minutes |
13329 | of time westward from Greenwich), and a flag that, if nonzero, indicates |
13330 | that Daylight Saving time applies locally during the appropriate part of |
13331 | the year. |
13332 | |
13333 | Only the superuser may set the time of day or time zone. If the system |
13334 | securelevel is greater than 1 (see init(8)), the time may only be |
13335 | advanced. This limitation is imposed to prevent a malicious superuser |
13336 | from setting arbitrary time stamps on files. The system time can still |
13337 | be adjusted backwards using the adjtime(2) system call even when the |
13338 | system is secure. |
13339 | |
13340 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13341 | Upon successful completion, the value 0 is returned; otherwise the |
13342 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
13343 | error. |
13344 | |
13345 | E\bER\bRR\bRO\bOR\bRS\bS |
13346 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() and s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() will succeed unless: |
13347 | |
13348 | [EFAULT] An argument address referenced invalid memory. |
13349 | |
13350 | In addition, s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() may return the following error: |
13351 | |
13352 | [EPERM] A user other than the superuser attempted to set the |
13353 | time. |
13354 | |
13355 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13356 | date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3) |
13357 | |
13358 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
13359 | The g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() function conforms to IEEE Std 1003.1-2008 |
13360 | (``POSIX.1''). |
13361 | |
13362 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
13363 | As predecessors of these functions, former system calls t\bti\bim\bme\be() and |
13364 | s\bst\bti\bim\bme\be() first appeared in Version 1 AT&T UNIX, and f\bft\bti\bim\bme\be() first appeared |
13365 | in Version 7 AT&T UNIX. The g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() and s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() system |
13366 | calls first appeared in 4.1cBSD. |
13367 | |
13368 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
13369 | Setting the time with s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() is dangerous; if possible use |
13370 | adjtime(2) instead. Many daemon programming techniques utilize time- |
13371 | delta techniques using the results from g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() instead of from |
13372 | clock_gettime(2) on the CLOCK_MONOTONIC clock. Time jumps can cause |
13373 | these programs to malfunction in unexpected ways. If the time must be |
13374 | set, consider rebooting the machine for safety. |
13375 | |
13376 | N\bNA\bAM\bME\bE |
13377 | g\bge\bet\btu\bui\bid\bd, g\bge\bet\bte\beu\bui\bid\bd - get user identification |
13378 | |
13379 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13380 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
13381 | |
13382 | _\bu_\bi_\bd_\b__\bt |
13383 | g\bge\bet\btu\bui\bid\bd(_\bv_\bo_\bi_\bd); |
13384 | |
13385 | _\bu_\bi_\bd_\b__\bt |
13386 | g\bge\bet\bte\beu\bui\bid\bd(_\bv_\bo_\bi_\bd); |
13387 | |
13388 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13389 | The g\bge\bet\btu\bui\bid\bd() function returns the real user ID of the calling process. |
13390 | The g\bge\bet\bte\beu\bui\bid\bd() function returns the effective user ID of the calling |
13391 | process. |
13392 | |
13393 | The real user ID is that of the user who has invoked the program. As the |
13394 | effective user ID gives the process additional permissions during |
13395 | execution of ``_\bs_\be_\bt_\b-_\bu_\bs_\be_\br_\b-_\bI_\bD'' mode processes, g\bge\bet\btu\bui\bid\bd() is used to |
13396 | determine the real user ID of the calling process. |
13397 | |
13398 | E\bER\bRR\bRO\bOR\bRS\bS |
13399 | The g\bge\bet\btu\bui\bid\bd() and g\bge\bet\bte\beu\bui\bid\bd() functions are always successful, and no return |
13400 | value is reserved to indicate an error. |
13401 | |
13402 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13403 | getgid(2), getresuid(2), setreuid(2), setuid(2) |
13404 | |
13405 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
13406 | The g\bge\bet\btu\bui\bid\bd() and g\bge\bet\bte\beu\bui\bid\bd() functions conform to IEEE Std 1003.1-2008 |
13407 | (``POSIX.1''). |
13408 | |
13409 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
13410 | The g\bge\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX, and |
13411 | g\bge\bet\bte\beu\bui\bid\bd() in Version 7 AT&T UNIX. |
13412 | |
13413 | N\bNA\bAM\bME\bE |
13414 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be - manage i386 per-thread %fs base |
13415 | address |
13416 | |
13417 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13418 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13419 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13420 | |
13421 | _\bi_\bn_\bt |
13422 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
13423 | |
13424 | _\bi_\bn_\bt |
13425 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
13426 | |
13427 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13428 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() copies the current base address of the segment that, by |
13429 | default, is referenced by the %fs selector into the memory referenced by |
13430 | _\bb_\ba_\bs_\be. |
13431 | |
13432 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() sets the base address of the segment that, by default, |
13433 | is referenced by %fs to the address _\bb_\ba_\bs_\be. |
13434 | |
13435 | The segment base address is local to each thread. The initial thread of |
13436 | a new process inherits its segment base address from the parent thread. |
13437 | __tfork(2) sets the initial segment base address for threads that it |
13438 | creates. |
13439 | |
13440 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() functions |
13441 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
13442 | |
13443 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13444 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() |
13445 | return 0. Otherwise, a value of -1 is returned and the global variable |
13446 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
13447 | |
13448 | E\bER\bRR\bRO\bOR\bRS\bS |
13449 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() will fail if: |
13450 | |
13451 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
13452 | |
13453 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13454 | __tfork(2), fork(2) |
13455 | |
13456 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13457 | |
13458 | N\bNA\bAM\bME\bE |
13459 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be - manage i386 per-thread %gs base |
13460 | address |
13461 | |
13462 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13463 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13464 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13465 | |
13466 | _\bi_\bn_\bt |
13467 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
13468 | |
13469 | _\bi_\bn_\bt |
13470 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
13471 | |
13472 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13473 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() copies the current base address of the segment that, by |
13474 | default, is referenced by the %gs selector into the memory referenced by |
13475 | _\bb_\ba_\bs_\be. |
13476 | |
13477 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() sets the base address of the segment that, by default, |
13478 | is referenced by %gs to the address _\bb_\ba_\bs_\be. |
13479 | |
13480 | The segment base address is local to each thread. The initial thread of |
13481 | a new process inherits its segment base address from the parent thread. |
13482 | __tfork(2) sets the initial segment base address for threads that it |
13483 | creates. |
13484 | |
13485 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() functions |
13486 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
13487 | |
13488 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13489 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() |
13490 | return 0. Otherwise, a value of -1 is returned and the global variable |
13491 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
13492 | |
13493 | E\bER\bRR\bRO\bOR\bRS\bS |
13494 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() will fail if: |
13495 | |
13496 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
13497 | |
13498 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13499 | __tfork(2), fork(2) |
13500 | |
13501 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13502 | |
13503 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
13504 | The ELF Thread-Local Storage ABI reserves %gs for its own use and |
13505 | requires that the dynamic linker and thread library set it to reference |
13506 | data-structures internal to and shared between them. Programs should use |
13507 | the __thread storage class keyword instead of using these calls. To be |
13508 | maximally portable, programs that require per-thread data should use the |
13509 | p\bpt\bth\bhr\bre\bea\bad\bd_\b_k\bke\bey\by_\b_c\bcr\bre\bea\bat\bte\be() interface. |
13510 | |
13511 | N\bNA\bAM\bME\bE |
13512 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm - manage i386 per-process I/O permission |
13513 | bitmap |
13514 | |
13515 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13516 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13517 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13518 | |
13519 | _\bi_\bn_\bt |
13520 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm(_\bu_\b__\bl_\bo_\bn_\bg _\b*_\bi_\bo_\bm_\ba_\bp); |
13521 | |
13522 | _\bi_\bn_\bt |
13523 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm(_\bu_\b__\bl_\bo_\bn_\bg _\b*_\bi_\bo_\bm_\ba_\bp); |
13524 | |
13525 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13526 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() copies the current I/O permission bitmap into the |
13527 | memory referenced by _\bi_\bo_\bm_\ba_\bp. |
13528 | |
13529 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() sets the I/O permission bitmap from the data pointed to |
13530 | by _\bi_\bo_\bm_\ba_\bp. This call may only be made by the superuser. Additionally, it |
13531 | is only permitted when the securelevel(7) is less than or equal to 0 or |
13532 | the _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be sysctl has been set to a non-zero value. |
13533 | |
13534 | The permission bitmap contains 1024 bits in 32 longwords. If bit _\bn is |
13535 | clear in the bitmap, then access is granted to I/O port _\bn. If bit _\bn is |
13536 | set in the bitmap, then an attempt to access I/O port _\bn results in |
13537 | delivery of a SIGBUS signal unless the process's I/O permission level |
13538 | would grant I/O access. |
13539 | |
13540 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() functions |
13541 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
13542 | |
13543 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13544 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() |
13545 | return 0. Otherwise, a value of -1 is returned and the global variable |
13546 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
13547 | |
13548 | E\bER\bRR\bRO\bOR\bRS\bS |
13549 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() will fail if: |
13550 | |
13551 | [EFAULT] _\bi_\bo_\bm_\ba_\bp points outside the process's allocated address space. |
13552 | |
13553 | Additionally i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() will fail if: |
13554 | |
13555 | [EPERM] The caller was not the superuser, or the securelevel is greater |
13556 | than zero and _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be has not been set to a non- |
13557 | zero value. |
13558 | |
13559 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13560 | i386_iopl(2) |
13561 | |
13562 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13563 | |
13564 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
13565 | You can really hose your machine if you enable user-level I/O and write |
13566 | to hardware ports without care. |
13567 | |
13568 | B\bBU\bUG\bGS\bS |
13569 | The bitmap should really cover 65536 bits, but that's just too big for |
13570 | allocation in a kernel structure. If you need access to ports beyond |
13571 | 1024, use i386_iopl(2). |
13572 | |
13573 | N\bNA\bAM\bME\bE |
13574 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt - manage i386 per-process Local Descriptor |
13575 | Table entries |
13576 | |
13577 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13578 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13579 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bse\beg\bgm\bme\ben\bnt\bts\bs.\b.h\bh>\b> |
13580 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13581 | |
13582 | _\bi_\bn_\bt |
13583 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl, _\bu_\bn_\bi_\bo_\bn _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br _\b*_\bd_\be_\bs_\bc_\bs, _\bi_\bn_\bt _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs); |
13584 | |
13585 | _\bi_\bn_\bt |
13586 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl, _\bu_\bn_\bi_\bo_\bn _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br _\b*_\bd_\be_\bs_\bc_\bs, _\bi_\bn_\bt _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs); |
13587 | |
13588 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13589 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() returns a list of the i386 descriptors in the current |
13590 | process' LDT. i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() sets a list of i386 descriptors in the |
13591 | current process' LDT. For both routines, _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl specifies the index |
13592 | of the selector in the LDT at which to begin and _\bd_\be_\bs_\bc_\bs points to an array |
13593 | of _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs descriptors to be set or returned. |
13594 | |
13595 | Each entry in the _\bd_\be_\bs_\bc_\bs array can be either a segment_descriptor or a |
13596 | gate_descriptor, as defined in <_\bi_\b3_\b8_\b6_\b/_\bs_\be_\bg_\bm_\be_\bn_\bt_\bs_\b._\bh>. These structures are |
13597 | defined by the architecture as disjoint bit-fields, so care must be taken |
13598 | in constructing them. |
13599 | |
13600 | Before this API can be used the functionality has to be enabled using the |
13601 | machdep.userldt sysctl(8) variable. |
13602 | |
13603 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() functions must be |
13604 | compiled using -\b-l\bli\bi3\b38\b86\b6. |
13605 | |
13606 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13607 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() returns the number of i386 |
13608 | descriptors copied into _\bd_\be_\bs_\bc_\bs from the current process' LDT. Otherwise, |
13609 | a value of -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to |
13610 | indicate the error. |
13611 | |
13612 | Upon successful completion, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() returns the first selector |
13613 | set; if the kernel allocated a descriptor in the LDT, the allocated index |
13614 | is returned. Otherwise, a value of -1 is returned and the global |
13615 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
13616 | |
13617 | E\bER\bRR\bRO\bOR\bRS\bS |
13618 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() will fail if: |
13619 | |
13620 | [EINVAL] An inappropriate parameter was used for _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl or _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs. |
13621 | |
13622 | [EACCES] The caller attempted to use a descriptor that would circumvent |
13623 | protection or cause a failure. |
13624 | |
13625 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
13626 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13627 | |
13628 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
13629 | You can really hose your process using this. |
13630 | |
13631 | N\bNA\bAM\bME\bE |
13632 | i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl - change the i386 I/O privilege level |
13633 | |
13634 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13635 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13636 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13637 | |
13638 | _\bi_\bn_\bt |
13639 | i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl(_\bi_\bn_\bt _\bi_\bo_\bp_\bl); |
13640 | |
13641 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13642 | i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl() sets the i386 I/O privilege level to the value specified by |
13643 | _\bi_\bo_\bp_\bl. |
13644 | |
13645 | This call may only be made by the superuser. Additionally, it is only |
13646 | permitted when the securelevel(7) is less than or equal to 0 or the |
13647 | _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be sysctl has been set to a non-zero value. |
13648 | |
13649 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl() function must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
13650 | |
13651 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13652 | Upon successful completion, i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl() returns 0. Otherwise, a value of |
13653 | -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
13654 | error. |
13655 | |
13656 | E\bER\bRR\bRO\bOR\bRS\bS |
13657 | i\bi3\b38\b86\b6_\b_i\bio\bop\bpl\bl() will fail if: |
13658 | |
13659 | [EPERM] The caller was not the superuser, or the securelevel is greater |
13660 | than zero and _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be has not been set to a non- |
13661 | zero value. |
13662 | |
13663 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13664 | i386_get_ioperm(2), securelevel(7) |
13665 | |
13666 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
13667 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13668 | |
13669 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
13670 | You can really hose your machine if you enable user-level I/O and write |
13671 | to hardware ports without care. |
13672 | |
13673 | N\bNA\bAM\bME\bE |
13674 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be - manage i386 per-thread %fs base |
13675 | address |
13676 | |
13677 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13678 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13679 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13680 | |
13681 | _\bi_\bn_\bt |
13682 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
13683 | |
13684 | _\bi_\bn_\bt |
13685 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
13686 | |
13687 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13688 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() copies the current base address of the segment that, by |
13689 | default, is referenced by the %fs selector into the memory referenced by |
13690 | _\bb_\ba_\bs_\be. |
13691 | |
13692 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() sets the base address of the segment that, by default, |
13693 | is referenced by %fs to the address _\bb_\ba_\bs_\be. |
13694 | |
13695 | The segment base address is local to each thread. The initial thread of |
13696 | a new process inherits its segment base address from the parent thread. |
13697 | __tfork(2) sets the initial segment base address for threads that it |
13698 | creates. |
13699 | |
13700 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() functions |
13701 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
13702 | |
13703 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13704 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() |
13705 | return 0. Otherwise, a value of -1 is returned and the global variable |
13706 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
13707 | |
13708 | E\bER\bRR\bRO\bOR\bRS\bS |
13709 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_f\bfs\bsb\bba\bas\bse\be() will fail if: |
13710 | |
13711 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
13712 | |
13713 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13714 | __tfork(2), fork(2) |
13715 | |
13716 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13717 | |
13718 | N\bNA\bAM\bME\bE |
13719 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be - manage i386 per-thread %gs base |
13720 | address |
13721 | |
13722 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13723 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13724 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13725 | |
13726 | _\bi_\bn_\bt |
13727 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\b*_\bb_\ba_\bs_\be); |
13728 | |
13729 | _\bi_\bn_\bt |
13730 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be(_\bv_\bo_\bi_\bd _\b*_\bb_\ba_\bs_\be); |
13731 | |
13732 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13733 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() copies the current base address of the segment that, by |
13734 | default, is referenced by the %gs selector into the memory referenced by |
13735 | _\bb_\ba_\bs_\be. |
13736 | |
13737 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() sets the base address of the segment that, by default, |
13738 | is referenced by %gs to the address _\bb_\ba_\bs_\be. |
13739 | |
13740 | The segment base address is local to each thread. The initial thread of |
13741 | a new process inherits its segment base address from the parent thread. |
13742 | __tfork(2) sets the initial segment base address for threads that it |
13743 | creates. |
13744 | |
13745 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() functions |
13746 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
13747 | |
13748 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13749 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() |
13750 | return 0. Otherwise, a value of -1 is returned and the global variable |
13751 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
13752 | |
13753 | E\bER\bRR\bRO\bOR\bRS\bS |
13754 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_g\bgs\bsb\bba\bas\bse\be() will fail if: |
13755 | |
13756 | [EFAULT] _\bb_\ba_\bs_\be points outside the process's allocated address space. |
13757 | |
13758 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13759 | __tfork(2), fork(2) |
13760 | |
13761 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13762 | |
13763 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
13764 | The ELF Thread-Local Storage ABI reserves %gs for its own use and |
13765 | requires that the dynamic linker and thread library set it to reference |
13766 | data-structures internal to and shared between them. Programs should use |
13767 | the __thread storage class keyword instead of using these calls. To be |
13768 | maximally portable, programs that require per-thread data should use the |
13769 | p\bpt\bth\bhr\bre\bea\bad\bd_\b_k\bke\bey\by_\b_c\bcr\bre\bea\bat\bte\be() interface. |
13770 | |
13771 | N\bNA\bAM\bME\bE |
13772 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm - manage i386 per-process I/O permission |
13773 | bitmap |
13774 | |
13775 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13776 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13777 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13778 | |
13779 | _\bi_\bn_\bt |
13780 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm(_\bu_\b__\bl_\bo_\bn_\bg _\b*_\bi_\bo_\bm_\ba_\bp); |
13781 | |
13782 | _\bi_\bn_\bt |
13783 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm(_\bu_\b__\bl_\bo_\bn_\bg _\b*_\bi_\bo_\bm_\ba_\bp); |
13784 | |
13785 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13786 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() copies the current I/O permission bitmap into the |
13787 | memory referenced by _\bi_\bo_\bm_\ba_\bp. |
13788 | |
13789 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() sets the I/O permission bitmap from the data pointed to |
13790 | by _\bi_\bo_\bm_\ba_\bp. This call may only be made by the superuser. Additionally, it |
13791 | is only permitted when the securelevel(7) is less than or equal to 0 or |
13792 | the _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be sysctl has been set to a non-zero value. |
13793 | |
13794 | The permission bitmap contains 1024 bits in 32 longwords. If bit _\bn is |
13795 | clear in the bitmap, then access is granted to I/O port _\bn. If bit _\bn is |
13796 | set in the bitmap, then an attempt to access I/O port _\bn results in |
13797 | delivery of a SIGBUS signal unless the process's I/O permission level |
13798 | would grant I/O access. |
13799 | |
13800 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() functions |
13801 | must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
13802 | |
13803 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13804 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() |
13805 | return 0. Otherwise, a value of -1 is returned and the global variable |
13806 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
13807 | |
13808 | E\bER\bRR\bRO\bOR\bRS\bS |
13809 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() will fail if: |
13810 | |
13811 | [EFAULT] _\bi_\bo_\bm_\ba_\bp points outside the process's allocated address space. |
13812 | |
13813 | Additionally i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_i\bio\bop\bpe\ber\brm\bm() will fail if: |
13814 | |
13815 | [EPERM] The caller was not the superuser, or the securelevel is greater |
13816 | than zero and _\bm_\ba_\bc_\bh_\bd_\be_\bp_\b._\ba_\bl_\bl_\bo_\bw_\ba_\bp_\be_\br_\bt_\bu_\br_\be has not been set to a non- |
13817 | zero value. |
13818 | |
13819 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
13820 | i386_iopl(2) |
13821 | |
13822 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13823 | |
13824 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
13825 | You can really hose your machine if you enable user-level I/O and write |
13826 | to hardware ports without care. |
13827 | |
13828 | B\bBU\bUG\bGS\bS |
13829 | The bitmap should really cover 65536 bits, but that's just too big for |
13830 | allocation in a kernel structure. If you need access to ports beyond |
13831 | 1024, use i386_iopl(2). |
13832 | |
13833 | N\bNA\bAM\bME\bE |
13834 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt - manage i386 per-process Local Descriptor |
13835 | Table entries |
13836 | |
13837 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13838 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13839 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bse\beg\bgm\bme\ben\bnt\bts\bs.\b.h\bh>\b> |
13840 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13841 | |
13842 | _\bi_\bn_\bt |
13843 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl, _\bu_\bn_\bi_\bo_\bn _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br _\b*_\bd_\be_\bs_\bc_\bs, _\bi_\bn_\bt _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs); |
13844 | |
13845 | _\bi_\bn_\bt |
13846 | i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt(_\bi_\bn_\bt _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl, _\bu_\bn_\bi_\bo_\bn _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br _\b*_\bd_\be_\bs_\bc_\bs, _\bi_\bn_\bt _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs); |
13847 | |
13848 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13849 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() returns a list of the i386 descriptors in the current |
13850 | process' LDT. i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() sets a list of i386 descriptors in the |
13851 | current process' LDT. For both routines, _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl specifies the index |
13852 | of the selector in the LDT at which to begin and _\bd_\be_\bs_\bc_\bs points to an array |
13853 | of _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs descriptors to be set or returned. |
13854 | |
13855 | Each entry in the _\bd_\be_\bs_\bc_\bs array can be either a segment_descriptor or a |
13856 | gate_descriptor, as defined in <_\bi_\b3_\b8_\b6_\b/_\bs_\be_\bg_\bm_\be_\bn_\bt_\bs_\b._\bh>. These structures are |
13857 | defined by the architecture as disjoint bit-fields, so care must be taken |
13858 | in constructing them. |
13859 | |
13860 | Before this API can be used the functionality has to be enabled using the |
13861 | machdep.userldt sysctl(8) variable. |
13862 | |
13863 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() functions must be |
13864 | compiled using -\b-l\bli\bi3\b38\b86\b6. |
13865 | |
13866 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13867 | Upon successful completion, i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() returns the number of i386 |
13868 | descriptors copied into _\bd_\be_\bs_\bc_\bs from the current process' LDT. Otherwise, |
13869 | a value of -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to |
13870 | indicate the error. |
13871 | |
13872 | Upon successful completion, i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() returns the first selector |
13873 | set; if the kernel allocated a descriptor in the LDT, the allocated index |
13874 | is returned. Otherwise, a value of -1 is returned and the global |
13875 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
13876 | |
13877 | E\bER\bRR\bRO\bOR\bRS\bS |
13878 | i\bi3\b38\b86\b6_\b_g\bge\bet\bt_\b_l\bld\bdt\bt() and i\bi3\b38\b86\b6_\b_s\bse\bet\bt_\b_l\bld\bdt\bt() will fail if: |
13879 | |
13880 | [EINVAL] An inappropriate parameter was used for _\bs_\bt_\ba_\br_\bt_\b__\bs_\be_\bl or _\bn_\bu_\bm_\b__\bs_\be_\bl_\bs. |
13881 | |
13882 | [EACCES] The caller attempted to use a descriptor that would circumvent |
13883 | protection or cause a failure. |
13884 | |
13885 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
13886 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13887 | |
13888 | W\bWA\bAR\bRN\bNI\bIN\bNG\bG |
13889 | You can really hose your process using this. |
13890 | |
13891 | N\bNA\bAM\bME\bE |
13892 | i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6 - set virtual 8086 processor registers and mode |
13893 | |
13894 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13895 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
13896 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
13897 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bse\beg\bgm\bme\ben\bnt\bts\bs.\b.h\bh>\b> |
13898 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
13899 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/v\bvm\bm8\b86\b6.\b.h\bh>\b> |
13900 | |
13901 | _\bi_\bn_\bt |
13902 | i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6(_\bs_\bt_\br_\bu_\bc_\bt _\bv_\bm_\b8_\b6_\b__\bs_\bt_\br_\bu_\bc_\bt _\b*_\bv_\bm_\bc_\bp); |
13903 | |
13904 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13905 | i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6() will set the process into virtual 8086 mode using the |
13906 | registers and selectors specified by the context pointed to by _\bv_\bm_\bc_\bp. The |
13907 | processor registers are set from _\bv_\bm_\bc_\bp_\b-_\b>_\bs_\bu_\bb_\bs_\bt_\br_\b._\br_\be_\bg_\bs, and the emulated |
13908 | processor type from _\bv_\bm_\bc_\bp_\b-_\b>_\bs_\bu_\bb_\bs_\bt_\br_\b._\bs_\bs_\b__\bc_\bp_\bu_\b__\bt_\by_\bp_\be. |
13909 | |
13910 | The kernel keeps a pointer to the context, and uses the tables stored at |
13911 | _\bv_\bm_\bc_\bp_\b-_\b>_\bi_\bn_\bt_\b__\bb_\by_\bu_\bs_\be_\br and _\bv_\bm_\bc_\bp_\b-_\b>_\bi_\bn_\bt_\b2_\b1_\b__\bb_\by_\bu_\bs_\be_\br for fast virtual interrupt |
13912 | handling. If the _\bnth bit is clear in the first of these arrays, then the |
13913 | kernel may directly emulate the real-mode x86 INT _\bn instruction handling. |
13914 | If the _\bnth bit is set, then the process is delivered a signal when an INT |
13915 | instruction is executed. |
13916 | |
13917 | Since MS-DOS puts many DOS functions onto interrupt 21, it is handled |
13918 | specially: the _\bkth bit in the _\bv_\bm_\bc_\bp_\b-_\b>_\bi_\bn_\bt_\b2_\b1_\b__\bb_\by_\bu_\bs_\be_\br array is checked when |
13919 | INT _\b2_\b1 is requested and the _\ba_\bh register is _\bk. |
13920 | |
13921 | N\bNo\bot\bte\be:\b: Code using the i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6() function must be compiled using -\b-l\bli\bi3\b38\b86\b6. |
13922 | |
13923 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
13924 | This routine does not normally return: 32-bit mode will be restored by |
13925 | the delivery of a signal to the process. In case of an error in setting |
13926 | the VM86 mode, a value of -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
13927 | set to indicate the error. |
13928 | |
13929 | E\bER\bRR\bRO\bOR\bRS\bS |
13930 | i\bi3\b38\b86\b6_\b_v\bvm\bm8\b86\b6() will fail if: |
13931 | |
13932 | [EFAULT] The state at _\bv_\bm_\bc_\bp was not readable to the user process. |
13933 | |
13934 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
13935 | Intel, _\bi_\b3_\b8_\b6 _\bM_\bi_\bc_\br_\bo_\bp_\br_\bo_\bc_\be_\bs_\bs_\bo_\br _\bP_\br_\bo_\bg_\br_\ba_\bm_\bm_\be_\br_\b'_\bs _\bR_\be_\bf_\be_\br_\be_\bn_\bc_\be _\bM_\ba_\bn_\bu_\ba_\bl. |
13936 | |
13937 | N\bNA\bAM\bME\bE |
13938 | i\bin\bnt\btr\bro\bo - introduction to system calls and error numbers |
13939 | |
13940 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
13941 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<e\ber\brr\brn\bno\bo.\b.h\bh>\b> |
13942 | |
13943 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
13944 | The manual pages in section 2 provide an overview of the system calls, |
13945 | their error returns, and other common definitions and concepts. |
13946 | |
13947 | D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS |
13948 | Nearly all of the system calls provide an error number via the identifier |
13949 | errno, which expands to an addressable location of type _\bi_\bn_\bt. The address |
13950 | of _\be_\br_\br_\bn_\bo in each thread is guaranteed to be unique for the lifetime of |
13951 | the thread. Applications must use _\be_\br_\br_\bn_\bo as defined in <_\be_\br_\br_\bn_\bo_\b._\bh> and not |
13952 | attempt to use a custom definition. |
13953 | |
13954 | When a system call detects an error, it returns an integer value |
13955 | indicating failure (usually -1) and sets the variable _\be_\br_\br_\bn_\bo accordingly. |
13956 | (This allows interpretation of the failure on receiving a -1 and to take |
13957 | action accordingly.) Successful calls never set _\be_\br_\br_\bn_\bo; once set, it |
13958 | remains until another error occurs. It should only be examined after an |
13959 | error. Note that a number of system calls overload the meanings of these |
13960 | error numbers, and that the meanings must be interpreted according to the |
13961 | type and circumstances of the call. |
13962 | |
13963 | The following is a complete list of the errors and their names as given |
13964 | in <_\bs_\by_\bs_\b/_\be_\br_\br_\bn_\bo_\b._\bh>. |
13965 | |
13966 | 0 _\bU_\bn_\bd_\be_\bf_\bi_\bn_\be_\bd _\be_\br_\br_\bo_\br_\b: _\b0. Not used. |
13967 | |
13968 | 1 EPERM _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bp_\be_\br_\bm_\bi_\bt_\bt_\be_\bd. An attempt was made to perform an |
13969 | operation limited to processes with appropriate privileges or to |
13970 | the owner of a file or other resources. |
13971 | |
13972 | 2 ENOENT _\bN_\bo _\bs_\bu_\bc_\bh _\bf_\bi_\bl_\be _\bo_\br _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. A component of a specified pathname |
13973 | did not exist, or the pathname was an empty string. |
13974 | |
13975 | 3 ESRCH _\bN_\bo _\bs_\bu_\bc_\bh _\bp_\br_\bo_\bc_\be_\bs_\bs. No process could be found which corresponds to |
13976 | the given process ID. |
13977 | |
13978 | 4 EINTR _\bI_\bn_\bt_\be_\br_\br_\bu_\bp_\bt_\be_\bd _\bs_\by_\bs_\bt_\be_\bm _\bc_\ba_\bl_\bl. An asynchronous signal (such as SIGINT |
13979 | or SIGQUIT) was caught by the thread during the execution of an |
13980 | interruptible function. If the signal handler performs a normal |
13981 | return, the interrupted function call will seem to have returned |
13982 | the error condition. |
13983 | |
13984 | 5 EIO _\bI_\bn_\bp_\bu_\bt_\b/_\bo_\bu_\bt_\bp_\bu_\bt _\be_\br_\br_\bo_\br. Some physical input or output error occurred. |
13985 | This error will not be reported until a subsequent operation on |
13986 | the same file descriptor and may be lost (overwritten) by any |
13987 | subsequent errors. |
13988 | |
13989 | 6 ENXIO _\bD_\be_\bv_\bi_\bc_\be _\bn_\bo_\bt _\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\bd. Input or output on a special file referred |
13990 | to a device that did not exist, or made a request beyond the |
13991 | limits of the device. This error may also occur when, for |
13992 | example, a tape drive is not online or no disk pack is loaded on |
13993 | a drive. |
13994 | |
13995 | 7 E2BIG _\bA_\br_\bg_\bu_\bm_\be_\bn_\bt _\bl_\bi_\bs_\bt _\bt_\bo_\bo _\bl_\bo_\bn_\bg. The number of bytes used for the argument |
13996 | and environment list of the new process exceeded the limit NCARGS |
13997 | (specified in <_\bs_\by_\bs_\b/_\bp_\ba_\br_\ba_\bm_\b._\bh>). |
13998 | |
13999 | 8 ENOEXEC _\bE_\bx_\be_\bc _\bf_\bo_\br_\bm_\ba_\bt _\be_\br_\br_\bo_\br. A request was made to execute a file that, |
14000 | although it has the appropriate permissions, was not in the |
14001 | format required for an executable file. |
14002 | |
14003 | 9 EBADF _\bB_\ba_\bd _\bf_\bi_\bl_\be _\bd_\be_\bs_\bc_\br_\bi_\bp_\bt_\bo_\br. A file descriptor argument was out of range, |
14004 | referred to no open file, or a read (write) request was made to a |
14005 | file that was only open for writing (reading). |
14006 | |
14007 | 10 ECHILD _\bN_\bo _\bc_\bh_\bi_\bl_\bd _\bp_\br_\bo_\bc_\be_\bs_\bs_\be_\bs. A wait(2) or waitpid(2) function was |
14008 | executed by a process that had no existing or unwaited-for child |
14009 | processes. |
14010 | |
14011 | 11 EDEADLK _\bR_\be_\bs_\bo_\bu_\br_\bc_\be _\bd_\be_\ba_\bd_\bl_\bo_\bc_\bk _\ba_\bv_\bo_\bi_\bd_\be_\bd. An attempt was made to lock a |
14012 | system resource that would have resulted in a deadlock situation. |
14013 | |
14014 | 12 ENOMEM _\bC_\ba_\bn_\bn_\bo_\bt _\ba_\bl_\bl_\bo_\bc_\ba_\bt_\be _\bm_\be_\bm_\bo_\br_\by. The new process image required more |
14015 | memory than was allowed by the hardware or by system-imposed |
14016 | memory management constraints. A lack of swap space is normally |
14017 | temporary; however, a lack of core is not. Soft limits may be |
14018 | increased to their corresponding hard limits. |
14019 | |
14020 | 13 EACCES _\bP_\be_\br_\bm_\bi_\bs_\bs_\bi_\bo_\bn _\bd_\be_\bn_\bi_\be_\bd. An attempt was made to access a file in a |
14021 | way forbidden by its file access permissions. |
14022 | |
14023 | 14 EFAULT _\bB_\ba_\bd _\ba_\bd_\bd_\br_\be_\bs_\bs. The system detected an invalid address in |
14024 | attempting to use an argument of a call. |
14025 | |
14026 | 15 ENOTBLK _\bB_\bl_\bo_\bc_\bk _\bd_\be_\bv_\bi_\bc_\be _\br_\be_\bq_\bu_\bi_\br_\be_\bd. A block device operation was attempted |
14027 | on a non-block device or file. |
14028 | |
14029 | 16 EBUSY _\bD_\be_\bv_\bi_\bc_\be _\bb_\bu_\bs_\by. An attempt to use a system resource which was in |
14030 | use at the time in a manner which would have conflicted with the |
14031 | request. |
14032 | |
14033 | 17 EEXIST _\bF_\bi_\bl_\be _\be_\bx_\bi_\bs_\bt_\bs. An existing file was mentioned in an inappropriate |
14034 | context, for instance, as the new link name in a link(2) |
14035 | function. |
14036 | |
14037 | 18 EXDEV _\bC_\br_\bo_\bs_\bs_\b-_\bd_\be_\bv_\bi_\bc_\be _\bl_\bi_\bn_\bk. A hard link to a file on another file system |
14038 | was attempted. |
14039 | |
14040 | 19 ENODEV _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd _\bb_\by _\bd_\be_\bv_\bi_\bc_\be. An attempt was made to apply |
14041 | an inappropriate function to a device, for example, trying to |
14042 | read a write-only device such as a printer. |
14043 | |
14044 | 20 ENOTDIR _\bN_\bo_\bt _\ba _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. A component of the specified pathname |
14045 | existed, but it was not a directory, when a directory was |
14046 | expected. |
14047 | |
14048 | 21 EISDIR _\bI_\bs _\ba _\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by. An attempt was made to open a directory with |
14049 | write mode specified. |
14050 | |
14051 | 22 EINVAL _\bI_\bn_\bv_\ba_\bl_\bi_\bd _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt. Some invalid argument was supplied. (For |
14052 | example, specifying an undefined signal to a signal(3) or kill(2) |
14053 | function). |
14054 | |
14055 | 23 ENFILE _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bo_\bp_\be_\bn _\bf_\bi_\bl_\be_\bs _\bi_\bn _\bs_\by_\bs_\bt_\be_\bm. Maximum number of file |
14056 | descriptors allowable on the system has been reached and a |
14057 | request for an open cannot be satisfied until at least one has |
14058 | been closed. The sysctl(3) variable _\bk_\be_\br_\bn_\b._\bm_\ba_\bx_\bf_\bi_\bl_\be_\bs contains the |
14059 | current limit. |
14060 | |
14061 | 24 EMFILE _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bo_\bp_\be_\bn _\bf_\bi_\bl_\be_\bs. The maximum number of file descriptors |
14062 | allowable for this process has been reached and a request for an |
14063 | open cannot be satisfied until at least one has been closed. |
14064 | getdtablesize(3) will obtain the current limit. |
14065 | |
14066 | 25 ENOTTY _\bI_\bn_\ba_\bp_\bp_\br_\bo_\bp_\br_\bi_\ba_\bt_\be _\bi_\bo_\bc_\bt_\bl _\bf_\bo_\br _\bd_\be_\bv_\bi_\bc_\be. A control function (see |
14067 | ioctl(2)) was attempted for a file or special device for which |
14068 | the operation was inappropriate. |
14069 | |
14070 | 26 ETXTBSY _\bT_\be_\bx_\bt _\bf_\bi_\bl_\be _\bb_\bu_\bs_\by. An attempt was made either to execute a pure |
14071 | procedure (shared text) file which was open for writing by |
14072 | another process, or to open with write access a pure procedure |
14073 | file that is currently being executed. |
14074 | |
14075 | 27 EFBIG _\bF_\bi_\bl_\be _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be. The size of a file exceeded the maximum. (The |
14076 | system-wide maximum file size is 2**63 bytes. Each file system |
14077 | may impose a lower limit for files contained within it.) |
14078 | |
14079 | 28 ENOSPC _\bN_\bo _\bs_\bp_\ba_\bc_\be _\bl_\be_\bf_\bt _\bo_\bn _\bd_\be_\bv_\bi_\bc_\be. A write(2) to an ordinary file, the |
14080 | creation of a directory or symbolic link, or the creation of a |
14081 | directory entry failed because no more disk blocks were available |
14082 | on the file system, or the allocation of an inode for a newly |
14083 | created file failed because no more inodes were available on the |
14084 | file system. |
14085 | |
14086 | 29 ESPIPE _\bI_\bl_\bl_\be_\bg_\ba_\bl _\bs_\be_\be_\bk. An lseek(2) function was issued on a socket, pipe |
14087 | or FIFO. |
14088 | |
14089 | 30 EROFS _\bR_\be_\ba_\bd_\b-_\bo_\bn_\bl_\by _\bf_\bi_\bl_\be _\bs_\by_\bs_\bt_\be_\bm. An attempt was made to modify a file or |
14090 | create a directory on a file system that was read-only at the |
14091 | time. |
14092 | |
14093 | 31 EMLINK _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bl_\bi_\bn_\bk_\bs. The maximum allowable number of hard links to a |
14094 | single file has been exceeded (see pathconf(2) for how to obtain |
14095 | this value). |
14096 | |
14097 | 32 EPIPE _\bB_\br_\bo_\bk_\be_\bn _\bp_\bi_\bp_\be. A write on a pipe, socket or FIFO for which there |
14098 | is no process to read the data. |
14099 | |
14100 | 33 EDOM _\bN_\bu_\bm_\be_\br_\bi_\bc_\ba_\bl _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt _\bo_\bu_\bt _\bo_\bf _\bd_\bo_\bm_\ba_\bi_\bn. A numerical input argument was |
14101 | outside the defined domain of the mathematical function. |
14102 | |
14103 | 34 ERANGE _\bR_\be_\bs_\bu_\bl_\bt _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be. A result of the function was too large to fit |
14104 | in the available space (perhaps exceeded precision). |
14105 | |
14106 | 35 EAGAIN _\bR_\be_\bs_\bo_\bu_\br_\bc_\be _\bt_\be_\bm_\bp_\bo_\br_\ba_\br_\bi_\bl_\by _\bu_\bn_\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. This is a temporary condition |
14107 | and later calls to the same routine may complete normally. |
14108 | |
14109 | 36 EINPROGRESS _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bw _\bi_\bn _\bp_\br_\bo_\bg_\br_\be_\bs_\bs. An operation that takes a long |
14110 | time to complete (such as a connect(2)) was attempted on a non- |
14111 | blocking object (see fcntl(2)). |
14112 | |
14113 | 37 EALREADY _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\ba_\bl_\br_\be_\ba_\bd_\by _\bi_\bn _\bp_\br_\bo_\bg_\br_\be_\bs_\bs. An operation was attempted on |
14114 | a non-blocking object that already had an operation in progress. |
14115 | |
14116 | 38 ENOTSOCK _\bS_\bo_\bc_\bk_\be_\bt _\bo_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bo_\bn _\bn_\bo_\bn_\b-_\bs_\bo_\bc_\bk_\be_\bt. Self-explanatory. |
14117 | |
14118 | 39 EDESTADDRREQ _\bD_\be_\bs_\bt_\bi_\bn_\ba_\bt_\bi_\bo_\bn _\ba_\bd_\bd_\br_\be_\bs_\bs _\br_\be_\bq_\bu_\bi_\br_\be_\bd. A required address was |
14119 | omitted from an operation on a socket. |
14120 | |
14121 | 40 EMSGSIZE _\bM_\be_\bs_\bs_\ba_\bg_\be _\bt_\bo_\bo _\bl_\bo_\bn_\bg. A message sent on a socket was larger than |
14122 | the internal message buffer or some other network limit. |
14123 | |
14124 | 41 EPROTOTYPE _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bw_\br_\bo_\bn_\bg _\bt_\by_\bp_\be _\bf_\bo_\br _\bs_\bo_\bc_\bk_\be_\bt. A protocol was specified |
14125 | that does not support the semantics of the socket type requested. |
14126 | For example, you cannot use the Internet UDP protocol with type |
14127 | SOCK_STREAM. |
14128 | |
14129 | 42 ENOPROTOOPT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bn_\bo_\bt _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. A bad option or level was |
14130 | specified in a getsockopt(2) or setsockopt(2) call. |
14131 | |
14132 | 43 EPROTONOSUPPORT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The protocol has not been |
14133 | configured into the system or no implementation for it exists. |
14134 | |
14135 | 44 ESOCKTNOSUPPORT _\bS_\bo_\bc_\bk_\be_\bt _\bt_\by_\bp_\be _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The support for the socket |
14136 | type has not been configured into the system or no implementation |
14137 | for it exists. |
14138 | |
14139 | 45 EOPNOTSUPP _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The attempted operation is not |
14140 | supported for the type of object referenced. Usually this occurs |
14141 | when a file descriptor refers to a file or socket that cannot |
14142 | support this operation, for example, trying to _\ba_\bc_\bc_\be_\bp_\bt a |
14143 | connection on a datagram socket. |
14144 | |
14145 | 46 EPFNOSUPPORT _\bP_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bf_\ba_\bm_\bi_\bl_\by _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The protocol family has |
14146 | not been configured into the system or no implementation for it |
14147 | exists. |
14148 | |
14149 | 47 EAFNOSUPPORT _\bA_\bd_\bd_\br_\be_\bs_\bs _\bf_\ba_\bm_\bi_\bl_\by _\bn_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd _\bb_\by _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl _\bf_\ba_\bm_\bi_\bl_\by. An |
14150 | address incompatible with the requested protocol was used. For |
14151 | example, you shouldn't necessarily expect to be able to use NS |
14152 | addresses with Internet protocols. |
14153 | |
14154 | 48 EADDRINUSE _\bA_\bd_\bd_\br_\be_\bs_\bs _\ba_\bl_\br_\be_\ba_\bd_\by _\bi_\bn _\bu_\bs_\be. Only one usage of each address is |
14155 | normally permitted. |
14156 | |
14157 | 49 EADDRNOTAVAIL _\bC_\ba_\bn_\b'_\bt _\ba_\bs_\bs_\bi_\bg_\bn _\br_\be_\bq_\bu_\be_\bs_\bt_\be_\bd _\ba_\bd_\bd_\br_\be_\bs_\bs. Normally results from an |
14158 | attempt to create a socket with an address not on this machine. |
14159 | |
14160 | 50 ENETDOWN _\bN_\be_\bt_\bw_\bo_\br_\bk _\bi_\bs _\bd_\bo_\bw_\bn. A socket operation encountered a dead |
14161 | network. |
14162 | |
14163 | 51 ENETUNREACH _\bN_\be_\bt_\bw_\bo_\br_\bk _\bi_\bs _\bu_\bn_\br_\be_\ba_\bc_\bh_\ba_\bb_\bl_\be. A socket operation was attempted |
14164 | to an unreachable network. |
14165 | |
14166 | 52 ENETRESET _\bN_\be_\bt_\bw_\bo_\br_\bk _\bd_\br_\bo_\bp_\bp_\be_\bd _\bc_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\bo_\bn _\br_\be_\bs_\be_\bt. The host you were |
14167 | connected to crashed and rebooted. |
14168 | |
14169 | 53 ECONNABORTED _\bS_\bo_\bf_\bt_\bw_\ba_\br_\be _\bc_\ba_\bu_\bs_\be_\bd _\bc_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\ba_\bb_\bo_\br_\bt. A connection abort was |
14170 | caused internal to your host machine. |
14171 | |
14172 | 54 ECONNRESET _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\br_\be_\bs_\be_\bt _\bb_\by _\bp_\be_\be_\br. A connection was forcibly closed |
14173 | by a peer. This normally results from a loss of the connection |
14174 | on the remote socket due to a timeout or a reboot. |
14175 | |
14176 | 55 ENOBUFS _\bN_\bo _\bb_\bu_\bf_\bf_\be_\br _\bs_\bp_\ba_\bc_\be _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. An operation on a socket or pipe |
14177 | was not performed because the system lacked sufficient buffer |
14178 | space or because a queue was full. |
14179 | |
14180 | 56 EISCONN _\bS_\bo_\bc_\bk_\be_\bt _\bi_\bs _\ba_\bl_\br_\be_\ba_\bd_\by _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd. A connect(2) request was made on |
14181 | an already connected socket; or, a sendto(2) or sendmsg(2) |
14182 | request on a connected socket specified a destination when |
14183 | already connected. |
14184 | |
14185 | 57 ENOTCONN _\bS_\bo_\bc_\bk_\be_\bt _\bi_\bs _\bn_\bo_\bt _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd. A request to send or receive data |
14186 | was disallowed because the socket was not connected and (when |
14187 | sending on a datagram socket) no address was supplied. |
14188 | |
14189 | 58 ESHUTDOWN _\bC_\ba_\bn_\b'_\bt _\bs_\be_\bn_\bd _\ba_\bf_\bt_\be_\br _\bs_\bo_\bc_\bk_\be_\bt _\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn. A request to send data was |
14190 | disallowed because the socket had already been shut down with a |
14191 | previous shutdown(2) call. |
14192 | |
14193 | 59 ETOOMANYREFS _\bT_\bo_\bo _\bm_\ba_\bn_\by _\br_\be_\bf_\be_\br_\be_\bn_\bc_\be_\bs_\b: _\bc_\ba_\bn_\b'_\bt _\bs_\bp_\bl_\bi_\bc_\be. Not used in OpenBSD. |
14194 | |
14195 | 60 ETIMEDOUT _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bt_\bi_\bm_\be_\bd _\bo_\bu_\bt. A connect(2) or send(2) request failed |
14196 | because the connected party did not properly respond after a |
14197 | period of time. (The timeout period is dependent on the |
14198 | communication protocol.) |
14199 | |
14200 | 61 ECONNREFUSED _\bC_\bo_\bn_\bn_\be_\bc_\bt_\bi_\bo_\bn _\br_\be_\bf_\bu_\bs_\be_\bd. No connection could be made because |
14201 | the target machine actively refused it. This usually results |
14202 | from trying to connect to a service that is inactive on the |
14203 | foreign host. |
14204 | |
14205 | 62 ELOOP _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bl_\be_\bv_\be_\bl_\bs _\bo_\bf _\bs_\by_\bm_\bb_\bo_\bl_\bi_\bc _\bl_\bi_\bn_\bk_\bs. A path name lookup involved |
14206 | more than 32 (SYMLOOP_MAX) symbolic links. |
14207 | |
14208 | 63 ENAMETOOLONG _\bF_\bi_\bl_\be _\bn_\ba_\bm_\be _\bt_\bo_\bo _\bl_\bo_\bn_\bg. A component of a pathname exceeded |
14209 | 255 (NAME_MAX) characters, or an entire pathname (including the |
14210 | terminating NUL) exceeded 1024 (PATH_MAX) bytes. |
14211 | |
14212 | 64 EHOSTDOWN _\bH_\bo_\bs_\bt _\bi_\bs _\bd_\bo_\bw_\bn. A socket operation failed because the |
14213 | destination host was down. |
14214 | |
14215 | 65 EHOSTUNREACH _\bN_\bo _\br_\bo_\bu_\bt_\be _\bt_\bo _\bh_\bo_\bs_\bt. A socket operation was attempted to an |
14216 | unreachable host. |
14217 | |
14218 | 66 ENOTEMPTY _\bD_\bi_\br_\be_\bc_\bt_\bo_\br_\by _\bn_\bo_\bt _\be_\bm_\bp_\bt_\by. A directory with entries other than `.' |
14219 | and `..' was supplied to a remove directory or rename call. |
14220 | |
14221 | 67 EPROCLIM _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bp_\br_\bo_\bc_\be_\bs_\bs_\be_\bs. |
14222 | |
14223 | 68 EUSERS _\bT_\bo_\bo _\bm_\ba_\bn_\by _\bu_\bs_\be_\br_\bs. The quota system ran out of table entries. |
14224 | |
14225 | 69 EDQUOT _\bD_\bi_\bs_\bc _\bq_\bu_\bo_\bt_\ba _\be_\bx_\bc_\be_\be_\bd_\be_\bd. A write(2) to an ordinary file, the |
14226 | creation of a directory or symbolic link, or the creation of a |
14227 | directory entry failed because the user's quota of disk blocks |
14228 | was exhausted, or the allocation of an inode for a newly created |
14229 | file failed because the user's quota of inodes was exhausted. |
14230 | |
14231 | 70 ESTALE _\bS_\bt_\ba_\bl_\be _\bN_\bF_\bS _\bf_\bi_\bl_\be _\bh_\ba_\bn_\bd_\bl_\be. An attempt was made to access an open |
14232 | file on an NFS filesystem which is now unavailable as referenced |
14233 | by the file descriptor. This may indicate the file was deleted |
14234 | on the NFS server or some other catastrophic event occurred. |
14235 | |
14236 | 72 EBADRPC _\bR_\bP_\bC _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bs _\bb_\ba_\bd. Exchange of rpc(3) information was |
14237 | unsuccessful. |
14238 | |
14239 | 73 ERPCMISMATCH _\bR_\bP_\bC _\bv_\be_\br_\bs_\bi_\bo_\bn _\bw_\br_\bo_\bn_\bg. The version of rpc(3) on the remote |
14240 | peer is not compatible with the local version. |
14241 | |
14242 | 74 EPROGUNAVAIL _\bR_\bP_\bC _\bp_\br_\bo_\bg_\b. _\bn_\bo_\bt _\ba_\bv_\ba_\bi_\bl. The requested rpc(3) program is not |
14243 | registered on the remote host. |
14244 | |
14245 | 75 EPROGMISMATCH _\bP_\br_\bo_\bg_\br_\ba_\bm _\bv_\be_\br_\bs_\bi_\bo_\bn _\bw_\br_\bo_\bn_\bg. The requested version of the |
14246 | rpc(3) program is not available on the remote host. |
14247 | |
14248 | 76 EPROCUNAVAIL _\bB_\ba_\bd _\bp_\br_\bo_\bc_\be_\bd_\bu_\br_\be _\bf_\bo_\br _\bp_\br_\bo_\bg_\br_\ba_\bm. An rpc(3) call was attempted |
14249 | for a procedure which doesn't exist in the remote program. |
14250 | |
14251 | 77 ENOLCK _\bN_\bo _\bl_\bo_\bc_\bk_\bs _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be. A system-imposed limit on the number of |
14252 | simultaneous file locks was reached. |
14253 | |
14254 | 78 ENOSYS _\bF_\bu_\bn_\bc_\bt_\bi_\bo_\bn _\bn_\bo_\bt _\bi_\bm_\bp_\bl_\be_\bm_\be_\bn_\bt_\be_\bd. Attempted a system call that is not |
14255 | available on this system. |
14256 | |
14257 | 79 EFTYPE _\bI_\bn_\ba_\bp_\bp_\br_\bo_\bp_\br_\bi_\ba_\bt_\be _\bf_\bi_\bl_\be _\bt_\by_\bp_\be _\bo_\br _\bf_\bo_\br_\bm_\ba_\bt. The file contains invalid |
14258 | data or set to invalid modes. |
14259 | |
14260 | 80 EAUTH _\bA_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\be_\br_\br_\bo_\br. Attempted to use an invalid authentication |
14261 | ticket to mount a NFS filesystem. |
14262 | |
14263 | 81 ENEEDAUTH _\bN_\be_\be_\bd _\ba_\bu_\bt_\bh_\be_\bn_\bt_\bi_\bc_\ba_\bt_\bo_\br. An authentication ticket must be |
14264 | obtained before the given NFS filesystem may be mounted. |
14265 | |
14266 | 82 EIPSEC _\bI_\bP_\bs_\be_\bc _\bp_\br_\bo_\bc_\be_\bs_\bs_\bi_\bn_\bg _\bf_\ba_\bi_\bl_\bu_\br_\be. IPsec subsystem error. Not used in |
14267 | OpenBSD. |
14268 | |
14269 | 83 ENOATTR _\bA_\bt_\bt_\br_\bi_\bb_\bu_\bt_\be _\bn_\bo_\bt _\bf_\bo_\bu_\bn_\bd. A UFS Extended Attribute is not found for |
14270 | the specified pathname. |
14271 | |
14272 | 84 EILSEQ _\bI_\bl_\bl_\be_\bg_\ba_\bl _\bb_\by_\bt_\be _\bs_\be_\bq_\bu_\be_\bn_\bc_\be. An illegal sequence of bytes was used |
14273 | when using wide characters. |
14274 | |
14275 | 85 ENOMEDIUM _\bN_\bo _\bm_\be_\bd_\bi_\bu_\bm _\bf_\bo_\bu_\bn_\bd. Attempted to use a removable media device |
14276 | with no medium present. |
14277 | |
14278 | 86 EMEDIUMTYPE _\bW_\br_\bo_\bn_\bg _\bm_\be_\bd_\bi_\bu_\bm _\bt_\by_\bp_\be. Attempted to use a removable media |
14279 | device with incorrect or incompatible medium. |
14280 | |
14281 | 87 EOVERFLOW _\bV_\ba_\bl_\bu_\be _\bt_\bo_\bo _\bl_\ba_\br_\bg_\be _\bt_\bo _\bb_\be _\bs_\bt_\bo_\br_\be_\bd _\bi_\bn _\bd_\ba_\bt_\ba _\bt_\by_\bp_\be. A numerical |
14282 | result of the function was too large to be stored in the caller |
14283 | provided space. |
14284 | |
14285 | 88 ECANCELED _\bO_\bp_\be_\br_\ba_\bt_\bi_\bo_\bn _\bc_\ba_\bn_\bc_\be_\bl_\be_\bd. The requested operation was canceled. |
14286 | |
14287 | 89 EIDRM _\bI_\bd_\be_\bn_\bt_\bi_\bf_\bi_\be_\br _\br_\be_\bm_\bo_\bv_\be_\bd. An IPC identifier was removed while the |
14288 | current thread was waiting on it. |
14289 | |
14290 | 90 ENOMSG _\bN_\bo _\bm_\be_\bs_\bs_\ba_\bg_\be _\bo_\bf _\bd_\be_\bs_\bi_\br_\be_\bd _\bt_\by_\bp_\be. An IPC message queue does not |
14291 | contain a message of the desired type, or a message catalog does |
14292 | not contain the requested message. |
14293 | |
14294 | 91 ENOTSUP _\bN_\bo_\bt _\bs_\bu_\bp_\bp_\bo_\br_\bt_\be_\bd. The operation has requested an unsupported |
14295 | value. |
14296 | |
14297 | D\bDE\bEF\bFI\bIN\bNI\bIT\bTI\bIO\bON\bNS\bS |
14298 | Process |
14299 | A process is a collection of one or more threads, plus the |
14300 | resources shared by those threads such as process ID, address |
14301 | space, user IDs and group IDs, and root directory and current |
14302 | working directory. |
14303 | |
14304 | Process ID |
14305 | Each active process in the system is uniquely identified by a |
14306 | non-negative integer called a process ID. The range of this ID |
14307 | is from 1 to 32766. |
14308 | |
14309 | Parent Process ID |
14310 | A new process is created by a currently active process; (see |
14311 | fork(2)). The parent process ID of a process is initially the |
14312 | process ID of its creator. If the creating process exits, the |
14313 | parent process ID of each child is set to the ID of a system |
14314 | process, init(8). |
14315 | |
14316 | Process Group |
14317 | Each active process is a member of a process group that is |
14318 | identified by a non-negative integer called the process group ID. |
14319 | This is the process ID of the group leader. This grouping |
14320 | permits the signaling of related processes (see termios(4)) and |
14321 | the job control mechanisms of csh(1). |
14322 | |
14323 | Session |
14324 | A session is a set of one or more process groups. A session is |
14325 | created by a successful call to setsid(2), which causes the |
14326 | caller to become the only member of the only process group in the |
14327 | new session. |
14328 | |
14329 | Session Leader |
14330 | A process that has created a new session by a successful call to |
14331 | setsid(2), is known as a session leader. Only a session leader |
14332 | may acquire a terminal as its controlling terminal (see |
14333 | termios(4)). |
14334 | |
14335 | Controlling Process |
14336 | A session leader with a controlling terminal is a controlling |
14337 | process. |
14338 | |
14339 | Controlling Terminal |
14340 | A terminal that is associated with a session is known as the |
14341 | controlling terminal for that session and its members. |
14342 | |
14343 | Terminal Process Group ID |
14344 | A terminal may be acquired by a session leader as its controlling |
14345 | terminal. Once a terminal is associated with a session, any of |
14346 | the process groups within the session may be placed into the |
14347 | foreground by setting the terminal process group ID to the ID of |
14348 | the process group. This facility is used to arbitrate between |
14349 | multiple jobs contending for the same terminal; (see csh(1) and |
14350 | tty(4)). |
14351 | |
14352 | Orphaned Process Group |
14353 | A process group is considered to be _\bo_\br_\bp_\bh_\ba_\bn_\be_\bd if it is not under |
14354 | the control of a job control shell. More precisely, a process |
14355 | group is orphaned when none of its members has a parent process |
14356 | that is in the same session as the group, but is in a different |
14357 | process group. Note that when a process exits, the parent |
14358 | process for its children is changed to be init(8), which is in a |
14359 | separate session. Not all members of an orphaned process group |
14360 | are necessarily orphaned processes (those whose creating process |
14361 | has exited). The process group of a session leader is orphaned |
14362 | by definition. |
14363 | |
14364 | Thread A thread is a preemptively scheduled flow of control within a |
14365 | process, with its own set of register values, floating point |
14366 | environment, thread ID, signal mask, pending signal set, |
14367 | alternate signal stack, thread control block address, resource |
14368 | utilization, errno variable location, and values for thread- |
14369 | specific keys. A process initially has just one thread, a |
14370 | duplicate of the thread in the parent process that created this |
14371 | process. |
14372 | |
14373 | Real User ID and Real Group ID |
14374 | Each user on the system is identified by a positive integer |
14375 | termed the real user ID. |
14376 | |
14377 | Each user is also a member of one or more groups. One of these |
14378 | groups is distinguished from others and used in implementing |
14379 | accounting facilities. The positive integer corresponding to |
14380 | this distinguished group is termed the real group ID. |
14381 | |
14382 | All processes have a real user ID and real group ID. These are |
14383 | initialized from the equivalent attributes of the process that |
14384 | created it. |
14385 | |
14386 | Effective User ID, Effective Group ID, and Group Access List |
14387 | Access to system resources is governed by two values: the |
14388 | effective user ID, and the group access list. The first member |
14389 | of the group access list is also known as the effective group ID. |
14390 | (In POSIX.1, the group access list is known as the set of |
14391 | supplementary group IDs, and it is unspecified whether the |
14392 | effective group ID is a member of the list.) |
14393 | |
14394 | The effective user ID and effective group ID are initially the |
14395 | process's real user ID and real group ID respectively. Either |
14396 | may be modified through execution of a set-user-ID or set-group- |
14397 | ID file (possibly by one of its ancestors) (see execve(2)). By |
14398 | convention, the effective group ID (the first member of the group |
14399 | access list) is duplicated, so that the execution of a set-group- |
14400 | ID program does not result in the loss of the original (real) |
14401 | group ID. |
14402 | |
14403 | The group access list is a set of group IDs used only in |
14404 | determining resource accessibility. Access checks are performed |
14405 | as described below in ``File Access Permissions''. |
14406 | |
14407 | Saved Set User ID and Saved Set Group ID |
14408 | When a process executes a new file, the effective user ID is set |
14409 | to the owner of the file if the file is set-user-ID, and the |
14410 | effective group ID (first element of the group access list) is |
14411 | set to the group of the file if the file is set-group-ID. The |
14412 | effective user ID of the process is then recorded as the saved |
14413 | set-user-ID, and the effective group ID of the process is |
14414 | recorded as the saved set-group-ID. These values may be used to |
14415 | regain those values as the effective user or group ID after |
14416 | reverting to the real ID (see setuid(2)). (In POSIX.1, the saved |
14417 | set-user-ID and saved set-group-ID are optional, and are used in |
14418 | setuid and setgid, but this does not work as desired for the |
14419 | superuser.) |
14420 | |
14421 | Superuser |
14422 | A process is recognized as a _\bs_\bu_\bp_\be_\br_\bu_\bs_\be_\br process and is granted |
14423 | special privileges if its effective user ID is 0. |
14424 | |
14425 | Special Processes |
14426 | The processes with process IDs of 0 and 1 are special. Process 0 |
14427 | is the scheduler. Process 1 is the initialization process |
14428 | init(8), and is the ancestor of every other process in the |
14429 | system. It is used to control the process structure. |
14430 | |
14431 | Descriptor |
14432 | An integer assigned by the system when a file is referenced by |
14433 | open(2) or dup(2), or when a socket is created by pipe(2), |
14434 | socket(2) or socketpair(2), which uniquely identifies an access |
14435 | path to that file or socket from a given process or any of its |
14436 | children. |
14437 | |
14438 | File Name |
14439 | Names consisting of up to 255 (NAME_MAX) characters may be used |
14440 | to name an ordinary file, special file, or directory. |
14441 | |
14442 | These characters may be arbitrary eight-bit values, excluding 0 |
14443 | (NUL) and the ASCII code for `/' (slash). |
14444 | |
14445 | Note that it is generally unwise to use `*', `?', `[' or `]' as |
14446 | part of file names because of the special meaning attached to |
14447 | these characters by the shell. |
14448 | |
14449 | Note also that NAME_MAX is an upper limit fixed by the kernel, |
14450 | meant to be used for sizing buffers. Some filesystems may have |
14451 | additional restrictions. These can be queried using pathconf(2) |
14452 | and fpathconf(2). |
14453 | |
14454 | Path Name |
14455 | A path name is a NUL-terminated character string starting with an |
14456 | optional slash `/', followed by zero or more directory names |
14457 | separated by slashes, optionally followed by a file name. The |
14458 | total length of a path name must be less than 1024 (PATH_MAX) |
14459 | characters. Additional restrictions may apply, depending upon |
14460 | the filesystem, to be queried with pathconf(2) or fpathconf(2) if |
14461 | needed. |
14462 | |
14463 | If a path name begins with a slash, the path search begins at the |
14464 | _\br_\bo_\bo_\bt directory. Otherwise, the search begins from the current |
14465 | working directory. A slash by itself names the root directory. |
14466 | An empty pathname is invalid. |
14467 | |
14468 | Directory |
14469 | A directory is a special type of file that contains entries that |
14470 | are references to other files. Directory entries are called |
14471 | links. By convention, a directory contains at least two links, |
14472 | `.' and `..', referred to as _\bd_\bo_\bt and _\bd_\bo_\bt_\b-_\bd_\bo_\bt respectively. Dot |
14473 | refers to the directory itself and dot-dot refers to its parent |
14474 | directory. |
14475 | |
14476 | Root Directory and Current Working Directory |
14477 | Each process has associated with it a concept of a root directory |
14478 | and a current working directory for the purpose of resolving path |
14479 | name searches. A process's root directory need not be the root |
14480 | directory of the root file system. |
14481 | |
14482 | File Access Permissions |
14483 | Every file in the file system has a set of access permissions. |
14484 | These permissions are used in determining whether a process may |
14485 | perform a requested operation on the file (such as opening a file |
14486 | for writing). Access permissions are established at the time a |
14487 | file is created. They may be changed at some later time through |
14488 | the chmod(2) call. |
14489 | |
14490 | File access is broken down according to whether a file may be: |
14491 | read, written, or executed. Directory files use the execute |
14492 | permission to control if the directory may be searched. |
14493 | |
14494 | File access permissions are interpreted by the system as they |
14495 | apply to three different classes of users: the owner of the file, |
14496 | those users in the file's group, anyone else. Every file has an |
14497 | independent set of access permissions for each of these classes. |
14498 | When an access check is made, the system decides if permission |
14499 | should be granted by checking the access information applicable |
14500 | to the caller. |
14501 | |
14502 | Read, write, and execute/search permissions on a file are granted |
14503 | to a process if: |
14504 | |
14505 | The process's effective user ID is that of the superuser. (Note: |
14506 | even the superuser cannot execute a non-executable file.) |
14507 | |
14508 | The process's effective user ID matches the user ID of the owner |
14509 | of the file and the owner permissions allow the access. |
14510 | |
14511 | The process's effective user ID does not match the user ID of the |
14512 | owner of the file, and either the process's effective group ID |
14513 | matches the group ID of the file, or the group ID of the file is |
14514 | in the process's group access list, and the group permissions |
14515 | allow the access. |
14516 | |
14517 | Neither the effective user ID nor effective group ID and group |
14518 | access list of the process match the corresponding user ID and |
14519 | group ID of the file, but the permissions for ``other users'' |
14520 | allow access. |
14521 | |
14522 | Otherwise, permission is denied. |
14523 | |
14524 | Sockets and Address Families |
14525 | A socket is an endpoint for communication between processes. |
14526 | Each socket has queues for sending and receiving data. |
14527 | |
14528 | Sockets are typed according to their communications properties. |
14529 | These properties include whether messages sent and received at a |
14530 | socket require the name of the partner, whether communication is |
14531 | reliable, the format used in naming message recipients, etc. |
14532 | |
14533 | Each instance of the system supports some collection of socket |
14534 | types; consult socket(2) for more information about the types |
14535 | available and their properties. |
14536 | |
14537 | Each instance of the system supports some number of sets of |
14538 | communications protocols. Each protocol set supports addresses |
14539 | of a certain format. An Address Family is the set of addresses |
14540 | for a specific group of protocols. Each socket has an address |
14541 | chosen from the address family in which the socket was created. |
14542 | |
14543 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
14544 | intro(3), perror(3) |
14545 | |
14546 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
14547 | An k\bkq\bqu\bue\beu\bue\be manual page appeared in Version 6 AT&T UNIX. |
14548 | |
14549 | N\bNA\bAM\bME\bE |
14550 | i\bio\boc\bct\btl\bl - control device |
14551 | |
14552 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
14553 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/i\bio\boc\bct\btl\bl.\b.h\bh>\b> |
14554 | |
14555 | _\bi_\bn_\bt |
14556 | i\bio\boc\bct\btl\bl(_\bi_\bn_\bt _\bd, _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bl_\bo_\bn_\bg _\br_\be_\bq_\bu_\be_\bs_\bt, _\b._\b._\b.); |
14557 | |
14558 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
14559 | The i\bio\boc\bct\btl\bl() function manipulates the underlying device parameters of |
14560 | special files. In particular, many operating characteristics of |
14561 | character special files (e.g., terminals) may be controlled with i\bio\boc\bct\btl\bl() |
14562 | requests. |
14563 | |
14564 | The argument _\bd must be an open file descriptor. The third argument is |
14565 | called _\ba_\br_\bg and contains additional information needed by this device to |
14566 | perform the requested function. _\ba_\br_\bg is either an int or a pointer to a |
14567 | device-specific data structure, depending upon the given _\br_\be_\bq_\bu_\be_\bs_\bt. |
14568 | |
14569 | An k\bkq\bqu\bue\beu\bue\be _\br_\be_\bq_\bu_\be_\bs_\bt has encoded in it whether the argument is an ``in'' |
14570 | parameter or ``out'' parameter, and the size of the third argument (_\ba_\br_\bg) |
14571 | in bytes. Macros and defines used in specifying an ioctl _\br_\be_\bq_\bu_\be_\bs_\bt are |
14572 | located in the file <_\bs_\by_\bs_\b/_\bi_\bo_\bc_\bt_\bl_\b._\bh>. |
14573 | |
14574 | G\bGE\bEN\bNE\bER\bRI\bIC\bC I\bIO\bOC\bCT\bTL\bLS\bS |
14575 | Some ioctls are applicable to any file descriptor. These include: |
14576 | |
14577 | FIOCLEX |
14578 | Set close-on-exec flag. The file will be closed when exec(3) is |
14579 | invoked. |
14580 | |
14581 | FIONCLEX |
14582 | Clear close-on-exec flag. The file will remain open across |
14583 | exec(3). |
14584 | |
14585 | Some generic ioctls are not implemented for all types of file |
14586 | descriptors. These include: |
14587 | |
14588 | FIONREAD _\bi_\bn_\bt _\b* |
14589 | Get the number of bytes that are immediately available for |
14590 | reading. |
14591 | |
14592 | FIONBIO _\bi_\bn_\bt _\b* |
14593 | Set non-blocking I/O mode if the argument is non-zero. In non- |
14594 | blocking mode, read(2) or write(2) calls return -1 and set _\be_\br_\br_\bn_\bo |
14595 | to EAGAIN immediately when no data is available. |
14596 | |
14597 | FIOASYNC _\bi_\bn_\bt _\b* |
14598 | Set asynchronous I/O mode if the argument is non-zero. In |
14599 | asynchronous mode, the process or process group specified by |
14600 | FIOSETOWN will start receiving SIGIO signals when data is |
14601 | available. The SIGIO signal will be delivered when data is |
14602 | available on the file descriptor. |
14603 | |
14604 | FIOSETOWN, FIOGETOWN _\bi_\bn_\bt _\b* |
14605 | Set/get the process or the process group (if negative) that |
14606 | should receive SIGIO signals when data is available. |
14607 | |
14608 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
14609 | If an error has occurred, a value of -1 is returned and _\be_\br_\br_\bn_\bo is set to |
14610 | indicate the error. |
14611 | |
14612 | E\bER\bRR\bRO\bOR\bRS\bS |
14613 | i\bio\boc\bct\btl\bl() will fail if: |
14614 | |
14615 | [EBADF] _\bd is not a valid descriptor. |
14616 | |
14617 | [ENOTTY] _\bd is not associated with a character special device. |
14618 | |
14619 | [ENOTTY] The specified request does not apply to the kind of |
14620 | object that the descriptor _\bd references. |
14621 | |
14622 | [EINVAL] _\br_\be_\bq_\bu_\be_\bs_\bt or _\ba_\br_\bg is not valid. |
14623 | |
14624 | [EFAULT] _\ba_\br_\bg points outside the process's allocated address |
14625 | space. |
14626 | |
14627 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
14628 | cdio(1), chio(1), mt(1), execve(2), fcntl(2), intro(4), tty(4) |
14629 | |
14630 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
14631 | An i\bio\boc\bct\btl\bl() function call appeared in Version 7 AT&T UNIX. |
14632 | |
14633 | N\bNA\bAM\bME\bE |
14634 | i\bis\bss\bse\bet\btu\bug\bgi\bid\bd - is current executable running setuid or setgid |
14635 | |
14636 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
14637 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
14638 | |
14639 | _\bi_\bn_\bt |
14640 | i\bis\bss\bse\bet\btu\bug\bgi\bid\bd(_\bv_\bo_\bi_\bd); |
14641 | |
14642 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
14643 | The i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() function returns 1 if the process was made setuid or |
14644 | setgid as the result of the last or other previous e\bex\bxe\bec\bcv\bve\be() system calls. |
14645 | Otherwise it returns 0. |
14646 | |
14647 | This system call exists so that library routines (inside libtermlib, |
14648 | libc, or other libraries) can guarantee safe behavior when used inside |
14649 | setuid or setgid programs. Some library routines may be passed |
14650 | insufficient information and hence not know whether the current program |
14651 | was started setuid or setgid because higher level calling code may have |
14652 | made changes to the uid, euid, gid, or egid. Hence these low-level |
14653 | library routines are unable to determine if they are being run with |
14654 | elevated or normal privileges. |
14655 | |
14656 | In particular, it is wise to use this call to determine if a pathname |
14657 | returned from a g\bge\bet\bte\ben\bnv\bv() call may safely be used to o\bop\bpe\ben\bn() the specified |
14658 | file. Quite often this is not wise because the status of the effective |
14659 | uid is not known. |
14660 | |
14661 | The i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() system call's result is unaffected by calls to s\bse\bet\btu\bui\bid\bd(), |
14662 | s\bse\bet\btg\bgi\bid\bd(), or other such calls. In case of a f\bfo\bor\brk\bk(), the child process |
14663 | inherits the same status. |
14664 | |
14665 | The status of i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() is only affected by e\bex\bxe\bec\bcv\bve\be(). If a child |
14666 | process executes a new executable file, a new issetugid status will be |
14667 | determined. This status is based on the existing process's uid, euid, |
14668 | gid, and egid permissions and on the modes of the executable file. If |
14669 | the new executable file modes are setuid or setgid, or if the existing |
14670 | process is executing the new image with uid != euid or gid != egid, the |
14671 | new process will be considered issetugid. |
14672 | |
14673 | E\bER\bRR\bRO\bOR\bRS\bS |
14674 | The i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() function is always successful, and no return value is |
14675 | reserved to indicate an error. |
14676 | |
14677 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
14678 | execve(2), setegid(2), seteuid(2), setgid(2), setuid(2), getenv(3) |
14679 | |
14680 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
14681 | The i\bis\bss\bse\bet\btu\bug\bgi\bid\bd() function call first appeared in OpenBSD 2.0. |
14682 | |
14683 | N\bNA\bAM\bME\bE |
14684 | k\bkq\bqu\bue\beu\bue\be, k\bke\bev\bve\ben\bnt\bt - kernel event notification mechanism |
14685 | |
14686 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
14687 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
14688 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/e\bev\bve\ben\bnt\bt.\b.h\bh>\b> |
14689 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
14690 | |
14691 | _\bi_\bn_\bt |
14692 | k\bkq\bqu\bue\beu\bue\be(_\bv_\bo_\bi_\bd); |
14693 | |
14694 | _\bi_\bn_\bt |
14695 | k\bke\bev\bve\ben\bnt\bt(_\bi_\bn_\bt _\bk_\bq, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs, |
14696 | _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\be_\bv_\be_\bn_\bt_\bs, |
14697 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
14698 | |
14699 | E\bEV\bV_\b_S\bSE\bET\bT(_\b&_\bk_\be_\bv, _\bi_\bd_\be_\bn_\bt, _\bf_\bi_\bl_\bt_\be_\br, _\bf_\bl_\ba_\bg_\bs, _\bf_\bf_\bl_\ba_\bg_\bs, _\bd_\ba_\bt_\ba, _\bu_\bd_\ba_\bt_\ba); |
14700 | |
14701 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
14702 | k\bkq\bqu\bue\beu\bue\be() provides a generic method of notifying the user when an event |
14703 | happens or a condition holds, based on the results of small pieces of |
14704 | kernel code termed ``filters''. A kevent is identified by the (ident, |
14705 | filter) pair; there may only be one unique kevent per kqueue. |
14706 | |
14707 | The filter is executed upon the initial registration of a kevent in order |
14708 | to detect whether a preexisting condition is present, and is also |
14709 | executed whenever an event is passed to the filter for evaluation. If |
14710 | the filter determines that the condition should be reported, then the |
14711 | kevent is placed on the kqueue for the user to retrieve. |
14712 | |
14713 | The filter is also run when the user attempts to retrieve the kevent from |
14714 | the kqueue. If the filter indicates that the condition that triggered |
14715 | the event no longer holds, the kevent is removed from the kqueue and is |
14716 | not returned. |
14717 | |
14718 | Multiple events which trigger the filter do not result in multiple |
14719 | kevents being placed on the kqueue; instead, the filter will aggregate |
14720 | the events into a single struct kevent. Calling c\bcl\blo\bos\bse\be() on a file |
14721 | descriptor will remove any kevents that reference the descriptor. |
14722 | |
14723 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a descriptor. The |
14724 | queue is not inherited by a child created with fork(2). Similarly, |
14725 | kqueues cannot be passed across UNIX-domain sockets. |
14726 | |
14727 | k\bke\bev\bve\ben\bnt\bt() is used to register events with the queue, and return any |
14728 | pending events to the user. _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt is a pointer to an array of |
14729 | _\bk_\be_\bv_\be_\bn_\bt structures, as defined in <_\bs_\by_\bs_\b/_\be_\bv_\be_\bn_\bt_\b._\bh>. All changes contained in |
14730 | the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt are applied before any pending events are read from the |
14731 | queue. _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs gives the size of _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt. _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt is a pointer to |
14732 | an array of kevent structures. _\bn_\be_\bv_\be_\bn_\bt_\bs determines the size of _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
14733 | When _\bn_\be_\bv_\be_\bn_\bt_\bs is zero, k\bke\bev\bve\ben\bnt\bt() will return immediately even if there is a |
14734 | _\bt_\bi_\bm_\be_\bo_\bu_\bt specified unlike select(2). If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it |
14735 | specifies a maximum interval to wait for an event, which will be |
14736 | interpreted as a struct timespec. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, k\bke\bev\bve\ben\bnt\bt() |
14737 | waits indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
14738 | non-null, pointing to a zero-valued _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc structure. The same array |
14739 | may be used for the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
14740 | |
14741 | E\bEV\bV_\b_S\bSE\bET\bT() is a macro which is provided for ease of initializing a kevent |
14742 | structure. |
14743 | |
14744 | The _\bk_\be_\bv_\be_\bn_\bt structure is defined as: |
14745 | |
14746 | struct kevent { |
14747 | uintptr_t ident; /* identifier for this event */ |
14748 | short filter; /* filter for event */ |
14749 | u_short flags; /* action flags for kqueue */ |
14750 | u_int fflags; /* filter flag value */ |
14751 | quad_t data; /* filter data value */ |
14752 | void *udata; /* opaque user data identifier */ |
14753 | }; |
14754 | |
14755 | The fields of struct kevent are: |
14756 | |
14757 | ident Value used to identify this event. The exact interpretation |
14758 | is determined by the attached filter, but often is a file |
14759 | descriptor. |
14760 | |
14761 | filter Identifies the kernel filter used to process this event. The |
14762 | pre-defined system filters are described below. |
14763 | |
14764 | flags Actions to perform on the event. |
14765 | |
14766 | fflags Filter-specific flags. |
14767 | |
14768 | data Filter-specific data value. |
14769 | |
14770 | udata Opaque user-defined value passed through the kernel unchanged. |
14771 | |
14772 | The _\bf_\bl_\ba_\bg_\bs field can contain the following values: |
14773 | |
14774 | EV_ADD Adds the event to the kqueue. Re-adding an existing event |
14775 | will modify the parameters of the original event, and not |
14776 | result in a duplicate entry. Adding an event |
14777 | automatically enables it, unless overridden by the |
14778 | EV_DISABLE flag. |
14779 | |
14780 | EV_ENABLE Permit k\bke\bev\bve\ben\bnt\bt() to return the event if it is triggered. |
14781 | |
14782 | EV_DISABLE Disable the event so k\bke\bev\bve\ben\bnt\bt() will not return it. The |
14783 | filter itself is not disabled. |
14784 | |
14785 | EV_DELETE Removes the event from the kqueue. Events which are |
14786 | attached to file descriptors are automatically deleted on |
14787 | the last close of the descriptor. |
14788 | |
14789 | EV_ONESHOT Causes the event to return only the first occurrence of |
14790 | the filter being triggered. After the user retrieves the |
14791 | event from the kqueue, it is deleted. |
14792 | |
14793 | EV_CLEAR After the event is retrieved by the user, its state is |
14794 | reset. This is useful for filters which report state |
14795 | transitions instead of the current state. Note that some |
14796 | filters may automatically set this flag internally. |
14797 | |
14798 | EV_EOF Filters may set this flag to indicate filter-specific EOF |
14799 | condition. |
14800 | |
14801 | EV_ERROR See _\bR_\bE_\bT_\bU_\bR_\bN _\bV_\bA_\bL_\bU_\bE_\bS below. |
14802 | |
14803 | The predefined system filters are listed below. Arguments may be passed |
14804 | to and from the filter via the _\bf_\bf_\bl_\ba_\bg_\bs and _\bd_\ba_\bt_\ba fields in the kevent |
14805 | structure. |
14806 | |
14807 | EVFILT_READ Takes a descriptor as the identifier, and returns whenever |
14808 | there is data available to read. The behavior of the |
14809 | filter is slightly different depending on the descriptor |
14810 | type. |
14811 | |
14812 | Sockets |
14813 | Sockets which have previously been passed to l\bli\bis\bst\bte\ben\bn() |
14814 | return when there is an incoming connection pending. |
14815 | _\bd_\ba_\bt_\ba contains the size of the listen backlog. |
14816 | |
14817 | Other socket descriptors return when there is data to |
14818 | be read, subject to the SO_RCVLOWAT value of the |
14819 | socket buffer. This may be overridden with a per- |
14820 | filter low water mark at the time the filter is added |
14821 | by setting the NOTE_LOWAT flag in _\bf_\bf_\bl_\ba_\bg_\bs, and |
14822 | specifying the new low water mark in _\bd_\ba_\bt_\ba. On return, |
14823 | _\bd_\ba_\bt_\ba contains the number of bytes in the socket |
14824 | buffer. |
14825 | |
14826 | If the read direction of the socket has shutdown, then |
14827 | the filter also sets EV_EOF in _\bf_\bl_\ba_\bg_\bs, and returns the |
14828 | socket error (if any) in _\bf_\bf_\bl_\ba_\bg_\bs. It is possible for |
14829 | EOF to be returned (indicating the connection is gone) |
14830 | while there is still data pending in the socket |
14831 | buffer. |
14832 | |
14833 | Vnodes |
14834 | Returns when the file pointer is not at the end of |
14835 | file. _\bd_\ba_\bt_\ba contains the offset from current position |
14836 | to end of file, and may be negative. If NOTE_EOF is |
14837 | set in _\bf_\bf_\bl_\ba_\bg_\bs, k\bke\bev\bve\ben\bnt\bt() will also return when the file |
14838 | pointer is at the end of file. The end of file |
14839 | condition is indicated by the presence of NOTE_EOF in |
14840 | _\bf_\bf_\bl_\ba_\bg_\bs on return. |
14841 | |
14842 | Fifos, Pipes |
14843 | Returns when there is data to read; _\bd_\ba_\bt_\ba contains the |
14844 | number of bytes available. |
14845 | |
14846 | When the last writer disconnects, the filter will set |
14847 | EV_EOF in _\bf_\bl_\ba_\bg_\bs. This may be cleared by passing in |
14848 | EV_CLEAR, at which point the filter will resume |
14849 | waiting for data to become available before returning. |
14850 | |
14851 | BPF devices |
14852 | Returns when the BPF buffer is full, the BPF timeout |
14853 | has expired, or when the BPF has ``immediate mode'' |
14854 | enabled and there is any data to read; _\bd_\ba_\bt_\ba contains |
14855 | the number of bytes available. |
14856 | |
14857 | EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever |
14858 | it is possible to write to the descriptor. For sockets, |
14859 | pipes, and FIFOs, _\bd_\ba_\bt_\ba will contain the amount of space |
14860 | remaining in the write buffer. The filter will set EV_EOF |
14861 | when the reader disconnects, and for the FIFO case, this |
14862 | may be cleared by use of EV_CLEAR. Note that this filter |
14863 | is not supported for vnodes or BPF devices. |
14864 | |
14865 | For sockets, the low water mark and socket error handling |
14866 | is identical to the EVFILT_READ case. |
14867 | |
14868 | EVFILT_VNODE Takes a file descriptor as the identifier and the events |
14869 | to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when one or more of |
14870 | the requested events occurs on the descriptor. The events |
14871 | to monitor are: |
14872 | |
14873 | NOTE_DELETE u\bun\bnl\bli\bin\bnk\bk() was called on the file referenced |
14874 | by the descriptor. |
14875 | |
14876 | NOTE_WRITE A write occurred on the file referenced by |
14877 | the descriptor. |
14878 | |
14879 | NOTE_EXTEND The file referenced by the descriptor was |
14880 | extended. |
14881 | |
14882 | NOTE_TRUNCATE The file referenced by the descriptor was |
14883 | truncated. |
14884 | |
14885 | NOTE_ATTRIB The file referenced by the descriptor had |
14886 | its attributes changed. |
14887 | |
14888 | NOTE_LINK The link count on the file changed. |
14889 | |
14890 | NOTE_RENAME The file referenced by the descriptor was |
14891 | renamed. |
14892 | |
14893 | NOTE_REVOKE Access to the file was revoked via |
14894 | revoke(2) or the underlying file system was |
14895 | unmounted. |
14896 | |
14897 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
14898 | filter. |
14899 | |
14900 | EVFILT_PROC Takes the process ID to monitor as the identifier and the |
14901 | events to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when the |
14902 | process performs one or more of the requested events. If |
14903 | a process can normally see another process, it can attach |
14904 | an event to it. The events to monitor are: |
14905 | |
14906 | NOTE_EXIT The process has exited. The exit status |
14907 | will be stored in _\bd_\ba_\bt_\ba in the same format |
14908 | as the status set by wait(2). |
14909 | |
14910 | NOTE_FORK The process has called f\bfo\bor\brk\bk(). |
14911 | |
14912 | NOTE_EXEC The process has executed a new process |
14913 | via execve(2) or similar call. |
14914 | |
14915 | NOTE_TRACK Follow a process across f\bfo\bor\brk\bk() calls. |
14916 | The parent process will return with |
14917 | NOTE_FORK set in the _\bf_\bf_\bl_\ba_\bg_\bs field, while |
14918 | the child process will return with |
14919 | NOTE_CHILD set in _\bf_\bf_\bl_\ba_\bg_\bs and the parent |
14920 | PID in _\bd_\ba_\bt_\ba. |
14921 | |
14922 | NOTE_TRACKERR This flag is returned if the system was |
14923 | unable to attach an event to the child |
14924 | process, usually due to resource |
14925 | limitations. |
14926 | |
14927 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
14928 | filter. |
14929 | |
14930 | EVFILT_SIGNAL Takes the signal number to monitor as the identifier and |
14931 | returns when the given signal is delivered to the process. |
14932 | This coexists with the s\bsi\big\bgn\bna\bal\bl() and s\bsi\big\bga\bac\bct\bti\bio\bon\bn() |
14933 | facilities, and has a lower precedence. The filter will |
14934 | record all attempts to deliver a signal to a process, even |
14935 | if the signal has been marked as SIG_IGN. Event |
14936 | notification happens after normal signal delivery |
14937 | processing. _\bd_\ba_\bt_\ba returns the number of times the signal |
14938 | has occurred since the last call to k\bke\bev\bve\ben\bnt\bt(). This filter |
14939 | automatically sets the EV_CLEAR flag internally. |
14940 | |
14941 | EVFILT_TIMER Establishes an arbitrary timer identified by _\bi_\bd_\be_\bn_\bt. When |
14942 | adding a timer, _\bd_\ba_\bt_\ba specifies the timeout period in |
14943 | milliseconds. The timer will be periodic unless |
14944 | EV_ONESHOT is specified. On return, _\bd_\ba_\bt_\ba contains the |
14945 | number of times the timeout has expired since the last |
14946 | call to k\bke\bev\bve\ben\bnt\bt(). This filter automatically sets the |
14947 | EV_CLEAR flag internally. |
14948 | |
14949 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
14950 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a file descriptor. |
14951 | If there was an error creating the kernel event queue, a value of -1 is |
14952 | returned and errno set. |
14953 | |
14954 | k\bke\bev\bve\ben\bnt\bt() returns the number of events placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, up to the |
14955 | value given by _\bn_\be_\bv_\be_\bn_\bt_\bs. If an error occurs while processing an element |
14956 | of the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and there is enough room in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, then the |
14957 | event will be placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt with EV_ERROR set in _\bf_\bl_\ba_\bg_\bs and the |
14958 | system error in _\bd_\ba_\bt_\ba. Otherwise, -1 will be returned, and errno will be |
14959 | set to indicate the error condition. If the time limit expires, then |
14960 | k\bke\bev\bve\ben\bnt\bt() returns 0. |
14961 | |
14962 | E\bER\bRR\bRO\bOR\bRS\bS |
14963 | The k\bkq\bqu\bue\beu\bue\be() function fails if: |
14964 | |
14965 | [ENOMEM] The kernel failed to allocate enough memory for the |
14966 | kernel queue. |
14967 | |
14968 | [EMFILE] The per-process descriptor table is full. |
14969 | |
14970 | [ENFILE] The system file table is full. |
14971 | |
14972 | The k\bke\bev\bve\ben\bnt\bt() function fails if: |
14973 | |
14974 | [EACCES] The process does not have permission to register a |
14975 | filter. |
14976 | |
14977 | [EFAULT] There was an error reading or writing the _\bk_\be_\bv_\be_\bn_\bt |
14978 | structure. |
14979 | |
14980 | [EBADF] The specified descriptor is invalid. |
14981 | |
14982 | [EINTR] A signal was delivered before the timeout expired and |
14983 | before any events were placed on the kqueue for |
14984 | return. |
14985 | |
14986 | [EINVAL] The specified time limit or filter is invalid. |
14987 | |
14988 | [ENOENT] The event could not be found to be modified or |
14989 | deleted. |
14990 | |
14991 | [ENOMEM] No memory was available to register the event. |
14992 | |
14993 | [ESRCH] The specified process to attach to does not exist. |
14994 | |
14995 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
14996 | poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) |
14997 | |
14998 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
14999 | The k\bkq\bqu\bue\beu\bue\be() and k\bke\bev\bve\ben\bnt\bt() functions first appeared in FreeBSD 4.1. |
15000 | |
15001 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
15002 | The k\bkq\bqu\bue\beu\bue\be() system and this manual page were written by Jonathan Lemon |
15003 | <_\bj_\bl_\be_\bm_\bo_\bn_\b@_\bF_\br_\be_\be_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
15004 | |
15005 | B\bBU\bUG\bGS\bS |
15006 | It is currently not possible to watch FIFOs or AIO that reside on |
15007 | anything but a UFS file system. Watching a vnode is possible on UFS, NFS |
15008 | and MS-DOS file systems. |
15009 | |
15010 | The _\bt_\bi_\bm_\be_\bo_\bu_\bt value is limited to 24 hours; longer timeouts will be |
15011 | silently reinterpreted as 24 hours. |
15012 | |
15013 | N\bNA\bAM\bME\bE |
15014 | k\bki\bil\bll\bl - send signal to a process |
15015 | |
15016 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
15017 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
15018 | |
15019 | _\bi_\bn_\bt |
15020 | k\bki\bil\bll\bl(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bi_\bn_\bt _\bs_\bi_\bg); |
15021 | |
15022 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
15023 | The k\bki\bil\bll\bl() function sends the signal given by _\bs_\bi_\bg to _\bp_\bi_\bd, a process or a |
15024 | group of processes. _\bs_\bi_\bg may be one of the signals specified in |
15025 | sigaction(2) or it may be 0, in which case error checking is performed |
15026 | but no signal is actually sent. This can be used to check the validity |
15027 | of _\bp_\bi_\bd. |
15028 | |
15029 | For a process to have permission to send a signal to a process designated |
15030 | by _\bp_\bi_\bd, the real or effective user ID of the receiving process must match |
15031 | that of the sending process or the user must have appropriate privileges |
15032 | (such as given by a set-user-ID program or the user is the superuser). A |
15033 | single exception is the signal SIGCONT, which may always be sent to any |
15034 | process with the same session ID as the caller. |
15035 | |
15036 | If _\bp_\bi_\bd is greater than zero: |
15037 | _\bs_\bi_\bg is sent to the process whose ID is equal to _\bp_\bi_\bd. |
15038 | |
15039 | If _\bp_\bi_\bd is zero: |
15040 | _\bs_\bi_\bg is sent to all processes whose group ID is equal to the |
15041 | process group ID of the sender, and for which the process has |
15042 | permission; this is a variant of killpg(3). |
15043 | |
15044 | If _\bp_\bi_\bd is -1: |
15045 | If the user has superuser privileges, the signal is sent to all |
15046 | processes excluding system processes and the process sending the |
15047 | signal. If the user is not the superuser, the signal is sent to |
15048 | all processes with the same uid as the user excluding the process |
15049 | sending the signal. No error is returned if any process could be |
15050 | signaled. |
15051 | |
15052 | Setuid and setgid processes are dealt with slightly differently. For the |
15053 | non-root user, to prevent attacks against such processes, some signal |
15054 | deliveries are not permitted and return the error EPERM. The following |
15055 | signals are allowed through to this class of processes: SIGKILL, SIGINT, |
15056 | SIGTERM, SIGSTOP, SIGTTIN, SIGTTOU, SIGTSTP, SIGHUP, SIGUSR1, SIGUSR2. |
15057 | |
15058 | For compatibility with System V, if the process number is negative but |
15059 | not -1, the signal is sent to all processes whose process group ID is |
15060 | equal to the absolute value of the process number. This is a variant of |
15061 | killpg(3). |
15062 | |
15063 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
15064 | Upon successful completion, the value 0 is returned; otherwise the |
15065 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
15066 | error. |
15067 | |
15068 | E\bER\bRR\bRO\bOR\bRS\bS |
15069 | k\bki\bil\bll\bl() will fail and no signal will be sent if: |
15070 | |
15071 | [EINVAL] _\bs_\bi_\bg is not a valid signal number. |
15072 | |
15073 | [ESRCH] No process can be found corresponding to that |
15074 | specified by _\bp_\bi_\bd. |
15075 | |
15076 | [EPERM] The sending process is not the superuser and its |
15077 | effective user ID does not match the effective user ID |
15078 | of the receiving process. When signaling a process |
15079 | group, this error is returned if none of the members |
15080 | of the group could be signaled. |
15081 | |
15082 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
15083 | getpgrp(2), getpid(2), sigaction(2), killpg(3), raise(3) |
15084 | |
15085 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
15086 | The k\bki\bil\bll\bl() function is expected to conform to IEEE Std 1003.1-2008 |
15087 | (``POSIX.1''). |
15088 | |
15089 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
15090 | The k\bki\bil\bll\bl() system call first appeared in Version 3 AT&T UNIX. The _\bs_\bi_\bg |
15091 | argument was introduced in Version 4 AT&T UNIX. |
15092 | |
15093 | B\bBU\bUG\bGS\bS |
15094 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that k\bki\bil\bll\bl(_\b0, _\bs_\bi_\bg) should |
15095 | send signal _\bs_\bi_\bg to the calling process, but OpenBSD doesn't do so for |
15096 | historical reasons. |
15097 | |
15098 | N\bNA\bAM\bME\bE |
15099 | k\bkq\bqu\bue\beu\bue\be, k\bke\bev\bve\ben\bnt\bt - kernel event notification mechanism |
15100 | |
15101 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
15102 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
15103 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/e\bev\bve\ben\bnt\bt.\b.h\bh>\b> |
15104 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
15105 | |
15106 | _\bi_\bn_\bt |
15107 | k\bkq\bqu\bue\beu\bue\be(_\bv_\bo_\bi_\bd); |
15108 | |
15109 | _\bi_\bn_\bt |
15110 | k\bke\bev\bve\ben\bnt\bt(_\bi_\bn_\bt _\bk_\bq, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs, |
15111 | _\bs_\bt_\br_\bu_\bc_\bt _\bk_\be_\bv_\be_\bn_\bt _\b*_\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, _\bi_\bn_\bt _\bn_\be_\bv_\be_\bn_\bt_\bs, |
15112 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
15113 | |
15114 | E\bEV\bV_\b_S\bSE\bET\bT(_\b&_\bk_\be_\bv, _\bi_\bd_\be_\bn_\bt, _\bf_\bi_\bl_\bt_\be_\br, _\bf_\bl_\ba_\bg_\bs, _\bf_\bf_\bl_\ba_\bg_\bs, _\bd_\ba_\bt_\ba, _\bu_\bd_\ba_\bt_\ba); |
15115 | |
15116 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
15117 | k\bkq\bqu\bue\beu\bue\be() provides a generic method of notifying the user when an event |
15118 | happens or a condition holds, based on the results of small pieces of |
15119 | kernel code termed ``filters''. A kevent is identified by the (ident, |
15120 | filter) pair; there may only be one unique kevent per kqueue. |
15121 | |
15122 | The filter is executed upon the initial registration of a kevent in order |
15123 | to detect whether a preexisting condition is present, and is also |
15124 | executed whenever an event is passed to the filter for evaluation. If |
15125 | the filter determines that the condition should be reported, then the |
15126 | kevent is placed on the kqueue for the user to retrieve. |
15127 | |
15128 | The filter is also run when the user attempts to retrieve the kevent from |
15129 | the kqueue. If the filter indicates that the condition that triggered |
15130 | the event no longer holds, the kevent is removed from the kqueue and is |
15131 | not returned. |
15132 | |
15133 | Multiple events which trigger the filter do not result in multiple |
15134 | kevents being placed on the kqueue; instead, the filter will aggregate |
15135 | the events into a single struct kevent. Calling c\bcl\blo\bos\bse\be() on a file |
15136 | descriptor will remove any kevents that reference the descriptor. |
15137 | |
15138 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a descriptor. The |
15139 | queue is not inherited by a child created with fork(2). Similarly, |
15140 | kqueues cannot be passed across UNIX-domain sockets. |
15141 | |
15142 | k\bke\bev\bve\ben\bnt\bt() is used to register events with the queue, and return any |
15143 | pending events to the user. _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt is a pointer to an array of |
15144 | _\bk_\be_\bv_\be_\bn_\bt structures, as defined in <_\bs_\by_\bs_\b/_\be_\bv_\be_\bn_\bt_\b._\bh>. All changes contained in |
15145 | the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt are applied before any pending events are read from the |
15146 | queue. _\bn_\bc_\bh_\ba_\bn_\bg_\be_\bs gives the size of _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt. _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt is a pointer to |
15147 | an array of kevent structures. _\bn_\be_\bv_\be_\bn_\bt_\bs determines the size of _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
15148 | When _\bn_\be_\bv_\be_\bn_\bt_\bs is zero, k\bke\bev\bve\ben\bnt\bt() will return immediately even if there is a |
15149 | _\bt_\bi_\bm_\be_\bo_\bu_\bt specified unlike select(2). If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it |
15150 | specifies a maximum interval to wait for an event, which will be |
15151 | interpreted as a struct timespec. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, k\bke\bev\bve\ben\bnt\bt() |
15152 | waits indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
15153 | non-null, pointing to a zero-valued _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc structure. The same array |
15154 | may be used for the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt. |
15155 | |
15156 | E\bEV\bV_\b_S\bSE\bET\bT() is a macro which is provided for ease of initializing a kevent |
15157 | structure. |
15158 | |
15159 | The _\bk_\be_\bv_\be_\bn_\bt structure is defined as: |
15160 | |
15161 | struct kevent { |
15162 | uintptr_t ident; /* identifier for this event */ |
15163 | short filter; /* filter for event */ |
15164 | u_short flags; /* action flags for kqueue */ |
15165 | u_int fflags; /* filter flag value */ |
15166 | quad_t data; /* filter data value */ |
15167 | void *udata; /* opaque user data identifier */ |
15168 | }; |
15169 | |
15170 | The fields of struct kevent are: |
15171 | |
15172 | ident Value used to identify this event. The exact interpretation |
15173 | is determined by the attached filter, but often is a file |
15174 | descriptor. |
15175 | |
15176 | filter Identifies the kernel filter used to process this event. The |
15177 | pre-defined system filters are described below. |
15178 | |
15179 | flags Actions to perform on the event. |
15180 | |
15181 | fflags Filter-specific flags. |
15182 | |
15183 | data Filter-specific data value. |
15184 | |
15185 | udata Opaque user-defined value passed through the kernel unchanged. |
15186 | |
15187 | The _\bf_\bl_\ba_\bg_\bs field can contain the following values: |
15188 | |
15189 | EV_ADD Adds the event to the kqueue. Re-adding an existing event |
15190 | will modify the parameters of the original event, and not |
15191 | result in a duplicate entry. Adding an event |
15192 | automatically enables it, unless overridden by the |
15193 | EV_DISABLE flag. |
15194 | |
15195 | EV_ENABLE Permit k\bke\bev\bve\ben\bnt\bt() to return the event if it is triggered. |
15196 | |
15197 | EV_DISABLE Disable the event so k\bke\bev\bve\ben\bnt\bt() will not return it. The |
15198 | filter itself is not disabled. |
15199 | |
15200 | EV_DELETE Removes the event from the kqueue. Events which are |
15201 | attached to file descriptors are automatically deleted on |
15202 | the last close of the descriptor. |
15203 | |
15204 | EV_ONESHOT Causes the event to return only the first occurrence of |
15205 | the filter being triggered. After the user retrieves the |
15206 | event from the kqueue, it is deleted. |
15207 | |
15208 | EV_CLEAR After the event is retrieved by the user, its state is |
15209 | reset. This is useful for filters which report state |
15210 | transitions instead of the current state. Note that some |
15211 | filters may automatically set this flag internally. |
15212 | |
15213 | EV_EOF Filters may set this flag to indicate filter-specific EOF |
15214 | condition. |
15215 | |
15216 | EV_ERROR See _\bR_\bE_\bT_\bU_\bR_\bN _\bV_\bA_\bL_\bU_\bE_\bS below. |
15217 | |
15218 | The predefined system filters are listed below. Arguments may be passed |
15219 | to and from the filter via the _\bf_\bf_\bl_\ba_\bg_\bs and _\bd_\ba_\bt_\ba fields in the kevent |
15220 | structure. |
15221 | |
15222 | EVFILT_READ Takes a descriptor as the identifier, and returns whenever |
15223 | there is data available to read. The behavior of the |
15224 | filter is slightly different depending on the descriptor |
15225 | type. |
15226 | |
15227 | Sockets |
15228 | Sockets which have previously been passed to l\bli\bis\bst\bte\ben\bn() |
15229 | return when there is an incoming connection pending. |
15230 | _\bd_\ba_\bt_\ba contains the size of the listen backlog. |
15231 | |
15232 | Other socket descriptors return when there is data to |
15233 | be read, subject to the SO_RCVLOWAT value of the |
15234 | socket buffer. This may be overridden with a per- |
15235 | filter low water mark at the time the filter is added |
15236 | by setting the NOTE_LOWAT flag in _\bf_\bf_\bl_\ba_\bg_\bs, and |
15237 | specifying the new low water mark in _\bd_\ba_\bt_\ba. On return, |
15238 | _\bd_\ba_\bt_\ba contains the number of bytes in the socket |
15239 | buffer. |
15240 | |
15241 | If the read direction of the socket has shutdown, then |
15242 | the filter also sets EV_EOF in _\bf_\bl_\ba_\bg_\bs, and returns the |
15243 | socket error (if any) in _\bf_\bf_\bl_\ba_\bg_\bs. It is possible for |
15244 | EOF to be returned (indicating the connection is gone) |
15245 | while there is still data pending in the socket |
15246 | buffer. |
15247 | |
15248 | Vnodes |
15249 | Returns when the file pointer is not at the end of |
15250 | file. _\bd_\ba_\bt_\ba contains the offset from current position |
15251 | to end of file, and may be negative. If NOTE_EOF is |
15252 | set in _\bf_\bf_\bl_\ba_\bg_\bs, k\bke\bev\bve\ben\bnt\bt() will also return when the file |
15253 | pointer is at the end of file. The end of file |
15254 | condition is indicated by the presence of NOTE_EOF in |
15255 | _\bf_\bf_\bl_\ba_\bg_\bs on return. |
15256 | |
15257 | Fifos, Pipes |
15258 | Returns when there is data to read; _\bd_\ba_\bt_\ba contains the |
15259 | number of bytes available. |
15260 | |
15261 | When the last writer disconnects, the filter will set |
15262 | EV_EOF in _\bf_\bl_\ba_\bg_\bs. This may be cleared by passing in |
15263 | EV_CLEAR, at which point the filter will resume |
15264 | waiting for data to become available before returning. |
15265 | |
15266 | BPF devices |
15267 | Returns when the BPF buffer is full, the BPF timeout |
15268 | has expired, or when the BPF has ``immediate mode'' |
15269 | enabled and there is any data to read; _\bd_\ba_\bt_\ba contains |
15270 | the number of bytes available. |
15271 | |
15272 | EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever |
15273 | it is possible to write to the descriptor. For sockets, |
15274 | pipes, and FIFOs, _\bd_\ba_\bt_\ba will contain the amount of space |
15275 | remaining in the write buffer. The filter will set EV_EOF |
15276 | when the reader disconnects, and for the FIFO case, this |
15277 | may be cleared by use of EV_CLEAR. Note that this filter |
15278 | is not supported for vnodes or BPF devices. |
15279 | |
15280 | For sockets, the low water mark and socket error handling |
15281 | is identical to the EVFILT_READ case. |
15282 | |
15283 | EVFILT_VNODE Takes a file descriptor as the identifier and the events |
15284 | to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when one or more of |
15285 | the requested events occurs on the descriptor. The events |
15286 | to monitor are: |
15287 | |
15288 | NOTE_DELETE u\bun\bnl\bli\bin\bnk\bk() was called on the file referenced |
15289 | by the descriptor. |
15290 | |
15291 | NOTE_WRITE A write occurred on the file referenced by |
15292 | the descriptor. |
15293 | |
15294 | NOTE_EXTEND The file referenced by the descriptor was |
15295 | extended. |
15296 | |
15297 | NOTE_TRUNCATE The file referenced by the descriptor was |
15298 | truncated. |
15299 | |
15300 | NOTE_ATTRIB The file referenced by the descriptor had |
15301 | its attributes changed. |
15302 | |
15303 | NOTE_LINK The link count on the file changed. |
15304 | |
15305 | NOTE_RENAME The file referenced by the descriptor was |
15306 | renamed. |
15307 | |
15308 | NOTE_REVOKE Access to the file was revoked via |
15309 | revoke(2) or the underlying file system was |
15310 | unmounted. |
15311 | |
15312 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
15313 | filter. |
15314 | |
15315 | EVFILT_PROC Takes the process ID to monitor as the identifier and the |
15316 | events to watch for in _\bf_\bf_\bl_\ba_\bg_\bs, and returns when the |
15317 | process performs one or more of the requested events. If |
15318 | a process can normally see another process, it can attach |
15319 | an event to it. The events to monitor are: |
15320 | |
15321 | NOTE_EXIT The process has exited. The exit status |
15322 | will be stored in _\bd_\ba_\bt_\ba in the same format |
15323 | as the status set by wait(2). |
15324 | |
15325 | NOTE_FORK The process has called f\bfo\bor\brk\bk(). |
15326 | |
15327 | NOTE_EXEC The process has executed a new process |
15328 | via execve(2) or similar call. |
15329 | |
15330 | NOTE_TRACK Follow a process across f\bfo\bor\brk\bk() calls. |
15331 | The parent process will return with |
15332 | NOTE_FORK set in the _\bf_\bf_\bl_\ba_\bg_\bs field, while |
15333 | the child process will return with |
15334 | NOTE_CHILD set in _\bf_\bf_\bl_\ba_\bg_\bs and the parent |
15335 | PID in _\bd_\ba_\bt_\ba. |
15336 | |
15337 | NOTE_TRACKERR This flag is returned if the system was |
15338 | unable to attach an event to the child |
15339 | process, usually due to resource |
15340 | limitations. |
15341 | |
15342 | On return, _\bf_\bf_\bl_\ba_\bg_\bs contains the events which triggered the |
15343 | filter. |
15344 | |
15345 | EVFILT_SIGNAL Takes the signal number to monitor as the identifier and |
15346 | returns when the given signal is delivered to the process. |
15347 | This coexists with the s\bsi\big\bgn\bna\bal\bl() and s\bsi\big\bga\bac\bct\bti\bio\bon\bn() |
15348 | facilities, and has a lower precedence. The filter will |
15349 | record all attempts to deliver a signal to a process, even |
15350 | if the signal has been marked as SIG_IGN. Event |
15351 | notification happens after normal signal delivery |
15352 | processing. _\bd_\ba_\bt_\ba returns the number of times the signal |
15353 | has occurred since the last call to k\bke\bev\bve\ben\bnt\bt(). This filter |
15354 | automatically sets the EV_CLEAR flag internally. |
15355 | |
15356 | EVFILT_TIMER Establishes an arbitrary timer identified by _\bi_\bd_\be_\bn_\bt. When |
15357 | adding a timer, _\bd_\ba_\bt_\ba specifies the timeout period in |
15358 | milliseconds. The timer will be periodic unless |
15359 | EV_ONESHOT is specified. On return, _\bd_\ba_\bt_\ba contains the |
15360 | number of times the timeout has expired since the last |
15361 | call to k\bke\bev\bve\ben\bnt\bt(). This filter automatically sets the |
15362 | EV_CLEAR flag internally. |
15363 | |
15364 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
15365 | k\bkq\bqu\bue\beu\bue\be() creates a new kernel event queue and returns a file descriptor. |
15366 | If there was an error creating the kernel event queue, a value of -1 is |
15367 | returned and errno set. |
15368 | |
15369 | k\bke\bev\bve\ben\bnt\bt() returns the number of events placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, up to the |
15370 | value given by _\bn_\be_\bv_\be_\bn_\bt_\bs. If an error occurs while processing an element |
15371 | of the _\bc_\bh_\ba_\bn_\bg_\be_\bl_\bi_\bs_\bt and there is enough room in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt, then the |
15372 | event will be placed in the _\be_\bv_\be_\bn_\bt_\bl_\bi_\bs_\bt with EV_ERROR set in _\bf_\bl_\ba_\bg_\bs and the |
15373 | system error in _\bd_\ba_\bt_\ba. Otherwise, -1 will be returned, and errno will be |
15374 | set to indicate the error condition. If the time limit expires, then |
15375 | k\bke\bev\bve\ben\bnt\bt() returns 0. |
15376 | |
15377 | E\bER\bRR\bRO\bOR\bRS\bS |
15378 | The k\bkq\bqu\bue\beu\bue\be() function fails if: |
15379 | |
15380 | [ENOMEM] The kernel failed to allocate enough memory for the |
15381 | kernel queue. |
15382 | |
15383 | [EMFILE] The per-process descriptor table is full. |
15384 | |
15385 | [ENFILE] The system file table is full. |
15386 | |
15387 | The k\bke\bev\bve\ben\bnt\bt() function fails if: |
15388 | |
15389 | [EACCES] The process does not have permission to register a |
15390 | filter. |
15391 | |
15392 | [EFAULT] There was an error reading or writing the _\bk_\be_\bv_\be_\bn_\bt |
15393 | structure. |
15394 | |
15395 | [EBADF] The specified descriptor is invalid. |
15396 | |
15397 | [EINTR] A signal was delivered before the timeout expired and |
15398 | before any events were placed on the kqueue for |
15399 | return. |
15400 | |
15401 | [EINVAL] The specified time limit or filter is invalid. |
15402 | |
15403 | [ENOENT] The event could not be found to be modified or |
15404 | deleted. |
15405 | |
15406 | [ENOMEM] No memory was available to register the event. |
15407 | |
15408 | [ESRCH] The specified process to attach to does not exist. |
15409 | |
15410 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
15411 | poll(2), read(2), select(2), sigaction(2), wait(2), write(2), signal(3) |
15412 | |
15413 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
15414 | The k\bkq\bqu\bue\beu\bue\be() and k\bke\bev\bve\ben\bnt\bt() functions first appeared in FreeBSD 4.1. |
15415 | |
15416 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
15417 | The k\bkq\bqu\bue\beu\bue\be() system and this manual page were written by Jonathan Lemon |
15418 | <_\bj_\bl_\be_\bm_\bo_\bn_\b@_\bF_\br_\be_\be_\bB_\bS_\bD_\b._\bo_\br_\bg>. |
15419 | |
15420 | B\bBU\bUG\bGS\bS |
15421 | It is currently not possible to watch FIFOs or AIO that reside on |
15422 | anything but a UFS file system. Watching a vnode is possible on UFS, NFS |
15423 | and MS-DOS file systems. |
15424 | |
15425 | The _\bt_\bi_\bm_\be_\bo_\bu_\bt value is limited to 24 hours; longer timeouts will be |
15426 | silently reinterpreted as 24 hours. |
15427 | |
15428 | N\bNA\bAM\bME\bE |
15429 | k\bkt\btr\bra\bac\bce\be - process tracing |
15430 | |
15431 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
15432 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
15433 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
15434 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
15435 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/k\bkt\btr\bra\bac\bce\be.\b.h\bh>\b> |
15436 | |
15437 | _\bi_\bn_\bt |
15438 | k\bkt\btr\bra\bac\bce\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\br_\ba_\bc_\be_\bf_\bi_\bl_\be, _\bi_\bn_\bt _\bo_\bp_\bs, _\bi_\bn_\bt _\bt_\br_\bp_\bo_\bi_\bn_\bt_\bs, _\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd); |
15439 | |
15440 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
15441 | The k\bkt\btr\bra\bac\bce\be() function enables or disables tracing of one or more |
15442 | processes. Users may only trace their own processes. Only the superuser |
15443 | can trace setuid or setgid programs. k\bkt\btr\bra\bac\bce\be() is only available on |
15444 | kernels compiled with the K\bKT\bTR\bRA\bAC\bCE\bE option. |
15445 | |
15446 | _\bt_\br_\ba_\bc_\be_\bf_\bi_\bl_\be gives the pathname of the file to be used for tracing. The |
15447 | file must exist, be writable by the calling process, and not be a |
15448 | symbolic link. All trace records are always appended to the file, so the |
15449 | file must be truncated to zero length to discard previous trace data. If |
15450 | tracing points are being disabled (see KTROP_CLEAR below), _\bt_\br_\ba_\bc_\be_\bf_\bi_\bl_\be may |
15451 | be NULL. |
15452 | |
15453 | The _\bo_\bp_\bs parameter specifies the requested ktrace operation. The defined |
15454 | operations are: |
15455 | |
15456 | KTROP_SET Enable trace points specified in _\bt_\br_\bp_\bo_\bi_\bn_\bt_\bs. |
15457 | KTROP_CLEAR Disable trace points specified in _\bt_\br_\bp_\bo_\bi_\bn_\bt_\bs. |
15458 | KTROP_CLEARFILE Stop all tracing. |
15459 | KTRFLAG_DESCEND The tracing change should apply to the specified |
15460 | process and all its current children. |
15461 | |
15462 | The _\bt_\br_\bp_\bo_\bi_\bn_\bt_\bs parameter specifies the trace points of interest. The |
15463 | defined trace points are: |
15464 | |
15465 | KTRFAC_SYSCALL Trace system calls. |
15466 | KTRFAC_SYSRET Trace return values from system calls. |
15467 | KTRFAC_NAMEI Trace name lookup operations. |
15468 | KTRFAC_GENIO Trace all I/O (note that this option can generate |
15469 | much output). |
15470 | KTRFAC_PSIG Trace posted signals. |
15471 | KTRFAC_EMUL Trace emulation changes. |
15472 | KTRFAC_CSW Trace context switch points. |
15473 | KTRFAC_STRUCT Trace various structs |
15474 | KTRFAC_USER Trace user data coming from utrace(2) calls. |
15475 | KTRFAC_INHERIT Inherit tracing to future children. |
15476 | |
15477 | The _\bp_\bi_\bd parameter refers to a process ID. If it is negative, it refers |
15478 | to a process group ID. |
15479 | |
15480 | Each tracing event outputs a record composed of a generic header followed |
15481 | by a trace point specific structure. The generic header is: |
15482 | |
15483 | struct ktr_header { |
15484 | uint ktr_type; /* trace record type */ |
15485 | pid_t ktr_pid; /* process id */ |
15486 | pid_t ktr_tid; /* thread id */ |
15487 | struct timespec ktr_time; /* timestamp */ |
15488 | char ktr_comm[MAXCOMLEN+1]; /* command name */ |
15489 | size_t ktr_len; /* length of buf */ |
15490 | }; |
15491 | |
15492 | The _\bk_\bt_\br_\b__\bl_\be_\bn field specifies the length of the _\bk_\bt_\br_\b__\bt_\by_\bp_\be data that follows |
15493 | this header. The _\bk_\bt_\br_\b__\bp_\bi_\bd, _\bk_\bt_\br_\b__\bt_\bi_\bd, and _\bk_\bt_\br_\b__\bc_\bo_\bm_\bm fields specify the |
15494 | process, thread, and command generating the record. The _\bk_\bt_\br_\b__\bt_\bi_\bm_\be field |
15495 | gives the time (with nanosecond resolution) that the record was |
15496 | generated. |
15497 | |
15498 | The generic header is followed by _\bk_\bt_\br_\b__\bl_\be_\bn bytes of a _\bk_\bt_\br_\b__\bt_\by_\bp_\be record. |
15499 | The type specific records are defined in the <_\bs_\by_\bs_\b/_\bk_\bt_\br_\ba_\bc_\be_\b._\bh> include file. |
15500 | |
15501 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
15502 | Upon successful completion, the value 0 is returned; otherwise the |
15503 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
15504 | error. |
15505 | |
15506 | E\bER\bRR\bRO\bOR\bRS\bS |
15507 | k\bkt\btr\bra\bac\bce\be() will fail if: |
15508 | |
15509 | [ENOTDIR] A component of the path prefix is not a directory. |
15510 | |
15511 | [EINVAL] No trace points were selected. |
15512 | |
15513 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, |
15514 | or an entire pathname (including the terminating NUL) |
15515 | exceeded PATH_MAX bytes. |
15516 | |
15517 | [ENOENT] The named tracefile does not exist. |
15518 | |
15519 | [EACCES] Search permission is denied for a component of the path |
15520 | prefix or the path refers to a symbolic link. |
15521 | |
15522 | [ELOOP] Too many symbolic links were encountered in translating |
15523 | the pathname. |
15524 | |
15525 | [EIO] An I/O error occurred while reading from or writing to |
15526 | the file system. |
15527 | |
15528 | [ESRCH] No process can be found corresponding to that specified |
15529 | by _\bp_\bi_\bd. |
15530 | |
15531 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
15532 | kdump(1), ktrace(1), utrace(2) |
15533 | |
15534 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
15535 | A k\bkt\btr\bra\bac\bce\be() function call first appeared in 4.4BSD. |
15536 | |
15537 | N\bNA\bAM\bME\bE |
15538 | c\bch\bho\bow\bwn\bn, l\blc\bch\bho\bow\bwn\bn, f\bfc\bch\bho\bow\bwn\bna\bat\bt, f\bfc\bch\bho\bow\bwn\bn - change owner and group of a file or |
15539 | link |
15540 | |
15541 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
15542 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
15543 | |
15544 | _\bi_\bn_\bt |
15545 | c\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
15546 | |
15547 | _\bi_\bn_\bt |
15548 | l\blc\bch\bho\bow\bwn\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
15549 | |
15550 | _\bi_\bn_\bt |
15551 | f\bfc\bch\bho\bow\bwn\bn(_\bi_\bn_\bt _\bf_\bd, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp); |
15552 | |
15553 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
15554 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
15555 | |
15556 | _\bi_\bn_\bt |
15557 | f\bfc\bch\bho\bow\bwn\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bu_\bi_\bd_\b__\bt _\bo_\bw_\bn_\be_\br, _\bg_\bi_\bd_\b__\bt _\bg_\br_\bo_\bu_\bp, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
15558 | |
15559 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
15560 | The owner ID and group ID of the file (or link) named by _\bp_\ba_\bt_\bh or |
15561 | referenced by _\bf_\bd is changed as specified by the arguments _\bo_\bw_\bn_\be_\br and |
15562 | _\bg_\br_\bo_\bu_\bp. The owner of a file may change the _\bg_\br_\bo_\bu_\bp to a group of which he |
15563 | or she is a member, but the change _\bo_\bw_\bn_\be_\br capability is restricted to the |
15564 | superuser. |
15565 | |
15566 | By default, c\bch\bho\bow\bwn\bn() clears the set-user-ID and set-group-ID bits on the |
15567 | file to prevent accidental or mischievous creation of set-user-ID and |
15568 | set-group-ID programs. This behaviour can be overridden by setting the |
15569 | sysctl(8) variable _\bf_\bs_\b._\bp_\bo_\bs_\bi_\bx_\b._\bs_\be_\bt_\bu_\bi_\bd to zero. |
15570 | |
15571 | l\blc\bch\bho\bow\bwn\bn() operates similarly to how c\bch\bho\bow\bwn\bn() operated on older systems, and |
15572 | does not follow symbolic links. It allows the owner and group of a |
15573 | symbolic link to be set. |
15574 | |
15575 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() function is equivalent to either the c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn() |
15576 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
15577 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose ownership is changed is |
15578 | determined relative to the directory associated with file descriptor _\bf_\bd |
15579 | instead of the current working directory. |
15580 | |
15581 | If f\bfc\bch\bho\bow\bwn\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
15582 | in the _\bf_\bd parameter, the current working directory is used and the |
15583 | behavior is identical to a call to c\bch\bho\bow\bwn\bn() or l\blc\bch\bho\bow\bwn\bn(), depending on |
15584 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
15585 | |
15586 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
15587 | values: |
15588 | |
15589 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
15590 | ownership of the symbolic link is changed. |
15591 | |
15592 | f\bfc\bch\bho\bow\bwn\bn() is particularly useful when used in conjunction with the file |
15593 | locking primitives (see flock(2)). |
15594 | |
15595 | One of the owner or group IDs may be left unchanged by specifying it as |
15596 | -1. |
15597 | |
15598 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
15599 | Upon successful completion, the value 0 is returned; otherwise the |
15600 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
15601 | error. |
15602 | |
15603 | E\bER\bRR\bRO\bOR\bRS\bS |
15604 | c\bch\bho\bow\bwn\bn(), l\blc\bch\bho\bow\bwn\bn(), and f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail and the file or link will be |
15605 | unchanged if: |
15606 | |
15607 | [ENOTDIR] A component of the path prefix is not a directory. |
15608 | |
15609 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
15610 | characters, or an entire pathname (including the |
15611 | terminating NUL) exceeded PATH_MAX bytes. |
15612 | |
15613 | [ENOENT] The named file does not exist. |
15614 | |
15615 | [EACCES] Search permission is denied for a component of the |
15616 | path prefix. |
15617 | |
15618 | [ELOOP] Too many symbolic links were encountered in |
15619 | translating the pathname. |
15620 | |
15621 | [EPERM] The effective user ID is not the superuser. |
15622 | |
15623 | [EROFS] The named file resides on a read-only file system. |
15624 | |
15625 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
15626 | space. |
15627 | |
15628 | [EIO] An I/O error occurred while reading from or writing to |
15629 | the file system. |
15630 | |
15631 | Additionally, f\bfc\bch\bho\bow\bwn\bna\bat\bt() will fail if: |
15632 | |
15633 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
15634 | AT_SYMLINK_NOFOLLOW. |
15635 | |
15636 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
15637 | argument is neither AT_FDCWD nor a valid file |
15638 | descriptor. |
15639 | |
15640 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
15641 | argument is a valid file descriptor but it does not |
15642 | reference a directory. |
15643 | |
15644 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
15645 | permission is denied for the directory which the _\bf_\bd |
15646 | file descriptor references. |
15647 | |
15648 | f\bfc\bch\bho\bow\bwn\bn() will fail if: |
15649 | |
15650 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
15651 | |
15652 | [EINVAL] _\bf_\bd refers to a socket, not a file. |
15653 | |
15654 | [EPERM] The effective user ID is not the superuser. |
15655 | |
15656 | [EROFS] The named file resides on a read-only file system. |
15657 | |
15658 | [EIO] An I/O error occurred while reading from or writing to |
15659 | the file system. |
15660 | |
15661 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
15662 | chgrp(1), chmod(2), flock(2), chown(8) |
15663 | |
15664 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
15665 | The c\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), and l\blc\bch\bho\bow\bwn\bn() functions are expected to |
15666 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
15667 | |
15668 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
15669 | The c\bch\bho\bow\bwn\bn() system call first appeared in Version 1 AT&T UNIX. Since |
15670 | Version 6 AT&T UNIX it supports changing the group as well, and in |
15671 | Version 7 AT&T UNIX _\bg_\br_\bo_\bu_\bp was made a separate argument. |
15672 | |
15673 | The f\bfc\bch\bho\bow\bwn\bn() system call first appeared in 4.1cBSD. |
15674 | |
15675 | The c\bch\bho\bow\bwn\bn() and f\bfc\bch\bho\bow\bwn\bn() system calls were changed to follow symbolic |
15676 | links in 4.4BSD; therefore, and for compatibility with AT&T System V |
15677 | Release 4 UNIX, the l\blc\bch\bho\bow\bwn\bn() system call was added to OpenBSD 2.1. |
15678 | |
15679 | The f\bfc\bch\bho\bow\bwn\bna\bat\bt() system call has been available since OpenBSD 5.0. |
15680 | |
15681 | N\bNA\bAM\bME\bE |
15682 | l\bli\bin\bnk\bk, l\bli\bin\bnk\bka\bat\bt - make hard link to a file |
15683 | |
15684 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
15685 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
15686 | |
15687 | _\bi_\bn_\bt |
15688 | l\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
15689 | |
15690 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
15691 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
15692 | |
15693 | _\bi_\bn_\bt |
15694 | l\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bi_\bn_\bt _\bf_\bd_\b2, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
15695 | |
15696 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
15697 | The l\bli\bin\bnk\bk() function atomically creates the specified directory entry |
15698 | (hard link) _\bn_\ba_\bm_\be_\b2 with the attributes of the underlying object pointed at |
15699 | by _\bn_\ba_\bm_\be_\b1. If the link is successful: the link count of the underlying |
15700 | object is incremented; _\bn_\ba_\bm_\be_\b1 and _\bn_\ba_\bm_\be_\b2 share equal access and rights to |
15701 | the underlying object. |
15702 | |
15703 | If _\bn_\ba_\bm_\be_\b1 is removed, the file _\bn_\ba_\bm_\be_\b2 is not deleted and the link count of |
15704 | the underlying object is decremented. |
15705 | |
15706 | _\bn_\ba_\bm_\be_\b1 must exist for the hard link to succeed and both _\bn_\ba_\bm_\be_\b1 and _\bn_\ba_\bm_\be_\b2 |
15707 | must be in the same file system. As mandated by POSIX.1 _\bn_\ba_\bm_\be_\b1 may not be |
15708 | a directory. |
15709 | |
15710 | The l\bli\bin\bnk\bka\bat\bt() function is equivalent to l\bli\bin\bnk\bk() except that where _\bn_\ba_\bm_\be_\b1 or |
15711 | _\bn_\ba_\bm_\be_\b2 specifies a relative path, the directory entries linked are |
15712 | resolved relative to the directories associated with file descriptors _\bf_\bd_\b1 |
15713 | or _\bf_\bd_\b2 (respectively) instead of the current working directory. |
15714 | |
15715 | If l\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
15716 | in the _\bf_\bd_\b1 or _\bf_\bd_\b2 parameter, the current working directory is used for |
15717 | resolving the respective _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument. |
15718 | |
15719 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
15720 | values: |
15721 | |
15722 | AT_SYMLINK_FOLLOW If _\bn_\ba_\bm_\be_\b1 names a symbolic link, a new link for |
15723 | the target of the symbolic link is created. |
15724 | |
15725 | If the AT_SYMLINK_FOLLOW flag is clear and _\bn_\ba_\bm_\be_\b1 names a symbolic link, a |
15726 | new link is created for the symbolic link _\bn_\ba_\bm_\be_\b1 and not its target. |
15727 | |
15728 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
15729 | Upon successful completion, the value 0 is returned; otherwise the |
15730 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
15731 | error. |
15732 | |
15733 | E\bER\bRR\bRO\bOR\bRS\bS |
15734 | l\bli\bin\bnk\bk() and l\bli\bin\bnk\bka\bat\bt() will fail and no link will be created if: |
15735 | |
15736 | [ENOTDIR] A component of either path prefix is not a directory. |
15737 | |
15738 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
15739 | characters, or an entire pathname (including the |
15740 | terminating NUL) exceeded PATH_MAX bytes. |
15741 | |
15742 | [ENOENT] A component of either path prefix does not exist. |
15743 | |
15744 | [EOPNOTSUPP] The file system containing the file named by _\bn_\ba_\bm_\be_\b1 |
15745 | does not support links. |
15746 | |
15747 | [EMLINK] The link count of the file named by _\bn_\ba_\bm_\be_\b1 would exceed |
15748 | LINK_MAX. |
15749 | |
15750 | [EACCES] A component of either path prefix denies search |
15751 | permission. |
15752 | |
15753 | [EACCES] The requested link requires writing in a directory |
15754 | with a mode that denies write permission. |
15755 | |
15756 | [ELOOP] Too many symbolic links were encountered in |
15757 | translating one of the pathnames. |
15758 | |
15759 | [ENOENT] The file named by _\bn_\ba_\bm_\be_\b1 does not exist. |
15760 | |
15761 | [EEXIST] The link named by _\bn_\ba_\bm_\be_\b2 does exist. |
15762 | |
15763 | [EPERM] The file named by _\bn_\ba_\bm_\be_\b1 is a directory and the |
15764 | effective user ID is not superuser, or the file system |
15765 | containing the file does not permit the use of l\bli\bin\bnk\bk() |
15766 | on a directory. |
15767 | |
15768 | [EPERM] The file named by _\bn_\ba_\bm_\be_\b1 is flagged immutable or |
15769 | append-only. |
15770 | |
15771 | [EXDEV] The link named by _\bn_\ba_\bm_\be_\b2 and the file named by _\bn_\ba_\bm_\be_\b1 |
15772 | are on different file systems. |
15773 | |
15774 | [ENOSPC] The directory in which the entry for the new link is |
15775 | being placed cannot be extended because there is no |
15776 | space left on the file system containing the |
15777 | directory. |
15778 | |
15779 | [EDQUOT] The directory in which the entry for the new link is |
15780 | being placed cannot be extended because the user's |
15781 | quota of disk blocks on the file system containing the |
15782 | directory has been exhausted. |
15783 | |
15784 | [EIO] An I/O error occurred while reading from or writing to |
15785 | the file system to make the directory entry. |
15786 | |
15787 | [EROFS] The requested link requires writing in a directory on |
15788 | a read-only file system. |
15789 | |
15790 | [EFAULT] One of the pathnames specified is outside the |
15791 | process's allocated address space. |
15792 | |
15793 | Additionally, l\bli\bin\bnk\bka\bat\bt() will fail if: |
15794 | |
15795 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
15796 | AT_SYMLINK_FOLLOW. |
15797 | |
15798 | [EBADF] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
15799 | and the _\bf_\bd_\b1 or _\bf_\bd_\b2 argument, respectively, is neither |
15800 | AT_FDCWD nor a valid file descriptor. |
15801 | |
15802 | [ENOTDIR] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
15803 | and the _\bf_\bd_\b1 or _\bf_\bd_\b2 argument, respectively, is a valid |
15804 | file descriptor but it does not reference a directory. |
15805 | |
15806 | [EACCES] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
15807 | but search permission is denied for the directory |
15808 | which the _\bf_\bd_\b1 or _\bf_\bd_\b2 file descriptor, respectively, |
15809 | references. |
15810 | |
15811 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
15812 | ln(1), readlink(2), symlink(2), unlink(2) |
15813 | |
15814 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
15815 | The l\bli\bin\bnk\bk() and l\bli\bin\bnk\bka\bat\bt() functions are expected to conform to IEEE Std |
15816 | 1003.1-2008 (``POSIX.1''). |
15817 | |
15818 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
15819 | The l\bli\bin\bnk\bk() system call first appeared in Version 1 AT&T UNIX. The |
15820 | l\bli\bin\bnk\bka\bat\bt() function appeared in OpenBSD 5.0. |
15821 | |
15822 | N\bNA\bAM\bME\bE |
15823 | l\bli\bin\bnk\bk, l\bli\bin\bnk\bka\bat\bt - make hard link to a file |
15824 | |
15825 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
15826 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
15827 | |
15828 | _\bi_\bn_\bt |
15829 | l\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
15830 | |
15831 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
15832 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
15833 | |
15834 | _\bi_\bn_\bt |
15835 | l\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bi_\bn_\bt _\bf_\bd_\b2, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
15836 | |
15837 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
15838 | The l\bli\bin\bnk\bk() function atomically creates the specified directory entry |
15839 | (hard link) _\bn_\ba_\bm_\be_\b2 with the attributes of the underlying object pointed at |
15840 | by _\bn_\ba_\bm_\be_\b1. If the link is successful: the link count of the underlying |
15841 | object is incremented; _\bn_\ba_\bm_\be_\b1 and _\bn_\ba_\bm_\be_\b2 share equal access and rights to |
15842 | the underlying object. |
15843 | |
15844 | If _\bn_\ba_\bm_\be_\b1 is removed, the file _\bn_\ba_\bm_\be_\b2 is not deleted and the link count of |
15845 | the underlying object is decremented. |
15846 | |
15847 | _\bn_\ba_\bm_\be_\b1 must exist for the hard link to succeed and both _\bn_\ba_\bm_\be_\b1 and _\bn_\ba_\bm_\be_\b2 |
15848 | must be in the same file system. As mandated by POSIX.1 _\bn_\ba_\bm_\be_\b1 may not be |
15849 | a directory. |
15850 | |
15851 | The l\bli\bin\bnk\bka\bat\bt() function is equivalent to l\bli\bin\bnk\bk() except that where _\bn_\ba_\bm_\be_\b1 or |
15852 | _\bn_\ba_\bm_\be_\b2 specifies a relative path, the directory entries linked are |
15853 | resolved relative to the directories associated with file descriptors _\bf_\bd_\b1 |
15854 | or _\bf_\bd_\b2 (respectively) instead of the current working directory. |
15855 | |
15856 | If l\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
15857 | in the _\bf_\bd_\b1 or _\bf_\bd_\b2 parameter, the current working directory is used for |
15858 | resolving the respective _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument. |
15859 | |
15860 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
15861 | values: |
15862 | |
15863 | AT_SYMLINK_FOLLOW If _\bn_\ba_\bm_\be_\b1 names a symbolic link, a new link for |
15864 | the target of the symbolic link is created. |
15865 | |
15866 | If the AT_SYMLINK_FOLLOW flag is clear and _\bn_\ba_\bm_\be_\b1 names a symbolic link, a |
15867 | new link is created for the symbolic link _\bn_\ba_\bm_\be_\b1 and not its target. |
15868 | |
15869 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
15870 | Upon successful completion, the value 0 is returned; otherwise the |
15871 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
15872 | error. |
15873 | |
15874 | E\bER\bRR\bRO\bOR\bRS\bS |
15875 | l\bli\bin\bnk\bk() and l\bli\bin\bnk\bka\bat\bt() will fail and no link will be created if: |
15876 | |
15877 | [ENOTDIR] A component of either path prefix is not a directory. |
15878 | |
15879 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
15880 | characters, or an entire pathname (including the |
15881 | terminating NUL) exceeded PATH_MAX bytes. |
15882 | |
15883 | [ENOENT] A component of either path prefix does not exist. |
15884 | |
15885 | [EOPNOTSUPP] The file system containing the file named by _\bn_\ba_\bm_\be_\b1 |
15886 | does not support links. |
15887 | |
15888 | [EMLINK] The link count of the file named by _\bn_\ba_\bm_\be_\b1 would exceed |
15889 | LINK_MAX. |
15890 | |
15891 | [EACCES] A component of either path prefix denies search |
15892 | permission. |
15893 | |
15894 | [EACCES] The requested link requires writing in a directory |
15895 | with a mode that denies write permission. |
15896 | |
15897 | [ELOOP] Too many symbolic links were encountered in |
15898 | translating one of the pathnames. |
15899 | |
15900 | [ENOENT] The file named by _\bn_\ba_\bm_\be_\b1 does not exist. |
15901 | |
15902 | [EEXIST] The link named by _\bn_\ba_\bm_\be_\b2 does exist. |
15903 | |
15904 | [EPERM] The file named by _\bn_\ba_\bm_\be_\b1 is a directory and the |
15905 | effective user ID is not superuser, or the file system |
15906 | containing the file does not permit the use of l\bli\bin\bnk\bk() |
15907 | on a directory. |
15908 | |
15909 | [EPERM] The file named by _\bn_\ba_\bm_\be_\b1 is flagged immutable or |
15910 | append-only. |
15911 | |
15912 | [EXDEV] The link named by _\bn_\ba_\bm_\be_\b2 and the file named by _\bn_\ba_\bm_\be_\b1 |
15913 | are on different file systems. |
15914 | |
15915 | [ENOSPC] The directory in which the entry for the new link is |
15916 | being placed cannot be extended because there is no |
15917 | space left on the file system containing the |
15918 | directory. |
15919 | |
15920 | [EDQUOT] The directory in which the entry for the new link is |
15921 | being placed cannot be extended because the user's |
15922 | quota of disk blocks on the file system containing the |
15923 | directory has been exhausted. |
15924 | |
15925 | [EIO] An I/O error occurred while reading from or writing to |
15926 | the file system to make the directory entry. |
15927 | |
15928 | [EROFS] The requested link requires writing in a directory on |
15929 | a read-only file system. |
15930 | |
15931 | [EFAULT] One of the pathnames specified is outside the |
15932 | process's allocated address space. |
15933 | |
15934 | Additionally, l\bli\bin\bnk\bka\bat\bt() will fail if: |
15935 | |
15936 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
15937 | AT_SYMLINK_FOLLOW. |
15938 | |
15939 | [EBADF] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
15940 | and the _\bf_\bd_\b1 or _\bf_\bd_\b2 argument, respectively, is neither |
15941 | AT_FDCWD nor a valid file descriptor. |
15942 | |
15943 | [ENOTDIR] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
15944 | and the _\bf_\bd_\b1 or _\bf_\bd_\b2 argument, respectively, is a valid |
15945 | file descriptor but it does not reference a directory. |
15946 | |
15947 | [EACCES] The _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 argument specifies a relative path |
15948 | but search permission is denied for the directory |
15949 | which the _\bf_\bd_\b1 or _\bf_\bd_\b2 file descriptor, respectively, |
15950 | references. |
15951 | |
15952 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
15953 | ln(1), readlink(2), symlink(2), unlink(2) |
15954 | |
15955 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
15956 | The l\bli\bin\bnk\bk() and l\bli\bin\bnk\bka\bat\bt() functions are expected to conform to IEEE Std |
15957 | 1003.1-2008 (``POSIX.1''). |
15958 | |
15959 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
15960 | The l\bli\bin\bnk\bk() system call first appeared in Version 1 AT&T UNIX. The |
15961 | l\bli\bin\bnk\bka\bat\bt() function appeared in OpenBSD 5.0. |
15962 | |
15963 | N\bNA\bAM\bME\bE |
15964 | l\bli\bis\bst\bte\ben\bn - listen for connections on a socket |
15965 | |
15966 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
15967 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
15968 | |
15969 | _\bi_\bn_\bt |
15970 | l\bli\bis\bst\bte\ben\bn(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bb_\ba_\bc_\bk_\bl_\bo_\bg); |
15971 | |
15972 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
15973 | To accept connections, a socket is first created with socket(2), a |
15974 | willingness to accept incoming connections and a queue limit for incoming |
15975 | connections are specified with l\bli\bis\bst\bte\ben\bn(), and then the connections are |
15976 | accepted with accept(2). The l\bli\bis\bst\bte\ben\bn() call applies only to sockets of |
15977 | type SOCK_STREAM or SOCK_SEQPACKET. |
15978 | |
15979 | The _\bb_\ba_\bc_\bk_\bl_\bo_\bg parameter defines the maximum length the queue of pending |
15980 | connections may grow to. If a connection request arrives with the queue |
15981 | full the client may receive an error with an indication of ECONNREFUSED, |
15982 | or, if the underlying protocol supports retransmission, the request may |
15983 | be ignored so that retries may succeed. |
15984 | |
15985 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
15986 | Upon successful completion, the value 0 is returned; otherwise the |
15987 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
15988 | error. |
15989 | |
15990 | E\bER\bRR\bRO\bOR\bRS\bS |
15991 | l\bli\bis\bst\bte\ben\bn() will fail if: |
15992 | |
15993 | [EBADF] The argument _\bs is not a valid descriptor. |
15994 | |
15995 | [ENOTSOCK] The argument _\bs is not a socket. |
15996 | |
15997 | [EOPNOTSUPP] The socket is not of a type that supports the |
15998 | operation l\bli\bis\bst\bte\ben\bn(). |
15999 | |
16000 | [EINVAL] The socket is already connected. |
16001 | |
16002 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16003 | accept(2), connect(2), socket(2), sysctl(8) |
16004 | |
16005 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
16006 | The l\bli\bis\bst\bte\ben\bn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
16007 | |
16008 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16009 | The l\bli\bis\bst\bte\ben\bn() system call first appeared in 4.1cBSD. |
16010 | |
16011 | B\bBU\bUG\bGS\bS |
16012 | The _\bb_\ba_\bc_\bk_\bl_\bo_\bg is currently limited (silently) to the value of the |
16013 | kern.somaxconn sysctl, which defaults to 128. |
16014 | |
16015 | N\bNA\bAM\bME\bE |
16016 | l\bls\bse\bee\bek\bk - reposition read/write file offset |
16017 | |
16018 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16019 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
16020 | |
16021 | _\bo_\bf_\bf_\b__\bt |
16022 | l\bls\bse\bee\bek\bk(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt, _\bi_\bn_\bt _\bw_\bh_\be_\bn_\bc_\be); |
16023 | |
16024 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16025 | The l\bls\bse\bee\bek\bk() function repositions the offset of the file descriptor _\bf_\bi_\bl_\bd_\be_\bs |
16026 | to the argument _\bo_\bf_\bf_\bs_\be_\bt according to the directive _\bw_\bh_\be_\bn_\bc_\be. The argument |
16027 | _\bf_\bi_\bl_\bd_\be_\bs must be an open file descriptor. l\bls\bse\bee\bek\bk() repositions the file |
16028 | pointer _\bf_\bi_\bl_\bd_\be_\bs as follows: |
16029 | |
16030 | If _\bw_\bh_\be_\bn_\bc_\be is SEEK_SET, the offset is set to _\bo_\bf_\bf_\bs_\be_\bt bytes. |
16031 | |
16032 | If _\bw_\bh_\be_\bn_\bc_\be is SEEK_CUR, the offset is set to its current location |
16033 | plus _\bo_\bf_\bf_\bs_\be_\bt bytes. |
16034 | |
16035 | If _\bw_\bh_\be_\bn_\bc_\be is SEEK_END, the offset is set to the size of the file |
16036 | plus _\bo_\bf_\bf_\bs_\be_\bt bytes. |
16037 | |
16038 | The l\bls\bse\bee\bek\bk() function allows the file offset to be set beyond the end of |
16039 | the existing end-of-file of the file. If data is later written at this |
16040 | point, subsequent reads of the data in the gap return bytes of zeros |
16041 | (until data is actually written into the gap). |
16042 | |
16043 | Some devices are incapable of seeking. The value of the pointer |
16044 | associated with such a device is undefined. |
16045 | |
16046 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16047 | Upon successful completion, l\bls\bse\bee\bek\bk() returns the resulting offset location |
16048 | as measured in bytes from the beginning of the file. Otherwise, a value |
16049 | of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
16050 | |
16051 | E\bER\bRR\bRO\bOR\bRS\bS |
16052 | l\bls\bse\bee\bek\bk() will fail and the file pointer will remain unchanged if: |
16053 | |
16054 | [EBADF] _\bf_\bi_\bl_\bd_\be_\bs is not an open file descriptor. |
16055 | |
16056 | [ESPIPE] _\bf_\bi_\bl_\bd_\be_\bs is associated with a pipe, socket, or FIFO. |
16057 | |
16058 | [EINVAL] _\bw_\bh_\be_\bn_\bc_\be is not a proper value or the resulting offset |
16059 | would be negative on a file system or special device |
16060 | that does not allow negative offsets to be used. |
16061 | |
16062 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16063 | dup(2), open(2) |
16064 | |
16065 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
16066 | The l\bls\bse\bee\bek\bk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
16067 | |
16068 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16069 | A s\bse\bee\bek\bk() system call first appeared in Version 1 AT&T UNIX. In Version 7 |
16070 | AT&T UNIX it was renamed to l\bls\bse\bee\bek\bk() for ``long seek'' due to a larger |
16071 | _\bo_\bf_\bf_\bs_\be_\bt argument type. |
16072 | |
16073 | B\bBU\bUG\bGS\bS |
16074 | This document's use of _\bw_\bh_\be_\bn_\bc_\be is incorrect English, but is maintained for |
16075 | historical reasons. |
16076 | |
16077 | N\bNA\bAM\bME\bE |
16078 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
16079 | |
16080 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16081 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16082 | |
16083 | _\bi_\bn_\bt |
16084 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
16085 | |
16086 | _\bi_\bn_\bt |
16087 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
16088 | |
16089 | _\bi_\bn_\bt |
16090 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
16091 | |
16092 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16093 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
16094 | |
16095 | _\bi_\bn_\bt |
16096 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
16097 | |
16098 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16099 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
16100 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
16101 | required, but all directories listed in the path name leading to the file |
16102 | must be searchable. |
16103 | |
16104 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
16105 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
16106 | itself, not the file the link references. |
16107 | |
16108 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
16109 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
16110 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
16111 | determined relative to the directory associated with file descriptor _\bf_\bd |
16112 | instead of the current working directory. |
16113 | |
16114 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
16115 | in the _\bf_\bd parameter, the current working directory is used and the |
16116 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
16117 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
16118 | |
16119 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
16120 | values: |
16121 | |
16122 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
16123 | of the symbolic link is returned. |
16124 | |
16125 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
16126 | known by the file descriptor _\bf_\bd. |
16127 | |
16128 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
16129 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
16130 | concerning the file. |
16131 | |
16132 | struct stat { |
16133 | dev_t st_dev; /* inode's device */ |
16134 | ino_t st_ino; /* inode's number */ |
16135 | mode_t st_mode; /* inode protection mode */ |
16136 | nlink_t st_nlink; /* number of hard links */ |
16137 | uid_t st_uid; /* user ID of the file's owner */ |
16138 | gid_t st_gid; /* group ID of the file's group */ |
16139 | dev_t st_rdev; /* device type */ |
16140 | struct timespec st_atim; /* time of last access */ |
16141 | struct timespec st_mtim; /* time of last data modification */ |
16142 | struct timespec st_ctim; /* time of last file status change */ |
16143 | off_t st_size; /* file size, in bytes */ |
16144 | blkcnt_t st_blocks; /* blocks allocated for file */ |
16145 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
16146 | u_int32_t st_flags; /* user defined flags for file */ |
16147 | u_int32_t st_gen; /* file generation number */ |
16148 | }; |
16149 | |
16150 | The time-related fields of struct stat are represented in struct timespec |
16151 | format, which has nanosecond precision. However, the actual precision is |
16152 | generally limited by the file system holding the file. The fields are as |
16153 | follows: |
16154 | |
16155 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
16156 | system object was created and updated by the utimes(2) and |
16157 | read(2) system calls. |
16158 | |
16159 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
16160 | truncate(2), utimes(2), and write(2) system calls. For |
16161 | directories, changed by any system call that alters which |
16162 | files are in the directory, such as the unlink(2), rename(2), |
16163 | mkdir(2), and symlink(2) system calls. |
16164 | |
16165 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
16166 | modification). Changed by the chmod(2), chown(2), link(2), |
16167 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
16168 | |
16169 | In addition, all the time fields are set to the current time when a file |
16170 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
16171 | open(2), and symlink(2) system calls. |
16172 | |
16173 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
16174 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
16175 | respective struct timespec member. Deprecated macros are also provided |
16176 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
16177 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
16178 | |
16179 | The size-related fields of the struct stat are as follows: |
16180 | |
16181 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
16182 | |
16183 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
16184 | 512-byte units. As short symbolic links are stored in the |
16185 | inode, this number may be zero. |
16186 | |
16187 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
16188 | |
16189 | #define S_IFMT 0170000 /* type of file mask */ |
16190 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
16191 | #define S_IFCHR 0020000 /* character special */ |
16192 | #define S_IFDIR 0040000 /* directory */ |
16193 | #define S_IFBLK 0060000 /* block special */ |
16194 | #define S_IFREG 0100000 /* regular */ |
16195 | #define S_IFLNK 0120000 /* symbolic link */ |
16196 | #define S_IFSOCK 0140000 /* socket */ |
16197 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
16198 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
16199 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
16200 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
16201 | #define S_IRUSR 0000400 /* R for owner */ |
16202 | #define S_IWUSR 0000200 /* W for owner */ |
16203 | #define S_IXUSR 0000100 /* X for owner */ |
16204 | #define S_IRWXG 0000070 /* RWX mask for group */ |
16205 | #define S_IRGRP 0000040 /* R for group */ |
16206 | #define S_IWGRP 0000020 /* W for group */ |
16207 | #define S_IXGRP 0000010 /* X for group */ |
16208 | #define S_IRWXO 0000007 /* RWX mask for other */ |
16209 | #define S_IROTH 0000004 /* R for other */ |
16210 | #define S_IWOTH 0000002 /* W for other */ |
16211 | #define S_IXOTH 0000001 /* X for other */ |
16212 | |
16213 | The following macros test a file's type. If the file is of that type, a |
16214 | non-zero value is returned; otherwise, 0 is returned. |
16215 | |
16216 | S_ISBLK(st_mode m) /* block special */ |
16217 | S_ISCHR(st_mode m) /* char special */ |
16218 | S_ISDIR(st_mode m) /* directory */ |
16219 | S_ISFIFO(st_mode m) /* fifo */ |
16220 | S_ISLNK(st_mode m) /* symbolic link */ |
16221 | S_ISREG(st_mode m) /* regular file */ |
16222 | S_ISSOCK(st_mode m) /* socket */ |
16223 | |
16224 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
16225 | |
16226 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16227 | Upon successful completion, the value 0 is returned; otherwise the |
16228 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16229 | error. |
16230 | |
16231 | E\bER\bRR\bRO\bOR\bRS\bS |
16232 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
16233 | |
16234 | [ENOTDIR] A component of the path prefix is not a directory. |
16235 | |
16236 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
16237 | characters, or an entire pathname (including the |
16238 | terminating NUL) exceeded PATH_MAX bytes. |
16239 | |
16240 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
16241 | empty path. |
16242 | |
16243 | [EACCES] Search permission is denied for a component of the |
16244 | path prefix. |
16245 | |
16246 | [ELOOP] Too many symbolic links were encountered in |
16247 | translating the pathname. |
16248 | |
16249 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
16250 | |
16251 | [EIO] An I/O error occurred while reading from or writing to |
16252 | the file system. |
16253 | |
16254 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
16255 | |
16256 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
16257 | AT_SYMLINK_NOFOLLOW. |
16258 | |
16259 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16260 | argument is neither AT_FDCWD nor a valid file |
16261 | descriptor. |
16262 | |
16263 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16264 | argument is a valid file descriptor but it does not |
16265 | reference a directory. |
16266 | |
16267 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
16268 | permission is denied for the directory which the _\bf_\bd |
16269 | file descriptor references. |
16270 | |
16271 | f\bfs\bst\bta\bat\bt() will fail if: |
16272 | |
16273 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
16274 | |
16275 | [EFAULT] _\bs_\bb points to an invalid address. |
16276 | |
16277 | [EIO] An I/O error occurred while reading from the file |
16278 | system. |
16279 | |
16280 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16281 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
16282 | |
16283 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
16284 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
16285 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
16286 | |
16287 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
16288 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
16289 | |
16290 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16291 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
16292 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
16293 | in Version 7 AT&T UNIX. |
16294 | |
16295 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
16296 | appeared in OpenBSD 5.0. |
16297 | |
16298 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
16299 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
16300 | |
16301 | Certain programs written when the timestamps were just of type time_t |
16302 | assumed that the members were consecutive (and could therefore be treated |
16303 | as an array and have their address passed directly to utime(3)). The |
16304 | transition to timestamps of type struct timespec broke them irrevocably. |
16305 | |
16306 | B\bBU\bUG\bGS\bS |
16307 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
16308 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
16309 | the time fields. |
16310 | |
16311 | N\bNA\bAM\bME\bE |
16312 | m\bma\bad\bdv\bvi\bis\bse\be, p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be - give advice about use of memory |
16313 | |
16314 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16315 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
16316 | |
16317 | _\bi_\bn_\bt |
16318 | m\bma\bad\bdv\bvi\bis\bse\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bb_\be_\bh_\ba_\bv); |
16319 | |
16320 | _\bi_\bn_\bt |
16321 | p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bb_\be_\bh_\ba_\bv); |
16322 | |
16323 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16324 | The m\bma\bad\bdv\bvi\bis\bse\be() system call allows a process that has knowledge of its |
16325 | memory behavior to describe it to the system. The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() |
16326 | interface has the same effect, but returns the error value instead of |
16327 | only setting _\be_\br_\br_\bn_\bo. |
16328 | |
16329 | The possible behaviors are: |
16330 | |
16331 | MADV_NORMAL No further special treatment needed. |
16332 | |
16333 | MADV_RANDOM Expect random page access patterns. |
16334 | |
16335 | MADV_SEQUENTIAL Expect sequential page references. |
16336 | |
16337 | MADV_WILLNEED The pages will be referenced soon. |
16338 | |
16339 | MADV_DONTNEED The pages will not be referenced soon. |
16340 | |
16341 | MADV_SPACEAVAIL Ensure that resources are reserved. |
16342 | |
16343 | MADV_FREE The pages don't contain any useful data and can be |
16344 | recycled. |
16345 | |
16346 | Portable programs that call the p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() interface should use the |
16347 | aliases POSIX_MADV_NORMAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, |
16348 | POSIX_MADV_WILLNEED, and POSIX_MADV_DONTNEED rather than the flags |
16349 | described above. |
16350 | |
16351 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16352 | The m\bma\bad\bdv\bvi\bis\bse\be() function returns the value 0 if successful; otherwise the |
16353 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16354 | error. |
16355 | |
16356 | If successful, the p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() function will return zero. Otherwise |
16357 | an error number will be returned to indicate the error. |
16358 | |
16359 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16360 | mincore(2), minherit(2), mprotect(2), msync(2), munmap(2) |
16361 | |
16362 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
16363 | The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() system call conforms to IEEE Std 1003.1-2008 |
16364 | (``POSIX.1''). |
16365 | |
16366 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16367 | The m\bma\bad\bdv\bvi\bis\bse\be() function first appeared in 4.4BSD. The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() |
16368 | function first appeared in OpenBSD 4.8. |
16369 | |
16370 | B\bBU\bUG\bGS\bS |
16371 | The MADV_WILLNEED behavior is ignored. The MADV_SPACEAVAIL behavior is |
16372 | not implemented and will always fail. |
16373 | |
16374 | N\bNA\bAM\bME\bE |
16375 | m\bmi\bin\bnc\bco\bor\bre\be - determine residency of memory pages |
16376 | |
16377 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16378 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
16379 | |
16380 | _\bi_\bn_\bt |
16381 | m\bmi\bin\bnc\bco\bor\bre\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bc_\bh_\ba_\br _\b*_\bv_\be_\bc); |
16382 | |
16383 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16384 | The m\bmi\bin\bnc\bco\bor\bre\be() system call allows a process to obtain information about |
16385 | whether pages are core resident. Here the current core residency of the |
16386 | pages is returned in the character array _\bv_\be_\bc, with a value of 1 meaning |
16387 | that the page is in-core. |
16388 | |
16389 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16390 | Upon successful completion, the value 0 is returned; otherwise the |
16391 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16392 | error. |
16393 | |
16394 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16395 | madvise(2), minherit(2), mlock(2), mprotect(2), msync(2), munmap(2) |
16396 | |
16397 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16398 | The m\bmi\bin\bnc\bco\bor\bre\be() function first appeared in 4.4BSD. |
16399 | |
16400 | N\bNA\bAM\bME\bE |
16401 | m\bmi\bin\bnh\bhe\ber\bri\bit\bt - control the inheritance of pages |
16402 | |
16403 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16404 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
16405 | |
16406 | _\bi_\bn_\bt |
16407 | m\bmi\bin\bnh\bhe\ber\bri\bit\bt(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bi_\bn_\bh_\be_\br_\bi_\bt); |
16408 | |
16409 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16410 | The m\bmi\bin\bnh\bhe\ber\bri\bit\bt() system call changes the specified pages to have the |
16411 | inheritance characteristic _\bi_\bn_\bh_\be_\br_\bi_\bt. A page's inheritance characteristic |
16412 | controls how it will be mapped in child processes as created by fork(2). |
16413 | |
16414 | The possible inheritance characteristics are: |
16415 | |
16416 | MAP_INHERIT_NONE Pages are not mapped in the child process. |
16417 | MAP_INHERIT_COPY Private copy of pages are mapped in the child |
16418 | process. |
16419 | MAP_INHERIT_SHARE Mapped pages are shared between the parent and |
16420 | child processes. |
16421 | MAP_INHERIT_ZERO New anonymous pages (initialized to all zero |
16422 | bytes) are mapped in the child process. |
16423 | |
16424 | Not all implementations will guarantee that the inheritance |
16425 | characteristic can be set on a page basis; the granularity of changes may |
16426 | be as large as an entire region. |
16427 | |
16428 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16429 | Upon successful completion, the value 0 is returned; otherwise the |
16430 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16431 | error. |
16432 | |
16433 | E\bER\bRR\bRO\bOR\bRS\bS |
16434 | The m\bmi\bin\bnh\bhe\ber\bri\bit\bt() system call will fail if: |
16435 | |
16436 | [EINVAL] The virtual address range specified by the _\ba_\bd_\bd_\br and |
16437 | _\bl_\be_\bn arguments is not valid. |
16438 | |
16439 | [EINVAL] The _\bi_\bn_\bh_\be_\br_\bi_\bt argument is invalid. |
16440 | |
16441 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16442 | madvise(2), mincore(2), mprotect(2), msync(2), munmap(2) |
16443 | |
16444 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16445 | The m\bmi\bin\bnh\bhe\ber\bri\bit\bt() function first appeared in OpenBSD 2.0. |
16446 | |
16447 | N\bNA\bAM\bME\bE |
16448 | m\bmk\bkd\bdi\bir\br, m\bmk\bkd\bdi\bir\bra\bat\bt - make a directory file |
16449 | |
16450 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16451 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16452 | |
16453 | _\bi_\bn_\bt |
16454 | m\bmk\bkd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
16455 | |
16456 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16457 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
16458 | |
16459 | _\bi_\bn_\bt |
16460 | m\bmk\bkd\bdi\bir\bra\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
16461 | |
16462 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16463 | The directory _\bp_\ba_\bt_\bh is created with the access permissions specified by |
16464 | _\bm_\bo_\bd_\be and restricted by the umask(2) of the calling process. |
16465 | |
16466 | The directory's owner ID is set to the process's effective user ID. The |
16467 | directory's group ID is set to that of the parent directory in which it |
16468 | is created. |
16469 | |
16470 | The m\bmk\bkd\bdi\bir\bra\bat\bt() function is equivalent to m\bmk\bkd\bdi\bir\br() except that where _\bp_\ba_\bt_\bh |
16471 | specifies a relative path, the newly created directory is created |
16472 | relative to the directory associated with file descriptor _\bf_\bd instead of |
16473 | the current working directory. |
16474 | |
16475 | If m\bmk\bkd\bdi\bir\bra\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
16476 | in the _\bf_\bd parameter, the current working directory is used and the |
16477 | behavior is identical to a call to m\bmk\bkd\bdi\bir\br(). |
16478 | |
16479 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16480 | Upon successful completion, the value 0 is returned; otherwise the |
16481 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16482 | error. |
16483 | |
16484 | E\bER\bRR\bRO\bOR\bRS\bS |
16485 | m\bmk\bkd\bdi\bir\br() and m\bmk\bkd\bdi\bir\bra\bat\bt() will fail and no directory will be created if: |
16486 | |
16487 | [ENOTDIR] A component of the path prefix is not a directory. |
16488 | |
16489 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
16490 | characters, or an entire pathname (including the |
16491 | terminating NUL) exceeded PATH_MAX bytes. |
16492 | |
16493 | [ENOENT] A component of the path prefix does not exist. |
16494 | |
16495 | [EACCES] Search permission is denied for a component of the |
16496 | path prefix. |
16497 | |
16498 | [ELOOP] Too many symbolic links were encountered in |
16499 | translating the pathname. |
16500 | |
16501 | [EROFS] The named file resides on a read-only file system. |
16502 | |
16503 | [EEXIST] The named file exists. |
16504 | |
16505 | [ENOSPC] The new directory cannot be created because there is |
16506 | no space left on the file system that will contain the |
16507 | directory. |
16508 | |
16509 | [ENOSPC] There are no free inodes on the file system on which |
16510 | the directory is being created. |
16511 | |
16512 | [EDQUOT] The new directory cannot be created because the user's |
16513 | quota of disk blocks on the file system that will |
16514 | contain the directory has been exhausted. |
16515 | |
16516 | [EDQUOT] The user's quota of inodes on the file system on which |
16517 | the directory is being created has been exhausted. |
16518 | |
16519 | [EIO] An I/O error occurred while making the directory entry |
16520 | or allocating the inode. |
16521 | |
16522 | [EIO] An I/O error occurred while reading from or writing to |
16523 | the file system. |
16524 | |
16525 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
16526 | space. |
16527 | |
16528 | Additionally, m\bmk\bkd\bdi\bir\bra\bat\bt() will fail if: |
16529 | |
16530 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16531 | argument is neither AT_FDCWD nor a valid file |
16532 | descriptor. |
16533 | |
16534 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16535 | argument is a valid file descriptor but it does not |
16536 | reference a directory. |
16537 | |
16538 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
16539 | permission is denied for the directory which the _\bf_\bd |
16540 | file descriptor references. |
16541 | |
16542 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16543 | chmod(2), stat(2), umask(2) |
16544 | |
16545 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
16546 | The m\bmk\bkd\bdi\bir\br() and m\bmk\bkd\bdi\bir\bra\bat\bt() functions conform to IEEE Std 1003.1-2008 |
16547 | (``POSIX.1''). |
16548 | |
16549 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16550 | A m\bmk\bkd\bdi\bir\br() system call first appeared in Version 1 AT&T UNIX. It was |
16551 | renamed to m\bma\bak\bkd\bdi\bir\br() in Version 2 AT&T UNIX. However, it did not exist |
16552 | from Version 4 AT&T UNIX to 4.1BSD; in those releases, mknod(2) had to be |
16553 | used. Since m\bmk\bkd\bdi\bir\br() reappeared in 4.1cBSD, it no longer requires |
16554 | superuser privileges and it automatically creates the `.' and `..' |
16555 | directory entries. |
16556 | |
16557 | The m\bmk\bkd\bdi\bir\bra\bat\bt() system call has been available since OpenBSD 5.0. |
16558 | |
16559 | N\bNA\bAM\bME\bE |
16560 | m\bmk\bkd\bdi\bir\br, m\bmk\bkd\bdi\bir\bra\bat\bt - make a directory file |
16561 | |
16562 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16563 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16564 | |
16565 | _\bi_\bn_\bt |
16566 | m\bmk\bkd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
16567 | |
16568 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16569 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
16570 | |
16571 | _\bi_\bn_\bt |
16572 | m\bmk\bkd\bdi\bir\bra\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
16573 | |
16574 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16575 | The directory _\bp_\ba_\bt_\bh is created with the access permissions specified by |
16576 | _\bm_\bo_\bd_\be and restricted by the umask(2) of the calling process. |
16577 | |
16578 | The directory's owner ID is set to the process's effective user ID. The |
16579 | directory's group ID is set to that of the parent directory in which it |
16580 | is created. |
16581 | |
16582 | The m\bmk\bkd\bdi\bir\bra\bat\bt() function is equivalent to m\bmk\bkd\bdi\bir\br() except that where _\bp_\ba_\bt_\bh |
16583 | specifies a relative path, the newly created directory is created |
16584 | relative to the directory associated with file descriptor _\bf_\bd instead of |
16585 | the current working directory. |
16586 | |
16587 | If m\bmk\bkd\bdi\bir\bra\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
16588 | in the _\bf_\bd parameter, the current working directory is used and the |
16589 | behavior is identical to a call to m\bmk\bkd\bdi\bir\br(). |
16590 | |
16591 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16592 | Upon successful completion, the value 0 is returned; otherwise the |
16593 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16594 | error. |
16595 | |
16596 | E\bER\bRR\bRO\bOR\bRS\bS |
16597 | m\bmk\bkd\bdi\bir\br() and m\bmk\bkd\bdi\bir\bra\bat\bt() will fail and no directory will be created if: |
16598 | |
16599 | [ENOTDIR] A component of the path prefix is not a directory. |
16600 | |
16601 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
16602 | characters, or an entire pathname (including the |
16603 | terminating NUL) exceeded PATH_MAX bytes. |
16604 | |
16605 | [ENOENT] A component of the path prefix does not exist. |
16606 | |
16607 | [EACCES] Search permission is denied for a component of the |
16608 | path prefix. |
16609 | |
16610 | [ELOOP] Too many symbolic links were encountered in |
16611 | translating the pathname. |
16612 | |
16613 | [EROFS] The named file resides on a read-only file system. |
16614 | |
16615 | [EEXIST] The named file exists. |
16616 | |
16617 | [ENOSPC] The new directory cannot be created because there is |
16618 | no space left on the file system that will contain the |
16619 | directory. |
16620 | |
16621 | [ENOSPC] There are no free inodes on the file system on which |
16622 | the directory is being created. |
16623 | |
16624 | [EDQUOT] The new directory cannot be created because the user's |
16625 | quota of disk blocks on the file system that will |
16626 | contain the directory has been exhausted. |
16627 | |
16628 | [EDQUOT] The user's quota of inodes on the file system on which |
16629 | the directory is being created has been exhausted. |
16630 | |
16631 | [EIO] An I/O error occurred while making the directory entry |
16632 | or allocating the inode. |
16633 | |
16634 | [EIO] An I/O error occurred while reading from or writing to |
16635 | the file system. |
16636 | |
16637 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
16638 | space. |
16639 | |
16640 | Additionally, m\bmk\bkd\bdi\bir\bra\bat\bt() will fail if: |
16641 | |
16642 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16643 | argument is neither AT_FDCWD nor a valid file |
16644 | descriptor. |
16645 | |
16646 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16647 | argument is a valid file descriptor but it does not |
16648 | reference a directory. |
16649 | |
16650 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
16651 | permission is denied for the directory which the _\bf_\bd |
16652 | file descriptor references. |
16653 | |
16654 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16655 | chmod(2), stat(2), umask(2) |
16656 | |
16657 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
16658 | The m\bmk\bkd\bdi\bir\br() and m\bmk\bkd\bdi\bir\bra\bat\bt() functions conform to IEEE Std 1003.1-2008 |
16659 | (``POSIX.1''). |
16660 | |
16661 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16662 | A m\bmk\bkd\bdi\bir\br() system call first appeared in Version 1 AT&T UNIX. It was |
16663 | renamed to m\bma\bak\bkd\bdi\bir\br() in Version 2 AT&T UNIX. However, it did not exist |
16664 | from Version 4 AT&T UNIX to 4.1BSD; in those releases, mknod(2) had to be |
16665 | used. Since m\bmk\bkd\bdi\bir\br() reappeared in 4.1cBSD, it no longer requires |
16666 | superuser privileges and it automatically creates the `.' and `..' |
16667 | directory entries. |
16668 | |
16669 | The m\bmk\bkd\bdi\bir\bra\bat\bt() system call has been available since OpenBSD 5.0. |
16670 | |
16671 | N\bNA\bAM\bME\bE |
16672 | m\bmk\bkf\bfi\bif\bfo\bo, m\bmk\bkf\bfi\bif\bfo\boa\bat\bt - make a FIFO file |
16673 | |
16674 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16675 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16676 | |
16677 | _\bi_\bn_\bt |
16678 | m\bmk\bkf\bfi\bif\bfo\bo(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
16679 | |
16680 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16681 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
16682 | |
16683 | _\bi_\bn_\bt |
16684 | m\bmk\bkf\bfi\bif\bfo\boa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
16685 | |
16686 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16687 | m\bmk\bkf\bfi\bif\bfo\bo() creates a new FIFO file with name _\bp_\ba_\bt_\bh. The access permissions |
16688 | are specified by _\bm_\bo_\bd_\be and restricted by the umask(2) of the calling |
16689 | process. |
16690 | |
16691 | The FIFO's owner ID is set to the process's effective user ID. The |
16692 | FIFO's group ID is set to that of the parent directory in which it is |
16693 | created. |
16694 | |
16695 | The m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() function is equivalent to m\bmk\bkf\bfi\bif\bfo\bo() except that where _\bp_\ba_\bt_\bh |
16696 | specifies a relative path, the newly created FIFO is created relative to |
16697 | the directory associated with file descriptor _\bf_\bd instead of the current |
16698 | working directory. |
16699 | |
16700 | If m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
16701 | in the _\bf_\bd parameter, the current working directory is used and the |
16702 | behavior is identical to a call to m\bmk\bkf\bfi\bif\bfo\bo(). |
16703 | |
16704 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16705 | Upon successful completion, the value 0 is returned; otherwise the |
16706 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16707 | error. |
16708 | |
16709 | E\bER\bRR\bRO\bOR\bRS\bS |
16710 | m\bmk\bkf\bfi\bif\bfo\bo() and m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() will fail and no FIFO will be created if: |
16711 | |
16712 | [EOPNOTSUPP] The kernel has not been configured to support FIFOs. |
16713 | |
16714 | [ENOTDIR] A component of the path prefix is not a directory. |
16715 | |
16716 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
16717 | characters, or an entire pathname (including the |
16718 | terminating NUL) exceeded PATH_MAX bytes. |
16719 | |
16720 | [ENOENT] A component of the path prefix does not exist. |
16721 | |
16722 | [EACCES] Search permission is denied for a component of the |
16723 | path prefix. |
16724 | |
16725 | [ELOOP] Too many symbolic links were encountered in |
16726 | translating the pathname. |
16727 | |
16728 | [EROFS] The named file resides on a read-only file system. |
16729 | |
16730 | [EEXIST] The named file exists. |
16731 | |
16732 | [ENOSPC] The directory in which the entry for the new FIFO is |
16733 | being placed cannot be extended because there is no |
16734 | space left on the file system containing the |
16735 | directory. |
16736 | |
16737 | [ENOSPC] There are no free inodes on the file system on which |
16738 | the FIFO is being created. |
16739 | |
16740 | [EDQUOT] The directory in which the entry for the new FIFO is |
16741 | being placed cannot be extended because the user's |
16742 | quota of disk blocks on the file system containing the |
16743 | directory has been exhausted. |
16744 | |
16745 | [EDQUOT] The user's quota of inodes on the file system on which |
16746 | the FIFO is being created has been exhausted. |
16747 | |
16748 | [EIO] An I/O error occurred while making the directory entry |
16749 | or allocating the inode. |
16750 | |
16751 | [EIO] An I/O error occurred while reading from or writing to |
16752 | the file system. |
16753 | |
16754 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
16755 | space. |
16756 | |
16757 | Additionally, m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() will fail if: |
16758 | |
16759 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16760 | argument is neither AT_FDCWD nor a valid file |
16761 | descriptor. |
16762 | |
16763 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16764 | argument is a valid file descriptor but it does not |
16765 | reference a directory. |
16766 | |
16767 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
16768 | permission is denied for the directory which the _\bf_\bd |
16769 | file descriptor references. |
16770 | |
16771 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16772 | chmod(2), stat(2), umask(2) |
16773 | |
16774 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
16775 | The m\bmk\bkf\bfi\bif\bfo\bo and m\bmk\bkf\bfi\bif\bfo\boa\bat\bt functions conform to IEEE Std 1003.1-2008 |
16776 | (``POSIX.1''). |
16777 | |
16778 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16779 | The m\bmk\bkf\bfi\bif\bfo\boa\bat\bt function appeared in OpenBSD 5.0. |
16780 | |
16781 | N\bNA\bAM\bME\bE |
16782 | m\bmk\bkf\bfi\bif\bfo\bo, m\bmk\bkf\bfi\bif\bfo\boa\bat\bt - make a FIFO file |
16783 | |
16784 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16785 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16786 | |
16787 | _\bi_\bn_\bt |
16788 | m\bmk\bkf\bfi\bif\bfo\bo(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
16789 | |
16790 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16791 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
16792 | |
16793 | _\bi_\bn_\bt |
16794 | m\bmk\bkf\bfi\bif\bfo\boa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be); |
16795 | |
16796 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16797 | m\bmk\bkf\bfi\bif\bfo\bo() creates a new FIFO file with name _\bp_\ba_\bt_\bh. The access permissions |
16798 | are specified by _\bm_\bo_\bd_\be and restricted by the umask(2) of the calling |
16799 | process. |
16800 | |
16801 | The FIFO's owner ID is set to the process's effective user ID. The |
16802 | FIFO's group ID is set to that of the parent directory in which it is |
16803 | created. |
16804 | |
16805 | The m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() function is equivalent to m\bmk\bkf\bfi\bif\bfo\bo() except that where _\bp_\ba_\bt_\bh |
16806 | specifies a relative path, the newly created FIFO is created relative to |
16807 | the directory associated with file descriptor _\bf_\bd instead of the current |
16808 | working directory. |
16809 | |
16810 | If m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
16811 | in the _\bf_\bd parameter, the current working directory is used and the |
16812 | behavior is identical to a call to m\bmk\bkf\bfi\bif\bfo\bo(). |
16813 | |
16814 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16815 | Upon successful completion, the value 0 is returned; otherwise the |
16816 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16817 | error. |
16818 | |
16819 | E\bER\bRR\bRO\bOR\bRS\bS |
16820 | m\bmk\bkf\bfi\bif\bfo\bo() and m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() will fail and no FIFO will be created if: |
16821 | |
16822 | [EOPNOTSUPP] The kernel has not been configured to support FIFOs. |
16823 | |
16824 | [ENOTDIR] A component of the path prefix is not a directory. |
16825 | |
16826 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
16827 | characters, or an entire pathname (including the |
16828 | terminating NUL) exceeded PATH_MAX bytes. |
16829 | |
16830 | [ENOENT] A component of the path prefix does not exist. |
16831 | |
16832 | [EACCES] Search permission is denied for a component of the |
16833 | path prefix. |
16834 | |
16835 | [ELOOP] Too many symbolic links were encountered in |
16836 | translating the pathname. |
16837 | |
16838 | [EROFS] The named file resides on a read-only file system. |
16839 | |
16840 | [EEXIST] The named file exists. |
16841 | |
16842 | [ENOSPC] The directory in which the entry for the new FIFO is |
16843 | being placed cannot be extended because there is no |
16844 | space left on the file system containing the |
16845 | directory. |
16846 | |
16847 | [ENOSPC] There are no free inodes on the file system on which |
16848 | the FIFO is being created. |
16849 | |
16850 | [EDQUOT] The directory in which the entry for the new FIFO is |
16851 | being placed cannot be extended because the user's |
16852 | quota of disk blocks on the file system containing the |
16853 | directory has been exhausted. |
16854 | |
16855 | [EDQUOT] The user's quota of inodes on the file system on which |
16856 | the FIFO is being created has been exhausted. |
16857 | |
16858 | [EIO] An I/O error occurred while making the directory entry |
16859 | or allocating the inode. |
16860 | |
16861 | [EIO] An I/O error occurred while reading from or writing to |
16862 | the file system. |
16863 | |
16864 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
16865 | space. |
16866 | |
16867 | Additionally, m\bmk\bkf\bfi\bif\bfo\boa\bat\bt() will fail if: |
16868 | |
16869 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16870 | argument is neither AT_FDCWD nor a valid file |
16871 | descriptor. |
16872 | |
16873 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16874 | argument is a valid file descriptor but it does not |
16875 | reference a directory. |
16876 | |
16877 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
16878 | permission is denied for the directory which the _\bf_\bd |
16879 | file descriptor references. |
16880 | |
16881 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
16882 | chmod(2), stat(2), umask(2) |
16883 | |
16884 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
16885 | The m\bmk\bkf\bfi\bif\bfo\bo and m\bmk\bkf\bfi\bif\bfo\boa\bat\bt functions conform to IEEE Std 1003.1-2008 |
16886 | (``POSIX.1''). |
16887 | |
16888 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
16889 | The m\bmk\bkf\bfi\bif\bfo\boa\bat\bt function appeared in OpenBSD 5.0. |
16890 | |
16891 | N\bNA\bAM\bME\bE |
16892 | m\bmk\bkn\bno\bod\bd, m\bmk\bkn\bno\bod\bda\bat\bt - make a special file node |
16893 | |
16894 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
16895 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16896 | |
16897 | _\bi_\bn_\bt |
16898 | m\bmk\bkn\bno\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bd_\be_\bv_\b__\bt _\bd_\be_\bv); |
16899 | |
16900 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
16901 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
16902 | |
16903 | _\bi_\bn_\bt |
16904 | m\bmk\bkn\bno\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bd_\be_\bv_\b__\bt _\bd_\be_\bv); |
16905 | |
16906 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
16907 | The m\bmk\bkn\bno\bod\bd() function creates _\bp_\ba_\bt_\bh with a file type and mode of _\bm_\bo_\bd_\be, as |
16908 | modified by umask(2). Only FIFO and device special files are supported |
16909 | by this implementation. |
16910 | |
16911 | If _\bm_\bo_\bd_\be is the bitwise OR of S_IFIFO and zero or more file permissions, |
16912 | and _\bd_\be_\bv is zero, then a FIFO is created. If _\bm_\bo_\bd_\be is the bitwise OR of |
16913 | S_IFCHR or S_IFBLK and zero or more file permissions, then a character or |
16914 | block device special (respectively) is created with major and minor |
16915 | device numbers extracted from _\bd_\be_\bv. |
16916 | |
16917 | The m\bmk\bkn\bno\bod\bda\bat\bt() function is equivalent to m\bmk\bkn\bno\bod\bd() except that where _\bp_\ba_\bt_\bh |
16918 | specifies a relative path, the newly created device special file is |
16919 | created relative to the directory associated with file descriptor _\bf_\bd |
16920 | instead of the current working directory. |
16921 | |
16922 | If m\bmk\bkn\bno\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
16923 | in the _\bf_\bd parameter, the current working directory is used and the |
16924 | behavior is identical to a call to m\bmk\bkn\bno\bod\bd(). |
16925 | |
16926 | Creating a device special file with m\bmk\bkn\bno\bod\bd() or m\bmk\bkn\bno\bod\bda\bat\bt() requires |
16927 | superuser privileges. |
16928 | |
16929 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
16930 | Upon successful completion, the value 0 is returned; otherwise the |
16931 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
16932 | error. |
16933 | |
16934 | E\bER\bRR\bRO\bOR\bRS\bS |
16935 | m\bmk\bkn\bno\bod\bd() and m\bmk\bkn\bno\bod\bda\bat\bt() will fail and the file will be not created if: |
16936 | |
16937 | [EINVAL] _\bm_\bo_\bd_\be is an invalid file type or _\bd_\be_\bv is an invalid |
16938 | value for that file type. |
16939 | |
16940 | [ENOTDIR] A component of the path prefix is not a directory. |
16941 | |
16942 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
16943 | characters, or an entire pathname (including the |
16944 | terminating NUL) exceeded PATH_MAX bytes. |
16945 | |
16946 | [ENOENT] A component of the path prefix does not exist. |
16947 | |
16948 | [EACCES] Search permission is denied for a component of the |
16949 | path prefix. |
16950 | |
16951 | [ELOOP] Too many symbolic links were encountered in |
16952 | translating the pathname. |
16953 | |
16954 | [EPERM] _\bm_\bo_\bd_\be is a device special and the process's effective |
16955 | user ID is not superuser. |
16956 | |
16957 | [EIO] An I/O error occurred while making the directory entry |
16958 | or allocating the inode. |
16959 | |
16960 | [ENOSPC] The directory in which the entry for the new node is |
16961 | being placed cannot be extended because there is no |
16962 | space left on the file system containing the |
16963 | directory. |
16964 | |
16965 | [ENOSPC] There are no free inodes on the file system on which |
16966 | the node is being created. |
16967 | |
16968 | [EDQUOT] The directory in which the entry for the new node is |
16969 | being placed cannot be extended because the user's |
16970 | quota of disk blocks on the file system containing the |
16971 | directory has been exhausted. |
16972 | |
16973 | [EDQUOT] The user's quota of inodes on the file system on which |
16974 | the node is being created has been exhausted. |
16975 | |
16976 | [EROFS] The named file resides on a read-only file system. |
16977 | |
16978 | [EEXIST] The named file exists. |
16979 | |
16980 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
16981 | space. |
16982 | |
16983 | [EINVAL] The process is running within an alternate root |
16984 | directory, as created by chroot(2). |
16985 | |
16986 | Additionally, m\bmk\bkn\bno\bod\bda\bat\bt() will fail if: |
16987 | |
16988 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16989 | argument is neither AT_FDCWD nor a valid file |
16990 | descriptor. |
16991 | |
16992 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
16993 | argument is a valid file descriptor but it does not |
16994 | reference a directory. |
16995 | |
16996 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
16997 | permission is denied for the directory which the _\bf_\bd |
16998 | file descriptor references. |
16999 | |
17000 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17001 | chmod(2), chroot(2), mkfifo(2), stat(2), umask(2) |
17002 | |
17003 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
17004 | The m\bmk\bkn\bno\bod\bd() and m\bmk\bkn\bno\bod\bda\bat\bt() functions conform to IEEE Std 1003.1-2008 |
17005 | (``POSIX.1''). |
17006 | |
17007 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17008 | The m\bmk\bkn\bno\bod\bd() system call first appeared in Version 4 AT&T UNIX, and |
17009 | m\bmk\bkn\bno\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
17010 | |
17011 | N\bNA\bAM\bME\bE |
17012 | m\bmk\bkn\bno\bod\bd, m\bmk\bkn\bno\bod\bda\bat\bt - make a special file node |
17013 | |
17014 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17015 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
17016 | |
17017 | _\bi_\bn_\bt |
17018 | m\bmk\bkn\bno\bod\bd(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bd_\be_\bv_\b__\bt _\bd_\be_\bv); |
17019 | |
17020 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
17021 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
17022 | |
17023 | _\bi_\bn_\bt |
17024 | m\bmk\bkn\bno\bod\bda\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bm_\bo_\bd_\be_\b__\bt _\bm_\bo_\bd_\be, _\bd_\be_\bv_\b__\bt _\bd_\be_\bv); |
17025 | |
17026 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17027 | The m\bmk\bkn\bno\bod\bd() function creates _\bp_\ba_\bt_\bh with a file type and mode of _\bm_\bo_\bd_\be, as |
17028 | modified by umask(2). Only FIFO and device special files are supported |
17029 | by this implementation. |
17030 | |
17031 | If _\bm_\bo_\bd_\be is the bitwise OR of S_IFIFO and zero or more file permissions, |
17032 | and _\bd_\be_\bv is zero, then a FIFO is created. If _\bm_\bo_\bd_\be is the bitwise OR of |
17033 | S_IFCHR or S_IFBLK and zero or more file permissions, then a character or |
17034 | block device special (respectively) is created with major and minor |
17035 | device numbers extracted from _\bd_\be_\bv. |
17036 | |
17037 | The m\bmk\bkn\bno\bod\bda\bat\bt() function is equivalent to m\bmk\bkn\bno\bod\bd() except that where _\bp_\ba_\bt_\bh |
17038 | specifies a relative path, the newly created device special file is |
17039 | created relative to the directory associated with file descriptor _\bf_\bd |
17040 | instead of the current working directory. |
17041 | |
17042 | If m\bmk\bkn\bno\bod\bda\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
17043 | in the _\bf_\bd parameter, the current working directory is used and the |
17044 | behavior is identical to a call to m\bmk\bkn\bno\bod\bd(). |
17045 | |
17046 | Creating a device special file with m\bmk\bkn\bno\bod\bd() or m\bmk\bkn\bno\bod\bda\bat\bt() requires |
17047 | superuser privileges. |
17048 | |
17049 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17050 | Upon successful completion, the value 0 is returned; otherwise the |
17051 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
17052 | error. |
17053 | |
17054 | E\bER\bRR\bRO\bOR\bRS\bS |
17055 | m\bmk\bkn\bno\bod\bd() and m\bmk\bkn\bno\bod\bda\bat\bt() will fail and the file will be not created if: |
17056 | |
17057 | [EINVAL] _\bm_\bo_\bd_\be is an invalid file type or _\bd_\be_\bv is an invalid |
17058 | value for that file type. |
17059 | |
17060 | [ENOTDIR] A component of the path prefix is not a directory. |
17061 | |
17062 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
17063 | characters, or an entire pathname (including the |
17064 | terminating NUL) exceeded PATH_MAX bytes. |
17065 | |
17066 | [ENOENT] A component of the path prefix does not exist. |
17067 | |
17068 | [EACCES] Search permission is denied for a component of the |
17069 | path prefix. |
17070 | |
17071 | [ELOOP] Too many symbolic links were encountered in |
17072 | translating the pathname. |
17073 | |
17074 | [EPERM] _\bm_\bo_\bd_\be is a device special and the process's effective |
17075 | user ID is not superuser. |
17076 | |
17077 | [EIO] An I/O error occurred while making the directory entry |
17078 | or allocating the inode. |
17079 | |
17080 | [ENOSPC] The directory in which the entry for the new node is |
17081 | being placed cannot be extended because there is no |
17082 | space left on the file system containing the |
17083 | directory. |
17084 | |
17085 | [ENOSPC] There are no free inodes on the file system on which |
17086 | the node is being created. |
17087 | |
17088 | [EDQUOT] The directory in which the entry for the new node is |
17089 | being placed cannot be extended because the user's |
17090 | quota of disk blocks on the file system containing the |
17091 | directory has been exhausted. |
17092 | |
17093 | [EDQUOT] The user's quota of inodes on the file system on which |
17094 | the node is being created has been exhausted. |
17095 | |
17096 | [EROFS] The named file resides on a read-only file system. |
17097 | |
17098 | [EEXIST] The named file exists. |
17099 | |
17100 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
17101 | space. |
17102 | |
17103 | [EINVAL] The process is running within an alternate root |
17104 | directory, as created by chroot(2). |
17105 | |
17106 | Additionally, m\bmk\bkn\bno\bod\bda\bat\bt() will fail if: |
17107 | |
17108 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
17109 | argument is neither AT_FDCWD nor a valid file |
17110 | descriptor. |
17111 | |
17112 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
17113 | argument is a valid file descriptor but it does not |
17114 | reference a directory. |
17115 | |
17116 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
17117 | permission is denied for the directory which the _\bf_\bd |
17118 | file descriptor references. |
17119 | |
17120 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17121 | chmod(2), chroot(2), mkfifo(2), stat(2), umask(2) |
17122 | |
17123 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
17124 | The m\bmk\bkn\bno\bod\bd() and m\bmk\bkn\bno\bod\bda\bat\bt() functions conform to IEEE Std 1003.1-2008 |
17125 | (``POSIX.1''). |
17126 | |
17127 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17128 | The m\bmk\bkn\bno\bod\bd() system call first appeared in Version 4 AT&T UNIX, and |
17129 | m\bmk\bkn\bno\bod\bda\bat\bt() has been available since OpenBSD 5.0. |
17130 | |
17131 | N\bNA\bAM\bME\bE |
17132 | m\bml\blo\boc\bck\bk, m\bmu\bun\bnl\blo\boc\bck\bk - lock (unlock) physical pages in memory |
17133 | |
17134 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17135 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
17136 | |
17137 | _\bi_\bn_\bt |
17138 | m\bml\blo\boc\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
17139 | |
17140 | _\bi_\bn_\bt |
17141 | m\bmu\bun\bnl\blo\boc\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
17142 | |
17143 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17144 | The m\bml\blo\boc\bck\bk() system call locks into memory the physical pages associated |
17145 | with the virtual address range starting at _\ba_\bd_\bd_\br for _\bl_\be_\bn bytes. The |
17146 | m\bmu\bun\bnl\blo\boc\bck\bk() call unlocks pages previously locked by one or more m\bml\blo\boc\bck\bk() |
17147 | calls. For both, the _\ba_\bd_\bd_\br parameter should be aligned to a multiple of |
17148 | the page size. If the _\bl_\be_\bn parameter is not a multiple of the page size, |
17149 | it will be rounded up to be so. The entire range must be allocated. |
17150 | |
17151 | After an m\bml\blo\boc\bck\bk() call, the indicated pages will cause neither a non- |
17152 | resident page nor address-translation fault until they are unlocked. |
17153 | They may still cause protection-violation faults or TLB-miss faults on |
17154 | architectures with software-managed TLBs. The physical pages remain in |
17155 | memory until all locked mappings for the pages are removed. Multiple |
17156 | processes may have the same physical pages locked via their own virtual |
17157 | address mappings. A single process may likewise have pages multiply |
17158 | locked via different virtual mappings of the same pages or via nested |
17159 | m\bml\blo\boc\bck\bk() calls on the same address range. Unlocking is performed |
17160 | explicitly by m\bmu\bun\bnl\blo\boc\bck\bk() or implicitly by a call to munmap(2) which |
17161 | deallocates the unmapped address range. Locked mappings are not |
17162 | inherited by the child process after a fork(2). |
17163 | |
17164 | Since physical memory is a potentially scarce resource, processes are |
17165 | limited in how much they can lock down. A single process can m\bml\blo\boc\bck\bk() the |
17166 | minimum of a system-wide ``wired pages'' limit and the per-process |
17167 | RLIMIT_MEMLOCK resource limit. |
17168 | |
17169 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17170 | The m\bml\blo\boc\bck\bk() and m\bmu\bun\bnl\blo\boc\bck\bk() functions return the value 0 if successful; |
17171 | otherwise the value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
17172 | to indicate the error. |
17173 | |
17174 | E\bER\bRR\bRO\bOR\bRS\bS |
17175 | m\bml\blo\boc\bck\bk() will fail if: |
17176 | |
17177 | [EINVAL] The address given is not page aligned or the length is |
17178 | negative. |
17179 | |
17180 | [EAGAIN] Locking the indicated range would exceed either the |
17181 | system or per-process limit for locked memory. |
17182 | |
17183 | [ENOMEM] Some portion of the indicated address range is not |
17184 | allocated. There was an error faulting/mapping a |
17185 | page. |
17186 | |
17187 | m\bmu\bun\bnl\blo\boc\bck\bk() will fail if: |
17188 | |
17189 | [EINVAL] The address given is not page aligned or _\ba_\bd_\bd_\br and _\bs_\bi_\bz_\be |
17190 | specify a region that would extend beyond the end of |
17191 | the address space. |
17192 | |
17193 | [ENOMEM] Some portion of the indicated address range is not |
17194 | allocated. Some portion of the indicated address |
17195 | range is not locked. |
17196 | |
17197 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17198 | fork(2), mincore(2), minherit(2), mlockall(2), mmap(2), munmap(2), |
17199 | setrlimit(2), getpagesize(3) |
17200 | |
17201 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17202 | The m\bml\blo\boc\bck\bk() and m\bmu\bun\bnl\blo\boc\bck\bk() functions first appeared in 4.4BSD. |
17203 | |
17204 | B\bBU\bUG\bGS\bS |
17205 | Unlike Sun's implementation, multiple m\bml\blo\boc\bck\bk() calls on the same address |
17206 | range require the corresponding number of m\bmu\bun\bnl\blo\boc\bck\bk() calls to actually |
17207 | unlock the pages, i.e., m\bml\blo\boc\bck\bk() nests. This should be considered a |
17208 | consequence of the implementation and not a feature. |
17209 | |
17210 | The per-process resource limit is a limit on the amount of virtual memory |
17211 | locked, while the system-wide limit is for the number of locked physical |
17212 | pages. Hence a process with two distinct locked mappings of the same |
17213 | physical page counts as 2 pages against the per-process limit and as only |
17214 | a single page in the system limit. |
17215 | |
17216 | N\bNA\bAM\bME\bE |
17217 | m\bml\blo\boc\bck\bka\bal\bll\bl, m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl - lock (unlock) the address space of a process |
17218 | |
17219 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17220 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
17221 | |
17222 | _\bi_\bn_\bt |
17223 | m\bml\blo\boc\bck\bka\bal\bll\bl(_\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
17224 | |
17225 | _\bi_\bn_\bt |
17226 | m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl(_\bv_\bo_\bi_\bd); |
17227 | |
17228 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17229 | The m\bml\blo\boc\bck\bka\bal\bll\bl() system call locks into memory the physical pages |
17230 | associated with the address space of a process until the address space is |
17231 | unlocked, the process exits, or execs another program image. |
17232 | |
17233 | The following flags affect the behavior of m\bml\blo\boc\bck\bka\bal\bll\bl(): |
17234 | |
17235 | MCL_CURRENT Lock all pages currently mapped into the process's address |
17236 | space. |
17237 | |
17238 | MCL_FUTURE Lock all pages mapped into the process's address space in |
17239 | the future, at the time the mapping is established. Note |
17240 | that this may cause future mappings to fail if those |
17241 | mappings cause resource limits to be exceeded. |
17242 | |
17243 | Since physical memory is a potentially scarce resource, processes are |
17244 | limited in how much they can lock down. A single process can lock the |
17245 | minimum of a system-wide ``wired pages'' limit and the per-process |
17246 | RLIMIT_MEMLOCK resource limit. |
17247 | |
17248 | The m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() call unlocks any locked memory regions in the process |
17249 | address space. Any regions mapped after an m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() call will not be |
17250 | locked. |
17251 | |
17252 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17253 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions return the value 0 if |
17254 | successful; otherwise the value -1 is returned and the global variable |
17255 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
17256 | |
17257 | E\bER\bRR\bRO\bOR\bRS\bS |
17258 | m\bml\blo\boc\bck\bka\bal\bll\bl() will fail if: |
17259 | |
17260 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs argument is zero or includes unimplemented |
17261 | flags. |
17262 | |
17263 | [ENOMEM] Locking all of the pages currently mapped would exceed |
17264 | either the system or per-process limit for locked |
17265 | memory. |
17266 | |
17267 | [EAGAIN] Some or all of the memory mapped into the process's |
17268 | address space could not be locked when the call was |
17269 | made. |
17270 | |
17271 | [EPERM] The calling process does not have the appropriate |
17272 | privileges to perform the requested operation. |
17273 | |
17274 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17275 | mincore(2), mlock(2), mmap(2), munmap(2), setrlimit(2) |
17276 | |
17277 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
17278 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions conform to IEEE Std 1003.1-2008 |
17279 | (``POSIX.1''). |
17280 | |
17281 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17282 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions first appeared in OpenBSD 2.9. |
17283 | |
17284 | B\bBU\bUG\bGS\bS |
17285 | The per-process resource limit is a limit on the amount of virtual memory |
17286 | locked, while the system-wide limit is for the number of locked physical |
17287 | pages. Hence a process with two distinct locked mappings of the same |
17288 | physical page counts as 2 pages against the per-process limit and only as |
17289 | a single page in the system limit. |
17290 | |
17291 | N\bNA\bAM\bME\bE |
17292 | m\bmm\bma\bap\bp - map files or devices into memory |
17293 | |
17294 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17295 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
17296 | |
17297 | _\bv_\bo_\bi_\bd _\b* |
17298 | m\bmm\bma\bap\bp(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bp_\br_\bo_\bt, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\bf_\bd, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
17299 | |
17300 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17301 | The m\bmm\bma\bap\bp() function causes the contents of _\bf_\bd, starting at _\bo_\bf_\bf_\bs_\be_\bt, to be |
17302 | mapped in memory at the given _\ba_\bd_\bd_\br. The mapping will extend at least _\bl_\be_\bn |
17303 | bytes, subject to page alignment restrictions. |
17304 | |
17305 | The _\ba_\bd_\bd_\br argument describes the address where the system should place the |
17306 | mapping. If the MAP_FIXED flag is specified, the allocation will happen |
17307 | at the specified address, replacing any previously established mappings |
17308 | in its range. Otherwise, the mapping will be placed at the available |
17309 | spot at _\ba_\bd_\bd_\br; failing that it will be placed "close by". If _\ba_\bd_\bd_\br is NULL |
17310 | the system can pick any address. Except for MAP_FIXED mappings, the |
17311 | system will never replace existing mappings. |
17312 | |
17313 | The _\bl_\be_\bn argument describes the minimum amount of bytes the mapping will |
17314 | span. Since m\bmm\bma\bap\bp() maps pages into memory, _\bl_\be_\bn may be rounded up to hit |
17315 | a page boundary. If _\bl_\be_\bn is 0, the mapping will fail with EINVAL. |
17316 | |
17317 | If an _\bf_\bd and _\bo_\bf_\bf_\bs_\be_\bt are specified, the resulting address may end up not |
17318 | on a page boundary, in order to align the page offset in the _\ba_\bd_\bd_\br to the |
17319 | page offset in _\bo_\bf_\bf_\bs_\be_\bt. |
17320 | |
17321 | The protections (region accessibility) are specified in the _\bp_\br_\bo_\bt |
17322 | argument. It should either be PROT_NONE (no permissions) or the bitwise |
17323 | OR of one or more of the following values: |
17324 | |
17325 | PROT_EXEC Pages may be executed. |
17326 | PROT_READ Pages may be read. |
17327 | PROT_WRITE Pages may be written. |
17328 | |
17329 | The _\bf_\bl_\ba_\bg_\bs parameter specifies the type of the mapped object, mapping |
17330 | options, and whether modifications made to the mapped copy of the page |
17331 | are private to the process or are to be shared with other references. |
17332 | Sharing, mapping type, and options are specified in the _\bf_\bl_\ba_\bg_\bs argument by |
17333 | OR'ing the following values. Exactly one of the first two values must be |
17334 | specified: |
17335 | |
17336 | MAP_PRIVATE Modifications are private. |
17337 | |
17338 | MAP_SHARED Modifications are shared. |
17339 | |
17340 | Any combination of the following flags may additionally be used: |
17341 | |
17342 | MAP_ANON Map anonymous memory not associated with any |
17343 | specific file. The file descriptor used for |
17344 | creating MAP_ANON must currently be -1 indicating no |
17345 | name is associated with the region. |
17346 | |
17347 | MAP_ANONYMOUS Synonym for MAP_ANON. |
17348 | |
17349 | MAP_FIXED Demand that the mapping is placed at _\ba_\bd_\bd_\br, rather |
17350 | than having the system select a location. _\ba_\bd_\bd_\br, _\bl_\be_\bn |
17351 | and _\bo_\bf_\bf_\bs_\be_\bt (in the case of _\bf_\bd mappings) must be |
17352 | multiples of the page size. Existing mappings in |
17353 | the address range will be replaced. Use of this |
17354 | option is discouraged. |
17355 | |
17356 | Finally, the following flags are also provided for source compatibility |
17357 | with code written for other operating systems, but are not recommended |
17358 | for use in new OpenBSD code: |
17359 | |
17360 | MAP_COPY Modifications are private and, unlike MAP_PRIVATE, |
17361 | modifications made by others are not visible. On |
17362 | OpenBSD this behaves just like MAP_PRIVATE. |
17363 | |
17364 | MAP_FILE Mapped from a regular file, character special file, |
17365 | or block special file specified by file descriptor |
17366 | _\bf_\bd. On OpenBSD and all systems conforming to IEEE |
17367 | Std 1003.1-2008 (``POSIX.1'') this is the default |
17368 | mapping type and need not be specified. |
17369 | |
17370 | MAP_HASSEMAPHORE |
17371 | Notify the kernel that the region may contain |
17372 | semaphores and that special handling may be |
17373 | necessary. On OpenBSD this flag is ignored. |
17374 | |
17375 | MAP_INHERIT Permit regions to be inherited across exec(3) system |
17376 | calls. On OpenBSD this flag is ignored. |
17377 | |
17378 | MAP_TRYFIXED Attempt to use the hint provided by _\ba_\bd_\bd_\br. On |
17379 | OpenBSD this is the default behavior. |
17380 | |
17381 | The close(2) function does not unmap pages; see munmap(2) for further |
17382 | information. |
17383 | |
17384 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17385 | The m\bmm\bma\bap\bp() function returns a pointer to the mapped region if successful; |
17386 | otherwise the value MAP_FAILED is returned and the global variable _\be_\br_\br_\bn_\bo |
17387 | is set to indicate the error. A successful return from m\bmm\bma\bap\bp() will never |
17388 | return the value MAP_FAILED. |
17389 | |
17390 | E\bER\bRR\bRO\bOR\bRS\bS |
17391 | m\bmm\bma\bap\bp() will fail if: |
17392 | |
17393 | [EACCES] The flag PROT_READ was specified as part of the _\bp_\br_\bo_\bt |
17394 | parameter and _\bf_\bd was not open for reading. The flags |
17395 | MAP_SHARED and PROT_WRITE were specified as part of |
17396 | the _\bf_\bl_\ba_\bg_\bs and _\bp_\br_\bo_\bt parameters and _\bf_\bd was not open for |
17397 | writing. |
17398 | |
17399 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
17400 | |
17401 | [EINVAL] MAP_PRIVATE and MAP_SHARED were both specified. |
17402 | |
17403 | [EINVAL] MAP_FIXED was specified and the _\ba_\bd_\bd_\br parameter was not |
17404 | page aligned. |
17405 | |
17406 | [EINVAL] _\ba_\bd_\bd_\br and _\bl_\be_\bn specified a region that would extend |
17407 | beyond the end of the address space. |
17408 | |
17409 | [EINVAL] _\bf_\bd did not specify a regular, character special, or |
17410 | block special file. |
17411 | |
17412 | [EINVAL] The allocation _\bl_\be_\bn was 0. |
17413 | |
17414 | [ENOMEM] MAP_FIXED was specified and the _\ba_\bd_\bd_\br parameter wasn't |
17415 | available. MAP_ANON was specified and insufficient |
17416 | memory was available. |
17417 | |
17418 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17419 | madvise(2), mincore(2), mlock(2), mprotect(2), mquery(2), msync(2), |
17420 | munmap(2), getpagesize(3) |
17421 | |
17422 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
17423 | The m\bmm\bma\bap\bp() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
17424 | |
17425 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17426 | The m\bmm\bma\bap\bp() system call first appeared in 4.1cBSD. |
17427 | |
17428 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
17429 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that references to pages |
17430 | beyond the end of a mapped object shall generate a SIGBUS signal; |
17431 | however, OpenBSD generates a SIGSEGV signal in this case instead. |
17432 | |
17433 | Additionally, IEEE Std 1003.1-2008 (``POSIX.1'') specifies that m\bmm\bma\bap\bp() |
17434 | shall fail with EINVAL if neither MAP_PRIVATE nor MAP_SHARED is specified |
17435 | by _\bf_\bl_\ba_\bg_\bs; however, for compatibility with old programs, OpenBSD instead |
17436 | defaults to MAP_SHARED for mappings of character special files, and to |
17437 | MAP_PRIVATE for all other mappings. New programs should not rely on this |
17438 | behavior. |
17439 | |
17440 | B\bBU\bUG\bGS\bS |
17441 | Due to a limitation of the current vm system (see uvm(9)), mapping |
17442 | descriptors PROT_WRITE without also specifying PROT_READ is useless |
17443 | (results in a segmentation fault when first accessing the mapping). This |
17444 | means that such descriptors must be opened with O_RDWR, which requires |
17445 | both read and write permissions on the underlying object. |
17446 | |
17447 | N\bNA\bAM\bME\bE |
17448 | m\bmo\bou\bun\bnt\bt, u\bun\bnm\bmo\bou\bun\bnt\bt - mount or dismount a filesystem |
17449 | |
17450 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17451 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
17452 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
17453 | |
17454 | _\bi_\bn_\bt |
17455 | m\bmo\bou\bun\bnt\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\by_\bp_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bv_\bo_\bi_\bd _\b*_\bd_\ba_\bt_\ba); |
17456 | |
17457 | _\bi_\bn_\bt |
17458 | u\bun\bnm\bmo\bou\bun\bnt\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
17459 | |
17460 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17461 | The m\bmo\bou\bun\bnt\bt() function grafts a filesystem object onto the system file tree |
17462 | at the point _\bd_\bi_\br. The argument _\bd_\ba_\bt_\ba describes the filesystem object to |
17463 | be mounted. The argument _\bt_\by_\bp_\be tells the kernel how to interpret _\bd_\ba_\bt_\ba |
17464 | (see _\bt_\by_\bp_\be below). The contents of the filesystem become available |
17465 | through the new mount point _\bd_\bi_\br. Any files in _\bd_\bi_\br at the time of a |
17466 | successful mount are swept under the carpet, so to speak, and are |
17467 | unavailable until the filesystem is unmounted. |
17468 | |
17469 | The following _\bf_\bl_\ba_\bg_\bs may be specified to suppress default semantics which |
17470 | affect filesystem access. |
17471 | |
17472 | MNT_RDONLY The filesystem should be treated as read-only: even the |
17473 | superuser may not write to it. |
17474 | |
17475 | MNT_NOATIME Do not update the access time on files in the filesystem |
17476 | unless the modification or status change times are also |
17477 | being updated. |
17478 | |
17479 | MNT_NOEXEC Do not allow files to be executed from the filesystem. |
17480 | |
17481 | MNT_NOSUID Do not honor setuid or setgid bits on files when |
17482 | executing them. |
17483 | |
17484 | MNT_NODEV Do not interpret special files on the filesystem. |
17485 | |
17486 | MNT_SYNCHRONOUS All I/O to the filesystem should be done synchronously. |
17487 | |
17488 | MNT_ASYNC All I/O to the filesystem should be done asynchronously. |
17489 | |
17490 | MNT_SOFTDEP Use soft dependencies. Applies to FFS filesystems only |
17491 | (see 'softdep' in mount(8)). |
17492 | |
17493 | The flag MNT_UPDATE indicates that the mount command is being applied to |
17494 | an already mounted filesystem. This allows the mount flags to be changed |
17495 | without requiring that the filesystem be unmounted and remounted. Some |
17496 | filesystems may not allow all flags to be changed. For example, most |
17497 | filesystems will not allow a change from read-write to read-only. |
17498 | |
17499 | The _\bt_\by_\bp_\be argument defines the type of the filesystem. The types of |
17500 | filesystems known to the system are defined in <_\bs_\by_\bs_\b/_\bm_\bo_\bu_\bn_\bt_\b._\bh>. _\bd_\ba_\bt_\ba is a |
17501 | pointer to a structure that contains the type specific arguments to |
17502 | mount. The currently supported types of filesystems and their type |
17503 | specific data are: |
17504 | |
17505 | MOUNT_CD9660 |
17506 | struct iso_args { |
17507 | char *fspec; /* block special device to mount */ |
17508 | struct export_args export_info; |
17509 | /* network export info */ |
17510 | int flags; /* mounting flags, see below */ |
17511 | }; |
17512 | #define ISOFSMNT_NORRIP 0x00000001 /* disable Rock Ridge Ext.*/ |
17513 | #define ISOFSMNT_GENS 0x00000002 /* enable generation numbers */ |
17514 | #define ISOFSMNT_EXTATT 0x00000004 /* enable extended attributes */ |
17515 | #define ISOFSMNT_NOJOLIET 0x00000008 /* disable Joliet Ext.*/ |
17516 | #define ISOFSMNT_SESS 0x00000010 /* use iso_args.sess */ |
17517 | |
17518 | MOUNT_FFS |
17519 | struct ufs_args { |
17520 | char *fspec; /* block special file to mount */ |
17521 | struct export_args export_info; |
17522 | /* network export information */ |
17523 | }; |
17524 | |
17525 | MOUNT_MFS |
17526 | struct mfs_args { |
17527 | char *fspec; /* name to export for statfs */ |
17528 | struct export_args export_info; |
17529 | /* if we can export an MFS */ |
17530 | caddr_t base; /* base of filesystem in mem */ |
17531 | u_long size; /* size of filesystem */ |
17532 | }; |
17533 | |
17534 | MOUNT_MSDOS |
17535 | struct msdosfs_args { |
17536 | char *fspec; /* blocks special holding fs to mount */ |
17537 | struct export_args export_info; |
17538 | /* network export information */ |
17539 | uid_t uid; /* uid that owns msdosfs files */ |
17540 | gid_t gid; /* gid that owns msdosfs files */ |
17541 | mode_t mask; /* mask to be applied for msdosfs perms */ |
17542 | int flags; /* see below */ |
17543 | }; |
17544 | |
17545 | /* |
17546 | * Msdosfs mount options: |
17547 | */ |
17548 | #define MSDOSFSMNT_SHORTNAME 1 /* Force old DOS short names only */ |
17549 | #define MSDOSFSMNT_LONGNAME 2 /* Force Win'95 long names */ |
17550 | #define MSDOSFSMNT_NOWIN95 4 /* Completely ignore Win95 entries */ |
17551 | |
17552 | MOUNT_NFS |
17553 | struct nfs_args { |
17554 | int version; /* args structure version */ |
17555 | struct sockaddr *addr; /* file server address */ |
17556 | int addrlen; /* length of address */ |
17557 | int sotype; /* Socket type */ |
17558 | int proto; /* and Protocol */ |
17559 | u_char *fh; /* File handle to be mounted */ |
17560 | int fhsize; /* Size, in bytes, of fh */ |
17561 | int flags; /* flags */ |
17562 | int wsize; /* write size in bytes */ |
17563 | int rsize; /* read size in bytes */ |
17564 | int readdirsize; /* readdir size in bytes */ |
17565 | int timeo; /* initial timeout in .1 secs */ |
17566 | int retrans; /* times to retry send */ |
17567 | int maxgrouplist; /* Max. size of group list */ |
17568 | int readahead; /* # of blocks to readahead */ |
17569 | int leaseterm; /* Term (sec) of lease */ |
17570 | int deadthresh; /* Retrans threshold */ |
17571 | char *hostname; /* server's name */ |
17572 | int acregmin; /* Attr cache file recently modified */ |
17573 | int acregmax; /* ac file not recently modified */ |
17574 | int acdirmin; /* ac for dir recently modified */ |
17575 | int acdirmax; /* ac for dir not recently modified */ |
17576 | }; |
17577 | |
17578 | MOUNT_NTFS |
17579 | struct ntfs_args { |
17580 | char *fspec; /* block special device to mount */ |
17581 | struct export_args export_info; |
17582 | /* network export information */ |
17583 | uid_t uid; /* uid that owns ntfs files */ |
17584 | gid_t gid; /* gid that owns ntfs files */ |
17585 | mode_t mode; /* mask to be applied for ntfs perms */ |
17586 | u_long flag; /* additional flags */ |
17587 | }; |
17588 | |
17589 | /* |
17590 | * ntfs mount options: |
17591 | */ |
17592 | #define NTFS_MFLAG_CASEINS 0x00000001 |
17593 | #define NTFS_MFLAG_ALLNAMES 0x00000002 |
17594 | |
17595 | MOUNT_UDF |
17596 | struct udf_args { |
17597 | char *fspec; /* block special device to mount */ |
17598 | }; |
17599 | |
17600 | The u\bun\bnm\bmo\bou\bun\bnt\bt() function call disassociates the filesystem from the |
17601 | specified mount point _\bd_\bi_\br. |
17602 | |
17603 | The _\bf_\bl_\ba_\bg_\bs argument may specify MNT_FORCE to specify that the filesystem |
17604 | should be forcibly unmounted even if files are still active. Active |
17605 | special devices continue to work, but any further accesses to any other |
17606 | active files result in errors even if the filesystem is later remounted. |
17607 | |
17608 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17609 | Upon successful completion, the value 0 is returned; otherwise the |
17610 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
17611 | error. |
17612 | |
17613 | E\bER\bRR\bRO\bOR\bRS\bS |
17614 | m\bmo\bou\bun\bnt\bt() will fail when one of the following occurs: |
17615 | |
17616 | [EPERM] The caller is not the superuser. |
17617 | |
17618 | [ENAMETOOLONG] The path name exceeded {MNAMELEN} characters. |
17619 | |
17620 | [ELOOP] Too many symbolic links were encountered in translating a |
17621 | pathname. |
17622 | |
17623 | [ENOENT] A component of _\bd_\bi_\br does not exist. |
17624 | |
17625 | [ENOTDIR] A component of _\bn_\ba_\bm_\be is not a directory, or a path prefix |
17626 | of _\bs_\bp_\be_\bc_\bi_\ba_\bl is not a directory. |
17627 | |
17628 | [EINVAL] An argument given was invalid. |
17629 | |
17630 | [EBUSY] Another process currently holds a reference to _\bd_\bi_\br. |
17631 | |
17632 | [EFAULT] _\bd_\bi_\br points outside the process's allocated address space. |
17633 | |
17634 | [EOPNOTSUPP] _\bt_\by_\bp_\be is not supported by the kernel. |
17635 | |
17636 | The following errors can occur for a ``ufs'' filesystem mount: |
17637 | |
17638 | [ENODEV] A component of ufs_args _\bf_\bs_\bp_\be_\bc does not exist. |
17639 | |
17640 | [ENOTBLK] _\bf_\bs_\bp_\be_\bc is not a block device. |
17641 | |
17642 | [ENXIO] The major device number of _\bf_\bs_\bp_\be_\bc is out of range (this |
17643 | indicates no device driver exists for the associated |
17644 | hardware). |
17645 | |
17646 | [EBUSY] _\bf_\bs_\bp_\be_\bc is already mounted. |
17647 | |
17648 | [EINVAL] The super block for the filesystem had a bad magic number, an |
17649 | out of range block size, or an invalid combination of flags. |
17650 | |
17651 | [ENOMEM] Not enough memory was available to read the cylinder group |
17652 | information for the filesystem. |
17653 | |
17654 | [EIO] An I/O error occurred while reading the super block or |
17655 | cylinder group information. |
17656 | |
17657 | [EFAULT] _\bf_\bs_\bp_\be_\bc points outside the process's allocated address space. |
17658 | |
17659 | [EROFS] The filesystem was not unmounted cleanly and MNT_FORCE was not |
17660 | specified. |
17661 | |
17662 | [EROFS] An attempt was made to mount a 4.2BSD filesystem without the |
17663 | MNT_RDONLY flag. |
17664 | |
17665 | The following errors can occur for an _\bN_\bF_\bS filesystem mount: |
17666 | |
17667 | [ETIMEDOUT] _\bN_\bF_\bS timed out trying to contact the server. |
17668 | |
17669 | [EFAULT] Some part of the information described by nfs_args points |
17670 | outside the process's allocated address space. |
17671 | |
17672 | The following errors can occur for a _\bm_\bf_\bs filesystem mount: |
17673 | |
17674 | [EMFILE] No space remains in the mount table. |
17675 | |
17676 | [EINVAL] The super block for the filesystem had a bad magic number or an |
17677 | out of range block size. |
17678 | |
17679 | [ENOMEM] Not enough memory was available to read the cylinder group |
17680 | information for the filesystem. |
17681 | |
17682 | [EIO] A paging error occurred while reading the super block or |
17683 | cylinder group information. |
17684 | |
17685 | [EFAULT] _\bN_\ba_\bm_\be points outside the process's allocated address space. |
17686 | |
17687 | u\bun\bnm\bmo\bou\bun\bnt\bt() may fail with one of the following errors: |
17688 | |
17689 | [EPERM] The caller is not the superuser. |
17690 | |
17691 | [ENOTDIR] A component of the path is not a directory. |
17692 | |
17693 | [EINVAL] An argument given was invalid. |
17694 | |
17695 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, |
17696 | or an entire pathname (including the terminating NUL) |
17697 | exceeded PATH_MAX bytes. |
17698 | |
17699 | [ELOOP] Too many symbolic links were encountered in translating |
17700 | the pathname. |
17701 | |
17702 | [EINVAL] The requested directory is not in the mount table. |
17703 | |
17704 | [EBUSY] A process is holding a reference to a file located on the |
17705 | filesystem. |
17706 | |
17707 | [EIO] An I/O error occurred while writing cached filesystem |
17708 | information. |
17709 | |
17710 | [EFAULT] _\bd_\bi_\br points outside the process's allocated address space. |
17711 | |
17712 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17713 | statfs(2), mfs(8), mount(8), umount(8) |
17714 | |
17715 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17716 | The m\bmo\bou\bun\bnt\bt() and u\bun\bnm\bmo\bou\bun\bnt\bt() system calls first appeared in Version 1 AT&T |
17717 | UNIX. The _\bf_\bl_\ba_\bg_\bs argument is supported by m\bmo\bou\bun\bnt\bt() since Version 5 AT&T |
17718 | UNIX and by u\bun\bnm\bmo\bou\bun\bnt\bt() since 4.3BSD-Reno. The current calling convention |
17719 | involving _\bt_\by_\bp_\be and _\bd_\ba_\bt_\ba arguments was introduced by 4.3BSD-Reno as well. |
17720 | |
17721 | B\bBU\bUG\bGS\bS |
17722 | Some of the error codes need translation to more obvious messages. |
17723 | |
17724 | N\bNA\bAM\bME\bE |
17725 | m\bmp\bpr\bro\bot\bte\bec\bct\bt - control the protection of pages |
17726 | |
17727 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17728 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
17729 | |
17730 | _\bi_\bn_\bt |
17731 | m\bmp\bpr\bro\bot\bte\bec\bct\bt(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bp_\br_\bo_\bt); |
17732 | |
17733 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17734 | The m\bmp\bpr\bro\bot\bte\bec\bct\bt() system call sets the access protections for the pages that |
17735 | contain the address range _\ba_\bd_\bd_\br through _\ba_\bd_\bd_\br + _\bl_\be_\bn - 1 (inclusive). If |
17736 | _\bl_\be_\bn is 0, no action is taken on the page that contains _\ba_\bd_\bd_\br. |
17737 | |
17738 | The protections (region accessibility) are specified in the _\bp_\br_\bo_\bt |
17739 | argument. It should either be PROT_NONE (no permissions) or the bitwise |
17740 | OR of one or more of the following values: |
17741 | |
17742 | PROT_EXEC Pages may be executed. |
17743 | PROT_READ Pages may be read. |
17744 | PROT_WRITE Pages may be written. |
17745 | |
17746 | Not all implementations will guarantee protection on a page basis; the |
17747 | granularity of protection changes may be as large as an entire region. |
17748 | Nor will all implementations guarantee to give exactly the requested |
17749 | permissions; more permissions may be granted than requested by _\bp_\br_\bo_\bt. |
17750 | However, if PROT_WRITE was not specified then the page will not be |
17751 | writable. |
17752 | |
17753 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17754 | Upon successful completion, the value 0 is returned; otherwise the |
17755 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
17756 | error. |
17757 | |
17758 | E\bER\bRR\bRO\bOR\bRS\bS |
17759 | m\bmp\bpr\bro\bot\bte\bec\bct\bt() will fail if: |
17760 | |
17761 | [EACCES] The process does not have sufficient access to the |
17762 | underlying memory object to provide the requested |
17763 | protection. |
17764 | |
17765 | [ENOMEM] The process has locked future pages with |
17766 | m\bml\blo\boc\bck\bka\bal\bll\bl(_\bM_\bC_\bL_\b__\bF_\bU_\bT_\bU_\bR_\bE), a page being protected is not |
17767 | currently accessible, and making it accessible and |
17768 | locked would exceed process or system limits. |
17769 | |
17770 | [EINVAL] The _\bp_\br_\bo_\bt argument is invalid or the specified address |
17771 | range would wrap around. |
17772 | |
17773 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17774 | madvise(2), mincore(2), msync(2), munmap(2) |
17775 | |
17776 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
17777 | The m\bmp\bpr\bro\bot\bte\bec\bct\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
17778 | |
17779 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17780 | The m\bmp\bpr\bro\bot\bte\bec\bct\bt() function first appeared in 4.4BSD. |
17781 | |
17782 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
17783 | The OpenBSD implementation of m\bmp\bpr\bro\bot\bte\bec\bct\bt() does not require _\ba_\bd_\bd_\br to be |
17784 | page-aligned, although other implementations may. |
17785 | |
17786 | N\bNA\bAM\bME\bE |
17787 | m\bmq\bqu\bue\ber\bry\by - provide mapping hints to applications |
17788 | |
17789 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17790 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
17791 | |
17792 | _\bv_\bo_\bi_\bd _\b* |
17793 | m\bmq\bqu\bue\ber\bry\by(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bp_\br_\bo_\bt, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bi_\bn_\bt _\bf_\bd, |
17794 | _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
17795 | |
17796 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17797 | The m\bmq\bqu\bue\ber\bry\by() system call checks the existing memory mappings of a process |
17798 | and returns hints to the caller about where to put a memory mapping. |
17799 | This hint can be later used when performing memory mappings with the |
17800 | mmap(2) system call with MAP_FIXED in the flags. The _\ba_\bd_\bd_\br argument |
17801 | should be a memory location that which the caller specifies the preferred |
17802 | address. The _\bs_\bi_\bz_\be argument specifies the requested size of the memory |
17803 | area the caller is looking for. The _\bf_\bd and _\bo_\bf_\bf arguments specify the |
17804 | file that will be mapped and the offset in it, this is the same as the |
17805 | corresponding arguments to mmap(2). |
17806 | |
17807 | The behavior of the function depends on the _\bf_\bl_\ba_\bg_\bs argument. If set to |
17808 | MAP_FIXED the pointer _\ba_\bd_\bd_\br is used as a fixed hint and m\bmq\bqu\bue\ber\bry\by() will |
17809 | return MAP_FAILED and set _\be_\br_\br_\bn_\bo to ENOMEM if there is not _\bs_\bi_\bz_\be bytes free |
17810 | after that address. Otherwise it will return the hint addr. If no flags |
17811 | are set m\bmq\bqu\bue\ber\bry\by() will use _\ba_\bd_\bd_\br as a starting point in memory and will |
17812 | search forward to find a memory area with _\bs_\bi_\bz_\be bytes free and that will |
17813 | be suitable for creating a mapping for the file and offset specified in |
17814 | the _\bf_\bd and _\bo_\bf_\bf arguments. When no such area can be found m\bmq\bqu\bue\ber\bry\by() will |
17815 | return and set _\be_\br_\br_\bn_\bo to indicate the error. |
17816 | |
17817 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17818 | When a memory range satisfying the request is found m\bmq\bqu\bue\ber\bry\by() returns the |
17819 | available address. Otherwise, MAP_FAILED is returned and _\be_\br_\br_\bn_\bo is set to |
17820 | indicate the error. |
17821 | |
17822 | E\bER\bRR\bRO\bOR\bRS\bS |
17823 | m\bmq\bqu\bue\ber\bry\by() will fail if: |
17824 | |
17825 | [EINVAL] MAP_FIXED was specified and the requested memory area |
17826 | is unavailable. |
17827 | |
17828 | [ENOMEM] There was not enough memory left after the hint |
17829 | specified. |
17830 | |
17831 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
17832 | |
17833 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17834 | mmap(2) |
17835 | |
17836 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
17837 | The m\bmq\bqu\bue\ber\bry\by() function should not be used in portable applications. |
17838 | |
17839 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17840 | The m\bmq\bqu\bue\ber\bry\by() function first appeared in OpenBSD 3.4. |
17841 | |
17842 | N\bNA\bAM\bME\bE |
17843 | m\bms\bsg\bgc\bct\btl\bl - message control operations |
17844 | |
17845 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17846 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bms\bsg\bg.\b.h\bh>\b> |
17847 | |
17848 | _\bi_\bn_\bt |
17849 | m\bms\bsg\bgc\bct\btl\bl(_\bi_\bn_\bt _\bm_\bs_\bq_\bi_\bd, _\bi_\bn_\bt _\bc_\bm_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bq_\bi_\bd_\b__\bd_\bs _\b*_\bb_\bu_\bf); |
17850 | |
17851 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17852 | The m\bms\bsg\bgc\bct\btl\bl() system call performs some control operations on the message |
17853 | queue specified by _\bm_\bs_\bq_\bi_\bd. |
17854 | |
17855 | Each message queue has a data structure associated with it, parts of |
17856 | which may be altered by m\bms\bsg\bgc\bct\btl\bl() and parts of which determine the actions |
17857 | of m\bms\bsg\bgc\bct\btl\bl(). The data structure is defined in <_\bs_\by_\bs_\b/_\bm_\bs_\bg_\b._\bh> and contains |
17858 | (amongst others) the following members: |
17859 | |
17860 | struct msqid_ds { |
17861 | struct ipc_perm msg_perm; /* msg queue permission bits */ |
17862 | u_long msg_cbytes; /* # of bytes in use on the queue */ |
17863 | u_long msg_qnum; /* # of msgs in the queue */ |
17864 | u_long msg_qbytes; /* max # of bytes on the queue */ |
17865 | pid_t msg_lspid; /* pid of last msgsnd() */ |
17866 | pid_t msg_lrpid; /* pid of last msgrcv() */ |
17867 | time_t msg_stime; /* time of last msgsnd() */ |
17868 | time_t msg_rtime; /* time of last msgrcv() */ |
17869 | time_t msg_ctime; /* time of last msgctl() */ |
17870 | }; |
17871 | |
17872 | The _\bi_\bp_\bc_\b__\bp_\be_\br_\bm structure used inside the _\bm_\bs_\bq_\bi_\bd_\b__\bd_\bs structure is defined in |
17873 | <_\bs_\by_\bs_\b/_\bi_\bp_\bc_\b._\bh> and looks like this: |
17874 | |
17875 | struct ipc_perm { |
17876 | uid_t cuid; /* creator user id */ |
17877 | gid_t cgid; /* creator group id */ |
17878 | uid_t uid; /* user id */ |
17879 | gid_t gid; /* group id */ |
17880 | mode_t mode; /* permission (9 bits, see chmod(2)) */ |
17881 | u_short seq; /* sequence # (to generate unique id) */ |
17882 | key_t key; /* user specified msg/sem/shm key */ |
17883 | }; |
17884 | |
17885 | The operation to be performed by m\bms\bsg\bgc\bct\btl\bl() is specified in _\bc_\bm_\bd and is one |
17886 | of: |
17887 | |
17888 | IPC_STAT Gather information about the message queue and place it in the |
17889 | structure pointed to by _\bb_\bu_\bf. |
17890 | |
17891 | IPC_SET Set the value of the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd, _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd, _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be |
17892 | and _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs fields in the structure associated with _\bm_\bs_\bq_\bi_\bd. |
17893 | The values are taken from the corresponding fields in the |
17894 | structure pointed to by _\bb_\bu_\bf. This operation can only be |
17895 | executed by the superuser, or a process that has an effective |
17896 | user ID equal to either _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd in the |
17897 | data structure associated with the message queue. The value |
17898 | of _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs can only be increased by the superuser. Values |
17899 | for _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs that exceed the system limit (MSGMNB from |
17900 | <_\bs_\by_\bs_\b/_\bm_\bs_\bg_\b._\bh>) are silently truncated to that limit. |
17901 | |
17902 | IPC_RMID Remove the message queue specified by _\bm_\bs_\bq_\bi_\bd and destroy the |
17903 | data associated with it. Only the superuser or a process with |
17904 | an effective UID equal to the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd |
17905 | values in the data structure associated with the queue can do |
17906 | this. |
17907 | |
17908 | The permission to read from or write to a message queue (see msgsnd(2) |
17909 | and msgrcv(2)) is determined by the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be field in the same way |
17910 | as is done with files (see chmod(2)), but the effective UID can match |
17911 | either the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd field or the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd field, and the |
17912 | effective GID can match either _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd or _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd. |
17913 | |
17914 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17915 | Upon successful completion, the value 0 is returned; otherwise the |
17916 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
17917 | error. |
17918 | |
17919 | E\bER\bRR\bRO\bOR\bRS\bS |
17920 | m\bms\bsg\bgc\bct\btl\bl() will fail if: |
17921 | |
17922 | [EPERM] _\bc_\bm_\bd is equal to IPC_SET or IPC_RMID and the caller is |
17923 | not the superuser, nor does the effective UID match |
17924 | either the _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd or _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd fields of the |
17925 | data structure associated with the message queue. |
17926 | |
17927 | An attempt is made to increase the value of _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs |
17928 | through IPC_SET but the caller is not the superuser. |
17929 | |
17930 | [EACCES] The command is IPC_STAT and the caller has no read |
17931 | permission for this message queue. |
17932 | |
17933 | [EINVAL] _\bm_\bs_\bq_\bi_\bd is not a valid message queue identifier. |
17934 | |
17935 | _\bc_\bm_\bd is not a valid command. |
17936 | |
17937 | [EFAULT] _\bb_\bu_\bf specifies an invalid address. |
17938 | |
17939 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
17940 | msgget(2), msgrcv(2), msgsnd(2) |
17941 | |
17942 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
17943 | Message queues appeared in AT&T System V Release 1 UNIX. |
17944 | |
17945 | N\bNA\bAM\bME\bE |
17946 | m\bms\bsg\bgg\bge\bet\bt - get message queue |
17947 | |
17948 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
17949 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bms\bsg\bg.\b.h\bh>\b> |
17950 | |
17951 | _\bi_\bn_\bt |
17952 | m\bms\bsg\bgg\bge\bet\bt(_\bk_\be_\by_\b__\bt _\bk_\be_\by, _\bi_\bn_\bt _\bm_\bs_\bg_\bf_\bl_\bg); |
17953 | |
17954 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
17955 | m\bms\bsg\bgg\bge\bet\bt() returns the message queue identifier associated with _\bk_\be_\by. A |
17956 | message queue identifier is a unique integer greater than zero. |
17957 | |
17958 | A message queue is created if either _\bk_\be_\by is equal to IPC_PRIVATE, or _\bk_\be_\by |
17959 | does not have a message queue identifier associated with it, and the |
17960 | IPC_CREAT bit is set in _\bm_\bs_\bg_\bf_\bl_\bg. |
17961 | |
17962 | If a new message queue is created, the data structure associated with it |
17963 | (the _\bm_\bs_\bq_\bi_\bd_\b__\bd_\bs structure, see msgctl(2)) is initialized as follows: |
17964 | |
17965 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd and _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd are set to the effective UID of the |
17966 | calling process. |
17967 | |
17968 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd are set to the effective GID of the |
17969 | calling process. |
17970 | |
17971 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be is set to the lower 9 bits of _\bm_\bs_\bg_\bf_\bl_\bg. |
17972 | |
17973 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bc_\bb_\by_\bt_\be_\bs, _\bm_\bs_\bg_\b__\bq_\bn_\bu_\bm, _\bm_\bs_\bg_\b__\bl_\bs_\bp_\bi_\bd, _\bm_\bs_\bg_\b__\bl_\br_\bp_\bi_\bd, _\bm_\bs_\bg_\b__\br_\bt_\bi_\bm_\be, and _\bm_\bs_\bg_\b__\bs_\bt_\bi_\bm_\be |
17974 | are set to 0. |
17975 | |
17976 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs is set to the system wide maximum value for the number of |
17977 | bytes in a queue (MSGMNB). |
17978 | |
17979 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bc_\bt_\bi_\bm_\be is set to the current time. |
17980 | |
17981 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
17982 | Upon successful completion a positive message queue identifier is |
17983 | returned. Otherwise, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
17984 | to indicate the error. |
17985 | |
17986 | E\bER\bRR\bRO\bOR\bRS\bS |
17987 | [EACCES] A message queue is already associated with _\bk_\be_\by and the |
17988 | caller has no permission to access it. |
17989 | |
17990 | [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _\bm_\bs_\bg_\bf_\bl_\bg, and a |
17991 | message queue is already associated with _\bk_\be_\by. |
17992 | |
17993 | [ENOSPC] A new message queue could not be created because the |
17994 | system limit for the number of message queues has been |
17995 | reached. |
17996 | |
17997 | [ENOENT] IPC_CREAT was not set in _\bm_\bs_\bg_\bf_\bl_\bg and no message queue |
17998 | associated with _\bk_\be_\by was found. |
17999 | |
18000 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18001 | msgctl(2), msgrcv(2), msgsnd(2), ftok(3) |
18002 | |
18003 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18004 | Message queues appeared in AT&T System V Release 1 UNIX. |
18005 | |
18006 | N\bNA\bAM\bME\bE |
18007 | m\bms\bsg\bgr\brc\bcv\bv - receive a message from a message queue |
18008 | |
18009 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18010 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bms\bsg\bg.\b.h\bh>\b> |
18011 | |
18012 | _\bi_\bn_\bt |
18013 | m\bms\bsg\bgr\brc\bcv\bv(_\bi_\bn_\bt _\bm_\bs_\bq_\bi_\bd, _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg_\bp, _\bs_\bi_\bz_\be_\b__\bt _\bm_\bs_\bg_\bs_\bz, _\bl_\bo_\bn_\bg _\bm_\bs_\bg_\bt_\by_\bp, _\bi_\bn_\bt _\bm_\bs_\bg_\bf_\bl_\bg); |
18014 | |
18015 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18016 | The m\bms\bsg\bgr\brc\bcv\bv() function receives a message from the message queue specified |
18017 | in _\bm_\bs_\bq_\bi_\bd, and places it into the structure pointed to by _\bm_\bs_\bg_\bp. This |
18018 | structure should consist of the following members: |
18019 | |
18020 | long mtype; /* message type */ |
18021 | char mtext[1]; /* body of message */ |
18022 | |
18023 | _\bm_\bt_\by_\bp_\be is an integer greater than 0 that can be used for selecting |
18024 | messages, _\bm_\bt_\be_\bx_\bt is an array of bytes, with a size up to that of the |
18025 | system limit (MSGMAX). |
18026 | |
18027 | The value of _\bm_\bs_\bg_\bt_\by_\bp has one of the following meanings: |
18028 | |
18029 | +\b+\bo\bo _\bm_\bs_\bg_\bt_\by_\bp is greater than 0. The first message of type _\bm_\bs_\bg_\bt_\by_\bp will be |
18030 | received. |
18031 | |
18032 | +\b+\bo\bo _\bm_\bs_\bg_\bt_\by_\bp is equal to 0. The first message on the queue will be |
18033 | received. |
18034 | |
18035 | +\b+\bo\bo _\bm_\bs_\bg_\bt_\by_\bp is less than 0. The first message of the lowest message type |
18036 | that is less than or equal to the absolute value of _\bm_\bs_\bg_\bt_\by_\bp will be |
18037 | received. |
18038 | |
18039 | _\bm_\bs_\bg_\bs_\bz specifies the maximum length of the requested message. If the |
18040 | received message has a length greater than _\bm_\bs_\bg_\bs_\bz it will be silently |
18041 | truncated if the MSG_NOERROR flag is set in _\bm_\bs_\bg_\bf_\bl_\bg, otherwise an error |
18042 | will be returned. |
18043 | |
18044 | If no matching message is present on the message queue specified by |
18045 | _\bm_\bs_\bq_\bi_\bd, the behavior of m\bms\bsg\bgr\brc\bcv\bv() depends on whether the IPC_NOWAIT flag is |
18046 | set in _\bm_\bs_\bg_\bf_\bl_\bg or not. If IPC_NOWAIT is set, m\bms\bsg\bgr\brc\bcv\bv() will immediately |
18047 | return a value of -1, and set _\be_\br_\br_\bn_\bo to EAGAIN. If IPC_NOWAIT is not set, |
18048 | the calling process will be blocked until: |
18049 | |
18050 | +\b+\bo\bo A message of the requested type becomes available on the message |
18051 | queue. |
18052 | |
18053 | +\b+\bo\bo The message queue is removed, in which case -1 will be returned, and |
18054 | _\be_\br_\br_\bn_\bo set to EINVAL. |
18055 | |
18056 | +\b+\bo\bo A signal is received and caught. -1 is returned, and _\be_\br_\br_\bn_\bo set to |
18057 | EINTR. |
18058 | |
18059 | If a message is successfully received, the data structure associated with |
18060 | _\bm_\bs_\bq_\bi_\bd is updated as follows: |
18061 | |
18062 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bc_\bb_\by_\bt_\be_\bs is decremented by the size of the message. |
18063 | |
18064 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bl_\br_\bp_\bi_\bd is set to the pid of the caller. |
18065 | |
18066 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bl_\br_\bt_\bi_\bm_\be is set to the current time. |
18067 | |
18068 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bq_\bn_\bu_\bm is decremented by 1. |
18069 | |
18070 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18071 | Upon successful completion, m\bms\bsg\bgr\brc\bcv\bv() returns the number of bytes received |
18072 | into the _\bm_\bt_\be_\bx_\bt field of the structure pointed to by _\bm_\bs_\bg_\bp. Otherwise, -1 |
18073 | is returned, and _\be_\br_\br_\bn_\bo set to indicate the error. |
18074 | |
18075 | E\bER\bRR\bRO\bOR\bRS\bS |
18076 | m\bms\bsg\bgr\brc\bcv\bv() will fail if: |
18077 | |
18078 | [EINVAL] _\bm_\bs_\bq_\bi_\bd is not a valid message queue identifier. |
18079 | |
18080 | _\bm_\bs_\bg_\bs_\bz is less than 0. |
18081 | |
18082 | [E2BIG] A matching message was received, but its size was |
18083 | greater than _\bm_\bs_\bg_\bs_\bz and the MSG_NOERROR flag was not |
18084 | set in _\bm_\bs_\bg_\bf_\bl_\bg. |
18085 | |
18086 | [EACCES] The calling process does not have read access to the |
18087 | message queue. |
18088 | |
18089 | [EFAULT] _\bm_\bs_\bg_\bp points to an invalid address. |
18090 | |
18091 | [EINTR] The system call was interrupted by the delivery of a |
18092 | signal. |
18093 | |
18094 | [ENOMSG] There is no message of the requested type available on |
18095 | the message queue, and IPC_NOWAIT is set in _\bm_\bs_\bg_\bf_\bl_\bg. |
18096 | |
18097 | [EIDRM] The message queue was removed while m\bms\bsg\bgr\brc\bcv\bv() was |
18098 | waiting for a message of the requested type to become |
18099 | available on it. |
18100 | |
18101 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18102 | msgctl(2), msgget(2), msgsnd(2) |
18103 | |
18104 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18105 | Message queues appeared in AT&T System V Release 1 UNIX. |
18106 | |
18107 | N\bNA\bAM\bME\bE |
18108 | m\bms\bsg\bgs\bsn\bnd\bd - send a message to a message queue |
18109 | |
18110 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18111 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bms\bsg\bg.\b.h\bh>\b> |
18112 | |
18113 | _\bi_\bn_\bt |
18114 | m\bms\bsg\bgs\bsn\bnd\bd(_\bi_\bn_\bt _\bm_\bs_\bq_\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg_\bp, _\bs_\bi_\bz_\be_\b__\bt _\bm_\bs_\bg_\bs_\bz, _\bi_\bn_\bt _\bm_\bs_\bg_\bf_\bl_\bg); |
18115 | |
18116 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18117 | The m\bms\bsg\bgs\bsn\bnd\bd() function sends a message to the message queue specified by |
18118 | _\bm_\bs_\bq_\bi_\bd. _\bm_\bs_\bg_\bp points to a structure containing the message. This |
18119 | structure should consist of the following members: |
18120 | |
18121 | long mtype; /* message type */ |
18122 | char mtext[1]; /* body of message */ |
18123 | |
18124 | _\bm_\bt_\by_\bp_\be is an integer greater than 0 that can be used for selecting |
18125 | messages (see msgrcv(2)); _\bm_\bt_\be_\bx_\bt is an array of _\bm_\bs_\bg_\bs_\bz bytes, with a size |
18126 | between 0 and that of the system limit (MSGMAX). |
18127 | |
18128 | If the number of bytes already on the message queue plus _\bm_\bs_\bg_\bs_\bz is bigger |
18129 | than the maximum number of bytes on the message queue (_\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs, |
18130 | see msgctl(2)), or the number of messages on all queues system-wide is |
18131 | already equal to the system limit, _\bm_\bs_\bg_\bf_\bl_\bg determines the action of |
18132 | m\bms\bsg\bgs\bsn\bnd\bd(). If _\bm_\bs_\bg_\bf_\bl_\bg has IPC_NOWAIT mask set in it, the call will return |
18133 | immediately. If _\bm_\bs_\bg_\bf_\bl_\bg does not have IPC_NOWAIT set in it, the call will |
18134 | block until: |
18135 | |
18136 | +\b+\bo\bo The condition which caused the call to block does no longer exist. |
18137 | The message will be sent. |
18138 | |
18139 | +\b+\bo\bo The message queue is removed, in which case -1 will be returned, and |
18140 | _\be_\br_\br_\bn_\bo is set to EINVAL. |
18141 | |
18142 | +\b+\bo\bo The caller catches a signal. The call returns with _\be_\br_\br_\bn_\bo set to |
18143 | EINTR. |
18144 | |
18145 | After a successful call, the data structure associated with the message |
18146 | queue is updated in the following way: |
18147 | |
18148 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bc_\bb_\by_\bt_\be_\bs is incremented by the size of the message. |
18149 | |
18150 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bq_\bn_\bu_\bm is incremented by 1. |
18151 | |
18152 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bl_\bs_\bp_\bi_\bd is set to the pid of the calling process. |
18153 | |
18154 | +\b+\bo\bo _\bm_\bs_\bg_\b__\bs_\bt_\bi_\bm_\be is set to the current time. |
18155 | |
18156 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18157 | Upon successful completion, the value 0 is returned; otherwise the |
18158 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
18159 | error. |
18160 | |
18161 | E\bER\bRR\bRO\bOR\bRS\bS |
18162 | m\bms\bsg\bgs\bsn\bnd\bd() will fail if: |
18163 | |
18164 | [EINVAL] _\bm_\bs_\bq_\bi_\bd is not a valid message queue identifier. |
18165 | |
18166 | _\bm_\bs_\bg_\bs_\bz is greater than _\bm_\bs_\bg_\b__\bq_\bb_\by_\bt_\be_\bs. |
18167 | |
18168 | [EACCES] The calling process does not have write access to the |
18169 | message queue. |
18170 | |
18171 | [EAGAIN] There was no space for this message either on the |
18172 | queue, or in the whole system, and IPC_NOWAIT was set |
18173 | in _\bm_\bs_\bg_\bf_\bl_\bg. |
18174 | |
18175 | [EFAULT] _\bm_\bs_\bg_\bp points to an invalid address. |
18176 | |
18177 | [EINTR] The system call was interrupted by the delivery of a |
18178 | signal. |
18179 | |
18180 | [EIDRM] The message queue was removed while m\bms\bsg\bgs\bsn\bnd\bd() was |
18181 | waiting for a resource to become available in order to |
18182 | deliver the message. |
18183 | |
18184 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18185 | msgctl(2), msgget(2), msgrcv(2) |
18186 | |
18187 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18188 | Message queues appeared in AT&T System V Release 1 UNIX. |
18189 | |
18190 | N\bNA\bAM\bME\bE |
18191 | m\bms\bsy\byn\bnc\bc - synchronize a mapped region |
18192 | |
18193 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18194 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
18195 | |
18196 | _\bi_\bn_\bt |
18197 | m\bms\bsy\byn\bnc\bc(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
18198 | |
18199 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18200 | The m\bms\bsy\byn\bnc\bc() system call writes all pages with shared modifications in the |
18201 | specified region of the process's address space back to permanent |
18202 | storage, and, if requested, invalidates cached data mapped in the region. |
18203 | If _\bl_\be_\bn is 0, all modified pages within the region containing _\ba_\bd_\bd_\br will be |
18204 | flushed; if _\bl_\be_\bn is non-zero, only modified pages containing _\ba_\bd_\bd_\br and |
18205 | _\bl_\be_\bn_\b-_\b1 succeeding locations will be flushed. Any required synchronization |
18206 | of memory caches will also take place at this time. Filesystem |
18207 | operations on a file that is mapped for shared modifications are |
18208 | unpredictable except after an m\bms\bsy\byn\bnc\bc(). |
18209 | |
18210 | The _\bf_\bl_\ba_\bg_\bs argument is the bitwise OR of zero or more of the following |
18211 | values: |
18212 | |
18213 | MS_ASYNC Perform asynchronous writes. |
18214 | MS_SYNC Perform synchronous writes. |
18215 | MS_INVALIDATE Invalidate cached data after writing. |
18216 | |
18217 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18218 | Upon successful completion, the value 0 is returned; otherwise the |
18219 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
18220 | error. |
18221 | |
18222 | E\bER\bRR\bRO\bOR\bRS\bS |
18223 | The following errors may be reported: |
18224 | |
18225 | [EBUSY] The MS_INVALIDATE flag was specified and a portion of |
18226 | the specified region was locked with mlock(2). |
18227 | |
18228 | [EINVAL] The specified _\bf_\bl_\ba_\bg_\bs argument was invalid. |
18229 | |
18230 | [EINVAL] The _\ba_\bd_\bd_\br parameter was not page aligned or _\ba_\bd_\bd_\br and |
18231 | _\bs_\bi_\bz_\be specify a region that would extend beyond the end |
18232 | of the address space. |
18233 | |
18234 | [ENOMEM] Addresses in the specified region are outside the |
18235 | range allowed for the address space of the process, or |
18236 | specify one or more pages which are unmapped. |
18237 | |
18238 | [EIO] An I/O error occurred while writing. |
18239 | |
18240 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18241 | madvise(2), mincore(2), minherit(2), mprotect(2), munmap(2) |
18242 | |
18243 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18244 | The m\bms\bsy\byn\bnc\bc() function first appeared in 4.4BSD. It was modified to |
18245 | conform to IEEE Std 1003.1b-1993 (``POSIX.1b'') |
18246 | |
18247 | B\bBU\bUG\bGS\bS |
18248 | Writes are currently done synchronously even if the MS_ASYNC flag is |
18249 | specified. |
18250 | |
18251 | N\bNA\bAM\bME\bE |
18252 | m\bml\blo\boc\bck\bk, m\bmu\bun\bnl\blo\boc\bck\bk - lock (unlock) physical pages in memory |
18253 | |
18254 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18255 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
18256 | |
18257 | _\bi_\bn_\bt |
18258 | m\bml\blo\boc\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
18259 | |
18260 | _\bi_\bn_\bt |
18261 | m\bmu\bun\bnl\blo\boc\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
18262 | |
18263 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18264 | The m\bml\blo\boc\bck\bk() system call locks into memory the physical pages associated |
18265 | with the virtual address range starting at _\ba_\bd_\bd_\br for _\bl_\be_\bn bytes. The |
18266 | m\bmu\bun\bnl\blo\boc\bck\bk() call unlocks pages previously locked by one or more m\bml\blo\boc\bck\bk() |
18267 | calls. For both, the _\ba_\bd_\bd_\br parameter should be aligned to a multiple of |
18268 | the page size. If the _\bl_\be_\bn parameter is not a multiple of the page size, |
18269 | it will be rounded up to be so. The entire range must be allocated. |
18270 | |
18271 | After an m\bml\blo\boc\bck\bk() call, the indicated pages will cause neither a non- |
18272 | resident page nor address-translation fault until they are unlocked. |
18273 | They may still cause protection-violation faults or TLB-miss faults on |
18274 | architectures with software-managed TLBs. The physical pages remain in |
18275 | memory until all locked mappings for the pages are removed. Multiple |
18276 | processes may have the same physical pages locked via their own virtual |
18277 | address mappings. A single process may likewise have pages multiply |
18278 | locked via different virtual mappings of the same pages or via nested |
18279 | m\bml\blo\boc\bck\bk() calls on the same address range. Unlocking is performed |
18280 | explicitly by m\bmu\bun\bnl\blo\boc\bck\bk() or implicitly by a call to munmap(2) which |
18281 | deallocates the unmapped address range. Locked mappings are not |
18282 | inherited by the child process after a fork(2). |
18283 | |
18284 | Since physical memory is a potentially scarce resource, processes are |
18285 | limited in how much they can lock down. A single process can m\bml\blo\boc\bck\bk() the |
18286 | minimum of a system-wide ``wired pages'' limit and the per-process |
18287 | RLIMIT_MEMLOCK resource limit. |
18288 | |
18289 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18290 | The m\bml\blo\boc\bck\bk() and m\bmu\bun\bnl\blo\boc\bck\bk() functions return the value 0 if successful; |
18291 | otherwise the value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
18292 | to indicate the error. |
18293 | |
18294 | E\bER\bRR\bRO\bOR\bRS\bS |
18295 | m\bml\blo\boc\bck\bk() will fail if: |
18296 | |
18297 | [EINVAL] The address given is not page aligned or the length is |
18298 | negative. |
18299 | |
18300 | [EAGAIN] Locking the indicated range would exceed either the |
18301 | system or per-process limit for locked memory. |
18302 | |
18303 | [ENOMEM] Some portion of the indicated address range is not |
18304 | allocated. There was an error faulting/mapping a |
18305 | page. |
18306 | |
18307 | m\bmu\bun\bnl\blo\boc\bck\bk() will fail if: |
18308 | |
18309 | [EINVAL] The address given is not page aligned or _\ba_\bd_\bd_\br and _\bs_\bi_\bz_\be |
18310 | specify a region that would extend beyond the end of |
18311 | the address space. |
18312 | |
18313 | [ENOMEM] Some portion of the indicated address range is not |
18314 | allocated. Some portion of the indicated address |
18315 | range is not locked. |
18316 | |
18317 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18318 | fork(2), mincore(2), minherit(2), mlockall(2), mmap(2), munmap(2), |
18319 | setrlimit(2), getpagesize(3) |
18320 | |
18321 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18322 | The m\bml\blo\boc\bck\bk() and m\bmu\bun\bnl\blo\boc\bck\bk() functions first appeared in 4.4BSD. |
18323 | |
18324 | B\bBU\bUG\bGS\bS |
18325 | Unlike Sun's implementation, multiple m\bml\blo\boc\bck\bk() calls on the same address |
18326 | range require the corresponding number of m\bmu\bun\bnl\blo\boc\bck\bk() calls to actually |
18327 | unlock the pages, i.e., m\bml\blo\boc\bck\bk() nests. This should be considered a |
18328 | consequence of the implementation and not a feature. |
18329 | |
18330 | The per-process resource limit is a limit on the amount of virtual memory |
18331 | locked, while the system-wide limit is for the number of locked physical |
18332 | pages. Hence a process with two distinct locked mappings of the same |
18333 | physical page counts as 2 pages against the per-process limit and as only |
18334 | a single page in the system limit. |
18335 | |
18336 | N\bNA\bAM\bME\bE |
18337 | m\bml\blo\boc\bck\bka\bal\bll\bl, m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl - lock (unlock) the address space of a process |
18338 | |
18339 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18340 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
18341 | |
18342 | _\bi_\bn_\bt |
18343 | m\bml\blo\boc\bck\bka\bal\bll\bl(_\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
18344 | |
18345 | _\bi_\bn_\bt |
18346 | m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl(_\bv_\bo_\bi_\bd); |
18347 | |
18348 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18349 | The m\bml\blo\boc\bck\bka\bal\bll\bl() system call locks into memory the physical pages |
18350 | associated with the address space of a process until the address space is |
18351 | unlocked, the process exits, or execs another program image. |
18352 | |
18353 | The following flags affect the behavior of m\bml\blo\boc\bck\bka\bal\bll\bl(): |
18354 | |
18355 | MCL_CURRENT Lock all pages currently mapped into the process's address |
18356 | space. |
18357 | |
18358 | MCL_FUTURE Lock all pages mapped into the process's address space in |
18359 | the future, at the time the mapping is established. Note |
18360 | that this may cause future mappings to fail if those |
18361 | mappings cause resource limits to be exceeded. |
18362 | |
18363 | Since physical memory is a potentially scarce resource, processes are |
18364 | limited in how much they can lock down. A single process can lock the |
18365 | minimum of a system-wide ``wired pages'' limit and the per-process |
18366 | RLIMIT_MEMLOCK resource limit. |
18367 | |
18368 | The m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() call unlocks any locked memory regions in the process |
18369 | address space. Any regions mapped after an m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() call will not be |
18370 | locked. |
18371 | |
18372 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18373 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions return the value 0 if |
18374 | successful; otherwise the value -1 is returned and the global variable |
18375 | _\be_\br_\br_\bn_\bo is set to indicate the error. |
18376 | |
18377 | E\bER\bRR\bRO\bOR\bRS\bS |
18378 | m\bml\blo\boc\bck\bka\bal\bll\bl() will fail if: |
18379 | |
18380 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs argument is zero or includes unimplemented |
18381 | flags. |
18382 | |
18383 | [ENOMEM] Locking all of the pages currently mapped would exceed |
18384 | either the system or per-process limit for locked |
18385 | memory. |
18386 | |
18387 | [EAGAIN] Some or all of the memory mapped into the process's |
18388 | address space could not be locked when the call was |
18389 | made. |
18390 | |
18391 | [EPERM] The calling process does not have the appropriate |
18392 | privileges to perform the requested operation. |
18393 | |
18394 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18395 | mincore(2), mlock(2), mmap(2), munmap(2), setrlimit(2) |
18396 | |
18397 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
18398 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions conform to IEEE Std 1003.1-2008 |
18399 | (``POSIX.1''). |
18400 | |
18401 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18402 | The m\bml\blo\boc\bck\bka\bal\bll\bl() and m\bmu\bun\bnl\blo\boc\bck\bka\bal\bll\bl() functions first appeared in OpenBSD 2.9. |
18403 | |
18404 | B\bBU\bUG\bGS\bS |
18405 | The per-process resource limit is a limit on the amount of virtual memory |
18406 | locked, while the system-wide limit is for the number of locked physical |
18407 | pages. Hence a process with two distinct locked mappings of the same |
18408 | physical page counts as 2 pages against the per-process limit and only as |
18409 | a single page in the system limit. |
18410 | |
18411 | N\bNA\bAM\bME\bE |
18412 | m\bmu\bun\bnm\bma\bap\bp - remove a mapping |
18413 | |
18414 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18415 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
18416 | |
18417 | _\bi_\bn_\bt |
18418 | m\bmu\bun\bnm\bma\bap\bp(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
18419 | |
18420 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18421 | The m\bmu\bun\bnm\bma\bap\bp() system call deletes the mappings for the specified address |
18422 | range, and causes further references to addresses within the range to |
18423 | generate invalid memory references. |
18424 | |
18425 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18426 | Upon successful completion, the value 0 is returned; otherwise the |
18427 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
18428 | error. |
18429 | |
18430 | E\bER\bRR\bRO\bOR\bRS\bS |
18431 | m\bmu\bun\bnm\bma\bap\bp() will fail if: |
18432 | |
18433 | [EINVAL] The _\ba_\bd_\bd_\br parameter was not page aligned, _\ba_\bd_\bd_\br and _\bl_\be_\bn |
18434 | specify a region that would extend beyond the end of |
18435 | the address space, or some part of the region being |
18436 | unmapped is not part of the currently valid address |
18437 | space. |
18438 | |
18439 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18440 | madvise(2), mincore(2), mlock(2), mlockall(2), mmap(2), mprotect(2), |
18441 | msync(2), getpagesize(3) |
18442 | |
18443 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18444 | The m\bmu\bun\bnm\bma\bap\bp() system call first appeared in 4.1cBSD. |
18445 | |
18446 | N\bNA\bAM\bME\bE |
18447 | n\bna\ban\bno\bos\bsl\ble\bee\bep\bp - high resolution sleep |
18448 | |
18449 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18450 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<t\bti\bim\bme\be.\b.h\bh>\b> |
18451 | |
18452 | _\bi_\bn_\bt |
18453 | n\bna\ban\bno\bos\bsl\ble\bee\bep\bp(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\br_\be_\bm_\ba_\bi_\bn_\bd_\be_\br); |
18454 | |
18455 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18456 | n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() suspends execution of the calling process for the duration |
18457 | specified by _\bt_\bi_\bm_\be_\bo_\bu_\bt. An unmasked signal will cause it to terminate the |
18458 | sleep early, regardless of the SA_RESTART value on the interrupting |
18459 | signal. |
18460 | |
18461 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18462 | If the n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() function returns because the requested duration has |
18463 | elapsed, the value returned will be zero. |
18464 | |
18465 | If the n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() function returns due to the delivery of a signal, the |
18466 | value returned will be -1, and the global variable _\be_\br_\br_\bn_\bo will be set to |
18467 | indicate the interruption. If _\br_\be_\bm_\ba_\bi_\bn_\bd_\be_\br is non-null, the timespec |
18468 | structure it references is updated to contain the unslept amount (the |
18469 | requested duration minus the duration actually slept). |
18470 | |
18471 | E\bER\bRR\bRO\bOR\bRS\bS |
18472 | If any of the following conditions occur, the n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() function shall |
18473 | return -1 and set _\be_\br_\br_\bn_\bo to the corresponding value. |
18474 | |
18475 | [EINTR] k\bkq\bqu\bue\beu\bue\be was interrupted by the delivery of a signal. |
18476 | |
18477 | [EINVAL] _\bt_\bi_\bm_\be_\bo_\bu_\bt specified a nanosecond value less than zero or |
18478 | greater than 1000 million, or a second value less than |
18479 | zero or greater than 100 million. |
18480 | |
18481 | [EFAULT] Either _\bt_\bi_\bm_\be_\bo_\bu_\bt or _\br_\be_\bm_\ba_\bi_\bn_\bd_\be_\br points to memory that is |
18482 | not a valid part of the process address space. |
18483 | |
18484 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18485 | sleep(1), sleep(3) |
18486 | |
18487 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
18488 | The n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
18489 | |
18490 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18491 | The predecessor of this system call, s\bsl\ble\bee\bep\bp(), appeared in Version 3 AT&T |
18492 | UNIX, but was removed when alarm(3) was introduced into Version 7 AT&T |
18493 | UNIX. The n\bna\ban\bno\bos\bsl\ble\bee\bep\bp() system call has been available since NetBSD 1.3 |
18494 | and was ported to OpenBSD 2.1 and FreeBSD 3.0. |
18495 | |
18496 | N\bNA\bAM\bME\bE |
18497 | n\bnf\bfs\bss\bsv\bvc\bc - NFS services |
18498 | |
18499 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18500 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
18501 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<n\bnf\bfs\bs/\b/n\bnf\bfs\bs.\b.h\bh>\b> |
18502 | |
18503 | _\bi_\bn_\bt |
18504 | n\bnf\bfs\bss\bsv\bvc\bc(_\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bv_\bo_\bi_\bd _\b*_\ba_\br_\bg_\bs_\bt_\br_\bu_\bc_\bt_\bp); |
18505 | |
18506 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18507 | The n\bnf\bfs\bss\bsv\bvc\bc() function is used by NFS daemons to pass information into the |
18508 | kernel and also to enter the kernel as a server daemon. The _\bf_\bl_\ba_\bg_\bs |
18509 | argument consists of several bits that show what action is to be taken |
18510 | once in the kernel and the _\ba_\br_\bg_\bs_\bt_\br_\bu_\bc_\bt_\bp points to one of two structures |
18511 | depending on which bits are set in flags. |
18512 | |
18513 | To enter an nfsd(8) daemon into the kernel, n\bnf\bfs\bss\bsv\bvc\bc() is called with the |
18514 | flag NFSSVC_NFSD and a pointer to a structure: |
18515 | |
18516 | struct nfsd_srvargs { |
18517 | struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ |
18518 | uid_t nsd_uid; /* Effective uid mapped to cred */ |
18519 | u_int32_t nsd_haddr; /* IP address of client */ |
18520 | struct xucred nsd_cr; /* Cred. uid maps to */ |
18521 | int nsd_authlen; /* Length of auth string (ret) */ |
18522 | u_char *nsd_authstr; /* Auth string (ret) */ |
18523 | int nsd_verflen; /* and the verifier */ |
18524 | u_char *nsd_verfstr; |
18525 | struct timeval nsd_timestamp; /* timestamp from verifier */ |
18526 | u_int32_t nsd_ttl; /* credential ttl (sec) */ |
18527 | }; |
18528 | |
18529 | To add further sockets for processing by the nfsd(8) server daemons the |
18530 | master nfsd(8) daemon calls n\bnf\bfs\bss\bsv\bvc\bc() with the flag NFSSVC_ADDSOCK and a |
18531 | pointer to a structure: |
18532 | |
18533 | struct nfsd_args { |
18534 | int sock; /* Socket to serve */ |
18535 | caddr_t name; /* Client address for connection based sockets */ |
18536 | int namelen; /* Length of name */ |
18537 | }; |
18538 | |
18539 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18540 | Normally n\bnf\bfs\bss\bsv\bvc\bc does not return unless the server is terminated by a |
18541 | signal when a value of 0 is returned. Otherwise, -1 is returned and the |
18542 | global variable _\be_\br_\br_\bn_\bo is set to specify the error. |
18543 | |
18544 | E\bER\bRR\bRO\bOR\bRS\bS |
18545 | [EPERM] The caller is not the superuser. |
18546 | |
18547 | [EINVAL] The flag argument consisted of incompatible or |
18548 | otherwise unsupported bits. |
18549 | |
18550 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18551 | mount_nfs(8), nfsd(8), sysctl(8) |
18552 | |
18553 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18554 | The n\bnf\bfs\bss\bsv\bvc\bc function first appeared in 4.4BSD. |
18555 | |
18556 | B\bBU\bUG\bGS\bS |
18557 | The n\bnf\bfs\bss\bsv\bvc\bc system call is designed specifically for the NFS support |
18558 | daemons and as such is specific to their requirements. Several fields of |
18559 | the argument structures are assumed to be valid and sometimes to be |
18560 | unchanged from a previous call, such that n\bnf\bfs\bss\bsv\bvc\bc() must be used with |
18561 | extreme care. |
18562 | |
18563 | N\bNA\bAM\bME\bE |
18564 | o\bop\bpe\ben\bn, o\bop\bpe\ben\bna\bat\bt - open or create a file for reading or writing |
18565 | |
18566 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18567 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
18568 | |
18569 | _\bi_\bn_\bt |
18570 | o\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\b._\b._\b.); |
18571 | |
18572 | _\bi_\bn_\bt |
18573 | o\bop\bpe\ben\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\b._\b._\b.); |
18574 | |
18575 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18576 | The file name specified by _\bp_\ba_\bt_\bh is opened for reading and/or writing as |
18577 | specified by the argument _\bf_\bl_\ba_\bg_\bs and the file descriptor returned to the |
18578 | calling process. The _\bf_\bl_\ba_\bg_\bs argument may indicate the file is to be |
18579 | created if it does not exist (by specifying the O_CREAT flag), in which |
18580 | case the file is created with a mode specified by an additional argument |
18581 | of type _\bm_\bo_\bd_\be_\b__\bt as described in chmod(2) and modified by the process' |
18582 | umask value (see umask(2)). |
18583 | |
18584 | The _\bf_\bl_\ba_\bg_\bs specified are a bitwise OR of the following values. Exactly |
18585 | one of the first three values (file access modes) must be specified: |
18586 | |
18587 | O_RDONLY Open for reading only. |
18588 | O_WRONLY Open for writing only. |
18589 | O_RDWR Open for reading and writing. |
18590 | |
18591 | Any combination of the following flags may additionally be used: |
18592 | |
18593 | O_NONBLOCK Do not block on open or for data to become available. |
18594 | O_APPEND Append on each write. |
18595 | O_CREAT Create file if it does not exist. An additional |
18596 | argument of type _\bm_\bo_\bd_\be_\b__\bt must be supplied to the call. |
18597 | O_TRUNC Truncate size to 0. |
18598 | O_EXCL Error if O_CREAT is set and file exists. |
18599 | O_SYNC Perform synchronous I/O operations. |
18600 | O_SHLOCK Atomically obtain a shared lock. |
18601 | O_EXLOCK Atomically obtain an exclusive lock. |
18602 | O_NOFOLLOW If last path element is a symlink, don't follow it. |
18603 | O_CLOEXEC Set FD_CLOEXEC (the close-on-exec flag) on the new |
18604 | file descriptor. |
18605 | O_DIRECTORY Error if _\bp_\ba_\bt_\bh does not name a directory. |
18606 | |
18607 | Opening a file with O_APPEND set causes each write on the file to be |
18608 | appended to the end. If O_TRUNC and a writing mode are specified and the |
18609 | file exists, the file is truncated to zero length. If O_EXCL is set with |
18610 | O_CREAT and the file already exists, o\bop\bpe\ben\bn() returns an error. This may |
18611 | be used to implement a simple exclusive access locking mechanism. If |
18612 | either of O_EXCL or O_NOFOLLOW are set and the last component of the |
18613 | pathname is a symbolic link, o\bop\bpe\ben\bn() will fail even if the symbolic link |
18614 | points to a non-existent name. If the O_NONBLOCK flag is specified, do |
18615 | not wait for the device or file to be ready or available. If the o\bop\bpe\ben\bn() |
18616 | call would result in the process being blocked for some reason (e.g., |
18617 | waiting for carrier on a dialup line), o\bop\bpe\ben\bn() returns immediately. This |
18618 | flag also has the effect of making all subsequent I/O on the open file |
18619 | non-blocking. If the O_SYNC flag is set, all I/O operations on the file |
18620 | will be done synchronously. |
18621 | |
18622 | A FIFO should either be opened with O_RDONLY or with O_WRONLY. The |
18623 | behavior for opening a FIFO with O_RDWR is undefined. |
18624 | |
18625 | When opening a file, a lock with flock(2) semantics can be obtained by |
18626 | setting O_SHLOCK for a shared lock, or O_EXLOCK for an exclusive lock. |
18627 | If creating a file with O_CREAT, the request for the lock will never fail |
18628 | (provided that the underlying filesystem supports locking). |
18629 | |
18630 | If o\bop\bpe\ben\bn() is successful, the file pointer used to mark the current |
18631 | position within the file is set to the beginning of the file. |
18632 | |
18633 | When a new file is created it is given the group of the directory which |
18634 | contains it. |
18635 | |
18636 | The new descriptor is set to remain open across execve(2) system calls; |
18637 | see close(2) and fcntl(2). |
18638 | |
18639 | The system imposes a limit on the number of file descriptors open |
18640 | simultaneously by one process. getdtablesize(3) returns the current |
18641 | system limit. |
18642 | |
18643 | The o\bop\bpe\ben\bna\bat\bt() function is equivalent to o\bop\bpe\ben\bn() except that where _\bp_\ba_\bt_\bh |
18644 | specifies a relative path, the file to be opened is determined relative |
18645 | to the directory associated with file descriptor _\bf_\bd instead of the |
18646 | current working directory. |
18647 | |
18648 | If o\bop\bpe\ben\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
18649 | in the _\bf_\bd parameter, the current working directory is used and the |
18650 | behavior is identical to a call to o\bop\bpe\ben\bn(). |
18651 | |
18652 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18653 | If successful, o\bop\bpe\ben\bn() returns a non-negative integer, termed a file |
18654 | descriptor. Otherwise, a value of -1 is returned and _\be_\br_\br_\bn_\bo is set to |
18655 | indicate the error. |
18656 | |
18657 | E\bER\bRR\bRO\bOR\bRS\bS |
18658 | The o\bop\bpe\ben\bn() and o\bop\bpe\ben\bna\bat\bt() functions will fail if: |
18659 | |
18660 | [ENOTDIR] A component of the path prefix is not a directory. |
18661 | |
18662 | [ENOTDIR] O_DIRECTORY is specified and _\bp_\ba_\bt_\bh does not name a |
18663 | directory. |
18664 | |
18665 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
18666 | characters, or an entire pathname (including the |
18667 | terminating NUL) exceeded PATH_MAX bytes. |
18668 | |
18669 | [ENOENT] O_CREAT is not set and the named file does not exist. |
18670 | |
18671 | [ENOENT] A component of the path name that must exist does not |
18672 | exist. |
18673 | |
18674 | [EACCES] Search permission is denied for a component of the |
18675 | path prefix. |
18676 | |
18677 | [EACCES] The required permissions (for reading and/or writing) |
18678 | are denied for the given _\bf_\bl_\ba_\bg_\bs. |
18679 | |
18680 | [EACCES] O_CREAT is specified, the file does not exist, and the |
18681 | directory in which it is to be created does not permit |
18682 | writing. |
18683 | |
18684 | [ELOOP] Too many symbolic links were encountered in |
18685 | translating the pathname, or the O_NOFOLLOW flag was |
18686 | specified and the target is a symbolic link. |
18687 | |
18688 | [EISDIR] The named file is a directory, and the arguments |
18689 | specify it is to be opened for writing. |
18690 | |
18691 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs specified for opening the file are not |
18692 | valid. |
18693 | |
18694 | [EROFS] The named file resides on a read-only file system, and |
18695 | the file is to be modified. |
18696 | |
18697 | [EMFILE] The process has already reached its limit for open |
18698 | file descriptors. |
18699 | |
18700 | [ENFILE] The system file table is full. |
18701 | |
18702 | [ENXIO] The named file is a character special or block special |
18703 | file, and the device associated with this special file |
18704 | does not exist. |
18705 | |
18706 | [ENXIO] The named file is a FIFO, the O_NONBLOCK and O_WRONLY |
18707 | flags are set, and no process has the file open for |
18708 | reading. |
18709 | |
18710 | [EINTR] The o\bop\bpe\ben\bn() operation was interrupted by a signal. |
18711 | |
18712 | [EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying |
18713 | filesystem does not support locking. |
18714 | |
18715 | [EWOULDBLOCK] O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is |
18716 | specified and the file is already locked. |
18717 | |
18718 | [ENOSPC] O_CREAT is specified, the file does not exist, and the |
18719 | directory in which the entry for the new file is being |
18720 | placed cannot be extended because there is no space |
18721 | left on the file system containing the directory. |
18722 | |
18723 | [ENOSPC] O_CREAT is specified, the file does not exist, and |
18724 | there are no free inodes on the file system on which |
18725 | the file is being created. |
18726 | |
18727 | [EDQUOT] O_CREAT is specified, the file does not exist, and the |
18728 | directory in which the entry for the new file is being |
18729 | placed cannot be extended because the user's quota of |
18730 | disk blocks on the file system containing the |
18731 | directory has been exhausted. |
18732 | |
18733 | [EDQUOT] O_CREAT is specified, the file does not exist, and the |
18734 | user's quota of inodes on the file system on which the |
18735 | file is being created has been exhausted. |
18736 | |
18737 | [EIO] An I/O error occurred while making the directory entry |
18738 | or allocating the inode for O_CREAT. |
18739 | |
18740 | [ETXTBSY] The file is a pure procedure (shared text) file that |
18741 | is being executed and the o\bop\bpe\ben\bn() call requests write |
18742 | access. |
18743 | |
18744 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
18745 | space. |
18746 | |
18747 | [EEXIST] O_CREAT and O_EXCL were specified and the file exists. |
18748 | |
18749 | [EPERM] The file named by _\bp_\ba_\bt_\bh is flagged append-only but |
18750 | O_APPEND was not specified in _\bf_\bl_\ba_\bg_\bs. |
18751 | |
18752 | [EOPNOTSUPP] An attempt was made to open a socket (not currently |
18753 | implemented). |
18754 | |
18755 | [EBUSY] An attempt was made to open a terminal device that |
18756 | requires exclusive access and the specified device has |
18757 | already be opened. |
18758 | |
18759 | Additionally, the o\bop\bpe\ben\bna\bat\bt() function will fail if: |
18760 | |
18761 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
18762 | argument is neither AT_FDCWD nor a valid file |
18763 | descriptor. |
18764 | |
18765 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
18766 | argument is a valid file descriptor but it does not |
18767 | reference a directory. |
18768 | |
18769 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
18770 | permission is denied for the directory which the _\bf_\bd |
18771 | file descriptor references. |
18772 | |
18773 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
18774 | chflags(2), chmod(2), close(2), dup(2), flock(2), lseek(2), read(2), |
18775 | umask(2), write(2), getdtablesize(3) |
18776 | |
18777 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
18778 | The o\bop\bpe\ben\bn() and o\bop\bpe\ben\bna\bat\bt() functions conform to IEEE Std 1003.1-2008 |
18779 | (``POSIX.1''). |
18780 | |
18781 | POSIX specifies three different flavors for synchronous I/O: O_SYNC, |
18782 | O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent. |
18783 | |
18784 | The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should |
18785 | not be used if portability is of concern. |
18786 | |
18787 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
18788 | An o\bop\bpe\ben\bn() system call first appeared in Version 1 AT&T UNIX. The _\bf_\bl_\ba_\bg_\bs |
18789 | argument has been supported since 4.2BSD. Before that, a dedicated |
18790 | c\bcr\bre\bea\bat\bt() system call had to be used to create new files; it appeared in |
18791 | Version 1 AT&T UNIX, was deprecated in 4.3BSD-Reno, and removed in |
18792 | OpenBSD 5.0. |
18793 | |
18794 | The o\bop\bpe\ben\bna\bat\bt() system call has been available since OpenBSD 5.0. |
18795 | |
18796 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
18797 | The O_TRUNC flag requires that one of O_RDWR or O_WRONLY also be |
18798 | specified, else EINVAL is returned. |
18799 | |
18800 | N\bNA\bAM\bME\bE |
18801 | o\bop\bpe\ben\bn, o\bop\bpe\ben\bna\bat\bt - open or create a file for reading or writing |
18802 | |
18803 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
18804 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
18805 | |
18806 | _\bi_\bn_\bt |
18807 | o\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\b._\b._\b.); |
18808 | |
18809 | _\bi_\bn_\bt |
18810 | o\bop\bpe\ben\bna\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\b._\b._\b.); |
18811 | |
18812 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
18813 | The file name specified by _\bp_\ba_\bt_\bh is opened for reading and/or writing as |
18814 | specified by the argument _\bf_\bl_\ba_\bg_\bs and the file descriptor returned to the |
18815 | calling process. The _\bf_\bl_\ba_\bg_\bs argument may indicate the file is to be |
18816 | created if it does not exist (by specifying the O_CREAT flag), in which |
18817 | case the file is created with a mode specified by an additional argument |
18818 | of type _\bm_\bo_\bd_\be_\b__\bt as described in chmod(2) and modified by the process' |
18819 | umask value (see umask(2)). |
18820 | |
18821 | The _\bf_\bl_\ba_\bg_\bs specified are a bitwise OR of the following values. Exactly |
18822 | one of the first three values (file access modes) must be specified: |
18823 | |
18824 | O_RDONLY Open for reading only. |
18825 | O_WRONLY Open for writing only. |
18826 | O_RDWR Open for reading and writing. |
18827 | |
18828 | Any combination of the following flags may additionally be used: |
18829 | |
18830 | O_NONBLOCK Do not block on open or for data to become available. |
18831 | O_APPEND Append on each write. |
18832 | O_CREAT Create file if it does not exist. An additional |
18833 | argument of type _\bm_\bo_\bd_\be_\b__\bt must be supplied to the call. |
18834 | O_TRUNC Truncate size to 0. |
18835 | O_EXCL Error if O_CREAT is set and file exists. |
18836 | O_SYNC Perform synchronous I/O operations. |
18837 | O_SHLOCK Atomically obtain a shared lock. |
18838 | O_EXLOCK Atomically obtain an exclusive lock. |
18839 | O_NOFOLLOW If last path element is a symlink, don't follow it. |
18840 | O_CLOEXEC Set FD_CLOEXEC (the close-on-exec flag) on the new |
18841 | file descriptor. |
18842 | O_DIRECTORY Error if _\bp_\ba_\bt_\bh does not name a directory. |
18843 | |
18844 | Opening a file with O_APPEND set causes each write on the file to be |
18845 | appended to the end. If O_TRUNC and a writing mode are specified and the |
18846 | file exists, the file is truncated to zero length. If O_EXCL is set with |
18847 | O_CREAT and the file already exists, o\bop\bpe\ben\bn() returns an error. This may |
18848 | be used to implement a simple exclusive access locking mechanism. If |
18849 | either of O_EXCL or O_NOFOLLOW are set and the last component of the |
18850 | pathname is a symbolic link, o\bop\bpe\ben\bn() will fail even if the symbolic link |
18851 | points to a non-existent name. If the O_NONBLOCK flag is specified, do |
18852 | not wait for the device or file to be ready or available. If the o\bop\bpe\ben\bn() |
18853 | call would result in the process being blocked for some reason (e.g., |
18854 | waiting for carrier on a dialup line), o\bop\bpe\ben\bn() returns immediately. This |
18855 | flag also has the effect of making all subsequent I/O on the open file |
18856 | non-blocking. If the O_SYNC flag is set, all I/O operations on the file |
18857 | will be done synchronously. |
18858 | |
18859 | A FIFO should either be opened with O_RDONLY or with O_WRONLY. The |
18860 | behavior for opening a FIFO with O_RDWR is undefined. |
18861 | |
18862 | When opening a file, a lock with flock(2) semantics can be obtained by |
18863 | setting O_SHLOCK for a shared lock, or O_EXLOCK for an exclusive lock. |
18864 | If creating a file with O_CREAT, the request for the lock will never fail |
18865 | (provided that the underlying filesystem supports locking). |
18866 | |
18867 | If o\bop\bpe\ben\bn() is successful, the file pointer used to mark the current |
18868 | position within the file is set to the beginning of the file. |
18869 | |
18870 | When a new file is created it is given the group of the directory which |
18871 | contains it. |
18872 | |
18873 | The new descriptor is set to remain open across execve(2) system calls; |
18874 | see close(2) and fcntl(2). |
18875 | |
18876 | The system imposes a limit on the number of file descriptors open |
18877 | simultaneously by one process. getdtablesize(3) returns the current |
18878 | system limit. |
18879 | |
18880 | The o\bop\bpe\ben\bna\bat\bt() function is equivalent to o\bop\bpe\ben\bn() except that where _\bp_\ba_\bt_\bh |
18881 | specifies a relative path, the file to be opened is determined relative |
18882 | to the directory associated with file descriptor _\bf_\bd instead of the |
18883 | current working directory. |
18884 | |
18885 | If o\bop\bpe\ben\bna\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
18886 | in the _\bf_\bd parameter, the current working directory is used and the |
18887 | behavior is identical to a call to o\bop\bpe\ben\bn(). |
18888 | |
18889 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
18890 | If successful, o\bop\bpe\ben\bn() returns a non-negative integer, termed a file |
18891 | descriptor. Otherwise, a value of -1 is returned and _\be_\br_\br_\bn_\bo is set to |
18892 | indicate the error. |
18893 | |
18894 | E\bER\bRR\bRO\bOR\bRS\bS |
18895 | The o\bop\bpe\ben\bn() and o\bop\bpe\ben\bna\bat\bt() functions will fail if: |
18896 | |
18897 | [ENOTDIR] A component of the path prefix is not a directory. |
18898 | |
18899 | [ENOTDIR] O_DIRECTORY is specified and _\bp_\ba_\bt_\bh does not name a |
18900 | directory. |
18901 | |
18902 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
18903 | characters, or an entire pathname (including the |
18904 | terminating NUL) exceeded PATH_MAX bytes. |
18905 | |
18906 | [ENOENT] O_CREAT is not set and the named file does not exist. |
18907 | |
18908 | [ENOENT] A component of the path name that must exist does not |
18909 | exist. |
18910 | |
18911 | [EACCES] Search permission is denied for a component of the |
18912 | path prefix. |
18913 | |
18914 | [EACCES] The required permissions (for reading and/or writing) |
18915 | are denied for the given _\bf_\bl_\ba_\bg_\bs. |
18916 | |
18917 | [EACCES] O_CREAT is specified, the file does not exist, and the |
18918 | directory in which it is to be created does not permit |
18919 | writing. |
18920 | |
18921 | [ELOOP] Too many symbolic links were encountered in |
18922 | translating the pathname, or the O_NOFOLLOW flag was |
18923 | specified and the target is a symbolic link. |
18924 | |
18925 | [EISDIR] The named file is a directory, and the arguments |
18926 | specify it is to be opened for writing. |
18927 | |
18928 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs specified for opening the file are not |
18929 | valid. |
18930 | |
18931 | [EROFS] The named file resides on a read-only file system, and |
18932 | the file is to be modified. |
18933 | |
18934 | [EMFILE] The process has already reached its limit for open |
18935 | file descriptors. |
18936 | |
18937 | [ENFILE] The system file table is full. |
18938 | |
18939 | [ENXIO] The named file is a character special or block special |
18940 | file, and the device associated with this special file |
18941 | does not exist. |
18942 | |
18943 | [ENXIO] The named file is a FIFO, the O_NONBLOCK and O_WRONLY |
18944 | flags are set, and no process has the file open for |
18945 | reading. |
18946 | |
18947 | [EINTR] The o\bop\bpe\ben\bn() operation was interrupted by a signal. |
18948 | |
18949 | [EOPNOTSUPP] O_SHLOCK or O_EXLOCK is specified but the underlying |
18950 | filesystem does not support locking. |
18951 | |
18952 | [EWOULDBLOCK] O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is |
18953 | specified and the file is already locked. |
18954 | |
18955 | [ENOSPC] O_CREAT is specified, the file does not exist, and the |
18956 | directory in which the entry for the new file is being |
18957 | placed cannot be extended because there is no space |
18958 | left on the file system containing the directory. |
18959 | |
18960 | [ENOSPC] O_CREAT is specified, the file does not exist, and |
18961 | there are no free inodes on the file system on which |
18962 | the file is being created. |
18963 | |
18964 | [EDQUOT] O_CREAT is specified, the file does not exist, and the |
18965 | directory in which the entry for the new file is being |
18966 | placed cannot be extended because the user's quota of |
18967 | disk blocks on the file system containing the |
18968 | directory has been exhausted. |
18969 | |
18970 | [EDQUOT] O_CREAT is specified, the file does not exist, and the |
18971 | user's quota of inodes on the file system on which the |
18972 | file is being created has been exhausted. |
18973 | |
18974 | [EIO] An I/O error occurred while making the directory entry |
18975 | or allocating the inode for O_CREAT. |
18976 | |
18977 | [ETXTBSY] The file is a pure procedure (shared text) file that |
18978 | is being executed and the o\bop\bpe\ben\bn() call requests write |
18979 | access. |
18980 | |
18981 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
18982 | space. |
18983 | |
18984 | [EEXIST] O_CREAT and O_EXCL were specified and the file exists. |
18985 | |
18986 | [EPERM] The file named by _\bp_\ba_\bt_\bh is flagged append-only but |
18987 | O_APPEND was not specified in _\bf_\bl_\ba_\bg_\bs. |
18988 | |
18989 | [EOPNOTSUPP] An attempt was made to open a socket (not currently |
18990 | implemented). |
18991 | |
18992 | [EBUSY] An attempt was made to open a terminal device that |
18993 | requires exclusive access and the specified device has |
18994 | already be opened. |
18995 | |
18996 | Additionally, the o\bop\bpe\ben\bna\bat\bt() function will fail if: |
18997 | |
18998 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
18999 | argument is neither AT_FDCWD nor a valid file |
19000 | descriptor. |
19001 | |
19002 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
19003 | argument is a valid file descriptor but it does not |
19004 | reference a directory. |
19005 | |
19006 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
19007 | permission is denied for the directory which the _\bf_\bd |
19008 | file descriptor references. |
19009 | |
19010 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
19011 | chflags(2), chmod(2), close(2), dup(2), flock(2), lseek(2), read(2), |
19012 | umask(2), write(2), getdtablesize(3) |
19013 | |
19014 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
19015 | The o\bop\bpe\ben\bn() and o\bop\bpe\ben\bna\bat\bt() functions conform to IEEE Std 1003.1-2008 |
19016 | (``POSIX.1''). |
19017 | |
19018 | POSIX specifies three different flavors for synchronous I/O: O_SYNC, |
19019 | O_DSYNC, and O_RSYNC. In OpenBSD, these are all equivalent. |
19020 | |
19021 | The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should |
19022 | not be used if portability is of concern. |
19023 | |
19024 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
19025 | An o\bop\bpe\ben\bn() system call first appeared in Version 1 AT&T UNIX. The _\bf_\bl_\ba_\bg_\bs |
19026 | argument has been supported since 4.2BSD. Before that, a dedicated |
19027 | c\bcr\bre\bea\bat\bt() system call had to be used to create new files; it appeared in |
19028 | Version 1 AT&T UNIX, was deprecated in 4.3BSD-Reno, and removed in |
19029 | OpenBSD 5.0. |
19030 | |
19031 | The o\bop\bpe\ben\bna\bat\bt() system call has been available since OpenBSD 5.0. |
19032 | |
19033 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
19034 | The O_TRUNC flag requires that one of O_RDWR or O_WRONLY also be |
19035 | specified, else EINVAL is returned. |
19036 | |
19037 | N\bNA\bAM\bME\bE |
19038 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf, f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf - get configurable pathname variables |
19039 | |
19040 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
19041 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
19042 | |
19043 | _\bl_\bo_\bn_\bg |
19044 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bn_\ba_\bm_\be); |
19045 | |
19046 | _\bl_\bo_\bn_\bg |
19047 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf(_\bi_\bn_\bt _\bf_\bd, _\bi_\bn_\bt _\bn_\ba_\bm_\be); |
19048 | |
19049 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
19050 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf() and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf() functions provide a method for |
19051 | applications to determine the current value of a configurable system |
19052 | limit or option variable associated with a pathname or file descriptor. |
19053 | |
19054 | For p\bpa\bat\bth\bhc\bco\bon\bnf\bf, the _\bp_\ba_\bt_\bh argument is the name of a file or directory. For |
19055 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf, the _\bf_\bd argument is an open file descriptor. The _\bn_\ba_\bm_\be argument |
19056 | specifies the system variable to be queried. Symbolic constants for each |
19057 | name value are found in the include file <_\bu_\bn_\bi_\bs_\bt_\bd_\b._\bh>. |
19058 | |
19059 | The available values are as follows: |
19060 | |
19061 | _PC_LINK_MAX |
19062 | The maximum file link count. |
19063 | |
19064 | _PC_MAX_CANON |
19065 | The maximum number of bytes in a terminal canonical input line. |
19066 | |
19067 | _PC_MAX_INPUT |
19068 | The maximum number of bytes for which space is available in a |
19069 | terminal input queue. |
19070 | |
19071 | _PC_NAME_MAX |
19072 | The maximum number of bytes in a file name. |
19073 | |
19074 | _PC_PATH_MAX |
19075 | The maximum number of bytes in a pathname. |
19076 | |
19077 | _PC_PIPE_BUF |
19078 | The maximum number of bytes which will be written atomically to a |
19079 | pipe. |
19080 | |
19081 | _PC_CHOWN_RESTRICTED |
19082 | Returns 1 if appropriate privileges are required for the chown(2) |
19083 | system call, otherwise 0. IEEE Std 1003.1-2001 (``POSIX.1'') |
19084 | requires appropriate privilege in all cases, but this behavior |
19085 | was optional in prior editions of the standard. |
19086 | |
19087 | _PC_NO_TRUNC |
19088 | Returns 1 if attempts to use pathname components longer than |
19089 | {NAME_MAX} will result in an [ENAMETOOLONG] error; otherwise, |
19090 | such components will be truncated to {NAME_MAX}. IEEE Std |
19091 | 1003.1-2001 (``POSIX.1'') requires the error in all cases, but |
19092 | this behavior was optional in prior editions of the standard, and |
19093 | some non-POSIX-compliant file systems do not support this |
19094 | behavior. |
19095 | |
19096 | _PC_VDISABLE |
19097 | Returns the terminal character disabling value. |
19098 | |
19099 | _PC_2_SYMLINKS |
19100 | Returns 1 if the filesystem supports the creation of symbolic |
19101 | links within the specified directory; the meaning of |
19102 | _PC_2_SYMLINKS is unspecified for non-directory files. |
19103 | |
19104 | _PC_ALLOC_SIZE_MIN |
19105 | Minimum number of bytes of storage allocated for any portion of a |
19106 | file. |
19107 | |
19108 | _PC_ASYNC_IO |
19109 | Returns 1 if asynchronous I/O is supported, otherwise 0. |
19110 | |
19111 | _PC_FILESIZEBITS |
19112 | Number of bits needed to represent the maximum file size. |
19113 | |
19114 | _PC_PRIO_IO |
19115 | Returns 1 if prioritized I/O is supported, otherwise 0. |
19116 | |
19117 | _PC_REC_INCR_XFER_SIZE |
19118 | Recommended increment for file transfer sizes between |
19119 | _PC_REC_MIN_XFER_SIZE and _PC_REC_MAX_XFER_SIZE. |
19120 | |
19121 | _PC_REC_MAX_XFER_SIZE |
19122 | Maximum recommended file transfer size. |
19123 | |
19124 | _PC_REC_MIN_XFER_SIZE |
19125 | Minimum recommended file transfer size. |
19126 | |
19127 | _PC_REC_XFER_ALIGN |
19128 | Recommended file transfer buffer alignment. |
19129 | |
19130 | _PC_SYMLINK_MAX |
19131 | Maximum number of bytes in a symbolic link. |
19132 | |
19133 | _PC_SYNC_IO |
19134 | Returns 1 if synchronized I/O is supported, otherwise 0. |
19135 | |
19136 | _PC_TIMESTAMP_RESOLUTION |
19137 | The resolution in nanoseconds of file timestamps. |
19138 | |
19139 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
19140 | If the call to p\bpa\bat\bth\bhc\bco\bon\bnf\bf or f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf is not successful, -1 is returned |
19141 | and _\be_\br_\br_\bn_\bo is set appropriately. Otherwise, if the variable is associated |
19142 | with functionality that does not have a limit in the system, -1 is |
19143 | returned and _\be_\br_\br_\bn_\bo is not modified. Otherwise, the current variable |
19144 | value is returned. |
19145 | |
19146 | E\bER\bRR\bRO\bOR\bRS\bS |
19147 | If any of the following conditions occur, the p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf |
19148 | functions shall return -1 and set _\be_\br_\br_\bn_\bo to the corresponding value. |
19149 | |
19150 | [EINVAL] The value of the _\bn_\ba_\bm_\be argument is invalid. |
19151 | |
19152 | [EINVAL] The implementation does not support an association of |
19153 | the variable name with the associated file. |
19154 | |
19155 | [EIO] An I/O error occurred while reading from the file |
19156 | system. |
19157 | |
19158 | p\bpa\bat\bth\bhc\bco\bon\bnf\bf() will fail if: |
19159 | |
19160 | [ENOTDIR] A component of the path prefix is not a directory. |
19161 | |
19162 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters |
19163 | (but see _PC_NO_TRUNC above), or an entire pathname |
19164 | (including the terminating NUL) exceeded PATH_MAX |
19165 | bytes. |
19166 | |
19167 | [ENOENT] The named file does not exist. |
19168 | |
19169 | [EACCES] Search permission is denied for a component of the |
19170 | path prefix. |
19171 | |
19172 | [ELOOP] Too many symbolic links were encountered in |
19173 | translating the pathname. |
19174 | |
19175 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
19176 | space. |
19177 | |
19178 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf() will fail if: |
19179 | |
19180 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
19181 | |
19182 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
19183 | sysconf(3), sysctl(3) |
19184 | |
19185 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
19186 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf functions conform to IEEE Std 1003.1-2008 |
19187 | (``POSIX.1''). |
19188 | |
19189 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
19190 | The p\bpa\bat\bth\bhc\bco\bon\bnf\bf and f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf functions first appeared in 4.4BSD. |
19191 | |
19192 | N\bNA\bAM\bME\bE |
19193 | p\bpi\bip\bpe\be, p\bpi\bip\bpe\be2\b2 - create descriptor pair for interprocess communication |
19194 | |
19195 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
19196 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
19197 | |
19198 | _\bi_\bn_\bt |
19199 | p\bpi\bip\bpe\be(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b2_\b]); |
19200 | |
19201 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
19202 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
19203 | |
19204 | _\bi_\bn_\bt |
19205 | p\bpi\bip\bpe\be2\b2(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b2_\b], _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
19206 | |
19207 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
19208 | The p\bpi\bip\bpe\be() function creates a _\bp_\bi_\bp_\be, which is an object allowing |
19209 | unidirectional data flow, and allocates a pair of file descriptors. The |
19210 | first descriptor connects to the _\br_\be_\ba_\bd _\be_\bn_\bd of the pipe, and the second |
19211 | connects to the _\bw_\br_\bi_\bt_\be _\be_\bn_\bd, so that data written to _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b1_\b] appears on |
19212 | (i.e., can be read from) _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b0_\b]. This allows the output of one |
19213 | program to be sent to another program: the source's standard output is |
19214 | set up to be the write end of the pipe, and the sink's standard input is |
19215 | set up to be the read end of the pipe. The pipe itself persists until |
19216 | all its associated descriptors are closed. |
19217 | |
19218 | A pipe whose read or write end has been closed is considered _\bw_\bi_\bd_\bo_\bw_\be_\bd. |
19219 | Writing on such a pipe causes the writing process to receive a SIGPIPE |
19220 | signal. Widowing a pipe is the only way to deliver end-of-file to a |
19221 | reader: after the reader consumes any buffered data, reading a widowed |
19222 | pipe returns a zero count. |
19223 | |
19224 | The p\bpi\bip\bpe\be2\b2() function is identical to p\bpi\bip\bpe\be() except that the non-blocking |
19225 | I/O mode on both ends of the pipe is determined by the O_NONBLOCK flag in |
19226 | the _\bf_\bl_\ba_\bg_\bs argument and the close-on-exec flag on both the new file |
19227 | descriptors is determined by the O_CLOEXEC flag in the _\bf_\bl_\ba_\bg_\bs argument. |
19228 | |
19229 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
19230 | Upon successful completion, the value 0 is returned; otherwise the |
19231 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
19232 | error. |
19233 | |
19234 | E\bER\bRR\bRO\bOR\bRS\bS |
19235 | p\bpi\bip\bpe\be() and p\bpi\bip\bpe\be2\b2() will succeed unless: |
19236 | |
19237 | [EMFILE] Too many descriptors are active. |
19238 | |
19239 | [ENFILE] The system file table is full. |
19240 | |
19241 | [EFAULT] The _\bf_\bi_\bl_\bd_\be_\bs buffer is in an invalid area of the |
19242 | process's address space. |
19243 | |
19244 | In addition, p\bpi\bip\bpe\be2\b2() may return the following error: |
19245 | |
19246 | [EINVAL] _\bf_\bl_\ba_\bg_\bs is invalid. |
19247 | |
19248 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
19249 | sh(1), fork(2), read(2), socketpair(2), write(2) |
19250 | |
19251 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
19252 | The p\bpi\bip\bpe\be() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The |
19253 | p\bpi\bip\bpe\be2\b2() function is expected to conform to a future revision of that |
19254 | standard. |
19255 | |
19256 | As an extension, the pipe provided is actually capable of moving data |
19257 | bidirectionally. This is compatible with SVR4. However, this is non- |
19258 | POSIX behaviour which should not be relied on, for reasons of |
19259 | portability. |
19260 | |
19261 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
19262 | A p\bpi\bip\bpe\be() function call appeared in Version 3 AT&T UNIX. Since Version 4 |
19263 | AT&T UNIX, it allocates two distinct file descriptors. The p\bpi\bip\bpe\be2\b2() |
19264 | function appeared in OpenBSD 5.7. |
19265 | |
19266 | N\bNA\bAM\bME\bE |
19267 | p\bpi\bip\bpe\be, p\bpi\bip\bpe\be2\b2 - create descriptor pair for interprocess communication |
19268 | |
19269 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
19270 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
19271 | |
19272 | _\bi_\bn_\bt |
19273 | p\bpi\bip\bpe\be(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b2_\b]); |
19274 | |
19275 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
19276 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
19277 | |
19278 | _\bi_\bn_\bt |
19279 | p\bpi\bip\bpe\be2\b2(_\bi_\bn_\bt _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b2_\b], _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
19280 | |
19281 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
19282 | The p\bpi\bip\bpe\be() function creates a _\bp_\bi_\bp_\be, which is an object allowing |
19283 | unidirectional data flow, and allocates a pair of file descriptors. The |
19284 | first descriptor connects to the _\br_\be_\ba_\bd _\be_\bn_\bd of the pipe, and the second |
19285 | connects to the _\bw_\br_\bi_\bt_\be _\be_\bn_\bd, so that data written to _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b1_\b] appears on |
19286 | (i.e., can be read from) _\bf_\bi_\bl_\bd_\be_\bs_\b[_\b0_\b]. This allows the output of one |
19287 | program to be sent to another program: the source's standard output is |
19288 | set up to be the write end of the pipe, and the sink's standard input is |
19289 | set up to be the read end of the pipe. The pipe itself persists until |
19290 | all its associated descriptors are closed. |
19291 | |
19292 | A pipe whose read or write end has been closed is considered _\bw_\bi_\bd_\bo_\bw_\be_\bd. |
19293 | Writing on such a pipe causes the writing process to receive a SIGPIPE |
19294 | signal. Widowing a pipe is the only way to deliver end-of-file to a |
19295 | reader: after the reader consumes any buffered data, reading a widowed |
19296 | pipe returns a zero count. |
19297 | |
19298 | The p\bpi\bip\bpe\be2\b2() function is identical to p\bpi\bip\bpe\be() except that the non-blocking |
19299 | I/O mode on both ends of the pipe is determined by the O_NONBLOCK flag in |
19300 | the _\bf_\bl_\ba_\bg_\bs argument and the close-on-exec flag on both the new file |
19301 | descriptors is determined by the O_CLOEXEC flag in the _\bf_\bl_\ba_\bg_\bs argument. |
19302 | |
19303 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
19304 | Upon successful completion, the value 0 is returned; otherwise the |
19305 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
19306 | error. |
19307 | |
19308 | E\bER\bRR\bRO\bOR\bRS\bS |
19309 | p\bpi\bip\bpe\be() and p\bpi\bip\bpe\be2\b2() will succeed unless: |
19310 | |
19311 | [EMFILE] Too many descriptors are active. |
19312 | |
19313 | [ENFILE] The system file table is full. |
19314 | |
19315 | [EFAULT] The _\bf_\bi_\bl_\bd_\be_\bs buffer is in an invalid area of the |
19316 | process's address space. |
19317 | |
19318 | In addition, p\bpi\bip\bpe\be2\b2() may return the following error: |
19319 | |
19320 | [EINVAL] _\bf_\bl_\ba_\bg_\bs is invalid. |
19321 | |
19322 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
19323 | sh(1), fork(2), read(2), socketpair(2), write(2) |
19324 | |
19325 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
19326 | The p\bpi\bip\bpe\be() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). The |
19327 | p\bpi\bip\bpe\be2\b2() function is expected to conform to a future revision of that |
19328 | standard. |
19329 | |
19330 | As an extension, the pipe provided is actually capable of moving data |
19331 | bidirectionally. This is compatible with SVR4. However, this is non- |
19332 | POSIX behaviour which should not be relied on, for reasons of |
19333 | portability. |
19334 | |
19335 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
19336 | A p\bpi\bip\bpe\be() function call appeared in Version 3 AT&T UNIX. Since Version 4 |
19337 | AT&T UNIX, it allocates two distinct file descriptors. The p\bpi\bip\bpe\be2\b2() |
19338 | function appeared in OpenBSD 5.7. |
19339 | |
19340 | N\bNA\bAM\bME\bE |
19341 | p\bpo\bol\bll\bl, p\bpp\bpo\bol\bll\bl - synchronous I/O multiplexing |
19342 | |
19343 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
19344 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<p\bpo\bol\bll\bl.\b.h\bh>\b> |
19345 | |
19346 | _\bi_\bn_\bt |
19347 | p\bpo\bol\bll\bl(_\bs_\bt_\br_\bu_\bc_\bt _\bp_\bo_\bl_\bl_\bf_\bd _\b*_\bf_\bd_\bs, _\bn_\bf_\bd_\bs_\b__\bt _\bn_\bf_\bd_\bs, _\bi_\bn_\bt _\bt_\bi_\bm_\be_\bo_\bu_\bt); |
19348 | |
19349 | _\bi_\bn_\bt |
19350 | p\bpp\bpo\bol\bll\bl(_\bs_\bt_\br_\bu_\bc_\bt _\bp_\bo_\bl_\bl_\bf_\bd _\b*_\bf_\bd_\bs, _\bn_\bf_\bd_\bs_\b__\bt _\bn_\bf_\bd_\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, |
19351 | _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bm_\ba_\bs_\bk); |
19352 | |
19353 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
19354 | p\bpo\bol\bll\bl() provides a mechanism for multiplexing I/O across a set of file |
19355 | descriptors. It is similar in function to select(2). Unlike select(2), |
19356 | however, it is possible to only pass in data corresponding to the file |
19357 | descriptors for which events are wanted. This makes p\bpo\bol\bll\bl() more |
19358 | efficient than select(2) in most cases. |
19359 | |
19360 | The arguments are as follows: |
19361 | |
19362 | _\bf_\bd_\bs Points to an array of _\bp_\bo_\bl_\bl_\bf_\bd structures, which are defined as: |
19363 | |
19364 | struct pollfd { |
19365 | int fd; |
19366 | short events; |
19367 | short revents; |
19368 | }; |
19369 | |
19370 | The _\bf_\bd member is an open file descriptor. If _\bf_\bd is -1, the |
19371 | _\bp_\bo_\bl_\bl_\bf_\bd structure is considered unused, and _\br_\be_\bv_\be_\bn_\bt_\bs will be |
19372 | cleared. |
19373 | |
19374 | The _\be_\bv_\be_\bn_\bt_\bs and _\br_\be_\bv_\be_\bn_\bt_\bs members are bitmasks of conditions to |
19375 | monitor and conditions found, respectively. |
19376 | |
19377 | _\bn_\bf_\bd_\bs An unsigned integer specifying the number of _\bp_\bo_\bl_\bl_\bf_\bd structures |
19378 | in the array. |
19379 | |
19380 | _\bt_\bi_\bm_\be_\bo_\bu_\bt Maximum interval to wait for the poll to complete, in |
19381 | milliseconds. If this value is 0, p\bpo\bol\bll\bl() will return |
19382 | immediately. If this value is INFTIM (-1), p\bpo\bol\bll\bl() will block |
19383 | indefinitely until a condition is found. |
19384 | |
19385 | The calling process sets the _\be_\bv_\be_\bn_\bt_\bs bitmask and p\bpo\bol\bll\bl() sets the _\br_\be_\bv_\be_\bn_\bt_\bs |
19386 | bitmask. Each call to p\bpo\bol\bll\bl() resets the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask for accuracy. |
19387 | The condition flags in the bitmasks are defined as: |
19388 | |
19389 | POLLIN Data other than high-priority data may be read without |
19390 | blocking. |
19391 | |
19392 | POLLRDNORM Normal data may be read without blocking. |
19393 | |
19394 | POLLRDBAND Priority data may be read without blocking. |
19395 | |
19396 | POLLNORM Same as POLLRDNORM. This flag is provided for source code |
19397 | compatibility with older programs and should not be used in |
19398 | new code. |
19399 | |
19400 | POLLPRI High-priority data may be read without blocking. |
19401 | |
19402 | POLLOUT Normal data may be written without blocking. |
19403 | |
19404 | POLLWRNORM Same as POLLOUT. |
19405 | |
19406 | POLLWRBAND Priority data may be written. |
19407 | |
19408 | POLLERR An error has occurred on the device or socket. This flag is |
19409 | only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; it is ignored in the |
19410 | _\be_\bv_\be_\bn_\bt_\bs member. |
19411 | |
19412 | POLLHUP The device or socket has been disconnected. This event and |
19413 | POLLOUT are mutually-exclusive; a descriptor can never be |
19414 | writable if a hangup has occurred. However, this event and |
19415 | POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually- |
19416 | exclusive. This flag is only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; |
19417 | it is ignored in the _\be_\bv_\be_\bn_\bt_\bs member. |
19418 | |
19419 | POLLNVAL The corresponding file descriptor is invalid. This flag is |
19420 | only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; it is ignored in the |
19421 | _\be_\bv_\be_\bn_\bt_\bs member. |
19422 | |
19423 | The significance and semantics of normal, priority, and high-priority |
19424 | data are device-specific. |
19425 | |
19426 | In addition to I/O multiplexing, p\bpo\bol\bll\bl() can be used to generate simple |
19427 | timeouts. This functionality may be achieved by passing a null pointer |
19428 | for _\bf_\bd_\bs. |
19429 | |
19430 | The p\bpp\bpo\bol\bll\bl() function is similar to p\bpo\bol\bll\bl() except that it specifies the |
19431 | timeout using a timespec structure, and a null pointer is used to specify |
19432 | an indefinite timeout instead of INFTIM. Also, if _\bm_\ba_\bs_\bk is a non-null |
19433 | pointer, p\bpp\bpo\bol\bll\bl() atomically sets the calling thread's signal mask to the |
19434 | signal set pointed to by _\bm_\ba_\bs_\bk for the duration of the function call. In |
19435 | this case, the original signal mask will be restored before p\bpp\bpo\bol\bll\bl() |
19436 | returns. |
19437 | |
19438 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
19439 | Upon error, p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() return -1 and set the global variable |
19440 | _\be_\br_\br_\bn_\bo to indicate the error. If the timeout interval was reached before |
19441 | any events occurred, they return 0. Otherwise, they return the number of |
19442 | _\bp_\bo_\bl_\bl_\bf_\bd structures for which _\br_\be_\bv_\be_\bn_\bt_\bs is non-zero. |
19443 | |
19444 | I\bID\bDI\bIO\bOM\bMS\bS |
19445 | Care must be taken when converting code from select(2) to p\bpo\bol\bll\bl() as they |
19446 | have slightly different semantics. The first semantic difference is |
19447 | that, unlike select(2), p\bpo\bol\bll\bl() has a way of indicating that one or more |
19448 | file descriptors is invalid by setting a flag in the _\br_\be_\bv_\be_\bn_\bt_\bs field of |
19449 | corresponding entry of _\bf_\bd_\bs, whereas select(2) returns an error (-1) if |
19450 | any of the descriptors with bits set in the _\bf_\bd_\b__\bs_\be_\bt are invalid. The |
19451 | second difference is that on EOF there is no guarantee that POLLIN will |
19452 | be set in _\br_\be_\bv_\be_\bn_\bt_\bs, the caller must also check for POLLHUP. This differs |
19453 | from select(2) where EOF is considered as a read event. |
19454 | |
19455 | Consider the following usage of select(2) that implements a read from the |
19456 | standard input with a 60 second time out: |
19457 | |
19458 | struct timeval timeout; |
19459 | fd_set readfds; |
19460 | char buf[BUFSIZ]; |
19461 | int nready; |
19462 | |
19463 | timeout.tv_sec = 60; |
19464 | timeout.tv_usec = 0; |
19465 | FD_ZERO(&readfds); |
19466 | FD_SET(STDIN_FILENO); |
19467 | nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); |
19468 | if (nready == -1) |
19469 | err(1, "select"); |
19470 | if (nready == 0) |
19471 | errx(1, "time out"); |
19472 | if (FD_ISSET(STDIN_FILENO, &readfds)) { |
19473 | if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) |
19474 | err(1, "read"); |
19475 | } |
19476 | |
19477 | This can be converted to p\bpo\bol\bll\bl() as follows: |
19478 | |
19479 | struct pollfd pdf[1]; |
19480 | char buf[BUFSIZ]; |
19481 | int nready; |
19482 | |
19483 | pfd[0].fd = STDIN_FILENO; |
19484 | pfd[0].events = POLLIN; |
19485 | nready = poll(pfd, 1, 60 * 1000); |
19486 | if (nready == -1) |
19487 | err(1, "poll"); |
19488 | if (nready == 0) |
19489 | errx(1, "time out"); |
19490 | if ((pfd[0].revents & (POLLERR|POLLNVAL))) |
19491 | errx(1, "bad fd %d", pfd[0].fd); |
19492 | if ((pfd[0].revents & (POLLIN|POLLHUP))) |
19493 | if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) |
19494 | err(1, "read"); |
19495 | } |
19496 | |
19497 | E\bER\bRR\bRO\bOR\bRS\bS |
19498 | p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() will fail if: |
19499 | |
19500 | [EFAULT] _\bf_\bd_\bs points outside the process's allocated address |
19501 | space. |
19502 | |
19503 | [EINTR] A signal was caught before any polled events occurred |
19504 | and before the timeout elapsed. |
19505 | |
19506 | [EINVAL] _\bn_\bf_\bd_\bs was greater than the number of available file |
19507 | descriptors. |
19508 | |
19509 | [EINVAL] The timeout passed was invalid. |
19510 | |
19511 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
19512 | clock_gettime(2), getrlimit(2), read(2), select(2), write(2) |
19513 | |
19514 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
19515 | The p\bpo\bol\bll\bl() function is compliant with the IEEE Std 1003.1-2008 |
19516 | (``POSIX.1'') specification. The p\bpp\bpo\bol\bll\bl() function is a Linux extension. |
19517 | |
19518 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
19519 | A p\bpo\bol\bll\bl() system call appeared in AT&T System V Release 3 UNIX. The |
19520 | p\bpp\bpo\bol\bll\bl() function appeared in OpenBSD 5.4. |
19521 | |
19522 | B\bBU\bUG\bGS\bS |
19523 | The POLLWRBAND flag is accepted but ignored by the kernel. |
19524 | |
19525 | Because OpenBSD does not implement STREAMS, there is no distinction |
19526 | between some of the fields in the _\be_\bv_\be_\bn_\bt_\bs and _\br_\be_\bv_\be_\bn_\bt_\bs bitmasks. As a |
19527 | result, the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent. |
19528 | |
19529 | Internally to the kernel, p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() work poorly if multiple |
19530 | processes wait on the same file descriptor. |
19531 | |
19532 | N\bNA\bAM\bME\bE |
19533 | m\bma\bad\bdv\bvi\bis\bse\be, p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be - give advice about use of memory |
19534 | |
19535 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
19536 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmm\bma\ban\bn.\b.h\bh>\b> |
19537 | |
19538 | _\bi_\bn_\bt |
19539 | m\bma\bad\bdv\bvi\bis\bse\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bb_\be_\bh_\ba_\bv); |
19540 | |
19541 | _\bi_\bn_\bt |
19542 | p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bb_\be_\bh_\ba_\bv); |
19543 | |
19544 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
19545 | The m\bma\bad\bdv\bvi\bis\bse\be() system call allows a process that has knowledge of its |
19546 | memory behavior to describe it to the system. The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() |
19547 | interface has the same effect, but returns the error value instead of |
19548 | only setting _\be_\br_\br_\bn_\bo. |
19549 | |
19550 | The possible behaviors are: |
19551 | |
19552 | MADV_NORMAL No further special treatment needed. |
19553 | |
19554 | MADV_RANDOM Expect random page access patterns. |
19555 | |
19556 | MADV_SEQUENTIAL Expect sequential page references. |
19557 | |
19558 | MADV_WILLNEED The pages will be referenced soon. |
19559 | |
19560 | MADV_DONTNEED The pages will not be referenced soon. |
19561 | |
19562 | MADV_SPACEAVAIL Ensure that resources are reserved. |
19563 | |
19564 | MADV_FREE The pages don't contain any useful data and can be |
19565 | recycled. |
19566 | |
19567 | Portable programs that call the p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() interface should use the |
19568 | aliases POSIX_MADV_NORMAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, |
19569 | POSIX_MADV_WILLNEED, and POSIX_MADV_DONTNEED rather than the flags |
19570 | described above. |
19571 | |
19572 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
19573 | The m\bma\bad\bdv\bvi\bis\bse\be() function returns the value 0 if successful; otherwise the |
19574 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
19575 | error. |
19576 | |
19577 | If successful, the p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() function will return zero. Otherwise |
19578 | an error number will be returned to indicate the error. |
19579 | |
19580 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
19581 | mincore(2), minherit(2), mprotect(2), msync(2), munmap(2) |
19582 | |
19583 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
19584 | The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() system call conforms to IEEE Std 1003.1-2008 |
19585 | (``POSIX.1''). |
19586 | |
19587 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
19588 | The m\bma\bad\bdv\bvi\bis\bse\be() function first appeared in 4.4BSD. The p\bpo\bos\bsi\bix\bx_\b_m\bma\bad\bdv\bvi\bis\bse\be() |
19589 | function first appeared in OpenBSD 4.8. |
19590 | |
19591 | B\bBU\bUG\bGS\bS |
19592 | The MADV_WILLNEED behavior is ignored. The MADV_SPACEAVAIL behavior is |
19593 | not implemented and will always fail. |
19594 | |
19595 | N\bNA\bAM\bME\bE |
19596 | p\bpo\bol\bll\bl, p\bpp\bpo\bol\bll\bl - synchronous I/O multiplexing |
19597 | |
19598 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
19599 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<p\bpo\bol\bll\bl.\b.h\bh>\b> |
19600 | |
19601 | _\bi_\bn_\bt |
19602 | p\bpo\bol\bll\bl(_\bs_\bt_\br_\bu_\bc_\bt _\bp_\bo_\bl_\bl_\bf_\bd _\b*_\bf_\bd_\bs, _\bn_\bf_\bd_\bs_\b__\bt _\bn_\bf_\bd_\bs, _\bi_\bn_\bt _\bt_\bi_\bm_\be_\bo_\bu_\bt); |
19603 | |
19604 | _\bi_\bn_\bt |
19605 | p\bpp\bpo\bol\bll\bl(_\bs_\bt_\br_\bu_\bc_\bt _\bp_\bo_\bl_\bl_\bf_\bd _\b*_\bf_\bd_\bs, _\bn_\bf_\bd_\bs_\b__\bt _\bn_\bf_\bd_\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, |
19606 | _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bm_\ba_\bs_\bk); |
19607 | |
19608 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
19609 | p\bpo\bol\bll\bl() provides a mechanism for multiplexing I/O across a set of file |
19610 | descriptors. It is similar in function to select(2). Unlike select(2), |
19611 | however, it is possible to only pass in data corresponding to the file |
19612 | descriptors for which events are wanted. This makes p\bpo\bol\bll\bl() more |
19613 | efficient than select(2) in most cases. |
19614 | |
19615 | The arguments are as follows: |
19616 | |
19617 | _\bf_\bd_\bs Points to an array of _\bp_\bo_\bl_\bl_\bf_\bd structures, which are defined as: |
19618 | |
19619 | struct pollfd { |
19620 | int fd; |
19621 | short events; |
19622 | short revents; |
19623 | }; |
19624 | |
19625 | The _\bf_\bd member is an open file descriptor. If _\bf_\bd is -1, the |
19626 | _\bp_\bo_\bl_\bl_\bf_\bd structure is considered unused, and _\br_\be_\bv_\be_\bn_\bt_\bs will be |
19627 | cleared. |
19628 | |
19629 | The _\be_\bv_\be_\bn_\bt_\bs and _\br_\be_\bv_\be_\bn_\bt_\bs members are bitmasks of conditions to |
19630 | monitor and conditions found, respectively. |
19631 | |
19632 | _\bn_\bf_\bd_\bs An unsigned integer specifying the number of _\bp_\bo_\bl_\bl_\bf_\bd structures |
19633 | in the array. |
19634 | |
19635 | _\bt_\bi_\bm_\be_\bo_\bu_\bt Maximum interval to wait for the poll to complete, in |
19636 | milliseconds. If this value is 0, p\bpo\bol\bll\bl() will return |
19637 | immediately. If this value is INFTIM (-1), p\bpo\bol\bll\bl() will block |
19638 | indefinitely until a condition is found. |
19639 | |
19640 | The calling process sets the _\be_\bv_\be_\bn_\bt_\bs bitmask and p\bpo\bol\bll\bl() sets the _\br_\be_\bv_\be_\bn_\bt_\bs |
19641 | bitmask. Each call to p\bpo\bol\bll\bl() resets the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask for accuracy. |
19642 | The condition flags in the bitmasks are defined as: |
19643 | |
19644 | POLLIN Data other than high-priority data may be read without |
19645 | blocking. |
19646 | |
19647 | POLLRDNORM Normal data may be read without blocking. |
19648 | |
19649 | POLLRDBAND Priority data may be read without blocking. |
19650 | |
19651 | POLLNORM Same as POLLRDNORM. This flag is provided for source code |
19652 | compatibility with older programs and should not be used in |
19653 | new code. |
19654 | |
19655 | POLLPRI High-priority data may be read without blocking. |
19656 | |
19657 | POLLOUT Normal data may be written without blocking. |
19658 | |
19659 | POLLWRNORM Same as POLLOUT. |
19660 | |
19661 | POLLWRBAND Priority data may be written. |
19662 | |
19663 | POLLERR An error has occurred on the device or socket. This flag is |
19664 | only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; it is ignored in the |
19665 | _\be_\bv_\be_\bn_\bt_\bs member. |
19666 | |
19667 | POLLHUP The device or socket has been disconnected. This event and |
19668 | POLLOUT are mutually-exclusive; a descriptor can never be |
19669 | writable if a hangup has occurred. However, this event and |
19670 | POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually- |
19671 | exclusive. This flag is only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; |
19672 | it is ignored in the _\be_\bv_\be_\bn_\bt_\bs member. |
19673 | |
19674 | POLLNVAL The corresponding file descriptor is invalid. This flag is |
19675 | only valid in the _\br_\be_\bv_\be_\bn_\bt_\bs bitmask; it is ignored in the |
19676 | _\be_\bv_\be_\bn_\bt_\bs member. |
19677 | |
19678 | The significance and semantics of normal, priority, and high-priority |
19679 | data are device-specific. |
19680 | |
19681 | In addition to I/O multiplexing, p\bpo\bol\bll\bl() can be used to generate simple |
19682 | timeouts. This functionality may be achieved by passing a null pointer |
19683 | for _\bf_\bd_\bs. |
19684 | |
19685 | The p\bpp\bpo\bol\bll\bl() function is similar to p\bpo\bol\bll\bl() except that it specifies the |
19686 | timeout using a timespec structure, and a null pointer is used to specify |
19687 | an indefinite timeout instead of INFTIM. Also, if _\bm_\ba_\bs_\bk is a non-null |
19688 | pointer, p\bpp\bpo\bol\bll\bl() atomically sets the calling thread's signal mask to the |
19689 | signal set pointed to by _\bm_\ba_\bs_\bk for the duration of the function call. In |
19690 | this case, the original signal mask will be restored before p\bpp\bpo\bol\bll\bl() |
19691 | returns. |
19692 | |
19693 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
19694 | Upon error, p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() return -1 and set the global variable |
19695 | _\be_\br_\br_\bn_\bo to indicate the error. If the timeout interval was reached before |
19696 | any events occurred, they return 0. Otherwise, they return the number of |
19697 | _\bp_\bo_\bl_\bl_\bf_\bd structures for which _\br_\be_\bv_\be_\bn_\bt_\bs is non-zero. |
19698 | |
19699 | I\bID\bDI\bIO\bOM\bMS\bS |
19700 | Care must be taken when converting code from select(2) to p\bpo\bol\bll\bl() as they |
19701 | have slightly different semantics. The first semantic difference is |
19702 | that, unlike select(2), p\bpo\bol\bll\bl() has a way of indicating that one or more |
19703 | file descriptors is invalid by setting a flag in the _\br_\be_\bv_\be_\bn_\bt_\bs field of |
19704 | corresponding entry of _\bf_\bd_\bs, whereas select(2) returns an error (-1) if |
19705 | any of the descriptors with bits set in the _\bf_\bd_\b__\bs_\be_\bt are invalid. The |
19706 | second difference is that on EOF there is no guarantee that POLLIN will |
19707 | be set in _\br_\be_\bv_\be_\bn_\bt_\bs, the caller must also check for POLLHUP. This differs |
19708 | from select(2) where EOF is considered as a read event. |
19709 | |
19710 | Consider the following usage of select(2) that implements a read from the |
19711 | standard input with a 60 second time out: |
19712 | |
19713 | struct timeval timeout; |
19714 | fd_set readfds; |
19715 | char buf[BUFSIZ]; |
19716 | int nready; |
19717 | |
19718 | timeout.tv_sec = 60; |
19719 | timeout.tv_usec = 0; |
19720 | FD_ZERO(&readfds); |
19721 | FD_SET(STDIN_FILENO); |
19722 | nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); |
19723 | if (nready == -1) |
19724 | err(1, "select"); |
19725 | if (nready == 0) |
19726 | errx(1, "time out"); |
19727 | if (FD_ISSET(STDIN_FILENO, &readfds)) { |
19728 | if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) |
19729 | err(1, "read"); |
19730 | } |
19731 | |
19732 | This can be converted to p\bpo\bol\bll\bl() as follows: |
19733 | |
19734 | struct pollfd pdf[1]; |
19735 | char buf[BUFSIZ]; |
19736 | int nready; |
19737 | |
19738 | pfd[0].fd = STDIN_FILENO; |
19739 | pfd[0].events = POLLIN; |
19740 | nready = poll(pfd, 1, 60 * 1000); |
19741 | if (nready == -1) |
19742 | err(1, "poll"); |
19743 | if (nready == 0) |
19744 | errx(1, "time out"); |
19745 | if ((pfd[0].revents & (POLLERR|POLLNVAL))) |
19746 | errx(1, "bad fd %d", pfd[0].fd); |
19747 | if ((pfd[0].revents & (POLLIN|POLLHUP))) |
19748 | if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) |
19749 | err(1, "read"); |
19750 | } |
19751 | |
19752 | E\bER\bRR\bRO\bOR\bRS\bS |
19753 | p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() will fail if: |
19754 | |
19755 | [EFAULT] _\bf_\bd_\bs points outside the process's allocated address |
19756 | space. |
19757 | |
19758 | [EINTR] A signal was caught before any polled events occurred |
19759 | and before the timeout elapsed. |
19760 | |
19761 | [EINVAL] _\bn_\bf_\bd_\bs was greater than the number of available file |
19762 | descriptors. |
19763 | |
19764 | [EINVAL] The timeout passed was invalid. |
19765 | |
19766 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
19767 | clock_gettime(2), getrlimit(2), read(2), select(2), write(2) |
19768 | |
19769 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
19770 | The p\bpo\bol\bll\bl() function is compliant with the IEEE Std 1003.1-2008 |
19771 | (``POSIX.1'') specification. The p\bpp\bpo\bol\bll\bl() function is a Linux extension. |
19772 | |
19773 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
19774 | A p\bpo\bol\bll\bl() system call appeared in AT&T System V Release 3 UNIX. The |
19775 | p\bpp\bpo\bol\bll\bl() function appeared in OpenBSD 5.4. |
19776 | |
19777 | B\bBU\bUG\bGS\bS |
19778 | The POLLWRBAND flag is accepted but ignored by the kernel. |
19779 | |
19780 | Because OpenBSD does not implement STREAMS, there is no distinction |
19781 | between some of the fields in the _\be_\bv_\be_\bn_\bt_\bs and _\br_\be_\bv_\be_\bn_\bt_\bs bitmasks. As a |
19782 | result, the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent. |
19783 | |
19784 | Internally to the kernel, p\bpo\bol\bll\bl() and p\bpp\bpo\bol\bll\bl() work poorly if multiple |
19785 | processes wait on the same file descriptor. |
19786 | |
19787 | N\bNA\bAM\bME\bE |
19788 | r\bre\bea\bad\bd, r\bre\bea\bad\bdv\bv, p\bpr\bre\bea\bad\bd, p\bpr\bre\bea\bad\bdv\bv - read input |
19789 | |
19790 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
19791 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
19792 | |
19793 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
19794 | r\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
19795 | |
19796 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
19797 | p\bpr\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
19798 | |
19799 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
19800 | |
19801 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
19802 | r\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
19803 | |
19804 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
19805 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
19806 | |
19807 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
19808 | p\bpr\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
19809 | |
19810 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
19811 | r\bre\bea\bad\bd() attempts to read _\bn_\bb_\by_\bt_\be_\bs of data from the object referenced by the |
19812 | descriptor _\bd into the buffer pointed to by _\bb_\bu_\bf. r\bre\bea\bad\bdv\bv() performs the |
19813 | same action, but scatters the input data into the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
19814 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
19815 | iov[iovcnt-1]. p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() perform the same functions, but read |
19816 | from the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the file |
19817 | pointer. |
19818 | |
19819 | For r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
19820 | |
19821 | struct iovec { |
19822 | void *iov_base; |
19823 | size_t iov_len; |
19824 | }; |
19825 | |
19826 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
19827 | memory where data should be placed. r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will always |
19828 | fill an area completely before proceeding to the next. |
19829 | |
19830 | On objects capable of seeking, the r\bre\bea\bad\bd() starts at a position given by |
19831 | the pointer associated with _\bd (see lseek(2)). Upon return from r\bre\bea\bad\bd(), |
19832 | the pointer is incremented by the number of bytes actually read. |
19833 | |
19834 | Objects that are not capable of seeking always read from the current |
19835 | position. The value of the pointer associated with such an object is |
19836 | undefined. |
19837 | |
19838 | Upon successful completion, r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() return |
19839 | the number of bytes actually read and placed in the buffer. The system |
19840 | guarantees to read the number of bytes requested if the descriptor |
19841 | references a normal file that has that many bytes left before the end-of- |
19842 | file, but in no other case. |
19843 | |
19844 | Note that r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
19845 | the constant IOV_MAX. |
19846 | |
19847 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
19848 | If successful, the number of bytes actually read is returned. Upon |
19849 | reading end-of-file, zero is returned. Otherwise, a -1 is returned and |
19850 | the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
19851 | |
19852 | E\bER\bRR\bRO\bOR\bRS\bS |
19853 | r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() will succeed unless: |
19854 | |
19855 | [EBADF] _\bd is not a valid file or socket descriptor open for |
19856 | reading. |
19857 | |
19858 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
19859 | address space. |
19860 | |
19861 | [EIO] An I/O error occurred while reading from the file |
19862 | system. |
19863 | |
19864 | [EINTR] A read from a slow device (i.e. one that might block |
19865 | for an arbitrary amount of time) was interrupted by |
19866 | the delivery of a signal before any data arrived. |
19867 | |
19868 | In addition, r\bre\bea\bad\bd() and r\bre\bea\bad\bdv\bv() may return the following errors: |
19869 | |
19870 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
19871 | were ready to be read. |
19872 | |
19873 | [ENOTCONN] The file is a socket associated with a connection- |
19874 | oriented protocol and has not been connected. |
19875 | |
19876 | [EIO] The process is a member of a background process |
19877 | attempting to read from its controlling terminal, the |
19878 | process is ignoring or blocking the SIGTTIN signal or |
19879 | the process group is orphaned. |
19880 | |
19881 | r\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bd() may return the following error: |
19882 | |
19883 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
19884 | |
19885 | p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() may return the following errors: |
19886 | |
19887 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
19888 | |
19889 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
19890 | |
19891 | r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() may return one of the following errors: |
19892 | |
19893 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
19894 | IOV_MAX. |
19895 | |
19896 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
19897 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
19898 | |
19899 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
19900 | address space. |
19901 | |
19902 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
19903 | dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), |
19904 | socketpair(2) |
19905 | |
19906 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
19907 | The r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), and p\bpr\bre\bea\bad\bd() functions conform to IEEE Std |
19908 | 1003.1-2008 (``POSIX.1''). |
19909 | |
19910 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
19911 | A r\bre\bea\bad\bd() system call first appeared in Version 1 AT&T UNIX; r\bre\bea\bad\bdv\bv() in |
19912 | 4.1cBSD; p\bpr\bre\bea\bad\bd() in AT&T System V Release 4 UNIX; and p\bpr\bre\bea\bad\bdv\bv() in |
19913 | OpenBSD 2.7. |
19914 | |
19915 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
19916 | Error checks should explicitly test for -1. Code such as |
19917 | |
19918 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
19919 | |
19920 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
19921 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
19922 | error-free r\bre\bea\bad\bd() may appear as a negative number distinct from -1. |
19923 | Proper loops should use |
19924 | |
19925 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
19926 | |
19927 | N\bNA\bAM\bME\bE |
19928 | r\bre\bea\bad\bd, r\bre\bea\bad\bdv\bv, p\bpr\bre\bea\bad\bd, p\bpr\bre\bea\bad\bdv\bv - read input |
19929 | |
19930 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
19931 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
19932 | |
19933 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
19934 | r\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
19935 | |
19936 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
19937 | p\bpr\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
19938 | |
19939 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
19940 | |
19941 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
19942 | r\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
19943 | |
19944 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
19945 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
19946 | |
19947 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
19948 | p\bpr\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
19949 | |
19950 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
19951 | r\bre\bea\bad\bd() attempts to read _\bn_\bb_\by_\bt_\be_\bs of data from the object referenced by the |
19952 | descriptor _\bd into the buffer pointed to by _\bb_\bu_\bf. r\bre\bea\bad\bdv\bv() performs the |
19953 | same action, but scatters the input data into the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
19954 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
19955 | iov[iovcnt-1]. p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() perform the same functions, but read |
19956 | from the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the file |
19957 | pointer. |
19958 | |
19959 | For r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
19960 | |
19961 | struct iovec { |
19962 | void *iov_base; |
19963 | size_t iov_len; |
19964 | }; |
19965 | |
19966 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
19967 | memory where data should be placed. r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will always |
19968 | fill an area completely before proceeding to the next. |
19969 | |
19970 | On objects capable of seeking, the r\bre\bea\bad\bd() starts at a position given by |
19971 | the pointer associated with _\bd (see lseek(2)). Upon return from r\bre\bea\bad\bd(), |
19972 | the pointer is incremented by the number of bytes actually read. |
19973 | |
19974 | Objects that are not capable of seeking always read from the current |
19975 | position. The value of the pointer associated with such an object is |
19976 | undefined. |
19977 | |
19978 | Upon successful completion, r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() return |
19979 | the number of bytes actually read and placed in the buffer. The system |
19980 | guarantees to read the number of bytes requested if the descriptor |
19981 | references a normal file that has that many bytes left before the end-of- |
19982 | file, but in no other case. |
19983 | |
19984 | Note that r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
19985 | the constant IOV_MAX. |
19986 | |
19987 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
19988 | If successful, the number of bytes actually read is returned. Upon |
19989 | reading end-of-file, zero is returned. Otherwise, a -1 is returned and |
19990 | the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
19991 | |
19992 | E\bER\bRR\bRO\bOR\bRS\bS |
19993 | r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() will succeed unless: |
19994 | |
19995 | [EBADF] _\bd is not a valid file or socket descriptor open for |
19996 | reading. |
19997 | |
19998 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
19999 | address space. |
20000 | |
20001 | [EIO] An I/O error occurred while reading from the file |
20002 | system. |
20003 | |
20004 | [EINTR] A read from a slow device (i.e. one that might block |
20005 | for an arbitrary amount of time) was interrupted by |
20006 | the delivery of a signal before any data arrived. |
20007 | |
20008 | In addition, r\bre\bea\bad\bd() and r\bre\bea\bad\bdv\bv() may return the following errors: |
20009 | |
20010 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
20011 | were ready to be read. |
20012 | |
20013 | [ENOTCONN] The file is a socket associated with a connection- |
20014 | oriented protocol and has not been connected. |
20015 | |
20016 | [EIO] The process is a member of a background process |
20017 | attempting to read from its controlling terminal, the |
20018 | process is ignoring or blocking the SIGTTIN signal or |
20019 | the process group is orphaned. |
20020 | |
20021 | r\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bd() may return the following error: |
20022 | |
20023 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
20024 | |
20025 | p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() may return the following errors: |
20026 | |
20027 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
20028 | |
20029 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
20030 | |
20031 | r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() may return one of the following errors: |
20032 | |
20033 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
20034 | IOV_MAX. |
20035 | |
20036 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
20037 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
20038 | |
20039 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
20040 | address space. |
20041 | |
20042 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
20043 | dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), |
20044 | socketpair(2) |
20045 | |
20046 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
20047 | The r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), and p\bpr\bre\bea\bad\bd() functions conform to IEEE Std |
20048 | 1003.1-2008 (``POSIX.1''). |
20049 | |
20050 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
20051 | A r\bre\bea\bad\bd() system call first appeared in Version 1 AT&T UNIX; r\bre\bea\bad\bdv\bv() in |
20052 | 4.1cBSD; p\bpr\bre\bea\bad\bd() in AT&T System V Release 4 UNIX; and p\bpr\bre\bea\bad\bdv\bv() in |
20053 | OpenBSD 2.7. |
20054 | |
20055 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
20056 | Error checks should explicitly test for -1. Code such as |
20057 | |
20058 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
20059 | |
20060 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
20061 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
20062 | error-free r\bre\bea\bad\bd() may appear as a negative number distinct from -1. |
20063 | Proper loops should use |
20064 | |
20065 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
20066 | |
20067 | N\bNA\bAM\bME\bE |
20068 | p\bpr\bro\bof\bfi\bil\bl - control process profiling |
20069 | |
20070 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
20071 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
20072 | |
20073 | _\bi_\bn_\bt |
20074 | p\bpr\bro\bof\bfi\bil\bl(_\bc_\bh_\ba_\br _\b*_\bs_\ba_\bm_\bp_\bl_\be_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bs_\bi_\bz_\be, _\bu_\b__\bl_\bo_\bn_\bg _\bo_\bf_\bf_\bs_\be_\bt, _\bu_\b__\bi_\bn_\bt _\bs_\bc_\ba_\bl_\be); |
20075 | |
20076 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
20077 | The p\bpr\bro\bof\bfi\bil\bl() function enables or disables program counter profiling of |
20078 | the current process. If profiling is enabled, then at every clock tick, |
20079 | the kernel updates an appropriate count in the _\bs_\ba_\bm_\bp_\bl_\be_\bs buffer. |
20080 | |
20081 | The buffer _\bs_\ba_\bm_\bp_\bl_\be_\bs contains _\bs_\bi_\bz_\be bytes and is divided into a series of |
20082 | 16-bit bins. Each bin counts the number of times the program counter was |
20083 | in a particular address range in the process when a clock tick occurred |
20084 | while profiling was enabled. For a given program counter address, the |
20085 | number of the corresponding bin is given by the relation: |
20086 | |
20087 | [(pc - offset) / 2] * scale / 65536 |
20088 | |
20089 | The _\bo_\bf_\bf_\bs_\be_\bt parameter is the lowest address at which the kernel takes |
20090 | program counter samples. The _\bs_\bc_\ba_\bl_\be parameter ranges from 1 to 65536 and |
20091 | can be used to change the span of the bins. A scale of 65536 maps each |
20092 | bin to 2 bytes of address range; a scale of 32768 gives 4 bytes, 16384 |
20093 | gives 8 bytes and so on. Intermediate values provide approximate |
20094 | intermediate ranges. A _\bs_\bc_\ba_\bl_\be value of 0 disables profiling. |
20095 | |
20096 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
20097 | If the _\bs_\bc_\ba_\bl_\be value is nonzero and the buffer _\bs_\ba_\bm_\bp_\bl_\be_\bs contains an illegal |
20098 | address, p\bpr\bro\bof\bfi\bil\bl() returns -1, profiling is terminated, and _\be_\br_\br_\bn_\bo is set |
20099 | appropriately. Otherwise, p\bpr\bro\bof\bfi\bil\bl() returns 0. |
20100 | |
20101 | F\bFI\bIL\bLE\bES\bS |
20102 | _\b/_\bu_\bs_\br_\b/_\bl_\bi_\bb_\b/_\bg_\bc_\br_\bt_\b0_\b._\bo profiling C run-time startup file |
20103 | _\bg_\bm_\bo_\bn_\b._\bo_\bu_\bt conventional name for profiling output file |
20104 | |
20105 | E\bER\bRR\bRO\bOR\bRS\bS |
20106 | The following error may be reported: |
20107 | |
20108 | [EFAULT] The buffer _\bs_\ba_\bm_\bp_\bl_\be_\bs contains an invalid address. |
20109 | |
20110 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
20111 | gprof(1) |
20112 | |
20113 | B\bBU\bUG\bGS\bS |
20114 | This routine should be named p\bpr\bro\bof\bfi\bil\ble\be(). |
20115 | |
20116 | The _\bs_\ba_\bm_\bp_\bl_\be_\bs argument should really be a vector of type _\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\bs_\bh_\bo_\br_\bt. |
20117 | |
20118 | The format of the gmon.out file is undocumented. |
20119 | |
20120 | N\bNA\bAM\bME\bE |
20121 | s\bse\bel\ble\bec\bct\bt, p\bps\bse\bel\ble\bec\bct\bt - synchronous I/O multiplexing |
20122 | |
20123 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
20124 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bel\ble\bec\bct\bt.\b.h\bh>\b> |
20125 | |
20126 | _\bi_\bn_\bt |
20127 | s\bse\bel\ble\bec\bct\bt(_\bi_\bn_\bt _\bn_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\br_\be_\ba_\bd_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs, |
20128 | _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
20129 | |
20130 | _\bi_\bn_\bt |
20131 | p\bps\bse\bel\ble\bec\bct\bt(_\bi_\bn_\bt _\bn_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\br_\be_\ba_\bd_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs, |
20132 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bm_\ba_\bs_\bk); |
20133 | |
20134 | F\bFD\bD_\b_S\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
20135 | |
20136 | F\bFD\bD_\b_C\bCL\bLR\bR(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
20137 | |
20138 | F\bFD\bD_\b_I\bIS\bSS\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
20139 | |
20140 | F\bFD\bD_\b_Z\bZE\bER\bRO\bO(_\b&_\bf_\bd_\bs_\be_\bt); |
20141 | |
20142 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
20143 | s\bse\bel\ble\bec\bct\bt() examines the I/O descriptor sets whose addresses are passed in |
20144 | _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, and _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs to see if some of their descriptors are |
20145 | ready for reading, are ready for writing, or have an exceptional |
20146 | condition pending, respectively. The first _\bn_\bf_\bd_\bs descriptors are checked |
20147 | in each set; i.e., the descriptors from 0 through _\bn_\bf_\bd_\bs-1 in the |
20148 | descriptor sets are examined. On return, s\bse\bel\ble\bec\bct\bt() replaces the given |
20149 | descriptor sets with subsets consisting of those descriptors that are |
20150 | ready for the requested operation. s\bse\bel\ble\bec\bct\bt() returns the total number of |
20151 | ready descriptors in all the sets. |
20152 | |
20153 | The descriptor sets are stored as bit fields in arrays of integers. The |
20154 | following macros are provided for manipulating such descriptor sets: |
20155 | F\bFD\bD_\b_Z\bZE\bER\bRO\bO(_\b&_\bf_\bd_\bs_\be_\bt) initializes a descriptor set _\bf_\bd_\bs_\be_\bt to the null set. |
20156 | F\bFD\bD_\b_S\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) includes a particular descriptor _\bf_\bd in _\bf_\bd_\bs_\be_\bt. |
20157 | F\bFD\bD_\b_C\bCL\bLR\bR(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) removes _\bf_\bd from _\bf_\bd_\bs_\be_\bt. F\bFD\bD_\b_I\bIS\bSS\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) is non- |
20158 | zero if _\bf_\bd is a member of _\bf_\bd_\bs_\be_\bt, zero otherwise. The behavior of these |
20159 | macros is undefined if a descriptor value is less than zero or greater |
20160 | than or equal to FD_SETSIZE, which is normally at least equal to the |
20161 | maximum number of descriptors supported by the system. |
20162 | |
20163 | If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it specifies a maximum interval to wait |
20164 | for the selection to complete. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, the select |
20165 | blocks indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
20166 | non-null, pointing to a zero-valued timeval structure. _\bt_\bi_\bm_\be_\bo_\bu_\bt is not |
20167 | changed by s\bse\bel\ble\bec\bct\bt(), and may be reused on subsequent calls; however, it |
20168 | is good style to re-initialize it before each invocation of s\bse\bel\ble\bec\bct\bt(). |
20169 | |
20170 | Any of _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, and _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs may be given as null pointers if |
20171 | no descriptors are of interest. |
20172 | |
20173 | The p\bps\bse\bel\ble\bec\bct\bt() function is similar to s\bse\bel\ble\bec\bct\bt() except that it specifies |
20174 | the timeout using a timespec structure. Also, if _\bm_\ba_\bs_\bk is a non-null |
20175 | pointer, p\bps\bse\bel\ble\bec\bct\bt() atomically sets the calling thread's signal mask to |
20176 | the signal set pointed to by _\bm_\ba_\bs_\bk for the duration of the function call. |
20177 | In this case, the original signal mask will be restored before p\bps\bse\bel\ble\bec\bct\bt() |
20178 | returns. |
20179 | |
20180 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
20181 | If successful, s\bse\bel\ble\bec\bct\bt() and p\bps\bse\bel\ble\bec\bct\bt() return the number of ready |
20182 | descriptors that are contained in the descriptor sets. If a descriptor |
20183 | is included in multiple descriptor sets, each inclusion is counted |
20184 | separately. If the time limit expires before any descriptors become |
20185 | ready, they return 0. |
20186 | |
20187 | Otherwise, if s\bse\bel\ble\bec\bct\bt() or p\bps\bse\bel\ble\bec\bct\bt() return with an error, including one |
20188 | due to an interrupted call, they return -1, and the descriptor sets will |
20189 | be unmodified. |
20190 | |
20191 | E\bER\bRR\bRO\bOR\bRS\bS |
20192 | An error return from s\bse\bel\ble\bec\bct\bt() or p\bps\bse\bel\ble\bec\bct\bt() indicates: |
20193 | |
20194 | [EFAULT] One or more of _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, or _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs points |
20195 | outside the process's allocated address space. |
20196 | |
20197 | [EBADF] One of the descriptor sets specified an invalid |
20198 | descriptor. |
20199 | |
20200 | [EINTR] A signal was delivered before the time limit expired |
20201 | and before any of the selected descriptors became |
20202 | ready. |
20203 | |
20204 | [EINVAL] The specified time limit is invalid. One of its |
20205 | components is negative or too large. |
20206 | |
20207 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
20208 | accept(2), clock_gettime(2), connect(2), gettimeofday(2), poll(2), |
20209 | read(2), recv(2), send(2), write(2), getdtablesize(3) |
20210 | |
20211 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
20212 | The s\bse\bel\ble\bec\bct\bt() system call first appeared in 4.1cBSD. The p\bps\bse\bel\ble\bec\bct\bt() system |
20213 | call has been available since OpenBSD 5.4. |
20214 | |
20215 | B\bBU\bUG\bGS\bS |
20216 | Although the provision of getdtablesize(3) was intended to allow user |
20217 | programs to be written independent of the kernel limit on the number of |
20218 | open files, the dimension of a sufficiently large bit field for select |
20219 | remains a problem. The default bit size of _\bf_\bd_\b__\bs_\be_\bt is based on the symbol |
20220 | FD_SETSIZE (currently 1024), but that is somewhat smaller than the |
20221 | current kernel limit to the number of open files. However, in order to |
20222 | accommodate programs which might potentially use a larger number of open |
20223 | files with select, it is possible to increase this size within a program |
20224 | by providing a larger definition of FD_SETSIZE before the inclusion of |
20225 | any headers. The kernel will cope, and the userland libraries provided |
20226 | with the system are also ready for large numbers of file descriptors. |
20227 | |
20228 | Alternatively, to be really safe, it is possible to allocate _\bf_\bd_\b__\bs_\be_\bt bit- |
20229 | arrays dynamically. The idea is to permit a program to work properly |
20230 | even if it is execve(2)'d with 4000 file descriptors pre-allocated. The |
20231 | following illustrates the technique which is used by userland libraries: |
20232 | |
20233 | fd_set *fdsr; |
20234 | int max = fd; |
20235 | |
20236 | fdsr = calloc(howmany(max+1, NFDBITS), sizeof(fd_mask)); |
20237 | if (fdsr == NULL) { |
20238 | ... |
20239 | return (-1); |
20240 | } |
20241 | FD_SET(fd, fdsr); |
20242 | n = select(max+1, fdsr, NULL, NULL, &tv); |
20243 | ... |
20244 | free(fdsr); |
20245 | |
20246 | Alternatively, it is possible to use the poll(2) interface. poll(2) is |
20247 | more efficient when the size of s\bse\bel\ble\bec\bct\bt()'s _\bf_\bd_\b__\bs_\be_\bt bit-arrays are very |
20248 | large, and for fixed numbers of file descriptors one need not size and |
20249 | dynamically allocate a memory object. |
20250 | |
20251 | s\bse\bel\ble\bec\bct\bt() should probably have been designed to return the time remaining |
20252 | from the original timeout, if any, by modifying the time value in place. |
20253 | Even though some systems stupidly act in this different way, it is |
20254 | unlikely this semantic will ever be commonly implemented, as the change |
20255 | causes massive source code compatibility problems. Furthermore, recent |
20256 | new standards have dictated the current behaviour. In general, due to |
20257 | the existence of those brain-damaged non-conforming systems, it is unwise |
20258 | to assume that the timeout value will be unmodified by the s\bse\bel\ble\bec\bct\bt() call, |
20259 | and the caller should reinitialize it on each invocation. Calculating |
20260 | the delta is easily done by calling gettimeofday(2) before and after the |
20261 | call to s\bse\bel\ble\bec\bct\bt(), and using t\bti\bim\bme\ber\brs\bsu\bub\bb() (as described in getitimer(2)). |
20262 | |
20263 | Internally to the kernel, s\bse\bel\ble\bec\bct\bt() and p\bps\bse\bel\ble\bec\bct\bt() work poorly if multiple |
20264 | processes wait on the same file descriptor. Given that, it is rather |
20265 | surprising to see that many daemons are written that way. |
20266 | |
20267 | N\bNA\bAM\bME\bE |
20268 | p\bpt\btr\bra\bac\bce\be - process tracing and debugging |
20269 | |
20270 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
20271 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
20272 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpt\btr\bra\bac\bce\be.\b.h\bh>\b> |
20273 | |
20274 | _\bi_\bn_\bt |
20275 | p\bpt\btr\bra\bac\bce\be(_\bi_\bn_\bt _\br_\be_\bq_\bu_\be_\bs_\bt, _\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bc_\ba_\bd_\bd_\br_\b__\bt _\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bd_\ba_\bt_\ba); |
20276 | |
20277 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
20278 | p\bpt\btr\bra\bac\bce\be() provides tracing and debugging facilities. It allows one |
20279 | process (the _\bt_\br_\ba_\bc_\bi_\bn_\bg process) to control another (the _\bt_\br_\ba_\bc_\be_\bd process). |
20280 | Most of the time, the traced process runs normally, but when it receives |
20281 | a signal (see sigaction(2)), it stops. The tracing process is expected |
20282 | to notice this via wait(2) or the delivery of a SIGCHLD signal, examine |
20283 | the state of the stopped process, and cause it to terminate or continue |
20284 | as appropriate. p\bpt\btr\bra\bac\bce\be() is the mechanism by which all this happens. |
20285 | p\bpt\btr\bra\bac\bce\be() is only available on kernels compiled with the P\bPT\bTR\bRA\bAC\bCE\bE option. |
20286 | |
20287 | The _\br_\be_\bq_\bu_\be_\bs_\bt argument specifies what operation is being performed; the |
20288 | meaning of the rest of the arguments depends on the operation, but except |
20289 | for one special case noted below, all p\bpt\btr\bra\bac\bce\be() calls are made by the |
20290 | tracing process, and the _\bp_\bi_\bd argument specifies the process ID of the |
20291 | traced process. _\br_\be_\bq_\bu_\be_\bs_\bt can be: |
20292 | |
20293 | PT_TRACE_ME This request is the only one used by the traced process; it |
20294 | declares that the process expects to be traced by its |
20295 | parent. All the other arguments are ignored. (If the |
20296 | parent process does not expect to trace the child, it will |
20297 | probably be rather confused by the results; once the traced |
20298 | process stops, it cannot be made to continue except via |
20299 | p\bpt\btr\bra\bac\bce\be().) When a process has used this request and calls |
20300 | execve(2) or any of the routines built on it (such as |
20301 | execv(3)), it will stop before executing the first |
20302 | instruction of the new image. Also, any setuid or setgid |
20303 | bits on the executable being executed will be ignored. |
20304 | |
20305 | PT_READ_I, PT_READ_D |
20306 | These requests read a single int of data from the traced |
20307 | process' address space. Traditionally, p\bpt\btr\bra\bac\bce\be() has |
20308 | allowed for machines with distinct address spaces for |
20309 | instruction and data, which is why there are two requests: |
20310 | conceptually, PT_READ_I reads from the instruction space |
20311 | and PT_READ_D reads from the data space. In the current |
20312 | OpenBSD implementation, these two requests are completely |
20313 | identical. The _\ba_\bd_\bd_\br argument specifies the address (in the |
20314 | traced process' virtual address space) at which the read is |
20315 | to be done. This address does not have to meet any |
20316 | alignment constraints. The value read is returned as the |
20317 | return value from p\bpt\btr\bra\bac\bce\be(). |
20318 | |
20319 | PT_WRITE_I, PT_WRITE_D |
20320 | These requests parallel PT_READ_I and PT_READ_D, except |
20321 | that they write rather than read. The _\bd_\ba_\bt_\ba argument |
20322 | supplies the value to be written. |
20323 | |
20324 | PT_CONTINUE The traced process continues execution. _\ba_\bd_\bd_\br is an address |
20325 | specifying the place where execution is to be resumed (a |
20326 | new value for the program counter), or (caddr_t)1 to |
20327 | indicate that execution is to pick up where it left off. |
20328 | _\bd_\ba_\bt_\ba provides a signal number to be delivered to the traced |
20329 | process as it resumes execution, or 0 if no signal is to be |
20330 | sent. |
20331 | |
20332 | PT_KILL The traced process terminates, as if PT_CONTINUE had been |
20333 | used with SIGKILL given as the signal to be delivered. |
20334 | |
20335 | PT_ATTACH This request allows a process to gain control of an |
20336 | otherwise unrelated process and begin tracing it. It does |
20337 | not need any cooperation from the to-be-traced process. In |
20338 | this case, _\bp_\bi_\bd specifies the process ID of the to-be-traced |
20339 | process, and the other two arguments are ignored. This |
20340 | request requires that the target process must have the same |
20341 | real UID as the tracing process, and that it must not be |
20342 | executing a set-user-ID or set-group-ID executable. |
20343 | Additionally, if the kern.global_ptrace sysctl is 0, then |
20344 | the target process must be a descendent of the tracing |
20345 | process. (If the tracing process is running as root, these |
20346 | restrictions do not apply.) The tracing process will see |
20347 | the newly traced process stop and may then control it as if |
20348 | it had been traced all along. |
20349 | |
20350 | PT_DETACH This request is like PT_CONTINUE, except that it does not |
20351 | allow specifying an alternate place to continue execution, |
20352 | and after it succeeds, the traced process is no longer |
20353 | traced and continues execution normally. |
20354 | |
20355 | PT_IO This request is a more general interface that can be used |
20356 | instead of PT_READ_D, PT_WRITE_D, PT_READ_I and PT_WRITE_I. |
20357 | The I/O request is encoded in a ``struct ptrace_io_desc'' |
20358 | defined as: |
20359 | |
20360 | struct ptrace_io_desc { |
20361 | int piod_op; |
20362 | void *piod_offs; |
20363 | void *piod_addr; |
20364 | size_t piod_len; |
20365 | }; |
20366 | |
20367 | Where _\bp_\bi_\bo_\bd_\b__\bo_\bf_\bf_\bs is the offset within the traced process |
20368 | where the I/O operation should be made, _\bp_\bi_\bo_\bd_\b__\ba_\bd_\bd_\br is the |
20369 | buffer in the parent and _\bp_\bi_\bo_\bd_\b__\bl_\be_\bn is the length of the I/O |
20370 | request. The _\bp_\bi_\bo_\bd_\b__\bo_\bp member specifies what operation needs |
20371 | to be done. Possible values are: |
20372 | |
20373 | PIOD_READ_D |
20374 | PIOD_WRITE_D |
20375 | PIOD_READ_I |
20376 | PIOD_WRITE_I |
20377 | PIOD_READ_AUXV |
20378 | |
20379 | See also the description of PT_READ_I for the difference |
20380 | between D and I spaces. The PIOD_READ_AUXV operation can |
20381 | be used to read from the ELF auxiliary vector. A pointer |
20382 | to the descriptor is passed in _\ba_\bd_\bd_\br. On return the |
20383 | _\bp_\bi_\bo_\bd_\b__\bl_\be_\bn field in the descriptor will be updated with the |
20384 | actual number of bytes transferred. If the requested I/O |
20385 | couldn't be successfully performed p\bpt\btr\bra\bac\bce\be() will return -1 |
20386 | and set _\be_\br_\br_\bn_\bo. |
20387 | |
20388 | PT_SET_EVENT_MASK |
20389 | This request can be used to specify which events in the |
20390 | traced process should be reported to the tracing process. |
20391 | These events are specified in a ``struct ptrace_event'' |
20392 | defined as: |
20393 | |
20394 | typedef struct ptrace_event { |
20395 | int pe_set_event; |
20396 | } ptrace_event_t; |
20397 | |
20398 | Where _\bp_\be_\b__\bs_\be_\bt_\b__\be_\bv_\be_\bn_\bt is the set of events to be reported. |
20399 | This set is formed by OR'ing together the following values: |
20400 | |
20401 | PTRACE_FORK Report fork(2). |
20402 | |
20403 | A pointer to this structure is passed in _\ba_\bd_\bd_\br. The _\bd_\ba_\bt_\ba |
20404 | argument should be set to sizeof(struct ptrace_event). |
20405 | |
20406 | PT_GET_EVENT_MASK |
20407 | This request can be used to determine which events in the |
20408 | traced process will be reported. The information is read |
20409 | into the ``struct ptrace_event'' pointed to by _\ba_\bd_\bd_\br. The |
20410 | _\bd_\ba_\bt_\ba argument should be set to sizeof(struct ptrace_event). |
20411 | |
20412 | PT_GET_PROCESS_STATE |
20413 | This request reads the state information associated with |
20414 | the event that stopped the traced process. The information |
20415 | is reported in a ``struct ptrace_state'' defined as: |
20416 | |
20417 | typedef struct ptrace_state { |
20418 | int pe_report_event; |
20419 | pid_t pe_other_pid; |
20420 | } ptrace_state_t; |
20421 | |
20422 | Where _\bp_\be_\b__\br_\be_\bp_\bo_\br_\bt_\b__\be_\bv_\be_\bn_\bt is the event being reported. If the |
20423 | event being reported is PTRACE_FORK, _\bp_\be_\b__\bo_\bt_\bh_\be_\br_\b__\bp_\bi_\bd will be |
20424 | set to the process ID of the other end of the fork. A |
20425 | pointer to this structure is passed in _\ba_\bd_\bd_\br. The _\bd_\ba_\bt_\ba |
20426 | argument should be set to sizeof(struct ptrace_state). |
20427 | |
20428 | Additionally, machine-specific requests can exist. Depending on the |
20429 | architecture, the following requests may be available under OpenBSD: |
20430 | |
20431 | PT_GETREGS (all platforms) |
20432 | This request reads the traced process' machine registers |
20433 | into the ``struct reg'' (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) |
20434 | pointed to by _\ba_\bd_\bd_\br. |
20435 | |
20436 | PT_SETREGS (all platforms) |
20437 | This request is the converse of PT_GETREGS; it loads the |
20438 | traced process' machine registers from the ``struct reg'' |
20439 | (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed to by _\ba_\bd_\bd_\br. |
20440 | |
20441 | PT_STEP (not available on sparc and sparc64) |
20442 | The traced process continues execution, as in request |
20443 | PT_CONTINUE; however, execution stops as soon as possible |
20444 | after execution of at least one instruction (single-step). |
20445 | |
20446 | PT_GETFPREGS (not available on aviion, luna88k, sgi and vax) |
20447 | This request reads the traced process' floating-point |
20448 | registers into the ``struct fpreg'' (defined in |
20449 | <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed to by _\ba_\bd_\bd_\br. |
20450 | |
20451 | PT_SETFPREGS (not available on aviion, luna88k, sgi and vax) |
20452 | This request is the converse of PT_GETFPREGS; it loads the |
20453 | traced process' floating-point registers from the ``struct |
20454 | fpreg'' (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed to by _\ba_\bd_\bd_\br. |
20455 | |
20456 | PT_GETXMMREGS (i386 only) |
20457 | This request reads the traced process' XMM registers into |
20458 | the ``struct xmmregs'' (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed |
20459 | to by _\ba_\bd_\bd_\br. |
20460 | |
20461 | PT_SETXMMREGS (i386 only) |
20462 | This request is the converse of PT_GETXMMREGS; it loads the |
20463 | traced process' XMM registers from the ``struct xmmregs'' |
20464 | (defined in <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\br_\be_\bg_\b._\bh>) pointed to by _\ba_\bd_\bd_\br. |
20465 | |
20466 | PT_WCOOKIE (sparc and sparc64 only) |
20467 | This request reads the traced process' `window cookie' into |
20468 | the int pointed to by _\ba_\bd_\bd_\br. The window cookie needs to be |
20469 | `XOR'ed' to stack-saved program counters. |
20470 | |
20471 | E\bER\bRR\bRO\bOR\bRS\bS |
20472 | Some requests can cause p\bpt\btr\bra\bac\bce\be() to return -1 as a non-error value; to |
20473 | disambiguate, _\be_\br_\br_\bn_\bo is set to zero and this should be checked. The |
20474 | possible errors are: |
20475 | |
20476 | [ESRCH] |
20477 | No process having the specified process ID exists. |
20478 | |
20479 | [EINVAL] |
20480 | +\b+\bo\bo A process attempted to use PT_ATTACH on itself. |
20481 | +\b+\bo\bo The _\br_\be_\bq_\bu_\be_\bs_\bt was not one of the legal requests. |
20482 | +\b+\bo\bo The signal number (in _\bd_\ba_\bt_\ba) to PT_CONTINUE was neither 0 nor a |
20483 | legal signal number. |
20484 | +\b+\bo\bo PT_GETREGS, PT_SETREGS, PT_GETFPREGS, or PT_SETFPREGS was |
20485 | attempted on a process with no valid register set. (This is |
20486 | normally true only of system processes.) |
20487 | |
20488 | [EBUSY] |
20489 | +\b+\bo\bo PT_ATTACH was attempted on a process that was already being |
20490 | traced. |
20491 | +\b+\bo\bo A request attempted to manipulate a process that was being |
20492 | traced by some process other than the one making the request. |
20493 | +\b+\bo\bo A request (other than PT_ATTACH) specified a process that |
20494 | wasn't stopped. |
20495 | |
20496 | [EPERM] |
20497 | +\b+\bo\bo A request (other than PT_ATTACH) attempted to manipulate a |
20498 | process that wasn't being traced at all. |
20499 | +\b+\bo\bo An attempt was made to use PT_ATTACH on a process in violation |
20500 | of the requirements listed under PT_ATTACH above. |
20501 | +\b+\bo\bo An attempt was made to use PT_ATTACH on a system process. |
20502 | |
20503 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
20504 | The p\bpt\btr\bra\bac\bce\be() system call first appeared in Version 6 AT&T UNIX. |
20505 | |
20506 | B\bBU\bUG\bGS\bS |
20507 | On several RISC architectures (such as aviion, luna88k, sparc and |
20508 | sparc64), the PC is set to the provided PC value for PT_CONTINUE and |
20509 | similar calls, and the remainder of the execution pipeline registers are |
20510 | set to the following instructions, even if the instruction at PC is a |
20511 | branch instruction. Using PT_GETREGS and PT_SETREGS to modify the PC, |
20512 | passing (caddr_t)1 to p\bpt\btr\bra\bac\bce\be(), should be able to sidestep this. |
20513 | |
20514 | N\bNA\bAM\bME\bE |
20515 | w\bwr\bri\bit\bte\be, w\bwr\bri\bit\bte\bev\bv, p\bpw\bwr\bri\bit\bte\be, p\bpw\bwr\bri\bit\bte\bev\bv - write output |
20516 | |
20517 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
20518 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
20519 | |
20520 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20521 | w\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
20522 | |
20523 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20524 | p\bpw\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
20525 | |
20526 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
20527 | |
20528 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20529 | w\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
20530 | |
20531 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
20532 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
20533 | |
20534 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20535 | p\bpw\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
20536 | |
20537 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
20538 | w\bwr\bri\bit\bte\be() attempts to write _\bn_\bb_\by_\bt_\be_\bs of data to the object referenced by the |
20539 | descriptor _\bd from the buffer pointed to by _\bb_\bu_\bf. w\bwr\bri\bit\bte\bev\bv() performs the |
20540 | same action, but gathers the output data from the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
20541 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
20542 | iov[iovcnt-1]. p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() perform the same functions, but |
20543 | write to the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the |
20544 | file pointer. |
20545 | |
20546 | For w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
20547 | |
20548 | struct iovec { |
20549 | void *iov_base; |
20550 | size_t iov_len; |
20551 | }; |
20552 | |
20553 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
20554 | memory from which data should be written. w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will |
20555 | always write a complete area before proceeding to the next. |
20556 | |
20557 | On objects capable of seeking, the w\bwr\bri\bit\bte\be() starts at a position given by |
20558 | the pointer associated with _\bd (see lseek(2)). Upon return from w\bwr\bri\bit\bte\be(), |
20559 | the pointer is incremented by the number of bytes which were written. If |
20560 | a file was opened with the O_APPEND flag (see open(2)), calls to w\bwr\bri\bit\bte\be() |
20561 | or w\bwr\bri\bit\bte\bev\bv() will automatically set the pointer to the end of the file |
20562 | before writing. |
20563 | |
20564 | Objects that are not capable of seeking always write from the current |
20565 | position. The value of the pointer associated with such an object is |
20566 | undefined. |
20567 | |
20568 | If the real user is not the superuser, then w\bwr\bri\bit\bte\be() clears the set-user- |
20569 | ID bit on a file. This prevents penetration of system security by a user |
20570 | who ``captures'' a writable set-user-ID file owned by the superuser. |
20571 | |
20572 | If w\bwr\bri\bit\bte\be() succeeds it will update the st_ctime and st_mtime fields of |
20573 | the file's meta-data (see stat(2)). |
20574 | |
20575 | When using non-blocking I/O on objects such as sockets that are subject |
20576 | to flow control, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may write fewer bytes than |
20577 | requested; the return value must be noted, and the remainder of the |
20578 | operation should be retried when possible. |
20579 | |
20580 | Note that w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
20581 | the constant IOV_MAX. |
20582 | |
20583 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
20584 | Upon successful completion the number of bytes which were written is |
20585 | returned. Otherwise, a -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
20586 | set to indicate the error. |
20587 | |
20588 | E\bER\bRR\bRO\bOR\bRS\bS |
20589 | w\bwr\bri\bit\bte\be(), p\bpw\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\bev\bv() will fail and the file pointer |
20590 | will remain unchanged if: |
20591 | |
20592 | [EBADF] _\bd is not a valid descriptor open for writing. |
20593 | |
20594 | [EFBIG] An attempt was made to write a file that exceeds the |
20595 | process's file size limit or the maximum file size. |
20596 | |
20597 | [ENOSPC] There is no free space remaining on the file system |
20598 | containing the file. |
20599 | |
20600 | [EDQUOT] The user's quota of disk blocks on the file system |
20601 | containing the file has been exhausted. |
20602 | |
20603 | [EINTR] A write to a slow device (i.e. one that might block |
20604 | for an arbitrary amount of time) was interrupted by |
20605 | the delivery of a signal before any data could be |
20606 | written. |
20607 | |
20608 | [EIO] An I/O error occurred while reading from or writing to |
20609 | the file system. |
20610 | |
20611 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
20612 | address space. |
20613 | |
20614 | In addition, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may return the following errors: |
20615 | |
20616 | [EPIPE] An attempt is made to write to a pipe that is not open |
20617 | for reading by any process. |
20618 | |
20619 | [EPIPE] An attempt is made to write to a socket of type |
20620 | SOCK_STREAM that is not connected to a peer socket. |
20621 | |
20622 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
20623 | could be written immediately. |
20624 | |
20625 | [ENETDOWN] The destination address specified a network that is |
20626 | down. |
20627 | |
20628 | [EDESTADDRREQ] The destination is no longer available when writing to |
20629 | a UNIX-domain datagram socket on which connect(2) had |
20630 | been used to set a destination address. |
20631 | |
20632 | [EIO] The process is a member of a background process |
20633 | attempting to write to its controlling terminal, |
20634 | TOSTOP is set on the terminal, the process isn't |
20635 | ignoring the SIGTTOUT signal and the thread isn't |
20636 | blocking the SIGTTOUT signal, and either the process |
20637 | was created with vfork(2) and hasn't successfully |
20638 | executed one of the exec functions or the process |
20639 | group is orphaned. |
20640 | |
20641 | w\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\be() may return the following error: |
20642 | |
20643 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
20644 | |
20645 | p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() may return the following error: |
20646 | |
20647 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
20648 | |
20649 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
20650 | |
20651 | w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() may return one of the following errors: |
20652 | |
20653 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
20654 | IOV_MAX. |
20655 | |
20656 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
20657 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
20658 | |
20659 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
20660 | address space. |
20661 | |
20662 | [ENOBUFS] The system lacked sufficient buffer space or a queue |
20663 | was full. |
20664 | |
20665 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
20666 | fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) |
20667 | |
20668 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
20669 | The w\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\be() functions conform to IEEE Std |
20670 | 1003.1-2008 (``POSIX.1''). |
20671 | |
20672 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
20673 | The p\bpw\bwr\bri\bit\bte\bev\bv() function call appeared in OpenBSD 2.7. The p\bpw\bwr\bri\bit\bte\be() |
20674 | function call appeared in AT&T System V Release 4 UNIX. The w\bwr\bri\bit\bte\bev\bv() |
20675 | function call appeared in 4.2BSD. The w\bwr\bri\bit\bte\be() function call appeared in |
20676 | Version 2 AT&T UNIX. |
20677 | |
20678 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
20679 | Error checks should explicitly test for -1. Code such as |
20680 | |
20681 | while ((nr = write(fd, buf, sizeof(buf))) > 0) |
20682 | |
20683 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
20684 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
20685 | error-free w\bwr\bri\bit\bte\be() may appear as a negative number distinct from -1. |
20686 | Proper loops should use |
20687 | |
20688 | while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) |
20689 | |
20690 | N\bNA\bAM\bME\bE |
20691 | w\bwr\bri\bit\bte\be, w\bwr\bri\bit\bte\bev\bv, p\bpw\bwr\bri\bit\bte\be, p\bpw\bwr\bri\bit\bte\bev\bv - write output |
20692 | |
20693 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
20694 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
20695 | |
20696 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20697 | w\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
20698 | |
20699 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20700 | p\bpw\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
20701 | |
20702 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
20703 | |
20704 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20705 | w\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
20706 | |
20707 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
20708 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
20709 | |
20710 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20711 | p\bpw\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
20712 | |
20713 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
20714 | w\bwr\bri\bit\bte\be() attempts to write _\bn_\bb_\by_\bt_\be_\bs of data to the object referenced by the |
20715 | descriptor _\bd from the buffer pointed to by _\bb_\bu_\bf. w\bwr\bri\bit\bte\bev\bv() performs the |
20716 | same action, but gathers the output data from the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
20717 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
20718 | iov[iovcnt-1]. p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() perform the same functions, but |
20719 | write to the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the |
20720 | file pointer. |
20721 | |
20722 | For w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
20723 | |
20724 | struct iovec { |
20725 | void *iov_base; |
20726 | size_t iov_len; |
20727 | }; |
20728 | |
20729 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
20730 | memory from which data should be written. w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will |
20731 | always write a complete area before proceeding to the next. |
20732 | |
20733 | On objects capable of seeking, the w\bwr\bri\bit\bte\be() starts at a position given by |
20734 | the pointer associated with _\bd (see lseek(2)). Upon return from w\bwr\bri\bit\bte\be(), |
20735 | the pointer is incremented by the number of bytes which were written. If |
20736 | a file was opened with the O_APPEND flag (see open(2)), calls to w\bwr\bri\bit\bte\be() |
20737 | or w\bwr\bri\bit\bte\bev\bv() will automatically set the pointer to the end of the file |
20738 | before writing. |
20739 | |
20740 | Objects that are not capable of seeking always write from the current |
20741 | position. The value of the pointer associated with such an object is |
20742 | undefined. |
20743 | |
20744 | If the real user is not the superuser, then w\bwr\bri\bit\bte\be() clears the set-user- |
20745 | ID bit on a file. This prevents penetration of system security by a user |
20746 | who ``captures'' a writable set-user-ID file owned by the superuser. |
20747 | |
20748 | If w\bwr\bri\bit\bte\be() succeeds it will update the st_ctime and st_mtime fields of |
20749 | the file's meta-data (see stat(2)). |
20750 | |
20751 | When using non-blocking I/O on objects such as sockets that are subject |
20752 | to flow control, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may write fewer bytes than |
20753 | requested; the return value must be noted, and the remainder of the |
20754 | operation should be retried when possible. |
20755 | |
20756 | Note that w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
20757 | the constant IOV_MAX. |
20758 | |
20759 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
20760 | Upon successful completion the number of bytes which were written is |
20761 | returned. Otherwise, a -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
20762 | set to indicate the error. |
20763 | |
20764 | E\bER\bRR\bRO\bOR\bRS\bS |
20765 | w\bwr\bri\bit\bte\be(), p\bpw\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\bev\bv() will fail and the file pointer |
20766 | will remain unchanged if: |
20767 | |
20768 | [EBADF] _\bd is not a valid descriptor open for writing. |
20769 | |
20770 | [EFBIG] An attempt was made to write a file that exceeds the |
20771 | process's file size limit or the maximum file size. |
20772 | |
20773 | [ENOSPC] There is no free space remaining on the file system |
20774 | containing the file. |
20775 | |
20776 | [EDQUOT] The user's quota of disk blocks on the file system |
20777 | containing the file has been exhausted. |
20778 | |
20779 | [EINTR] A write to a slow device (i.e. one that might block |
20780 | for an arbitrary amount of time) was interrupted by |
20781 | the delivery of a signal before any data could be |
20782 | written. |
20783 | |
20784 | [EIO] An I/O error occurred while reading from or writing to |
20785 | the file system. |
20786 | |
20787 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
20788 | address space. |
20789 | |
20790 | In addition, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may return the following errors: |
20791 | |
20792 | [EPIPE] An attempt is made to write to a pipe that is not open |
20793 | for reading by any process. |
20794 | |
20795 | [EPIPE] An attempt is made to write to a socket of type |
20796 | SOCK_STREAM that is not connected to a peer socket. |
20797 | |
20798 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
20799 | could be written immediately. |
20800 | |
20801 | [ENETDOWN] The destination address specified a network that is |
20802 | down. |
20803 | |
20804 | [EDESTADDRREQ] The destination is no longer available when writing to |
20805 | a UNIX-domain datagram socket on which connect(2) had |
20806 | been used to set a destination address. |
20807 | |
20808 | [EIO] The process is a member of a background process |
20809 | attempting to write to its controlling terminal, |
20810 | TOSTOP is set on the terminal, the process isn't |
20811 | ignoring the SIGTTOUT signal and the thread isn't |
20812 | blocking the SIGTTOUT signal, and either the process |
20813 | was created with vfork(2) and hasn't successfully |
20814 | executed one of the exec functions or the process |
20815 | group is orphaned. |
20816 | |
20817 | w\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\be() may return the following error: |
20818 | |
20819 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
20820 | |
20821 | p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() may return the following error: |
20822 | |
20823 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
20824 | |
20825 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
20826 | |
20827 | w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() may return one of the following errors: |
20828 | |
20829 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
20830 | IOV_MAX. |
20831 | |
20832 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
20833 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
20834 | |
20835 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
20836 | address space. |
20837 | |
20838 | [ENOBUFS] The system lacked sufficient buffer space or a queue |
20839 | was full. |
20840 | |
20841 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
20842 | fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) |
20843 | |
20844 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
20845 | The w\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\be() functions conform to IEEE Std |
20846 | 1003.1-2008 (``POSIX.1''). |
20847 | |
20848 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
20849 | The p\bpw\bwr\bri\bit\bte\bev\bv() function call appeared in OpenBSD 2.7. The p\bpw\bwr\bri\bit\bte\be() |
20850 | function call appeared in AT&T System V Release 4 UNIX. The w\bwr\bri\bit\bte\bev\bv() |
20851 | function call appeared in 4.2BSD. The w\bwr\bri\bit\bte\be() function call appeared in |
20852 | Version 2 AT&T UNIX. |
20853 | |
20854 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
20855 | Error checks should explicitly test for -1. Code such as |
20856 | |
20857 | while ((nr = write(fd, buf, sizeof(buf))) > 0) |
20858 | |
20859 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
20860 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
20861 | error-free w\bwr\bri\bit\bte\be() may appear as a negative number distinct from -1. |
20862 | Proper loops should use |
20863 | |
20864 | while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) |
20865 | |
20866 | N\bNA\bAM\bME\bE |
20867 | q\bqu\buo\bot\bta\bac\bct\btl\bl - manipulate filesystem quotas |
20868 | |
20869 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
20870 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\buf\bfs\bs/\b/u\buf\bfs\bs/\b/q\bqu\buo\bot\bta\ba.\b.h\bh>\b> |
20871 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
20872 | |
20873 | _\bi_\bn_\bt |
20874 | q\bqu\buo\bot\bta\bac\bct\btl\bl(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bc_\bm_\bd, _\bi_\bn_\bt _\bi_\bd, _\bc_\bh_\ba_\br _\b*_\ba_\bd_\bd_\br); |
20875 | |
20876 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
20877 | The q\bqu\buo\bot\bta\bac\bct\btl\bl() call enables, disables and manipulates filesystem quotas. |
20878 | A quota control command given by _\bc_\bm_\bd operates on the given filename _\bp_\ba_\bt_\bh |
20879 | for the given user _\bi_\bd. The address of an optional command specific data |
20880 | structure, _\ba_\bd_\bd_\br, may be given; its interpretation is discussed below with |
20881 | each command. |
20882 | |
20883 | Currently quotas are supported only for the ``ffs'' filesystem. For |
20884 | ``ffs'', a command is composed of a primary command (see below) and a |
20885 | command type used to interpret the _\bi_\bd. Types are supported for |
20886 | interpretation of user identifiers and group identifiers. The ``ffs'' |
20887 | specific commands are: |
20888 | |
20889 | Q_QUOTAON Enable disk quotas for the filesystem specified by _\bp_\ba_\bt_\bh. The |
20890 | command type specifies the type of the quotas being enabled. |
20891 | The _\ba_\bd_\bd_\br argument specifies a file from which to take the |
20892 | quotas. The quota file must exist; it is normally created |
20893 | with the quotacheck(8) program. The _\bi_\bd argument is unused. |
20894 | Only the superuser may turn quotas on. |
20895 | |
20896 | Q_QUOTAOFF |
20897 | Disable disk quotas for the filesystem specified by _\bp_\ba_\bt_\bh. The |
20898 | command type specifies the type of the quotas being disabled. |
20899 | The _\ba_\bd_\bd_\br and _\bi_\bd arguments are unused. Only the superuser may |
20900 | turn quotas off. |
20901 | |
20902 | Q_GETQUOTA |
20903 | Get disk quota limits and current usage for the user or group |
20904 | (as determined by the command type) with identifier _\bi_\bd. _\ba_\bd_\bd_\br |
20905 | is a pointer to a struct dqblk structure. |
20906 | |
20907 | Q_SETQUOTA |
20908 | Set disk quota limits for the user or group (as determined by |
20909 | the command type) with identifier _\bi_\bd. _\ba_\bd_\bd_\br is a pointer to a |
20910 | struct dqblk structure. The usage fields of struct dqblk |
20911 | structure are ignored. This call is restricted to the |
20912 | superuser. |
20913 | |
20914 | Q_SETUSE Set disk usage limits for the user or group (as determined by |
20915 | the command type) with identifier _\bi_\bd. _\ba_\bd_\bd_\br is a pointer to a |
20916 | struct dqblk structure. Only the usage fields are used. This |
20917 | call is restricted to the superuser. |
20918 | |
20919 | Q_SYNC Update the on-disk copy of quota usages. The command type |
20920 | specifies which type of quotas are to be updated. The _\bi_\bd and |
20921 | _\ba_\bd_\bd_\br parameters are ignored. |
20922 | |
20923 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
20924 | Upon successful completion, the value 0 is returned; otherwise the |
20925 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
20926 | error. |
20927 | |
20928 | E\bER\bRR\bRO\bOR\bRS\bS |
20929 | A q\bqu\buo\bot\bta\bac\bct\btl\bl() call will fail if: |
20930 | |
20931 | [EOPNOTSUPP] The kernel has not been compiled with the QUOTA |
20932 | option. |
20933 | |
20934 | [EUSERS] The quota table cannot be expanded. |
20935 | |
20936 | [EINVAL] _\bc_\bm_\bd or the command type is invalid. |
20937 | |
20938 | [EACCES] In Q_QUOTAON, the quota file is not a plain file. |
20939 | |
20940 | [EACCES] Search permission is denied for a component of a path |
20941 | prefix. |
20942 | |
20943 | [ENOTDIR] A component of a path prefix was not a directory. |
20944 | |
20945 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
20946 | characters, or an entire pathname (including the |
20947 | terminating NUL) exceeded PATH_MAX bytes. |
20948 | |
20949 | [ENOENT] A filename does not exist. |
20950 | |
20951 | [ELOOP] Too many symbolic links were encountered in |
20952 | translating a pathname. |
20953 | |
20954 | [EROFS] In Q_QUOTAON, the quota file resides on a read-only |
20955 | filesystem. |
20956 | |
20957 | [EIO] An I/O error occurred while reading from or writing to |
20958 | a file containing quotas. |
20959 | |
20960 | [EFAULT] An invalid _\ba_\bd_\bd_\br was supplied; the associated structure |
20961 | could not be copied in or out of the kernel. |
20962 | |
20963 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
20964 | space. |
20965 | |
20966 | [EPERM] The call was privileged and the caller was not the |
20967 | superuser. |
20968 | |
20969 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
20970 | quota(1), fstab(5), edquota(8), quotacheck(8), quotaon(8), repquota(8) |
20971 | |
20972 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
20973 | The q\bqu\buo\bot\bta\bac\bct\btl\bl() function call appeared in 4.3BSD-Reno. |
20974 | |
20975 | B\bBU\bUG\bGS\bS |
20976 | There should be some way to integrate this call with the resource limit |
20977 | interface provided by setrlimit(2) and getrlimit(2). |
20978 | |
20979 | N\bNA\bAM\bME\bE |
20980 | r\bre\bea\bad\bd, r\bre\bea\bad\bdv\bv, p\bpr\bre\bea\bad\bd, p\bpr\bre\bea\bad\bdv\bv - read input |
20981 | |
20982 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
20983 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
20984 | |
20985 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20986 | r\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
20987 | |
20988 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20989 | p\bpr\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
20990 | |
20991 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
20992 | |
20993 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
20994 | r\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
20995 | |
20996 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
20997 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
20998 | |
20999 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21000 | p\bpr\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
21001 | |
21002 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
21003 | r\bre\bea\bad\bd() attempts to read _\bn_\bb_\by_\bt_\be_\bs of data from the object referenced by the |
21004 | descriptor _\bd into the buffer pointed to by _\bb_\bu_\bf. r\bre\bea\bad\bdv\bv() performs the |
21005 | same action, but scatters the input data into the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
21006 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
21007 | iov[iovcnt-1]. p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() perform the same functions, but read |
21008 | from the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the file |
21009 | pointer. |
21010 | |
21011 | For r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
21012 | |
21013 | struct iovec { |
21014 | void *iov_base; |
21015 | size_t iov_len; |
21016 | }; |
21017 | |
21018 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
21019 | memory where data should be placed. r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will always |
21020 | fill an area completely before proceeding to the next. |
21021 | |
21022 | On objects capable of seeking, the r\bre\bea\bad\bd() starts at a position given by |
21023 | the pointer associated with _\bd (see lseek(2)). Upon return from r\bre\bea\bad\bd(), |
21024 | the pointer is incremented by the number of bytes actually read. |
21025 | |
21026 | Objects that are not capable of seeking always read from the current |
21027 | position. The value of the pointer associated with such an object is |
21028 | undefined. |
21029 | |
21030 | Upon successful completion, r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() return |
21031 | the number of bytes actually read and placed in the buffer. The system |
21032 | guarantees to read the number of bytes requested if the descriptor |
21033 | references a normal file that has that many bytes left before the end-of- |
21034 | file, but in no other case. |
21035 | |
21036 | Note that r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
21037 | the constant IOV_MAX. |
21038 | |
21039 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
21040 | If successful, the number of bytes actually read is returned. Upon |
21041 | reading end-of-file, zero is returned. Otherwise, a -1 is returned and |
21042 | the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
21043 | |
21044 | E\bER\bRR\bRO\bOR\bRS\bS |
21045 | r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() will succeed unless: |
21046 | |
21047 | [EBADF] _\bd is not a valid file or socket descriptor open for |
21048 | reading. |
21049 | |
21050 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
21051 | address space. |
21052 | |
21053 | [EIO] An I/O error occurred while reading from the file |
21054 | system. |
21055 | |
21056 | [EINTR] A read from a slow device (i.e. one that might block |
21057 | for an arbitrary amount of time) was interrupted by |
21058 | the delivery of a signal before any data arrived. |
21059 | |
21060 | In addition, r\bre\bea\bad\bd() and r\bre\bea\bad\bdv\bv() may return the following errors: |
21061 | |
21062 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
21063 | were ready to be read. |
21064 | |
21065 | [ENOTCONN] The file is a socket associated with a connection- |
21066 | oriented protocol and has not been connected. |
21067 | |
21068 | [EIO] The process is a member of a background process |
21069 | attempting to read from its controlling terminal, the |
21070 | process is ignoring or blocking the SIGTTIN signal or |
21071 | the process group is orphaned. |
21072 | |
21073 | r\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bd() may return the following error: |
21074 | |
21075 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
21076 | |
21077 | p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() may return the following errors: |
21078 | |
21079 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
21080 | |
21081 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
21082 | |
21083 | r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() may return one of the following errors: |
21084 | |
21085 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
21086 | IOV_MAX. |
21087 | |
21088 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
21089 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
21090 | |
21091 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
21092 | address space. |
21093 | |
21094 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
21095 | dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), |
21096 | socketpair(2) |
21097 | |
21098 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
21099 | The r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), and p\bpr\bre\bea\bad\bd() functions conform to IEEE Std |
21100 | 1003.1-2008 (``POSIX.1''). |
21101 | |
21102 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
21103 | A r\bre\bea\bad\bd() system call first appeared in Version 1 AT&T UNIX; r\bre\bea\bad\bdv\bv() in |
21104 | 4.1cBSD; p\bpr\bre\bea\bad\bd() in AT&T System V Release 4 UNIX; and p\bpr\bre\bea\bad\bdv\bv() in |
21105 | OpenBSD 2.7. |
21106 | |
21107 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
21108 | Error checks should explicitly test for -1. Code such as |
21109 | |
21110 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
21111 | |
21112 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
21113 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
21114 | error-free r\bre\bea\bad\bd() may appear as a negative number distinct from -1. |
21115 | Proper loops should use |
21116 | |
21117 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
21118 | |
21119 | N\bNA\bAM\bME\bE |
21120 | r\bre\bea\bad\bdl\bli\bin\bnk\bk, r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt - read value of a symbolic link |
21121 | |
21122 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
21123 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
21124 | |
21125 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21126 | r\bre\bea\bad\bdl\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\be_\bs_\bt_\br_\bi_\bc_\bt _\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\br_\be_\bs_\bt_\br_\bi_\bc_\bt _\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz); |
21127 | |
21128 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
21129 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
21130 | |
21131 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21132 | r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz); |
21133 | |
21134 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
21135 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() function places the contents of the symbolic link _\bp_\ba_\bt_\bh in |
21136 | the buffer _\bb_\bu_\bf, which has size _\bb_\bu_\bf_\bs_\bi_\bz. r\bre\bea\bad\bdl\bli\bin\bnk\bk does not append a NUL |
21137 | character to _\bb_\bu_\bf. |
21138 | |
21139 | The r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() function is equivalent to r\bre\bea\bad\bdl\bli\bin\bnk\bk() except that where |
21140 | _\bp_\ba_\bt_\bh specifies a relative path, the symbolic link whose contents are read |
21141 | is determined relative to the directory associated with file descriptor |
21142 | _\bf_\bd instead of the current working directory. |
21143 | |
21144 | If r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in |
21145 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used and |
21146 | the behavior is identical to a call to r\bre\bea\bad\bdl\bli\bin\bnk\bk(). |
21147 | |
21148 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
21149 | The call returns the count of characters placed in the buffer if it |
21150 | succeeds, or a -1 if an error occurs, placing the error code in the |
21151 | global variable _\be_\br_\br_\bn_\bo. |
21152 | |
21153 | E\bER\bRR\bRO\bOR\bRS\bS |
21154 | r\bre\bea\bad\bdl\bli\bin\bnk\bk() and r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() will fail if: |
21155 | |
21156 | [ENOTDIR] A component of the path prefix is not a directory. |
21157 | |
21158 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
21159 | characters, or an entire pathname (including the |
21160 | terminating NUL) exceeded PATH_MAX bytes. |
21161 | |
21162 | [ENOENT] The named file does not exist. |
21163 | |
21164 | [EACCES] Search permission is denied for a component of the |
21165 | path prefix. |
21166 | |
21167 | [ELOOP] Too many symbolic links were encountered in |
21168 | translating the pathname. |
21169 | |
21170 | [EINVAL] The named file is not a symbolic link. |
21171 | |
21172 | [EIO] An I/O error occurred while reading from the file |
21173 | system. |
21174 | |
21175 | [EFAULT] _\bb_\bu_\bf or _\bp_\ba_\bt_\bh extends outside the process's allocated |
21176 | address space. |
21177 | |
21178 | Additionally, r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() will fail if: |
21179 | |
21180 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
21181 | argument is neither AT_FDCWD nor a valid file |
21182 | descriptor. |
21183 | |
21184 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
21185 | argument is a valid file descriptor but it does not |
21186 | reference a directory. |
21187 | |
21188 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
21189 | permission is denied for the directory which the _\bf_\bd |
21190 | file descriptor references. |
21191 | |
21192 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
21193 | lstat(2), stat(2), symlink(2), symlink(7) |
21194 | |
21195 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
21196 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() and r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
21197 | (``POSIX.1''). |
21198 | |
21199 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
21200 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() system call first appeared in 4.1cBSD. The r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() |
21201 | system call has been available since OpenBSD 5.0. |
21202 | |
21203 | N\bNA\bAM\bME\bE |
21204 | r\bre\bea\bad\bdl\bli\bin\bnk\bk, r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt - read value of a symbolic link |
21205 | |
21206 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
21207 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
21208 | |
21209 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21210 | r\bre\bea\bad\bdl\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\be_\bs_\bt_\br_\bi_\bc_\bt _\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\br_\be_\bs_\bt_\br_\bi_\bc_\bt _\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz); |
21211 | |
21212 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
21213 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
21214 | |
21215 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21216 | r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bb_\bu_\bf_\bs_\bi_\bz); |
21217 | |
21218 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
21219 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() function places the contents of the symbolic link _\bp_\ba_\bt_\bh in |
21220 | the buffer _\bb_\bu_\bf, which has size _\bb_\bu_\bf_\bs_\bi_\bz. r\bre\bea\bad\bdl\bli\bin\bnk\bk does not append a NUL |
21221 | character to _\bb_\bu_\bf. |
21222 | |
21223 | The r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() function is equivalent to r\bre\bea\bad\bdl\bli\bin\bnk\bk() except that where |
21224 | _\bp_\ba_\bt_\bh specifies a relative path, the symbolic link whose contents are read |
21225 | is determined relative to the directory associated with file descriptor |
21226 | _\bf_\bd instead of the current working directory. |
21227 | |
21228 | If r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in |
21229 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used and |
21230 | the behavior is identical to a call to r\bre\bea\bad\bdl\bli\bin\bnk\bk(). |
21231 | |
21232 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
21233 | The call returns the count of characters placed in the buffer if it |
21234 | succeeds, or a -1 if an error occurs, placing the error code in the |
21235 | global variable _\be_\br_\br_\bn_\bo. |
21236 | |
21237 | E\bER\bRR\bRO\bOR\bRS\bS |
21238 | r\bre\bea\bad\bdl\bli\bin\bnk\bk() and r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() will fail if: |
21239 | |
21240 | [ENOTDIR] A component of the path prefix is not a directory. |
21241 | |
21242 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
21243 | characters, or an entire pathname (including the |
21244 | terminating NUL) exceeded PATH_MAX bytes. |
21245 | |
21246 | [ENOENT] The named file does not exist. |
21247 | |
21248 | [EACCES] Search permission is denied for a component of the |
21249 | path prefix. |
21250 | |
21251 | [ELOOP] Too many symbolic links were encountered in |
21252 | translating the pathname. |
21253 | |
21254 | [EINVAL] The named file is not a symbolic link. |
21255 | |
21256 | [EIO] An I/O error occurred while reading from the file |
21257 | system. |
21258 | |
21259 | [EFAULT] _\bb_\bu_\bf or _\bp_\ba_\bt_\bh extends outside the process's allocated |
21260 | address space. |
21261 | |
21262 | Additionally, r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() will fail if: |
21263 | |
21264 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
21265 | argument is neither AT_FDCWD nor a valid file |
21266 | descriptor. |
21267 | |
21268 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
21269 | argument is a valid file descriptor but it does not |
21270 | reference a directory. |
21271 | |
21272 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
21273 | permission is denied for the directory which the _\bf_\bd |
21274 | file descriptor references. |
21275 | |
21276 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
21277 | lstat(2), stat(2), symlink(2), symlink(7) |
21278 | |
21279 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
21280 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() and r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
21281 | (``POSIX.1''). |
21282 | |
21283 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
21284 | The r\bre\bea\bad\bdl\bli\bin\bnk\bk() system call first appeared in 4.1cBSD. The r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt() |
21285 | system call has been available since OpenBSD 5.0. |
21286 | |
21287 | N\bNA\bAM\bME\bE |
21288 | r\bre\bea\bad\bd, r\bre\bea\bad\bdv\bv, p\bpr\bre\bea\bad\bd, p\bpr\bre\bea\bad\bdv\bv - read input |
21289 | |
21290 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
21291 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
21292 | |
21293 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21294 | r\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
21295 | |
21296 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21297 | p\bpr\bre\bea\bad\bd(_\bi_\bn_\bt _\bd, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
21298 | |
21299 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
21300 | |
21301 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21302 | r\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
21303 | |
21304 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
21305 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
21306 | |
21307 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21308 | p\bpr\bre\bea\bad\bdv\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
21309 | |
21310 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
21311 | r\bre\bea\bad\bd() attempts to read _\bn_\bb_\by_\bt_\be_\bs of data from the object referenced by the |
21312 | descriptor _\bd into the buffer pointed to by _\bb_\bu_\bf. r\bre\bea\bad\bdv\bv() performs the |
21313 | same action, but scatters the input data into the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
21314 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
21315 | iov[iovcnt-1]. p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() perform the same functions, but read |
21316 | from the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the file |
21317 | pointer. |
21318 | |
21319 | For r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
21320 | |
21321 | struct iovec { |
21322 | void *iov_base; |
21323 | size_t iov_len; |
21324 | }; |
21325 | |
21326 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
21327 | memory where data should be placed. r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will always |
21328 | fill an area completely before proceeding to the next. |
21329 | |
21330 | On objects capable of seeking, the r\bre\bea\bad\bd() starts at a position given by |
21331 | the pointer associated with _\bd (see lseek(2)). Upon return from r\bre\bea\bad\bd(), |
21332 | the pointer is incremented by the number of bytes actually read. |
21333 | |
21334 | Objects that are not capable of seeking always read from the current |
21335 | position. The value of the pointer associated with such an object is |
21336 | undefined. |
21337 | |
21338 | Upon successful completion, r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() return |
21339 | the number of bytes actually read and placed in the buffer. The system |
21340 | guarantees to read the number of bytes requested if the descriptor |
21341 | references a normal file that has that many bytes left before the end-of- |
21342 | file, but in no other case. |
21343 | |
21344 | Note that r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
21345 | the constant IOV_MAX. |
21346 | |
21347 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
21348 | If successful, the number of bytes actually read is returned. Upon |
21349 | reading end-of-file, zero is returned. Otherwise, a -1 is returned and |
21350 | the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
21351 | |
21352 | E\bER\bRR\bRO\bOR\bRS\bS |
21353 | r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), p\bpr\bre\bea\bad\bd(), and p\bpr\bre\bea\bad\bdv\bv() will succeed unless: |
21354 | |
21355 | [EBADF] _\bd is not a valid file or socket descriptor open for |
21356 | reading. |
21357 | |
21358 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
21359 | address space. |
21360 | |
21361 | [EIO] An I/O error occurred while reading from the file |
21362 | system. |
21363 | |
21364 | [EINTR] A read from a slow device (i.e. one that might block |
21365 | for an arbitrary amount of time) was interrupted by |
21366 | the delivery of a signal before any data arrived. |
21367 | |
21368 | In addition, r\bre\bea\bad\bd() and r\bre\bea\bad\bdv\bv() may return the following errors: |
21369 | |
21370 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
21371 | were ready to be read. |
21372 | |
21373 | [ENOTCONN] The file is a socket associated with a connection- |
21374 | oriented protocol and has not been connected. |
21375 | |
21376 | [EIO] The process is a member of a background process |
21377 | attempting to read from its controlling terminal, the |
21378 | process is ignoring or blocking the SIGTTIN signal or |
21379 | the process group is orphaned. |
21380 | |
21381 | r\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bd() may return the following error: |
21382 | |
21383 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
21384 | |
21385 | p\bpr\bre\bea\bad\bd() and p\bpr\bre\bea\bad\bdv\bv() may return the following errors: |
21386 | |
21387 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
21388 | |
21389 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
21390 | |
21391 | r\bre\bea\bad\bdv\bv() and p\bpr\bre\bea\bad\bdv\bv() may return one of the following errors: |
21392 | |
21393 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
21394 | IOV_MAX. |
21395 | |
21396 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
21397 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
21398 | |
21399 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
21400 | address space. |
21401 | |
21402 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
21403 | dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socket(2), |
21404 | socketpair(2) |
21405 | |
21406 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
21407 | The r\bre\bea\bad\bd(), r\bre\bea\bad\bdv\bv(), and p\bpr\bre\bea\bad\bd() functions conform to IEEE Std |
21408 | 1003.1-2008 (``POSIX.1''). |
21409 | |
21410 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
21411 | A r\bre\bea\bad\bd() system call first appeared in Version 1 AT&T UNIX; r\bre\bea\bad\bdv\bv() in |
21412 | 4.1cBSD; p\bpr\bre\bea\bad\bd() in AT&T System V Release 4 UNIX; and p\bpr\bre\bea\bad\bdv\bv() in |
21413 | OpenBSD 2.7. |
21414 | |
21415 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
21416 | Error checks should explicitly test for -1. Code such as |
21417 | |
21418 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
21419 | |
21420 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
21421 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
21422 | error-free r\bre\bea\bad\bd() may appear as a negative number distinct from -1. |
21423 | Proper loops should use |
21424 | |
21425 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
21426 | |
21427 | N\bNA\bAM\bME\bE |
21428 | r\bre\beb\bbo\boo\bot\bt - reboot system or halt processor |
21429 | |
21430 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
21431 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
21432 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\beb\bbo\boo\bot\bt.\b.h\bh>\b> |
21433 | |
21434 | _\bi_\bn_\bt |
21435 | r\bre\beb\bbo\boo\bot\bt(_\bi_\bn_\bt _\bh_\bo_\bw_\bt_\bo); |
21436 | |
21437 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
21438 | r\bre\beb\bbo\boo\bot\bt() reboots the system. Only the superuser may reboot a machine on |
21439 | demand. However, a reboot is invoked automatically in the event of |
21440 | unrecoverable system failures. |
21441 | |
21442 | _\bh_\bo_\bw_\bt_\bo is a mask of options; the system call interface allows the |
21443 | following options, defined in the include file <_\bs_\by_\bs_\b/_\br_\be_\bb_\bo_\bo_\bt_\b._\bh>, to be |
21444 | passed to the new kernel or the new bootstrap and init programs. |
21445 | |
21446 | RB_AUTOBOOT The default, causing the system to reboot in its usual |
21447 | fashion. |
21448 | |
21449 | RB_ASKNAME Interpreted by the bootstrap program itself, causing it to |
21450 | prompt on the console as to what file should be booted. |
21451 | Normally, the system is booted from the file |
21452 | ``_\bx_\bx(0,0)bsd'', where _\bx_\bx is the default disk name, without |
21453 | prompting for the file name. |
21454 | |
21455 | RB_DFLTROOT Use the compiled in root device. Normally, the system uses |
21456 | the device from which it was booted as the root device if |
21457 | possible. (The default behavior is dependent on the |
21458 | ability of the bootstrap program to determine the drive |
21459 | from which it was loaded, which is not possible on all |
21460 | systems.) |
21461 | |
21462 | RB_DUMP Dump kernel memory before rebooting; see savecore(8) for |
21463 | more information. |
21464 | |
21465 | RB_HALT The processor is simply halted; no reboot takes place. |
21466 | |
21467 | RB_POWERDOWN If used in conjunction with RB_HALT, and if the system |
21468 | hardware supports the function, the system will be powered |
21469 | off. |
21470 | |
21471 | RB_USERREQ By default, the system will halt if r\bre\beb\bbo\boo\bot\bt() is called |
21472 | during startup (before the system has finished |
21473 | autoconfiguration), even if RB_HALT is not specified. This |
21474 | is because panic(9)s during startup will probably just |
21475 | repeat on the next boot. Use of this option implies that |
21476 | the user has requested the action specified (for example, |
21477 | using the ddb(4) b\bbo\boo\bot\bt r\bre\beb\bbo\boo\bot\bt command), so the system will |
21478 | reboot if a halt is not explicitly requested. |
21479 | |
21480 | RB_INITNAME An option allowing the specification of an init program |
21481 | (see init(8)) other than _\b/_\bs_\bb_\bi_\bn_\b/_\bi_\bn_\bi_\bt to be run when the |
21482 | system reboots. This switch is not currently available. |
21483 | |
21484 | RB_KDB Load the symbol table and enable a built-in debugger in the |
21485 | system. This option will have no useful function if the |
21486 | kernel is not configured for debugging. Several other |
21487 | options have different meaning if combined with this |
21488 | option, although their use may not be possible via the |
21489 | r\bre\beb\bbo\boo\bot\bt() call. See ddb(4) for more information. |
21490 | |
21491 | RB_NOSYNC Normally, the disks are sync'd (see sync(8)) before the |
21492 | processor is halted or rebooted. This option may be useful |
21493 | if file system changes have been made manually or if the |
21494 | processor is on fire. |
21495 | |
21496 | RB_RDONLY Initially mount the root file system read-only. This is |
21497 | currently the default, and this option has been deprecated. |
21498 | |
21499 | RB_SINGLE Normally, the reboot procedure involves an automatic disk |
21500 | consistency check and then multi-user operations. |
21501 | RB_SINGLE prevents this, booting the system with a single- |
21502 | user shell on the console. RB_SINGLE is actually |
21503 | interpreted by the init(8) program in the newly booted |
21504 | system. |
21505 | |
21506 | When no options are given (i.e., RB_AUTOBOOT is used), the |
21507 | system is rebooted from file _\b/_\bb_\bs_\bd in the root file system |
21508 | of unit 0 of a disk chosen in a processor specific way. An |
21509 | automatic consistency check of the disks is normally |
21510 | performed (see fsck(8)). |
21511 | |
21512 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
21513 | If successful, this call never returns. Otherwise, a -1 is returned and |
21514 | an error is returned in the global variable _\be_\br_\br_\bn_\bo. |
21515 | |
21516 | E\bER\bRR\bRO\bOR\bRS\bS |
21517 | [EPERM] The caller is not the superuser. |
21518 | |
21519 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
21520 | ddb(4), crash(8), halt(8), init(8), reboot(8), savecore(8), boot(9), |
21521 | panic(9) |
21522 | |
21523 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
21524 | The r\bre\beb\bbo\boo\bot\bt() system call finally appeared in 4.0BSD. |
21525 | |
21526 | B\bBU\bUG\bGS\bS |
21527 | Not all platforms support all possible arguments. |
21528 | |
21529 | N\bNA\bAM\bME\bE |
21530 | r\bre\bec\bcv\bv, r\bre\bec\bcv\bvf\bfr\bro\bom\bm, r\bre\bec\bcv\bvm\bms\bsg\bg - receive a message from a socket |
21531 | |
21532 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
21533 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
21534 | |
21535 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21536 | r\bre\bec\bcv\bv(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
21537 | |
21538 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21539 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bf_\br_\bo_\bm, |
21540 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bf_\br_\bo_\bm_\bl_\be_\bn); |
21541 | |
21542 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21543 | r\bre\bec\bcv\bvm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
21544 | |
21545 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
21546 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm() and r\bre\bec\bcv\bvm\bms\bsg\bg() are used to receive messages from a socket, _\bs, |
21547 | and may be used to receive data on a socket whether or not it is |
21548 | connection-oriented. |
21549 | |
21550 | If _\bf_\br_\bo_\bm is non-null and the socket is not connection-oriented, the source |
21551 | address of the message is filled in. _\bf_\br_\bo_\bm_\bl_\be_\bn is a value-result |
21552 | parameter, initialized to the size of the buffer associated with _\bf_\br_\bo_\bm, |
21553 | and modified on return to indicate the actual size of the address stored |
21554 | there. |
21555 | |
21556 | The r\bre\bec\bcv\bv() call is normally used only on a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd socket (see |
21557 | connect(2)) and is identical to r\bre\bec\bcv\bvf\bfr\bro\bom\bm() with a null _\bf_\br_\bo_\bm parameter. |
21558 | As it is redundant, it may not be supported in future releases. |
21559 | |
21560 | On successful completion, all three routines return the number of message |
21561 | bytes read. If a message is too long to fit in the supplied buffer, |
21562 | excess bytes may be discarded depending on the type of socket the message |
21563 | is received from (see socket(2)). |
21564 | |
21565 | If no messages are available at the socket, the receive call waits for a |
21566 | message to arrive, unless the socket is nonblocking (see fcntl(2)) in |
21567 | which case the value -1 is returned and the external variable _\be_\br_\br_\bn_\bo set |
21568 | to EAGAIN. The receive calls normally return any data available, up to |
21569 | the requested amount, rather than waiting for receipt of the full amount |
21570 | requested; this behavior is affected by the socket-level options |
21571 | SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). |
21572 | |
21573 | The select(2) or poll(2) system calls may be used to determine when more |
21574 | data arrive. |
21575 | |
21576 | The _\bf_\bl_\ba_\bg_\bs argument is the bitwise OR of zero or more of the following |
21577 | values: |
21578 | |
21579 | MSG_OOB process out-of-band data |
21580 | MSG_PEEK peek at incoming message |
21581 | MSG_WAITALL wait for full request or error |
21582 | MSG_DONTWAIT don't block |
21583 | MSG_CMSG_CLOEXEC set the close-on-exec flag on received file |
21584 | descriptors |
21585 | |
21586 | The MSG_OOB flag requests receipt of out-of-band data that would not be |
21587 | received in the normal data stream. Some protocols place expedited data |
21588 | at the head of the normal data queue, and thus this flag cannot be used |
21589 | with such protocols. The MSG_PEEK flag causes the receive operation to |
21590 | return data from the beginning of the receive queue without removing that |
21591 | data from the queue. Thus, a subsequent receive call will return the |
21592 | same data. The MSG_WAITALL flag requests that the operation block until |
21593 | the full request is satisfied. However, the call may still return less |
21594 | data than requested if a signal is caught, an error or disconnect occurs, |
21595 | or the next data to be received is of a different type than that |
21596 | returned. The MSG_DONTWAIT flag requests the call to return when it |
21597 | would block otherwise. If no data is available, _\be_\br_\br_\bn_\bo is set to EAGAIN. |
21598 | This flag is not available in strict ANSI or C99 compilation mode. The |
21599 | MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary |
21600 | data with r\bre\bec\bcv\bvm\bms\bsg\bg() (see below) have their close-on-exec flag set. |
21601 | |
21602 | The r\bre\bec\bcv\bvm\bms\bsg\bg() call uses a _\bm_\bs_\bg_\bh_\bd_\br structure to minimize the number of |
21603 | directly supplied parameters. This structure has the following form, as |
21604 | defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>: |
21605 | |
21606 | struct msghdr { |
21607 | void *msg_name; /* optional address */ |
21608 | socklen_t msg_namelen; /* size of address */ |
21609 | struct iovec *msg_iov; /* scatter/gather array */ |
21610 | unsigned int msg_iovlen; /* # elements in msg_iov */ |
21611 | void *msg_control; /* ancillary data, see below */ |
21612 | socklen_t msg_controllen; /* ancillary data buffer len */ |
21613 | int msg_flags; /* flags on received message */ |
21614 | }; |
21615 | |
21616 | Here _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be and _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be_\bl_\be_\bn specify the source address if the socket is |
21617 | unconnected; _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be may be given as a null pointer if no names are |
21618 | desired or required. _\bm_\bs_\bg_\b__\bi_\bo_\bv and _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn describe scatter gather |
21619 | locations, as discussed in read(2). _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl, which has length |
21620 | _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl_\bl_\be_\bn, points to a buffer for other protocol control related |
21621 | messages or other miscellaneous ancillary data. The messages are of the |
21622 | form: |
21623 | |
21624 | struct cmsghdr { |
21625 | socklen_t cmsg_len; /* data byte count, including hdr */ |
21626 | int cmsg_level; /* originating protocol */ |
21627 | int cmsg_type; /* protocol-specific type */ |
21628 | /* followed by u_char cmsg_data[]; */ |
21629 | }; |
21630 | |
21631 | See CMSG_DATA(3) for how these messages are constructed and decomposed. |
21632 | |
21633 | Open file descriptors are now passed as ancillary data for AF_UNIX domain |
21634 | and socketpair(2) sockets, with _\bc_\bm_\bs_\bg_\b__\bl_\be_\bv_\be_\bl set to SOL_SOCKET and |
21635 | _\bc_\bm_\bs_\bg_\b__\bt_\by_\bp_\be set to SCM_RIGHTS. |
21636 | |
21637 | The _\bm_\bs_\bg_\b__\bf_\bl_\ba_\bg_\bs field is set on return according to the message received. |
21638 | It will contain zero or more of the following values: |
21639 | |
21640 | MSG_OOB Returned to indicate that expedited or out-of-band data |
21641 | was received. |
21642 | MSG_EOR Indicates end-of-record; the data returned completed a |
21643 | record (generally used with sockets of type |
21644 | SOCK_SEQPACKET). |
21645 | MSG_TRUNC Indicates that the trailing portion of a datagram was |
21646 | discarded because the datagram was larger than the |
21647 | buffer supplied. |
21648 | MSG_CTRUNC Indicates that some control data were discarded due to |
21649 | lack of space in the buffer for ancillary data. |
21650 | MSG_BCAST Indicates that the packet was received as broadcast. |
21651 | MSG_MCAST Indicates that the packet was received as multicast. |
21652 | |
21653 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
21654 | These calls return the number of bytes received, or -1 if an error |
21655 | occurred. |
21656 | |
21657 | E\bER\bRR\bRO\bOR\bRS\bS |
21658 | r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() fail if: |
21659 | |
21660 | [EBADF] The argument _\bs is an invalid descriptor. |
21661 | |
21662 | [ENOTCONN] The socket is associated with a connection-oriented |
21663 | protocol and has not been connected (see connect(2) and |
21664 | accept(2)). |
21665 | |
21666 | [ENOTSOCK] The argument _\bs does not refer to a socket. |
21667 | |
21668 | [EAGAIN] The socket is marked non-blocking, and the receive |
21669 | operation would block, or a receive timeout had been set, |
21670 | and the timeout expired before data were received. |
21671 | |
21672 | [EINTR] The receive was interrupted by delivery of a signal |
21673 | before any data were available. |
21674 | |
21675 | [EFAULT] The receive buffer pointer(s) point outside the process's |
21676 | address space. |
21677 | |
21678 | [EHOSTUNREACH] A socket operation was attempted to an unreachable host. |
21679 | |
21680 | [EHOSTDOWN] A socket operation failed because the destination host |
21681 | was down. |
21682 | |
21683 | [ENETDOWN] A socket operation encountered a dead network. |
21684 | |
21685 | [ECONNREFUSED] The socket is associated with a connection-oriented |
21686 | protocol and the connection was forcefully rejected (see |
21687 | connect(2)). |
21688 | |
21689 | In addition, r\bre\bec\bcv\bv() and r\bre\bec\bcv\bvf\bfr\bro\bom\bm() may return the following error: |
21690 | |
21691 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
21692 | |
21693 | And r\bre\bec\bcv\bvm\bms\bsg\bg() may return one of the following errors: |
21694 | |
21695 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
21696 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
21697 | |
21698 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
21699 | than IOV_MAX. |
21700 | |
21701 | [EMSGSIZE] The receiving program did not have sufficient free |
21702 | file descriptor slots. The descriptors are closed and |
21703 | any pending data can be returned by another call to |
21704 | r\bre\bec\bcv\bvm\bms\bsg\bg(). |
21705 | |
21706 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
21707 | connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), |
21708 | socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) |
21709 | |
21710 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
21711 | The r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() functions conform to IEEE Std |
21712 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST |
21713 | flags are extensions to that specification. |
21714 | |
21715 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
21716 | The r\bre\bec\bcv\bv() function call appeared in 4.2BSD. |
21717 | |
21718 | N\bNA\bAM\bME\bE |
21719 | r\bre\bec\bcv\bv, r\bre\bec\bcv\bvf\bfr\bro\bom\bm, r\bre\bec\bcv\bvm\bms\bsg\bg - receive a message from a socket |
21720 | |
21721 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
21722 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
21723 | |
21724 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21725 | r\bre\bec\bcv\bv(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
21726 | |
21727 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21728 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bf_\br_\bo_\bm, |
21729 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bf_\br_\bo_\bm_\bl_\be_\bn); |
21730 | |
21731 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21732 | r\bre\bec\bcv\bvm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
21733 | |
21734 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
21735 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm() and r\bre\bec\bcv\bvm\bms\bsg\bg() are used to receive messages from a socket, _\bs, |
21736 | and may be used to receive data on a socket whether or not it is |
21737 | connection-oriented. |
21738 | |
21739 | If _\bf_\br_\bo_\bm is non-null and the socket is not connection-oriented, the source |
21740 | address of the message is filled in. _\bf_\br_\bo_\bm_\bl_\be_\bn is a value-result |
21741 | parameter, initialized to the size of the buffer associated with _\bf_\br_\bo_\bm, |
21742 | and modified on return to indicate the actual size of the address stored |
21743 | there. |
21744 | |
21745 | The r\bre\bec\bcv\bv() call is normally used only on a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd socket (see |
21746 | connect(2)) and is identical to r\bre\bec\bcv\bvf\bfr\bro\bom\bm() with a null _\bf_\br_\bo_\bm parameter. |
21747 | As it is redundant, it may not be supported in future releases. |
21748 | |
21749 | On successful completion, all three routines return the number of message |
21750 | bytes read. If a message is too long to fit in the supplied buffer, |
21751 | excess bytes may be discarded depending on the type of socket the message |
21752 | is received from (see socket(2)). |
21753 | |
21754 | If no messages are available at the socket, the receive call waits for a |
21755 | message to arrive, unless the socket is nonblocking (see fcntl(2)) in |
21756 | which case the value -1 is returned and the external variable _\be_\br_\br_\bn_\bo set |
21757 | to EAGAIN. The receive calls normally return any data available, up to |
21758 | the requested amount, rather than waiting for receipt of the full amount |
21759 | requested; this behavior is affected by the socket-level options |
21760 | SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). |
21761 | |
21762 | The select(2) or poll(2) system calls may be used to determine when more |
21763 | data arrive. |
21764 | |
21765 | The _\bf_\bl_\ba_\bg_\bs argument is the bitwise OR of zero or more of the following |
21766 | values: |
21767 | |
21768 | MSG_OOB process out-of-band data |
21769 | MSG_PEEK peek at incoming message |
21770 | MSG_WAITALL wait for full request or error |
21771 | MSG_DONTWAIT don't block |
21772 | MSG_CMSG_CLOEXEC set the close-on-exec flag on received file |
21773 | descriptors |
21774 | |
21775 | The MSG_OOB flag requests receipt of out-of-band data that would not be |
21776 | received in the normal data stream. Some protocols place expedited data |
21777 | at the head of the normal data queue, and thus this flag cannot be used |
21778 | with such protocols. The MSG_PEEK flag causes the receive operation to |
21779 | return data from the beginning of the receive queue without removing that |
21780 | data from the queue. Thus, a subsequent receive call will return the |
21781 | same data. The MSG_WAITALL flag requests that the operation block until |
21782 | the full request is satisfied. However, the call may still return less |
21783 | data than requested if a signal is caught, an error or disconnect occurs, |
21784 | or the next data to be received is of a different type than that |
21785 | returned. The MSG_DONTWAIT flag requests the call to return when it |
21786 | would block otherwise. If no data is available, _\be_\br_\br_\bn_\bo is set to EAGAIN. |
21787 | This flag is not available in strict ANSI or C99 compilation mode. The |
21788 | MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary |
21789 | data with r\bre\bec\bcv\bvm\bms\bsg\bg() (see below) have their close-on-exec flag set. |
21790 | |
21791 | The r\bre\bec\bcv\bvm\bms\bsg\bg() call uses a _\bm_\bs_\bg_\bh_\bd_\br structure to minimize the number of |
21792 | directly supplied parameters. This structure has the following form, as |
21793 | defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>: |
21794 | |
21795 | struct msghdr { |
21796 | void *msg_name; /* optional address */ |
21797 | socklen_t msg_namelen; /* size of address */ |
21798 | struct iovec *msg_iov; /* scatter/gather array */ |
21799 | unsigned int msg_iovlen; /* # elements in msg_iov */ |
21800 | void *msg_control; /* ancillary data, see below */ |
21801 | socklen_t msg_controllen; /* ancillary data buffer len */ |
21802 | int msg_flags; /* flags on received message */ |
21803 | }; |
21804 | |
21805 | Here _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be and _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be_\bl_\be_\bn specify the source address if the socket is |
21806 | unconnected; _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be may be given as a null pointer if no names are |
21807 | desired or required. _\bm_\bs_\bg_\b__\bi_\bo_\bv and _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn describe scatter gather |
21808 | locations, as discussed in read(2). _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl, which has length |
21809 | _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl_\bl_\be_\bn, points to a buffer for other protocol control related |
21810 | messages or other miscellaneous ancillary data. The messages are of the |
21811 | form: |
21812 | |
21813 | struct cmsghdr { |
21814 | socklen_t cmsg_len; /* data byte count, including hdr */ |
21815 | int cmsg_level; /* originating protocol */ |
21816 | int cmsg_type; /* protocol-specific type */ |
21817 | /* followed by u_char cmsg_data[]; */ |
21818 | }; |
21819 | |
21820 | See CMSG_DATA(3) for how these messages are constructed and decomposed. |
21821 | |
21822 | Open file descriptors are now passed as ancillary data for AF_UNIX domain |
21823 | and socketpair(2) sockets, with _\bc_\bm_\bs_\bg_\b__\bl_\be_\bv_\be_\bl set to SOL_SOCKET and |
21824 | _\bc_\bm_\bs_\bg_\b__\bt_\by_\bp_\be set to SCM_RIGHTS. |
21825 | |
21826 | The _\bm_\bs_\bg_\b__\bf_\bl_\ba_\bg_\bs field is set on return according to the message received. |
21827 | It will contain zero or more of the following values: |
21828 | |
21829 | MSG_OOB Returned to indicate that expedited or out-of-band data |
21830 | was received. |
21831 | MSG_EOR Indicates end-of-record; the data returned completed a |
21832 | record (generally used with sockets of type |
21833 | SOCK_SEQPACKET). |
21834 | MSG_TRUNC Indicates that the trailing portion of a datagram was |
21835 | discarded because the datagram was larger than the |
21836 | buffer supplied. |
21837 | MSG_CTRUNC Indicates that some control data were discarded due to |
21838 | lack of space in the buffer for ancillary data. |
21839 | MSG_BCAST Indicates that the packet was received as broadcast. |
21840 | MSG_MCAST Indicates that the packet was received as multicast. |
21841 | |
21842 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
21843 | These calls return the number of bytes received, or -1 if an error |
21844 | occurred. |
21845 | |
21846 | E\bER\bRR\bRO\bOR\bRS\bS |
21847 | r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() fail if: |
21848 | |
21849 | [EBADF] The argument _\bs is an invalid descriptor. |
21850 | |
21851 | [ENOTCONN] The socket is associated with a connection-oriented |
21852 | protocol and has not been connected (see connect(2) and |
21853 | accept(2)). |
21854 | |
21855 | [ENOTSOCK] The argument _\bs does not refer to a socket. |
21856 | |
21857 | [EAGAIN] The socket is marked non-blocking, and the receive |
21858 | operation would block, or a receive timeout had been set, |
21859 | and the timeout expired before data were received. |
21860 | |
21861 | [EINTR] The receive was interrupted by delivery of a signal |
21862 | before any data were available. |
21863 | |
21864 | [EFAULT] The receive buffer pointer(s) point outside the process's |
21865 | address space. |
21866 | |
21867 | [EHOSTUNREACH] A socket operation was attempted to an unreachable host. |
21868 | |
21869 | [EHOSTDOWN] A socket operation failed because the destination host |
21870 | was down. |
21871 | |
21872 | [ENETDOWN] A socket operation encountered a dead network. |
21873 | |
21874 | [ECONNREFUSED] The socket is associated with a connection-oriented |
21875 | protocol and the connection was forcefully rejected (see |
21876 | connect(2)). |
21877 | |
21878 | In addition, r\bre\bec\bcv\bv() and r\bre\bec\bcv\bvf\bfr\bro\bom\bm() may return the following error: |
21879 | |
21880 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
21881 | |
21882 | And r\bre\bec\bcv\bvm\bms\bsg\bg() may return one of the following errors: |
21883 | |
21884 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
21885 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
21886 | |
21887 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
21888 | than IOV_MAX. |
21889 | |
21890 | [EMSGSIZE] The receiving program did not have sufficient free |
21891 | file descriptor slots. The descriptors are closed and |
21892 | any pending data can be returned by another call to |
21893 | r\bre\bec\bcv\bvm\bms\bsg\bg(). |
21894 | |
21895 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
21896 | connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), |
21897 | socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) |
21898 | |
21899 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
21900 | The r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() functions conform to IEEE Std |
21901 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST |
21902 | flags are extensions to that specification. |
21903 | |
21904 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
21905 | The r\bre\bec\bcv\bv() function call appeared in 4.2BSD. |
21906 | |
21907 | N\bNA\bAM\bME\bE |
21908 | r\bre\bec\bcv\bv, r\bre\bec\bcv\bvf\bfr\bro\bom\bm, r\bre\bec\bcv\bvm\bms\bsg\bg - receive a message from a socket |
21909 | |
21910 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
21911 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
21912 | |
21913 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21914 | r\bre\bec\bcv\bv(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
21915 | |
21916 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21917 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm(_\bi_\bn_\bt _\bs, _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bf_\br_\bo_\bm, |
21918 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bf_\br_\bo_\bm_\bl_\be_\bn); |
21919 | |
21920 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
21921 | r\bre\bec\bcv\bvm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
21922 | |
21923 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
21924 | r\bre\bec\bcv\bvf\bfr\bro\bom\bm() and r\bre\bec\bcv\bvm\bms\bsg\bg() are used to receive messages from a socket, _\bs, |
21925 | and may be used to receive data on a socket whether or not it is |
21926 | connection-oriented. |
21927 | |
21928 | If _\bf_\br_\bo_\bm is non-null and the socket is not connection-oriented, the source |
21929 | address of the message is filled in. _\bf_\br_\bo_\bm_\bl_\be_\bn is a value-result |
21930 | parameter, initialized to the size of the buffer associated with _\bf_\br_\bo_\bm, |
21931 | and modified on return to indicate the actual size of the address stored |
21932 | there. |
21933 | |
21934 | The r\bre\bec\bcv\bv() call is normally used only on a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd socket (see |
21935 | connect(2)) and is identical to r\bre\bec\bcv\bvf\bfr\bro\bom\bm() with a null _\bf_\br_\bo_\bm parameter. |
21936 | As it is redundant, it may not be supported in future releases. |
21937 | |
21938 | On successful completion, all three routines return the number of message |
21939 | bytes read. If a message is too long to fit in the supplied buffer, |
21940 | excess bytes may be discarded depending on the type of socket the message |
21941 | is received from (see socket(2)). |
21942 | |
21943 | If no messages are available at the socket, the receive call waits for a |
21944 | message to arrive, unless the socket is nonblocking (see fcntl(2)) in |
21945 | which case the value -1 is returned and the external variable _\be_\br_\br_\bn_\bo set |
21946 | to EAGAIN. The receive calls normally return any data available, up to |
21947 | the requested amount, rather than waiting for receipt of the full amount |
21948 | requested; this behavior is affected by the socket-level options |
21949 | SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(2). |
21950 | |
21951 | The select(2) or poll(2) system calls may be used to determine when more |
21952 | data arrive. |
21953 | |
21954 | The _\bf_\bl_\ba_\bg_\bs argument is the bitwise OR of zero or more of the following |
21955 | values: |
21956 | |
21957 | MSG_OOB process out-of-band data |
21958 | MSG_PEEK peek at incoming message |
21959 | MSG_WAITALL wait for full request or error |
21960 | MSG_DONTWAIT don't block |
21961 | MSG_CMSG_CLOEXEC set the close-on-exec flag on received file |
21962 | descriptors |
21963 | |
21964 | The MSG_OOB flag requests receipt of out-of-band data that would not be |
21965 | received in the normal data stream. Some protocols place expedited data |
21966 | at the head of the normal data queue, and thus this flag cannot be used |
21967 | with such protocols. The MSG_PEEK flag causes the receive operation to |
21968 | return data from the beginning of the receive queue without removing that |
21969 | data from the queue. Thus, a subsequent receive call will return the |
21970 | same data. The MSG_WAITALL flag requests that the operation block until |
21971 | the full request is satisfied. However, the call may still return less |
21972 | data than requested if a signal is caught, an error or disconnect occurs, |
21973 | or the next data to be received is of a different type than that |
21974 | returned. The MSG_DONTWAIT flag requests the call to return when it |
21975 | would block otherwise. If no data is available, _\be_\br_\br_\bn_\bo is set to EAGAIN. |
21976 | This flag is not available in strict ANSI or C99 compilation mode. The |
21977 | MSG_CMSG_CLOEXEC requests that any file descriptors received as ancillary |
21978 | data with r\bre\bec\bcv\bvm\bms\bsg\bg() (see below) have their close-on-exec flag set. |
21979 | |
21980 | The r\bre\bec\bcv\bvm\bms\bsg\bg() call uses a _\bm_\bs_\bg_\bh_\bd_\br structure to minimize the number of |
21981 | directly supplied parameters. This structure has the following form, as |
21982 | defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>: |
21983 | |
21984 | struct msghdr { |
21985 | void *msg_name; /* optional address */ |
21986 | socklen_t msg_namelen; /* size of address */ |
21987 | struct iovec *msg_iov; /* scatter/gather array */ |
21988 | unsigned int msg_iovlen; /* # elements in msg_iov */ |
21989 | void *msg_control; /* ancillary data, see below */ |
21990 | socklen_t msg_controllen; /* ancillary data buffer len */ |
21991 | int msg_flags; /* flags on received message */ |
21992 | }; |
21993 | |
21994 | Here _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be and _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be_\bl_\be_\bn specify the source address if the socket is |
21995 | unconnected; _\bm_\bs_\bg_\b__\bn_\ba_\bm_\be may be given as a null pointer if no names are |
21996 | desired or required. _\bm_\bs_\bg_\b__\bi_\bo_\bv and _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn describe scatter gather |
21997 | locations, as discussed in read(2). _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl, which has length |
21998 | _\bm_\bs_\bg_\b__\bc_\bo_\bn_\bt_\br_\bo_\bl_\bl_\be_\bn, points to a buffer for other protocol control related |
21999 | messages or other miscellaneous ancillary data. The messages are of the |
22000 | form: |
22001 | |
22002 | struct cmsghdr { |
22003 | socklen_t cmsg_len; /* data byte count, including hdr */ |
22004 | int cmsg_level; /* originating protocol */ |
22005 | int cmsg_type; /* protocol-specific type */ |
22006 | /* followed by u_char cmsg_data[]; */ |
22007 | }; |
22008 | |
22009 | See CMSG_DATA(3) for how these messages are constructed and decomposed. |
22010 | |
22011 | Open file descriptors are now passed as ancillary data for AF_UNIX domain |
22012 | and socketpair(2) sockets, with _\bc_\bm_\bs_\bg_\b__\bl_\be_\bv_\be_\bl set to SOL_SOCKET and |
22013 | _\bc_\bm_\bs_\bg_\b__\bt_\by_\bp_\be set to SCM_RIGHTS. |
22014 | |
22015 | The _\bm_\bs_\bg_\b__\bf_\bl_\ba_\bg_\bs field is set on return according to the message received. |
22016 | It will contain zero or more of the following values: |
22017 | |
22018 | MSG_OOB Returned to indicate that expedited or out-of-band data |
22019 | was received. |
22020 | MSG_EOR Indicates end-of-record; the data returned completed a |
22021 | record (generally used with sockets of type |
22022 | SOCK_SEQPACKET). |
22023 | MSG_TRUNC Indicates that the trailing portion of a datagram was |
22024 | discarded because the datagram was larger than the |
22025 | buffer supplied. |
22026 | MSG_CTRUNC Indicates that some control data were discarded due to |
22027 | lack of space in the buffer for ancillary data. |
22028 | MSG_BCAST Indicates that the packet was received as broadcast. |
22029 | MSG_MCAST Indicates that the packet was received as multicast. |
22030 | |
22031 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22032 | These calls return the number of bytes received, or -1 if an error |
22033 | occurred. |
22034 | |
22035 | E\bER\bRR\bRO\bOR\bRS\bS |
22036 | r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() fail if: |
22037 | |
22038 | [EBADF] The argument _\bs is an invalid descriptor. |
22039 | |
22040 | [ENOTCONN] The socket is associated with a connection-oriented |
22041 | protocol and has not been connected (see connect(2) and |
22042 | accept(2)). |
22043 | |
22044 | [ENOTSOCK] The argument _\bs does not refer to a socket. |
22045 | |
22046 | [EAGAIN] The socket is marked non-blocking, and the receive |
22047 | operation would block, or a receive timeout had been set, |
22048 | and the timeout expired before data were received. |
22049 | |
22050 | [EINTR] The receive was interrupted by delivery of a signal |
22051 | before any data were available. |
22052 | |
22053 | [EFAULT] The receive buffer pointer(s) point outside the process's |
22054 | address space. |
22055 | |
22056 | [EHOSTUNREACH] A socket operation was attempted to an unreachable host. |
22057 | |
22058 | [EHOSTDOWN] A socket operation failed because the destination host |
22059 | was down. |
22060 | |
22061 | [ENETDOWN] A socket operation encountered a dead network. |
22062 | |
22063 | [ECONNREFUSED] The socket is associated with a connection-oriented |
22064 | protocol and the connection was forcefully rejected (see |
22065 | connect(2)). |
22066 | |
22067 | In addition, r\bre\bec\bcv\bv() and r\bre\bec\bcv\bvf\bfr\bro\bom\bm() may return the following error: |
22068 | |
22069 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
22070 | |
22071 | And r\bre\bec\bcv\bvm\bms\bsg\bg() may return one of the following errors: |
22072 | |
22073 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
22074 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
22075 | |
22076 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
22077 | than IOV_MAX. |
22078 | |
22079 | [EMSGSIZE] The receiving program did not have sufficient free |
22080 | file descriptor slots. The descriptors are closed and |
22081 | any pending data can be returned by another call to |
22082 | r\bre\bec\bcv\bvm\bms\bsg\bg(). |
22083 | |
22084 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22085 | connect(2), fcntl(2), getsockopt(2), poll(2), read(2), select(2), |
22086 | socket(2), socketpair(2), CMSG_DATA(3), sockatmark(3) |
22087 | |
22088 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
22089 | The r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), and r\bre\bec\bcv\bvm\bms\bsg\bg() functions conform to IEEE Std |
22090 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT, MSG_BCAST, and MSG_MCAST |
22091 | flags are extensions to that specification. |
22092 | |
22093 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
22094 | The r\bre\bec\bcv\bv() function call appeared in 4.2BSD. |
22095 | |
22096 | N\bNA\bAM\bME\bE |
22097 | r\bre\ben\bna\bam\bme\be, r\bre\ben\bna\bam\bme\bea\bat\bt - change the name of a file |
22098 | |
22099 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22100 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> |
22101 | |
22102 | _\bi_\bn_\bt |
22103 | r\bre\ben\bna\bam\bme\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\br_\bo_\bm, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\bo); |
22104 | |
22105 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
22106 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> |
22107 | |
22108 | _\bi_\bn_\bt |
22109 | r\bre\ben\bna\bam\bme\bea\bat\bt(_\bi_\bn_\bt _\bf_\br_\bo_\bm_\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\br_\bo_\bm, _\bi_\bn_\bt _\bt_\bo_\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\bo); |
22110 | |
22111 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22112 | The r\bre\ben\bna\bam\bme\be() function causes the link named _\bf_\br_\bo_\bm to be renamed as _\bt_\bo. If |
22113 | _\bt_\bo exists, it is first removed. Both _\bf_\br_\bo_\bm and _\bt_\bo must be of the same |
22114 | type (that is, both directories or both non-directories), and must reside |
22115 | on the same file system. |
22116 | |
22117 | r\bre\ben\bna\bam\bme\be() guarantees that if _\bt_\bo already exists, an instance of _\bt_\bo will |
22118 | always exist, even if the system should crash in the middle of the |
22119 | operation. |
22120 | |
22121 | If the final component of _\bf_\br_\bo_\bm is a symbolic link, the symbolic link is |
22122 | renamed, not the file or directory to which it points. |
22123 | |
22124 | The r\bre\ben\bna\bam\bme\bea\bat\bt() function is equivalent to r\bre\ben\bna\bam\bme\be() except that where _\bf_\br_\bo_\bm |
22125 | or _\bt_\bo specifies a relative path, the directory entry names used are |
22126 | resolved relative to the directories associated with file descriptors |
22127 | _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd (respectively) instead of the current working directory. |
22128 | |
22129 | If r\bre\ben\bna\bam\bme\bea\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
22130 | in the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd parameter, the current working directory is used |
22131 | for resolving the respective _\bf_\br_\bo_\bm or _\bt_\bo argument. |
22132 | |
22133 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22134 | Upon successful completion, the value 0 is returned; otherwise the |
22135 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
22136 | error. |
22137 | |
22138 | E\bER\bRR\bRO\bOR\bRS\bS |
22139 | r\bre\ben\bna\bam\bme\be() and r\bre\ben\bna\bam\bme\bea\bat\bt() will fail and neither of the argument files will |
22140 | be affected if: |
22141 | |
22142 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
22143 | characters, or an entire pathname (including the |
22144 | terminating NUL) exceeded PATH_MAX bytes. |
22145 | |
22146 | [ENOENT] A component of the _\bf_\br_\bo_\bm path does not exist, or a path |
22147 | prefix of _\bt_\bo does not exist. |
22148 | |
22149 | [EACCES] A component of either path prefix denies search |
22150 | permission. |
22151 | |
22152 | [EACCES] The requested change requires writing in a directory |
22153 | that denies write permission. |
22154 | |
22155 | [EACCES] The _\bf_\br_\bo_\bm argument is a directory and denies write |
22156 | permission. |
22157 | |
22158 | [EPERM] The directory containing _\bf_\br_\bo_\bm is marked sticky, and |
22159 | neither the containing directory nor _\bf_\br_\bo_\bm are owned by |
22160 | the effective user ID. |
22161 | |
22162 | [EPERM] The _\bt_\bo file exists, the directory containing _\bt_\bo is |
22163 | marked sticky, and neither the containing directory |
22164 | nor _\bt_\bo are owned by the effective user ID. |
22165 | |
22166 | [ELOOP] Too many symbolic links were encountered in |
22167 | translating either pathname. |
22168 | |
22169 | [EMLINK] The link count on the source file or destination |
22170 | directory is at the maximum. A rename cannot be |
22171 | completed under these conditions. |
22172 | |
22173 | [ENOTDIR] A component of either path prefix is not a directory. |
22174 | |
22175 | [ENOTDIR] _\bf_\br_\bo_\bm is a directory, but _\bt_\bo is not a directory. |
22176 | |
22177 | [EISDIR] _\bt_\bo is a directory, but _\bf_\br_\bo_\bm is not a directory. |
22178 | |
22179 | [EXDEV] The link named by _\bt_\bo and the file named by _\bf_\br_\bo_\bm are on |
22180 | different logical devices (file systems). Note that |
22181 | this error code will not be returned if the |
22182 | implementation permits cross-device links. |
22183 | |
22184 | [ENOSPC] The directory in which the entry for the new name is |
22185 | being placed cannot be extended because there is no |
22186 | space left on the file system containing the |
22187 | directory. |
22188 | |
22189 | [EDQUOT] The directory in which the entry for the new name is |
22190 | being placed cannot be extended because the user's |
22191 | quota of disk blocks on the file system containing the |
22192 | directory has been exhausted. |
22193 | |
22194 | [EIO] An I/O error occurred while making or updating a |
22195 | directory entry. |
22196 | |
22197 | [EROFS] The requested link requires writing in a directory on |
22198 | a read-only file system. |
22199 | |
22200 | [EFAULT] _\bf_\br_\bo_\bm or _\bt_\bo points outside the process's allocated |
22201 | address space. |
22202 | |
22203 | [EINVAL] _\bf_\br_\bo_\bm is a parent directory of _\bt_\bo, or an attempt is |
22204 | made to rename `.' or `..'. |
22205 | |
22206 | [ENOTEMPTY] _\bt_\bo is a directory and is not empty. |
22207 | |
22208 | Additionally, r\bre\ben\bna\bam\bme\bea\bat\bt() will fail if: |
22209 | |
22210 | [EBADF] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path and |
22211 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd argument, respectively, is neither |
22212 | AT_FDCWD nor a valid file descriptor. |
22213 | |
22214 | [ENOTDIR] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path and |
22215 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd argument, respectively, is a valid |
22216 | file descriptor but it does not reference a directory. |
22217 | |
22218 | [EACCES] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path but |
22219 | search permission is denied for the directory which |
22220 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd file descriptor, respectively, |
22221 | references. |
22222 | |
22223 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22224 | mv(1), open(2), symlink(7) |
22225 | |
22226 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
22227 | The r\bre\ben\bna\bam\bme\be() and r\bre\ben\bna\bam\bme\bea\bat\bt() functions conform to IEEE Std 1003.1-2008 |
22228 | (``POSIX.1''). |
22229 | |
22230 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
22231 | The r\bre\ben\bna\bam\bme\bea\bat\bt() function appeared in OpenBSD 5.0. |
22232 | |
22233 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
22234 | The system can deadlock if a loop in the file system graph is present. |
22235 | This loop takes the form of an entry in directory `_\ba', say `_\ba_\b/_\bf_\bo_\bo', being |
22236 | a hard link to directory `_\bb', and an entry in directory `_\bb', say `_\bb_\b/_\bb_\ba_\br', |
22237 | being a hard link to directory `_\ba'. When such a loop exists and two |
22238 | separate processes attempt to perform `rename a/foo b/bar' and `rename |
22239 | b/bar a/foo', respectively, the system may deadlock attempting to lock |
22240 | both directories for modification. Hard links to directories should be |
22241 | replaced by symbolic links by the system administrator. |
22242 | |
22243 | N\bNA\bAM\bME\bE |
22244 | r\bre\ben\bna\bam\bme\be, r\bre\ben\bna\bam\bme\bea\bat\bt - change the name of a file |
22245 | |
22246 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22247 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> |
22248 | |
22249 | _\bi_\bn_\bt |
22250 | r\bre\ben\bna\bam\bme\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\br_\bo_\bm, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\bo); |
22251 | |
22252 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
22253 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bst\btd\bdi\bio\bo.\b.h\bh>\b> |
22254 | |
22255 | _\bi_\bn_\bt |
22256 | r\bre\ben\bna\bam\bme\bea\bat\bt(_\bi_\bn_\bt _\bf_\br_\bo_\bm_\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\br_\bo_\bm, _\bi_\bn_\bt _\bt_\bo_\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\bo); |
22257 | |
22258 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22259 | The r\bre\ben\bna\bam\bme\be() function causes the link named _\bf_\br_\bo_\bm to be renamed as _\bt_\bo. If |
22260 | _\bt_\bo exists, it is first removed. Both _\bf_\br_\bo_\bm and _\bt_\bo must be of the same |
22261 | type (that is, both directories or both non-directories), and must reside |
22262 | on the same file system. |
22263 | |
22264 | r\bre\ben\bna\bam\bme\be() guarantees that if _\bt_\bo already exists, an instance of _\bt_\bo will |
22265 | always exist, even if the system should crash in the middle of the |
22266 | operation. |
22267 | |
22268 | If the final component of _\bf_\br_\bo_\bm is a symbolic link, the symbolic link is |
22269 | renamed, not the file or directory to which it points. |
22270 | |
22271 | The r\bre\ben\bna\bam\bme\bea\bat\bt() function is equivalent to r\bre\ben\bna\bam\bme\be() except that where _\bf_\br_\bo_\bm |
22272 | or _\bt_\bo specifies a relative path, the directory entry names used are |
22273 | resolved relative to the directories associated with file descriptors |
22274 | _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd (respectively) instead of the current working directory. |
22275 | |
22276 | If r\bre\ben\bna\bam\bme\bea\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
22277 | in the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd parameter, the current working directory is used |
22278 | for resolving the respective _\bf_\br_\bo_\bm or _\bt_\bo argument. |
22279 | |
22280 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22281 | Upon successful completion, the value 0 is returned; otherwise the |
22282 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
22283 | error. |
22284 | |
22285 | E\bER\bRR\bRO\bOR\bRS\bS |
22286 | r\bre\ben\bna\bam\bme\be() and r\bre\ben\bna\bam\bme\bea\bat\bt() will fail and neither of the argument files will |
22287 | be affected if: |
22288 | |
22289 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
22290 | characters, or an entire pathname (including the |
22291 | terminating NUL) exceeded PATH_MAX bytes. |
22292 | |
22293 | [ENOENT] A component of the _\bf_\br_\bo_\bm path does not exist, or a path |
22294 | prefix of _\bt_\bo does not exist. |
22295 | |
22296 | [EACCES] A component of either path prefix denies search |
22297 | permission. |
22298 | |
22299 | [EACCES] The requested change requires writing in a directory |
22300 | that denies write permission. |
22301 | |
22302 | [EACCES] The _\bf_\br_\bo_\bm argument is a directory and denies write |
22303 | permission. |
22304 | |
22305 | [EPERM] The directory containing _\bf_\br_\bo_\bm is marked sticky, and |
22306 | neither the containing directory nor _\bf_\br_\bo_\bm are owned by |
22307 | the effective user ID. |
22308 | |
22309 | [EPERM] The _\bt_\bo file exists, the directory containing _\bt_\bo is |
22310 | marked sticky, and neither the containing directory |
22311 | nor _\bt_\bo are owned by the effective user ID. |
22312 | |
22313 | [ELOOP] Too many symbolic links were encountered in |
22314 | translating either pathname. |
22315 | |
22316 | [EMLINK] The link count on the source file or destination |
22317 | directory is at the maximum. A rename cannot be |
22318 | completed under these conditions. |
22319 | |
22320 | [ENOTDIR] A component of either path prefix is not a directory. |
22321 | |
22322 | [ENOTDIR] _\bf_\br_\bo_\bm is a directory, but _\bt_\bo is not a directory. |
22323 | |
22324 | [EISDIR] _\bt_\bo is a directory, but _\bf_\br_\bo_\bm is not a directory. |
22325 | |
22326 | [EXDEV] The link named by _\bt_\bo and the file named by _\bf_\br_\bo_\bm are on |
22327 | different logical devices (file systems). Note that |
22328 | this error code will not be returned if the |
22329 | implementation permits cross-device links. |
22330 | |
22331 | [ENOSPC] The directory in which the entry for the new name is |
22332 | being placed cannot be extended because there is no |
22333 | space left on the file system containing the |
22334 | directory. |
22335 | |
22336 | [EDQUOT] The directory in which the entry for the new name is |
22337 | being placed cannot be extended because the user's |
22338 | quota of disk blocks on the file system containing the |
22339 | directory has been exhausted. |
22340 | |
22341 | [EIO] An I/O error occurred while making or updating a |
22342 | directory entry. |
22343 | |
22344 | [EROFS] The requested link requires writing in a directory on |
22345 | a read-only file system. |
22346 | |
22347 | [EFAULT] _\bf_\br_\bo_\bm or _\bt_\bo points outside the process's allocated |
22348 | address space. |
22349 | |
22350 | [EINVAL] _\bf_\br_\bo_\bm is a parent directory of _\bt_\bo, or an attempt is |
22351 | made to rename `.' or `..'. |
22352 | |
22353 | [ENOTEMPTY] _\bt_\bo is a directory and is not empty. |
22354 | |
22355 | Additionally, r\bre\ben\bna\bam\bme\bea\bat\bt() will fail if: |
22356 | |
22357 | [EBADF] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path and |
22358 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd argument, respectively, is neither |
22359 | AT_FDCWD nor a valid file descriptor. |
22360 | |
22361 | [ENOTDIR] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path and |
22362 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd argument, respectively, is a valid |
22363 | file descriptor but it does not reference a directory. |
22364 | |
22365 | [EACCES] The _\bf_\br_\bo_\bm or _\bt_\bo argument specifies a relative path but |
22366 | search permission is denied for the directory which |
22367 | the _\bf_\br_\bo_\bm_\bf_\bd or _\bt_\bo_\bf_\bd file descriptor, respectively, |
22368 | references. |
22369 | |
22370 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22371 | mv(1), open(2), symlink(7) |
22372 | |
22373 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
22374 | The r\bre\ben\bna\bam\bme\be() and r\bre\ben\bna\bam\bme\bea\bat\bt() functions conform to IEEE Std 1003.1-2008 |
22375 | (``POSIX.1''). |
22376 | |
22377 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
22378 | The r\bre\ben\bna\bam\bme\bea\bat\bt() function appeared in OpenBSD 5.0. |
22379 | |
22380 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
22381 | The system can deadlock if a loop in the file system graph is present. |
22382 | This loop takes the form of an entry in directory `_\ba', say `_\ba_\b/_\bf_\bo_\bo', being |
22383 | a hard link to directory `_\bb', and an entry in directory `_\bb', say `_\bb_\b/_\bb_\ba_\br', |
22384 | being a hard link to directory `_\ba'. When such a loop exists and two |
22385 | separate processes attempt to perform `rename a/foo b/bar' and `rename |
22386 | b/bar a/foo', respectively, the system may deadlock attempting to lock |
22387 | both directories for modification. Hard links to directories should be |
22388 | replaced by symbolic links by the system administrator. |
22389 | |
22390 | N\bNA\bAM\bME\bE |
22391 | r\bre\bev\bvo\bok\bke\be - revoke file access |
22392 | |
22393 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22394 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
22395 | |
22396 | _\bi_\bn_\bt |
22397 | r\bre\bev\bvo\bok\bke\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
22398 | |
22399 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22400 | The r\bre\bev\bvo\bok\bke\be function invalidates all current open file descriptors in the |
22401 | system for the file named by _\bp_\ba_\bt_\bh. Subsequent operations on any such |
22402 | descriptors fail, with the exceptions that a r\bre\bea\bad\bd() from a character |
22403 | device file which has been revoked returns a count of zero (end of file), |
22404 | and a c\bcl\blo\bos\bse\be() call will succeed. If the file is a special file for a |
22405 | device which is open, the device close function is called as if all open |
22406 | references to the file had been closed. |
22407 | |
22408 | Access to a file may be revoked only by its owner or the superuser. The |
22409 | r\bre\bev\bvo\bok\bke\be function is normally used to prepare a terminal device for a new |
22410 | login session, preventing any access by a previous user of the terminal. |
22411 | |
22412 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22413 | Upon successful completion, the value 0 is returned; otherwise the |
22414 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
22415 | error. |
22416 | |
22417 | E\bER\bRR\bRO\bOR\bRS\bS |
22418 | Access to the named file is revoked unless one of the following: |
22419 | |
22420 | [ENOTDIR] A component of the path prefix is not a directory. |
22421 | |
22422 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
22423 | characters, or an entire pathname (including the |
22424 | terminating NUL) exceeded PATH_MAX bytes. |
22425 | |
22426 | [ENOENT] The named file or a component of the path name does |
22427 | not exist. |
22428 | |
22429 | [EACCES] Search permission is denied for a component of the |
22430 | path prefix. |
22431 | |
22432 | [ELOOP] Too many symbolic links were encountered in |
22433 | translating the pathname. |
22434 | |
22435 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
22436 | space. |
22437 | |
22438 | [EPERM] The caller is neither the owner of the file nor the |
22439 | superuser. |
22440 | |
22441 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22442 | close(2) |
22443 | |
22444 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
22445 | The r\bre\bev\bvo\bok\bke\be function was introduced in 4.3BSD-Reno. |
22446 | |
22447 | N\bNA\bAM\bME\bE |
22448 | r\brm\bmd\bdi\bir\br - remove a directory file |
22449 | |
22450 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22451 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
22452 | |
22453 | _\bi_\bn_\bt |
22454 | r\brm\bmd\bdi\bir\br(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
22455 | |
22456 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22457 | r\brm\bmd\bdi\bir\br() removes a directory file whose name is given by _\bp_\ba_\bt_\bh. The |
22458 | directory must not have any entries other than `.' and `..'. |
22459 | |
22460 | There is no r\brm\bmd\bdi\bir\bra\bat\bt() function; to remove a directory with a path |
22461 | relative to the directory associated with a file descriptor use the |
22462 | unlinkat(2) function with the AT_REMOVEDIR flag. |
22463 | |
22464 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22465 | Upon successful completion, the value 0 is returned; otherwise the |
22466 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
22467 | error. |
22468 | |
22469 | E\bER\bRR\bRO\bOR\bRS\bS |
22470 | The named file is removed unless: |
22471 | |
22472 | [ENOTDIR] A component of the path is not a directory. |
22473 | |
22474 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
22475 | characters, or an entire pathname (including the |
22476 | terminating NUL) exceeded PATH_MAX bytes. |
22477 | |
22478 | [ENOENT] The named directory does not exist. |
22479 | |
22480 | [ELOOP] Too many symbolic links were encountered in |
22481 | translating the pathname. |
22482 | |
22483 | [ENOTEMPTY] The named directory contains files other than `.' and |
22484 | `..' in it. |
22485 | |
22486 | [EACCES] Search permission is denied for a component of the |
22487 | path prefix. |
22488 | |
22489 | [EACCES] Write permission is denied on the directory containing |
22490 | the directory to be removed. |
22491 | |
22492 | [EPERM] The directory containing the directory to be removed |
22493 | is marked sticky, and neither the containing directory |
22494 | nor the directory to be removed are owned by the |
22495 | effective user ID. |
22496 | |
22497 | [EPERM] The directory to be removed or the directory |
22498 | containing it has its immutable or append-only flag |
22499 | set (see chflags(2)). |
22500 | |
22501 | [EBUSY] The directory to be removed is the mount point for a |
22502 | mounted file system or the current directory. |
22503 | |
22504 | [EIO] An I/O error occurred while deleting the directory |
22505 | entry or deallocating the inode. |
22506 | |
22507 | [EROFS] The directory entry to be removed resides on a read- |
22508 | only file system. |
22509 | |
22510 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
22511 | space. |
22512 | |
22513 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22514 | rmdir(1), chflags(2), mkdir(2), unlink(2) |
22515 | |
22516 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
22517 | r\brm\bmd\bdi\bir\br() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
22518 | |
22519 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
22520 | The r\brm\bmd\bdi\bir\br() function call appeared in 4.2BSD. |
22521 | |
22522 | N\bNA\bAM\bME\bE |
22523 | b\bbr\brk\bk, s\bsb\bbr\brk\bk - change data segment size |
22524 | |
22525 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22526 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
22527 | |
22528 | _\bi_\bn_\bt |
22529 | b\bbr\brk\bk(_\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br); |
22530 | |
22531 | _\bv_\bo_\bi_\bd _\b* |
22532 | s\bsb\bbr\brk\bk(_\bi_\bn_\bt _\bi_\bn_\bc_\br); |
22533 | |
22534 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22535 | T\bTh\bhe\be b\bbr\brk\bk(\b()\b) a\ban\bnd\bd s\bsb\bbr\brk\bk(\b()\b) f\bfu\bun\bnc\bct\bti\bio\bon\bns\bs a\bar\bre\be h\bhi\bis\bst\bto\bor\bri\bic\bca\bal\bl c\bcu\bur\bri\bio\bos\bsi\bit\bti\bie\bes\bs l\ble\bef\bft\bt o\bov\bve\ber\br f\bfr\bro\bom\bm |
22536 | e\bea\bar\brl\bli\bie\ber\br d\bda\bay\bys\bs b\bbe\bef\bfo\bor\bre\be t\bth\bhe\be a\bad\bdv\bve\ben\bnt\bt o\bof\bf v\bvi\bir\brt\btu\bua\bal\bl m\bme\bem\bmo\bor\bry\by m\bma\ban\bna\bag\bge\bem\bme\ben\bnt\bt.\b. The b\bbr\brk\bk() |
22537 | function sets the break or lowest address of a process's data segment |
22538 | (uninitialized data) to _\ba_\bd_\bd_\br (immediately above bss). Data addressing is |
22539 | restricted between _\ba_\bd_\bd_\br and the lowest stack pointer to the stack |
22540 | segment. Memory is allocated by b\bbr\brk\bk() in page size pieces; if _\ba_\bd_\bd_\br is |
22541 | not evenly divisible by the system page size, it is increased to the next |
22542 | page boundary. |
22543 | |
22544 | The current value of the program break is reliably returned by |
22545 | ``sbrk(0)'' (see also end(3)). The getrlimit(2) system call may be used |
22546 | to determine the maximum permissible size of the _\bd_\ba_\bt_\ba segment; it will |
22547 | not be possible to set the break beyond the _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx value returned from |
22548 | a call to getrlimit(2), e.g., ``etext + rlp->rlim_max'' (see end(3) for |
22549 | the definition of _\be_\bt_\be_\bx_\bt). |
22550 | |
22551 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22552 | The b\bbr\brk\bk() function returns the value 0 if successful; otherwise the |
22553 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
22554 | error. |
22555 | |
22556 | The s\bsb\bbr\brk\bk() function returns a pointer to the base of the new storage if |
22557 | successful; otherwise -1 with _\be_\br_\br_\bn_\bo set to indicate why the allocation |
22558 | failed. |
22559 | |
22560 | E\bER\bRR\bRO\bOR\bRS\bS |
22561 | s\bsb\bbr\brk\bk() will fail and no additional memory will be allocated if one of the |
22562 | following are true: |
22563 | |
22564 | [ENOMEM] The limit, as set by setrlimit(2), was exceeded. |
22565 | |
22566 | [ENOMEM] The maximum possible size of a data segment (compiled |
22567 | into the system) was exceeded. |
22568 | |
22569 | [ENOMEM] Insufficient space existed in the swap area to support |
22570 | the expansion. |
22571 | |
22572 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22573 | execve(2), getrlimit(2), mmap(2), end(3), malloc(3) |
22574 | |
22575 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
22576 | A b\bbr\brk\bk() function call appeared in Version 7 AT&T UNIX. |
22577 | |
22578 | B\bBU\bUG\bGS\bS |
22579 | Setting the break may fail due to a temporary lack of swap space. It is |
22580 | not possible to distinguish this from a failure caused by exceeding the |
22581 | maximum size of the data segment without consulting getrlimit(2). |
22582 | |
22583 | N\bNA\bAM\bME\bE |
22584 | s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd - yield the processor |
22585 | |
22586 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22587 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsc\bch\bhe\bed\bd.\b.h\bh>\b> |
22588 | |
22589 | _\bi_\bn_\bt |
22590 | s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd(_\bv_\bo_\bi_\bd); |
22591 | |
22592 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22593 | The s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd() function makes the current thread yield the processor |
22594 | and be put at the end of its run queue without altering its priority. |
22595 | |
22596 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22597 | Upon successful completion, the value 0 is returned; otherwise the |
22598 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
22599 | error. |
22600 | |
22601 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
22602 | The s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd() function conforms to IEEE Std 1003.1-2008 |
22603 | (``POSIX.1''). |
22604 | |
22605 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
22606 | The s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd() system call appeared in OpenBSD 4.2. |
22607 | |
22608 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
22609 | The effect of s\bsc\bch\bhe\bed\bd_\b_y\byi\bie\bel\bld\bd() is only precisely defined for real-time |
22610 | scheduling classes, none of which are currently supported by OpenBSD. |
22611 | |
22612 | N\bNA\bAM\bME\bE |
22613 | s\bse\bel\ble\bec\bct\bt, p\bps\bse\bel\ble\bec\bct\bt - synchronous I/O multiplexing |
22614 | |
22615 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22616 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bel\ble\bec\bct\bt.\b.h\bh>\b> |
22617 | |
22618 | _\bi_\bn_\bt |
22619 | s\bse\bel\ble\bec\bct\bt(_\bi_\bn_\bt _\bn_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\br_\be_\ba_\bd_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs, |
22620 | _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt); |
22621 | |
22622 | _\bi_\bn_\bt |
22623 | p\bps\bse\bel\ble\bec\bct\bt(_\bi_\bn_\bt _\bn_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\br_\be_\ba_\bd_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, _\bf_\bd_\b__\bs_\be_\bt _\b*_\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs, |
22624 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\b*_\bt_\bi_\bm_\be_\bo_\bu_\bt, _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bm_\ba_\bs_\bk); |
22625 | |
22626 | F\bFD\bD_\b_S\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
22627 | |
22628 | F\bFD\bD_\b_C\bCL\bLR\bR(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
22629 | |
22630 | F\bFD\bD_\b_I\bIS\bSS\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt); |
22631 | |
22632 | F\bFD\bD_\b_Z\bZE\bER\bRO\bO(_\b&_\bf_\bd_\bs_\be_\bt); |
22633 | |
22634 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22635 | s\bse\bel\ble\bec\bct\bt() examines the I/O descriptor sets whose addresses are passed in |
22636 | _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, and _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs to see if some of their descriptors are |
22637 | ready for reading, are ready for writing, or have an exceptional |
22638 | condition pending, respectively. The first _\bn_\bf_\bd_\bs descriptors are checked |
22639 | in each set; i.e., the descriptors from 0 through _\bn_\bf_\bd_\bs-1 in the |
22640 | descriptor sets are examined. On return, s\bse\bel\ble\bec\bct\bt() replaces the given |
22641 | descriptor sets with subsets consisting of those descriptors that are |
22642 | ready for the requested operation. s\bse\bel\ble\bec\bct\bt() returns the total number of |
22643 | ready descriptors in all the sets. |
22644 | |
22645 | The descriptor sets are stored as bit fields in arrays of integers. The |
22646 | following macros are provided for manipulating such descriptor sets: |
22647 | F\bFD\bD_\b_Z\bZE\bER\bRO\bO(_\b&_\bf_\bd_\bs_\be_\bt) initializes a descriptor set _\bf_\bd_\bs_\be_\bt to the null set. |
22648 | F\bFD\bD_\b_S\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) includes a particular descriptor _\bf_\bd in _\bf_\bd_\bs_\be_\bt. |
22649 | F\bFD\bD_\b_C\bCL\bLR\bR(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) removes _\bf_\bd from _\bf_\bd_\bs_\be_\bt. F\bFD\bD_\b_I\bIS\bSS\bSE\bET\bT(_\bf_\bd, _\b&_\bf_\bd_\bs_\be_\bt) is non- |
22650 | zero if _\bf_\bd is a member of _\bf_\bd_\bs_\be_\bt, zero otherwise. The behavior of these |
22651 | macros is undefined if a descriptor value is less than zero or greater |
22652 | than or equal to FD_SETSIZE, which is normally at least equal to the |
22653 | maximum number of descriptors supported by the system. |
22654 | |
22655 | If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a non-null pointer, it specifies a maximum interval to wait |
22656 | for the selection to complete. If _\bt_\bi_\bm_\be_\bo_\bu_\bt is a null pointer, the select |
22657 | blocks indefinitely. To effect a poll, the _\bt_\bi_\bm_\be_\bo_\bu_\bt argument should be |
22658 | non-null, pointing to a zero-valued timeval structure. _\bt_\bi_\bm_\be_\bo_\bu_\bt is not |
22659 | changed by s\bse\bel\ble\bec\bct\bt(), and may be reused on subsequent calls; however, it |
22660 | is good style to re-initialize it before each invocation of s\bse\bel\ble\bec\bct\bt(). |
22661 | |
22662 | Any of _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, and _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs may be given as null pointers if |
22663 | no descriptors are of interest. |
22664 | |
22665 | The p\bps\bse\bel\ble\bec\bct\bt() function is similar to s\bse\bel\ble\bec\bct\bt() except that it specifies |
22666 | the timeout using a timespec structure. Also, if _\bm_\ba_\bs_\bk is a non-null |
22667 | pointer, p\bps\bse\bel\ble\bec\bct\bt() atomically sets the calling thread's signal mask to |
22668 | the signal set pointed to by _\bm_\ba_\bs_\bk for the duration of the function call. |
22669 | In this case, the original signal mask will be restored before p\bps\bse\bel\ble\bec\bct\bt() |
22670 | returns. |
22671 | |
22672 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22673 | If successful, s\bse\bel\ble\bec\bct\bt() and p\bps\bse\bel\ble\bec\bct\bt() return the number of ready |
22674 | descriptors that are contained in the descriptor sets. If a descriptor |
22675 | is included in multiple descriptor sets, each inclusion is counted |
22676 | separately. If the time limit expires before any descriptors become |
22677 | ready, they return 0. |
22678 | |
22679 | Otherwise, if s\bse\bel\ble\bec\bct\bt() or p\bps\bse\bel\ble\bec\bct\bt() return with an error, including one |
22680 | due to an interrupted call, they return -1, and the descriptor sets will |
22681 | be unmodified. |
22682 | |
22683 | E\bER\bRR\bRO\bOR\bRS\bS |
22684 | An error return from s\bse\bel\ble\bec\bct\bt() or p\bps\bse\bel\ble\bec\bct\bt() indicates: |
22685 | |
22686 | [EFAULT] One or more of _\br_\be_\ba_\bd_\bf_\bd_\bs, _\bw_\br_\bi_\bt_\be_\bf_\bd_\bs, or _\be_\bx_\bc_\be_\bp_\bt_\bf_\bd_\bs points |
22687 | outside the process's allocated address space. |
22688 | |
22689 | [EBADF] One of the descriptor sets specified an invalid |
22690 | descriptor. |
22691 | |
22692 | [EINTR] A signal was delivered before the time limit expired |
22693 | and before any of the selected descriptors became |
22694 | ready. |
22695 | |
22696 | [EINVAL] The specified time limit is invalid. One of its |
22697 | components is negative or too large. |
22698 | |
22699 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22700 | accept(2), clock_gettime(2), connect(2), gettimeofday(2), poll(2), |
22701 | read(2), recv(2), send(2), write(2), getdtablesize(3) |
22702 | |
22703 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
22704 | The s\bse\bel\ble\bec\bct\bt() system call first appeared in 4.1cBSD. The p\bps\bse\bel\ble\bec\bct\bt() system |
22705 | call has been available since OpenBSD 5.4. |
22706 | |
22707 | B\bBU\bUG\bGS\bS |
22708 | Although the provision of getdtablesize(3) was intended to allow user |
22709 | programs to be written independent of the kernel limit on the number of |
22710 | open files, the dimension of a sufficiently large bit field for select |
22711 | remains a problem. The default bit size of _\bf_\bd_\b__\bs_\be_\bt is based on the symbol |
22712 | FD_SETSIZE (currently 1024), but that is somewhat smaller than the |
22713 | current kernel limit to the number of open files. However, in order to |
22714 | accommodate programs which might potentially use a larger number of open |
22715 | files with select, it is possible to increase this size within a program |
22716 | by providing a larger definition of FD_SETSIZE before the inclusion of |
22717 | any headers. The kernel will cope, and the userland libraries provided |
22718 | with the system are also ready for large numbers of file descriptors. |
22719 | |
22720 | Alternatively, to be really safe, it is possible to allocate _\bf_\bd_\b__\bs_\be_\bt bit- |
22721 | arrays dynamically. The idea is to permit a program to work properly |
22722 | even if it is execve(2)'d with 4000 file descriptors pre-allocated. The |
22723 | following illustrates the technique which is used by userland libraries: |
22724 | |
22725 | fd_set *fdsr; |
22726 | int max = fd; |
22727 | |
22728 | fdsr = calloc(howmany(max+1, NFDBITS), sizeof(fd_mask)); |
22729 | if (fdsr == NULL) { |
22730 | ... |
22731 | return (-1); |
22732 | } |
22733 | FD_SET(fd, fdsr); |
22734 | n = select(max+1, fdsr, NULL, NULL, &tv); |
22735 | ... |
22736 | free(fdsr); |
22737 | |
22738 | Alternatively, it is possible to use the poll(2) interface. poll(2) is |
22739 | more efficient when the size of s\bse\bel\ble\bec\bct\bt()'s _\bf_\bd_\b__\bs_\be_\bt bit-arrays are very |
22740 | large, and for fixed numbers of file descriptors one need not size and |
22741 | dynamically allocate a memory object. |
22742 | |
22743 | s\bse\bel\ble\bec\bct\bt() should probably have been designed to return the time remaining |
22744 | from the original timeout, if any, by modifying the time value in place. |
22745 | Even though some systems stupidly act in this different way, it is |
22746 | unlikely this semantic will ever be commonly implemented, as the change |
22747 | causes massive source code compatibility problems. Furthermore, recent |
22748 | new standards have dictated the current behaviour. In general, due to |
22749 | the existence of those brain-damaged non-conforming systems, it is unwise |
22750 | to assume that the timeout value will be unmodified by the s\bse\bel\ble\bec\bct\bt() call, |
22751 | and the caller should reinitialize it on each invocation. Calculating |
22752 | the delta is easily done by calling gettimeofday(2) before and after the |
22753 | call to s\bse\bel\ble\bec\bct\bt(), and using t\bti\bim\bme\ber\brs\bsu\bub\bb() (as described in getitimer(2)). |
22754 | |
22755 | Internally to the kernel, s\bse\bel\ble\bec\bct\bt() and p\bps\bse\bel\ble\bec\bct\bt() work poorly if multiple |
22756 | processes wait on the same file descriptor. Given that, it is rather |
22757 | surprising to see that many daemons are written that way. |
22758 | |
22759 | N\bNA\bAM\bME\bE |
22760 | s\bse\bem\bmc\bct\btl\bl - semaphore control operations |
22761 | |
22762 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22763 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bem\bm.\b.h\bh>\b> |
22764 | |
22765 | _\bi_\bn_\bt |
22766 | s\bse\bem\bmc\bct\btl\bl(_\bi_\bn_\bt _\bs_\be_\bm_\bi_\bd, _\bi_\bn_\bt _\bs_\be_\bm_\bn_\bu_\bm, _\bi_\bn_\bt _\bc_\bm_\bd, _\bu_\bn_\bi_\bo_\bn _\bs_\be_\bm_\bu_\bn _\ba_\br_\bg); |
22767 | |
22768 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22769 | The s\bse\bem\bmc\bct\btl\bl() system call provides a number of control operations on the |
22770 | semaphore specified by _\bs_\be_\bm_\bn_\bu_\bm and _\bs_\be_\bm_\bi_\bd. The operation to be performed |
22771 | is specified in _\bc_\bm_\bd (see below). _\ba_\br_\bg is a union of the following fields: |
22772 | |
22773 | int val; /* value for SETVAL */ |
22774 | struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */ |
22775 | u_short *array; /* array for GETALL & SETALL */ |
22776 | |
22777 | The semid_ds structure used in the IPC_SET and IPC_STAT commands is |
22778 | defined as follows in <_\bs_\by_\bs_\b/_\bs_\be_\bm_\b._\bh>: |
22779 | |
22780 | struct semid_ds { |
22781 | struct ipc_perm sem_perm; /* operation permissions */ |
22782 | struct sem *sem_base; /* semaphore set */ |
22783 | u_short sem_nsems; /* number of sems in set */ |
22784 | time_t sem_otime; /* last operation time */ |
22785 | time_t sem_ctime; /* last change time */ |
22786 | }; |
22787 | |
22788 | The ipc_perm structure used inside the semid_ds structure is defined in |
22789 | <_\bs_\by_\bs_\b/_\bi_\bp_\bc_\b._\bh> and looks like this: |
22790 | |
22791 | struct ipc_perm { |
22792 | uid_t cuid; /* creator user id */ |
22793 | gid_t cgid; /* creator group id */ |
22794 | uid_t uid; /* user id */ |
22795 | gid_t gid; /* group id */ |
22796 | mode_t mode; /* r/w permission (see chmod(2)) */ |
22797 | u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ |
22798 | key_t key; /* user specified msg/sem/shm key */ |
22799 | }; |
22800 | |
22801 | s\bse\bem\bmc\bct\btl\bl() provides the following operations: |
22802 | |
22803 | GETVAL Return the value of the semaphore. |
22804 | |
22805 | SETVAL Set the value of the semaphore to _\ba_\br_\bg_\b._\bv_\ba_\bl. |
22806 | |
22807 | GETPID Return the pid of the last process that did an operation on |
22808 | this semaphore. |
22809 | |
22810 | GETNCNT Return the number of processes waiting to acquire the |
22811 | semaphore. |
22812 | |
22813 | GETZCNT Return the number of processes waiting for the value of the |
22814 | semaphore to reach 0. |
22815 | |
22816 | GETALL Return the values for all the semaphores associated with |
22817 | _\bs_\be_\bm_\bi_\bd. |
22818 | |
22819 | SETALL Set the values for all the semaphores that are associated with |
22820 | the semaphore identifier _\bs_\be_\bm_\bi_\bd to the corresponding values in |
22821 | _\ba_\br_\bg_\b._\ba_\br_\br_\ba_\by. |
22822 | |
22823 | IPC_STAT Gather statistics about a semaphore and place the information |
22824 | in the semid_ds structure pointed to by _\ba_\br_\bg_\b._\bb_\bu_\bf (see above). |
22825 | |
22826 | IPC_SET Set the value of the _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd, _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and |
22827 | _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be fields in the structure associated with the |
22828 | semaphore. The values are taken from the corresponding fields |
22829 | in the structure pointed to by _\ba_\br_\bg_\b._\bb_\bu_\bf. This operation can |
22830 | only be executed by the superuser, or a process that has an |
22831 | effective user ID equal to either _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or |
22832 | _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd in the data structure associated with the message |
22833 | queue. |
22834 | |
22835 | IPC_RMID Remove the semaphores associated with _\bs_\be_\bm_\bi_\bd from the system |
22836 | and destroy the data structures associated with it. Only the |
22837 | superuser or a process with an effective UID equal to the |
22838 | _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd values in the data structure |
22839 | associated with the semaphore can do this. |
22840 | |
22841 | The permission to read or change a message queue (see semop(2)) is |
22842 | determined by the _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be field in the same way as is done with |
22843 | files (see chmod(2)), but the effective UID can match either the |
22844 | _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd field or the _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd field, and the effective GID can |
22845 | match either _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd or _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd. |
22846 | |
22847 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22848 | For the GETVAL, GETPID, GETNCNT, and GETZCNT operations, s\bse\bem\bmc\bct\btl\bl() returns |
22849 | one of the values described above if successful. All other operations |
22850 | will make s\bse\bem\bmc\bct\btl\bl() return 0 if no errors occur. Otherwise -1 is returned |
22851 | and _\be_\br_\br_\bn_\bo set to reflect the error. |
22852 | |
22853 | E\bER\bRR\bRO\bOR\bRS\bS |
22854 | s\bse\bem\bmc\bct\btl\bl() will fail if: |
22855 | |
22856 | [EPERM] _\bc_\bm_\bd is equal to IPC_SET or IPC_RMID and the caller is |
22857 | not the superuser, nor does the effective UID match |
22858 | either the _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd or _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd fields of the |
22859 | data structure associated with the message queue. |
22860 | |
22861 | [EACCES] The caller has no operation permission for this |
22862 | semaphore. |
22863 | |
22864 | [EINVAL] _\bs_\be_\bm_\bi_\bd is not a valid message semaphore identifier. |
22865 | |
22866 | _\bc_\bm_\bd is not a valid command. |
22867 | |
22868 | [EFAULT] _\ba_\br_\bg_\b._\bb_\bu_\bf or _\ba_\br_\bg_\b._\ba_\br_\br_\ba_\by specify an invalid address. |
22869 | |
22870 | [ERANGE] _\bc_\bm_\bd is equal to SETVAL or SETALL and _\ba_\br_\bg_\b._\bv_\ba_\bl or the |
22871 | values in _\ba_\br_\bg_\b._\ba_\br_\br_\ba_\by are greater than the system- |
22872 | imposed limit. |
22873 | |
22874 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22875 | semget(2), semop(2) |
22876 | |
22877 | N\bNA\bAM\bME\bE |
22878 | s\bse\bem\bmg\bge\bet\bt - get semaphore set |
22879 | |
22880 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22881 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bem\bm.\b.h\bh>\b> |
22882 | |
22883 | _\bi_\bn_\bt |
22884 | s\bse\bem\bmg\bge\bet\bt(_\bk_\be_\by_\b__\bt _\bk_\be_\by, _\bi_\bn_\bt _\bn_\bs_\be_\bm_\bs, _\bi_\bn_\bt _\bs_\be_\bm_\bf_\bl_\bg); |
22885 | |
22886 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22887 | The s\bse\bem\bmg\bge\bet\bt() system call returns the semaphore identifier associated with |
22888 | _\bk_\be_\by. |
22889 | |
22890 | A new set containing _\bn_\bs_\be_\bm_\bs semaphores is created if either _\bk_\be_\by is equal |
22891 | to IPC_PRIVATE, or _\bk_\be_\by does not have a semaphore set associated with it |
22892 | and the IPC_CREAT bit is set in _\bs_\be_\bm_\bf_\bl_\bg. |
22893 | |
22894 | The access modes of the created semaphores is specified in _\bs_\be_\bm_\bf_\bl_\bg as a |
22895 | bitwise OR of zero or more of the following values: |
22896 | |
22897 | SEM_A alter permission for owner |
22898 | SEM_R read permission for owner |
22899 | |
22900 | SEM_A >> 3 alter permission for group |
22901 | SEM_R >> 3 read permission for group |
22902 | |
22903 | SEM_A >> 6 alter permission for other |
22904 | SEM_R >> 6 read permission for other |
22905 | |
22906 | If a new set of semaphores is created, the data structure associated with |
22907 | it (the _\bs_\be_\bm_\bi_\bd_\b__\bd_\bs structure, see semctl(2)) is initialized as follows: |
22908 | |
22909 | +\b+\bo\bo _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd and _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd are set to the effective UID of the |
22910 | calling process. |
22911 | |
22912 | +\b+\bo\bo _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd are set to the effective GID of the |
22913 | calling process. |
22914 | |
22915 | +\b+\bo\bo _\bs_\be_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be is set to the lower 9 bits of _\bs_\be_\bm_\bf_\bl_\bg. |
22916 | |
22917 | +\b+\bo\bo _\bs_\be_\bm_\b__\bn_\bs_\be_\bm_\bs is set to the value of _\bn_\bs_\be_\bm_\bs. |
22918 | |
22919 | +\b+\bo\bo _\bs_\be_\bm_\b__\bc_\bt_\bi_\bm_\be is set to the current time. |
22920 | |
22921 | +\b+\bo\bo _\bs_\be_\bm_\b__\bo_\bt_\bi_\bm_\be is set to 0. |
22922 | |
22923 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
22924 | s\bse\bem\bmg\bge\bet\bt() returns a non-negative semaphore identifier if successful. |
22925 | Otherwise, -1 is returned and _\be_\br_\br_\bn_\bo is set to reflect the error. |
22926 | |
22927 | E\bER\bRR\bRO\bOR\bRS\bS |
22928 | [EACCES] The caller has no permission to access a semaphore set |
22929 | already associated with _\bk_\be_\by. |
22930 | |
22931 | [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _\bs_\be_\bm_\bf_\bl_\bg, and a |
22932 | semaphore set is already associated with _\bk_\be_\by. |
22933 | |
22934 | [EINVAL] _\bn_\bs_\be_\bm_\bs is less than or equal to 0 or greater than the |
22935 | system limit for the number in a semaphore set. |
22936 | |
22937 | A semaphore set associated with _\bk_\be_\by exists, but has |
22938 | fewer semaphores than the number specified in _\bn_\bs_\be_\bm_\bs. |
22939 | |
22940 | [ENOSPC] A new set of semaphores could not be created because |
22941 | the system limit for the number of semaphores or the |
22942 | number of semaphore sets has been reached. |
22943 | |
22944 | [ENOENT] IPC_CREAT was not set in _\bs_\be_\bm_\bf_\bl_\bg and no semaphore set |
22945 | associated with _\bk_\be_\by was found. |
22946 | |
22947 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
22948 | semctl(2), semop(2), ftok(3) |
22949 | |
22950 | N\bNA\bAM\bME\bE |
22951 | s\bse\bem\bmo\bop\bp - semaphore operations |
22952 | |
22953 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
22954 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bse\bem\bm.\b.h\bh>\b> |
22955 | |
22956 | _\bi_\bn_\bt |
22957 | s\bse\bem\bmo\bop\bp(_\bi_\bn_\bt _\bs_\be_\bm_\bi_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\be_\bm_\bb_\bu_\bf _\b*_\bs_\bo_\bp_\bs, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bs_\bo_\bp_\bs); |
22958 | |
22959 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
22960 | s\bse\bem\bmo\bop\bp() provides a number of atomic operations on a set of semaphores. |
22961 | The semaphore set is specified by _\bs_\be_\bm_\bi_\bd. _\bs_\bo_\bp_\bs is an array of semaphore |
22962 | operations, _\bn_\bs_\bo_\bp_\bs is the number of operations in this array. The _\bs_\be_\bm_\bb_\bu_\bf |
22963 | structures in the array contain the following members: |
22964 | |
22965 | u_short sem_num; /* semaphore # */ |
22966 | short sem_op; /* semaphore operation */ |
22967 | short sem_flg; /* operation flags */ |
22968 | |
22969 | Each operation (specified in _\bs_\be_\bm_\b__\bo_\bp) is applied to semaphore number |
22970 | _\bs_\be_\bm_\b__\bn_\bu_\bm in the set of semaphores specified by _\bs_\be_\bm_\bi_\bd. The value of _\bs_\be_\bm_\b__\bo_\bp |
22971 | determines the action taken in the following way: |
22972 | |
22973 | +\b+\bo\bo _\bs_\be_\bm_\b__\bo_\bp is less than 0. The current process is blocked until the |
22974 | value of the semaphore is greater than or equal to the absolute value |
22975 | of _\bs_\be_\bm_\b__\bo_\bp. The absolute value of _\bs_\be_\bm_\b__\bo_\bp is then subtracted from the |
22976 | value of the semaphore, and the calling process continues. Negative |
22977 | values of _\bs_\be_\bm_\b__\bo_\bp are thus used to enter critical regions. |
22978 | |
22979 | +\b+\bo\bo _\bs_\be_\bm_\b__\bo_\bp is greater than 0. Its value is added to the value of the |
22980 | specified semaphore. This is used to leave critical regions. |
22981 | |
22982 | +\b+\bo\bo _\bs_\be_\bm_\b__\bo_\bp is equal to 0. The calling process is blocked until the value |
22983 | of the specified semaphore reaches 0. |
22984 | |
22985 | The behavior of each operation is influenced by the flags set in _\bs_\be_\bm_\b__\bf_\bl_\bg |
22986 | in the following way: |
22987 | |
22988 | IPC_NOWAIT In the case where the calling process would normally block, |
22989 | waiting for a semaphore to reach a certain value, IPC_NOWAIT |
22990 | makes the call return immediately, returning a value of -1 |
22991 | and setting _\be_\br_\br_\bn_\bo to EAGAIN. |
22992 | |
22993 | SEM_UNDO Keep track of the changes that this call makes to the value |
22994 | of a semaphore, so that they can be undone when the calling |
22995 | process terminates. This is useful to prevent other |
22996 | processes waiting on a semaphore to block forever, should |
22997 | the process that has the semaphore locked terminate in a |
22998 | critical section. |
22999 | |
23000 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23001 | Upon successful completion, the value 0 is returned; otherwise the |
23002 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
23003 | error. |
23004 | |
23005 | E\bER\bRR\bRO\bOR\bRS\bS |
23006 | s\bse\bem\bmo\bop\bp() will fail if: |
23007 | |
23008 | [EINVAL] There is no semaphore associated with _\bs_\be_\bm_\bi_\bd. |
23009 | |
23010 | [EIDRM] The semaphore set was removed while the process was |
23011 | waiting for one of its semaphores to reach a certain |
23012 | value. |
23013 | |
23014 | [EACCES] The calling process has no permission to access the |
23015 | specified semaphore set. |
23016 | |
23017 | [E2BIG] The value of _\bn_\bs_\bo_\bp_\bs is too big. The maximum is |
23018 | specified in MAX_SOPS in <_\bs_\by_\bs_\b/_\bs_\be_\bm_\b._\bh>. |
23019 | |
23020 | [EFBIG] _\bs_\be_\bm_\b__\bn_\bu_\bm in one of the sem_buf structures is less than |
23021 | 0, or greater than the actual number of semaphores in |
23022 | the set specified by _\bs_\be_\bm_\bi_\bd. |
23023 | |
23024 | [ENOSPC] SEM_UNDO was requested, and there is not enough space |
23025 | left in the kernel to store the undo information. |
23026 | |
23027 | [EAGAIN] The requested operation can not immediately be |
23028 | performed, and IPC_NOWAIT was set in _\bs_\be_\bm_\b__\bf_\bl_\bg. |
23029 | |
23030 | [EFAULT] _\bs_\bo_\bp_\bs points to an illegal address. |
23031 | |
23032 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23033 | semctl(2), semget(2) |
23034 | |
23035 | N\bNA\bAM\bME\bE |
23036 | s\bse\ben\bnd\bd, s\bse\ben\bnd\bdt\bto\bo, s\bse\ben\bnd\bdm\bms\bsg\bg - send a message from a socket |
23037 | |
23038 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23039 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
23040 | |
23041 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23042 | s\bse\ben\bnd\bd(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
23043 | |
23044 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23045 | s\bse\ben\bnd\bdt\bto\bo(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, |
23046 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bt_\bo, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bt_\bo_\bl_\be_\bn); |
23047 | |
23048 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23049 | s\bse\ben\bnd\bdm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
23050 | |
23051 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23052 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() are used to transmit a message to another |
23053 | socket. s\bse\ben\bnd\bd() may be used only when the socket is in a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd state, |
23054 | while s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may be used at any time. |
23055 | |
23056 | The address of the target is given by _\bt_\bo with _\bt_\bo_\bl_\be_\bn specifying its size. |
23057 | The length of the message is given by _\bl_\be_\bn. If the message is too long to |
23058 | pass atomically through the underlying protocol, the error EMSGSIZE is |
23059 | returned, and the message is not transmitted. |
23060 | |
23061 | No indication of failure to deliver is implicit in a s\bse\ben\bnd\bd(). Locally |
23062 | detected errors are indicated by a return value of -1. |
23063 | |
23064 | If no messages space is available at the socket to hold the message to be |
23065 | transmitted, then s\bse\ben\bnd\bd() normally blocks, unless the socket has been |
23066 | placed in non-blocking I/O mode. The select(2) or poll(2) system calls |
23067 | may be used to determine when it is possible to send more data. |
23068 | |
23069 | The _\bf_\bl_\ba_\bg_\bs parameter may include one or more of the following: |
23070 | |
23071 | MSG_DONTROUTE bypass routing tables, silently ignored |
23072 | MSG_DONTWAIT don't block |
23073 | MSG_EOR terminate the record (SOCK_SEQPACKET only) |
23074 | MSG_NOSIGNAL don't send SIGPIPE |
23075 | MSG_OOB process out-of-band data |
23076 | |
23077 | The flag MSG_OOB is used to send ``out-of-band'' data on sockets that |
23078 | support this notion (e.g., SOCK_STREAM); the underlying protocol must |
23079 | also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not |
23080 | to send the SIGPIPE signal if an attempt to send is made on a socket that |
23081 | is shut down for writing or no longer connected. |
23082 | |
23083 | See recv(2) for a description of the _\bm_\bs_\bg_\bh_\bd_\br structure. |
23084 | |
23085 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23086 | The call returns the number of characters sent, or -1 if an error |
23087 | occurred. |
23088 | |
23089 | E\bER\bRR\bRO\bOR\bRS\bS |
23090 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() fail if: |
23091 | |
23092 | [EBADF] An invalid descriptor was specified. |
23093 | |
23094 | [ENOTSOCK] The argument _\bs is not a socket. |
23095 | |
23096 | [EFAULT] An invalid user space address was specified for a |
23097 | parameter. |
23098 | |
23099 | [EMSGSIZE] The socket requires that message be sent atomically, |
23100 | and the size of the message to be sent made this |
23101 | impossible. |
23102 | |
23103 | [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT |
23104 | flag is set and the requested operation would block. |
23105 | |
23106 | [ENOBUFS] The system was unable to allocate an internal buffer. |
23107 | The operation may succeed when buffers become |
23108 | available. |
23109 | |
23110 | [ENOBUFS] The output queue for a network interface was full. |
23111 | This generally indicates that the interface has |
23112 | stopped sending, but may be caused by transient |
23113 | congestion. |
23114 | |
23115 | [EACCES] The SO_BROADCAST option is not set on the socket, and |
23116 | a broadcast address was given as the destination. |
23117 | |
23118 | [EHOSTUNREACH] The destination address specified an unreachable host. |
23119 | |
23120 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs parameter is invalid. |
23121 | |
23122 | [EHOSTDOWN] The destination address specified a host that is down. |
23123 | |
23124 | [ENETDOWN] The destination address specified a network that is |
23125 | down. |
23126 | |
23127 | [ECONNREFUSED] The destination host rejected the message (or a |
23128 | previous one). This error can only be returned by |
23129 | connected sockets. |
23130 | |
23131 | [ENOPROTOOPT] There was a problem sending the message. This error |
23132 | can only be returned by connected sockets. |
23133 | |
23134 | [EDESTADDRREQ] The socket is not connected, and no destination |
23135 | address was specified. |
23136 | |
23137 | [EPIPE] The socket is shut down for writing or not longer |
23138 | connected and the MSG_NOSIGNAL flag is set. |
23139 | |
23140 | In addition, s\bse\ben\bnd\bd() and s\bse\ben\bnd\bdt\bto\bo() may return the following error: |
23141 | |
23142 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
23143 | |
23144 | s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
23145 | |
23146 | [EAFNOSUPPORT] Addresses in the specified address family cannot be |
23147 | used with this socket. |
23148 | |
23149 | [EISCONN] The socket is already connected, and a destination |
23150 | address was specified. |
23151 | |
23152 | s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
23153 | |
23154 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
23155 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
23156 | |
23157 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
23158 | than IOV_MAX. |
23159 | |
23160 | [EMFILE] The message contains control information utilizing |
23161 | CMSG_DATA(3) to pass file descriptors, but too many |
23162 | file descriptors are already in-flight. |
23163 | |
23164 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23165 | fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), |
23166 | write(2), CMSG_DATA(3) |
23167 | |
23168 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
23169 | The s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() functions conform to IEEE Std |
23170 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are |
23171 | extensions to that specification. |
23172 | |
23173 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23174 | The s\bse\ben\bnd\bd() function call appeared in 4.2BSD. |
23175 | |
23176 | N\bNA\bAM\bME\bE |
23177 | s\bse\ben\bnd\bd, s\bse\ben\bnd\bdt\bto\bo, s\bse\ben\bnd\bdm\bms\bsg\bg - send a message from a socket |
23178 | |
23179 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23180 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
23181 | |
23182 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23183 | s\bse\ben\bnd\bd(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
23184 | |
23185 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23186 | s\bse\ben\bnd\bdt\bto\bo(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, |
23187 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bt_\bo, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bt_\bo_\bl_\be_\bn); |
23188 | |
23189 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23190 | s\bse\ben\bnd\bdm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
23191 | |
23192 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23193 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() are used to transmit a message to another |
23194 | socket. s\bse\ben\bnd\bd() may be used only when the socket is in a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd state, |
23195 | while s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may be used at any time. |
23196 | |
23197 | The address of the target is given by _\bt_\bo with _\bt_\bo_\bl_\be_\bn specifying its size. |
23198 | The length of the message is given by _\bl_\be_\bn. If the message is too long to |
23199 | pass atomically through the underlying protocol, the error EMSGSIZE is |
23200 | returned, and the message is not transmitted. |
23201 | |
23202 | No indication of failure to deliver is implicit in a s\bse\ben\bnd\bd(). Locally |
23203 | detected errors are indicated by a return value of -1. |
23204 | |
23205 | If no messages space is available at the socket to hold the message to be |
23206 | transmitted, then s\bse\ben\bnd\bd() normally blocks, unless the socket has been |
23207 | placed in non-blocking I/O mode. The select(2) or poll(2) system calls |
23208 | may be used to determine when it is possible to send more data. |
23209 | |
23210 | The _\bf_\bl_\ba_\bg_\bs parameter may include one or more of the following: |
23211 | |
23212 | MSG_DONTROUTE bypass routing tables, silently ignored |
23213 | MSG_DONTWAIT don't block |
23214 | MSG_EOR terminate the record (SOCK_SEQPACKET only) |
23215 | MSG_NOSIGNAL don't send SIGPIPE |
23216 | MSG_OOB process out-of-band data |
23217 | |
23218 | The flag MSG_OOB is used to send ``out-of-band'' data on sockets that |
23219 | support this notion (e.g., SOCK_STREAM); the underlying protocol must |
23220 | also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not |
23221 | to send the SIGPIPE signal if an attempt to send is made on a socket that |
23222 | is shut down for writing or no longer connected. |
23223 | |
23224 | See recv(2) for a description of the _\bm_\bs_\bg_\bh_\bd_\br structure. |
23225 | |
23226 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23227 | The call returns the number of characters sent, or -1 if an error |
23228 | occurred. |
23229 | |
23230 | E\bER\bRR\bRO\bOR\bRS\bS |
23231 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() fail if: |
23232 | |
23233 | [EBADF] An invalid descriptor was specified. |
23234 | |
23235 | [ENOTSOCK] The argument _\bs is not a socket. |
23236 | |
23237 | [EFAULT] An invalid user space address was specified for a |
23238 | parameter. |
23239 | |
23240 | [EMSGSIZE] The socket requires that message be sent atomically, |
23241 | and the size of the message to be sent made this |
23242 | impossible. |
23243 | |
23244 | [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT |
23245 | flag is set and the requested operation would block. |
23246 | |
23247 | [ENOBUFS] The system was unable to allocate an internal buffer. |
23248 | The operation may succeed when buffers become |
23249 | available. |
23250 | |
23251 | [ENOBUFS] The output queue for a network interface was full. |
23252 | This generally indicates that the interface has |
23253 | stopped sending, but may be caused by transient |
23254 | congestion. |
23255 | |
23256 | [EACCES] The SO_BROADCAST option is not set on the socket, and |
23257 | a broadcast address was given as the destination. |
23258 | |
23259 | [EHOSTUNREACH] The destination address specified an unreachable host. |
23260 | |
23261 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs parameter is invalid. |
23262 | |
23263 | [EHOSTDOWN] The destination address specified a host that is down. |
23264 | |
23265 | [ENETDOWN] The destination address specified a network that is |
23266 | down. |
23267 | |
23268 | [ECONNREFUSED] The destination host rejected the message (or a |
23269 | previous one). This error can only be returned by |
23270 | connected sockets. |
23271 | |
23272 | [ENOPROTOOPT] There was a problem sending the message. This error |
23273 | can only be returned by connected sockets. |
23274 | |
23275 | [EDESTADDRREQ] The socket is not connected, and no destination |
23276 | address was specified. |
23277 | |
23278 | [EPIPE] The socket is shut down for writing or not longer |
23279 | connected and the MSG_NOSIGNAL flag is set. |
23280 | |
23281 | In addition, s\bse\ben\bnd\bd() and s\bse\ben\bnd\bdt\bto\bo() may return the following error: |
23282 | |
23283 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
23284 | |
23285 | s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
23286 | |
23287 | [EAFNOSUPPORT] Addresses in the specified address family cannot be |
23288 | used with this socket. |
23289 | |
23290 | [EISCONN] The socket is already connected, and a destination |
23291 | address was specified. |
23292 | |
23293 | s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
23294 | |
23295 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
23296 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
23297 | |
23298 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
23299 | than IOV_MAX. |
23300 | |
23301 | [EMFILE] The message contains control information utilizing |
23302 | CMSG_DATA(3) to pass file descriptors, but too many |
23303 | file descriptors are already in-flight. |
23304 | |
23305 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23306 | fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), |
23307 | write(2), CMSG_DATA(3) |
23308 | |
23309 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
23310 | The s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() functions conform to IEEE Std |
23311 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are |
23312 | extensions to that specification. |
23313 | |
23314 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23315 | The s\bse\ben\bnd\bd() function call appeared in 4.2BSD. |
23316 | |
23317 | N\bNA\bAM\bME\bE |
23318 | s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg - send a message to syslogd |
23319 | |
23320 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23321 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
23322 | |
23323 | _\bi_\bn_\bt |
23324 | s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
23325 | |
23326 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23327 | s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg() is used to transmit a syslog(3) formatted message direct to |
23328 | syslogd(8) without requiring the allocation of a socket. This is used |
23329 | internally by syslog_r(3), so that messages can be sent during difficult |
23330 | situations. |
23331 | |
23332 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23333 | Upon successful completion, the value 0 is returned; otherwise the |
23334 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
23335 | error. |
23336 | |
23337 | E\bER\bRR\bRO\bOR\bRS\bS |
23338 | s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg() can fail if: |
23339 | |
23340 | [ENOTCONN] The message cannot be sent, likely because syslogd(8) |
23341 | is not running. |
23342 | |
23343 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23344 | syslog_r(3), syslogd(8) |
23345 | |
23346 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23347 | The s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg() function call appeared in OpenBSD 5.6. |
23348 | |
23349 | N\bNA\bAM\bME\bE |
23350 | s\bse\ben\bnd\bd, s\bse\ben\bnd\bdt\bto\bo, s\bse\ben\bnd\bdm\bms\bsg\bg - send a message from a socket |
23351 | |
23352 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23353 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
23354 | |
23355 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23356 | s\bse\ben\bnd\bd(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
23357 | |
23358 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23359 | s\bse\ben\bnd\bdt\bto\bo(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bm_\bs_\bg, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, |
23360 | _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\ba_\bd_\bd_\br _\b*_\bt_\bo, _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bt_\bo_\bl_\be_\bn); |
23361 | |
23362 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
23363 | s\bse\ben\bnd\bdm\bms\bsg\bg(_\bi_\bn_\bt _\bs, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bm_\bs_\bg_\bh_\bd_\br _\b*_\bm_\bs_\bg, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
23364 | |
23365 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23366 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() are used to transmit a message to another |
23367 | socket. s\bse\ben\bnd\bd() may be used only when the socket is in a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd state, |
23368 | while s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may be used at any time. |
23369 | |
23370 | The address of the target is given by _\bt_\bo with _\bt_\bo_\bl_\be_\bn specifying its size. |
23371 | The length of the message is given by _\bl_\be_\bn. If the message is too long to |
23372 | pass atomically through the underlying protocol, the error EMSGSIZE is |
23373 | returned, and the message is not transmitted. |
23374 | |
23375 | No indication of failure to deliver is implicit in a s\bse\ben\bnd\bd(). Locally |
23376 | detected errors are indicated by a return value of -1. |
23377 | |
23378 | If no messages space is available at the socket to hold the message to be |
23379 | transmitted, then s\bse\ben\bnd\bd() normally blocks, unless the socket has been |
23380 | placed in non-blocking I/O mode. The select(2) or poll(2) system calls |
23381 | may be used to determine when it is possible to send more data. |
23382 | |
23383 | The _\bf_\bl_\ba_\bg_\bs parameter may include one or more of the following: |
23384 | |
23385 | MSG_DONTROUTE bypass routing tables, silently ignored |
23386 | MSG_DONTWAIT don't block |
23387 | MSG_EOR terminate the record (SOCK_SEQPACKET only) |
23388 | MSG_NOSIGNAL don't send SIGPIPE |
23389 | MSG_OOB process out-of-band data |
23390 | |
23391 | The flag MSG_OOB is used to send ``out-of-band'' data on sockets that |
23392 | support this notion (e.g., SOCK_STREAM); the underlying protocol must |
23393 | also support ``out-of-band'' data. MSG_NOSIGNAL is used to request not |
23394 | to send the SIGPIPE signal if an attempt to send is made on a socket that |
23395 | is shut down for writing or no longer connected. |
23396 | |
23397 | See recv(2) for a description of the _\bm_\bs_\bg_\bh_\bd_\br structure. |
23398 | |
23399 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23400 | The call returns the number of characters sent, or -1 if an error |
23401 | occurred. |
23402 | |
23403 | E\bER\bRR\bRO\bOR\bRS\bS |
23404 | s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() fail if: |
23405 | |
23406 | [EBADF] An invalid descriptor was specified. |
23407 | |
23408 | [ENOTSOCK] The argument _\bs is not a socket. |
23409 | |
23410 | [EFAULT] An invalid user space address was specified for a |
23411 | parameter. |
23412 | |
23413 | [EMSGSIZE] The socket requires that message be sent atomically, |
23414 | and the size of the message to be sent made this |
23415 | impossible. |
23416 | |
23417 | [EAGAIN] The socket is marked non-blocking or the MSG_DONTWAIT |
23418 | flag is set and the requested operation would block. |
23419 | |
23420 | [ENOBUFS] The system was unable to allocate an internal buffer. |
23421 | The operation may succeed when buffers become |
23422 | available. |
23423 | |
23424 | [ENOBUFS] The output queue for a network interface was full. |
23425 | This generally indicates that the interface has |
23426 | stopped sending, but may be caused by transient |
23427 | congestion. |
23428 | |
23429 | [EACCES] The SO_BROADCAST option is not set on the socket, and |
23430 | a broadcast address was given as the destination. |
23431 | |
23432 | [EHOSTUNREACH] The destination address specified an unreachable host. |
23433 | |
23434 | [EINVAL] The _\bf_\bl_\ba_\bg_\bs parameter is invalid. |
23435 | |
23436 | [EHOSTDOWN] The destination address specified a host that is down. |
23437 | |
23438 | [ENETDOWN] The destination address specified a network that is |
23439 | down. |
23440 | |
23441 | [ECONNREFUSED] The destination host rejected the message (or a |
23442 | previous one). This error can only be returned by |
23443 | connected sockets. |
23444 | |
23445 | [ENOPROTOOPT] There was a problem sending the message. This error |
23446 | can only be returned by connected sockets. |
23447 | |
23448 | [EDESTADDRREQ] The socket is not connected, and no destination |
23449 | address was specified. |
23450 | |
23451 | [EPIPE] The socket is shut down for writing or not longer |
23452 | connected and the MSG_NOSIGNAL flag is set. |
23453 | |
23454 | In addition, s\bse\ben\bnd\bd() and s\bse\ben\bnd\bdt\bto\bo() may return the following error: |
23455 | |
23456 | [EINVAL] _\bl_\be_\bn was larger than SSIZE_MAX. |
23457 | |
23458 | s\bse\ben\bnd\bdt\bto\bo() and s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
23459 | |
23460 | [EAFNOSUPPORT] Addresses in the specified address family cannot be |
23461 | used with this socket. |
23462 | |
23463 | [EISCONN] The socket is already connected, and a destination |
23464 | address was specified. |
23465 | |
23466 | s\bse\ben\bnd\bdm\bms\bsg\bg() may return the following errors: |
23467 | |
23468 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bm_\bs_\bg_\b__\bi_\bo_\bv array |
23469 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
23470 | |
23471 | [EMSGSIZE] The _\bm_\bs_\bg_\b__\bi_\bo_\bv_\bl_\be_\bn member of _\bm_\bs_\bg was less than 0 or larger |
23472 | than IOV_MAX. |
23473 | |
23474 | [EMFILE] The message contains control information utilizing |
23475 | CMSG_DATA(3) to pass file descriptors, but too many |
23476 | file descriptors are already in-flight. |
23477 | |
23478 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23479 | fcntl(2), getsockopt(2), poll(2), recv(2), select(2), socket(2), |
23480 | write(2), CMSG_DATA(3) |
23481 | |
23482 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
23483 | The s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdt\bto\bo(), and s\bse\ben\bnd\bdm\bms\bsg\bg() functions conform to IEEE Std |
23484 | 1003.1-2008 (``POSIX.1''). The MSG_DONTWAIT and MSG_NOSIGNAL flags are |
23485 | extensions to that specification. |
23486 | |
23487 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23488 | The s\bse\ben\bnd\bd() function call appeared in 4.2BSD. |
23489 | |
23490 | N\bNA\bAM\bME\bE |
23491 | s\bse\bet\btu\bui\bid\bd, s\bse\bet\bte\beu\bui\bid\bd, s\bse\bet\btg\bgi\bid\bd, s\bse\bet\bte\beg\bgi\bid\bd - set user and group ID |
23492 | |
23493 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23494 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
23495 | |
23496 | _\bi_\bn_\bt |
23497 | s\bse\bet\btu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\bu_\bi_\bd); |
23498 | |
23499 | _\bi_\bn_\bt |
23500 | s\bse\bet\bte\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
23501 | |
23502 | _\bi_\bn_\bt |
23503 | s\bse\bet\btg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
23504 | |
23505 | _\bi_\bn_\bt |
23506 | s\bse\bet\bte\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
23507 | |
23508 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23509 | The s\bse\bet\btu\bui\bid\bd() function sets the real and effective user IDs and the saved |
23510 | set-user-ID of the current process to the specified value. The s\bse\bet\btu\bui\bid\bd() |
23511 | function is permitted if the effective user ID is that of the superuser, |
23512 | or if the specified user ID is the same as the effective user ID. If |
23513 | not, but the specified user ID is the same as the real user ID, s\bse\bet\btu\bui\bid\bd() |
23514 | will set the effective user ID to the real user ID. |
23515 | |
23516 | The s\bse\bet\btg\bgi\bid\bd() function sets the real and effective group IDs and the saved |
23517 | set-group-ID of the current process to the specified value. The s\bse\bet\btg\bgi\bid\bd() |
23518 | function is permitted if the effective user ID is that of the superuser, |
23519 | or if the specified group ID is the same as the effective group ID. If |
23520 | not, but the specified group ID is the same as the real group ID, |
23521 | s\bse\bet\btg\bgi\bid\bd() will set the effective group ID to the real group ID. |
23522 | Supplementary group IDs remain unchanged. |
23523 | |
23524 | The s\bse\bet\bte\beu\bui\bid\bd() function (s\bse\bet\bte\beg\bgi\bid\bd()) sets the effective user ID (group ID) |
23525 | of the current process. The effective user ID may be set to the value of |
23526 | the real user ID or the saved set-user-ID (see intro(2) and execve(2)); |
23527 | in this way, the effective user ID of a set-user-ID executable may be |
23528 | toggled by switching to the real user ID, then re-enabled by reverting to |
23529 | the set-user-ID value. Similarly, the effective group ID may be set to |
23530 | the value of the real group ID or the saved set-group-ID. |
23531 | |
23532 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23533 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions return the |
23534 | value 0 if successful; otherwise the value -1 is returned and the global |
23535 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
23536 | |
23537 | E\bER\bRR\bRO\bOR\bRS\bS |
23538 | s\bse\bet\btu\bui\bid\bd() and s\bse\bet\bte\beu\bui\bid\bd() will succeed unless: |
23539 | |
23540 | [EPERM] The user is not the superuser and the requested _\bu_\bi_\bd or |
23541 | _\be_\bu_\bi_\bd is not the process's real, effective, or saved |
23542 | UID. |
23543 | |
23544 | s\bse\bet\btg\bgi\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() will succeed unless: |
23545 | |
23546 | [EPERM] The user is not the superuser and the requested _\bg_\bi_\bd or |
23547 | _\be_\bg_\bi_\bd is not the process's real, effective, or saved |
23548 | GID. |
23549 | |
23550 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23551 | getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), |
23552 | setresgid(2), setresuid(2), setreuid(2) |
23553 | |
23554 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
23555 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions conform to |
23556 | IEEE Std 1003.1-2008 (``POSIX.1''). |
23557 | |
23558 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23559 | The s\bse\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX; s\bse\bet\btg\bgi\bid\bd() |
23560 | in Version 4 AT&T UNIX; and s\bse\bet\bte\beu\bui\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() in 4.2BSD. |
23561 | |
23562 | N\bNA\bAM\bME\bE |
23563 | s\bse\bet\btu\bui\bid\bd, s\bse\bet\bte\beu\bui\bid\bd, s\bse\bet\btg\bgi\bid\bd, s\bse\bet\bte\beg\bgi\bid\bd - set user and group ID |
23564 | |
23565 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23566 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
23567 | |
23568 | _\bi_\bn_\bt |
23569 | s\bse\bet\btu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\bu_\bi_\bd); |
23570 | |
23571 | _\bi_\bn_\bt |
23572 | s\bse\bet\bte\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
23573 | |
23574 | _\bi_\bn_\bt |
23575 | s\bse\bet\btg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
23576 | |
23577 | _\bi_\bn_\bt |
23578 | s\bse\bet\bte\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
23579 | |
23580 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23581 | The s\bse\bet\btu\bui\bid\bd() function sets the real and effective user IDs and the saved |
23582 | set-user-ID of the current process to the specified value. The s\bse\bet\btu\bui\bid\bd() |
23583 | function is permitted if the effective user ID is that of the superuser, |
23584 | or if the specified user ID is the same as the effective user ID. If |
23585 | not, but the specified user ID is the same as the real user ID, s\bse\bet\btu\bui\bid\bd() |
23586 | will set the effective user ID to the real user ID. |
23587 | |
23588 | The s\bse\bet\btg\bgi\bid\bd() function sets the real and effective group IDs and the saved |
23589 | set-group-ID of the current process to the specified value. The s\bse\bet\btg\bgi\bid\bd() |
23590 | function is permitted if the effective user ID is that of the superuser, |
23591 | or if the specified group ID is the same as the effective group ID. If |
23592 | not, but the specified group ID is the same as the real group ID, |
23593 | s\bse\bet\btg\bgi\bid\bd() will set the effective group ID to the real group ID. |
23594 | Supplementary group IDs remain unchanged. |
23595 | |
23596 | The s\bse\bet\bte\beu\bui\bid\bd() function (s\bse\bet\bte\beg\bgi\bid\bd()) sets the effective user ID (group ID) |
23597 | of the current process. The effective user ID may be set to the value of |
23598 | the real user ID or the saved set-user-ID (see intro(2) and execve(2)); |
23599 | in this way, the effective user ID of a set-user-ID executable may be |
23600 | toggled by switching to the real user ID, then re-enabled by reverting to |
23601 | the set-user-ID value. Similarly, the effective group ID may be set to |
23602 | the value of the real group ID or the saved set-group-ID. |
23603 | |
23604 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23605 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions return the |
23606 | value 0 if successful; otherwise the value -1 is returned and the global |
23607 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
23608 | |
23609 | E\bER\bRR\bRO\bOR\bRS\bS |
23610 | s\bse\bet\btu\bui\bid\bd() and s\bse\bet\bte\beu\bui\bid\bd() will succeed unless: |
23611 | |
23612 | [EPERM] The user is not the superuser and the requested _\bu_\bi_\bd or |
23613 | _\be_\bu_\bi_\bd is not the process's real, effective, or saved |
23614 | UID. |
23615 | |
23616 | s\bse\bet\btg\bgi\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() will succeed unless: |
23617 | |
23618 | [EPERM] The user is not the superuser and the requested _\bg_\bi_\bd or |
23619 | _\be_\bg_\bi_\bd is not the process's real, effective, or saved |
23620 | GID. |
23621 | |
23622 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23623 | getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), |
23624 | setresgid(2), setresuid(2), setreuid(2) |
23625 | |
23626 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
23627 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions conform to |
23628 | IEEE Std 1003.1-2008 (``POSIX.1''). |
23629 | |
23630 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23631 | The s\bse\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX; s\bse\bet\btg\bgi\bid\bd() |
23632 | in Version 4 AT&T UNIX; and s\bse\bet\bte\beu\bui\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() in 4.2BSD. |
23633 | |
23634 | N\bNA\bAM\bME\bE |
23635 | s\bse\bet\btu\bui\bid\bd, s\bse\bet\bte\beu\bui\bid\bd, s\bse\bet\btg\bgi\bid\bd, s\bse\bet\bte\beg\bgi\bid\bd - set user and group ID |
23636 | |
23637 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23638 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
23639 | |
23640 | _\bi_\bn_\bt |
23641 | s\bse\bet\btu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\bu_\bi_\bd); |
23642 | |
23643 | _\bi_\bn_\bt |
23644 | s\bse\bet\bte\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
23645 | |
23646 | _\bi_\bn_\bt |
23647 | s\bse\bet\btg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
23648 | |
23649 | _\bi_\bn_\bt |
23650 | s\bse\bet\bte\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
23651 | |
23652 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23653 | The s\bse\bet\btu\bui\bid\bd() function sets the real and effective user IDs and the saved |
23654 | set-user-ID of the current process to the specified value. The s\bse\bet\btu\bui\bid\bd() |
23655 | function is permitted if the effective user ID is that of the superuser, |
23656 | or if the specified user ID is the same as the effective user ID. If |
23657 | not, but the specified user ID is the same as the real user ID, s\bse\bet\btu\bui\bid\bd() |
23658 | will set the effective user ID to the real user ID. |
23659 | |
23660 | The s\bse\bet\btg\bgi\bid\bd() function sets the real and effective group IDs and the saved |
23661 | set-group-ID of the current process to the specified value. The s\bse\bet\btg\bgi\bid\bd() |
23662 | function is permitted if the effective user ID is that of the superuser, |
23663 | or if the specified group ID is the same as the effective group ID. If |
23664 | not, but the specified group ID is the same as the real group ID, |
23665 | s\bse\bet\btg\bgi\bid\bd() will set the effective group ID to the real group ID. |
23666 | Supplementary group IDs remain unchanged. |
23667 | |
23668 | The s\bse\bet\bte\beu\bui\bid\bd() function (s\bse\bet\bte\beg\bgi\bid\bd()) sets the effective user ID (group ID) |
23669 | of the current process. The effective user ID may be set to the value of |
23670 | the real user ID or the saved set-user-ID (see intro(2) and execve(2)); |
23671 | in this way, the effective user ID of a set-user-ID executable may be |
23672 | toggled by switching to the real user ID, then re-enabled by reverting to |
23673 | the set-user-ID value. Similarly, the effective group ID may be set to |
23674 | the value of the real group ID or the saved set-group-ID. |
23675 | |
23676 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23677 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions return the |
23678 | value 0 if successful; otherwise the value -1 is returned and the global |
23679 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
23680 | |
23681 | E\bER\bRR\bRO\bOR\bRS\bS |
23682 | s\bse\bet\btu\bui\bid\bd() and s\bse\bet\bte\beu\bui\bid\bd() will succeed unless: |
23683 | |
23684 | [EPERM] The user is not the superuser and the requested _\bu_\bi_\bd or |
23685 | _\be_\bu_\bi_\bd is not the process's real, effective, or saved |
23686 | UID. |
23687 | |
23688 | s\bse\bet\btg\bgi\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() will succeed unless: |
23689 | |
23690 | [EPERM] The user is not the superuser and the requested _\bg_\bi_\bd or |
23691 | _\be_\bg_\bi_\bd is not the process's real, effective, or saved |
23692 | GID. |
23693 | |
23694 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23695 | getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), |
23696 | setresgid(2), setresuid(2), setreuid(2) |
23697 | |
23698 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
23699 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions conform to |
23700 | IEEE Std 1003.1-2008 (``POSIX.1''). |
23701 | |
23702 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23703 | The s\bse\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX; s\bse\bet\btg\bgi\bid\bd() |
23704 | in Version 4 AT&T UNIX; and s\bse\bet\bte\beu\bui\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() in 4.2BSD. |
23705 | |
23706 | N\bNA\bAM\bME\bE |
23707 | s\bse\bet\btg\bgr\bro\bou\bup\bps\bs - set group access list |
23708 | |
23709 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23710 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
23711 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
23712 | |
23713 | _\bi_\bn_\bt |
23714 | s\bse\bet\btg\bgr\bro\bou\bup\bps\bs(_\bi_\bn_\bt _\bn_\bg_\br_\bo_\bu_\bp_\bs, _\bc_\bo_\bn_\bs_\bt _\bg_\bi_\bd_\b__\bt _\b*_\bg_\bi_\bd_\bs_\be_\bt); |
23715 | |
23716 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23717 | s\bse\bet\btg\bgr\bro\bou\bup\bps\bs() sets the group access list of the current user process |
23718 | according to the array _\bg_\bi_\bd_\bs_\be_\bt. The parameter _\bn_\bg_\br_\bo_\bu_\bp_\bs indicates the |
23719 | number of entries in the array and must be no more than {NGROUPS_MAX}. |
23720 | |
23721 | Only the superuser may set new groups. |
23722 | |
23723 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23724 | Upon successful completion, the value 0 is returned; otherwise the |
23725 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
23726 | error. |
23727 | |
23728 | E\bER\bRR\bRO\bOR\bRS\bS |
23729 | The s\bse\bet\btg\bgr\bro\bou\bup\bps\bs() call will fail if: |
23730 | |
23731 | [EINVAL] The value of _\bn_\bg_\br_\bo_\bu_\bp_\bs is greater than {NGROUPS_MAX}. |
23732 | |
23733 | [EPERM] The caller is not the superuser. |
23734 | |
23735 | [EFAULT] The address specified for _\bg_\bi_\bd_\bs_\be_\bt is outside the |
23736 | process address space. |
23737 | |
23738 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23739 | getgroups(2), setgid(2), setregid(2), initgroups(3) |
23740 | |
23741 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23742 | The s\bse\bet\btg\bgr\bro\bou\bup\bps\bs() system call first appeared in 4.1cBSD. |
23743 | |
23744 | N\bNA\bAM\bME\bE |
23745 | g\bge\bet\bti\bit\bti\bim\bme\ber\br, s\bse\bet\bti\bit\bti\bim\bme\ber\br - get/set value of interval timer |
23746 | |
23747 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23748 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
23749 | |
23750 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_R\bRE\bEA\bAL\bL 0\b0 |
23751 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_V\bVI\bIR\bRT\bTU\bUA\bAL\bL 1\b1 |
23752 | #\b#d\bde\bef\bfi\bin\bne\be I\bIT\bTI\bIM\bME\bER\bR_\b_P\bPR\bRO\bOF\bF 2\b2 |
23753 | |
23754 | _\bi_\bn_\bt |
23755 | g\bge\bet\bti\bit\bti\bim\bme\ber\br(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bv_\ba_\bl_\bu_\be); |
23756 | |
23757 | _\bi_\bn_\bt |
23758 | s\bse\bet\bti\bit\bti\bim\bme\ber\br(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bv_\ba_\bl_\bu_\be, |
23759 | _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl _\b*_\bo_\bv_\ba_\bl_\bu_\be); |
23760 | |
23761 | _\bv_\bo_\bi_\bd |
23762 | t\bti\bim\bme\ber\brc\bcl\ble\bea\bar\br(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*); |
23763 | |
23764 | _\bi_\bn_\bt |
23765 | t\bti\bim\bme\ber\bri\bis\bss\bse\bet\bt(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*); |
23766 | |
23767 | _\bi_\bn_\bt |
23768 | t\bti\bim\bme\ber\brc\bcm\bmp\bp(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bC_\bM_\bP); |
23769 | |
23770 | _\bv_\bo_\bi_\bd |
23771 | t\bti\bim\bme\ber\brs\bsu\bub\bb(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\br_\be_\bs); |
23772 | |
23773 | _\bv_\bo_\bi_\bd |
23774 | t\bti\bim\bme\ber\bra\bad\bdd\bd(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\ba, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bb, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\br_\be_\bs); |
23775 | |
23776 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23777 | The system provides each process with three interval timers, defined in |
23778 | <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. The g\bge\bet\bti\bit\bti\bim\bme\ber\br() call returns the current value for the |
23779 | timer specified in _\bw_\bh_\bi_\bc_\bh in the structure at _\bv_\ba_\bl_\bu_\be. The s\bse\bet\bti\bit\bti\bim\bme\ber\br() call |
23780 | sets a timer to the specified _\bv_\ba_\bl_\bu_\be (returning the previous value of the |
23781 | timer if _\bo_\bv_\ba_\bl_\bu_\be is non-null). |
23782 | |
23783 | A timer value is defined by the _\bi_\bt_\bi_\bm_\be_\br_\bv_\ba_\bl structure: |
23784 | |
23785 | struct itimerval { |
23786 | struct timeval it_interval; /* timer interval */ |
23787 | struct timeval it_value; /* current value */ |
23788 | }; |
23789 | |
23790 | If _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be is non-zero, it indicates the time to the next timer |
23791 | expiration. If _\bi_\bt_\b__\bi_\bn_\bt_\be_\br_\bv_\ba_\bl is non-zero, it specifies a value to be used |
23792 | in reloading _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be when the timer expires. Setting _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be to 0 |
23793 | disables a timer. Setting _\bi_\bt_\b__\bi_\bn_\bt_\be_\br_\bv_\ba_\bl to 0 causes a timer to be disabled |
23794 | after its next expiration (assuming _\bi_\bt_\b__\bv_\ba_\bl_\bu_\be is non-zero). |
23795 | |
23796 | Time values smaller than the resolution of the system clock are rounded |
23797 | up to this resolution (typically 10 milliseconds). |
23798 | |
23799 | The ITIMER_REAL timer decrements in real time. A SIGALRM signal is |
23800 | delivered when this timer expires. |
23801 | |
23802 | The ITIMER_VIRTUAL timer decrements in process virtual time. It runs |
23803 | only when the process is executing. A SIGVTALRM signal is delivered when |
23804 | it expires. |
23805 | |
23806 | The ITIMER_PROF timer decrements both in process virtual time and when |
23807 | the system is running on behalf of the process. It is designed to be |
23808 | used by interpreters in statistically profiling the execution of |
23809 | interpreted programs. Each time the ITIMER_PROF timer expires, the |
23810 | SIGPROF signal is delivered. Because this signal may interrupt in- |
23811 | progress system calls, programs using this timer must be prepared to |
23812 | restart interrupted system calls. |
23813 | |
23814 | The remaining five functions are in fact macros for manipulating time |
23815 | values, defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. |
23816 | |
23817 | t\bti\bim\bme\ber\brc\bcl\ble\bea\bar\br(_\ba) sets the time value in _\ba to zero. |
23818 | |
23819 | t\bti\bim\bme\ber\bri\bis\bss\bse\bet\bt(_\ba) tests if the time value in _\ba is non-zero. |
23820 | |
23821 | t\bti\bim\bme\ber\brc\bcm\bmp\bp(_\ba, _\bb, _\bC_\bM_\bP) compares two time values in the form _\ba CMP _\bb, where |
23822 | _\bC_\bM_\bP is <, <=, ==, !=, >=, or > . |
23823 | |
23824 | t\bti\bim\bme\ber\brs\bsu\bub\bb(_\ba, _\bb, _\br_\be_\bs) subtracts _\ba - _\bb and stores the result in _\br_\be_\bs. |
23825 | |
23826 | t\bti\bim\bme\ber\bra\bad\bdd\bd(_\ba, _\bb, _\br_\be_\bs) adds two timers and stores the result in _\br_\be_\bs. |
23827 | |
23828 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23829 | Upon successful completion, the value 0 is returned; otherwise the |
23830 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
23831 | error. |
23832 | |
23833 | E\bER\bRR\bRO\bOR\bRS\bS |
23834 | g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() will fail if: |
23835 | |
23836 | [EFAULT] The _\bv_\ba_\bl_\bu_\be parameter specified a bad address. |
23837 | |
23838 | [EINVAL] An unrecognized value for _\bw_\bh_\bi_\bc_\bh was specified. |
23839 | |
23840 | In addition, s\bse\bet\bti\bit\bti\bim\bme\ber\br() may return the following error: |
23841 | |
23842 | [EINVAL] _\bv_\ba_\bl_\bu_\be or _\bo_\bv_\ba_\bl_\bu_\be specified a time that was too large to |
23843 | be handled. |
23844 | |
23845 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23846 | clock_gettime(2), gettimeofday(2), poll(2), select(2), sigaction(2) |
23847 | |
23848 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
23849 | The g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() functions conform to IEEE Std 1003.1-2008 |
23850 | (``POSIX.1''). |
23851 | |
23852 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23853 | The g\bge\bet\bti\bit\bti\bim\bme\ber\br() and s\bse\bet\bti\bit\bti\bim\bme\ber\br() system calls first appeared in 4.1cBSD. |
23854 | |
23855 | N\bNA\bAM\bME\bE |
23856 | g\bge\bet\btl\blo\bog\bgi\bin\bn, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br, s\bse\bet\btl\blo\bog\bgi\bin\bn - get/set login name |
23857 | |
23858 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23859 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
23860 | |
23861 | _\bc_\bh_\ba_\br _\b* |
23862 | g\bge\bet\btl\blo\bog\bgi\bin\bn(_\bv_\bo_\bi_\bd); |
23863 | |
23864 | _\bi_\bn_\bt |
23865 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br(_\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be, _\bs_\bi_\bz_\be_\b__\bt _\bn_\ba_\bm_\be_\bl_\be_\bn); |
23866 | |
23867 | _\bi_\bn_\bt |
23868 | s\bse\bet\btl\blo\bog\bgi\bin\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be); |
23869 | |
23870 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23871 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() routine returns the login name of the user associated with |
23872 | the current session, as previously set by s\bse\bet\btl\blo\bog\bgi\bin\bn(). The name is |
23873 | normally associated with a login shell at the time a session is created, |
23874 | and is inherited by all processes descended from the login shell. (This |
23875 | is true even if some of those processes assume another user ID, for |
23876 | example when su(1) is used.) |
23877 | |
23878 | The g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() routine is a reentrant version of g\bge\bet\btl\blo\bog\bgi\bin\bn(). It is |
23879 | functionally identical to g\bge\bet\btl\blo\bog\bgi\bin\bn() except that the caller must provide |
23880 | a buffer, _\bn_\ba_\bm_\be, in which to store the user's login name and a |
23881 | corresponding length parameter, _\bn_\ba_\bm_\be_\bl_\be_\bn, that specifies the size of the |
23882 | buffer. The buffer should be large enough to store the login name and a |
23883 | trailing NUL (typically LOGIN_NAME_MAX bytes). |
23884 | |
23885 | s\bse\bet\btl\blo\bog\bgi\bin\bn() sets the login name of the user associated with the current |
23886 | session to _\bn_\ba_\bm_\be. This call is restricted to the superuser, and is |
23887 | normally used only when a new session is being created on behalf of the |
23888 | named user (for example, at login time, or when a remote shell is |
23889 | invoked). |
23890 | |
23891 | _\bN_\bO_\bT_\bE: There is only one login name per session. |
23892 | |
23893 | It is _\bC_\bR_\bI_\bT_\bI_\bC_\bA_\bL_\bL_\bY important to ensure that s\bse\bet\btl\blo\bog\bgi\bin\bn() is only ever called |
23894 | after the process has taken adequate steps to ensure that it is detached |
23895 | from its parent's session. The _\bO_\bN_\bL_\bY way to do this is via the s\bse\bet\bts\bsi\bid\bd() |
23896 | function. The d\bda\bae\bem\bmo\bon\bn() function calls s\bse\bet\bts\bsi\bid\bd() which is an ideal way of |
23897 | detaching from a controlling terminal and forking into the background. |
23898 | |
23899 | In particular, neither i\bio\boc\bct\btl\bl(_\bt_\bt_\by_\bf_\bd, _\bT_\bI_\bO_\bC_\bN_\bO_\bT_\bT_\bY, _\b._\b._\b.) nor s\bse\bet\btp\bpg\bgr\brp\bp(_\b._\b._\b.) is |
23900 | sufficient to create a new session. |
23901 | |
23902 | Once a parent process has called s\bse\bet\bts\bsi\bid\bd(), it is acceptable for some |
23903 | child of that process to then call s\bse\bet\btl\blo\bog\bgi\bin\bn(), even though it is not the |
23904 | session leader. Beware, however, that _\bA_\bL_\bL processes in the session will |
23905 | change their login name at the same time, even the parent. |
23906 | |
23907 | This is different from traditional UNIX privilege inheritance and as such |
23908 | can be counter-intuitive. |
23909 | |
23910 | Since the s\bse\bet\btl\blo\bog\bgi\bin\bn() routine is restricted to the super-user, it is |
23911 | assumed that (like all other privileged programs) the programmer has |
23912 | taken adequate precautions to prevent security violations. |
23913 | |
23914 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23915 | If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn() succeeds, it returns a pointer to a NUL- |
23916 | terminated string in a static buffer. If the name has not been set, it |
23917 | returns NULL. If a call to g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() succeeds, a value of 0 is |
23918 | returned, else the error number is returned. If a call to s\bse\bet\btl\blo\bog\bgi\bin\bn() |
23919 | succeeds, a value of 0 is returned. If s\bse\bet\btl\blo\bog\bgi\bin\bn() fails, a value of -1 |
23920 | is returned and an error code is placed in the global location _\be_\br_\br_\bn_\bo. |
23921 | |
23922 | E\bER\bRR\bRO\bOR\bRS\bS |
23923 | g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() and s\bse\bet\btl\blo\bog\bgi\bin\bn() will succeed unless: |
23924 | |
23925 | [EFAULT] The _\bn_\ba_\bm_\be parameter points to an invalid address. |
23926 | |
23927 | In addition, g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() may return the following error: |
23928 | |
23929 | [ERANGE] The value of _\bn_\ba_\bm_\be_\bl_\be_\bn is not large enough to store the |
23930 | user's login name and a trailing NUL. |
23931 | |
23932 | s\bse\bet\btl\blo\bog\bgi\bin\bn() may return the following errors: |
23933 | |
23934 | [EINVAL] The _\bn_\ba_\bm_\be parameter pointed to a string that was too |
23935 | long. Login names are limited to LOGIN_NAME_MAX-1 |
23936 | characters, currently 31. |
23937 | |
23938 | [EPERM] The caller tried to set the login name and was not the |
23939 | superuser. |
23940 | |
23941 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
23942 | setsid(2) |
23943 | |
23944 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
23945 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() and g\bge\bet\btl\blo\bog\bgi\bin\bn_\b_r\br() functions conform to IEEE Std 1003.1-2008 |
23946 | (``POSIX.1''). |
23947 | |
23948 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
23949 | The g\bge\bet\btl\blo\bog\bgi\bin\bn() function first appeared in 4.2BSD. |
23950 | |
23951 | B\bBU\bUG\bGS\bS |
23952 | In earlier versions of the system, g\bge\bet\btl\blo\bog\bgi\bin\bn() failed unless the process |
23953 | was associated with a login terminal. The current implementation (using |
23954 | s\bse\bet\btl\blo\bog\bgi\bin\bn()) allows getlogin to succeed even when the process has no |
23955 | controlling terminal. In earlier versions of the system, the value |
23956 | returned by g\bge\bet\btl\blo\bog\bgi\bin\bn() could not be trusted without checking the user ID. |
23957 | Portable programs should probably still make this check. |
23958 | |
23959 | N\bNA\bAM\bME\bE |
23960 | s\bse\bet\btp\bpg\bgi\bid\bd, s\bse\bet\btp\bpg\bgr\brp\bp - set process group |
23961 | |
23962 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
23963 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
23964 | |
23965 | _\bi_\bn_\bt |
23966 | s\bse\bet\btp\bpg\bgi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bp_\bi_\bd_\b__\bt _\bp_\bg_\br_\bp); |
23967 | |
23968 | _\bi_\bn_\bt |
23969 | s\bse\bet\btp\bpg\bgr\brp\bp(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bp_\bi_\bd_\b__\bt _\bp_\bg_\br_\bp); |
23970 | |
23971 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
23972 | s\bse\bet\btp\bpg\bgi\bid\bd() sets the process group of the specified process _\bp_\bi_\bd to the |
23973 | specified _\bp_\bg_\br_\bp. If _\bp_\bi_\bd is zero, then the call applies to the current |
23974 | process. If _\bp_\bg_\br_\bp is zero, the process ID of the specified process is |
23975 | used. |
23976 | |
23977 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
23978 | Upon successful completion, the value 0 is returned; otherwise the |
23979 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
23980 | error. |
23981 | |
23982 | E\bER\bRR\bRO\bOR\bRS\bS |
23983 | s\bse\bet\btp\bpg\bgi\bid\bd() will fail and the process group will not be altered if: |
23984 | |
23985 | [EACCES] The value of the _\bp_\bi_\bd argument matches the process ID |
23986 | of a child process of the calling process, and the |
23987 | child process has successfully executed one of the |
23988 | exec functions. |
23989 | |
23990 | [EINVAL] The value of the _\bp_\bg_\br_\bp argument is less than zero. |
23991 | |
23992 | [EPERM] The requested process is a descendant of the calling |
23993 | process, and is either a session leader or not in the |
23994 | same session as the calling process. |
23995 | |
23996 | [EPERM] The value of the _\bp_\bg_\br_\bp argument is neither the PID of |
23997 | the process indicated by the _\bp_\bi_\bd argument nor the |
23998 | process group ID of an existing process group in the |
23999 | same session as the calling process. |
24000 | |
24001 | [ESRCH] The value of the _\bp_\bi_\bd argument does not match the |
24002 | process ID of the calling process or of a descendant |
24003 | of the calling process. |
24004 | |
24005 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24006 | getpgrp(2), setsid(2) |
24007 | |
24008 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24009 | s\bse\bet\btp\bpg\bgr\brp\bp() is identical to s\bse\bet\btp\bpg\bgi\bid\bd(), and is retained for calling |
24010 | convention compatibility with historical versions of BSD. |
24011 | |
24012 | The s\bse\bet\btp\bpg\bgi\bid\bd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
24013 | |
24014 | N\bNA\bAM\bME\bE |
24015 | s\bse\bet\btp\bpg\bgi\bid\bd, s\bse\bet\btp\bpg\bgr\brp\bp - set process group |
24016 | |
24017 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24018 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
24019 | |
24020 | _\bi_\bn_\bt |
24021 | s\bse\bet\btp\bpg\bgi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bp_\bi_\bd_\b__\bt _\bp_\bg_\br_\bp); |
24022 | |
24023 | _\bi_\bn_\bt |
24024 | s\bse\bet\btp\bpg\bgr\brp\bp(_\bp_\bi_\bd_\b__\bt _\bp_\bi_\bd, _\bp_\bi_\bd_\b__\bt _\bp_\bg_\br_\bp); |
24025 | |
24026 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24027 | s\bse\bet\btp\bpg\bgi\bid\bd() sets the process group of the specified process _\bp_\bi_\bd to the |
24028 | specified _\bp_\bg_\br_\bp. If _\bp_\bi_\bd is zero, then the call applies to the current |
24029 | process. If _\bp_\bg_\br_\bp is zero, the process ID of the specified process is |
24030 | used. |
24031 | |
24032 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24033 | Upon successful completion, the value 0 is returned; otherwise the |
24034 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
24035 | error. |
24036 | |
24037 | E\bER\bRR\bRO\bOR\bRS\bS |
24038 | s\bse\bet\btp\bpg\bgi\bid\bd() will fail and the process group will not be altered if: |
24039 | |
24040 | [EACCES] The value of the _\bp_\bi_\bd argument matches the process ID |
24041 | of a child process of the calling process, and the |
24042 | child process has successfully executed one of the |
24043 | exec functions. |
24044 | |
24045 | [EINVAL] The value of the _\bp_\bg_\br_\bp argument is less than zero. |
24046 | |
24047 | [EPERM] The requested process is a descendant of the calling |
24048 | process, and is either a session leader or not in the |
24049 | same session as the calling process. |
24050 | |
24051 | [EPERM] The value of the _\bp_\bg_\br_\bp argument is neither the PID of |
24052 | the process indicated by the _\bp_\bi_\bd argument nor the |
24053 | process group ID of an existing process group in the |
24054 | same session as the calling process. |
24055 | |
24056 | [ESRCH] The value of the _\bp_\bi_\bd argument does not match the |
24057 | process ID of the calling process or of a descendant |
24058 | of the calling process. |
24059 | |
24060 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24061 | getpgrp(2), setsid(2) |
24062 | |
24063 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24064 | s\bse\bet\btp\bpg\bgr\brp\bp() is identical to s\bse\bet\btp\bpg\bgi\bid\bd(), and is retained for calling |
24065 | convention compatibility with historical versions of BSD. |
24066 | |
24067 | The s\bse\bet\btp\bpg\bgi\bid\bd() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
24068 | |
24069 | N\bNA\bAM\bME\bE |
24070 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by, s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by - get/set process scheduling priority |
24071 | |
24072 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24073 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
24074 | |
24075 | _\bi_\bn_\bt |
24076 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bi_\bd_\b__\bt _\bw_\bh_\bo); |
24077 | |
24078 | _\bi_\bn_\bt |
24079 | s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by(_\bi_\bn_\bt _\bw_\bh_\bi_\bc_\bh, _\bi_\bd_\b__\bt _\bw_\bh_\bo, _\bi_\bn_\bt _\bp_\br_\bi_\bo); |
24080 | |
24081 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24082 | The scheduling priority of the process, process group, or user, as |
24083 | indicated by _\bw_\bh_\bi_\bc_\bh and _\bw_\bh_\bo is obtained with the g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call and |
24084 | set with the s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call. _\bw_\bh_\bi_\bc_\bh is one of PRIO_PROCESS, |
24085 | PRIO_PGRP, or PRIO_USER, and _\bw_\bh_\bo is interpreted relative to _\bw_\bh_\bi_\bc_\bh (a |
24086 | process identifier for PRIO_PROCESS, process group identifier for |
24087 | PRIO_PGRP, and a user ID for PRIO_USER). A zero value of _\bw_\bh_\bo denotes the |
24088 | current process, process group, or user. _\bp_\br_\bi_\bo is a value in the range |
24089 | -20 to 20. The default priority is 0; lower priorities cause more |
24090 | favorable scheduling. |
24091 | |
24092 | The g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call returns the highest priority (lowest numerical |
24093 | value) enjoyed by any of the specified processes. The s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call |
24094 | sets the priorities of all of the specified processes to the specified |
24095 | value. Priority values outside the range -20 to 20 are truncated to the |
24096 | appropriate limit. Only the superuser may lower priorities. |
24097 | |
24098 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24099 | Since g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() can legitimately return the value -1, it is necessary |
24100 | to clear the external variable _\be_\br_\br_\bn_\bo prior to the call, then check it |
24101 | afterward to determine if a -1 is an error or a legitimate value. The |
24102 | s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() call returns 0 if there is no error, or -1 if there is. |
24103 | |
24104 | E\bER\bRR\bRO\bOR\bRS\bS |
24105 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() will fail if: |
24106 | |
24107 | [ESRCH] No process was located using the _\bw_\bh_\bi_\bc_\bh and _\bw_\bh_\bo values |
24108 | specified. |
24109 | |
24110 | [EINVAL] _\bw_\bh_\bi_\bc_\bh was not one of PRIO_PROCESS, PRIO_PGRP, or |
24111 | PRIO_USER. |
24112 | |
24113 | In addition, s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() will fail if: |
24114 | |
24115 | [EPERM] A process was located, but neither its effective nor |
24116 | real user ID matched the effective user ID of the |
24117 | caller. |
24118 | |
24119 | [EACCES] A non-superuser attempted to lower a process priority. |
24120 | |
24121 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24122 | nice(1), fork(2), renice(8) |
24123 | |
24124 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24125 | The g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() functions conform to IEEE Std |
24126 | 1003.1-2008 (``POSIX.1''). |
24127 | |
24128 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24129 | The predecessor of these functions, the former n\bni\bic\bce\be() system call, |
24130 | appeared in Version 3 AT&T UNIX and was removed in 4.3BSD-Reno. The |
24131 | g\bge\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() and s\bse\bet\btp\bpr\bri\bio\bor\bri\bit\bty\by() system calls appeared in 4.1cBSD. |
24132 | |
24133 | N\bNA\bAM\bME\bE |
24134 | s\bse\bet\btr\bre\beg\bgi\bid\bd - set real and effective group IDs |
24135 | |
24136 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24137 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
24138 | |
24139 | _\bi_\bn_\bt |
24140 | s\bse\bet\btr\bre\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
24141 | |
24142 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24143 | The real and effective group IDs of the current process are set according |
24144 | to the arguments. The saved group ID will be set to the new value of the |
24145 | real group ID if a real group ID is specified and either the new real |
24146 | group ID value is different from the current value or the new value of |
24147 | the effective group ID differs from the current saved group ID. |
24148 | |
24149 | Unprivileged users may change either group ID to the current value of the |
24150 | real, effective, or saved group ID. Only the superuser may make other |
24151 | changes. |
24152 | |
24153 | Supplying a value of -1 for either the real or effective group ID forces |
24154 | the system to substitute the current ID in place of the -1 parameter. |
24155 | |
24156 | The s\bse\bet\btr\bre\beg\bgi\bid\bd() function was intended to allow swapping the real and |
24157 | effective group IDs in set-group-ID programs to temporarily relinquish |
24158 | the set-group-ID value. This purpose is now better served by the use of |
24159 | the setegid(2) function. |
24160 | |
24161 | When setting the real and effective group IDs to the same value, the |
24162 | setgid(2) function is preferred. |
24163 | |
24164 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24165 | Upon successful completion, the value 0 is returned; otherwise the |
24166 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
24167 | error. |
24168 | |
24169 | E\bER\bRR\bRO\bOR\bRS\bS |
24170 | [EPERM] The current process is not the superuser and a change |
24171 | other than changing the effective group ID to the real |
24172 | group ID was specified. |
24173 | |
24174 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24175 | getgid(2), setegid(2), setgid(2), setresgid(2), setreuid(2) |
24176 | |
24177 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24178 | The s\bse\bet\btr\bre\beg\bgi\bid\bd() function conforms to the IEEE Std 1003.1-2008 |
24179 | (``POSIX.1'') specification, except that the conditions for changing the |
24180 | saved group ID differ and that, if it is changed, the saved group ID is |
24181 | set to the real group ID instead of the effective group ID. |
24182 | |
24183 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24184 | The s\bse\bet\btr\bre\beg\bgi\bid\bd() system call first appeared in 4.1cBSD, predating POSIX. A |
24185 | semantically different version appeared in 4.4BSD. The current version, |
24186 | with the original semantics restored, appeared in OpenBSD 3.3. |
24187 | |
24188 | N\bNA\bAM\bME\bE |
24189 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd, g\bge\bet\btr\bre\bes\bsu\bui\bid\bd, s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd, s\bse\bet\btr\bre\bes\bsu\bui\bid\bd - get or set real, effective |
24190 | and saved user or group ID |
24191 | |
24192 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24193 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
24194 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
24195 | |
24196 | _\bi_\bn_\bt |
24197 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\b*_\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\bs_\bg_\bi_\bd); |
24198 | |
24199 | _\bi_\bn_\bt |
24200 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\b*_\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\bs_\bu_\bi_\bd); |
24201 | |
24202 | _\bi_\bn_\bt |
24203 | s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\bs_\bg_\bi_\bd); |
24204 | |
24205 | _\bi_\bn_\bt |
24206 | s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\bs_\bu_\bi_\bd); |
24207 | |
24208 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24209 | The s\bse\bet\btr\bre\bes\bsu\bui\bid\bd() function sets the real, effective and saved user IDs of |
24210 | the current process. The analogous s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd() sets the real, effective |
24211 | and saved group IDs. |
24212 | |
24213 | Privileged processes may set these IDs to arbitrary values. Unprivileged |
24214 | processes are restricted in that each of the new IDs must match one of |
24215 | the current IDs. |
24216 | |
24217 | Passing -1 as an argument causes the corresponding value to remain |
24218 | unchanged. |
24219 | |
24220 | The g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() and g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() calls retrieve the real, effective, and |
24221 | saved group and user IDs of the current process, respectively. |
24222 | |
24223 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24224 | Upon successful completion, the value 0 is returned; otherwise the |
24225 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
24226 | error. |
24227 | |
24228 | E\bER\bRR\bRO\bOR\bRS\bS |
24229 | [EPERM] The calling process was not privileged and tried to |
24230 | change one or more IDs to a value which was not the |
24231 | current real ID, the current effective ID nor the |
24232 | current saved ID. |
24233 | |
24234 | [EFAULT] An address passed to g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() or g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() was |
24235 | invalid. |
24236 | |
24237 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24238 | getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), |
24239 | setregid(2), setreuid(2), setuid(2) |
24240 | |
24241 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24242 | These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') |
24243 | specification. While they are not completely portable, they are the |
24244 | least ambiguous way to manage user and group IDs. |
24245 | |
24246 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24247 | These functions first appeared in HP-UX. |
24248 | |
24249 | N\bNA\bAM\bME\bE |
24250 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd, g\bge\bet\btr\bre\bes\bsu\bui\bid\bd, s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd, s\bse\bet\btr\bre\bes\bsu\bui\bid\bd - get or set real, effective |
24251 | and saved user or group ID |
24252 | |
24253 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24254 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
24255 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
24256 | |
24257 | _\bi_\bn_\bt |
24258 | g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\b*_\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\b*_\bs_\bg_\bi_\bd); |
24259 | |
24260 | _\bi_\bn_\bt |
24261 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\b*_\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\b*_\bs_\bu_\bi_\bd); |
24262 | |
24263 | _\bi_\bn_\bt |
24264 | s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\br_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd, _\bg_\bi_\bd_\b__\bt _\bs_\bg_\bi_\bd); |
24265 | |
24266 | _\bi_\bn_\bt |
24267 | s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\bs_\bu_\bi_\bd); |
24268 | |
24269 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24270 | The s\bse\bet\btr\bre\bes\bsu\bui\bid\bd() function sets the real, effective and saved user IDs of |
24271 | the current process. The analogous s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd() sets the real, effective |
24272 | and saved group IDs. |
24273 | |
24274 | Privileged processes may set these IDs to arbitrary values. Unprivileged |
24275 | processes are restricted in that each of the new IDs must match one of |
24276 | the current IDs. |
24277 | |
24278 | Passing -1 as an argument causes the corresponding value to remain |
24279 | unchanged. |
24280 | |
24281 | The g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() and g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() calls retrieve the real, effective, and |
24282 | saved group and user IDs of the current process, respectively. |
24283 | |
24284 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24285 | Upon successful completion, the value 0 is returned; otherwise the |
24286 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
24287 | error. |
24288 | |
24289 | E\bER\bRR\bRO\bOR\bRS\bS |
24290 | [EPERM] The calling process was not privileged and tried to |
24291 | change one or more IDs to a value which was not the |
24292 | current real ID, the current effective ID nor the |
24293 | current saved ID. |
24294 | |
24295 | [EFAULT] An address passed to g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd() or g\bge\bet\btr\bre\bes\bsu\bui\bid\bd() was |
24296 | invalid. |
24297 | |
24298 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24299 | getegid(2), geteuid(2), getgid(2), getuid(2), issetugid(2), setgid(2), |
24300 | setregid(2), setreuid(2), setuid(2) |
24301 | |
24302 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24303 | These functions are not part of the IEEE Std 1003.1 (``POSIX.1'') |
24304 | specification. While they are not completely portable, they are the |
24305 | least ambiguous way to manage user and group IDs. |
24306 | |
24307 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24308 | These functions first appeared in HP-UX. |
24309 | |
24310 | N\bNA\bAM\bME\bE |
24311 | s\bse\bet\btr\bre\beu\bui\bid\bd - set real and effective user IDs |
24312 | |
24313 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24314 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
24315 | |
24316 | _\bi_\bn_\bt |
24317 | s\bse\bet\btr\bre\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\br_\bu_\bi_\bd, _\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
24318 | |
24319 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24320 | The real and effective user IDs of the current process are set according |
24321 | to the arguments. The saved user ID will be set to the new value of the |
24322 | real user ID if a real user ID is specified and either the new real user |
24323 | ID value is different from the current value or the new value of the |
24324 | effective user ID differs from the current saved user ID. |
24325 | |
24326 | Unprivileged users may change either user ID to the current value of the |
24327 | real, effective, or saved user ID. Only the superuser may make other |
24328 | changes. |
24329 | |
24330 | Supplying a value of -1 for either the real or effective user ID forces |
24331 | the system to substitute the current ID in place of the -1 parameter. |
24332 | |
24333 | The s\bse\bet\btr\bre\beu\bui\bid\bd() function was intended to allow swapping the real and |
24334 | effective user IDs in set-user-ID programs to temporarily relinquish the |
24335 | set-user-ID value. This purpose is now better served by the use of the |
24336 | seteuid(2) function. |
24337 | |
24338 | When setting the real and effective user IDs to the same value, the |
24339 | setuid(2) function is preferred. |
24340 | |
24341 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24342 | Upon successful completion, the value 0 is returned; otherwise the |
24343 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
24344 | error. |
24345 | |
24346 | E\bER\bRR\bRO\bOR\bRS\bS |
24347 | [EPERM] The current process is not the superuser and a change |
24348 | other than changing the effective user ID to the real |
24349 | user ID was specified. |
24350 | |
24351 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24352 | getuid(2), seteuid(2), setregid(2), setresuid(2), setuid(2) |
24353 | |
24354 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24355 | The s\bse\bet\btr\bre\beu\bui\bid\bd() function conforms to the IEEE Std 1003.1-2008 |
24356 | (``POSIX.1'') specification, except that the conditions for changing the |
24357 | saved user ID differ and that, if it is changed, the saved user ID is set |
24358 | to the real user ID instead of the effective user ID. |
24359 | |
24360 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24361 | The s\bse\bet\btr\bre\beu\bui\bid\bd() system call first appeared in 4.1cBSD, predating POSIX. A |
24362 | semantically different version appeared in 4.4BSD. The current version, |
24363 | with the original semantics restored, appeared in OpenBSD 3.3. |
24364 | |
24365 | N\bNA\bAM\bME\bE |
24366 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt, s\bse\bet\btr\brl\bli\bim\bmi\bit\bt - control maximum system resource consumption |
24367 | |
24368 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24369 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
24370 | |
24371 | _\bi_\bn_\bt |
24372 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt(_\bi_\bn_\bt _\br_\be_\bs_\bo_\bu_\br_\bc_\be, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bl_\bi_\bm_\bi_\bt _\b*_\br_\bl_\bp); |
24373 | |
24374 | _\bi_\bn_\bt |
24375 | s\bse\bet\btr\brl\bli\bim\bmi\bit\bt(_\bi_\bn_\bt _\br_\be_\bs_\bo_\bu_\br_\bc_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\br_\bl_\bi_\bm_\bi_\bt _\b*_\br_\bl_\bp); |
24376 | |
24377 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24378 | Limits on the consumption of system resources by the current process and |
24379 | each process it creates may be obtained with the g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() call, and |
24380 | set with the s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() call. |
24381 | |
24382 | The _\br_\be_\bs_\bo_\bu_\br_\bc_\be parameter is one of the following: |
24383 | |
24384 | RLIMIT_CORE The largest size (in bytes) _\bc_\bo_\br_\be file that may be |
24385 | created. |
24386 | |
24387 | RLIMIT_CPU The maximum amount of CPU time (in seconds) to be used by |
24388 | each process. |
24389 | |
24390 | RLIMIT_DATA The maximum size (in bytes) of the data segment for a |
24391 | process; this includes memory allocated via malloc(3) and |
24392 | all other anonymous memory mapped via mmap(2). |
24393 | |
24394 | RLIMIT_FSIZE The largest size (in bytes) file that may be created. |
24395 | |
24396 | RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into |
24397 | memory using the mlock(2) function. |
24398 | |
24399 | RLIMIT_NOFILE The maximum number of open files for this process. |
24400 | |
24401 | RLIMIT_NPROC The maximum number of simultaneous processes for this |
24402 | user id. |
24403 | |
24404 | RLIMIT_RSS The maximum size (in bytes) to which a process's resident |
24405 | set size may grow. This imposes a limit on the amount of |
24406 | physical memory to be given to a process; if memory is |
24407 | tight, the system will prefer to take memory from |
24408 | processes that are exceeding their declared resident set |
24409 | size. |
24410 | |
24411 | RLIMIT_STACK The maximum size (in bytes) of the stack segment for a |
24412 | process, which defines how far a process's stack segment |
24413 | may be extended. Stack extension is performed |
24414 | automatically by the system, and is only used by the main |
24415 | thread of a process. |
24416 | |
24417 | A resource limit is specified as a soft limit and a hard limit. When a |
24418 | soft limit is exceeded a process may receive a signal (for example, if |
24419 | the CPU time or file size is exceeded), but it will be allowed to |
24420 | continue execution until it reaches the hard limit (or modifies its |
24421 | resource limit). The _\br_\bl_\bi_\bm_\bi_\bt structure is used to specify the hard and |
24422 | soft limits on a resource, |
24423 | |
24424 | struct rlimit { |
24425 | rlim_t rlim_cur; /* current (soft) limit */ |
24426 | rlim_t rlim_max; /* hard limit */ |
24427 | }; |
24428 | |
24429 | Only the superuser may raise the maximum limits. Other users may only |
24430 | alter _\br_\bl_\bi_\bm_\b__\bc_\bu_\br within the range from 0 to _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx or (irreversibly) |
24431 | lower _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx. |
24432 | |
24433 | An ``infinite'' value for a limit is defined as RLIM_INFINITY. |
24434 | |
24435 | A value of RLIM_SAVED_CUR or RLIM_SAVED_MAX will be stored in _\br_\bl_\bi_\bm_\b__\bc_\bu_\br or |
24436 | _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx respectively by g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() if the value for the current or |
24437 | maximum resource limit cannot be stored in an rlim_t. The values |
24438 | RLIM_SAVED_CUR and RLIM_SAVED_MAX should not be used in a call to |
24439 | s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() unless they were returned by a previous call to g\bge\bet\btr\brl\bli\bim\bmi\bit\bt(). |
24440 | |
24441 | Because this information is stored in the per-process information, this |
24442 | system call must be executed directly by the shell if it is to affect all |
24443 | future processes created by the shell; l\bli\bim\bmi\bit\bt is thus a built-in command |
24444 | to csh(1) and u\bul\bli\bim\bmi\bit\bt is the sh(1) equivalent. |
24445 | |
24446 | The system refuses to extend the data or stack space when the limits |
24447 | would be exceeded in the normal way: a brk(2) call fails if the data |
24448 | space limit is reached. When the stack limit is reached, the process |
24449 | receives a segmentation fault (SIGSEGV); if this signal is not caught by |
24450 | a handler using the signal stack, this signal will kill the process. |
24451 | |
24452 | A file I/O operation that would create a file larger than the process' |
24453 | soft limit will cause the write to fail and a signal SIGXFSZ to be |
24454 | generated; this normally terminates the process, but may be caught. When |
24455 | the soft CPU time limit is exceeded, a signal SIGXCPU is sent to the |
24456 | offending process. |
24457 | |
24458 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24459 | Upon successful completion, the value 0 is returned; otherwise the |
24460 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
24461 | error. |
24462 | |
24463 | E\bER\bRR\bRO\bOR\bRS\bS |
24464 | g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() will fail if: |
24465 | |
24466 | [EFAULT] The address specified for _\br_\bl_\bp is invalid. |
24467 | |
24468 | [EINVAL] An unrecognized value for _\br_\be_\bs_\bo_\bu_\br_\bc_\be was specified. |
24469 | |
24470 | In addition, s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() may return the following errors: |
24471 | |
24472 | [EINVAL] The new _\br_\bl_\bi_\bm_\b__\bc_\bu_\br is greater than the new _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx. |
24473 | |
24474 | [EPERM] The new _\br_\bl_\bi_\bm_\b__\bm_\ba_\bx is greater than the current maximum |
24475 | limit value, and the caller is not the superuser. |
24476 | |
24477 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24478 | csh(1), sh(1), quotactl(2), sigaction(2), sigaltstack(2), sysctl(3) |
24479 | |
24480 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24481 | The g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() functions conform to IEEE Std 1003.1-2008 |
24482 | (``POSIX.1''). |
24483 | |
24484 | The RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS resources are non- |
24485 | standard extensions. |
24486 | |
24487 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24488 | The g\bge\bet\btr\brl\bli\bim\bmi\bit\bt() and s\bse\bet\btr\brl\bli\bim\bmi\bit\bt() system calls first appeared in 4.1cBSD. |
24489 | |
24490 | B\bBU\bUG\bGS\bS |
24491 | The RLIMIT_AS resource is missing. |
24492 | |
24493 | N\bNA\bAM\bME\bE |
24494 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be, s\bse\bet\btr\brt\bta\bab\bbl\ble\be - get and set the default routing table of the |
24495 | current process |
24496 | |
24497 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24498 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
24499 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
24500 | |
24501 | _\bi_\bn_\bt |
24502 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be(_\bv_\bo_\bi_\bd); |
24503 | |
24504 | _\bi_\bn_\bt |
24505 | s\bse\bet\btr\brt\bta\bab\bbl\ble\be(_\bi_\bn_\bt _\br_\bt_\ba_\bb_\bl_\be_\bi_\bd); |
24506 | |
24507 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24508 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be() and s\bse\bet\btr\brt\bta\bab\bbl\ble\be() manipulate the routing table and routing |
24509 | domain associated with the current process. |
24510 | |
24511 | Only the superuser is allowed to change the process routing table if it |
24512 | is already set to a non-zero value. |
24513 | |
24514 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24515 | g\bge\bet\btr\brt\bta\bab\bbl\ble\be() returns the routing table of the current process. Upon |
24516 | successful completion, s\bse\bet\btr\brt\bta\bab\bbl\ble\be() returns 0 if the call succeeds, -1 if |
24517 | it fails. |
24518 | |
24519 | E\bER\bRR\bRO\bOR\bRS\bS |
24520 | The call succeeds unless: |
24521 | |
24522 | [EINVAL] The value of the _\br_\bt_\ba_\bb_\bl_\be_\bi_\bd argument is not a valid |
24523 | routing table. |
24524 | |
24525 | [EPERM] The user is not the superuser and the routing table of |
24526 | the calling process is already set to a non-zero |
24527 | value. |
24528 | |
24529 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24530 | getsockopt(2), route(8) |
24531 | |
24532 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24533 | The g\bge\bet\btr\brt\bta\bab\bbl\ble\be() and s\bse\bet\btr\brt\bta\bab\bbl\ble\be() system calls appeared in OpenBSD 4.8. |
24534 | |
24535 | N\bNA\bAM\bME\bE |
24536 | s\bse\bet\bts\bsi\bid\bd - create session and set process group ID |
24537 | |
24538 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24539 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
24540 | |
24541 | _\bp_\bi_\bd_\b__\bt |
24542 | s\bse\bet\bts\bsi\bid\bd(_\bv_\bo_\bi_\bd); |
24543 | |
24544 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24545 | The s\bse\bet\bts\bsi\bid\bd function creates a new session. The calling process is the |
24546 | session leader of the new session, is the process group leader of a new |
24547 | process group and has no controlling terminal. The calling process is |
24548 | the only process in either the session or the process group. |
24549 | |
24550 | Upon successful completion, the s\bse\bet\bts\bsi\bid\bd function returns the value of the |
24551 | process group ID of the new process group, which is the same as the |
24552 | process ID of the calling process. |
24553 | |
24554 | E\bER\bRR\bRO\bOR\bRS\bS |
24555 | If an error occurs, s\bse\bet\bts\bsi\bid\bd returns -1 and the global variable _\be_\br_\br_\bn_\bo is |
24556 | set to indicate the error, as follows: |
24557 | |
24558 | [EPERM] The calling process is already a process group leader, |
24559 | or the process group ID of a process other than the |
24560 | calling process matches the process ID of the calling |
24561 | process. |
24562 | |
24563 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24564 | getsid(2), setpgid(2), tcgetpgrp(3), tcsetpgrp(3) |
24565 | |
24566 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24567 | The s\bse\bet\bts\bsi\bid\bd function is expected to be compliant with the IEEE Std |
24568 | 1003.1-2008 (``POSIX.1'') specification. |
24569 | |
24570 | N\bNA\bAM\bME\bE |
24571 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt, s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt - get and set options on sockets |
24572 | |
24573 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24574 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
24575 | |
24576 | _\bi_\bn_\bt |
24577 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bl_\be_\bv_\be_\bl, _\bi_\bn_\bt _\bo_\bp_\bt_\bn_\ba_\bm_\be, _\bv_\bo_\bi_\bd _\b*_\bo_\bp_\bt_\bv_\ba_\bl, |
24578 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\b*_\bo_\bp_\bt_\bl_\be_\bn); |
24579 | |
24580 | _\bi_\bn_\bt |
24581 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bl_\be_\bv_\be_\bl, _\bi_\bn_\bt _\bo_\bp_\bt_\bn_\ba_\bm_\be, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bo_\bp_\bt_\bv_\ba_\bl, |
24582 | _\bs_\bo_\bc_\bk_\bl_\be_\bn_\b__\bt _\bo_\bp_\bt_\bl_\be_\bn); |
24583 | |
24584 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24585 | g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() manipulate the _\bo_\bp_\bt_\bi_\bo_\bn_\bs associated with a |
24586 | socket. Options may exist at multiple protocol levels; they are always |
24587 | present at the uppermost ``socket'' level. |
24588 | |
24589 | When manipulating socket options the level at which the option resides |
24590 | and the name of the option must be specified. To manipulate options at |
24591 | the socket level, _\bl_\be_\bv_\be_\bl is specified as SOL_SOCKET. To manipulate |
24592 | options at any other level the protocol number of the appropriate |
24593 | protocol controlling the option is supplied. For example, to indicate |
24594 | that an option is to be interpreted by the TCP protocol, _\bl_\be_\bv_\be_\bl should be |
24595 | set to the protocol number of TCP; see getprotoent(3). |
24596 | |
24597 | The parameters _\bo_\bp_\bt_\bv_\ba_\bl and _\bo_\bp_\bt_\bl_\be_\bn are used to access option values for |
24598 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() they identify a buffer in which the value |
24599 | for the requested option(s) are to be returned. For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), _\bo_\bp_\bt_\bl_\be_\bn |
24600 | is a value-result parameter, initially containing the size of the buffer |
24601 | pointed to by _\bo_\bp_\bt_\bv_\ba_\bl, and modified on return to indicate the actual size |
24602 | of the value returned. If no option value is to be supplied or returned, |
24603 | _\bo_\bp_\bt_\bv_\ba_\bl may be NULL. |
24604 | |
24605 | _\bo_\bp_\bt_\bn_\ba_\bm_\be and any specified options are passed uninterpreted to the |
24606 | appropriate protocol module for interpretation. The include file |
24607 | <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh> contains definitions for socket level options, described |
24608 | below. Options at other protocol levels vary in format and name; consult |
24609 | the appropriate entries in section 4 of the manual. |
24610 | |
24611 | Most socket-level options utilize an int parameter for _\bo_\bp_\bt_\bv_\ba_\bl. For |
24612 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), the parameter should be non-zero to enable a boolean |
24613 | option, or zero if the option is to be disabled. SO_LINGER uses a struct |
24614 | linger parameter, defined in <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>, which specifies the desired |
24615 | state of the option and the linger interval (see below). SO_SNDTIMEO and |
24616 | SO_RCVTIMEO use a struct timeval parameter, defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh>. |
24617 | |
24618 | The following options are recognized at the socket level. Except as |
24619 | noted, each may be examined with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and set with s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). |
24620 | |
24621 | SO_DEBUG enables recording of debugging information |
24622 | SO_REUSEADDR enables local address reuse |
24623 | SO_REUSEPORT enables duplicate address and port bindings |
24624 | SO_KEEPALIVE enables keep connections alive |
24625 | SO_DONTROUTE enables routing bypass; not supported |
24626 | SO_LINGER linger on close if data present |
24627 | SO_BROADCAST enables permission to transmit broadcast messages |
24628 | SO_OOBINLINE enables reception of out-of-band data in band |
24629 | SO_BINDANY enables binding to any address |
24630 | SO_SNDBUF set buffer size for output |
24631 | SO_RCVBUF set buffer size for input |
24632 | SO_SNDLOWAT set minimum count for output |
24633 | SO_RCVLOWAT set minimum count for input |
24634 | SO_SNDTIMEO set timeout value for output |
24635 | SO_RCVTIMEO set timeout value for input |
24636 | SO_TIMESTAMP enables reception of a timestamp with datagrams |
24637 | SO_PEERCRED get the credentials from other side of connection |
24638 | SO_RTABLE set the routing table used for route lookups |
24639 | SO_SPLICE splice two sockets together or get data length |
24640 | SO_TYPE get the type of the socket (get only) |
24641 | SO_ERROR get and clear error on the socket (get only) |
24642 | |
24643 | SO_DEBUG enables debugging in the underlying protocol modules. |
24644 | SO_REUSEADDR indicates that the rules used in validating addresses |
24645 | supplied in a bind(2) call should allow reuse of local addresses. |
24646 | SO_REUSEPORT allows completely duplicate bindings by multiple processes |
24647 | if they all set SO_REUSEPORT before binding the port. This option |
24648 | permits multiple instances of a program to each receive UDP/IP multicast |
24649 | or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables |
24650 | the periodic transmission of messages on a connected socket. Should the |
24651 | connected party fail to respond to these messages, the connection is |
24652 | considered broken and processes using the socket are notified via a |
24653 | SIGPIPE signal when attempting to send data. |
24654 | |
24655 | SO_LINGER controls the action taken when unsent messages are queued on |
24656 | socket and a close(2) is performed. If the socket promises reliable |
24657 | delivery of data and SO_LINGER is set, the system will block the process |
24658 | on the close(2) attempt until it is able to transmit the data or until it |
24659 | decides it is unable to deliver the information (a timeout period |
24660 | measured in seconds, termed the linger interval, is specified in the |
24661 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() call when SO_LINGER is requested). If SO_LINGER is disabled |
24662 | and a close(2) is issued, the system will process the close in a manner |
24663 | that allows the process to continue as quickly as possible. |
24664 | |
24665 | The option SO_BROADCAST requests permission to send broadcast datagrams |
24666 | on the socket. Broadcast was a privileged operation in earlier versions |
24667 | of the system. With protocols that support out-of-band data, the |
24668 | SO_OOBINLINE option requests that out-of-band data be placed in the |
24669 | normal data input queue as received; it will then be accessible with |
24670 | recv(2) or read(2) calls without the MSG_OOB flag. Some protocols always |
24671 | behave as if this option is set. |
24672 | |
24673 | SO_BINDANY allows the socket to be bound to addresses which are not local |
24674 | to the machine, so it can be used to make a transparent proxy. Note that |
24675 | this option is limited to the super-user. In order to receive packets |
24676 | for these addresses, SO_BINDANY needs to be combined with matching |
24677 | outgoing pf(4) rules with the _\bd_\bi_\bv_\be_\br_\bt_\b-_\br_\be_\bp_\bl_\by parameter. For example, with |
24678 | the following rule the socket receives packets for 192.168.0.10 even if |
24679 | it is not a local address: |
24680 | |
24681 | pass out inet from 192.168.0.10 divert-reply |
24682 | |
24683 | SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes |
24684 | allocated for output and input buffers, respectively. The buffer size |
24685 | may be increased for high-volume connections, or may be decreased to |
24686 | limit the possible backlog of incoming data. The system places an |
24687 | absolute limit on these values. |
24688 | |
24689 | SO_SNDLOWAT is an option to set the minimum count for output operations. |
24690 | Most output operations process all of the data supplied by the call, |
24691 | delivering data to the protocol for transmission and blocking as |
24692 | necessary for flow control. Nonblocking output operations will process |
24693 | as much data as permitted subject to flow control without blocking, but |
24694 | will process no data if flow control does not allow the smaller of the |
24695 | low water mark value or the entire request to be processed. A select(2) |
24696 | or poll(2) operation testing the ability to write to a socket will return |
24697 | true only if the low water mark amount could be processed. The default |
24698 | value for SO_SNDLOWAT is set to a convenient size for network efficiency, |
24699 | often 1024. SO_RCVLOWAT is an option to set the minimum count for input |
24700 | operations. In general, receive calls will block until any (non-zero) |
24701 | amount of data is received, then return with the smaller of the amount |
24702 | available or the amount requested. The default value for SO_RCVLOWAT is |
24703 | 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls |
24704 | normally wait until they have received the smaller of the low water mark |
24705 | value or the requested amount. Receive calls may still return less than |
24706 | the low water mark if an error occurs, a signal is caught, or the type of |
24707 | data next in the receive queue is different than that returned. |
24708 | |
24709 | SO_SNDTIMEO is an option to set a timeout value for output operations. |
24710 | It accepts a struct timeval parameter with the number of seconds and |
24711 | microseconds used to limit waits for output operations to complete. If a |
24712 | send operation has blocked for this much time, it returns with a partial |
24713 | count or with the error EWOULDBLOCK if no data was sent. In the current |
24714 | implementation, this timer is restarted each time additional data are |
24715 | delivered to the protocol, implying that the limit applies to output |
24716 | portions ranging in size from the low water mark to the high water mark |
24717 | for output. SO_RCVTIMEO is an option to set a timeout value for input |
24718 | operations. It accepts a struct timeval parameter with the number of |
24719 | seconds and microseconds used to limit waits for input operations to |
24720 | complete. In the current implementation, this timer is restarted each |
24721 | time additional data are received by the protocol, and thus the limit is |
24722 | in effect an inactivity timer. If a receive operation has been blocked |
24723 | for this much time without receiving additional data, it returns with a |
24724 | short count or with the error EWOULDBLOCK if no data were received. |
24725 | |
24726 | If the SO_TIMESTAMP option is enabled on a SOCK_DGRAM socket, the |
24727 | recvmsg(2) call will return a timestamp corresponding to when the |
24728 | datagram was received. The msg_control field in the msghdr structure |
24729 | points to a buffer that contains a cmsghdr structure followed by a struct |
24730 | timeval. The cmsghdr fields have the following values: |
24731 | |
24732 | cmsg_len = CMSG_LEN(sizeof(struct timeval)) |
24733 | cmsg_level = SOL_SOCKET |
24734 | cmsg_type = SCM_TIMESTAMP |
24735 | |
24736 | SO_PEERCRED fetches the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bo_\bc_\bk_\bp_\be_\be_\br_\bc_\br_\be_\bd credentials from the other |
24737 | side of the connection (currently only possible on AF_UNIX sockets). |
24738 | These credentials are from the time that bind(2) or connect(2) were |
24739 | called. |
24740 | |
24741 | The SO_RTABLE option gets or sets the routing table which will be used by |
24742 | the socket for address lookups. If a protocol family of the socket |
24743 | doesn't support switching routing tables, the ENOPROTOOPT error is |
24744 | returned. Only the superuser is allowed to change the routing table if |
24745 | it is already set to a non-zero value. A socket's chosen routing table |
24746 | is initialized from the process's configuration, previously selected |
24747 | using setrtable(2). |
24748 | |
24749 | SO_SPLICE can splice together two TCP or UDP sockets for zero-copy data |
24750 | transfers. Both sockets must be of the same type. In the first form, |
24751 | s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() is called with the source socket _\bs and the drain socket's |
24752 | _\bi_\bn_\bt file descriptor as _\bo_\bp_\bt_\bv_\ba_\bl. In the second form, _\bo_\bp_\bt_\bv_\ba_\bl is a _\bs_\bt_\br_\bu_\bc_\bt |
24753 | _\bs_\bp_\bl_\bi_\bc_\be with the drain socket in _\bs_\bp_\b__\bf_\bd, a positive maximum number of bytes |
24754 | or 0 in _\bs_\bp_\b__\bm_\ba_\bx and an idle timeout _\bs_\bp_\b__\bi_\bd_\bl_\be in the form of a _\bs_\bt_\br_\bu_\bc_\bt |
24755 | _\bt_\bi_\bm_\be_\bv_\ba_\bl. If -1 is given as drain socket, the source socket _\bs gets |
24756 | unspliced. Otherwise the spliced data transfer continues within the |
24757 | kernel until the optional maximum is reached, one of the connections |
24758 | terminates, idle timeout expires or an error occurs. A successful |
24759 | select(2), poll(2), or kqueue(2) operation testing the ability to read |
24760 | from the source socket indicates that the splicing has terminated. The |
24761 | error status can be examined with SO_ERROR at the source socket. The |
24762 | ETIMEDOUT error is set if there was no data transferred between two |
24763 | sockets during the _\bs_\bp_\b__\bi_\bd_\bl_\be period of time. The EFBIG error is set after |
24764 | exactly _\bs_\bp_\b__\bm_\ba_\bx bytes have been transferred. Note that if a maximum is |
24765 | given, it is only guaranteed that no more bytes are transferred. A short |
24766 | splice can happen, but then a second call to splice will transfer the |
24767 | remaining data immediately. The SO_SPLICE option with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and |
24768 | an _\bo_\bf_\bf_\b__\bt value as _\bo_\bp_\bt_\bv_\ba_\bl can be used to retrieve the number of bytes |
24769 | transferred so far from the source socket _\bs. A successful new splice |
24770 | resets this number. |
24771 | |
24772 | Finally, SO_TYPE and SO_ERROR are options used only with g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(). |
24773 | SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful |
24774 | for servers that inherit sockets on startup. SO_ERROR returns any |
24775 | pending error on the socket and clears the error status. It may be used |
24776 | to check for asynchronous errors on connected datagram sockets or for |
24777 | other asynchronous errors. |
24778 | |
24779 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24780 | Upon successful completion, the value 0 is returned; otherwise the |
24781 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
24782 | error. |
24783 | |
24784 | E\bER\bRR\bRO\bOR\bRS\bS |
24785 | The call succeeds unless: |
24786 | |
24787 | [EBADF] The argument _\bs is not a valid descriptor. |
24788 | |
24789 | [ENOTSOCK] The argument _\bs is a file, not a socket. |
24790 | |
24791 | [ENOPROTOOPT] The option is unknown at the level indicated. |
24792 | |
24793 | [EOPNOTSUPP] The option is unsupported. |
24794 | |
24795 | [EFAULT] The address pointed to by _\bo_\bp_\bt_\bv_\ba_\bl is not in a valid |
24796 | part of the process address space. For g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), |
24797 | this error may also be returned if _\bo_\bp_\bt_\bl_\be_\bn is not in a |
24798 | valid part of the process address space. |
24799 | |
24800 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24801 | connect(2), getrtable(2), ioctl(2), poll(2), select(2), socket(2), |
24802 | getprotoent(3), divert(4), pf.conf(5), protocols(5), sosplice(9) |
24803 | |
24804 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24805 | The g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() and s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt() functions conform to IEEE Std |
24806 | 1003.1-2008 (``POSIX.1''). |
24807 | |
24808 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24809 | The g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt() system call appeared in 4.2BSD. |
24810 | |
24811 | B\bBU\bUG\bGS\bS |
24812 | Several of the socket options should be handled at lower levels of the |
24813 | system. |
24814 | |
24815 | N\bNA\bAM\bME\bE |
24816 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by, s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by - get/set date and time |
24817 | |
24818 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24819 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
24820 | |
24821 | _\bi_\bn_\bt |
24822 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by(_\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bp, _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be _\b*_\bt_\bz_\bp); |
24823 | |
24824 | _\bi_\bn_\bt |
24825 | s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bp, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be _\b*_\bt_\bz_\bp); |
24826 | |
24827 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24828 | N\bNo\bot\bte\be:\b: t\bti\bim\bme\bez\bzo\bon\bne\be i\bis\bs n\bno\bo l\blo\bon\bng\bge\ber\br u\bus\bse\bed\bd;\b; t\bth\bhi\bis\bs i\bin\bnf\bfo\bor\brm\bma\bat\bti\bio\bon\bn i\bis\bs k\bke\bep\bpt\bt o\bou\but\bts\bsi\bid\bde\be t\bth\bhe\be |
24829 | k\bke\ber\brn\bne\bel\bl.\b. |
24830 | |
24831 | The system's notion of the current Greenwich time and the current time |
24832 | zone is obtained with the g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() call, and set with the |
24833 | s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() call. The time is expressed in seconds and microseconds |
24834 | since midnight (0 hour), January 1, 1970. The resolution of the system |
24835 | clock is hardware dependent, and the time may be updated continuously or |
24836 | in ``ticks''. If _\bt_\bp or _\bt_\bz_\bp is NULL, the associated time information will |
24837 | not be returned or set. |
24838 | |
24839 | The structures pointed to by _\bt_\bp and _\bt_\bz_\bp are defined in <_\bs_\by_\bs_\b/_\bt_\bi_\bm_\be_\b._\bh> as: |
24840 | |
24841 | struct timeval { |
24842 | time_t tv_sec; /* seconds since Jan. 1, 1970 */ |
24843 | suseconds_t tv_usec; /* and microseconds */ |
24844 | }; |
24845 | |
24846 | struct timezone { |
24847 | int tz_minuteswest; /* of Greenwich */ |
24848 | int tz_dsttime; /* type of dst correction to apply */ |
24849 | }; |
24850 | |
24851 | The _\bt_\bi_\bm_\be_\bz_\bo_\bn_\be structure indicates the local time zone (measured in minutes |
24852 | of time westward from Greenwich), and a flag that, if nonzero, indicates |
24853 | that Daylight Saving time applies locally during the appropriate part of |
24854 | the year. |
24855 | |
24856 | Only the superuser may set the time of day or time zone. If the system |
24857 | securelevel is greater than 1 (see init(8)), the time may only be |
24858 | advanced. This limitation is imposed to prevent a malicious superuser |
24859 | from setting arbitrary time stamps on files. The system time can still |
24860 | be adjusted backwards using the adjtime(2) system call even when the |
24861 | system is secure. |
24862 | |
24863 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24864 | Upon successful completion, the value 0 is returned; otherwise the |
24865 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
24866 | error. |
24867 | |
24868 | E\bER\bRR\bRO\bOR\bRS\bS |
24869 | g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() and s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() will succeed unless: |
24870 | |
24871 | [EFAULT] An argument address referenced invalid memory. |
24872 | |
24873 | In addition, s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() may return the following error: |
24874 | |
24875 | [EPERM] A user other than the superuser attempted to set the |
24876 | time. |
24877 | |
24878 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24879 | date(1), adjtime(2), clock_gettime(2), getitimer(2), ctime(3), time(3) |
24880 | |
24881 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24882 | The g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() function conforms to IEEE Std 1003.1-2008 |
24883 | (``POSIX.1''). |
24884 | |
24885 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24886 | As predecessors of these functions, former system calls t\bti\bim\bme\be() and |
24887 | s\bst\bti\bim\bme\be() first appeared in Version 1 AT&T UNIX, and f\bft\bti\bim\bme\be() first appeared |
24888 | in Version 7 AT&T UNIX. The g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() and s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() system |
24889 | calls first appeared in 4.1cBSD. |
24890 | |
24891 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
24892 | Setting the time with s\bse\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() is dangerous; if possible use |
24893 | adjtime(2) instead. Many daemon programming techniques utilize time- |
24894 | delta techniques using the results from g\bge\bet\btt\bti\bim\bme\beo\bof\bfd\bda\bay\by() instead of from |
24895 | clock_gettime(2) on the CLOCK_MONOTONIC clock. Time jumps can cause |
24896 | these programs to malfunction in unexpected ways. If the time must be |
24897 | set, consider rebooting the machine for safety. |
24898 | |
24899 | N\bNA\bAM\bME\bE |
24900 | s\bse\bet\btu\bui\bid\bd, s\bse\bet\bte\beu\bui\bid\bd, s\bse\bet\btg\bgi\bid\bd, s\bse\bet\bte\beg\bgi\bid\bd - set user and group ID |
24901 | |
24902 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24903 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
24904 | |
24905 | _\bi_\bn_\bt |
24906 | s\bse\bet\btu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\bu_\bi_\bd); |
24907 | |
24908 | _\bi_\bn_\bt |
24909 | s\bse\bet\bte\beu\bui\bid\bd(_\bu_\bi_\bd_\b__\bt _\be_\bu_\bi_\bd); |
24910 | |
24911 | _\bi_\bn_\bt |
24912 | s\bse\bet\btg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\bg_\bi_\bd); |
24913 | |
24914 | _\bi_\bn_\bt |
24915 | s\bse\bet\bte\beg\bgi\bid\bd(_\bg_\bi_\bd_\b__\bt _\be_\bg_\bi_\bd); |
24916 | |
24917 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24918 | The s\bse\bet\btu\bui\bid\bd() function sets the real and effective user IDs and the saved |
24919 | set-user-ID of the current process to the specified value. The s\bse\bet\btu\bui\bid\bd() |
24920 | function is permitted if the effective user ID is that of the superuser, |
24921 | or if the specified user ID is the same as the effective user ID. If |
24922 | not, but the specified user ID is the same as the real user ID, s\bse\bet\btu\bui\bid\bd() |
24923 | will set the effective user ID to the real user ID. |
24924 | |
24925 | The s\bse\bet\btg\bgi\bid\bd() function sets the real and effective group IDs and the saved |
24926 | set-group-ID of the current process to the specified value. The s\bse\bet\btg\bgi\bid\bd() |
24927 | function is permitted if the effective user ID is that of the superuser, |
24928 | or if the specified group ID is the same as the effective group ID. If |
24929 | not, but the specified group ID is the same as the real group ID, |
24930 | s\bse\bet\btg\bgi\bid\bd() will set the effective group ID to the real group ID. |
24931 | Supplementary group IDs remain unchanged. |
24932 | |
24933 | The s\bse\bet\bte\beu\bui\bid\bd() function (s\bse\bet\bte\beg\bgi\bid\bd()) sets the effective user ID (group ID) |
24934 | of the current process. The effective user ID may be set to the value of |
24935 | the real user ID or the saved set-user-ID (see intro(2) and execve(2)); |
24936 | in this way, the effective user ID of a set-user-ID executable may be |
24937 | toggled by switching to the real user ID, then re-enabled by reverting to |
24938 | the set-user-ID value. Similarly, the effective group ID may be set to |
24939 | the value of the real group ID or the saved set-group-ID. |
24940 | |
24941 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
24942 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions return the |
24943 | value 0 if successful; otherwise the value -1 is returned and the global |
24944 | variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
24945 | |
24946 | E\bER\bRR\bRO\bOR\bRS\bS |
24947 | s\bse\bet\btu\bui\bid\bd() and s\bse\bet\bte\beu\bui\bid\bd() will succeed unless: |
24948 | |
24949 | [EPERM] The user is not the superuser and the requested _\bu_\bi_\bd or |
24950 | _\be_\bu_\bi_\bd is not the process's real, effective, or saved |
24951 | UID. |
24952 | |
24953 | s\bse\bet\btg\bgi\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() will succeed unless: |
24954 | |
24955 | [EPERM] The user is not the superuser and the requested _\bg_\bi_\bd or |
24956 | _\be_\bg_\bi_\bd is not the process's real, effective, or saved |
24957 | GID. |
24958 | |
24959 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
24960 | getgid(2), getuid(2), issetugid(2), setgroups(2), setregid(2), |
24961 | setresgid(2), setresuid(2), setreuid(2) |
24962 | |
24963 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
24964 | The s\bse\bet\btu\bui\bid\bd(), s\bse\bet\bte\beu\bui\bid\bd(), s\bse\bet\btg\bgi\bid\bd(), and s\bse\bet\bte\beg\bgi\bid\bd() functions conform to |
24965 | IEEE Std 1003.1-2008 (``POSIX.1''). |
24966 | |
24967 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
24968 | The s\bse\bet\btu\bui\bid\bd() system call first appeared in Version 1 AT&T UNIX; s\bse\bet\btg\bgi\bid\bd() |
24969 | in Version 4 AT&T UNIX; and s\bse\bet\bte\beu\bui\bid\bd() and s\bse\bet\bte\beg\bgi\bid\bd() in 4.2BSD. |
24970 | |
24971 | N\bNA\bAM\bME\bE |
24972 | s\bsh\bhm\bma\bat\bt, s\bsh\bhm\bmd\bdt\bt - map/unmap shared memory |
24973 | |
24974 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
24975 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsh\bhm\bm.\b.h\bh>\b> |
24976 | |
24977 | _\bv_\bo_\bi_\bd _\b* |
24978 | s\bsh\bhm\bma\bat\bt(_\bi_\bn_\bt _\bs_\bh_\bm_\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bs_\bh_\bm_\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bs_\bh_\bm_\bf_\bl_\bg); |
24979 | |
24980 | _\bi_\bn_\bt |
24981 | s\bsh\bhm\bmd\bdt\bt(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bs_\bh_\bm_\ba_\bd_\bd_\br); |
24982 | |
24983 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
24984 | s\bsh\bhm\bma\bat\bt() maps the shared memory segment associated with the shared memory |
24985 | identifier _\bs_\bh_\bm_\bi_\bd into the address space of the calling process. The |
24986 | address at which the segment is mapped is determined by the _\bs_\bh_\bm_\ba_\bd_\bd_\br |
24987 | parameter. If it is equal to 0, the system will pick an address itself. |
24988 | Otherwise, an attempt is made to map the shared memory segment at the |
24989 | address _\bs_\bh_\bm_\ba_\bd_\bd_\br specifies. If SHM_RND is set in _\bs_\bh_\bm_\bf_\bl_\bg, the system will |
24990 | round the address down to a multiple of SHMLBA bytes (SHMLBA is defined |
24991 | in <_\bs_\by_\bs_\b/_\bs_\bh_\bm_\b._\bh>). |
24992 | |
24993 | A shared memory segment can be mapped read-only by specifying the |
24994 | SHM_RDONLY flag in _\bs_\bh_\bm_\bf_\bl_\bg. |
24995 | |
24996 | s\bsh\bhm\bmd\bdt\bt() unmaps the shared memory segment that is currently mapped at |
24997 | _\bs_\bh_\bm_\ba_\bd_\bd_\br from the calling process' address space. _\bs_\bh_\bm_\ba_\bd_\bd_\br must be a value |
24998 | returned by a prior s\bsh\bhm\bma\bat\bt() call. A shared memory segment will remain |
24999 | existent until it is removed by a call to shmctl(2) with the IPC_RMID |
25000 | command. |
25001 | |
25002 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25003 | s\bsh\bhm\bma\bat\bt() returns the address at which the shared memory segment has been |
25004 | mapped into the calling process' address space when successful, s\bsh\bhm\bmd\bdt\bt() |
25005 | returns 0 on successful completion. Otherwise, a value of -1 is |
25006 | returned, and the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
25007 | |
25008 | E\bER\bRR\bRO\bOR\bRS\bS |
25009 | s\bsh\bhm\bma\bat\bt() will fail if: |
25010 | |
25011 | [EACCES] The calling process has no permission to access this |
25012 | shared memory segment. |
25013 | |
25014 | [ENOMEM] There is not enough available data space for the |
25015 | calling process to map the shared memory segment. |
25016 | |
25017 | [EINVAL] _\bs_\bh_\bm_\bi_\bd is not a valid shared memory identifier. |
25018 | |
25019 | _\bs_\bh_\bm_\ba_\bd_\bd_\br specifies an illegal address. |
25020 | |
25021 | [EMFILE] The number of shared memory segments has reached the |
25022 | system-wide limit. |
25023 | |
25024 | s\bsh\bhm\bmd\bdt\bt() will fail if: |
25025 | |
25026 | [EINVAL] _\bs_\bh_\bm_\ba_\bd_\bd_\br is not the start address of a mapped shared |
25027 | memory segment. |
25028 | |
25029 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25030 | ipcrm(1), ipcs(1), mmap(2), shmctl(2), shmget(2) |
25031 | |
25032 | N\bNA\bAM\bME\bE |
25033 | s\bsh\bhm\bmc\bct\btl\bl - shared memory control operations |
25034 | |
25035 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25036 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsh\bhm\bm.\b.h\bh>\b> |
25037 | |
25038 | _\bi_\bn_\bt |
25039 | s\bsh\bhm\bmc\bct\btl\bl(_\bi_\bn_\bt _\bs_\bh_\bm_\bi_\bd, _\bi_\bn_\bt _\bc_\bm_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bh_\bm_\bi_\bd_\b__\bd_\bs _\b*_\bb_\bu_\bf); |
25040 | |
25041 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25042 | The s\bsh\bhm\bmc\bct\btl\bl() system call performs some control operations on the shared |
25043 | memory area specified by _\bs_\bh_\bm_\bi_\bd. |
25044 | |
25045 | Each shared memory segment has a data structure associated with it, parts |
25046 | of which may be altered by s\bsh\bhm\bmc\bct\btl\bl() and parts of which determine the |
25047 | actions of s\bsh\bhm\bmc\bct\btl\bl(). |
25048 | |
25049 | This structure is defined as follows in <_\bs_\by_\bs_\b/_\bs_\bh_\bm_\b._\bh>: |
25050 | |
25051 | struct shmid_ds { |
25052 | struct ipc_perm shm_perm; /* operation permissions */ |
25053 | int shm_segsz; /* size of segment in bytes */ |
25054 | pid_t shm_lpid; /* pid of last shm op */ |
25055 | pid_t shm_cpid; /* pid of creator */ |
25056 | short shm_nattch; /* # of current attaches */ |
25057 | time_t shm_atime; /* last shmat() time*/ |
25058 | time_t shm_dtime; /* last shmdt() time */ |
25059 | time_t shm_ctime; /* last change by shmctl() */ |
25060 | void *shm_internal; /* sysv stupidity */ |
25061 | }; |
25062 | |
25063 | The ipc_perm structure used inside the shmid_ds structure is defined in |
25064 | <_\bs_\by_\bs_\b/_\bi_\bp_\bc_\b._\bh> and looks like this: |
25065 | |
25066 | struct ipc_perm { |
25067 | uid_t cuid; /* creator user id */ |
25068 | gid_t cgid; /* creator group id */ |
25069 | uid_t uid; /* user id */ |
25070 | gid_t gid; /* group id */ |
25071 | mode_t mode; /* r/w permission (see chmod(2)) */ |
25072 | u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ |
25073 | key_t key; /* user specified msg/sem/shm key */ |
25074 | }; |
25075 | |
25076 | The operation to be performed by s\bsh\bhm\bmc\bct\btl\bl() is specified in _\bc_\bm_\bd and is one |
25077 | of: |
25078 | |
25079 | IPC_STAT Gather information about the shared memory segment and place |
25080 | it in the structure pointed to by _\bb_\bu_\bf. |
25081 | |
25082 | IPC_SET Set the value of the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd, _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and |
25083 | _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be fields in the structure associated with _\bs_\bh_\bm_\bi_\bd. |
25084 | The values are taken from the corresponding fields in the |
25085 | structure pointed to by _\bb_\bu_\bf. This operation can only be |
25086 | executed by the superuser, or a process that has an effective |
25087 | user ID equal to either _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd in the |
25088 | data structure associated with the shared memory segment. |
25089 | |
25090 | IPC_RMID Mark the shared memory segment specified by _\bs_\bh_\bm_\bi_\bd for removal |
25091 | when it is no longer in use by any process. When it is |
25092 | removed, all data associated with it will be destroyed too. |
25093 | Only the superuser or a process with an effective UID equal to |
25094 | the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd or _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd values in the data structure |
25095 | associated with the queue can do this. |
25096 | |
25097 | The read and write permissions on a shared memory identifier are |
25098 | determined by the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be field in the same way as is done with |
25099 | files (see chmod(2)), but the effective UID can match either the |
25100 | _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd field or the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd field, and the effective GID can |
25101 | match either _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd or _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd. |
25102 | |
25103 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25104 | Upon successful completion, the value 0 is returned; otherwise the |
25105 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
25106 | error. |
25107 | |
25108 | E\bER\bRR\bRO\bOR\bRS\bS |
25109 | s\bsh\bhm\bmc\bct\btl\bl() will fail if: |
25110 | |
25111 | [EPERM] _\bc_\bm_\bd is equal to IPC_SET or IPC_RMID and the caller is |
25112 | not the superuser, nor does the effective UID match |
25113 | either the _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd or _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd fields of the |
25114 | data structure associated with the shared memory |
25115 | segment. |
25116 | |
25117 | An attempt is made to increase the value of _\bs_\bh_\bm_\b__\bq_\bb_\by_\bt_\be_\bs |
25118 | through IPC_SET but the caller is not the superuser. |
25119 | |
25120 | [EACCES] The command is IPC_STAT and the caller has no read |
25121 | permission for this shared memory segment. |
25122 | |
25123 | [EINVAL] _\bs_\bh_\bm_\bi_\bd is not a valid shared memory segment identifier. |
25124 | |
25125 | _\bc_\bm_\bd is not a valid command. |
25126 | |
25127 | [EFAULT] _\bb_\bu_\bf specifies an invalid address. |
25128 | |
25129 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25130 | shmat(2), shmget(2) |
25131 | |
25132 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
25133 | Segments which are marked for removal (but not yet removed since they are |
25134 | still in use) can be attached to by new callers using shmat(2). This is |
25135 | permitted as an extension beyond the standards. |
25136 | |
25137 | N\bNA\bAM\bME\bE |
25138 | s\bsh\bhm\bma\bat\bt, s\bsh\bhm\bmd\bdt\bt - map/unmap shared memory |
25139 | |
25140 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25141 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsh\bhm\bm.\b.h\bh>\b> |
25142 | |
25143 | _\bv_\bo_\bi_\bd _\b* |
25144 | s\bsh\bhm\bma\bat\bt(_\bi_\bn_\bt _\bs_\bh_\bm_\bi_\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bs_\bh_\bm_\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bs_\bh_\bm_\bf_\bl_\bg); |
25145 | |
25146 | _\bi_\bn_\bt |
25147 | s\bsh\bhm\bmd\bdt\bt(_\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bs_\bh_\bm_\ba_\bd_\bd_\br); |
25148 | |
25149 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25150 | s\bsh\bhm\bma\bat\bt() maps the shared memory segment associated with the shared memory |
25151 | identifier _\bs_\bh_\bm_\bi_\bd into the address space of the calling process. The |
25152 | address at which the segment is mapped is determined by the _\bs_\bh_\bm_\ba_\bd_\bd_\br |
25153 | parameter. If it is equal to 0, the system will pick an address itself. |
25154 | Otherwise, an attempt is made to map the shared memory segment at the |
25155 | address _\bs_\bh_\bm_\ba_\bd_\bd_\br specifies. If SHM_RND is set in _\bs_\bh_\bm_\bf_\bl_\bg, the system will |
25156 | round the address down to a multiple of SHMLBA bytes (SHMLBA is defined |
25157 | in <_\bs_\by_\bs_\b/_\bs_\bh_\bm_\b._\bh>). |
25158 | |
25159 | A shared memory segment can be mapped read-only by specifying the |
25160 | SHM_RDONLY flag in _\bs_\bh_\bm_\bf_\bl_\bg. |
25161 | |
25162 | s\bsh\bhm\bmd\bdt\bt() unmaps the shared memory segment that is currently mapped at |
25163 | _\bs_\bh_\bm_\ba_\bd_\bd_\br from the calling process' address space. _\bs_\bh_\bm_\ba_\bd_\bd_\br must be a value |
25164 | returned by a prior s\bsh\bhm\bma\bat\bt() call. A shared memory segment will remain |
25165 | existent until it is removed by a call to shmctl(2) with the IPC_RMID |
25166 | command. |
25167 | |
25168 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25169 | s\bsh\bhm\bma\bat\bt() returns the address at which the shared memory segment has been |
25170 | mapped into the calling process' address space when successful, s\bsh\bhm\bmd\bdt\bt() |
25171 | returns 0 on successful completion. Otherwise, a value of -1 is |
25172 | returned, and the global variable _\be_\br_\br_\bn_\bo is set to indicate the error. |
25173 | |
25174 | E\bER\bRR\bRO\bOR\bRS\bS |
25175 | s\bsh\bhm\bma\bat\bt() will fail if: |
25176 | |
25177 | [EACCES] The calling process has no permission to access this |
25178 | shared memory segment. |
25179 | |
25180 | [ENOMEM] There is not enough available data space for the |
25181 | calling process to map the shared memory segment. |
25182 | |
25183 | [EINVAL] _\bs_\bh_\bm_\bi_\bd is not a valid shared memory identifier. |
25184 | |
25185 | _\bs_\bh_\bm_\ba_\bd_\bd_\br specifies an illegal address. |
25186 | |
25187 | [EMFILE] The number of shared memory segments has reached the |
25188 | system-wide limit. |
25189 | |
25190 | s\bsh\bhm\bmd\bdt\bt() will fail if: |
25191 | |
25192 | [EINVAL] _\bs_\bh_\bm_\ba_\bd_\bd_\br is not the start address of a mapped shared |
25193 | memory segment. |
25194 | |
25195 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25196 | ipcrm(1), ipcs(1), mmap(2), shmctl(2), shmget(2) |
25197 | |
25198 | N\bNA\bAM\bME\bE |
25199 | s\bsh\bhm\bmg\bge\bet\bt - get shared memory area identifier |
25200 | |
25201 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25202 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsh\bhm\bm.\b.h\bh>\b> |
25203 | |
25204 | _\bi_\bn_\bt |
25205 | s\bsh\bhm\bmg\bge\bet\bt(_\bk_\be_\by_\b__\bt _\bk_\be_\by, _\bs_\bi_\bz_\be_\b__\bt _\bs_\bi_\bz_\be, _\bi_\bn_\bt _\bs_\bh_\bm_\bf_\bl_\bg); |
25206 | |
25207 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25208 | s\bsh\bhm\bmg\bge\bet\bt() returns the shared memory identifier associated with the key |
25209 | _\bk_\be_\by. |
25210 | |
25211 | A shared memory segment is created if either _\bk_\be_\by is equal to IPC_PRIVATE, |
25212 | or _\bk_\be_\by does not have a shared memory segment identifier associated with |
25213 | it, and the IPC_CREAT bit is set in _\bs_\bh_\bm_\bf_\bl_\bg. |
25214 | |
25215 | If a new shared memory segment is created, the data structure associated |
25216 | with it (the _\bs_\bh_\bm_\bi_\bd_\b__\bd_\bs structure, see shmctl(2)) is initialized as |
25217 | follows: |
25218 | |
25219 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bu_\bi_\bd and _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bu_\bi_\bd are set to the effective uid of the |
25220 | calling process. |
25221 | |
25222 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bg_\bi_\bd and _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bc_\bg_\bi_\bd are set to the effective gid of the |
25223 | calling process. |
25224 | |
25225 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bp_\be_\br_\bm_\b._\bm_\bo_\bd_\be is set to the lower 9 bits of _\bs_\bh_\bm_\bf_\bl_\bg. |
25226 | |
25227 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bl_\bp_\bi_\bd, _\bs_\bh_\bm_\b__\bn_\ba_\bt_\bt_\bc_\bh, _\bs_\bh_\bm_\b__\ba_\bt_\bi_\bm_\be, and _\bs_\bh_\bm_\b__\bd_\bt_\bi_\bm_\be are set to 0. |
25228 | |
25229 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bc_\bt_\bi_\bm_\be is set to the current time. |
25230 | |
25231 | +\b+\bo\bo _\bs_\bh_\bm_\b__\bs_\be_\bg_\bs_\bz is set to the value of _\bs_\bi_\bz_\be. |
25232 | |
25233 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25234 | Upon successful completion a positive shared memory segment identifier is |
25235 | returned. Otherwise, -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set |
25236 | to indicate the error. |
25237 | |
25238 | E\bER\bRR\bRO\bOR\bRS\bS |
25239 | [EACCES] A shared memory segment is already associated with _\bk_\be_\by |
25240 | and the caller has no permission to access it. |
25241 | |
25242 | [EEXIST] Both IPC_CREAT and IPC_EXCL are set in _\bs_\bh_\bm_\bf_\bl_\bg, and a |
25243 | shared memory segment is already associated with _\bk_\be_\by. |
25244 | |
25245 | [EINVAL] A shared memory segment is already associated with _\bk_\be_\by |
25246 | and its _\bs_\bi_\bz_\be is less than the requested size. |
25247 | |
25248 | [ENOSPC] A new shared memory identifier could not be created |
25249 | because the system limit for the number of shared |
25250 | memory identifiers has been reached. |
25251 | |
25252 | [ENOENT] IPC_CREAT was not set in _\bs_\bh_\bm_\bf_\bl_\bg and no shared memory |
25253 | segment associated with _\bk_\be_\by was found. |
25254 | |
25255 | [ENOMEM] There is not enough memory left to create a shared |
25256 | memory segment of the requested size. |
25257 | |
25258 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25259 | ipcrm(1), ipcs(1), mmap(2), shmat(2), shmctl(2), ftok(3) |
25260 | |
25261 | N\bNA\bAM\bME\bE |
25262 | s\bsh\bhu\but\btd\bdo\bow\bwn\bn - disable sends or receives on a socket |
25263 | |
25264 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25265 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
25266 | |
25267 | _\bi_\bn_\bt |
25268 | s\bsh\bhu\but\btd\bdo\bow\bwn\bn(_\bi_\bn_\bt _\bs, _\bi_\bn_\bt _\bh_\bo_\bw); |
25269 | |
25270 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25271 | The s\bsh\bhu\but\btd\bdo\bow\bwn\bn() system call disables sends or receives on a socket. |
25272 | |
25273 | If the file descriptor _\bs is associated with a SOCK_STREAM socket, all or |
25274 | part of the full-duplex connection will be shut down. |
25275 | |
25276 | The _\bh_\bo_\bw argument specifies the type of shutdown. Possible values are: |
25277 | |
25278 | SHUT_RD Further receives will be disallowed. |
25279 | |
25280 | SHUT_WR Further sends will be disallowed. This may cause |
25281 | actions specific to the protocol family of the socket |
25282 | _\bs to happen. |
25283 | |
25284 | SHUT_RDWR Further sends and receives will be disallowed. |
25285 | |
25286 | The following protocol specific actions apply to the use of SHUT_WR based |
25287 | on the properties of the socket associated with the file descriptor _\bs: |
25288 | |
25289 | DOMAIN TYPE PROTOCOL RETURN VALUE AND ACTION |
25290 | |
25291 | |
25292 | AF_INET SOCK_DGRAM IPPROTO_UDP Return 0. ICMP messages |
25293 | will _\bn_\bo_\bt be generated. |
25294 | AF_INET SOCK_STREAM IPPROTO_TCP Return 0. Send queued |
25295 | data, wait for ACK, then |
25296 | send FIN. |
25297 | AF_INET6 SOCK_DGRAM IPPROTO_UDP Return 0. ICMP messages |
25298 | will _\bn_\bo_\bt be generated. |
25299 | AF_INET6 SOCK_STREAM IPPROTO_TCP Return 0. Send queued |
25300 | data, wait for ACK, then |
25301 | send FIN. |
25302 | |
25303 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25304 | Upon successful completion, the value 0 is returned; otherwise the |
25305 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
25306 | error. |
25307 | |
25308 | E\bER\bRR\bRO\bOR\bRS\bS |
25309 | The s\bsh\bhu\but\btd\bdo\bow\bwn\bn() system call fails if: |
25310 | |
25311 | [EBADF] The _\bs argument is not a valid file descriptor. |
25312 | |
25313 | [EINVAL] The _\bh_\bo_\bw argument is invalid. |
25314 | |
25315 | [ENOTCONN] The _\bs argument specifies a SOCK_STREAM socket which is |
25316 | not connected. |
25317 | |
25318 | [ENOTSOCK] The _\bs argument does not refer to a socket. |
25319 | |
25320 | [EOPNOTSUPP] The socket associated with the file descriptor _\bs does |
25321 | not support this operation. |
25322 | |
25323 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25324 | connect(2), socket(2), inet(4), inet6(4) |
25325 | |
25326 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
25327 | The s\bsh\bhu\but\btd\bdo\bow\bwn\bn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
25328 | |
25329 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
25330 | The s\bsh\bhu\but\btd\bdo\bow\bwn\bn() system call first appeared in 4.1cBSD. The SHUT_RD, |
25331 | SHUT_WR, and SHUT_RDWR constants appeared in IEEE Std 1003.1g-2000 |
25332 | (``POSIX.1g''). |
25333 | |
25334 | B\bBU\bUG\bGS\bS |
25335 | The ICMP ``port unreachable'' message should be generated in response to |
25336 | datagrams received on a local port to which _\bs is bound after s\bsh\bhu\but\btd\bdo\bow\bwn\bn() |
25337 | is called. |
25338 | |
25339 | N\bNA\bAM\bME\bE |
25340 | s\bsi\big\bga\bac\bct\bti\bio\bon\bn - software signal facilities |
25341 | |
25342 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25343 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
25344 | |
25345 | struct sigaction { |
25346 | union { /* signal handler */ |
25347 | void (*__sa_handler)(int); |
25348 | void (*__sa_sigaction)(int, siginfo_t *, void *); |
25349 | } __sigaction_u; |
25350 | sigset_t sa_mask; /* signal mask to apply */ |
25351 | int sa_flags; /* see signal options below */ |
25352 | }; |
25353 | |
25354 | #\b#d\bde\bef\bfi\bin\bne\be s\bsa\ba_\b_h\bha\ban\bnd\bdl\ble\ber\br _\b__\b_s\bsi\big\bga\bac\bct\bti\bio\bon\bn_\b_u\bu.\b._\b__\b_s\bsa\ba_\b_h\bha\ban\bnd\bdl\ble\ber\br |
25355 | #\b#d\bde\bef\bfi\bin\bne\be s\bsa\ba_\b_s\bsi\big\bga\bac\bct\bti\bio\bon\bn _\b__\b_s\bsi\big\bga\bac\bct\bti\bio\bon\bn_\b_u\bu.\b._\b__\b_s\bsa\ba_\b_s\bsi\big\bga\bac\bct\bti\bio\bon\bn |
25356 | |
25357 | _\bi_\bn_\bt |
25358 | s\bsi\big\bga\bac\bct\bti\bio\bon\bn(_\bi_\bn_\bt _\bs_\bi_\bg, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn _\b*_\ba_\bc_\bt, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn _\b*_\bo_\ba_\bc_\bt); |
25359 | |
25360 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25361 | The system defines a set of signals that may be delivered to a process. |
25362 | Signal delivery resembles the occurrence of a hardware interrupt: the |
25363 | signal is normally blocked from further occurrence, the current process |
25364 | context is saved, and a new one is built. A process may specify a |
25365 | _\bh_\ba_\bn_\bd_\bl_\be_\br to which a signal is delivered, or specify that a signal is to be |
25366 | _\bi_\bg_\bn_\bo_\br_\be_\bd. A process may also specify that a default action is to be taken |
25367 | by the system when a signal occurs. A signal may also be _\bb_\bl_\bo_\bc_\bk_\be_\bd, in |
25368 | which case its delivery is postponed until it is _\bu_\bn_\bb_\bl_\bo_\bc_\bk_\be_\bd. The action |
25369 | to be taken on delivery is determined at the time of delivery. Normally, |
25370 | signal handlers execute on the current stack of the process. This may be |
25371 | changed, on a per-handler basis, so that signals are taken on a special |
25372 | _\bs_\bi_\bg_\bn_\ba_\bl _\bs_\bt_\ba_\bc_\bk. |
25373 | |
25374 | Signal routines normally execute with the signal that caused their |
25375 | invocation _\bb_\bl_\bo_\bc_\bk_\be_\bd, but other signals may yet occur. A global _\bs_\bi_\bg_\bn_\ba_\bl |
25376 | _\bm_\ba_\bs_\bk defines the set of signals currently blocked from delivery to a |
25377 | process. The signal mask for a process is initialized from that of its |
25378 | parent (normally empty). It may be changed with a sigprocmask(2) call, |
25379 | or when a signal is delivered to the process. |
25380 | |
25381 | When a signal condition arises for a process, the signal is added to a |
25382 | set of signals pending for the process. If the signal is not currently |
25383 | _\bb_\bl_\bo_\bc_\bk_\be_\bd by the process then it is delivered to the process. Signals may |
25384 | be delivered any time a process enters the operating system (e.g., during |
25385 | a system call, page fault or trap, or clock interrupt). If multiple |
25386 | signals are ready to be delivered at the same time, any signals that |
25387 | could be caused by traps are delivered first. Additional signals may be |
25388 | processed at the same time, with each appearing to interrupt the handlers |
25389 | for the previous signals before their first instructions. The set of |
25390 | pending signals is returned by the sigpending(2) function. When a caught |
25391 | signal is delivered, the current state of the process is saved, a new |
25392 | signal mask is calculated (as described below), and the signal handler is |
25393 | invoked. The call to the handler is arranged so that if the signal |
25394 | handling routine returns normally the process will resume execution in |
25395 | the context from before the signal's delivery. If the process wishes to |
25396 | resume in a different context, then it must arrange to restore the |
25397 | previous context itself. |
25398 | |
25399 | When a signal is delivered to a process a new signal mask is installed |
25400 | for the duration of the process' signal handler (or until a |
25401 | sigprocmask(2) call is made). This mask is formed by taking the union of |
25402 | the current signal mask set, the signal to be delivered, and the signal |
25403 | mask _\bs_\ba_\b__\bm_\ba_\bs_\bk associated with the handler to be invoked, but always |
25404 | excluding SIGKILL and SIGSTOP. |
25405 | |
25406 | s\bsi\big\bga\bac\bct\bti\bio\bon\bn() assigns an action for a signal specified by _\bs_\bi_\bg. If _\ba_\bc_\bt is |
25407 | non-zero, it specifies an action (SIG_DFL, SIG_IGN, or a handler routine) |
25408 | and mask to be used when delivering the specified signal. If _\bo_\ba_\bc_\bt is |
25409 | non-zero, the previous handling information for the signal is returned to |
25410 | the user. |
25411 | |
25412 | Once a signal handler is installed, it normally remains installed until |
25413 | another s\bsi\big\bga\bac\bct\bti\bio\bon\bn() call is made, or an execve(2) is performed. The |
25414 | value of _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br (or, if the SA_SIGINFO flag is set, the value of |
25415 | _\bs_\ba_\b__\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn instead) indicates what action should be performed when a |
25416 | signal arrives. A signal-specific default action may be reset by setting |
25417 | _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br to SIG_DFL. Alternately, if the SA_RESETHAND flag is set the |
25418 | default action will be reinstated when the signal is first posted. The |
25419 | defaults are process termination, possibly with core dump; no action; |
25420 | stopping the process; or continuing the process. See the signal list |
25421 | below for each signal's default action. If _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br is SIG_DFL, the |
25422 | default action for the signal is to discard the signal, and if a signal |
25423 | is pending, the pending signal is discarded even if the signal is masked. |
25424 | If _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br is set to SIG_IGN, current and pending instances of the |
25425 | signal are ignored and discarded. If _\bs_\bi_\bg is SIGCHLD and _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br is |
25426 | set to SIG_IGN, the SA_NOCLDWAIT flag (described below) is implied. |
25427 | |
25428 | Options may be specified by setting _\bs_\ba_\b__\bf_\bl_\ba_\bg_\bs. The meaning of the various |
25429 | bits is as follows: |
25430 | |
25431 | SA_NOCLDSTOP If this bit is set when installing a catching |
25432 | function for the SIGCHLD signal, the SIGCHLD signal |
25433 | will be generated only when a child process exits, |
25434 | not when a child process stops. |
25435 | |
25436 | SA_NOCLDWAIT If this bit is set when calling s\bsi\big\bga\bac\bct\bti\bio\bon\bn() for the |
25437 | SIGCHLD signal, the system will not create zombie |
25438 | processes when children of the calling process |
25439 | exit, though existing zombies will remain. If the |
25440 | calling process subsequently issues a waitpid(2) |
25441 | (or equivalent) and there are no previously |
25442 | existing zombie child processes that match the |
25443 | waitpid(2) criteria, it blocks until all of the |
25444 | calling process's child processes that would match |
25445 | terminate, and then returns a value of -1 with |
25446 | _\be_\br_\br_\bn_\bo set to ECHILD. |
25447 | |
25448 | SA_ONSTACK If this bit is set, the system will deliver the |
25449 | signal to the process on a _\bs_\bi_\bg_\bn_\ba_\bl _\bs_\bt_\ba_\bc_\bk, specified |
25450 | with sigaltstack(2). |
25451 | |
25452 | SA_NODEFER If this bit is set, further occurrences of the |
25453 | delivered signal are not masked during the |
25454 | execution of the handler. |
25455 | |
25456 | SA_RESETHAND If this bit is set, the handler is reset back to |
25457 | SIG_DFL at the moment the signal is delivered. |
25458 | |
25459 | SA_SIGINFO If this bit is set, the 2nd argument of the handler |
25460 | is set to be a pointer to a _\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b__\bt structure as |
25461 | described in <_\bs_\by_\bs_\b/_\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b._\bh>. It provides much |
25462 | more information about the causes and attributes of |
25463 | the signal that is being delivered. |
25464 | |
25465 | SA_RESTART If a signal is caught during the system calls |
25466 | listed below, the call may be forced to terminate |
25467 | with the error EINTR, the call may return with a |
25468 | data transfer shorter than requested, or the call |
25469 | may be restarted. Restarting of pending calls is |
25470 | requested by setting the SA_RESTART bit in |
25471 | _\bs_\ba_\b__\bf_\bl_\ba_\bg_\bs. The affected system calls include |
25472 | read(2), write(2), sendto(2), recvfrom(2), |
25473 | sendmsg(2) and recvmsg(2) on a communications |
25474 | channel or a slow device (such as a terminal, but |
25475 | not a regular file) and during a wait(2) or |
25476 | ioctl(2). However, calls that have already |
25477 | committed are not restarted, but instead return a |
25478 | partial success (for example, a short read count). |
25479 | |
25480 | After a fork(2) or vfork(2), all signals, the signal mask, the signal |
25481 | stack, and the restart/interrupt flags are inherited by the child. |
25482 | |
25483 | execve(2) reinstates the default action for all signals which were caught |
25484 | and resets all signals to be caught on the user stack. Ignored signals |
25485 | remain ignored; the signal mask remains the same; signals that restart |
25486 | pending system calls continue to do so. |
25487 | |
25488 | The following is a list of all signals with names as in the include file |
25489 | <_\bs_\bi_\bg_\bn_\ba_\bl_\b._\bh>: |
25490 | |
25491 | N\bNa\bam\bme\be D\bDe\bef\bfa\bau\bul\blt\bt A\bAc\bct\bti\bio\bon\bn D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn |
25492 | SIGHUP terminate process terminal line hangup |
25493 | SIGINT terminate process interrupt program |
25494 | SIGQUIT create core image quit program |
25495 | SIGILL create core image illegal instruction |
25496 | SIGTRAP create core image trace trap |
25497 | SIGABRT create core image abort(3) call (formerly SIGIOT) |
25498 | SIGEMT create core image emulate instruction executed |
25499 | SIGFPE create core image floating-point exception |
25500 | SIGKILL terminate process kill program (cannot be caught or |
25501 | ignored) |
25502 | SIGBUS create core image bus error |
25503 | SIGSEGV create core image segmentation violation |
25504 | SIGSYS create core image system call given invalid argument |
25505 | SIGPIPE terminate process write on a pipe with no reader |
25506 | SIGALRM terminate process real-time timer expired |
25507 | SIGTERM terminate process software termination signal |
25508 | SIGURG discard signal urgent condition present on socket |
25509 | SIGSTOP stop process stop (cannot be caught or ignored) |
25510 | SIGTSTP stop process stop signal generated from keyboard |
25511 | SIGCONT discard signal continue after stop |
25512 | SIGCHLD discard signal child status has changed |
25513 | SIGTTIN stop process background read attempted from control |
25514 | terminal |
25515 | SIGTTOU stop process background write attempted to control |
25516 | terminal |
25517 | SIGIO discard signal I/O is possible on a descriptor (see |
25518 | fcntl(2)) |
25519 | SIGXCPU terminate process CPU time limit exceeded (see |
25520 | setrlimit(2)) |
25521 | SIGXFSZ terminate process file size limit exceeded (see |
25522 | setrlimit(2)) |
25523 | SIGVTALRM terminate process virtual time alarm (see setitimer(2)) |
25524 | SIGPROF terminate process profiling timer alarm (see |
25525 | setitimer(2)) |
25526 | SIGWINCH discard signal window size change |
25527 | SIGINFO discard signal status request from keyboard |
25528 | SIGUSR1 terminate process user defined signal 1 |
25529 | SIGUSR2 terminate process user defined signal 2 |
25530 | SIGTHR discard signal thread AST |
25531 | |
25532 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25533 | Upon successful completion, the value 0 is returned; otherwise the |
25534 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
25535 | error. |
25536 | |
25537 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS |
25538 | The handler routine can be declared: |
25539 | |
25540 | void |
25541 | handler(int sig) |
25542 | |
25543 | If the SA_SIGINFO option is enabled, the canonical way to declare it is: |
25544 | |
25545 | void |
25546 | handler(int sig, siginfo_t *sip, struct sigcontext *scp) |
25547 | |
25548 | Here _\bs_\bi_\bg is the signal number, into which the hardware faults and traps |
25549 | are mapped. If the SA_SIGINFO option is set, _\bs_\bi_\bp is a pointer to a |
25550 | siginfo_t as described in <_\bs_\by_\bs_\b/_\bs_\bi_\bg_\bi_\bn_\bf_\bo_\b._\bh>. If SA_SIGINFO is not set, |
25551 | this pointer will be NULL instead. The function specified in |
25552 | _\bs_\ba_\b__\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn will be called instead of the function specified by |
25553 | _\bs_\ba_\b__\bh_\ba_\bn_\bd_\bl_\be_\br (Note that in some implementations these are in fact the |
25554 | same). _\bs_\bc_\bp is a pointer to the _\bs_\bi_\bg_\bc_\bo_\bn_\bt_\be_\bx_\bt structure (defined in |
25555 | <_\bs_\bi_\bg_\bn_\ba_\bl_\b._\bh>), used to restore the context from before the signal. |
25556 | |
25557 | E\bER\bRR\bRO\bOR\bRS\bS |
25558 | s\bsi\big\bga\bac\bct\bti\bio\bon\bn() will fail and no new signal handler will be installed if one |
25559 | of the following occurs: |
25560 | |
25561 | [EFAULT] Either _\ba_\bc_\bt or _\bo_\ba_\bc_\bt points to memory that is not a |
25562 | valid part of the process address space. |
25563 | |
25564 | [EINVAL] _\bs_\bi_\bg is not a valid signal number. |
25565 | |
25566 | [EINVAL] An attempt is made to ignore or supply a handler for |
25567 | SIGKILL or SIGSTOP. |
25568 | |
25569 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25570 | kill(1), kill(2), ptrace(2), sigaltstack(2), sigprocmask(2), |
25571 | sigsuspend(2), wait(2), setjmp(3), sigblock(3), sigpause(3), |
25572 | sigsetops(3), sigvec(3), tty(4) |
25573 | |
25574 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
25575 | The s\bsi\big\bga\bac\bct\bti\bio\bon\bn() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
25576 | |
25577 | The SA_ONSTACK flag and the SIGPROF, SIGSYS, SIGTRAP, SIGVTALRM, SIGXCPU, |
25578 | and SIGXFSZ signals conform to the X/Open System Interfaces option of |
25579 | that standard. The standard marks SIGPROF as obsolescent. The signals |
25580 | SIGEMT, SIGINFO, SIGIO, and SIGWINCH are Berkeley extensions. These |
25581 | signals are available on most BSD-derived systems. The SIGTHR signal is |
25582 | specific to OpenBSD and is part of the implementation of thread |
25583 | cancellation; _\bs_\bi_\bg_\ba_\bc_\bt_\bi_\bo_\bn and other signal interfaces may reject attempts |
25584 | to use or alter the handling of SIGTHR. |
25585 | |
25586 | The following functions are either reentrant or not interruptible by |
25587 | signals and are async-signal-safe. Therefore applications may invoke |
25588 | them, without restriction, from signal-catching functions: |
25589 | |
25590 | Standard Interfaces: |
25591 | |
25592 | _\b_e\bex\bxi\bit\bt(), _\b_E\bEx\bxi\bit\bt(), a\bab\bbo\bor\brt\bt(), a\bac\bcc\bce\bep\bpt\bt(), a\bac\bcc\bce\bes\bss\bs(), a\bal\bla\bar\brm\bm(), b\bbi\bin\bnd\bd(), |
25593 | c\bcf\bfg\bge\bet\bti\bis\bsp\bpe\bee\bed\bd(), c\bcf\bfg\bge\bet\bto\bos\bsp\bpe\bee\bed\bd(), c\bcf\bfs\bse\bet\bti\bis\bsp\bpe\bee\bed\bd(), c\bcf\bfs\bse\bet\bto\bos\bsp\bpe\bee\bed\bd(), c\bch\bhd\bdi\bir\br(), |
25594 | c\bch\bhm\bmo\bod\bd(), c\bch\bho\bow\bwn\bn(), c\bcl\blo\boc\bck\bk_\b_g\bge\bet\btt\bti\bim\bme\be(), c\bcl\blo\bos\bse\be(), c\bco\bon\bnn\bne\bec\bct\bt(), c\bcr\bre\bea\bat\bt(), d\bdu\bup\bp(), |
25595 | d\bdu\bup\bp2\b2(), e\bex\bxe\bec\bcl\bl(), e\bex\bxe\bec\bcl\ble\be(), e\bex\bxe\bec\bcv\bv(), e\bex\bxe\bec\bcv\bve\be(), f\bfa\bac\bcc\bce\bes\bss\bsa\bat\bt(), f\bfc\bch\bhd\bdi\bir\br(), |
25596 | f\bfc\bch\bhm\bmo\bod\bd(), f\bfc\bch\bhm\bmo\bod\bda\bat\bt(), f\bfc\bch\bho\bow\bwn\bn(), f\bfc\bch\bho\bow\bwn\bna\bat\bt(), f\bfc\bcn\bnt\btl\bl(), f\bfd\bda\bat\bta\bas\bsy\byn\bnc\bc(), f\bfo\bor\brk\bk(), |
25597 | f\bfp\bpa\bat\bth\bhc\bco\bon\bnf\bf(), f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), f\bfs\bsy\byn\bnc\bc(), f\bft\btr\bru\bun\bnc\bca\bat\bte\be(), f\bfu\but\bti\bim\bme\ben\bns\bs(), |
25598 | f\bfu\but\bti\bim\bme\bes\bs(), g\bge\bet\bte\beg\bgi\bid\bd(), g\bge\bet\bte\beu\bui\bid\bd(), g\bge\bet\btg\bgi\bid\bd(), g\bge\bet\btg\bgr\bro\bou\bup\bps\bs(), g\bge\bet\btp\bpe\bee\ber\brn\bna\bam\bme\be(), |
25599 | g\bge\bet\btp\bpg\bgr\brp\bp(), g\bge\bet\btp\bpi\bid\bd(), g\bge\bet\btp\bpp\bpi\bid\bd(), g\bge\bet\bts\bso\boc\bck\bkn\bna\bam\bme\be(), g\bge\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), g\bge\bet\btu\bui\bid\bd(), |
25600 | k\bki\bil\bll\bl(), l\bli\bin\bnk\bk(), l\bli\bin\bnk\bka\bat\bt(), l\bli\bis\bst\bte\ben\bn(), l\bls\bse\bee\bek\bk(), l\bls\bst\bta\bat\bt(), m\bmk\bkd\bdi\bir\br(), m\bmk\bkd\bdi\bir\bra\bat\bt(), |
25601 | m\bmk\bkf\bfi\bif\bfo\bo(), m\bmk\bkf\bfi\bif\bfo\boa\bat\bt(), m\bmk\bkn\bno\bod\bd(), m\bmk\bkn\bno\bod\bda\bat\bt(), o\bop\bpe\ben\bn(), o\bop\bpe\ben\bna\bat\bt(), p\bpa\bat\bth\bhc\bco\bon\bnf\bf(), |
25602 | p\bpa\bau\bus\bse\be(), p\bpi\bip\bpe\be(), p\bpo\bol\bll\bl(), p\bps\bse\bel\ble\bec\bct\bt(), p\bpt\bth\bhr\bre\bea\bad\bd_\b_s\bsi\big\bgm\bma\bas\bsk\bk(), r\bra\bai\bis\bse\be(), r\bre\bea\bad\bd(), |
25603 | r\bre\bea\bad\bdl\bli\bin\bnk\bk(), r\bre\bea\bad\bdl\bli\bin\bnk\bka\bat\bt(), r\bre\bec\bcv\bv(), r\bre\bec\bcv\bvf\bfr\bro\bom\bm(), r\bre\bec\bcv\bvm\bms\bsg\bg(), r\bre\ben\bna\bam\bme\be(), |
25604 | r\bre\ben\bna\bam\bme\bea\bat\bt(), r\brm\bmd\bdi\bir\br(), s\bse\bel\ble\bec\bct\bt(), s\bse\ben\bnd\bd(), s\bse\ben\bnd\bdm\bms\bsg\bg(), s\bse\ben\bnd\bdt\bto\bo(), s\bse\bet\btg\bgi\bid\bd(), |
25605 | s\bse\bet\btp\bpg\bgi\bid\bd(), s\bse\bet\bts\bsi\bid\bd(), s\bse\bet\bts\bso\boc\bck\bko\bop\bpt\bt(), s\bse\bet\btu\bui\bid\bd(), s\bsh\bhu\but\btd\bdo\bow\bwn\bn(), s\bsi\big\bga\bac\bct\bti\bio\bon\bn(), |
25606 | s\bsi\big\bga\bad\bdd\bds\bse\bet\bt(), s\bsi\big\bgd\bde\bel\bls\bse\bet\bt(), s\bsi\big\bge\bem\bmp\bpt\bty\bys\bse\bet\bt(), s\bsi\big\bgf\bfi\bil\bll\bls\bse\bet\bt(), s\bsi\big\bgi\bis\bsm\bme\bem\bmb\bbe\ber\br(), |
25607 | s\bsi\big\bgn\bna\bal\bl(), s\bsi\big\bgp\bpa\bau\bus\bse\be(), s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg(), s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk(), s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd(), s\bsl\ble\bee\bep\bp(), |
25608 | s\bso\boc\bck\bka\bat\btm\bma\bar\brk\bk(), s\bso\boc\bck\bke\bet\bt(), s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br(), s\bst\bta\bat\bt(), s\bst\btr\brc\bca\bat\bt(), s\bst\btr\brc\bcp\bpy\by(), |
25609 | s\bst\btr\brn\bnc\bca\bat\bt(), s\bst\btr\brn\bnc\bcp\bpy\by(), s\bsy\bym\bml\bli\bin\bnk\bk(), s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt(), s\bsy\bys\bsc\bco\bon\bnf\bf(), t\btc\bcd\bdr\bra\bai\bin\bn(), |
25610 | t\btc\bcf\bfl\blo\bow\bw(), t\btc\bcf\bfl\blu\bus\bsh\bh(), t\btc\bcg\bge\bet\bta\bat\btt\btr\br(), t\btc\bcg\bge\bet\btp\bpg\bgr\brp\bp(), t\btc\bcs\bse\ben\bnd\bdb\bbr\bre\bea\bak\bk(), |
25611 | t\btc\bcs\bse\bet\bta\bat\btt\btr\br(), t\btc\bcs\bse\bet\btp\bpg\bgr\brp\bp(), t\bti\bim\bme\be(), t\bti\bim\bme\bes\bs(), u\bum\bma\bas\bsk\bk(), u\bun\bna\bam\bme\be(), u\bun\bnl\bli\bin\bnk\bk(), |
25612 | u\bun\bnl\bli\bin\bnk\bka\bat\bt(), u\but\bti\bim\bme\be(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), u\but\bti\bim\bme\bes\bs(), w\bwa\bai\bit\bt(), w\bwa\bai\bit\btp\bpi\bid\bd(), w\bwr\bri\bit\bte\be(), |
25613 | and perhaps some others. |
25614 | |
25615 | Extension Interfaces: |
25616 | |
25617 | a\bac\bcc\bce\bep\bpt\bt4\b4(), c\bch\bhf\bfl\bla\bag\bgs\bs(), d\bdu\bup\bp3\b3(), f\bfc\bch\bhf\bfl\bla\bag\bgs\bs(), g\bge\bet\bte\ben\bnt\btr\bro\bop\bpy\by(), g\bge\bet\btr\bre\bes\bsg\bgi\bid\bd(), |
25618 | g\bge\bet\btr\bre\bes\bsu\bui\bid\bd(), p\bpi\bip\bpe\be2\b2(), p\bpp\bpo\bol\bll\bl(), s\bse\ben\bnd\bds\bsy\bys\bsl\blo\bog\bg(), s\bse\bet\btr\bre\bes\bsg\bgi\bid\bd(), s\bse\bet\btr\bre\bes\bsu\bui\bid\bd(), |
25619 | s\bst\btr\brl\blc\bca\bat\bt(), s\bst\btr\brl\blc\bcp\bpy\by(), w\bwa\bai\bit\bt3\b3(), w\bwa\bai\bit\bt4\b4(). |
25620 | |
25621 | In addition, access and updates to _\be_\br_\br_\bn_\bo are guaranteed to be safe. Most |
25622 | functions not in the above lists are considered to be unsafe with respect |
25623 | to signals. That is to say, the behaviour of such functions when called |
25624 | from a signal handler is undefined. In general though, signal handlers |
25625 | should do little more than set a flag, ideally of type volatile |
25626 | sig_atomic_t; most other actions are not safe. |
25627 | |
25628 | Additionally, it is advised that signal handlers guard against |
25629 | modification of the external symbol _\be_\br_\br_\bn_\bo by the above functions, saving |
25630 | it at entry and restoring it on return, thus: |
25631 | |
25632 | void |
25633 | handler(int sig) |
25634 | { |
25635 | int save_errno = errno; |
25636 | |
25637 | ... |
25638 | errno = save_errno; |
25639 | } |
25640 | |
25641 | The functions below are async-signal-safe in OpenBSD except when used |
25642 | with floating-point arguments or directives, but are probably unsafe on |
25643 | other systems: |
25644 | |
25645 | d\bdp\bpr\bri\bin\bnt\btf\bf() Safe. |
25646 | v\bvd\bdp\bpr\bri\bin\bnt\btf\bf() Safe. |
25647 | s\bsn\bnp\bpr\bri\bin\bnt\btf\bf() Safe. |
25648 | v\bvs\bsn\bnp\bpr\bri\bin\bnt\btf\bf() Safe. |
25649 | s\bsy\bys\bsl\blo\bog\bg_\b_r\br() Safe if the _\bs_\by_\bs_\bl_\bo_\bg_\b__\bd_\ba_\bt_\ba struct is initialized as a |
25650 | local variable. |
25651 | |
25652 | N\bNA\bAM\bME\bE |
25653 | s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk - set and/or get signal stack context |
25654 | |
25655 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25656 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
25657 | |
25658 | typedef struct sigaltstack { |
25659 | void *ss_sp; |
25660 | size_t ss_size; |
25661 | int ss_flags; |
25662 | } stack_t; |
25663 | _\bi_\bn_\bt |
25664 | s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk(_\bc_\bo_\bn_\bs_\bt _\bs_\bt_\ba_\bc_\bk_\b__\bt _\b*_\bs_\bs, _\bs_\bt_\ba_\bc_\bk_\b__\bt _\b*_\bo_\bs_\bs); |
25665 | |
25666 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25667 | s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk() allows users to define an alternate stack on which signals |
25668 | delivered to this thread are to be processed. If _\bs_\bs is non-zero and |
25669 | SS_DISABLE is set in _\bs_\bs_\b__\bf_\bl_\ba_\bg_\bs, the signal stack will be disabled. A |
25670 | disabled stack will cause all signals to be taken on the regular user |
25671 | stack. Trying to disable an active stack will cause k\bkq\bqu\bue\beu\bue\be to return -1 |
25672 | with _\be_\br_\br_\bn_\bo set to EPERM. |
25673 | |
25674 | Otherwise, _\bs_\bs_\b__\bs_\bp specifies a pointer to a space to be used as the signal |
25675 | stack and _\bs_\bs_\b__\bs_\bi_\bz_\be specifies the size of that space. When a signal's |
25676 | action indicates its handler should execute on the signal stack |
25677 | (specified with a sigaction(2) call), the system checks to see if the |
25678 | thread is currently executing on that stack. If the thread is not |
25679 | currently executing on the signal stack, the system arranges a switch to |
25680 | the signal stack for the duration of the signal handler's execution. |
25681 | |
25682 | If _\bo_\bs_\bs is non-zero, the current signal stack state is returned. The |
25683 | _\bs_\bs_\b__\bf_\bl_\ba_\bg_\bs field will contain the value SS_ONSTACK if the thread is |
25684 | currently on a signal stack and SS_DISABLE if the signal stack is |
25685 | currently disabled. |
25686 | |
25687 | N\bNO\bOT\bTE\bES\bS |
25688 | The value SIGSTKSZ is defined to be the number of bytes/chars that would |
25689 | be used to cover the usual case when allocating an alternate stack area. |
25690 | The following code fragment is typically used to allocate an alternate |
25691 | stack. |
25692 | |
25693 | if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) |
25694 | /* error return */ |
25695 | sigstk.ss_size = SIGSTKSZ; |
25696 | sigstk.ss_flags = 0; |
25697 | if (sigaltstack(&sigstk, 0) == -1) |
25698 | perror("sigaltstack"); |
25699 | |
25700 | An alternative approach is provided for programs with signal handlers |
25701 | that require a specific amount of stack space other than the default |
25702 | size. The value MINSIGSTKSZ is defined to be the number of bytes/chars |
25703 | that is required by the operating system to implement the alternate stack |
25704 | feature. In computing an alternate stack size, programs should add |
25705 | MINSIGSTKSZ to their stack requirements to allow for the operating system |
25706 | overhead. |
25707 | |
25708 | Signal stacks are automatically adjusted for the direction of stack |
25709 | growth and alignment requirements. Signal stacks may or may not be |
25710 | protected by the hardware and are not ``grown'' automatically as is done |
25711 | for the normal stack. If the stack overflows and this space is not |
25712 | protected unpredictable results may occur. |
25713 | |
25714 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25715 | Upon successful completion, the value 0 is returned; otherwise the |
25716 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
25717 | error. |
25718 | |
25719 | E\bER\bRR\bRO\bOR\bRS\bS |
25720 | s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk() will fail and the signal stack context will remain |
25721 | unchanged if one of the following occurs. |
25722 | |
25723 | [EFAULT] Either _\bs_\bs or _\bo_\bs_\bs points to memory that is not a valid part of |
25724 | the process address space. |
25725 | |
25726 | [EINVAL] The _\bs_\bs_\b__\bf_\bl_\ba_\bg_\bs member pointed to by the _\bs_\bs argument contains |
25727 | flags other than SS_DISABLE. |
25728 | |
25729 | [ENOMEM] Size of alternate stack area is less than or equal to |
25730 | MINSIGSTKSZ. |
25731 | |
25732 | [EPERM] An attempt was made to disable an active stack. |
25733 | |
25734 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25735 | sigaction(2), setjmp(3) |
25736 | |
25737 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
25738 | The k\bkq\bqu\bue\beu\bue\be function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
25739 | |
25740 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
25741 | The predecessor to s\bsi\big\bga\bal\blt\bts\bst\bta\bac\bck\bk, the s\bsi\big\bgs\bst\bta\bac\bck\bk() system call, appeared in |
25742 | 4.2BSD. |
25743 | |
25744 | N\bNA\bAM\bME\bE |
25745 | s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg - get pending signals |
25746 | |
25747 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25748 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
25749 | |
25750 | _\bi_\bn_\bt |
25751 | s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg(_\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bs_\be_\bt); |
25752 | |
25753 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25754 | The s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg function returns a mask of the signals pending for |
25755 | delivery to the calling process in the location indicated by _\bs_\be_\bt. |
25756 | Signals may be pending because they are currently masked, or transiently |
25757 | before delivery (although the latter case is not normally detectable). |
25758 | |
25759 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25760 | Upon successful completion, the value 0 is returned; otherwise the |
25761 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
25762 | error. |
25763 | |
25764 | E\bER\bRR\bRO\bOR\bRS\bS |
25765 | The s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg function does not currently detect any errors. |
25766 | |
25767 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25768 | sigaction(2), sigprocmask(2), sigsetops(3) |
25769 | |
25770 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
25771 | The s\bsi\big\bgp\bpe\ben\bnd\bdi\bin\bng\bg function is defined by IEEE Std 1003.1-2008 (``POSIX.1''). |
25772 | |
25773 | N\bNA\bAM\bME\bE |
25774 | s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk - manipulate current signal mask |
25775 | |
25776 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25777 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
25778 | |
25779 | _\bi_\bn_\bt |
25780 | s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk(_\bi_\bn_\bt _\bh_\bo_\bw, _\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bs_\be_\bt, _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bo_\bs_\be_\bt); |
25781 | |
25782 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25783 | The s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk() function examines and/or changes the current signal |
25784 | mask (those signals that are blocked from delivery). Signals are blocked |
25785 | if they are members of the current signal mask set. |
25786 | |
25787 | If _\bs_\be_\bt is not null, the action of s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk() depends on the value of |
25788 | the parameter _\bh_\bo_\bw, which can be one of the following values: |
25789 | |
25790 | SIG_BLOCK The new mask is the union of the current mask and the |
25791 | specified _\bs_\be_\bt. |
25792 | |
25793 | SIG_UNBLOCK The new mask is the intersection of the current mask and the |
25794 | complement of the specified _\bs_\be_\bt. |
25795 | |
25796 | SIG_SETMASK The current mask is replaced by the specified _\bs_\be_\bt. |
25797 | |
25798 | If _\bo_\bs_\be_\bt is not null, it is set to the previous value of the signal mask. |
25799 | When _\bs_\be_\bt is null, the value of _\bh_\bo_\bw is insignificant and the mask remains |
25800 | unchanged, providing a way to examine the signal mask without |
25801 | modification. |
25802 | |
25803 | The system quietly disallows SIGKILL or SIGSTOP to be blocked. |
25804 | |
25805 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25806 | Upon successful completion, the value 0 is returned; otherwise the |
25807 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
25808 | error. |
25809 | |
25810 | E\bER\bRR\bRO\bOR\bRS\bS |
25811 | The s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk() call will fail and the signal mask will be unchanged if |
25812 | one of the following occurs: |
25813 | |
25814 | [EINVAL] _\bh_\bo_\bw has a value other than those listed here. |
25815 | |
25816 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25817 | kill(2), sigaction(2), sigsuspend(2), sigsetops(3) |
25818 | |
25819 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
25820 | The s\bsi\big\bgp\bpr\bro\boc\bcm\bma\bas\bsk\bk() function call is expected to conform to IEEE Std |
25821 | 1003.1-2008 (``POSIX.1''). |
25822 | |
25823 | N\bNA\bAM\bME\bE |
25824 | s\bsi\big\bgr\bre\bet\btu\bur\brn\bn - return from signal |
25825 | |
25826 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25827 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
25828 | |
25829 | _\bi_\bn_\bt |
25830 | s\bsi\big\bgr\bre\bet\btu\bur\brn\bn(_\bs_\bt_\br_\bu_\bc_\bt _\bs_\bi_\bg_\bc_\bo_\bn_\bt_\be_\bx_\bt _\b*_\bs_\bc_\bp); |
25831 | |
25832 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25833 | s\bsi\big\bgr\bre\bet\btu\bur\brn\bn() allows users to atomically unmask, switch stacks, and return |
25834 | from a signal context. The processes signal mask and stack status are |
25835 | restored from the context. The system call does not return; the users |
25836 | stack pointer, frame pointer, argument pointer, and processor status |
25837 | longword are restored from the context. Execution resumes at the |
25838 | specified pc. This system call is used by the trampoline code and |
25839 | longjmp(3) when returning from a signal to the previously executing |
25840 | program. |
25841 | |
25842 | Note that sigcontext contains machine dependent information. |
25843 | |
25844 | N\bNO\bOT\bTE\bES\bS |
25845 | This system call is not available in 4.2BSD hence it should not be used |
25846 | if backward compatibility is needed. |
25847 | |
25848 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25849 | If successful, the system call does not return. Otherwise, a value of -1 |
25850 | is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
25851 | |
25852 | E\bER\bRR\bRO\bOR\bRS\bS |
25853 | s\bsi\big\bgr\bre\bet\btu\bur\brn\bn() will fail and the process context will remain unchanged if |
25854 | one of the following occurs. |
25855 | |
25856 | [EFAULT] _\bs_\bc_\bp points to memory that is not a valid part of the |
25857 | process address space. |
25858 | |
25859 | [EINVAL] The process status longword is invalid or would |
25860 | improperly raise the privilege level of the process. |
25861 | |
25862 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25863 | sigaction(2), setjmp(3) |
25864 | |
25865 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
25866 | The s\bsi\big\bgr\bre\bet\btu\bur\brn\bn() function call appeared in 4.3BSD. |
25867 | |
25868 | N\bNA\bAM\bME\bE |
25869 | s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd - atomically change the signal mask and wait for interrupt |
25870 | |
25871 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25872 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsi\big\bgn\bna\bal\bl.\b.h\bh>\b> |
25873 | |
25874 | _\bi_\bn_\bt |
25875 | s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd(_\bc_\bo_\bn_\bs_\bt _\bs_\bi_\bg_\bs_\be_\bt_\b__\bt _\b*_\bs_\bi_\bg_\bm_\ba_\bs_\bk); |
25876 | |
25877 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25878 | s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd() temporarily changes the blocked signal mask to the set to |
25879 | which _\bs_\bi_\bg_\bm_\ba_\bs_\bk points, and then waits for a signal to arrive; on return |
25880 | the previous set of masked signals is restored. The signal mask set is |
25881 | usually empty to indicate that all signals are to be unblocked for the |
25882 | duration of the call. |
25883 | |
25884 | In normal usage, a signal is blocked using sigprocmask(2) to begin a |
25885 | critical section, variables modified on the occurrence of the signal are |
25886 | examined to determine that there is no work to be done, and the process |
25887 | pauses awaiting work by using s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd() with the previous mask |
25888 | returned by sigprocmask(2). |
25889 | |
25890 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25891 | The s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd() function always terminates by being interrupted, |
25892 | returning -1 with _\be_\br_\br_\bn_\bo set to EINTR. |
25893 | |
25894 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
25895 | sigaction(2), sigprocmask(2), sigsetops(3) |
25896 | |
25897 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
25898 | The s\bsi\big\bgs\bsu\bus\bsp\bpe\ben\bnd\bd function call conforms to IEEE Std 1003.1-2008 |
25899 | (``POSIX.1''). |
25900 | |
25901 | N\bNA\bAM\bME\bE |
25902 | s\bso\boc\bck\bke\bet\bt - create an endpoint for communication |
25903 | |
25904 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
25905 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
25906 | |
25907 | _\bi_\bn_\bt |
25908 | s\bso\boc\bck\bke\bet\bt(_\bi_\bn_\bt _\bd_\bo_\bm_\ba_\bi_\bn, _\bi_\bn_\bt _\bt_\by_\bp_\be, _\bi_\bn_\bt _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl); |
25909 | |
25910 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
25911 | s\bso\boc\bck\bke\bet\bt() creates an endpoint for communication and returns a descriptor. |
25912 | |
25913 | The _\bd_\bo_\bm_\ba_\bi_\bn parameter specifies a communications domain within which |
25914 | communication will take place; this selects the protocol family which |
25915 | should be used. These families are defined in the include file |
25916 | <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>. The currently understood formats are: |
25917 | |
25918 | AF_UNIX UNIX internal protocols |
25919 | AF_INET ARPA Internet protocols |
25920 | AF_INET6 IPv6 (Internet Protocol version 6) protocols |
25921 | |
25922 | The socket has the indicated _\bt_\by_\bp_\be, which specifies the semantics of |
25923 | communication. Currently defined types are: |
25924 | |
25925 | SOCK_STREAM |
25926 | SOCK_DGRAM |
25927 | SOCK_RAW |
25928 | SOCK_SEQPACKET |
25929 | |
25930 | A SOCK_STREAM type provides sequenced, reliable, two-way connection based |
25931 | byte streams. An out-of-band data transmission mechanism may be |
25932 | supported. A SOCK_DGRAM socket supports datagrams (connectionless, |
25933 | unreliable messages of a fixed (typically small) maximum length). A |
25934 | SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way |
25935 | connection-based data transmission path for datagrams of fixed maximum |
25936 | length; a consumer may be required to read an entire packet with each |
25937 | read system call. This facility is protocol specific, and presently |
25938 | implemented only for AF_UNIX. SOCK_RAW sockets provide access to |
25939 | internal network protocols and interfaces, and are available only to the |
25940 | superuser. |
25941 | |
25942 | Any combination of the following flags may additionally be used in the |
25943 | _\bt_\by_\bp_\be argument: |
25944 | |
25945 | SOCK_CLOEXEC Set close-on-exec flag on the new descriptor. |
25946 | SOCK_NONBLOCK Set non-blocking I/O mode on the new socket. |
25947 | |
25948 | The _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl specifies a particular protocol to be used with the socket. |
25949 | Normally only a single protocol exists to support a particular socket |
25950 | type within a given protocol family. However, it is possible that many |
25951 | protocols may exist, in which case a particular protocol must be |
25952 | specified in this manner. The protocol number to use is particular to |
25953 | the ``communication domain'' in which communication is to take place; see |
25954 | protocols(5). A value of 0 for _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl will let the system select an |
25955 | appropriate protocol for the requested socket type. |
25956 | |
25957 | Sockets of type SOCK_STREAM are full-duplex byte streams. A stream |
25958 | socket must be in a _\bc_\bo_\bn_\bn_\be_\bc_\bt_\be_\bd state before any data may be sent or |
25959 | received on it. A connection to another socket is created with a |
25960 | connect(2) call. Once connected, data may be transferred using read(2) |
25961 | and write(2) calls or some variant of the send(2) and recv(2) calls. |
25962 | When a session has been completed a close(2) may be performed. Out-of- |
25963 | band data may also be transmitted as described in send(2) and received as |
25964 | described in recv(2). |
25965 | |
25966 | The communications protocols used to implement a SOCK_STREAM ensure that |
25967 | data is not lost or duplicated. If a piece of data for which the peer |
25968 | protocol has buffer space cannot be successfully transmitted within a |
25969 | reasonable length of time, then the connection is considered broken and |
25970 | calls will indicate an error with -1 returns and with ETIMEDOUT as the |
25971 | specific code in the global variable _\be_\br_\br_\bn_\bo. The protocols optionally |
25972 | keep sockets ``warm'' by forcing transmissions roughly every minute in |
25973 | the absence of other activity. An error is then indicated if no response |
25974 | can be elicited on an otherwise idle connection for an extended period |
25975 | (e.g., 5 minutes). A SIGPIPE signal is raised if a process sends on a |
25976 | broken stream; this causes naive processes, which do not handle the |
25977 | signal, to exit. |
25978 | |
25979 | SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM |
25980 | sockets. The only difference is that read(2) calls will return only the |
25981 | amount of data requested, and any remaining in the arriving packet will |
25982 | be discarded. |
25983 | |
25984 | SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to |
25985 | correspondents named in send(2) calls. Datagrams are generally received |
25986 | with recvfrom(2), which returns the next datagram with its return |
25987 | address. |
25988 | |
25989 | An fcntl(2) call can be used to specify a process group to receive a |
25990 | SIGURG signal when the out-of-band data arrives. It may also enable non- |
25991 | blocking I/O and asynchronous notification of I/O events via SIGIO. |
25992 | |
25993 | The operation of sockets is controlled by socket level _\bo_\bp_\bt_\bi_\bo_\bn_\bs. These |
25994 | options are defined in the file <_\bs_\by_\bs_\b/_\bs_\bo_\bc_\bk_\be_\bt_\b._\bh>. setsockopt(2) and |
25995 | getsockopt(2) are used to set and get options, respectively. |
25996 | |
25997 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
25998 | A -1 is returned if an error occurs, otherwise the return value is a |
25999 | descriptor referencing the socket. |
26000 | |
26001 | E\bER\bRR\bRO\bOR\bRS\bS |
26002 | The s\bso\boc\bck\bke\bet\bt() call fails if: |
26003 | |
26004 | [EAFNOSUPPORT] The specified address family is not supported on this |
26005 | machine. |
26006 | |
26007 | [EPROTONOSUPPORT] The protocol type or the specified protocol is not |
26008 | supported within this domain. |
26009 | |
26010 | [EPROTOTYPE] The combination of the specified protocol and type is |
26011 | not supported. |
26012 | |
26013 | [EMFILE] The per-process descriptor table is full. |
26014 | |
26015 | [ENFILE] The system file table is full. |
26016 | |
26017 | [ENOBUFS] Insufficient resources were available in the system to |
26018 | perform the operation. |
26019 | |
26020 | [EACCES] Permission to create a socket of the specified type |
26021 | and/or protocol is denied. |
26022 | |
26023 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26024 | accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), ioctl(2), |
26025 | listen(2), poll(2), read(2), recv(2), select(2), send(2), setsockopt(2), |
26026 | shutdown(2), socketpair(2), write(2), getprotoent(3), inet(4), inet6(4), |
26027 | netintro(4), unix(4) |
26028 | |
26029 | _\bA_\bn _\bI_\bn_\bt_\br_\bo_\bd_\bu_\bc_\bt_\bo_\br_\by _\b4_\b._\b3 _\bB_\bS_\bD _\bI_\bn_\bt_\be_\br_\bp_\br_\bo_\bc_\be_\bs_\bs _\bC_\bo_\bm_\bm_\bu_\bn_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\bT_\bu_\bt_\bo_\br_\bi_\ba_\bl, reprinted in |
26030 | UNIX Programmer's Supplementary Documents Volume 1. |
26031 | |
26032 | _\bB_\bS_\bD _\bI_\bn_\bt_\be_\br_\bp_\br_\bo_\bc_\be_\bs_\bs _\bC_\bo_\bm_\bm_\bu_\bn_\bi_\bc_\ba_\bt_\bi_\bo_\bn _\bT_\bu_\bt_\bo_\br_\bi_\ba_\bl, reprinted in UNIX Programmer's |
26033 | Supplementary Documents Volume 1. |
26034 | |
26035 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
26036 | The s\bso\boc\bck\bke\bet\bt() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
26037 | |
26038 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26039 | The s\bso\boc\bck\bke\bet\bt() system call first appeared in 4.1cBSD. |
26040 | |
26041 | N\bNA\bAM\bME\bE |
26042 | s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br - create a pair of connected sockets |
26043 | |
26044 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26045 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b> |
26046 | |
26047 | _\bi_\bn_\bt |
26048 | s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br(_\bi_\bn_\bt _\bd, _\bi_\bn_\bt _\bt_\by_\bp_\be, _\bi_\bn_\bt _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl, _\bi_\bn_\bt _\bs_\bv_\b[_\b2_\b]); |
26049 | |
26050 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26051 | The s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br() call creates an unnamed pair of connected sockets in the |
26052 | specified domain _\bd, of the specified _\bt_\by_\bp_\be, and using the optionally |
26053 | specified _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl. The descriptors used in referencing the new sockets |
26054 | are returned in _\bs_\bv[0] and _\bs_\bv[1]. The two sockets are indistinguishable. |
26055 | |
26056 | Any combination of the following flags may additionally be used in the |
26057 | _\bt_\by_\bp_\be argument: |
26058 | |
26059 | SOCK_CLOEXEC Set close-on-exec flag on both the new descriptors. |
26060 | SOCK_NONBLOCK Set non-blocking I/O mode on both the new sockets. |
26061 | |
26062 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26063 | Upon successful completion, the value 0 is returned; otherwise the |
26064 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
26065 | error. |
26066 | |
26067 | E\bER\bRR\bRO\bOR\bRS\bS |
26068 | The call succeeds unless: |
26069 | |
26070 | [EAFNOSUPPORT] The specified address family is not supported on this |
26071 | machine. |
26072 | |
26073 | [EPROTONOSUPPORT] The specified protocol is not supported on this |
26074 | machine. |
26075 | |
26076 | [EOPNOTSUPP] The specified protocol does not support creation of |
26077 | socket pairs. |
26078 | |
26079 | [EPROTOTYPE] The combination of the specified protocol and type is |
26080 | not supported. |
26081 | |
26082 | [EMFILE] The per-process descriptor table is full. |
26083 | |
26084 | [ENFILE] The system file table is full. |
26085 | |
26086 | [ENOBUFS] Insufficient resources were available in the system to |
26087 | perform the operation. |
26088 | |
26089 | [EFAULT] The address _\bs_\bv does not specify a valid part of the |
26090 | process address space. |
26091 | |
26092 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26093 | pipe(2), read(2), socket(2), write(2) |
26094 | |
26095 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
26096 | The s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
26097 | |
26098 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26099 | The s\bso\boc\bck\bke\bet\btp\bpa\bai\bir\br() function call appeared in 4.2BSD. |
26100 | |
26101 | B\bBU\bUG\bGS\bS |
26102 | This call is currently implemented only for the LOCAL domain. Many |
26103 | operating systems only accept a _\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl of PF_UNSPEC, so that should be |
26104 | used instead of PF_LOCAL for maximal portability. |
26105 | |
26106 | N\bNA\bAM\bME\bE |
26107 | s\bst\bta\bat\bt, l\bls\bst\bta\bat\bt, f\bfs\bst\bta\bat\bta\bat\bt, f\bfs\bst\bta\bat\bt - get file status |
26108 | |
26109 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26110 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
26111 | |
26112 | _\bi_\bn_\bt |
26113 | s\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
26114 | |
26115 | _\bi_\bn_\bt |
26116 | l\bls\bst\bta\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
26117 | |
26118 | _\bi_\bn_\bt |
26119 | f\bfs\bst\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb); |
26120 | |
26121 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
26122 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
26123 | |
26124 | _\bi_\bn_\bt |
26125 | f\bfs\bst\bta\bat\bta\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt _\b*_\bs_\bb, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
26126 | |
26127 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26128 | The s\bst\bta\bat\bt() function obtains information about the file pointed to by |
26129 | _\bp_\ba_\bt_\bh. Read, write, or execute permission of the named file is not |
26130 | required, but all directories listed in the path name leading to the file |
26131 | must be searchable. |
26132 | |
26133 | The l\bls\bst\bta\bat\bt() function is identical to s\bst\bta\bat\bt() except when the named file is |
26134 | a symbolic link, in which case l\bls\bst\bta\bat\bt() returns information about the link |
26135 | itself, not the file the link references. |
26136 | |
26137 | The f\bfs\bst\bta\bat\bta\bat\bt() function is equivalent to either the s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt() |
26138 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
26139 | _\bp_\ba_\bt_\bh specifies a relative path, the file whose information is returned is |
26140 | determined relative to the directory associated with file descriptor _\bf_\bd |
26141 | instead of the current working directory. |
26142 | |
26143 | If f\bfs\bst\bta\bat\bta\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
26144 | in the _\bf_\bd parameter, the current working directory is used and the |
26145 | behavior is identical to a call to s\bst\bta\bat\bt() or l\bls\bst\bta\bat\bt(), depending on |
26146 | whether or not the AT_SYMLINK_NOFOLLOW bit is set in _\bf_\bl_\ba_\bg. |
26147 | |
26148 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
26149 | values: |
26150 | |
26151 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the status |
26152 | of the symbolic link is returned. |
26153 | |
26154 | The f\bfs\bst\bta\bat\bt() function obtains the same information about an open file |
26155 | known by the file descriptor _\bf_\bd. |
26156 | |
26157 | The _\bs_\bb argument is a pointer to a s\bst\bta\bat\bt() structure as defined by |
26158 | <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> (shown below) and into which information is placed |
26159 | concerning the file. |
26160 | |
26161 | struct stat { |
26162 | dev_t st_dev; /* inode's device */ |
26163 | ino_t st_ino; /* inode's number */ |
26164 | mode_t st_mode; /* inode protection mode */ |
26165 | nlink_t st_nlink; /* number of hard links */ |
26166 | uid_t st_uid; /* user ID of the file's owner */ |
26167 | gid_t st_gid; /* group ID of the file's group */ |
26168 | dev_t st_rdev; /* device type */ |
26169 | struct timespec st_atim; /* time of last access */ |
26170 | struct timespec st_mtim; /* time of last data modification */ |
26171 | struct timespec st_ctim; /* time of last file status change */ |
26172 | off_t st_size; /* file size, in bytes */ |
26173 | blkcnt_t st_blocks; /* blocks allocated for file */ |
26174 | blksize_t st_blksize;/* optimal blocksize for I/O */ |
26175 | u_int32_t st_flags; /* user defined flags for file */ |
26176 | u_int32_t st_gen; /* file generation number */ |
26177 | }; |
26178 | |
26179 | The time-related fields of struct stat are represented in struct timespec |
26180 | format, which has nanosecond precision. However, the actual precision is |
26181 | generally limited by the file system holding the file. The fields are as |
26182 | follows: |
26183 | |
26184 | _\bs_\bt_\b__\ba_\bt_\bi_\bm Time when file data was last accessed. Set when the file |
26185 | system object was created and updated by the utimes(2) and |
26186 | read(2) system calls. |
26187 | |
26188 | _\bs_\bt_\b__\bm_\bt_\bi_\bm Time when file data was last modified. Changed by the |
26189 | truncate(2), utimes(2), and write(2) system calls. For |
26190 | directories, changed by any system call that alters which |
26191 | files are in the directory, such as the unlink(2), rename(2), |
26192 | mkdir(2), and symlink(2) system calls. |
26193 | |
26194 | _\bs_\bt_\b__\bc_\bt_\bi_\bm Time when file status was last changed (inode data |
26195 | modification). Changed by the chmod(2), chown(2), link(2), |
26196 | rename(2), unlink(2), utimes(2), and write(2) system calls. |
26197 | |
26198 | In addition, all the time fields are set to the current time when a file |
26199 | system object is first created by the mkdir(2), mkfifo(2), mknod(2), |
26200 | open(2), and symlink(2) system calls. |
26201 | |
26202 | For compatibility with previous standards, _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be, and |
26203 | _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be macros are provided that expand to the _\bt_\bv_\b__\bs_\be_\bc_\bs member of their |
26204 | respective struct timespec member. Deprecated macros are also provided |
26205 | for some transitional names: _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bn_\bs_\be_\bc, |
26206 | _\bs_\bt_\b__\ba_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, _\bs_\bt_\b__\bm_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc, and _\bs_\bt_\b__\bc_\bt_\bi_\bm_\be_\bs_\bp_\be_\bc |
26207 | |
26208 | The size-related fields of the struct stat are as follows: |
26209 | |
26210 | _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be The optimal I/O block size for the file. |
26211 | |
26212 | _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs The actual number of blocks allocated for the file in |
26213 | 512-byte units. As short symbolic links are stored in the |
26214 | inode, this number may be zero. |
26215 | |
26216 | The status information word _\bs_\bt_\b__\bm_\bo_\bd_\be has the following bits: |
26217 | |
26218 | #define S_IFMT 0170000 /* type of file mask */ |
26219 | #define S_IFIFO 0010000 /* named pipe (fifo) */ |
26220 | #define S_IFCHR 0020000 /* character special */ |
26221 | #define S_IFDIR 0040000 /* directory */ |
26222 | #define S_IFBLK 0060000 /* block special */ |
26223 | #define S_IFREG 0100000 /* regular */ |
26224 | #define S_IFLNK 0120000 /* symbolic link */ |
26225 | #define S_IFSOCK 0140000 /* socket */ |
26226 | #define S_ISUID 0004000 /* set-user-ID on execution */ |
26227 | #define S_ISGID 0002000 /* set-group-ID on execution */ |
26228 | #define S_ISVTX 0001000 /* save swapped text even after use */ |
26229 | #define S_IRWXU 0000700 /* RWX mask for owner */ |
26230 | #define S_IRUSR 0000400 /* R for owner */ |
26231 | #define S_IWUSR 0000200 /* W for owner */ |
26232 | #define S_IXUSR 0000100 /* X for owner */ |
26233 | #define S_IRWXG 0000070 /* RWX mask for group */ |
26234 | #define S_IRGRP 0000040 /* R for group */ |
26235 | #define S_IWGRP 0000020 /* W for group */ |
26236 | #define S_IXGRP 0000010 /* X for group */ |
26237 | #define S_IRWXO 0000007 /* RWX mask for other */ |
26238 | #define S_IROTH 0000004 /* R for other */ |
26239 | #define S_IWOTH 0000002 /* W for other */ |
26240 | #define S_IXOTH 0000001 /* X for other */ |
26241 | |
26242 | The following macros test a file's type. If the file is of that type, a |
26243 | non-zero value is returned; otherwise, 0 is returned. |
26244 | |
26245 | S_ISBLK(st_mode m) /* block special */ |
26246 | S_ISCHR(st_mode m) /* char special */ |
26247 | S_ISDIR(st_mode m) /* directory */ |
26248 | S_ISFIFO(st_mode m) /* fifo */ |
26249 | S_ISLNK(st_mode m) /* symbolic link */ |
26250 | S_ISREG(st_mode m) /* regular file */ |
26251 | S_ISSOCK(st_mode m) /* socket */ |
26252 | |
26253 | For a list of access modes, see <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>, access(2), and chmod(2). |
26254 | |
26255 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26256 | Upon successful completion, the value 0 is returned; otherwise the |
26257 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
26258 | error. |
26259 | |
26260 | E\bER\bRR\bRO\bOR\bRS\bS |
26261 | s\bst\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
26262 | |
26263 | [ENOTDIR] A component of the path prefix is not a directory. |
26264 | |
26265 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
26266 | characters, or an entire pathname (including the |
26267 | terminating NUL) exceeded PATH_MAX bytes. |
26268 | |
26269 | [ENOENT] A component of _\bn_\ba_\bm_\be does not exist or _\bn_\ba_\bm_\be is the |
26270 | empty path. |
26271 | |
26272 | [EACCES] Search permission is denied for a component of the |
26273 | path prefix. |
26274 | |
26275 | [ELOOP] Too many symbolic links were encountered in |
26276 | translating the pathname. |
26277 | |
26278 | [EFAULT] _\bs_\bb or _\bn_\ba_\bm_\be points to an invalid address. |
26279 | |
26280 | [EIO] An I/O error occurred while reading from or writing to |
26281 | the file system. |
26282 | |
26283 | Additionally, f\bfs\bst\bta\bat\bta\bat\bt() will fail if: |
26284 | |
26285 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
26286 | AT_SYMLINK_NOFOLLOW. |
26287 | |
26288 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
26289 | argument is neither AT_FDCWD nor a valid file |
26290 | descriptor. |
26291 | |
26292 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
26293 | argument is a valid file descriptor but it does not |
26294 | reference a directory. |
26295 | |
26296 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
26297 | permission is denied for the directory which the _\bf_\bd |
26298 | file descriptor references. |
26299 | |
26300 | f\bfs\bst\bta\bat\bt() will fail if: |
26301 | |
26302 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
26303 | |
26304 | [EFAULT] _\bs_\bb points to an invalid address. |
26305 | |
26306 | [EIO] An I/O error occurred while reading from the file |
26307 | system. |
26308 | |
26309 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26310 | chmod(2), chown(2), clock_gettime(2), utimes(2), symlink(7) |
26311 | |
26312 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
26313 | Previous versions of the system used different types for the _\bs_\bt_\b__\bd_\be_\bv, |
26314 | _\bs_\bt_\b__\bu_\bi_\bd, _\bs_\bt_\b__\bg_\bi_\bd, _\bs_\bt_\b__\br_\bd_\be_\bv, _\bs_\bt_\b__\bs_\bi_\bz_\be, _\bs_\bt_\b__\bb_\bl_\bk_\bs_\bi_\bz_\be, and _\bs_\bt_\b__\bb_\bl_\bo_\bc_\bk_\bs fields. |
26315 | |
26316 | The f\bfs\bst\bta\bat\bt(), f\bfs\bst\bta\bat\bta\bat\bt(), l\bls\bst\bta\bat\bt(), and s\bst\bta\bat\bt() functions are intended to |
26317 | conform to IEEE Std 1003.1-2008 (``POSIX.1''). |
26318 | |
26319 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26320 | The s\bst\bta\bat\bt() and f\bfs\bst\bta\bat\bt() system calls first appeared in Version 1 AT&T |
26321 | UNIX. The <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh> header file and the _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt were introduced |
26322 | in Version 7 AT&T UNIX. |
26323 | |
26324 | An l\bls\bst\bta\bat\bt() function call appeared in 4.2BSD. The f\bfs\bst\bta\bat\bta\bat\bt() function |
26325 | appeared in OpenBSD 5.0. |
26326 | |
26327 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
26328 | The file generation number, _\bs_\bt_\b__\bg_\be_\bn, is only available to the superuser. |
26329 | |
26330 | Certain programs written when the timestamps were just of type time_t |
26331 | assumed that the members were consecutive (and could therefore be treated |
26332 | as an array and have their address passed directly to utime(3)). The |
26333 | transition to timestamps of type struct timespec broke them irrevocably. |
26334 | |
26335 | B\bBU\bUG\bGS\bS |
26336 | Applying f\bfs\bst\bta\bat\bt() to a pipe or socket fails to fill in a unique device and |
26337 | inode number pair. Applying f\bfs\bst\bta\bat\bt() to a socket also fails to fill in |
26338 | the time fields. |
26339 | |
26340 | N\bNA\bAM\bME\bE |
26341 | s\bst\bta\bat\btf\bfs\bs, f\bfs\bst\bta\bat\btf\bfs\bs - get file system statistics |
26342 | |
26343 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26344 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
26345 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
26346 | |
26347 | _\bi_\bn_\bt |
26348 | s\bst\bta\bat\btf\bfs\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
26349 | |
26350 | _\bi_\bn_\bt |
26351 | f\bfs\bst\bta\bat\btf\bfs\bs(_\bi_\bn_\bt _\bf_\bd, _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bt_\ba_\bt_\bf_\bs _\b*_\bb_\bu_\bf); |
26352 | |
26353 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26354 | s\bst\bta\bat\btf\bfs\bs() returns information about a mounted file system. _\bp_\ba_\bt_\bh is the |
26355 | path name of any file within the mounted file system. _\bb_\bu_\bf is a pointer |
26356 | to a s\bst\bta\bat\btf\bfs\bs structure defined as follows: |
26357 | |
26358 | typedef struct { int32_t val[2]; } fsid_t; |
26359 | |
26360 | #define MFSNAMELEN 16 /* length of fs type name, including nul */ |
26361 | #define MNAMELEN 90 /* length of buffer for returned name */ |
26362 | |
26363 | struct statfs { |
26364 | u_int32_t f_flags; /* copy of mount flags */ |
26365 | u_int32_t f_bsize; /* file system block size */ |
26366 | u_int32_t f_iosize; /* optimal transfer block size */ |
26367 | |
26368 | /* unit is f_bsize */ |
26369 | u_int64_t f_blocks; /* total data blocks in file system */ |
26370 | u_int64_t f_bfree; /* free blocks in fs */ |
26371 | int64_t f_bavail; /* free blocks avail to non-superuser */ |
26372 | |
26373 | u_int64_t f_files; /* total file nodes in file system */ |
26374 | u_int64_t f_ffree; /* free file nodes in fs */ |
26375 | int64_t f_favail; /* free file nodes avail to non-root */ |
26376 | |
26377 | u_int64_t f_syncwrites; /* count of sync writes since mount */ |
26378 | u_int64_t f_syncreads; /* count of sync reads since mount */ |
26379 | u_int64_t f_asyncwrites; /* count of async writes since mount */ |
26380 | u_int64_t f_asyncreads; /* count of async reads since mount */ |
26381 | |
26382 | fsid_t f_fsid; /* file system id */ |
26383 | u_int32_t f_namemax; /* maximum filename length */ |
26384 | uid_t f_owner; /* user that mounted the file system */ |
26385 | u_int64_t f_ctime; /* last mount [-u] time */ |
26386 | |
26387 | char f_fstypename[MFSNAMELEN]; /* fs type name */ |
26388 | char f_mntonname[MNAMELEN]; /* directory on which mounted */ |
26389 | char f_mntfromname[MNAMELEN]; /* mounted file system */ |
26390 | char f_mntfromspec[MNAMELEN]; /* special for mount request */ |
26391 | union mount_info mount_info; /* per-filesystem mount options */ |
26392 | }; |
26393 | |
26394 | f\bfs\bst\bta\bat\btf\bfs\bs() returns the same information about an open file referenced by |
26395 | descriptor _\bf_\bd. |
26396 | |
26397 | Note that _\bf_\b__\bf_\bs_\bi_\bd will be empty unless the user is the superuser. |
26398 | |
26399 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26400 | Upon successful completion, the value 0 is returned; otherwise the |
26401 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
26402 | error. |
26403 | |
26404 | E\bER\bRR\bRO\bOR\bRS\bS |
26405 | s\bst\bta\bat\btf\bfs\bs() fails if one or more of the following are true: |
26406 | |
26407 | [ENOTDIR] A component of the path prefix of _\bp_\ba_\bt_\bh is not a |
26408 | directory. |
26409 | |
26410 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
26411 | characters, or an entire pathname (including the |
26412 | terminating NUL) exceeded PATH_MAX bytes. |
26413 | |
26414 | [ENOENT] The file referred to by _\bp_\ba_\bt_\bh does not exist. |
26415 | |
26416 | [EACCES] Search permission is denied for a component of the |
26417 | path prefix of _\bp_\ba_\bt_\bh. |
26418 | |
26419 | [ELOOP] Too many symbolic links were encountered in |
26420 | translating _\bp_\ba_\bt_\bh. |
26421 | |
26422 | [EFAULT] _\bb_\bu_\bf or _\bp_\ba_\bt_\bh points to an invalid address. |
26423 | |
26424 | [EIO] An I/O error occurred while reading from or writing to |
26425 | the file system. |
26426 | |
26427 | f\bfs\bst\bta\bat\btf\bfs\bs() fails if one or more of the following are true: |
26428 | |
26429 | [EBADF] _\bf_\bd is not a valid open file descriptor. |
26430 | |
26431 | [EFAULT] _\bb_\bu_\bf points to an invalid address. |
26432 | |
26433 | [EIO] An I/O error occurred while reading from or writing to |
26434 | the file system. |
26435 | |
26436 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26437 | df(1), getfsstat(2), mount(2), stat(2) |
26438 | |
26439 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26440 | The s\bst\bta\bat\btf\bfs\bs() function first appeared in 4.4BSD. |
26441 | |
26442 | N\bNA\bAM\bME\bE |
26443 | s\bsw\bwa\bap\bpc\bct\btl\bl - modify swap configuration |
26444 | |
26445 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26446 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
26447 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsw\bwa\bap\bp.\b.h\bh>\b> |
26448 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
26449 | |
26450 | _\bi_\bn_\bt |
26451 | s\bsw\bwa\bap\bpc\bct\btl\bl(_\bi_\bn_\bt _\bc_\bm_\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\ba_\br_\bg, _\bi_\bn_\bt _\bm_\bi_\bs_\bc); |
26452 | |
26453 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26454 | The s\bsw\bwa\bap\bpc\bct\btl\bl() function is used to add and delete swap devices, and modify |
26455 | their configuration. |
26456 | |
26457 | The _\bc_\bm_\bd parameter specifies the operation to be performed. The _\ba_\br_\bg and |
26458 | _\bm_\bi_\bs_\bc parameters have different meanings, depending on the _\bc_\bm_\bd parameter. |
26459 | |
26460 | If _\bc_\bm_\bd is SWAP_NSWAP, the current number of swap devices in the |
26461 | system is returned. The _\ba_\br_\bg and _\bm_\bi_\bs_\bc parameters are ignored. |
26462 | |
26463 | If _\bc_\bm_\bd is SWAP_STATS, the current statistics for swap devices are |
26464 | returned in the _\ba_\br_\bg parameter. No more than _\bm_\bi_\bs_\bc swap devices are |
26465 | returned. The _\ba_\br_\bg parameter should point to an array of at least |
26466 | _\bm_\bi_\bs_\bc struct swapent structures: |
26467 | |
26468 | struct swapent { |
26469 | dev_t se_dev; /* device id */ |
26470 | int se_flags; /* entry flags */ |
26471 | int se_nblks; /* total blocks */ |
26472 | int se_inuse; /* blocks in use */ |
26473 | int se_priority; /* priority */ |
26474 | char se_path[PATH_MAX]; /* path to entry */ |
26475 | }; |
26476 | |
26477 | The flags are defined as |
26478 | |
26479 | SWF_INUSE in use: we have swapped here |
26480 | SWF_ENABLE enabled: we can swap here |
26481 | SWF_BUSY busy: I/O happening here |
26482 | SWF_FAKE fake: still being built |
26483 | |
26484 | All but SWAP_NSWAP and SWAP_STATS require superuser privileges. |
26485 | |
26486 | If _\bc_\bm_\bd is SWAP_ON, the _\ba_\br_\bg parameter is used as a pathname of a |
26487 | file to enable swapping to. The _\bm_\bi_\bs_\bc parameter is used to set the |
26488 | priority of this swap device. |
26489 | |
26490 | If _\bc_\bm_\bd is SWAP_OFF, the _\ba_\br_\bg parameter is used as the pathname of a |
26491 | file to disable swapping from. The _\bm_\bi_\bs_\bc parameter is ignored. |
26492 | |
26493 | If _\bc_\bm_\bd is SWAP_CTL, the _\ba_\br_\bg and _\bm_\bi_\bs_\bc parameters have the same |
26494 | function as for the SWAP_ON case, except that they change the |
26495 | priority of a currently enabled swap device. |
26496 | |
26497 | When swapping is enabled on a block device, the first portion of the disk |
26498 | is left unused to prevent any disklabel present from being overwritten. |
26499 | This space is allocated from the swap device when the SWAP_ON command is |
26500 | used. |
26501 | |
26502 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26503 | If the _\bc_\bm_\bd parameter is SWAP_NSWAP or SWAP_STATS, s\bsw\bwa\bap\bpc\bct\btl\bl() returns the |
26504 | number of swap devices, if successful. The SWAP_NSWAP command is always |
26505 | successful. Otherwise it returns 0 on success and -1 on failure, setting |
26506 | the global variable _\be_\br_\br_\bn_\bo to indicate the error. |
26507 | |
26508 | E\bER\bRR\bRO\bOR\bRS\bS |
26509 | s\bsw\bwa\bap\bpc\bct\btl\bl() succeeds unless: |
26510 | |
26511 | [ENOTDIR] A component of the path prefix is not a directory. |
26512 | |
26513 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
26514 | characters, or an entire pathname (including the |
26515 | terminating NUL) exceeded PATH_MAX bytes. |
26516 | |
26517 | [ENOENT] The named device does not exist. For the SWAP_CTL |
26518 | command, the named device is not currently enabled for |
26519 | swapping. |
26520 | |
26521 | [EACCES] Search permission is denied for a component of the |
26522 | path prefix. |
26523 | |
26524 | [ELOOP] Too many symbolic links were encountered in |
26525 | translating the pathname. |
26526 | |
26527 | [EPERM] The caller is not the superuser. |
26528 | |
26529 | [EBUSY] The device specified by _\ba_\br_\bg has already been made |
26530 | available for swapping. |
26531 | |
26532 | [EINVAL] The device configured by _\ba_\br_\bg has no associated size, |
26533 | or the _\bc_\bm_\bd was unknown. |
26534 | |
26535 | [ENXIO] The major device number of _\ba_\br_\bg is out of range (this |
26536 | indicates no device driver exists for the associated |
26537 | hardware). |
26538 | |
26539 | [EIO] An I/O error occurred while opening the swap device. |
26540 | |
26541 | [EFAULT] _\ba_\br_\bg points outside the process' allocated address |
26542 | space. |
26543 | |
26544 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26545 | config(8), swapctl(8) |
26546 | |
26547 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26548 | The s\bsw\bwa\bap\bpc\bct\btl\bl() function call appeared in NetBSD 1.3. The _\bs_\be_\b__\bp_\ba_\bt_\bh member |
26549 | was added to _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bw_\ba_\bp_\be_\bn_\bt in NetBSD 1.4, when the header file was also |
26550 | moved from <_\bv_\bm_\b/_\bv_\bm_\b__\bs_\bw_\ba_\bp_\b._\bh>. |
26551 | |
26552 | A\bAU\bUT\bTH\bHO\bOR\bRS\bS |
26553 | The current swap system was designed and implemented by Matthew Green |
26554 | <_\bm_\br_\bg_\b@_\be_\bt_\be_\br_\bn_\ba_\b._\bc_\bo_\bm_\b._\ba_\bu>, with help from Paul Kranenburg <_\bp_\bk_\b@_\bN_\be_\bt_\bB_\bS_\bD_\b._\bO_\bR_\bG> and |
26555 | Leo Weppelman <_\bl_\be_\bo_\b@_\bN_\be_\bt_\bB_\bS_\bD_\b._\bO_\bR_\bG>, and insights from Jason R. Thorpe |
26556 | <_\bt_\bh_\bo_\br_\bp_\be_\bj_\b@_\bN_\be_\bt_\bB_\bS_\bD_\b._\bO_\bR_\bG>. |
26557 | |
26558 | N\bNA\bAM\bME\bE |
26559 | s\bsy\bym\bml\bli\bin\bnk\bk, s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt - make symbolic link to a file |
26560 | |
26561 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26562 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
26563 | |
26564 | _\bi_\bn_\bt |
26565 | s\bsy\bym\bml\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
26566 | |
26567 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
26568 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
26569 | |
26570 | _\bi_\bn_\bt |
26571 | s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
26572 | |
26573 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26574 | A symbolic link _\bn_\ba_\bm_\be_\b2 is created to _\bn_\ba_\bm_\be_\b1 (_\bn_\ba_\bm_\be_\b2 is the name of the file |
26575 | created, _\bn_\ba_\bm_\be_\b1 is the string used in creating the symbolic link). Either |
26576 | name may be an arbitrary path name; the files need not be on the same |
26577 | file system, and the file specified by _\bn_\ba_\bm_\be_\b1 need not exist at all. |
26578 | |
26579 | The s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() function is equivalent to s\bsy\bym\bml\bli\bin\bnk\bk() except that where |
26580 | _\bn_\ba_\bm_\be_\b2 specifies a relative path, the newly created symbolic link is |
26581 | created relative to the directory associated with file descriptor _\bf_\bd |
26582 | instead of the current working directory. |
26583 | |
26584 | If s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in |
26585 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used and |
26586 | the behavior is identical to a call to s\bsy\bym\bml\bli\bin\bnk\bk(). |
26587 | |
26588 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26589 | Upon successful completion, the value 0 is returned; otherwise the |
26590 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
26591 | error. |
26592 | |
26593 | E\bER\bRR\bRO\bOR\bRS\bS |
26594 | The symbolic link succeeds unless: |
26595 | |
26596 | [ENOTDIR] A component of the _\bn_\ba_\bm_\be_\b2 prefix is not a directory. |
26597 | |
26598 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
26599 | characters, or an entire pathname (including the |
26600 | terminating NUL) exceeded PATH_MAX bytes. |
26601 | |
26602 | [ENOENT] The named file does not exist. |
26603 | |
26604 | [EACCES] A component of the _\bn_\ba_\bm_\be_\b2 path prefix denies search |
26605 | permission. |
26606 | |
26607 | [ELOOP] Too many symbolic links were encountered in |
26608 | translating the pathname. |
26609 | |
26610 | [EEXIST] _\bn_\ba_\bm_\be_\b2 already exists. |
26611 | |
26612 | [EIO] An I/O error occurred while making the directory entry |
26613 | for _\bn_\ba_\bm_\be_\b2, or allocating the inode for _\bn_\ba_\bm_\be_\b2, or |
26614 | writing out the link contents of _\bn_\ba_\bm_\be_\b2. |
26615 | |
26616 | [EROFS] The file _\bn_\ba_\bm_\be_\b2 would reside on a read-only file |
26617 | system. |
26618 | |
26619 | [ENOSPC] The directory in which the entry for the new symbolic |
26620 | link is being placed cannot be extended because there |
26621 | is no space left on the file system containing the |
26622 | directory. |
26623 | |
26624 | [ENOSPC] The new symbolic link cannot be created because there |
26625 | is no space left on the file system that will contain |
26626 | the symbolic link. |
26627 | |
26628 | [ENOSPC] There are no free inodes on the file system on which |
26629 | the symbolic link is being created. |
26630 | |
26631 | [EDQUOT] The directory in which the entry for the new symbolic |
26632 | link is being placed cannot be extended because the |
26633 | user's quota of disk blocks on the file system |
26634 | containing the directory has been exhausted. |
26635 | |
26636 | [EDQUOT] The new symbolic link cannot be created because the |
26637 | user's quota of disk blocks on the file system that |
26638 | will contain the symbolic link has been exhausted. |
26639 | |
26640 | [EDQUOT] The user's quota of inodes on the file system on which |
26641 | the symbolic link is being created has been exhausted. |
26642 | |
26643 | [EIO] An I/O error occurred while making the directory entry |
26644 | or allocating the inode. |
26645 | |
26646 | [EFAULT] _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 points outside the process's allocated |
26647 | address space. |
26648 | |
26649 | Additionally, s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() will fail if: |
26650 | |
26651 | [EBADF] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path and the |
26652 | _\bf_\bd argument is neither AT_FDCWD nor a valid file |
26653 | descriptor. |
26654 | |
26655 | [ENOTDIR] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path and the |
26656 | _\bf_\bd argument is a valid file descriptor but it does not |
26657 | reference a directory. |
26658 | |
26659 | [EACCES] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path but |
26660 | search permission is denied for the directory which |
26661 | the _\bf_\bd file descriptor references. |
26662 | |
26663 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26664 | ln(1), link(2), readlink(2), unlink(2), symlink(7) |
26665 | |
26666 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
26667 | The s\bsy\bym\bml\bli\bin\bnk\bk() and s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
26668 | (``POSIX.1''). |
26669 | |
26670 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26671 | The s\bsy\bym\bml\bli\bin\bnk\bk() system call first appeared in 4.1cBSD. The s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() |
26672 | system call has been available since OpenBSD 5.0. |
26673 | |
26674 | N\bNA\bAM\bME\bE |
26675 | s\bsy\bym\bml\bli\bin\bnk\bk, s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt - make symbolic link to a file |
26676 | |
26677 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26678 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
26679 | |
26680 | _\bi_\bn_\bt |
26681 | s\bsy\bym\bml\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
26682 | |
26683 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
26684 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
26685 | |
26686 | _\bi_\bn_\bt |
26687 | s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b1, _\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be_\b2); |
26688 | |
26689 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26690 | A symbolic link _\bn_\ba_\bm_\be_\b2 is created to _\bn_\ba_\bm_\be_\b1 (_\bn_\ba_\bm_\be_\b2 is the name of the file |
26691 | created, _\bn_\ba_\bm_\be_\b1 is the string used in creating the symbolic link). Either |
26692 | name may be an arbitrary path name; the files need not be on the same |
26693 | file system, and the file specified by _\bn_\ba_\bm_\be_\b1 need not exist at all. |
26694 | |
26695 | The s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() function is equivalent to s\bsy\bym\bml\bli\bin\bnk\bk() except that where |
26696 | _\bn_\ba_\bm_\be_\b2 specifies a relative path, the newly created symbolic link is |
26697 | created relative to the directory associated with file descriptor _\bf_\bd |
26698 | instead of the current working directory. |
26699 | |
26700 | If s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in |
26701 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used and |
26702 | the behavior is identical to a call to s\bsy\bym\bml\bli\bin\bnk\bk(). |
26703 | |
26704 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26705 | Upon successful completion, the value 0 is returned; otherwise the |
26706 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
26707 | error. |
26708 | |
26709 | E\bER\bRR\bRO\bOR\bRS\bS |
26710 | The symbolic link succeeds unless: |
26711 | |
26712 | [ENOTDIR] A component of the _\bn_\ba_\bm_\be_\b2 prefix is not a directory. |
26713 | |
26714 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
26715 | characters, or an entire pathname (including the |
26716 | terminating NUL) exceeded PATH_MAX bytes. |
26717 | |
26718 | [ENOENT] The named file does not exist. |
26719 | |
26720 | [EACCES] A component of the _\bn_\ba_\bm_\be_\b2 path prefix denies search |
26721 | permission. |
26722 | |
26723 | [ELOOP] Too many symbolic links were encountered in |
26724 | translating the pathname. |
26725 | |
26726 | [EEXIST] _\bn_\ba_\bm_\be_\b2 already exists. |
26727 | |
26728 | [EIO] An I/O error occurred while making the directory entry |
26729 | for _\bn_\ba_\bm_\be_\b2, or allocating the inode for _\bn_\ba_\bm_\be_\b2, or |
26730 | writing out the link contents of _\bn_\ba_\bm_\be_\b2. |
26731 | |
26732 | [EROFS] The file _\bn_\ba_\bm_\be_\b2 would reside on a read-only file |
26733 | system. |
26734 | |
26735 | [ENOSPC] The directory in which the entry for the new symbolic |
26736 | link is being placed cannot be extended because there |
26737 | is no space left on the file system containing the |
26738 | directory. |
26739 | |
26740 | [ENOSPC] The new symbolic link cannot be created because there |
26741 | is no space left on the file system that will contain |
26742 | the symbolic link. |
26743 | |
26744 | [ENOSPC] There are no free inodes on the file system on which |
26745 | the symbolic link is being created. |
26746 | |
26747 | [EDQUOT] The directory in which the entry for the new symbolic |
26748 | link is being placed cannot be extended because the |
26749 | user's quota of disk blocks on the file system |
26750 | containing the directory has been exhausted. |
26751 | |
26752 | [EDQUOT] The new symbolic link cannot be created because the |
26753 | user's quota of disk blocks on the file system that |
26754 | will contain the symbolic link has been exhausted. |
26755 | |
26756 | [EDQUOT] The user's quota of inodes on the file system on which |
26757 | the symbolic link is being created has been exhausted. |
26758 | |
26759 | [EIO] An I/O error occurred while making the directory entry |
26760 | or allocating the inode. |
26761 | |
26762 | [EFAULT] _\bn_\ba_\bm_\be_\b1 or _\bn_\ba_\bm_\be_\b2 points outside the process's allocated |
26763 | address space. |
26764 | |
26765 | Additionally, s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() will fail if: |
26766 | |
26767 | [EBADF] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path and the |
26768 | _\bf_\bd argument is neither AT_FDCWD nor a valid file |
26769 | descriptor. |
26770 | |
26771 | [ENOTDIR] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path and the |
26772 | _\bf_\bd argument is a valid file descriptor but it does not |
26773 | reference a directory. |
26774 | |
26775 | [EACCES] The _\bn_\ba_\bm_\be_\b2 argument specifies a relative path but |
26776 | search permission is denied for the directory which |
26777 | the _\bf_\bd file descriptor references. |
26778 | |
26779 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26780 | ln(1), link(2), readlink(2), unlink(2), symlink(7) |
26781 | |
26782 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
26783 | The s\bsy\bym\bml\bli\bin\bnk\bk() and s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
26784 | (``POSIX.1''). |
26785 | |
26786 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26787 | The s\bsy\bym\bml\bli\bin\bnk\bk() system call first appeared in 4.1cBSD. The s\bsy\bym\bml\bli\bin\bnk\bka\bat\bt() |
26788 | system call has been available since OpenBSD 5.0. |
26789 | |
26790 | N\bNA\bAM\bME\bE |
26791 | s\bsy\byn\bnc\bc - synchronize disk block in-core status with that on disk |
26792 | |
26793 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26794 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
26795 | |
26796 | _\bv_\bo_\bi_\bd |
26797 | s\bsy\byn\bnc\bc(_\bv_\bo_\bi_\bd); |
26798 | |
26799 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26800 | The s\bsy\byn\bnc\bc() function forces a write of dirty (modified) buffers in the |
26801 | block buffer cache out to disk. The kernel keeps this information in |
26802 | core to reduce the number of disk I/O transfers required by the system. |
26803 | As information in the cache is lost after a system crash a s\bsy\byn\bnc\bc() call is |
26804 | issued frequently by the in-kernel process update (about every 30 |
26805 | seconds). |
26806 | |
26807 | The function fsync(2) may be used to synchronize individual file |
26808 | descriptor attributes. |
26809 | |
26810 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26811 | fsync(2), sync(8) |
26812 | |
26813 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
26814 | The s\bsy\byn\bnc\bc() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
26815 | |
26816 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26817 | A s\bsy\byn\bnc\bc() function call appeared in Version 2 AT&T UNIX. |
26818 | |
26819 | B\bBU\bUG\bGS\bS |
26820 | s\bsy\byn\bnc\bc() may return before the buffers are completely flushed. |
26821 | |
26822 | N\bNA\bAM\bME\bE |
26823 | s\bsy\bys\bsa\bar\brc\bch\bh - architecture-dependent system call |
26824 | |
26825 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26826 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
26827 | |
26828 | _\bi_\bn_\bt |
26829 | s\bsy\bys\bsa\bar\brc\bch\bh(_\bi_\bn_\bt _\bn_\bu_\bm_\bb_\be_\br, _\bv_\bo_\bi_\bd _\b*_\ba_\br_\bg_\bs); |
26830 | |
26831 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26832 | s\bsy\bys\bsa\bar\brc\bch\bh() performs the architecture-dependent function specified by |
26833 | _\bn_\bu_\bm_\bb_\be_\br with the arguments specified by the _\ba_\br_\bg_\bs pointer. _\ba_\br_\bg_\bs is a |
26834 | pointer to a structure defining the actual arguments of the function. |
26835 | Symbolic constants and argument structures for the architecture-dependent |
26836 | functions can be found in the header file <_\bm_\ba_\bc_\bh_\bi_\bn_\be_\b/_\bs_\by_\bs_\ba_\br_\bc_\bh_\b._\bh>. |
26837 | |
26838 | The s\bsy\bys\bsa\bar\brc\bch\bh() system call should never be called directly by user |
26839 | programs. Instead, they should access its functions using the |
26840 | architecture-dependent library. |
26841 | |
26842 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26843 | See the manual pages for specific architecture-dependent function calls |
26844 | for information about their return values. |
26845 | |
26846 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26847 | The s\bsy\bys\bsa\bar\brc\bch\bh() function call appeared in NetBSD 0.9a. |
26848 | |
26849 | N\bNA\bAM\bME\bE |
26850 | s\bsy\bys\bsc\bca\bal\bll\bl, _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl - indirect system call |
26851 | |
26852 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26853 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bsy\bys\bsc\bca\bal\bll\bl.\b.h\bh>\b> |
26854 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
26855 | |
26856 | _\bi_\bn_\bt |
26857 | s\bsy\bys\bsc\bca\bal\bll\bl(_\bi_\bn_\bt _\bn_\bu_\bm_\bb_\be_\br, _\b._\b._\b.); |
26858 | |
26859 | _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl(_\bq_\bu_\ba_\bd_\b__\bt _\bn_\bu_\bm_\bb_\be_\br, _\b._\b._\b.); |
26860 | |
26861 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26862 | s\bsy\bys\bsc\bca\bal\bll\bl() performs the system call whose assembly language interface has |
26863 | the specified _\bn_\bu_\bm_\bb_\be_\br with the specified arguments. Symbolic constants |
26864 | for system calls can be found in the header file <_\bs_\by_\bs_\b/_\bs_\by_\bs_\bc_\ba_\bl_\bl_\b._\bh>. |
26865 | |
26866 | Since different system calls have different return types, a prototype of |
26867 | _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl specifying the correct return type should be declared locally. |
26868 | This is especially important for system calls returning larger-than-int |
26869 | results. |
26870 | |
26871 | The _\b__\b_s\bsy\bys\bsc\bca\bal\bll\bl form should be used when one or more of the parameters is a |
26872 | 64-bit argument to ensure that argument alignment is correct. This |
26873 | system call is useful for testing new system calls that do not have |
26874 | entries in the C library. |
26875 | |
26876 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26877 | The return values are defined by the system call being invoked. In |
26878 | general, for system calls returning _\bi_\bn_\bt, a 0 return value indicates |
26879 | success. A -1 return value indicates an error, and an error code is |
26880 | stored in _\be_\br_\br_\bn_\bo. |
26881 | |
26882 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26883 | The predecessor of these functions, the former i\bin\bnd\bdi\bir\br() system call, first |
26884 | appeared in Version 4 AT&T UNIX. The s\bsy\bys\bsc\bca\bal\bll\bl() function first appeared |
26885 | in 3BSD. |
26886 | |
26887 | B\bBU\bUG\bGS\bS |
26888 | There is no way to simulate system calls that have multiple return values |
26889 | such as pipe(2). |
26890 | |
26891 | N\bNA\bAM\bME\bE |
26892 | t\btr\bru\bun\bnc\bca\bat\bte\be, f\bft\btr\bru\bun\bnc\bca\bat\bte\be - truncate or extend a file to a specified length |
26893 | |
26894 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26895 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
26896 | |
26897 | _\bi_\bn_\bt |
26898 | t\btr\bru\bun\bnc\bca\bat\bte\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bo_\bf_\bf_\b__\bt _\bl_\be_\bn_\bg_\bt_\bh); |
26899 | |
26900 | _\bi_\bn_\bt |
26901 | f\bft\btr\bru\bun\bnc\bca\bat\bte\be(_\bi_\bn_\bt _\bf_\bd, _\bo_\bf_\bf_\b__\bt _\bl_\be_\bn_\bg_\bt_\bh); |
26902 | |
26903 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26904 | t\btr\bru\bun\bnc\bca\bat\bte\be() causes the file named by _\bp_\ba_\bt_\bh or referenced by _\bf_\bd to be |
26905 | truncated or extended to _\bl_\be_\bn_\bg_\bt_\bh bytes in size. If the file was larger |
26906 | than this size, the extra data is lost. If the file was smaller than |
26907 | this size, it will be extended as if by writing bytes with the value |
26908 | zero. With f\bft\btr\bru\bun\bnc\bca\bat\bte\be(), the file must be open for writing. |
26909 | |
26910 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26911 | Upon successful completion, the value 0 is returned; otherwise the |
26912 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
26913 | error. |
26914 | |
26915 | E\bER\bRR\bRO\bOR\bRS\bS |
26916 | t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() will succeed unless: |
26917 | |
26918 | [EINVAL] The _\bl_\be_\bn_\bg_\bt_\bh is a negative value. |
26919 | |
26920 | [EIO] An I/O error occurred updating the inode. |
26921 | |
26922 | In addition, t\btr\bru\bun\bnc\bca\bat\bte\be() may return the following errors: |
26923 | |
26924 | [ENOTDIR] A component of the path prefix is not a directory. |
26925 | |
26926 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
26927 | characters, or an entire pathname (including the |
26928 | terminating NUL) exceeded PATH_MAX bytes. |
26929 | |
26930 | [ENOENT] The named file does not exist. |
26931 | |
26932 | [EACCES] Search permission is denied for a component of the |
26933 | path prefix. |
26934 | |
26935 | [EACCES] The named file is not writable by the user. |
26936 | |
26937 | [ELOOP] Too many symbolic links were encountered in |
26938 | translating the pathname. |
26939 | |
26940 | [EISDIR] The named file is a directory. |
26941 | |
26942 | [EROFS] The named file resides on a read-only file system. |
26943 | |
26944 | [ETXTBSY] The file is a pure procedure (shared text) file that |
26945 | is being executed. |
26946 | |
26947 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
26948 | space. |
26949 | |
26950 | f\bft\btr\bru\bun\bnc\bca\bat\bte\be() may return the following errors: |
26951 | |
26952 | [EBADF] The _\bf_\bd is not a valid descriptor. |
26953 | |
26954 | [EINVAL] The _\bf_\bd references a socket, not a file. |
26955 | |
26956 | [EINVAL] The _\bf_\bd is not open for writing. |
26957 | |
26958 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
26959 | open(2) |
26960 | |
26961 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
26962 | The t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() functions conform to IEEE Std 1003.1-2008 |
26963 | (``POSIX.1''). |
26964 | |
26965 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
26966 | The t\btr\bru\bun\bnc\bca\bat\bte\be() and f\bft\btr\bru\bun\bnc\bca\bat\bte\be() system calls first appeared in 4.1cBSD. |
26967 | |
26968 | B\bBU\bUG\bGS\bS |
26969 | These calls should be generalized to allow ranges of bytes in a file to |
26970 | be discarded. |
26971 | |
26972 | Use of t\btr\bru\bun\bnc\bca\bat\bte\be() to extend a file is not portable. |
26973 | |
26974 | N\bNA\bAM\bME\bE |
26975 | u\bum\bma\bas\bsk\bk - set file creation mode mask |
26976 | |
26977 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
26978 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
26979 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
26980 | |
26981 | _\bm_\bo_\bd_\be_\b__\bt |
26982 | u\bum\bma\bas\bsk\bk(_\bm_\bo_\bd_\be_\b__\bt _\bn_\bu_\bm_\ba_\bs_\bk); |
26983 | |
26984 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
26985 | The u\bum\bma\bas\bsk\bk() routine sets the process's file mode creation mask to _\bn_\bu_\bm_\ba_\bs_\bk |
26986 | and returns the previous value of the mask. The 9 low-order access |
26987 | permission bits of _\bn_\bu_\bm_\ba_\bs_\bk are used by system calls, including open(2), |
26988 | mkdir(2), mkfifo(2) and mknod(2) to turn off corresponding bits requested |
26989 | in the file mode (see chmod(2)). This clearing allows each user to |
26990 | restrict the default access to his files. |
26991 | |
26992 | The default mask value is S_IWGRP|S_IWOTH (022, write access for the |
26993 | owner only). Child processes inherit the mask of the calling process. |
26994 | |
26995 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
26996 | The previous value of the file mode mask is returned by the call. |
26997 | |
26998 | E\bER\bRR\bRO\bOR\bRS\bS |
26999 | The u\bum\bma\bas\bsk\bk() function is always successful. |
27000 | |
27001 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
27002 | chmod(2), mkdir(2), mkfifo(2), mknod(2), open(2) |
27003 | |
27004 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
27005 | The u\bum\bma\bas\bsk\bk() function conforms to IEEE Std 1003.1-2008 (``POSIX.1''). |
27006 | |
27007 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
27008 | The u\bum\bma\bas\bsk\bk() system call first appeared in Version 7 AT&T UNIX. |
27009 | |
27010 | N\bNA\bAM\bME\bE |
27011 | u\bun\bnl\bli\bin\bnk\bk, u\bun\bnl\bli\bin\bnk\bka\bat\bt - remove directory entry |
27012 | |
27013 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
27014 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
27015 | |
27016 | _\bi_\bn_\bt |
27017 | u\bun\bnl\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
27018 | |
27019 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
27020 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
27021 | |
27022 | _\bi_\bn_\bt |
27023 | u\bun\bnl\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
27024 | |
27025 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
27026 | The u\bun\bnl\bli\bin\bnk\bk() function removes the link named by _\bp_\ba_\bt_\bh from its directory |
27027 | and decrements the link count of the file which was referenced by the |
27028 | link. If that decrement reduces the link count of the file to zero, and |
27029 | no process has the file open, then all resources associated with the file |
27030 | are reclaimed. If one or more processes have the file open when the last |
27031 | link is removed, the link is removed, but the removal of the file is |
27032 | delayed until all references to it have been closed. |
27033 | |
27034 | The u\bun\bnl\bli\bin\bnk\bka\bat\bt() function is equivalent to either the u\bun\bnl\bli\bin\bnk\bk() or rmdir(2) |
27035 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
27036 | _\bp_\ba_\bt_\bh specifies a relative path, the directory entry to be removed is |
27037 | determined relative to the directory associated with file descriptor _\bf_\bd |
27038 | instead of the current working directory. |
27039 | |
27040 | If u\bun\bnl\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
27041 | in the _\bf_\bd parameter, the current working directory is used and the |
27042 | behavior is identical to a call to u\bun\bnl\bli\bin\bnk\bk() or rmdir(2), depending on |
27043 | whether or not the AT_REMOVEDIR bit is set in _\bf_\bl_\ba_\bg. |
27044 | |
27045 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
27046 | values: |
27047 | |
27048 | AT_REMOVEDIR Remove the directory entry specified by _\bp_\ba_\bt_\bh as a |
27049 | directory, not a normal file. |
27050 | |
27051 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
27052 | Upon successful completion, the value 0 is returned; otherwise the |
27053 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
27054 | error. |
27055 | |
27056 | E\bER\bRR\bRO\bOR\bRS\bS |
27057 | The u\bun\bnl\bli\bin\bnk\bk() and u\bun\bnl\bli\bin\bnk\bka\bat\bt() functions will fail if: |
27058 | |
27059 | [ENOTDIR] A component of the path prefix is not a directory. |
27060 | |
27061 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
27062 | characters, or an entire pathname (including the |
27063 | terminating NUL) exceeded PATH_MAX bytes. |
27064 | |
27065 | [ENOENT] The named file does not exist. |
27066 | |
27067 | [EACCES] Search permission is denied for a component of the |
27068 | path prefix. |
27069 | |
27070 | [EACCES] Write permission is denied on the directory containing |
27071 | the link to be removed. |
27072 | |
27073 | [ELOOP] Too many symbolic links were encountered in |
27074 | translating the pathname. |
27075 | |
27076 | [EPERM] The named file is a directory and the effective user |
27077 | ID of the process is not the superuser, or the file |
27078 | system containing the file does not permit the use of |
27079 | u\bun\bnl\bli\bin\bnk\bk() on a directory. |
27080 | |
27081 | [EPERM] The directory containing the file is marked sticky, |
27082 | and neither the containing directory nor the file to |
27083 | be removed are owned by the effective user ID. |
27084 | |
27085 | [EPERM] The named file or the directory containing it has its |
27086 | immutable or append-only flag set (see chflags(2)). |
27087 | |
27088 | [EBUSY] The entry to be unlinked is the mount point for a |
27089 | mounted file system. |
27090 | |
27091 | [EIO] An I/O error occurred while deleting the directory |
27092 | entry or deallocating the inode. |
27093 | |
27094 | [EROFS] The named file resides on a read-only file system. |
27095 | |
27096 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
27097 | space. |
27098 | |
27099 | Additionally, u\bun\bnl\bli\bin\bnk\bka\bat\bt() will fail if: |
27100 | |
27101 | [ENOTDIR] The AT_REMOVEDIR flag bit is set and _\bp_\ba_\bt_\bh does not |
27102 | name a directory. |
27103 | |
27104 | [ENOTEMPTY] The AT_REMOVEDIR flag bit is set and the named |
27105 | directory contains files other than `.' and `..' in |
27106 | it. |
27107 | |
27108 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
27109 | AT_REMOVEDIR. |
27110 | |
27111 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
27112 | argument is neither AT_FDCWD nor a valid file |
27113 | descriptor. |
27114 | |
27115 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
27116 | argument is a valid file descriptor but it does not |
27117 | reference a directory. |
27118 | |
27119 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
27120 | permission is denied for the directory which the _\bf_\bd |
27121 | file descriptor references. |
27122 | |
27123 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
27124 | rm(1), chflags(2), close(2), link(2), rmdir(2), symlink(7) |
27125 | |
27126 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
27127 | The u\bun\bnl\bli\bin\bnk\bk() and u\bun\bnl\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
27128 | (``POSIX.1''). |
27129 | |
27130 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
27131 | The u\bun\bnl\bli\bin\bnk\bk() system call first appeared in Version 1 AT&T UNIX. The |
27132 | u\bun\bnl\bli\bin\bnk\bka\bat\bt() function appeared in OpenBSD 5.0. |
27133 | |
27134 | N\bNA\bAM\bME\bE |
27135 | u\bun\bnl\bli\bin\bnk\bk, u\bun\bnl\bli\bin\bnk\bka\bat\bt - remove directory entry |
27136 | |
27137 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
27138 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
27139 | |
27140 | _\bi_\bn_\bt |
27141 | u\bun\bnl\bli\bin\bnk\bk(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh); |
27142 | |
27143 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
27144 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
27145 | |
27146 | _\bi_\bn_\bt |
27147 | u\bun\bnl\bli\bin\bnk\bka\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
27148 | |
27149 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
27150 | The u\bun\bnl\bli\bin\bnk\bk() function removes the link named by _\bp_\ba_\bt_\bh from its directory |
27151 | and decrements the link count of the file which was referenced by the |
27152 | link. If that decrement reduces the link count of the file to zero, and |
27153 | no process has the file open, then all resources associated with the file |
27154 | are reclaimed. If one or more processes have the file open when the last |
27155 | link is removed, the link is removed, but the removal of the file is |
27156 | delayed until all references to it have been closed. |
27157 | |
27158 | The u\bun\bnl\bli\bin\bnk\bka\bat\bt() function is equivalent to either the u\bun\bnl\bli\bin\bnk\bk() or rmdir(2) |
27159 | function depending on the value of _\bf_\bl_\ba_\bg (see below), except that where |
27160 | _\bp_\ba_\bt_\bh specifies a relative path, the directory entry to be removed is |
27161 | determined relative to the directory associated with file descriptor _\bf_\bd |
27162 | instead of the current working directory. |
27163 | |
27164 | If u\bun\bnl\bli\bin\bnk\bka\bat\bt() is passed the special value AT_FDCWD (defined in <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) |
27165 | in the _\bf_\bd parameter, the current working directory is used and the |
27166 | behavior is identical to a call to u\bun\bnl\bli\bin\bnk\bk() or rmdir(2), depending on |
27167 | whether or not the AT_REMOVEDIR bit is set in _\bf_\bl_\ba_\bg. |
27168 | |
27169 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
27170 | values: |
27171 | |
27172 | AT_REMOVEDIR Remove the directory entry specified by _\bp_\ba_\bt_\bh as a |
27173 | directory, not a normal file. |
27174 | |
27175 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
27176 | Upon successful completion, the value 0 is returned; otherwise the |
27177 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
27178 | error. |
27179 | |
27180 | E\bER\bRR\bRO\bOR\bRS\bS |
27181 | The u\bun\bnl\bli\bin\bnk\bk() and u\bun\bnl\bli\bin\bnk\bka\bat\bt() functions will fail if: |
27182 | |
27183 | [ENOTDIR] A component of the path prefix is not a directory. |
27184 | |
27185 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
27186 | characters, or an entire pathname (including the |
27187 | terminating NUL) exceeded PATH_MAX bytes. |
27188 | |
27189 | [ENOENT] The named file does not exist. |
27190 | |
27191 | [EACCES] Search permission is denied for a component of the |
27192 | path prefix. |
27193 | |
27194 | [EACCES] Write permission is denied on the directory containing |
27195 | the link to be removed. |
27196 | |
27197 | [ELOOP] Too many symbolic links were encountered in |
27198 | translating the pathname. |
27199 | |
27200 | [EPERM] The named file is a directory and the effective user |
27201 | ID of the process is not the superuser, or the file |
27202 | system containing the file does not permit the use of |
27203 | u\bun\bnl\bli\bin\bnk\bk() on a directory. |
27204 | |
27205 | [EPERM] The directory containing the file is marked sticky, |
27206 | and neither the containing directory nor the file to |
27207 | be removed are owned by the effective user ID. |
27208 | |
27209 | [EPERM] The named file or the directory containing it has its |
27210 | immutable or append-only flag set (see chflags(2)). |
27211 | |
27212 | [EBUSY] The entry to be unlinked is the mount point for a |
27213 | mounted file system. |
27214 | |
27215 | [EIO] An I/O error occurred while deleting the directory |
27216 | entry or deallocating the inode. |
27217 | |
27218 | [EROFS] The named file resides on a read-only file system. |
27219 | |
27220 | [EFAULT] _\bp_\ba_\bt_\bh points outside the process's allocated address |
27221 | space. |
27222 | |
27223 | Additionally, u\bun\bnl\bli\bin\bnk\bka\bat\bt() will fail if: |
27224 | |
27225 | [ENOTDIR] The AT_REMOVEDIR flag bit is set and _\bp_\ba_\bt_\bh does not |
27226 | name a directory. |
27227 | |
27228 | [ENOTEMPTY] The AT_REMOVEDIR flag bit is set and the named |
27229 | directory contains files other than `.' and `..' in |
27230 | it. |
27231 | |
27232 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
27233 | AT_REMOVEDIR. |
27234 | |
27235 | [EBADF] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
27236 | argument is neither AT_FDCWD nor a valid file |
27237 | descriptor. |
27238 | |
27239 | [ENOTDIR] The _\bp_\ba_\bt_\bh argument specifies a relative path and the _\bf_\bd |
27240 | argument is a valid file descriptor but it does not |
27241 | reference a directory. |
27242 | |
27243 | [EACCES] The _\bp_\ba_\bt_\bh argument specifies a relative path but search |
27244 | permission is denied for the directory which the _\bf_\bd |
27245 | file descriptor references. |
27246 | |
27247 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
27248 | rm(1), chflags(2), close(2), link(2), rmdir(2), symlink(7) |
27249 | |
27250 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
27251 | The u\bun\bnl\bli\bin\bnk\bk() and u\bun\bnl\bli\bin\bnk\bka\bat\bt() functions conform to IEEE Std 1003.1-2008 |
27252 | (``POSIX.1''). |
27253 | |
27254 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
27255 | The u\bun\bnl\bli\bin\bnk\bk() system call first appeared in Version 1 AT&T UNIX. The |
27256 | u\bun\bnl\bli\bin\bnk\bka\bat\bt() function appeared in OpenBSD 5.0. |
27257 | |
27258 | N\bNA\bAM\bME\bE |
27259 | m\bmo\bou\bun\bnt\bt, u\bun\bnm\bmo\bou\bun\bnt\bt - mount or dismount a filesystem |
27260 | |
27261 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
27262 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
27263 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/m\bmo\bou\bun\bnt\bt.\b.h\bh>\b> |
27264 | |
27265 | _\bi_\bn_\bt |
27266 | m\bmo\bou\bun\bnt\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bt_\by_\bp_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bv_\bo_\bi_\bd _\b*_\bd_\ba_\bt_\ba); |
27267 | |
27268 | _\bi_\bn_\bt |
27269 | u\bun\bnm\bmo\bou\bun\bnt\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bd_\bi_\br, _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs); |
27270 | |
27271 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
27272 | The m\bmo\bou\bun\bnt\bt() function grafts a filesystem object onto the system file tree |
27273 | at the point _\bd_\bi_\br. The argument _\bd_\ba_\bt_\ba describes the filesystem object to |
27274 | be mounted. The argument _\bt_\by_\bp_\be tells the kernel how to interpret _\bd_\ba_\bt_\ba |
27275 | (see _\bt_\by_\bp_\be below). The contents of the filesystem become available |
27276 | through the new mount point _\bd_\bi_\br. Any files in _\bd_\bi_\br at the time of a |
27277 | successful mount are swept under the carpet, so to speak, and are |
27278 | unavailable until the filesystem is unmounted. |
27279 | |
27280 | The following _\bf_\bl_\ba_\bg_\bs may be specified to suppress default semantics which |
27281 | affect filesystem access. |
27282 | |
27283 | MNT_RDONLY The filesystem should be treated as read-only: even the |
27284 | superuser may not write to it. |
27285 | |
27286 | MNT_NOATIME Do not update the access time on files in the filesystem |
27287 | unless the modification or status change times are also |
27288 | being updated. |
27289 | |
27290 | MNT_NOEXEC Do not allow files to be executed from the filesystem. |
27291 | |
27292 | MNT_NOSUID Do not honor setuid or setgid bits on files when |
27293 | executing them. |
27294 | |
27295 | MNT_NODEV Do not interpret special files on the filesystem. |
27296 | |
27297 | MNT_SYNCHRONOUS All I/O to the filesystem should be done synchronously. |
27298 | |
27299 | MNT_ASYNC All I/O to the filesystem should be done asynchronously. |
27300 | |
27301 | MNT_SOFTDEP Use soft dependencies. Applies to FFS filesystems only |
27302 | (see 'softdep' in mount(8)). |
27303 | |
27304 | The flag MNT_UPDATE indicates that the mount command is being applied to |
27305 | an already mounted filesystem. This allows the mount flags to be changed |
27306 | without requiring that the filesystem be unmounted and remounted. Some |
27307 | filesystems may not allow all flags to be changed. For example, most |
27308 | filesystems will not allow a change from read-write to read-only. |
27309 | |
27310 | The _\bt_\by_\bp_\be argument defines the type of the filesystem. The types of |
27311 | filesystems known to the system are defined in <_\bs_\by_\bs_\b/_\bm_\bo_\bu_\bn_\bt_\b._\bh>. _\bd_\ba_\bt_\ba is a |
27312 | pointer to a structure that contains the type specific arguments to |
27313 | mount. The currently supported types of filesystems and their type |
27314 | specific data are: |
27315 | |
27316 | MOUNT_CD9660 |
27317 | struct iso_args { |
27318 | char *fspec; /* block special device to mount */ |
27319 | struct export_args export_info; |
27320 | /* network export info */ |
27321 | int flags; /* mounting flags, see below */ |
27322 | }; |
27323 | #define ISOFSMNT_NORRIP 0x00000001 /* disable Rock Ridge Ext.*/ |
27324 | #define ISOFSMNT_GENS 0x00000002 /* enable generation numbers */ |
27325 | #define ISOFSMNT_EXTATT 0x00000004 /* enable extended attributes */ |
27326 | #define ISOFSMNT_NOJOLIET 0x00000008 /* disable Joliet Ext.*/ |
27327 | #define ISOFSMNT_SESS 0x00000010 /* use iso_args.sess */ |
27328 | |
27329 | MOUNT_FFS |
27330 | struct ufs_args { |
27331 | char *fspec; /* block special file to mount */ |
27332 | struct export_args export_info; |
27333 | /* network export information */ |
27334 | }; |
27335 | |
27336 | MOUNT_MFS |
27337 | struct mfs_args { |
27338 | char *fspec; /* name to export for statfs */ |
27339 | struct export_args export_info; |
27340 | /* if we can export an MFS */ |
27341 | caddr_t base; /* base of filesystem in mem */ |
27342 | u_long size; /* size of filesystem */ |
27343 | }; |
27344 | |
27345 | MOUNT_MSDOS |
27346 | struct msdosfs_args { |
27347 | char *fspec; /* blocks special holding fs to mount */ |
27348 | struct export_args export_info; |
27349 | /* network export information */ |
27350 | uid_t uid; /* uid that owns msdosfs files */ |
27351 | gid_t gid; /* gid that owns msdosfs files */ |
27352 | mode_t mask; /* mask to be applied for msdosfs perms */ |
27353 | int flags; /* see below */ |
27354 | }; |
27355 | |
27356 | /* |
27357 | * Msdosfs mount options: |
27358 | */ |
27359 | #define MSDOSFSMNT_SHORTNAME 1 /* Force old DOS short names only */ |
27360 | #define MSDOSFSMNT_LONGNAME 2 /* Force Win'95 long names */ |
27361 | #define MSDOSFSMNT_NOWIN95 4 /* Completely ignore Win95 entries */ |
27362 | |
27363 | MOUNT_NFS |
27364 | struct nfs_args { |
27365 | int version; /* args structure version */ |
27366 | struct sockaddr *addr; /* file server address */ |
27367 | int addrlen; /* length of address */ |
27368 | int sotype; /* Socket type */ |
27369 | int proto; /* and Protocol */ |
27370 | u_char *fh; /* File handle to be mounted */ |
27371 | int fhsize; /* Size, in bytes, of fh */ |
27372 | int flags; /* flags */ |
27373 | int wsize; /* write size in bytes */ |
27374 | int rsize; /* read size in bytes */ |
27375 | int readdirsize; /* readdir size in bytes */ |
27376 | int timeo; /* initial timeout in .1 secs */ |
27377 | int retrans; /* times to retry send */ |
27378 | int maxgrouplist; /* Max. size of group list */ |
27379 | int readahead; /* # of blocks to readahead */ |
27380 | int leaseterm; /* Term (sec) of lease */ |
27381 | int deadthresh; /* Retrans threshold */ |
27382 | char *hostname; /* server's name */ |
27383 | int acregmin; /* Attr cache file recently modified */ |
27384 | int acregmax; /* ac file not recently modified */ |
27385 | int acdirmin; /* ac for dir recently modified */ |
27386 | int acdirmax; /* ac for dir not recently modified */ |
27387 | }; |
27388 | |
27389 | MOUNT_NTFS |
27390 | struct ntfs_args { |
27391 | char *fspec; /* block special device to mount */ |
27392 | struct export_args export_info; |
27393 | /* network export information */ |
27394 | uid_t uid; /* uid that owns ntfs files */ |
27395 | gid_t gid; /* gid that owns ntfs files */ |
27396 | mode_t mode; /* mask to be applied for ntfs perms */ |
27397 | u_long flag; /* additional flags */ |
27398 | }; |
27399 | |
27400 | /* |
27401 | * ntfs mount options: |
27402 | */ |
27403 | #define NTFS_MFLAG_CASEINS 0x00000001 |
27404 | #define NTFS_MFLAG_ALLNAMES 0x00000002 |
27405 | |
27406 | MOUNT_UDF |
27407 | struct udf_args { |
27408 | char *fspec; /* block special device to mount */ |
27409 | }; |
27410 | |
27411 | The u\bun\bnm\bmo\bou\bun\bnt\bt() function call disassociates the filesystem from the |
27412 | specified mount point _\bd_\bi_\br. |
27413 | |
27414 | The _\bf_\bl_\ba_\bg_\bs argument may specify MNT_FORCE to specify that the filesystem |
27415 | should be forcibly unmounted even if files are still active. Active |
27416 | special devices continue to work, but any further accesses to any other |
27417 | active files result in errors even if the filesystem is later remounted. |
27418 | |
27419 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
27420 | Upon successful completion, the value 0 is returned; otherwise the |
27421 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
27422 | error. |
27423 | |
27424 | E\bER\bRR\bRO\bOR\bRS\bS |
27425 | m\bmo\bou\bun\bnt\bt() will fail when one of the following occurs: |
27426 | |
27427 | [EPERM] The caller is not the superuser. |
27428 | |
27429 | [ENAMETOOLONG] The path name exceeded {MNAMELEN} characters. |
27430 | |
27431 | [ELOOP] Too many symbolic links were encountered in translating a |
27432 | pathname. |
27433 | |
27434 | [ENOENT] A component of _\bd_\bi_\br does not exist. |
27435 | |
27436 | [ENOTDIR] A component of _\bn_\ba_\bm_\be is not a directory, or a path prefix |
27437 | of _\bs_\bp_\be_\bc_\bi_\ba_\bl is not a directory. |
27438 | |
27439 | [EINVAL] An argument given was invalid. |
27440 | |
27441 | [EBUSY] Another process currently holds a reference to _\bd_\bi_\br. |
27442 | |
27443 | [EFAULT] _\bd_\bi_\br points outside the process's allocated address space. |
27444 | |
27445 | [EOPNOTSUPP] _\bt_\by_\bp_\be is not supported by the kernel. |
27446 | |
27447 | The following errors can occur for a ``ufs'' filesystem mount: |
27448 | |
27449 | [ENODEV] A component of ufs_args _\bf_\bs_\bp_\be_\bc does not exist. |
27450 | |
27451 | [ENOTBLK] _\bf_\bs_\bp_\be_\bc is not a block device. |
27452 | |
27453 | [ENXIO] The major device number of _\bf_\bs_\bp_\be_\bc is out of range (this |
27454 | indicates no device driver exists for the associated |
27455 | hardware). |
27456 | |
27457 | [EBUSY] _\bf_\bs_\bp_\be_\bc is already mounted. |
27458 | |
27459 | [EINVAL] The super block for the filesystem had a bad magic number, an |
27460 | out of range block size, or an invalid combination of flags. |
27461 | |
27462 | [ENOMEM] Not enough memory was available to read the cylinder group |
27463 | information for the filesystem. |
27464 | |
27465 | [EIO] An I/O error occurred while reading the super block or |
27466 | cylinder group information. |
27467 | |
27468 | [EFAULT] _\bf_\bs_\bp_\be_\bc points outside the process's allocated address space. |
27469 | |
27470 | [EROFS] The filesystem was not unmounted cleanly and MNT_FORCE was not |
27471 | specified. |
27472 | |
27473 | [EROFS] An attempt was made to mount a 4.2BSD filesystem without the |
27474 | MNT_RDONLY flag. |
27475 | |
27476 | The following errors can occur for an _\bN_\bF_\bS filesystem mount: |
27477 | |
27478 | [ETIMEDOUT] _\bN_\bF_\bS timed out trying to contact the server. |
27479 | |
27480 | [EFAULT] Some part of the information described by nfs_args points |
27481 | outside the process's allocated address space. |
27482 | |
27483 | The following errors can occur for a _\bm_\bf_\bs filesystem mount: |
27484 | |
27485 | [EMFILE] No space remains in the mount table. |
27486 | |
27487 | [EINVAL] The super block for the filesystem had a bad magic number or an |
27488 | out of range block size. |
27489 | |
27490 | [ENOMEM] Not enough memory was available to read the cylinder group |
27491 | information for the filesystem. |
27492 | |
27493 | [EIO] A paging error occurred while reading the super block or |
27494 | cylinder group information. |
27495 | |
27496 | [EFAULT] _\bN_\ba_\bm_\be points outside the process's allocated address space. |
27497 | |
27498 | u\bun\bnm\bmo\bou\bun\bnt\bt() may fail with one of the following errors: |
27499 | |
27500 | [EPERM] The caller is not the superuser. |
27501 | |
27502 | [ENOTDIR] A component of the path is not a directory. |
27503 | |
27504 | [EINVAL] An argument given was invalid. |
27505 | |
27506 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX characters, |
27507 | or an entire pathname (including the terminating NUL) |
27508 | exceeded PATH_MAX bytes. |
27509 | |
27510 | [ELOOP] Too many symbolic links were encountered in translating |
27511 | the pathname. |
27512 | |
27513 | [EINVAL] The requested directory is not in the mount table. |
27514 | |
27515 | [EBUSY] A process is holding a reference to a file located on the |
27516 | filesystem. |
27517 | |
27518 | [EIO] An I/O error occurred while writing cached filesystem |
27519 | information. |
27520 | |
27521 | [EFAULT] _\bd_\bi_\br points outside the process's allocated address space. |
27522 | |
27523 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
27524 | statfs(2), mfs(8), mount(8), umount(8) |
27525 | |
27526 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
27527 | The m\bmo\bou\bun\bnt\bt() and u\bun\bnm\bmo\bou\bun\bnt\bt() system calls first appeared in Version 1 AT&T |
27528 | UNIX. The _\bf_\bl_\ba_\bg_\bs argument is supported by m\bmo\bou\bun\bnt\bt() since Version 5 AT&T |
27529 | UNIX and by u\bun\bnm\bmo\bou\bun\bnt\bt() since 4.3BSD-Reno. The current calling convention |
27530 | involving _\bt_\by_\bp_\be and _\bd_\ba_\bt_\ba arguments was introduced by 4.3BSD-Reno as well. |
27531 | |
27532 | B\bBU\bUG\bGS\bS |
27533 | Some of the error codes need translation to more obvious messages. |
27534 | |
27535 | N\bNA\bAM\bME\bE |
27536 | u\but\bti\bim\bme\bes\bs, f\bfu\but\bti\bim\bme\bes\bs, u\but\bti\bim\bme\ben\bns\bsa\bat\bt, f\bfu\but\bti\bim\bme\ben\bns\bs - set file access and modification |
27537 | times |
27538 | |
27539 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
27540 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
27541 | |
27542 | _\bi_\bn_\bt |
27543 | u\but\bti\bim\bme\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
27544 | |
27545 | _\bi_\bn_\bt |
27546 | f\bfu\but\bti\bim\bme\bes\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
27547 | |
27548 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
27549 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
27550 | |
27551 | _\bi_\bn_\bt |
27552 | u\but\bti\bim\bme\ben\bns\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b], |
27553 | _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
27554 | |
27555 | _\bi_\bn_\bt |
27556 | f\bfu\but\bti\bim\bme\ben\bns\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b]); |
27557 | |
27558 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
27559 | The access and modification times of the file named by _\bp_\ba_\bt_\bh or referenced |
27560 | by _\bf_\bd are changed as specified by the argument _\bt_\bi_\bm_\be_\bs. |
27561 | |
27562 | If _\bt_\bi_\bm_\be_\bs is NULL, the access and modification times are set to the |
27563 | current time. The caller must be the owner of the file, have permission |
27564 | to write the file, or be the superuser. |
27565 | |
27566 | If _\bt_\bi_\bm_\be_\bs is non-null, it is assumed to point to an array of two timeval |
27567 | structures. The access time is set to the value of the first element, |
27568 | and the modification time is set to the value of the second element. The |
27569 | caller must be the owner of the file or be the superuser. |
27570 | |
27571 | In either case, the inode-change-time of the file is set to the current |
27572 | time. |
27573 | |
27574 | The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() are equivalent to u\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\bes\bs(), |
27575 | respectively, with the following differences. |
27576 | |
27577 | Both u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() take two timespec values instead of two |
27578 | timeval values. Further, either of the _\bt_\bv_\b__\bn_\bs_\be_\bc fields can be set to one |
27579 | of the following special values defined in <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>: |
27580 | |
27581 | UTIME_NOW Set the respective timestamp to the greatest value |
27582 | supported that is not greater than the current time. |
27583 | UTIME_OMIT Do not change the respective timestamp. |
27584 | |
27585 | Additionally, if the _\bp_\ba_\bt_\bh argument to u\but\bti\bim\bme\ben\bns\bsa\bat\bt() specifies a relative |
27586 | path, the file whose timestamps are changed is determined relative to the |
27587 | directory associated with file descriptor _\bf_\bd instead of the current |
27588 | working directory. |
27589 | |
27590 | If u\but\bti\bim\bme\ben\bns\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
27591 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
27592 | |
27593 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
27594 | values: |
27595 | |
27596 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
27597 | timestamps of the symbolic link are changed. |
27598 | |
27599 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
27600 | Upon successful completion, the value 0 is returned; otherwise the |
27601 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
27602 | error. |
27603 | |
27604 | E\bER\bRR\bRO\bOR\bRS\bS |
27605 | u\but\bti\bim\bme\bes\bs() and u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
27606 | |
27607 | [EACCES] Search permission is denied for a component of the |
27608 | path prefix; or the _\bt_\bi_\bm_\be_\bs argument is NULL and the |
27609 | effective user ID of the process does not match the |
27610 | owner of the file, and is not the superuser, and write |
27611 | access is denied. |
27612 | |
27613 | [EFAULT] _\bf_\bi_\bl_\be or _\bt_\bi_\bm_\be_\bs points outside the process's allocated |
27614 | address space. |
27615 | |
27616 | [EIO] An I/O error occurred while reading or writing the |
27617 | affected inode. |
27618 | |
27619 | [ELOOP] Too many symbolic links were encountered in |
27620 | translating the pathname. |
27621 | |
27622 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
27623 | characters, or an entire pathname (including the |
27624 | terminating NUL) exceeded PATH_MAX bytes. |
27625 | |
27626 | [ENOENT] The named file does not exist. |
27627 | |
27628 | [ENOTDIR] A component of the path prefix is not a directory. |
27629 | |
27630 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
27631 | process's effective user ID does not match the owner |
27632 | of the file and is not the superuser. |
27633 | |
27634 | [EROFS] The file system containing the file is mounted read- |
27635 | only. |
27636 | |
27637 | Additionally, u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
27638 | |
27639 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
27640 | AT_SYMLINK_NOFOLLOW. |
27641 | |
27642 | [EBADF] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
27643 | argument is neither AT_FDCWD nor a valid file |
27644 | descriptor. |
27645 | |
27646 | [ENOTDIR] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
27647 | argument is a valid file descriptor but it does not |
27648 | reference a directory. |
27649 | |
27650 | [EACCES] The _\bf_\bi_\bl_\be argument specifies a relative path but search |
27651 | permission is denied for the directory which the _\bf_\bd |
27652 | file descriptor references. |
27653 | |
27654 | f\bfu\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\ben\bns\bs() will fail if: |
27655 | |
27656 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
27657 | |
27658 | [EACCES] The _\bt_\bi_\bm_\be_\bs argument is NULL and the effective user ID |
27659 | of the process does not match the owner of the file, |
27660 | and is not the superuser, and write access is denied. |
27661 | |
27662 | [EFAULT] _\bt_\bi_\bm_\be_\bs points outside the process's allocated address |
27663 | space. |
27664 | |
27665 | [EIO] An I/O error occurred while reading or writing the |
27666 | affected inode. |
27667 | |
27668 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
27669 | process's effective user ID does not match the owner |
27670 | of the file and is not the superuser. |
27671 | |
27672 | [EROFS] The file system containing the file is mounted read- |
27673 | only. |
27674 | |
27675 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
27676 | clock_gettime(2), stat(2), utime(3) |
27677 | |
27678 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
27679 | The u\but\bti\bim\bme\bes\bs(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), and f\bfu\but\bti\bim\bme\ben\bns\bs() functions conform to IEEE Std |
27680 | 1003.1-2008 (``POSIX.1''). |
27681 | |
27682 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
27683 | The predecessors of u\but\bti\bim\bme\bes\bs() were s\bsm\bmd\bda\bat\bte\be() in Version 1 AT&T UNIX, |
27684 | m\bmd\bda\bat\bte\be() in Version 3 AT&T UNIX, and u\but\bti\bim\bme\be() in Version 7 AT&T UNIX; the |
27685 | latter first supported the concept of an access time in addition to the |
27686 | modification time. |
27687 | |
27688 | The u\but\bti\bim\bme\bes\bs() function call appeared in 4.2BSD. The f\bfu\but\bti\bim\bme\bes\bs() function |
27689 | call appeared in NetBSD 1.2. The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() function |
27690 | calls appeared in OpenBSD 5.0. |
27691 | |
27692 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
27693 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and |
27694 | f\bfu\but\bti\bim\bme\ben\bns\bs() shall mark the last file status change timestamp (i.e. |
27695 | _\bs_\bt_\b__\bc_\bt_\bi_\bm) for update upon successful completion. However, currently some |
27696 | filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the |
27697 | modification timestamp argument. |
27698 | |
27699 | N\bNA\bAM\bME\bE |
27700 | u\but\bti\bim\bme\bes\bs, f\bfu\but\bti\bim\bme\bes\bs, u\but\bti\bim\bme\ben\bns\bsa\bat\bt, f\bfu\but\bti\bim\bme\ben\bns\bs - set file access and modification |
27701 | times |
27702 | |
27703 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
27704 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bti\bim\bme\be.\b.h\bh>\b> |
27705 | |
27706 | _\bi_\bn_\bt |
27707 | u\but\bti\bim\bme\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
27708 | |
27709 | _\bi_\bn_\bt |
27710 | f\bfu\but\bti\bim\bme\bes\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bv_\ba_\bl _\b*_\bt_\bi_\bm_\be_\bs); |
27711 | |
27712 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bst\bta\bat\bt.\b.h\bh>\b> |
27713 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b> |
27714 | |
27715 | _\bi_\bn_\bt |
27716 | u\but\bti\bim\bme\ben\bns\bsa\bat\bt(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b], |
27717 | _\bi_\bn_\bt _\bf_\bl_\ba_\bg); |
27718 | |
27719 | _\bi_\bn_\bt |
27720 | f\bfu\but\bti\bim\bme\ben\bns\bs(_\bi_\bn_\bt _\bf_\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bt_\bi_\bm_\be_\bs_\bp_\be_\bc _\bt_\bi_\bm_\be_\bs_\b[_\b2_\b]); |
27721 | |
27722 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
27723 | The access and modification times of the file named by _\bp_\ba_\bt_\bh or referenced |
27724 | by _\bf_\bd are changed as specified by the argument _\bt_\bi_\bm_\be_\bs. |
27725 | |
27726 | If _\bt_\bi_\bm_\be_\bs is NULL, the access and modification times are set to the |
27727 | current time. The caller must be the owner of the file, have permission |
27728 | to write the file, or be the superuser. |
27729 | |
27730 | If _\bt_\bi_\bm_\be_\bs is non-null, it is assumed to point to an array of two timeval |
27731 | structures. The access time is set to the value of the first element, |
27732 | and the modification time is set to the value of the second element. The |
27733 | caller must be the owner of the file or be the superuser. |
27734 | |
27735 | In either case, the inode-change-time of the file is set to the current |
27736 | time. |
27737 | |
27738 | The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() are equivalent to u\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\bes\bs(), |
27739 | respectively, with the following differences. |
27740 | |
27741 | Both u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() take two timespec values instead of two |
27742 | timeval values. Further, either of the _\bt_\bv_\b__\bn_\bs_\be_\bc fields can be set to one |
27743 | of the following special values defined in <_\bs_\by_\bs_\b/_\bs_\bt_\ba_\bt_\b._\bh>: |
27744 | |
27745 | UTIME_NOW Set the respective timestamp to the greatest value |
27746 | supported that is not greater than the current time. |
27747 | UTIME_OMIT Do not change the respective timestamp. |
27748 | |
27749 | Additionally, if the _\bp_\ba_\bt_\bh argument to u\but\bti\bim\bme\ben\bns\bsa\bat\bt() specifies a relative |
27750 | path, the file whose timestamps are changed is determined relative to the |
27751 | directory associated with file descriptor _\bf_\bd instead of the current |
27752 | working directory. |
27753 | |
27754 | If u\but\bti\bim\bme\ben\bns\bsa\bat\bt() is passed the special value AT_FDCWD (defined in |
27755 | <_\bf_\bc_\bn_\bt_\bl_\b._\bh>) in the _\bf_\bd parameter, the current working directory is used. |
27756 | |
27757 | The _\bf_\bl_\ba_\bg argument is the bitwise OR of zero or more of the following |
27758 | values: |
27759 | |
27760 | AT_SYMLINK_NOFOLLOW If _\bp_\ba_\bt_\bh names a symbolic link, then the |
27761 | timestamps of the symbolic link are changed. |
27762 | |
27763 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
27764 | Upon successful completion, the value 0 is returned; otherwise the |
27765 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
27766 | error. |
27767 | |
27768 | E\bER\bRR\bRO\bOR\bRS\bS |
27769 | u\but\bti\bim\bme\bes\bs() and u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
27770 | |
27771 | [EACCES] Search permission is denied for a component of the |
27772 | path prefix; or the _\bt_\bi_\bm_\be_\bs argument is NULL and the |
27773 | effective user ID of the process does not match the |
27774 | owner of the file, and is not the superuser, and write |
27775 | access is denied. |
27776 | |
27777 | [EFAULT] _\bf_\bi_\bl_\be or _\bt_\bi_\bm_\be_\bs points outside the process's allocated |
27778 | address space. |
27779 | |
27780 | [EIO] An I/O error occurred while reading or writing the |
27781 | affected inode. |
27782 | |
27783 | [ELOOP] Too many symbolic links were encountered in |
27784 | translating the pathname. |
27785 | |
27786 | [ENAMETOOLONG] A component of a pathname exceeded NAME_MAX |
27787 | characters, or an entire pathname (including the |
27788 | terminating NUL) exceeded PATH_MAX bytes. |
27789 | |
27790 | [ENOENT] The named file does not exist. |
27791 | |
27792 | [ENOTDIR] A component of the path prefix is not a directory. |
27793 | |
27794 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
27795 | process's effective user ID does not match the owner |
27796 | of the file and is not the superuser. |
27797 | |
27798 | [EROFS] The file system containing the file is mounted read- |
27799 | only. |
27800 | |
27801 | Additionally, u\but\bti\bim\bme\ben\bns\bsa\bat\bt() will fail if: |
27802 | |
27803 | [EINVAL] The value of the _\bf_\bl_\ba_\bg argument was neither zero nor |
27804 | AT_SYMLINK_NOFOLLOW. |
27805 | |
27806 | [EBADF] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
27807 | argument is neither AT_FDCWD nor a valid file |
27808 | descriptor. |
27809 | |
27810 | [ENOTDIR] The _\bf_\bi_\bl_\be argument specifies a relative path and the _\bf_\bd |
27811 | argument is a valid file descriptor but it does not |
27812 | reference a directory. |
27813 | |
27814 | [EACCES] The _\bf_\bi_\bl_\be argument specifies a relative path but search |
27815 | permission is denied for the directory which the _\bf_\bd |
27816 | file descriptor references. |
27817 | |
27818 | f\bfu\but\bti\bim\bme\bes\bs() and f\bfu\but\bti\bim\bme\ben\bns\bs() will fail if: |
27819 | |
27820 | [EBADF] _\bf_\bd does not refer to a valid descriptor. |
27821 | |
27822 | [EACCES] The _\bt_\bi_\bm_\be_\bs argument is NULL and the effective user ID |
27823 | of the process does not match the owner of the file, |
27824 | and is not the superuser, and write access is denied. |
27825 | |
27826 | [EFAULT] _\bt_\bi_\bm_\be_\bs points outside the process's allocated address |
27827 | space. |
27828 | |
27829 | [EIO] An I/O error occurred while reading or writing the |
27830 | affected inode. |
27831 | |
27832 | [EPERM] The _\bt_\bi_\bm_\be_\bs argument is not NULL and the calling |
27833 | process's effective user ID does not match the owner |
27834 | of the file and is not the superuser. |
27835 | |
27836 | [EROFS] The file system containing the file is mounted read- |
27837 | only. |
27838 | |
27839 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
27840 | clock_gettime(2), stat(2), utime(3) |
27841 | |
27842 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
27843 | The u\but\bti\bim\bme\bes\bs(), u\but\bti\bim\bme\ben\bns\bsa\bat\bt(), and f\bfu\but\bti\bim\bme\ben\bns\bs() functions conform to IEEE Std |
27844 | 1003.1-2008 (``POSIX.1''). |
27845 | |
27846 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
27847 | The predecessors of u\but\bti\bim\bme\bes\bs() were s\bsm\bmd\bda\bat\bte\be() in Version 1 AT&T UNIX, |
27848 | m\bmd\bda\bat\bte\be() in Version 3 AT&T UNIX, and u\but\bti\bim\bme\be() in Version 7 AT&T UNIX; the |
27849 | latter first supported the concept of an access time in addition to the |
27850 | modification time. |
27851 | |
27852 | The u\but\bti\bim\bme\bes\bs() function call appeared in 4.2BSD. The f\bfu\but\bti\bim\bme\bes\bs() function |
27853 | call appeared in NetBSD 1.2. The u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and f\bfu\but\bti\bim\bme\ben\bns\bs() function |
27854 | calls appeared in OpenBSD 5.0. |
27855 | |
27856 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
27857 | IEEE Std 1003.1-2008 (``POSIX.1'') specifies that u\but\bti\bim\bme\ben\bns\bsa\bat\bt() and |
27858 | f\bfu\but\bti\bim\bme\ben\bns\bs() shall mark the last file status change timestamp (i.e. |
27859 | _\bs_\bt_\b__\bc_\bt_\bi_\bm) for update upon successful completion. However, currently some |
27860 | filesystems (e.g. UFS) will not do so if UTIME_OMIT is specified for the |
27861 | modification timestamp argument. |
27862 | |
27863 | N\bNA\bAM\bME\bE |
27864 | u\but\btr\bra\bac\bce\be - insert user record in ktrace log |
27865 | |
27866 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
27867 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
27868 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/p\bpa\bar\bra\bam\bm.\b.h\bh>\b> |
27869 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
27870 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/k\bkt\btr\bra\bac\bce\be.\b.h\bh>\b> |
27871 | |
27872 | _\bi_\bn_\bt |
27873 | u\but\btr\bra\bac\bce\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\ba_\bb_\be_\bl, _\bv_\bo_\bi_\bd _\b*_\ba_\bd_\bd_\br, _\bs_\bi_\bz_\be_\b__\bt _\bl_\be_\bn); |
27874 | |
27875 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
27876 | Adds a record to the process trace with information supplied by the user. |
27877 | The record is identified by _\bl_\ba_\bb_\be_\bl and contains _\bl_\be_\bn bytes from memory |
27878 | pointed to by _\ba_\bd_\bd_\br. This call only has an effect if the calling process |
27879 | is being traced. |
27880 | |
27881 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
27882 | Upon successful completion, the value 0 is returned; otherwise the |
27883 | value -1 is returned and the global variable _\be_\br_\br_\bn_\bo is set to indicate the |
27884 | error. |
27885 | |
27886 | E\bER\bRR\bRO\bOR\bRS\bS |
27887 | [ENOSYS] The currently running kernel was compiled without |
27888 | ktrace(2) support (option KTRACE). |
27889 | |
27890 | [ENAMETOOLONG] The length of the _\bl_\ba_\bb_\be_\bl string was longer than |
27891 | KTR_USER_MAXIDLEN-1. |
27892 | |
27893 | [EINVAL] The specified data length _\bl_\be_\bn was bigger than |
27894 | KTR_USER_MAXLEN. |
27895 | |
27896 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
27897 | kdump(1), ktrace(1), ktrace(2), options(4) |
27898 | |
27899 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
27900 | The u\but\btr\bra\bac\bce\be() system call first appeared in FreeBSD 2.2. It was added to |
27901 | OpenBSD in OpenBSD 5.4. The _\bl_\ba_\bb_\be_\bl argument is an extension. |
27902 | |
27903 | N\bNA\bAM\bME\bE |
27904 | v\bvf\bfo\bor\brk\bk - spawn new process and block parent |
27905 | |
27906 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
27907 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
27908 | |
27909 | _\bp_\bi_\bd_\b__\bt |
27910 | v\bvf\bfo\bor\brk\bk(_\bv_\bo_\bi_\bd); |
27911 | |
27912 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
27913 | v\bvf\bfo\bor\brk\bk() was originally used to create new processes without fully copying |
27914 | the address space of the old process, which is horrendously inefficient |
27915 | in a paged environment. It was useful when the purpose of fork(2) would |
27916 | have been to create a new system context for an execve(2). Since fork(2) |
27917 | is now efficient, even in the above case, the need for v\bvf\bfo\bor\brk\bk() has |
27918 | diminished. v\bvf\bfo\bor\brk\bk() differs from fork(2) in that the parent is suspended |
27919 | until the child makes a call to execve(2) or an exit (either by a call to |
27920 | _exit(2) or abnormally). In addition, fork handlers established using |
27921 | pthread_atfork(3) are not called when a multithreaded program calls |
27922 | v\bvf\bfo\bor\brk\bk(). |
27923 | |
27924 | v\bvf\bfo\bor\brk\bk() returns 0 in the child's context and (later) the PID of the child |
27925 | in the parent's context. |
27926 | |
27927 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
27928 | Same as for fork(2). |
27929 | |
27930 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
27931 | execve(2), fork(2), sigaction(2), wait(2) |
27932 | |
27933 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
27934 | The v\bvf\bfo\bor\brk\bk() function call appeared in 2.9BSD with the additional |
27935 | semantics that the child process ran in the memory of the parent until it |
27936 | called execve(2) or exited. That sharing of memory was removed in |
27937 | 4.4BSD, leaving just the semantics of blocking the parent until the child |
27938 | calls execve(2) or exits. On many other systems the original behavior |
27939 | has been restored, making this interface particularly unportable. |
27940 | |
27941 | B\bBU\bUG\bGS\bS |
27942 | To avoid a possible deadlock situation, processes that are children in |
27943 | the middle of a v\bvf\bfo\bor\brk\bk() are never sent SIGTTOU or SIGTTIN signals; |
27944 | rather, output or ioctl(2) calls are allowed and input attempts result in |
27945 | an end-of-file indication. |
27946 | |
27947 | N\bNA\bAM\bME\bE |
27948 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
27949 | |
27950 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
27951 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
27952 | |
27953 | _\bp_\bi_\bd_\b__\bt |
27954 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
27955 | |
27956 | _\bp_\bi_\bd_\b__\bt |
27957 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
27958 | |
27959 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
27960 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
27961 | |
27962 | _\bp_\bi_\bd_\b__\bt |
27963 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
27964 | |
27965 | _\bp_\bi_\bd_\b__\bt |
27966 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
27967 | |
27968 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
27969 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
27970 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
27971 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
27972 | area, if non-zero, is filled in with termination information about the |
27973 | process that exited (see below). |
27974 | |
27975 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
27976 | to wait for certain child processes, that need resource utilization |
27977 | statistics accumulated by child processes, or that require options. The |
27978 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
27979 | |
27980 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
27981 | wait. The following symbolic constants are currently defined in |
27982 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
27983 | |
27984 | #define WAIT_ANY (-1) /* any process */ |
27985 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
27986 | |
27987 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
27988 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
27989 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
27990 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
27991 | call waits for any process whose process group ID equals the absolute |
27992 | value of _\bw_\bp_\bi_\bd. |
27993 | |
27994 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
27995 | bitwise OR of zero or more of the following values: |
27996 | |
27997 | WCONTINUED Causes status to be reported for stopped child processes that |
27998 | have been continued by receipt of a SIGCONT signal. |
27999 | |
28000 | WNOHANG Indicates that the call should not block if there are no |
28001 | processes that wish to report status. |
28002 | |
28003 | WUNTRACED If set, children of the current process that are stopped due |
28004 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
28005 | their status reported. |
28006 | |
28007 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
28008 | process and all its children is returned (this information is currently |
28009 | not available for stopped processes). |
28010 | |
28011 | When the WNOHANG option is specified and no processes wish to report |
28012 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
28013 | |
28014 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
28015 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
28016 | |
28017 | The following macros may be used to test the manner of exit of the |
28018 | process. One of the first three macros will evaluate to a non-zero |
28019 | (true) value: |
28020 | |
28021 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28022 | True if the process has not terminated, and has continued after a |
28023 | job control stop. This macro can be true only if the wait call |
28024 | specified the WCONTINUED option. |
28025 | |
28026 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28027 | True if the process terminated normally by a call to _exit(2) or |
28028 | exit(3). |
28029 | |
28030 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28031 | True if the process terminated due to receipt of a signal. |
28032 | |
28033 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28034 | True if the process has not terminated, but has stopped and can |
28035 | be restarted. This macro can be true only if the wait call |
28036 | specified the WUNTRACED option or if the child process is being |
28037 | traced (see ptrace(2)). |
28038 | |
28039 | Depending on the values of those macros, the following macros produce the |
28040 | remaining status information about the child process: |
28041 | |
28042 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
28043 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
28044 | of the argument passed to _exit(2) or exit(3) by the child. |
28045 | |
28046 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
28047 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
28048 | signal that caused the termination of the process. |
28049 | |
28050 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
28051 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
28052 | termination of the process was accompanied by the creation of a |
28053 | core file containing an image of the process when the signal was |
28054 | received. |
28055 | |
28056 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
28057 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
28058 | signal that caused the process to stop. |
28059 | |
28060 | N\bNO\bOT\bTE\bES\bS |
28061 | See sigaction(2) for a list of termination signals. A status of 0 |
28062 | indicates normal termination. |
28063 | |
28064 | If a parent process terminates without waiting for all of its child |
28065 | processes to terminate, the remaining child processes are assigned the |
28066 | parent process 1 ID (the init process ID). |
28067 | |
28068 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
28069 | may be interrupted or restarted when the signal-catching routine returns, |
28070 | depending on the options in effect for the signal; for further |
28071 | information, see siginterrupt(3). |
28072 | |
28073 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
28074 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
28075 | process ID of the child is returned to the calling process. Otherwise, a |
28076 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
28077 | |
28078 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
28079 | child process, the process ID of the child is returned to the calling |
28080 | process. If there are no children not previously awaited, -1 is returned |
28081 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
28082 | are no stopped or exited children, 0 is returned. If an error is |
28083 | detected or a caught signal aborts the call, a value of -1 is returned |
28084 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
28085 | |
28086 | E\bER\bRR\bRO\bOR\bRS\bS |
28087 | w\bwa\bai\bit\bt() will fail and return immediately if: |
28088 | |
28089 | [ECHILD] The calling process has no existing unwaited-for child |
28090 | processes. |
28091 | |
28092 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
28093 | address. (May not be detected before exit of a child |
28094 | process.) |
28095 | |
28096 | [EINTR] The call was interrupted by a caught signal, or the |
28097 | signal did not have the SA_RESTART flag set. |
28098 | |
28099 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
28100 | argument. |
28101 | |
28102 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
28103 | _exit(2), sigaction(2), exit(3) |
28104 | |
28105 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
28106 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
28107 | (``POSIX.1''). |
28108 | |
28109 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
28110 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
28111 | specification. |
28112 | |
28113 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
28114 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
28115 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
28116 | first appeared in 4BSD, but the final calling convention was only |
28117 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
28118 | appeared in 4.3BSD-Reno. |
28119 | |
28120 | N\bNA\bAM\bME\bE |
28121 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
28122 | |
28123 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
28124 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
28125 | |
28126 | _\bp_\bi_\bd_\b__\bt |
28127 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
28128 | |
28129 | _\bp_\bi_\bd_\b__\bt |
28130 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
28131 | |
28132 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
28133 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
28134 | |
28135 | _\bp_\bi_\bd_\b__\bt |
28136 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
28137 | |
28138 | _\bp_\bi_\bd_\b__\bt |
28139 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
28140 | |
28141 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
28142 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
28143 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
28144 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
28145 | area, if non-zero, is filled in with termination information about the |
28146 | process that exited (see below). |
28147 | |
28148 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
28149 | to wait for certain child processes, that need resource utilization |
28150 | statistics accumulated by child processes, or that require options. The |
28151 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
28152 | |
28153 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
28154 | wait. The following symbolic constants are currently defined in |
28155 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
28156 | |
28157 | #define WAIT_ANY (-1) /* any process */ |
28158 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
28159 | |
28160 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
28161 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
28162 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
28163 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
28164 | call waits for any process whose process group ID equals the absolute |
28165 | value of _\bw_\bp_\bi_\bd. |
28166 | |
28167 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
28168 | bitwise OR of zero or more of the following values: |
28169 | |
28170 | WCONTINUED Causes status to be reported for stopped child processes that |
28171 | have been continued by receipt of a SIGCONT signal. |
28172 | |
28173 | WNOHANG Indicates that the call should not block if there are no |
28174 | processes that wish to report status. |
28175 | |
28176 | WUNTRACED If set, children of the current process that are stopped due |
28177 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
28178 | their status reported. |
28179 | |
28180 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
28181 | process and all its children is returned (this information is currently |
28182 | not available for stopped processes). |
28183 | |
28184 | When the WNOHANG option is specified and no processes wish to report |
28185 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
28186 | |
28187 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
28188 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
28189 | |
28190 | The following macros may be used to test the manner of exit of the |
28191 | process. One of the first three macros will evaluate to a non-zero |
28192 | (true) value: |
28193 | |
28194 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28195 | True if the process has not terminated, and has continued after a |
28196 | job control stop. This macro can be true only if the wait call |
28197 | specified the WCONTINUED option. |
28198 | |
28199 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28200 | True if the process terminated normally by a call to _exit(2) or |
28201 | exit(3). |
28202 | |
28203 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28204 | True if the process terminated due to receipt of a signal. |
28205 | |
28206 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28207 | True if the process has not terminated, but has stopped and can |
28208 | be restarted. This macro can be true only if the wait call |
28209 | specified the WUNTRACED option or if the child process is being |
28210 | traced (see ptrace(2)). |
28211 | |
28212 | Depending on the values of those macros, the following macros produce the |
28213 | remaining status information about the child process: |
28214 | |
28215 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
28216 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
28217 | of the argument passed to _exit(2) or exit(3) by the child. |
28218 | |
28219 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
28220 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
28221 | signal that caused the termination of the process. |
28222 | |
28223 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
28224 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
28225 | termination of the process was accompanied by the creation of a |
28226 | core file containing an image of the process when the signal was |
28227 | received. |
28228 | |
28229 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
28230 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
28231 | signal that caused the process to stop. |
28232 | |
28233 | N\bNO\bOT\bTE\bES\bS |
28234 | See sigaction(2) for a list of termination signals. A status of 0 |
28235 | indicates normal termination. |
28236 | |
28237 | If a parent process terminates without waiting for all of its child |
28238 | processes to terminate, the remaining child processes are assigned the |
28239 | parent process 1 ID (the init process ID). |
28240 | |
28241 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
28242 | may be interrupted or restarted when the signal-catching routine returns, |
28243 | depending on the options in effect for the signal; for further |
28244 | information, see siginterrupt(3). |
28245 | |
28246 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
28247 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
28248 | process ID of the child is returned to the calling process. Otherwise, a |
28249 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
28250 | |
28251 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
28252 | child process, the process ID of the child is returned to the calling |
28253 | process. If there are no children not previously awaited, -1 is returned |
28254 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
28255 | are no stopped or exited children, 0 is returned. If an error is |
28256 | detected or a caught signal aborts the call, a value of -1 is returned |
28257 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
28258 | |
28259 | E\bER\bRR\bRO\bOR\bRS\bS |
28260 | w\bwa\bai\bit\bt() will fail and return immediately if: |
28261 | |
28262 | [ECHILD] The calling process has no existing unwaited-for child |
28263 | processes. |
28264 | |
28265 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
28266 | address. (May not be detected before exit of a child |
28267 | process.) |
28268 | |
28269 | [EINTR] The call was interrupted by a caught signal, or the |
28270 | signal did not have the SA_RESTART flag set. |
28271 | |
28272 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
28273 | argument. |
28274 | |
28275 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
28276 | _exit(2), sigaction(2), exit(3) |
28277 | |
28278 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
28279 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
28280 | (``POSIX.1''). |
28281 | |
28282 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
28283 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
28284 | specification. |
28285 | |
28286 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
28287 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
28288 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
28289 | first appeared in 4BSD, but the final calling convention was only |
28290 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
28291 | appeared in 4.3BSD-Reno. |
28292 | |
28293 | N\bNA\bAM\bME\bE |
28294 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
28295 | |
28296 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
28297 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
28298 | |
28299 | _\bp_\bi_\bd_\b__\bt |
28300 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
28301 | |
28302 | _\bp_\bi_\bd_\b__\bt |
28303 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
28304 | |
28305 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
28306 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
28307 | |
28308 | _\bp_\bi_\bd_\b__\bt |
28309 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
28310 | |
28311 | _\bp_\bi_\bd_\b__\bt |
28312 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
28313 | |
28314 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
28315 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
28316 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
28317 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
28318 | area, if non-zero, is filled in with termination information about the |
28319 | process that exited (see below). |
28320 | |
28321 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
28322 | to wait for certain child processes, that need resource utilization |
28323 | statistics accumulated by child processes, or that require options. The |
28324 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
28325 | |
28326 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
28327 | wait. The following symbolic constants are currently defined in |
28328 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
28329 | |
28330 | #define WAIT_ANY (-1) /* any process */ |
28331 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
28332 | |
28333 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
28334 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
28335 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
28336 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
28337 | call waits for any process whose process group ID equals the absolute |
28338 | value of _\bw_\bp_\bi_\bd. |
28339 | |
28340 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
28341 | bitwise OR of zero or more of the following values: |
28342 | |
28343 | WCONTINUED Causes status to be reported for stopped child processes that |
28344 | have been continued by receipt of a SIGCONT signal. |
28345 | |
28346 | WNOHANG Indicates that the call should not block if there are no |
28347 | processes that wish to report status. |
28348 | |
28349 | WUNTRACED If set, children of the current process that are stopped due |
28350 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
28351 | their status reported. |
28352 | |
28353 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
28354 | process and all its children is returned (this information is currently |
28355 | not available for stopped processes). |
28356 | |
28357 | When the WNOHANG option is specified and no processes wish to report |
28358 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
28359 | |
28360 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
28361 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
28362 | |
28363 | The following macros may be used to test the manner of exit of the |
28364 | process. One of the first three macros will evaluate to a non-zero |
28365 | (true) value: |
28366 | |
28367 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28368 | True if the process has not terminated, and has continued after a |
28369 | job control stop. This macro can be true only if the wait call |
28370 | specified the WCONTINUED option. |
28371 | |
28372 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28373 | True if the process terminated normally by a call to _exit(2) or |
28374 | exit(3). |
28375 | |
28376 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28377 | True if the process terminated due to receipt of a signal. |
28378 | |
28379 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28380 | True if the process has not terminated, but has stopped and can |
28381 | be restarted. This macro can be true only if the wait call |
28382 | specified the WUNTRACED option or if the child process is being |
28383 | traced (see ptrace(2)). |
28384 | |
28385 | Depending on the values of those macros, the following macros produce the |
28386 | remaining status information about the child process: |
28387 | |
28388 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
28389 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
28390 | of the argument passed to _exit(2) or exit(3) by the child. |
28391 | |
28392 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
28393 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
28394 | signal that caused the termination of the process. |
28395 | |
28396 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
28397 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
28398 | termination of the process was accompanied by the creation of a |
28399 | core file containing an image of the process when the signal was |
28400 | received. |
28401 | |
28402 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
28403 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
28404 | signal that caused the process to stop. |
28405 | |
28406 | N\bNO\bOT\bTE\bES\bS |
28407 | See sigaction(2) for a list of termination signals. A status of 0 |
28408 | indicates normal termination. |
28409 | |
28410 | If a parent process terminates without waiting for all of its child |
28411 | processes to terminate, the remaining child processes are assigned the |
28412 | parent process 1 ID (the init process ID). |
28413 | |
28414 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
28415 | may be interrupted or restarted when the signal-catching routine returns, |
28416 | depending on the options in effect for the signal; for further |
28417 | information, see siginterrupt(3). |
28418 | |
28419 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
28420 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
28421 | process ID of the child is returned to the calling process. Otherwise, a |
28422 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
28423 | |
28424 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
28425 | child process, the process ID of the child is returned to the calling |
28426 | process. If there are no children not previously awaited, -1 is returned |
28427 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
28428 | are no stopped or exited children, 0 is returned. If an error is |
28429 | detected or a caught signal aborts the call, a value of -1 is returned |
28430 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
28431 | |
28432 | E\bER\bRR\bRO\bOR\bRS\bS |
28433 | w\bwa\bai\bit\bt() will fail and return immediately if: |
28434 | |
28435 | [ECHILD] The calling process has no existing unwaited-for child |
28436 | processes. |
28437 | |
28438 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
28439 | address. (May not be detected before exit of a child |
28440 | process.) |
28441 | |
28442 | [EINTR] The call was interrupted by a caught signal, or the |
28443 | signal did not have the SA_RESTART flag set. |
28444 | |
28445 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
28446 | argument. |
28447 | |
28448 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
28449 | _exit(2), sigaction(2), exit(3) |
28450 | |
28451 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
28452 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
28453 | (``POSIX.1''). |
28454 | |
28455 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
28456 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
28457 | specification. |
28458 | |
28459 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
28460 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
28461 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
28462 | first appeared in 4BSD, but the final calling convention was only |
28463 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
28464 | appeared in 4.3BSD-Reno. |
28465 | |
28466 | N\bNA\bAM\bME\bE |
28467 | w\bwa\bai\bit\bt, w\bwa\bai\bit\btp\bpi\bid\bd, w\bwa\bai\bit\bt4\b4, w\bwa\bai\bit\bt3\b3 - wait for process termination |
28468 | |
28469 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
28470 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
28471 | |
28472 | _\bp_\bi_\bd_\b__\bt |
28473 | w\bwa\bai\bit\bt(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs); |
28474 | |
28475 | _\bp_\bi_\bd_\b__\bt |
28476 | w\bwa\bai\bit\btp\bpi\bid\bd(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs); |
28477 | |
28478 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/r\bre\bes\bso\bou\bur\brc\bce\be.\b.h\bh>\b> |
28479 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/w\bwa\bai\bit\bt.\b.h\bh>\b> |
28480 | |
28481 | _\bp_\bi_\bd_\b__\bt |
28482 | w\bwa\bai\bit\bt3\b3(_\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
28483 | |
28484 | _\bp_\bi_\bd_\b__\bt |
28485 | w\bwa\bai\bit\bt4\b4(_\bp_\bi_\bd_\b__\bt _\bw_\bp_\bi_\bd, _\bi_\bn_\bt _\b*_\bs_\bt_\ba_\bt_\bu_\bs, _\bi_\bn_\bt _\bo_\bp_\bt_\bi_\bo_\bn_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\br_\bu_\bs_\ba_\bg_\be _\b*_\br_\bu_\bs_\ba_\bg_\be); |
28486 | |
28487 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
28488 | The w\bwa\bai\bit\bt() function suspends execution of its calling process until |
28489 | _\bs_\bt_\ba_\bt_\bu_\bs information is available for a terminated child process, or a |
28490 | signal is received. On return from a successful w\bwa\bai\bit\bt() call, the _\bs_\bt_\ba_\bt_\bu_\bs |
28491 | area, if non-zero, is filled in with termination information about the |
28492 | process that exited (see below). |
28493 | |
28494 | The w\bwa\bai\bit\bt4\b4() call provides a more general interface for programs that need |
28495 | to wait for certain child processes, that need resource utilization |
28496 | statistics accumulated by child processes, or that require options. The |
28497 | other wait functions are implemented using w\bwa\bai\bit\bt4\b4(). |
28498 | |
28499 | The _\bw_\bp_\bi_\bd parameter specifies the set of child processes for which to |
28500 | wait. The following symbolic constants are currently defined in |
28501 | <_\bs_\by_\bs_\b/_\bw_\ba_\bi_\bt_\b._\bh>: |
28502 | |
28503 | #define WAIT_ANY (-1) /* any process */ |
28504 | #define WAIT_MYPGRP 0 /* any process in my process group */ |
28505 | |
28506 | If _\bw_\bp_\bi_\bd is set to WAIT_ANY, the call waits for any child process. If |
28507 | _\bw_\bp_\bi_\bd is set to WAIT_MYPGRP, the call waits for any child process in the |
28508 | process group of the caller. If _\bw_\bp_\bi_\bd is greater than zero, the call |
28509 | waits for the process with process ID _\bw_\bp_\bi_\bd. If _\bw_\bp_\bi_\bd is less than -1, the |
28510 | call waits for any process whose process group ID equals the absolute |
28511 | value of _\bw_\bp_\bi_\bd. |
28512 | |
28513 | The _\bs_\bt_\ba_\bt_\bu_\bs parameter is defined below. The _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument is the |
28514 | bitwise OR of zero or more of the following values: |
28515 | |
28516 | WCONTINUED Causes status to be reported for stopped child processes that |
28517 | have been continued by receipt of a SIGCONT signal. |
28518 | |
28519 | WNOHANG Indicates that the call should not block if there are no |
28520 | processes that wish to report status. |
28521 | |
28522 | WUNTRACED If set, children of the current process that are stopped due |
28523 | to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal also have |
28524 | their status reported. |
28525 | |
28526 | If _\br_\bu_\bs_\ba_\bg_\be is non-zero, a summary of the resources used by the terminated |
28527 | process and all its children is returned (this information is currently |
28528 | not available for stopped processes). |
28529 | |
28530 | When the WNOHANG option is specified and no processes wish to report |
28531 | status, w\bwa\bai\bit\bt4\b4() returns a process ID of 0. |
28532 | |
28533 | The w\bwa\bai\bit\btp\bpi\bid\bd() call is identical to w\bwa\bai\bit\bt4\b4() with an _\br_\bu_\bs_\ba_\bg_\be value of zero. |
28534 | The older w\bwa\bai\bit\bt3\b3() call is the same as w\bwa\bai\bit\bt4\b4() with a _\bw_\bp_\bi_\bd value of -1. |
28535 | |
28536 | The following macros may be used to test the manner of exit of the |
28537 | process. One of the first three macros will evaluate to a non-zero |
28538 | (true) value: |
28539 | |
28540 | W\bWI\bIF\bFC\bCO\bON\bNT\bTI\bIN\bNU\bUE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28541 | True if the process has not terminated, and has continued after a |
28542 | job control stop. This macro can be true only if the wait call |
28543 | specified the WCONTINUED option. |
28544 | |
28545 | W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28546 | True if the process terminated normally by a call to _exit(2) or |
28547 | exit(3). |
28548 | |
28549 | W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28550 | True if the process terminated due to receipt of a signal. |
28551 | |
28552 | W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) |
28553 | True if the process has not terminated, but has stopped and can |
28554 | be restarted. This macro can be true only if the wait call |
28555 | specified the WUNTRACED option or if the child process is being |
28556 | traced (see ptrace(2)). |
28557 | |
28558 | Depending on the values of those macros, the following macros produce the |
28559 | remaining status information about the child process: |
28560 | |
28561 | W\bWE\bEX\bXI\bIT\bTS\bST\bTA\bAT\bTU\bUS\bS(_\bs_\bt_\ba_\bt_\bu_\bs) |
28562 | If W\bWI\bIF\bFE\bEX\bXI\bIT\bTE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the low-order 8 bits |
28563 | of the argument passed to _exit(2) or exit(3) by the child. |
28564 | |
28565 | W\bWT\bTE\bER\bRM\bMS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
28566 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
28567 | signal that caused the termination of the process. |
28568 | |
28569 | W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP(_\bs_\bt_\ba_\bt_\bu_\bs) |
28570 | If W\bWI\bIF\bFS\bSI\bIG\bGN\bNA\bAL\bLE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates as true if the |
28571 | termination of the process was accompanied by the creation of a |
28572 | core file containing an image of the process when the signal was |
28573 | received. |
28574 | |
28575 | W\bWS\bST\bTO\bOP\bPS\bSI\bIG\bG(_\bs_\bt_\ba_\bt_\bu_\bs) |
28576 | If W\bWI\bIF\bFS\bST\bTO\bOP\bPP\bPE\bED\bD(_\bs_\bt_\ba_\bt_\bu_\bs) is true, evaluates to the number of the |
28577 | signal that caused the process to stop. |
28578 | |
28579 | N\bNO\bOT\bTE\bES\bS |
28580 | See sigaction(2) for a list of termination signals. A status of 0 |
28581 | indicates normal termination. |
28582 | |
28583 | If a parent process terminates without waiting for all of its child |
28584 | processes to terminate, the remaining child processes are assigned the |
28585 | parent process 1 ID (the init process ID). |
28586 | |
28587 | If a signal is caught while any of the w\bwa\bai\bit\bt() calls is pending, the call |
28588 | may be interrupted or restarted when the signal-catching routine returns, |
28589 | depending on the options in effect for the signal; for further |
28590 | information, see siginterrupt(3). |
28591 | |
28592 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
28593 | If w\bwa\bai\bit\bt() returns due to a stopped or terminated child process, the |
28594 | process ID of the child is returned to the calling process. Otherwise, a |
28595 | value of -1 is returned and _\be_\br_\br_\bn_\bo is set to indicate the error. |
28596 | |
28597 | If w\bwa\bai\bit\bt4\b4(), w\bwa\bai\bit\bt3\b3() or w\bwa\bai\bit\btp\bpi\bid\bd() returns due to a stopped or terminated |
28598 | child process, the process ID of the child is returned to the calling |
28599 | process. If there are no children not previously awaited, -1 is returned |
28600 | with _\be_\br_\br_\bn_\bo set to [ECHILD]. Otherwise, if WNOHANG is specified and there |
28601 | are no stopped or exited children, 0 is returned. If an error is |
28602 | detected or a caught signal aborts the call, a value of -1 is returned |
28603 | and _\be_\br_\br_\bn_\bo is set to indicate the error. |
28604 | |
28605 | E\bER\bRR\bRO\bOR\bRS\bS |
28606 | w\bwa\bai\bit\bt() will fail and return immediately if: |
28607 | |
28608 | [ECHILD] The calling process has no existing unwaited-for child |
28609 | processes. |
28610 | |
28611 | [EFAULT] The _\bs_\bt_\ba_\bt_\bu_\bs or _\br_\bu_\bs_\ba_\bg_\be arguments point to an illegal |
28612 | address. (May not be detected before exit of a child |
28613 | process.) |
28614 | |
28615 | [EINTR] The call was interrupted by a caught signal, or the |
28616 | signal did not have the SA_RESTART flag set. |
28617 | |
28618 | [EINVAL] Invalid or undefined flags were passed in the _\bo_\bp_\bt_\bi_\bo_\bn_\bs |
28619 | argument. |
28620 | |
28621 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
28622 | _exit(2), sigaction(2), exit(3) |
28623 | |
28624 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
28625 | The w\bwa\bai\bit\bt() and w\bwa\bai\bit\btp\bpi\bid\bd() functions conform to IEEE Std 1003.1-2008 |
28626 | (``POSIX.1''). |
28627 | |
28628 | w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\bt3\b3() are not specified by POSIX. The W\bWC\bCO\bOR\bRE\bED\bDU\bUM\bMP\bP() macro |
28629 | and the ability to restart a pending w\bwa\bai\bit\bt() call are extensions to that |
28630 | specification. |
28631 | |
28632 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
28633 | A w\bwa\bai\bit\bt() system call first appeared in Version 1 AT&T UNIX. The _\bs_\bt_\ba_\bt_\bu_\bs |
28634 | argument is accepted since Version 2 AT&T UNIX. A w\bwa\bai\bit\bt3\b3() system call |
28635 | first appeared in 4BSD, but the final calling convention was only |
28636 | established in 4.2BSD. The w\bwa\bai\bit\bt4\b4() and w\bwa\bai\bit\btp\bpi\bid\bd() function calls first |
28637 | appeared in 4.3BSD-Reno. |
28638 | |
28639 | N\bNA\bAM\bME\bE |
28640 | w\bwr\bri\bit\bte\be, w\bwr\bri\bit\bte\bev\bv, p\bpw\bwr\bri\bit\bte\be, p\bpw\bwr\bri\bit\bte\bev\bv - write output |
28641 | |
28642 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
28643 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
28644 | |
28645 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
28646 | w\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
28647 | |
28648 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
28649 | p\bpw\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
28650 | |
28651 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
28652 | |
28653 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
28654 | w\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
28655 | |
28656 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
28657 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
28658 | |
28659 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
28660 | p\bpw\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
28661 | |
28662 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
28663 | w\bwr\bri\bit\bte\be() attempts to write _\bn_\bb_\by_\bt_\be_\bs of data to the object referenced by the |
28664 | descriptor _\bd from the buffer pointed to by _\bb_\bu_\bf. w\bwr\bri\bit\bte\bev\bv() performs the |
28665 | same action, but gathers the output data from the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
28666 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
28667 | iov[iovcnt-1]. p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() perform the same functions, but |
28668 | write to the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the |
28669 | file pointer. |
28670 | |
28671 | For w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
28672 | |
28673 | struct iovec { |
28674 | void *iov_base; |
28675 | size_t iov_len; |
28676 | }; |
28677 | |
28678 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
28679 | memory from which data should be written. w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will |
28680 | always write a complete area before proceeding to the next. |
28681 | |
28682 | On objects capable of seeking, the w\bwr\bri\bit\bte\be() starts at a position given by |
28683 | the pointer associated with _\bd (see lseek(2)). Upon return from w\bwr\bri\bit\bte\be(), |
28684 | the pointer is incremented by the number of bytes which were written. If |
28685 | a file was opened with the O_APPEND flag (see open(2)), calls to w\bwr\bri\bit\bte\be() |
28686 | or w\bwr\bri\bit\bte\bev\bv() will automatically set the pointer to the end of the file |
28687 | before writing. |
28688 | |
28689 | Objects that are not capable of seeking always write from the current |
28690 | position. The value of the pointer associated with such an object is |
28691 | undefined. |
28692 | |
28693 | If the real user is not the superuser, then w\bwr\bri\bit\bte\be() clears the set-user- |
28694 | ID bit on a file. This prevents penetration of system security by a user |
28695 | who ``captures'' a writable set-user-ID file owned by the superuser. |
28696 | |
28697 | If w\bwr\bri\bit\bte\be() succeeds it will update the st_ctime and st_mtime fields of |
28698 | the file's meta-data (see stat(2)). |
28699 | |
28700 | When using non-blocking I/O on objects such as sockets that are subject |
28701 | to flow control, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may write fewer bytes than |
28702 | requested; the return value must be noted, and the remainder of the |
28703 | operation should be retried when possible. |
28704 | |
28705 | Note that w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
28706 | the constant IOV_MAX. |
28707 | |
28708 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
28709 | Upon successful completion the number of bytes which were written is |
28710 | returned. Otherwise, a -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
28711 | set to indicate the error. |
28712 | |
28713 | E\bER\bRR\bRO\bOR\bRS\bS |
28714 | w\bwr\bri\bit\bte\be(), p\bpw\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\bev\bv() will fail and the file pointer |
28715 | will remain unchanged if: |
28716 | |
28717 | [EBADF] _\bd is not a valid descriptor open for writing. |
28718 | |
28719 | [EFBIG] An attempt was made to write a file that exceeds the |
28720 | process's file size limit or the maximum file size. |
28721 | |
28722 | [ENOSPC] There is no free space remaining on the file system |
28723 | containing the file. |
28724 | |
28725 | [EDQUOT] The user's quota of disk blocks on the file system |
28726 | containing the file has been exhausted. |
28727 | |
28728 | [EINTR] A write to a slow device (i.e. one that might block |
28729 | for an arbitrary amount of time) was interrupted by |
28730 | the delivery of a signal before any data could be |
28731 | written. |
28732 | |
28733 | [EIO] An I/O error occurred while reading from or writing to |
28734 | the file system. |
28735 | |
28736 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
28737 | address space. |
28738 | |
28739 | In addition, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may return the following errors: |
28740 | |
28741 | [EPIPE] An attempt is made to write to a pipe that is not open |
28742 | for reading by any process. |
28743 | |
28744 | [EPIPE] An attempt is made to write to a socket of type |
28745 | SOCK_STREAM that is not connected to a peer socket. |
28746 | |
28747 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
28748 | could be written immediately. |
28749 | |
28750 | [ENETDOWN] The destination address specified a network that is |
28751 | down. |
28752 | |
28753 | [EDESTADDRREQ] The destination is no longer available when writing to |
28754 | a UNIX-domain datagram socket on which connect(2) had |
28755 | been used to set a destination address. |
28756 | |
28757 | [EIO] The process is a member of a background process |
28758 | attempting to write to its controlling terminal, |
28759 | TOSTOP is set on the terminal, the process isn't |
28760 | ignoring the SIGTTOUT signal and the thread isn't |
28761 | blocking the SIGTTOUT signal, and either the process |
28762 | was created with vfork(2) and hasn't successfully |
28763 | executed one of the exec functions or the process |
28764 | group is orphaned. |
28765 | |
28766 | w\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\be() may return the following error: |
28767 | |
28768 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
28769 | |
28770 | p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() may return the following error: |
28771 | |
28772 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
28773 | |
28774 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
28775 | |
28776 | w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() may return one of the following errors: |
28777 | |
28778 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
28779 | IOV_MAX. |
28780 | |
28781 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
28782 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
28783 | |
28784 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
28785 | address space. |
28786 | |
28787 | [ENOBUFS] The system lacked sufficient buffer space or a queue |
28788 | was full. |
28789 | |
28790 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
28791 | fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) |
28792 | |
28793 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
28794 | The w\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\be() functions conform to IEEE Std |
28795 | 1003.1-2008 (``POSIX.1''). |
28796 | |
28797 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
28798 | The p\bpw\bwr\bri\bit\bte\bev\bv() function call appeared in OpenBSD 2.7. The p\bpw\bwr\bri\bit\bte\be() |
28799 | function call appeared in AT&T System V Release 4 UNIX. The w\bwr\bri\bit\bte\bev\bv() |
28800 | function call appeared in 4.2BSD. The w\bwr\bri\bit\bte\be() function call appeared in |
28801 | Version 2 AT&T UNIX. |
28802 | |
28803 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
28804 | Error checks should explicitly test for -1. Code such as |
28805 | |
28806 | while ((nr = write(fd, buf, sizeof(buf))) > 0) |
28807 | |
28808 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
28809 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
28810 | error-free w\bwr\bri\bit\bte\be() may appear as a negative number distinct from -1. |
28811 | Proper loops should use |
28812 | |
28813 | while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) |
28814 | |
28815 | N\bNA\bAM\bME\bE |
28816 | w\bwr\bri\bit\bte\be, w\bwr\bri\bit\bte\bev\bv, p\bpw\bwr\bri\bit\bte\be, p\bpw\bwr\bri\bit\bte\bev\bv - write output |
28817 | |
28818 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
28819 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> |
28820 | |
28821 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
28822 | w\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs); |
28823 | |
28824 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
28825 | p\bpw\bwr\bri\bit\bte\be(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bv_\bo_\bi_\bd _\b*_\bb_\bu_\bf, _\bs_\bi_\bz_\be_\b__\bt _\bn_\bb_\by_\bt_\be_\bs, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
28826 | |
28827 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
28828 | |
28829 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
28830 | w\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt); |
28831 | |
28832 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/t\bty\byp\bpe\bes\bs.\b.h\bh>\b> |
28833 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/u\bui\bio\bo.\b.h\bh>\b> |
28834 | |
28835 | _\bs_\bs_\bi_\bz_\be_\b__\bt |
28836 | p\bpw\bwr\bri\bit\bte\bev\bv(_\bi_\bn_\bt _\bd, _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\bi_\bo_\bv_\be_\bc _\b*_\bi_\bo_\bv, _\bi_\bn_\bt _\bi_\bo_\bv_\bc_\bn_\bt, _\bo_\bf_\bf_\b__\bt _\bo_\bf_\bf_\bs_\be_\bt); |
28837 | |
28838 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
28839 | w\bwr\bri\bit\bte\be() attempts to write _\bn_\bb_\by_\bt_\be_\bs of data to the object referenced by the |
28840 | descriptor _\bd from the buffer pointed to by _\bb_\bu_\bf. w\bwr\bri\bit\bte\bev\bv() performs the |
28841 | same action, but gathers the output data from the _\bi_\bo_\bv_\bc_\bn_\bt buffers |
28842 | specified by the members of the _\bi_\bo_\bv array: iov[0], iov[1], ..., |
28843 | iov[iovcnt-1]. p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() perform the same functions, but |
28844 | write to the specified position _\bo_\bf_\bf_\bs_\be_\bt in the file without modifying the |
28845 | file pointer. |
28846 | |
28847 | For w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv(), the _\bi_\bo_\bv_\be_\bc structure is defined as: |
28848 | |
28849 | struct iovec { |
28850 | void *iov_base; |
28851 | size_t iov_len; |
28852 | }; |
28853 | |
28854 | Each _\bi_\bo_\bv_\be_\bc entry specifies the base address and length of an area in |
28855 | memory from which data should be written. w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will |
28856 | always write a complete area before proceeding to the next. |
28857 | |
28858 | On objects capable of seeking, the w\bwr\bri\bit\bte\be() starts at a position given by |
28859 | the pointer associated with _\bd (see lseek(2)). Upon return from w\bwr\bri\bit\bte\be(), |
28860 | the pointer is incremented by the number of bytes which were written. If |
28861 | a file was opened with the O_APPEND flag (see open(2)), calls to w\bwr\bri\bit\bte\be() |
28862 | or w\bwr\bri\bit\bte\bev\bv() will automatically set the pointer to the end of the file |
28863 | before writing. |
28864 | |
28865 | Objects that are not capable of seeking always write from the current |
28866 | position. The value of the pointer associated with such an object is |
28867 | undefined. |
28868 | |
28869 | If the real user is not the superuser, then w\bwr\bri\bit\bte\be() clears the set-user- |
28870 | ID bit on a file. This prevents penetration of system security by a user |
28871 | who ``captures'' a writable set-user-ID file owned by the superuser. |
28872 | |
28873 | If w\bwr\bri\bit\bte\be() succeeds it will update the st_ctime and st_mtime fields of |
28874 | the file's meta-data (see stat(2)). |
28875 | |
28876 | When using non-blocking I/O on objects such as sockets that are subject |
28877 | to flow control, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may write fewer bytes than |
28878 | requested; the return value must be noted, and the remainder of the |
28879 | operation should be retried when possible. |
28880 | |
28881 | Note that w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() will fail if the value of _\bi_\bo_\bv_\bc_\bn_\bt exceeds |
28882 | the constant IOV_MAX. |
28883 | |
28884 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
28885 | Upon successful completion the number of bytes which were written is |
28886 | returned. Otherwise, a -1 is returned and the global variable _\be_\br_\br_\bn_\bo is |
28887 | set to indicate the error. |
28888 | |
28889 | E\bER\bRR\bRO\bOR\bRS\bS |
28890 | w\bwr\bri\bit\bte\be(), p\bpw\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\bev\bv() will fail and the file pointer |
28891 | will remain unchanged if: |
28892 | |
28893 | [EBADF] _\bd is not a valid descriptor open for writing. |
28894 | |
28895 | [EFBIG] An attempt was made to write a file that exceeds the |
28896 | process's file size limit or the maximum file size. |
28897 | |
28898 | [ENOSPC] There is no free space remaining on the file system |
28899 | containing the file. |
28900 | |
28901 | [EDQUOT] The user's quota of disk blocks on the file system |
28902 | containing the file has been exhausted. |
28903 | |
28904 | [EINTR] A write to a slow device (i.e. one that might block |
28905 | for an arbitrary amount of time) was interrupted by |
28906 | the delivery of a signal before any data could be |
28907 | written. |
28908 | |
28909 | [EIO] An I/O error occurred while reading from or writing to |
28910 | the file system. |
28911 | |
28912 | [EFAULT] Part of _\bb_\bu_\bf points outside the process's allocated |
28913 | address space. |
28914 | |
28915 | In addition, w\bwr\bri\bit\bte\be() and w\bwr\bri\bit\bte\bev\bv() may return the following errors: |
28916 | |
28917 | [EPIPE] An attempt is made to write to a pipe that is not open |
28918 | for reading by any process. |
28919 | |
28920 | [EPIPE] An attempt is made to write to a socket of type |
28921 | SOCK_STREAM that is not connected to a peer socket. |
28922 | |
28923 | [EAGAIN] The file was marked for non-blocking I/O, and no data |
28924 | could be written immediately. |
28925 | |
28926 | [ENETDOWN] The destination address specified a network that is |
28927 | down. |
28928 | |
28929 | [EDESTADDRREQ] The destination is no longer available when writing to |
28930 | a UNIX-domain datagram socket on which connect(2) had |
28931 | been used to set a destination address. |
28932 | |
28933 | [EIO] The process is a member of a background process |
28934 | attempting to write to its controlling terminal, |
28935 | TOSTOP is set on the terminal, the process isn't |
28936 | ignoring the SIGTTOUT signal and the thread isn't |
28937 | blocking the SIGTTOUT signal, and either the process |
28938 | was created with vfork(2) and hasn't successfully |
28939 | executed one of the exec functions or the process |
28940 | group is orphaned. |
28941 | |
28942 | w\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\be() may return the following error: |
28943 | |
28944 | [EINVAL] _\bn_\bb_\by_\bt_\be_\bs was larger than SSIZE_MAX. |
28945 | |
28946 | p\bpw\bwr\bri\bit\bte\be() and p\bpw\bwr\bri\bit\bte\bev\bv() may return the following error: |
28947 | |
28948 | [EINVAL] _\bo_\bf_\bf_\bs_\be_\bt was negative. |
28949 | |
28950 | [ESPIPE] _\bd is associated with a pipe, socket, FIFO, or tty. |
28951 | |
28952 | w\bwr\bri\bit\bte\bev\bv() and p\bpw\bwr\bri\bit\bte\bev\bv() may return one of the following errors: |
28953 | |
28954 | [EINVAL] _\bi_\bo_\bv_\bc_\bn_\bt was less than or equal to 0, or greater than |
28955 | IOV_MAX. |
28956 | |
28957 | [EINVAL] The sum of the _\bi_\bo_\bv_\b__\bl_\be_\bn values in the _\bi_\bo_\bv array |
28958 | overflowed an _\bs_\bs_\bi_\bz_\be_\b__\bt. |
28959 | |
28960 | [EFAULT] Part of _\bi_\bo_\bv points outside the process's allocated |
28961 | address space. |
28962 | |
28963 | [ENOBUFS] The system lacked sufficient buffer space or a queue |
28964 | was full. |
28965 | |
28966 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
28967 | fcntl(2), lseek(2), open(2), pipe(2), poll(2), select(2), termios(4) |
28968 | |
28969 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
28970 | The w\bwr\bri\bit\bte\be(), w\bwr\bri\bit\bte\bev\bv(), and p\bpw\bwr\bri\bit\bte\be() functions conform to IEEE Std |
28971 | 1003.1-2008 (``POSIX.1''). |
28972 | |
28973 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
28974 | The p\bpw\bwr\bri\bit\bte\bev\bv() function call appeared in OpenBSD 2.7. The p\bpw\bwr\bri\bit\bte\be() |
28975 | function call appeared in AT&T System V Release 4 UNIX. The w\bwr\bri\bit\bte\bev\bv() |
28976 | function call appeared in 4.2BSD. The w\bwr\bri\bit\bte\be() function call appeared in |
28977 | Version 2 AT&T UNIX. |
28978 | |
28979 | C\bCA\bAV\bVE\bEA\bAT\bTS\bS |
28980 | Error checks should explicitly test for -1. Code such as |
28981 | |
28982 | while ((nr = write(fd, buf, sizeof(buf))) > 0) |
28983 | |
28984 | is not maximally portable, as some platforms allow for _\bn_\bb_\by_\bt_\be_\bs to range |
28985 | between SSIZE_MAX and SIZE_MAX - 2, in which case the return value of an |
28986 | error-free w\bwr\bri\bit\bte\be() may appear as a negative number distinct from -1. |
28987 | Proper loops should use |
28988 | |
28989 | while ((nr = write(fd, buf, sizeof(buf))) != -1 && nr != 0) |
28990 | |
28991 | N\bNA\bAM\bME\bE |
28992 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf - drains the CPU write buffer |
28993 | |
28994 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
28995 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
28996 | |
28997 | _\bi_\bn_\bt |
28998 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf(); |
28999 | |
29000 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
29001 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf() will make sure that all the entries in the processor |
29002 | write buffer are written out to memory. |
29003 | |
29004 | Not all processors support this operation (currently only the SA110 |
29005 | does). Those processes that do not, treat this function as a null-op. |
29006 | |
29007 | E\bER\bRR\bRO\bOR\bRS\bS |
29008 | a\bar\brm\bm_\b_d\bdr\bra\bai\bin\bn_\b_w\bwr\bri\bit\bte\beb\bbu\buf\bf() will never fail so will always return 0. |
29009 | |
29010 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
29011 | StrongARM Data Sheet |
29012 | |
29013 | N\bNA\bAM\bME\bE |
29014 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be - clean the CPU data cache and flush the CPU instruction |
29015 | cache |
29016 | |
29017 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
29018 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<m\bma\bac\bch\bhi\bin\bne\be/\b/s\bsy\bys\bsa\bar\brc\bch\bh.\b.h\bh>\b> |
29019 | |
29020 | _\bi_\bn_\bt |
29021 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be(_\bu_\b__\bi_\bn_\bt _\ba_\bd_\bd_\br, _\bi_\bn_\bt _\bl_\be_\bn); |
29022 | |
29023 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
29024 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will make sure that all the entries in the processor |
29025 | instruction cache are synchronized with main memory and that any data in |
29026 | a write back cache has been cleaned. Some ARM processors (e.g. SA110) |
29027 | have separate instruction and data caches, thus any dynamically generated |
29028 | or modified code needs to be written back from any data caches to main |
29029 | memory and the instruction cache needs to be synchronized with main |
29030 | memory. |
29031 | |
29032 | On such processors, a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will clean the data cache and |
29033 | invalidate the processor instruction cache to force reloading from main |
29034 | memory. On processors that have a shared instruction and data cache and |
29035 | have a write through cache (e.g. ARM6), no action needs to be taken. |
29036 | |
29037 | The routine takes a start address _\ba_\bd_\bd_\br and a length _\bl_\be_\bn to describe the |
29038 | area of memory that needs to be cleaned and synchronized. |
29039 | |
29040 | E\bER\bRR\bRO\bOR\bRS\bS |
29041 | a\bar\brm\bm_\b_s\bsy\byn\bnc\bc_\b_i\bic\bca\bac\bch\bhe\be() will never fail so will always return 0. |
29042 | |
29043 | R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bES\bS |
29044 | StrongARM Data Sheet |
29045 | |
29046 | OpenBSD 5.7 August 14, 2013 OpenBSD 5.7 |