.\" Copyright (c) 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)stdio.3	8.7 (Berkeley) 4/19/94
.\" %FreeBSD: src/lib/libc/stdio/stdio.3,v 1.10.2.7 2001/12/14 18:33:57 ru Exp %
.\" $FreeBSD$
.\"
.Dd April 19, 1994
.Dt STDIO 3
.Os
.Sh 名称
.Nm stdio
.Nd 標準入出力ライブラリ関数
.Sh ライブラリ
.Lb libc
.Sh 書式
.In stdio.h
.Vt FILE *stdin ;
.Vt FILE *stdout ;
.Vt FILE *stderr ;
.Sh 解説
標準
.Tn I/O
ライブラリは、単純かつ効率的なバッファ付きストリーム
.Tn I/O
インタフェースを提供します。
入力と出力は論理的データストリームにマップされ、
物理的な
.Tn I/O
特性値は隠されます。関数およびマクロは下に示す通りですが、
それぞれに関する個別のマニュアルページにさらに詳しい説明があります。
.Pp
ストリームはファイルを
.Em 開く
ことによって、外部ファイル (物理的なデバイスのときもあります) に
関連づけられます。
それによって新しいファイルが作成される場合もあります。
存在するファイルを作成しようとすると、
そのファイルの以前の内容は破棄されます。
ファイルが位置指定要求 (端末ではなく、ディスクファイルというような) を
サポートする場合は、そのファイルが追加モードで開かれているのでない限り、
ストリームに関連づけられた
.Em ファイル位置指示子
はファイルの先頭 (バイト 0) を指します。
追加モードを使った場合は、位置指示子はファイルの最後を指します。
位置指示子は以降の読み取り、書込み、位置指定の要求によって取り扱われます。
すべての入力はあたかもキャラクタが
.Xr fgetc 3
関数の連続的な呼び出しによって読み取られたかのようにして行われ、すべての
出力はすべてのキャラクタが
.Xr fputc 3
関数の連続的な呼び出しによって
書込まれたかのようにして行われます。
.Pp
ファイルは、そのファイルを
.Em 閉じる
ことによってストリームとの関連づけが解除されます。
出力ストリームは、ファイルとの関連づけが解除される前にフラッシュされます
(書込まれなかったバッファの内容はホスト環境に送られます)。
.Dv FILE
オブジェクトへのポインタの値は、ファイルを閉じた後は
不定 (ゴミ) になります。
.Pp
同じプログラムまたは別のプログラムの実行から
ファイルを再度オープンしてもよく、
(ファイルの開始位置に再度位置づけできる場合は)
元のファイルの内容を再利用または変更できます。
main 関数が呼び出し元に返るか、または
.Xr exit 3
関数が呼び出された場合には、開いている全てのファイルは閉じられます
(従って、すべての出力ストリームはフラッシュされます)。
それ以外の方法でプログラムを終了したときは、
ファイルが適切に閉じられない可能性があるため、
バッファリングされた出力が失われることがあります。
特に、
.Xr _exit 2
は stdio ファイルをフラッシュしません。シグナルによる exit も同様です。
.Xr abort 3
は POSIX の要請に従いバッファをフラッシュしますが、
以前の実装ではこれを行っていません。
.Pp
この実装では、
.Dq テキスト
と
.Dq バイナリ
のストリームを区別しません。
実際にはすべてのストリームはバイナリです。
いかなるストリームにも、
変換が行われたり余分のパディングが現れたりすることはありません。
.Pp
プログラムの開始時には、次の 3 つのストリームが
事前に定義され、それらを明示的に開く必要はありません。
.Bl -bullet -compact -offset indent
.It
.Em 標準入力
(通常入力読み取り用)
.It
.Em 標準出力
(通常出力書込み用)
.It
.Em 標準エラー出力
(診断出力書込み用)
.El
これらのストリームは
.Em stdin ,  stdout
そして
.Em stderr
と略記されます。
初期状態では標準エラーストリームはバッファリングされていません。
標準入力および出力ストリームは、そのストリームが
.Xr isatty 3
関数で判定されるような
会話型または
.Dq 端末
デバイスへの参照でない場合に限り、完全にバッファリングされます。
実際に、端末デバイスを参照する新規に開かれた
.Em すべての
ストリームは行バッファがデフォルトであり、
このようなストリームへの保留されている出力は、
入力ストリームが読み込まれたときは常に自動的に書込まれます。
このことは、
.Dq 本当の読み込み
に対してのみ当てはまることに注意してください。
読み込み要求がバッファリングされた既存のデータで間に合う場合は、
自動的なフラッシュは起きません。
このような場合、
または出力端末に行の一部をプリントした後で大量の処理が行う場合には、
出力が現れるように、先に進んで処理を行う前に、標準出力を
.Xr fflush 3
する必要があります。
もしくは、これらのデフォルトを
.Xr setvbuf 3
関数で修正することでも可能です。
.Pp
.Nm
ライブラリはライブラリ
.Nm libc
の一部であり、
ルーチンは C コンパイラによって必要に応じて自動的にロードされます。
以下のマニュアルの
.Tn 書式
の節では、どのインクルードファイルが使用されるか、
関数に対するコンパイラの宣言がどのようになっているか、
どの外部変数が関係しているかを示します。
.Pp
以下のものはマクロとして定義されています。これらの名称は、現在の定義を
.Dv #undef
を使って削除してからでないと再使用することはできません：
.Dv BUFSIZ ,
.Dv EOF ,
.Dv FILENAME_MAX ,
.Dv FOPEN_MAX ,
.Dv L_cuserid ,
.Dv L_ctermid ,
.Dv L_tmpnam ,
.Dv NULL ,
.Dv P_tmpdir ,
.Dv SEEK_CUR ,
.Dv SEEK_END ,
.Dv SEEK_SET ,
.Dv TMP_MAX ,
.Dv clearerr ,
.Dv feof ,
.Dv ferror ,
.Dv fileno ,
.Dv fropen ,
.Dv fwopen ,
.Dv getc ,
.Dv getchar ,
.Dv putc ,
.Dv putchar ,
.Dv stderr ,
.Dv stdin ,
.Dv stdout ,
.Dv vfscanf
。
マクロ関数
.Fn clearerr ,
.Fn feof ,
.Fn ferror ,
.Fn fileno ,
.Fn getc ,
.Fn getchar ,
.Fn putc ,
および
.Fn putchar
には関数バージョンが存在し、
マクロ定義が明示的に削除された場合にはそれが使われます。
.Sh 関連項目
.Xr close 2 ,
.Xr open 2 ,
.Xr read 2 ,
.Xr write 2
.Sh バグ
標準のバッファ付き関数は、他のライブラリ関数およびシステム関数、特に
.Xr vfork 2
とはうまく相互運用することができません。
.Sh 規格
.Nm
ライブラリは、
.St -isoC
に適合しています。
.Sh 関数一覧
.Bl -column "Description"
.It Sy "関数	説明"
.It "asprintf	書式付き出力変換"
.It "clearerr	ストリームの状態のチェックとリセット"
.It "fclose	ストリームを閉じる"
.It "fdopen	ストリームを開く関数"
.It "feof	ストリームの状態のチェックとリセット"
.It "ferror	ストリームの状態のチェックとリセット"
.It "fflush	ストリームのフラッシュ"
.It "fgetc	入力ストリームから次のキャラクタまたはワードを取得"
.It "fgetln	ストリームから 1 行を取得"
.It "fgetpos	ストリームの位置指定"
.It "fgets	ストリームから 1 行を取得"
.It "fileno	ストリームの状態のチェックとリセット"
.It "fopen	ストリームを開く関数"
.It "fprintf	書式付き出力変換"
.It "fpurge	ストリームのフラッシュ"
.It "fputc	1 キャラクタまたは 1 ワードをストリームに出力"
.It "fputs	1 行をストリームに出力"
.It "fread	バイナリストリームの入力/出力"
.It "freopen	ストリームを開く関数"
.It "fropen	ストリームを開く"
.It "fscanf	書式付き入力変換"
.It "fseek	ストリームの位置指定"
.It "fsetpos	ストリームの位置指定"
.It "ftell	ストリームの位置指定"
.It "funopen	ストリームを開く"
.It "fwopen	ストリームを開く"
.It "fwrite	バイナリストリームの入力/出力"
.It "getc	入力ストリームから次のキャラクタまたはワードを取得"
.It "getchar	入力ストリームから次のキャラクタまたはワードを取得"
.It "gets	ストリームから 1 行を取得"
.It "getw	入力ストリームから次のキャラクタまたはワードを取得"
.It "mkdtemp	ユニークなテンポラリファイルを作成"
.It "mkstemp	ユニークなテンポラリファイルを作成"
.It "mktemp	ユニークなテンポラリファイルを作成"
.It "perror	システムエラーメッセージ"
.It "printf	書式付き出力変換"
.It "putc	1 キャラクタまたはワードをストリームに出力"
.It "putchar	1 キャラクタまたはワードをストリームに出力"
.It "puts	1 行をストリームに出力"
.It "putw	1 キャラクタまたはワードをストリームに出力"
.It "remove	ディレクトリエントリの削除"
.It "rewind	ストリームの位置指定"
.It "scanf	書式付き入力変換"
.It "setbuf	ストリームのバッファリング操作"
.It "setbuffer	ストリームのバッファリング操作"
.It "setlinebuf	ストリームのバッファリング操作"
.It "setvbuf	ストリームのバッファリング操作"
.It "snprintf	書式付き出力変換"
.It "sprintf	書式付き出力変換"
.It "sscanf	書式付き入力変換"
.It "strerror	システムエラーメッセージ"
.It "sys_errlist	システムエラーメッセージ"
.It "sys_nerr	システムエラーメッセージ"
.It "tempnam	テンポラリファイルルーチン"
.It "tmpfile	テンポラリファイルルーチン"
.It "tmpnam	テンポラリファイルルーチン"
.It "ungetc	入力ストリームに文字を返す"
.It "vasprintf	書式付き出力変換"
.It "vfprintf	書式付き出力変換"
.It "vfscanf	書式付き入力変換"
.It "vprintf	書式付き出力変換"
.It "vscanf	書式付き入力変換"
.It "vsnprintf	書式付き出力変換"
.It "vsprintf	書式付き出力変換"
.It "vsscanf	書式付き入力変換"
.El