ftrylockfile(3)                                         ftrylockfile(3)

  flockfile()

  NAME

    flockfile(), ftrylockfile(), funlockfile() - lock stdio (FILE *) objects

  SYNOPSIS

    #include 

    void flockfile(FILE *file);
    int ftrylockfile(FILE *file);
    void funlockfile(FILE *file);

  DESCRIPTION

    These functions are used to lock stdio (FILE *) objects at the application
    level. Threads can use these functions to identify a sequence of I/
    O statements that are to be executed as a unit. These functions
    effectively maintain a lock count for the stdio stream referenced by the
    file argument.

    The flockfile(3) function acquires ownership for a thread of the stdio
    stream referenced by file. If the lock count of the stream is zero, then
    the calling thread takes ownership of the stream and the lock count is
    incremented. If the lock count of the stream is greater than one and the
    calling thread owns the stream, then the lock count is incremented. If the
    lock count of the stream is greater than one and the calling thread does
    not own the stream, then the calling thread is blocked until the lock
    count reaches zero, at which time the calling thread receives ownership of
    the stream and the lock count is incremented.

    The ftrylockfile(3) is identical to flockfile(), except that the function
    immediately returns (the calling thread is not blocked) if the lock count
    of the stream referenced by file is greater than zero and the stream is
    not owned by the calling thread.

    The funlockfile(3) function decrements the lock count for the stream
    referenced by file. This function should be called once for each
    successful call to flockfile() or ftrylockfile().

  RETURN VALUES

    No return values are defined for flockfile() and funlockfile().

    The ftrylockfile() function returns zero to indicate success. Any other
    return value indicates that the lock could not be acquired.

  USAGE NOTES

    All of these functions are thread safe.

    None of these functions are async-signal safe.