vnode.h

Includes:

Overview

Use the links in the table of contents to the left to access the documentation.

Functions

cache_enter: Add a (name,vnode) entry to the VFS namecache.
cache_lookup: Check for a filename in a directory using the VFS name cache.
cache_purge: Remove all data relating to a vnode from the namecache.
cache_purge_negatives: Remove all negative cache entries which are children of a given vnode.
vcount: Count total references to a given file, disregarding "kusecount" (event listener, as with O_EVTONLY) references.
vflush: Reclaim the vnodes associated with a mount.
vfs_addname: Deprecated
vfs_context_create: Create a new vfs_context_t with appropriate references held.
vfs_context_current: Get the vfs_context for the current thread, or the kernel context if there is no context for current thread.
vfs_context_is64bit: Determine if a vfs_context_t corresponds to a 64-bit user process.
vfs_context_issignal: Get a bitfield of pending signals for the BSD process associated with a vfs_context_t.
vfs_context_pid: Get the process id of the BSD process associated with a vfs_context_t.
vfs_context_proc: Get the BSD process structure associated with a vfs_context_t.
vfs_context_rele: Release references on components of a context and deallocate it.
vfs_context_suser: Determine if a vfs_context_t corresponds to the superuser.
vfs_context_ucred: Get the credential associated with a vfs_context_t.
vfs_removename: Deprecated
vfs_rootvnode: Returns the root vnode with an iocount.
vn_bwrite: System-provided implementation of "bwrite" vnop.
vn_default_error: Default vnode operation to fill unsupported slots in vnode operation vectors.
vn_getpath: Construct the path to a vnode.
vn_path_package_check: Figure out if a path corresponds to a Mac OS X package.
vn_rdwr: Read from or write to a file.
vn_revoke: Invalidate all references to a vnode.
vnode_addfsref: Mark a vnode as being stored in a filesystem hash.
vnode_authattr: Given a vnode_attr structure, determine what kauth-style actions must be authorized in order to set those attributes.
vnode_authattr_new: Initialize and validate file creation parameters with respect to the current context.
vnode_authorize: Authorize a kauth-style action on a vnode.
vnode_clearfsnode: Sets a vnode's filesystem-specific data to be NULL.
vnode_clearmountedon: Clear flags indicating that a block device vnode has been mounted as a filesystem.
vnode_clearnocache: Clear the flag on a vnode indicating that data should not be cached in memory (i.e. we write-through to disk and always read from disk).
vnode_clearnoreadahead: Clear the flag indicating that a vnode should not have data speculatively read in.
vnode_close: Close a file as opened with vnode_open().
vnode_create: Create and initialize a vnode.
vnode_fsnode: Gets the filesystem-specific data associated with a vnode.
vnode_get: Increase the iocount on a vnode.
vnode_getattr: Get vnode attributes.
vnode_getname: Get the name of a vnode from the VFS namecache.
vnode_getparent: Get an iocount on the parent of a vnode.
vnode_getwithref: Increase the iocount on a vnode on which a usecount (persistent reference) is held.
vnode_getwithvid: Increase the iocount on a vnode, checking that the vnode is alive and has not changed vid (i.e. been recycled)
vnode_hascleanblks: Check if a vnode has clean buffers associated with it.
vnode_hasdirtyblks: Check if a vnode has dirty data waiting to be written to disk.
vnode_isblk: Determine if a vnode is a block device special file.
vnode_ischr: Determine if a vnode is a character device special file.
vnode_isdir: Determine if a vnode is a directory.
vnode_isfifo: Determine if a vnode is a named pipe.
vnode_isinuse: Determine if the number of persistent (usecount) references on a vnode is greater than a given count.
vnode_islnk: Determine if a vnode is a symbolic link.
vnode_ismount: Determine if there is currently a mount occurring which will cover this vnode.
vnode_ismountedon: Determine if a vnode is a block device on which a filesystem has been mounted.
vnode_isnamedstream: Determine if a vnode is a named stream.
vnode_isnocache: Check if a vnode is set to not have its data cached in memory (i.e. we write-through to disk and always read from disk).
vnode_isnoreadahead: Check if a vnode is set to not have data speculatively read in in hopes of future cache hits.
vnode_israge: Check if a vnode is marked for rapid aging
vnode_isrecycled: Check if a vnode is dead or in the process of being killed (recycled).
vnode_isreg: Determine if a vnode is a regular file.
vnode_isswap: Determine if a vnode is being used as a swap file.
vnode_issystem: Determine if a vnode is marked as a System vnode.
vnode_isvroot: Determine if a vnode is the root of its filesystem.
vnode_iterate: Perform an operation on (almost) all vnodes from a given mountpoint.
vnode_lookup: Convert a path into a vnode.
vnode_mount: Get the mount structure for the filesystem that a vnode belongs to.
vnode_mountedhere: Returns a pointer to a mount placed on top of a vnode, should it exist.
vnode_open: Open a file identified by a path--roughly speaking an in-kernel open(2).
vnode_put: Decrement the iocount on a vnode.
vnode_putname: Release a reference on a name from the VFS cache.
vnode_recycle: Cause a vnode to be reclaimed and prepared for reuse.
vnode_ref: Increment the usecount on a vnode.
vnode_rele: Decrement the usecount on a vnode.
vnode_removefsref: Mark a vnode as no longer being stored in a filesystem hash.
vnode_setattr: Set vnode attributes.
vnode_setmountedon: Set flags indicating that a block device vnode has been mounted as a filesystem.
vnode_setmultipath: Mark a vnode as being reachable by multiple paths, i.e. as a hard link.
vnode_setnocache: Set a vnode to not have its data cached in memory (i.e. we write-through to disk and always read from disk).
vnode_setnoreadahead: Set a vnode to not have data speculatively read in in hopes of hitting in cache.
vnode_settag: Set a vnode filesystem-specific "tag."
vnode_specrdev: Return the device id of the device associated with a special file.
vnode_startwrite(vnode_t): Increment the count of pending writes on a vnode.
vnode_startwrite(vnode_t): Decrement the count of pending writes on a vnode .
vnode_tag: Get the vnode filesystem-specific "tag."
vnode_uncache_credentials: Clear out cached credentials on a vnode.
vnode_update_identity: Update vnode data associated with the vfs cache.
vnode_vfs64bitready: Determine if the filesystem to which a vnode belongs is marked as ready to interact with 64-bit user processes.
vnode_vfsisrdonly: Determine if the filesystem to which a vnode belongs is mounted read-only.
vnode_vfsmaxsymlen: Determine the maximum length of a symbolic link for the filesystem on which a vnode resides.
vnode_vfsname: Get the name of the filesystem to which a vnode belongs.
vnode_vfstypenum: Get the "type number" of the filesystem to which a vnode belongs.
vnode_vid: Return a vnode's vid (generation number), which is constant from creation until reclaim.
vnode_vtype: Return a vnode's type.
vnode_waitforwrites: Wait for the number of pending writes on a vnode to drop below a target.
vnode_writedone: Decrement the count of pending writes on a vnode .

