You'll pardon my asking something obvious and stupid, but...

Why are we doing stuff like using user space locks? Aren't things like
O_EXCL or flock more sensible in the modern world? I know I must be
missing something...

Perry

Curt Sampson writes:
> 
> Ok. Appended is my first go at a manual page for pidlock() and
> uucplock(). If anyone notices anything that should be changed in
> my mandoc macro calls, as well as in the content of the page itself,
> don't hesitate to let me know. (It's my first manual page in about
> five years.)
> 
> cjs
> 
> Curt Sampson    cjs@portal.ca		Info at http://www.portal.ca/
> Internet Portal Services, Inc.	
> Vancouver, BC   (604) 257-9400		De gustibus, aut bene aut nihil
.
> 
> .\" $Id: pidlock.3,v 1.1 1996/11/11 06:39:44 cjs Exp cjs $
> .Dd November 10, 1996
> .Os
> .Dt PIDLOCK 3
> .Sh NAME
> .Nm pidlock ,
> .Nm uucplock
> .Nd locks based on files containing PIDs
> .Sh SYNOPSIS
> .Fd #include <util.h>
> .Ft int
> .Fn pidlock "const char *lockfile" "int flags" "pid_t *locker"
> .Ft int
> .Fn uucplock "const char *tty" "int flags" "pid_t *locker"
> .Sh DESCRIPTION
> The
> .Fn pidlock
> and
> .Fn uucplock
> functions attempt to create a lockfile for an arbitrary resource that
> only one program may hold at a time.  (In the case of
> .Fn uucplock ,
> this is by convention access to a tty device.) If the
> function succeeds in creating the lockfile, it will succeed for
> no other program using it with the same lockfile until the original
> calling program has removed the lockfile or exited.
> .Pp
> These functions use the method of creating a lockfile traditionally
> used by UUCP software.  This is described as follows in the
> documentation for Taylor UUCP:
> .Bd -filled -offset indent
> The lock file normally contains the process ID of the locking
> process.  This makes it easy to determine whether a lock is still
> valid.  The algorithm is to create a temporary file and then link
> it to the name that must be locked.  If the link fails because a
> file with that name already exists, the existing file is read to
> get the process ID.  If the process still exists, the lock attempt
> fails.  Otherwise the lock file is deleted and the locking algorithm
> is retried.
> .Ed
> .Pp
> .Pp
> The PID is stored in ASCII format, with leading spaces to pad it
> out to ten characters, and a terminating newline.
> .Pp
> The
> .Fn pidlock
> function will attempt to create the file
> .Fa lockfile
> and put the current process's pid in it. The
> .Fn uucplock
> function will do the same, but should be passed only the base name
> (with no leading directory prefix) of the tty to be locked; it will
> create the file in the
> .Pa /var/spool/lock
> directory and prefix the filename with
> .Pa LCK.. .
> .Pp
> If the function should return immediately when a lock is held by another
> active process, it should be passed
> .Dv PIDLOCK_NONBLOCK
> in
> .Pa flags ,
> otherwise
> .Pa flags
> should be 0.
> .Pp
> If
> .Pa locker
> is non-null, it will contain the PID of the locking process on
> return.  (This will be the current process's PID if no process
> already holds the lock.)
> .Pp
> The
> .Fn uucplock
> function will
> .Fn chown
> the lockfile to the
> .Em uucp
> user if the process is currently running as root.
> .Sh RETURN VALUES
> Zero is returned if the operation was successful; on an error a -1
> is returned and a standard error code is left in the global location errno.
> .Sh ERRORS
> These are among the values left in
> .Va errno
> if
> .Fn pidlock
> or
> .Fn uucplock
> returns a failure:
> .Bl -tag -width Er
> .It Bq Er EPERM
> The current process does not have some of the privileges necessary
> to perform the lock. These include read and write access to the lock
> directory, and read access to the current lockfile, if it exists.
> .It Bq Er ENOENT
> A component of a specified pathname did not exist, or the pathname
> was an empty string.
> .It Bq Er EWOULBLOCK
> Another runnning process has a lock and the
> .Dv PIDLOCK_NONBLOCK
> flag was specified.
> .It Bq Er ENAMETOOLONG
> A component of the path name exceeded 255 (MAXNAMELEN) characters,
> or an entire path name exceeded 1023 (MAXPATHLEN-1) characters.
> .Sh SEE ALSO
> .\" .Sh HISTORY
> The
> .Fn pidlock
> and
> .Fn uucplock
> functions appeared in
> .Nx 1.3 .
> .\" .Sh AUTHORS
> .\" .Sh BUGS
> .Pp
>