You are here: Administration > Man Pages > getlocks(1M)

getlocks(1M)

NAME

getlocks(1M) — operations of LifeKeeper "admin lock flags"

SYNOPSIS

LKROOT/lkadm/bin/getlocks -a amach -i identifier -l lockfile [-o omach][-e] [-p pid]

LKROOT/lkadm/bin/rlslocks -a amach -l lockfile

DESCRIPTION

These commands are used to obtain (getlocks) and release (rlslocks) an"admin lock flag". These flags are used with actions that require that no other action be performed at the same time on any of the servers in a LifeKeeper configuration. For example, one may not create a hierarchy on one server while creating a hierarchy on another. The "admin lock flags" are used to ensure that one of these "global" operations is not performed, until the one currently running completes. These flags use the LifeKeeper flag interface described in LCDI-flag(1M).

 

The following is the format of the "admin lock flags":

!action!procid!timestamp!uname:identifier

The identifier field of the "admin lock flag" identifies the kind of action being performed. The server running the process that requested the"admin lock flag" is specified by uname. The flag was created at timestamp number of seconds after Jan 1, 1970, by a process with a process ID of procid that called getlocks. All of the processes waiting for the "admin lock flag" are shown with their own "admin lockflag" in the listing produced by the lcdstatus command. The only one allowed to run is the first process that has its lock flag show up from the left side of the listing when reading the listing from left-to-right.

 

An example of such a flag is as follows:

!action!01525!701120147!cindy:filesys

This flag indicates that the action filesys is in progress, indicating a"file system hierarchy" is being created. The process with processID 1525 requested the "admin lock flag," at the time 701120147 on system cindy.

SYNTAX

getlocks -a amach -i identifier -l lockfile [-o omach] [-e] [-p pid]

This command is used to obtain an "admin lock flag". It assumes that the current process has no "admin lock flag" currently out. Multiple calls to getlocks, without an intervening call to rlslocks, are unnecessary and will have unpredictable results.

If a process calls getlocks and an "admin lock flag" already exists, getlocks will first check if the process indicated by procid in the"admin lock flag" that already exists is still running. If the process procid is still running, getlocks will wait until that process either exits or removes the "admin lock flag". If process procid is not running, the "admin lock flag" is removed and the next action waiting on the next "admin lock flag" in the LCDI-flag(1M) queue is allowed to run.

The amach argument of the -a option is used to specify which server is the server doing the administering, or the server that is controlling the global operation.

The identifier argument of the -i option is used to specify a string that can be used to identify what kind of operation is being performed (theidentifier described above). For example, filesys is used to identify the operation of creating a "file system resource hierarchy," and delhier is used to identify the operation of deleting a hierarchy.

The lockfile argument of the -l option is used to specify the name of the temporary file that getlocks will use to save server names of servers thathave succeeded in having the "admin lock flag" created. The contents of this file will be required by rlslocks to remove the flags when it is later run. Care must be taken to choose a name that will be unique and not to alter the contents of the file, or unpredictable results will occur.

If the omach argument of the -o option is used, getlocks will assume that the global operation is limited to only two servers, the server named amachand the server named omach, and will only obtain the "admin lock flag" on those two servers. If the option is not specified, it is assumedby getlocks that the "admin lock flag" should be obtained from all servers in the LifeKeeper configuration, that is, all servers that the command $LKROOT/bin/sys_list -d amach displays. Note that since amach could in principle be a different server than the current server, the current server and amach must be able to communicate with the same set of servers. In N+1 configurations, a direct link may not exist between the current server and another server in that set. In this case, getlocks will use an indirect route via the +1 server.

With the -e option, no error message will be printed if exit code 9 is returned.

The pid argument to the -p option is by default the pid of the process that executes getlocks (i.e. getlock's parent process). This default works as long as that parent process eventually calls the rlslocks command. If that is not the case, then some other relationship (e.g. getlock's grandparent process ID) must be used and that must be communicated to getlocks with the -p option. Some process must persist for the interval between the getlock and rlslock operations so LifeKeeper can determine if a lock is still valid.

rlslocks -a amach -l lockfile

This command is used to release an "admin lock flag." It assumes that the current process has one, and only one, "admin lock flag" currently out. Multiple calls to getlocks without an intervening call to rlslocks are unnecessary and will have unpredictable results.

The amach argument of the -a option is used to specify which server is the server doing the administering, or the server that is controlling the global operation. The lockfile argument of the -l option is used to specify the name of the temporary file that getlocks previously used to save server names of servers that have succeeded in having the "admin lock flag" created. The rlslocks program will use this information to remove all of the"admin lock flags" created by getlocks on all the servers saved in lockfile.

EXAMPLE

The following illustrates how "admin lock flags" should be used:

PRIMACH=`uname`

#

# Obtain the "admin lock flag"

#

if $LK/bin/getlocks -a "$PRIMACH" -I filesys -l /tmp/FSLOCKS$$ -o$SECMACH

then

#

# Create the file system resource hierarchy

#

$FS/bin/filesyshier "$PRIMACH" "$PRIMP""$PRITAG" "$SECMP" ...

ret=$?

if [ "$ret" = 0 ]

then

RESULT=Successful

else

RESULT=Failed

fi

log "lifekeeper: Create File System Hierarchy $PRIMP on $PRIMACH$RESULT ..."

#

# Release "admin lock flag"

#

if $LK/bin/rlslocks -a "$PRIMACH" -l /tmp/FSLOCKS$$

then

exit $ret

fi

fi

exit 1

EXIT CODES

The following exit codes could be returned by these commands:

0

The operation has succeeded.

1

The operation has failed. An error message is printed to stderr even if the -e option is specified for getlocks.

9

Returned only by getlocks. The operation to obtain the "admin lockflag" failed because one of the servers in sys_list [see LCDI-systems(1M)] is currently marked as being DEAD.

NOTES

The location of this utility, LKROOT, is defined in the default file /etc/default/LifeKeeper.

FILES

/etc/default/LifeKeeper

© 2012 SIOS Technology Corp., the industry's leading provider of business continuity solutions, data replication for continuous data protection.