# man flock

NAME
       flock - manage locks from shell scripts

SYNOPSIS
       flock [options] <file|directory> <command> [command args]
       flock [options] <file|directory> -c <command>
       flock [options] <file descriptor number>

DESCRIPTION
       This utility manages flock(2) locks from within shell scripts or the command line.

       The  first  and second forms wrap the lock around the executing a command, in a manner similar to su(1) or newgrp(1).  It locks a specified file or directory, which is created (assuming appropriate
       permissions), if it does not already exist.  By default, if the lock cannot be immediately acquired, flock waits until the lock is available.

       The third form uses open file by file descriptor number.  See examples how that can be used.

OPTIONS
       -s, --shared
              Obtain a shared lock, sometimes called a read lock.

       -x, -e, --exclusive
              Obtain an exclusive lock, sometimes called a write lock.  This is the default.

       -u, --unlock
              Drop a lock.  This is usually not required, since a lock is automatically dropped when the file is closed.  However, it may be required in special cases, for example if the enclosed  command
              group may have forked a background process which should not be holding the lock.

       -n, --nb, --nonblock
              Fail rather than wait if the lock cannot be immediately acquired.  See the -E option for the exit code used.

       -w, --wait, --timeout seconds
              Fail if the lock cannot be acquired within seconds.  Decimal fractional values are allowed.  See the -E option for the exit code used.

       -o, --close
              Close the file descriptor on which the lock is held before executing command .  This is useful if command spawns a child process which should not be holding the lock.

       -E, --conflict-exit-code number
              The exit code used when the -n option is in use, and the conflicting lock exists, or the -w option is in use, and the timeout is reached. The default value is 1.

       -c, --command command
              Pass a single command, without arguments, to the shell with -c.

       -h, --help
              Print a help message.

       -V, --version
              Show version number and exit.

/* 本文的内核源码版本为linux-3.10.103 */

/* linux-3.10.103/linux-3.10.103/include/linux/fs.h */

struct inode {
    ...

    struct file_lock    *i_flock;

    ...
}

/* linux-3.10.103/linux-3.10.103/include/linux/fs.h */

struct file_lock {
    struct file_lock *fl_next;    /* singly linked list for this inode  */
    struct list_head fl_link;    /* doubly linked list of all locks */
    struct list_head fl_block;    /* circular list of blocked processes */
    fl_owner_t fl_owner;
    unsigned int fl_flags;
    unsigned char fl_type;
    unsigned int fl_pid;
    struct pid *fl_nspid;
    wait_queue_head_t fl_wait;
    struct file *fl_file;
    loff_t fl_start;
    loff_t fl_end;

    struct fasync_struct *    fl_fasync; /* for lease break notifications */
    /* for lease breaks: */
    unsigned long fl_break_time;
    unsigned long fl_downgrade_time;

    const struct file_lock_operations *fl_ops;    /* Callbacks for filesystems */
    const struct lock_manager_operations *fl_lmops;    /* Callbacks for lockmanagers */
    union {
        struct nfs_lock_info    nfs_fl;
        struct nfs4_lock_info    nfs4_fl;
        struct {
            struct list_head link;    /* link in AFS vnode's pending_locks list */
            int state;        /* state of grant or error if -ve */
        } afs;
    } fl_u;
};

/* linux-3.10.103/linux-3.10.103/include/linux/fs.h */

struct file {
    ...

    struct inode        *f_inode;    /* cached value */

    ...
}

/* linux-3.10.103/linux-3.10.103/fs/open.c */

long do_sys_open(int dfd, const char __user *filename, int flags, umode_t mode)
{
    struct open_flags op;
    int lookup = build_open_flags(flags, mode, &op);
    struct filename *tmp = getname(filename);
    int fd = PTR_ERR(tmp);

    if (!IS_ERR(tmp)) {
        fd = get_unused_fd_flags(flags);
        if (fd >= 0) {
            struct file *f = do_filp_open(dfd, tmp, &op, lookup);
            if (IS_ERR(f)) {
                put_unused_fd(fd);
                fd = PTR_ERR(f);
            } else {
                fsnotify_open(f);
                fd_install(fd, f);
            }
        }
        putname(tmp);
    }
    return fd;
}

int flock(int fd, int operation);

/* linux-3.10.103/linux-3.10.103/fs/locks.c */

/**
 *    sys_flock: - flock() system call.
 *    @fd: the file descriptor to lock.
 *    @cmd: the type of lock to apply.
 *
 *    Apply a %FL_FLOCK style lock to an open file descriptor.
 *    The @cmd can be one of
 *
 *    %LOCK_SH -- a shared lock.
 *
 *    %LOCK_EX -- an exclusive lock.
 *
 *    %LOCK_UN -- remove an existing lock.
 *
 *    %LOCK_MAND -- a `mandatory' flock.  This exists to emulate Windows Share Modes.
 *
 *    %LOCK_MAND can be combined with %LOCK_READ or %LOCK_WRITE to allow other
 *    processes read and write access respectively.
 */
