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