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