share/man/man9/VOP_READDIR.9

   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
  45 Read directory entries.
  46 .Bl -tag -width ncookies
  47 .It Fa vp
  48 the vnode of the directory
  49 .It Fa uio
  50 where to read the directory contents
  51 .It Fa cred
  52 the caller's credentials
  53 .It Fa eofflag
  54 return end of file status (NULL if not wanted)
  55 .It Fa ncookies
  56 number of directory cookies generated for NFS (NULL if not wanted)
  57 .It Fa cookies
  58 directory seek cookies generated for NFS (NULL if not wanted)
  59 .El
  60 The directory contents are read into
  61 .Vt struct dirent
  62 structures.  If the on-disc data structures differ from this then they
  63 should be translated.
  64 .Sh LOCKS
  65 The directory should be locked on entry and will still be locked on exit.
  66 .Sh RETURN VALUES
  67 Zero is returned on success, otherwise an error code is returned.
  68 .Pp
  69 If this is called from the NFS server, the extra arguments
  70 .Fa eofflag ,
  71 .Fa ncookies
  72 and
  73 .Fa cookies
  74 are given.
  75 The value of
  76 .Fa *eofflag
  77 should be set to TRUE if the end of the directory is reached while
  78 reading.
  79 The directory seek cookies are returned to the NFS client and may be used
  80 later to restart a directory read part way through the directory.
  81 There should be one cookie returned per directory entry.  The value of
  82 the cookie should be the offset within the directory where the on-disc
  83 version of the appropriate directory entry starts.
  84 Memory 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
  94 int
  95 vop_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
 159 attempt to read from an illegal offset in the directory
 160 .It Bq Er EIO
 161 a read error occurred while reading the directory
 162 .El
 163 .Sh SEE ALSO
 164 .Xr vnode 9
 165 .Sh AUTHORS
 166 This man page was written by
 167 .An Doug Rabson .