man pages section 1: User Commands

Exit Print View

Updated: July 2014

lockfile (1)


lockfile - file creator


lockfile -sleeptime | -r retries |
-l locktimeout | -s suspend | -!  | -ml | -mu | file-
name ...


User Commands                                         LOCKFILE(1)

     lockfile - conditional semaphore-file creator

     lockfile -sleeptime | -r retries |
          -l locktimeout | -s suspend | -!  | -ml | -mu | file-
     name ...

     lockfile can be used to create one or more semaphore  files.
     If  lockfile  can't  create  all the specified files (in the
     specified order), it waits sleeptime (defaults to 8) seconds
     and  retries  the  last  file  that didn't succeed.  You can
     specify the  number  of  retries  to  do  until  failure  is
     returned.   If  the  number of retries is -1 (default, i.e.,
     -r-1) lockfile will retry forever.

     If the number of retries expires before all files have  been
     created,  lockfile returns failure and removes all the files
     it created up till that point.

     Using lockfile as the condition of a loop in a shell  script
     can  be done easily by using the -!  flag to invert the exit
     status.  To prevent infinite loops, failures for any  reason
     other than the lockfile already existing are not inverted to
     success but rather are still returned as failures.

     All flags can be specified anywhere  on  the  command  line,
     they  will  be processed when encountered.  The command line
     is simply parsed from left to right.

     All files created by lockfile will be read-only, and  there-
     fore will have to be removed with rm -f.

     If you specify a locktimeout then a lockfile will be removed
     by force after locktimeout seconds  have  passed  since  the
     lockfile  was  last  modified/created  (most  likely by some
     other program that unexpectedly died a long  time  ago,  and
     hence  could not clean up any leftover lockfiles).  Lockfile
     is clock skew immune.  After a lockfile has been removed  by
     force,  a  suspension of suspend seconds (defaults to 16) is
     taken into account, in  order  to  prevent  the  inadvertent
     immediate  removal  of any newly created lockfile by another
     program (compare SUSPEND in procmail(1)).

BuGless              Last change: 2001/06/23                    1

User Commands                                         LOCKFILE(1)

  Mailbox locks
     If the permissions on the system mail spool directory  allow
     it,  or  if  lockfile is suitably setgid, it will be able to
     lock and unlock your system mailbox by using the options -ml
     and -mu respectively.

     Suppose  you  want  to  make  sure  that  access to the file
     "important" is serialised, i.e., no more than one program or
     shell  script  should be allowed to access it.  For simplic-
     ity's sake, let's suppose that it is  a  shell  script.   In
     this case you could solve it like this:
          lockfile important.lock
          rm -f important.lock
     Now  if  all the scripts that access "important" follow this
     guideline, you will be assured that at most one script  will
     be executing between the `lockfile' and the `rm' commands.

     LOGNAME                used  as  a  hint  to  determine  the
                            invoker's loginname

     /etc/passwd            to   verify   and/or   correct    the
                            invoker's  loginname (and to find out
                            his HOME directory, if needed)

                            lockfile for the system mailbox,  the
                            environment variables present in here
                            will not be taken from  the  environ-
                            ment, but will be determined by look-
                            ing in /etc/passwd

     See  attributes(5)  for  descriptions   of   the   following

     |Availability   | mail/procmail    |
     |Stability      | Uncommitted      |

BuGless              Last change: 2001/06/23                    2

User Commands                                         LOCKFILE(1)

     rm(1), mail(1), binmail(1), sendmail(8), procmail(1)

     Filename too long, ... Use shorter filenames.

     Forced unlock denied on "x"
                            No  write permission in the directory
                            where lockfile "x" resides,  or  more
                            than  one  lockfile trying to force a
                            lock at exactly the same time.

     Forcing lock on "x"    Lockfile "x" is going to  be  removed
                            by  force  because of a timeout (com-
                            pare LOCKTIMEOUT in procmail(1)).

     Out of memory, ...     The system is out of swap space.

     Signal received, ...   Lockfile will remove anything it cre-
                            ated till now and terminate.

     Sorry, ...             The retries limit has been reached.

     Truncating "x" and retrying lock
                            "x" does not seem to be a valid file-

     Try praying, ...       Missing  subdirectories  or  insuffi-
                            cient privileges.

     Definitely less than one.

     The behavior of the -!  flag, while useful, is not necessar-
     ily intuitive or consistent.  When testing lockfile's return
     value,   shell  script  writers  should  consider  carefully
     whether they want to use the -!  flag,  simply  reverse  the
     test, or do a switch on the exact exitcode.  In general, the
     -!  flag should only be used when lockfile is the condition-
     al of a loop.

     Lockfile is NFS-resistant and eight-bit clean.

BuGless              Last change: 2001/06/23                    3

User Commands                                         LOCKFILE(1)

     Calling  up lockfile with the -h or -? options will cause it
     to display a command-line help page.  Calling it up with the
     -v  option will cause it to display its version information.

     Multiple -!  flags will toggle the return status.

     Since flags can occur anywhere  on  the  command  line,  any
     filename starting with a '-' has to be preceded by './'.

     The  number  of retries will not be reset when any following
     file is being created (i.e., they are simply used  up).   It
     can,  however, be reset by specifying -rnewretries after ev-
     ery file on the command line.

     Although files with any name can be used as lockfiles, it is
     common  practice  to use the extension `.lock' to lock mail-
     folders (it is appended to the mailfolder  name).   In  case
     one  does not want to have to worry about too long filenames
     and does not have to conform to any other lockfilename  con-
     vention,  then  an  excellent way to generate a lockfilename
     corresponding to some already existing file is by taking the
     prefix  `lock.'  and appending the i-node number of the file
     which is to be locked.

     This program is part of the procmail mail-processing-package
     (v3.22)  available  at or ftp.proc- in pub/procmail/.

     There exists a mailinglist for  questions  relating  to  any
     program in the procmail package:
               for submitting questions/answers.
               for subscription requests.

     If  you  would  like to stay informed about new versions and
     official patches send a subscription request to

     (this is a readonly list).

BuGless              Last change: 2001/06/23                    4

User Commands                                         LOCKFILE(1)

     Stephen R. van den Berg
     Philip A. Guenther

     This software was built from source available at https://ja-   The  original  community
     source  was  downloaded  from

     Further  information about this software can be found on the
     open source community website at

BuGless              Last change: 2001/06/23                    5