cache_enter

Add a (name,vnode) entry to the VFS namecache.


void cache_enter(
    vnode_t dvp,
    vnode_t vp,
    struct componentname *cnp);

Parameters

dvp: Directory in which file lives.
vp: File to add to cache. A non-NULL vp is stored for rapid access; a NULL vp indicates that there is no such file in the directory and speeds future failed lookups.
cnp: Various data about lookup, e.g. filename and intended operation.

Return Value

void.

Discussion

Generally used to add a cache entry after a successful filesystem-level lookup or to add a negative entry after one which did not find its target.

cache_lookup

Check for a filename in a directory using the VFS name cache.


int cache_lookup(
    vnode_t dvp,
    vnode_t *vpp,
    struct componentname *cnp);

Parameters

dvp: Directory in which lookup is occurring.
vpp: Destination for vnode pointer.
cnp: Various data about lookup, e.g. filename and intended operation.

Return Value

ENOENT: the filesystem has previously added a negative entry with cache_enter() to indicate that there is no file of the given name in "dp." -1: successfully found a cached vnode (vpp is set). 0: No data in the cache, or operation is CRETE/RENAME.

Discussion

cache_lookup() will flush negative cache entries and return 0 if the operation of the cn_nameiop is CREATE or RENAME. Often used from the filesystem during a lookup vnop. The filesystem will be called to if there is a negative cache entry for a file, so it can make sense to initially check for negative entries (and possibly lush them).

cache_purge

Remove all data relating to a vnode from the namecache.


void cache_purge(
    vnode_t vp);

Parameters

vp: The vnode to purge.

Return Value

void.

Discussion

Will flush all hardlinks to the vnode as well as all children (should any exist). Logical to use when cached data about a vnode becomes invalid, for instance in an unlink.

cache_purge_negatives

Remove all negative cache entries which are children of a given vnode.


void cache_purge_negatives(
    vnode_t vp);

Parameters

vp: The vnode whose negative children to purge.

Return Value

void.

Discussion

Appropriate to use when negative cache information for a directory could have become invalid, e.g. after file creation.

vcount

Count total references to a given file, disregarding "kusecount" (event listener, as with O_EVTONLY) references.


int vcount(
    vnode_t vp);

Parameters

vp: The vnode whose references to count.

Return Value

Count of references.

Discussion

For a regular file, just return (usecount-kusecount); for device files, return the sum over all vnodes 'v' which reference that device of (usecount(v) - kusecount(v)). Note that this is merely a snapshot and could be invalid by the time the caller checks the result.

vflush

Reclaim the vnodes associated with a mount.


int vflush(
    struct mount *mp,
    struct vnode *skipvp,
    int flags);

Parameters

mp: The mount whose vnodes to kill.
skipvp: A specific vnode to not reclaim or to let interrupt an un-forced flush
flags: Control which

Return Value

0 for success, EBUSY if vnodes were busy and FORCECLOSE was not set.

Discussion

This function is used to clear out the vnodes associated with a mount as part of the unmount process. Its parameters can determine which vnodes to skip in the process and whether in-use vnodes should be forcibly reclaimed. Filesystems should call this function from their unmount code, because VFS code will always call it with SKIPROOT | SKIPSWAP | SKIPSYSTEM; filesystems must take care of such vnodes themselves. SKIPSYSTEM skip vnodes marked VSYSTEM FORCECLOSE force file closeure WRITECLOSE only close writeable files SKIPSWAP skip vnodes marked VSWAP SKIPROOT skip root vnodes marked VROOT

vfs_addname

Deprecated


const char *vfs_addname(
    const char *name,
    uint32_t len,
    uint32_t nc_hash,
    uint32_t flags);

Discussion

vnode_update_identity() and vnode_create() make vfs_addname() unnecessary for kexts.

vfs_context_create

Create a new vfs_context_t with appropriate references held.


vfs_context_t vfs_context_create(
    vfs_context_t);

Parameters

ctx: Context to copy, or NULL to use information from running thread.

