vnode_if.h Reference

Declared in
vnode_if.h

Overview

Included Headers

  • <sys/appleapiopts.h>

  • <sys/cdefs.h>

  • <sys/kernel_types.h>

  • <sys/buf.h>

  • <mach/memory_object_types.h>

Functions

See the Overview section above for header-level documentation.

VNOP_BWRITE

Write a buffer to backing store.

extern errno_t VNOP_BWRITE(
   buf_t);
Parameters
bp

The buffer to write.

Return Value

0 for success, else an error code.

Discussion

VNOP_BWRITE() is called by buf_bawrite() (asynchronous write) and potentially by buf_bdwrite() (delayed write) but not by buf_bwrite(). A filesystem may choose to perform some kind of manipulation of the buffer in this routine; it generally will end up calling VFS's default implementation, vn_bwrite() (which calls buf_bwrite() without further ado).

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

VNOP_FSYNC

Call down to a filesystem to synchronize a file with on-disk state.

extern errno_t VNOP_FSYNC(
   vnode_t,
   int,
   vfs_context_t);
Parameters
vp

The vnode whose data to flush to backing store.

ctx

Context to authenticate for fsync request.

Return Value

0 for success, else an error code.

Discussion

VNOP_FSYNC is called whenever we need to make sure that a file's data has been pushed to backing store, for example when recycling; it is also the heart of the fsync() system call.

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

VNOP_GETXATTR

Get extended file attributes.

extern errno_t VNOP_GETXATTR(
   vnode_t,
   const char *,
   uio_t,
   size_t *,
   int,
   vfs_context_t);
Parameters
vp

The vnode to get extended attributes for.

name

Which property to extract.

uio

Destination information for attribute value.

size

Should be set to the amount of data written.

options

XATTR_NOSECURITY: bypass security-checking.

ctx

Context to authenticate for getxattr request.

Return Value

0 for success, or an error code.

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

VNOP_IOCTL

Call down to a filesystem or device driver to execute various control operations on or request data about a file.

extern errno_t VNOP_IOCTL(
   vnode_t,
   u_long,
   caddr_t,
   int,
   vfs_context_t);
Parameters
vp

The vnode to execute the command on.

command

Identifier for action to take.

data

Pointer to data; this can be an integer constant (of 32 bits only) or an address to be read from or written to, depending on "command." If it is an address, it is valid and resides in the kernel; callers of VNOP_IOCTL() are responsible for copying to and from userland.

ctx

Context against which to authenticate ioctl request.

Return Value

0 for success or a filesystem-specific error.

Discussion

Ioctl controls are typically associated with devices, but they can in fact be passed down for any file; they are used to implement any of a wide range of controls and information requests. fcntl() calls VNOP_IOCTL for several commands, and will attempt a VNOP_IOCTL if it is passed an unknown command, though no copyin or copyout of arguments can occur in this case--the "arg" must be an integer value. Filesystems can define their own fcntls using this mechanism. How ioctl commands are structured is slightly complicated; see the manual page for ioctl(2).

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

VNOP_READ

Call down to a filesystem to read file data.

extern errno_t VNOP_READ(
   vnode_t,
   struct uio *,
   int,
   vfs_context_t);
Parameters
vp

The vnode to read from.

uio

Description of request, including file offset, amount of data requested, destination address for data, and whether that destination is in kernel or user space.

ctx

Context against which to authenticate read request.

Return Value

0 for success or a filesystem-specific error. VNOP_READ() can return success even if less data was read than originally requested; returning an error value should indicate that something actually went wrong.

Discussion

VNOP_READ() is where the hard work of of the read() system call happens. The filesystem may use the buffer cache, the cluster layer, or an alternative method to get its data; uio routines will be used to see that data is copied to the correct virtual address in the correct address space and will update its uio argument to indicate how much data has been moved.

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

VNOP_SETXATTR

Set extended file attributes.

extern errno_t VNOP_SETXATTR(
   vnode_t,
   const char *,
   uio_t,
   int,
   vfs_context_t);
Parameters
vp

The vnode to set extended attributes for.

name

Which property to extract.

uio

Source information for attribute value.

options

XATTR_NOSECURITY: bypass security-checking. XATTR_CREATE: set value, fail if exists. XATTR_REPLACE: set value, fail if does not exist.

ctx

Context to authenticate for setxattr request.

Return Value

0 for success, or an error code.

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

VNOP_STRATEGY

Initiate I/O on a file (both read and write).

extern errno_t VNOP_STRATEGY(
   struct buf *bp);
Parameters
bp

Complete specificiation of requested I/O: region of data involved, whether request is for read or write, and so on.

Return Value

0 for success, else an error code.

Discussion

A filesystem strategy routine takes a buffer, performs whatever manipulations are necessary for passing the I/O request down to the device layer, and calls the appropriate device's strategy routine. Most filesystems should just call buf_strategy() with "bp" as the argument.

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

VNOP_WRITE

Call down to the filesystem to write file data.

extern errno_t VNOP_WRITE(
   vnode_t,
   struct uio *,
   int,
   vfs_context_t);
Parameters
vp

The vnode to write to.

uio

Description of request, including file offset, amount of data to write, source address for data, and whether that destination is in kernel or user space.

ctx

Context against which to authenticate write request.

Return Value

