Mac Developer Library

Developer

vnode_if.h Reference

Options
Deployment Target:

On This Page

vnode_if.h Reference

Included Headers

  • <sys/appleapiopts.h>

  • <sys/cdefs.h>

  • <sys/kernel_types.h>

  • <sys/buf.h>

  • <mach/memory_object_types.h>

Functions

  • Write a buffer to backing store.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <vnode_if.h>;

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <vnode_if.h>;

    Availability

    Available in OS X v10.4 and later.

  • Get extended file attributes.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <vnode_if.h>;

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <vnode_if.h>;

    Availability

    Available in OS X v10.4 and later.

  • Call down to a filesystem to read file data.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <vnode_if.h>;

    Availability

    Available in OS X v10.4 and later.

  • Set extended file attributes.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <vnode_if.h>;

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <vnode_if.h>;

    Availability

    Available in OS X v10.4 and later.

  • Call down to the filesystem to write file data.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <vnode_if.h>;

    Availability

    Available in OS X v10.4 and later.

Data Types

See the Overview section above for header-level documentation.

  • Call down to a filesystem to close a file.

    Declaration

    Objective-C

    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.

  • Query a filesystem for path properties.

    Declaration

    Objective-C

    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.

  • Aquire or release and advisory lock on a vnode.

    Declaration

    Objective-C

    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.

  • List extended attribute keys.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to open a file.

    Declaration

    Objective-C

    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.

  • Write data from a mapped file back to disk.

    Declaration

    Objective-C

    /* @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.

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

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Inform a filesystem that a file is no longer mapped.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Associate a MACF label with a file.

    Declaration

    Objective-C

    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.

  • Write data from a mapped file back to disk.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to delete a file.

    Declaration

    Objective-C

    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.

  • Remove extended file attributes.

    Declaration

    Objective-C

    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.

  • Get a named stream associated with a file.

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to rename a file.

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to create a whiteout.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to create a special file.

    Declaration

    Objective-C

    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.

  • Pre-allocate space for a file.

    Declaration

    Objective-C

    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.

  • Pull file data into memory.

    Declaration

    Objective-C

    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.

  • Release filesystem-internal resources for a vnode.

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to set vnode attributes.

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to create a symbolic link.

    Declaration

    Objective-C

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

  • Call down to a filesystem to enumerate directory entries.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Create a named stream associated with a file.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to create a directory.

    Declaration

    Objective-C

    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.

  • Write data from a mapped file back to disk.

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to get vnode attributes.

    Declaration

    Objective-C

    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.

  • Associate a MACF label with a file.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Call down to a filesystem to delete a directory.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    extern struct vnodeop_desc vnop_getxattr_desc; extern struct vnodeop_desc vnop_listxattr_desc;

    Constants

    • vnop_getxattr_desc

      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.

    • vnop_listxattr_desc

      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.