1.\" $NetBSD: getdirentries.3,v 1.1 2005/09/13 01:44:09 christos 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 June 9, 1993 33.Dt GETDIRENTRIES 3 34.Os 35.Sh NAME 36.Nm getdirentries 37.Nd "get directory entries in a filesystem independent format" 38.Sh SYNOPSIS 39.In dirent.h 40.Ft int 41.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" 42.Sh DESCRIPTION 43.Bf -symbolic 44.\" This interface is available from the compatibility library, libcompat and 45This interface is provided for compatibility only and 46has been obsoleted by 47.Xr getdents 2 . 48.Ef 49.Pp 50.Fn getdirentries 51reads directory entries from the directory 52referenced by the file descriptor 53.Fa fd 54into the buffer pointed to by 55.Fa buf , 56in a filesystem independent format. 57Up to 58.Fa nbytes 59of data will be transferred. 60.Fa nbytes 61must be greater than or equal to the 62block size associated with the file, 63see 64.Xr stat 2 . 65Some filesystems may not support 66.Fn getdirentries 67with buffers smaller than this size. 68.Pp 69The data in the buffer is a series of 70.Em dirent 71structures each containing the following entries: 72.Bd -literal -offset indent 73unsigned long d_fileno; 74unsigned short d_reclen; 75unsigned short d_namlen; 76char d_name[MAXNAMELEN + 1]; /* see below */ 77.Ed 78.Pp 79The 80.Fa d_fileno 81entry is a number which is unique for each 82distinct file in the filesystem. 83Files that are linked by hard links (see 84.Xr link 2 ) 85have the same 86.Fa d_fileno . 87If 88.Fa d_fileno 89is zero, the entry refers to a deleted file. 90.Pp 91The 92.Fa d_reclen 93entry is the length, in bytes, of the directory record. 94.Pp 95The 96.Fa d_namlen 97entry specifies the length of the file name excluding the null byte. 98Thus the actual size of 99.Fa d_name 100may vary from 1 to 101.Dv MAXNAMELEN 102\&+ 1. 103.Pp 104The 105.Fa d_name 106entry contains a null terminated file name. 107.Pp 108Entries may be separated by extra space. 109The 110.Fa d_reclen 111entry may be used as an offset from the start of a 112.Fa dirent 113structure to the next structure, if any. 114.Pp 115The actual number of bytes transferred is returned. 116The current position pointer associated with 117.Fa fd 118is set to point to the next block of entries. 119The pointer may not advance by the number of bytes returned by 120.Fn getdirentries . 121A value of zero is returned when 122the end of the directory has been reached. 123.Pp 124.Fn getdirentries 125writes the position of the block read into the location pointed to by 126.Fa basep . 127Alternatively, the current position pointer may be set and retrieved by 128.Xr lseek 2 . 129The current position pointer should only be set to a value returned by 130.Xr lseek 2 , 131a value returned in the location pointed to by 132.Fa basep , 133or zero. 134.Sh RETURN VALUES 135If successful, the number of bytes actually transferred is returned. 136Otherwise, \-1 is returned and the global variable 137.Va errno 138is set to indicate the error. 139.Sh ERRORS 140.Fn getdirentries 141will fail if: 142.Bl -tag -width Er 143.It Bq Er EBADF 144.Fa fd 145is not a valid file descriptor open for reading. 146.It Bq Er EFAULT 147Either 148.Fa buf 149or 150.Fa basep 151point outside the allocated address space. 152.It Bq Er EIO 153An 154.Tn I/O 155error occurred while reading from or writing to the file system. 156.El 157.Sh SEE ALSO 158.Xr lseek 2 , 159.Xr open 2 160.Sh HISTORY 161The 162.Fn getdirentries 163function first appeared in 164.Bx 4.4 . 165