0 for success or a filesystem-specific error. VNOP_WRITE() can return success even if less data was written than originally requested; returning an error value should indicate that something actually went wrong.

Discussion

VNOP_WRITE() is to write() as VNOP_READ() is to read(). The filesystem may use the buffer cache, the cluster layer, or an alternative method to write its data; uio routines will be used to see that data is copied to the correct virtual address in the correct address space and will update its uio argument to indicate how much data has been moved.

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

Data Types

See the Overview section above for header-level documentation.

vnop_access_args

Call down to a filesystem to close a file.

struct vnop_access_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   int a_action;
   vfs_context_t a_context;
};
Fields
vp

File to close.

fflag

FREAD and/or FWRITE; in the case of a file opened with open(2), fflag corresponds to how the file was opened.

ctx

Context against which to authenticate close.

Discussion

The close vnop gives a filesystem a chance to release state set up by a VNOP_OPEN(). VFS promises to send down exactly one VNOP_CLOSE() for each VNOP_OPEN().

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

vnop_advlock_args

Query a filesystem for path properties.

struct vnop_advlock_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   caddr_t a_id;
   int a_op;
   struct flock *a_fl;
   int a_flags;
   vfs_context_t a_context;
   struct timespec *a_timeout;
};
Fields
vp

The vnode whose filesystem to query.

name

Which property to request: see unistd.h. For example: _PC_CASE_SENSITIVE (is a filesystem case-sensitive?). Only one property can be requested at a time.

retval

Destination for value of property.

ctx

Context to authenticate for pathconf request.

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

vnop_allocate_args

Aquire or release and advisory lock on a vnode.

struct vnop_allocate_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   off_t a_length;
   u_int32_t a_flags;
   off_t *a_bytesallocated;
   off_t a_offset;
   vfs_context_t a_context;
};
Fields
vp

The vnode to lock or unlock.

id

Identifier for lock holder: ignored by most filesystems.

op

Which locking operation: F_SETLK: set locking information about a region. F_GETLK: get locking information about the specified region. F_UNLCK: Unlock a region.

fl

Description of file region to lock. l_whence is as with "lseek." Includes a type: F_RDLCK (shared lock), F_UNLCK (unlock) , and F_WRLCK (exclusive lock).

flags

F_FLOCK: use flock() semantics. F_POSIX: use POSIX semantics. F_WAIT: sleep if necessary. F_PROV: Non-coelesced provisional lock (unused in xnu).

ctx

Context to authenticate for advisory locking request.

timeout

Timespec for timeout in case of F_SETLKWTIMEOUT.

Discussion

Advisory locking is somewhat complicated. VNOP_ADVLOCK is overloaded for both flock() and POSIX advisory locking usage, though not all filesystems support both (or any). VFS provides an advisory locking mechanism for filesystems which can take advantage of it; vfs_setlocklocal() marks a filesystem as using VFS advisory locking support.

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

vnop_blktooff_args

List extended attribute keys.

struct vnop_blktooff_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   daddr64_t a_lblkno;
   off_t *a_offset;
};
Fields
vp

The vnode for which to get extended attribute keys.

uio

Description of target memory for attribute keys.

size

Should be set to amount of data written to buffer.

options

XATTR_NOSECURITY: bypass security checking.

ctx

Context to authenticate for attribute name request.

Discussion

Should write a sequence of unseparated, null-terminated extended-attribute names into the space described by the provided uio. These keys can then be passed to getxattr() (and VNOP_GETXATTR()).

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

vnop_blockmap_args

Call down to a filesystem to convert a file offset to a logical block number.

struct vnop_blockmap_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   off_t a_foffset;
   size_t a_size;
   daddr64_t *a_bpn;
   size_t *a_run;
   void *a_poff;
   int a_flags;
   vfs_context_t a_context;
};
Fields
vp

The vnode for which to convert an offset to a logical block number.

offset

File offset to convert.

lblkno

Destination for corresponding logical block number.

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

vnop_close_args

Call down to a filesystem to open a file.

struct vnop_close_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   int a_fflag;
   vfs_context_t a_context;
};
Fields
vp

File to open.

mode

FREAD and/or FWRITE.

ctx

Context against which to authenticate open.

Discussion

The open vnop gives a filesystem a chance to initialize a file for operations like reading, writing, and ioctls. VFS promises to send down exactly one VNOP_CLOSE() for each VNOP_OPEN().

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

vnop_copyfile_args

Write data from a mapped file back to disk.

