PUFFS_OPS(3)            NetBSD Library Functions Manual           PUFFS_OPS(3)

NAME
     puffs_ops -- puffs callback operations

LIBRARY
     puffs Convenience Library (libpuffs, -lpuffs)

SYNOPSIS
     #include <puffs.h>

     int
     puffs_fs_statvfs(struct puffs_usermount *pu, struct statvfs *sbp);

     int
     puffs_fs_sync(struct puffs_usermount *pu, int waitfor,
         const struct puffs_cred *pcr);

     int
     puffs_fs_fhtonode(struct puffs_usermount *pu, void *fid, size_t fidsize,
         struct puffs_newinfo *pni);

     int
     puffs_fs_nodetofh(struct puffs_usermount *pu, puffs_cooie_t cookie,
         void *fid, size_t *fidsize);

     void
     puffs_fs_suspend(struct puffs_usermount *pu, int status);

     int
     puffs_fs_unmount(struct puffs_usermount *pu, int flags);

     int
     puffs_node_lookup(struct puffs_usermount *pu, puffs_cookie_t opc,
         struct puffs_newinfo *pni, const struct puffs_cn *pcn);

     int
     puffs_node_create(struct puffs_usermount *pu, puffs_cookie_t opc,
         struct puffs_newinfo *pni, const struct puffs_cn *pcn,
         const struct vattr *vap);

     int
     puffs_node_mknod(struct puffs_usermount *pu, puffs_cookie_t opc,
         struct puffs_newinfo *pni, const struct puffs_cn *pcn,
         const struct vattr *vap);

     int
     puffs_node_open(struct puffs_usermount *pu, puffs_cookie_t opc, int mode,
         const struct puffs_cred *pcr);

     int
     puffs_node_close(struct puffs_usermount *pu, puffs_cookie_t opc,
         int flags, const struct puffs_cred *pcr);

     int
     puffs_node_access(struct puffs_usermount *pu, puffs_cookie_t opc,
         int mode, const struct puffs_cred *pcr);

     int
     puffs_node_getattr(struct puffs_usermount *pu, puffs_cookie_t opc,
         struct vattr *vap, const struct puffs_cred *pcr);

     int
     puffs_node_setattr(struct puffs_usermount *pu, puffs_cookie_t opc,
         const struct vattr *vap, const struct puffs_cred *pcr);

     int
     puffs_node_poll(struct puffs_usermount *pu, puffs_cookie_t opc,
         int *events);

     int
     puffs_node_mmap(struct puffs_usermount *pu, puffs_cookie_t opc,
         int flags, const struct puffs_cred *pcr);

     int
     puffs_node_fsync(struct puffs_usermount *pu, puffs_cookie_t opc,
         const struct puffs_cred *pcr, int flags, off_t offlo, off_t offhi);

     int
     puffs_node_seek(struct puffs_usermount *pu, puffs_cookie_t opc,
         off_t oldoff, off_t newoff, const struct puffs_cred *pcr);

     int
     puffs_node_remove(struct puffs_usermount *pu, puffs_cookie_t opc,
         puffs_cookie_t targ, const struct puffs_cn *pcn);

     int
     puffs_node_link(struct puffs_usermount *pu, puffs_cookie_t opc,
         puffs_cookie_t targ, const struct puffs_cn *pcn);

     int
     puffs_node_rename(struct puffs_usermount *pu, puffs_cookie_t opc,
         puffs_cookie_t src, const struct puffs_cn *pcn_src,
         puffs_cookie_t targ_dir, puffs_cookie_t targ,
         const struct puffs_cn *pcn_targ);

     int
     puffs_node_mkdir(struct puffs_usermount *pu, puffs_cookie_t opc,
         struct puffs_newinfo *pni, const struct puffs_cn *pcn,
         const struct vattr *vap);

     int
     puffs_node_rmdir(struct puffs_usermount *pu, puffs_cookie_t opc,
         puffs_cookie_t targ, const struct puffs_cn *pcn);

     int
     puffs_node_readdir(struct puffs_usermount *pu, puffs_cookie_t opc,
         struct dirent *dent, off_t *readoff, size_t *reslen,
         const struct puffs_cred *pcr, int *eofflag, off_t *cookies,
         size_t *ncookies);

     int
     puffs_node_symlink(struct puffs_usermount *pu, puffs_cookie_t opc,
         struct puffs_newinfo *pni, const struct puffs_cn *pcn_src,
         const struct vattr *vap, const char *link_target);

     int
     puffs_node_readlink(struct puffs_usermount *pu, puffs_cookie_t opc,
         const struct puffs_cred *pcr, char *link, size_t *linklen);

     int
     puffs_node_read(struct puffs_usermount *pu, puffs_cookie_t opc,
         uint8_t *buf, off_t offset, size_t *resid,
         const struct puffs_cred *pcr, int ioflag);

     int
     puffs_node_write(struct puffs_usermount *pu, puffs_cookie_t opc,
         uint8_t *buf, off_t offset, size_t *resid,
         const struct puffs_cred *pcr, int ioflag);

     int
     puffs_node_print(struct puffs_usermount *pu, puffs_cookie_t opc);

     int
     puffs_node_reclaim(struct puffs_usermount *pu, puffs_cookie_t opc);

     int
     puffs_node_inactive(struct puffs_usermount *pu, puffs_cookie_t opc);

     void
     puffs_setback(struct puffs_cc *pcc, int op);

     void
     puffs_newinfo_setcookie(struct puffs_newinfo *pni,
         puffs_cookie_t cookie);

     void
     puffs_newinfo_setvtype(struct puffs_newinfo *pni, enum vtype vtype);

     void
     puffs_newinfo_setsize(struct puffs_newinfo *pni, voff_t size);

     void
     puffs_newinfo_setrdev(struct puffs_newinfo *pni, dev_t rdev);

