1fcntl(2)                         System Calls                         fcntl(2)
2
3
4

NAME

6       fcntl - file control
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <unistd.h>
11       #include <fcntl.h>
12
13       int fcntl(int fildes, int cmd, /* arg */ ...);
14
15

DESCRIPTION

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

RETURN VALUES

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

ERRORS

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

ATTRIBUTES

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

SEE ALSO

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

NOTES

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)
Impressum