stdio/FreeBSD/flockfile.3

   1 .\" Copyright (c) 2003 Tim J. Robbins
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libc/stdio/flockfile.3,v 1.3 2003/01/13 01:29:14 tjr Exp $
  26 .\"
  27 .Dd January 10, 2003
  28 .Dt FLOCKFILE 3
  29 .Os
  30 .Sh NAME
  31 .Nm flockfile ,
  32 .Nm ftrylockfile ,
  33 .Nm funlockfile
  34 .Nd "stdio locking functions"
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In stdio.h
  39 .Ft void
  40 .Fn flockfile "FILE *stream"
  41 .Ft int
  42 .Fn ftrylockfile "FILE *stream"
  43 .Ft void
  44 .Fn funlockfile "FILE *stream"
  45 .Sh DESCRIPTION
  46 These functions provide explicit application-level locking of stdio streams.
  47 They can be used to avoid output from multiple threads being interspersed,
  48 input being dispersed among multiple readers, and to avoid the overhead
  49 of locking the stream for each operation.
  50 .Pp
  51 The
  52 .Fn flockfile
  53 function acquires an exclusive lock on the specified stream.
  54 If another thread has already locked the stream,
  55 .Fn flockfile
  56 will block until the lock is released.
  57 .Pp
  58 The
  59 .Fn ftrylockfile
  60 function is a non-blocking version of
  61 .Fn flockfile ;
  62 if the lock cannot be acquired immediately,
  63 .Fn ftrylockfile
  64 returns non-zero instead of blocking.
  65 .Pp
  66 The
  67 .Fn funlockfile
  68 function releases the lock on a stream acquired by an earlier call to
  69 .Fn flockfile
  70 or
  71 .Fn ftrylockfile .
  72 .Pp
  73 These functions behave as if there is a lock count associated
  74 with each stream.
  75 Each time
  76 .Fn flockfile
  77 is called on the stream, the count is incremented,
  78 and each time
  79 .Fn funlockfile
  80 is called on the stream, the count is decremented.
  81 The lock is only actually released when the count reaches zero.
  82 .Sh RETURN VALUES
  83 The
  84 .Fn flockfile
  85 and
  86 .Fn funlockfile
  87 functions return no value.
  88 .Pp
  89 The
  90 .Fn ftrylockfile
  91 function
  92 returns zero if the stream was successfully locked,
  93 non-zero otherwise.
  94 .Sh SEE ALSO
  95 .Xr getc_unlocked 3 ,
  96 .Xr putc_unlocked 3
  97 .Sh STANDARDS
  98 The
  99 .Fn flockfile ,
 100 .Fn ftrylockfile
 101 and
 102 .Fn funlockfile
 103 functions conform to
 104 .St -p1003.1-2001 .