SYSCALL_DEFINE2(flock, unsigned int, fd, unsigned int, cmd)
{
    struct fd f = fdget(fd);
    struct file_lock *lock;
    int can_sleep, unlock;
    int error;

    error = -EBADF;
    if (!f.file)
        goto out;

    can_sleep = !(cmd & LOCK_NB);
    cmd &= ~LOCK_NB;
    unlock = (cmd == LOCK_UN);

    if (!unlock && !(cmd & LOCK_MAND) &&
        !(f.file->f_mode & (FMODE_READ|FMODE_WRITE)))
        goto out_putf;

    error = flock_make_lock(f.file, &lock, cmd);
    if (error)
        goto out_putf;
    if (can_sleep)
        lock->fl_flags |= FL_SLEEP;

    error = security_file_lock(f.file, lock->fl_type);
    if (error)
        goto out_free;

    if (f.file->f_op && f.file->f_op->flock)
        error = f.file->f_op->flock(f.file,
                      (can_sleep) ? F_SETLKW : F_SETLK,
                      lock);
    else
        error = flock_lock_file_wait(f.file, lock);

 out_free:
    locks_free_lock(lock);

 out_putf:
    fdput(f);
 out:
    return error;
}

/* linux-3.10.103/linux-3.10.103/fs/locks.c */

/**
 * flock_lock_file_wait - Apply a FLOCK-style lock to a file
 * @filp: The file to apply the lock to
 * @fl: The lock to be applied
 *
 * Add a FLOCK style lock to a file.
 */
int flock_lock_file_wait(struct file *filp, struct file_lock *fl)
{
    int error;
    might_sleep();
    for (;;) {
        error = flock_lock_file(filp, fl);
        if (error != FILE_LOCK_DEFERRED)
            break;
        error = wait_event_interruptible(fl->fl_wait, !fl->fl_next);
        if (!error)
            continue;

        locks_delete_block(fl);
        break;
    }
    return error;
}

/* linux-3.10.103/linux-3.10.103/fs/locks.c */

/* Try to create a FLOCK lock on filp. We always insert new FLOCK locks
 * after any leases, but before any posix locks.
 *
 * Note that if called with an FL_EXISTS argument, the caller may determine
 * whether or not a lock was successfully freed by testing the return
 * value for -ENOENT.
 */
static int flock_lock_file(struct file *filp, struct file_lock *request)
{
    struct file_lock *new_fl = NULL;
    struct file_lock **before;
    struct inode * inode = file_inode(filp);
    int error = 0;
    int found = 0;

    if (!(request->fl_flags & FL_ACCESS) && (request->fl_type != F_UNLCK)) {
        new_fl = locks_alloc_lock();
        if (!new_fl)
            return -ENOMEM;
    }

    lock_flocks();
    if (request->fl_flags & FL_ACCESS)
        goto find_conflict;

    for_each_lock(inode, before) {
        struct file_lock *fl = *before;
        if (IS_POSIX(fl))
            break;
        if (IS_LEASE(fl))
            continue;
        if (filp != fl->fl_file)
            continue;
        if (request->fl_type == fl->fl_type)
            goto out;
        found = 1;
        locks_delete_lock(before);
        break;
    }

    if (request->fl_type == F_UNLCK) {
        if ((request->fl_flags & FL_EXISTS) && !found)
            error = -ENOENT;
        goto out;
    }

    /*
     * If a higher-priority process was blocked on the old file lock,
     * give it the opportunity to lock the file.
     */
    if (found) {
        unlock_flocks();
        cond_resched();
        lock_flocks();
    }

find_conflict:
    for_each_lock(inode, before) {
        struct file_lock *fl = *before;
        if (IS_POSIX(fl))
            break;
        if (IS_LEASE(fl))
            continue;
        if (!flock_locks_conflict(request, fl))
            continue;
        error = -EAGAIN;
        if (!(request->fl_flags & FL_SLEEP))
            goto out;
        error = FILE_LOCK_DEFERRED;
        locks_insert_block(fl, request);
        goto out;
    }
    if (request->fl_flags & FL_ACCESS)
        goto out;
    locks_copy_lock(new_fl, request);
    locks_insert_lock(before, new_fl);
    new_fl = NULL;
    error = 0;

out:
    unlock_flocks();
    if (new_fl)
        locks_free_lock(new_fl);
    return error;
}

/* flock.c */

#include <fcntl.h>
#include <stdlib.h>
#include <stdio.h>
#include <sys/file.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include <wait.h>

#define PATH "/tmp/lock"

