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