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 .\" 3. 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: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $
  30 .\"
  31 .Dd June 12, 2013
  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_DUP2FD_CLOEXEC
  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
  77 .Dv FD_CLOEXEC
  78 associated with the new file descriptor is cleared, so the file descriptor is
  79 to remain open across
  80 .Xr execve 2
  81 system calls.
  82 .El
  83 .It Dv F_DUPFD_CLOEXEC
  84 Like
  85 .Dv F_DUPFD ,
  86 but the
  87 .Dv FD_CLOEXEC
  88 flag associated with the new file descriptor is set, so the file descriptor
  89 is closed when
  90 .Xr execve 2
  91 system call executes.
  92 .It Dv F_DUP2FD
  93 It is functionally equivalent to
  94 .Bd -literal -offset indent
  95 dup2(fd, arg)
  96 .Ed
  97 .It Dv F_DUP2FD_CLOEXEC
  98 Like
  99 .Dv F_DUP2FD ,
 100 but the
 101 .Dv FD_CLOEXEC
 102 flag associated with the new file descriptor is set.
 103 .Pp
 104 The
 105 .Dv F_DUP2FD
 106 and
 107 .Dv F_DUP2FD_CLOEXEC
 108 constants are not portable, so they should not be used if
 109 portability is needed.
 110 Use
 111 .Fn dup2
 112 instead of
 113 .Dv F_DUP2FD .
 114 .It Dv F_GETFD
 115 Get the close-on-exec flag associated with the file descriptor
 116 .Fa fd
 117 as
 118 .Dv FD_CLOEXEC .
 119 If the returned value ANDed with
 120 .Dv FD_CLOEXEC
 121 is 0,
 122 the file will remain open across
 123 .Fn exec ,
 124 otherwise the file will be closed upon execution of
 125 .Fn exec
 126 .Fa ( arg
 127 is ignored).
 128 .It Dv F_SETFD
 129 Set the close-on-exec flag associated with
 130 .Fa fd
 131 to
 132 .Fa arg ,
 133 where
 134 .Fa arg
 135 is either 0 or
 136 .Dv FD_CLOEXEC ,
 137 as described above.
 138 .It Dv F_GETFL
 139 Get descriptor status flags, as described below
 140 .Fa ( arg
 141 is ignored).
 142 .It Dv F_SETFL
 143 Set descriptor status flags to
 144 .Fa arg .
 145 .It Dv F_GETOWN
 146 Get the process ID or process group
 147 currently receiving
 148 .Dv SIGIO
 149 and
 150 .Dv SIGURG
 151 signals; process groups are returned
 152 as negative values
 153 .Fa ( arg
 154 is ignored).
 155 .It Dv F_SETOWN
 156 Set the process or process group
 157 to receive
 158 .Dv SIGIO
 159 and
 160 .Dv SIGURG
 161 signals;
 162 process groups are specified by supplying
 163 .Fa arg
 164 as negative, otherwise
 165 .Fa arg
 166 is interpreted as a process ID.
 167 .El
 168 .Pp
 169 The flags for the
 170 .Dv F_GETFL
 171 and
 172 .Dv F_SETFL
 173 flags are as follows:
 174 .Bl -tag -width O_NONBLOCKX
 175 .It Dv O_NONBLOCK
 176 Non-blocking I/O; if no data is available to a
 177 .Xr read 2
 178 system call, or if a
 179 .Xr write 2
 180 operation would block,
 181 the read or write call returns -1 with the error
 182 .Er EAGAIN .
 183 .It Dv O_APPEND
 184 Force each write to append at the end of file;
 185 corresponds to the
 186 .Dv O_APPEND
 187 flag of
 188 .Xr open 2 .
 189 .It Dv O_DIRECT
 190 Minimize or eliminate the cache effects of reading and writing.
 191 The system
 192 will attempt to avoid caching the data you read or write.
 193 If it cannot
 194 avoid caching the data, it will minimize the impact the data has on the cache.
 195 Use of this flag can drastically reduce performance if not used with care.
 196 .It Dv O_ASYNC
 197 Enable the
 198 .Dv SIGIO
 199 signal to be sent to the process group
 200 when I/O is possible, e.g.,
 201 upon availability of data to be read.
 202 .El
 203 .Pp
 204 Several commands are available for doing advisory file locking;
 205 they all operate on the following structure:
 206 .Bd -literal
 207 struct flock {
 208         off_t   l_start;        /* starting offset */
 209         off_t   l_len;          /* len = 0 means until end of file */
 210         pid_t   l_pid;          /* lock owner */
 211         short   l_type;         /* lock type: read/write, etc. */
 212         short   l_whence;       /* type of l_start */
 213 };
 214 .Ed
 215 The commands available for advisory record locking are as follows:
 216 .Bl -tag -width F_SETLKWX
 217 .It Dv F_GETLK
 218 Get the first lock that blocks the lock description pointed to by the
 219 third argument,
 220 .Fa arg ,
 221 taken as a pointer to a
 222 .Fa "struct flock"
 223 (see above).
 224 The information retrieved overwrites the information passed to
 225 .Fn fcntl
 226 in the
 227 .Fa flock
 228 structure.
 229 If no lock is found that would prevent this lock from being created,
 230 the structure is left unchanged by this system call except for the
 231 lock type which is set to
 232 .Dv F_UNLCK .
 233 .It Dv F_SETLK
 234 Set or clear a file segment lock according to the lock description
 235 pointed to by the third argument,
 236 .Fa arg ,
 237 taken as a pointer to a
 238 .Fa "struct flock"
 239 (see above).
 240 .Dv F_SETLK
 241 is used to establish shared (or read) locks
 242 .Pq Dv F_RDLCK
 243 or exclusive (or write) locks,
 244 .Pq Dv F_WRLCK ,
 245 as well as remove either type of lock
 246 .Pq Dv F_UNLCK .
 247 If a shared or exclusive lock cannot be set,
 248 .Fn fcntl
 249 returns immediately with
 250 .Er EAGAIN .
 251 .It Dv F_SETLKW
 252 This command is the same as
 253 .Dv F_SETLK
 254 except that if a shared or exclusive lock is blocked by other locks,
 255 the process waits until the request can be satisfied.
 256 If a signal that is to be caught is received while
 257 .Fn fcntl
 258 is waiting for a region, the
 259 .Fn fcntl
 260 will be interrupted if the signal handler has not specified the
 261 .Dv SA_RESTART
 262 (see
 263 .Xr sigaction 2 ) .
 264 .El
 265 .Pp
 266 When a shared lock has been set on a segment of a file,
 267 other processes can set shared locks on that segment
 268 or a portion of it.
 269 A shared lock prevents any other process from setting an exclusive
 270 lock on any portion of the protected area.
 271 A request for a shared lock fails if the file descriptor was not
 272 opened with read access.
 273 .Pp
 274 An exclusive lock prevents any other process from setting a shared lock or
 275 an exclusive lock on any portion of the protected area.
 276 A request for an exclusive lock fails if the file was not
 277 opened with write access.
 278 .Pp
 279 The value of
 280 .Fa l_whence
 281 is
 282 .Dv SEEK_SET ,
 283 .Dv SEEK_CUR ,
 284 or
 285 .Dv SEEK_END
 286 to indicate that the relative offset,
 287 .Fa l_start
 288 bytes, will be measured from the start of the file,
 289 current position, or end of the file, respectively.
 290 The value of
 291 .Fa l_len
 292 is the number of consecutive bytes to be locked.
 293 If
 294 .Fa l_len
 295 is negative, the result is undefined.
 296 The
 297 .Fa l_pid
 298 field is only used with
 299 .Dv F_GETLK
 300 to return the process ID of the process holding a blocking lock.
 301 After a successful
 302 .Dv F_GETLK
 303 request, the value of
 304 .Fa l_whence
 305 is
 306 .Dv SEEK_SET .
 307 .Pp
 308 Locks may start and extend beyond the current end of a file,
 309 but may not start or extend before the beginning of the file.
 310 A lock is set to extend to the largest possible value of the
 311 file offset for that file if
 312 .Fa l_len
 313 is set to zero.
 314 If
 315 .Fa l_whence
 316 and
 317 .Fa l_start
 318 point to the beginning of the file, and
 319 .Fa l_len
 320 is zero, the entire file is locked.
 321 If an application wishes only to do entire file locking, the
 322 .Xr flock 2
 323 system call is much more efficient.
 324 .Pp
 325 There is at most one type of lock set for each byte in the file.
 326 Before a successful return from an
 327 .Dv F_SETLK
 328 or an
 329 .Dv F_SETLKW
 330 request when the calling process has previously existing locks
 331 on bytes in the region specified by the request,
 332 the previous lock type for each byte in the specified
 333 region is replaced by the new lock type.
 334 As specified above under the descriptions
 335 of shared locks and exclusive locks, an
 336 .Dv F_SETLK
 337 or an
 338 .Dv F_SETLKW
 339 request fails or blocks respectively when another process has existing
 340 locks on bytes in the specified region and the type of any of those
 341 locks conflicts with the type specified in the request.
 342 .Pp
 343 This interface follows the completely stupid semantics of System V and
 344 .St -p1003.1-88
 345 that require that all locks associated with a file for a given process are
 346 removed when
 347 .Em any
 348 file descriptor for that file is closed by that process.
 349 This semantic means that applications must be aware of any files that
 350 a subroutine library may access.
 351 For example if an application for updating the password file locks the
 352 password file database while making the update, and then calls
 353 .Xr getpwnam 3
 354 to retrieve a record,
 355 the lock will be lost because
 356 .Xr getpwnam 3
 357 opens, reads, and closes the password database.
 358 The database close will release all locks that the process has
 359 associated with the database, even if the library routine never
 360 requested a lock on the database.
 361 Another minor semantic problem with this interface is that
 362 locks are not inherited by a child process created using the
 363 .Xr fork 2
 364 system call.
 365 The
 366 .Xr flock 2
 367 interface has much more rational last close semantics and
 368 allows locks to be inherited by child processes.
 369 The
 370 .Xr flock 2
 371 system call is recommended for applications that want to ensure the integrity
 372 of their locks when using library routines or wish to pass locks
 373 to their children.
 374 .Pp
 375 The
 376 .Fn fcntl ,
 377 .Xr flock 2 ,
 378 and
 379 .Xr lockf 3
 380 locks are compatible.
 381 Processes using different locking interfaces can cooperate
 382 over the same file safely.
 383 However, only one of such interfaces should be used within
 384 the same process.
 385 If a file is locked by a process through
 386 .Xr flock 2 ,
 387 any record within the file will be seen as locked
 388 from the viewpoint of another process using
 389 .Fn fcntl
 390 or
 391 .Xr lockf 3 ,
 392 and vice versa.
 393 Note that
 394 .Fn fcntl F_GETLK
 395 returns \-1 in
 396 .Fa l_pid
 397 if the process holding a blocking lock previously locked the
 398 file descriptor by
 399 .Xr flock 2 .
 400 .Pp
 401 All locks associated with a file for a given process are
 402 removed when the process terminates.
 403 .Pp
 404 All locks obtained before a call to
 405 .Xr execve 2
 406 remain in effect until the new program releases them.
 407 If the new program does not know about the locks, they will not be
 408 released until the program exits.
 409 .Pp
 410 A potential for deadlock occurs if a process controlling a locked region
 411 is put to sleep by attempting to lock the locked region of another process.
 412 This implementation detects that sleeping until a locked region is unlocked
 413 would cause a deadlock and fails with an
 414 .Er EDEADLK
 415 error.
 416 .Sh RETURN VALUES
 417 Upon successful completion, the value returned depends on
 418 .Fa cmd
 419 as follows:
 420 .Bl -tag -width F_GETOWNX -offset indent
 421 .It Dv F_DUPFD
 422 A new file descriptor.
 423 .It Dv F_DUP2FD
 424 A file descriptor equal to
 425 .Fa arg .
 426 .It Dv F_GETFD
 427 Value of flag (only the low-order bit is defined).
 428 .It Dv F_GETFL
 429 Value of flags.
 430 .It Dv F_GETOWN
 431 Value of file descriptor owner.
 432 .It other
 433 Value other than -1.
 434 .El
 435 .Pp
 436 Otherwise, a value of -1 is returned and
 437 .Va errno
 438 is set to indicate the error.
 439 .Sh ERRORS
 440 The
 441 .Fn fcntl
 442 system call will fail if:
 443 .Bl -tag -width Er
 444 .It Bq Er EAGAIN
 445 The argument
 446 .Fa cmd
 447 is
 448 .Dv F_SETLK ,
 449 the type of lock
 450 .Pq Fa l_type
 451 is a shared lock
 452 .Pq Dv F_RDLCK
 453 or exclusive lock
 454 .Pq Dv F_WRLCK ,
 455 and the segment of a file to be locked is already
 456 exclusive-locked by another process;
 457 or the type is an exclusive lock and some portion of the
 458 segment of a file to be locked is already shared-locked or
 459 exclusive-locked by another process.
 460 .It Bq Er EBADF
 461 The
 462 .Fa fd
 463 argument
 464 is not a valid open file descriptor.
 465 .Pp
 466 The argument
 467 .Fa cmd
 468 is
 469 .Dv F_DUP2FD ,
 470 and
 471 .Fa arg
 472 is not a valid file descriptor.
 473 .Pp
 474 The argument
 475 .Fa cmd
 476 is
 477 .Dv F_SETLK
 478 or
 479 .Dv F_SETLKW ,
 480 the type of lock
 481 .Pq Fa l_type
 482 is a shared lock
 483 .Pq Dv F_RDLCK ,
 484 and
 485 .Fa fd
 486 is not a valid file descriptor open for reading.
 487 .Pp
 488 The argument
 489 .Fa cmd
 490 is
 491 .Dv F_SETLK
 492 or
 493 .Dv F_SETLKW ,
 494 the type of lock
 495 .Pq Fa l_type
 496 is an exclusive lock
 497 .Pq Dv F_WRLCK ,
 498 and
 499 .Fa fd
 500 is not a valid file descriptor open for writing.
 501 .It Bq Er EDEADLK
 502 The argument
 503 .Fa cmd
 504 is
 505 .Dv F_SETLKW ,
 506 and a deadlock condition was detected.
 507 .It Bq Er EINTR
 508 The argument
 509 .Fa cmd
 510 is
 511 .Dv F_SETLKW ,
 512 and the system call was interrupted by a signal.
 513 .It Bq Er EINVAL
 514 The
 515 .Fa cmd
 516 argument
 517 is
 518 .Dv F_DUPFD
 519 and
 520 .Fa arg
 521 is negative or greater than the maximum allowable number
 522 (see
 523 .Xr getdtablesize 2 ) .
 524 .Pp
 525 The argument
 526 .Fa cmd
 527 is
 528 .Dv F_GETLK ,
 529 .Dv F_SETLK
 530 or
 531 .Dv F_SETLKW
 532 and the data to which
 533 .Fa arg
 534 points is not valid.
 535 .It Bq Er EMFILE
 536 The argument
 537 .Fa cmd
 538 is
 539 .Dv F_DUPFD
 540 and the maximum number of file descriptors permitted for the
 541 process are already in use,
 542 or no file descriptors greater than or equal to
 543 .Fa arg
 544 are available.
 545 .It Bq Er ENOLCK
 546 The argument
 547 .Fa cmd
 548 is
 549 .Dv F_SETLK
 550 or
 551 .Dv F_SETLKW ,
 552 and satisfying the lock or unlock request would result in the
 553 number of locked regions in the system exceeding a system-imposed limit.
 554 .It Bq Er EPERM
 555 The
 556 .Fa cmd
 557 argument
 558 is
 559 .Dv F_SETOWN
 560 and
 561 the process ID or process group given as an argument is in a
 562 different session than the caller.
 563 .It Bq Er ESRCH
 564 The
 565 .Fa cmd
 566 argument
 567 is
 568 .Dv F_SETOWN
 569 and
 570 the process ID given as argument is not in use.
 571 .El
 572 .Pp
 573 In addition, if
 574 .Fa fd
 575 refers to a descriptor open on a terminal device (as opposed to a
 576 descriptor open on a socket), a
 577 .Fa cmd
 578 of
 579 .Dv F_SETOWN
 580 can fail for the same reasons as in
 581 .Xr tcsetpgrp 3 ,
 582 and a
 583 .Fa cmd
 584 of
 585 .Dv F_GETOWN
 586 for the reasons as stated in
 587 .Xr tcgetpgrp 3 .
 588 .Sh SEE ALSO
 589 .Xr close 2 ,
 590 .Xr dup2 2 ,
 591 .Xr execve 2 ,
 592 .Xr flock 2 ,
 593 .Xr getdtablesize 2 ,
 594 .Xr open 2 ,
 595 .Xr sigaction 2 ,
 596 .Xr lockf 3 ,
 597 .Xr tcgetpgrp 3 ,
 598 .Xr tcsetpgrp 3
 599 .Sh STANDARDS
 600 The
 601 .Dv F_DUP2FD
 602 constant is non portable.
 603 It is provided for compatibility with AIX and Solaris.
 604 .Sh HISTORY
 605 The
 606 .Fn fcntl
 607 system call appeared in
 608 .Bx 4.2 .
 609 .Pp
 610 The
 611 .Dv F_DUP_CLOEXEC ,
 612 .Dv F_DUP2FD
 613 and
 614 .Dv F_DUP2FD_CLOEXEC
 615 constants first appeared in
 616 .Dx 3.5 .