* 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 

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 credentials, but might also be user credentials. However, most of the time it is advisable to sync regardless of the credentials of the caller.

This function provides essentially the same information to the kernel as puffs_node_lookup(). The information is necessary for creating a new vnode corresponding to the file handle.

For file systems which want dynamic length file handles, this function 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 parameter as the kernel always supplies the correct size buffer.

If puffs_init() was called with PUFFS_KFLAG_CACHE_FS_TTL then puffs_newinfo_setva(), puffs_newinfo_setvattl(), and puffs_newinfo_setcnttl() can be called to specify the new node attributes, cached attributes time to live, and cached name time to live.

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

NAMEI_LOOKUP

Normal lookup operation.

NAMEI_CREATE

Lookup to create a node.

NAMEI_DELETE

Lookup for node deletion.

NAMEI_RENAME

Lookup for the target of a rename operation (source will be looked up using NAMEI_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 operation.

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 NAMEI_CREATE or NAMEI_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 consume 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.

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

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.

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() or puffs_node_reclaim2() is called for the node, as this assures there are no further users.

It is legal to replace a directory node by another directory node with the means of rename if the target directory is empty, otherwise 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, depending on the target type.

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 corresponding 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 following 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 directory 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().

If the filesystem maps cookies to struct puffs_node then the framework will do that work, and puffs_node_reclaim() can be reliabily used without the race condition.