int main() {
    int fd;
    pid_t pid;

    fd = open(PATH, O_RDWR|O_CREAT|O_TRUNC, 0644);
    if (fd < 0) {
        perror("open()");
        exit(1);
    }

    if (flock(fd, LOCK_SH) < 0) {
        perror("flock()");
        exit(1);
    }
    printf("%d: locked!\n", getpid());

    pid = fork();
    if (pid < 0) {
        perror("fork()");
        exit(1);
    }

    if (pid == 0) {

         fd = open(PATH, O_RDWR|O_CREAT|O_TRUNC, 0644);
         if (fd < 0) {
             perror("open()");
             exit(1);
         }

        if (flock(fd, LOCK_SH) < 0) {
            perror("flock()");
            exit(1);
        }
        printf("%d: locked!\n", getpid());
        exit(0);
    }
    wait(NULL);
    unlink(PATH);
    exit(0);
}

# gcc flock.c -o flock

# ./flock
11205: locked!
11206: locked!

# man fcntl

NAME
    Fcntl - load the C Fcntl.h defines

SYNOPSIS
    use Fcntl;
    use Fcntl qw(:DEFAULT :flock);

DESCRIPTION
    This module is just a translation of the C fcntl.h file.  Unlike the old mechanism of requiring a translated fcntl.ph file, this uses the h2xs program (see the Perl source distribution) and your
    native C compiler.  This means that it has a far more likely chance of getting the numbers right.

int fcntl(int fd, int cmd, ... /* arg */ );

/* linux-3.10.103/linux-3.10.103/include/uapi/asm-generic/fcntl.h */

struct flock {
    short    l_type;
    short    l_whence;
    __kernel_off_t    l_start;
    __kernel_off_t    l_len;
    __kernel_pid_t    l_pid;
    __ARCH_FLOCK_PAD
};

/* linux-3.10.103/linux-3.10.103/fs/fcntl.c */

static long do_fcntl(int fd, unsigned int cmd, unsigned long arg,
        struct file *filp)
{
    ...

    case F_GETLK:
        err = fcntl_getlk(filp, (struct flock __user *) arg);
        break;
    case F_SETLK:
    case F_SETLKW:
        err = fcntl_setlk(fd, filp, cmd, (struct flock __user *) arg);
        break;

    ...
}

/* linux-3.10.103/linux-3.10.103/fs/locks.c */

/* Apply the lock described by l to an open file descriptor.
 * This implements both the F_SETLK and F_SETLKW commands of fcntl().
 */
int fcntl_setlk(unsigned int fd, struct file *filp, unsigned int cmd,
        struct flock __user *l)
{
    struct file_lock *file_lock = locks_alloc_lock();
    struct flock flock;
    struct inode *inode;
    struct file *f;
    int error;

    ...

    inode = file_inode(filp);

    ...

    error = flock_to_posix_lock(filp, file_lock, &flock);
    if (error)
        goto out;

    ...

    error = do_lock_file_wait(filp, cmd, file_lock);

    /*
     * Attempt to detect a close/fcntl race and recover by
     * releasing the lock that was just acquired.
     */
    if (!error && file_lock->fl_type != F_UNLCK) {
        /*
         * We need that spin_lock here - it prevents reordering between
         * update of inode->i_flock and check for it done in
         * close(). rcu_read_lock() wouldn't do.
         */
        spin_lock(&current->files->file_lock);
        f = fcheck(fd);
        spin_unlock(&current->files->file_lock);
        if (f != filp) {
            file_lock->fl_type = F_UNLCK;
            error = do_lock_file_wait(filp, cmd, file_lock);
            WARN_ON_ONCE(error);
            error = -EBADF;
        }
    }
out:
    locks_free_lock(file_lock);
    return error;
}

/* linux-3.10.103/linux-3.10.103/fs/locks.c */

/* Verify a "struct flock" and copy it to a "struct file_lock" as a POSIX
 * style lock.
 */
static int flock_to_posix_lock(struct file *filp, struct file_lock *fl,
                   struct flock *l)
{
    off_t start, end;

    switch (l->l_whence) {
    case SEEK_SET:
        start = 0;
        break;
    case SEEK_CUR:
        start = filp->f_pos;
        break;
    case SEEK_END:
        start = i_size_read(file_inode(filp));
        break;
    default:
        return -EINVAL;
    }

    /* POSIX-1996 leaves the case l->l_len < 0 undefined;
       POSIX-2001 defines it. */
    start += l->l_start;
    if (start < 0)
        return -EINVAL;
    fl->fl_end = OFFSET_MAX;
    if (l->l_len > 0) {
        end = start + l->l_len - 1;
        fl->fl_end = end;
    } else if (l->l_len < 0) {
        end = start - 1;
        fl->fl_end = end;
        start += l->l_len;
        if (start < 0)
            return -EINVAL;
    }
    fl->fl_start = start;    /* we record the absolute position */
    if (fl->fl_end < fl->fl_start)
        return -EOVERFLOW;
    
