Debian Codegraph @

upstream/debian-unstable/man3/telldir.3

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