man3/telldir.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith (faith@cs.unc.edu)
  10 .TH TELLDIR 3  2021-03-22 "" "Linux Programmer's Manual"
  11 .SH NAME
  12 telldir \- return current location in directory stream
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <dirent.h>
  19 .PP
  20 .BI "long telldir(DIR *" dirp );
  21 .fi
  22 .PP
  23 .RS -4
  24 Feature Test Macro Requirements for glibc (see
  25 .BR feature_test_macros (7)):
  26 .RE
  27 .PP
  28 .BR telldir ():
  29 .nf
  30     _XOPEN_SOURCE
  31        || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  32        || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  33 .fi
  34 .SH DESCRIPTION
  35 The
  36 .BR telldir ()
  37 function returns the current location associated with
  38 the directory stream \fIdirp\fP.
  39 .SH RETURN VALUE
  40 On success, the
  41 .BR telldir ()
  42 function returns the current location
  43 in the directory stream.
  44 On error, \-1 is returned, and
  45 .I errno
  46 is set to indicate the error.
  47 .SH ERRORS
  48 .TP
  49 .B EBADF
  50 Invalid directory stream descriptor \fIdirp\fP.
  51 .SH ATTRIBUTES
  52 For an explanation of the terms used in this section, see
  53 .BR attributes (7).
  54 .ad l
  55 .nh
  56 .TS
  57 allbox;
  58 lbx lb lb
  59 l l l.
  60 Interface       Attribute       Value
  61 T{
  62 .BR telldir ()
  63 T}      Thread safety   MT-Safe
  64 .TE
  65 .hy
  66 .ad
  67 .sp 1
  68 .SH CONFORMING TO
  69 POSIX.1-2001, POSIX.1-2008, 4.3BSD.
  70 .SH NOTES
  71 In glibc up to version 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 .PP
  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)