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

FreeBSD Manual Pages


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

       dotlockfile - Utility to	manage lockfiles

       dotlockfile -l [-r retries] [-i interval] [-p] [-q] <-m | lockfile>
       dotlockfile  -l	[-r  retries]  [-i interval] [-p] [-q] <-m | lockfile>
       [-P] cmd	args ...
       dotlockfile -u |	-t

       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	:).

       -l     Create  a	 lockfile  if  no preexisting valid lockfile is	found,
	      else wait	and retry according to option -r.  Retry interval  can
	      be  explicitly  set with option -i.  This	option (-l) is the de-
	      fault, 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 unless over-
	      ridden by	-i.  The default number	of retries is 5.  To try  only
	      once, use	"-r 0".	 To try	indefinitely, use "-r -1".

       -i interval
	      Sets a consistent	retry interval.

       -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

       -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.

       -q     Don't  print  warnings  or  errors to the	standard error output.
	      Used internally by liblockfile when it spawns dotlockfile	 as  a
	      helper program.

       -P     On  successful  "lock and	spawn command",	don't exit with	status
	      zero, but	pass through the exit value of the spawned command.

	      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.

       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.

       Unless  the -P option was supplied, when	a command is executed, the re-
       turn value does not correspond with that	of the command that  was  run.
       If locking and unlocking	was successful,	the exit status	is zero.

       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.

       None known.

       lockfile_create(3), maillock(3)

       Miquel van Smoorenburg

			       January 10, 2017			DOTLOCKFILE(1)


Want to link to this manual page? Use this URL:

home | help