.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" References consulted: .\" Linux libc source code .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) .\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) .\" 2007-07-30 Ulrich Drepper , mtk: .\" Rework discussion of nonstandard structure fields. .\" 2008-09-11, mtk, Document readdir_r(). .\" .\" Japanese Version Copyright (c) 1997 HIROFUMI Nishizuka .\" all rights reserved. .\" Translated 1997-12-24, HIROFUMI Nishizuka .\" Updated & Modified 2002-03-24, Yuichi SATO .\" Updated & Modified 2005-01-16, Yuichi SATO .\" Updated & Modified 2005-09-06, Akihiro MOTOKI .\" Updated 2008-08-11, Akihiro MOTOKI , LDP v3.05 .\" .TH READDIR 3 2010-09-10 "" "Linux Programmer's Manual" .\"O .SH NAME .SH 名前 .\"O readdir, readdir_r \- read a directory readdir, readdir_r \- ディレクトリを読み込む .\"O .SH SYNOPSIS .SH 書式 .nf .B #include .sp .BI "struct dirent *readdir(DIR *" dirp ); .sp .BI "int readdir_r(DIR *" dirp ", struct dirent *" entry \ ", struct dirent **" result ); .fi .sp .in -4n .\"O Feature Test Macro Requirements for glibc (see .\"O .BR feature_test_macros (7)): glibc 向けの機能検査マクロの要件 .RB ( feature_test_macros (7) 参照): .ad l .in .sp .BR readdir_r (): .RS 4 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE .RE .ad b .\"O .SH DESCRIPTION .SH 説明 .\"O The .\"O .BR readdir () .\"O function returns a pointer to a \fIdirent\fP structure .\"O representing the next directory entry in the directory stream pointed .\"O to by \fIdirp\fP. .\"O It returns NULL on reaching the end of the directory stream or if .\"O an error occurred. .BR readdir () 関数は、\fIdirp\fP が指すディレクトリストリームの中で、 次のディレクトリエントリを表す \fIdirent\fP 構造体へのポインタを返す。 ディレクトリストリームの末尾に達した場合や、 エラーが発生した場合は、 NULL を返す。 .PP .\"O On Linux, the .\"O .I dirent .\"O structure is defined as follows: Linux では .I dirent 構造体は以下のように定義されている。 .PP .in +4n .nf struct dirent { .\"O ino_t d_ino; /* inode number */ .\"O off_t d_off; /* offset to the next dirent */ .\"O unsigned short d_reclen; /* length of this record */ .\"O unsigned char d_type; /* type of file; not supported .\"O by all file system types */ .\"O char d_name[256]; /* filename */ ino_t d_ino; /* inode 番号 */ off_t d_off; /* 次の dirent へのオフセット */ unsigned short d_reclen; /* このレコードの長さ */ unsigned char d_type; /* ファイル種別。全ファイルシステム */ でサポートされているわけではない */ char d_name[256]; /* ファイル名 */ }; .fi .in .PP .\"O The only fields in the .\"O .I dirent .\"O structure that are mandated by POSIX.1 are: .\"O .IR d_name [], .\"O of unspecified size, with at most .\"O .B NAME_MAX .\"O characters preceding the terminating null byte; .\"O and (as an XSI extension) .\"O .IR d_ino . .I dirent 構造体のフィールドで POSIX.1 で要求されているのは、 .IR d_name [] と (XSI 拡張での) .I d_ino だけである。 .IR d_name [] はその大きさも規定されておらず、 このフィールドには最大で .B NAME_MAX 個の文字と、それに続く終端の NULL バイトが格納される。 .\"O The other fields are unstandardized, and not present on all systems; .\"O see NOTES below for some further details. 他のフィールドは非標準であり、全てのシステムに存在するわけではない。 詳細については、下記の「注意」を参照のこと。 .PP .\"O The data returned by .\"O .BR readdir () .\"O may be overwritten by subsequent calls to .\"O .BR readdir () .\"O for the same directory stream. .BR readdir () によって返されるデータは、それ以降の同じストリームに対する .BR readdir () の呼び出しによって上書きされる可能性がある。 .\"O The .\"O .BR readdir_r () .\"O function is a reentrant version of .\"O .BR readdir (). .\"O It reads the next directory entry from the directory stream .\"O .IR dirp , .\"O and returns it in the caller-allocated buffer pointed to by .\"O .IR entry . .\"O (See NOTES for information on allocating this buffer.) .\"O A pointer to the returned item is placed in .\"O .IR *result ; .\"O if the end of the directory stream was encountered, .\"O then NULL is instead returned in .\"O .IR *result . .BR readdir_r () 関数は .BR readdir () のリエントラント版である。 この関数はディレクトリストリーム .I dirp から次のディレクトリエントリを読み込み、 .I entry が指す呼び出し元が割り当てたバッファにそのエントリを格納して返す (このバッファの割り当てについては「注意」の節を参照のこと)。 返されるエントリへのポインタが .I *result に格納される。ディレクトリストリームの末尾に達した場合は、 NULL が .I *result に格納される。 .\"O .SH "RETURN VALUE" .SH 返り値 .\"O On success, .\"O .BR readdir () .\"O returns a pointer to a .\"O .I dirent .\"O structure. .\"O (This structure may be statically allocated; do not attempt to .\"O .BR free (3) .\"O it.) .\"O If the end of the directory stream is reached, NULL is returned and .\"O .I errno .\"O is not changed. 成功すると、 .BR readdir () は .I dirent 構造体へのポインタを返す。 (この構造体は静的に割り当てられているかもしれない。 このポインタを .BR free (3) しようとしないこと。) ディレクトリストリームの末尾に達した場合には、NULL が返され、 .I errno は変化しない。 .\"O If an error occurs, NULL is returned and .\"O .I errno .\"O is set appropriately. エラーが発生した場合、NULL が返され、 .I errno が適切に設定される。 .\"O The .\"O .BR readdir_r () .\"O function returns 0 on success. .\"O On error, it returns a positive error number (listed under ERRORS). .\"O If the end of the directory stream is reached, .\"O .BR readdir_r () .\"O returns 0, and returns NULL in .\"O .IR *result . 成功すると、 .BR readdir_r () 関数は 0 を返す。 エラーの場合、(「エラー」の節のリストに載っている) 正のエラー番号を返す。 ディレクトリストリームの末尾に達した場合、 .BR readdir_r () は返り値として 0 を返し、 .I *result に NULL を格納する。 .\"O .SH ERRORS .SH エラー .TP .B EBADF .\"O Invalid directory stream descriptor \fIdirp\fP. ディレクトリストリームディスクリプタ \fIdirp\fP が無効。 .\"O .SH "CONFORMING TO" .SH 準拠 SVr4, 4.3BSD, POSIX.1-2001. .\"O .SH NOTES .SH 注意 .\"O Only the fields .\"O .I d_name .\"O and .\"O .I d_ino .\"O are specified in POSIX.1-2001. .\"O The remaining fields are available on many, but not all systems. .\"O Under glibc, .\"O programs can check for the availability of the fields not defined .\"O in POSIX.1 by testing whether the macros .\"O .BR _DIRENT_HAVE_D_NAMLEN , .\"O .BR _DIRENT_HAVE_D_RECLEN , .\"O .BR _DIRENT_HAVE_D_OFF , .\"O or .\"O .B _DIRENT_HAVE_D_TYPE .\"O are defined. フィールド .I d_name と .I d_ino だけが POSIX.1-2001 で規定されている。 残りのフィールドは多くのシステムに存在するが、全てのシステムに 存在するわけではない。 glibc では、プログラムが POSIX.1 で定義されていないフィールドが 利用できるかをチェックすることができる。 チェックするには、マクロ .BR _DIRENT_HAVE_D_NAMLEN , .BR _DIRENT_HAVE_D_RECLEN , .BR _DIRENT_HAVE_D_OFF , .B _DIRENT_HAVE_D_TYPE が定義されているかをテストすればよい。 .\"O Other than Linux, the .\"O .I d_type .\"O field is available mainly only on BSD systems. .I d_type フィールドは、Linux 以外では、 主に BSD 系のシステムにだけ存在する。 .\"O This field makes it possible to avoid the expense of calling .\"O .BR lstat (2) .\"O if further actions depend on the type of the file. このフィールドを使うと、 その後の動作がファイルの種別により決まる場合に、 .BR lstat (2) を呼び出すコストを避けることができる。 .\"O If the .\"O .B _BSD_SOURCE .\"O feature test macro is defined, .\"O then glibc defines the following macro constants .\"O for the value returned in .\"O .IR d_type : 機能検査マクロ .B _BSD_SOURCE が定義された場合、glibc は .I d_type で返される値として以下のマクロ定数を定義する。 .TP 12 .B DT_BLK .\"O This is a block device. ブロック・デバイスである。 .TP .B DT_CHR .\"O This is a character device. キャラクタ・デバイスである。 .TP .B DT_DIR .\"O This is a directory. ディレクトリである。 .TP .B DT_FIFO .\"O This is a named pipe (FIFO). 名前付きパイプ (FIFO) である。 .TP .B DT_LNK .\"O This is a symbolic link. シンボリック・リンクである。 .TP .B DT_REG .\"O This is a regular file. 通常のファイルである。 .TP .B DT_SOCK .\"O This is a UNIX domain socket. UNIX ドメインソケットである。 .TP .B DT_UNKNOWN .\"O The file type is unknown. ファイルタイプが不明である。 .\" The glibc manual says that on some systems this is the only .\" value returned .PP .\"O If the file type could not be determined, the value .\"O .B DT_UNKNOWN .\"O is returned in .\"O .IR d_type . ファイル種別を決定できなかった場合には、 .I d_type に .B DT_UNKNOWN が入る。 .\"O Currently, .\"O .\" kernel 2.6.27 .\"O .\" The same sentence is in readdir.2 .\"O only some file systems (among them: Btrfs, ext2, etx3, and ext4) .\"O have full support returning the file type in .\"O .IR d_type . .\"O All applications must properly handle a return of .\"O .BR DT_UNKNOWN . 現在のところ、 .\" カーネル 2.6.27 .\" 同じ説明文が readdir.2 にもある。 .I d_type でファイルタイプを返す機能が完全にサポートされているのは、 いくつかのファイルシステムにおいてのみである (Btrfs, ext2, ext3, ext4 はサポートしている)。 どのアプリケーションも、 .B DT_UNKNOWN が返された際に適切に処理できなければならない。 .\"O Since POSIX.1 does not specify the size of the .\"O .I d_name .\"O field, and other nonstandard fields may precede that field within the .\"O .I dirent .\"O structure, portable applications that use .\"O .BR readdir_r () .\"O should allocate the buffer whose address is passed in .\"O .IR entry .\"O as follows: POSIX.1 では .I d_name フィールドのサイズは規定されておらず、 .I dirent 構造体の .I d_name の後ろに他の非標準のフィールドがあるかもしれないので、 移植性が必要なアプリケーションで .BR readdir_r () を使う場合は .I entry に渡すバッファを次のようにして割り当てるべきである。 .in +4n .nf len = offsetof(struct dirent, d_name) + pathconf(dirpath, _PC_NAME_MAX) + 1 entryp = malloc(len); .fi .in .\"O (POSIX.1 requires that .\"O .I d_name .\"O is the last field in a .\"O .IR "struct dirent" .) (POSIX.1 では .I "struct dirent" の最後のフィールドが .I d_name であることを要求している。) .\"O .SH "SEE ALSO" .SH 関連項目 .BR getdents (2), .BR read (2), .BR closedir (3), .BR dirfd (3), .BR ftw (3), .BR offsetof (3), .BR opendir (3), .BR rewinddir (3), .BR scandir (3), .BR seekdir (3), .BR telldir (3)