Section 4.3. Locking Files

As its first argument the fcntl system call is passed a valid integer file descriptor of an open file. The second argument, cmd , is an integer command value that specifies the action that fcntl should take. The command values for locking are specified as defined constants in the header file <bits/fcntl.h> that is included by the <fcntl.h> header file. The lock specific constants are shown in Table 4.7.

Table 4.7. Lock-Specific Defined Constants Used with the fcntl System Call.

The third argument for fcntl is optional for some invocations (as indicated by it being gcommented out in the function prototype). However, when working with locks, the third argument is specified and references a flock structure, which is defined as

struct flock  {
     short int l_type;   /* Type of lock: F_RDLCK, F_WRLCK, or F_UNLCK. */
     short int l_whence; /* Where 'l_start' is relative to.             */
     #ifndef __USE_FILE_OFFSET64
     __off_t l_start;    /* Offset where the lock begins.               */
     __off_t l_len;      /* Size of the locked area; (0 == EOF).       */
     #else
     __off64_t l_start;  /* For systems with 64 bit offset.             */
     __off64_t l_len;
     #endif
     __pid_t l_pid;      /* PID of process holding the lock.            */
};

The flock structure is used to pass information to and return information from the fcntl call. The type of lock, l_type , is indicated by using one of the defined constants shown in Table 4.8.

The l_whence , l_start , and l_len flock members are used to indicate the starting location (0, the beginning of the file; 1, the current location; and 2, the end of the file), relative offset, and size of the record (segment). If these values are set to 0, the entire file will be operated upon. The l_pid member is used to return the PID of the process that placed the lock.

Table 4.8. Defined Constants Used in the flock l_type Member.

When dealing with locks, if fcntl fails to carry out an indicated command, it will return a value of -1 and set errno . Error messages associated with locking are shown in Table 4.9.

Table 4.9. fcntl Error Messages Relating to Locking.

Program 4.2 demonstrates the use of file locking.

Program 4.2 Using fcntl to lock a file.

File : p4.2.cxx
       /* Locking a file with fcntl
        */
       #include <iostream>
  +     #include <cstdio>
       #include <cerrno>
       #include <fcntl.h>
       #include <unistd.h>
       using namespace std;
       const int MAX = 5;
 10     int
       main(int argc, char *argv[ ]) {
         int             f_des, pass = 0;
         pid_t           pid = getpid();
         struct flock    lock;                // for fcntl info
  +       if (argc < 2) {                      // name of file to lock missing
           cerr << "Usage " << *argv << " lock_file_name" << endl;
           return 1;
         }
         sleep(1);                            // don't start immediately
 20       if ((f_des = open(argv[1], O_RDWR)) < 0){
           perror(argv[1]);                   // could not access file
           return 2;
         }
         lock.l_type   = F_WRLCK;             // set a write lock
  +       lock.l_whence = 0;                   // start at beginning
         lock.l_start  = 0;                   // with a 0 offset
         lock.l_len    = 0;                   // whole file
         while (fcntl(f_des, F_SETLK, &lock) < 0) {
           switch (errno) {
 30         case EAGAIN:
           case EACCES:
             if (++pass < MAX)
               sleep(1);
             else {                           // run out of tries
  +             fcntl(f_des, F_GETLK, &lock);
               cerr << "Process " << pid << " found file "
                    << argv[1] << " locked by " << lock.l_pid << endl;
               return 3;
             }
 40           continue;
           }
           perror("fcntl");
           return 4;
         }
  +       cerr << endl << "Process " << pid << " has the file" << endl;
         sleep(3);                            // fake processing
         cerr << "Process " << pid << " is done with the file" << endl;
         return 0;
       }

In this program the name of the file to be locked is passed on the command line. A call to sleep is placed at the start of the program to slow down the processing (for demonstration purposes only). The designated file is opened for reading and writing. In lines 24 through 27 the lock structure is assigned values that indicate a write lock is to be applied to the entire file. In the while loop that follows , a call to fcntl requests the lock be placed. If fcntl fails and errno is set to either EAGAIN or EACCES (values that indicate the lock could not be applied), the process will sleep for one second and try to apply the lock again. To be safe, the EACCES constant is grouped with EAGAIN, as in some versions of UNIX this is the value that is returned when a lock cannot be applied. If the MAX number of tries ( passes ) has been exceeded, another call to fcntl (line 35) is made to obtain information about the process that has locked the file. In this call the address of the lock structure is passed to fcntl . The PID of the locking process is displayed, and the program exits. If an error other than EAGAIN or EACCES is encountered when attempting to set the lock, perror is called, a message is displayed, and the program exits. If the process successfully obtains the lock, the process prints an informational message, sleeps three seconds (to simulate some sort of processing), and prints a second message as it terminates. When the process terminates, the system automatically removes the lock on the file. If the process were not to terminate, the process would need to set the l_type member to F_UNLCK and reissue the fcntl call to clear the lock.

If we run three copies of Program 4.2 in rapid succession, using the file x.dat as the lock file, their output will be similar to that shown in Figure 4.6.

Figure 4.6 Running multiple copies of Program 4.2locking a file.

linux$ p4.2 x.dat & p4.2 x.dat &  p4.2 x.dat &

<-- 1

[1] 28392
[2] 28393
[3] 28394
$
Process 28392 has the file
Process 28392 is done with the file
Process 28393 has the file
Process 28394 found file x.dat locked by 28393
Process 28393 is done with the file

[3]   Exit 3                        p4.2 x.dat
[2]   Done                          p4.2 x.dat
[1]  + Done                          p4.2 x.dat

(1) All three processes will use the same file :

Notice that the last process, PID 28394 in this example, is unable to place a lock on the file and returns the process ID of the process that currently has the lock on the file. The second process, PID 28393, through repeated retries (with intervening calls to sleep ) is able to lock the file once the first process is finished with it.

The lockf library function may also be used to apply, test, or remove a lock on an open file. Beneath the covers this library function is an alternate interface for the fcntl system call. The lockf library function is summarized in Table 4.10.

Table 4.10. Summary of the lockf Library Call

<sys/file.h>
<unistd.h>

The fd argument is a file descriptor of a file that has been opened for either writing (O_WRONLY) or for reading and writing (O_RDWR). The cmd argument for lockf is similar to the cmd argument used with fcntl . The cmd value indicates the action to be taken. The action that lockf will take for each cmd value (as specified in the include file <unistd.h> ) is summarized in Table 4.11.

Table 4.11. Defined cmd Constants.

The len argument of lockf indicates the number of contiguous bytes to lock or unlock. A value of zero indicates the section should be from the present location to the end of the file.

If the lockf call is successful, it returns a value of 0. If the call fails, it sets errno and returns the value -1 (Table 4.12).

Table 4.12. lockf error messages.

Of the two techniques, lockf is simpler but less flexible than using fcntl . Note that when using the lockf call, the user must issue a separate lseek system call to position the file pointer to the proper location in the file prior to the call. Also, when generating parent/child process pairs, each shares the same file pointer. If locks are to be used in both processes, it is sometimes best to close and reopen the file in question so that each process has its own separate file pointer.

A final noteLinux supports a shlock command that can be used in shell scripts. The shlock command creates a lock file that contains an identifying PID.

4-5 EXERCISE Write Exercise 4.3 using the lockf system call. Verify that your solution works.

---

Top