bsd/man/man2/fcntl.2

   1 .\"     $NetBSD: fcntl.2,v 1.6 1995/02/27 12:32:29 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)fcntl.2     8.2 (Berkeley) 1/12/94
  35 .\"
  36 .Dd January 12, 1994
  37 .Dt FCNTL 2
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm fcntl
  41 .Nd file control
  42 .Sh SYNOPSIS
  43 .Fd #include <fcntl.h>
  44 .Ft int
  45 .Fo fcntl
  46 .Fa "int fildes"
  47 .Fa "int cmd"
  48 .Fa "..."
  49 .Fc
  50 .Sh DESCRIPTION
  51 .Fn Fcntl
  52 provides for control over descriptors.
  53 The argument
  54 .Fa fildes
  55 is a descriptor to be operated on by
  56 .Fa cmd
  57 as follows:
  58 .Bl -tag -width F_WRITEBOOTSTRAPX
  59 .It Dv F_DUPFD
  60 Return a new descriptor as follows:
  61 .Pp
  62 .Bl -bullet -compact -offset 4n
  63 .It
  64 Lowest numbered available descriptor greater than or equal to
  65 .Fa arg .
  66 .It
  67 Same object references as the original descriptor.
  68 .It
  69 New descriptor shares the same file offset if the object
  70 was a file.
  71 .It
  72 Same access mode (read, write or read/write).
  73 .It
  74 Same file status flags (i.e., both file descriptors
  75 share the same file status flags).
  76 .It
  77 The close-on-exec flag associated with the new file descriptor
  78 is set to remain open across
  79 .Xr execv 2
  80 system calls.
  81 .El
  82 .It Dv F_GETFD
  83 Get the close-on-exec flag associated with the file descriptor
  84 .Fa fildes .
  85 If the low-order bit of the returned value is 0,
  86 the file will remain open across
  87 .Fn exec ,
  88 otherwise the file will be closed upon execution of
  89 .Fn exec
  90 .Fa ( arg
  91 is ignored).
  92 .It Dv F_SETFD
  93 Set the close-on-exec flag associated with
  94 .Fa fildes
  95 to the low order bit of
  96 .Fa arg
  97 (0 or 1 as above).
  98 .It Dv F_GETFL
  99 Get descriptor status flags, as described below
 100 .Fa ( arg
 101 is ignored).
 102 .It Dv F_SETFL
 103 Set descriptor status flags to
 104 .Fa arg .
 105 .It Dv F_GETOWN
 106 Get the process ID or process group
 107 currently receiving
 108 .Dv SIGIO
 109 and
 110 .Dv SIGURG
 111 signals; process groups are returned
 112 as negative values
 113 .Fa ( arg
 114 is ignored).
 115 .It Dv F_SETOWN
 116 Set the process or process group
 117 to receive
 118 .Dv SIGIO
 119 and
 120 .Dv SIGURG
 121 signals;
 122 process groups are specified by supplying
 123 .Fa arg
 124 as negative, otherwise
 125 .Fa arg
 126 is interpreted as a process ID.
 127 .It Dv F_GETPATH
 128 Get the path of the file descriptor
 129 .Fa Fildes .
 130 The argument must be a buffer of size
 131 .Sy MAXPATHLEN
 132 or greater.
 133 .It Dv F_PREALLOCATE
 134 Preallocate file storage space.
 135 .It Dv F_SETSIZE
 136 Truncate a file without zeroing space.
 137 The calling process must have root privileges.
 138 .It Dv F_RDADVISE
 139 Issue an advisory read async with no copy to user.
 140 .It Dv F_RDAHEAD
 141 Turn read ahead off/on.
 142 A zero value in
 143 .Fa arg
 144 disables read ahead.
 145 A non-zero value in
 146 .Fa arg
 147 turns read ahead on.
 148 .It Dv F_READBOOTSTRAP
 149 Read bootstrap from disk.
 150 .It Dv F_WRITEBOOTSTRAP
 151 Write bootstrap on disk.
 152 The calling process must have root privileges.
 153 .It Dv F_NOCACHE
 154 Turns data caching off/on. A non-zero value in
 155 .Fa arg
 156 turns data caching off.
 157 A value of zero in
 158 .Fa arg
 159 turns data caching on.
 160 .It Dv F_LOG2PHYS
 161 Get disk device information.
 162 Currently this only includes the
 163 disk device address that corresponds
 164 to the current file offset.
 165 .It Dv F_FULLFSYNC
 166 Does the same thing as
 167 .Xr fsync 2
 168 then asks the drive to
 169 flush all buffered data to
 170 the permanent storage device
 171 .Fa ( arg
 172 is ignored).
 173 This is currently implemented on HFS, MS-DOS (FAT),
 174 and Universal Disk Format (UDF) file systems.
 175 The operation may take quite a while to complete.
 176 Certain FireWire drives have also been known
 177 to ignore the request to flush their buffered data.
 178 .El
 179 .Pp
 180 The flags for the
 181 .Dv F_GETFL
 182 and
 183 .Dv F_SETFL
 184 commands are as follows:
 185 .Bl -tag -width O_NONBLOCKX -offset indent
 186 .It Dv O_NONBLOCK
 187 Non-blocking I/O; if no data is available to a
 188 .Xr read
 189 call, or if a
 190 .Xr write
 191 operation would block,
 192 the read or write call returns -1 with the error
 193 .Er EAGAIN .
 194 .It Dv O_APPEND
 195 Force each write to append at the end of file;
 196 corresponds to the
 197 .Dv O_APPEND
 198 flag of
 199 .Xr open 2 .
 200 .It Dv O_ASYNC
 201 Enable the
 202 .Dv SIGIO
 203 signal to be sent to the process group
 204 when I/O is possible, e.g.,
 205 upon availability of data to be read.
 206 .El
 207 .Pp
 208 Several commands are available for doing advisory file locking;
 209 they all operate on the following structure:
 210 .ne 7v
 211 .Bd -literal
 212         struct flock {
 213             off_t       l_start;    /* starting offset */
 214             off_t       l_len;      /* len = 0 means until end of file */
 215             pid_t       l_pid;      /* lock owner */
 216             short       l_type;     /* lock type: read/write, etc. */
 217             short       l_whence;   /* type of l_start */
 218         };
 219 .Ed
 220 .Pp
 221 The commands available for advisory record locking are as follows:
 222 .Bl -tag -width F_SETLKWX
 223 .It Dv F_GETLK
 224 Get the first lock that blocks the lock description pointed to by the
 225 third argument,
 226 .Fa arg ,
 227 taken as a pointer to a
 228 .Fa "struct flock"
 229 (see above).
 230 The information retrieved overwrites the information passed to
 231 .Nm fcntl
 232 in the
 233 .Fa flock
 234 structure.
 235 If no lock is found that would prevent this lock from being created,
 236 the structure is left unchanged by this function call except for the
 237 lock type which is set to
 238 .Dv F_UNLCK .
 239 .It Dv F_SETLK
 240 Set or clear a file segment lock according to the lock description
 241 pointed to by the third argument,
 242 .Fa arg ,
 243 taken as a pointer to a
 244 .Fa "struct flock"
 245 (see above).
 246 .Dv F_SETLK
 247 is used to establish shared (or read) locks
 248 .Dv (F_RDLCK)
 249 or exclusive (or write) locks,
 250 .Dv (F_WRLCK) ,
 251 as well as remove either type of lock
 252 .Dv (F_UNLCK) .
 253 If a shared or exclusive lock cannot be set,
 254 .Nm fcntl
 255 returns immediately with
 256 .Er EACCES .
 257 .It Dv F_SETLKW
 258 This command is the same as
 259 .Dv F_SETLK
 260 except that if a shared or exclusive lock is blocked by other locks,
 261 the process waits until the request can be satisfied.
 262 If a signal that is to be caught is received while
 263 .Nm fcntl
 264 is waiting for a region, the
 265 .Nm fcntl
 266 will be interrupted if the signal handler has not specified the
 267 .Dv SA_RESTART
 268 (see
 269 .Xr sigaction 2 ) .
 270 .El
 271 .Pp
 272 When a shared lock has been set on a segment of a file,
 273 other processes can set shared locks on that segment
 274 or a portion of it.
 275 A shared lock prevents any other process from setting an exclusive
 276 lock on any portion of the protected area.
 277 A request for a shared lock fails if the file descriptor was not
 278 opened with read access.
 279 .Pp
 280 An exclusive lock prevents any other process from setting a shared lock or
 281 an exclusive lock on any portion of the protected area.
 282 A request for an exclusive lock fails if the file was not
 283 opened with write access.
 284 .Pp
 285 The value of
 286 .Fa l_whence
 287 is
 288 .Dv SEEK_SET ,
 289 .Dv SEEK_CUR ,
 290 or
 291 .Dv SEEK_END
 292 to indicate that the relative offset,
 293 .Fa l_start
 294 bytes, will be measured from the start of the file,
 295 current position, or end of the file, respectively.
 296 The value of
 297 .Fa l_len
 298 is the number of consecutive bytes to be locked.
 299 If
 300 .Fa l_len
 301 is negative, the result is undefined.
 302 The
 303 .Fa l_pid
 304 field is only used with
 305 .Dv F_GETLK
 306 to return the process ID of the process holding a blocking lock.
 307 After a successful
 308 .Dv F_GETLK
 309 request, the value of
 310 .Fa l_whence
 311 is
 312 .Dv SEEK_SET .
 313 .Pp
 314 Locks may start and extend beyond the current end of a file,
 315 but may not start or extend before the beginning of the file.
 316 A lock is set to extend to the largest possible value of the
 317 file offset for that file if
 318 .Fa l_len
 319 is set to zero. If
 320 .Fa l_whence
 321 and
 322 .Fa l_start
 323 point to the beginning of the file, and
 324 .Fa l_len
 325 is zero, the entire file is locked.
 326 If an application wishes only to do entire file locking, the
 327 .Xr flock 2
 328 system call is much more efficient.
 329 .Pp
 330 There is at most one type of lock set for each byte in the file.
 331 Before a successful return from an
 332 .Dv F_SETLK
 333 or an
 334 .Dv F_SETLKW
 335 request when the calling process has previously existing locks
 336 on bytes in the region specified by the request,
 337 the previous lock type for each byte in the specified
 338 region is replaced by the new lock type.
 339 As specified above under the descriptions
 340 of shared locks and exclusive locks, an
 341 .Dv F_SETLK
 342 or an
 343 .Dv F_SETLKW
 344 request fails or blocks respectively when another process has existing
 345 locks on bytes in the specified region and the type of any of those
 346 locks conflicts with the type specified in the request.
 347 .Pp
 348 This interface follows the completely stupid semantics of System V and
 349 .St -p1003.1-88
 350 that require that all locks associated with a file for a given process are
 351 removed when \fIany\fP file descriptor for that file is closed by that process.
 352 This semantic means that applications must be aware of any files that
 353 a subroutine library may access.
 354 For example if an application for updating the password file locks the
 355 password file database while making the update, and then calls
 356 .Xr getpwname 3
 357 to retrieve a record,
 358 the lock will be lost because
 359 .Xr getpwname 3
 360 opens, reads, and closes the password database.
 361 The database close will release all locks that the process has
 362 associated with the database, even if the library routine never
 363 requested a lock on the database.
 364 Another minor semantic problem with this interface is that
 365 locks are not inherited by a child process created using the
 366 .Xr fork 2
 367 function.
 368 The
 369 .Xr flock 2
 370 interface has much more rational last close semantics and
 371 allows locks to be inherited by child processes.
 372 .Xr Flock 2
 373 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 Note that
 377 .Xr flock 2
 378 and
 379 .Xr fcntl 2
 380 locks may be safely used concurrently.
 381 .Pp
 382 All locks associated with a file for a given process are
 383 removed when the process terminates.
 384 .Pp
 385 A potential for deadlock occurs if a process controlling a locked region
 386 is put to sleep by attempting to lock the locked region of another process.
 387 This implementation detects that sleeping until a locked region is unlocked
 388 would cause a deadlock and fails with an
 389 .Er EDEADLK
 390 error.
 391 .Pp
 392 The
 393 .Dv F_PREALLOCATE
 394 command operates on the following structure:
 395 .ne 7v
 396 .Bd -literal
 397         typedef struct fstore {
 398             u_int32_t fst_flags;      /* IN: flags word */
 399             int       fst_posmode;    /* IN: indicates offset field */
 400             off_t     fst_offset;     /* IN: start of the region */
 401             off_t     fst_length;     /* IN: size of the region */
 402             off_t     fst_bytesalloc; /* OUT: number of bytes allocated */
 403         } fstore_t;
 404 .Ed
 405 .Pp
 406 The flags (fst_flags) for the
 407 .Dv F_PREALLOCATE
 408 command are as follows:
 409 .Bl -tag -width F_ALLOCATECONTIGX -offset indent
 410 .It Dv F_ALLOCATECONTIG
 411 Allocate contiguous space.
 412 .It Dv F_ALLOCATEALL
 413 Allocate all requested space or no space at all.
 414 .El
 415 .Pp
 416 The position modes (fst_posmode) for the
 417 .Dv F_PREALLOCATE
 418 command indicate how to use the offset field.
 419 The modes are as follows:
 420 .Bl -tag -width F_PEOFPOSMODEX -offset indent
 421 .It Dv F_PEOFPOSMODE
 422 Allocate from the physical end of file.
 423 .It Dv F_VOLPOSMODE
 424 Allocate from the volume offset.
 425 .El
 426 .Pp
 427 The
 428 .Dv F_RDADVISE
 429 command operates on the following structure
 430 which holds information passed from the
 431 user to the system:
 432 .ne 7v
 433 .Bd -literal
 434         struct radvisory {
 435            off_t   ra_offset;  /* offset into the file */
 436            int     ra_count;   /* size of the read     */
 437         };
 438 .Ed
 439 .Pp
 440 The
 441 .Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP
 442 commands operate on the following structure.
 443 .ne 7v
 444 .Bd -literal
 445         typedef struct fbootstraptransfer {
 446             off_t fbt_offset;       /* IN: offset to start read/write */
 447             size_t fbt_length;      /* IN: number of bytes to transfer */
 448             void *fbt_buffer;       /* IN: buffer to be read/written */
 449         } fbootstraptransfer_t;
 450 .Ed
 451 .Pp
 452 The
 453 .Dv F_LOG2PHYS
 454 command operates on the following structure.
 455 .ne 7v
 456 .Bd -literal
 457         struct log2phys {
 458             u_int32_t   l2p_flags;              /* unused so far */
 459             off_t       l2p_contigbytes;        /* unused so far */
 460             off_t       l2p_devoffset;      /* bytes into device */
 461         };
 462 .Ed
 463 .Sh RETURN VALUES
 464 Upon successful completion, the value returned depends on
 465 .Fa cmd
 466 as follows:
 467 .Bl -tag -width F_GETOWNX -offset indent
 468 .It Dv F_DUPFD
 469 A new file descriptor.
 470 .It Dv F_GETFD
 471 Value of flag (only the low-order bit is defined).
 472 .It Dv F_GETFL
 473 Value of flags.
 474 .It Dv F_GETOWN
 475 Value of file descriptor owner.
 476 .It other
 477 Value other than -1.
 478 .El
 479 .Pp
 480 Otherwise, a value of -1 is returned and
 481 .Va errno
 482 is set to indicate the error.
 483 .Sh ERRORS
 484 The
 485 .Fn fcntl
 486 system call will fail if:
 487 .Bl -tag -width Er
 488 .\" ==========
 489 .It Bq Er EACCES
 490 The argument
 491 .Fa cmd
 492 is
 493 .Dv F_SETLK ,
 494 the type of lock
 495 .Fa (l_type)
 496 is a shared lock
 497 .Dv (F_RDLCK)
 498 or exclusive lock
 499 .Dv (F_WRLCK) ,
 500 and the segment of a file to be locked is already
 501 exclusive-locked by another process;
 502 or the type is an exclusive lock and some portion of the
 503 segment of a file to be locked is already shared-locked or
 504 exclusive-locked by another process.
 505 .Pp
 506 The argument
 507 .Fa cmd
 508 is either
 509 .Dv F_SETSIZE
 510 or
 511 .Dv F_WRITEBOOTSTRAP
 512 and the calling process does not have root privileges.
 513 .\" ==========
 514 .It Bq Er EBADF
 515 .Fa Fildes
 516 is not a valid open file descriptor.
 517 .Pp
 518 The argument
 519 .Fa cmd
 520 is
 521 .Dv F_SETLK
 522 or
 523 .Dv F_SETLKW ,
 524 the type of lock
 525 .Fa (l_type)
 526 is a shared lock
 527 .Dv (F_RDLCK) ,
 528 and
 529 .Fa fildes
 530 is not a valid file descriptor open for reading.
 531 .Pp
 532 The argument
 533 .Fa cmd
 534 is
 535 .Dv F_SETLK
 536 or
 537 .Dv F_SETLKW ,
 538 the type of lock
 539 .Fa (l_type)
 540 is an exclusive lock
 541 .Dv (F_WRLCK) ,
 542 and
 543 .Fa fildes
 544 is not a valid file descriptor open for writing.
 545 .Pp
 546 The argument
 547 .Fa cmd
 548 is
 549 .Dv F_PREALLOCATE
 550 and the calling process does not have
 551 file write permission.
 552 .Pp
 553 The argument
 554 .Fa cmd
 555 is
 556 .Dv F_LOG2PHYS
 557 and
 558 .Fa fildes
 559 is not a valid file descriptor open for reading.
 560 .\" ==========
 561 .It Bq Er EDEADLK
 562 The argument
 563 .Fa cmd
 564 is
 565 .Dv F_SETLKW ,
 566 and a deadlock condition was detected.
 567 .\" ==========
 568 .It Bq Er EINTR
 569 The argument
 570 .Fa cmd
 571 is
 572 .Dv F_SETLKW ,
 573 and the function was interrupted by a signal.
 574 .\" ==========
 575 .It Bq Er EINVAL
 576 .Fa Cmd
 577 is
 578 .Dv F_DUPFD
 579 and
 580 .Fa arg
 581 is negative or greater than the maximum allowable number
 582 (see
 583 .Xr getdtablesize 2 ) .
 584 .Pp
 585 The argument
 586 .Fa cmd
 587 is
 588 .Dv F_GETLK ,
 589 .Dv F_SETLK ,
 590 or
 591 .Dv F_SETLKW
 592 and the data to which
 593 .Fa arg
 594 points is not valid, or
 595 .Fa fildes
 596 refers to a file that does not support locking.
 597 .Pp
 598 The argument
 599 .Fa cmd
 600 is
 601 .Dv F_PREALLOCATE
 602 and the
 603 .Fa fst_posmode
 604 is not a valid mode,
 605 or when
 606 .Dv F_PEOFPOSMODE
 607 is set and
 608 .Fa fst_offset
 609 is a non-zero value,
 610 or when
 611 .Dv F_VOLPOSMODE
 612 is set and
 613 .Fa fst_offset
 614 is a negative or zero value.
 615 .Pp
 616 The argument
 617 .Fa cmd
 618 is either
 619 .Dv F_READBOOTSTRAP
 620 or
 621 .Dv F_WRITEBOOTSTRAP
 622 and the operation was attempted on a non-HFS disk type.
 623 .\" ==========
 624 .It Bq Er EMFILE
 625 .Fa Cmd
 626 is
 627 .Dv F_DUPFD
 628 and the maximum allowed number of file descriptors are currently
 629 open.
 630 .\" ==========
 631 .It Bq Er EMFILE
 632 The argument
 633 .Fa cmd
 634 is
 635 .Dv F_DUPED
 636 and the maximum number of file descriptors permitted for the
 637 process are already in use,
 638 or no file descriptors greater than or equal to
 639 .Fa arg
 640 are available.
 641 .\" ==========
 642 .It Bq Er ENOLCK
 643 The argument
 644 .Fa cmd
 645 is
 646 .Dv F_SETLK
 647 or
 648 .Dv F_SETLKW ,
 649 and satisfying the lock or unlock request would result in the
 650 number of locked regions in the system exceeding a system-imposed limit.
 651 .\" ==========
 652 .It Bq Er EOVERFLOW
 653 A return value would overflow its representation.
 654 For example,
 655 .Fa cmd
 656 is F_GETLK, F_SETLK, or F_SETLKW
 657 and the smallest (or, if l_len is non-zero, the largest) offset
 658 of a byte in the requested segment
 659 will not fit in an object of type off_t.
 660 .\" ==========
 661 .It Bq Er ESRCH
 662 .Fa Cmd
 663 is
 664 .Dv F_SETOWN
 665 and
 666 the process ID given as argument is not in use.
 667 .El
 668 .Sh SEE ALSO
 669 .Xr close 2 ,
 670 .Xr execve 2 ,
 671 .Xr flock 2 ,
 672 .Xr getdtablesize 2 ,
 673 .Xr open 2 ,
 674 .Xr sigaction 3
 675 .Sh HISTORY
 676 The
 677 .Fn fcntl
 678 function call appeared in
 679 .Bx 4.2 .