    fl->fl_owner = current->files;
    fl->fl_pid = current->tgid;
    fl->fl_file = filp;
    fl->fl_flags = FL_POSIX;
    fl->fl_ops = NULL;
    fl->fl_lmops = NULL;

    return assign_type(fl, l->l_type);
}

/* linux-3.10.103/linux-3.10.103/fs/locks.c */

static int do_lock_file_wait(struct file *filp, unsigned int cmd,
                 struct file_lock *fl)
{
    int error;

    error = security_file_lock(filp, fl->fl_type);
    if (error)
        return error;

    for (;;) {
        error = vfs_lock_file(filp, cmd, fl, NULL);
        if (error != FILE_LOCK_DEFERRED)
            break;
        error = wait_event_interruptible(fl->fl_wait, !fl->fl_next);
        if (!error)
            continue;

        locks_delete_block(fl);
        break;
    }

    return error;
}

/* linux-3.10.103/linux-3.10.103/fs/locks.c */

/**
 * vfs_lock_file - file byte range lock
 * @filp: The file to apply the lock to
 * @cmd: type of locking operation (F_SETLK, F_GETLK, etc.)
 * @fl: The lock to be applied
 * @conf: Place to return a copy of the conflicting lock, if found.
 *
 * A caller that doesn't care about the conflicting lock may pass NULL
 * as the final argument.
 *
 * If the filesystem defines a private ->lock() method, then @conf will
 * be left unchanged; so a caller that cares should initialize it to
 * some acceptable default.
 *
 * To avoid blocking kernel daemons, such as lockd, that need to acquire POSIX
 * locks, the ->lock() interface may return asynchronously, before the lock has
 * been granted or denied by the underlying filesystem, if (and only if)
 * lm_grant is set. Callers expecting ->lock() to return asynchronously
 * will only use F_SETLK, not F_SETLKW; they will set FL_SLEEP if (and only if)
 * the request is for a blocking lock. When ->lock() does return asynchronously,
 * it must return FILE_LOCK_DEFERRED, and call ->lm_grant() when the lock
 * request completes.
 * If the request is for non-blocking lock the file system should return
 * FILE_LOCK_DEFERRED then try to get the lock and call the callback routine
 * with the result. If the request timed out the callback routine will return a
 * nonzero return code and the file system should release the lock. The file
 * system is also responsible to keep a corresponding posix lock when it
 * grants a lock so the VFS can find out which locks are locally held and do
 * the correct lock cleanup when required.
 * The underlying filesystem must not drop the kernel lock or call
 * ->lm_grant() before returning to the caller with a FILE_LOCK_DEFERRED
 * return code.
 */
int vfs_lock_file(struct file *filp, unsigned int cmd, struct file_lock *fl, struct file_lock *conf)
{
    if (filp->f_op && filp->f_op->lock)
        return filp->f_op->lock(filp, cmd, fl);
    else
        return posix_lock_file(filp, fl, conf);
}

/* fcntl.c */

#include <fcntl.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <sys/file.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include <wait.h>

#define PATH "/tmp/lock"

int main(int argc, char *argv[])
{
    int fd;
    pid_t pid;

    fd = open(PATH, O_RDWR|O_CREAT|O_TRUNC, 0644);
    if (fd < 0) {
        perror("open()");
        exit(1);
    }

    if (write(fd, "fcntl", strlen("fcntl")) != strlen("fcntl")) {
        perror("write()");
        exit(1);
    }

    struct flock lock;
    lock.l_type = F_WRLCK;
    lock.l_whence = SEEK_SET;
    lock.l_start = 0;
    lock.l_len = strlen("fcntl");

    if (fcntl(fd, F_SETLK, &lock) < 0) {
        perror("fcntl()");
        exit(1);
    }
    printf("%d: locked!\n", getpid());

    pid = fork();
    if (pid < 0) {
        perror("fork()");
        exit(1);
    }

    if (pid == 0) {

        fd = open(PATH, O_RDWR|O_CREAT|O_TRUNC, 0644);
        if (fd < 0) {
            perror("open()");
            exit(1);
        }

        lock.l_start = strlen("fcntl");
        lock.l_len = 0;

        if (fcntl(fd, F_SETLK, &lock) < 0) {
            perror("fcntl()");
            exit(1);
        }
        printf("%d: locked!\n", getpid());
        exit(0);
    }
    wait(NULL);
    unlink(PATH);
    exit(0);

}

# gcc fcntl.c -o fcntl

# ./fcntl
11919: locked!
11920: locked!