lockf(3)                                                       lockf(3)

  lockf()

  NAME

    lockf() - lock sections of file with advisory-mode locks

  SYNOPSIS

    #include 

    int lockf(int fd, int function, off_t size)

  DESCRIPTION

    The lockf(3) function can be used to lock sections of a file with
    advisory-mode locks. If another process uses lockf(3) to lock an already-
    locked section of the file, lockf(3) will return an error or block
    (depending upon function).

    The lockf(3) function takes three arguments:

    fd
        An open file descriptor. In order to establish a lock, the file must
        have been opened with either write-only permission or read/write
        permission (O_WRONLY or O_RDWR).

    function
        The action to be taken by lockf(3). The following values for function
        are defined in :

        F_LOCK
            Lock a section for exclusive use. The calling process is blocked
            until the section is available. (Blocking on a section is
            interrupted by any signal.)

        F_TEST
            Test a section for locks by other processes.

        F_TLOCK
            Test and lock a section for exclusive use. The function fails if
            the section is not available.

        F_ULOCK
            Unlock all or part of a locked sections. File locks are also
            released the first time any file descriptor for the file is closed
            by the calling process. If the middle part of a locked section is
            unlocked, it leaves behind two separate locked sections.

    size
        The number of continguous bytes to be locked or unlocked. If size is
        positive, size bytes will be locked (or unlocked) starting at the
        current offset in the file; if size is negative, size bytes will be
        locked (or unlocked) ending at the current offset in the file. If size
        is 0, the lockf(3) function locks from the current offset to the
        present or any future end-of-file.

    Sections locked may overlap, contain, or be contained by another section
    already locked by the same process. In this case, the sections are
    combined into a single locked section.

  RETURN VALUES

    The lockf(3) function returns 0 on success. It returns -1 on failure and
    sets errno; existing locks are not changed.

  NOTES

    This implementation of the lockf(3) function is a wrapper around the
    fcntl(2) function, using F_SETLK, F_SETLKW, and F_GETLK.

  ERRORS

    The lockf(3) function can fail for the following reasons:

    [EACCES] or [EAGAIN]
        The function is F_TLOCK or F_TEST and the section is already locked by
        another process.

    [EAGAIN]
        The function attempted to lock a file that is mapped with mmap(2).

    [EBADF]
        The file descriptor is not a valid open file descriptor, or the call
        is trying to lock the file (F_LOCK or F_TLOCK) and the file isn't open
        for writing.

    [EINTR]
        A signal interrupted the execution of the function.

    [EINVAL]
        The function argument is not one of the ones defined here, or size
        plus the current offset is less than zero or is greater than the
        largest possible offset.

    [EOPNOTSUPP]
        This implementation does not support the locking of files of the type
        indicated by the file descriptor.

  SEE ALSO

    alarm(2)

    chmod(2)

    close(2)

    creat(2)

    fcntl(2)

    flock(2)

    mmap(2)

    open(2)

    read(2)

    write(2)

  USAGE NOTES

    The lockf function is thread safe.

    The lockf function is not async-signal safe.