Attachment 598670 Details for Bug 621953 – readdir.patch

[patch] readdir.patch

readdir.patch (text/plain), 6.18 KB, created by Peter Schiffer on 2012-07-17 15:15:11 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Peter Schiffer

Created: 2012-07-17 15:15:11 UTC

Size: 6.18 KB

patch

obsolete

>--- readdir.3.orig	2012-07-17 11:38:58.000000000 +0200
>+++ readdir.3	2012-07-17 17:09:21.564113253 +0200
>@@ -27,22 +27,29 @@
> .\" 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 <drepper@redhat.com>, mtk:
>+.\"     Rework discussion of non-standard structure fields.
>+.\" 2008-09-11, mtk, Document readdir_r().
> .\"
>-.TH READDIR 3  1996-04-22 "" "Linux Programmer's Manual"
>+.TH READDIR 3  2009-07-04 "" "Linux Programmer's Manual"
> .SH NAME
>-readdir \- read a directory
>+readdir, readdir_r \- read a directory
> .SH SYNOPSIS
> .nf
>-.B #include <sys/types.h>
>-.sp
> .B #include <dirent.h>
> .sp
>-.BI "struct dirent *readdir(DIR *" dir );
>+.BI "struct dirent *readdir(DIR *" dirp );
>+.sp
>+.BI "int readdir_r(DIR *" dirp ", struct dirent *" entry \
>+", struct dirent **" result );
> .fi
> .SH DESCRIPTION
>-The \fBreaddir\fP() function returns a pointer to a \fIdirent\fP structure
>+The
>+.BR readdir ()
>+function returns a pointer to a \fIdirent\fP structure
> representing the next directory entry in the directory stream pointed
>-to by \fIdir\fP.  It returns NULL on reaching the end-of-file or if
>+to by \fIdirp\fP.
>+It returns NULL on reaching the end of the directory stream or if
> an error occurred.
> .PP
> On Linux, the
>@@ -55,45 +62,176 @@
>     ino_t          d_ino;       /* inode number */
>     off_t          d_off;       /* offset to the next dirent */
>     unsigned short d_reclen;    /* length of this record */
>-    unsigned char  d_type;      /* type of file */
>+    unsigned char  d_type;      /* type of file; not supported
>+                                   by all file system types */
>     char           d_name[256]; /* filename */
> };
> .fi
> .RE
> .PP
>-According to POSIX, the
>+The only fields in the
> .I dirent
>-structure contains a field
>-.I "char d_name[]"
>+structure that are mandated by POSIX.1 are:
>+.IR d_name [],
> of unspecified size, with at most
> .B NAME_MAX
>-characters preceding the terminating null byte.
>-POSIX.1-2001 also documents the field
>-.I "ino_t d_ino"
>-as an XSI extension.
>-.IR "Use of other fields will harm the portability of your programs" .
>+characters preceding the terminating null byte;
>+and (as an XSI extension)
>+.IR d_ino .
>+The other fields are unstandardized, and not present on all systems;
>+see NOTES below for some further details.
> .PP
>-The data returned by \fBreaddir\fP() may be overwritten by subsequent
>-calls to \fBreaddir\fP() for the same directory stream.
>+The data returned by
>+.BR readdir ()
>+may be overwritten by subsequent calls to
>+.BR readdir ()
>+for the same directory stream.
>+
>+The
>+.BR readdir_r ()
>+function is a reentrant version of
>+.BR readdir ().
>+It reads the next directory entry from the directory stream
>+.IR dirp ,
>+and returns it in the caller-allocated buffer pointed to by
>+.IR entry .
>+(See NOTES for information on allocating this buffer.)
>+A pointer to the returned item is placed in
>+.IR *result ;
>+if the end of the directory stream was encountered,
>+then NULL is instead returned in
>+.IR *result .
> .SH "RETURN VALUE"
>-The \fBreaddir\fP() function returns a pointer to a 
>-.I dirent 
>-structure, or
>-NULL if an error occurs or end-of-file is reached.
>-On error,
>+On success,
>+.BR readdir ()
>+returns a pointer to a
>+.I dirent
>+structure.
>+(This structure may be statically allocated; do not attempt to
>+.BR free (3)
>+it.)
>+If the end of the directory stream is reached, NULL is returned and
>+.I errno
>+is not changed.
>+If an error occurs, NULL is returned and
> .I errno
> is set appropriately.
>+
>+The
>+.BR readdir_r ()
>+function returns 0 on success.
>+On error, it returns a positive error number.
>+If the end of the directory stream is reached,
>+.BR readdir_r ()
>+returns 0, and returns NULL in
>+.IR *result .
> .SH ERRORS
> .TP
> .B EBADF
>-Invalid directory stream descriptor \fIdir\fP.
>+Invalid directory stream descriptor \fIdirp\fP.
> .SH "CONFORMING TO"
> SVr4, 4.3BSD, POSIX.1-2001
>+.SH NOTES
>+Only the fields
>+.I d_name
>+and
>+.I d_ino
>+are specified in POSIX.1-2001.
>+The remaining fields are available on many, but not all systems.
>+Under glibc,
>+programs can check for the availability of the fields not defined
>+in POSIX.1 by testing whether the macros
>+.BR _DIRENT_HAVE_D_NAMLEN ,
>+.BR _DIRENT_HAVE_D_RECLEN ,
>+.BR _DIRENT_HAVE_D_OFF ,
>+or
>+.B _DIRENT_HAVE_D_TYPE
>+are defined.
>+
>+Other than Linux, the
>+.I d_type
>+field is available mainly only on BSD systems.
>+This field makes it possible to avoid the expense of calling
>+.BR lstat (2)
>+if further actions depend on the type of the file.
>+If the
>+.B _BSD_SOURCE
>+feature test macro is defined,
>+then glibc defines the following macro constants
>+for the value returned in
>+.IR d_type :
>+.TP 12
>+.B DT_BLK
>+This is a block device.
>+.TP
>+.B DT_CHR
>+This is a character device.
>+.TP
>+.B DT_DIR
>+This is a directory.
>+.TP
>+.B DT_FIFO
>+This is a named pipe (FIFO).
>+.TP
>+.B DT_LNK
>+This is a symbolic link.
>+.TP
>+.B DT_REG
>+This is a regular file.
>+.TP
>+.B DT_SOCK
>+This is a Unix domain socket.
>+.TP
>+.B DT_UNKNOWN
>+The file type is unknown.
>+.\" The glibc manual says that on some systems this is the only
>+.\" value returned
>+.PP
>+If the file type could not be determined, the value
>+.B DT_UNKNOWN
>+is returned in
>+.IR d_type .
>+
>+Currently,
>+.\" kernel 2.6.27
>+.\" The same sentence is in getdents.2
>+only some file systems (among them: Btrfs, ext2, ext3, and ext4)
>+have full support returning the file type in
>+.IR d_type .
>+All applications must properly handle a return of
>+.BR DT_UNKNOWN .
>+
>+Since POSIX.1 does not specify the size of the
>+.I d_name
>+field, and other non-standard fields may precede that field within the
>+.I dirent
>+structure, portable applications that use
>+.BR readdir_r ()
>+should allocate the buffer whose address is passed in
>+.IR entry
>+as follows:
>+.in +4n
>+.nf
>+
>+len = (offsetof(struct dirent, d_name) +
>+          pathconf(dirpath, _PC_NAME_MAX) + 1 + sizeof(long))
>+          & -sizeof(long);
>+
>+entryp = malloc(len);
>+
>+.fi
>+.in
>+(POSIX.1 requires that
>+.I d_name
>+is the last field in a
>+.IR "struct dirent" .)
> .SH "SEE ALSO"
>+.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),

Actions: View | Diff

Attachments on bug 621953: 437184 | 587263 | 598637 | 598670