The first requirement for locking a file or segment of a file is having a valid open file descriptor. If read locks are to be used, then the file must be opened with at least read access; likewise for write locks and write access.

In the example that follows, we open a file for both read and write access:

#include <stdio.h>
#include <errno.h>
#include <fcntl.h>
int fd;    /* file descriptor */
char *filename;

main(argc, argv)
int argc;
char *argv[];
{
    extern void exit(), perror();

    /* get database file name from command line and open the
     * file for read and write access. 
     */
    if (argc < 2) {
        (void) fprintf(stderr, "usage: %s filename\n", argv[0]);
        exit(2);
    }
    filename = argv[1];
    fd = open(filename, O_RDWR);
    if (fd < 0) {
        perror(filename);
        exit(2);
    }
}

The file is now open for us to perform both locking and I/O functions. We then proceed with the task of setting a lock.

Several ways exist to set a lock on a file. These methods depend upon how the lock interacts with the rest of the program. Questions of portability and performance exist. Two methods are given: using the fcntl(2) system call and using the /usr/group standards-compatible lockf(3) library function call.

Locking an entire file is just a special case of record locking. For both these methods the concept and the effect of the lock are the same. The file is locked starting at a byte offset of zero and going until the end of the maximum file size. This point is beyond any real end-of-file so that no other lock can be placed on the file. To set such a lock, set the size of the lock to zero. Here is a sample code fragment using the fcntl() system call:

#include <fcntl.h>
#define MAX_TRY 10
int try;
struct flock lck;

try = 0;
/* set up the record locking structure, the address of which
 * is passed to the fcntl() system call. */
lck.l_type = F_WRLCK; /* setting a write lock */
lck.l_whence = 0; /* offset l_start from beginning of file */
lck.l_start = 0L;
lck.l_len = 0L; /* until the end of the file address space */
/* Attempt locking MAX_TRY times before giving up. */
while (fcntl(fd, F_SETLK, &lck) < 0) {
    if (errno == EAGAIN || errno == EACCES) {
        /* there might be other error cases in which
         * you might try again.
         */
        if (++try < MAX_TRY) {
            (void) sleep(2);
            continue;
        }
        (void) fprintf(stderr,"File busy try again later!\n");
        return;
    }
    perror("fcntl");
    exit(2);
}
...

This piece of code tries to lock a file. The lock is attempted several times until one of the following events occurs:

To perform the same task using the lockf() function, use code like this:

#include <unistd.h>
#define MAX_TRY 10
int try;
try = 0;

/* make sure the file ptr is at the beginning of file. */
lseek(fd, 0L, 0);

/* Attempt locking MAX_TRY times before giving up. */
while (lockf(fd, F_TLOCK, 0L) < 0) {
    if (errno == EAGAIN || errno == EACCES) {
        /* there might be other error cases in which
         * you might try again.
         */
        if (++try < MAX_TRY) {
            sleep(2);
            continue;
        }
        (void) fprintf(stderr,"File busy try again later!\n");
        return;
    }
    perror("lockf");
    exit(2);

}
...

It should be noted that the lockf() example appears to be simpler, but the fcntl() example exhibits additional flexibility. Using the fcntl() method, it is possible to set the type and start of the lock request simply by setting a few structure variables. lockf() merely sets write (exclusive) locks; an additional system call (lseek()) is required to specify the start of the lock.

Locking a record is done the same way as locking a file except for the differing starting point and length of the lock. We now try to solve an example problem of dealing with two records (which may be either in the same file or in different files) that must be updated simultaneously so that other processes get a consistent view of the information they contain. This type of problem occurs, for example, when updating the inter-record pointers in a doubly linked list.

To deal with multiple locks, consider the following questions:

In managing record locks, you must plan a failure strategy for the case in which you cannot obtain all the required locks. It is because of contention for these records that we have decided to use record locking in the first place. Different programs might:

Let us now look at our example of inserting an entry into a doubly linked list. For the example, we assume that the record after which the new record is to be inserted has a read lock on it already. The lock on this record must be changed or promoted to a write lock so that the record may be edited.

Promoting a lock (generally from read lock to write lock) is permitted if no other process is holding a read lock in the same section of the file. If processes exist with pending write locks that are waiting for the same section of the file, the lock promotion succeeds and the other (sleeping) locks wait. Promoting (or demoting) a write lock to a read lock carries no restrictions. In either case, the lock is reset with the new lock type. Because the /usr/group lockf() function does not have read locks, lock promotion is not applicable to that call.

The code below shows an example of record locking with lock promotion:

