manual/LDP_man-pages/release/man3/flockfile.3

   1 .\" Copyright (C) 2001 Andries Brouwer <aeb@cwi.nl>.
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Japanese Version Copyright (c) 2001 Yuichi SATO
  24 .\"         all rights reserved.
  25 .\" Translated Sun Nov  4 14:09:45 2001
  26 .\"         by Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  27 .\"
  28 .\"WORD:        lockcount       ロック数
  29 .\"WORD:        owner thread    所有者スレッド
  30 .\"
  31 .TH FLOCKFILE 3  2008-08-29 "" "Linux Programmer's Manual"
  32 .SH 名前
  33 flockfile, ftrylockfile, funlockfile \- 標準入出力 FILE のロックを行う
  34 .SH 書式
  35 .nf
  36 .B #include <stdio.h>
  37 .sp
  38 .BI "void flockfile(FILE *" filehandle );
  39 .br
  40 .BI "int ftrylockfile(FILE *" filehandle );
  41 .br
  42 .BI "void funlockfile(FILE *" filehandle );
  43 .fi
  44 .sp
  45 .in -4n
  46 glibc 向けの機能検査マクロの要件
  47 .RB ( feature_test_macros (7)
  48 参照):
  49 .in
  50 .ad l
  51 .sp
  52 上記の全ての関数:
  53 .RS 4
  54 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
  55 _SVID_SOURCE || _POSIX_SOURCE
  56 .RE
  57 .ad b
  58 .SH 説明
  59 標準入出力関数はスレッドセーフである。これは、各
  60 .I FILE
  61 オブジェクトに対し、ロック数 (lockcount) と
  62 (ロック数が 0 でない場合は) 所有者スレッド (owner thread)
  63 を管理することで実現される。
  64 ライブラリの呼び出しが行われる毎に、標準入出力関数は
  65 .I FILE
  66 オブジェクトが他のスレッドによってロックされていない状態になるまで待ち、
  67 .I FILE
  68 オブジェクトをロックし、要求されて入出力を行い、
  69 オブジェクトのロックを解除する。
  70 .LP
  71 (注: このロックは、
  72 .BR flock (2)
  73 や
  74 .BR lockf (3)
  75 といった関数が行うロックとは全く無関係である。)
  76 .LP
  77 これらのことはすべて C プログラマには見えない部分で行われるが、
  78 より細かい制御ができた方がよい理由が2つあるだろう。一つは、一つのスレッドが
  79 行う一連の入出力動作は一緒に行われ、他のスレッドの入出力によって中断されない
  80 方がよいということであろう。もう一つは、効率を大きく上げるためには
  81 ロックのオーバヘッドを避ける必要があるということであろう。
  82 .LP
  83 この目的を実現するために、
  84 .I FILE
  85 オブジェクトのロック、一連の入出力動作の実行、
  86 ロックの解除をスレッドが明示的に指示することができる。
  87 これにより、他のスレッドが途中で入出力を行うのを防止する。
  88 このようなことを行う理由が効率の向上であるならば、
  89 ロックを行わないバージョンの標準入出力関数を使うこともできる。
  90 例えば、
  91 .BR getc (3)
  92 や
  93 .BR putc (3)
  94 の代わりに
  95 .BR getc_unlocked (3)
  96 や
  97 .BR putc_unlocked (3)
  98 を使用する。
  99 .LP
 100 .BR flockfile ()
 101 関数は、\fI*filehandle\fP が他のスレッドにロックされていな
 102 い状態になるまで待ったのち、現在のスレッドを \fI*filehandle\fP のオーナに設
 103 定し、ロック数を加算する。
 104 .LP
 105 .BR funlockfile ()
 106 関数は、ロック数を減算する。
 107 .LP
 108 .BR ftrylockfile ()
 109 関数は
 110 .BR flockfile ()
 111 のブロッキングを行わない
 112 バージョンである。他のスレッドが \fI*filehandle\fP をロックしている時は
 113 何も行わず、そうでない場合は \fI*filehandle\fP の所有権を獲得し、
 114 ロック数を加算する。
 115 .SH 返り値
 116 .BR ftrylockfile ()
 117 関数はロックに成功すると 0 を返し、
 118 失敗した場合は 0 以外の値を返す。
 119 .SH エラー
 120 なし。
 121 .SH 準拠
 122 POSIX.1-2001.
 123 .SH 可用性
 124 .B _POSIX_THREAD_SAFE_FUNCTIONS
 125 が定義されているときにこれらの関数を使用することができる。
 126 5.1.1 以降の libc と 2.0 以降の glibc に存在する。
 127 .SH 関連項目
 128 .BR unlocked_stdio (3)