telldir(3)

1telldir(3)                 Library Functions Manual                 telldir(3)
2
3
4

NAME

6       telldir - return current location in directory stream
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <dirent.h>
13
14       long telldir(DIR *dirp);
15
16   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
17
18       telldir():
19           _XOPEN_SOURCE
20              || /* glibc >= 2.19: */ _DEFAULT_SOURCE
21              || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
22

DESCRIPTION

24       The telldir() function returns the current location associated with the
25       directory stream dirp.
26

RETURN VALUE

28       On success, the telldir() function returns the current location in  the
29       directory  stream.  On error, -1 is returned, and errno is set to indi‐
30       cate the error.
31

ERRORS

33       EBADF  Invalid directory stream descriptor dirp.
34

ATTRIBUTES

36       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
37       tributes(7).
38
39       ┌────────────────────────────────────────────┬───────────────┬─────────┐
40       │Interface                                   │ Attribute     │ Value   │
41       ├────────────────────────────────────────────┼───────────────┼─────────┤
42       │telldir()                                   │ Thread safety │ MT-Safe │
43       └────────────────────────────────────────────┴───────────────┴─────────┘
44

STANDARDS

46       POSIX.1-2008.
47

HISTORY

49       POSIX.1-2001, 4.3BSD.
50
51       Up   to   glibc   2.1.1,  the  return  type  of  telldir()  was  off_t.
52       POSIX.1-2001 specifies long, and this is  the  type  used  since  glibc
53       2.1.2.
54
55       In early filesystems, the value returned by telldir() was a simple file
56       offset within a directory.  Modern filesystems use tree or hash  struc‐
57       tures,  rather  than  flat  tables,  to represent directories.  On such
58       filesystems, the value returned by telldir() (and  used  internally  by
59       readdir(3))  is a "cookie" that is used by the implementation to derive
60       a position within a directory.  Application programs should treat  this
61       strictly as an opaque value, making no assumptions about its contents.
62