Print this page
3742 zfs comments need cleaner, more consistent style
Submitted by:   Will Andrews <willa@spectralogic.com>
Submitted by:   Alan Somers <alans@spectralogic.com>
Reviewed by:    Matthew Ahrens <mahrens@delphix.com>
Reviewed by:    George Wilson <george.wilson@delphix.com>
Reviewed by:    Eric Schrock <eric.schrock@delphix.com>

@@ -431,12 +431,11 @@
  *              cr      - credentials of caller.
  *              ct      - caller context
  *
  *      OUT:    uio     - updated offset and range, buffer filled.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Side Effects:
  *      vp - atime updated if byte count > 0
  */
 /* ARGSUSED */

@@ -568,18 +567,18 @@
  * Write the bytes to a file.
  *
  *      IN:     vp      - vnode of file to be written to.
  *              uio     - structure supplying write location, range info,
  *                        and data buffer.
- *              ioflag  - FAPPEND flag set if in append mode.
+ *              ioflag  - FAPPEND, FSYNC, and/or FDSYNC.  FAPPEND is
+ *                        set if in append mode.
  *              cr      - credentials of caller.
  *              ct      - caller context (NFS/CIFS fem monitor only)
  *
  *      OUT:    uio     - updated offset and range.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      vp - ctime|mtime updated if byte count > 0
  */
 

@@ -1146,12 +1145,11 @@
  *              direntflags - directory lookup flags
  *              realpnp - returned pathname.
  *
  *      OUT:    vpp     - vnode of located entry, NULL if not found.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      NA
  */
 /* ARGSUSED */

@@ -1288,12 +1286,11 @@
  *              ct      - caller context
  *              vsecp   - ACL to be set
  *
  *      OUT:    vpp     - vnode of created or trunc'd entry.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      dvp - ctime|mtime updated if new entry created
  *       vp - ctime|mtime always, atime if new
  */

@@ -1539,12 +1536,11 @@
  *              name    - name of entry to remove.
  *              cr      - credentials of caller.
  *              ct      - caller context
  *              flags   - case flags
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      dvp - ctime|mtime
  *       vp - ctime (if nlink > 0)
  */

@@ -1770,16 +1766,16 @@
  *      IN:     dvp     - vnode of directory to add subdir to.
  *              dirname - name of new directory.
  *              vap     - attributes of new directory.
  *              cr      - credentials of caller.
  *              ct      - caller context
+ *              flags   - case flags
  *              vsecp   - ACL to be set
  *
  *      OUT:    vpp     - vnode of created directory.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      dvp - ctime|mtime updated
  *       vp - ctime|mtime|atime updated
  */

@@ -1955,12 +1951,11 @@
  *              cwd     - vnode of current working directory.
  *              cr      - credentials of caller.
  *              ct      - caller context
  *              flags   - case flags
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      dvp - ctime|mtime updated
  */
 /*ARGSUSED*/

@@ -2074,11 +2069,11 @@
 }
 
 /*
  * Read as many directory entries as will fit into the provided
  * buffer from the given directory cursor position (specified in
- * the uio structure.
+ * the uio structure).
  *
  *      IN:     vp      - vnode of directory to read.
  *              uio     - structure supplying read location, range info,
  *                        and return buffer.
  *              cr      - credentials of caller.

@@ -2086,12 +2081,11 @@
  *              flags   - case flags
  *
  *      OUT:    uio     - updated offset and range, buffer filled.
  *              eofp    - set to true if end-of-file detected.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      vp - atime updated
  *
  * Note that the low 4 bits of the cookie returned by zap is always zero.

@@ -2406,11 +2400,11 @@
  *              cr      - credentials of caller.
  *              ct      - caller context
  *
  *      OUT:    vap     - attribute values.
  *
- *      RETURN: 0 (always succeeds)
+ *      RETURN: 0 (always succeeds).
  */
 /* ARGSUSED */
 static int
 zfs_getattr(vnode_t *vp, vattr_t *vap, int flags, cred_t *cr,
     caller_context_t *ct)

@@ -2608,12 +2602,11 @@
  *              flags   - ATTR_UTIME set if non-default time values provided.
  *                      - ATTR_NOACLCHECK (CIFS context only).
  *              cr      - credentials of caller.
  *              ct      - caller context
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      vp - ctime updated, mtime updated if size changed.
  */
 /* ARGSUSED */

@@ -3210,10 +3203,11 @@
                 ASSERT(err2 == 0);
         }
 
         if (attrzp)
                 VN_RELE(ZTOV(attrzp));
