[unix-history] / usr / src / lib / libc / sys / getdirentries.2

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