sys/ubc.h Kernel.framework

Converts a logical block number in the given vnode to an offset in its backing object (file), by calling the file system's VNOP_BLKTOOFF. Returns the offset, or -1 if the vnode has no ubc_info or the underlying VFS translation fails (most commonly a block past the end of the file). Since the error is returned in band, it is indistinguishable from an offset of -1, which is conventionally EOF.

Converts an offset in the given vnode's backing object into a logical block number, by calling the file system's VNOP_OFFTOBLK. Returns the block number, or -1 if the vnode has no ubc_info or the underlying VFS translation fails.

Returns the size of the file associated with the vnode as tracked by the unified buffer cache (ubc_info ui_size). Returns 0 both for a zero-length file and for a vnode with no associated ubc_info; the two cases cannot be distinguished by the caller.

Informs the unified buffer cache of a change in file size; file systems must call this when truncating or extending a file so the VM view stays coherent. Growing the file updates the tracked size and posts NOTE_EXTEND. Shrinking zeroes the resident tail of the new last page beyond the new EOF and invalidates all pages past the new size via memory_object_lock_request. Boolean return, unlike most KPIs: 1 on success, 0 on failure (EINVAL for a negative size, ENOENT for no ubc_info, or an I/O error while flushing); ubc_setsize_ex returns the errno instead.

Returns the credential recorded in the vnode's ubc_info, or NOCRED if the vnode has no ubc_info or no credential has been set. The credential is established by ubc_setcred or ubc_setthreadcred and is used by the NFS client to build requests on the page-in and page-out paths.

If the ubc_info associated with the vnode has no credential yet, records the calling thread's credential in it; otherwise leaves it alone. p and thread must be the current process and thread; the routine simply defers to ubc_setcred(vp, kauth_cred_get()). The return convention is inverted from most of the kernel: 0 if the vnode has no ubc_info, nonzero on success. Typically called for files memory-mapped via mmap, swap backing files, and after a successful write, so the paging path (notably NFS) has a usable credential.

Cleans and/or invalidates a range of the memory object backing the vnode, in the manner of msync(2). flags must contain at least one of: UBC_PUSHDIRTY clean dirty pages in the range to backing store UBC_PUSHALL push both dirty and precious pages UBC_INVALIDATE invalidate pages in the range (may combine with the above) UBC_SYNC with UBC_PUSHDIRTY, wait for the I/O to complete end_off is exclusive; the range is expanded to page boundaries. Returns 0 on success and an errno on failure; EINVAL if the operation failed without an I/O error (e.g. no valid flags). A vnode with no ubc_info, or end_off <= beg_off, succeeds trivially. If resid_off is non-NULL it is set to beg_off, and after an I/O error indicates how far the push got; its value on success is undefined.

Returns 1 if the memory object associated with the vnode currently has any resident pages, 0 otherwise (including when the vnode has no ubc_info or the memory object query fails). Wrapper around memory_object_pages_resident.

Queries or manipulates the state of the single page of the vnode's memory object containing f_offset (a page-aligned offset avoids an internal hash lookup). ops is either UPL_POP_PHYSICAL (return the physical page number through phys_entryp; fails with KERN_INVALID_OBJECT unless the object is physically contiguous), UPL_POP_DUMP (discard the page), or a bitmap of UPL_POP_DIRTY, UPL_POP_PAGEOUT, UPL_POP_PRECIOUS, UPL_POP_ABSENT, and UPL_POP_BUSY, optionally with exactly one of UPL_POP_SET or UPL_POP_CLR to modify rather than query those bits. With neither SET nor CLR, the page's current state is returned through flagsp. Returns KERN_SUCCESS, KERN_INVALID_ARGUMENT if the vnode has no memory object control, or KERN_FAILURE if the page cannot be looked up.

Operates on a range of pages [f_offset_beg, f_offset_end) of the vnode's memory object when no per-page state needs to be returned. ops must be one of: UPL_ROP_ABSENT return the extent of the leading run of absent pages UPL_ROP_PRESENT return the extent of the leading run of resident pages UPL_ROP_DUMP discard the pages found in the range If range is non-NULL, on success it receives the number of bytes covered (only the first matching region is reported for ROP_ABSENT/ROP_PRESENT). Returns KERN_SUCCESS, KERN_INVALID_ARGUMENT if the vnode has no memory object control, or KERN_INVALID_OBJECT for a physically contiguous object, on which this call cannot be used.

