LDP: Update original to LDP v3.79

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

diff --git a/original/man3/telldir.3 b/original/man3/telldir.3
index d54779c..f045992 100644 (file)
--- a/original/man3/telldir.3
+++ b/original/man3/telldir.3
@@ -1,5 +1,6 @@
 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
 .\"
+.\" %%%LICENSE_START(VERBATIM)
 .\" 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.
@@ -19,13 +20,14 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
 .\"
 .\" References consulted:
 .\"     Linux libc source code
 .\"     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
@@ -47,7 +49,7 @@ The
 .BR telldir ()
 function returns the current location associated with
 the directory stream \fIdirp\fP.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 On success, the
 .BR telldir ()
 function returns the current location
@@ -59,7 +61,12 @@ is set appropriately.
 .TP
 .B EBADF
 Invalid directory stream descriptor \fIdirp\fP.
-.SH "CONFORMING TO"
+.SH ATTRIBUTES
+.SS Multithreading (see pthreads(7))
+The
+.BR telldir ()
+function is thread-safe.
+.SH CONFORMING TO
 4.3BSD, POSIX.1-2001.
 .SH NOTES
 In glibc up to version 2.1.1, the return type of
@@ -69,10 +76,35 @@ was
 POSIX.1-2001 specifies
 .IR long ,
 and this is the type used since glibc 2.1.2.
-.SH "SEE ALSO"
+
+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),
 .BR readdir (3),
 .BR rewinddir (3),
 .BR scandir (3),
 .BR seekdir (3)
+.SH COLOPHON
+This page is part of release 3.79 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/.