Return Value

The new context, or NULL in the event of failure.

Discussion

The context must be released with vfs_context_rele() when no longer in use.

vfs_context_current

Get the vfs_context for the current thread, or the kernel context if there is no context for current thread.


vfs_context_t vfs_context_current(
    void);

Return Value

Context for current thread, or kernel context if thread context is unavailable.

Discussion

Kexts should not use this function--it is preferred to use vfs_context_create(NULL) and vfs_context_rele(), which ensure proper reference counting of underlying structures.

vfs_context_is64bit

Determine if a vfs_context_t corresponds to a 64-bit user process.


int vfs_context_is64bit(
    vfs_context_t);

Parameters

ctx: Context to examine.

Return Value

Nonzero if context is of 64-bit process, 0 otherwise.

vfs_context_issignal

Get a bitfield of pending signals for the BSD process associated with a vfs_context_t.


int vfs_context_issignal(
    vfs_context_t,
    sigset_t);

Parameters

ctx: Context whose associated process to find.

Return Value

Bitfield of pending signals.

Discussion

The bitfield is constructed using the sigmask() macro, in the sense of bits |= sigmask(SIGSEGV).

vfs_context_pid

Get the process id of the BSD process associated with a vfs_context_t.


int vfs_context_pid(
    vfs_context_t);

Parameters

ctx: Context whose associated process to find.

Return Value

Process id.

vfs_context_proc

Get the BSD process structure associated with a vfs_context_t.


proc_t vfs_context_proc(
    vfs_context_t);

Parameters

ctx: Context whose associated process to find.

Return Value

Process if available, NULL otherwise.

vfs_context_rele

Release references on components of a context and deallocate it.


int vfs_context_rele(
    vfs_context_t);

Parameters

ctx: Context to release.

Return Value

Always 0.

Discussion

A context should not be referenced after vfs_context_rele has been called.

vfs_context_suser

Determine if a vfs_context_t corresponds to the superuser.


int vfs_context_suser(
    vfs_context_t);

Parameters

ctx: Context to examine.

Return Value

Nonzero if context belongs to superuser, 0 otherwise.

vfs_context_ucred

Get the credential associated with a vfs_context_t.


kauth_cred_t vfs_context_ucred(
    vfs_context_t);

Parameters

ctx: Context whose associated process to find.

Return Value

Process if available, NULL otherwise.

Discussion

Succeeds if and only if the context has a thread, the thread has a task, and the task has a BSD proc.

vfs_removename

Deprecated


int vfs_removename(
    const char *name);

Discussion

vnode_update_identity() and vnode_create() make vfs_addname() unnecessary for kexts.

vfs_rootvnode

Returns the root vnode with an iocount.


vnode_t vfs_rootvnode(
    void);

Return Value

Pointer to root vnode if successful; error code if there is a problem taking an iocount.

Discussion

Caller must vnode_put() the root node when done.

vn_bwrite

System-provided implementation of "bwrite" vnop.


int vn_bwrite(
    struct vnop_bwrite_args *ap);

Parameters

ap: Standard parameters to a bwrite vnop.

Return Value

Results of buf_bwrite directly.

Discussion

This routine is available for filesystems which do not want to implement their own "bwrite" vnop. It just calls buf_bwrite() without modifying its arguments.

vn_default_error

Default vnode operation to fill unsupported slots in vnode operation vectors.


int vn_default_error(
    void);

Return Value

ENOTSUP

vn_getpath

Construct the path to a vnode.


int vn_getpath(
    struct vnode *vp,
    char *pathbuf,
    int *len);

Parameters

vp: The vnode whose path to obtain.
pathbuf: Destination for pathname; should be of size MAXPATHLEN
len: Destination for length of resulting path string. Result will include NULL-terminator in count--that is, "len" will be strlen(pathbuf) + 1.

Return Value

0 for success or an error code.

Discussion

Paths to vnodes are not always straightforward: a file with multiple hard-links will have multiple pathnames, and it is sometimes impossible to determine a vnode's full path. vn_getpath() will not enter the filesystem.

vn_path_package_check

Figure out if a path corresponds to a Mac OS X package.


int vn_path_package_check(
    vnode_t vp,
    char *path,
    int pathlen,
    int *component);

Parameters

vp: Unused.
path: Path to check.
pathlen: Size of path buffer.
component: Set to index of start of last path component if the path is found to be a package. Set to -1 if the path is not a known package type.

Return Value

0 unless some parameter was invalid, in which case EINVAL is returned. Determine package-ness by checking what *component is set to.

Discussion

Determines if the extension on a path is a known OS X extension type.

vn_rdwr

Read from or write to a file.


int vn_rdwr(
    enum uio_rw,
    vnode_t,
    caddr_t,
    int,
    off_t,
    enum uio_seg,
    int,
    kauth_cred_t,
    int *,
    proc_t);

Parameters

rw: UIO_READ for a read, UIO_WRITE for a write.
vp: The vnode on which to perform I/O.
base: Start of buffer into which to read or from which to write data.
len: Length of buffer.
offset: Offset within the file at which to start I/O.
segflg: What kind of address "base" is. See uio_seg definition in sys/uio.h. UIO_SYSSPACE for kernelspace, UIO_USERSPACE for userspace. UIO_USERSPACE32 and UIO_USERSPACE64 are in general preferred, but vn_rdwr will make sure that has the correct address sizes.
ioflg: Defined in vnode.h, e.g. IO_NOAUTH, IO_NOCACHE.
cred: Credential to pass down to filesystem for authentication.
aresid: Destination for amount of requested I/O which was not completed, as with uio_resid().
p: Process requesting I/O.

