[BACK]Return to pidlock.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libutil

Annotation of src/lib/libutil/pidlock.3, Revision 1.3

1.3     ! lukem       1: .\"    $NetBSD: pidlock.3,v 1.2 1998/02/05 18:52:28 perry Exp $
1.1       cjs         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
1.2       perry      31: .Sh LIBRARY
                     32: .Lb libutil
1.1       cjs        33: .Sh SYNOPSIS
                     34: .Fd #include <util.h>
                     35: .Ft int
                     36: .Fn pidlock "const char *lockfile" "int flags" "pid_t *locker" "const char *info"
                     37: .Ft int
                     38: .Fn ttylock "const char *tty" "int flags" "pid_t *locker"
                     39: .Ft int
                     40: .Fn ttyunlock "const char *tty"
                     41: .Sh DESCRIPTION
                     42: The
                     43: .Fn pidlock
                     44: .Fn ttylock ,
                     45: and
                     46: .Fn ttyunlock
                     47: functions attempt to create a lockfile for an arbitrary resource that
                     48: only one program may hold at a time.  (In the case of
                     49: .Fn ttylock ,
                     50: this is access to a tty device.) If the
                     51: function succeeds in creating the lockfile, it will succeed for
                     52: no other program calling it with the same lockfile until the original
                     53: calling program has removed the lockfile or exited.  The
                     54: .Fn ttyunlock
                     55: function will remove the lockfile created by
                     56: .Fn ttylock .
                     57: .Pp
                     58: These functions use the method of creating a lockfile traditionally
                     59: used by UUCP software.  This is described as follows in the
                     60: documentation for Taylor UUCP:
                     61: .Bd -filled -offset indent
                     62: The lock file normally contains the process ID of the locking
                     63: process.  This makes it easy to determine whether a lock is still
                     64: valid.  The algorithm is to create a temporary file and then link
                     65: it to the name that must be locked.  If the link fails because a
                     66: file with that name already exists, the existing file is read to
                     67: get the process ID.  If the process still exists, the lock attempt
                     68: fails.  Otherwise the lock file is deleted and the locking algorithm
                     69: is retried.
                     70: .Ed
                     71: .Pp
                     72: The PID is stored in ASCII format, with leading spaces to pad it
                     73: out to ten characters, and a terminating newline.  This
                     74: implementation has been extended to put the hostname
                     75: on the second line of the file, terminated with a newline, and
                     76: optionally an arbitrary comment on the third line of the file, also
                     77: terminated with a newline. If a comment is given, but
                     78: .Dv PIDLOCK_NONBLOCK
                     79: is not, a blank line will be written as the second line of the file.
                     80: .Pp
                     81: The
                     82: .Fn pidlock
                     83: function will attempt to create the file
                     84: .Fa lockfile
                     85: and put the current process's pid in it. The
                     86: .Fn ttylock
                     87: function will do the same, but should be passed only the base name
                     88: (with no leading directory prefix) of the tty to be locked; it will
                     89: test that the tty exists in
                     90: .Pa /dev
                     91: and is a character device, and then create
                     92: the file in the
                     93: .Pa /var/spool/lock
                     94: directory and prefix the filename with
                     95: .Pa LCK.. .
                     96: Use the
                     97: .Fn ttyunlock
                     98: function to remove this lock.
                     99: .Pp
                    100: The following flags may be passed in
                    101: .Pa flags :
                    102: .Bl -tag -width Dv -offset indent
                    103: .It Dv PIDLOCK_NONBLOCK
                    104: The function should return immediately when a lock is held by another
                    105: active process.  Otherwise the function will wait (forever, if necessary)
                    106: for the lock to be freed.
                    107: .It Dv PIDLOCK_USEHOSTNAME
                    108: The hostname should be compared against the hostname in the second
                    109: line of the file (if present), and if they differ, no attempt at
                    110: checking for a living process holding the lock will be made, and
                    111: the lockfile will never be deleted.  (The process is assumed to be
                    112: alive.)  This is used for locking on NFS or other remote filesystems.
                    113: (The function will never create a lock if
                    114: .Dv PIDLOCK_USEHOSTNAME
                    115: is specified and no hostname is present.)
                    116: .El
                    117: .Pp
                    118: If
                    119: .Pa locker
                    120: is non-null, it will contain the PID of the locking process, if there
                    121: is one, on return.
                    122: .Pp
                    123: If
                    124: .Pa info
                    125: is non-null and the lock succeeds, the string it points to will be
                    126: written as the third line of the lock file.
                    127: .Sh RETURN VALUES
                    128: Zero is returned if the operation was successful; on an error a -1
                    129: is returned and a standard error code is left in the global location errno.
                    130: .Sh ERRORS
                    131: These are among the values left in
                    132: .Va errno
                    133: if
                    134: .Fn pidlock
                    135: or
                    136: .Fn ttylock
                    137: returns a failure:
                    138: .Bl -tag -width Er
                    139: .It Bq Er EPERM
                    140: The current process does not have some of the privileges necessary
                    141: to perform the lock. These include read and write access to the lock
                    142: directory, and read access to the current lockfile, if it exists.
                    143: .It Bq Er ENOENT
                    144: A component of a specified pathname did not exist, or the pathname
                    145: was an empty string.
                    146: .It Bq Er EWOULBLOCK
                    147: Another runnning process has a lock and the
                    148: .Dv PIDLOCK_NONBLOCK
                    149: flag was specified.
                    150: .It Bq Er ENAMETOOLONG
                    151: A component of the path name exceeded 255 (MAXNAMELEN) characters,
                    152: or an entire path name exceeded 1023 (MAXPATHLEN-1) characters.
                    153: .El
                    154: .\" .Sh SEE ALSO
                    155: .Sh HISTORY
                    156: The
                    157: .Fn pidlock
                    158: and
                    159: .Fn ttylock
                    160: functions appeared in
                    161: .Nx 1.3 .
                    162: .Sh AUTHORS
                    163: Curt Sampson <cjs@netbsd.org>
                    164: .Sh BUGS
                    165: The lockfile format breaks if a pid is longer than ten digits when
                    166: printed in decimal form.
                    167: .Pp
                    168: The PID returned will be the pid of the locker on the remote machine if
                    169: .Dv PIDLOCK_USEHOSTNAME
                    170: is specified, but there is no indication that this is not on the local
                    171: machine.

CVSweb <webmaster@jp.NetBSD.org>