struct record {
    .
    .             /* data portion of record */
    .
    long prev;    /* index to previous record in the list */
    long next;    /* index to next record in the list */
};

/* Lock promotion using fcntl(2)
 * When this routine is entered it is assumed that there are
 * read locks on "here" and "next".
 * If write locks on "here" and "next" are obtained:
 * Set a write lock on "this".
 * Return index to "this" record.
 * If any write lock is not obtained:
 * Restore read locks on "here" and "next".
 * Remove all other locks.
 * Return a -1.
 */
long set3lock (this, here, next)
long this, here, next;
{
    struct flock lck;
    
    lck.l_type = F_WRLCK;    /* setting a write lock */
    lck.l_whence = 0;        /* offset l_start from beginning of file */
    lck.l_start = here;
    lck.l_len = sizeof(struct record);

    /* promote lock on "here" to write lock */
    if (fcntl(fd, F_SETLKW, &lck) < 0) {
        return (-1);
    }
    /* lock "this" with write lock */
    lck.l_start = this;
    if (fcntl(fd, F_SETLKW, &lck) < 0) {
        /* Lock on "this" failed;
         * demote lock on "here" to read lock.
         */
        lck.l_type = F_RDLCK;
        lck.l_start = here;
        (void) fcntl(fd, F_SETLKW, &lck);
        return (-1);
    }
    /* promote lock on "next" to write lock */
    lck.l_start = next;
    if (fcntl(fd, F_SETLKW, &lck) < 0) {
        /* Lock on "next" failed; demote lock on "here" to read lock,... */
        lck.l_type = F_RDLCK;
        lck.l_start = here;
        (void) fcntl(fd, F_SETLK, &lck);
        /* ...and remove lock on "this".  */
        lck.l_type = F_UNLCK;
        lck.l_start = this;
        (void) fcntl(fd, F_SETLK, &lck);
        return (-1) /* cannot set lock, try again or quit */
    }

    return (this);
}

The locks on these three records were all set to wait (sleep) if another process was blocking them from being set. This was done with the F_SETLKW command. If the F_SETLK command was used instead, the fcntl() system calls would fail if blocked. The program would then have to be changed to handle the blocked condition in each of the error return sections.

Let us now look at a similar example using the lockf() function. Since there are no read locks, all (write) locks are referenced generically as locks.

/* Lock promotion using lockf(3).
 * When this routine is entered it is assumed that there are
 * no locks on "here" and "next".
 * If locks are obtained:
 * Set a lock on "this".
 * Return index to "this" record.
 * If any lock is not obtained:
 * Remove all other locks.
 * Return a -1.
 */

#include <unistd.h>

long set3lock (this, here, next)
long this, here, next;
{

    /* lock "here" */
    (void) lseek(fd, here, 0);
    if (lockf(fd, F_LOCK, sizeof(struct record)) < 0) {
        return (-1);
    }
    /* lock "this" */
    (void) lseek(fd, this, 0);
    if (lockf(fd, F_LOCK, sizeof(struct record)) < 0) {
        /* Lock on "this" failed.  Clear lock on "here". */
        (void) lseek(fd, here, 0);
        (void) lockf(fd, F_ULOCK, sizeof(struct record));
        return (-1);
    }

    /* lock "next" */
    (void) lseek(fd, next, 0);
    if (lockf(fd, F_LOCK, sizeof(struct record)) < 0) {
        /* Lock on "next" failed.  Clear lock on "here", */
        (void) lseek(fd, here, 0);
        (void) lockf(fd, F_ULOCK, sizeof(struct record));
        /* and remove lock on "this". */
        (void) lseek(fd, this, 0);
        (void) lockf(fd, F_ULOCK, sizeof(struct record));
        return (-1); /* cannot set lock, try again or quit */
    }

    return (this);
}

Locks are removed in the same manner as they are set; only the lock type is different (F_UNLCK or F_ULOCK). An unlock cannot be blocked by another process and only affects locks that were placed by the unlocking process. The unlock only affects the section of the file defined in the previous example by lck. It is possible to unlock or change the type of lock on a subsection of a previously set lock; this may cause an additional lock (two locks for one system call) to be used by the operating system. This occurs if the subsection is from the middle of the previously set lock.