Return Value

0 for success; errors from filesystem, and EIO if did not perform all requested I/O and the "aresid" parameter is NULL.

Discussion

vn_rdwr() abstracts the details of constructing a uio and picking a vnode operation to allow simple in-kernel file I/O.

vn_revoke

Invalidate all references to a vnode.


int vn_revoke(
    vnode_t vp,
    int flags,
    vfs_context_t);

Parameters

vp: The vnode to revoke.
flags: Unused.
ctx: Context against which to validate operation.

Return Value

0 always.

Discussion

Reclaims the vnode, giving it deadfs vnops (though not halting operations which are already in progress). Also reclaims all aliased vnodes (important for devices). People holding usecounts on the vnode, e.g. processes with the file open, will find that all subsequent operations but closing the file fail.

vnode_addfsref

Mark a vnode as being stored in a filesystem hash.


int vnode_addfsref(
    vnode_t);

Parameters

vp: The vnode to mark.

Return Value

Always 0.

Discussion

Should only be called once on a vnode, and never if that vnode was created with VNFS_ADDFSREF. There should be a corresponding call to vnode_removefsref() when the vnode is reclaimed; VFS assumes that a n unused vnode will not be marked as referenced by a filesystem.

vnode_authattr

Given a vnode_attr structure, determine what kauth-style actions must be authorized in order to set those attributes.


int vnode_authattr(
    vnode_t,
    struct vnode_attr *,
    kauth_action_t *,
    vfs_context_t);

Parameters

vp: The vnode on which to authorize action.
vap: Pointer to vnode_attr struct containing desired attributes to set and their values.
actionp: Destination for set of actions to authorize
ctx: Context for which to authorize actions.

Return Value

0 (and a result in "actionp" for success. Otherwise, an error code.

Discussion

vnode_authorize requires kauth-style actions; if we want to set a vnode_attr structure on a vnode, we need to translate the set of attributes to a set of kauth-style actions. This routine will return errors for certain obviously disallowed, or incoherent, actions.

vnode_authattr_new

Initialize and validate file creation parameters with respect to the current context.


int vnode_authattr_new(
    vnode_t /*dvp*/,
    struct vnode_attr *,
    int /*noauth*/,
    vfs_context_t);

Parameters

dvp: The directory in which creation will occur.
vap: Pointer to vnode_attr struct containing desired attributes to set and their values.
noauth: If 1, treat the caller as the superuser, i.e. do not check permissions.
ctx: Context for which to authorize actions.

Return Value

KAUTH_RESULT_ALLOW for success, an error to indicate invalid or disallowed attributes.

Discussion

vnode_authattr_new() will fill in unitialized values in the vnode_attr struct with defaults, and will validate the structure with respect to the current context for file creation.

vnode_authorize

Authorize a kauth-style action on a vnode.


int vnode_authorize(
    vnode_t /*vp*/,
    vnode_t /*dvp*/,
    kauth_action_t,
    vfs_context_t);

Parameters

vp: Vnode on which to authorize action.
dvp: Parent of "vp," can be NULL.
action: Action to authorize, e.g. KAUTH_VNODE_READ_DATA. See bsd/sys/kauth.h.
ctx: Context for which to authorize actions.

Return Value

EACCESS if permission is denied. 0 if operation allowed. Various errors from lower layers.

Discussion

Operations on dead vnodes are always allowed (though never do anything).

vnode_clearfsnode

Sets a vnode's filesystem-specific data to be NULL.


void vnode_clearfsnode(
    vnode_t);

Parameters

vp: The vnode whose data to clear out.

Return Value

void.

Discussion

This routine should only be called when a vnode is no longer in use, i.e. during a VNOP_RECLAIM.

vnode_clearmountedon

Clear flags indicating that a block device vnode has been mounted as a filesystem.


void vnode_clearmountedon(
    vnode_t);

Parameters

vp: The vnode to clear flags on, a block device.

Return Value

void.

vnode_clearnocache

Clear the flag on a vnode indicating that data should not be cached in memory (i.e. we write-through to disk and always read from disk).


void vnode_clearnocache(
    vnode_t);

Parameters

vp: The vnode whose flags to clear.

Return Value

void.

vnode_clearnoreadahead

Clear the flag indicating that a vnode should not have data speculatively read in.


void vnode_clearnoreadahead(
    vnode_t);

Parameters

vp: The vnode whose flag to clear.

Return Value

void.

vnode_close

Close a file as opened with vnode_open().


errno_t vnode_close(
    vnode_t,
    int,
    vfs_context_t);

Parameters

vp: The vnode to close.
flags: Flags to close: FWASWRITTEN indicates that the file was written to.
ctx: Context against which to validate operation.

Return Value

0 for success or an error from the filesystem.

Discussion

vnode_close() drops the refcount (persistent reference) picked up in vnode_open() and calls down to the filesystem with VNOP_CLOSE. It should be called with both an iocount and a refcount on the vnode and will drop both.

vnode_create

Create and initialize a vnode.


errno_t vnode_create(
    uint32_t,
    uint32_t,
    void *,
    vnode_t *);

Parameters

flavor: Should be VNCREATE_FLAVOR.
size: Size of the struct vnode_fsparam in "data".
data: Pointer to a struct vnode_fsparam containing initialization information.
vpp: Pointer to a vnode pointer, to be filled in with newly created vnode.

Return Value

0 for success, error code otherwise.

Discussion

Returns wth an iocount held on the vnode which must eventually be dropped with vnode_put().

vnode_fsnode

Gets the filesystem-specific data associated with a vnode.


void * vnode_fsnode(
    vnode_t);

Parameters

vp: The vnode whose data to grab.

Return Value

The filesystem-specific data, directly.

vnode_get

Increase the iocount on a vnode.


int vnode_get(
    vnode_t);

Return Value

0 for success, ENOENT if the vnode is dead and without existing io-reference.

Discussion

If vnode_get() succeeds, the resulting io-reference must be dropped with vnode_put(). This function succeeds unless the vnode in question is dead or in the process of dying AND the current iocount is zero. This means that it can block an ongoing reclaim which is blocked behind some other iocount.

On success, vnode_get() returns with an iocount held on the vnode; this type of reference is intended to be held only for short periods of time (e.g. across a function call) and provides a strong guarantee about the life of the vnode; vnodes with positive iocounts cannot be recycled, and an iocount is required for any operation on a vnode. However, vnode_get() does not provide any guarantees about the identity of the vnode it is called on; unless there is a known existing iocount on the vnode at time the call is made, it could be recycled and put back in use before the vnode_get() succeeds, so the caller may be referencing a completely different vnode than was intended. vnode_getwithref() and vnode_getwithvid() provide guarantees about vnode identity.

vnode_getattr

Get vnode attributes.


int vnode_getattr(
    vnode_t vp,
    struct vnode_attr *vap,
    vfs_context_t ctx);

Parameters

vp: The vnode whose attributes to grab.
vap: Structure containing: 1) A list of requested attributes 2) Space to indicate which attributes are supported and being returned 3) Space to return attributes.
ctx: Context for authentication.