Issues advisory (speculative) read I/O for the byte range starting at f_offset for resid bytes of the file, in the largest chunks possible; completed pages are released into the VM page cache. Ranges already resident are skipped. filesize is the current EOF and bounds the I/O. Returns EINVAL if the vnode has no ubc_info or f_offset/resid is negative, otherwise 0 or an I/O error. Equivalent to advisory_read_ext with no callback and CL_PASSIVE.

Form of advisory_read that additionally invokes callback(bp, callback_arg) as each speculative I/O completes, and takes bflag flags applied to the issued I/Os (e.g. CL_PASSIVE to keep the reads from opening throttle windows).

Reads file data into the uio through the unified buffer cache; the standard read engine called by file systems from VNOP_READ. filesize is the current EOF and bounds the transfer. xflags accepts IO_* flags from sys/vnode.h, notably IO_SYNC, IO_NOCACHE (uncached/direct path) and IO_RAOFF (suppress read-ahead); the vnode flags VNOCACHE_DATA and VRAOFF have the same effect. Cached reads copy from resident UBC pages and drive cluster read-ahead. Returns 0 or an errno. Equivalent to cluster_read_ext with no callback.

Form of cluster_read that additionally invokes callback(bp, callback_arg) on completion of each buffer actually issued to the device, letting the file system post-process the I/O (used e.g. for content protection).

Writes file data from the uio through the unified buffer cache; the standard write engine called by file systems from VNOP_WRITE. oldEOF and newEOF are the file's EOF before and after the write (newEOF reflecting any extension); headOff and tailOff bound the regions zero-filled when IO_HEADZEROFILL or IO_TAILZEROFILL is set in xflags, and a NULL uio zero-fills the range without user data. Other xflags include IO_SYNC and IO_NOCACHE; VNOCACHE_DATA on the vnode forces the uncached path. Dirty data is clustered for deferred write-behind unless written synchronously or uncached. Returns 0 or an errno. Equivalent to cluster_write_ext with no callback.

Form of cluster_write that additionally invokes callback(bp, callback_arg) on completion of each buffer issued to the device, letting the file system post-process the I/O.

Writes pages of the given upl to the file; the standard implementation a file system calls from VNOP_PAGEOUT. The range starts at upl_offset in the upl, covering file range [f_offset, f_offset + size); filesize is the current EOF, and I/O beyond it is trimmed and the excess pages aborted. flags: UPL_IOSYNC (synchronous rather than async), UPL_NOCOMMIT (caller keeps responsibility for committing/aborting the upl), UPL_KEEPCACHED, UPL_PAGING_ENCRYPTED. f_offset and size must be page aligned. Returns EINVAL for size <= 0, misalignment, or an offset at or beyond EOF; EROFS on a read-only mount; otherwise the cluster I/O result. Pageouts are subject to I/O throttling. Equivalent to cluster_pageout_ext with no callback.

Form of cluster_pageout that additionally invokes callback(bp, callback_arg) on I/O completion, letting the file system post-process the pageout.

Reads pages of the file into the given upl; the standard implementation a file system calls from VNOP_PAGEIN. The range starts at upl_offset in the upl, covering file range [f_offset, f_offset + size); filesize is the current EOF, and the transfer is trimmed to it, with pages past the rounded size aborted. flags: UPL_IOSYNC (synchronous), UPL_NOCOMMIT (caller commits/aborts the upl), UPL_IOSTREAMING, UPL_PAGING_ENCRYPTED. Returns EINVAL for a negative or non-page-aligned offset, unaligned size or upl_offset, or an offset at or beyond EOF (aborting the upl with UPL_ABORT_ERROR unless UPL_NOCOMMIT); otherwise the cluster I/O result. Panics if upl is NULL. Large pageins on SSD-backed vnodes may be split so the faulting page is read first. Equivalent to cluster_pagein_ext with no callback.

Form of cluster_pagein that additionally invokes callback(bp, callback_arg) on I/O completion, letting the file system post-process the pagein.