One can determine which processes, if any, are blocking a lock from being set. This can be used as a simple test or as a means to find locks on a file. To find this information, set up a lock as in the previous examples and use the F_GETLK command in the fcntl() call. If the lock passed to fcntl() would be blocked, the first blocking lock is returned to the process through the structure passed to fcntl(). That is, the lock data passed to fcntl() is overwritten by blocking lock information. This information includes two pieces of data that have not been discussed yet, l_pidf and l_sysid, that are only used by F_GETLK. (For systems that do not support a distributed architecture the value in l_sysid should be ignored.) These fields uniquely identify the process holding the lock.

If a lock passed to fcntl() using the F_GETLK command is not blocked by another process' lock, then the l_type field is changed to F_UNLCK and the remaining fields in the structure are unaffected. Let us use this capability to print all the segments locked by other processes. Note that if several read locks occur over the same segment, only one of these is found.

struct flock lck;

/* Find and print "write lock" blocked segments of file. */
(void) printf("sysid pid type start length\n");
lck.l_whence = 0;
lck.l_start = 0L;
lck.l_len = 0L;
do {
    lck.l_type = F_WRLCK;
    (void) fcntl(fd, F_GETLK, &lck);
    if (lck.l_type != F_UNLCK) {
        (void) printf("%5d %5d %c %8d %8d\n",
                      lck.l_sysid,
                      lck.l_pid,
                      (lck.l_type == F_WRLCK) ? `W' : `R',
                      lck.l_start,
                      lck.l_len);
        /* if this lock goes to the end of the address
         * space, no need to look further, so break out.
         */
        if (lck.l_len == 0)
            break;
        /* otherwise, look for new lock after the one
         * just found.
         */
        lck.l_start += lck.l_len;
    }
} while (lck.l_type != F_UNLCK);

fcntl() with the F_GETLK command always returns correctly (that is, it will not sleep or fail) if the values passed to it as arguments are valid.

The lockf() function with the F_TEST command can also be used to test if there is a process blocking a lock. This function does not, however, return the information about where the lock actually is and which process owns the lock. Here is a routine using lockf() to test for a lock on a file:

/* find a blocked record. */

/* seek to beginning of file */
(void) lseek(fd, 0, 0L);
/* set the size of the test region to zero
 * to test until the end of the file address space.
 */
if (lockf(fd, F_TEST, 0L) < 0) {
    switch (errno) {
    case EACCES:
    case EAGAIN:
        (void) printf("file is locked by another process\n");
        break;
    case EBADF:
        /* bad argument passed to lockf */
        perror("lockf");
        break;

    default:
        (void) printf("lockf: unknown error <%d>\n", errno);
        break;
    }
}

When a process forks, the child receives a copy of the file descriptors that the parent has opened. The parent and child also share a common file pointer for each file. If the parent were to seek to a point in the file, the child's file pointer would also be at that location. This feature has important implications when using record locking. The current value of the file pointer is used as the reference for the offset of the beginning of the lock, as described by l_start, when using an l_whence value of 1. If both the parent and child process set locks on the same file, possibly a lock will be set using a file pointer that was reset by the other process. This problem appears in the lockf() function call as well and is a result of the /usr/group requirements for record locking.

If forking is used in a record locking program, the child process should close and reopen the file if either locking method is used. This results in the creation of a new and separate file pointer that can be manipulated without this problem occurring. Another solution is to use the fcntl() system call with an l_whence value of 0 or 2. This makes the locking function atomic, so processes sharing file pointers can lock without difficulty.

A certain level of deadlock detection/avoidance is built into the record locking facility. This deadlock handling provides the same level of protection granted by the /usr/group standard lockf() call. This deadlock detection is only valid for processes that are locking files or records on a single system.

Deadlocks can potentially occur only when the system is about to put a record locking system call to sleep. A search is made for constraint loops of processes that would cause the system call to sleep indefinitely. If such a situation is found, the locking system call fails and sets errno to the deadlock error number.

If a process wishes to avoid using the system's deadlock detection, it should set its locks using F_GETLK instead of F_GETLKW.

Some points to remember about mandatory locking:

In a UNIX environment, the system on which the locking process resides may be remote from the system on which the file and record locks reside. In this way multiple processes on different systems may put locks upon a single file that resides on one of them, or on yet another system. The record locks for a file reside on the system that maintains the file. It is also important to note that deadlock detection and avoidance is only determined by the record locks being held by and for a single system. Therefore, it is necessary that a process hold record locks on only a single system at any given time for the deadlock mechanism to be effective.

If a process needs to maintain locks over several systems, it is suggested that the process avoid the sleep-when-blocked features of fcntl() or lockf() and that the process maintain its own deadlock detection. If the process uses the sleep-when-blocked feature, then a timeout mechanism should be provided by the process so that it does not hang waiting for a lock to be cleared.