share/man/man3c/flock.3c

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 1989 AT&T
  13 .\" Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
  14 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
  15 .\" Copyright 2015 Joyent, Inc.
  16 .\"
  17 .TH FLOCK 3C "Feb 16, 2015"
  18 .SH NAME
  19 flock \- OFD(open file description)-style file locking
  20 .SH SYNOPSIS
  21 .LP
  22 .nf
  23 #include <sys/file.h>
  24
  25 \fBint\fR \fBflock\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIoperation\fR);
  26 .fi
  27
  28 .SH DESCRIPTION
  29 .LP
  30 The \fBflock()\fR function allows advisory locks to be applied to and removed
  31 from a file. Calls to \fBflock()\fR from callers that attempt to lock
  32 the locked file section via a different open file handle will either return an
  33 error value or be put to sleep until the resource becomes unlocked.
  34 See \fBfcntl\fR(2) for more information about record locking. Locks created or
  35 removed via this function will apply to the entire file, including any future
  36 growth in the file's length.
  37 .sp
  38 .LP
  39 The \fIfildes\fR argument is an open file descriptor. A lock can be established
  40 without regard for the mode with which the file was opened.
  41 .sp
  42 .LP
  43 The \fIoperation\fR argument is a control value that specifies the action to be
  44 taken. The permissible values for \fIoperation\fR are defined in
  45 <\fBsys/file.h\fR> as follows:
  46 .sp
  47 .in +2
  48 .nf
  49 #define   LOCK_SH   1   /* shared file lock */
  50 #define   LOCK_EX   2   /* exclusive file lock */
  51 #define   LOCK_NB   4   /* do not block when attempting to create lock */
  52 #define   LOCK_UN   8   /* remove existing file lock */
  53 .fi
  54 .in -2
  55
  56 .sp
  57 .LP
  58 To create a lock, either \fBLOCK_SH\fR or \fBLOCK_EX\fR should be specified,
  59 optionally bitwise-ored with \fBLOCK_NB\fR.  To remove a lock, \fBLOCK_UN\fR
  60 should be specified. All other values of \fIoperation\fR are reserved for
  61 future extensions and will result in an error if not implemented.
  62 .sp
  63 .LP
  64 This function creates, upgrades, downgrades, or removes either shared or
  65 exclusive OFD-style locks. Locks created by this function are owned by open
  66 files, not file descriptors. That is, file descriptors duplicated through
  67 \fBdup\fR(2), \fBfork\fR(2), or \fBfcntl\fR(2) do not result in multiple
  68 instances of a lock, but rather multiple references to the same lock. If a
  69 process holding a lock on a file forks and the child explicitly unlocks the
  70 file, the parent will lose its lock.  See \fBfcntl\fR(2) for more information
  71 about file locking and the interaction between locks created by this function
  72 and those created by other mechanisms. These locks are currently not supported
  73 over remote file systems (e.g. \fBnfs\fR(4)) which use the Network Lock
  74 Manager.
  75 .sp
  76 .LP
  77 Sleeping on a resource is interrupted with any signal. The \fBalarm\fR(2)
  78 function may be used to provide a timeout facility in applications that require
  79 this facility.
  80 .SH RETURN VALUES
  81 .LP
  82 Upon successful completion, \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
  83 returned and \fBerrno\fR is set to indicate the error.
  84 .SH ERRORS
  85 .LP
  86 The \fBflock()\fR function will fail if:
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBEBADF\fR\fR
  91 .ad
  92 .RS 20n
  93 The \fIfildes\fR argument is not a valid open file descriptor; or
  94 \fIoperation\fR contains \fBLOCK_SH\fR and \fIfiledes\fR is not open for
  95 reading; or \fIoperation\fR contains \fBLOCK_EX\fR and \fIfiledes\fR is not
  96 open for writing.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBEWOULDBLOCK\fR\fR
 103 .ad
 104 .RS 20n
 105 The \fIoperation\fR argument contains \fBLOCK_NB\fR and a conflicting lock
 106 exists.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBEINTR\fR\fR
 113 .ad
 114 .RS 20n
 115 A signal was caught during execution of the function.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBEINVAL\fR\fR
 122 .ad
 123 .RS 20n
 124 The \fIoperation\fR argument does not contain one of \fBLOCK_SH\fR,
 125 \fBLOCK_EX\fR, or \fBLOCK_UN\fR; or the \fIoperation\fR argument contains
 126 \fBLOCK_UN\fR and \fBLOCK_NB\fR; or the \fIoperation\fR argument contains
 127 any bits other than those set by \fBLOCK_SH\fR, \fBLOCK_EX\fR, \fBLOCK_NB\fR,
 128 and \fBLOCK_UN\fR.
 129 .RE
 130
 131 .sp
 132 .LP
 133 The \fBflock()\fR function may fail if:
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBEAGAIN\fR\fR
 138 .ad
 139 .RS 24n
 140 The \fIoperation\fR argument contains \fBLOCK_SH\fR or \fBLOCK_EX\fR and the
 141 file is mapped with \fBmmap\fR(2).
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBENOLCK\fR\fR
 148 .ad
 149 .RS 20n
 150 The number of locked file regions in the system would exceed a system-imposed
 151 limit.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBEOPNOTSUPP\fR
 158 .ad
 159 .RS 24n
 160 The locking of files of the type indicated by the \fIfildes\fR argument is not
 161 supported.
 162 .RE
 163
 164 .SH USAGE
 165 .LP
 166 File-locking should not be used in combination with the \fBfopen\fR(3C),
 167 \fBfread\fR(3C), \fBfwrite\fR(3C) and other \fBstdio\fR functions.  Instead,
 168 the more primitive, non-buffered functions (such as \fBopen\fR(2)) should be
 169 used.  Unexpected results may occur in processes that do buffering in the user
 170 address space.  The process may later read/write data which is/was locked.  The
 171 \fBstdio\fR functions are the most common source of unexpected buffering.
 172 .sp
 173 .LP
 174 The \fBalarm\fR(2) function may be used to provide a timeout facility in
 175 applications requiring it.
 176 .sp
 177 .LP
 178 Locks created by this facility conflict with those created by the
 179 \fBlockf\fR(3C) and \fBfcntl\fR(2) facilities.  This facility creates and
 180 removed OFD-style locks; see \fBfcntl\fR(2) for information about the
 181 interaction between OFD-style and POSIX-style file locks.
 182 .SH ATTRIBUTES
 183 .LP
 184 See \fBattributes\fR(5) for descriptions of the following attributes:
 185 .sp
 186
 187 .sp
 188 .TS
 189 box;
 190 c | c
 191 l | l .
 192 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 193 _
 194 Interface Stability     Standard
 195 _
 196 MT-Level        MT-Safe
 197 .TE
 198
 199 .SH SEE ALSO
 200 .LP
 201 \fBIntro\fR(2), \fBalarm\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2),
 202 \fBfcntl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2),
 203 \fBattributes\fR(5), \fBstandards\fR(5)