Differential D28664 Diff 83901 lib/libc/sys/getdirentries.2

Changeset View

Standalone View

lib/libc/sys/getdirentries.2

	Show All 22 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95			.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd March 30, 2020			.Dd February 14, 2021
	.Dt GETDIRENTRIES 2			.Dt GETDIRENTRIES 2
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm getdirentries ,			.Nm getdirentries ,
	.Nm getdents			.Nm getdents
	.Nd "get directory entries in a file system independent format"			.Nd "get directory entries in a file system independent format"
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Lines
	entry is a number which is unique for each			entry is a number which is unique for each
	distinct file in the file system.			distinct file in the file system.
	Files that are linked by hard links (see			Files that are linked by hard links (see
	.Xr link 2 )			.Xr link 2 )
	have the same			have the same
	.Fa d_fileno .			.Fa d_fileno .
	The			The
	.Fa d_off			.Fa d_off
	field returns a cookie which can be used with			field returns a cookie which, if non-zero, can be used with
	.Xr lseek 2			.Xr lseek 2
	to position the directory descriptor to the next entry.			to position the directory descriptor to the next entry.
	The			The
				asomersUnsubmitted Done Inline Actions I find this confusing. Is the antecedent of "it" "cookie", "directory descriptor", or "entry"? I would say "returns a cookie which, if non-zero, can be used with lseek to position the directory descriptor to the next entry." asomers: I find this confusing. Is the antecedent of "it" "cookie", "directory descriptor", or "entry"?
	.Fa d_reclen			.Fa d_reclen
	entry is the length, in bytes, of the directory record.			entry is the length, in bytes, of the directory record.
	The			The
	.Fa d_type			.Fa d_type
	entry is the type of the file pointed to by the directory record.			entry is the type of the file pointed to by the directory record.
	The file type values are defined in			The file type values are defined in
	.Fa <sys/dirent.h> .			.Fa <sys/dirent.h> .
	The			The
	Show All 39 Lines
	.Xr lseek 2 ,			.Xr lseek 2 ,
	a value returned in the location pointed to by			a value returned in the location pointed to by
	.Fa basep			.Fa basep
	.Po Fn getdirentries			.Po Fn getdirentries
	only			only
	.Pc ,			.Pc ,
	a value returned in the			a value returned in the
	.Fa d_off			.Fa d_off
	field,			field if it is non-zero,
				asomersUnsubmitted Done Inline Actions I would shorten this to "if non-zero". asomers: I would shorten this to "if non-zero".
	or zero.			or zero.
	.Sh IMPLEMENTATION NOTES			.Sh IMPLEMENTATION NOTES
	The			The
	.Fa d_off			.Fa d_off
	field is being used as a cookie to readdir for nfs servers.			field is currently set to 0 by the NFS client, since the
	These cookies can be cached and allow to read directory entries at a specific			directory offset cookies returned by an NFS server cannot
	offset on demand.			be used by
				.Xr lseek 2
				at this time.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	If successful, the number of bytes actually transferred is returned.			If successful, the number of bytes actually transferred is returned.
	Otherwise, -1 is returned and the global variable			Otherwise, -1 is returned and the global variable
	.Va errno			.Va errno
	is set to indicate the error.			is set to indicate the error.
	.Sh ERRORS			.Sh ERRORS
	The			The
	.Fn getdirentries			.Fn getdirentries
	Show All 40 Lines