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.