+
         if (aclp)
                 zfs_acl_free(aclp);
 
         if (fuidp) {
                 zfs_fuid_info_free(fuidp);

@@ -3344,12 +3338,11 @@
  *              tnm     - New entry name.
  *              cr      - credentials of caller.
  *              ct      - caller context
  *              flags   - case flags
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      sdvp,tdvp - ctime|mtime updated
  */
 /*ARGSUSED*/

@@ -3692,17 +3685,15 @@
  * Insert the indicated symbolic reference entry into the directory.
  *
  *      IN:     dvp     - Directory to contain new symbolic link.
  *              link    - Name for new symlink entry.
  *              vap     - Attributes of new entry.
- *              target  - Target path of new symlink.
  *              cr      - credentials of caller.
  *              ct      - caller context
  *              flags   - case flags
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      dvp - ctime|mtime updated
  */
 /*ARGSUSED*/

@@ -3844,18 +3835,17 @@
 /*
  * Return, in the buffer contained in the provided uio structure,
  * the symbolic path referred to by vp.
  *
  *      IN:     vp      - vnode of symbolic link.
- *              uoip    - structure to contain the link path.
+ *              uio     - structure to contain the link path.
  *              cr      - credentials of caller.
  *              ct      - caller context
  *
- *      OUT:    uio     - structure to contain the link path.
+ *      OUT:    uio     - structure containing the link path.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      vp - atime updated
  */
 /* ARGSUSED */

@@ -3890,12 +3880,11 @@
  *              svp     - vnode of new entry.
  *              name    - name of new entry.
  *              cr      - credentials of caller.
  *              ct      - caller context
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      tdvp - ctime|mtime updated
  *       svp - ctime updated
  */

@@ -4059,12 +4048,11 @@
  *              cr      - credentials of caller.
  *
  *      OUT:    offp    - start of range pushed.
  *              lenp    - len of range pushed.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * NOTE: callers must have locked the page to be pushed.  On
  * exit, the page (and all other pages in the kluster) must be
  * unlocked.
  */

@@ -4182,12 +4170,11 @@
  *              len     - amount of data to write.
  *              flags   - flags to control the operation.
  *              cr      - credentials of caller.
  *              ct      - caller context.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      vp - ctime|mtime updated
  */
 /*ARGSUSED*/

@@ -4348,12 +4335,11 @@
  *      IN:     vp      - vnode seeking within
  *              ooff    - old file offset
  *              noffp   - pointer to new file offset
  *              ct      - caller context
  *
- *      RETURN: 0 if success
- *              EINVAL if new offset invalid
+ *      RETURN: 0 on success, EINVAL if new offset invalid.
  */
 /* ARGSUSED */
 static int
 zfs_seek(vnode_t *vp, offset_t ooff, offset_t *noffp,
     caller_context_t *ct)

@@ -4485,12 +4471,11 @@
  *              ct      - caller context.
  *
  *      OUT:    protp   - protection mode of created pages.
  *              pl      - list of pages created.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      vp - atime updated
  */
 /* ARGSUSED */

@@ -4570,19 +4555,15 @@
 
 /*
  * Request a memory map for a section of a file.  This code interacts
  * with common code and the VM system as follows:
  *
- *      common code calls mmap(), which ends up in smmap_common()
- *
- *      this calls VOP_MAP(), which takes you into (say) zfs
- *
- *      zfs_map() calls as_map(), passing segvn_create() as the callback
- *
- *      segvn_create() creates the new segment and calls VOP_ADDMAP()
- *
- *      zfs_addmap() updates z_mapcnt
+ * - common code calls mmap(), which ends up in smmap_common()
+ * - this calls VOP_MAP(), which takes you into (say) zfs
+ * - zfs_map() calls as_map(), passing segvn_create() as the callback
+ * - segvn_create() creates the new segment and calls VOP_ADDMAP()
+ * - zfs_addmap() updates z_mapcnt
  */
 /*ARGSUSED*/
 static int
 zfs_map(vnode_t *vp, offset_t off, struct as *as, caddr_t *addrp,
     size_t len, uchar_t prot, uchar_t maxprot, uint_t flags, cred_t *cr,

@@ -4720,12 +4701,11 @@
  *              flag    - current file open mode flags.
  *              offset  - current file offset.
  *              cr      - credentials of caller [UNUSED].
  *              ct      - caller context.
  *
- *      RETURN: 0 if success
- *              error code if failure
+ *      RETURN: 0 on success, error code on failure.
  *
  * Timestamps:
  *      vp - ctime|mtime updated
  */
 /* ARGSUSED */

@@ -4936,17 +4916,18 @@
         ZFS_EXIT(zfsvfs);
         return (error);
 }
 
 /*
- * Tunable, both must be a power of 2.
- *
- * zcr_blksz_min: the smallest read we may consider to loan out an arcbuf
- * zcr_blksz_max: if set to less than the file block size, allow loaning out of
- *                an arcbuf for a partial block read
+ * The smallest read we may consider to loan out an arcbuf.
+ * This must be a power of 2.
  */
 int zcr_blksz_min = (1 << 10);  /* 1K */
+/*
+ * If set to less than the file block size, allow loaning out of an
+ * arcbuf for a partial block read.  This must be a power of 2.
+ */
 int zcr_blksz_max = (1 << 17);  /* 128K */
 
 /*ARGSUSED*/
 static int
 zfs_reqzcbuf(vnode_t *vp, enum uio_rw ioflag, xuio_t *xuio, cred_t *cr,

@@ -5216,14 +5197,16 @@
         NULL,                   NULL
 };
 
 /*
  * Extended attribute directory vnode operations template
+ *
  *      This template is identical to the directory vnodes
  *      operation template except for restricted operations:
  *              VOP_MKDIR()
  *              VOP_SYMLINK()
+ *
  * Note that there are other restrictions embedded in:
  *      zfs_create()    - restrict type to VREG
  *      zfs_link()      - no links into/out of attribute space
  *      zfs_rename()    - no moves into/out of attribute space
  */