/*
@function VNOP_SEARCHFS
@abstract Search a filesystem quickly for files or directories that match the passed-in search criteria.
@discussion VNOP_SEARCHFS is a getattrlist-based system call which is implemented almost entirely inside
supported filesystems.  Callers provide a set of criteria to match against, and the filesystem is responsible
for finding all files or directories that match the criteria.  Once these files or directories are found,
the user-requested attributes of these files is provided as output.  The set of searchable attributes is a
subset of the getattrlist  attributes.  For example, ATTR_CMN_UUID is not a valid searchable attribute as of
10.6.  A common usage scenario could be to request all files whose mod dates is greater than time X, less than
time Y, and provide the inode ID and filename of the matching objects as output.
@param vp The vnode representing the mountpoint of the filesystem to be searched.
@param a_searchparams1 If one-argument search criteria is requested, the search criteria would go here. However,
some search criteria, like ATTR_CMN_MODTIME, can be bounded.  The user could request files modified between time X
and time Y.  In this case, the lower bound goes in a_searchparams1.
@param a_searchparams2 If two-argument search criteria is requested, the upper bound goes in here.
@param a_searchattrs Contains the getattrlist-style attribute bits which are requested by the current search.
@param a_maxmatches The maximum number of matches to return in a single system call.
@param a_timelimit The suggested maximum amount of time we can spend in the kernel to service this system call.
Filesystems should use this as a guide only, and set their own internal maximum time to avoid denial of service.
@param a_returnattrs The getattrlist-style attributes to return for items in the filesystem that match the search
criteria above.
@param a_scriptcode Currently ignored.
@param a_uio The uio in which to write out the search matches.
@param a_searchstate Sometimes searches cannot be completed in a single system call.  In this case, we provide
an identifier back to the user which indicates where to resume a previously-started search.  This is an opaque structure
used by the filesystem to identify where to resume said search.
@param a_context The context in which to perform the filesystem search.
@return 0 on success, EAGAIN for searches which could not be completed in 1 call, and other ERRNOS as needed.
*/
struct vnop_copyfile_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_fvp;
   vnode_t a_tdvp;
   vnode_t a_tvp;
   struct componentname *a_tcnp;
   int a_mode;
   int a_flags;
   vfs_context_t a_context;
};
Fields
vp

The vnode for which to page out data.

pl

UPL describing pages needed to be paged out. If UPL is NULL, then it means the filesystem has opted into VFC_VFSVNOP_PAGEOUTV2 semantics, which means that it will create and operate on its own UPLs as opposed to relying on the one passed down into the filesystem. This means that the filesystem must be responsible for N cluster_pageout calls for N dirty ranges in the UPL.

pl_offset

Offset in UPL from which to start paging out data. Under the new VFC_VFSVNOP_PAGEOUTV2 semantics, this is the offset in the range specified that must be paged out if the associated page is dirty.

f_offset

Offset in file of data needing to be paged out. Under the new VFC_VFSVNOP_PAGEOUTV2 semantics, this represents the offset in the file where we should start looking for dirty pages.

size

Amount of data to page out (in bytes). Under VFC_VFSVNOP_PAGEOUTV2, this represents the size of the range to be considered. The fileystem is free to extend or shrink the specified range to better fit its blocking model as long as the page at 'pl_offset' is included.

flags

UPL-style flags: UPL_IOSYNC, UPL_NOCOMMIT, UPL_NORDAHEAD, UPL_VNODE_PAGER, UPL_MSYNC. Filesystems should generally leave it to the cluster layer to handle these flags. See the memory_object_types.h header in the kernel framework if interested.

ctx

Context to authenticate for pageout request.

Discussion

VNOP_PAGEOUT() is called when data from a mapped file needs to be flushed to disk, either because of an msync() call or due to memory pressure. Filesystems are for the most part expected to just call cluster_pageout(). However, if they opt into the VFC_VFSVNOP_PAGEOUTV2 flag, then they will be responsible for creating their own UPLs.

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

vnop_create_args

Call down to a filesystem to look for a directory entry by name.

struct vnop_create_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_dvp;
   vnode_t *a_vpp;
   struct componentname *a_cnp;
   struct vnode_attr *a_vap;
   vfs_context_t a_context;
};
Fields
dvp

Directory in which to look up file.

vpp

Destination for found vnode.

cnp

Structure describing filename to find, reason for lookup, and various other data.

ctx

Context against which to authenticate lookup request.

Discussion

VNOP_LOOKUP is the key pathway through which VFS asks a filesystem to find a file. The vnode should be returned with an iocount to be dropped by the caller. A VNOP_LOOKUP() calldown can come without a preceding VNOP_OPEN().

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

vnop_exchange_args

Call down to a filesystem or device to check if a file is ready for I/O and request later notification if it is not currently ready.

struct vnop_exchange_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_fvp;
   vnode_t a_tvp;
   int a_options;
   vfs_context_t a_context;
};
Fields
vp

The vnode to check for I/O readiness.

which

What kind of I/O is desired: FREAD, FWRITE.

fflags

Flags from fileglob as seen in fcntl.h, e.g. O_NONBLOCK, O_APPEND.

wql

Opaque object to pass to selrecord().

ctx

Context to authenticate for select request.

Discussion

In general, regular are always "ready for I/O" and their select vnops simply return "1." Devices, though, may or may not be read; they keep track of who is selecting on them and send notifications when they become ready. xnu provides structures and routines for tracking threads waiting for I/O and waking up those threads: see selrecord(), selthreadclear(), seltrue(), selwait(), selwakeup(), and the selinfo structure (sys/select.h).

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

vnop_fsync_args

Inform a filesystem that a file is no longer mapped.

struct vnop_fsync_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   int a_waitfor;
   vfs_context_t a_context;
};
Fields
vp

The vnode which is no longer mapped.

ctx

Context to authenticate for mnomap request.

Discussion

In general, no action is required of a filesystem for VNOP_MNOMAP.

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

vnop_getattr_args

Call down to a filesystem to see if a kauth-style operation is permitted.

struct vnop_getattr_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   struct vnode_attr *a_vap;
   vfs_context_t a_context;
};
Fields
vp

File to authorize action for.

action

kauth-style action to be checked for permissions, e.g. KAUTH_VNODE_DELETE.

ctx