DESCRIPTION
     The operations puffs requires to function can be divided into two cate-
     gories: file system callbacks and node callbacks.  The former affect the
     entire file system while the latter are targeted at a file or a directory
     and a file.  They are roughly equivalent to the vfs and vnode operations
     in the kernel.

     All callbacks can be prototyped with the file system name and operation
     name using the macro PUFFSOP_PROTOS(fsname).

   File system callbacks (puffs_fs)
     puffs_fs_statvfs(pu, sbp)
           The following fields of the argument sbp need to be filled:

            * unsigned long  f_bsize;     file system block size
            * unsigned long  f_frsize;    fundamental file system block size
            * fsblkcnt_t     f_blocks;    number of blocks in file system,
            *                                      (in units of f_frsize)
            *
            * fsblkcnt_t     f_bfree;     free blocks avail in file system
            * fsblkcnt_t     f_bavail;    free blocks avail to non-root
            * fsblkcnt_t     f_bresvd;    blocks reserved for root

            * fsfilcnt_t     f_files;     total file nodes in file system
            * fsfilcnt_t     f_ffree;     free file nodes in file system
            * fsfilcnt_t     f_favail;    free file nodes avail to non-root
            * fsfilcnt_t     f_fresvd;    file nodes reserved for root


     puffs_fs_sync(pu, waitfor, pcr)
           All the dirty buffers that have been cached at the file server
           level including metadata should be committed to stable storage.
           The waitfor parameter affects the operation.  Possible values are:

           MNT_WAIT      Wait for all I/O for complete until returning.

           MNT_NOWAIT    Initiate I/O, but do not wait for completion.

           MNT_LAZY      Synchorize data not synchoronized by the file system
                         syncer, i.e. data not written when node_fsync() is
                         called with FSYNC_LAZY.

           The credentials for the initiator of the sync operation are present
           in pcr and will usually be either file system or kernel creden-
           tials, but might also be user credentials.  However, most of the
           time it is advisable to sync regardless of the credentials of the
           caller.

     puffs_fs_fhtonode(pu, fid, fidsize, pni)
           Translates a file handle fid to a node.  The parameter fidsize
           indicates how large the file handle is.  In case the file system's
           handles are static length, this parameter can be ignored as the
           kernel guarantees all file handles passed to the file server are of
           correct length.  For dynamic length handles the field should be
           examined and EINVAL returned in case the file handle length is not
           correct.

           This function provides essentially the same information to the ker-
           nel as puffs_node_lookup().  The information is necessary for cre-
           ating a new vnode corresponding to the file handle.

     puffs_fs_nodetofh(pu, cookie, fid, fidsize)
           Create a file handle from the node described by cookie.  The file
           handle should contain enough information to reliably identify the
           node even after reboots and the pathname/inode being replaced by
           another file.  If this is not possible, it is up to the author of
           the file system to act responsibly and decide if the file system
           can support file handles at all.

           For file systems which want dynamic length file handles, this func-
           tion must check if the file handle space indicated by fidsize is
           large enough to accommodate the file handle for the node.  If not,
           it must fill in the correct size and return E2BIG.  In either case,
           the handle length should be supplied to the kernel in fidsize.
           File systems with static length handles can ignore the size parame-
           ter as the kernel always supplies the correct size buffer.

     puffs_fs_suspend(pu, status)
           Called when file system suspension reaches various phases.  See
           puffs_suspend(3) for more information.

     puffs_fs_unmount(pu, flags)
           Unmount the file system.  The kernel has assumedly flushed all
           cached data when this callback is executed.  If the file system
           cannot currently be safely be unmounted, for whatever reason, the
           kernel will honor an error value and not forcibly unmount.  How-
           ever, if the flag MNT_FORCE is not honored by the file server, the
           kernel will forcibly unmount the file system.

   Node callbacks
     These operations operate in the level of individual files.  The file
     cookie is always provided as the second argument opc.  If the operation
     is for a file, it will be the cookie of the file.  The case the operation
     involves a directory (such as ``create file in directory''), the cookie
     will be for the directory.  Some operations take additional cookies to
     describe the rest of the operands.  The return value 0 signals success,
     else an appropriate errno value should be returned.  Please note that
     neither this list nor the descriptions are complete.

     puffs_node_lookup(pu, opc, pni, pcn)
           This function is used to locate nodes, or in other words translate
           pathname components to file system data structures.  The implemen-
           tation should match the name in pcn against the existing entries in
           the directory provided by the cookie opc.  If found, the cookie for
           the located node should be set in pni using
           puffs_newinfo_setcookie().  Additionally, the vnode type and size
           (latter applicable to regular files only) should be set using
           puffs_newinfo_setvtype() and puffs_newinfo_setsize(), respectively.
           If the located entry is a block device or character device file,
           the dev_t for the entry should be set using
           puffs_newinfo_setrdev().

           The type of operation is found from pcn->pcn_nameiop:

           PUFFSLOOKUP_LOOKUP    Normal lookup operation.

           PUFFSLOOKUP_CREATE    Lookup to create a node.

           PUFFSLOOKUP_DELETE    Lookup for node deletion.

           PUFFSLOOKUP_RENAME    Lookup for the target of a rename operation
                                 (source will be looked up using
                                 PUFFSLOOKUP_DELETE).

           The final component from a pathname lookup usually requires special
           treatment.  It can be identified by looking at the pcn->pcn_flags
           fields for the flag PUFFSLOOKUP_ISLASTCN.  For example, in most
           cases the lookup operation will want to check if a delete, rename
           or create operation has enough credentials to perform the opera-
           tion.

           The return value 0 signals a found node and a nonzero value signals
           an errno.  As a special case, ENOENT signals "success" for cases
           where the lookup operation is PUFFSLOOKUP_CREATE or
           PUFFSLOOKUP_RENAME.  Failure in these cases can be signalled by
           returning another appropriate error code, for example EACCESS.

           Usually a null-terminated string for the next pathname component is
           provided in pcn->pcn_name.  In case the file system is using the
           option PUFFS_KFLAG_LOOKUP_FULLPNBUF, the remainder of the complete
           pathname under lookup is found in the same location.
           pcn->pcn_namelen always specifies the length of the next component.
           If operating with a full path, the file system is allowed to con-
           sume more than the next component's length in node lookup.  This is
           done by setting pcn->pcn_consume to indicate the amount of extra
           characters in addition to pcn->pcn_namelen processed.

     puffs_node_create(pu, opc, pni, pcn, va)

     puffs_node_mkdir(pu, opc, pni, pcn, va)

     puffs_node_mknod(pu, opc, pni, pcn, va)
           A file node is created in the directory denoted by the cookie opc
           by any of the above callbacks.  The name of the new file can be
           found from pcn and the attributes are specified by va and the
           cookie for the newly created node should be set in pni.  The only
           difference between these three is that they create a regular file,
           directory and device special file, respectively.

           In case of mknod, the device identifier can be found in
           va->va_rdev.

     puffs_node_open(pu, opc, mode, pcr)
           Open the node denoted by the cookie opc.  The parameter mode speci-
           fies the flags that open(2) was called with, e.g.  O_APPEND and
           O_NONBLOCK.

     puffs_node_close(pu, opc, flags, pcr)
           Close a node.  The parameter flags parameter describes the flags
           that the file was opened with.

     puffs_node_access(pu, opc, mode, pcr)
           Check if the credentials of pcr have the right to perform the oper-
           ation specified by mode onto the node opc.  The argument mode can
           specify read, write or execute by PUFFS_VREAD, PUFFS_VWRITE, and
           PUFFS_VEXEC, respectively.

     puffs_node_getattr(pu, opc, va, pcr)
           The attributes of the node specified by opc must be copied to the
           space pointed by va.

     puffs_node_setattr(pu, opc, va, pcr)
           The attributes for the node specified by opc must be set to those
           contained in va.  Only fields of va which contain a value different
           from PUFFS_VNOVAL (typecast to the field's type!) contain a valid
           value.

     puffs_node_poll(pu, opc, events)
           Poll for events on node opc.  If poll(2) events specified in events
           are available, the function should set the bitmask to match avail-
           able events and return immediately.  Otherwise, the function should
           block (yield) until some events in events become available and only
           then set the events bitmask and return.

           In case this function returns an error, POLLERR (or it's select(2)
           equivalent) will be delivered to the calling process.

           NOTE! The system call interface for poll() contains a timeout
           parameter.  At this level, however, the timeout is not supplied.
           In case input does not arrive, the file system should periodically
           unblock and return 0 new events to avoid hanging forever.  This
           will hopefully be better supported by libpuffs in the future.

     puffs_node_mmap(pu, opc, flags, pcr)
           Called when a regular file is being memory mapped by mmap(2).
           flags is currently always 0.

     puffs_node_fsync(pu, opc, pcr, flags, offlo, offhi)
           Sychronize a node's contents onto stable storage.  This is neces-
           sary only if the file server caches some information before commit-
           ting it.  The parameter flags specifies the minimum level of
           sychronization required (XXX: they are not yet available).  The
           parameters offlo and offhi specify the data offsets requiring to be
           synced.  A high offset of 0 means sync from offlo to the end of the
           file.

     puffs_node_seek(pu, opc, oldoff, newoff, pcr)
           Test if the node opc is seekable to the location newoff.  The argu-
           ment oldoff specifies the offset we are starting the seek from.
           Most file systems dealing only with regular will choose to not
           implement this.  However, it is useful for example in cases where
           files are unseekable streams.

     puffs_node_remove(pu, opc, targ, pcn)

     puffs_node_rmdir(pu, opc, targ, pcn)
           Remove the node targ from the directory indicated by opc.  The
           directory entry name to be removed is provided by pcn.  The rmdir
           operation removes only directories, while the remove operation
           removes all other types except directories.

           It is paramount to note that the file system may not remove the
           node data structures at this point, only the directory entry and
           prevent lookups from finding the node again.  This is to retain the
           UNIX open file semantics.  The data may be removed only when
           puffs_node_reclaim() is called for the node, as this assures there
           are no further users.

     puffs_node_link(pu, opc, targ, pcn)
           Create a hard link for the node targ into the directory opc.  The
           argument pcn provides the directory entry name for the new link.

     puffs_node_rename(pu, src_dir, src, pcn_src, targ_dir, targ, pcn_targ)
           Rename the node src with the name specified by pcn_src from the
           directory src_dir.  The target directory and target name are given
           by targ_dir and pcn_targ, respectively.  If the target node already
           exists, it is specified by targ and must be replaced atomically.
           Otherwise targ is gives as NULL.

           It is legal to replace a directory node by another directory node
           with the means of rename if the target directory is empty, other-
           wise ENOTEMPTY should be returned.  All other types can replace all
           other types.  In case a rename between incompatible types is
           attempted, the errors ENOTDIR or EISDIR should be returned, depend-
           ing on the target type.

     puffs_node_readdir(pu, opc, dent, readoff, reslen, pcr, eofflag, cookies,
           ncookies)
           To read directory entries, puffs_node_readdir() is called.  It
           should store directories as struct dirent in the space pointed to
           by dent.  The amount of space available is given by reslen and
           before returning it should be set to the amount of space remaining
           in the buffer.  The argument offset is used to specify the offset
           to the directory.  Its intepretation is up to the file system and
           it should be set to signal the continuation point when there is no
           more room for the next entry in dent.  It is most performant to
           return the maximal amount of directory entries each call.  It is
           easiest to generate directory entries by using puffs_nextdent(),
           which also automatically advances the necessary pointers.

           In case end-of-directory is reached, eofflag should be set to one.
           Note that even a new call to readdir may start where readoff points
           to end-of-directory.

           If the file system supports file handles, the arguments cookies and
           ncookies must be filled out.  cookies is a vector for offsets cor-
           responding to read offsets.  One cookie should be filled out for
           each directory entry.  The value of the cookie should equal the
           offset of the next directory entry, i.e. which offset should be
           passed to readdir for the first entry read to be the entry follow-
           ing the current one.  ncookies is the number of slots for cookies
           in the cookie vector upon entry to the function and must be set to
           the amount of cookies stored in the vector (i.e. amount of direc-
           tory entries read) upon exit.  There is always enough space in the
           cookie vector for the maximal number of entries that will fit into
           the directory entry buffer.  For filling out the vector, the helper
           function PUFFS_STORE_DCOOKIE(cookies, ncookies, offset) can be
           used.  This properly checks against cookies being NULL.  Note that
           ncookies must be initialized to zero before the first call to
           PUFFS_STORE_DCOOKIE().

     puffs_node_symlink(pu, opc, pni, pcn_src, va, link_target)
           Create a symbolic link into the directory opc with the name in
           pcn_src and the initial attributes in va.  The argument link_target
           contains a null-terminated string for the link target.  The created
           node cookie should be set in pni.

     puffs_node_readlink(pu, opc, pcr, link, linklen)
           Read the target of a symbolic link opc.  The result is placed in
           the buffer pointed to by link.  This buffer's length is given in
           linklen and it must be updated to reflect the real link length.  A
           terminating nul character should not be put into the buffer and
           must not be included in the link length.

     puffs_node_read(pu, opc, buf, offset, resid, pcr, ioflag)
           Read the contents of a file opc.  It will gather the data from
           offset in the file and read the number resid octets.  The buffer is
           guaranteed to have this much space.  The amount of data requested
           by resid should be read, except in the case of eof-of-file or an
           error.  The parameter resid should be set to indicate the amount of
           request NOT completed.  In the normal case this should be 0.

     puffs_node_write(pu, opc, buf, offset, resid, pcr, ioflag)
           puffs_node_write() Write data to a file opc at offset and extend
           the file if necessary.  The number of octets written is indicated
           by resid; everything must be written or an error will be generated.
           The parameter must be set to indicate the amount of data NOT writ-
           ten.  In case the flag PUFFS_IO_APPEND is specified, the data
           should be appended to the end of the file.

     puffs_node_print(pu, opc)
           Print information about node.  This is used only for kernel-initi-
           ated diagnostic purposes.

     puffs_node_reclaim(pu, opc)
           The kernel will no longer reference the cookie and resources asso-
           ciated with it may be freed.  In case the file opc has a link count
           of zero, it may be safely removed now.

     puffs_node_inactive(pu, opc)
           The node opc has lost its last reference in the kernel.  However,
           the cookie must still remain valid until puffs_node_reclaim() is
           called.

     puffs_setback(pcc, op)
           Issue a "setback" operation which will be handled when the request
           response is returned to the kernel.  Currently this can be only
           called from mmap, open, remove and rmdir.  The valid parameters for
           op are PUFFS_SETBACK_INACT_N1 and PUFFS_SETBACK_INACT_N2.  These
           signal that a file system mounted with PUFFS_KFLAG_IAONDEMAND
           should call the file system inactive method for the specified node.
           The node number 1 always means the operation cookie opc, while the
           node number 2 can be used to specify the second node argument
           present in some methods, e.g. remove.

     puffs_newinfo_setcookie(pni, cookie)
           Set cookie for node provided by this method to cookie.

     puffs_newinfo_setvtype(pni, vtype)
           Set the type of the newly located node to vtype.  This call is
           valid only for lookup() and fhtonode().

     puffs_newinfo_setsize(pni, size)
           Set the size of the newly located node to size.  If left unset, the
           value defaults to 0.  This call is valid only for lookup() and
           fhtovp().

     puffs_newinfo_setrdev(pni, rdev)
           Set the type of the newly located node to vtype.  This call is
           valid only for lookup() and fhtovp() producing device type nodes.

SEE ALSO
     puffs(3), vfsops(9), vnodeops(9)

NetBSD 5.0_STABLE              December 16, 2007             NetBSD 5.0_STABLE
