buf.h Reference

Declared in
buf.h

Overview

Included Headers

  • <sys/cdefs.h>

  • <sys/kernel_types.h>

  • <sys/ucred.h>

  • <mach/memory_object_types.h>

Functions

See the Overview section above for header-level documentation.

buf_alloc

Allocate an uninitialized buffer.

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

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

buf_attr

Gets the attributes for this buf.

bufattr_t buf_attr(
   buf_t);
Parameters
bp

Buffer whose attributes to get.

Return Value

bufattr_t.

Availability
  • Available in OS X v10.7 and later.
Declared In
buf.h

buf_bawrite

Start an asychronous write on a buffer.

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.

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

buf_bdwrite

Mark a buffer for delayed write.

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.

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

buf_biodone

Mark an I/O as completed.

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.

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

buf_biowait

Wait for I/O on a buffer to complete.

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.

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

buf_blkno

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

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

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

buf_bread

Synchronously read a block of a file.

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.

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

buf_breadn

Read a block from a file with read-ahead.

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.

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

buf_brelse

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

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.

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

buf_bwrite

Write a buffer's data to backing store.

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

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

buf_callback

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

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

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

buf_clear

Zero out the storage associated with a buffer.

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

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

buf_clearflags

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

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.

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

buf_clear_redundancy_flags

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

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
buf.h

buf_clone

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

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

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

buf_count

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

uint32_t buf_count(
   buf_t);
Parameters
bp

Buffer whose byte count to get.

Return Value

Byte count.

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

buf_create_shadow

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

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
buf.h

buf_dataptr

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

uintptr_t buf_dataptr(
   buf_t);
Parameters
bp

Buffer whose data pointer to retrieve.

Return Value

Data pointer; NULL if unset.

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

buf_device

Get the device ID associated with a buffer.

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.

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

buf_dirtyend

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

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.

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

buf_dirtyoff

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

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

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

buf_drvdata

Get driver-specific data from a buffer.

void * buf_drvdata(
   buf_t);
Parameters
bp

Buffer whose driver data to get.

Return Value

Opaque driver data.

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

buf_error

Get the error value associated with a buffer.

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

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

buf_flags

Get flags set on a buffer.

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.

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

buf_flushdirtyblks

Write dirty file blocks to disk.

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.

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

buf_free

Free a buffer that was allocated with buf_alloc().

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.

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

buf_fromcache

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

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

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

buf_fsprivate

Get filesystem-specific data from a buffer.

void * buf_fsprivate(
   buf_t);
Parameters
bp

Buffer whose filesystem data to get.

Return Value

Opaque filesystem data.

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

buf_fua

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

int buf_fua(
   buf_t);
Parameters
bp

Buffer to test.

Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
buf.h

buf_getblk

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

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

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

buf_geteblk

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

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.

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

buf_invalblkno

Invalidate a filesystem logical block in a file.

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.

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

buf_invalidateblks

Invalidate all the blocks associated with a vnode.

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.

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

buf_iterate

Perform some operation on all buffers associated with a vnode.

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.

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

buf_lblkno

Get logical block number associated with a buffer.

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

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

buf_map

Get virtual mappings for buffer data.

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

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

buf_markaged

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

void buf_markaged(
   buf_t);
Parameters
bp

Buffer to mark.

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

buf_markdelayed

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

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.

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

buf_markeintr

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

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.

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

buf_markfua

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

void buf_markfua(
   buf_t);
Parameters
bp

Buffer to mark.

Availability
  • Available in OS X v10.5 and later.
Declared In
buf.h

buf_markinvalid

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

void buf_markinvalid(
   buf_t);
Parameters
bp

Buffer to mark.

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

buf_markstatic

Mark a buffer as being likely to contain static data.

void buf_markstatic(
   buf_t);
Parameters
bp

Buffer to mark.

Return Value

void.

Availability
  • Available in OS X v10.8 and later.
Declared In
buf.h

buf_meta_bread

Synchronously read a metadata block of a file.

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.

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

buf_meta_breadn

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

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.

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

buf_proc

Get the process associated with this buffer.

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.

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

buf_rcred

Get the credential associated with a buffer for reading.

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.

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

buf_redundancy_flags

Get redundancy flags set on a buffer.

uint32_t buf_redundancy_flags(
   buf_t);
Parameters
bp

Buffer whose redundancy flags to grab.

Return Value

flags.

Availability
  • Available in OS X v10.7 and later.
Declared In
buf.h

buf_reset

Reset I/O flag state on a buffer.

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.

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

buf_resid

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

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.

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

buf_setblkno

Set physical block number associated with a buffer.

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

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

buf_setcallback

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

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.

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

buf_setcount

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

void buf_setcount(
   buf_t,
   uint32_t);
Parameters
bp

Buffer whose byte count to set.

bcount

Count to set.

Return Value

void.

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

buf_setdataptr

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

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

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

buf_setdevice

Set the device associated with a buffer.

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.

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

buf_setdirtyend

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

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.

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

buf_setdirtyoff

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

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.

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

buf_setdrvdata

Set driver-specific data on a buffer.

void buf_setdrvdata(
   buf_t,
   void *);
Parameters
bp

Buffer whose driver-data to set.

drvdata

Opaque driver data.

Return Value

void.

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

buf_seterror

Set an error value on a buffer.

void buf_seterror(
   buf_t,
   errno_t);
Parameters
bp

Buffer whose error value to set.

Return Value

void.

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

buf_setflags

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

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.

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

buf_setfsprivate

Set filesystem-specific data on a buffer.

void buf_setfsprivate(
   buf_t,
   void *);
Parameters
bp

Buffer whose filesystem data to set.

fsprivate

Opaque filesystem data.

Return Value

void.

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

buf_setlblkno

Set logical block number associated with a buffer.

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

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

buf_setresid

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

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.

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

buf_setsize

Set size of data region allocated to a buffer.

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

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

buf_setupl

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

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.

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

buf_setvnode

Set the vnode associated with a buffer.

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.

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

buf_set_redundancy_flags

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

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
buf.h

buf_shadow

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

int buf_shadow(
   buf_t bp);
Parameters
bp

Buffer to query.

Return Value

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

Availability
  • Available in OS X v10.7 and later.
Declared In
buf.h

buf_size

Get size of data region allocated to a buffer.

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.

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

buf_static

Check if a buffer contains static data.

int buf_static(
   buf_t);
Parameters
bp

Buffer to test.

Return Value

Nonzero if buffer has static data, 0 otherwise.

Availability
  • Available in OS X v10.8 and later.
Declared In
buf.h

buf_strategy

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

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.

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

buf_unmap

Release mappings for buffer data.

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.

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

buf_upl

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

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.

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

buf_uploffset

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

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

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

buf_valid

Check if a buffer contains valid data.

int buf_valid(
   buf_t);
Parameters
bp

Buffer to test.

Return Value

Nonzero if buffer has valid data, 0 if not.

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

buf_vnode

Get the vnode associated with a buffer.

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.

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

buf_wcred

Get the credential associated with a buffer for writing.

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.

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

minphys

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

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.

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

physio

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

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.

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