1fcntl(2) System Calls fcntl(2)
2
3
4
6 fcntl - file control
7
9 #include <sys/types.h>
10 #include <unistd.h>
11 #include <fcntl.h>
12
13 int fcntl(int fildes, int cmd, /* arg */ ...);
14
15
17 The fcntl() function provides for control over open files. The fildes
18 argument is an open file descriptor.
19
20
21 The fcntl() function can take a third argument, arg, whose data type,
22 value, and use depend upon the value of cmd. The cmd argument specifies
23 the operation to be performed by fcntl().
24
25
26 The values for cmd are defined in <fcntl.h> and include:
27
28 F_DUPFD Return a new file descriptor which is the lowest num‐
29 bered available (that is, not already open) file
30 descriptor greater than or equal to the third argument,
31 arg, taken as an integer of type int. The new file
32 descriptor refers to the same open file description as
33 the original file descriptor, and shares any locks. The
34 FD_CLOEXEC flag associated with the new file descriptor
35 is cleared to keep the file open across calls to one of
36 the exec(2) functions.
37
38
39 F_DUP2FD Similar to F_DUPFD, but always returns arg. F_DUP2FD
40 closes arg if it is open and not equal to fildes.
41 F_DUP2FD is equivalent to dup2(fildes, arg).
42
43
44 F_FREESP Free storage space associated with a section of the
45 ordinary file fildes. The section is specified by a
46 variable of data type struct flock pointed to by arg.
47 The data type struct flock is defined in the <fcntl.h>
48 header (see fcntl.h(3HEAD)) and is described below. Note
49 that all file systems might not support all possible
50 variations of F_FREESP arguments. In particular, many
51 file systems allow space to be freed only at the end of
52 a file.
53
54
55 F_FREESP64 Equivalent to F_FREESP, but takes a struct flock64 argu‐
56 ment rather than a struct flock argument.
57
58
59 F_ALLOCSP Allocate space for a section of the ordinary file
60 fildes. The section is specified by a variable of data
61 type struct flock pointed to by arg. The data type
62 struct flock is defined in the <fcntl.h> header (see
63 fcntl.h(3HEAD) and is described below.
64
65
66 F_ALLOCSP64 Equivalent to F_ALLOCSP, but takes a struct flock64
67 argument rather than a struct flock argument.
68
69
70 F_GETFD Get the file descriptor flags defined in <fcntl.h> that
71 are associated with the file descriptor fildes. File
72 descriptor flags are associated with a single file
73 descriptor and do not affect other file descriptors that
74 refer to the same file.
75
76
77 F_GETFL Get the file status flags and file access modes, defined
78 in <fcntl.h>, for the file descriptor specified by
79 fildes. The file access modes can be extracted from the
80 return value using the mask O_ACCMODE, which is defined
81 in <fcntl.h>. File status flags and file access modes do
82 not affect other file descriptors that refer to the same
83 file with different open file descriptions.
84
85
86 F_GETOWN If fildes refers to a socket, get the process or process
87 group ID specified to receive SIGURG signals when out-
88 of-band data is available. Positive values indicate a
89 process ID; negative values, other than −1, indicate a
90 process group ID. If fildes does not refer to a socket,
91 the results are unspecified.
92
93
94 F_GETXFL Get the file status flags, file access modes, and file
95 creation and assignment flags, defined in <fcntl.h>, for
96 the file descriptor specified by fildes. The file access
97 modes can be extracted from the return value using the
98 mask O_ACCMODE, which is defined in <fcntl.h>. File sta‐
99 tus flags, file access modes, and file creation and
100 assignment flags do not affect other file descriptors
101 that refer to the same file with different open file
102 descriptions.
103
104
105 F_SETFD Set the file descriptor flags defined in <fcntl.h>, that
106 are associated with fildes, to the third argument, arg,
107 taken as type int. If the FD_CLOEXEC flag in the third
108 argument is 0, the file will remain open across the
109 exec() functions; otherwise the file will be closed upon
110 successful execution of one of the exec() functions.
111
112
113 F_SETFL Set the file status flags, defined in <fcntl.h>, for the
114 file descriptor specified by fildes from the correspond‐
115 ing bits in the arg argument, taken as type int. Bits
116 corresponding to the file access mode and file creation
117 and assignment flags that are set in arg are ignored. If
118 any bits in arg other than those mentioned here are
119 changed by the application, the result is unspecified.
120
121
122 F_SETOWN If fildes refers to a socket, set the process or process
123 group ID specified to receive SIGURG signals when out-
124 of-band data is available, using the value of the third
125 argument, arg, taken as type int. Positive values indi‐
126 cate a process ID; negative values, other than −1, indi‐
127 cate a process group ID. If fildes does not refer to a
128 socket, the results are unspecified.
129
130
131
132 The following commands are available for advisory record locking.
133 Record locking is supported for regular files, and may be supported for
134 other files.
135
136 F_GETLK Get the first lock which blocks the lock description
137 pointed to by the third argument, arg, taken as a pointer
138 to type struct flock, defined in <fcntl.h>. The informa‐
139 tion retrieved overwrites the information passed to
140 fcntl() in the structure flock. If no lock is found that
141 would prevent this lock from being created, then the
142 structure will be left unchanged except for the lock type
143 which will be set to F_UNLCK.
144
145
146 F_GETLK64 Equivalent to F_GETLK, but takes a struct flock64 argu‐
147 ment rather than a struct flock argument.
148
149
150 F_SETLK Set or clear a file segment lock according to the lock
151 description pointed to by the third argument, arg, taken
152 as a pointer to type struct flock, defined in <fcntl.h>.
153 F_SETLK is used to establish shared (or read) locks
154 (F_RDLCK) or exclusive (or write) locks (F_WRLCK), as
155 well as to remove either type of lock (F_UNLCK). F_RDLCK,
156 F_WRLCK and F_UNLCK are defined in <fcntl.h>. If a shared
157 or exclusive lock cannot be set, fcntl() will return
158 immediately with a return value of −1.
159
160
161 F_SETLK64 Equivalent to F_SETLK, but takes a struct flock64 argu‐
162 ment rather than a struct flock argument.
163
164
165 F_SETLKW This command is the same as F_SETLK except that if a
166 shared or exclusive lock is blocked by other locks, the
167 process will wait until the request can be satisfied. If
168 a signal that is to be caught is received while fcntl()
169 is waiting for a region, fcntl() will be interrupted.
170 Upon return from the process' signal handler, fcntl()
171 will return −1 with errno set to EINTR, and the lock
172 operation will not be done.
173
174
175 F_SETLKW64 Equivalent to F_SETLKW, but takes a struct flock64 argu‐
176 ment rather than a struct flock argument.
177
178
179
180 When a shared lock is set on a segment of a file, other processes will
181 be able to set shared locks on that segment or a portion of it. A
182 shared lock prevents any other process from setting an exclusive lock
183 on any portion of the protected area. A request for a shared lock will
184 fail if the file descriptor was not opened with read access.
185
186
187 An exclusive lock will prevent any other process from setting a shared
188 lock or an exclusive lock on any portion of the protected area. A
189 request for an exclusive lock will fail if the file descriptor was not
190 opened with write access.
191
192
193 The flock structure contains at least the following elements:
194
195 short l_type; /* lock operation type */
196 short l_whence; /* lock base indicator */
197 off_t l_start; /* starting offset from base */
198 off_t l_len; /* lock length; l_len == 0 means
199 until end of file */
200 int l_sysid; /* system ID running process holding lock */
201 pid_t l_pid; /* process ID of process holding lock */
202
203
204
205 The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to indicate
206 that the relative offset l_start bytes will be measured from the start
207 of the file, current position or end of the file, respectively. The
208 value of l_len is the number of consecutive bytes to be locked. The
209 value of l_len may be negative (where the definition of off_t permits
210 negative values of l_len). After a successful F_GETLK or F_GETLK64
211 request, that is, one in which a lock was found, the value of l_whence
212 will be SEEK_SET.
213
214
215 The l_pid and l_sysid fields are used only with F_GETLK or F_GETLK64 to
216 return the process ID of the process holding a blocking lock and to
217 indicate which system is running that process.
218
219
220 If l_len is positive, the area affected starts at l_start and ends at
221 l_start + l_len − 1. If l_len is negative, the area affected starts at
222 l_start + l_len and ends at l_start − 1. Locks may start and extend
223 beyond the current end of a file, but must not be negative relative to
224 the beginning of the file. A lock will be set to extend to the largest
225 possible value of the file offset for that file by setting l_len to 0.
226 If such a lock also has l_start set to 0 and l_whence is set to
227 SEEK_SET, the whole file will be locked.
228
229
230 If a process has an existing lock in which l_len is 0 and which
231 includes the last byte of the requested segment, and an unlock
232 (F_UNLCK) request is made in which l_len is non-zero and the offset of
233 the last byte of the requested segment is the maximum value for an
234 object of type off_t, then the F_UNLCK request will be treated as a
235 request to unlock from the start of the requested segment with an l_len
236 equal to 0. Otherwise, the request will attempt to unlock only the
237 requested segment.
238
239
240 There will be at most one type of lock set for each byte in the file.
241 Before a successful return from an F_SETLK, F_SETLK64, F_SETLKW, or
242 F_SETLKW64 request when the calling process has previously existing
243 locks on bytes in the region specified by the request, the previous
244 lock type for each byte in the specified region will be replaced by the
245 new lock type. As specified above under the descriptions of shared
246 locks and exclusive locks, an F_SETLK, F_SETLK64, F_SETLKW, or
247 F_SETLKW64 request will (respectively) fail or block when another
248 process has existing locks on bytes in the specified region and the
249 type of any of those locks conflicts with the type specified in the
250 request.
251
252
253 All locks associated with a file for a given process are removed when a
254 file descriptor for that file is closed by that process or the process
255 holding that file descriptor terminates. Locks are not inherited by a
256 child process created using fork(2).
257
258
259 A potential for deadlock occurs if a process controlling a locked
260 region is put to sleep by attempting to lock another process' locked
261 region. If the system detects that sleeping until a locked region is
262 unlocked would cause a deadlock, fcntl() will fail with an EDEADLK
263 error.
264
265
266 The following values for cmd are used for file share reservations. A
267 share reservation is placed on an entire file to allow cooperating pro‐
268 cesses to control access to the file.
269
270 F_SHARE Sets a share reservation on a file with the specified
271 access mode and designates which types of access to deny.
272
273
274 F_UNSHARE Remove an existing share reservation.
275
276
277
278 File share reservations are an advisory form of access control among
279 cooperating processes, on both local and remote machines. They are most
280 often used by DOS or Windows emulators and DOS based NFS clients. How‐
281 ever, native UNIX versions of DOS or Windows applications may also
282 choose to use this form of access control.
283
284
285 A share reservation is described by an fshare structure defined in
286 <sys/fcntl.h>, which is included in <fcntl.h> as follows:
287
288 typedef struct fshare {
289 short f_access;
290 short f_deny;
291 int f_id;
292 } fshare_t;
293
294
295
296 A share reservation specifies the type of access, f_access, to be
297 requested on the open file descriptor. If access is granted, it further
298 specifies what type of access to deny other processes, f_deny. A single
299 process on the same file may hold multiple non-conflicting reserva‐
300 tions by specifying an identifier, f_id, unique to the process, with
301 each request.
302
303
304 An F_UNSHARE request releases the reservation with the specified f_id.
305 The f_access and f_deny fields are ignored.
306
307
308 Valid f_access values are:
309
310 F_RDACC Set a file share reservation for read-only access.
311
312
313 F_WRACC Set a file share reservation for write-only access.
314
315
316 F_RWACC Set a file share reservation for read and write access.
317
318
319
320 Valid f_deny values are:
321
322 F_COMPAT Set a file share reservation to compatibility mode.
323
324
325 F_RDDNY Set a file share reservation to deny read access to other
326 processes.
327
328
329 F_WRDNY Set a file share reservation to deny write access to other
330 processes.
331
332
333 F_RWDNY Set a file share reservation to deny read and write access
334 to other processes.
335
336
337 F_NODNY Do not deny read or write access to any other process.
338
339
341 Upon successful completion, the value returned depends on cmd as fol‐
342 lows:
343
344 F_DUPFD A new file descriptor.
345
346
347 F_FREESP Value of 0.
348
349
350 F_GETFD Value of flags defined in <fcntl.h>. The return value
351 will not be negative.
352
353
354 F_GETFL Value of file status flags and access modes. The return
355 value will not be negative.
356
357
358 F_GETLK Value other than −1.
359
360
361 F_GETLK64 Value other than −1.
362
363
364 F_GETOWN Value of the socket owner process or process group; this
365 will not be −1.
366
367
368 F_GETXFL Value of file status flags, access modes, and creation
369 and assignment flags. The return value will not be nega‐
370 tive.
371
372
373 F_SETFD Value other than −1.
374
375
376 F_SETFL Value other than −1.
377
378
379 F_SETLK Value other than −1.
380
381
382 F_SETLK64 Value other than −1.
383
384
385 F_SETLKW Value other than −1.
386
387
388 F_SETLKW64 Value other than −1.
389
390
391 F_SETOWN Value other than −1.
392
393
394 F_SHARE Value other than −1.
395
396
397 F_UNSHARE Value other than −1.
398
399
400
401 Otherwise, −1 is returned and errno is set to indicate the error.
402
404 The fcntl() function will fail if:
405
406 EAGAIN The cmd argument is F_SETLK or F_SETLK64, the type of lock
407 (l_type) is a shared (F_RDLCK) or exclusive (F_WRLCK)
408 lock, and the segment of a file to be locked is already
409 exclusive-locked by another process; or the type is an
410 exclusive lock and some portion of the segment of a file
411 to be locked is already shared-locked or exclusive-locked
412 by another process.
413
414 The cmd argument is F_FREESP, the file exists, mandatory
415 file/record locking is set, and there are outstanding
416 record locks on the file; or the cmd argument is F_SETLK,
417 F_SETLK64, F_SETLKW, or F_SETLKW64, mandatory file/record
418 locking is set, and the file is currently being mapped to
419 virtual memory using mmap(2).
420
421 The cmd argument is F_SHARE and f_access conflicts with an
422 existing f_deny share reservation.
423
424
425 EBADF The fildes argument is not a valid open file descriptor;
426 or the cmd argument is F_SETLK, F_SETLK64, F_SETLKW, or
427 F_SETLKW64, the type of lock, l_type, is a shared lock
428 (F_RDLCK), and fildes is not a valid file descriptor open
429 for reading; or the type of lock l_type is an exclusive
430 lock (F_WRLCK) and fildes is not a valid file descriptor
431 open for writing.
432
433 The cmd argument is F_FREESP and fildes is not a valid
434 file descriptor open for writing.
435
436 The cmd argument is F_DUP2FD, and arg is negative or is
437 not less than the current resource limit for
438 RLIMIT_NOFILE.
439
440 The cmd argument is F_SHARE, the f_access share reserva‐
441 tion is for write access, and fildes is not a valid file
442 descriptor open for writing.
443
444 The cmd argument is F_SHARE, the f_access share reserva‐
445 tion is for read access, and fildes is not a valid file
446 descriptor open for reading.
447
448
449 EFAULT The cmd argument is F_GETLK, F_GETLK64, F_SETLK,
450 F_SETLK64, F_SETLKW, F_SETLKW64, or F_FREESP and the arg
451 argument points to an illegal address.
452
453 The cmd argument is F_SHARE or F_UNSHARE and arg points to
454 an illegal address.
455
456
457 EINTR The cmd argument is F_SETLKW or F_SETLKW64 and the func‐
458 tion was interrupted by a signal.
459
460
461 EINVAL The cmd argument is invalid or not supported by the file
462 system; or the cmd argument is F_DUPFD and arg is negative
463 or greater than or equal to OPEN_MAX; or the cmd argument
464 is F_GETLK, F_GETLK64, F_SETLK, F_SETLK64, F_SETLKW, or
465 F_SETLKW64 and the data pointed to by arg is not valid; or
466 fildes refers to a file that does not support locking.
467
468 The cmd argument is F_UNSHARE and a reservation with this
469 f_id for this process does not exist.
470
471
472 EIO An I/O error occurred while reading from or writing to the
473 file system.
474
475
476 EMFILE The cmd argument is F_DUPFD and either OPEN_MAX file
477 descriptors are currently open in the calling process, or
478 no file descriptors greater than or equal to arg are
479 available.
480
481
482 ENOLCK The cmd argument is F_SETLK, F_SETLK64, F_SETLKW, or
483 F_SETLKW64 and satisfying the lock or unlock request would
484 result in the number of locked regions in the system
485 exceeding a system-imposed limit.
486
487
488 ENOLINK Either the fildes argument is on a remote machine and the
489 link to that machine is no longer active; or the cmd argu‐
490 ment is F_FREESP, the file is on a remote machine, and the
491 link to that machine is no longer active.
492
493
494 EOVERFLOW One of the values to be returned cannot be represented
495 correctly.
496
497 The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the
498 smallest or, if l_len is non-zero, the largest, offset of
499 any byte in the requested segment cannot be represented
500 correctly in an object of type off_t.
501
502 The cmd argument is F_GETLK64, F_SETLK64, or F_SETLKW64
503 and the smallest or, if l_len is non-zero, the largest,
504 offset of any byte in the requested segment cannot be rep‐
505 resented correctly in an object of type off64_t.
506
507
508
509 The fcntl() function may fail if:
510
511 EAGAIN The cmd argument is F_SETLK, F_SETLK64, F_SETLKW, or
512 F_SETLKW64, and the file is currently being mapped to vir‐
513 tual memory using mmap(2).
514
515
516 EDEADLK The cmd argument is F_SETLKW or F_SETLKW64, the lock is
517 blocked by some lock from another process and putting the
518 calling process to sleep, waiting for that lock to become
519 free would cause a deadlock.
520
521 The cmd argument is F_FREESP, mandatory record locking is
522 enabled, O_NDELAY and O_NONBLOCK are clear and a deadlock
523 condition was detected.
524
525
527 See attributes(5) for descriptions of the following attributes:
528
529
530
531
532 ┌─────────────────────────────┬─────────────────────────────┐
533 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
534 ├─────────────────────────────┼─────────────────────────────┤
535 │Interface Stability │Standard │
536 ├─────────────────────────────┼─────────────────────────────┤
537 │MT-Level │Async-Signal Safe │
538 └─────────────────────────────┴─────────────────────────────┘
539
541 lockd(1M), chmod(2), close(2), creat(2), dup(2), exec(2), fork(2),
542 mmap(2), open(2), pipe(2), read(2), sigaction(2), write(2), dup2(3C),
543 fcntl.h(3HEAD), attributes(5), standards(5)
544
545
546 Programming Interfaces Guide
547
549 In the past, the variable errno was set to EACCES rather than EAGAIN
550 when a section of a file is already locked by another process. There‐
551 fore, portable application programs should expect and test for either
552 value.
553
554
555 Advisory locks allow cooperating processes to perform consistent opera‐
556 tions on files, but do not guarantee exclusive access. Files can be
557 accessed without advisory locks, but inconsistencies may result. The
558 network share locking protocol does not support the f_deny value of
559 F_COMPAT. For network file systems, if f_access is F_RDACC, f_deny is
560 mapped to F_RDDNY. Otherwise, it is mapped to F_RWDNY.
561
562
563 To prevent possible file corruption, the system may reject mmap()
564 requests for advisory locked files, or it may reject advisory locking
565 requests for mapped files. Applications that require a file be both
566 locked and mapped should lock the entire file (l_start and l_len both
567 set to 0). If a file is mapped, the system may reject an unlock
568 request, resulting in a lock that does not cover the entire file.
569
570
571 The process ID returned for locked files on network file systems might
572 not be meaningful.
573
574
575 If the file server crashes and has to be rebooted, the lock manager
576 (see lockd(1M)) attempts to recover all locks that were associated with
577 that server. If a lock cannot be reclaimed, the process that held the
578 lock is issued a SIGLOST signal.
579
580
581
582SunOS 5.11 17 Jan 2007 fcntl(2)