Mac Developer Library

Developer

buf.h Reference

Options
Deployment Target:

On This Page

buf.h Reference

Included Headers

  • <sys/cdefs.h>

  • <sys/kernel_types.h>

  • <sys/ucred.h>

  • <mach/memory_object_types.h>

Functions

  • Allocate an uninitialized buffer.

    Declaration

    Objective-C

    buf_t buf_alloc ( vnode_t );

    Parameters

    vp

    vnode to associate with the buffer: optionally NULL. If vp is a device file, then the buffer's associated device will be set. If vp is NULL, it can be set later with buf_setvnode().

    Return Value

    New buffer.

    Discussion

    A buffer returned by buf_alloc() is marked as busy and as an iobuf; it has no storage set up and must be set up using buf_setdataptr() or buf_setupl()/buf_map().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Gets the attributes for this buf.

    Declaration

    Objective-C

    bufattr_t buf_attr ( buf_t );

    Parameters

    bp

    Buffer whose attributes to get.

    Return Value

    bufattr_t.

    Import Statement

    Availability

    Available in OS X v10.7 and later.

  • Start an asychronous write on a buffer.

    Declaration

    Objective-C

    errno_t buf_bawrite ( buf_t );

    Parameters

    bp

    The buffer on which to initiate I/O.

    throttle

    If "throttle" is nonzero and more than VNODE_ASYNC_THROTTLE writes are in progress on this file, buf_bawrite() will block until the write count drops below VNODE_ASYNC_THROTTLE. If "throttle" is zero and the write count is high, it will fail with EWOULDBLOCK; the caller can decide whether to make a blocking call or pursue other opportunities.

    Return Value

    EWOULDBLOCK if write count is high and "throttle" is zero; otherwise, errors from VNOP_BWRITE.

    Discussion

    Calls VNOP_BWRITE to start the process of propagating an asynchronous write down to the device layer. Callers can wait for writes to complete at their discretion using buf_biowait(). When this function is called, data should already have been written to the buffer's data region.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Mark a buffer for delayed write.

    Declaration

    Objective-C

    errno_t buf_bdwrite ( buf_t );

    Parameters

    bp

    The buffer to mark for delayed write.

    return_error

    If the number of pending delayed writes systemwide is larger than an internal limit, return EAGAIN rather than doing an asynchronous write.

    Return Value

    EAGAIN for return_error != 0 case, 0 for succeess, errors from buf_bawrite.

    Discussion

    Marks a buffer as waiting for delayed write and the current I/O as complete; data will be written to backing store before the buffer is reused, but it will not be queued for I/O immediately. Note that for buffers allocated with buf_alloc(), there are no such guarantees; you must take care of your own flushing to disk. If the number of delayed writes pending on the system is greater than an internal limit and the caller has not requested otherwise [see return_error] , buf_bdwrite() will unilaterally launch an asynchronous I/O with buf_bawrite() to keep the pile of delayed writes from getting too large.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Mark an I/O as completed.

    Declaration

    Objective-C

    void buf_biodone ( buf_t );

    Parameters

    bp

    The buffer to mark as done with I/O.

    Return Value

    void.

    Discussion

    buf_biodone() should be called by whosoever decides that an I/O on a buffer is complete; for example, IOStorageFamily. It clears the dirty flag on a buffer and signals on the vnode that a write has completed with vnode_writedone(). If a callout or filter has been set on the buffer, that function is called. In the case of a callout, that function is expected to take care of cleaning up and freeing the buffer. Otherwise, if the buffer is marked B_ASYNC (e.g. it was passed to buf_bawrite()), then buf_biodone() considers itself justified in calling buf_brelse() to return it to free lists--no one is waiting for it. Finally, waiters on the bp (e.g. in buf_biowait()) are woken up.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Wait for I/O on a buffer to complete.

    Declaration

    Objective-C

    errno_t buf_biowait ( buf_t );

    Parameters

    bp

    The buffer to wait on.

    Return Value

    0 for a successful wait; nonzero the buffer has been marked as EINTR or had an error set on it.

    Discussion

    Waits for I/O on a buffer to finish, as marked by a buf_biodone() call.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get physical block number associated with a buffer, in the sense of VNOP_BLOCKMAP.

    Declaration

    Objective-C

    daddr64_t buf_blkno ( buf_t );

    Parameters

    bp

    Buffer whose physical block number to get.

    Return Value

    Block number.

    Discussion

    When a buffer's physical block number is the same is its logical block number, then the physical block number is considered uninitialized. A physical block number of -1 indicates that there is no valid physical mapping (e.g. the logical block is invalid or corresponds to a sparse region in a file). Physical block number is normally set by the cluster layer or by buf_getblk().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Synchronously read a block of a file.

    Declaration

    Objective-C

    errno_t buf_bread ( vnode_t, daddr64_t, int, kauth_cred_t, buf_t * );

    Parameters

    vp

    The file from which to read.

    blkno

    The logical (filesystem) block number to read.

    size

    Size of block; do not use for sizes > 4K.

    cred

    Credential to store and use for reading from disk if data are not already in core.

    bpp

    Destination pointer for buffer.

    Return Value

    0 for success, or an error from buf_biowait().

    Discussion

    buf_bread() is the traditional way to read a single logical block of a file through the buffer cache. It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data into memory, and waits for I/O to complete. It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster routines for large reads. Indeed, the cluster layer is a more efficient choice for reading DATA unless you need some finely-tuned semantics that it cannot provide.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Read a block from a file with read-ahead.

    Declaration

    Objective-C

    errno_t buf_breadn ( vnode_t, daddr64_t, int, daddr64_t *, int *, int, kauth_cred_t, buf_t * );

    Parameters

    vp

    The file from which to read.

    blkno

    The logical (filesystem) block number to read synchronously.

    size

    Size of block; do not use for sizes > 4K.

    rablks

    Array of logical block numbers for asynchronous read-aheads.

    rasizes

    Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."

    nrablks

    Number of entries in read-ahead arrays.

    cred

    Credential to store and use for reading from disk if data are not already in core.

    bpp

    Destination pointer for buffer.

    Return Value

    0 for success, or an error from buf_biowait().

    Discussion

    buf_breadn() reads one block synchronously in the style of buf_bread() and fires off a specified set of asynchronous reads to improve the likelihood of future cache hits. It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster routines for large reads. Indeed, the cluster layer is a more efficient choice for reading DATA unless you need some finely-tuned semantics that it cannot provide.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Release any claim to a buffer, sending it back to free lists.

    Declaration

    Objective-C

    void buf_brelse ( buf_t );

    Parameters

    bp

    The buffer to release. @retrn void.

    Discussion

    buf_brelse() cleans up buffer state and releases a buffer to the free lists. If the buffer is not marked invalid and its pages are dirty (e.g. a delayed write was made), its data will be commited to backing store. If it is marked invalid, its data will be discarded completely. A valid, cacheable buffer will be put on a list and kept in the buffer hash so it can be found again; otherwise, it will be dissociated from its vnode and treated as empty. Which list a valid buffer is placed on depends on the use of buf_markaged(), whether it is metadata, and the B_LOCKED flag. A B_LOCKED buffer will not be available for reuse by other files, though its data may be paged out. Note that buf_brelse() is intended for use with traditionally allocated buffers.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Write a buffer's data to backing store.

    Declaration

    Objective-C

    errno_t buf_bwrite ( buf_t );

    Parameters

    bp

    The buffer to write to disk.

    Return Value

    0 for success; errors from buf_biowait().

    Discussion

    Once the data in a buffer has been modified, buf_bwrite() starts sending it to disk by calling VNOP_STRATEGY. Unless B_ASYNC has been set on the buffer (by buf_setflags() or otherwise), data will have been written to disk when buf_bwrite() returns. See Bach (p 56).

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the function set to be called when I/O on a buffer completes.

    Declaration

    Objective-C

    void * buf_callback ( buf_t );

    Parameters

    bp

    Buffer whose callback to get.

    Return Value

    0 for success, or errors from filesystem or device layers.

    Discussion

    A function returned by buf_callback was originally set with buf_setcallback().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Zero out the storage associated with a buffer.

    Declaration

    Objective-C

    void buf_clear ( buf_t );

    Parameters

    bp

    The buffer to zero out.

    Return Value

    void.

    Discussion

    Calls buf_map() to get the buffer's data address; for a B_CLUSTER buffer (one which has had buf_setupl() called on it), it tries to map the buffer's UPL into memory; should only be called once during the life cycle of an iobuf (one allocated with buf_alloc()).

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Clear flags on a buffer. @discussion: buffer_redundancy_flags &= ~flags

    Declaration

    Objective-C

    void buf_clear_redundancy_flags ( buf_t, uint32_t );

    Parameters

    bp

    Buffer whose flags to clear.

    flags

    Flags to remove from buffer's mask

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.7 and later.

  • Clear flags on a buffer. @discussion: buffer_flags &= ~flags

    Declaration

    Objective-C

    void buf_clearflags ( buf_t, int32_t );

    Parameters

    bp

    Buffer whose flags to clear.

    flags

    Flags to remove from buffer's mask. B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Clone a buffer with a restricted range and an optional callback.

    Declaration

    Objective-C

    buf_t buf_clone ( buf_t, int, int, void (*)(buf_t, void *), void * );

    Parameters

    bp

    Buffer to clone.

    io_offset

    Offset, relative to start of data in original buffer, at which new buffer's data will begin.

    io_size

    Size of buffer region in new buffer, in the sense of buf_count().

    iodone

    Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback().

    arg

    Argument to pass to iodone() callback.

    Return Value

    NULL if io_offset/io_size combination is invalid for the buffer to be cloned; otherwise, the new buffer.

    Discussion

    Generates a buffer which is identical to its "bp" argument except that it spans a subset of the data of the original. The buffer to be cloned should have been allocated with buf_alloc(). Checks its arguments to make sure that the data subset is coherent. Optionally, adds a callback function and argument to it to be called when I/O completes (as with buf_setcallback(), but B_ASYNC is not set). If the original buffer had a upl set through buf_setupl(), this upl is copied to the new buffer; otherwise, the original's data pointer is used raw. The buffer must be released with buf_free().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get count of valid bytes in a buffer. This may be less than the space allocated to the buffer.

    Declaration

    Objective-C

    uint32_t buf_count ( buf_t );

    Parameters

    bp

    Buffer whose byte count to get.

    Return Value

    Byte count.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Create a shadow buffer with optional private storage and an optional callback.

    Declaration

    Objective-C

    buf_t buf_create_shadow ( buf_t bp, boolean_t force_copy, uintptr_t external_storage, void (*iodone)(buf_t, void *), void *arg );

    Parameters

    bp

    Buffer to shadow.

    force_copy

    If TRUE, do not link the shadaow to 'bp' and if 'external_storage' == NULL, force a copy of the data associated with 'bp'.

    external_storage

    If non-NULL, associate it with the new buffer as its storage instead of the storage currently associated with 'bp'.

    iodone

    Callback to be called from buf_biodone() when I/O completes, in the sense of buf_setcallback().

    arg

    Argument to pass to iodone() callback.

    Return Value

    NULL if the buffer to be shadowed is not B_META or a primary buffer (i.e. not a shadow buffer); otherwise, the new buffer.

    Import Statement

    Availability

    Available in OS X v10.7 and later.

  • Get the address at which a buffer's data is stored; for iobufs, this must be set with buf_setdataptr(). See buf_map().

    Declaration

    Objective-C

    uintptr_t buf_dataptr ( buf_t );

    Parameters

    bp

    Buffer whose data pointer to retrieve.

    Return Value

    Data pointer; NULL if unset.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the device ID associated with a buffer.

    Declaration

    Objective-C

    dev_t buf_device ( buf_t );

    Parameters

    bp

    Buffer whose device ID to retrieve.

    Return Value

    Device id.

    Discussion

    In traditional buffer use, this value is NODEV until buf_strategy() is called unless buf_getblk() was passed a device vnode. It is set on an iobuf if buf_alloc() is passed a device vnode or if buf_setdevice() is called.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the ending offset of the dirty region associated with a buffer.

    Declaration

    Objective-C

    uint32_t buf_dirtyend ( buf_t );

    Parameters

    bp

    Buffer whose dirty end to get.

    Return Value

    0 if buffer is found clean; size of buffer if found dirty. Can be set to any value by callers of buf_setdirtyend().

    Discussion

    If the buffer's data was found incore and dirty, the dirty end is the size of the block; otherwise, unless someone outside of xnu explicitly changes it by calling buf_setdirtyend(), it will be zero.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the starting offset of the dirty region associated with a buffer.

    Declaration

    Objective-C

    uint32_t buf_dirtyoff ( buf_t );

    Parameters

    bp

    Buffer whose dirty offset to get.

    Return Value

    Dirty offset (0 if not explicitly changed).

    Discussion

    The dirty offset is zero unless someone explicitly calls buf_setdirtyoff() (which the kernel does not).

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get driver-specific data from a buffer.

    Declaration

    Objective-C

    void * buf_drvdata ( buf_t );

    Parameters

    bp

    Buffer whose driver data to get.

    Return Value

    Opaque driver data.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the error value associated with a buffer.

    Declaration

    Objective-C

    errno_t buf_error ( buf_t );

    Parameters

    bp

    Buffer whose error value to retrieve.

    Return Value

    Error value, directly.

    Discussion

    Errors are set with buf_seterror().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get flags set on a buffer.

    Declaration

    Objective-C

    int32_t buf_flags ( buf_t );

    Parameters

    bp

    Buffer whose flags to grab.

    Return Value

    flags.

    Discussion

    Valid flags are B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Write dirty file blocks to disk.

    Declaration

    Objective-C

    void buf_flushdirtyblks ( vnode_t, int, int, const char * );

    Parameters

    vp

    The vnode whose blocks to flush.

    wait

    Wait for writes to complete before returning.

    flags

    Can pass zero, meaning "flush all dirty buffers." BUF_SKIP_NONLOCKED: Skip buffers which are not busy when we encounter them. BUF_SKIP_LOCKED: Skip buffers which are busy when we encounter them.

    msg

    String to pass to msleep().

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Free a buffer that was allocated with buf_alloc().

    Declaration

    Objective-C

    void buf_free ( buf_t );

    Parameters

    bp

    The buffer to free.

    Return Value

    void.

    Discussion

    The storage (UPL, data pointer) associated with an iobuf must be freed manually.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Check if a buffer's data was found in core.

    Declaration

    Objective-C

    int buf_fromcache ( buf_t );

    Parameters

    bp

    Buffer to test.

    Return Value

    Nonzero if we got this buffer's data without doing I/O, 0 if not.

    Discussion

    Will return truth after a buf_getblk that finds a valid buffer in the cache or the relevant data in core (but not in a buffer).

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get filesystem-specific data from a buffer.

    Declaration

    Objective-C

    void * buf_fsprivate ( buf_t );

    Parameters

    bp

    Buffer whose filesystem data to get.

    Return Value

    Opaque filesystem data.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Check if a buffer is marked for write through disk caches.

    Declaration

    Objective-C

    int buf_fua ( buf_t );

    Parameters

    bp

    Buffer to test.

    Return Value

    Nonzero if buffer is marked for write-through, 0 if not.

    Import Statement

    Availability

    Available in OS X v10.5 and later.

  • Traditional buffer cache routine to get a buffer corresponding to a logical block in a file.

    Declaration

    Objective-C

    buf_t buf_getblk ( vnode_t, daddr64_t, int, int, int, int );

    Parameters

    vp

    File for which to get block.

    blkno

    Logical block number.

    size

    Size of block.

    slpflag

    Flag to pass to msleep() while waiting for buffer to become unbusy.

    slptimeo

    Time, in milliseconds, to wait for buffer to become unbusy. 0 means to wait indefinitely.

    operation

    BLK_READ: want a read buffer. BLK_WRITE: want a write buffer. BLK_META: want a metadata buffer. BLK_ONLYVALID: only return buffers which are found in core (do not allocate anew), and do not change buffer size. The last remark means that if a given logical block is found in core with a different size than what is requested, the buffer size will not be modified.

    Return Value

    Buffer found in core or newly allocated, either containing valid data or ready for I/O.

    Discussion

    buf_getblk() gets a buffer, not necessarily containing valid data, representing a block in a file. A metadata buffer will be returned with its own zone-allocated storage, managed by the traditional buffer-cache layer, whereas data buffers will be returned hooked into backing by the UBC (which in fact controls the caching of data). buf_getblk() first looks for the buffer header in cache; if the buffer is in-core but busy, buf_getblk() will wait for it to become unbusy, depending on the slpflag and slptimeo parameters. If the buffer is found unbusy and is a metadata buffer, it must already contain valid data and will be returned directly; data buffers will have a UPL configured to prepare for interaction with the underlying UBC. If the buffer is found in core, it will be marked as such and buf_fromcache() will return truth. A buffer is allocated and initialized (but not filled with data) if none is found in core. buf_bread(), buf_breadn(), buf_meta_bread(), and buf_meta_breadn() all return buffers obtained with buf_getblk().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get a metadata buffer which is marked invalid and not associated with any vnode.

    Declaration

    Objective-C

    buf_t buf_geteblk ( int );

    Parameters

    size

    Size of buffer.

    Return Value

    Always returns a new buffer.

    Discussion

    A buffer is returned with zone-allocated storage of the specified size, marked B_META and invalid. It has no vnode and is not visible in the buffer hash.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Invalidate a filesystem logical block in a file.

    Declaration

    Objective-C

    errno_t buf_invalblkno ( vnode_t, daddr64_t, int );

    Parameters

    bp

    Buffer whose block to invalidate.

    lblkno

    Logical block number.

    flags

    BUF_WAIT: wait for busy buffers to become unbusy and invalidate them then. Otherwise, just return EBUSY for busy blocks.

    Return Value

    0 for success, EINVAL if vp is not a device file.

    Discussion

    buf_invalblkno() tries to make the data for a given block in a file invalid; if the buffer for that block is found in core and is not busy, we mark it invalid and call buf_brelse() (see "flags" param for what happens if the buffer is busy). buf_brelse(), noticing that it is invalid, will will return the buffer to the empty-buffer list and tell the VM subsystem to abandon the relevant pages. Data will not be written to backing store--it will be cast aside. Note that this function will only work if the block in question has been obtained with a buf_getblk(). If data has been read into core without using traditional buffer cache routines, buf_invalblkno() will not be able to invalidate it--this includes the use of iobufs.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Invalidate all the blocks associated with a vnode.

    Declaration

    Objective-C

    int buf_invalidateblks ( vnode_t, int, int, int );

    Parameters

    bp

    The buffer whose data to invalidate.

    flags

    BUF_WRITE_DATA: write dirty data to disk with VNOP_BWRITE() before kicking buffer cache entries out. BUF_SKIP_META: do not invalidate metadata blocks.

    slpflag

    Flags to pass to "msleep" while waiting to acquire busy buffers.

    slptimeo

    Timeout in "hz" (1/100 second) to wait for a buffer to become unbusy before waking from sleep and re-starting the scan.

    Return Value

    0 for success, error values from msleep().

    Discussion

    This function does for all blocks associated with a vnode what buf_invalblkno does for one block. Again, it will only be able to invalidate data which were populated with traditional buffer cache routines, i.e. by buf_getblk() and callers thereof. Unlike buf_invalblkno(), it can be made to write dirty data to disk rather than casting it aside.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Perform some operation on all buffers associated with a vnode.

    Declaration

    Objective-C

    void buf_iterate ( vnode_t, int (*)(buf_t, void *), int, void * );

    Parameters

    vp

    The vnode whose buffers to scan.

    callout

    Function to call on each buffer. Should return one of: BUF_RETURNED: buf_iterate() should call buf_brelse() on the buffer. BUF_RETURNED_DONE: buf_iterate() should call buf_brelse() on the buffer and then stop iterating. BUF_CLAIMED: buf_iterate() should continue iterating (and not call buf_brelse()). BUF_CLAIMED_DONE: buf_iterate() should stop iterating (and not call buf_brelse()).

    flag

    BUF_SKIP_NONLOCKED: Skip buffers which are not busy when we encounter them. BUF_SKIP_LOCKED: Skip buffers which are busy when we encounter them. BUF_SCAN_CLEAN: Call out on clean buffers. BUF_SCAN_DIRTY: Call out on dirty buffers. BUF_NOTIFY_BUSY: If a buffer cannot be acquired, pass a NULL buffer to callout; otherwise, that buffer will be silently skipped.

    arg

    Argument to pass to callout in addition to buffer.

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get logical block number associated with a buffer.

    Declaration

    Objective-C

    daddr64_t buf_lblkno ( buf_t );

    Parameters

    bp

    Buffer whose logical block number to get.

    Return Value

    Block number.

    Discussion

    Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(), for example by buf_bread().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get virtual mappings for buffer data.

    Declaration

    Objective-C

    errno_t buf_map ( buf_t, caddr_t * );

    Parameters

    bp

    Buffer whose mapping to find or create.

    io_addr

    Destination for mapping address.

    Return Value

    0 for success, ENOMEM if unable to map the buffer.

    Discussion

    For buffers created through buf_getblk() (i.e. traditional buffer cache usage), buf_map() just returns the address at which data was mapped by but_getblk(). For a B_CLUSTER buffer, i.e. an iobuf whose upl state is managed manually, there are two possibilities. If the buffer was created with an underlying "real" buffer through cluster_bp(), the mapping of the "real" buffer is returned. Otherwise, the buffer was created with buf_alloc() and buf_setupl() was subsequently called; buf_map() will call ubc_upl_map() to get a mapping for the buffer's upl and return the start of that mapping plus the buffer's upl offset (set in buf_setupl()). In the last case, buf_unmap() must later be called to tear down the mapping. NOTE: buf_map() does not set the buffer data pointer; this must be done with buf_setdataptr().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Mark a buffer as "aged," i.e. as a good candidate to be discarded and reused after buf_brelse().

    Declaration

    Objective-C

    void buf_markaged ( buf_t );

    Parameters

    bp

    Buffer to mark.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Mark a buffer as a delayed write: mark it dirty without actually scheduling I/O.

    Declaration

    Objective-C

    void buf_markdelayed ( buf_t );

    Parameters

    bp

    Buffer to mark.

    Discussion

    Data will be flushed to disk at some later time, not with brelse(). A sync()/fsync() or pressure necessitating reuse of the buffer will cause it to be written back to disk.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Mark a buffer as having been interrupted during I/O.

    Declaration

    Objective-C

    void buf_markeintr ( buf_t );

    Parameters

    bp

    Buffer to mark.

    Discussion

    Waiters for I/O to complete (buf_biowait()) will return with EINTR when woken up. buf_markeintr does not itself do a wakeup.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Mark a buffer for write through disk cache, if disk supports it.

    Declaration

    Objective-C

    void buf_markfua ( buf_t );

    Parameters

    bp

    Buffer to mark.

    Import Statement

    Availability

    Available in OS X v10.5 and later.

  • Mark a buffer as not having valid data and being ready for immediate reuse after buf_brelse().

    Declaration

    Objective-C

    void buf_markinvalid ( buf_t );

    Parameters

    bp

    Buffer to mark.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Mark a buffer as being likely to contain static data.

    Declaration

    Objective-C

    void buf_markstatic ( buf_t );

    Parameters

    bp

    Buffer to mark.

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.8 and later.

  • Synchronously read a metadata block of a file.

    Declaration

    Objective-C

    errno_t buf_meta_bread ( vnode_t, daddr64_t, int, kauth_cred_t, buf_t * );

    Parameters

    vp

    The file from which to read.

    blkno

    The logical (filesystem) block number to read.

    size

    Size of block; do not use for sizes > 4K.

    cred

    Credential to store and use for reading from disk if data are not already in core.

    bpp

    Destination pointer for buffer.

    Return Value

    0 for success, or an error from buf_biowait().

    Discussion

    buf_meta_bread() is the traditional way to read a single logical block of a file through the buffer cache. It tries to find the buffer and corresponding page(s) in core, calls VNOP_STRATEGY if necessary to bring the data into memory, and waits for I/O to complete. It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster routines for large reads. Reading meta-data through the traditional buffer cache, unlike reading data, is efficient and encouraged, especially if the blocks being read are significantly smaller than page size.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Read a metadata block from a file with read-ahead.

    Declaration

    Objective-C

    errno_t buf_meta_breadn ( vnode_t, daddr64_t, int, daddr64_t *, int *, int, kauth_cred_t, buf_t * );

    Parameters

    vp

    The file from which to read.

    blkno

    The logical (filesystem) block number to read synchronously.

    size

    Size of block; do not use for sizes > 4K.

    rablks

    Array of logical block numbers for asynchronous read-aheads.

    rasizes

    Array of block sizes for asynchronous read-aheads, each index corresponding to same index in "rablks."

    nrablks

    Number of entries in read-ahead arrays.

    cred

    Credential to store and use for reading from disk if data are not already in core.

    bpp

    Destination pointer for buffer.

    Return Value

    0 for success, or an error from buf_biowait().

    Discussion

    buf_meta_breadn() reads one block synchronously in the style of buf_meta_bread() and fires off a specified set of asynchronous reads to improve the likelihood of future cache hits. It should not be used to read blocks of greater than 4K (one VM page) in size; use cluster routines for large reads.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the process associated with this buffer.

    Declaration

    Objective-C

    proc_t buf_proc ( buf_t );

    Parameters

    bp

    Buffer whose associated process to find.

    Return Value

    Associated process, possibly NULL.

    Discussion

    buf_proc() will generally return NULL; a process is currently only associated with a buffer in the event of a physio() call.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the credential associated with a buffer for reading.

    Declaration

    Objective-C

    kauth_cred_t buf_rcred ( buf_t );

    Parameters

    bp

    Buffer whose credential to grab.

    Return Value

    Credential if it exists, else NULL.

    Discussion

    No reference is taken; if the credential is to be held on to persistently, an additional reference must be taken with kauth_cred_ref.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get redundancy flags set on a buffer.

    Declaration

    Objective-C

    uint32_t buf_redundancy_flags ( buf_t );

    Parameters

    bp

    Buffer whose redundancy flags to grab.

    Return Value

    flags.

    Import Statement

    Availability

    Available in OS X v10.7 and later.

  • Reset I/O flag state on a buffer.

    Declaration

    Objective-C

    void buf_reset ( buf_t, int32_t );

    Parameters

    bp

    Buffer whose flags to grab.

    flags

    Flags to set on buffer: B_READ, B_WRITE, B_ASYNC, B_NOCACHE.

    Return Value

    void.

    Discussion

    Clears current flags on a buffer (internal and external) and allows some new flags to be set. Used perhaps to prepare an iobuf for reuse.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get a count of bytes which were not consumed by an I/O on a buffer.

    Declaration

    Objective-C

    uint32_t buf_resid ( buf_t );

    Parameters

    bp

    Buffer whose outstanding count to get.

    Return Value

    Count of unwritten/unread bytes.

    Discussion

    Set when an I/O operations completes.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set redundancy flags on a buffer. @discussion: buffer_redundancy_flags |= flags

    Declaration

    Objective-C

    void buf_set_redundancy_flags ( buf_t, uint32_t );

    Parameters

    bp

    Buffer whose flags to set.

    flags

    Flags to add to buffer's redundancy flags

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.7 and later.

  • Set physical block number associated with a buffer.

    Declaration

    Objective-C

    void buf_setblkno ( buf_t, daddr64_t );

    Parameters

    bp

    Buffer whose physical block number to set.

    blkno

    Block number to set.

    Return Value

    void.

    Discussion

    Physical block number is generally set by the cluster layer or by buf_getblk().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set a function to be called once when I/O on a buffer completes.

    Declaration

    Objective-C

    errno_t buf_setcallback ( buf_t, void (*)(buf_t, void *), void * );

    Parameters

    bp

    Buffer whose callback to set.

    callback

    function to use as callback.

    transaction

    Additional argument to callback function.

    Return Value

    0; always succeeds.

    Discussion

    A one-shot callout set with buf_setcallback() will be called from buf_biodone() when I/O completes. It will be passed the "transaction" argument as well as the buffer. buf_setcallback() also marks the buffer as B_ASYNC.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set count of valid bytes in a buffer. This may be less than the space allocated to the buffer.

    Declaration

    Objective-C

    void buf_setcount ( buf_t, uint32_t );

    Parameters

    bp

    Buffer whose byte count to set.

    bcount

    Count to set.

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set the address at which a buffer's data will be stored.

    Declaration

    Objective-C

    void buf_setdataptr ( buf_t, uintptr_t );

    Parameters

    bp

    Buffer whose data pointer to set.

    data

    Pointer to data region.

    Return Value

    void.

    Discussion

    In traditional buffer use, the data pointer will be set automatically. This routine is useful with iobufs (allocated with buf_alloc()).

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set the device associated with a buffer.

    Declaration

    Objective-C

    errno_t buf_setdevice ( buf_t, vnode_t );

    Parameters

    bp

    Buffer whose device ID to set.

    vp

    Device to set on the buffer.

    Return Value

    0 for success, EINVAL if vp is not a device file.

    Discussion

    A buffer's device is set in buf_strategy() (or in buf_getblk() if the file is a device). It is also set on an iobuf if buf_alloc() is passed a device vnode.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set the ending offset of the dirty region associated with a buffer.

    Declaration

    Objective-C

    void buf_setdirtyend ( buf_t, uint32_t );

    Parameters

    bp

    Buffer whose dirty end to set.

    Return Value

    void.

    Discussion

    If the buffer's data was found incore and dirty, the dirty end is the size of the block; otherwise, unless someone outside of xnu explicitly changes it by calling buf_setdirtyend(), it will be zero.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set the starting offset of the dirty region associated with a buffer.

    Declaration

    Objective-C

    void buf_setdirtyoff ( buf_t, uint32_t );

    Parameters

    bp

    Buffer whose dirty end to set.

    Return Value

    void.

    Discussion

    This value is zero unless someone set it explicitly.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set driver-specific data on a buffer.

    Declaration

    Objective-C

    void buf_setdrvdata ( buf_t, void * );

    Parameters

    bp

    Buffer whose driver-data to set.

    drvdata

    Opaque driver data.

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set an error value on a buffer.

    Declaration

    Objective-C

    void buf_seterror ( buf_t, errno_t );

    Parameters

    bp

    Buffer whose error value to set.

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set flags on a buffer. @discussion: buffer_flags |= flags

    Declaration

    Objective-C

    void buf_setflags ( buf_t, int32_t );

    Parameters

    bp

    Buffer whose flags to set.

    flags

    Flags to add to buffer's mask. B_LOCKED/B_NOCACHE/B_ASYNC/B_READ/B_WRITE/B_PAGEIO/B_FUA

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set filesystem-specific data on a buffer.

    Declaration

    Objective-C

    void buf_setfsprivate ( buf_t, void * );

    Parameters

    bp

    Buffer whose filesystem data to set.

    fsprivate

    Opaque filesystem data.

    Return Value

    void.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set logical block number associated with a buffer.

    Declaration

    Objective-C

    void buf_setlblkno ( buf_t, daddr64_t );

    Parameters

    bp

    Buffer whose logical block number to set.

    lblkno

    Block number to set.

    Return Value

    void.

    Discussion

    Logical block number is set on traditionally-used buffers by an argument passed to buf_getblk(), for example by buf_bread().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set a count of bytes outstanding for I/O in a buffer.

    Declaration

    Objective-C

    void buf_setresid ( buf_t, uint32_t );

    Parameters

    bp

    Buffer whose outstanding count to set.

    Return Value

    Count of unwritten/unread bytes.

    Discussion

    Set when an I/O operations completes. Examples: called by IOStorageFamily when I/O completes, often called on an "original" buffer when using a manipulated buffer to perform I/O on behalf of the first.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set size of data region allocated to a buffer.

    Declaration

    Objective-C

    void buf_setsize ( buf_t, uint32_t );

    Parameters

    bp

    Buffer whose size to set.

    Return Value

    void.

    Discussion

    May be larger than amount of valid data in buffer. Should be used by code which is manually providing storage for an iobuf, one allocated with buf_alloc().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set the UPL (Universal Page List), and offset therein, on a buffer.

    Declaration

    Objective-C

    errno_t buf_setupl ( buf_t, upl_t, uint32_t );

    Parameters

    bp

    Buffer whose upl to set.

    upl

    UPL to set in the buffer. @parma offset Offset within upl at which relevant data begin.

    Return Value

    0 for success, EINVAL if the buffer was not allocated with buf_alloc().

    Discussion

    buf_setupl() should only be called on buffers allocated with buf_alloc(). A subsequent call to buf_map() will map the UPL and give back the address at which data begins. After buf_setupl() is called, a buffer is marked B_CLUSTER; when this is the case, buf_strategy() assumes that a buffer is correctly configured to be passed to the device layer without modification. Passing a NULL upl will clear the upl and the B_CLUSTER flag on the buffer.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Set the vnode associated with a buffer.

    Declaration

    Objective-C

    void buf_setvnode ( buf_t, vnode_t );

    Parameters

    bp

    Buffer whose vnode to set.

    vp

    The vnode to attach to the buffer.

    Return Value

    void.

    Discussion

    This call need not be used on traditional buffers; it is for use with iobufs.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • returns true if 'bp' is a shadow of another buffer.

    Declaration

    Objective-C

    int buf_shadow ( buf_t bp );

    Parameters

    bp

    Buffer to query.

    Return Value

    1 if 'bp' is a shadow, 0 otherwise.

    Import Statement

    Availability

    Available in OS X v10.7 and later.

  • Get size of data region allocated to a buffer.

    Declaration

    Objective-C

    uint32_t buf_size ( buf_t );

    Parameters

    bp

    Buffer whose size to get.

    Return Value

    Size.

    Discussion

    May be larger than amount of valid data in buffer.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Check if a buffer contains static data.

    Declaration

    Objective-C

    int buf_static ( buf_t );

    Parameters

    bp

    Buffer to test.

    Return Value

    Nonzero if buffer has static data, 0 otherwise.

    Import Statement

    Availability

    Available in OS X v10.8 and later.

  • Pass an I/O request for a buffer down to the device layer.

    Declaration

    Objective-C

    errno_t buf_strategy ( vnode_t, void * );

    Parameters

    devvp

    Device on which to perform I/O

    ap

    vnop_strategy_args structure (most importantly, a buffer).

    Return Value

    0 for success, or errors from filesystem or device layers.

    Discussion

    This is one of the most important routines in the buffer cache layer. For buffers obtained through buf_getblk, it handles finding physical block numbers for the I/O (with VNOP_BLKTOOFF and VNOP_BLOCKMAP), packaging the I/O into page-sized chunks, and initiating I/O on the disk by calling the device's strategy routine. If a buffer's UPL has been set manually with buf_setupl(), it assumes that the request is already correctly configured with a block number and a size divisible by page size and will just call directly to the device.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Release mappings for buffer data.

    Declaration

    Objective-C

    errno_t buf_unmap ( buf_t );

    Parameters

    bp

    Buffer whose mapping to find or create.

    io_addr

    Destination for mapping address.

    Return Value

    0 for success, EINVAL if unable to unmap buffer.

    Discussion

    For buffers created through buf_getblk() (i.e. traditional buffer cache usage), buf_unmap() does nothing; buf_brelse() will take care of unmapping. For a B_CLUSTER buffer, i.e. an iobuf whose upl state is managed manually, there are two possibilities. If the buffer was created with an underlying "real" buffer through cluster_bp(), buf_unmap() does nothing; buf_brelse() on the underlying buffer will tear down the mapping. Otherwise, the buffer was created with buf_alloc() and buf_setupl() was subsequently called; buf_map() created the mapping. In this case, buf_unmap() will unmap the buffer.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the upl (Universal Page List) associated with a buffer.

    Declaration

    Objective-C

    void * buf_upl ( buf_t );

    Parameters

    bp

    Buffer whose upl to grab.

    Return Value

    Buffer's upl if it has one, else NULL.

    Discussion

    Buffers allocated with buf_alloc() are not returned with a upl, and traditional buffers only have a upl while an I/O is in progress.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the offset into a UPL at which this buffer begins.

    Declaration

    Objective-C

    uint32_t buf_uploffset ( buf_t );

    Parameters

    bp

    Buffer whose uploffset to grab.

    Return Value

    Buffer's uploffset--does not check whether that value makes sense for this buffer.

    Discussion

    This function should only be called on iobufs, i.e. buffers allocated with buf_alloc().

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Check if a buffer contains valid data.

    Declaration

    Objective-C

    int buf_valid ( buf_t );

    Parameters

    bp

    Buffer to test.

    Return Value

    Nonzero if buffer has valid data, 0 if not.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the vnode associated with a buffer.

    Declaration

    Objective-C

    vnode_t buf_vnode ( buf_t );

    Parameters

    bp

    Buffer whose vnode to retrieve.

    Return Value

    Buffer's vnode.

    Discussion

    Every buffer is associated with a file. Because there is an I/O in flight, there is an iocount on this vnode; it is returned WITHOUT an extra iocount, and vnode_put() need NOT be called.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Get the credential associated with a buffer for writing.

    Declaration

    Objective-C

    kauth_cred_t buf_wcred ( buf_t );

    Parameters

    bp

    Buffer whose credential to grab.

    Return Value

    Credential if it exists, else NULL.

    Discussion

    No reference is taken; if the credential is to be held on to persistently, an additional reference must be taken with kauth_cred_ref.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Adjust a buffer's count to be no more than maximum physical I/O transfer size for the host architecture.

    Declaration

    Objective-C

    u_int minphys ( buf_t bp );

    Parameters

    bp

    The buffer whose byte count to modify.

    Return Value

    New byte count.

    Discussion

    physio() takes as a parameter a function to bound transfer sizes for each VNOP_STRATEGY() call. minphys() is a default implementation. It calls buf_setcount() to make the buffer's count the min() of its current count and the max I/O size for the host architecture.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Perform I/O on a device to/from target memory described by a uio.

    Declaration

    Objective-C

    int physio ( void (*)(buf_t), buf_t, dev_t, int, u_int (*)(buf_t), struct uio *, int );

    Parameters

    f_strategy

    Strategy routine to call to initiate I/O.

    bp

    Buffer to configure and pass to strategy routine; can be NULL.

    dev

    Device on which to perform I/O.

    flags

    B_READ or B_WRITE.

    f_minphys

    Function which calls buf_setcount() to set a byte count which is suitably small for the device in question. Returns byte count that has been set (or unchanged) on the buffer.

    uio

    UIO describing the I/O operation.

    blocksize

    Logical block size for this vnode.

    Return Value

    0 for success; EFAULT for an invalid uio; errors from buf_biowait().

    Discussion

    physio() allows I/O directly from a device to user-space memory. It waits for all I/O to complete before returning.

    Import Statement

    Availability

    Available in OS X v10.4 and later.