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.\" $DragonFly: src/share/man/man9/VOP_READDIR.9,v 1.6 2008/05/02 02:05:06 swildner Exp $ 29.\" 30.Dd July 24, 1996 31.Os 32.Dt VOP_READDIR 9 33.Sh NAME 34.Nm VOP_READDIR 35.Nd read contents of a directory 36.Sh SYNOPSIS 37.In sys/param.h 38.In sys/dirent.h 39.In sys/vnode.h 40.Ft int 41.Fn VOP_READDIR "struct vnode *vp" "struct uio *uio" "struct ucred *cred" "int *eofflag" "int *ncookies" "u_long **cookies" 42.Sh DESCRIPTION 43Read directory entries. 44.Bl -tag -width ncookies 45.It Fa vp 46the vnode of the directory 47.It Fa uio 48where to read the directory contents 49.It Fa cred 50the caller's credentials 51.It Fa eofflag 52return end of file status (NULL if not wanted) 53.It Fa ncookies 54number of directory cookies generated for NFS (NULL if not wanted) 55.It Fa cookies 56directory seek cookies generated for NFS (NULL if not wanted) 57.El 58The directory contents are read into 59.Vt struct dirent 60structures. If the on-disc data structures differ from this then they 61should be translated. 62.Sh LOCKS 63The directory should be locked on entry and will still be locked on exit. 64.Sh RETURN VALUES 65Zero is returned on success, otherwise an error code is returned. 66.Pp 67If this is called from the NFS server, the extra arguments 68.Fa eofflag , 69.Fa ncookies 70and 71.Fa cookies 72are given. 73The value of 74.Fa *eofflag 75should be set to TRUE if the end of the directory is reached while 76reading. 77The directory seek cookies are returned to the NFS client and may be used 78later to restart a directory read part way through the directory. 79There should be one cookie returned per directory entry. The value of 80the cookie should be the offset within the directory where the on-disc 81version of the appropriate directory entry starts. 82Memory for the cookies should be allocated using: 83.Bd -literal 84 ...; 85 *ncookies = number of entries read; 86 *cookies = (u_int*)# 87 kmalloc(*ncookies * sizeof(u_int), M_TEMP, M_WAITOK); 88.Ed 89.Sh PSEUDOCODE 90.Bd -literal 91int 92vop_readdir(struct vnode *vp, struct uio *uio, struct ucred *cred, 93 int *eofflag, int *ncookies, u_int **cookies) 94{ 95 off_t off; 96 int error = 0; 97 98 /* 99 * Remember the original offset to use later in generating cookies. 100 */ 101 off = uio->uio_offset; 102 103 /* 104 * Read directory contents starting at uio->uio_offset into buffer 105 * pointed to by uio. 106 */ 107 ...; 108 109 if (!error && ncookies != NULL) { 110 struct dirent *dpStart; 111 struct dirent *dpEnd; 112 struct dirent *dp; 113 int count; 114 u_int *cookiebuf; 115 u_int *cookiep; 116 117 if (uio->uio_segflg != UIO_SYSSPACE || uio->uio_iovcnt != 1) 118 panic("vop_readdir: unexpected uio from NFS server"); 119 120 /* 121 * Parse the stuff just read into the uio. 122 */ 123 dpStart = (struct dirent *) 124 (uio->uio_iov->iov_base - (uio->uio_offset - off)); 125 dpEnd = (struct dirent *) uio->uio_iov->iov_base; 126 127 /* 128 * Count number of entries. 129 */ 130 for (dp = dpStart, count = 0; 131 dp < dpEnd; 132 dp = (struct dirent *)((caddr_t) dp + dp->d_reclen)) 133 count++; 134 135 cookiebuf = (u_int *) kmalloc(count * sizeof(u_int), M_TEMP, M_WAITOK); 136 for (dp = dpStart; cookiep = cookiebuf; 137 dp < dpEnd; 138 dp = (struct dirent *)((caddr_t) dp + dp->d_reclen)) { 139 off += dp->d_reclen; 140 *cookiep++ = (u_int) off; 141 } 142 *ncookies = count; 143 *cookies = cookiebuf; 144 } 145 146 if (eofflag && uio->uio_offset is past the end of the directory) { 147 *eofflag = TRUE; 148 } 149 150 return error; 151} 152.Ed 153.Sh ERRORS 154.Bl -tag -width Er 155.It Bq Er EINVAL 156attempt to read from an illegal offset in the directory 157.It Bq Er EIO 158a read error occurred while reading the directory 159.El 160.Sh SEE ALSO 161.Xr vnode 9 162.Sh AUTHORS 163This man page was written by 164.An Doug Rabson . 165