Pushes the vnode's pending write-behind clusters (delayed writes accumulated by cluster_write) to the file. flags may include IO_SYNC to wait for the writes to complete and IO_DEFWRITE (with MNT_DEFWRITE mounts) to defer. Returns the number of clusters pushed; 0 if the vnode has no ubc_info or no write-behind state. Equivalent to cluster_push_ext with no callback.

Form of cluster_push that invokes callback(bp, callback_arg) on completion of each buffer issued. Errors are not reported; use cluster_push_err to obtain them.

Same as cluster_push_ext, but additionally stores the first write error encountered through err (set to 0 first if non-NULL). Returns the number of clusters written; a serialized sparse-push in progress is waited for, and IO_SYNC blocks until the pushed I/O completes.

Issues the I/O described by the buffer through the cluster layer: converts bp->b_lblkno to a file offset with ubc_blktooff and starts an asynchronous cluster I/O on the buffer's vnode for b_bcount bytes, honoring B_READ and B_PASSIVE in b_flags. Completion is delivered through the normal buffer biodone path. Equivalent to cluster_bp_ext with no callback.

Form of cluster_bp that additionally invokes callback(bp, callback_arg) when the I/O completes.

Zero-fills size bytes of the upl beginning at upl_offset. If bp is NULL or has no kernel data mapping, the pages are zeroed through their physical addresses using the upl's page list; otherwise the corresponding range of the buffer's mapped data is bzeroed. Used by file systems to clear the invalid portions of pages around a partial-page I/O.

