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 May 28, 2017
  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_reclen
  92 entry is the length, in bytes, of the directory record.
  93 The
  94 .Fa d_type
  95 entry is the type of the file pointed to by the directory record.
  96 The file type values are defined in
  97 .Fa <sys/dirent.h> .
  98 The
  99 .Fa d_name
 100 entry contains a null terminated file name.
 101 The
 102 .Fa d_namlen
 103 entry specifies the length of the file name excluding the null byte.
 104 Thus the actual size of
 105 .Fa d_name
 106 may vary from 1 to
 107 .Dv MAXNAMLEN
 108 \&+ 1.
 109 .Pp
 110 Entries may be separated by extra space.
 111 The
 112 .Fa d_reclen
 113 entry may be used as an offset from the start of a
 114 .Fa dirent
 115 structure to the next structure, if any.
 116 .Pp
 117 The actual number of bytes transferred is returned.
 118 The current position pointer associated with
 119 .Fa fd
 120 is set to point to the next block of entries.
 121 The pointer may not advance by the number of bytes returned by
 122 .Fn getdirentries
 123 or
 124 .Fn getdents .
 125 A value of zero is returned when
 126 the end of the directory has been reached.
 127 .Pp
 128 If the
 129 .Fa basep
 130 pointer value is non-NULL ,
 131 the
 132 .Fn getdirentries
 133 system call writes the position of the block read into the location pointed to by
 134 .Fa basep .
 135 Alternatively, the current position pointer may be set and retrieved by
 136 .Xr lseek 2 .
 137 The current position pointer should only be set to a value returned by
 138 .Xr lseek 2 ,
 139 a value returned in the location pointed to by
 140 .Fa basep
 141 .Po Fn getdirentries
 142 only
 143 .Pc
 144 or zero.
 145 .Sh RETURN VALUES
 146 If successful, the number of bytes actually transferred is returned.
 147 Otherwise, -1 is returned and the global variable
 148 .Va errno
 149 is set to indicate the error.
 150 .Sh ERRORS
 151 The
 152 .Fn getdirentries
 153 system call
 154 will fail if:
 155 .Bl -tag -width Er
 156 .It Bq Er EBADF
 157 The
 158 .Fa fd
 159 argument
 160 is not a valid file descriptor open for reading.
 161 .It Bq Er EFAULT
 162 Either
 163 .Fa buf
 164 or non-NULL
 165 .Fa basep
 166 point outside the allocated address space.
 167 .It Bq Er EINVAL
 168 The file referenced by
 169 .Fa fd
 170 is not a directory, or
 171 .Fa nbytes
 172 is too small for returning a directory entry or block of entries,
 173 or the current position pointer is invalid.
 174 .It Bq Er EIO
 175 An
 176 .Tn I/O
 177 error occurred while reading from or writing to the file system.
 178 .El
 179 .Sh SEE ALSO
 180 .Xr lseek 2 ,
 181 .Xr open 2
 182 .Sh HISTORY
 183 The
 184 .Fn getdirentries
 185 system call first appeared in
 186 .Bx 4.4 .
 187 The
 188 .Fn getdents
 189 system call first appeared in
 190 .Fx 3.0 .