release/man3/readdir.3

   1 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu)
  30 .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl)
  31 .\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl)
  32 .\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk:
  33 .\"     Rework discussion of nonstandard structure fields.
  34 .\" 2008-09-11, mtk, Document readdir_r().
  35 .\"
  36 .\"*******************************************************************
  37 .\"
  38 .\" This file was generated with po4a. Translate the source file.
  39 .\"
  40 .\"*******************************************************************
  41 .\"
  42 .\" Japanese Version Copyright (c) 1997 HIROFUMI Nishizuka
  43 .\"     all rights reserved.
  44 .\" Translated 1997-12-24, HIROFUMI Nishizuka <nishi@rpts.cl.nec.co.jp>
  45 .\" Updated & Modified 2002-03-24, Yuichi SATO <ysato@h4.dion.ne.jp>
  46 .\" Updated & Modified 2005-01-16, Yuichi SATO <ysato444@yahoo.co.jp>
  47 .\" Updated & Modified 2005-09-06, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  48 .\" Updated 2008-08-11, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.05
  49 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  50 .\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  51 .\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
  52 .\"
  53 .TH READDIR 3 2013\-06\-21 "" "Linux Programmer's Manual"
  54 .SH 名前
  55 readdir, readdir_r \- ディレクトリを読み込む
  56 .SH 書式
  57 .nf
  58 \fB#include <dirent.h>\fP
  59 .sp
  60 \fBstruct dirent *readdir(DIR *\fP\fIdirp\fP\fB);\fP
  61 .sp
  62 \fBint readdir_r(DIR *\fP\fIdirp\fP\fB, struct dirent *\fP\fIentry\fP\fB, struct dirent **\fP\fIresult\fP\fB);\fP
  63 .fi
  64 .sp
  65 .in -4n
  66 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  67 .ad l
  68 .in
  69 .sp
  70 \fBreaddir_r\fP():
  71 .RS 4
  72 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
  73 || _POSIX_SOURCE
  74 .RE
  75 .ad b
  76 .SH 説明
  77 \fBreaddir\fP()  関数は、\fIdirp\fP が指すディレクトリストリームの中で、 次のディレクトリエントリを表す \fIdirent\fP
  78 構造体へのポインタを返す。 ディレクトリストリームの末尾に達した場合や、 エラーが発生した場合は、 NULL を返す。
  79 .PP
  80 Linux では \fIdirent\fP 構造体は以下のように定義されている。
  81 .PP
  82 .in +4n
  83 .nf
  84 struct dirent {
  85     ino_t          d_ino;       /* inode number */
  86     off_t          d_off;       /* not an offset; see NOTES */
  87     unsigned short d_reclen;    /* length of this record */
  88     unsigned char  d_type;      /* type of file; not supported
  89                                    by all filesystem types */
  90     char           d_name[256]; /* filename */
  91 };
  92 .fi
  93 .in
  94 .PP
  95 \fIdirent\fP 構造体のフィールドで POSIX.1 で要求されているのは、 \fId_name\fP[] と (XSI 拡張での)  \fId_ino\fP
  96 だけである。 \fId_name\fP[] はその大きさも規定されておらず、 このフィールドには最大で \fBNAME_MAX\fP 個の文字と、それに続く終端の
  97 NULL バイト (\(aq\e0\(aq)が格納される。 他のフィールドは非標準であり、全てのシステムに存在するわけではない。
  98 詳細については、下記の「注意」を参照のこと。
  99 .PP
 100 \fBreaddir\fP()  によって返されるデータは、それ以降の同じストリームに対する \fBreaddir\fP()
 101 の呼び出しによって上書きされる可能性がある。
 102
 103 \fBreaddir_r\fP()  関数は \fBreaddir\fP()  のリエントラント版である。 この関数はディレクトリストリーム \fIdirp\fP
 104 から次のディレクトリエントリを読み込み、 \fIentry\fP が指す呼び出し元が割り当てたバッファにそのエントリを格納して返す
 105 (このバッファの割り当てについては「注意」の節を参照のこと)。 返されるエントリへのポインタが \fI*result\fP
 106 に格納される。ディレクトリストリームの末尾に達した場合は、 NULL が \fI*result\fP に格納される。
 107 .SH 返り値
 108 成功すると、 \fBreaddir\fP()  は \fIdirent\fP 構造体へのポインタを返す。 (この構造体は静的に割り当てられているかもしれない。
 109 このポインタを \fBfree\fP(3)  しようとしないこと。)  ディレクトリストリームの末尾に達した場合には、NULL が返され、 \fIerrno\fP
 110 は変化しない。 エラーが発生した場合、NULL が返され、 \fIerrno\fP が適切に設定される。
 111
 112 成功すると、 \fBreaddir_r\fP()  関数は 0 を返す。 エラーの場合、(「エラー」の節のリストに載っている) 正のエラー番号を返す。
 113 ディレクトリストリームの末尾に達した場合、 \fBreaddir_r\fP()  は返り値として 0 を返し、 \fI*result\fP に NULL
 114 を格納する。
 115 .SH エラー
 116 .TP
 117 \fBEBADF\fP
 118 ディレクトリストリームディスクリプタ \fIdirp\fP が無効である。
 119 .SH 属性
 120 .SS "マルチスレッディング (pthreads(7) 参照)"
 121 \fBreaddir\fP() 関数はスレッドセーフではない。
 122 .LP
 123 \fBreaddir_r\fP() 関数はスレッドセーフである。
 124 .SH 準拠
 125 SVr4, 4.3BSD, POSIX.1\-2001.
 126 .SH 注意
 127 フィールド \fId_name\fP と \fId_ino\fP だけが POSIX.1\-2001 で規定されている。
 128 残りのフィールドは多くのシステムに存在するが、全てのシステムに 存在するわけではない。 glibc では、プログラムが POSIX.1
 129 で定義されていないフィールドが 利用できるかをチェックすることができる。 チェックするには、マクロ \fB_DIRENT_HAVE_D_NAMLEN\fP,
 130 \fB_DIRENT_HAVE_D_RECLEN\fP, \fB_DIRENT_HAVE_D_OFF\fP, \fB_DIRENT_HAVE_D_TYPE\fP
 131 が定義されているかをテストすればよい。
 132
 133 .\" https://lwn.net/Articles/544298/
 134 The value returned in \fId_off\fP is the same as would be returned by calling
 135 \fBtelldir\fP(3)  at the current position in the directory stream.  Be aware
 136 that despite its type and name, the \fId_off\fP field is seldom any kind of
 137 directory offset on modern filesystems.  Applications should treat this
 138 field as an opaque value, making no assumptions about its contents; see also
 139 \fBtelldir\fP(3).
 140
 141 \fId_type\fP フィールドは、Linux 以外では、 主に BSD 系のシステムにだけ存在する。 このフィールドを使うと、
 142 その後の動作がファイルの種別により決まる場合に、 \fBlstat\fP(2)  を呼び出すコストを避けることができる。 機能検査マクロ
 143 \fB_BSD_SOURCE\fP が定義された場合、glibc は \fId_type\fP で返される値として以下のマクロ定数を定義する。
 144 .TP  12
 145 \fBDT_BLK\fP
 146 ブロックデバイスである。
 147 .TP
 148 \fBDT_CHR\fP
 149 キャラクタデバイスである。
 150 .TP
 151 \fBDT_DIR\fP
 152 ディレクトリである。
 153 .TP
 154 \fBDT_FIFO\fP
 155 名前付きパイプ (FIFO) である。
 156 .TP
 157 \fBDT_LNK\fP
 158 シンボリックリンクである。
 159 .TP
 160 \fBDT_REG\fP
 161 通常のファイルである。
 162 .TP
 163 \fBDT_SOCK\fP
 164 UNIX ドメインソケットである。
 165 .TP
 166 \fBDT_UNKNOWN\fP
 167 .\" The glibc manual says that on some systems this is the only
 168 .\" value returned
 169 ファイルタイプが不明である。
 170 .PP
 171 ファイル種別を決定できなかった場合には、 \fId_type\fP に \fBDT_UNKNOWN\fP が入る。
 172
 173 .\" kernel 2.6.27
 174 .\" The same sentence is in getdents.2
 175 Currently, only some filesystems (among them: Btrfs, ext2, ext3, and ext4)
 176 have full support for returning the file type in \fId_type\fP.  All
 177 applications must properly handle a return of \fBDT_UNKNOWN\fP.
 178
 179 POSIX.1 では \fId_name\fP フィールドのサイズは規定されておらず、 \fIdirent\fP 構造体の \fId_name\fP
 180 の後ろに他の非標準のフィールドがあるかもしれないので、 移植性が必要なアプリケーションで \fBreaddir_r\fP()  を使う場合は \fIentry\fP
 181 に渡すバッファを次のようにして割り当てるべきである。
 182 .in +4n
 183 .nf
 184
 185 name_max = pathconf(dirpath, _PC_NAME_MAX);
 186 if (name_max == \-1)         /* 上限が定義されていない、またはエラー */
 187     name_max = 255;         /* 適当な値を入れる */
 188 len = offsetof(struct dirent, d_name) + name_max + 1;
 189 entryp = malloc(len);
 190
 191 .fi
 192 .in
 193 (POSIX.1 では \fIstruct dirent\fP の最後のフィールドが \fId_name\fP であることを要求している。)
 194 .SH 関連項目
 195 \fBgetdents\fP(2), \fBread\fP(2), \fBclosedir\fP(3), \fBdirfd\fP(3), \fBftw\fP(3),
 196 \fBoffsetof\fP(3), \fBopendir\fP(3), \fBrewinddir\fP(3), \fBscandir\fP(3),
 197 \fBseekdir\fP(3), \fBtelldir\fP(3)
 198 .SH この文書について
 199 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.54 の一部
 200 である。プロジェクトの説明とバグ報告に関する情報は
 201 http://www.kernel.org/doc/man\-pages/ に書かれている。