Return Value

0 for success or an error code.

Discussion

Desired attributes are set with VATTR_SET_ACTIVE and VNODE_ATTR* macros. Supported attributes are determined after call with VATTR_IS_SUPPORTED.

vnode_getname

Get the name of a vnode from the VFS namecache.


const char *vnode_getname(
    vnode_t vp);

Parameters

vp: The vnode whose name to grab.

Return Value

The name, or NULL if unavailable.

Discussion

Not all vnodes have names, and vnode names can change (notably, hardlinks). Use this routine at your own risk. The string is returned with a refcount incremented in the cache; callers must call vnode_putname() to release that reference.

vnode_getparent

Get an iocount on the parent of a vnode.


vnode_t vnode_getparent(
    vnode_t vp);

Parameters

vp: The vnode whose parent to grab.

Return Value

Parent if available, else NULL.

Discussion

A vnode's parent may change over time or be reclaimed, so vnode_getparent() may return different results at different times (e.g. a multiple-hardlink file). The parent is returned with an iocount which must subsequently be dropped with vnode_put().

vnode_getwithref

Increase the iocount on a vnode on which a usecount (persistent reference) is held.


int vnode_getwithref(
    vnode_t);

Return Value

0 for success, ENOENT if the vnode is dead, in the process of being reclaimed, or has been recycled and reused.

Discussion

If vnode_getwithref() succeeds, the resulting io-reference must be dropped with vnode_put(). vnode_getwithref() will succeed on dead vnodes; it should fail with ENOENT on vnodes which are in the process of being reclaimed. Because it is only called with a usecount on the vnode, the caller is guaranteed that the vnode has not been reused for a different file, though it may now be dead and have deadfs vnops (which return errors like EIO, ENXIO, ENOTDIR). On success, vnode_getwithref() returns with an iocount held on the vnode; this type of reference is intended to be held only for short periods of time (e.g. across a function call) and provides a strong guarantee about the life of the vnode. vnodes with positive iocounts cannot be recycled. An iocount is required for any operation on a vnode.

vnode_getwithvid

Increase the iocount on a vnode, checking that the vnode is alive and has not changed vid (i.e. been recycled)


int vnode_getwithvid(
    vnode_t,
    uint32_t);

Return Value

0 for success, ENOENT if the vnode is dead, in the process of being reclaimed, or has been recycled and reused.

Discussion

If vnode_getwithvid() succeeds, the resulting io-reference must be dropped with vnode_put(). This function succeeds unless the vnode in question is dead, in the process of dying, or has been recycled (and given a different vnode id). The intended usage is that a vnode is stored and its vid (vnode_vid(vp)) recorded while an iocount is held (example: a filesystem hash). The iocount is then dropped, and time passes (perhaps locks are dropped and picked back up). Subsequently, vnode_getwithvid() is called to get an iocount, but we are alerted if the vnode has been recycled.

On success, vnode_getwithvid() returns with an iocount held on the vnode; this type of reference is intended to be held only for short periods of time (e.g. across a function call) and provides a strong guarantee about the life of the vnode. vnodes with positive iocounts cannot be recycled. An iocount is required for any operation on a vnode.

vnode_hascleanblks

Check if a vnode has clean buffers associated with it.


