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.5 2006/10/19 18:44:00 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.Pp 84.Bd -literal 85 ...; 86 *ncookies = number of entries read; 87 *cookies = (u_int*)# 88 kmalloc(*ncookies * sizeof(u_int), M_TEMP, M_WAITOK); 89.Ed 90.Sh PSEUDOCODE 91.Bd -literal 92int 93vop_readdir(struct vnode *vp, struct uio *uio, struct ucred *cred, 94 int *eofflag, int *ncookies, u_int **cookies) 95{ 96 off_t off; 97 int error = 0; 98 99 /* 100 * Remember the original offset to use later in generating cookies. 101 */ 102 off = uio->uio_offset; 103 104 /* 105 * Read directory contents starting at uio->uio_offset into buffer 106 * pointed to by uio. 107 */ 108 ...; 109 110 if (!error && ncookies != NULL) { 111 struct dirent *dpStart; 112 struct dirent *dpEnd; 113 struct dirent *dp; 114 int count; 115 u_int *cookiebuf; 116 u_int *cookiep; 117 118 if (uio->uio_segflg != UIO_SYSSPACE || uio->uio_iovcnt != 1) 119 panic("vop_readdir: unexpected uio from NFS server"); 120 121 /* 122 * Parse the stuff just read into the uio. 123 */ 124 dpStart = (struct dirent *) 125 (uio->uio_iov->iov_base - (uio->uio_offset - off)); 126 dpEnd = (struct dirent *) uio->uio_iov->iov_base; 127 128 /* 129 * Count number of entries. 130 */ 131 for (dp = dpStart, count = 0; 132 dp < dpEnd; 133 dp = (struct dirent *)((caddr_t) dp + dp->d_reclen)) 134 count++; 135 136 cookiebuf = (u_int *) kmalloc(count * sizeof(u_int), M_TEMP, M_WAITOK); 137 for (dp = dpStart; cookiep = cookiebuf; 138 dp < dpEnd; 139 dp = (struct dirent *)((caddr_t) dp + dp->d_reclen)) { 140 off += dp->d_reclen; 141 *cookiep++ = (u_int) off; 142 } 143 *ncookies = count; 144 *cookies = cookiebuf; 145 } 146 147 if (eofflag && uio->uio_offset is past the end of the directory) { 148 *eofflag = TRUE; 149 } 150 151 return error; 152} 153.Ed 154.Sh ERRORS 155.Bl -tag -width Er 156.It Bq Er EINVAL 157attempt to read from an illegal offset in the directory 158.It Bq Er EIO 159a read error occurred while reading the directory 160.El 161.Sh SEE ALSO 162.Xr vnode 9 163.Sh AUTHORS 164This man page was written by 165.An Doug Rabson . 166