admlock(1M)                    DG/UX 5.4R3.00                    admlock(1M)


NAME
       admlock - manage simple process synchronization

SYNOPSIS
       admlock -o create [ -qv ] [ -w time-limit ] lock-name

       admlock -o remove [ -qv ] lock-name

       admlock -o check [ -qv ] [ lock-name...  ]

       admlock -o list [ -qv ] [ lock-name...  ]

   where:
       time-limit
                 The number of seconds to wait for a lock
       lock-name A string that conforms to simple filename rules.  If no
                 lock-name is specified for the check and list operations,
                 all known locks will be examined.

DESCRIPTION
       Admlock manages a simple process synchronization mechanism where the
       existence of a named file acts as an advisory lock.  Cooperating
       processes may use the lock to control access to critical resources.

       Admlock is intended for use in shell scripts, providing them an
       atomic test and set mechanism.  Each shell script or set of shell
       scripts that will cooperate in managing a resource should select a
       lock-name.  By testing and setting the lock before manipulating a
       critical resource, and releasing the lock afterwards, concurrent
       processes can maintain the resource's integrity.

   Operations
       create    Test and set a lock using the specified lock name.  A file
                 by that name will be created in /etc/sysadm/locks.

       remove    Release a lock by removing the corresponding lock file.

       check     Examine a lock to make sure that the locking process is
                 still active.  If the locking process is not active, the
                 lock will be released.

       list      List information about one or more locks.

   Options
       -w     Specify a time limit to wait for a lock.  This option's value
              should be based on the expected length of time a cooperating
              process might hold the lock, and is provided to guard against
              accidental persistence of a lock after the locking process
              goes away.  A zero value implies that the caller should not
              wait at all if the lock is already set.

       -q     Quiet, do not print headers for the list operation or error
              messages from other operations.  This is the default for all
              operations except list.



Licensed material--property of copyright holder(s)                         1

admlock(1M)                    DG/UX 5.4R3.00                    admlock(1M)


       -v     Verbose, include header lines in the list output and error
              messages from other operations.  This is the default for the
              list operation.

EXAMPLE
       To test and set a lock:

            if admlock -o create -w 30 mylockname
            then
                :
            else
                echo "could not get lock in 30 seconds"
                exit 1
            fi

       To release a lock when done:

            admlock -o remove mylockname

DIAGNOSTICS
   Exit Codes
        0     The lock was created (create) or released (remove)
              successfully.  The check operation returns this value if the
              specified lock file does not exist, or an existing lock file
              which did not have an active process associated with it was
              successfully removed, or the locking process is on a remote
              system and cannot be checked.

        1     The lock could not be created within the time limit
              restrictions (create), or an existing lock has an active
              locking process (check).

        2     A previous lock does not exist but a lock file could not be
              created (create), a lock file owned by this process could not
              be released (remove), or the specified lock file does not have
              an active process associated with it and the lock file was not
              or could not be removed (check).

        3     There was an error in the command line.

ENVIRONMENT
       The following environment variables are used:

       ROOT      An alternate root pathname, if not ``/''.  This is provided
                 for use by a server system.

FILES
       /etc/sysadm/locks   Directory containing lock files

SEE ALSO
       fcntl(2), semop(2).

NOTES
       Admlock works by attempting to create the named file.  If the



Licensed material--property of copyright holder(s)                         2

admlock(1M)                    DG/UX 5.4R3.00                    admlock(1M)


       creation fails because the file already exists, the command waits a
       short time and tries again.  As failure persists, the command waits
       longer and longer time periods until the time limit expires (it waits
       at most 30 seconds between tries).  At each failure, a check is made
       to ensure that the locking process continues to exist, and the old
       lock is released if the locking process is no longer active.  When
       the file creation succeeds, the following information is written to
       the lock file using the indicated format:

            "%5d %-12s %15d\n",  parent-pid, host-name, time-since-epoch

       This information is used by the check operation and by the create
       operation to ensure that the calling process does not already have
       the file locked.

       Any signal received while waiting to create a lock file will cause
       the command to exit with an exit code of 1.

       File locking using fcntl(2) is not involved in this procedure.

BUGS
       Deadlock detection is not attempted, except in the case where a
       process attempts to lock a lock it already has.


































Licensed material--property of copyright holder(s)                         3