Context against which to authenticate action.

Discussion

VNOP_ACCESS is currently only called on filesystems which mark themselves as doing their authentication remotely (vfs_setauthopaque(), vfs_authopaque()). A VNOP_ACCESS() calldown may come without any preceding VNOP_OPEN().

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

vnop_getnamedstream_args

Associate a MACF label with a file.

struct vnop_getnamedstream_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   vnode_t *a_svpp;
   const char *a_name;
   enum nsoperation a_operation; int a_flags; vfs_context_t a_context;
};
Fields
vp

The vnode to label.

label

The desired label.

ctx

Context to authenticate for label change.

See Also
  • VNOP_SETLABEL
  • nsoperation
  • VNOP_SETLABEL

vnop_getxattr_args

Write data from a mapped file back to disk.

struct vnop_getxattr_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   const char *a_name;
   uio_t a_uio;
   size_t *a_size;
   int a_options;
   vfs_context_t a_context;
};
Fields
vp

The vnode for which to page out data.

pl

UPL describing pages needed to be paged out. If UPL is NULL, then it means the filesystem has opted into VFC_VFSVNOP_PAGEOUTV2 semantics, which means that it will create and operate on its own UPLs as opposed to relying on the one passed down into the filesystem. This means that the filesystem must be responsible for N cluster_pageout calls for N dirty ranges in the UPL.

pl_offset

Offset in UPL from which to start paging out data. Under the new VFC_VFSVNOP_PAGEOUTV2 semantics, this is the offset in the range specified that must be paged out if the associated page is dirty.

f_offset

Offset in file of data needing to be paged out. Under the new VFC_VFSVNOP_PAGEOUTV2 semantics, this represents the offset in the file where we should start looking for dirty pages.

size

Amount of data to page out (in bytes). Under VFC_VFSVNOP_PAGEOUTV2, this represents the size of the range to be considered. The fileystem is free to extend or shrink the specified range to better fit its blocking model as long as the page at 'pl_offset' is included.

flags

UPL-style flags: UPL_IOSYNC, UPL_NOCOMMIT, UPL_NORDAHEAD, UPL_VNODE_PAGER, UPL_MSYNC. Filesystems should generally leave it to the cluster layer to handle these flags. See the memory_object_types.h header in the kernel framework if interested.

ctx

Context to authenticate for pageout request.

Discussion

VNOP_PAGEOUT() is called when data from a mapped file needs to be flushed to disk, either because of an msync() call or due to memory pressure. Filesystems are for the most part expected to just call cluster_pageout(). However, if they opt into the VFC_VFSVNOP_PAGEOUTV2 flag, then they will be responsible for creating their own UPLs.

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

vnop_inactive_args

Call down to a filesystem to get the pathname represented by a symbolic link.

struct vnop_inactive_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   vfs_context_t a_context;
};
Fields
vp

Symbolic link to read from.

uio

Destination information for link path.

ctx

Context to authenticate for readlink request.

Discussion

VNOP_READLINK() gets the path stored in a symbolic link; it is called by namei() and the readlink() system call.

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

vnop_link_args

Call down to a filesystem to delete a file.

struct vnop_link_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   vnode_t a_tdvp;
   struct componentname *a_cnp;
   vfs_context_t a_context;
};
Fields
dvp

Directory in which to delete a file.

vp

The file to delete.

cnp

Filename information.

ctx

Context to authenticate for fsync request.

Discussion

VNOP_REMOVE is called to remove a file from a filesystem's namespace, for example by unlink(). It can operate on regular files, named pipes, special files, and in some cases on directories.

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

vnop_listxattr_args

Remove extended file attributes.

struct vnop_listxattr_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   uio_t a_uio;
   size_t *a_size;
   int a_options;
   vfs_context_t a_context;
};
Fields
vp

The vnode from which to remove extended attributes.

name

Which attribute to delete.

options

XATTR_NOSECURITY: bypass security-checking.

ctx

Context to authenticate for attribute delete request.

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

vnop_makenamedstream_args

Get a named stream associated with a file.

struct vnop_makenamedstream_args {
   struct vnodeop_desc *a_desc;
   vnode_t *a_svpp;
   vnode_t a_vp;
   const char *a_name;
   int a_flags;
   vfs_context_t a_context;
};
Fields
vp

The vnode for which to get a named stream.

svpp

Destination for pointer to named stream's vnode.

name

The name of the named stream, e.g. "com.apple.ResourceFork".

operation

Operation to perform. In HFS and AFP, this parameter is only considered as follows: if the resource fork has not been opened and the operation is not NS_OPEN, fail with ENOATTR. Currently only passed as NS_OPEN by VFS.

flags

Currently unused.

ctx

Context to authenticate for getting named stream.

Discussion

If this call sucecss, svpp should be returned with an iocount which the caller will drop. VFS provides a facility for simulating named streams when interacting with filesystems which do not support them.

vnop_mkdir_args

Call down to a filesystem to rename a file.

struct vnop_mkdir_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_dvp;
   vnode_t *a_vpp;
   struct componentname *a_cnp;
   struct vnode_attr *a_vap;
   vfs_context_t a_context;
};
Fields
fdvp

Directory in which source file resides.

fvp

File being renamed.

fcnp

Name information for source file.

tdvp

Directory file is being moved to.

tvp

Existing file with same name as target, should one exist.

tcnp

