lib/libc/sys/getdirentries.2

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)getdirentries.2     8.2 (Berkeley) 5/3/95
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd March 30, 2020
  32 .Dt GETDIRENTRIES 2
  33 .Os
  34 .Sh NAME
  35 .Nm getdirentries ,
  36 .Nm getdents
  37 .Nd "get directory entries in a file system independent format"
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In dirent.h
  43 .Ft ssize_t
  44 .Fn getdirentries "int fd" "char *buf" "size_t nbytes" "off_t *basep"
  45 .Ft ssize_t
  46 .Fn getdents "int fd" "char *buf" "size_t nbytes"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn getdirentries
  50 and
  51 .Fn getdents
  52 system calls read directory entries from the directory
  53 referenced by the file descriptor
  54 .Fa fd
  55 into the buffer pointed to by
  56 .Fa buf ,
  57 in a file system independent format.
  58 Up to
  59 .Fa nbytes
  60 of data will be transferred.
  61 The
  62 .Fa nbytes
  63 argument must be greater than or equal to the
  64 block size associated with the file,
  65 see
  66 .Xr stat 2 .
  67 Some file systems may not support these system calls
  68 with buffers smaller than this size.
  69 .Pp
  70 The data in the buffer is a series of
  71 .Vt dirent
  72 structures each containing the following entries:
  73 .Bd -literal -offset indent
  74 ino_t   d_fileno;
  75 off_t   d_off;
  76 uint16_t        d_reclen;
  77 uint8_t d_type;
  78 uint16_t        d_namlen;
  79 char    d_name[MAXNAMLEN + 1];  /* see below */
  80 .Ed
  81 .Pp
  82 The
  83 .Fa d_fileno
  84 entry is a number which is unique for each
  85 distinct file in the file system.
  86 Files that are linked by hard links (see
  87 .Xr link 2 )
  88 have the same
  89 .Fa d_fileno .
  90 The
  91 .Fa d_off
  92 field returns a cookie which can be used with
  93 .Xr lseek 2
  94 to position the directory descriptor to the next entry.
  95 The
  96 .Fa d_reclen
  97 entry is the length, in bytes, of the directory record.
  98 The
  99 .Fa d_type
 100 entry is the type of the file pointed to by the directory record.
 101 The file type values are defined in
 102 .Fa <sys/dirent.h> .
 103 The
 104 .Fa d_name
 105 entry contains a null terminated file name.
 106 The
 107 .Fa d_namlen
 108 entry specifies the length of the file name excluding the null byte.
 109 Thus the actual size of
 110 .Fa d_name
 111 may vary from 1 to
 112 .Dv MAXNAMLEN
 113 \&+ 1.
 114 .Pp
 115 Entries may be separated by extra space.
 116 The
 117 .Fa d_reclen
 118 entry may be used as an offset from the start of a
 119 .Fa dirent
 120 structure to the next structure, if any.
 121 .Pp
 122 The actual number of bytes transferred is returned.
 123 The current position pointer associated with
 124 .Fa fd
 125 is set to point to the next block of entries.
 126 The pointer may not advance by the number of bytes returned by
 127 .Fn getdirentries
 128 or
 129 .Fn getdents .
 130 A value of zero is returned when
 131 the end of the directory has been reached.
 132 .Pp
 133 If the
 134 .Fa basep
 135 pointer value is non-NULL ,
 136 the
 137 .Fn getdirentries
 138 system call writes the position of the block read into the location pointed to by
 139 .Fa basep .
 140 Alternatively, the current position pointer may be set and retrieved by
 141 .Xr lseek 2 .
 142 The current position pointer should only be set to a value returned by
 143 .Xr lseek 2 ,
 144 a value returned in the location pointed to by
 145 .Fa basep
 146 .Po Fn getdirentries
 147 only
 148 .Pc ,
 149 a value returned in the
 150 .Fa d_off
 151 field,
 152 or zero.
 153 .Sh IMPLEMENTATION NOTES
 154 The
 155 .Fa d_off
 156 field is being used as a cookie to readdir for nfs servers.
 157 These cookies can be cached and allow to read directory entries at a specific
 158 offset on demand.
 159 .Sh RETURN VALUES
 160 If successful, the number of bytes actually transferred is returned.
 161 Otherwise, -1 is returned and the global variable
 162 .Va errno
 163 is set to indicate the error.
 164 .Sh ERRORS
 165 The
 166 .Fn getdirentries
 167 system call
 168 will fail if:
 169 .Bl -tag -width Er
 170 .It Bq Er EBADF
 171 The
 172 .Fa fd
 173 argument
 174 is not a valid file descriptor open for reading.
 175 .It Bq Er EFAULT
 176 Either
 177 .Fa buf
 178 or non-NULL
 179 .Fa basep
 180 point outside the allocated address space.
 181 .It Bq Er EINVAL
 182 The file referenced by
 183 .Fa fd
 184 is not a directory, or
 185 .Fa nbytes
 186 is too small for returning a directory entry or block of entries,
 187 or the current position pointer is invalid.
 188 .It Bq Er EIO
 189 An
 190 .Tn I/O
 191 error occurred while reading from or writing to the file system.
 192 .It Bq Er EINTEGRITY
 193 Corrupted data was detected while reading from the file system.
 194 .El
 195 .Sh SEE ALSO
 196 .Xr lseek 2 ,
 197 .Xr open 2
 198 .Sh HISTORY
 199 The
 200 .Fn getdirentries
 201 system call first appeared in
 202 .Bx 4.4 .
 203 The
 204 .Fn getdents
 205 system call first appeared in
 206 .Fx 3.0 .