lib/libc/sys/getdents.2

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