Name information for target path.

ctx

Context to authenticate for rename request.

Discussion

VNOP_RENAME() will only be called with a source and target on the same volume.

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

vnop_mknod_args

Call down to a filesystem to create a whiteout.

struct vnop_mknod_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_dvp;
   vnode_t *a_vpp;
   struct componentname *a_cnp;
   struct vnode_attr *a_vap;
   vfs_context_t a_context;
};
Fields
dvp

Directory in which to create.

cnp

Name information for whiteout.

flags

CREATE: create a whiteout. LOOKUP: check whether a directory supports whiteouts, DELETE: remove a whiteout.

ctx

Context against which to authenticate whiteout creation.

Discussion

Whiteouts are used to support the union filesystem, whereby one filesystem is mounted "transparently" on top of another. A whiteout in the upper layer of a union mount is a "deletion" of a file in the lower layer; lookups will catch the whiteout and fail, setting ISWHITEOUT in the componentname structure, even if an underlying file of the same name exists. The whiteout vnop is used for creation, deletion, and checking whether a directory supports whiteouts (see flags). also support the LOOKUP flag, which is used to test whether a directory supports whiteouts.

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

vnop_mmap_args

Call down to a filesystem to invalidate all open file descriptors for a vnode.

struct vnop_mmap_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   int a_fflags;
   vfs_context_t a_context;
};
Fields
vp

The vnode to revoke.

flags

Unused.

ctx

Context to authenticate for revoke request.

Discussion

This function is typically called as part of a TTY revoke, but can also be used on regular files. Most filesystems simply use nop_revoke(), which calls vn_revoke(), as their revoke vnop implementation.

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

vnop_mnomap_args

Notify a filesystem that a file is being mmap-ed.

struct vnop_mnomap_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   vfs_context_t a_context;
};
Fields
vp

The vnode being mmapped.

flags

Memory protection: PROT_READ, PROT_WRITE, PROT_EXEC.

ctx

Context to authenticate for mmap request.

Discussion

VNOP_MMAP is an advisory calldown to say that the system is mmap-ing a file.

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

vnop_offtoblk_args

Call down to a filesystem to convert a logical block number to a file offset.

struct vnop_offtoblk_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   off_t a_offset;
   daddr64_t *a_lblkno;
};
Fields
vp

The vnode for which to convert a logical block to an offset.

lblkno

Logical block number to turn into offset.

offset

Destination for file offset.

Discussion

VNOP_BLKTOOFF() converts a logical block to a file offset in bytes. That offset can be passed to VNOP_BLOCKMAP(), then, to get a physical block number--buf_strategy() does this.

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

vnop_open_args

Call down to a filesystem to create a special file.

struct vnop_open_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   int a_mode;
   vfs_context_t a_context;
};
Fields
dvp

Directory in which to create the special file.

vpp

Destination for newly created vnode.

cnp

Name information for new file.

vap

Attributes for new file, including type.

ctx

Context against which to authenticate node creation.

Discussion

The mknod vnop is used to create character and block device files, named pipe (FIFO) files, and named sockets. The newly created file should be returned with an iocount which will be dropped by the caller. A VNOP_MKNOD() call can come down without a preceding VNOP_OPEN().

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

vnop_pagein_args

Pre-allocate space for a file.

struct vnop_pagein_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   upl_t a_pl;
   upl_offset_t a_pl_offset;
   off_t a_f_offset;
   size_t a_size;
   int a_flags;
   vfs_context_t a_context;
};
Fields
vp

The vnode for which to preallocate space.

length

Desired preallocated file length.

flags

PREALLOCATE: preallocate allocation blocks. ALLOCATECONTIG: allocate contigious space. ALLOCATEALL: allocate all requested space or no space at all. FREEREMAINDER: deallocate allocated but unfilled blocks. ALLOCATEFROMPEOF: allocate from the physical eof. ALLOCATEFROMVOL: allocate from the volume offset.

bytesallocated

Additional bytes set aside for file. Set to 0 if none are allocated OR if the file is contracted.

offset

Hint for where to find free blocks.

ctx

Context to authenticate for allocation request.

Discussion

VNOP_ALLOCATE() changes the amount of backing store set aside to a file. It can be used to either shrink or grow a file. If the file shrinks, its ubc size will be modified accordingly, but if it grows, then the ubc size is unchanged; space is set aside without being actively used by the file. VNOP_ALLOCATE() is currently only called as part of the F_PREALLOCATE fcntl.

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

vnop_pageout_args

Pull file data into memory.

struct vnop_pageout_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   upl_t a_pl;
   upl_offset_t a_pl_offset;
   off_t a_f_offset;
   size_t a_size;
   int a_flags;
   vfs_context_t a_context;
};
Fields
vp

The vnode for which to page in data.

pl

UPL describing pages needing to be paged in.

pl_offset

Offset in UPL at which to start placing data.

f_offset

Offset in file of data needing to be paged in.

size

Amount of data to page in (in bytes).

flags

UPL-style flags: UPL_IOSYNC, UPL_NOCOMMIT, UPL_NORDAHEAD, UPL_VNODE_PAGER, UPL_MSYNC. Filesystems should generally leave it to the cluster layer to handle these flags. See the memory_object_types.h header in the kernel framework if interested.

ctx

Context to authenticate for pagein request.

Discussion

