lib/libutil/flopen.3

   1 .\"-
   2 .\" Copyright (c) 2007 Dag-Erling Coïdan Smørgrav
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd July 28, 2017
  29 .Dt FLOPEN 3
  30 .Os
  31 .Sh NAME
  32 .Nm flopen ,
  33 .Nm flopenat
  34 .Nd "Reliably open and lock a file"
  35 .Sh LIBRARY
  36 .Lb libutil
  37 .Sh SYNOPSIS
  38 .In sys/fcntl.h
  39 .In libutil.h
  40 .Ft int
  41 .Fn flopen "const char *path" "int flags"
  42 .Ft int
  43 .Fn flopen "const char *path" "int flags" "mode_t mode"
  44 .Ft int
  45 .Fn flopenat "int fd" "const char *path" "int flags"
  46 .Ft int
  47 .Fn flopenat "int fd" "const char *path" "int flags" "mode_t mode"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn flopen
  51 function opens or creates a file and acquires an exclusive lock on it.
  52 It is essentially equivalent with calling
  53 .Fn open
  54 with the same parameters followed by
  55 .Fn flock
  56 with an
  57 .Fa operation
  58 argument of
  59 .Dv LOCK_EX ,
  60 except that
  61 .Fn flopen
  62 will attempt to detect and handle races that may occur between opening
  63 / creating the file and locking it.
  64 Thus, it is well suited for opening lock files, PID files, spool
  65 files, mailboxes and other kinds of files which are used for
  66 synchronization between processes.
  67 .Pp
  68 If
  69 .Fa flags
  70 includes
  71 .Dv O_NONBLOCK
  72 and the file is already locked,
  73 .Fn flopen
  74 will fail and set
  75 .Va errno
  76 to
  77 .Dv EWOULDBLOCK .
  78 .Pp
  79 As with
  80 .Fn open ,
  81 the additional
  82 .Fa mode
  83 argument is required if
  84 .Fa flags
  85 includes
  86 .Dv O_CREAT .
  87 .Pp
  88 The
  89 .Fn flopenat
  90 function is equivalent to the
  91 .Fn flopen
  92 function except in the case where the
  93 .Fa path
  94 specifies a relative path.
  95 In this case the file to be opened is determined relative to the directory
  96 associated with the file descriptor
  97 .Fa fd
  98 instead of the current working directory.
  99 If
 100 .Fn flopenat
 101 is passed the special value
 102 .Dv AT_FDCWD
 103 in the
 104 .Fa fd
 105 parameter, the current working directory is used
 106 and the behavior is identical to a call to
 107 .Fn flopen .
 108 .Sh RETURN VALUES
 109 If successful,
 110 .Fn flopen
 111 returns a valid file descriptor.
 112 Otherwise, it returns -1, and sets
 113 .Va errno
 114 as described in
 115 .Xr flock 2
 116 and
 117 .Xr open 2 .
 118 .Sh SEE ALSO
 119 .Xr errno 2 ,
 120 .Xr flock 2 ,
 121 .Xr open 2
 122 .Sh AUTHORS
 123 .An -nosplit
 124 The
 125 .Nm
 126 function and this manual page were written by
 127 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .