draft/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 .\"O .SH NAME
  33 .\"O flockfile, ftrylockfile, funlockfile \- lock FILE for stdio
  34 .SH 名前
  35 flockfile, ftrylockfile, funlockfile \- 標準入出力 FILE のロックを行う
  36 .\"O .SH SYNOPSIS
  37 .SH 書式
  38 .nf
  39 .B #include <stdio.h>
  40 .sp
  41 .BI "void flockfile(FILE *" filehandle );
  42 .br
  43 .BI "int ftrylockfile(FILE *" filehandle );
  44 .br
  45 .BI "void funlockfile(FILE *" filehandle );
  46 .fi
  47 .sp
  48 .in -4n
  49 .\"O Feature Test Macro Requirements for glibc (see
  50 .\"O .BR feature_test_macros (7)):
  51 glibc 向けの機能検査マクロの要件
  52 .RB ( feature_test_macros (7)
  53 参照):
  54 .in
  55 .ad l
  56 .sp
  57 .\"O All functions shown above:
  58 上記の全ての関数:
  59 .RS 4
  60 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
  61 _SVID_SOURCE || _POSIX_SOURCE
  62 .RE
  63 .ad b
  64 .\"O .SH DESCRIPTION
  65 .SH 説明
  66 .\"O The stdio functions are thread-safe.
  67 .\"O This is achieved by assigning
  68 .\"O to each
  69 .\"O .I FILE
  70 .\"O object a lockcount and (if the lockcount is nonzero)
  71 .\"O an owning thread.
  72 標準入出力関数はスレッドセーフである。これは、各
  73 .I FILE
  74 オブジェクトに対し、ロック数 (lockcount) と
  75 (ロック数が 0 でない場合は) 所有者スレッド (owner thread)
  76 を管理することで実現される。
  77 .\"O For each library call, these functions wait until the
  78 .\"O .I FILE
  79 .\"O object
  80 .\"O is no longer locked by a different thread, then lock it, do the
  81 .\"O requested I/O, and unlock the object again.
  82 ライブラリの呼び出しが行われる毎に、標準入出力関数は
  83 .I FILE
  84 オブジェクトが他のスレッドによってロックされていない状態になるまで待ち、
  85 .I FILE
  86 オブジェクトをロックし、要求されて入出力を行い、
  87 オブジェクトのロックを解除する。
  88 .LP
  89 .\"O (Note: this locking has nothing to do with the file locking done
  90 .\"O by functions like
  91 .\"O .BR flock (2)
  92 .\"O and
  93 .\"O .BR lockf (3).)
  94 (注: このロックは、
  95 .BR flock (2)
  96 や
  97 .BR lockf (3)
  98 といった関数が行うロックとは全く無関係である。)
  99 .LP
 100 .\"O All this is invisible to the C-programmer, but there may be two
 101 .\"O reasons to wish for more detailed control.
 102 .\"O On the one hand, maybe
 103 .\"O a series of I/O actions by one thread belongs together, and should
 104 .\"O not be interrupted by the I/O of some other thread.
 105 .\"O On the other hand, maybe the locking overhead should be avoided
 106 .\"O for greater efficiency.
 107 これらのことはすべて C プログラマには見えない部分で行われるが、
 108 より細かい制御ができた方がよい理由が2つあるだろう。一つは、一つのスレッドが
 109 行う一連の入出力動作は一緒に行われ、他のスレッドの入出力によって中断されない
 110 方がよいということであろう。もう一つは、効率を大きく上げるためには
 111 ロックのオーバヘッドを避ける必要があるということであろう。
 112 .LP
 113 .\"O To this end, a thread can explicitly lock the
 114 .\"O .I FILE
 115 .\"O object,
 116 .\"O then do its series of I/O actions, then unlock.
 117 .\"O This prevents
 118 .\"O other threads from coming in between.
 119 .\"O If the reason for doing
 120 .\"O this was to achieve greater efficiency, one does the I/O with
 121 .\"O the nonlocking versions of the stdio functions: with
 122 .\"O .BR getc_unlocked (3)
 123 .\"O and
 124 .\"O .BR putc_unlocked (3)
 125 .\"O instead of
 126 .\"O .BR getc (3)
 127 .\"O and
 128 .\"O .BR putc (3).
 129 この目的を実現するために、
 130 .I FILE
 131 オブジェクトのロック、一連の入出力動作の実行、
 132 ロックの解除をスレッドが明示的に指示することができる。
 133 これにより、他のスレッドが途中で入出力を行うのを防止する。
 134 このようなことを行う理由が効率の向上であるならば、
 135 ロックを行わないバージョンの標準入出力関数を使うこともできる。
 136 例えば、
 137 .BR getc (3)
 138 や
 139 .BR putc (3)
 140 の代わりに
 141 .BR getc_unlocked (3)
 142 や
 143 .BR putc_unlocked (3)
 144 を使用する。
 145 .LP
 146 .\"O The
 147 .\"O .BR flockfile ()
 148 .\"O function waits for \fI*filehandle\fP to be
 149 .\"O no longer locked by a different thread, then makes the
 150 .\"O current thread owner of \fI*filehandle\fP, and increments
 151 .\"O the lockcount.
 152 .BR flockfile ()
 153 関数は、\fI*filehandle\fP が他のスレッドにロックされていな
 154 い状態になるまで待ったのち、現在のスレッドを \fI*filehandle\fP のオーナに設
 155 定し、ロック数を加算する。
 156 .LP
 157 .\"O The
 158 .\"O .BR funlockfile ()
 159 .\"O function decrements the lock count.
 160 .BR funlockfile ()
 161 関数は、ロック数を減算する。
 162 .LP
 163 .\"O The
 164 .\"O .BR ftrylockfile ()
 165 .\"O function is a nonblocking version
 166 .\"O of
 167 .\"O .BR flockfile ().
 168 .\"O It does nothing in case some other thread
 169 .\"O owns \fI*filehandle\fP, and it obtains ownership and increments
 170 .\"O the lockcount otherwise.
 171 .BR ftrylockfile ()
 172 関数は
 173 .BR flockfile ()
 174 のブロッキングを行わない
 175 バージョンである。他のスレッドが \fI*filehandle\fP をロックしている時は
 176 何も行わず、そうでない場合は \fI*filehandle\fP の所有権を獲得し、
 177 ロック数を加算する。
 178 .\"O .SH "RETURN VALUE"
 179 .SH 返り値
 180 .\"O The
 181 .\"O .BR ftrylockfile ()
 182 .\"O function returns zero for success
 183 .\"O (the lock was obtained), and nonzero for failure.
 184 .BR ftrylockfile ()
 185 関数はロックに成功すると 0 を返し、
 186 失敗した場合は 0 以外の値を返す。
 187 .\"O .SH ERRORS
 188 .\"O None.
 189 .SH エラー
 190 なし。
 191 .\"O .SH "CONFORMING TO"
 192 .SH 準拠
 193 POSIX.1-2001.
 194 .\"O .SH AVAILABILITY
 195 .SH 可用性
 196 .\"O These functions are available when
 197 .\"O .B _POSIX_THREAD_SAFE_FUNCTIONS
 198 .\"O is defined.
 199 .\"O They are in libc since libc 5.1.1 and in glibc
 200 .\"O since glibc 2.0.
 201 .B _POSIX_THREAD_SAFE_FUNCTIONS
 202 が定義されているときにこれらの関数を使用することができる。
 203 5.1.1 以降の libc と 2.0 以降の glibc に存在する。
 204 .\"O .SH "SEE ALSO"
 205 .SH 関連項目
 206 .BR unlocked_stdio (3)