vnode.h Reference

Declared in
vnode.h

Overview

Included Headers

  • <sys/appleapiopts.h>

  • <sys/cdefs.h>

  • <sys/kernel_types.h>

  • <sys/param.h>

  • <sys/signal.h>

  • <sys/vnode_if.h>

Functions

See the Overview section above for header-level documentation.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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).

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
vnode.h

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

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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).

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

vfs_removename

Deprecated

int vfs_removename(
   const char *name);
Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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).

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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().

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
vnode.h

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().

Availability
  • Available in OS X v10.6 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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..

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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..

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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

Availability
  • Available in OS X v10.6 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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().

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

vnode_needssnapshots

Check if a vnode needs snapshots events (regardless of its ctime status)

int vnode_needssnapshots(
   vnode_t);
Parameters
vp

The vnode to test.

Return Value

Nonzero if vnode needs snapshot events, 0 otherwise

Availability
  • Available in OS X v10.7 and later.
Declared In
vnode.h

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().

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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().

Availability
  • Available in OS X v10.6 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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().

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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().

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

vn_default_error

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

int vn_default_error(
   void);
Return Value

ENOTSUP

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
vnode.h

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
vnode.h