man3/flockfile.3

   1 '\" t
   2 .\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>.
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH flockfile 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 flockfile, ftrylockfile, funlockfile \- lock FILE for stdio
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <stdio.h>
  15 .PP
  16 .BI "void flockfile(FILE *" filehandle );
  17 .BI "int ftrylockfile(FILE *" filehandle );
  18 .BI "void funlockfile(FILE *" filehandle );
  19 .fi
  20 .PP
  21 .RS -4
  22 Feature Test Macro Requirements for glibc (see
  23 .BR feature_test_macros (7)):
  24 .RE
  25 .PP
  26 All functions shown above:
  27 .nf
  28     /* Since glibc 2.24: */ _POSIX_C_SOURCE >= 199309L
  29         || /* glibc <= 2.23: */ _POSIX_C_SOURCE
  30         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  31 .fi
  32 .SH DESCRIPTION
  33 The stdio functions are thread-safe.
  34 This is achieved by assigning
  35 to each
  36 .I FILE
  37 object a lockcount and (if the lockcount is nonzero)
  38 an owning thread.
  39 For each library call, these functions wait until the
  40 .I FILE
  41 object
  42 is no longer locked by a different thread, then lock it, do the
  43 requested I/O, and unlock the object again.
  44 .PP
  45 (Note: this locking has nothing to do with the file locking done
  46 by functions like
  47 .BR flock (2)
  48 and
  49 .BR lockf (3).)
  50 .PP
  51 All this is invisible to the C-programmer, but there may be two
  52 reasons to wish for more detailed control.
  53 On the one hand, maybe
  54 a series of I/O actions by one thread belongs together, and should
  55 not be interrupted by the I/O of some other thread.
  56 On the other hand, maybe the locking overhead should be avoided
  57 for greater efficiency.
  58 .PP
  59 To this end, a thread can explicitly lock the
  60 .I FILE
  61 object,
  62 then do its series of I/O actions, then unlock.
  63 This prevents
  64 other threads from coming in between.
  65 If the reason for doing
  66 this was to achieve greater efficiency, one does the I/O with
  67 the nonlocking versions of the stdio functions: with
  68 .BR getc_unlocked (3)
  69 and
  70 .BR putc_unlocked (3)
  71 instead of
  72 .BR getc (3)
  73 and
  74 .BR putc (3).
  75 .PP
  76 The
  77 .BR flockfile ()
  78 function waits for
  79 .I *filehandle
  80 to be
  81 no longer locked by a different thread, then makes the
  82 current thread owner of
  83 .IR *filehandle ,
  84 and increments
  85 the lockcount.
  86 .PP
  87 The
  88 .BR funlockfile ()
  89 function decrements the lock count.
  90 .PP
  91 The
  92 .BR ftrylockfile ()
  93 function is a nonblocking version
  94 of
  95 .BR flockfile ().
  96 It does nothing in case some other thread
  97 owns
  98 .IR *filehandle ,
  99 and it obtains ownership and increments
 100 the lockcount otherwise.
 101 .SH RETURN VALUE
 102 The
 103 .BR ftrylockfile ()
 104 function returns zero for success
 105 (the lock was obtained), and nonzero for failure.
 106 .SH ERRORS
 107 None.
 108 .SH ATTRIBUTES
 109 For an explanation of the terms used in this section, see
 110 .BR attributes (7).
 111 .ad l
 112 .nh
 113 .TS
 114 allbox;
 115 lbx lb lb
 116 l l l.
 117 Interface       Attribute       Value
 118 T{
 119 .BR flockfile (),
 120 .BR ftrylockfile (),
 121 .BR funlockfile ()
 122 T}      Thread safety   MT-Safe
 123 .TE
 124 .hy
 125 .ad
 126 .sp 1
 127 .SH STANDARDS
 128 POSIX.1-2001, POSIX.1-2008.
 129 .PP
 130 These functions are available when
 131 .B _POSIX_THREAD_SAFE_FUNCTIONS
 132 is defined.
 133 .SH SEE ALSO
 134 .BR unlocked_stdio (3)