VNOP_PAGEIN() is called by when a process faults on data mapped from a file or when madvise() demands pre-fetching. It is conceptually somewhat similar to VNOP_READ(). Filesystems are typically expected to call cluster_pagein() to handle the labor of mapping and committing the UPL.

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

vnop_pathconf_args

Release filesystem-internal resources for a vnode.

struct vnop_pathconf_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   int a_name;
   int32_t *a_retval;
   vfs_context_t a_context;
};
Fields
vp

The vnode to reclaim.

ctx

Context to authenticate for reclaim.

Discussion

VNOP_RECLAIM() is called as part of the process of recycling a vnode. During a reclaim routine, a filesystem should remove a vnode from its hash and deallocate any resources allocated to that vnode. VFS guarantees that when VNOP_RECLAIM() is called, there are no more iocount references on a vnode (though there may still be usecount references--these are invalidated by the reclaim) and that no more will be granted. This means in practice that there will be no filesystem calls on the vnode being reclaimed until the reclaim has finished and the vnode has been reused.

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

vnop_read_args

Call down to a filesystem to set vnode attributes.

struct vnop_read_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   struct uio *a_uio;
   int a_ioflag;
   vfs_context_t a_context;
};
Fields
vp

The vnode whose attributes to set.

vap

Container for which attributes are to be set and their desired values, as well as for the filesystem to return information about which attributes were successfully set.

ctx

Context against which to authenticate request for attribute change.

Discussion

Supported attributes ("Yes, I am setting this attribute.") are set with VATTR_SET_SUPPORTED. Requested attributes are checked with VATTR_IS_ACTIVE. Attribute values are accessed directly through structure fields. VNOP_SETATTR() is the core of the KPI function vnode_setattr(), which is used by chmod(), chown(), truncate(), and many others. A VNOP_SETATTR() call may come without any preceding VNOP_OPEN().

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

vnop_readdir_args

Call down to a filesystem to create a symbolic link.

/*
*
*  When VNOP_READDIR is called from the NFS Server, the nfs_data
*  argument is non-NULL.
*
*  The value of nfs_eofflag should be set to TRUE if the end of
*  the directory was reached while reading.
*
*  The directory seek offset (cookies) are returned to the NFS client and
*  may be used later to restart a directory read part way through
*  the directory. There is one cookie returned for each directory
*  entry returned and its size is determince from nfs_sizeofcookie.
*  The value of the cookie should be the logical offset within the
*  directory where the on-disc version of the appropriate directory
*  entry starts. Memory for the cookies is allocated from M_TEMP
*  and it is freed by the caller of VNOP_READDIR.
*
*/
struct vnop_readdir_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   struct uio *a_uio;
   int a_flags;
   int *a_eofflag;
   int *a_numdirent;
   vfs_context_t a_context;
};
Fields
If

VNOP_SYMLINK() is successful, the new file should be returned with an iocount which will be dropped by the caller. VFS does not ensure that the target path will have a length shorter than the max symlink length for the filesystem.

dvp

Parent directory for new symlink file.

vpp
cnp

Name information for new symlink.

vap

Attributes for symlink.

target

Path for symlink to store; for "ln -s /var/vardir linktovardir", "target" would be "/var/vardir"

ctx

Context to authenticate for symlink request.

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

vnop_readdirattr_args

Call down to a filesystem to enumerate directory entries.

struct vnop_readdirattr_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   struct attrlist *a_alist;
   struct uio *a_uio;
   uint32_t a_maxcount;
   uint32_t a_options;
   uint32_t *a_newstate;
   int *a_eofflag;
   uint32_t *a_actualcount;
   vfs_context_t a_context;
};
Fields
vp

Directory to enumerate.

uio

Destination information for resulting direntries.

flags

VNODE_READDIR_EXTENDED, VNODE_READDIR_REQSEEKOFF, VNODE_READDIR_SEEKOFF32: Apple-internal flags.

eofflag

Should be set to 1 if the end of the directory has been reached.

numdirent

Should be set to number of entries written into buffer.

ctx

Context to authenticate for readdir request.

Discussion

VNOP_READDIR() packs a buffer with "struct dirent" directory entry representations as described by the "getdirentries" manual page.

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

vnop_readlink_args

Call down to get file attributes for many files in a directory at once.

struct vnop_readlink_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   struct uio *a_uio;
   vfs_context_t a_context;
};
Fields
vp

Directory in which to enumerate entries' attributes.

alist

Which attributes are wanted for each directory entry.

uio

Destination information for resulting attributes.

maxcount

Maximum count of files to get attributes for.

options

FSOPT_NOFOLLOW: do not follow symbolic links. FSOPT_NOINMEMUPDATE: do not use data which have been updated since an inode was loaded into memory.

newstate

The "newstate" should be set to a value which changes if the contents of a directory change through an addition or deletion but stays the same otherwise.

eofflag

Should be set to 1 if the end of the directory has been reached.

actualcount

Should be set to number of files whose attributes were written into buffer.

ctx

Context to authenticate for readdirattr request.

Discussion

VNOP_READDIRATTR() packs a buffer with file attributes, as if the results of many "getattrlist" calls.

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

vnop_reclaim_args

Notify a filesystem that the last usecount (persistent reference) on a vnode has been dropped.

struct vnop_reclaim_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   vfs_context_t a_context;
};
Fields
vp

The vnode which is now inactive.

ctx

