1 '\" t
   2 .\" Copyright (C) 2008 Paul Armstrong. 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 .\"
  13 .\"  THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\"  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\"  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\"  ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\"  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\"  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\"  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\"  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\"  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\"  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\"  SUCH DAMAGE.
  24 
  25 .TH lockf 1 "2008 Apr 08" "SunOS 5.11" "User Commands"
  26 .SH NAME
  27 lockf \- create, test or destroy file locks
  28 .SH SYNOPSIS
  29 .LP
  30 .nf
  31 \fBlockf\fR [[\fI-l|-t|-w\fR] \fI-f /path/to/lock\fR\fB] | [\fR \fI-u pid\fR]
  32 .fi
  33 
  34 .SH DESCRIPTION
  35 .sp
  36 .LP
  37 The \fBlockf\fR utility creates a lock file and then attempts to lock it using
  38 lockf(3C) so it is NFS safe and then returns the pid of the lock handler
  39 process. \fBlockf\fR also checks periodically to ensure that the calling
  40 process still exists and exits if it does not.
  41 
  42 .SH OPTIONS
  43 .sp
  44 .LP
  45 The following options are supported:
  46 
  47 .sp
  48 .ne 2
  49 .mk
  50 .na
  51 \fB\fB-f\fR file\fR
  52 .ad
  53 .RS 10n
  54 .rt  
  55 The file to be used for locking. If it exists already, you need to have write
  56 permissions to the file.  \fBlockf\fR chdir's to / so file \fImust\fR be fully
  57 pathed. The file will be removed when the lock is removed if it did not exist
  58 prior to being created by \fBlockf\fR and left otherwise.
  59 .RE
  60 
  61 .sp
  62 .ne 2
  63 .mk
  64 .na
  65 \fB\fB-l\fR\fR
  66 .ad
  67 .RS 10n
  68 .rt  
  69 Lock the file specified with the \fB-f\fR argument. Fails if a lock already
  70 exists.
  71 .RE
  72 
  73 .sp
  74 .ne 2
  75 .mk
  76 .na
  77 \fB\fB-t\fR\fR
  78 .ad
  79 .RS 10n
  80 .rt  
  81 Test for the existance of a lock on the file specified with \fB-f\fR.
  82 .RE
  83 
  84 .sp
  85 .ne 2
  86 .mk
  87 .na
  88 \fB\fB-u\fR pid\fR
  89 .ad
  90 .RS 10n
  91 .rt  
  92 Kill the lock process at \fBpid\fR (unlocks the file).
  93 .RE
  94 
  95 .sp
  96 .ne 2
  97 .mk
  98 .na
  99 \fB\fB-w\fR\fR
 100 .ad
 101 .RS 10n
 102 .rt  
 103 Lock the file specified with the \fB-f\fR argument. Waits if a lock already
 104 exists and returns when a lock is gained.
 105 .RE
 106 
 107 .bp
 108 
 109 .SH EXAMPLES
 110 
 111 .LP
 112 \fBExample 1:\fR Creating a lock file, entering the critical section and then
 113 removing the lock.
 114 .sp
 115 .LP
 116 
 117 .sp
 118 .in +2
 119 .nf
 120 LOCK_PID="`lockf -l -f ${LOCK_DIR}/lock_file`"
 121 if [ -z "${LOCK_PID}" ]; then
 122   echo "Failed to create lock" >&2
 123 else
 124   critical_section
 125   lockf -u "${LOCK_PID}"
 126 fi
 127 
 128 .fi
 129 .in -2
 130 .sp
 131 
 132 .LP
 133 \fBExample 2:\fR Testing for a lock on a file
 134 .sp
 135 
 136 .sp
 137 .in +2
 138 .nf
 139 example% \fBlockf -t -f ${PWD}/lock_file\fR
 140 .fi
 141 .in -2
 142 .sp
 143 
 144 .LP
 145 \fBExample 3:\fR Waiting until a lock can be created
 146 .sp
 147 
 148 .sp
 149 .in +2
 150 .nf
 151 example% \fBlockf -w -f ${PWD}/lock_file\fR
 152 .fi
 153 .in -2
 154 .sp
 155 
 156 
 157 .SH ENVIRONMENT VARIABLES
 158 .sp
 159 .LP
 160 See \fBenviron\fR(5) for descriptions of the following environment variables
 161 that affect the execution of \fBrealpath\fR: \fBLANG\fR, \fBLC_ALL\fR,
 162 \fBLC_CTYPE\fR,  \fBLC_MESSAGES\fR,  and \fBNLSPATH\fR.
 163 .SH EXIT STATUS
 164 .sp
 165 .LP
 166 \fBlockf\fR returns 0 if a lock is successfully created, or in the case of a
 167 test if no lock exists. It returns 1 if an error occurs, or a lock file exists
 168 and either a lock or test is being attempted.
 169 .sp
 170 
 171 .SH ATTRIBUTES
 172 .sp
 173 .LP
 174 See \fBattributes\fR(5) for descriptions of the following attributes:
 175 .sp
 176 
 177 .sp
 178 .TS
 179 tab() box;
 180 cw(2.75i) |cw(2.75i) 
 181 lw(2.75i) |lw(2.75i) 
 182 .
 183 ATTRIBUTE TYPEATTRIBUTE VALUE
 184 _
 185 AvailabilitySUNWesu
 186 .TE
 187 
 188 .SH SEE ALSO
 189 .sp
 190 .LP
 191 \fBlockf\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5)
 192 .SH NOTES
 193 .sp
 194 .LP
 195 \fBlockf\fR can not be called by init as the case of the parent being init is
 196 used to check if the original caller died during process start up.
 197 .sp
 198 .LP
 199 While you can use existing files, other processes calling \fBlockf\fR(3C) or
 200 \fBfcntl\fR(3C) may interfere with the proper operation of \fBlockf\fR(1).
 201 .sp
 202 .LP
 203 \fBlockf\fR will wait indefinitely when called with \fI-w\fR so you may
 204 consider using \fBalarm\fR(1) to kill it after some reasonable amount of time.