lib/libc/sys/fcntl.2

   1 .\" Copyright (c) 1983, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)fcntl.2     8.2 (Berkeley) 1/12/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd September 28, 2009
  32 .Dt FCNTL 2
  33 .Os
  34 .Sh NAME
  35 .Nm fcntl
  36 .Nd file control
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In fcntl.h
  41 .Ft int
  42 .Fn fcntl "int fd" "int cmd" "..."
  43 .Sh DESCRIPTION
  44 The
  45 .Fn fcntl
  46 system call provides for control over descriptors.
  47 The argument
  48 .Fa fd
  49 is a descriptor to be operated on by
  50 .Fa cmd
  51 as described below.
  52 Depending on the value of
  53 .Fa cmd ,
  54 .Fn fcntl
  55 can take an additional third argument
  56 .Fa "int arg" .
  57 .Bl -tag -width F_GETOWNX
  58 .It Dv F_DUPFD
  59 Return a new descriptor as follows:
  60 .Pp
  61 .Bl -bullet -compact -offset 4n
  62 .It
  63 Lowest numbered available descriptor greater than or equal to
  64 .Fa arg .
  65 .It
  66 Same object references as the original descriptor.
  67 .It
  68 New descriptor shares the same file offset if the object
  69 was a file.
  70 .It
  71 Same access mode (read, write or read/write).
  72 .It
  73 Same file status flags (i.e., both file descriptors
  74 share the same file status flags).
  75 .It
  76 The close-on-exec flag associated with the new file descriptor
  77 is set to remain open across
  78 .Xr execve 2
  79 system calls.
  80 .El
  81 .It Dv F_DUP2FD
  82 It is functionally equivalent to
  83 .Bd -literal -offset indent
  84 dup2(fd, arg)
  85 .Ed
  86 .Pp
  87 The
  88 .Dv F_DUP2FD
  89 constant is not portable, so it should not be used if portability is needed.
  90 Use
  91 .Fn dup2
  92 instead.
  93 .It Dv F_GETFD
  94 Get the close-on-exec flag associated with the file descriptor
  95 .Fa fd
  96 as
  97 .Dv FD_CLOEXEC .
  98 If the returned value ANDed with
  99 .Dv FD_CLOEXEC
 100 is 0,
 101 the file will remain open across
 102 .Fn exec ,
 103 otherwise the file will be closed upon execution of
 104 .Fn exec
 105 .Fa ( arg
 106 is ignored).
 107 .It Dv F_SETFD
 108 Set the close-on-exec flag associated with
 109 .Fa fd
 110 to
 111 .Fa arg ,
 112 where
 113 .Fa arg
 114 is either 0 or
 115 .Dv FD_CLOEXEC ,
 116 as described above.
 117 .It Dv F_GETFL
 118 Get descriptor status flags, as described below
 119 .Fa ( arg
 120 is ignored).
 121 .It Dv F_SETFL
 122 Set descriptor status flags to
 123 .Fa arg .
 124 .It Dv F_GETOWN
 125 Get the process ID or process group
 126 currently receiving
 127 .Dv SIGIO
 128 and
 129 .Dv SIGURG
 130 signals; process groups are returned
 131 as negative values
 132 .Fa ( arg
 133 is ignored).
 134 .It Dv F_SETOWN
 135 Set the process or process group
 136 to receive
 137 .Dv SIGIO
 138 and
 139 .Dv SIGURG
 140 signals;
 141 process groups are specified by supplying
 142 .Fa arg
 143 as negative, otherwise
 144 .Fa arg
 145 is interpreted as a process ID.
 146 .El
 147 .Pp
 148 The flags for the
 149 .Dv F_GETFL
 150 and
 151 .Dv F_SETFL
 152 flags are as follows:
 153 .Bl -tag -width O_NONBLOCKX
 154 .It Dv O_NONBLOCK
 155 Non-blocking I/O; if no data is available to a
 156 .Xr read 2
 157 system call, or if a
 158 .Xr write 2
 159 operation would block,
 160 the read or write call returns -1 with the error
 161 .Er EAGAIN .
 162 .It Dv O_APPEND
 163 Force each write to append at the end of file;
 164 corresponds to the
 165 .Dv O_APPEND
 166 flag of
 167 .Xr open 2 .
 168 .It Dv O_DIRECT
 169 Minimize or eliminate the cache effects of reading and writing.
 170 The system
 171 will attempt to avoid caching the data you read or write.
 172 If it cannot
 173 avoid caching the data, it will minimize the impact the data has on the cache.
 174 Use of this flag can drastically reduce performance if not used with care.
 175 .It Dv O_ASYNC
 176 Enable the
 177 .Dv SIGIO
 178 signal to be sent to the process group
 179 when I/O is possible, e.g.,
 180 upon availability of data to be read.
 181 .El
 182 .Pp
 183 Several commands are available for doing advisory file locking;
 184 they all operate on the following structure:
 185 .Bd -literal
 186 struct flock {
 187         off_t   l_start;        /* starting offset */
 188         off_t   l_len;          /* len = 0 means until end of file */
 189         pid_t   l_pid;          /* lock owner */
 190         short   l_type;         /* lock type: read/write, etc. */
 191         short   l_whence;       /* type of l_start */
 192         int     l_sysid;        /* remote system id or zero for local */
 193 };
 194 .Ed
 195 The commands available for advisory record locking are as follows:
 196 .Bl -tag -width F_SETLKWX
 197 .It Dv F_GETLK
 198 Get the first lock that blocks the lock description pointed to by the
 199 third argument,
 200 .Fa arg ,
 201 taken as a pointer to a
 202 .Fa "struct flock"
 203 (see above).
 204 The information retrieved overwrites the information passed to
 205 .Fn fcntl
 206 in the
 207 .Fa flock
 208 structure.
 209 If no lock is found that would prevent this lock from being created,
 210 the structure is left unchanged by this system call except for the
 211 lock type which is set to
 212 .Dv F_UNLCK .
 213 .It Dv F_SETLK
 214 Set or clear a file segment lock according to the lock description
 215 pointed to by the third argument,
 216 .Fa arg ,
 217 taken as a pointer to a
 218 .Fa "struct flock"
 219 (see above).
 220 .Dv F_SETLK
 221 is used to establish shared (or read) locks
 222 .Pq Dv F_RDLCK
 223 or exclusive (or write) locks,
 224 .Pq Dv F_WRLCK ,
 225 as well as remove either type of lock
 226 .Pq Dv F_UNLCK .
 227 If a shared or exclusive lock cannot be set,
 228 .Fn fcntl
 229 returns immediately with
 230 .Er EAGAIN .
 231 .It Dv F_SETLKW
 232 This command is the same as
 233 .Dv F_SETLK
 234 except that if a shared or exclusive lock is blocked by other locks,
 235 the process waits until the request can be satisfied.
 236 If a signal that is to be caught is received while
 237 .Fn fcntl
 238 is waiting for a region, the
 239 .Fn fcntl
 240 will be interrupted if the signal handler has not specified the
 241 .Dv SA_RESTART
 242 (see
 243 .Xr sigaction 2 ) .
 244 .It Dv F_READAHEAD
 245 Set or clear the read ahead amount for sequential access to the third
 246 argument,
 247 .Fa arg ,
 248 which is rounded up to the nearest block size.
 249 A zero value in
 250 .Fa arg
 251 turns off read ahead.
 252 .It Dv F_RDAHEAD
 253 Equivalent to Darwin counterpart which sets read ahead amount of 128KB
 254 when the third argument,
 255 .Fa arg
 256 is non-zero.
 257 A zero value in
 258 .Fa arg
 259 turns off read ahead.
 260 .El
 261 .Pp
 262 When a shared lock has been set on a segment of a file,
 263 other processes can set shared locks on that segment
 264 or a portion of it.
 265 A shared lock prevents any other process from setting an exclusive
 266 lock on any portion of the protected area.
 267 A request for a shared lock fails if the file descriptor was not
 268 opened with read access.
 269 .Pp
 270 An exclusive lock prevents any other process from setting a shared lock or
 271 an exclusive lock on any portion of the protected area.
 272 A request for an exclusive lock fails if the file was not
 273 opened with write access.
 274 .Pp
 275 The value of
 276 .Fa l_whence
 277 is
 278 .Dv SEEK_SET ,
 279 .Dv SEEK_CUR ,
 280 or
 281 .Dv SEEK_END
 282 to indicate that the relative offset,
 283 .Fa l_start
 284 bytes, will be measured from the start of the file,
 285 current position, or end of the file, respectively.
 286 The value of
 287 .Fa l_len
 288 is the number of consecutive bytes to be locked.
 289 If
 290 .Fa l_len
 291 is negative,
 292 .Fa l_start
 293 means end edge of the region.
 294 The
 295 .Fa l_pid
 296 and
 297 .Fa l_sysid
 298 fields are only used with
 299 .Dv F_GETLK
 300 to return the process ID of the process holding a blocking lock and
 301 the system ID of the system that owns that process.
 302 Locks created by the local system will have a system ID of zero.
 303 After a successful
 304 .Dv F_GETLK
 305 request, the value of
 306 .Fa l_whence
 307 is
 308 .Dv SEEK_SET .
 309 .Pp
 310 Locks may start and extend beyond the current end of a file,
 311 but may not start or extend before the beginning of the file.
 312 A lock is set to extend to the largest possible value of the
 313 file offset for that file if
 314 .Fa l_len
 315 is set to zero.
 316 If
 317 .Fa l_whence
 318 and
 319 .Fa l_start
 320 point to the beginning of the file, and
 321 .Fa l_len
 322 is zero, the entire file is locked.
 323 If an application wishes only to do entire file locking, the
 324 .Xr flock 2
 325 system call is much more efficient.
 326 .Pp
 327 There is at most one type of lock set for each byte in the file.
 328 Before a successful return from an
 329 .Dv F_SETLK
 330 or an
 331 .Dv F_SETLKW
 332 request when the calling process has previously existing locks
 333 on bytes in the region specified by the request,
 334 the previous lock type for each byte in the specified
 335 region is replaced by the new lock type.
 336 As specified above under the descriptions
 337 of shared locks and exclusive locks, an
 338 .Dv F_SETLK
 339 or an
 340 .Dv F_SETLKW
 341 request fails or blocks respectively when another process has existing
 342 locks on bytes in the specified region and the type of any of those
 343 locks conflicts with the type specified in the request.
 344 .Pp
 345 This interface follows the completely stupid semantics of System V and
 346 .St -p1003.1-88
 347 that require that all locks associated with a file for a given process are
 348 removed when
 349 .Em any
 350 file descriptor for that file is closed by that process.
 351 This semantic means that applications must be aware of any files that
 352 a subroutine library may access.
 353 For example if an application for updating the password file locks the
 354 password file database while making the update, and then calls
 355 .Xr getpwnam 3
 356 to retrieve a record,
 357 the lock will be lost because
 358 .Xr getpwnam 3
 359 opens, reads, and closes the password database.
 360 The database close will release all locks that the process has
 361 associated with the database, even if the library routine never
 362 requested a lock on the database.
 363 Another minor semantic problem with this interface is that
 364 locks are not inherited by a child process created using the
 365 .Xr fork 2
 366 system call.
 367 The
 368 .Xr flock 2
 369 interface has much more rational last close semantics and
 370 allows locks to be inherited by child processes.
 371 The
 372 .Xr flock 2
 373 system call is recommended for applications that want to ensure the integrity
 374 of their locks when using library routines or wish to pass locks
 375 to their children.
 376 .Pp
 377 The
 378 .Fn fcntl ,
 379 .Xr flock 2 ,
 380 and
 381 .Xr lockf 3
 382 locks are compatible.
 383 Processes using different locking interfaces can cooperate
 384 over the same file safely.
 385 However, only one of such interfaces should be used within
 386 the same process.
 387 If a file is locked by a process through
 388 .Xr flock 2 ,
 389 any record within the file will be seen as locked
 390 from the viewpoint of another process using
 391 .Fn fcntl
 392 or
 393 .Xr lockf 3 ,
 394 and vice versa.
 395 Note that
 396 .Fn fcntl F_GETLK
 397 returns \-1 in
 398 .Fa l_pid
 399 if the process holding a blocking lock previously locked the
 400 file descriptor by
 401 .Xr flock 2 .
 402 .Pp
 403 All locks associated with a file for a given process are
 404 removed when the process terminates.
 405 .Pp
 406 All locks obtained before a call to
 407 .Xr execve 2
 408 remain in effect until the new program releases them.
 409 If the new program does not know about the locks, they will not be
 410 released until the program exits.
 411 .Pp
 412 A potential for deadlock occurs if a process controlling a locked region
 413 is put to sleep by attempting to lock the locked region of another process.
 414 This implementation detects that sleeping until a locked region is unlocked
 415 would cause a deadlock and fails with an
 416 .Er EDEADLK
 417 error.
 418 .Sh RETURN VALUES
 419 Upon successful completion, the value returned depends on
 420 .Fa cmd
 421 as follows:
 422 .Bl -tag -width F_GETOWNX -offset indent
 423 .It Dv F_DUPFD
 424 A new file descriptor.
 425 .It Dv F_DUP2FD
 426 A file descriptor equal to
 427 .Fa arg .
 428 .It Dv F_GETFD
 429 Value of flag (only the low-order bit is defined).
 430 .It Dv F_GETFL
 431 Value of flags.
 432 .It Dv F_GETOWN
 433 Value of file descriptor owner.
 434 .It other
 435 Value other than -1.
 436 .El
 437 .Pp
 438 Otherwise, a value of -1 is returned and
 439 .Va errno
 440 is set to indicate the error.
 441 .Sh ERRORS
 442 The
 443 .Fn fcntl
 444 system call will fail if:
 445 .Bl -tag -width Er
 446 .It Bq Er EAGAIN
 447 The argument
 448 .Fa cmd
 449 is
 450 .Dv F_SETLK ,
 451 the type of lock
 452 .Pq Fa l_type
 453 is a shared lock
 454 .Pq Dv F_RDLCK
 455 or exclusive lock
 456 .Pq Dv F_WRLCK ,
 457 and the segment of a file to be locked is already
 458 exclusive-locked by another process;
 459 or the type is an exclusive lock and some portion of the
 460 segment of a file to be locked is already shared-locked or
 461 exclusive-locked by another process.
 462 .It Bq Er EBADF
 463 The
 464 .Fa fd
 465 argument
 466 is not a valid open file descriptor.
 467 .Pp
 468 The argument
 469 .Fa cmd
 470 is
 471 .Dv F_DUP2FD ,
 472 and
 473 .Fa arg
 474 is not a valid file descriptor.
 475 .Pp
 476 The argument
 477 .Fa cmd
 478 is
 479 .Dv F_SETLK
 480 or
 481 .Dv F_SETLKW ,
 482 the type of lock
 483 .Pq Fa l_type
 484 is a shared lock
 485 .Pq Dv F_RDLCK ,
 486 and
 487 .Fa fd
 488 is not a valid file descriptor open for reading.
 489 .Pp
 490 The argument
 491 .Fa cmd
 492 is
 493 .Dv F_SETLK
 494 or
 495 .Dv F_SETLKW ,
 496 the type of lock
 497 .Pq Fa l_type
 498 is an exclusive lock
 499 .Pq Dv F_WRLCK ,
 500 and
 501 .Fa fd
 502 is not a valid file descriptor open for writing.
 503 .It Bq Er EDEADLK
 504 The argument
 505 .Fa cmd
 506 is
 507 .Dv F_SETLKW ,
 508 and a deadlock condition was detected.
 509 .It Bq Er EINTR
 510 The argument
 511 .Fa cmd
 512 is
 513 .Dv F_SETLKW ,
 514 and the system call was interrupted by a signal.
 515 .It Bq Er EINVAL
 516 The
 517 .Fa cmd
 518 argument
 519 is
 520 .Dv F_DUPFD
 521 and
 522 .Fa arg
 523 is negative or greater than the maximum allowable number
 524 (see
 525 .Xr getdtablesize 2 ) .
 526 .Pp
 527 The argument
 528 .Fa cmd
 529 is
 530 .Dv F_GETLK ,
 531 .Dv F_SETLK
 532 or
 533 .Dv F_SETLKW
 534 and the data to which
 535 .Fa arg
 536 points is not valid.
 537 .It Bq Er EMFILE
 538 The argument
 539 .Fa cmd
 540 is
 541 .Dv F_DUPFD
 542 or
 543 .Dv F_DUP2FD
 544 and the maximum number of file descriptors permitted for the
 545 process are already in use,
 546 or no file descriptors greater than or equal to
 547 .Fa arg
 548 are available.
 549 .It Bq Er ENOLCK
 550 The argument
 551 .Fa cmd
 552 is
 553 .Dv F_SETLK
 554 or
 555 .Dv F_SETLKW ,
 556 and satisfying the lock or unlock request would result in the
 557 number of locked regions in the system exceeding a system-imposed limit.
 558 .It Bq Er EOPNOTSUPP
 559 The argument
 560 .Fa cmd
 561 is
 562 .Dv F_GETLK ,
 563 .Dv F_SETLK
 564 or
 565 .Dv F_SETLKW
 566 and
 567 .Fa fd
 568 refers to a file for which locking is not supported.
 569 .It Bq Er EOVERFLOW
 570 The argument
 571 .Fa cmd
 572 is
 573 .Dv F_GETLK ,
 574 .Dv F_SETLK
 575 or
 576 .Dv F_SETLKW
 577 and an
 578 .Fa off_t
 579 calculation overflowed.
 580 .It Bq Er EPERM
 581 The
 582 .Fa cmd
 583 argument
 584 is
 585 .Dv F_SETOWN
 586 and
 587 the process ID or process group given as an argument is in a
 588 different session than the caller.
 589 .It Bq Er ESRCH
 590 The
 591 .Fa cmd
 592 argument
 593 is
 594 .Dv F_SETOWN
 595 and
 596 the process ID given as argument is not in use.
 597 .El
 598 .Pp
 599 In addition, if
 600 .Fa fd
 601 refers to a descriptor open on a terminal device (as opposed to a
 602 descriptor open on a socket), a
 603 .Fa cmd
 604 of
 605 .Dv F_SETOWN
 606 can fail for the same reasons as in
 607 .Xr tcsetpgrp 3 ,
 608 and a
 609 .Fa cmd
 610 of
 611 .Dv F_GETOWN
 612 for the reasons as stated in
 613 .Xr tcgetpgrp 3 .
 614 .Sh SEE ALSO
 615 .Xr close 2 ,
 616 .Xr dup2 2 ,
 617 .Xr execve 2 ,
 618 .Xr flock 2 ,
 619 .Xr getdtablesize 2 ,
 620 .Xr open 2 ,
 621 .Xr sigvec 2 ,
 622 .Xr lockf 3 ,
 623 .Xr tcgetpgrp 3 ,
 624 .Xr tcsetpgrp 3
 625 .Sh STANDARDS
 626 The
 627 .Dv F_DUP2FD
 628 constant is non portable.
 629 It is provided for compatibility with AIX and Solaris.
 630 .Sh HISTORY
 631 The
 632 .Fn fcntl
 633 system call appeared in
 634 .Bx 4.2 .
 635 .Pp
 636 The
 637 .Dv F_DUP2FD
 638 constant first appeared in
 639 .Fx 7.1 .