Context to authenticate for inactive message.

Discussion

VNOP_INACTVE() gives a filesystem a chance to aggressively release resources assocated with a vnode, perhaps even to call vnode_recycle(), but no action is prescribed; it is acceptable for VNOP_INACTIVE to be a no-op and to defer all reclamation until VNOP_RECLAIM(). VNOP_INACTVE() will not be called on a vnode if no persistent reference is ever taken; an important example is a stat(), which takes an iocount, reads its data, and drops that iocount.

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

vnop_removenamedstream_args

Create a named stream associated with a file.

struct vnop_removenamedstream_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   vnode_t a_svp;
   const char *a_name;
   int a_flags;
   vfs_context_t a_context;
};
Fields
vp

The vnode for which to get a named stream.

svpp

Destination for pointer to named stream's vnode.

name

The name of the named stream, e.g. "com.apple.ResourceFork".

flags

Currently unused.

ctx

Context to authenticate creating named stream.

Discussion

If this call succeeds, svpp should be returned with an iocount which the caller will drop. VFS provides a facility for simulating named streams when interacting with filesystems which do not support them.

vnop_rename_args

Call down to a filesystem to create a hardlink to a file.

struct vnop_rename_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_fdvp;
   vnode_t a_fvp;
   struct componentname *a_fcnp;
   vnode_t a_tdvp;
   vnode_t a_tvp;
   struct componentname *a_tcnp;
   vfs_context_t a_context;
};
Fields
vp

File to link to.

dvp

Directory in which to create the link.

cnp

Filename information for new link.

ctx

Context to authenticate for link request.

Discussion

See "man 2 link".

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

vnop_revoke_args

Call down to a filesystem to atomically exchange the data of two files.

struct vnop_revoke_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   int a_flags;
   vfs_context_t a_context;
};
Fields
fvp

First vnode.

tvp

Second vnode.

options

Unused.

ctx

Context to authenticate for exchangedata request.

Discussion

VNOP_EXCHANGE() is currently only called by the exchangedata() system call. It will only be applied to files on the same volume.

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

vnop_rmdir_args

Call down to a filesystem to create a directory.

struct vnop_rmdir_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_dvp;
   vnode_t a_vp;
   struct componentname *a_cnp;
   vfs_context_t a_context;
};
Fields
dvp

Directory in which to create new directory.

vpp

Destination for pointer to new directory's vnode.

cnp

Name information for new directory.

vap

Attributes for new directory.

ctx

Context to authenticate for mkdir request.

Discussion

The newly created directory should be returned with an iocount which will be dropped by the caller.

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

vnop_searchfs_args

Write data from a mapped file back to disk.

struct vnop_searchfs_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   void *a_searchparams1;
   void *a_searchparams2;
   struct attrlist *a_searchattrs;
   uint32_t a_maxmatches;
   struct timeval *a_timelimit;
   struct attrlist *a_returnattrs;
   uint32_t *a_nummatches;
   uint32_t a_scriptcode;
   uint32_t a_options;
   struct uio *a_uio;
   struct searchstate *a_searchstate;
   vfs_context_t a_context;
};
Fields
vp

The vnode for which to page out data.

pl

UPL describing pages needed to be paged out. If UPL is NULL, then it means the filesystem has opted into VFC_VFSVNOP_PAGEOUTV2 semantics, which means that it will create and operate on its own UPLs as opposed to relying on the one passed down into the filesystem. This means that the filesystem must be responsible for N cluster_pageout calls for N dirty ranges in the UPL.

pl_offset

Offset in UPL from which to start paging out data. Under the new VFC_VFSVNOP_PAGEOUTV2 semantics, this is the offset in the range specified that must be paged out if the associated page is dirty.

f_offset

Offset in file of data needing to be paged out. Under the new VFC_VFSVNOP_PAGEOUTV2 semantics, this represents the offset in the file where we should start looking for dirty pages.

size

Amount of data to page out (in bytes). Under VFC_VFSVNOP_PAGEOUTV2, this represents the size of the range to be considered. The fileystem is free to extend or shrink the specified range to better fit its blocking model as long as the page at 'pl_offset' is included.

flags

UPL-style flags: UPL_IOSYNC, UPL_NOCOMMIT, UPL_NORDAHEAD, UPL_VNODE_PAGER, UPL_MSYNC. Filesystems should generally leave it to the cluster layer to handle these flags. See the memory_object_types.h header in the kernel framework if interested.

ctx

Context to authenticate for pageout request.

Discussion

VNOP_PAGEOUT() is called when data from a mapped file needs to be flushed to disk, either because of an msync() call or due to memory pressure. Filesystems are for the most part expected to just call cluster_pageout(). However, if they opt into the VFC_VFSVNOP_PAGEOUTV2 flag, then they will be responsible for creating their own UPLs.

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

vnop_setattr_args

Call down to a filesystem to get vnode attributes.

struct vnop_setattr_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   struct vnode_attr *a_vap;
   vfs_context_t a_context;
};
Fields
vp

The vnode whose attributes to get.

vap

Container for which attributes are requested, which attributes are supported by the filesystem, and attribute values.

ctx

Context against which to authenticate request for attributes.

Discussion

Supported attributes ("Yes, I am returning this information") are set with VATTR_SET_SUPPORTED. Which attributes have been requested is checked with VATTR_IS_ACTIVE. Attributes are returned with VATTR_RETURN. It is through VNOP_GETATTR that routines like stat() get their information. A VNOP_GETATTR() calldown may come without any preceding VNOP_OPEN().

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

