LDP: Update original to LDP v3.68

[linuxjm/LDP_man-pages.git] / original / man3 / telldir.3

diff --git a/original/man3/telldir.3 b/original/man3/telldir.3
index 549bcae..a027fbd 100644 (file)
--- a/original/man3/telldir.3
+++ b/original/man3/telldir.3
@@ -27,7 +27,7 @@
 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
 .\"     386BSD man pages
 .\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith (faith@cs.unc.edu)
-.TH TELLDIR 3  2009-03-11 "" "Linux Programmer's Manual"
+.TH TELLDIR 3  2013-09-02 "" "Linux Programmer's Manual"
 .SH NAME
 telldir \- return current location in directory stream
 .SH SYNOPSIS
@@ -61,6 +61,11 @@ is set appropriately.
 .TP
 .B EBADF
 Invalid directory stream descriptor \fIdirp\fP.
+.SH ATTRIBUTES
+.SS Multithreading (see pthreads(7))
+The
+.BR telldir ()
+function is thread-safe.
 .SH CONFORMING TO
 4.3BSD, POSIX.1-2001.
 .SH NOTES
@@ -71,6 +76,22 @@ was
 POSIX.1-2001 specifies
 .IR long ,
 and this is the type used since glibc 2.1.2.
+
+In early filesystems, the value returned by
+.BR telldir ()
+was a simple file offset within a directory.
+Modern filesystems use tree or hash structures, rather than flat tables,
+to represent directories.
+On such filesystems, the value returned by
+.BR telldir ()
+(and used internally by
+.BR readdir (3))
+is a "cookie" that is used by the implementation
+to derive a position within a directory.
+.\" https://lwn.net/Articles/544298/
+Application programs should treat this strictly as an opaque value, making
+.I no
+assumptions about its contents.
 .SH SEE ALSO
 .BR closedir (3),
 .BR opendir (3),
@@ -78,3 +99,12 @@ and this is the type used since glibc 2.1.2.
 .BR rewinddir (3),
 .BR scandir (3),
 .BR seekdir (3)
+.SH COLOPHON
+This page is part of release 3.68 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.