pd.if.org Git - pdclib/blob - man3/flockfile.3

   1 .\" This file is part of the Public Domain C Library (PDCLib).
   2 .\" Permission is granted to use, modify, and / or redistribute at will.
   3 .\"
   4 .Dd
   5 .Dt flockfile 3
   6 .Os
   7 .\"
   8 .Sh NAME
   9 .Nm flockfile, ftrylockfile, funlockfile
  10 .Nd stdio file locking
  11 .\"
  12 .Sh SYNOPSIS
  13 .Sy #define _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600 || _SVID_SOURCE || _BSD_SOURCE
  14 .\"
  15 .In stdio.h
  16 .Fn "void flockfile" "FILE *file"
  17 .Fn "int ftrylockfile" "FILE *file"
  18 .Fn "void funlockfile" "FILE *file"
  19 .\"
  20 .Sh DESCRIPTION
  21 .Fn flockfile
  22 locks the passed FILE stream for access by the calling thread, potentially
  23 blocking.
  24 .Fn ftrylockfile
  25 attempts to lock the file for the calling thread, but will return failure if
  26 another thread has already locked the file.
  27 .Fn funlockfile
  28 releases the lock on the stream, allowing another thread in the process to
  29 access it.
  30 .\"
  31 .Pp
  32 The same stream may be locked multiple times by the calling thread; the number
  33 of calls to
  34 .Fn flockfile
  35 and
  36 .Fn ftrylockfile
  37 on a file must be equal to the number of calls to
  38 .Fn funlockfile .
  39 .\"
  40 .Pp
  41 No other thread may do I/O through the locked file while it is locked.
  42 .\"
  43 .Sh IMPLEMENTATION NOTES
  44 PDCLib implements the file locking on top of the Mutex primitives added by C11
  45 .\"
  46 .Sh SEE ALSO
  47 .Xr fopen 3
  48 .Xr fclose 3
  49 .Xr unlocked_stdio 3
  50 .Xr mtx_t 3
  51 .\"
  52 .Sh STANDARDS
  53 The locked I/O routines were initially introduced in
  54 .St -svid4 ,
  55 and incorporated into POSIX in
  56 .St -p1003.1-2001 .