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 March 8, 2008
  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 .El
 245 .Pp
 246 When a shared lock has been set on a segment of a file,
 247 other processes can set shared locks on that segment
 248 or a portion of it.
 249 A shared lock prevents any other process from setting an exclusive
 250 lock on any portion of the protected area.
 251 A request for a shared lock fails if the file descriptor was not
 252 opened with read access.
 253 .Pp
 254 An exclusive lock prevents any other process from setting a shared lock or
 255 an exclusive lock on any portion of the protected area.
 256 A request for an exclusive lock fails if the file was not
 257 opened with write access.
 258 .Pp
 259 The value of
 260 .Fa l_whence
 261 is
 262 .Dv SEEK_SET ,
 263 .Dv SEEK_CUR ,
 264 or
 265 .Dv SEEK_END
 266 to indicate that the relative offset,
 267 .Fa l_start
 268 bytes, will be measured from the start of the file,
 269 current position, or end of the file, respectively.
 270 The value of
 271 .Fa l_len
 272 is the number of consecutive bytes to be locked.
 273 If
 274 .Fa l_len
 275 is negative,
 276 .Fa l_start
 277 means end edge of the region.
 278 The
 279 .Fa l_pid
 280 and
 281 .Fa l_sysid
 282 fields are only used with
 283 .Dv F_GETLK
 284 to return the process ID of the process holding a blocking lock and
 285 the system ID of the system that owns that process.
 286 Locks created by the local system will have a system ID of zero.
 287 After a successful
 288 .Dv F_GETLK
 289 request, the value of
 290 .Fa l_whence
 291 is
 292 .Dv SEEK_SET .
 293 .Pp
 294 Locks may start and extend beyond the current end of a file,
 295 but may not start or extend before the beginning of the file.
 296 A lock is set to extend to the largest possible value of the
 297 file offset for that file if
 298 .Fa l_len
 299 is set to zero.
 300 If
 301 .Fa l_whence
 302 and
 303 .Fa l_start
 304 point to the beginning of the file, and
 305 .Fa l_len
 306 is zero, the entire file is locked.
 307 If an application wishes only to do entire file locking, the
 308 .Xr flock 2
 309 system call is much more efficient.
 310 .Pp
 311 There is at most one type of lock set for each byte in the file.
 312 Before a successful return from an
 313 .Dv F_SETLK
 314 or an
 315 .Dv F_SETLKW
 316 request when the calling process has previously existing locks
 317 on bytes in the region specified by the request,
 318 the previous lock type for each byte in the specified
 319 region is replaced by the new lock type.
 320 As specified above under the descriptions
 321 of shared locks and exclusive locks, an
 322 .Dv F_SETLK
 323 or an
 324 .Dv F_SETLKW
 325 request fails or blocks respectively when another process has existing
 326 locks on bytes in the specified region and the type of any of those
 327 locks conflicts with the type specified in the request.
 328 .Pp
 329 This interface follows the completely stupid semantics of System V and
 330 .St -p1003.1-88
 331 that require that all locks associated with a file for a given process are
 332 removed when
 333 .Em any
 334 file descriptor for that file is closed by that process.
 335 This semantic means that applications must be aware of any files that
 336 a subroutine library may access.
 337 For example if an application for updating the password file locks the
 338 password file database while making the update, and then calls
 339 .Xr getpwnam 3
 340 to retrieve a record,
 341 the lock will be lost because
 342 .Xr getpwnam 3
 343 opens, reads, and closes the password database.
 344 The database close will release all locks that the process has
 345 associated with the database, even if the library routine never
 346 requested a lock on the database.
 347 Another minor semantic problem with this interface is that
 348 locks are not inherited by a child process created using the
 349 .Xr fork 2
 350 system call.
 351 The
 352 .Xr flock 2
 353 interface has much more rational last close semantics and
 354 allows locks to be inherited by child processes.
 355 The
 356 .Xr flock 2
 357 system call is recommended for applications that want to ensure the integrity
 358 of their locks when using library routines or wish to pass locks
 359 to their children.
 360 .Pp
 361 The
 362 .Fn fcntl ,
 363 .Xr flock 2 ,
 364 and
 365 .Xr lockf 3
 366 locks are compatible.
 367 Processes using different locking interfaces can cooperate
 368 over the same file safely.
 369 However, only one of such interfaces should be used within
 370 the same process.
 371 If a file is locked by a process through
 372 .Xr flock 2 ,
 373 any record within the file will be seen as locked
 374 from the viewpoint of another process using
 375 .Fn fcntl
 376 or
 377 .Xr lockf 3 ,
 378 and vice versa.
 379 Note that
 380 .Fn fcntl F_GETLK
 381 returns \-1 in
 382 .Fa l_pid
 383 if the process holding a blocking lock previously locked the
 384 file descriptor by
 385 .Xr flock 2 .
 386 .Pp
 387 All locks associated with a file for a given process are
 388 removed when the process terminates.
 389 .Pp
 390 All locks obtained before a call to
 391 .Xr execve 2
 392 remain in effect until the new program releases them.
 393 If the new program does not know about the locks, they will not be
 394 released until the program exits.
 395 .Pp
 396 A potential for deadlock occurs if a process controlling a locked region
 397 is put to sleep by attempting to lock the locked region of another process.
 398 This implementation detects that sleeping until a locked region is unlocked
 399 would cause a deadlock and fails with an
 400 .Er EDEADLK
 401 error.
 402 .Sh RETURN VALUES
 403 Upon successful completion, the value returned depends on
 404 .Fa cmd
 405 as follows:
 406 .Bl -tag -width F_GETOWNX -offset indent
 407 .It Dv F_DUPFD
 408 A new file descriptor.
 409 .It Dv F_DUP2FD
 410 A file descriptor equal to
 411 .Fa arg .
 412 .It Dv F_GETFD
 413 Value of flag (only the low-order bit is defined).
 414 .It Dv F_GETFL
 415 Value of flags.
 416 .It Dv F_GETOWN
 417 Value of file descriptor owner.
 418 .It other
 419 Value other than -1.
 420 .El
 421 .Pp
 422 Otherwise, a value of -1 is returned and
 423 .Va errno
 424 is set to indicate the error.
 425 .Sh ERRORS
 426 The
 427 .Fn fcntl
 428 system call will fail if:
 429 .Bl -tag -width Er
 430 .It Bq Er EAGAIN
 431 The argument
 432 .Fa cmd
 433 is
 434 .Dv F_SETLK ,
 435 the type of lock
 436 .Pq Fa l_type
 437 is a shared lock
 438 .Pq Dv F_RDLCK
 439 or exclusive lock
 440 .Pq Dv F_WRLCK ,
 441 and the segment of a file to be locked is already
 442 exclusive-locked by another process;
 443 or the type is an exclusive lock and some portion of the
 444 segment of a file to be locked is already shared-locked or
 445 exclusive-locked by another process.
 446 .It Bq Er EBADF
 447 The
 448 .Fa fd
 449 argument
 450 is not a valid open file descriptor.
 451 .Pp
 452 The argument
 453 .Fa cmd
 454 is
 455 .Dv F_DUP2FD ,
 456 and
 457 .Fa arg
 458 is not a valid file descriptor.
 459 .Pp
 460 The argument
 461 .Fa cmd
 462 is
 463 .Dv F_SETLK
 464 or
 465 .Dv F_SETLKW ,
 466 the type of lock
 467 .Pq Fa l_type
 468 is a shared lock
 469 .Pq Dv F_RDLCK ,
 470 and
 471 .Fa fd
 472 is not a valid file descriptor open for reading.
 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 an exclusive lock
 483 .Pq Dv F_WRLCK ,
 484 and
 485 .Fa fd
 486 is not a valid file descriptor open for writing.
 487 .It Bq Er EDEADLK
 488 The argument
 489 .Fa cmd
 490 is
 491 .Dv F_SETLKW ,
 492 and a deadlock condition was detected.
 493 .It Bq Er EINTR
 494 The argument
 495 .Fa cmd
 496 is
 497 .Dv F_SETLKW ,
 498 and the system call was interrupted by a signal.
 499 .It Bq Er EINVAL
 500 The
 501 .Fa cmd
 502 argument
 503 is
 504 .Dv F_DUPFD
 505 and
 506 .Fa arg
 507 is negative or greater than the maximum allowable number
 508 (see
 509 .Xr getdtablesize 2 ) .
 510 .Pp
 511 The argument
 512 .Fa cmd
 513 is
 514 .Dv F_GETLK ,
 515 .Dv F_SETLK
 516 or
 517 .Dv F_SETLKW
 518 and the data to which
 519 .Fa arg
 520 points is not valid.
 521 .It Bq Er EMFILE
 522 The argument
 523 .Fa cmd
 524 is
 525 .Dv F_DUPFD
 526 or
 527 .Dv F_DUP2FD
 528 and the maximum number of file descriptors permitted for the
 529 process are already in use,
 530 or no file descriptors greater than or equal to
 531 .Fa arg
 532 are available.
 533 .It Bq Er ENOLCK
 534 The argument
 535 .Fa cmd
 536 is
 537 .Dv F_SETLK
 538 or
 539 .Dv F_SETLKW ,
 540 and satisfying the lock or unlock request would result in the
 541 number of locked regions in the system exceeding a system-imposed limit.
 542 .It Bq Er EOPNOTSUPP
 543 The argument
 544 .Fa cmd
 545 is
 546 .Dv F_GETLK ,
 547 .Dv F_SETLK
 548 or
 549 .Dv F_SETLKW
 550 and
 551 .Fa fd
 552 refers to a file for which locking is not supported.
 553 .It Bq Er EOVERFLOW
 554 The argument
 555 .Fa cmd
 556 is
 557 .Dv F_GETLK ,
 558 .Dv F_SETLK
 559 or
 560 .Dv F_SETLKW
 561 and an
 562 .Fa off_t
 563 calculation overflowed.
 564 .It Bq Er EPERM
 565 The
 566 .Fa cmd
 567 argument
 568 is
 569 .Dv F_SETOWN
 570 and
 571 the process ID or process group given as an argument is in a
 572 different session than the caller.
 573 .It Bq Er ESRCH
 574 The
 575 .Fa cmd
 576 argument
 577 is
 578 .Dv F_SETOWN
 579 and
 580 the process ID given as argument is not in use.
 581 .El
 582 .Pp
 583 In addition, if
 584 .Fa fd
 585 refers to a descriptor open on a terminal device (as opposed to a
 586 descriptor open on a socket), a
 587 .Fa cmd
 588 of
 589 .Dv F_SETOWN
 590 can fail for the same reasons as in
 591 .Xr tcsetpgrp 3 ,
 592 and a
 593 .Fa cmd
 594 of
 595 .Dv F_GETOWN
 596 for the reasons as stated in
 597 .Xr tcgetpgrp 3 .
 598 .Sh SEE ALSO
 599 .Xr close 2 ,
 600 .Xr dup2 2 ,
 601 .Xr execve 2 ,
 602 .Xr flock 2 ,
 603 .Xr getdtablesize 2 ,
 604 .Xr open 2 ,
 605 .Xr sigvec 2 ,
 606 .Xr lockf 3 ,
 607 .Xr tcgetpgrp 3 ,
 608 .Xr tcsetpgrp 3
 609 .Sh STANDARDS
 610 The
 611 .Dv F_DUP2FD
 612 constant is non portable.
 613 It is provided for compatibility with AIX and Solaris.
 614 .Sh HISTORY
 615 The
 616 .Fn fcntl
 617 system call appeared in
 618 .Bx 4.2 .
 619 .Pp
 620 The
 621 .Dv F_DUP2FD
 622 constant first appeared in
 623 .Fx 7.1 .