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 .\" 4. 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 3, 1995
  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 int
  44 .Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep"
  45 .Ft int
  46 .Fn getdents "int fd" "char *buf" "int 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 uint32_t d_fileno;
  75 uint16_t d_reclen;
  76 uint8_t  d_type;
  77 uint8_t  d_namlen;
  78 char    d_name[MAXNAMELEN + 1]; /* see below */
  79 .Ed
  80 .Pp
  81 The
  82 .Fa d_fileno
  83 entry is a number which is unique for each
  84 distinct file in the file system.
  85 Files that are linked by hard links (see
  86 .Xr link 2 )
  87 have the same
  88 .Fa d_fileno .
  89 The
  90 .Fa d_reclen
  91 entry is the length, in bytes, of the directory record.
  92 The
  93 .Fa d_type
  94 entry is the type of the file pointed to by the directory record.
  95 The file type values are defined in
  96 .Fa <sys/dirent.h> .
  97 The
  98 .Fa d_name
  99 entry contains a null terminated file name.
 100 The
 101 .Fa d_namlen
 102 entry specifies the length of the file name excluding the null byte.
 103 Thus the actual size of
 104 .Fa d_name
 105 may vary from 1 to
 106 .Dv MAXNAMELEN
 107 \&+ 1.
 108 .Pp
 109 Entries may be separated by extra space.
 110 The
 111 .Fa d_reclen
 112 entry may be used as an offset from the start of a
 113 .Fa dirent
 114 structure to the next structure, if any.
 115 .Pp
 116 The actual number of bytes transferred is returned.
 117 The current position pointer associated with
 118 .Fa fd
 119 is set to point to the next block of entries.
 120 The pointer may not advance by the number of bytes returned by
 121 .Fn getdirentries
 122 or
 123 .Fn getdents .
 124 A value of zero is returned when
 125 the end of the directory has been reached.
 126 .Pp
 127 The
 128 .Fn getdirentries
 129 system call writes the position of the block read into the location pointed to by
 130 .Fa basep .
 131 Alternatively, the current position pointer may be set and retrieved by
 132 .Xr lseek 2 .
 133 The current position pointer should only be set to a value returned by
 134 .Xr lseek 2 ,
 135 a value returned in the location pointed to by
 136 .Fa basep
 137 .Fn ( getdirentries
 138 only)
 139 or zero.
 140 .Sh RETURN VALUES
 141 If successful, the number of bytes actually transferred is returned.
 142 Otherwise, -1 is returned and the global variable
 143 .Va errno
 144 is set to indicate the error.
 145 .Sh ERRORS
 146 The
 147 .Fn getdirentries
 148 system call
 149 will fail if:
 150 .Bl -tag -width Er
 151 .It Bq Er EBADF
 152 The
 153 .Fa fd
 154 argument
 155 is not a valid file descriptor open for reading.
 156 .It Bq Er EFAULT
 157 Either
 158 .Fa buf
 159 or
 160 .Fa basep
 161 point outside the allocated address space.
 162 .It Bq Er EINVAL
 163 The file referenced by
 164 .Fa fd
 165 is not a directory, or
 166 .Fa nbytes
 167 is too small for returning a directory entry or block of entries,
 168 or the current position pointer is invalid.
 169 .It Bq Er EIO
 170 An
 171 .Tn I/O
 172 error occurred while reading from or writing to the file system.
 173 .El
 174 .Sh SEE ALSO
 175 .Xr lseek 2 ,
 176 .Xr open 2
 177 .Sh HISTORY
 178 The
 179 .Fn getdirentries
 180 system call first appeared in
 181 .Bx 4.4 .
 182 The
 183 .Fn getdents
 184 system call first appeared in
 185 .Fx 3.0 .