vnode_if.h

Includes:

Overview

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

Functions

VNOP_BWRITE: Write a buffer to backing store.
VNOP_FSYNC: Call down to a filesystem to synchronize a file with on-disk state.
VNOP_GETXATTR: Get extended file attributes.
VNOP_IOCTL: Call down to a filesystem or device driver to execute various control operations on or request data about a file.
VNOP_READ: Call down to a filesystem to read file data.
VNOP_SETXATTR: Set extended file attributes.
VNOP_STRATEGY: Initiate I/O on a file (both read and write).
VNOP_WRITE: Call down to the filesystem to write file data.

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

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.

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.

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

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. Filesystems will not receive a read request on a file without having first received a VNOP_OPEN().

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.

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.

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. Filesystems will not receive a write request on a file without having first received a VNOP_OPEN().

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

Did this document help you?

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

Last Updated: 2010-07-29