Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DOTLOCKFILE(1)		       Cistron Utilities		DOTLOCKFILE(1)

NAME
       dotlockfile - Utility to	manage lockfiles

SYNOPSIS
       dotlockfile -l [-r retries] [-p]	<-m | lockfile>
       dotlockfile -l [-r retries] [-p]	<-m | lockfile>	cmd args ...
       dotlockfile -u |	-t

DESCRIPTION
       dotlockfile  is a command line utility to reliably create, test and re-
       move lockfiles.	 It  creates  lockfiles	 reliably  on  local  and  NFS
       filesystems,  because  the  crucial  steps of testing for a preexisting
       lockfile	and creating it	are performed atomically by a single  call  to
       link(2).	 Manpage lockfile_create(3) describes the used algorithm.

       dotlockfile  is	installed with attribute SETGID	mail and thus can also
       be used to lock and unlock mailboxes even if the	mailspool directory is
       only writable by	group mail.

       The  name  dotlockfile  comes from the way mailboxes are	locked for up-
       dates on	a lot of UNIX systems.	A lockfile is created  with  the  same
       filename	as the mailbox but with	the string ".lock" appended.

       The names dotlock and lockfile were already taken - hence the name dot-
       lockfile	:).

OPTIONS
       -l     Create a lockfile	if no preexisting  valid  lockfile  is	found,
	      else  wait and retry according to	option -r.  This option	is the
	      default, so it can be left off.

	      A	lockfile is treated as valid,
	      o	 if it holds the process-id of a running process,
	      o	 or if it does not hold	any process-id and  has	 been  touched
	      less than	5 minutes ago (timestamp is younger than 5 minutes).

       -r retries
	      The  number  of times dotlockfile	retries	to acquire the lock if
	      it failed	the first time before giving up.   The	initial	 sleep
	      after  failing  to  acquire  the	lock is	5 seconds.  After each
	      retry the	sleep interval is increased incrementally by 5 seconds
	      up  to a maximum sleep of	60 seconds between tries.  The default
	      number of	retries	is 5.  To try only once, use "-r 0".   To  try
	      indefinitely, use	"-r -1".

       -u     Remove a lockfile.

       -t     Touch  an	 existing lockfile (update the timestamp).  Useful for
	      lockfiles	on NFS filesystems.  For lockfiles on  local  filesys-
	      tems the -p option is preferable.

       -p     Write  the process-id of the calling process (or dotlockfile it-
	      self if a	command	is executed) into  the	lockfile.   Also  when
	      testing  for  an	existing  lockfile, check the contents for the
	      process-id of a running process to verify	 if  the  lockfile  is
	      still  valid.   Obviously	 useful	 only  for  lockfiles on local
	      filesystems.

       -m     Lock or unlock the current users mailbox.	 The path to the mail-
	      box   is	 the   default	system	mailspool  directory  (usually
	      /var/mail) with the username as gotten from getpwuid() appended.
	      If  the environment variable $MAIL is set, that is used instead.
	      Then the string ".lock" is appended to get the name of  the  ac-
	      tual lockfile.

       lockfile
	      The lockfile to be created or removed.  Must not be specified if
	      the -m option is given.

       command argument	...
	      Create lockfile, run the command , wait for it to	exit, and  re-
	      move lockfile.

RETURN VALUE
       Zero  on	 success, and non-zero on failure.  When locking (the default,
       or with the -l option) dotlockfile returns the same values as  the  li-
       brary  function	lockfile_create(3).  Unlocking a non-existent lockfile
       is not an error.

       If a command is executed, the return value  does	 not  correspond  with
       that  of	 the  command  that was	run.  If the locking and unlocking was
       successful, the exit status is always zero.

NOTES
       The lockfile is created exactly as named	on the command line.  The  ex-
       tension ".lock" is not automatically appended.

       This  utility is	a lot like the lockfile(1) utility included with proc-
       mail, and the mutt_dotlock(1) utility included with mutt.  However  the
       command-line  arguments	differ,	 and so	does the return	status.	 It is
       believed, that dotlockfile is the most flexible	implementation,	 since
       it  automatically  detects  when	 it  needs to use privileges to	lock a
       mailbox,	and does it safely.

       The above mentioned lockfile_create(3) manpage is present  in  the  li-
       blockfile-dev package.

BUGS
       None known.

SEE ALSO
       lockfile_create(3), maillock(3)

AUTHOR
       Miquel van Smoorenburg, miquels@cistron.nl

			       January 10, 2017			DOTLOCKFILE(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | RETURN VALUE | NOTES | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dotlockfile&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help