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

FreeBSD Manual Pages


home | help
runlock(8)			   runtools			    runlock(8)

       runlock - run another program with a lockfile

       runlock [-bpx] lockfile program [ args ...  ]
       runlock -c [-q] lockfile
       runlock -V | -h

       runlock	may  be	 used  to run a	program	with a lockfile, or to check a
       lockfile	for the	presence of an existing	lock.

       In the first form of the	command, lockfile is a filename	and program is
       an executable program.  runlock opens lockfile for writing (creating it
       if it does not exist), obtains an exclusive posix advisory lock	on  it
       (see fcntl(2)), and then	runs program with any remaining	arguments.

       If the specified	program	name does not contain a	``/'' slash character,
       runlock will search for the executable in the search  path  defined  in
       the environment by the PATH variable.

       As long as program does not itself explicitly release the lock or close
       the descriptor for lockfile, the	lock will remain until the program ex-
       its.   Cooperative  programs  may  test	for the	existence of a lock on
       lockfile	to limit the execution of program to a single instance.

       In the second form of the command (with the -c  option),	 runlock  will
       check  lockfile	for  an	 existing lock.	 If lockfile exists and	can be
       opened for writing, runlock will	report the pid of  the	process	 which
       holds  a	 lock  on the file.  Note that the usefulness of this check is
       limited.	 A lock	on lockfile may	be acquired  or	 released  by  another
       process at anytime.

       -b     Blocking.	  Normally  runlock  exits immediately without running
	      program if an existing lock is found on lockfile.	 When  the  -b
	      option is	specified, runlock waits (blocks) to run program until
	      it can acquire a lock on lockfile.

       -c     Check mode.  If this option is specified,	runlock	 checks	 lock-
	      file for the existence of	a lock.	 runlock exits 0 if no lock is
	      found, exits 1 if	an existing lock is  held,  or	exits  111  if
	      there is a problem with lockfile.

       -h     Help.  Print a brief usage message to stderr and exit.

       -p     Pid.   Normally  runlock creates a zero-length lockfile.	If the
	      -p option	is specified, runlock writes a human-readable  process
	      ID number	into the lockfile.

       -q     Quiet.   In  check  mode,	 the -q	option suppresses the messages
	      normally printed to stderr.

       -V     Version.	Print the version number to stderr and exit.

       -x     Exit no-error.  Normally runlock	prints	an  error  message  to
	      stderr  and  exits nonzero if lockfile cannot be opened (or cre-
	      ated) or locked.	If the -x option is specified, runlock quietly
	      exits zero on these errors.

       runlock exits with one of the following values:

       0      program  was  invoked and	completed successfully.	 In this case,
	      the exit code is returned	by the program,	rather than by runlock

       100    runlock failed because of	a usage	error, such as an invalid com-
	      mand-line	option or argument.  In	this case,  runlock  prints  a
	      brief error message and usage help to stderr on exit.

       111    runlock  failed to acquire a lock	due to some system or resource
	      error, or	because	a lock was already found on lockfile (when not
	      using  the -b option).  In this case, runlock prints a brief di-
	      agnostic message to stderr on exit.

       1-127  program was invoked and failed with its own non-zero  exit  sta-

       Wayne Marshall,

       runtools_intro(8),  runargs(8), runargv0(8), runchoom(8), rundetach(8),
       rundeux(8),   runenv(8),	   runfile(8),	  runlimit(8),	  runpause(8),
       runsession(8), runtool(8), runtrap(8), runuid(8)

runtools-2.07			 January 2013			    runlock(8)


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

home | help