1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 1996 Doug Rabson 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" $FreeBSD: src/share/man/man9/VOP_READDIR.9,v 1.6.2.1 2001/12/17 11:30:18 ru Exp $ 30.\" $DragonFly: src/share/man/man9/VOP_READDIR.9,v 1.3 2003/07/27 05:36:06 hmp Exp $ 31.\" 32.Dd July 24, 1996 33.Os 34.Dt VOP_READDIR 9 35.Sh NAME 36.Nm VOP_READDIR 37.Nd read contents of a directory 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/dirent.h 41.In sys/vnode.h 42.Ft int 43.Fn VOP_READDIR "struct vnode *vp" "struct uio *uio" "struct ucred *cred" "int *eofflag" "int *ncookies" "u_long **cookies" 44.Sh DESCRIPTION 45Read directory entries. 46.Bl -tag -width ncookies 47.It Fa vp 48the vnode of the directory 49.It Fa uio 50where to read the directory contents 51.It Fa cred 52the caller's credentials 53.It Fa eofflag 54return end of file status (NULL if not wanted) 55.It Fa ncookies 56number of directory cookies generated for NFS (NULL if not wanted) 57.It Fa cookies 58directory seek cookies generated for NFS (NULL if not wanted) 59.El 60The directory contents are read into 61.Vt struct dirent 62structures. If the on-disc data structures differ from this then they 63should be translated. 64.Sh LOCKS 65The directory should be locked on entry and will still be locked on exit. 66.Sh RETURN VALUES 67Zero is returned on success, otherwise an error code is returned. 68.Pp 69If this is called from the NFS server, the extra arguments 70.Fa eofflag , 71.Fa ncookies 72and 73.Fa cookies 74are given. 75The value of 76.Fa *eofflag 77should be set to TRUE if the end of the directory is reached while 78reading. 79The directory seek cookies are returned to the NFS client and may be used 80later to restart a directory read part way through the directory. 81There should be one cookie returned per directory entry. The value of 82the cookie should be the offset within the directory where the on-disc 83version of the appropriate directory entry starts. 84Memory for the cookies should be allocated using: 85.Pp 86.Bd -literal 87 ...; 88 *ncookies = number of entries read; 89 *cookies = (u_int*)# 90 malloc(*ncookies * sizeof(u_int), M_TEMP, M_WAITOK); 91.Ed 92.Sh PSEUDOCODE 93.Bd -literal 94int 95vop_readdir(struct vnode *vp, struct uio *uio, struct ucred *cred, 96 int *eofflag, int *ncookies, u_int **cookies) 97{ 98 off_t off; 99 int error = 0; 100 101 /* 102 * Remember the original offset to use later in generating cookies. 103 */ 104 off = uio->uio_offset; 105 106 /* 107 * Read directory contents starting at uio->uio_offset into buffer 108 * pointed to by uio. 109 */ 110 ...; 111 112 if (!error && ncookies != NULL) { 113 struct dirent *dpStart; 114 struct dirent *dpEnd; 115 struct dirent *dp; 116 int count; 117 u_int *cookiebuf; 118 u_int *cookiep; 119 120 if (uio->uio_segflg != UIO_SYSSPACE || uio->uio_iovcnt != 1) 121 panic("vop_readdir: unexpected uio from NFS server"); 122 123 /* 124 * Parse the stuff just read into the uio. 125 */ 126 dpStart = (struct dirent *) 127 (uio->uio_iov->iov_base - (uio->uio_offset - off)); 128 dpEnd = (struct dirent *) uio->uio_iov->iov_base; 129 130 /* 131 * Count number of entries. 132 */ 133 for (dp = dpStart, count = 0; 134 dp < dpEnd; 135 dp = (struct dirent *)((caddr_t) dp + dp->d_reclen)) 136 count++; 137 138 cookiebuf = (u_int *) malloc(count * sizeof(u_int), M_TEMP, M_WAITOK); 139 for (dp = dpStart; cookiep = cookiebuf; 140 dp < dpEnd; 141 dp = (struct dirent *)((caddr_t) dp + dp->d_reclen)) { 142 off += dp->d_reclen; 143 *cookiep++ = (u_int) off; 144 } 145 *ncookies = count; 146 *cookies = cookiebuf; 147 } 148 149 if (eofflag && uio->uio_offset is past the end of the directory) { 150 *eofflag = TRUE; 151 } 152 153 return error; 154} 155.Ed 156.Sh ERRORS 157.Bl -tag -width Er 158.It Bq Er EINVAL 159attempt to read from an illegal offset in the directory 160.It Bq Er EIO 161a read error occurred while reading the directory 162.El 163.Sh SEE ALSO 164.Xr vnode 9 165.Sh AUTHORS 166This man page was written by 167.An Doug Rabson . 168