![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to getdirentries.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to getdirentries.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
1.1 root 1: .\" Copyright (c) 1989 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted provided
5: .\" that: (1) source distributions retain this entire copyright notice and
6: .\" comment, and (2) distributions including binaries display the following
7: .\" acknowledgement: ``This product includes software developed by the
8: .\" University of California, Berkeley and its contributors'' in the
9: .\" documentation or other materials provided with the distribution and in
10: .\" all advertising materials mentioning features or use of this software.
11: .\" Neither the name of the University nor the names of its contributors may
12: .\" be used to endorse or promote products derived from this software without
13: .\" specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)getdirentries.2 6.2 (Berkeley) 6/23/90
19: .\"
20: .TH GETDIRENTRIES 2 "June 23, 1990"
21: .UC 7
22: .SH NAME
23: getdirentries \- get directory entries in a filesystem independent format
24: .SH SYNOPSIS
25: .nf
26: .ft B
27: #include <sys/dirent.h>
28: .LP
29: .ft B
30: cc = getdirentries(fd, buf, nbytes, basep)
31: int cc, fd;
32: char *buf;
33: int nbytes;
34: long *basep;
35: .fi
36: .SH DESCRIPTION
37: .I Getdirentries
38: reads directory entries from the directory
39: referenced by the file descriptor
40: .I fd
41: into the buffer pointed to by
42: .IR buf ,
43: in a filesystem independent format.
44: Up to
45: .I nbytes
46: of data will be transferred.
47: .I Nbytes
48: must be greater than or equal to the
49: block size associated with the file,
50: see
51: .IR stat(2) .
52: Some filesystems may not support
53: .I getdirentries
54: with buffers smaller than this size.
55: .PP
56: The data in the buffer is a series of
57: .I dirent
58: structures each containing the following entries:
59: .PP
60: .RS
61: .ta +\w'unsigned\0short\0'u +\w'd_name[MAXNAMELEN + 1];\0'u
62: .nf
63: unsigned long d_fileno;
64: unsigned short d_reclen;
65: unsigned short d_namlen;
66: char d_name[MAXNAMELEN + 1]; /* see below */
67: .fi
68: .RE
69: .PP
70: The
71: .I d_fileno
72: entry is a number which is unique for each
73: distinct file in the filesystem.
74: Files that are linked by hard links (see
75: .IR link(2) )
76: have the same
77: .IR d_fileno .
78: The
79: .I d_reclen
80: entry is the length, in bytes, of the directory record.
81: The
82: .I d_name
83: entry contains a null terminated file name.
84: The
85: .I d_namlen
86: entry specifies the length of the file name excluding the null byte.
87: Thus the actual size of
88: .I d_name
89: may vary from 1 to \fBMAXNAMELEN + 1\fP.
90: .PP
91: Entries may be separated by extra space.
92: The
93: .I d_reclen
94: entry may be used as an offset from the start of a
95: .I dirent
96: structure to the next structure, if any.
97: .PP
98: The actual number of bytes transferred is returned.
99: The current position pointer associated with
100: .I fd
101: is set to point to the next block of entries.
102: The pointer may not advance by the number of bytes returned by
103: .IR getdirentries .
104: A value of zero is returned when
105: the end of the directory has been reached.
106: .PP
107: .I Getdirentries
108: writes the position of the block read into the location pointed to by
109: .IR basep .
110: Alternatively, the current position pointer may be set and retrieved by
111: .IR lseek(2) .
112: The current position pointer should only be set to a value returned by
113: .I lseek(2) ,
114: a value returned in the location pointed to by
115: .I basep ,
116: or zero.
117: .SH RETURN VALUE
118: If successful, the number of bytes actually transferred is returned.
119: Otherwise, a \-1 is returned and the global variable
120: .I errno
121: is set to indicate the error.
122: .SH ERRORS
123: .I Getdirentries
124: will fail if one or more of the following are true:
125: .TP 15
126: EBADF
127: \fIfd\fP is not a valid file descriptor open for reading.
128: .TP 15
129: EFAULT
130: Either \fIbuf\fP or \fIbasep\fP point outside the allocated address space.
131: .TP 15
132: EIO
133: An I/O error occurred while reading from or writing to the file system.
134: .SH "SEE ALSO"
135: open(2), lseek(2)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.