Moves data between the pages of the upl, starting at upl_offset, and the uio (direction given by the uio's uio_rw), addressing the upl pages physically. On return *io_resid holds the bytes remaining untransferred; the uio is advanced and its segment flag restored. Pages newly dirtied by a write are charged to the task's logical writes. Returns 0 or an error from uiomove64. Used on cached I/O paths where the caller already holds a upl.

Copies data between the uio and the file's resident pages in the unified buffer cache (memory_object_control_uiomove), transferring only while pages are resident. *io_resid is reduced by the number of bytes moved; if the vnode has no memory object control the call returns 0 having copied nothing. Nonzero mark_dirty marks the touched pages dirty (write path). Lets a file system satisfy I/O from the cache without issuing device I/O; the caller falls back to cluster_read/cluster_write for the remainder.

Takes the per-vnode read/write lock used to serialize direct (uncached) reads against page invalidation, in the given mode (LCK_RW_TYPE_SHARED or LCK_RW_TYPE_EXCLUSIVE). Locks are kept in a global reference-counted hash keyed by vnode and allocated on first use. Returns the lock token to pass to cluster_unlock_direct_read.

Releases a lock returned by cluster_lock_direct_read, freeing it when the last reference is dropped.

Maps the entire upl into the kernel address space; on success the kernel virtual address of the mapping is returned through dst_addr. Returns KERN_SUCCESS, KERN_INVALID_ARGUMENT if upl is UPL_NULL, or KERN_FAILURE if the upl is already mapped; vm_map_enter failures are passed through. The mapping must be removed with ubc_upl_unmap before the upl is committed or aborted.

Removes the kernel mapping of the upl established by ubc_upl_map. Returns KERN_SUCCESS, KERN_FAILURE if the upl is not currently mapped, or KERN_INVALID_ARGUMENT if upl is UPL_NULL.

Like ubc_upl_map, but maps only the given sub-range of the upl (offset_to_map, size_to_map), and with the protection prot_to_map rather than read/write. The offset and size are rounded to page boundaries internally, and the address returned through dst_addr reflects the requested (unaligned) offset. Unmap with ubc_upl_unmap_range.

Unmaps a range of the upl mapped by ubc_upl_map_range. The offset_to_unmap and size_to_unmap arguments are currently unused: the unmap always proceeds from the start of the upl's mapping for the tracked mapped size; the parameters exist for a possible future partial unmap.

Commits the entire upl to the backing store and unconditionally deallocates the upl, regardless of success or failure. Returns KERN_SUCCESS in practice; KERN_INVALID_ARGUMENT for UPL_NULL, or KERN_FAILURE if internal offset/size accounting is inconsistent (data structure corruption). Do not mix with ubc_upl_commit_range on the same upl, because of the unconditional deallocation.

Commits the range [offset, offset + size) of the upl to the backing store. flags is a bitmap: UPL_COMMIT_FREE_ON_EMPTY deallocate the upl once empty and committed UPL_COMMIT_CLEAR_DIRTY clear each page's dirty bit, preventing a later pageout UPL_COMMIT_SET_DIRTY set each page's dirty bit, causing a later pageout UPL_COMMIT_INACTIVATE clear each page's reference bit UPL_COMMIT_ALLOW_ACCESS unbusy the pages UPL_COMMIT_CLEAR_DIRTY and UPL_COMMIT_SET_DIRTY are mutually exclusive. Since the caller cannot tell when the upl becomes empty, UPL_COMMIT_FREE_ON_EMPTY should generally be used with offset 0 and the full upl size. Returns KERN_SUCCESS, KERN_INVALID_ARGUMENT for UPL_NULL or kernel-only flags, or KERN_FAILURE if offset plus size exceeds the upl.

Aborts the entire upl with the given abort_type flags (see ubc_upl_abort_range) and unconditionally deallocates it. Returns KERN_SUCCESS, KERN_INVALID_ARGUMENT for UPL_NULL, or KERN_FAILURE for inconsistent internal accounting.

Aborts the range [offset, offset + size) of the upl, releasing the pages without writing them. abort_flags is a bitmap: UPL_ABORT_FREE_ON_EMPTY deallocate the upl once empty and aborted UPL_ABORT_RESTART the operation must be restarted UPL_ABORT_UNAVAILABLE the pages are unavailable UPL_ABORT_ERROR an I/O error occurred; mark the pages in error UPL_ABORT_DUMP_PAGES just free the pages UPL_ABORT_NOTIFY_EMPTY is internal, and UPL_ABORT_ALLOW_ACCESS is defined but unreferenced; neither should be passed. Since the caller cannot tell when the upl becomes empty, UPL_ABORT_FREE_ON_EMPTY should generally be used with offset 0 and the full upl size. Returns KERN_SUCCESS, KERN_INVALID_ARGUMENT for UPL_NULL, or KERN_FAILURE if offset plus size exceeds the upl.

Marks count pages of the upl's internal page list, beginning at page index, as needed by the caller, so that later commit/abort processing can distinguish them from pages that were brought in only speculatively (e.g. keeping needed pages while discarding the rest on an aborted pagein). No effect if count <= 0 or the upl was not created with an internal page list (UPL_INTERNAL).

Returns the internal page list (upl_page_info_t array) of the upl, for inspection with the upl_valid_page/upl_dirty_page/upl_phys_page macros; NULL if none. Valid only for upls created with an internal page list (UPL_INTERNAL); provided as a helper for callers without access to the UPL_GET_INTERNAL_PAGE_LIST macro.

Returns the maximum buffer size, in bytes, that ubc_create_upl will accept (MAX_UPL_SIZE_BYTES).

Scans the file page by page from offset 0 to filesize, querying each resident page with ubc_page_op, and reports whether any page is dirty. Returns 0 if the file is clean; EINVAL if one or more dirty pages were found (note the error-code-as-boolean convention).

Maps a Mach kern_return_t to a BSD errno: KERN_SUCCESS to 0; invalid-argument style codes (KERN_INVALID_ARGUMENT, KERN_INVALID_ADDRESS, KERN_INVALID_VALUE, ...) to EINVAL; KERN_NOT_RECEIVER and KERN_NO_ACCESS to EACCES; KERN_NO_SPACE and KERN_RESOURCE_SHORTAGE to ENOMEM; KERN_MEMORY_ERROR and KERN_PROTECTION_FAILURE to EFAULT; KERN_DENIED and KERN_CODESIGN_ERROR to EPERM; KERN_NAME_EXISTS and similar to EEXIST; KERN_ABORTED to EINTR; KERN_TERMINATED and KERN_NOT_FOUND to ENOENT; KERN_NOT_SUPPORTED to ENOTSUP; KERN_OPERATION_TIMED_OUT to ETIMEDOUT; anything unrecognized, including KERN_FAILURE, to EIO.