VNOP_SETLABEL

Associate a MACF label with a file.

struct vnop_getnamedstream_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_vp;
   vnode_t *a_svpp;
   const char *a_name;
   enum nsoperation a_operation; int a_flags; vfs_context_t a_context;
};
Fields
vp

The vnode to label.

label

The desired label.

ctx

Context to authenticate for label change.

See Also

vnop_strategy_args

Call down to a filesystem to get information about the on-disk layout of a file region.

struct vnop_strategy_args {
   struct vnodeop_desc *a_desc;
   struct buf *a_bp;
};
Fields
vp

The vnode for which to get on-disk information.

foffset

Offset (in bytes) at which region starts.

size

Size of region.

bpn

Destination for physical block number at which region begins on disk.

run

Destination for number of bytes which can be found contiguously on-disk before first discontinuity.

poff

Currently unused.

flags

VNODE_READ: request is for a read. VNODE_WRITE: request is for a write.

ctx

Context to authenticate for blockmap request; currently often set to NULL.

Discussion

VNOP_BLOCKMAP() returns the information required to pass a request for a contiguous region down to a device's strategy routine.

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

vnop_symlink_args

Call down to a filesystem to delete a directory.

struct vnop_symlink_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_dvp;
   vnode_t *a_vpp;
   struct componentname *a_cnp;
   struct vnode_attr *a_vap;
   char *a_target;
   vfs_context_t a_context;
};
Fields
dvp

Parent of directory to be removed.

vp

Directory to remove.

cnp

Name information for directory to be deleted.

ctx

Context to authenticate for rmdir request.

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

vnop_whiteout_args

Call down to a filesystem to create a regular file (VREG).

struct vnop_whiteout_args {
   struct vnodeop_desc *a_desc;
   vnode_t a_dvp;
   struct componentname *a_cnp;
   int a_flags;
   vfs_context_t a_context;
};
Fields
dvp

Directory in which to create file.

vpp

Destination for vnode for newly created file.

cnp

Description of filename to create.

vap

File creation properties, as seen in vnode_getattr(). Manipulated with VATTR_ISACTIVE, VATTR_RETURN, VATTR_SET_SUPPORTED, and so forth.

ctx

Context against which to authenticate file creation.

Discussion

If file creation succeeds, "vpp" should be returned with an iocount to be dropped by the caller. A VNOP_CREATE() calldown can come without a preceding VNOP_OPEN().

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

Constants

See the Overview section above for header-level documentation.

Global Variables

extern struct vnodeop_desc vnop_getxattr_desc;
extern struct vnodeop_desc vnop_listxattr_desc;
Constants
vnop_getxattr_desc

Write data from a mapped file back to disk.

VNOP_PAGEOUT() is called when data from a mapped file needs to be flushed to disk, either because of an msync() call or due to memory pressure. Filesystems are for the most part expected to just call cluster_pageout(). However, if they opt into the VFC_VFSVNOP_PAGEOUTV2 flag, then they will be responsible for creating their own UPLs.

The vnode for which to page out data.

UPL describing pages needed to be paged out. If UPL is NULL, then it means the filesystem has opted into VFC_VFSVNOP_PAGEOUTV2 semantics, which means that it will create and operate on its own UPLs as opposed to relying on the one passed down into the filesystem. This means that the filesystem must be responsible for N cluster_pageout calls for N dirty ranges in the UPL.

Offset in UPL from which to start paging out data. Under the new VFC_VFSVNOP_PAGEOUTV2 semantics, this is the offset in the range specified that must be paged out if the associated page is dirty.

Offset in file of data needing to be paged out. Under the new VFC_VFSVNOP_PAGEOUTV2 semantics, this represents the offset in the file where we should start looking for dirty pages.

Amount of data to page out (in bytes). Under VFC_VFSVNOP_PAGEOUTV2, this represents the size of the range to be considered. The fileystem is free to extend or shrink the specified range to better fit its blocking model as long as the page at 'pl_offset' is included.

UPL-style flags: UPL_IOSYNC, UPL_NOCOMMIT, UPL_NORDAHEAD, UPL_VNODE_PAGER, UPL_MSYNC. Filesystems should generally leave it to the cluster layer to handle these flags. See the memory_object_types.h header in the kernel framework if interested.

Context to authenticate for pageout request.

Available in OS X v10.4 and later.

Declared in vnode_if.h.

vnop_listxattr_desc

Remove extended file attributes.

The vnode from which to remove extended attributes.

Which attribute to delete.

XATTR_NOSECURITY: bypass security-checking.

Context to authenticate for attribute delete request.

Available in OS X v10.4 and later.

Declared in vnode_if.h.

nsoperation

Associate a MACF label with a file.

   enum nsoperation {
   NS_OPEN,
   NS_CREATE,
   NS_DELETE
};
Constants
vp

The vnode to label.

label

The desired label.

ctx

Context to authenticate for label change.

See Also

VNOP_SETLABEL

Associate a MACF label with a file.

   enum nsoperation {
   NS_OPEN,
   NS_CREATE,
   NS_DELETE
};
Constants
vp

The vnode to label.

label

The desired label.

ctx

Context to authenticate for label change.

See Also