Debian Codegraph @

upstream/debian-trixie/man3/telldir.3

raw
1 '\" t
2 .\" Copyright 1993 David Metcalfe ([email protected])
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" References consulted:
7 .\" Linux libc source code
8 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
9 .\" 386BSD man pages
10 .\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith ([email protected])
11 .TH telldir 3 2024-05-02 "Linux man-pages 6.9.1"
12 .SH NAME
13 telldir \- return current location in directory stream
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ", " \-lc )
17 .SH SYNOPSIS
18 .nf
19 .B #include <dirent.h>
20 .P
21 .BI "long telldir(DIR *" dirp );
22 .fi
23 .P
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR telldir ():
30 .nf
31 _XOPEN_SOURCE
32 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
33 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR telldir ()
38 function returns the current location associated with
39 the directory stream \fIdirp\fP.
40 .SH RETURN VALUE
41 On success, the
42 .BR telldir ()
43 function returns the current location
44 in the directory stream.
45 On error, \-1 is returned, and
46 .I errno
47 is set to indicate the error.
48 .SH ERRORS
49 .TP
50 .B EBADF
51 Invalid directory stream descriptor \fIdirp\fP.
52 .SH ATTRIBUTES
53 For an explanation of the terms used in this section, see
54 .BR attributes (7).
55 .TS
56 allbox;
57 lbx lb lb
58 l l l.
59 Interface Attribute Value
60 T{
61 .na
62 .nh
63 .BR telldir ()
64 T} Thread safety MT-Safe
65 .TE
66 .SH STANDARDS
67 POSIX.1-2008.
68 .SH HISTORY
69 POSIX.1-2001, 4.3BSD.
70 .P
71 Up to glibc 2.1.1, the return type of
72 .BR telldir ()
73 was
74 .IR off_t .
75 POSIX.1-2001 specifies
76 .IR long ,
77 and this is the type used since glibc 2.1.2.
78 .P
79 In early filesystems, the value returned by
80 .BR telldir ()
81 was a simple file offset within a directory.
82 Modern filesystems use tree or hash structures, rather than flat tables,
83 to represent directories.
84 On such filesystems, the value returned by
85 .BR telldir ()
86 (and used internally by
87 .BR readdir (3))
88 is a "cookie" that is used by the implementation
89 to derive a position within a directory.
90 .\" https://lwn.net/Articles/544298/
91 Application programs should treat this strictly as an opaque value, making
92 .I no
93 assumptions about its contents.
94 .SH SEE ALSO
95 .BR closedir (3),
96 .BR opendir (3),
97 .BR readdir (3),
98 .BR rewinddir (3),
99 .BR scandir (3),
100 .BR seekdir (3)