int vnode_hascleanblks(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if there are clean blocks, 0 otherwise.

Discussion

Note that this routine is unsynchronized; it is only a snapshot and its result may cease to be true at the moment it is returned..

vnode_hasdirtyblks

Check if a vnode has dirty data waiting to be written to disk.


int vnode_hasdirtyblks(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if there are dirty blocks, 0 otherwise

Discussion

Note that this routine is unsynchronized; it is only a snapshot and its result may cease to be true at the moment it is returned..

vnode_isblk

Determine if a vnode is a block device special file.


int vnode_isblk(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is of type VBLK, 0 otherwise.

vnode_ischr

Determine if a vnode is a character device special file.


int vnode_ischr(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is of type VCHR, 0 otherwise.

vnode_isdir

Determine if a vnode is a directory.


int vnode_isdir(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is of type VDIR, 0 otherwise.

vnode_isfifo

Determine if a vnode is a named pipe.


int vnode_isfifo(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is of type VFIFO, 0 otherwise.

vnode_isinuse

Determine if the number of persistent (usecount) references on a vnode is greater than a given count.


int vnode_isinuse(
    vnode_t,
    int);

Parameters

vp: The vnode whose use-status to check.
refcnt: The threshold for saying that a vnode is in use.

Return Value

void.

Discussion

vnode_isinuse() compares a vnode's usecount (corresponding to vnode_ref() calls) to its refcnt parameter (the number of references the caller expects to be on the vnode). Note that "kusecount" references, corresponding to parties interested only in event notifications, e.g. open(..., O_EVTONLY), are not counted towards the total; the comparison is (usecount - kusecount > recnt). It is also important to note that the result is only a snapshot; usecounts can change from moment to moment, and the result of vnode_isinuse may no longer be correct the very moment that the caller receives it.

vnode_islnk

Determine if a vnode is a symbolic link.


int vnode_islnk(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is of type VLNK, 0 otherwise.

vnode_ismount

Determine if there is currently a mount occurring which will cover this vnode.


int vnode_ismount(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if there is a mount in progress, 0 otherwise.

Discussion

Note that this is only a snapshot; a mount may begin or end at any time.

vnode_ismountedon

Determine if a vnode is a block device on which a filesystem has been mounted.


int vnode_ismountedon(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is a block device on which an filesystem is mounted, 0 otherwise.

Discussion

A block device marked as being mounted on cannot be opened.

vnode_isnamedstream

Determine if a vnode is a named stream.


int vnode_isnamedstream(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is a named stream, 0 otherwise.

vnode_isnocache

Check if a vnode is set to not have its data cached in memory (i.e. we write-through to disk and always read from disk).


int vnode_isnocache(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if vnode is set to not have data chached, 0 otherwise.

vnode_isnoreadahead

Check if a vnode is set to not have data speculatively read in in hopes of future cache hits.


int vnode_isnoreadahead(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if readahead is disabled, 0 otherwise.

vnode_israge

Check if a vnode is marked for rapid aging


int vnode_israge(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if vnode is marked for rapid aging, 0 otherwise

vnode_isrecycled

Check if a vnode is dead or in the process of being killed (recycled).


int vnode_isrecycled(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if vnode is dead or being recycled, 0 otherwise.

Discussion

This is only a snapshot: a vnode may start to be recycled, or go from dead to in use, at any time.

vnode_isreg

Determine if a vnode is a regular file.


int vnode_isreg(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is of type VREG, 0 otherwise.

vnode_isswap

Determine if a vnode is being used as a swap file.


int vnode_isswap(
    vnode_t vp);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is being used as swap, 0 otherwise.

vnode_issystem

Determine if a vnode is marked as a System vnode.


int vnode_issystem(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is a system vnode, 0 if it is not.

vnode_isvroot

Determine if a vnode is the root of its filesystem.


int vnode_isvroot(
    vnode_t);

Parameters

vp: The vnode to test.

Return Value

Nonzero if the vnode is the root, 0 if it is not.

vnode_iterate

Perform an operation on (almost) all vnodes from a given mountpoint.


int vnode_iterate(
    struct mount *,
    int,
    int (*)(
        struct vnode *,
        void *),
    void *);

Parameters

mp: Mount whose vnodes to operate on.
flags: VNODE_RELOAD Mark inactive vnodes for recycle. VNODE_WAIT VNODE_WRITEABLE Only examine vnodes with writes in progress. VNODE_WITHID No effect. VNODE_NOLOCK_INTERNAL No effect. VNODE_NODEAD No effect. VNODE_NOSUSPEND No effect. VNODE_ITERATE_ALL No effect. VNODE_ITERATE_ACTIVE No effect. VNODE_ITERATE_INACTIVE No effect.
callout: Function to call on each vnode.
arg: Argument which will be passed to callout along with each vnode.

Return Value

Zero for success, else an error code. Will return 0 immediately if there are no vnodes hooked into the mount.

Discussion

Skips vnodes which are dead, in the process of reclaim, suspended, or of type VNON.

vnode_lookup

Convert a path into a vnode.


errno_t vnode_lookup(
    const char *,
    int,
    vnode_t *,
    vfs_context_t);

Parameters

path: Path to look up.
flags: VNODE_LOOKUP_NOFOLLOW: do not follow symbolic links. VNODE_LOOKUP_NOCROSSMOUNT: do not cross mount points.

Return Value

Results 0 for success or an error code.

Discussion

This routine is a thin wrapper around xnu-internal lookup routines; if successful, it returns with an iocount held on the resulting vnode which must be dropped with vnode_put().

vnode_mount

Get the mount structure for the filesystem that a vnode belongs to.


mount_t vnode_mount(
    vnode_t);

Parameters

vp: The vnode whose mount to grab.

Return Value

The mount, directly.

vnode_mountedhere

Returns a pointer to a mount placed on top of a vnode, should it exist.


mount_t vnode_mountedhere(
    vnode_t vp);

Parameters

vp: The vnode from whom to take the covering mount.

Return Value

Pointer to mount covering a vnode, or NULL if none exists.

vnode_open

Open a file identified by a path--roughly speaking an in-kernel open(2).


errno_t vnode_open(
    const char *,
    int,
    int,
    int,
    vnode_t *,
    vfs_context_t);

Parameters

path: Path to look up.
fmode: e.g. O_NONBLOCK, O_APPEND; see bsd/sys/fcntl.h.
cmode: Permissions with which to create file if it does not exist.
flags: Same as vnode_lookup().
vpp: Destination for vnode.
ctx: Context with which to authorize open/creation.

Return Value

0 for success or an error code.

Discussion

If vnode_open() succeeds, it returns with both an iocount and a usecount on the returned vnode. These must be released eventually; the iocount should be released with vnode_put() as soon as any initial operations on the vnode are over, whereas the usecount should be released via vnode_close().

vnode_put

Decrement the iocount on a vnode.


int vnode_put(
    vnode_t);

Parameters

vp: The vnode whose iocount to drop.

Return Value

Always 0.

Discussion

vnode_put() is called to indicate that a vnode is no longer in active use. It removes the guarantee that a vnode will not be recycled. This routine should be used to release io references no matter how they were obtained.

vnode_putname

Release a reference on a name from the VFS cache.


void vnode_putname(
    const char *name);

Parameters

name: String to release.

Return Value

void.

Discussion

Should be called on a string obtained with vnode_getname().

vnode_recycle

Cause a vnode to be reclaimed and prepared for reuse.


int vnode_recycle(
    vnode_t);

Parameters

vp: The vnode to recycle.

Return Value

1 if the vnode was reclaimed (i.e. there were no existing references), 0 if it was only marked for future reclaim.

Discussion

Like all vnode KPIs, must be called with an iocount on the target vnode. vnode_recycle() will mark that vnode for reclaim when all existing references are dropped.

vnode_ref

Increment the usecount on a vnode.


int vnode_ref(
    vnode_t);

Parameters

vp: The vnode on which to obtain a persistent reference.

Return Value

0 for success; ENOENT if the vnode is dead or in the process of being recycled AND the calling thread is not the vnode owner.

Discussion

If vnode_ref() succeeds, the resulting usecount must be released with vnode_rele(). vnode_ref() is called to obtain a persistent reference on a vnode. This type of reference does not provide the same strong guarantee that a vnode will persist as does an iocount--it merely ensures that a vnode will not be reused to represent a different file. However, a usecount may be held for extended periods of time, whereas an iocount is intended to be obtained and released quickly as part of performing a vnode operation. A holder of a usecount must call vnode_getwithref()/vnode_put() in order to perform any operations on that vnode.

vnode_rele

Decrement the usecount on a vnode.


void vnode_rele(
    vnode_t);

Parameters

vp: The vnode whose usecount to drop.

Return Value

void.

Discussion

vnode_rele() is called to relese a persistent reference on a vnode. Releasing the last usecount opens the door for a vnode to be reused as a new file; it also triggers a VNOP_INACTIVE call to the filesystem, though that will not happen immediately if there are outstanding iocount references.

vnode_removefsref

Mark a vnode as no longer being stored in a filesystem hash.


int vnode_removefsref(
    vnode_t);

Parameters

vp: The vnode to unmark.

Return Value

Always 0.

Discussion

Should only be called once on a vnode (during a reclaim), and only after the vnode has either been created with VNFS_ADDFSREF or marked by vnode_addfsref().

vnode_setattr

Set vnode attributes.


int vnode_setattr(
    vnode_t vp,
    struct vnode_attr *vap,
    vfs_context_t ctx);

Parameters

vp: The vnode whose attributes to set.
vap: Structure containing: 1) A list of attributes to set 2) Space for values for those attributes 3) Space to indicate which attributes were set.
ctx: Context for authentication.

Return Value

0 for success or an error code.

Discussion

Attributes to set are marked with VATTR_SET_ACTIVE and VNODE_ATTR* macros. Attributes successfully set are determined after call with VATTR_IS_SUPPORTED.

vnode_setmountedon

Set flags indicating that a block device vnode has been mounted as a filesystem.


void vnode_setmountedon(
    vnode_t);

Parameters

vp: The vnode to set flags on, a block device.

Return Value

void.

Discussion

A block device marked as being mounted on cannot be opened.

vnode_setmultipath

Mark a vnode as being reachable by multiple paths, i.e. as a hard link.


void vnode_setmultipath(
    vnode_t vp);

Parameters

vp: The vnode to mark.

Return Value

void.

Discussion

"Multipath" vnodes can be reached through more than one entry in the filesystem, and so must be handled differently for caching and event notification purposes. A filesystem should mark a vnode with multiple hardlinks this way.

vnode_setnocache

Set a vnode to not have its data cached in memory (i.e. we write-through to disk and always read from disk).


void vnode_setnocache(
    vnode_t);

Parameters

vp: The vnode whose flags to set.

Return Value

void.

vnode_setnoreadahead

Set a vnode to not have data speculatively read in in hopes of hitting in cache.


void vnode_setnoreadahead(
    vnode_t);

Parameters

vp: The vnode on which to prevent readahead.

Return Value

void.

vnode_settag

Set a vnode filesystem-specific "tag."


void vnode_settag(
    vnode_t,
    int);

Parameters

vp: The vnode whose tag to set.

Return Value

void.

Discussion

Sets a tag indicating which filesystem a vnode belongs to, e.g. VT_HFS, VT_UDF, VT_ZFS. The kernel never inspects this data, though the filesystem tags are defined in vnode.h; it is for the benefit of user programs via getattrlist.

vnode_specrdev

Return the device id of the device associated with a special file.


dev_t vnode_specrdev(
    vnode_t);

Parameters

vp: The vnode whose device id to extract--vnode must be a special file.

Return Value

The device id.

vnode_startwrite(vnode_t)

Increment the count of pending writes on a vnode.


void vnode_startwrite(
    vnode_t);

Parameters

vp: The vnode whose count to increment.

Return Value

void.

vnode_startwrite(vnode_t)

Decrement the count of pending writes on a vnode .


void vnode_writedone(
    vnode_t);

Parameters

vp: The vnode whose count to decrement.

Return Value

void.

Discussion

Also wakes up threads waiting for the write count to drop, as in vnode_waitforwrites.

vnode_tag

Get the vnode filesystem-specific "tag."


int vnode_tag(
    vnode_t);

Parameters

vp: The vnode whose tag to grab.

Return Value

The tag.

Discussion

Gets the tag indicating which filesystem a vnode belongs to, e.g. VT_HFS, VT_UDF, VT_ZFS. The kernel never inspects this data, though the filesystem tags are defined in vnode.h; it is for the benefit of user programs via getattrlist.

vnode_uncache_credentials

Clear out cached credentials on a vnode.


void vnode_uncache_credentials(
    vnode_t vp);

Parameters

vp: The vnode whose cache to clear.

Return Value

void.

Discussion

When we authorize an action on a vnode, we cache the credential that was authorized and the actions it was authorized for in case a similar request follows. This function destroys that caching.

vnode_update_identity

Update vnode data associated with the vfs cache.


void vnode_update_identity(
    vnode_t vp,
    vnode_t dvp,
    const char *name,
    int name_len,
    uint32_t name_hashval,
    int flags);

Parameters

vp: The vnode whose information to update.
dvp: Parent to set on the vnode if VNODE_UPDATE_PARENT is used.
name: Name to set in the cache for the vnode if VNODE_UPDATE_NAME is used. The buffer passed in can be subsequently freed, as the cache does its own name storage. String should be NULL-terminated unless length and hash value are specified.
name_len: Length of name, if known. Passing 0 causes the cache to determine the length itself.
name_hashval: Hash value of name, if known. Passing 0 causes the cache to hash the name itself.
flags: VNODE_UPDATE_PARENT: set parent. VNODE_UPDATE_NAME: set name. VNODE_UPDATE_CACHE: flush cache entries for hard links associated with this file. VNODE_UPDATE_PURGE: flush cache entries for hard links and children of this file.

Return Value

void.

Discussion

The vfs namecache is central to tracking vnode-identifying data and to locating files on the system. vnode_update_identity() is used to update vnode data associated with the cache. It can set a vnode's parent and/or name (also potentially set by vnode_create()) or flush cache data.

vnode_vfs64bitready

Determine if the filesystem to which a vnode belongs is marked as ready to interact with 64-bit user processes.


int vnode_vfs64bitready(
    vnode_t);

Parameters

vp: The vnode whose filesystem to examine.

Return Value

Nonzero if filesystem is marked ready for 64-bit interactions; 0 otherwise.

vnode_vfsisrdonly

Determine if the filesystem to which a vnode belongs is mounted read-only.


int vnode_vfsisrdonly(
    vnode_t);

Parameters

vp: The vnode for which to get filesystem writeability.

Return Value

Nonzero if the filesystem is read-only, 0 otherwise.

vnode_vfsmaxsymlen

Determine the maximum length of a symbolic link for the filesystem on which a vnode resides.


uint32_t vnode_vfsmaxsymlen(
    vnode_t);

Parameters

vp: The vnode for which to get filesystem symlink size cap.

Return Value

Max symlink length.

vnode_vfsname

Get the name of the filesystem to which a vnode belongs.


void vnode_vfsname(
    vnode_t,
    char *);

Parameters

vp: The vnode whose filesystem to examine.
buf: Destination for vfs name: should have size MFSNAMELEN or greater.

Return Value

The name of the fileystem to which the vnode belongs.

vnode_vfstypenum

Get the "type number" of the filesystem to which a vnode belongs.


int vnode_vfstypenum(
    vnode_t);

Parameters

vp: The vnode whose filesystem to examine.

Return Value

The type number of the fileystem to which the vnode belongs.

Discussion

This is an archaic construct; most filesystems are assigned a type number based on the order in which they are registered with the system.

vnode_vid

Return a vnode's vid (generation number), which is constant from creation until reclaim.


uint32_t vnode_vid(
    vnode_t);

Parameters

vp: The vnode whose vid to grab.

Return Value

The vnode's vid.

vnode_vtype

Return a vnode's type.


enum vtype vnode_vtype(
    vnode_t);

Parameters

vp: The vnode whose type to grab.

Return Value

The vnode's type.

vnode_waitforwrites

Wait for the number of pending writes on a vnode to drop below a target.


int vnode_waitforwrites(
    vnode_t,
    int,
    int,
    int,
    const char *);

Parameters

vp: The vnode to monitor.
output_target: Max pending write count with which to return.
slpflag: Flags for msleep().
slptimeout: Frequency with which to force a check for completion; increments of 10 ms.
msg: String to pass msleep() .

Return Value

0 for success, or an error value from msleep().

vnode_writedone

Decrement the count of pending writes on a vnode .


void vnode_writedone(
    vnode_t);

Parameters

vp: The vnode whose count to decrement.

Return Value

void.

Discussion

Also wakes up threads waiting for the write count to drop, as in vnode_waitforwrites.

Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: Kernel Device Drivers Kernel Framework Reference

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2010-07-29