1.\" $NetBSD: pidlock.3,v 1.1 1997/10/11 02:56:22 cjs Exp $ 2.\" 3.\" Copyright 1996, 1997 by Curt Sampson <cjs@netbsd.org> 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.\" 11.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 12.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 13.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 14.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 15.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 16.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 17.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 18.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 19.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 20.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 21.\" POSSIBILITY OF SUCH DAMAGE. 22.\" 23.Dd November 10, 1996 24.Os 25.Dt PIDLOCK 3 26.Sh NAME 27.Nm pidlock , 28.Nm ttylock , 29.Nm ttyunlock 30.Nd locks based on files containing PIDs 31.Sh SYNOPSIS 32.Fd #include <util.h> 33.Ft int 34.Fn pidlock "const char *lockfile" "int flags" "pid_t *locker" "const char *info" 35.Ft int 36.Fn ttylock "const char *tty" "int flags" "pid_t *locker" 37.Ft int 38.Fn ttyunlock "const char *tty" 39.Sh DESCRIPTION 40The 41.Fn pidlock 42.Fn ttylock , 43and 44.Fn ttyunlock 45functions attempt to create a lockfile for an arbitrary resource that 46only one program may hold at a time. (In the case of 47.Fn ttylock , 48this is access to a tty device.) If the 49function succeeds in creating the lockfile, it will succeed for 50no other program calling it with the same lockfile until the original 51calling program has removed the lockfile or exited. The 52.Fn ttyunlock 53function will remove the lockfile created by 54.Fn ttylock . 55.Pp 56These functions use the method of creating a lockfile traditionally 57used by UUCP software. This is described as follows in the 58documentation for Taylor UUCP: 59.Bd -filled -offset indent 60The lock file normally contains the process ID of the locking 61process. This makes it easy to determine whether a lock is still 62valid. The algorithm is to create a temporary file and then link 63it to the name that must be locked. If the link fails because a 64file with that name already exists, the existing file is read to 65get the process ID. If the process still exists, the lock attempt 66fails. Otherwise the lock file is deleted and the locking algorithm 67is retried. 68.Ed 69.Pp 70The PID is stored in ASCII format, with leading spaces to pad it 71out to ten characters, and a terminating newline. This 72implementation has been extended to put the hostname 73on the second line of the file, terminated with a newline, and 74optionally an arbitrary comment on the third line of the file, also 75terminated with a newline. If a comment is given, but 76.Dv PIDLOCK_NONBLOCK 77is not, a blank line will be written as the second line of the file. 78.Pp 79The 80.Fn pidlock 81function will attempt to create the file 82.Fa lockfile 83and put the current process's pid in it. The 84.Fn ttylock 85function will do the same, but should be passed only the base name 86(with no leading directory prefix) of the tty to be locked; it will 87test that the tty exists in 88.Pa /dev 89and is a character device, and then create 90the file in the 91.Pa /var/spool/lock 92directory and prefix the filename with 93.Pa LCK.. . 94Use the 95.Fn ttyunlock 96function to remove this lock. 97.Pp 98The following flags may be passed in 99.Pa flags : 100.Bl -tag -width Dv -offset indent 101.It Dv PIDLOCK_NONBLOCK 102The function should return immediately when a lock is held by another 103active process. Otherwise the function will wait (forever, if necessary) 104for the lock to be freed. 105.It Dv PIDLOCK_USEHOSTNAME 106The hostname should be compared against the hostname in the second 107line of the file (if present), and if they differ, no attempt at 108checking for a living process holding the lock will be made, and 109the lockfile will never be deleted. (The process is assumed to be 110alive.) This is used for locking on NFS or other remote filesystems. 111(The function will never create a lock if 112.Dv PIDLOCK_USEHOSTNAME 113is specified and no hostname is present.) 114.El 115.Pp 116If 117.Pa locker 118is non-null, it will contain the PID of the locking process, if there 119is one, on return. 120.Pp 121If 122.Pa info 123is non-null and the lock succeeds, the string it points to will be 124written as the third line of the lock file. 125.Sh RETURN VALUES 126Zero is returned if the operation was successful; on an error a -1 127is returned and a standard error code is left in the global location errno. 128.Sh ERRORS 129These are among the values left in 130.Va errno 131if 132.Fn pidlock 133or 134.Fn ttylock 135returns a failure: 136.Bl -tag -width Er 137.It Bq Er EPERM 138The current process does not have some of the privileges necessary 139to perform the lock. These include read and write access to the lock 140directory, and read access to the current lockfile, if it exists. 141.It Bq Er ENOENT 142A component of a specified pathname did not exist, or the pathname 143was an empty string. 144.It Bq Er EWOULBLOCK 145Another runnning process has a lock and the 146.Dv PIDLOCK_NONBLOCK 147flag was specified. 148.It Bq Er ENAMETOOLONG 149A component of the path name exceeded 255 (MAXNAMELEN) characters, 150or an entire path name exceeded 1023 (MAXPATHLEN-1) characters. 151.El 152.\" .Sh SEE ALSO 153.Sh HISTORY 154The 155.Fn pidlock 156and 157.Fn ttylock 158functions appeared in 159.Nx 1.3 . 160.Sh AUTHORS 161Curt Sampson <cjs@netbsd.org> 162.Sh BUGS 163The lockfile format breaks if a pid is longer than ten digits when 164printed in decimal form. 165.Pp 166The PID returned will be the pid of the locker on the remote machine if 167.Dv PIDLOCK_USEHOSTNAME 168is specified, but there is no indication that this is not on the local 169machine. 170.Pp 171